![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-20 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / cc|
Return to gcc.info-20 CVS log | Up to [Apple XNU] / GNUtools / cc |
1.1 root 1: This is Info file gcc.info, produced by Makeinfo-1.54 from the input
2: file gcc.texi.
3:
4: This file documents the use and the internals of the GNU compiler.
5:
6: Published by the Free Software Foundation 675 Massachusetts Avenue
7: Cambridge, MA 02139 USA
8:
9: Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
10:
11: Permission is granted to make and distribute verbatim copies of this
12: manual provided the copyright notice and this permission notice are
13: preserved on all copies.
14:
15: Permission is granted to copy and distribute modified versions of
16: this manual under the conditions for verbatim copying, provided also
17: that the sections entitled "GNU General Public License" and "Protect
18: Your Freedom--Fight `Look And Feel'" are included exactly as in the
19: original, and provided that the entire resulting derived work is
20: distributed under the terms of a permission notice identical to this
21: one.
22:
23: Permission is granted to copy and distribute translations of this
24: manual into another language, under the above conditions for modified
25: versions, except that the sections entitled "GNU General Public
26: License" and "Protect Your Freedom--Fight `Look And Feel'", and this
27: permission notice, may be included in translations approved by the Free
28: Software Foundation instead of in the original English.
29:
30:
31: File: gcc.info, Node: Condition Code, Next: Costs, Prev: Addressing Modes, Up: Target Macros
32:
33: Condition Code Status
34: =====================
35:
36: The file `conditions.h' defines a variable `cc_status' to describe
37: how the condition code was computed (in case the interpretation of the
38: condition code depends on the instruction that it was set by). This
39: variable contains the RTL expressions on which the condition code is
40: currently based, and several standard flags.
41:
42: Sometimes additional machine-specific flags must be defined in the
43: machine description header file. It can also add additional
44: machine-specific information by defining `CC_STATUS_MDEP'.
45:
46: `CC_STATUS_MDEP'
47: C code for a data type which is used for declaring the `mdep'
48: component of `cc_status'. It defaults to `int'.
49:
50: This macro is not used on machines that do not use `cc0'.
51:
52: `CC_STATUS_MDEP_INIT'
53: A C expression to initialize the `mdep' field to "empty". The
54: default definition does nothing, since most machines don't use the
55: field anyway. If you want to use the field, you should probably
56: define this macro to initialize it.
57:
58: This macro is not used on machines that do not use `cc0'.
59:
60: `NOTICE_UPDATE_CC (EXP, INSN)'
61: A C compound statement to set the components of `cc_status'
62: appropriately for an insn INSN whose body is EXP. It is this
63: macro's responsibility to recognize insns that set the condition
64: code as a byproduct of other activity as well as those that
65: explicitly set `(cc0)'.
66:
67: This macro is not used on machines that do not use `cc0'.
68:
69: If there are insns that do not set the condition code but do alter
70: other machine registers, this macro must check to see whether they
71: invalidate the expressions that the condition code is recorded as
72: reflecting. For example, on the 68000, insns that store in address
73: registers do not set the condition code, which means that usually
74: `NOTICE_UPDATE_CC' can leave `cc_status' unaltered for such insns.
75: But suppose that the previous insn set the condition code based
76: on location `a4@(102)' and the current insn stores a new value in
77: `a4'. Although the condition code is not changed by this, it will
78: no longer be true that it reflects the contents of `a4@(102)'.
79: Therefore, `NOTICE_UPDATE_CC' must alter `cc_status' in this case
80: to say that nothing is known about the condition code value.
81:
82: The definition of `NOTICE_UPDATE_CC' must be prepared to deal with
83: the results of peephole optimization: insns whose patterns are
84: `parallel' RTXs containing various `reg', `mem' or constants which
85: are just the operands. The RTL structure of these insns is not
86: sufficient to indicate what the insns actually do. What
87: `NOTICE_UPDATE_CC' should do when it sees one is just to run
88: `CC_STATUS_INIT'.
89:
90: A possible definition of `NOTICE_UPDATE_CC' is to call a function
91: that looks at an attribute (*note Insn Attributes::.) named, for
92: example, `cc'. This avoids having detailed information about
93: patterns in two places, the `md' file and in `NOTICE_UPDATE_CC'.
94:
95: `EXTRA_CC_MODES'
96: A list of names to be used for additional modes for condition code
97: values in registers (*note Jump Patterns::.). These names are
98: added to `enum machine_mode' and all have class `MODE_CC'. By
99: convention, they should start with `CC' and end with `mode'.
100:
101: You should only define this macro if your machine does not use
102: `cc0' and only if additional modes are required.
103:
104: `EXTRA_CC_NAMES'
105: A list of C strings giving the names for the modes listed in
106: `EXTRA_CC_MODES'. For example, the Sparc defines this macro and
107: `EXTRA_CC_MODES' as
108:
109: #define EXTRA_CC_MODES CC_NOOVmode, CCFPmode
110: #define EXTRA_CC_NAMES "CC_NOOV", "CCFP"
111:
112: This macro is not required if `EXTRA_CC_MODES' is not defined.
113:
114: `SELECT_CC_MODE (OP, X, Y)'
115: Returns a mode from class `MODE_CC' to be used when comparison
116: operation code OP is applied to rtx X and Y. For example, on the
117: Sparc, `SELECT_CC_MODE' is defined as (see *note Jump Patterns::.
118: for a description of the reason for this definition)
119:
120: #define SELECT_CC_MODE(OP,X,Y) \
121: (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \
122: ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \
123: : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \
124: || GET_CODE (X) == NEG) \
125: ? CC_NOOVmode : CCmode))
126:
127: This macro is not required if `EXTRA_CC_MODES' is not defined.
128:
129:
130: File: gcc.info, Node: Costs, Next: Sections, Prev: Condition Code, Up: Target Macros
131:
132: Describing Relative Costs of Operations
133: =======================================
134:
135: These macros let you describe the relative speed of various
136: operations on the target machine.
137:
138: `CONST_COSTS (X, CODE, OUTER_CODE)'
139: A part of a C `switch' statement that describes the relative costs
140: of constant RTL expressions. It must contain `case' labels for
141: expression codes `const_int', `const', `symbol_ref', `label_ref'
142: and `const_double'. Each case must ultimately reach a `return'
143: statement to return the relative cost of the use of that kind of
144: constant value in an expression. The cost may depend on the
145: precise value of the constant, which is available for examination
146: in X, and the rtx code of the expression in which it is contained,
147: found in OUTER_CODE.
148:
149: CODE is the expression code--redundant, since it can be obtained
150: with `GET_CODE (X)'.
151:
152: `RTX_COSTS (X, CODE, OUTER_CODE)'
153: Like `CONST_COSTS' but applies to nonconstant RTL expressions.
154: This can be used, for example, to indicate how costly a multiply
155: instruction is. In writing this macro, you can use the construct
156: `COSTS_N_INSNS (N)' to specify a cost equal to N fast
157: instructions. OUTER_CODE is the code of the expression in which X
158: is contained.
159:
160: This macro is optional; do not define it if the default cost
161: assumptions are adequate for the target machine.
162:
163: `ADDRESS_COST (ADDRESS)'
164: An expression giving the cost of an addressing mode that contains
165: ADDRESS. If not defined, the cost is computed from the ADDRESS
166: expression and the `CONST_COSTS' values.
167:
168: For most CISC machines, the default cost is a good approximation
169: of the true cost of the addressing mode. However, on RISC
170: machines, all instructions normally have the same length and
171: execution time. Hence all addresses will have equal costs.
172:
173: In cases where more than one form of an address is known, the form
174: with the lowest cost will be used. If multiple forms have the
175: same, lowest, cost, the one that is the most complex will be used.
176:
177: For example, suppose an address that is equal to the sum of a
178: register and a constant is used twice in the same basic block.
179: When this macro is not defined, the address will be computed in a
180: register and memory references will be indirect through that
181: register. On machines where the cost of the addressing mode
182: containing the sum is no higher than that of a simple indirect
183: reference, this will produce an additional instruction and
184: possibly require an additional register. Proper specification of
185: this macro eliminates this overhead for such machines.
186:
187: Similar use of this macro is made in strength reduction of loops.
188:
189: ADDRESS need not be valid as an address. In such a case, the cost
190: is not relevant and can be any value; invalid addresses need not be
191: assigned a different cost.
192:
193: On machines where an address involving more than one register is as
194: cheap as an address computation involving only one register,
195: defining `ADDRESS_COST' to reflect this can cause two registers to
196: be live over a region of code where only one would have been if
197: `ADDRESS_COST' were not defined in that manner. This effect should
198: be considered in the definition of this macro. Equivalent costs
199: should probably only be given to addresses with different numbers
200: of registers on machines with lots of registers.
201:
202: This macro will normally either not be defined or be defined as a
203: constant.
204:
205: `REGISTER_MOVE_COST (FROM, TO)'
206: A C expression for the cost of moving data from a register in class
207: FROM to one in class TO. The classes are expressed using the
208: enumeration values such as `GENERAL_REGS'. A value of 4 is the
209: default; other values are interpreted relative to that.
210:
211: It is not required that the cost always equal 2 when FROM is the
212: same as TO; on some machines it is expensive to move between
213: registers if they are not general registers.
214:
215: If reload sees an insn consisting of a single `set' between two
216: hard registers, and if `REGISTER_MOVE_COST' applied to their
217: classes returns a value of 2, reload does not check to ensure that
218: the constraints of the insn are met. Setting a cost of other than
219: 2 will allow reload to verify that the constraints are met. You
220: should do this if the `movM' pattern's constraints do not allow
221: such copying.
222:
223: `MEMORY_MOVE_COST (M)'
224: A C expression for the cost of moving data of mode M between a
225: register and memory. A value of 2 is the default; this cost is
226: relative to those in `REGISTER_MOVE_COST'.
227:
228: If moving between registers and memory is more expensive than
229: between two registers, you should define this macro to express the
230: relative cost.
231:
232: `BRANCH_COST'
233: A C expression for the cost of a branch instruction. A value of 1
234: is the default; other values are interpreted relative to that.
235:
236: Here are additional macros which do not specify precise relative
237: costs, but only that certain actions are more expensive than GNU CC
238: would ordinarily expect.
239:
240: `SLOW_BYTE_ACCESS'
241: Define this macro as a C expression which is nonzero if accessing
242: less than a word of memory (i.e. a `char' or a `short') is no
243: faster than accessing a word of memory, i.e., if such access
244: require more than one instruction or if there is no difference in
245: cost between byte and (aligned) word loads.
246:
247: When this macro is not defined, the compiler will access a field by
248: finding the smallest containing object; when it is defined, a
249: fullword load will be used if alignment permits. Unless bytes
250: accesses are faster than word accesses, using word accesses is
251: preferable since it may eliminate subsequent memory access if
252: subsequent accesses occur to other fields in the same word of the
253: structure, but to different bytes.
254:
255: `SLOW_ZERO_EXTEND'
256: Define this macro if zero-extension (of a `char' or `short' to an
257: `int') can be done faster if the destination is a register that is
258: known to be zero.
259:
260: If you define this macro, you must have instruction patterns that
261: recognize RTL structures like this:
262:
263: (set (strict_low_part (subreg:QI (reg:SI ...) 0)) ...)
264:
265: and likewise for `HImode'.
266:
267: `SLOW_UNALIGNED_ACCESS'
268: Define this macro to be the value 1 if unaligned accesses have a
269: cost many times greater than aligned accesses, for example if they
270: are emulated in a trap handler.
271:
272: When this macro is non-zero, the compiler will act as if
273: `STRICT_ALIGNMENT' were non-zero when generating code for block
274: moves. This can cause significantly more instructions to be
275: produced. Therefore, do not set this macro non-zero if unaligned
276: accesses only add a cycle or two to the time for a memory access.
277:
278: If the value of this macro is always zero, it need not be defined.
279:
280: `DONT_REDUCE_ADDR'
281: Define this macro to inhibit strength reduction of memory
282: addresses. (On some machines, such strength reduction seems to do
283: harm rather than good.)
284:
285: `MOVE_RATIO'
286: The number of scalar move insns which should be generated instead
287: of a string move insn or a library call. Increasing the value
288: will always make code faster, but eventually incurs high cost in
289: increased code size.
290:
291: If you don't define this, a reasonable default is used.
292:
293: `NO_FUNCTION_CSE'
294: Define this macro if it is as good or better to call a constant
295: function address than to call an address kept in a register.
296:
297: `NO_RECURSIVE_FUNCTION_CSE'
298: Define this macro if it is as good or better for a function to call
299: itself with an explicit address than to call an address kept in a
300: register.
301:
302: `ADJUST_COST (INSN, LINK, DEP_INSN, COST)'
303: A C statement (sans semicolon) to update the integer variable COST
304: based on the relationship between INSN that is dependent on
305: DEP_INSN through the dependence LINK. The default is to make no
306: adjustment to COST. This can be used for example to specify to
307: the scheduler that an output- or anti-dependence does not incur
308: the same cost as a data-dependence.
309:
310:
311: File: gcc.info, Node: Sections, Next: PIC, Prev: Costs, Up: Target Macros
312:
313: Dividing the Output into Sections (Texts, Data, ...)
314: ====================================================
315:
316: An object file is divided into sections containing different types of
317: data. In the most common case, there are three sections: the "text
318: section", which holds instructions and read-only data; the "data
319: section", which holds initialized writable data; and the "bss section",
320: which holds uninitialized data. Some systems have other kinds of
321: sections.
322:
323: The compiler must tell the assembler when to switch sections. These
324: macros control what commands to output to tell the assembler this. You
325: can also define additional sections.
326:
327: `TEXT_SECTION_ASM_OP'
328: A C expression whose value is a string containing the assembler
329: operation that should precede instructions and read-only data.
330: Normally `".text"' is right.
331:
332: `DATA_SECTION_ASM_OP'
333: A C expression whose value is a string containing the assembler
334: operation to identify the following data as writable initialized
335: data. Normally `".data"' is right.
336:
337: `SHARED_SECTION_ASM_OP'
338: if defined, a C expression whose value is a string containing the
339: assembler operation to identify the following data as shared data.
340: If not defined, `DATA_SECTION_ASM_OP' will be used.
341:
342: `INIT_SECTION_ASM_OP'
343: if defined, a C expression whose value is a string containing the
344: assembler operation to identify the following data as
345: initialization code. If not defined, GNU CC will assume such a
346: section does not exist.
347:
348: `EXTRA_SECTIONS'
349: A list of names for sections other than the standard two, which are
350: `in_text' and `in_data'. You need not define this macro on a
351: system with no other sections (that GCC needs to use).
352:
353: `EXTRA_SECTION_FUNCTIONS'
354: One or more functions to be defined in `varasm.c'. These
355: functions should do jobs analogous to those of `text_section' and
356: `data_section', for your additional sections. Do not define this
357: macro if you do not define `EXTRA_SECTIONS'.
358:
359: `READONLY_DATA_SECTION'
360: On most machines, read-only variables, constants, and jump tables
361: are placed in the text section. If this is not the case on your
362: machine, this macro should be defined to be the name of a function
363: (either `data_section' or a function defined in `EXTRA_SECTIONS')
364: that switches to the section to be used for read-only items.
365:
366: If these items should be placed in the text section, this macro
367: should not be defined.
368:
369: `SELECT_SECTION (EXP, RELOC)'
370: A C statement or statements to switch to the appropriate section
371: for output of EXP. You can assume that EXP is either a `VAR_DECL'
372: node or a constant of some sort. RELOC indicates whether the
373: initial value of EXP requires link-time relocations. Select the
374: section by calling `text_section' or one of the alternatives for
375: other sections.
376:
377: Do not define this macro if you put all read-only variables and
378: constants in the read-only data section (usually the text section).
379:
380: `SELECT_RTX_SECTION (MODE, RTX)'
381: A C statement or statements to switch to the appropriate section
382: for output of RTX in mode MODE. You can assume that RTX is some
383: kind of constant in RTL. The argument MODE is redundant except in
384: the case of a `const_int' rtx. Select the section by calling
385: `text_section' or one of the alternatives for other sections.
386:
387: Do not define this macro if you put all constants in the read-only
388: data section.
389:
390: `JUMP_TABLES_IN_TEXT_SECTION'
391: Define this macro if jump tables (for `tablejump' insns) should be
392: output in the text section, along with the assembler instructions.
393: Otherwise, the readonly data section is used.
394:
395: This macro is irrelevant if there is no separate readonly data
396: section.
397:
398: `ENCODE_SECTION_INFO (DECL)'
399: Define this macro if references to a symbol must be treated
400: differently depending on something about the variable or function
401: named by the symbol (such as what section it is in).
402:
403: The macro definition, if any, is executed immediately after the
404: rtl for DECL has been created and stored in `DECL_RTL (DECL)'.
405: The value of the rtl will be a `mem' whose address is a
406: `symbol_ref'.
407:
408: The usual thing for this macro to do is to record a flag in the
409: `symbol_ref' (such as `SYMBOL_REF_FLAG') or to store a modified
410: name string in the `symbol_ref' (if one bit is not enough
411: information).
412:
413: `STRIP_NAME_ENCODING (VAR, SYM_NAME)'
414: Decode SYM_NAME and store the real name part in VAR, sans the
415: characters that encode section info. Define this macro if
416: `ENCODE_SECTION_INFO' alters the symbol's name string.
417:
418:
419: File: gcc.info, Node: PIC, Next: Assembler Format, Prev: Sections, Up: Target Macros
420:
421: Position Independent Code
422: =========================
423:
424: This section describes macros that help implement generation of
425: position independent code. Simply defining these macros is not enough
426: to generate valid PIC; you must also add support to the macros
427: `GO_IF_LEGITIMATE_ADDRESS' and `PRINT_OPERAND_ADDRESS', as well as
428: `LEGITIMIZE_ADDRESS'. You must modify the definition of `movsi' to do
429: something appropriate when the source operand contains a symbolic
430: address. You may also need to alter the handling of switch statements
431: so that they use relative addresses.
432:
433: `PIC_OFFSET_TABLE_REGNUM'
434: The register number of the register used to address a table of
435: static data addresses in memory. In some cases this register is
436: defined by a processor's "application binary interface" (ABI).
437: When this macro is defined, RTL is generated for this register
438: once, as with the stack pointer and frame pointer registers. If
439: this macro is not defined, it is up to the machine-dependent files
440: to allocate such a register (if necessary).
441:
442: `FINALIZE_PIC'
443: By generating position-independent code, when two different
444: programs (A and B) share a common library (libC.a), the text of
445: the library can be shared whether or not the library is linked at
446: the same address for both programs. In some of these
447: environments, position-independent code requires not only the use
448: of different addressing modes, but also special code to enable the
449: use of these addressing modes.
450:
451: The `FINALIZE_PIC' macro serves as a hook to emit these special
452: codes once the function is being compiled into assembly code, but
453: not before. (It is not done before, because in the case of
454: compiling an inline function, it would lead to multiple PIC
455: prologues being included in functions which used inline functions
456: and were compiled to assembly language.)
457:
458: `LEGITIMATE_PIC_OPERAND_P (X)'
459: A C expression that is nonzero if X is a legitimate immediate
460: operand on the target machine when generating position independent
461: code. You can assume that X satisfies `CONSTANT_P', so you need
462: not check this. You can also assume FLAG_PIC is true, so you need
463: not check it either. You need not define this macro if all
464: constants (including `SYMBOL_REF') can be immediate operands when
465: generating position independent code.
466:
467:
468: File: gcc.info, Node: Assembler Format, Next: Debugging Info, Prev: PIC, Up: Target Macros
469:
470: Defining the Output Assembler Language
471: ======================================
472:
473: This section describes macros whose principal purpose is to describe
474: how to write instructions in assembler language-rather than what the
475: instructions do.
476:
477: * Menu:
478:
479: * File Framework:: Structural information for the assembler file.
480: * Data Output:: Output of constants (numbers, strings, addresses).
481: * Uninitialized Data:: Output of uninitialized variables.
482: * Label Output:: Output and generation of labels.
483: * Initialization:: General principles of initialization
484: and termination routines.
485: * Macros for Initialization::
486: Specific macros that control the handling of
487: initialization and termination routines.
488: * Instruction Output:: Output of actual instructions.
489: * Dispatch Tables:: Output of jump tables.
490: * Alignment Output:: Pseudo ops for alignment and skipping data.
491:
492:
493: File: gcc.info, Node: File Framework, Next: Data Output, Up: Assembler Format
494:
495: The Overall Framework of an Assembler File
496: ------------------------------------------
497:
498: `ASM_FILE_START (STREAM)'
499: A C expression which outputs to the stdio stream STREAM some
500: appropriate text to go at the start of an assembler file.
501:
502: Normally this macro is defined to output a line containing
503: `#NO_APP', which is a comment that has no effect on most
504: assemblers but tells the GNU assembler that it can save time by not
505: checking for certain assembler constructs.
506:
507: On systems that use SDB, it is necessary to output certain
508: commands; see `attasm.h'.
509:
510: `ASM_FILE_END (STREAM)'
511: A C expression which outputs to the stdio stream STREAM some
512: appropriate text to go at the end of an assembler file.
513:
514: If this macro is not defined, the default is to output nothing
515: special at the end of the file. Most systems don't require any
516: definition.
517:
518: On systems that use SDB, it is necessary to output certain
519: commands; see `attasm.h'.
520:
521: `ASM_IDENTIFY_GCC (FILE)'
522: A C statement to output assembler commands which will identify the
523: object file as having been compiled with GNU CC (or another GNU
524: compiler).
525:
526: If you don't define this macro, the string `gcc_compiled.:' is
527: output. This string is calculated to define a symbol which, on
528: BSD systems, will never be defined for any other reason. GDB
529: checks for the presence of this symbol when reading the symbol
530: table of an executable.
531:
532: On non-BSD systems, you must arrange communication with GDB in
533: some other fashion. If GDB is not used on your system, you can
534: define this macro with an empty body.
535:
536: `ASM_COMMENT_START'
537: A C string constant describing how to begin a comment in the target
538: assembler language. The compiler assumes that the comment will
539: end at the end of the line.
540:
541: `ASM_APP_ON'
542: A C string constant for text to be output before each `asm'
543: statement or group of consecutive ones. Normally this is
544: `"#APP"', which is a comment that has no effect on most assemblers
545: but tells the GNU assembler that it must check the lines that
546: follow for all valid assembler constructs.
547:
548: `ASM_APP_OFF'
549: A C string constant for text to be output after each `asm'
550: statement or group of consecutive ones. Normally this is
551: `"#NO_APP"', which tells the GNU assembler to resume making the
552: time-saving assumptions that are valid for ordinary compiler
553: output.
554:
555: `ASM_OUTPUT_SOURCE_FILENAME (STREAM, NAME)'
556: A C statement to output COFF information or DWARF debugging
557: information which indicates that filename NAME is the current
558: source file to the stdio stream STREAM.
559:
560: This macro need not be defined if the standard form of output for
561: the file format in use is appropriate.
562:
563: `ASM_OUTPUT_SOURCE_LINE (STREAM, LINE)'
564: A C statement to output DBX or SDB debugging information before
565: code for line number LINE of the current source file to the stdio
566: stream STREAM.
567:
568: This macro need not be defined if the standard form of debugging
569: information for the debugger in use is appropriate.
570:
571: `ASM_OUTPUT_IDENT (STREAM, STRING)'
572: A C statement to output something to the assembler file to handle a
573: `#ident' directive containing the text STRING. If this macro is
574: not defined, nothing is output for a `#ident' directive.
575:
576: `OBJC_PROLOGUE'
577: A C statement to output any assembler statements which are
578: required to precede any Objective C object definitions or message
579: sending. The statement is executed only when compiling an
580: Objective C program.
581:
582:
583: File: gcc.info, Node: Data Output, Next: Uninitialized Data, Prev: File Framework, Up: Assembler Format
584:
585: Output of Data
586: --------------
587:
588: `ASM_OUTPUT_LONG_DOUBLE (STREAM, VALUE)'
589: `ASM_OUTPUT_DOUBLE (STREAM, VALUE)'
590: `ASM_OUTPUT_FLOAT (STREAM, VALUE)'
591: A C statement to output to the stdio stream STREAM an assembler
592: instruction to assemble a floating-point constant of `TFmode',
593: `DFmode' or `SFmode', respectively, whose value is VALUE. VALUE
594: will be a C expression of type `REAL_VALUE_TYPE'. Macros such as
595: `REAL_VALUE_TO_TARGET_DOUBLE' are useful for writing these
596: definitions.
597:
598: `ASM_OUTPUT_QUADRUPLE_INT (STREAM, EXP)'
599: `ASM_OUTPUT_DOUBLE_INT (STREAM, EXP)'
600: `ASM_OUTPUT_INT (STREAM, EXP)'
601: `ASM_OUTPUT_SHORT (STREAM, EXP)'
602: `ASM_OUTPUT_CHAR (STREAM, EXP)'
603: A C statement to output to the stdio stream STREAM an assembler
604: instruction to assemble an integer of 16, 8, 4, 2 or 1 bytes,
605: respectively, whose value is VALUE. The argument EXP will be an
606: RTL expression which represents a constant value. Use
607: `output_addr_const (STREAM, EXP)' to output this value as an
608: assembler expression.
609:
610: For sizes larger than `UNITS_PER_WORD', if the action of a macro
611: would be identical to repeatedly calling the macro corresponding to
612: a size of `UNITS_PER_WORD', once for each word, you need not define
613: the macro.
614:
615: `ASM_OUTPUT_BYTE (STREAM, VALUE)'
616: A C statement to output to the stdio stream STREAM an assembler
617: instruction to assemble a single byte containing the number VALUE.
618:
619: `ASM_BYTE_OP'
620: A C string constant giving the pseudo-op to use for a sequence of
621: single-byte constants. If this macro is not defined, the default
622: is `"byte"'.
623:
624: `ASM_OUTPUT_ASCII (STREAM, PTR, LEN)'
625: A C statement to output to the stdio stream STREAM an assembler
626: instruction to assemble a string constant containing the LEN bytes
627: at PTR. PTR will be a C expression of type `char *' and LEN a C
628: expression of type `int'.
629:
630: If the assembler has a `.ascii' pseudo-op as found in the Berkeley
631: Unix assembler, do not define the macro `ASM_OUTPUT_ASCII'.
632:
633: `ASM_OUTPUT_POOL_PROLOGUE (FILE FUNNAME FUNDECL SIZE)'
634: A C statement to output assembler commands to define the start of
635: the constant pool for a function. FUNNAME is a string giving the
636: name of the function. Should the return type of the function be
637: required, it can be obtained via FUNDECL. SIZE is the size, in
638: bytes, of the constant pool that will be written immediately after
639: this call.
640:
641: If no constant-pool prefix is required, the usual case, this macro
642: need not be defined.
643:
644: `ASM_OUTPUT_SPECIAL_POOL_ENTRY (FILE, X, MODE, ALIGN, LABELNO, JUMPTO)'
645: A C statement (with or without semicolon) to output a constant in
646: the constant pool, if it needs special treatment. (This macro
647: need not do anything for RTL expressions that can be output
648: normally.)
649:
650: The argument FILE is the standard I/O stream to output the
651: assembler code on. X is the RTL expression for the constant to
652: output, and MODE is the machine mode (in case X is a `const_int').
653: ALIGN is the required alignment for the value X; you should
654: output an assembler directive to force this much alignment.
655:
656: The argument LABELNO is a number to use in an internal label for
657: the address of this pool entry. The definition of this macro is
658: responsible for outputting the label definition at the proper
659: place. Here is how to do this:
660:
661: ASM_OUTPUT_INTERNAL_LABEL (FILE, "LC", LABELNO);
662:
663: When you output a pool entry specially, you should end with a
664: `goto' to the label JUMPTO. This will prevent the same pool entry
665: from being output a second time in the usual manner.
666:
667: You need not define this macro if it would do nothing.
668:
669: `ASM_OPEN_PAREN'
670: `ASM_CLOSE_PAREN'
671: These macros are defined as C string constant, describing the
672: syntax in the assembler for grouping arithmetic expressions. The
673: following definitions are correct for most assemblers:
674:
675: #define ASM_OPEN_PAREN "("
676: #define ASM_CLOSE_PAREN ")"
677:
678: These macros are provided by `real.h' for writing the definitions of
679: `ASM_OUTPUT_DOUBLE' and the like:
680:
681: `REAL_VALUE_TO_TARGET_SINGLE (X, L)'
682: `REAL_VALUE_TO_TARGET_DOUBLE (X, L)'
683: `REAL_VALUE_TO_TARGET_LONG_DOUBLE (X, L)'
684: These translate X, of type `REAL_VALUE_TYPE', to the target's
685: floating point representation, and store its bit pattern in the
686: array of `long int' whose address is L. The number of elements in
687: the output array is determined by the size of the desired target
688: floating point data type: 32 bits of it go in each `long int' array
689: element. Each array element holds 32 bits of the result, even if
690: `long int' is wider than 32 bits on the host machine.
691:
692: The array element values are designed so that you can print them
693: out using `fprintf' in the order they should appear in the target
694: machine's memory.
695:
696: `REAL_VALUE_TO_DECIMAL (X, FORMAT, STRING)'
697: This macro converts X, of type `REAL_VALUE_TYPE', to a decimal
698: number and stores it as a string into STRING. You must pass, as
699: STRING, the address of a long enough block of space to hold the
700: result.
701:
702: The argument FORMAT is a `printf'-specification that serves as a
703: suggestion for how to format the output string.
704:
705:
706: File: gcc.info, Node: Uninitialized Data, Next: Label Output, Prev: Data Output, Up: Assembler Format
707:
708: Output of Uninitialized Variables
709: ---------------------------------
710:
711: Each of the macros in this section is used to do the whole job of
712: outputting a single uninitialized variable.
713:
714: `ASM_OUTPUT_COMMON (STREAM, NAME, SIZE, ROUNDED)'
715: A C statement (sans semicolon) to output to the stdio stream
716: STREAM the assembler definition of a common-label named NAME whose
717: size is SIZE bytes. The variable ROUNDED is the size rounded up
718: to whatever alignment the caller wants.
719:
720: Use the expression `assemble_name (STREAM, NAME)' to output the
721: name itself; before and after that, output the additional
722: assembler syntax for defining the name, and a newline.
723:
724: This macro controls how the assembler definitions of uninitialized
725: global variables are output.
726:
727: `ASM_OUTPUT_ALIGNED_COMMON (STREAM, NAME, SIZE, ALIGNMENT)'
728: Like `ASM_OUTPUT_COMMON' except takes the required alignment as a
729: separate, explicit argument. If you define this macro, it is used
730: in place of `ASM_OUTPUT_COMMON', and gives you more flexibility in
731: handling the required alignment of the variable.
732:
733: `ASM_OUTPUT_SHARED_COMMON (STREAM, NAME, SIZE, ROUNDED)'
734: If defined, it is similar to `ASM_OUTPUT_COMMON', except that it
735: is used when NAME is shared. If not defined, `ASM_OUTPUT_COMMON'
736: will be used.
737:
738: `ASM_OUTPUT_LOCAL (STREAM, NAME, SIZE, ROUNDED)'
739: A C statement (sans semicolon) to output to the stdio stream
740: STREAM the assembler definition of a local-common-label named NAME
741: whose size is SIZE bytes. The variable ROUNDED is the size
742: rounded up to whatever alignment the caller wants.
743:
744: Use the expression `assemble_name (STREAM, NAME)' to output the
745: name itself; before and after that, output the additional
746: assembler syntax for defining the name, and a newline.
747:
748: This macro controls how the assembler definitions of uninitialized
749: static variables are output.
750:
751: `ASM_OUTPUT_ALIGNED_LOCAL (STREAM, NAME, SIZE, ALIGNMENT)'
752: Like `ASM_OUTPUT_LOCAL' except takes the required alignment as a
753: separate, explicit argument. If you define this macro, it is used
754: in place of `ASM_OUTPUT_LOCAL', and gives you more flexibility in
755: handling the required alignment of the variable.
756:
757: `ASM_OUTPUT_SHARED_LOCAL (STREAM, NAME, SIZE, ROUNDED)'
758: If defined, it is similar to `ASM_OUTPUT_LOCAL', except that it is
759: used when NAME is shared. If not defined, `ASM_OUTPUT_LOCAL' will
760: be used.
761:
762:
763: File: gcc.info, Node: Label Output, Next: Initialization, Prev: Uninitialized Data, Up: Assembler Format
764:
765: Output and Generation of Labels
766: -------------------------------
767:
768: `ASM_OUTPUT_LABEL (STREAM, NAME)'
769: A C statement (sans semicolon) to output to the stdio stream
770: STREAM the assembler definition of a label named NAME. Use the
771: expression `assemble_name (STREAM, NAME)' to output the name
772: itself; before and after that, output the additional assembler
773: syntax for defining the name, and a newline.
774:
775: `ASM_DECLARE_FUNCTION_NAME (STREAM, NAME, DECL)'
776: A C statement (sans semicolon) to output to the stdio stream
777: STREAM any text necessary for declaring the name NAME of a
778: function which is being defined. This macro is responsible for
779: outputting the label definition (perhaps using
780: `ASM_OUTPUT_LABEL'). The argument DECL is the `FUNCTION_DECL'
781: tree node representing the function.
782:
783: If this macro is not defined, then the function name is defined in
784: the usual manner as a label (by means of `ASM_OUTPUT_LABEL').
785:
786: `ASM_DECLARE_FUNCTION_SIZE (STREAM, NAME, DECL)'
787: A C statement (sans semicolon) to output to the stdio stream
788: STREAM any text necessary for declaring the size of a function
789: which is being defined. The argument NAME is the name of the
790: function. The argument DECL is the `FUNCTION_DECL' tree node
791: representing the function.
792:
793: If this macro is not defined, then the function size is not
794: defined.
795:
796: `ASM_DECLARE_OBJECT_NAME (STREAM, NAME, DECL)'
797: A C statement (sans semicolon) to output to the stdio stream
798: STREAM any text necessary for declaring the name NAME of an
799: initialized variable which is being defined. This macro must
800: output the label definition (perhaps using `ASM_OUTPUT_LABEL').
801: The argument DECL is the `VAR_DECL' tree node representing the
802: variable.
803:
804: If this macro is not defined, then the variable name is defined in
805: the usual manner as a label (by means of `ASM_OUTPUT_LABEL').
806:
807: `ASM_FINISH_DECLARE_OBJECT (STREAM, DECL, TOPLEVEL, ATEND)'
808: A C statement (sans semicolon) to finish up declaring a variable
809: name once the compiler has processed its initializer fully and
810: thus has had a chance to determine the size of an array when
811: controlled by an initializer. This is used on systems where it's
812: necessary to declare something about the size of the object.
813:
814: If you don't define this macro, that is equivalent to defining it
815: to do nothing.
816:
817: `ASM_GLOBALIZE_LABEL (STREAM, NAME)'
818: A C statement (sans semicolon) to output to the stdio stream
819: STREAM some commands that will make the label NAME global; that
820: is, available for reference from other files. Use the expression
821: `assemble_name (STREAM, NAME)' to output the name itself; before
822: and after that, output the additional assembler syntax for making
823: that name global, and a newline.
824:
825: `ASM_OUTPUT_EXTERNAL (STREAM, DECL, NAME)'
826: A C statement (sans semicolon) to output to the stdio stream
827: STREAM any text necessary for declaring the name of an external
828: symbol named NAME which is referenced in this compilation but not
829: defined. The value of DECL is the tree node for the declaration.
830:
831: This macro need not be defined if it does not need to output
832: anything. The GNU assembler and most Unix assemblers don't
833: require anything.
834:
835: `ASM_OUTPUT_EXTERNAL_LIBCALL (STREAM, SYMREF)'
836: A C statement (sans semicolon) to output on STREAM an assembler
837: pseudo-op to declare a library function name external. The name
838: of the library function is given by SYMREF, which has type `rtx'
839: and is a `symbol_ref'.
840:
841: This macro need not be defined if it does not need to output
842: anything. The GNU assembler and most Unix assemblers don't
843: require anything.
844:
845: `ASM_OUTPUT_LABELREF (STREAM, NAME)'
846: A C statement (sans semicolon) to output to the stdio stream
847: STREAM a reference in assembler syntax to a label named NAME.
848: This should add `_' to the front of the name, if that is customary
849: on your operating system, as it is in most Berkeley Unix systems.
850: This macro is used in `assemble_name'.
851:
852: `ASM_OUTPUT_INTERNAL_LABEL (STREAM, PREFIX, NUM)'
853: A C statement to output to the stdio stream STREAM a label whose
854: name is made from the string PREFIX and the number NUM.
855:
856: It is absolutely essential that these labels be distinct from the
857: labels used for user-level functions and variables. Otherwise,
858: certain programs will have name conflicts with internal labels.
859:
860: It is desirable to exclude internal labels from the symbol table
861: of the object file. Most assemblers have a naming convention for
862: labels that should be excluded; on many systems, the letter `L' at
863: the beginning of a label has this effect. You should find out what
864: convention your system uses, and follow it.
865:
866: The usual definition of this macro is as follows:
867:
868: fprintf (STREAM, "L%s%d:\n", PREFIX, NUM)
869:
870: `ASM_GENERATE_INTERNAL_LABEL (STRING, PREFIX, NUM)'
871: A C statement to store into the string STRING a label whose name
872: is made from the string PREFIX and the number NUM.
873:
874: This string, when output subsequently by `assemble_name', should
875: produce the output that `ASM_OUTPUT_INTERNAL_LABEL' would produce
876: with the same PREFIX and NUM.
877:
878: If the string begins with `*', then `assemble_name' will output
879: the rest of the string unchanged. It is often convenient for
880: `ASM_GENERATE_INTERNAL_LABEL' to use `*' in this way. If the
881: string doesn't start with `*', then `ASM_OUTPUT_LABELREF' gets to
882: output the string, and may change it. (Of course,
883: `ASM_OUTPUT_LABELREF' is also part of your machine description, so
884: you should know what it does on your machine.)
885:
886: `ASM_FORMAT_PRIVATE_NAME (OUTVAR, NAME, NUMBER)'
887: A C expression to assign to OUTVAR (which is a variable of type
888: `char *') a newly allocated string made from the string NAME and
889: the number NUMBER, with some suitable punctuation added. Use
890: `alloca' to get space for the string.
891:
892: The string will be used as an argument to `ASM_OUTPUT_LABELREF' to
893: produce an assembler label for an internal static variable whose
894: name is NAME. Therefore, the string must be such as to result in
895: valid assembler code. The argument NUMBER is different each time
896: this macro is executed; it prevents conflicts between
897: similarly-named internal static variables in different scopes.
898:
899: Ideally this string should not be a valid C identifier, to prevent
900: any conflict with the user's own symbols. Most assemblers allow
901: periods or percent signs in assembler symbols; putting at least
902: one of these between the name and the number will suffice.
903:
904: `OBJC_GEN_METHOD_LABEL (BUF, IS_INST, CLASS_NAME, CAT_NAME, SEL_NAME)'
905: Define this macro to override the default assembler names used for
906: Objective C methods.
907:
908: The default name is a unique method number followed by the name of
909: the class (e.g. `_1_Foo'). For methods in categories, the name of
910: the category is also included in the assembler name (e.g.
911: `_1_Foo_Bar').
912:
913: These names are safe on most systems, but make debugging difficult
914: since the method's selector is not present in the name.
915: Therefore, particular systems define other ways of computing names.
916:
917: BUF is an expression of type `char *' which gives you a buffer in
918: which to store the name; its length is as long as CLASS_NAME,
919: CAT_NAME and SEL_NAME put together, plus 50 characters extra.
920:
921: The argument IS_INST specifies whether the method is an instance
922: method or a class method; CLASS_NAME is the name of the class;
923: CAT_NAME is the name of the category (or NULL if the method is not
924: in a category); and SEL_NAME is the name of the selector.
925:
926: On systems where the assembler can handle quoted names, you can
927: use this macro to provide more human-readable names.
928:
929:
930: File: gcc.info, Node: Initialization, Next: Macros for Initialization, Prev: Label Output, Up: Assembler Format
931:
932: How Initialization Functions Are Handled
933: ----------------------------------------
934:
935: The compiled code for certain languages includes "constructors"
936: (also called "initialization routines")--functions to initialize data
937: in the program when the program is started. These functions need to be
938: called before the program is "started"--that is to say, before `main'
939: is called.
940:
941: Compiling some languages generates "destructors" (also called
942: "termination routines") that should be called when the program
943: terminates.
944:
945: To make the initialization and termination functions work, the
946: compiler must output something in the assembler code to cause those
947: functions to be called at the appropriate time. When you port the
948: compiler to a new system, you need to specify how to do this.
949:
950: There are two major ways that GCC currently supports the execution of
951: initialization and termination functions. Each way has two variants.
952: Much of the structure is common to all four variations.
953:
954: The linker must build two lists of these functions--a list of
955: initialization functions, called `__CTOR_LIST__', and a list of
956: termination functions, called `__DTOR_LIST__'.
957:
958: Each list always begins with an ignored function pointer (which may
959: hold 0, -1, or a count of the function pointers after it, depending on
960: the environment). This is followed by a series of zero or more function
961: pointers to constructors (or destructors), followed by a function
962: pointer containing zero.
963:
964: Depending on the operating system and its executable file format,
965: either `crtstuff.c' or `libgcc2.c' traverses these lists at startup
966: time and exit time. Constructors are called in forward order of the
967: list; destructors in reverse order.
968:
969: The best way to handle static constructors works only for object file
970: formats which provide arbitrarily-named sections. A section is set
971: aside for a list of constructors, and another for a list of destructors.
972: Traditionally these are called `.ctors' and `.dtors'. Each object file
973: that defines an initialization function also puts a word in the
974: constructor section to point to that function. The linker accumulates
975: all these words into one contiguous `.ctors' section. Termination
976: functions are handled similarly.
977:
978: To use this method, you need appropriate definitions of the macros
979: `ASM_OUTPUT_CONSTRUCTOR' and `ASM_OUTPUT_DESTRUCTOR'. Usually you can
980: get them by including `svr4.h'.
981:
982: When arbitrary sections are available, there are two variants,
983: depending upon how the code in `crtstuff.c' is called. On systems that
984: support an "init" section which is executed at program startup, parts
985: of `crtstuff.c' are compiled into that section. The program is linked
986: by the `gcc' driver like this:
987:
988: ld -o OUTPUT_FILE crtbegin.o ... crtend.o -lgcc
989:
990: The head of a function (`__do_global_ctors') appears in the init
991: section of `crtbegin.o'; the remainder of the function appears in the
992: init section of `crtend.o'. The linker will pull these two parts of
993: the section together, making a whole function. If any of the user's
994: object files linked into the middle of it contribute code, then that
995: code will be executed as part of the body of `__do_global_ctors'.
996:
997: To use this variant, you must define the `INIT_SECTION_ASM_OP' macro
998: properly.
999:
1000: If no init section is available, do not define
1001: `INIT_SECTION_ASM_OP'. Then `__do_global_ctors' is built into the text
1002: section like all other functions, and resides in `libgcc.a'. When GCC
1003: compiles any function called `main', it inserts a procedure call to
1004: `__main' as the first executable code after the function prologue. The
1005: `__main' function, also defined in `libgcc2.c', simply calls
1006: `__do_global_ctors'.
1007:
1008: In file formats that don't support arbitrary sections, there are
1009: again two variants. In the simplest variant, the GNU linker (GNU `ld')
1010: and an `a.out' format must be used. In this case,
1011: `ASM_OUTPUT_CONSTRUCTOR' is defined to produce a `.stabs' entry of type
1012: `N_SETT', referencing the name `__CTOR_LIST__', and with the address of
1013: the void function containing the initialization code as its value. The
1014: GNU linker recognizes this as a request to add the value to a "set";
1015: the values are accumulated, and are eventually placed in the executable
1016: as a vector in the format described above, with a leading (ignored)
1017: count and a trailing zero element. `ASM_OUTPUT_DESTRUCTOR' is handled
1018: similarly. Since no init section is available, the absence of
1019: `INIT_SECTION_ASM_OP' causes the compilation of `main' to call `__main'
1020: as above, starting the initialization process.
1021:
1022: The last variant uses neither arbitrary sections nor the GNU linker.
1023: This is preferable when you want to do dynamic linking and when using
1024: file formats which the GNU linker does not support, such as `ECOFF'. In
1025: this case, `ASM_OUTPUT_CONSTRUCTOR' does not produce an `N_SETT'
1026: symbol; initialization and termination functions are recognized simply
1027: by their names. This requires an extra program in the linkage step,
1028: called `collect2'. This program pretends to be the linker, for use
1029: with GNU CC; it does its job by running the ordinary linker, but also
1030: arranges to include the vectors of initialization and termination
1031: functions. These functions are called via `__main' as described above.
1032:
1033: Choosing among these configuration options has been simplified by a
1034: set of operating-system-dependent files in the `config' subdirectory.
1035: These files define all of the relevant parameters. Usually it is
1036: sufficient to include one into your specific machine-dependent
1037: configuration file. These files are:
1038:
1039: `aoutos.h'
1040: For operating systems using the `a.out' format.
1041:
1042: `next.h'
1043: For operating systems using the `MachO' format.
1044:
1045: `svr3.h'
1046: For System V Release 3 and similar systems using `COFF' format.
1047:
1048: `svr4.h'
1049: For System V Release 4 and similar systems using `ELF' format.
1050:
1051: `vms.h'
1052: For the VMS operating system.
1053:
1054: The following section describes the specific macros that control and
1055: customize the handling of initialization and termination functions.
1056:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.