| This is Info file gcc.info, produced by Makeinfo version 1.68 from the |
| input file gcc.texi. |
| |
| This file documents the use and the internals of the GNU compiler. |
| |
| Published by the Free Software Foundation 59 Temple Place - Suite 330 |
| Boston, MA 02111-1307 USA |
| |
| Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of |
| this manual under the conditions for verbatim copying, provided also |
| that the sections entitled "GNU General Public License," "Funding for |
| Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are |
| included exactly as in the original, and provided that the entire |
| resulting derived work is distributed under the terms of a permission |
| notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this |
| manual into another language, under the above conditions for modified |
| versions, except that the sections entitled "GNU General Public |
| License," "Funding for Free Software," and "Protect Your Freedom--Fight |
| `Look And Feel'", and this permission notice, may be included in |
| translations approved by the Free Software Foundation instead of in the |
| original English. |
| |
| |
| File: gcc.info, Node: Costs, Next: Sections, Prev: Condition Code, Up: Target Macros |
| |
| Describing Relative Costs of Operations |
| ======================================= |
| |
| These macros let you describe the relative speed of various |
| operations on the target machine. |
| |
| `CONST_COSTS (X, CODE, OUTER_CODE)' |
| A part of a C `switch' statement that describes the relative costs |
| of constant RTL expressions. It must contain `case' labels for |
| expression codes `const_int', `const', `symbol_ref', `label_ref' |
| and `const_double'. Each case must ultimately reach a `return' |
| statement to return the relative cost of the use of that kind of |
| constant value in an expression. The cost may depend on the |
| precise value of the constant, which is available for examination |
| in X, and the rtx code of the expression in which it is contained, |
| found in OUTER_CODE. |
| |
| CODE is the expression code--redundant, since it can be obtained |
| with `GET_CODE (X)'. |
| |
| `RTX_COSTS (X, CODE, OUTER_CODE)' |
| Like `CONST_COSTS' but applies to nonconstant RTL expressions. |
| This can be used, for example, to indicate how costly a multiply |
| instruction is. In writing this macro, you can use the construct |
| `COSTS_N_INSNS (N)' to specify a cost equal to N fast |
| instructions. OUTER_CODE is the code of the expression in which X |
| is contained. |
| |
| This macro is optional; do not define it if the default cost |
| assumptions are adequate for the target machine. |
| |
| `ADDRESS_COST (ADDRESS)' |
| An expression giving the cost of an addressing mode that contains |
| ADDRESS. If not defined, the cost is computed from the ADDRESS |
| expression and the `CONST_COSTS' values. |
| |
| For most CISC machines, the default cost is a good approximation |
| of the true cost of the addressing mode. However, on RISC |
| machines, all instructions normally have the same length and |
| execution time. Hence all addresses will have equal costs. |
| |
| In cases where more than one form of an address is known, the form |
| with the lowest cost will be used. If multiple forms have the |
| same, lowest, cost, the one that is the most complex will be used. |
| |
| For example, suppose an address that is equal to the sum of a |
| register and a constant is used twice in the same basic block. |
| When this macro is not defined, the address will be computed in a |
| register and memory references will be indirect through that |
| register. On machines where the cost of the addressing mode |
| containing the sum is no higher than that of a simple indirect |
| reference, this will produce an additional instruction and |
| possibly require an additional register. Proper specification of |
| this macro eliminates this overhead for such machines. |
| |
| Similar use of this macro is made in strength reduction of loops. |
| |
| ADDRESS need not be valid as an address. In such a case, the cost |
| is not relevant and can be any value; invalid addresses need not be |
| assigned a different cost. |
| |
| On machines where an address involving more than one register is as |
| cheap as an address computation involving only one register, |
| defining `ADDRESS_COST' to reflect this can cause two registers to |
| be live over a region of code where only one would have been if |
| `ADDRESS_COST' were not defined in that manner. This effect should |
| be considered in the definition of this macro. Equivalent costs |
| should probably only be given to addresses with different numbers |
| of registers on machines with lots of registers. |
| |
| This macro will normally either not be defined or be defined as a |
| constant. |
| |
| `REGISTER_MOVE_COST (FROM, TO)' |
| A C expression for the cost of moving data from a register in class |
| FROM to one in class TO. The classes are expressed using the |
| enumeration values such as `GENERAL_REGS'. A value of 2 is the |
| default; other values are interpreted relative to that. |
| |
| It is not required that the cost always equal 2 when FROM is the |
| same as TO; on some machines it is expensive to move between |
| registers if they are not general registers. |
| |
| If reload sees an insn consisting of a single `set' between two |
| hard registers, and if `REGISTER_MOVE_COST' applied to their |
| classes returns a value of 2, reload does not check to ensure that |
| the constraints of the insn are met. Setting a cost of other than |
| 2 will allow reload to verify that the constraints are met. You |
| should do this if the `movM' pattern's constraints do not allow |
| such copying. |
| |
| `MEMORY_MOVE_COST (M)' |
| A C expression for the cost of moving data of mode M between a |
| register and memory. A value of 4 is the default; this cost is |
| relative to those in `REGISTER_MOVE_COST'. |
| |
| If moving between registers and memory is more expensive than |
| between two registers, you should define this macro to express the |
| relative cost. |
| |
| `BRANCH_COST' |
| A C expression for the cost of a branch instruction. A value of 1 |
| is the default; other values are interpreted relative to that. |
| |
| Here are additional macros which do not specify precise relative |
| costs, but only that certain actions are more expensive than GNU CC |
| would ordinarily expect. |
| |
| `SLOW_BYTE_ACCESS' |
| Define this macro as a C expression which is nonzero if accessing |
| less than a word of memory (i.e. a `char' or a `short') is no |
| faster than accessing a word of memory, i.e., if such access |
| require more than one instruction or if there is no difference in |
| cost between byte and (aligned) word loads. |
| |
| When this macro is not defined, the compiler will access a field by |
| finding the smallest containing object; when it is defined, a |
| fullword load will be used if alignment permits. Unless bytes |
| accesses are faster than word accesses, using word accesses is |
| preferable since it may eliminate subsequent memory access if |
| subsequent accesses occur to other fields in the same word of the |
| structure, but to different bytes. |
| |
| `SLOW_ZERO_EXTEND' |
| Define this macro if zero-extension (of a `char' or `short' to an |
| `int') can be done faster if the destination is a register that is |
| known to be zero. |
| |
| If you define this macro, you must have instruction patterns that |
| recognize RTL structures like this: |
| |
| (set (strict_low_part (subreg:QI (reg:SI ...) 0)) ...) |
| |
| and likewise for `HImode'. |
| |
| `SLOW_UNALIGNED_ACCESS' |
| Define this macro to be the value 1 if unaligned accesses have a |
| cost many times greater than aligned accesses, for example if they |
| are emulated in a trap handler. |
| |
| When this macro is non-zero, the compiler will act as if |
| `STRICT_ALIGNMENT' were non-zero when generating code for block |
| moves. This can cause significantly more instructions to be |
| produced. Therefore, do not set this macro non-zero if unaligned |
| accesses only add a cycle or two to the time for a memory access. |
| |
| If the value of this macro is always zero, it need not be defined. |
| |
| `DONT_REDUCE_ADDR' |
| Define this macro to inhibit strength reduction of memory |
| addresses. (On some machines, such strength reduction seems to do |
| harm rather than good.) |
| |
| `MOVE_RATIO' |
| The number of scalar move insns which should be generated instead |
| of a string move insn or a library call. Increasing the value |
| will always make code faster, but eventually incurs high cost in |
| increased code size. |
| |
| If you don't define this, a reasonable default is used. |
| |
| `NO_FUNCTION_CSE' |
| Define this macro if it is as good or better to call a constant |
| function address than to call an address kept in a register. |
| |
| `NO_RECURSIVE_FUNCTION_CSE' |
| Define this macro if it is as good or better for a function to call |
| itself with an explicit address than to call an address kept in a |
| register. |
| |
| `ADJUST_COST (INSN, LINK, DEP_INSN, COST)' |
| A C statement (sans semicolon) to update the integer variable COST |
| based on the relationship between INSN that is dependent on |
| DEP_INSN through the dependence LINK. The default is to make no |
| adjustment to COST. This can be used for example to specify to |
| the scheduler that an output- or anti-dependence does not incur |
| the same cost as a data-dependence. |
| |
| `ADJUST_PRIORITY (INSN)' |
| A C statement (sans semicolon) to update the integer scheduling |
| priority `INSN_PRIORITY(INSN)'. Reduce the priority to execute |
| the INSN earlier, increase the priority to execute INSN later. |
| Do not define this macro if you do not need to adjust the |
| scheduling priorities of insns. |
| |
| |
| File: gcc.info, Node: Sections, Next: PIC, Prev: Costs, Up: Target Macros |
| |
| Dividing the Output into Sections (Texts, Data, ...) |
| ==================================================== |
| |
| An object file is divided into sections containing different types of |
| data. In the most common case, there are three sections: the "text |
| section", which holds instructions and read-only data; the "data |
| section", which holds initialized writable data; and the "bss section", |
| which holds uninitialized data. Some systems have other kinds of |
| sections. |
| |
| The compiler must tell the assembler when to switch sections. These |
| macros control what commands to output to tell the assembler this. You |
| can also define additional sections. |
| |
| `TEXT_SECTION_ASM_OP' |
| A C expression whose value is a string containing the assembler |
| operation that should precede instructions and read-only data. |
| Normally `".text"' is right. |
| |
| `DATA_SECTION_ASM_OP' |
| A C expression whose value is a string containing the assembler |
| operation to identify the following data as writable initialized |
| data. Normally `".data"' is right. |
| |
| `SHARED_SECTION_ASM_OP' |
| If defined, a C expression whose value is a string containing the |
| assembler operation to identify the following data as shared data. |
| If not defined, `DATA_SECTION_ASM_OP' will be used. |
| |
| `BSS_SECTION_ASM_OP' |
| If defined, a C expression whose value is a string containing the |
| assembler operation to identify the following data as |
| uninitialized global data. If not defined, and neither |
| `ASM_OUTPUT_BSS' nor `ASM_OUTPUT_ALIGNED_BSS' are defined, |
| uninitialized global data will be output in the data section if |
| `-fno-common' is passed, otherwise `ASM_OUTPUT_COMMON' will be |
| used. |
| |
| `SHARED_BSS_SECTION_ASM_OP' |
| If defined, a C expression whose value is a string containing the |
| assembler operation to identify the following data as |
| uninitialized global shared data. If not defined, and |
| `BSS_SECTION_ASM_OP' is, the latter will be used. |
| |
| `INIT_SECTION_ASM_OP' |
| If defined, a C expression whose value is a string containing the |
| assembler operation to identify the following data as |
| initialization code. If not defined, GNU CC will assume such a |
| section does not exist. |
| |
| `EXTRA_SECTIONS' |
| A list of names for sections other than the standard two, which are |
| `in_text' and `in_data'. You need not define this macro on a |
| system with no other sections (that GCC needs to use). |
| |
| `EXTRA_SECTION_FUNCTIONS' |
| One or more functions to be defined in `varasm.c'. These |
| functions should do jobs analogous to those of `text_section' and |
| `data_section', for your additional sections. Do not define this |
| macro if you do not define `EXTRA_SECTIONS'. |
| |
| `READONLY_DATA_SECTION' |
| On most machines, read-only variables, constants, and jump tables |
| are placed in the text section. If this is not the case on your |
| machine, this macro should be defined to be the name of a function |
| (either `data_section' or a function defined in `EXTRA_SECTIONS') |
| that switches to the section to be used for read-only items. |
| |
| If these items should be placed in the text section, this macro |
| should not be defined. |
| |
| `SELECT_SECTION (EXP, RELOC)' |
| A C statement or statements to switch to the appropriate section |
| for output of EXP. You can assume that EXP is either a `VAR_DECL' |
| node or a constant of some sort. RELOC indicates whether the |
| initial value of EXP requires link-time relocations. Select the |
| section by calling `text_section' or one of the alternatives for |
| other sections. |
| |
| Do not define this macro if you put all read-only variables and |
| constants in the read-only data section (usually the text section). |
| |
| `SELECT_RTX_SECTION (MODE, RTX)' |
| A C statement or statements to switch to the appropriate section |
| for output of RTX in mode MODE. You can assume that RTX is some |
| kind of constant in RTL. The argument MODE is redundant except in |
| the case of a `const_int' rtx. Select the section by calling |
| `text_section' or one of the alternatives for other sections. |
| |
| Do not define this macro if you put all constants in the read-only |
| data section. |
| |
| `JUMP_TABLES_IN_TEXT_SECTION' |
| Define this macro if jump tables (for `tablejump' insns) should be |
| output in the text section, along with the assembler instructions. |
| Otherwise, the readonly data section is used. |
| |
| This macro is irrelevant if there is no separate readonly data |
| section. |
| |
| `ENCODE_SECTION_INFO (DECL)' |
| Define this macro if references to a symbol must be treated |
| differently depending on something about the variable or function |
| named by the symbol (such as what section it is in). |
| |
| The macro definition, if any, is executed immediately after the |
| rtl for DECL has been created and stored in `DECL_RTL (DECL)'. |
| The value of the rtl will be a `mem' whose address is a |
| `symbol_ref'. |
| |
| The usual thing for this macro to do is to record a flag in the |
| `symbol_ref' (such as `SYMBOL_REF_FLAG') or to store a modified |
| name string in the `symbol_ref' (if one bit is not enough |
| information). |
| |
| `STRIP_NAME_ENCODING (VAR, SYM_NAME)' |
| Decode SYM_NAME and store the real name part in VAR, sans the |
| characters that encode section info. Define this macro if |
| `ENCODE_SECTION_INFO' alters the symbol's name string. |
| |
| `UNIQUE_SECTION_P (DECL)' |
| A C expression which evaluates to true if DECL should be placed |
| into a unique section for some target-specific reason. If you do |
| not define this macro, the default is `0'. Note that the flag |
| `-ffunction-sections' will also cause functions to be placed into |
| unique sections. |
| |
| `UNIQUE_SECTION (DECL, RELOC)' |
| A C statement to build up a unique section name, expressed as a |
| STRING_CST node, and assign it to `DECL_SECTION_NAME (DECL)'. |
| RELOC indicates whether the initial value of EXP requires |
| link-time relocations. If you do not define this macro, GNU CC |
| will use the symbol name prefixed by `.' as the section name. |
| |
| |
| File: gcc.info, Node: PIC, Next: Assembler Format, Prev: Sections, Up: Target Macros |
| |
| Position Independent Code |
| ========================= |
| |
| This section describes macros that help implement generation of |
| position independent code. Simply defining these macros is not enough |
| to generate valid PIC; you must also add support to the macros |
| `GO_IF_LEGITIMATE_ADDRESS' and `PRINT_OPERAND_ADDRESS', as well as |
| `LEGITIMIZE_ADDRESS'. You must modify the definition of `movsi' to do |
| something appropriate when the source operand contains a symbolic |
| address. You may also need to alter the handling of switch statements |
| so that they use relative addresses. |
| |
| `PIC_OFFSET_TABLE_REGNUM' |
| The register number of the register used to address a table of |
| static data addresses in memory. In some cases this register is |
| defined by a processor's "application binary interface" (ABI). |
| When this macro is defined, RTL is generated for this register |
| once, as with the stack pointer and frame pointer registers. If |
| this macro is not defined, it is up to the machine-dependent files |
| to allocate such a register (if necessary). |
| |
| `PIC_OFFSET_TABLE_REG_CALL_CLOBBERED' |
| Define this macro if the register defined by |
| `PIC_OFFSET_TABLE_REGNUM' is clobbered by calls. Do not define |
| this macro if `PPIC_OFFSET_TABLE_REGNUM' is not defined. |
| |
| `FINALIZE_PIC' |
| By generating position-independent code, when two different |
| programs (A and B) share a common library (libC.a), the text of |
| the library can be shared whether or not the library is linked at |
| the same address for both programs. In some of these |
| environments, position-independent code requires not only the use |
| of different addressing modes, but also special code to enable the |
| use of these addressing modes. |
| |
| The `FINALIZE_PIC' macro serves as a hook to emit these special |
| codes once the function is being compiled into assembly code, but |
| not before. (It is not done before, because in the case of |
| compiling an inline function, it would lead to multiple PIC |
| prologues being included in functions which used inline functions |
| and were compiled to assembly language.) |
| |
| `LEGITIMATE_PIC_OPERAND_P (X)' |
| A C expression that is nonzero if X is a legitimate immediate |
| operand on the target machine when generating position independent |
| code. You can assume that X satisfies `CONSTANT_P', so you need |
| not check this. You can also assume FLAG_PIC is true, so you need |
| not check it either. You need not define this macro if all |
| constants (including `SYMBOL_REF') can be immediate operands when |
| generating position independent code. |
| |
| |
| File: gcc.info, Node: Assembler Format, Next: Debugging Info, Prev: PIC, Up: Target Macros |
| |
| Defining the Output Assembler Language |
| ====================================== |
| |
| This section describes macros whose principal purpose is to describe |
| how to write instructions in assembler language-rather than what the |
| instructions do. |
| |
| * Menu: |
| |
| * File Framework:: Structural information for the assembler file. |
| * Data Output:: Output of constants (numbers, strings, addresses). |
| * Uninitialized Data:: Output of uninitialized variables. |
| * Label Output:: Output and generation of labels. |
| * Initialization:: General principles of initialization |
| and termination routines. |
| * Macros for Initialization:: |
| Specific macros that control the handling of |
| initialization and termination routines. |
| * Instruction Output:: Output of actual instructions. |
| * Dispatch Tables:: Output of jump tables. |
| * Exception Region Output:: Output of exception region code. |
| * Alignment Output:: Pseudo ops for alignment and skipping data. |
| |
| |
| File: gcc.info, Node: File Framework, Next: Data Output, Up: Assembler Format |
| |
| The Overall Framework of an Assembler File |
| ------------------------------------------ |
| |
| This describes the overall framework of an assembler file. |
| |
| `ASM_FILE_START (STREAM)' |
| A C expression which outputs to the stdio stream STREAM some |
| appropriate text to go at the start of an assembler file. |
| |
| Normally this macro is defined to output a line containing |
| `#NO_APP', which is a comment that has no effect on most |
| assemblers but tells the GNU assembler that it can save time by not |
| checking for certain assembler constructs. |
| |
| On systems that use SDB, it is necessary to output certain |
| commands; see `attasm.h'. |
| |
| `ASM_FILE_END (STREAM)' |
| A C expression which outputs to the stdio stream STREAM some |
| appropriate text to go at the end of an assembler file. |
| |
| If this macro is not defined, the default is to output nothing |
| special at the end of the file. Most systems don't require any |
| definition. |
| |
| On systems that use SDB, it is necessary to output certain |
| commands; see `attasm.h'. |
| |
| `ASM_IDENTIFY_GCC (FILE)' |
| A C statement to output assembler commands which will identify the |
| object file as having been compiled with GNU CC (or another GNU |
| compiler). |
| |
| If you don't define this macro, the string `gcc_compiled.:' is |
| output. This string is calculated to define a symbol which, on |
| BSD systems, will never be defined for any other reason. GDB |
| checks for the presence of this symbol when reading the symbol |
| table of an executable. |
| |
| On non-BSD systems, you must arrange communication with GDB in |
| some other fashion. If GDB is not used on your system, you can |
| define this macro with an empty body. |
| |
| `ASM_COMMENT_START' |
| A C string constant describing how to begin a comment in the target |
| assembler language. The compiler assumes that the comment will |
| end at the end of the line. |
| |
| `ASM_APP_ON' |
| A C string constant for text to be output before each `asm' |
| statement or group of consecutive ones. Normally this is |
| `"#APP"', which is a comment that has no effect on most assemblers |
| but tells the GNU assembler that it must check the lines that |
| follow for all valid assembler constructs. |
| |
| `ASM_APP_OFF' |
| A C string constant for text to be output after each `asm' |
| statement or group of consecutive ones. Normally this is |
| `"#NO_APP"', which tells the GNU assembler to resume making the |
| time-saving assumptions that are valid for ordinary compiler |
| output. |
| |
| `ASM_OUTPUT_SOURCE_FILENAME (STREAM, NAME)' |
| A C statement to output COFF information or DWARF debugging |
| information which indicates that filename NAME is the current |
| source file to the stdio stream STREAM. |
| |
| This macro need not be defined if the standard form of output for |
| the file format in use is appropriate. |
| |
| `OUTPUT_QUOTED_STRING (STREAM, NAME)' |
| A C statement to output the string STRING to the stdio stream |
| STREAM. If you do not call the function `output_quoted_string' in |
| your config files, GNU CC will only call it to output filenames to |
| the assembler source. So you can use it to canonicalize the format |
| of the filename using this macro. |
| |
| `ASM_OUTPUT_SOURCE_LINE (STREAM, LINE)' |
| A C statement to output DBX or SDB debugging information before |
| code for line number LINE of the current source file to the stdio |
| stream STREAM. |
| |
| This macro need not be defined if the standard form of debugging |
| information for the debugger in use is appropriate. |
| |
| `ASM_OUTPUT_IDENT (STREAM, STRING)' |
| A C statement to output something to the assembler file to handle a |
| `#ident' directive containing the text STRING. If this macro is |
| not defined, nothing is output for a `#ident' directive. |
| |
| `ASM_OUTPUT_SECTION_NAME (STREAM, DECL, NAME, RELOC)' |
| A C statement to output something to the assembler file to switch |
| to section NAME for object DECL which is either a `FUNCTION_DECL', |
| a `VAR_DECL' or `NULL_TREE'. RELOC indicates whether the initial |
| value of EXP requires link-time relocations. Some target formats |
| do not support arbitrary sections. Do not define this macro in |
| such cases. |
| |
| At present this macro is only used to support section attributes. |
| When this macro is undefined, section attributes are disabled. |
| |
| `OBJC_PROLOGUE' |
| A C statement to output any assembler statements which are |
| required to precede any Objective C object definitions or message |
| sending. The statement is executed only when compiling an |
| Objective C program. |
| |
| |
| File: gcc.info, Node: Data Output, Next: Uninitialized Data, Prev: File Framework, Up: Assembler Format |
| |
| Output of Data |
| -------------- |
| |
| This describes data output. |
| |
| `ASM_OUTPUT_LONG_DOUBLE (STREAM, VALUE)' |
| `ASM_OUTPUT_DOUBLE (STREAM, VALUE)' |
| `ASM_OUTPUT_FLOAT (STREAM, VALUE)' |
| `ASM_OUTPUT_THREE_QUARTER_FLOAT (STREAM, VALUE)' |
| `ASM_OUTPUT_SHORT_FLOAT (STREAM, VALUE)' |
| `ASM_OUTPUT_BYTE_FLOAT (STREAM, VALUE)' |
| A C statement to output to the stdio stream STREAM an assembler |
| instruction to assemble a floating-point constant of `TFmode', |
| `DFmode', `SFmode', `TQFmode', `HFmode', or `QFmode', |
| respectively, whose value is VALUE. VALUE will be a C expression |
| of type `REAL_VALUE_TYPE'. Macros such as |
| `REAL_VALUE_TO_TARGET_DOUBLE' are useful for writing these |
| definitions. |
| |
| `ASM_OUTPUT_QUADRUPLE_INT (STREAM, EXP)' |
| `ASM_OUTPUT_DOUBLE_INT (STREAM, EXP)' |
| `ASM_OUTPUT_INT (STREAM, EXP)' |
| `ASM_OUTPUT_SHORT (STREAM, EXP)' |
| `ASM_OUTPUT_CHAR (STREAM, EXP)' |
| A C statement to output to the stdio stream STREAM an assembler |
| instruction to assemble an integer of 16, 8, 4, 2 or 1 bytes, |
| respectively, whose value is VALUE. The argument EXP will be an |
| RTL expression which represents a constant value. Use |
| `output_addr_const (STREAM, EXP)' to output this value as an |
| assembler expression. |
| |
| For sizes larger than `UNITS_PER_WORD', if the action of a macro |
| would be identical to repeatedly calling the macro corresponding to |
| a size of `UNITS_PER_WORD', once for each word, you need not define |
| the macro. |
| |
| `ASM_OUTPUT_BYTE (STREAM, VALUE)' |
| A C statement to output to the stdio stream STREAM an assembler |
| instruction to assemble a single byte containing the number VALUE. |
| |
| `ASM_BYTE_OP' |
| A C string constant giving the pseudo-op to use for a sequence of |
| single-byte constants. If this macro is not defined, the default |
| is `"byte"'. |
| |
| `ASM_OUTPUT_ASCII (STREAM, PTR, LEN)' |
| A C statement to output to the stdio stream STREAM an assembler |
| instruction to assemble a string constant containing the LEN bytes |
| at PTR. PTR will be a C expression of type `char *' and LEN a C |
| expression of type `int'. |
| |
| If the assembler has a `.ascii' pseudo-op as found in the Berkeley |
| Unix assembler, do not define the macro `ASM_OUTPUT_ASCII'. |
| |
| `CONSTANT_POOL_BEFORE_FUNCTION' |
| You may define this macro as a C expression. You should define the |
| expression to have a non-zero value if GNU CC should output the |
| constant pool for a function before the code for the function, or |
| a zero value if GNU CC should output the constant pool after the |
| function. If you do not define this macro, the usual case, GNU CC |
| will output the constant pool before the function. |
| |
| `ASM_OUTPUT_POOL_PROLOGUE (FILE FUNNAME FUNDECL SIZE)' |
| A C statement to output assembler commands to define the start of |
| the constant pool for a function. FUNNAME is a string giving the |
| name of the function. Should the return type of the function be |
| required, it can be obtained via FUNDECL. SIZE is the size, in |
| bytes, of the constant pool that will be written immediately after |
| this call. |
| |
| If no constant-pool prefix is required, the usual case, this macro |
| need not be defined. |
| |
| `ASM_OUTPUT_SPECIAL_POOL_ENTRY (FILE, X, MODE, ALIGN, LABELNO, JUMPTO)' |
| A C statement (with or without semicolon) to output a constant in |
| the constant pool, if it needs special treatment. (This macro |
| need not do anything for RTL expressions that can be output |
| normally.) |
| |
| The argument FILE is the standard I/O stream to output the |
| assembler code on. X is the RTL expression for the constant to |
| output, and MODE is the machine mode (in case X is a `const_int'). |
| ALIGN is the required alignment for the value X; you should |
| output an assembler directive to force this much alignment. |
| |
| The argument LABELNO is a number to use in an internal label for |
| the address of this pool entry. The definition of this macro is |
| responsible for outputting the label definition at the proper |
| place. Here is how to do this: |
| |
| ASM_OUTPUT_INTERNAL_LABEL (FILE, "LC", LABELNO); |
| |
| When you output a pool entry specially, you should end with a |
| `goto' to the label JUMPTO. This will prevent the same pool entry |
| from being output a second time in the usual manner. |
| |
| You need not define this macro if it would do nothing. |
| |
| `CONSTANT_AFTER_FUNCTION_P (EXP)' |
| Define this macro as a C expression which is nonzero if the |
| constant EXP, of type `tree', should be output after the code for a |
| function. The compiler will normally output all constants before |
| the function; you need not define this macro if this is OK. |
| |
| `ASM_OUTPUT_POOL_EPILOGUE (FILE FUNNAME FUNDECL SIZE)' |
| A C statement to output assembler commands to at the end of the |
| constant pool for a function. FUNNAME is a string giving the name |
| of the function. Should the return type of the function be |
| required, you can obtain it via FUNDECL. SIZE is the size, in |
| bytes, of the constant pool that GNU CC wrote immediately before |
| this call. |
| |
| If no constant-pool epilogue is required, the usual case, you need |
| not define this macro. |
| |
| `IS_ASM_LOGICAL_LINE_SEPARATOR (C)' |
| Define this macro as a C expression which is nonzero if C is used |
| as a logical line separator by the assembler. |
| |
| If you do not define this macro, the default is that only the |
| character `;' is treated as a logical line separator. |
| |
| `ASM_OPEN_PAREN' |
| `ASM_CLOSE_PAREN' |
| These macros are defined as C string constant, describing the |
| syntax in the assembler for grouping arithmetic expressions. The |
| following definitions are correct for most assemblers: |
| |
| #define ASM_OPEN_PAREN "(" |
| #define ASM_CLOSE_PAREN ")" |
| |
| These macros are provided by `real.h' for writing the definitions of |
| `ASM_OUTPUT_DOUBLE' and the like: |
| |
| `REAL_VALUE_TO_TARGET_SINGLE (X, L)' |
| `REAL_VALUE_TO_TARGET_DOUBLE (X, L)' |
| `REAL_VALUE_TO_TARGET_LONG_DOUBLE (X, L)' |
| These translate X, of type `REAL_VALUE_TYPE', to the target's |
| floating point representation, and store its bit pattern in the |
| array of `long int' whose address is L. The number of elements in |
| the output array is determined by the size of the desired target |
| floating point data type: 32 bits of it go in each `long int' array |
| element. Each array element holds 32 bits of the result, even if |
| `long int' is wider than 32 bits on the host machine. |
| |
| The array element values are designed so that you can print them |
| out using `fprintf' in the order they should appear in the target |
| machine's memory. |
| |
| `REAL_VALUE_TO_DECIMAL (X, FORMAT, STRING)' |
| This macro converts X, of type `REAL_VALUE_TYPE', to a decimal |
| number and stores it as a string into STRING. You must pass, as |
| STRING, the address of a long enough block of space to hold the |
| result. |
| |
| The argument FORMAT is a `printf'-specification that serves as a |
| suggestion for how to format the output string. |
| |
| |
| File: gcc.info, Node: Uninitialized Data, Next: Label Output, Prev: Data Output, Up: Assembler Format |
| |
| Output of Uninitialized Variables |
| --------------------------------- |
| |
| Each of the macros in this section is used to do the whole job of |
| outputting a single uninitialized variable. |
| |
| `ASM_OUTPUT_COMMON (STREAM, NAME, SIZE, ROUNDED)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM the assembler definition of a common-label named NAME whose |
| size is SIZE bytes. The variable ROUNDED is the size rounded up |
| to whatever alignment the caller wants. |
| |
| Use the expression `assemble_name (STREAM, NAME)' to output the |
| name itself; before and after that, output the additional |
| assembler syntax for defining the name, and a newline. |
| |
| This macro controls how the assembler definitions of uninitialized |
| common global variables are output. |
| |
| `ASM_OUTPUT_ALIGNED_COMMON (STREAM, NAME, SIZE, ALIGNMENT)' |
| Like `ASM_OUTPUT_COMMON' except takes the required alignment as a |
| separate, explicit argument. If you define this macro, it is used |
| in place of `ASM_OUTPUT_COMMON', and gives you more flexibility in |
| handling the required alignment of the variable. The alignment is |
| specified as the number of bits. |
| |
| `ASM_OUTPUT_ALIGNED_DECL_COMMON (STREAM, DECL, NAME, SIZE, ALIGNMENT)' |
| Like `ASM_OUTPUT_ALIGNED_COMMON' except that DECL of the variable |
| to be output, if there is one, or `NULL_TREE' if there is not |
| corresponding variable. If you define this macro, GNU CC wil use |
| it in place of both `ASM_OUTPUT_COMMON' and |
| `ASM_OUTPUT_ALIGNED_COMMON'. Define this macro when you need to |
| see the variable's decl in order to chose what to output. |
| |
| `ASM_OUTPUT_SHARED_COMMON (STREAM, NAME, SIZE, ROUNDED)' |
| If defined, it is similar to `ASM_OUTPUT_COMMON', except that it |
| is used when NAME is shared. If not defined, `ASM_OUTPUT_COMMON' |
| will be used. |
| |
| `ASM_OUTPUT_BSS (STREAM, DECL, NAME, SIZE, ROUNDED)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM the assembler definition of uninitialized global DECL named |
| NAME whose size is SIZE bytes. The variable ROUNDED is the size |
| rounded up to whatever alignment the caller wants. |
| |
| Try to use function `asm_output_bss' defined in `varasm.c' when |
| defining this macro. If unable, use the expression `assemble_name |
| (STREAM, NAME)' to output the name itself; before and after that, |
| output the additional assembler syntax for defining the name, and |
| a newline. |
| |
| This macro controls how the assembler definitions of uninitialized |
| global variables are output. This macro exists to properly |
| support languages like `c++' which do not have `common' data. |
| However, this macro currently is not defined for all targets. If |
| this macro and `ASM_OUTPUT_ALIGNED_BSS' are not defined then |
| `ASM_OUTPUT_COMMON' or `ASM_OUTPUT_ALIGNED_COMMON' or |
| `ASM_OUTPUT_ALIGNED_DECL_COMMON' is used. |
| |
| `ASM_OUTPUT_ALIGNED_BSS (STREAM, DECL, NAME, SIZE, ALIGNMENT)' |
| Like `ASM_OUTPUT_BSS' except takes the required alignment as a |
| separate, explicit argument. If you define this macro, it is used |
| in place of `ASM_OUTPUT_BSS', and gives you more flexibility in |
| handling the required alignment of the variable. The alignment is |
| specified as the number of bits. |
| |
| Try to use function `asm_output_aligned_bss' defined in file |
| `varasm.c' when defining this macro. |
| |
| `ASM_OUTPUT_SHARED_BSS (STREAM, DECL, NAME, SIZE, ROUNDED)' |
| If defined, it is similar to `ASM_OUTPUT_BSS', except that it is |
| used when NAME is shared. If not defined, `ASM_OUTPUT_BSS' will |
| be used. |
| |
| `ASM_OUTPUT_LOCAL (STREAM, NAME, SIZE, ROUNDED)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM the assembler definition of a local-common-label named NAME |
| whose size is SIZE bytes. The variable ROUNDED is the size |
| rounded up to whatever alignment the caller wants. |
| |
| Use the expression `assemble_name (STREAM, NAME)' to output the |
| name itself; before and after that, output the additional |
| assembler syntax for defining the name, and a newline. |
| |
| This macro controls how the assembler definitions of uninitialized |
| static variables are output. |
| |
| `ASM_OUTPUT_ALIGNED_LOCAL (STREAM, NAME, SIZE, ALIGNMENT)' |
| Like `ASM_OUTPUT_LOCAL' except takes the required alignment as a |
| separate, explicit argument. If you define this macro, it is used |
| in place of `ASM_OUTPUT_LOCAL', and gives you more flexibility in |
| handling the required alignment of the variable. The alignment is |
| specified as the number of bits. |
| |
| `ASM_OUTPUT_ALIGNED_DECL_LOCAL (STREAM, DECL, NAME, SIZE, ALIGNMENT)' |
| Like `ASM_OUTPUT_ALIGNED_DECL' except that DECL of the variable to |
| be output, if there is one, or `NULL_TREE' if there is not |
| corresponding variable. If you define this macro, GNU CC wil use |
| it in place of both `ASM_OUTPUT_DECL' and |
| `ASM_OUTPUT_ALIGNED_DECL'. Define this macro when you need to see |
| the variable's decl in order to chose what to output. |
| |
| `ASM_OUTPUT_SHARED_LOCAL (STREAM, NAME, SIZE, ROUNDED)' |
| If defined, it is similar to `ASM_OUTPUT_LOCAL', except that it is |
| used when NAME is shared. If not defined, `ASM_OUTPUT_LOCAL' will |
| be used. |
| |
| |
| File: gcc.info, Node: Label Output, Next: Initialization, Prev: Uninitialized Data, Up: Assembler Format |
| |
| Output and Generation of Labels |
| ------------------------------- |
| |
| This is about outputting labels. |
| |
| `ASM_OUTPUT_LABEL (STREAM, NAME)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM the assembler definition of a label named NAME. Use the |
| expression `assemble_name (STREAM, NAME)' to output the name |
| itself; before and after that, output the additional assembler |
| syntax for defining the name, and a newline. |
| |
| `ASM_DECLARE_FUNCTION_NAME (STREAM, NAME, DECL)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM any text necessary for declaring the name NAME of a |
| function which is being defined. This macro is responsible for |
| outputting the label definition (perhaps using |
| `ASM_OUTPUT_LABEL'). The argument DECL is the `FUNCTION_DECL' |
| tree node representing the function. |
| |
| If this macro is not defined, then the function name is defined in |
| the usual manner as a label (by means of `ASM_OUTPUT_LABEL'). |
| |
| `ASM_DECLARE_FUNCTION_SIZE (STREAM, NAME, DECL)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM any text necessary for declaring the size of a function |
| which is being defined. The argument NAME is the name of the |
| function. The argument DECL is the `FUNCTION_DECL' tree node |
| representing the function. |
| |
| If this macro is not defined, then the function size is not |
| defined. |
| |
| `ASM_DECLARE_OBJECT_NAME (STREAM, NAME, DECL)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM any text necessary for declaring the name NAME of an |
| initialized variable which is being defined. This macro must |
| output the label definition (perhaps using `ASM_OUTPUT_LABEL'). |
| The argument DECL is the `VAR_DECL' tree node representing the |
| variable. |
| |
| If this macro is not defined, then the variable name is defined in |
| the usual manner as a label (by means of `ASM_OUTPUT_LABEL'). |
| |
| `ASM_FINISH_DECLARE_OBJECT (STREAM, DECL, TOPLEVEL, ATEND)' |
| A C statement (sans semicolon) to finish up declaring a variable |
| name once the compiler has processed its initializer fully and |
| thus has had a chance to determine the size of an array when |
| controlled by an initializer. This is used on systems where it's |
| necessary to declare something about the size of the object. |
| |
| If you don't define this macro, that is equivalent to defining it |
| to do nothing. |
| |
| `ASM_GLOBALIZE_LABEL (STREAM, NAME)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM some commands that will make the label NAME global; that |
| is, available for reference from other files. Use the expression |
| `assemble_name (STREAM, NAME)' to output the name itself; before |
| and after that, output the additional assembler syntax for making |
| that name global, and a newline. |
| |
| `ASM_WEAKEN_LABEL' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM some commands that will make the label NAME weak; that is, |
| available for reference from other files but only used if no other |
| definition is available. Use the expression `assemble_name |
| (STREAM, NAME)' to output the name itself; before and after that, |
| output the additional assembler syntax for making that name weak, |
| and a newline. |
| |
| If you don't define this macro, GNU CC will not support weak |
| symbols and you should not define the `SUPPORTS_WEAK' macro. |
| |
| `SUPPORTS_WEAK' |
| A C expression which evaluates to true if the target supports weak |
| symbols. |
| |
| If you don't define this macro, `defaults.h' provides a default |
| definition. If `ASM_WEAKEN_LABEL' is defined, the default |
| definition is `1'; otherwise, it is `0'. Define this macro if you |
| want to control weak symbol support with a compiler flag such as |
| `-melf'. |
| |
| `MAKE_DECL_ONE_ONLY' |
| A C statement (sans semicolon) to mark DECL to be emitted as a |
| public symbol such that extra copies in multiple translation units |
| will be discarded by the linker. Define this macro if your object |
| file format provides support for this concept, such as the `COMDAT' |
| section flags in the Microsoft Windows PE/COFF format, and this |
| support requires changes to DECL, such as putting it in a separate |
| section. |
| |
| `SUPPORTS_ONE_ONLY' |
| A C expression which evaluates to true if the target supports |
| one-only semantics. |
| |
| If you don't define this macro, `varasm.c' provides a default |
| definition. If `MAKE_DECL_ONE_ONLY' is defined, the default |
| definition is `1'; otherwise, it is `0'. Define this macro if you |
| want to control one-only symbol support with a compiler flag, or if |
| setting the `DECL_ONE_ONLY' flag is enough to mark a declaration to |
| be emitted as one-only. |
| |
| `ASM_OUTPUT_EXTERNAL (STREAM, DECL, NAME)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM any text necessary for declaring the name of an external |
| symbol named NAME which is referenced in this compilation but not |
| defined. The value of DECL is the tree node for the declaration. |
| |
| This macro need not be defined if it does not need to output |
| anything. The GNU assembler and most Unix assemblers don't |
| require anything. |
| |
| `ASM_OUTPUT_EXTERNAL_LIBCALL (STREAM, SYMREF)' |
| A C statement (sans semicolon) to output on STREAM an assembler |
| pseudo-op to declare a library function name external. The name |
| of the library function is given by SYMREF, which has type `rtx' |
| and is a `symbol_ref'. |
| |
| This macro need not be defined if it does not need to output |
| anything. The GNU assembler and most Unix assemblers don't |
| require anything. |
| |
| `ASM_OUTPUT_LABELREF (STREAM, NAME)' |
| A C statement (sans semicolon) to output to the stdio stream |
| STREAM a reference in assembler syntax to a label named NAME. |
| This should add `_' to the front of the name, if that is customary |
| on your operating system, as it is in most Berkeley Unix systems. |
| This macro is used in `assemble_name'. |
| |
| `ASM_OUTPUT_INTERNAL_LABEL (STREAM, PREFIX, NUM)' |
| A C statement to output to the stdio stream STREAM a label whose |
| name is made from the string PREFIX and the number NUM. |
| |
| It is absolutely essential that these labels be distinct from the |
| labels used for user-level functions and variables. Otherwise, |
| certain programs will have name conflicts with internal labels. |
| |
| It is desirable to exclude internal labels from the symbol table |
| of the object file. Most assemblers have a naming convention for |
| labels that should be excluded; on many systems, the letter `L' at |
| the beginning of a label has this effect. You should find out what |
| convention your system uses, and follow it. |
| |
| The usual definition of this macro is as follows: |
| |
| fprintf (STREAM, "L%s%d:\n", PREFIX, NUM) |
| |
| `ASM_GENERATE_INTERNAL_LABEL (STRING, PREFIX, NUM)' |
| A C statement to store into the string STRING a label whose name |
| is made from the string PREFIX and the number NUM. |
| |
| This string, when output subsequently by `assemble_name', should |
| produce the output that `ASM_OUTPUT_INTERNAL_LABEL' would produce |
| with the same PREFIX and NUM. |
| |
| If the string begins with `*', then `assemble_name' will output |
| the rest of the string unchanged. It is often convenient for |
| `ASM_GENERATE_INTERNAL_LABEL' to use `*' in this way. If the |
| string doesn't start with `*', then `ASM_OUTPUT_LABELREF' gets to |
| output the string, and may change it. (Of course, |
| `ASM_OUTPUT_LABELREF' is also part of your machine description, so |
| you should know what it does on your machine.) |
| |
| `ASM_FORMAT_PRIVATE_NAME (OUTVAR, NAME, NUMBER)' |
| A C expression to assign to OUTVAR (which is a variable of type |
| `char *') a newly allocated string made from the string NAME and |
| the number NUMBER, with some suitable punctuation added. Use |
| `alloca' to get space for the string. |
| |
| The string will be used as an argument to `ASM_OUTPUT_LABELREF' to |
| produce an assembler label for an internal static variable whose |
| name is NAME. Therefore, the string must be such as to result in |
| valid assembler code. The argument NUMBER is different each time |
| this macro is executed; it prevents conflicts between |
| similarly-named internal static variables in different scopes. |
| |
| Ideally this string should not be a valid C identifier, to prevent |
| any conflict with the user's own symbols. Most assemblers allow |
| periods or percent signs in assembler symbols; putting at least |
| one of these between the name and the number will suffice. |
| |
| `ASM_OUTPUT_DEF (STREAM, NAME, VALUE)' |
| A C statement to output to the stdio stream STREAM assembler code |
| which defines (equates) the symbol NAME to have the value VALUE. |
| |
| If SET_ASM_OP is defined, a default definition is provided which is |
| correct for most systems. |
| |
| `ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL (STREAM, SYMBOL, HIGH, LOW)' |
| A C statement to output to the stdio stream STREAM assembler code |
| which defines (equates) the symbol SYMBOL to have a value equal to |
| the difference of the two symbols HIGH and LOW, i.e. HIGH minus |
| LOW. GNU CC guarantees that the symbols HIGH and LOW are already |
| known by the assembler so that the difference resolves into a |
| constant. |
| |
| If SET_ASM_OP is defined, a default definition is provided which is |
| correct for most systems. |
| |
| `ASM_OUTPUT_WEAK_ALIAS (STREAM, NAME, VALUE)' |
| A C statement to output to the stdio stream STREAM assembler code |
| which defines (equates) the weak symbol NAME to have the value |
| VALUE. |
| |
| Define this macro if the target only supports weak aliases; define |
| ASM_OUTPUT_DEF instead if possible. |
| |
| `OBJC_GEN_METHOD_LABEL (BUF, IS_INST, CLASS_NAME, CAT_NAME, SEL_NAME)' |
| Define this macro to override the default assembler names used for |
| Objective C methods. |
| |
| The default name is a unique method number followed by the name of |
| the class (e.g. `_1_Foo'). For methods in categories, the name of |
| the category is also included in the assembler name (e.g. |
| `_1_Foo_Bar'). |
| |
| These names are safe on most systems, but make debugging difficult |
| since the method's selector is not present in the name. |
| Therefore, particular systems define other ways of computing names. |
| |
| BUF is an expression of type `char *' which gives you a buffer in |
| which to store the name; its length is as long as CLASS_NAME, |
| CAT_NAME and SEL_NAME put together, plus 50 characters extra. |
| |
| The argument IS_INST specifies whether the method is an instance |
| method or a class method; CLASS_NAME is the name of the class; |
| CAT_NAME is the name of the category (or NULL if the method is not |
| in a category); and SEL_NAME is the name of the selector. |
| |
| On systems where the assembler can handle quoted names, you can |
| use this macro to provide more human-readable names. |
| |