1 This is Info file gcc.info, produced by Makeinfo version 1.68 from the
4 This file documents the use and the internals of the GNU compiler.
6 Published by the Free Software Foundation 59 Temple Place - Suite 330
7 Boston, MA 02111-1307 USA
9 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998
10 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided also
18 that the sections entitled "GNU General Public License," "Funding for
19 Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
20 included exactly as in the original, and provided that the entire
21 resulting derived work is distributed under the terms of a permission
22 notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that the sections entitled "GNU General Public
27 License," "Funding for Free Software," and "Protect Your Freedom--Fight
28 `Look And Feel'", and this permission notice, may be included in
29 translations approved by the Free Software Foundation instead of in the
33 File: gcc.info, Node: Costs, Next: Sections, Prev: Condition Code, Up: Target Macros
35 Describing Relative Costs of Operations
36 =======================================
38 These macros let you describe the relative speed of various
39 operations on the target machine.
41 `CONST_COSTS (X, CODE, OUTER_CODE)'
42 A part of a C `switch' statement that describes the relative costs
43 of constant RTL expressions. It must contain `case' labels for
44 expression codes `const_int', `const', `symbol_ref', `label_ref'
45 and `const_double'. Each case must ultimately reach a `return'
46 statement to return the relative cost of the use of that kind of
47 constant value in an expression. The cost may depend on the
48 precise value of the constant, which is available for examination
49 in X, and the rtx code of the expression in which it is contained,
52 CODE is the expression code--redundant, since it can be obtained
55 `RTX_COSTS (X, CODE, OUTER_CODE)'
56 Like `CONST_COSTS' but applies to nonconstant RTL expressions.
57 This can be used, for example, to indicate how costly a multiply
58 instruction is. In writing this macro, you can use the construct
59 `COSTS_N_INSNS (N)' to specify a cost equal to N fast
60 instructions. OUTER_CODE is the code of the expression in which X
63 This macro is optional; do not define it if the default cost
64 assumptions are adequate for the target machine.
66 `ADDRESS_COST (ADDRESS)'
67 An expression giving the cost of an addressing mode that contains
68 ADDRESS. If not defined, the cost is computed from the ADDRESS
69 expression and the `CONST_COSTS' values.
71 For most CISC machines, the default cost is a good approximation
72 of the true cost of the addressing mode. However, on RISC
73 machines, all instructions normally have the same length and
74 execution time. Hence all addresses will have equal costs.
76 In cases where more than one form of an address is known, the form
77 with the lowest cost will be used. If multiple forms have the
78 same, lowest, cost, the one that is the most complex will be used.
80 For example, suppose an address that is equal to the sum of a
81 register and a constant is used twice in the same basic block.
82 When this macro is not defined, the address will be computed in a
83 register and memory references will be indirect through that
84 register. On machines where the cost of the addressing mode
85 containing the sum is no higher than that of a simple indirect
86 reference, this will produce an additional instruction and
87 possibly require an additional register. Proper specification of
88 this macro eliminates this overhead for such machines.
90 Similar use of this macro is made in strength reduction of loops.
92 ADDRESS need not be valid as an address. In such a case, the cost
93 is not relevant and can be any value; invalid addresses need not be
94 assigned a different cost.
96 On machines where an address involving more than one register is as
97 cheap as an address computation involving only one register,
98 defining `ADDRESS_COST' to reflect this can cause two registers to
99 be live over a region of code where only one would have been if
100 `ADDRESS_COST' were not defined in that manner. This effect should
101 be considered in the definition of this macro. Equivalent costs
102 should probably only be given to addresses with different numbers
103 of registers on machines with lots of registers.
105 This macro will normally either not be defined or be defined as a
108 `REGISTER_MOVE_COST (FROM, TO)'
109 A C expression for the cost of moving data from a register in class
110 FROM to one in class TO. The classes are expressed using the
111 enumeration values such as `GENERAL_REGS'. A value of 2 is the
112 default; other values are interpreted relative to that.
114 It is not required that the cost always equal 2 when FROM is the
115 same as TO; on some machines it is expensive to move between
116 registers if they are not general registers.
118 If reload sees an insn consisting of a single `set' between two
119 hard registers, and if `REGISTER_MOVE_COST' applied to their
120 classes returns a value of 2, reload does not check to ensure that
121 the constraints of the insn are met. Setting a cost of other than
122 2 will allow reload to verify that the constraints are met. You
123 should do this if the `movM' pattern's constraints do not allow
126 `MEMORY_MOVE_COST (M)'
127 A C expression for the cost of moving data of mode M between a
128 register and memory. A value of 4 is the default; this cost is
129 relative to those in `REGISTER_MOVE_COST'.
131 If moving between registers and memory is more expensive than
132 between two registers, you should define this macro to express the
136 A C expression for the cost of a branch instruction. A value of 1
137 is the default; other values are interpreted relative to that.
139 Here are additional macros which do not specify precise relative
140 costs, but only that certain actions are more expensive than GNU CC
141 would ordinarily expect.
144 Define this macro as a C expression which is nonzero if accessing
145 less than a word of memory (i.e. a `char' or a `short') is no
146 faster than accessing a word of memory, i.e., if such access
147 require more than one instruction or if there is no difference in
148 cost between byte and (aligned) word loads.
150 When this macro is not defined, the compiler will access a field by
151 finding the smallest containing object; when it is defined, a
152 fullword load will be used if alignment permits. Unless bytes
153 accesses are faster than word accesses, using word accesses is
154 preferable since it may eliminate subsequent memory access if
155 subsequent accesses occur to other fields in the same word of the
156 structure, but to different bytes.
159 Define this macro if zero-extension (of a `char' or `short' to an
160 `int') can be done faster if the destination is a register that is
163 If you define this macro, you must have instruction patterns that
164 recognize RTL structures like this:
166 (set (strict_low_part (subreg:QI (reg:SI ...) 0)) ...)
168 and likewise for `HImode'.
170 `SLOW_UNALIGNED_ACCESS'
171 Define this macro to be the value 1 if unaligned accesses have a
172 cost many times greater than aligned accesses, for example if they
173 are emulated in a trap handler.
175 When this macro is non-zero, the compiler will act as if
176 `STRICT_ALIGNMENT' were non-zero when generating code for block
177 moves. This can cause significantly more instructions to be
178 produced. Therefore, do not set this macro non-zero if unaligned
179 accesses only add a cycle or two to the time for a memory access.
181 If the value of this macro is always zero, it need not be defined.
184 Define this macro to inhibit strength reduction of memory
185 addresses. (On some machines, such strength reduction seems to do
186 harm rather than good.)
189 The number of scalar move insns which should be generated instead
190 of a string move insn or a library call. Increasing the value
191 will always make code faster, but eventually incurs high cost in
194 If you don't define this, a reasonable default is used.
197 Define this macro if it is as good or better to call a constant
198 function address than to call an address kept in a register.
200 `NO_RECURSIVE_FUNCTION_CSE'
201 Define this macro if it is as good or better for a function to call
202 itself with an explicit address than to call an address kept in a
205 `ADJUST_COST (INSN, LINK, DEP_INSN, COST)'
206 A C statement (sans semicolon) to update the integer variable COST
207 based on the relationship between INSN that is dependent on
208 DEP_INSN through the dependence LINK. The default is to make no
209 adjustment to COST. This can be used for example to specify to
210 the scheduler that an output- or anti-dependence does not incur
211 the same cost as a data-dependence.
213 `ADJUST_PRIORITY (INSN)'
214 A C statement (sans semicolon) to update the integer scheduling
215 priority `INSN_PRIORITY(INSN)'. Reduce the priority to execute
216 the INSN earlier, increase the priority to execute INSN later.
217 Do not define this macro if you do not need to adjust the
218 scheduling priorities of insns.
221 File: gcc.info, Node: Sections, Next: PIC, Prev: Costs, Up: Target Macros
223 Dividing the Output into Sections (Texts, Data, ...)
224 ====================================================
226 An object file is divided into sections containing different types of
227 data. In the most common case, there are three sections: the "text
228 section", which holds instructions and read-only data; the "data
229 section", which holds initialized writable data; and the "bss section",
230 which holds uninitialized data. Some systems have other kinds of
233 The compiler must tell the assembler when to switch sections. These
234 macros control what commands to output to tell the assembler this. You
235 can also define additional sections.
237 `TEXT_SECTION_ASM_OP'
238 A C expression whose value is a string containing the assembler
239 operation that should precede instructions and read-only data.
240 Normally `".text"' is right.
242 `DATA_SECTION_ASM_OP'
243 A C expression whose value is a string containing the assembler
244 operation to identify the following data as writable initialized
245 data. Normally `".data"' is right.
247 `SHARED_SECTION_ASM_OP'
248 If defined, a C expression whose value is a string containing the
249 assembler operation to identify the following data as shared data.
250 If not defined, `DATA_SECTION_ASM_OP' will be used.
253 If defined, a C expression whose value is a string containing the
254 assembler operation to identify the following data as
255 uninitialized global data. If not defined, and neither
256 `ASM_OUTPUT_BSS' nor `ASM_OUTPUT_ALIGNED_BSS' are defined,
257 uninitialized global data will be output in the data section if
258 `-fno-common' is passed, otherwise `ASM_OUTPUT_COMMON' will be
261 `SHARED_BSS_SECTION_ASM_OP'
262 If defined, a C expression whose value is a string containing the
263 assembler operation to identify the following data as
264 uninitialized global shared data. If not defined, and
265 `BSS_SECTION_ASM_OP' is, the latter will be used.
267 `INIT_SECTION_ASM_OP'
268 If defined, a C expression whose value is a string containing the
269 assembler operation to identify the following data as
270 initialization code. If not defined, GNU CC will assume such a
271 section does not exist.
274 A list of names for sections other than the standard two, which are
275 `in_text' and `in_data'. You need not define this macro on a
276 system with no other sections (that GCC needs to use).
278 `EXTRA_SECTION_FUNCTIONS'
279 One or more functions to be defined in `varasm.c'. These
280 functions should do jobs analogous to those of `text_section' and
281 `data_section', for your additional sections. Do not define this
282 macro if you do not define `EXTRA_SECTIONS'.
284 `READONLY_DATA_SECTION'
285 On most machines, read-only variables, constants, and jump tables
286 are placed in the text section. If this is not the case on your
287 machine, this macro should be defined to be the name of a function
288 (either `data_section' or a function defined in `EXTRA_SECTIONS')
289 that switches to the section to be used for read-only items.
291 If these items should be placed in the text section, this macro
292 should not be defined.
294 `SELECT_SECTION (EXP, RELOC)'
295 A C statement or statements to switch to the appropriate section
296 for output of EXP. You can assume that EXP is either a `VAR_DECL'
297 node or a constant of some sort. RELOC indicates whether the
298 initial value of EXP requires link-time relocations. Select the
299 section by calling `text_section' or one of the alternatives for
302 Do not define this macro if you put all read-only variables and
303 constants in the read-only data section (usually the text section).
305 `SELECT_RTX_SECTION (MODE, RTX)'
306 A C statement or statements to switch to the appropriate section
307 for output of RTX in mode MODE. You can assume that RTX is some
308 kind of constant in RTL. The argument MODE is redundant except in
309 the case of a `const_int' rtx. Select the section by calling
310 `text_section' or one of the alternatives for other sections.
312 Do not define this macro if you put all constants in the read-only
315 `JUMP_TABLES_IN_TEXT_SECTION'
316 Define this macro if jump tables (for `tablejump' insns) should be
317 output in the text section, along with the assembler instructions.
318 Otherwise, the readonly data section is used.
320 This macro is irrelevant if there is no separate readonly data
323 `ENCODE_SECTION_INFO (DECL)'
324 Define this macro if references to a symbol must be treated
325 differently depending on something about the variable or function
326 named by the symbol (such as what section it is in).
328 The macro definition, if any, is executed immediately after the
329 rtl for DECL has been created and stored in `DECL_RTL (DECL)'.
330 The value of the rtl will be a `mem' whose address is a
333 The usual thing for this macro to do is to record a flag in the
334 `symbol_ref' (such as `SYMBOL_REF_FLAG') or to store a modified
335 name string in the `symbol_ref' (if one bit is not enough
338 `STRIP_NAME_ENCODING (VAR, SYM_NAME)'
339 Decode SYM_NAME and store the real name part in VAR, sans the
340 characters that encode section info. Define this macro if
341 `ENCODE_SECTION_INFO' alters the symbol's name string.
343 `UNIQUE_SECTION_P (DECL)'
344 A C expression which evaluates to true if DECL should be placed
345 into a unique section for some target-specific reason. If you do
346 not define this macro, the default is `0'. Note that the flag
347 `-ffunction-sections' will also cause functions to be placed into
350 `UNIQUE_SECTION (DECL, RELOC)'
351 A C statement to build up a unique section name, expressed as a
352 STRING_CST node, and assign it to `DECL_SECTION_NAME (DECL)'.
353 RELOC indicates whether the initial value of EXP requires
354 link-time relocations. If you do not define this macro, GNU CC
355 will use the symbol name prefixed by `.' as the section name.
358 File: gcc.info, Node: PIC, Next: Assembler Format, Prev: Sections, Up: Target Macros
360 Position Independent Code
361 =========================
363 This section describes macros that help implement generation of
364 position independent code. Simply defining these macros is not enough
365 to generate valid PIC; you must also add support to the macros
366 `GO_IF_LEGITIMATE_ADDRESS' and `PRINT_OPERAND_ADDRESS', as well as
367 `LEGITIMIZE_ADDRESS'. You must modify the definition of `movsi' to do
368 something appropriate when the source operand contains a symbolic
369 address. You may also need to alter the handling of switch statements
370 so that they use relative addresses.
372 `PIC_OFFSET_TABLE_REGNUM'
373 The register number of the register used to address a table of
374 static data addresses in memory. In some cases this register is
375 defined by a processor's "application binary interface" (ABI).
376 When this macro is defined, RTL is generated for this register
377 once, as with the stack pointer and frame pointer registers. If
378 this macro is not defined, it is up to the machine-dependent files
379 to allocate such a register (if necessary).
381 `PIC_OFFSET_TABLE_REG_CALL_CLOBBERED'
382 Define this macro if the register defined by
383 `PIC_OFFSET_TABLE_REGNUM' is clobbered by calls. Do not define
384 this macro if `PPIC_OFFSET_TABLE_REGNUM' is not defined.
387 By generating position-independent code, when two different
388 programs (A and B) share a common library (libC.a), the text of
389 the library can be shared whether or not the library is linked at
390 the same address for both programs. In some of these
391 environments, position-independent code requires not only the use
392 of different addressing modes, but also special code to enable the
393 use of these addressing modes.
395 The `FINALIZE_PIC' macro serves as a hook to emit these special
396 codes once the function is being compiled into assembly code, but
397 not before. (It is not done before, because in the case of
398 compiling an inline function, it would lead to multiple PIC
399 prologues being included in functions which used inline functions
400 and were compiled to assembly language.)
402 `LEGITIMATE_PIC_OPERAND_P (X)'
403 A C expression that is nonzero if X is a legitimate immediate
404 operand on the target machine when generating position independent
405 code. You can assume that X satisfies `CONSTANT_P', so you need
406 not check this. You can also assume FLAG_PIC is true, so you need
407 not check it either. You need not define this macro if all
408 constants (including `SYMBOL_REF') can be immediate operands when
409 generating position independent code.
412 File: gcc.info, Node: Assembler Format, Next: Debugging Info, Prev: PIC, Up: Target Macros
414 Defining the Output Assembler Language
415 ======================================
417 This section describes macros whose principal purpose is to describe
418 how to write instructions in assembler language-rather than what the
423 * File Framework:: Structural information for the assembler file.
424 * Data Output:: Output of constants (numbers, strings, addresses).
425 * Uninitialized Data:: Output of uninitialized variables.
426 * Label Output:: Output and generation of labels.
427 * Initialization:: General principles of initialization
428 and termination routines.
429 * Macros for Initialization::
430 Specific macros that control the handling of
431 initialization and termination routines.
432 * Instruction Output:: Output of actual instructions.
433 * Dispatch Tables:: Output of jump tables.
434 * Exception Region Output:: Output of exception region code.
435 * Alignment Output:: Pseudo ops for alignment and skipping data.
438 File: gcc.info, Node: File Framework, Next: Data Output, Up: Assembler Format
440 The Overall Framework of an Assembler File
441 ------------------------------------------
443 This describes the overall framework of an assembler file.
445 `ASM_FILE_START (STREAM)'
446 A C expression which outputs to the stdio stream STREAM some
447 appropriate text to go at the start of an assembler file.
449 Normally this macro is defined to output a line containing
450 `#NO_APP', which is a comment that has no effect on most
451 assemblers but tells the GNU assembler that it can save time by not
452 checking for certain assembler constructs.
454 On systems that use SDB, it is necessary to output certain
455 commands; see `attasm.h'.
457 `ASM_FILE_END (STREAM)'
458 A C expression which outputs to the stdio stream STREAM some
459 appropriate text to go at the end of an assembler file.
461 If this macro is not defined, the default is to output nothing
462 special at the end of the file. Most systems don't require any
465 On systems that use SDB, it is necessary to output certain
466 commands; see `attasm.h'.
468 `ASM_IDENTIFY_GCC (FILE)'
469 A C statement to output assembler commands which will identify the
470 object file as having been compiled with GNU CC (or another GNU
473 If you don't define this macro, the string `gcc_compiled.:' is
474 output. This string is calculated to define a symbol which, on
475 BSD systems, will never be defined for any other reason. GDB
476 checks for the presence of this symbol when reading the symbol
477 table of an executable.
479 On non-BSD systems, you must arrange communication with GDB in
480 some other fashion. If GDB is not used on your system, you can
481 define this macro with an empty body.
484 A C string constant describing how to begin a comment in the target
485 assembler language. The compiler assumes that the comment will
486 end at the end of the line.
489 A C string constant for text to be output before each `asm'
490 statement or group of consecutive ones. Normally this is
491 `"#APP"', which is a comment that has no effect on most assemblers
492 but tells the GNU assembler that it must check the lines that
493 follow for all valid assembler constructs.
496 A C string constant for text to be output after each `asm'
497 statement or group of consecutive ones. Normally this is
498 `"#NO_APP"', which tells the GNU assembler to resume making the
499 time-saving assumptions that are valid for ordinary compiler
502 `ASM_OUTPUT_SOURCE_FILENAME (STREAM, NAME)'
503 A C statement to output COFF information or DWARF debugging
504 information which indicates that filename NAME is the current
505 source file to the stdio stream STREAM.
507 This macro need not be defined if the standard form of output for
508 the file format in use is appropriate.
510 `OUTPUT_QUOTED_STRING (STREAM, NAME)'
511 A C statement to output the string STRING to the stdio stream
512 STREAM. If you do not call the function `output_quoted_string' in
513 your config files, GNU CC will only call it to output filenames to
514 the assembler source. So you can use it to canonicalize the format
515 of the filename using this macro.
517 `ASM_OUTPUT_SOURCE_LINE (STREAM, LINE)'
518 A C statement to output DBX or SDB debugging information before
519 code for line number LINE of the current source file to the stdio
522 This macro need not be defined if the standard form of debugging
523 information for the debugger in use is appropriate.
525 `ASM_OUTPUT_IDENT (STREAM, STRING)'
526 A C statement to output something to the assembler file to handle a
527 `#ident' directive containing the text STRING. If this macro is
528 not defined, nothing is output for a `#ident' directive.
530 `ASM_OUTPUT_SECTION_NAME (STREAM, DECL, NAME, RELOC)'
531 A C statement to output something to the assembler file to switch
532 to section NAME for object DECL which is either a `FUNCTION_DECL',
533 a `VAR_DECL' or `NULL_TREE'. RELOC indicates whether the initial
534 value of EXP requires link-time relocations. Some target formats
535 do not support arbitrary sections. Do not define this macro in
538 At present this macro is only used to support section attributes.
539 When this macro is undefined, section attributes are disabled.
542 A C statement to output any assembler statements which are
543 required to precede any Objective C object definitions or message
544 sending. The statement is executed only when compiling an
548 File: gcc.info, Node: Data Output, Next: Uninitialized Data, Prev: File Framework, Up: Assembler Format
553 This describes data output.
555 `ASM_OUTPUT_LONG_DOUBLE (STREAM, VALUE)'
556 `ASM_OUTPUT_DOUBLE (STREAM, VALUE)'
557 `ASM_OUTPUT_FLOAT (STREAM, VALUE)'
558 `ASM_OUTPUT_THREE_QUARTER_FLOAT (STREAM, VALUE)'
559 `ASM_OUTPUT_SHORT_FLOAT (STREAM, VALUE)'
560 `ASM_OUTPUT_BYTE_FLOAT (STREAM, VALUE)'
561 A C statement to output to the stdio stream STREAM an assembler
562 instruction to assemble a floating-point constant of `TFmode',
563 `DFmode', `SFmode', `TQFmode', `HFmode', or `QFmode',
564 respectively, whose value is VALUE. VALUE will be a C expression
565 of type `REAL_VALUE_TYPE'. Macros such as
566 `REAL_VALUE_TO_TARGET_DOUBLE' are useful for writing these
569 `ASM_OUTPUT_QUADRUPLE_INT (STREAM, EXP)'
570 `ASM_OUTPUT_DOUBLE_INT (STREAM, EXP)'
571 `ASM_OUTPUT_INT (STREAM, EXP)'
572 `ASM_OUTPUT_SHORT (STREAM, EXP)'
573 `ASM_OUTPUT_CHAR (STREAM, EXP)'
574 A C statement to output to the stdio stream STREAM an assembler
575 instruction to assemble an integer of 16, 8, 4, 2 or 1 bytes,
576 respectively, whose value is VALUE. The argument EXP will be an
577 RTL expression which represents a constant value. Use
578 `output_addr_const (STREAM, EXP)' to output this value as an
579 assembler expression.
581 For sizes larger than `UNITS_PER_WORD', if the action of a macro
582 would be identical to repeatedly calling the macro corresponding to
583 a size of `UNITS_PER_WORD', once for each word, you need not define
586 `ASM_OUTPUT_BYTE (STREAM, VALUE)'
587 A C statement to output to the stdio stream STREAM an assembler
588 instruction to assemble a single byte containing the number VALUE.
591 A C string constant giving the pseudo-op to use for a sequence of
592 single-byte constants. If this macro is not defined, the default
595 `ASM_OUTPUT_ASCII (STREAM, PTR, LEN)'
596 A C statement to output to the stdio stream STREAM an assembler
597 instruction to assemble a string constant containing the LEN bytes
598 at PTR. PTR will be a C expression of type `char *' and LEN a C
599 expression of type `int'.
601 If the assembler has a `.ascii' pseudo-op as found in the Berkeley
602 Unix assembler, do not define the macro `ASM_OUTPUT_ASCII'.
604 `CONSTANT_POOL_BEFORE_FUNCTION'
605 You may define this macro as a C expression. You should define the
606 expression to have a non-zero value if GNU CC should output the
607 constant pool for a function before the code for the function, or
608 a zero value if GNU CC should output the constant pool after the
609 function. If you do not define this macro, the usual case, GNU CC
610 will output the constant pool before the function.
612 `ASM_OUTPUT_POOL_PROLOGUE (FILE FUNNAME FUNDECL SIZE)'
613 A C statement to output assembler commands to define the start of
614 the constant pool for a function. FUNNAME is a string giving the
615 name of the function. Should the return type of the function be
616 required, it can be obtained via FUNDECL. SIZE is the size, in
617 bytes, of the constant pool that will be written immediately after
620 If no constant-pool prefix is required, the usual case, this macro
623 `ASM_OUTPUT_SPECIAL_POOL_ENTRY (FILE, X, MODE, ALIGN, LABELNO, JUMPTO)'
624 A C statement (with or without semicolon) to output a constant in
625 the constant pool, if it needs special treatment. (This macro
626 need not do anything for RTL expressions that can be output
629 The argument FILE is the standard I/O stream to output the
630 assembler code on. X is the RTL expression for the constant to
631 output, and MODE is the machine mode (in case X is a `const_int').
632 ALIGN is the required alignment for the value X; you should
633 output an assembler directive to force this much alignment.
635 The argument LABELNO is a number to use in an internal label for
636 the address of this pool entry. The definition of this macro is
637 responsible for outputting the label definition at the proper
638 place. Here is how to do this:
640 ASM_OUTPUT_INTERNAL_LABEL (FILE, "LC", LABELNO);
642 When you output a pool entry specially, you should end with a
643 `goto' to the label JUMPTO. This will prevent the same pool entry
644 from being output a second time in the usual manner.
646 You need not define this macro if it would do nothing.
648 `CONSTANT_AFTER_FUNCTION_P (EXP)'
649 Define this macro as a C expression which is nonzero if the
650 constant EXP, of type `tree', should be output after the code for a
651 function. The compiler will normally output all constants before
652 the function; you need not define this macro if this is OK.
654 `ASM_OUTPUT_POOL_EPILOGUE (FILE FUNNAME FUNDECL SIZE)'
655 A C statement to output assembler commands to at the end of the
656 constant pool for a function. FUNNAME is a string giving the name
657 of the function. Should the return type of the function be
658 required, you can obtain it via FUNDECL. SIZE is the size, in
659 bytes, of the constant pool that GNU CC wrote immediately before
662 If no constant-pool epilogue is required, the usual case, you need
663 not define this macro.
665 `IS_ASM_LOGICAL_LINE_SEPARATOR (C)'
666 Define this macro as a C expression which is nonzero if C is used
667 as a logical line separator by the assembler.
669 If you do not define this macro, the default is that only the
670 character `;' is treated as a logical line separator.
674 These macros are defined as C string constant, describing the
675 syntax in the assembler for grouping arithmetic expressions. The
676 following definitions are correct for most assemblers:
678 #define ASM_OPEN_PAREN "("
679 #define ASM_CLOSE_PAREN ")"
681 These macros are provided by `real.h' for writing the definitions of
682 `ASM_OUTPUT_DOUBLE' and the like:
684 `REAL_VALUE_TO_TARGET_SINGLE (X, L)'
685 `REAL_VALUE_TO_TARGET_DOUBLE (X, L)'
686 `REAL_VALUE_TO_TARGET_LONG_DOUBLE (X, L)'
687 These translate X, of type `REAL_VALUE_TYPE', to the target's
688 floating point representation, and store its bit pattern in the
689 array of `long int' whose address is L. The number of elements in
690 the output array is determined by the size of the desired target
691 floating point data type: 32 bits of it go in each `long int' array
692 element. Each array element holds 32 bits of the result, even if
693 `long int' is wider than 32 bits on the host machine.
695 The array element values are designed so that you can print them
696 out using `fprintf' in the order they should appear in the target
699 `REAL_VALUE_TO_DECIMAL (X, FORMAT, STRING)'
700 This macro converts X, of type `REAL_VALUE_TYPE', to a decimal
701 number and stores it as a string into STRING. You must pass, as
702 STRING, the address of a long enough block of space to hold the
705 The argument FORMAT is a `printf'-specification that serves as a
706 suggestion for how to format the output string.
709 File: gcc.info, Node: Uninitialized Data, Next: Label Output, Prev: Data Output, Up: Assembler Format
711 Output of Uninitialized Variables
712 ---------------------------------
714 Each of the macros in this section is used to do the whole job of
715 outputting a single uninitialized variable.
717 `ASM_OUTPUT_COMMON (STREAM, NAME, SIZE, ROUNDED)'
718 A C statement (sans semicolon) to output to the stdio stream
719 STREAM the assembler definition of a common-label named NAME whose
720 size is SIZE bytes. The variable ROUNDED is the size rounded up
721 to whatever alignment the caller wants.
723 Use the expression `assemble_name (STREAM, NAME)' to output the
724 name itself; before and after that, output the additional
725 assembler syntax for defining the name, and a newline.
727 This macro controls how the assembler definitions of uninitialized
728 common global variables are output.
730 `ASM_OUTPUT_ALIGNED_COMMON (STREAM, NAME, SIZE, ALIGNMENT)'
731 Like `ASM_OUTPUT_COMMON' except takes the required alignment as a
732 separate, explicit argument. If you define this macro, it is used
733 in place of `ASM_OUTPUT_COMMON', and gives you more flexibility in
734 handling the required alignment of the variable. The alignment is
735 specified as the number of bits.
737 `ASM_OUTPUT_ALIGNED_DECL_COMMON (STREAM, DECL, NAME, SIZE, ALIGNMENT)'
738 Like `ASM_OUTPUT_ALIGNED_COMMON' except that DECL of the variable
739 to be output, if there is one, or `NULL_TREE' if there is not
740 corresponding variable. If you define this macro, GNU CC wil use
741 it in place of both `ASM_OUTPUT_COMMON' and
742 `ASM_OUTPUT_ALIGNED_COMMON'. Define this macro when you need to
743 see the variable's decl in order to chose what to output.
745 `ASM_OUTPUT_SHARED_COMMON (STREAM, NAME, SIZE, ROUNDED)'
746 If defined, it is similar to `ASM_OUTPUT_COMMON', except that it
747 is used when NAME is shared. If not defined, `ASM_OUTPUT_COMMON'
750 `ASM_OUTPUT_BSS (STREAM, DECL, NAME, SIZE, ROUNDED)'
751 A C statement (sans semicolon) to output to the stdio stream
752 STREAM the assembler definition of uninitialized global DECL named
753 NAME whose size is SIZE bytes. The variable ROUNDED is the size
754 rounded up to whatever alignment the caller wants.
756 Try to use function `asm_output_bss' defined in `varasm.c' when
757 defining this macro. If unable, use the expression `assemble_name
758 (STREAM, NAME)' to output the name itself; before and after that,
759 output the additional assembler syntax for defining the name, and
762 This macro controls how the assembler definitions of uninitialized
763 global variables are output. This macro exists to properly
764 support languages like `c++' which do not have `common' data.
765 However, this macro currently is not defined for all targets. If
766 this macro and `ASM_OUTPUT_ALIGNED_BSS' are not defined then
767 `ASM_OUTPUT_COMMON' or `ASM_OUTPUT_ALIGNED_COMMON' or
768 `ASM_OUTPUT_ALIGNED_DECL_COMMON' is used.
770 `ASM_OUTPUT_ALIGNED_BSS (STREAM, DECL, NAME, SIZE, ALIGNMENT)'
771 Like `ASM_OUTPUT_BSS' except takes the required alignment as a
772 separate, explicit argument. If you define this macro, it is used
773 in place of `ASM_OUTPUT_BSS', and gives you more flexibility in
774 handling the required alignment of the variable. The alignment is
775 specified as the number of bits.
777 Try to use function `asm_output_aligned_bss' defined in file
778 `varasm.c' when defining this macro.
780 `ASM_OUTPUT_SHARED_BSS (STREAM, DECL, NAME, SIZE, ROUNDED)'
781 If defined, it is similar to `ASM_OUTPUT_BSS', except that it is
782 used when NAME is shared. If not defined, `ASM_OUTPUT_BSS' will
785 `ASM_OUTPUT_LOCAL (STREAM, NAME, SIZE, ROUNDED)'
786 A C statement (sans semicolon) to output to the stdio stream
787 STREAM the assembler definition of a local-common-label named NAME
788 whose size is SIZE bytes. The variable ROUNDED is the size
789 rounded up to whatever alignment the caller wants.
791 Use the expression `assemble_name (STREAM, NAME)' to output the
792 name itself; before and after that, output the additional
793 assembler syntax for defining the name, and a newline.
795 This macro controls how the assembler definitions of uninitialized
796 static variables are output.
798 `ASM_OUTPUT_ALIGNED_LOCAL (STREAM, NAME, SIZE, ALIGNMENT)'
799 Like `ASM_OUTPUT_LOCAL' except takes the required alignment as a
800 separate, explicit argument. If you define this macro, it is used
801 in place of `ASM_OUTPUT_LOCAL', and gives you more flexibility in
802 handling the required alignment of the variable. The alignment is
803 specified as the number of bits.
805 `ASM_OUTPUT_ALIGNED_DECL_LOCAL (STREAM, DECL, NAME, SIZE, ALIGNMENT)'
806 Like `ASM_OUTPUT_ALIGNED_DECL' except that DECL of the variable to
807 be output, if there is one, or `NULL_TREE' if there is not
808 corresponding variable. If you define this macro, GNU CC wil use
809 it in place of both `ASM_OUTPUT_DECL' and
810 `ASM_OUTPUT_ALIGNED_DECL'. Define this macro when you need to see
811 the variable's decl in order to chose what to output.
813 `ASM_OUTPUT_SHARED_LOCAL (STREAM, NAME, SIZE, ROUNDED)'
814 If defined, it is similar to `ASM_OUTPUT_LOCAL', except that it is
815 used when NAME is shared. If not defined, `ASM_OUTPUT_LOCAL' will
819 File: gcc.info, Node: Label Output, Next: Initialization, Prev: Uninitialized Data, Up: Assembler Format
821 Output and Generation of Labels
822 -------------------------------
824 This is about outputting labels.
826 `ASM_OUTPUT_LABEL (STREAM, NAME)'
827 A C statement (sans semicolon) to output to the stdio stream
828 STREAM the assembler definition of a label named NAME. Use the
829 expression `assemble_name (STREAM, NAME)' to output the name
830 itself; before and after that, output the additional assembler
831 syntax for defining the name, and a newline.
833 `ASM_DECLARE_FUNCTION_NAME (STREAM, NAME, DECL)'
834 A C statement (sans semicolon) to output to the stdio stream
835 STREAM any text necessary for declaring the name NAME of a
836 function which is being defined. This macro is responsible for
837 outputting the label definition (perhaps using
838 `ASM_OUTPUT_LABEL'). The argument DECL is the `FUNCTION_DECL'
839 tree node representing the function.
841 If this macro is not defined, then the function name is defined in
842 the usual manner as a label (by means of `ASM_OUTPUT_LABEL').
844 `ASM_DECLARE_FUNCTION_SIZE (STREAM, NAME, DECL)'
845 A C statement (sans semicolon) to output to the stdio stream
846 STREAM any text necessary for declaring the size of a function
847 which is being defined. The argument NAME is the name of the
848 function. The argument DECL is the `FUNCTION_DECL' tree node
849 representing the function.
851 If this macro is not defined, then the function size is not
854 `ASM_DECLARE_OBJECT_NAME (STREAM, NAME, DECL)'
855 A C statement (sans semicolon) to output to the stdio stream
856 STREAM any text necessary for declaring the name NAME of an
857 initialized variable which is being defined. This macro must
858 output the label definition (perhaps using `ASM_OUTPUT_LABEL').
859 The argument DECL is the `VAR_DECL' tree node representing the
862 If this macro is not defined, then the variable name is defined in
863 the usual manner as a label (by means of `ASM_OUTPUT_LABEL').
865 `ASM_FINISH_DECLARE_OBJECT (STREAM, DECL, TOPLEVEL, ATEND)'
866 A C statement (sans semicolon) to finish up declaring a variable
867 name once the compiler has processed its initializer fully and
868 thus has had a chance to determine the size of an array when
869 controlled by an initializer. This is used on systems where it's
870 necessary to declare something about the size of the object.
872 If you don't define this macro, that is equivalent to defining it
875 `ASM_GLOBALIZE_LABEL (STREAM, NAME)'
876 A C statement (sans semicolon) to output to the stdio stream
877 STREAM some commands that will make the label NAME global; that
878 is, available for reference from other files. Use the expression
879 `assemble_name (STREAM, NAME)' to output the name itself; before
880 and after that, output the additional assembler syntax for making
881 that name global, and a newline.
884 A C statement (sans semicolon) to output to the stdio stream
885 STREAM some commands that will make the label NAME weak; that is,
886 available for reference from other files but only used if no other
887 definition is available. Use the expression `assemble_name
888 (STREAM, NAME)' to output the name itself; before and after that,
889 output the additional assembler syntax for making that name weak,
892 If you don't define this macro, GNU CC will not support weak
893 symbols and you should not define the `SUPPORTS_WEAK' macro.
896 A C expression which evaluates to true if the target supports weak
899 If you don't define this macro, `defaults.h' provides a default
900 definition. If `ASM_WEAKEN_LABEL' is defined, the default
901 definition is `1'; otherwise, it is `0'. Define this macro if you
902 want to control weak symbol support with a compiler flag such as
906 A C statement (sans semicolon) to mark DECL to be emitted as a
907 public symbol such that extra copies in multiple translation units
908 will be discarded by the linker. Define this macro if your object
909 file format provides support for this concept, such as the `COMDAT'
910 section flags in the Microsoft Windows PE/COFF format, and this
911 support requires changes to DECL, such as putting it in a separate
915 A C expression which evaluates to true if the target supports
918 If you don't define this macro, `varasm.c' provides a default
919 definition. If `MAKE_DECL_ONE_ONLY' is defined, the default
920 definition is `1'; otherwise, it is `0'. Define this macro if you
921 want to control one-only symbol support with a compiler flag, or if
922 setting the `DECL_ONE_ONLY' flag is enough to mark a declaration to
923 be emitted as one-only.
925 `ASM_OUTPUT_EXTERNAL (STREAM, DECL, NAME)'
926 A C statement (sans semicolon) to output to the stdio stream
927 STREAM any text necessary for declaring the name of an external
928 symbol named NAME which is referenced in this compilation but not
929 defined. The value of DECL is the tree node for the declaration.
931 This macro need not be defined if it does not need to output
932 anything. The GNU assembler and most Unix assemblers don't
935 `ASM_OUTPUT_EXTERNAL_LIBCALL (STREAM, SYMREF)'
936 A C statement (sans semicolon) to output on STREAM an assembler
937 pseudo-op to declare a library function name external. The name
938 of the library function is given by SYMREF, which has type `rtx'
939 and is a `symbol_ref'.
941 This macro need not be defined if it does not need to output
942 anything. The GNU assembler and most Unix assemblers don't
945 `ASM_OUTPUT_LABELREF (STREAM, NAME)'
946 A C statement (sans semicolon) to output to the stdio stream
947 STREAM a reference in assembler syntax to a label named NAME.
948 This should add `_' to the front of the name, if that is customary
949 on your operating system, as it is in most Berkeley Unix systems.
950 This macro is used in `assemble_name'.
952 `ASM_OUTPUT_INTERNAL_LABEL (STREAM, PREFIX, NUM)'
953 A C statement to output to the stdio stream STREAM a label whose
954 name is made from the string PREFIX and the number NUM.
956 It is absolutely essential that these labels be distinct from the
957 labels used for user-level functions and variables. Otherwise,
958 certain programs will have name conflicts with internal labels.
960 It is desirable to exclude internal labels from the symbol table
961 of the object file. Most assemblers have a naming convention for
962 labels that should be excluded; on many systems, the letter `L' at
963 the beginning of a label has this effect. You should find out what
964 convention your system uses, and follow it.
966 The usual definition of this macro is as follows:
968 fprintf (STREAM, "L%s%d:\n", PREFIX, NUM)
970 `ASM_GENERATE_INTERNAL_LABEL (STRING, PREFIX, NUM)'
971 A C statement to store into the string STRING a label whose name
972 is made from the string PREFIX and the number NUM.
974 This string, when output subsequently by `assemble_name', should
975 produce the output that `ASM_OUTPUT_INTERNAL_LABEL' would produce
976 with the same PREFIX and NUM.
978 If the string begins with `*', then `assemble_name' will output
979 the rest of the string unchanged. It is often convenient for
980 `ASM_GENERATE_INTERNAL_LABEL' to use `*' in this way. If the
981 string doesn't start with `*', then `ASM_OUTPUT_LABELREF' gets to
982 output the string, and may change it. (Of course,
983 `ASM_OUTPUT_LABELREF' is also part of your machine description, so
984 you should know what it does on your machine.)
986 `ASM_FORMAT_PRIVATE_NAME (OUTVAR, NAME, NUMBER)'
987 A C expression to assign to OUTVAR (which is a variable of type
988 `char *') a newly allocated string made from the string NAME and
989 the number NUMBER, with some suitable punctuation added. Use
990 `alloca' to get space for the string.
992 The string will be used as an argument to `ASM_OUTPUT_LABELREF' to
993 produce an assembler label for an internal static variable whose
994 name is NAME. Therefore, the string must be such as to result in
995 valid assembler code. The argument NUMBER is different each time
996 this macro is executed; it prevents conflicts between
997 similarly-named internal static variables in different scopes.
999 Ideally this string should not be a valid C identifier, to prevent
1000 any conflict with the user's own symbols. Most assemblers allow
1001 periods or percent signs in assembler symbols; putting at least
1002 one of these between the name and the number will suffice.
1004 `ASM_OUTPUT_DEF (STREAM, NAME, VALUE)'
1005 A C statement to output to the stdio stream STREAM assembler code
1006 which defines (equates) the symbol NAME to have the value VALUE.
1008 If SET_ASM_OP is defined, a default definition is provided which is
1009 correct for most systems.
1011 `ASM_OUTPUT_DEFINE_LABEL_DIFFERENCE_SYMBOL (STREAM, SYMBOL, HIGH, LOW)'
1012 A C statement to output to the stdio stream STREAM assembler code
1013 which defines (equates) the symbol SYMBOL to have a value equal to
1014 the difference of the two symbols HIGH and LOW, i.e. HIGH minus
1015 LOW. GNU CC guarantees that the symbols HIGH and LOW are already
1016 known by the assembler so that the difference resolves into a
1019 If SET_ASM_OP is defined, a default definition is provided which is
1020 correct for most systems.
1022 `ASM_OUTPUT_WEAK_ALIAS (STREAM, NAME, VALUE)'
1023 A C statement to output to the stdio stream STREAM assembler code
1024 which defines (equates) the weak symbol NAME to have the value
1027 Define this macro if the target only supports weak aliases; define
1028 ASM_OUTPUT_DEF instead if possible.
1030 `OBJC_GEN_METHOD_LABEL (BUF, IS_INST, CLASS_NAME, CAT_NAME, SEL_NAME)'
1031 Define this macro to override the default assembler names used for
1032 Objective C methods.
1034 The default name is a unique method number followed by the name of
1035 the class (e.g. `_1_Foo'). For methods in categories, the name of
1036 the category is also included in the assembler name (e.g.
1039 These names are safe on most systems, but make debugging difficult
1040 since the method's selector is not present in the name.
1041 Therefore, particular systems define other ways of computing names.
1043 BUF is an expression of type `char *' which gives you a buffer in
1044 which to store the name; its length is as long as CLASS_NAME,
1045 CAT_NAME and SEL_NAME put together, plus 50 characters extra.
1047 The argument IS_INST specifies whether the method is an instance
1048 method or a class method; CLASS_NAME is the name of the class;
1049 CAT_NAME is the name of the category (or NULL if the method is not
1050 in a category); and SEL_NAME is the name of the selector.
1052 On systems where the assembler can handle quoted names, you can
1053 use this macro to provide more human-readable names.