![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tm.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to tm.texi CVS log | Up to [GCC 2.x] / gcc |
1.1.1.7 root 1: @c Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc.
1.1 root 2: @c This is part of the GCC manual.
3: @c For copying conditions, see the file gcc.texi.
4:
1.1.1.3 root 5: @node Target Macros
1.1.1.2 root 6: @chapter Target Description Macros
1.1 root 7: @cindex machine description macros
1.1.1.2 root 8: @cindex target description macros
9: @cindex macros, target description
1.1 root 10: @cindex @file{tm.h} macros
11:
12: In addition to the file @file{@var{machine}.md}, a machine description
13: includes a C header file conventionally given the name
14: @file{@var{machine}.h}. This header file defines numerous macros
15: that convey the information about the target machine that does not fit
16: into the scheme of the @file{.md} file. The file @file{tm.h} should be
17: a link to @file{@var{machine}.h}. The header file @file{config.h}
18: includes @file{tm.h} and most compiler source files include
19: @file{config.h}.
20:
21: @menu
22: * Driver:: Controlling how the driver runs the compilation passes.
23: * Run-time Target:: Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}.
24: * Storage Layout:: Defining sizes and alignments of data.
25: * Type Layout:: Defining sizes and properties of basic user data types.
26: * Registers:: Naming and describing the hardware registers.
27: * Register Classes:: Defining the classes of hardware registers.
28: * Stack and Calling:: Defining which way the stack grows and by how much.
29: * Varargs:: Defining the varargs macros.
30: * Trampolines:: Code set up at run time to enter a nested function.
31: * Library Calls:: Controlling how library routines are implicitly called.
32: * Addressing Modes:: Defining addressing modes valid for memory operands.
33: * Condition Code:: Defining how insns update the condition code.
34: * Costs:: Defining relative costs of different operations.
35: * Sections:: Dividing storage into text, data, and other sections.
36: * PIC:: Macros for position independent code.
37: * Assembler Format:: Defining how to write insns and pseudo-ops to output.
38: * Debugging Info:: Defining the format of debugging output.
39: * Cross-compilation:: Handling floating point for cross-compilers.
40: * Misc:: Everything else.
41: @end menu
42:
1.1.1.2 root 43: @node Driver
1.1 root 44: @section Controlling the Compilation Driver, @file{gcc}
45: @cindex driver
46: @cindex controlling the compilation driver
47:
1.1.1.7 root 48: @c prevent bad page break with this line
49: You can control the compilation driver.
50:
1.1 root 51: @table @code
52: @findex SWITCH_TAKES_ARG
53: @item SWITCH_TAKES_ARG (@var{char})
54: A C expression which determines whether the option @samp{-@var{char}}
55: takes arguments. The value should be the number of arguments that
56: option takes--zero, for many options.
57:
58: By default, this macro is defined to handle the standard options
59: properly. You need not define it unless you wish to add additional
60: options which take arguments.
61:
62: @findex WORD_SWITCH_TAKES_ARG
63: @item WORD_SWITCH_TAKES_ARG (@var{name})
64: A C expression which determines whether the option @samp{-@var{name}}
65: takes arguments. The value should be the number of arguments that
66: option takes--zero, for many options. This macro rather than
67: @code{SWITCH_TAKES_ARG} is used for multi-character option names.
68:
1.1.1.5 root 69: By default, this macro is defined as
70: @code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options
71: properly. You need not define @code{WORD_SWITCH_TAKES_ARG} unless you
72: wish to add additional options which take arguments. Any redefinition
73: should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for
74: additional options.
1.1 root 75:
76: @findex SWITCHES_NEED_SPACES
77: @item SWITCHES_NEED_SPACES
78: A string-valued C expression which is nonempty if the linker needs a
79: space between the @samp{-L} or @samp{-o} option and its argument.
80:
81: If this macro is not defined, the default value is 0.
82:
83: @findex CPP_SPEC
84: @item CPP_SPEC
85: A C string constant that tells the GNU CC driver program options to
86: pass to CPP. It can also specify how to translate options you
87: give to GNU CC into options for GNU CC to pass to the CPP.
88:
89: Do not define this macro if it does not need to do anything.
90:
1.1.1.5 root 91: @findex NO_BUILTIN_SIZE_TYPE
92: @item NO_BUILTIN_SIZE_TYPE
93: If this macro is defined, the preprocessor will not define the builtin macro
94: @code{__SIZE_TYPE__}. The macro @code{__SIZE_TYPE__} must then be defined
95: by @code{CPP_SPEC} instead.
96:
97: This should be defined if @code{SIZE_TYPE} depends on target dependent flags
98: which are not accessible to the preprocessor. Otherwise, it should not
99: be defined.
100:
101: @findex NO_BUILTIN_PTRDIFF_TYPE
102: @item NO_BUILTIN_PTRDIFF_TYPE
103: If this macro is defined, the preprocessor will not define the builtin macro
104: @code{__PTRDIFF_TYPE__}. The macro @code{__PTRDIFF_TYPE__} must then be
105: defined by @code{CPP_SPEC} instead.
106:
107: This should be defined if @code{PTRDIFF_TYPE} depends on target dependent flags
108: which are not accessible to the preprocessor. Otherwise, it should not
109: be defined.
110:
1.1 root 111: @findex SIGNED_CHAR_SPEC
112: @item SIGNED_CHAR_SPEC
113: A C string constant that tells the GNU CC driver program options to
114: pass to CPP. By default, this macro is defined to pass the option
115: @samp{-D__CHAR_UNSIGNED__} to CPP if @code{char} will be treated as
116: @code{unsigned char} by @code{cc1}.
117:
118: Do not define this macro unless you need to override the default
119: definition.
120:
121: @findex CC1_SPEC
122: @item CC1_SPEC
123: A C string constant that tells the GNU CC driver program options to
124: pass to @code{cc1}. It can also specify how to translate options you
125: give to GNU CC into options for GNU CC to pass to the @code{cc1}.
126:
127: Do not define this macro if it does not need to do anything.
128:
129: @findex CC1PLUS_SPEC
130: @item CC1PLUS_SPEC
131: A C string constant that tells the GNU CC driver program options to
132: pass to @code{cc1plus}. It can also specify how to translate options you
133: give to GNU CC into options for GNU CC to pass to the @code{cc1plus}.
134:
135: Do not define this macro if it does not need to do anything.
136:
137: @findex ASM_SPEC
138: @item ASM_SPEC
139: A C string constant that tells the GNU CC driver program options to
140: pass to the assembler. It can also specify how to translate options
141: you give to GNU CC into options for GNU CC to pass to the assembler.
142: See the file @file{sun3.h} for an example of this.
143:
144: Do not define this macro if it does not need to do anything.
145:
146: @findex ASM_FINAL_SPEC
147: @item ASM_FINAL_SPEC
148: A C string constant that tells the GNU CC driver program how to
149: run any programs which cleanup after the normal assembler.
150: Normally, this is not needed. See the file @file{mips.h} for
151: an example of this.
152:
153: Do not define this macro if it does not need to do anything.
154:
155: @findex LINK_SPEC
156: @item LINK_SPEC
157: A C string constant that tells the GNU CC driver program options to
158: pass to the linker. It can also specify how to translate options you
159: give to GNU CC into options for GNU CC to pass to the linker.
160:
161: Do not define this macro if it does not need to do anything.
162:
163: @findex LIB_SPEC
164: @item LIB_SPEC
165: Another C string constant used much like @code{LINK_SPEC}. The difference
166: between the two is that @code{LIB_SPEC} is used at the end of the
167: command given to the linker.
168:
169: If this macro is not defined, a default is provided that
170: loads the standard C library from the usual place. See @file{gcc.c}.
171:
1.1.1.8 ! root 172: @findex LIBGCC_SPEC
! 173: @item LIBGCC_SPEC
! 174: Another C string constant that tells the GNU CC driver program
! 175: how and when to place a reference to @file{libgcc.a} into the
! 176: linker command line. This constant is placed both before and after
! 177: the value of @code{LIB_SPEC}.
! 178:
! 179: If this macro is not defined, the GNU CC driver provides a default that
! 180: passes the string @samp{-lgcc} to the linker unless the @samp{-shared}
! 181: option is specified.
! 182:
1.1 root 183: @findex STARTFILE_SPEC
184: @item STARTFILE_SPEC
185: Another C string constant used much like @code{LINK_SPEC}. The
186: difference between the two is that @code{STARTFILE_SPEC} is used at
187: the very beginning of the command given to the linker.
188:
189: If this macro is not defined, a default is provided that loads the
190: standard C startup file from the usual place. See @file{gcc.c}.
191:
192: @findex ENDFILE_SPEC
193: @item ENDFILE_SPEC
194: Another C string constant used much like @code{LINK_SPEC}. The
195: difference between the two is that @code{ENDFILE_SPEC} is used at
196: the very end of the command given to the linker.
197:
198: Do not define this macro if it does not need to do anything.
199:
200: @findex LINK_LIBGCC_SPECIAL
201: @item LINK_LIBGCC_SPECIAL
1.1.1.8 ! root 202: Define this macro if the driver program should find the library
! 203: @file{libgcc.a} itself and should not pass @samp{-L} options to the
! 204: linker. If you do not define this macro, the driver program will pass
! 205: the argument @samp{-lgcc} to tell the linker to do the search and will
! 206: pass @samp{-L} options to it.
1.1.1.5 root 207:
208: @findex LINK_LIBGCC_SPECIAL_1
209: @item LINK_LIBGCC_SPECIAL_1
1.1.1.8 ! root 210: Define this macro if the driver program should find the library
! 211: @file{libgcc.a}. If you do not define this macro, the driver program will pass
! 212: the argument @samp{-lgcc} to tell the linker to do the search.
! 213: This macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it does
! 214: not affect @samp{-L} options.
! 215:
! 216: @findex MULTILIB_DEFAULTS
! 217: @item MULTILIB_DEFAULTS
! 218: Define this macro as a C expression for the initializer of an array of
! 219: string to tell the driver program which options are defaults for this
! 220: target and thus do not need to be handled specially when using
! 221: @code{MULTILIB_OPTIONS}.
! 222:
! 223: Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in
! 224: the target makefile fragment or if none of the options listed in
! 225: @code{MULTILIB_OPTIONS} are set by default.
! 226: @xref{Target Fragment}.
1.1 root 227:
228: @findex RELATIVE_PREFIX_NOT_LINKDIR
229: @item RELATIVE_PREFIX_NOT_LINKDIR
230: Define this macro to tell @code{gcc} that it should only translate
231: a @samp{-B} prefix into a @samp{-L} linker option if the prefix
232: indicates an absolute file name.
233:
234: @findex STANDARD_EXEC_PREFIX
235: @item STANDARD_EXEC_PREFIX
236: Define this macro as a C string constant if you wish to override the
1.1.1.2 root 237: standard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix to
1.1 root 238: try when searching for the executable files of the compiler.
239:
240: @findex MD_EXEC_PREFIX
241: @item MD_EXEC_PREFIX
242: If defined, this macro is an additional prefix to try after
243: @code{STANDARD_EXEC_PREFIX}. @code{MD_EXEC_PREFIX} is not searched
244: when the @samp{-b} option is used, or the compiler is built as a cross
245: compiler.
246:
247: @findex STANDARD_STARTFILE_PREFIX
248: @item STANDARD_STARTFILE_PREFIX
249: Define this macro as a C string constant if you wish to override the
1.1.1.3 root 250: standard choice of @file{/usr/local/lib/} as the default prefix to
1.1 root 251: try when searching for startup files such as @file{crt0.o}.
252:
253: @findex MD_STARTFILE_PREFIX
254: @item MD_STARTFILE_PREFIX
1.1.1.3 root 255: If defined, this macro supplies an additional prefix to try after the
256: standard prefixes. @code{MD_EXEC_PREFIX} is not searched when the
257: @samp{-b} option is used, or when the compiler is built as a cross
1.1 root 258: compiler.
259:
1.1.1.3 root 260: @findex MD_STARTFILE_PREFIX_1
261: @item MD_STARTFILE_PREFIX_1
262: If defined, this macro supplies yet another prefix to try after the
263: standard prefixes. It is not searched when the @samp{-b} option is
264: used, or when the compiler is built as a cross compiler.
265:
1.1.1.8 ! root 266: @findex INIT_ENVIRONMENT
! 267: @item INIT_ENVIRONMENT
! 268: Define this macro as a C string constant if you with to set environment
! 269: variables for programs called by the driver, such as the assembler and
! 270: loader. The driver passes the value of this macro to @code{putenv} to
! 271: initialize the necessary environment variables.
! 272:
1.1 root 273: @findex LOCAL_INCLUDE_DIR
274: @item LOCAL_INCLUDE_DIR
275: Define this macro as a C string constant if you wish to override the
276: standard choice of @file{/usr/local/include} as the default prefix to
277: try when searching for local header files. @code{LOCAL_INCLUDE_DIR}
278: comes before @code{SYSTEM_INCLUDE_DIR} in the search order.
279:
280: Cross compilers do not use this macro and do not search either
281: @file{/usr/local/include} or its replacement.
282:
283: @findex SYSTEM_INCLUDE_DIR
284: @item SYSTEM_INCLUDE_DIR
285: Define this macro as a C string constant if you wish to specify a
286: system-specific directory to search for header files before the standard
287: directory. @code{SYSTEM_INCLUDE_DIR} comes before
288: @code{STANDARD_INCLUDE_DIR} in the search order.
289:
290: Cross compilers do not use this macro and do not search the directory
291: specified.
292:
293: @findex STANDARD_INCLUDE_DIR
294: @item STANDARD_INCLUDE_DIR
295: Define this macro as a C string constant if you wish to override the
296: standard choice of @file{/usr/include} as the default prefix to
297: try when searching for header files.
298:
299: Cross compilers do not use this macro and do not search either
300: @file{/usr/include} or its replacement.
301:
302: @findex INCLUDE_DEFAULTS
303: @item INCLUDE_DEFAULTS
304: Define this macro if you wish to override the entire default search path
305: for include files. The default search path includes
1.1.1.5 root 306: @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR},
307: @code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and
308: @code{STANDARD_INCLUDE_DIR}. In addition, @code{GPLUSPLUS_INCLUDE_DIR}
309: and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile},
310: and specify private search areas for GCC. The directory
311: @code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs.
1.1 root 312:
313: The definition should be an initializer for an array of structures.
314: Each array element should have two elements: the directory name (a
315: string constant) and a flag for C++-only directories. Mark the end of
316: the array with a null element. For example, here is the definition used
317: for VMS:
318:
319: @example
320: #define INCLUDE_DEFAULTS \
321: @{ \
322: @{ "GNU_GXX_INCLUDE:", 1@}, \
323: @{ "GNU_CC_INCLUDE:", 0@}, \
324: @{ "SYS$SYSROOT:[SYSLIB.]", 0@}, \
325: @{ ".", 0@}, \
326: @{ 0, 0@} \
327: @}
328: @end example
329: @end table
330:
331: Here is the order of prefixes tried for exec files:
332:
333: @enumerate
334: @item
335: Any prefixes specified by the user with @samp{-B}.
336:
337: @item
338: The environment variable @code{GCC_EXEC_PREFIX}, if any.
339:
340: @item
341: The directories specified by the environment variable @code{COMPILER_PATH}.
342:
343: @item
344: The macro @code{STANDARD_EXEC_PREFIX}.
345:
346: @item
347: @file{/usr/lib/gcc/}.
348:
349: @item
350: The macro @code{MD_EXEC_PREFIX}, if any.
351: @end enumerate
352:
353: Here is the order of prefixes tried for startfiles:
354:
355: @enumerate
356: @item
357: Any prefixes specified by the user with @samp{-B}.
358:
359: @item
360: The environment variable @code{GCC_EXEC_PREFIX}, if any.
361:
362: @item
1.1.1.8 ! root 363: The directories specified by the environment variable @code{LIBRARY_PATH}
! 364: (native only, cross compilers do not use this).
1.1 root 365:
366: @item
367: The macro @code{STANDARD_EXEC_PREFIX}.
368:
369: @item
370: @file{/usr/lib/gcc/}.
371:
372: @item
373: The macro @code{MD_EXEC_PREFIX}, if any.
374:
375: @item
376: The macro @code{MD_STARTFILE_PREFIX}, if any.
377:
378: @item
379: The macro @code{STANDARD_STARTFILE_PREFIX}.
380:
381: @item
382: @file{/lib/}.
383:
384: @item
385: @file{/usr/lib/}.
386: @end enumerate
387:
1.1.1.2 root 388: @node Run-time Target
1.1 root 389: @section Run-time Target Specification
390: @cindex run-time target specification
391: @cindex predefined macros
392: @cindex target specifications
393:
1.1.1.7 root 394: @c prevent bad page break with this line
395: Here are run-time target specifications.
396:
1.1 root 397: @table @code
398: @findex CPP_PREDEFINES
399: @item CPP_PREDEFINES
400: Define this to be a string constant containing @samp{-D} options to
401: define the predefined macros that identify this machine and system.
402: These macros will be predefined unless the @samp{-ansi} option is
403: specified.
404:
405: In addition, a parallel set of macros are predefined, whose names are
406: made by appending @samp{__} at the beginning and at the end. These
407: @samp{__} macros are permitted by the ANSI standard, so they are
408: predefined regardless of whether @samp{-ansi} is specified.
409:
410: For example, on the Sun, one can use the following value:
411:
1.1.1.5 root 412: @smallexample
1.1 root 413: "-Dmc68000 -Dsun -Dunix"
1.1.1.5 root 414: @end smallexample
1.1 root 415:
416: The result is to define the macros @code{__mc68000__}, @code{__sun__}
417: and @code{__unix__} unconditionally, and the macros @code{mc68000},
418: @code{sun} and @code{unix} provided @samp{-ansi} is not specified.
419:
420: @findex extern int target_flags
421: @item extern int target_flags;
422: This declaration should be present.
423:
424: @cindex optional hardware or system features
425: @cindex features, optional, in system conventions
426: @item TARGET_@dots{}
427: This series of macros is to allow compiler command arguments to
428: enable or disable the use of optional features of the target machine.
429: For example, one machine description serves both the 68000 and
430: the 68020; a command argument tells the compiler whether it should
431: use 68020-only instructions or not. This command argument works
432: by means of a macro @code{TARGET_68020} that tests a bit in
433: @code{target_flags}.
434:
435: Define a macro @code{TARGET_@var{featurename}} for each such option.
436: Its definition should test a bit in @code{target_flags}; for example:
437:
1.1.1.5 root 438: @smallexample
1.1 root 439: #define TARGET_68020 (target_flags & 1)
1.1.1.5 root 440: @end smallexample
1.1 root 441:
442: One place where these macros are used is in the condition-expressions
443: of instruction patterns. Note how @code{TARGET_68020} appears
444: frequently in the 68000 machine description file, @file{m68k.md}.
445: Another place they are used is in the definitions of the other
446: macros in the @file{@var{machine}.h} file.
447:
448: @findex TARGET_SWITCHES
449: @item TARGET_SWITCHES
450: This macro defines names of command options to set and clear
451: bits in @code{target_flags}. Its definition is an initializer
452: with a subgrouping for each command option.
453:
454: Each subgrouping contains a string constant, that defines the option
455: name, and a number, which contains the bits to set in
456: @code{target_flags}. A negative number says to clear bits instead;
457: the negative of the number is which bits to clear. The actual option
458: name is made by appending @samp{-m} to the specified name.
459:
460: One of the subgroupings should have a null string. The number in
461: this grouping is the default value for @code{target_flags}. Any
462: target options act starting with that value.
463:
464: Here is an example which defines @samp{-m68000} and @samp{-m68020}
465: with opposite meanings, and picks the latter as the default:
466:
1.1.1.5 root 467: @smallexample
1.1 root 468: #define TARGET_SWITCHES \
469: @{ @{ "68020", 1@}, \
470: @{ "68000", -1@}, \
471: @{ "", 1@}@}
1.1.1.5 root 472: @end smallexample
1.1 root 473:
474: @findex TARGET_OPTIONS
475: @item TARGET_OPTIONS
476: This macro is similar to @code{TARGET_SWITCHES} but defines names of command
477: options that have values. Its definition is an initializer with a
478: subgrouping for each command option.
479:
480: Each subgrouping contains a string constant, that defines the fixed part
481: of the option name, and the address of a variable. The variable, type
482: @code{char *}, is set to the variable part of the given option if the fixed
483: part matches. The actual option name is made by appending @samp{-m} to the
484: specified name.
485:
486: Here is an example which defines @samp{-mshort-data-@var{number}}. If the
487: given option is @samp{-mshort-data-512}, the variable @code{m88k_short_data}
488: will be set to the string @code{"512"}.
489:
1.1.1.5 root 490: @smallexample
1.1 root 491: extern char *m88k_short_data;
1.1.1.5 root 492: #define TARGET_OPTIONS \
493: @{ @{ "short-data-", &m88k_short_data @} @}
494: @end smallexample
1.1 root 495:
496: @findex TARGET_VERSION
497: @item TARGET_VERSION
498: This macro is a C statement to print on @code{stderr} a string
499: describing the particular machine description choice. Every machine
500: description should define @code{TARGET_VERSION}. For example:
501:
1.1.1.5 root 502: @smallexample
1.1 root 503: #ifdef MOTOROLA
1.1.1.5 root 504: #define TARGET_VERSION \
505: fprintf (stderr, " (68k, Motorola syntax)");
1.1 root 506: #else
1.1.1.5 root 507: #define TARGET_VERSION \
508: fprintf (stderr, " (68k, MIT syntax)");
1.1 root 509: #endif
1.1.1.5 root 510: @end smallexample
1.1 root 511:
512: @findex OVERRIDE_OPTIONS
513: @item OVERRIDE_OPTIONS
514: Sometimes certain combinations of command options do not make sense on
515: a particular target machine. You can define a macro
516: @code{OVERRIDE_OPTIONS} to take account of this. This macro, if
517: defined, is executed once just after all the command options have been
518: parsed.
519:
520: Don't use this macro to turn on various extra optimizations for
521: @samp{-O}. That is what @code{OPTIMIZATION_OPTIONS} is for.
522:
523: @findex OPTIMIZATION_OPTIONS
524: @item OPTIMIZATION_OPTIONS (@var{level})
525: Some machines may desire to change what optimizations are performed for
526: various optimization levels. This macro, if defined, is executed once
527: just after the optimization level is determined and before the remainder
528: of the command options have been parsed. Values set in this macro are
529: used as the default values for the other command line options.
530:
1.1.1.7 root 531: @var{level} is the optimization level specified; 2 if @samp{-O2} is
532: specified, 1 if @samp{-O} is specified, and 0 if neither is specified.
1.1 root 533:
1.1.1.7 root 534: You should not use this macro to change options that are not
535: machine-specific. These should uniformly selected by the same
536: optimization level on all supported machines. Use this macro to enable
537: machbine-specific optimizations.
538:
539: @strong{Do not examine @code{write_symbols} in
540: this macro!} The debugging options are not supposed to alter the
541: generated code.
542:
543: @findex CAN_DEBUG_WITHOUT_FP
544: @item CAN_DEBUG_WITHOUT_FP
545: Define this macro if debugging can be performed even without a frame
546: pointer. If this macro is defined, GNU CC will turn on the
547: @samp{-fomit-frame-pointer} option whenever @samp{-O} is specified.
1.1 root 548: @end table
549:
1.1.1.2 root 550: @node Storage Layout
1.1 root 551: @section Storage Layout
552: @cindex storage layout
553:
554: Note that the definitions of the macros in this table which are sizes or
555: alignments measured in bits do not need to be constant. They can be C
556: expressions that refer to static variables, such as the @code{target_flags}.
557: @xref{Run-time Target}.
558:
559: @table @code
560: @findex BITS_BIG_ENDIAN
561: @item BITS_BIG_ENDIAN
1.1.1.8 ! root 562: Define this macro to have the value 1 if the most significant bit in a
! 563: byte has the lowest number; otherwise define it to have the value zero.
1.1 root 564: This means that bit-field instructions count from the most significant
1.1.1.5 root 565: bit. If the machine has no bit-field instructions, then this must still
1.1.1.8 ! root 566: be defined, but it doesn't matter which value it is defined to. This
! 567: macro need not be a constant.
1.1 root 568:
569: This macro does not affect the way structure fields are packed into
570: bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.
571:
572: @findex BYTES_BIG_ENDIAN
573: @item BYTES_BIG_ENDIAN
1.1.1.8 ! root 574: Define this macro to have the value 1 if the most significant byte in a
! 575: word has the lowest number. This macro need not be a constant.
1.1 root 576:
577: @findex WORDS_BIG_ENDIAN
578: @item WORDS_BIG_ENDIAN
1.1.1.8 ! root 579: Define this macro to have the value 1 if, in a multiword object, the
! 580: most significant word has the lowest number. This applies to both
! 581: memory locations and registers; GNU CC fundamentally assumes that the
! 582: order of words in memory is the same as the order in registers. This
! 583: macro need not be a constant.
! 584:
! 585: @findex LIBGCC2_WORDS_BIG_ENDIAN
! 586: @item LIBGCC2_WORDS_BIG_ENDIAN
! 587: Define this macro if WORDS_BIG_ENDIAN is not constant. This must be a
! 588: constant value with the same meaning as WORDS_BIG_ENDIAN, which will be
! 589: used only when compiling libgcc2.c. Typically the value will be set
! 590: based on preprocessor defines.
1.1 root 591:
1.1.1.6 root 592: @findex FLOAT_WORDS_BIG_ENDIAN
593: @item FLOAT_WORDS_BIG_ENDIAN
1.1.1.8 ! root 594: Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or
1.1.1.6 root 595: @code{TFmode} floating point numbers are stored in memory with the word
1.1.1.8 ! root 596: containing the sign bit at the lowest address; otherwise define it to
! 597: have the value 0. This macro need not be a constant.
1.1.1.6 root 598:
599: You need not define this macro if the ordering is the same as for
600: multi-word integers.
601:
1.1 root 602: @findex BITS_PER_UNIT
603: @item BITS_PER_UNIT
1.1.1.5 root 604: Define this macro to be the number of bits in an addressable storage
605: unit (byte); normally 8.
1.1 root 606:
607: @findex BITS_PER_WORD
608: @item BITS_PER_WORD
609: Number of bits in a word; normally 32.
610:
611: @findex MAX_BITS_PER_WORD
612: @item MAX_BITS_PER_WORD
613: Maximum number of bits in a word. If this is undefined, the default is
614: @code{BITS_PER_WORD}. Otherwise, it is the constant value that is the
615: largest value that @code{BITS_PER_WORD} can have at run-time.
616:
617: @findex UNITS_PER_WORD
618: @item UNITS_PER_WORD
619: Number of storage units in a word; normally 4.
620:
1.1.1.8 ! root 621: @findex MIN_UNITS_PER_WORD
! 622: @item MIN_UNITS_PER_WORD
! 623: Minimum number of units in a word. If this is undefined, the default is
1.1.1.6 root 624: @code{UNITS_PER_WORD}. Otherwise, it is the constant value that is the
1.1.1.8 ! root 625: smallest value that @code{UNITS_PER_WORD} can have at run-time.
1.1.1.6 root 626:
1.1 root 627: @findex POINTER_SIZE
628: @item POINTER_SIZE
1.1.1.8 ! root 629: Width of a pointer, in bits. You must specify a value no wider than the
! 630: width of @code{Pmode}. If it is not equal to the width of @code{Pmode},
! 631: you must define @code{POINTERS_EXTEND_UNSIGNED}.
! 632:
! 633: @findex POINTERS_EXTEND_UNSIGNED
! 634: @item POINTERS_EXTEND_UNSIGNED
! 635: A C expression whose value is nonzero if pointers that need to be
! 636: extended from being @code{POINTER_SIZE} bits wide to @code{Pmode}
! 637: are sign-extended and zero if they are zero-extended.
! 638:
! 639: You need not define this macro if the @code{POINTER_SIZE} is equal
! 640: to the width of @code{Pmode}.
1.1 root 641:
1.1.1.4 root 642: @findex PROMOTE_MODE
643: @item PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type})
644: A macro to update @var{m} and @var{unsignedp} when an object whose type
645: is @var{type} and which has the specified mode and signedness is to be
646: stored in a register. This macro is only called when @var{type} is a
647: scalar type.
648:
649: On most RISC machines, which only have operations that operate on a full
650: register, define this macro to set @var{m} to @code{word_mode} if
651: @var{m} is an integer mode narrower than @code{BITS_PER_WORD}. In most
652: cases, only integer modes should be widened because wider-precision
653: floating-point operations are usually more expensive than their narrower
654: counterparts.
655:
656: For most machines, the macro definition does not change @var{unsignedp}.
657: However, some machines, have instructions that preferentially handle
1.1.1.5 root 658: either signed or unsigned quantities of certain modes. For example, on
1.1.1.4 root 659: the DEC Alpha, 32-bit loads from memory and 32-bit add instructions
660: sign-extend the result to 64 bits. On such machines, set
661: @var{unsignedp} according to which kind of extension is more efficient.
662:
663: Do not define this macro if it would never modify @var{m}.
664:
665: @findex PROMOTE_FUNCTION_ARGS
666: @item PROMOTE_FUNCTION_ARGS
667: Define this macro if the promotion described by @code{PROMOTE_MODE}
668: should also be done for outgoing function arguments.
669:
670: @findex PROMOTE_FUNCTION_RETURN
671: @item PROMOTE_FUNCTION_RETURN
672: Define this macro if the promotion described by @code{PROMOTE_MODE}
673: should also be done for the return value of functions.
674:
675: If this macro is defined, @code{FUNCTION_VALUE} must perform the same
676: promotions done by @code{PROMOTE_MODE}.
677:
1.1.1.7 root 678: @findex PROMOTE_FOR_CALL_ONLY
679: @item PROMOTE_FOR_CALL_ONLY
680: Define this macro if the promotion described by @code{PROMOTE_MODE}
681: should @emph{only} be performed for outgoing function arguments or
682: function return values, as specified by @code{PROMOTE_FUNCTION_ARGS}
683: and @code{PROMOTE_FUNCTION_RETURN}, respectively.
684:
1.1 root 685: @findex PARM_BOUNDARY
686: @item PARM_BOUNDARY
687: Normal alignment required for function parameters on the stack, in
1.1.1.4 root 688: bits. All stack parameters receive at least this much alignment
1.1 root 689: regardless of data type. On most machines, this is the same as the
690: size of an integer.
691:
692: @findex STACK_BOUNDARY
693: @item STACK_BOUNDARY
694: Define this macro if you wish to preserve a certain alignment for
695: the stack pointer. The definition is a C expression
696: for the desired alignment (measured in bits).
697:
698: @cindex @code{PUSH_ROUNDING}, interaction with @code{STACK_BOUNDARY}
699: If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned
700: to the specified boundary. If @code{PUSH_ROUNDING} is defined and specifies a
701: less strict alignment than @code{STACK_BOUNDARY}, the stack may be
702: momentarily unaligned while pushing arguments.
703:
704: @findex FUNCTION_BOUNDARY
705: @item FUNCTION_BOUNDARY
706: Alignment required for a function entry point, in bits.
707:
708: @findex BIGGEST_ALIGNMENT
709: @item BIGGEST_ALIGNMENT
710: Biggest alignment that any data type can require on this machine, in bits.
711:
712: @findex BIGGEST_FIELD_ALIGNMENT
713: @item BIGGEST_FIELD_ALIGNMENT
714: Biggest alignment that any structure field can require on this machine,
1.1.1.3 root 715: in bits. If defined, this overrides @code{BIGGEST_ALIGNMENT} for
716: structure fields only.
1.1 root 717:
718: @findex MAX_OFILE_ALIGNMENT
719: @item MAX_OFILE_ALIGNMENT
720: Biggest alignment supported by the object file format of this machine.
721: Use this macro to limit the alignment which can be specified using the
722: @code{__attribute__ ((aligned (@var{n})))} construct. If not defined,
723: the default value is @code{BIGGEST_ALIGNMENT}.
724:
725: @findex DATA_ALIGNMENT
726: @item DATA_ALIGNMENT (@var{type}, @var{basic-align})
727: If defined, a C expression to compute the alignment for a static
728: variable. @var{type} is the data type, and @var{basic-align} is the
729: alignment that the object would ordinarily have. The value of this
730: macro is used instead of that alignment to align the object.
731:
732: If this macro is not defined, then @var{basic-align} is used.
733:
734: @findex strcpy
735: One use of this macro is to increase alignment of medium-size data to
736: make it all fit in fewer cache lines. Another is to cause character
737: arrays to be word-aligned so that @code{strcpy} calls that copy
738: constants to character arrays can be done inline.
739:
740: @findex CONSTANT_ALIGNMENT
741: @item CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align})
742: If defined, a C expression to compute the alignment given to a constant
743: that is being placed in memory. @var{constant} is the constant and
744: @var{basic-align} is the alignment that the object would ordinarily
745: have. The value of this macro is used instead of that alignment to
746: align the object.
747:
748: If this macro is not defined, then @var{basic-align} is used.
749:
750: The typical use of this macro is to increase alignment for string
751: constants to be word aligned so that @code{strcpy} calls that copy
752: constants can be done inline.
753:
754: @findex EMPTY_FIELD_BOUNDARY
755: @item EMPTY_FIELD_BOUNDARY
756: Alignment in bits to be given to a structure bit field that follows an
757: empty field such as @code{int : 0;}.
758:
1.1.1.2 root 759: Note that @code{PCC_BITFIELD_TYPE_MATTERS} also affects the alignment
760: that results from an empty field.
761:
1.1 root 762: @findex STRUCTURE_SIZE_BOUNDARY
763: @item STRUCTURE_SIZE_BOUNDARY
764: Number of bits which any structure or union's size must be a multiple of.
765: Each structure or union's size is rounded up to a multiple of this.
766:
767: If you do not define this macro, the default is the same as
768: @code{BITS_PER_UNIT}.
769:
770: @findex STRICT_ALIGNMENT
771: @item STRICT_ALIGNMENT
1.1.1.2 root 772: Define this macro to be the value 1 if instructions will fail to work
773: if given data not on the nominal alignment. If instructions will merely
774: go slower in that case, define this macro as 0.
1.1 root 775:
776: @findex PCC_BITFIELD_TYPE_MATTERS
777: @item PCC_BITFIELD_TYPE_MATTERS
778: Define this if you wish to imitate the way many other C compilers handle
779: alignment of bitfields and the structures that contain them.
780:
781: The behavior is that the type written for a bitfield (@code{int},
782: @code{short}, or other integer type) imposes an alignment for the
783: entire structure, as if the structure really did contain an ordinary
784: field of that type. In addition, the bitfield is placed within the
785: structure so that it would fit within such a field, not crossing a
786: boundary for it.
787:
788: Thus, on most machines, a bitfield whose type is written as @code{int}
789: would not cross a four-byte boundary, and would force four-byte
790: alignment for the whole structure. (The alignment used may not be four
791: bytes; it is controlled by the other alignment parameters.)
792:
793: If the macro is defined, its definition should be a C expression;
794: a nonzero value for the expression enables this behavior.
795:
796: Note that if this macro is not defined, or its value is zero, some
797: bitfields may cross more than one alignment boundary. The compiler can
798: support such references if there are @samp{insv}, @samp{extv}, and
799: @samp{extzv} insns that can directly reference memory.
800:
801: The other known way of making bitfields work is to define
802: @code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}.
803: Then every structure can be accessed with fullwords.
804:
805: Unless the machine has bitfield instructions or you define
806: @code{STRUCTURE_SIZE_BOUNDARY} that way, you must define
807: @code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value.
808:
1.1.1.4 root 809: If your aim is to make GNU CC use the same conventions for laying out
810: bitfields as are used by another compiler, here is how to investigate
811: what the other compiler does. Compile and run this program:
812:
813: @example
814: struct foo1
815: @{
816: char x;
817: char :0;
818: char y;
819: @};
820:
821: struct foo2
822: @{
823: char x;
824: int :0;
825: char y;
826: @};
827:
828: main ()
829: @{
1.1.1.5 root 830: printf ("Size of foo1 is %d\n",
831: sizeof (struct foo1));
832: printf ("Size of foo2 is %d\n",
833: sizeof (struct foo2));
1.1.1.4 root 834: exit (0);
835: @}
836: @end example
837:
838: If this prints 2 and 5, then the compiler's behavior is what you would
839: get from @code{PCC_BITFIELD_TYPE_MATTERS}.
840:
1.1 root 841: @findex BITFIELD_NBYTES_LIMITED
842: @item BITFIELD_NBYTES_LIMITED
843: Like PCC_BITFIELD_TYPE_MATTERS except that its effect is limited to
844: aligning a bitfield within the structure.
845:
846: @findex ROUND_TYPE_SIZE
847: @item ROUND_TYPE_SIZE (@var{struct}, @var{size}, @var{align})
848: Define this macro as an expression for the overall size of a structure
849: (given by @var{struct} as a tree node) when the size computed from the
850: fields is @var{size} and the alignment is @var{align}.
851:
852: The default is to round @var{size} up to a multiple of @var{align}.
853:
854: @findex ROUND_TYPE_ALIGN
855: @item ROUND_TYPE_ALIGN (@var{struct}, @var{computed}, @var{specified})
856: Define this macro as an expression for the alignment of a structure
857: (given by @var{struct} as a tree node) if the alignment computed in the
858: usual way is @var{computed} and the alignment explicitly specified was
859: @var{specified}.
860:
861: The default is to use @var{specified} if it is larger; otherwise, use
862: the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT}
863:
864: @findex MAX_FIXED_MODE_SIZE
865: @item MAX_FIXED_MODE_SIZE
866: An integer expression for the size in bits of the largest integer
867: machine mode that should actually be used. All integer machine modes of
868: this size or smaller can be used for structures and unions with the
869: appropriate sizes. If this macro is undefined, @code{GET_MODE_BITSIZE
870: (DImode)} is assumed.
871:
872: @findex CHECK_FLOAT_VALUE
1.1.1.7 root 873: @item CHECK_FLOAT_VALUE (@var{mode}, @var{value}, @var{overflow})
1.1 root 874: A C statement to validate the value @var{value} (of type
875: @code{double}) for mode @var{mode}. This means that you check whether
876: @var{value} fits within the possible range of values for mode
877: @var{mode} on this target machine. The mode @var{mode} is always
1.1.1.7 root 878: a mode of class @code{MODE_FLOAT}. @var{overflow} is nonzero if
879: the value is already known to be out of range.
1.1 root 880:
1.1.1.7 root 881: If @var{value} is not valid or if @var{overflow} is nonzero, you should
882: set @var{overflow} to 1 and then assign some valid value to @var{value}.
1.1 root 883: Allowing an invalid value to go through the compiler can produce
1.1.1.7 root 884: incorrect assembler code which may even cause Unix assemblers to crash.
1.1 root 885:
886: This macro need not be defined if there is no work for it to do.
887:
888: @findex TARGET_FLOAT_FORMAT
889: @item TARGET_FLOAT_FORMAT
890: A code distinguishing the floating point format of the target machine.
891: There are three defined values:
892:
893: @table @code
894: @findex IEEE_FLOAT_FORMAT
895: @item IEEE_FLOAT_FORMAT
896: This code indicates IEEE floating point. It is the default; there is no
897: need to define this macro when the format is IEEE.
898:
899: @findex VAX_FLOAT_FORMAT
900: @item VAX_FLOAT_FORMAT
901: This code indicates the peculiar format used on the Vax.
902:
903: @findex UNKNOWN_FLOAT_FORMAT
904: @item UNKNOWN_FLOAT_FORMAT
905: This code indicates any other format.
906: @end table
907:
908: The value of this macro is compared with @code{HOST_FLOAT_FORMAT}
909: (@pxref{Config}) to determine whether the target machine has the same
910: format as the host machine. If any other formats are actually in use on
911: supported machines, new codes should be defined for them.
1.1.1.6 root 912:
913: The ordering of the component words of floating point values stored in
914: memory is controlled by @code{FLOAT_WORDS_BIG_ENDIAN} for the target
915: machine and @code{HOST_FLOAT_WORDS_BIG_ENDIAN} for the host.
1.1 root 916: @end table
917:
1.1.1.2 root 918: @node Type Layout
1.1 root 919: @section Layout of Source Language Data Types
920:
921: These macros define the sizes and other characteristics of the standard
922: basic data types used in programs being compiled. Unlike the macros in
923: the previous section, these apply to specific features of C and related
924: languages, rather than to fundamental aspects of storage layout.
925:
926: @table @code
927: @findex INT_TYPE_SIZE
928: @item INT_TYPE_SIZE
929: A C expression for the size in bits of the type @code{int} on the
930: target machine. If you don't define this, the default is one word.
931:
1.1.1.6 root 932: @findex MAX_INT_TYPE_SIZE
933: @item MAX_INT_TYPE_SIZE
934: Maximum number for the size in bits of the type @code{int} on the target
935: machine. If this is undefined, the default is @code{INT_TYPE_SIZE}.
936: Otherwise, it is the constant value that is the largest value that
937: @code{INT_TYPE_SIZE} can have at run-time. This is used in @code{cpp}.
938:
1.1 root 939: @findex SHORT_TYPE_SIZE
940: @item SHORT_TYPE_SIZE
941: A C expression for the size in bits of the type @code{short} on the
942: target machine. If you don't define this, the default is half a word.
943: (If this would be less than one storage unit, it is rounded up to one
944: unit.)
945:
946: @findex LONG_TYPE_SIZE
947: @item LONG_TYPE_SIZE
948: A C expression for the size in bits of the type @code{long} on the
949: target machine. If you don't define this, the default is one word.
950:
1.1.1.6 root 951: @findex MAX_LONG_TYPE_SIZE
952: @item MAX_LONG_TYPE_SIZE
953: Maximum number for the size in bits of the type @code{long} on the
954: target machine. If this is undefined, the default is
955: @code{LONG_TYPE_SIZE}. Otherwise, it is the constant value that is the
956: largest value that @code{LONG_TYPE_SIZE} can have at run-time. This is
957: used in @code{cpp}.
958:
1.1 root 959: @findex LONG_LONG_TYPE_SIZE
960: @item LONG_LONG_TYPE_SIZE
961: A C expression for the size in bits of the type @code{long long} on the
962: target machine. If you don't define this, the default is two
1.1.1.8 ! root 963: words. If you want to support GNU Ada on your machine, the value of
! 964: macro must be at least 64.
1.1 root 965:
966: @findex CHAR_TYPE_SIZE
967: @item CHAR_TYPE_SIZE
968: A C expression for the size in bits of the type @code{char} on the
969: target machine. If you don't define this, the default is one quarter
970: of a word. (If this would be less than one storage unit, it is rounded up
971: to one unit.)
972:
1.1.1.6 root 973: @findex MAX_CHAR_TYPE_SIZE
974: @item MAX_CHAR_TYPE_SIZE
975: Maximum number for the size in bits of the type @code{char} on the
976: target machine. If this is undefined, the default is
977: @code{CHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the
978: largest value that @code{CHAR_TYPE_SIZE} can have at run-time. This is
979: used in @code{cpp}.
980:
1.1 root 981: @findex FLOAT_TYPE_SIZE
982: @item FLOAT_TYPE_SIZE
983: A C expression for the size in bits of the type @code{float} on the
984: target machine. If you don't define this, the default is one word.
985:
986: @findex DOUBLE_TYPE_SIZE
987: @item DOUBLE_TYPE_SIZE
988: A C expression for the size in bits of the type @code{double} on the
989: target machine. If you don't define this, the default is two
990: words.
991:
992: @findex LONG_DOUBLE_TYPE_SIZE
993: @item LONG_DOUBLE_TYPE_SIZE
994: A C expression for the size in bits of the type @code{long double} on
995: the target machine. If you don't define this, the default is two
996: words.
997:
998: @findex DEFAULT_SIGNED_CHAR
999: @item DEFAULT_SIGNED_CHAR
1000: An expression whose value is 1 or 0, according to whether the type
1001: @code{char} should be signed or unsigned by default. The user can
1002: always override this default with the options @samp{-fsigned-char}
1003: and @samp{-funsigned-char}.
1004:
1005: @findex DEFAULT_SHORT_ENUMS
1006: @item DEFAULT_SHORT_ENUMS
1007: A C expression to determine whether to give an @code{enum} type
1008: only as many bytes as it takes to represent the range of possible values
1009: of that type. A nonzero value means to do that; a zero value means all
1010: @code{enum} types should be allocated like @code{int}.
1011:
1012: If you don't define the macro, the default is 0.
1013:
1014: @findex SIZE_TYPE
1015: @item SIZE_TYPE
1016: A C expression for a string describing the name of the data type to use
1017: for size values. The typedef name @code{size_t} is defined using the
1018: contents of the string.
1019:
1020: The string can contain more than one keyword. If so, separate them with
1021: spaces, and write first any length keyword, then @code{unsigned} if
1022: appropriate, and finally @code{int}. The string must exactly match one
1023: of the data type names defined in the function
1024: @code{init_decl_processing} in the file @file{c-decl.c}. You may not
1025: omit @code{int} or change the order---that would cause the compiler to
1026: crash on startup.
1027:
1028: If you don't define this macro, the default is @code{"long unsigned
1029: int"}.
1030:
1031: @findex PTRDIFF_TYPE
1032: @item PTRDIFF_TYPE
1033: A C expression for a string describing the name of the data type to use
1034: for the result of subtracting two pointers. The typedef name
1035: @code{ptrdiff_t} is defined using the contents of the string. See
1036: @code{SIZE_TYPE} above for more information.
1037:
1038: If you don't define this macro, the default is @code{"long int"}.
1039:
1040: @findex WCHAR_TYPE
1041: @item WCHAR_TYPE
1042: A C expression for a string describing the name of the data type to use
1043: for wide characters. The typedef name @code{wchar_t} is defined using
1044: the contents of the string. See @code{SIZE_TYPE} above for more
1045: information.
1046:
1047: If you don't define this macro, the default is @code{"int"}.
1048:
1049: @findex WCHAR_TYPE_SIZE
1050: @item WCHAR_TYPE_SIZE
1051: A C expression for the size in bits of the data type for wide
1052: characters. This is used in @code{cpp}, which cannot make use of
1053: @code{WCHAR_TYPE}.
1054:
1.1.1.6 root 1055: @findex MAX_WCHAR_TYPE_SIZE
1056: @item MAX_WCHAR_TYPE_SIZE
1057: Maximum number for the size in bits of the data type for wide
1058: characters. If this is undefined, the default is
1059: @code{WCHAR_TYPE_SIZE}. Otherwise, it is the constant value that is the
1060: largest value that @code{WCHAR_TYPE_SIZE} can have at run-time. This is
1061: used in @code{cpp}.
1062:
1.1 root 1063: @findex OBJC_INT_SELECTORS
1064: @item OBJC_INT_SELECTORS
1065: Define this macro if the type of Objective C selectors should be
1066: @code{int}.
1067:
1068: If this macro is not defined, then selectors should have the type
1069: @code{struct objc_selector *}.
1070:
1.1.1.3 root 1071: @findex OBJC_SELECTORS_WITHOUT_LABELS
1072: @item OBJC_SELECTORS_WITHOUT_LABELS
1073: Define this macro if the compiler can group all the selectors together
1074: into a vector and use just one label at the beginning of the vector.
1075: Otherwise, the compiler must give each selector its own assembler
1076: label.
1077:
1078: On certain machines, it is important to have a separate label for each
1079: selector because this enables the linker to eliminate duplicate selectors.
1.1 root 1080:
1081: @findex TARGET_BELL
1082: @item TARGET_BELL
1083: A C constant expression for the integer value for escape sequence
1084: @samp{\a}.
1085:
1086: @findex TARGET_TAB
1087: @findex TARGET_BS
1088: @findex TARGET_NEWLINE
1089: @item TARGET_BS
1090: @itemx TARGET_TAB
1091: @itemx TARGET_NEWLINE
1092: C constant expressions for the integer values for escape sequences
1093: @samp{\b}, @samp{\t} and @samp{\n}.
1094:
1095: @findex TARGET_VT
1096: @findex TARGET_FF
1097: @findex TARGET_CR
1098: @item TARGET_VT
1099: @itemx TARGET_FF
1100: @itemx TARGET_CR
1101: C constant expressions for the integer values for escape sequences
1102: @samp{\v}, @samp{\f} and @samp{\r}.
1103: @end table
1104:
1.1.1.2 root 1105: @node Registers
1.1 root 1106: @section Register Usage
1107: @cindex register usage
1108:
1109: This section explains how to describe what registers the target machine
1110: has, and how (in general) they can be used.
1111:
1112: The description of which registers a specific instruction can use is
1113: done with register classes; see @ref{Register Classes}. For information
1114: on using registers to access a stack frame, see @ref{Frame Registers}.
1115: For passing values in registers, see @ref{Register Arguments}.
1116: For returning values in registers, see @ref{Scalar Return}.
1117:
1118: @menu
1119: * Register Basics:: Number and kinds of registers.
1120: * Allocation Order:: Order in which registers are allocated.
1121: * Values in Registers:: What kinds of values each reg can hold.
1122: * Leaf Functions:: Renumbering registers for leaf functions.
1123: * Stack Registers:: Handling a register stack such as 80387.
1124: * Obsolete Register Macros:: Macros formerly used for the 80387.
1125: @end menu
1126:
1127: @node Register Basics
1128: @subsection Basic Characteristics of Registers
1129:
1.1.1.7 root 1130: @c prevent bad page break with this line
1131: Registers have various characteristics.
1132:
1.1 root 1133: @table @code
1134: @findex FIRST_PSEUDO_REGISTER
1135: @item FIRST_PSEUDO_REGISTER
1136: Number of hardware registers known to the compiler. They receive
1137: numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
1138: pseudo register's number really is assigned the number
1139: @code{FIRST_PSEUDO_REGISTER}.
1140:
1141: @item FIXED_REGISTERS
1142: @findex FIXED_REGISTERS
1143: @cindex fixed register
1144: An initializer that says which registers are used for fixed purposes
1145: all throughout the compiled code and are therefore not available for
1146: general allocation. These would include the stack pointer, the frame
1147: pointer (except on machines where that can be used as a general
1148: register when no frame pointer is needed), the program counter on
1149: machines where that is considered one of the addressable registers,
1150: and any other numbered register with a standard use.
1151:
1152: This information is expressed as a sequence of numbers, separated by
1153: commas and surrounded by braces. The @var{n}th number is 1 if
1154: register @var{n} is fixed, 0 otherwise.
1155:
1156: The table initialized from this macro, and the table initialized by
1157: the following one, may be overridden at run time either automatically,
1158: by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
1159: the user with the command options @samp{-ffixed-@var{reg}},
1160: @samp{-fcall-used-@var{reg}} and @samp{-fcall-saved-@var{reg}}.
1161:
1162: @findex CALL_USED_REGISTERS
1163: @item CALL_USED_REGISTERS
1164: @cindex call-used register
1165: @cindex call-clobbered register
1166: @cindex call-saved register
1167: Like @code{FIXED_REGISTERS} but has 1 for each register that is
1168: clobbered (in general) by function calls as well as for fixed
1169: registers. This macro therefore identifies the registers that are not
1170: available for general allocation of values that must live across
1171: function calls.
1172:
1173: If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
1174: automatically saves it on function entry and restores it on function
1175: exit, if the register is used within the function.
1176:
1177: @findex CONDITIONAL_REGISTER_USAGE
1178: @findex fixed_regs
1179: @findex call_used_regs
1180: @item CONDITIONAL_REGISTER_USAGE
1181: Zero or more C statements that may conditionally modify two variables
1182: @code{fixed_regs} and @code{call_used_regs} (both of type @code{char
1183: []}) after they have been initialized from the two preceding macros.
1184:
1185: This is necessary in case the fixed or call-clobbered registers depend
1186: on target flags.
1187:
1188: You need not define this macro if it has no work to do.
1189:
1190: @cindex disabling certain registers
1191: @cindex controlling register usage
1192: If the usage of an entire class of registers depends on the target
1193: flags, you may indicate this to GCC by using this macro to modify
1194: @code{fixed_regs} and @code{call_used_regs} to 1 for each of the
1195: registers in the classes which should not be used by GCC. Also define
1196: the macro @code{REG_CLASS_FROM_LETTER} to return @code{NO_REGS} if it
1197: is called with a letter for a class that shouldn't be used.
1198:
1199: (However, if this class is not included in @code{GENERAL_REGS} and all
1200: of the insn patterns whose constraints permit this class are
1201: controlled by target switches, then GCC will automatically avoid using
1202: these registers when the target switches are opposed to them.)
1203:
1204: @findex NON_SAVING_SETJMP
1205: @item NON_SAVING_SETJMP
1206: If this macro is defined and has a nonzero value, it means that
1207: @code{setjmp} and related functions fail to save the registers, or that
1208: @code{longjmp} fails to restore them. To compensate, the compiler
1209: avoids putting variables in registers in functions that use
1210: @code{setjmp}.
1211:
1.1.1.5 root 1212: @findex INCOMING_REGNO
1213: @item INCOMING_REGNO (@var{out})
1214: Define this macro if the target machine has register windows. This C
1215: expression returns the register number as seen by the called function
1216: corresponding to the register number @var{out} as seen by the calling
1217: function. Return @var{out} if register number @var{out} is not an
1218: outbound register.
1219:
1220: @findex OUTGOING_REGNO
1221: @item OUTGOING_REGNO (@var{in})
1222: Define this macro if the target machine has register windows. This C
1223: expression returns the register number as seen by the calling function
1224: corresponding to the register number @var{in} as seen by the called
1225: function. Return @var{in} if register number @var{in} is not an inbound
1226: register.
1227:
1.1 root 1228: @ignore
1229: @findex PC_REGNUM
1230: @item PC_REGNUM
1231: If the program counter has a register number, define this as that
1232: register number. Otherwise, do not define it.
1233: @end ignore
1234: @end table
1235:
1236: @node Allocation Order
1237: @subsection Order of Allocation of Registers
1238: @cindex order of register allocation
1239: @cindex register allocation order
1240:
1.1.1.7 root 1241: @c prevent bad page break with this line
1242: Registers are allocated in order.
1243:
1.1 root 1244: @table @code
1245: @findex REG_ALLOC_ORDER
1246: @item REG_ALLOC_ORDER
1247: If defined, an initializer for a vector of integers, containing the
1248: numbers of hard registers in the order in which GNU CC should prefer
1249: to use them (from most preferred to least).
1250:
1251: If this macro is not defined, registers are used lowest numbered first
1252: (all else being equal).
1253:
1254: One use of this macro is on machines where the highest numbered
1255: registers must always be saved and the save-multiple-registers
1256: instruction supports only sequences of consecutive registers. On such
1257: machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists
1258: the highest numbered allocatable register first.
1259:
1260: @findex ORDER_REGS_FOR_LOCAL_ALLOC
1261: @item ORDER_REGS_FOR_LOCAL_ALLOC
1262: A C statement (sans semicolon) to choose the order in which to allocate
1263: hard registers for pseudo-registers local to a basic block.
1264:
1.1.1.5 root 1265: Store the desired register order in the array @code{reg_alloc_order}.
1266: Element 0 should be the register to allocate first; element 1, the next
1267: register; and so on.
1.1 root 1268:
1269: The macro body should not assume anything about the contents of
1270: @code{reg_alloc_order} before execution of the macro.
1271:
1272: On most machines, it is not necessary to define this macro.
1273: @end table
1274:
1275: @node Values in Registers
1276: @subsection How Values Fit in Registers
1277:
1278: This section discusses the macros that describe which kinds of values
1279: (specifically, which machine modes) each register can hold, and how many
1280: consecutive registers are needed for a given mode.
1281:
1282: @table @code
1283: @findex HARD_REGNO_NREGS
1284: @item HARD_REGNO_NREGS (@var{regno}, @var{mode})
1285: A C expression for the number of consecutive hard registers, starting
1286: at register number @var{regno}, required to hold a value of mode
1287: @var{mode}.
1288:
1289: On a machine where all registers are exactly one word, a suitable
1290: definition of this macro is
1291:
1.1.1.5 root 1292: @smallexample
1.1 root 1293: #define HARD_REGNO_NREGS(REGNO, MODE) \
1294: ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1) \
1295: / UNITS_PER_WORD))
1.1.1.5 root 1296: @end smallexample
1.1 root 1297:
1298: @findex HARD_REGNO_MODE_OK
1299: @item HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
1300: A C expression that is nonzero if it is permissible to store a value
1301: of mode @var{mode} in hard register number @var{regno} (or in several
1302: registers starting with that one). For a machine where all registers
1303: are equivalent, a suitable definition is
1304:
1.1.1.5 root 1305: @smallexample
1.1 root 1306: #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
1.1.1.5 root 1307: @end smallexample
1.1 root 1308:
1309: It is not necessary for this macro to check for the numbers of fixed
1310: registers, because the allocation mechanism considers them to be always
1311: occupied.
1312:
1313: @cindex register pairs
1314: On some machines, double-precision values must be kept in even/odd
1315: register pairs. The way to implement that is to define this macro
1316: to reject odd register numbers for such modes.
1317:
1318: @ignore
1319: @c I think this is not true now
1320: GNU CC assumes that it can always move values between registers and
1321: (suitably addressed) memory locations. If it is impossible to move a
1322: value of a certain mode between memory and certain registers, then
1323: @code{HARD_REGNO_MODE_OK} must not allow this mode in those registers.
1324: @end ignore
1325:
1326: The minimum requirement for a mode to be OK in a register is that the
1327: @samp{mov@var{mode}} instruction pattern support moves between the
1328: register and any other hard register for which the mode is OK; and that
1329: moving a value into the register and back out not alter it.
1330:
1331: Since the same instruction used to move @code{SImode} will work for all
1332: narrower integer modes, it is not necessary on any machine for
1333: @code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided
1334: you define patterns @samp{movhi}, etc., to take advantage of this. This
1335: is useful because of the interaction between @code{HARD_REGNO_MODE_OK}
1336: and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes
1337: to be tieable.
1338:
1339: Many machines have special registers for floating point arithmetic.
1340: Often people assume that floating point machine modes are allowed only
1341: in floating point registers. This is not true. Any registers that
1342: can hold integers can safely @emph{hold} a floating point machine
1343: mode, whether or not floating arithmetic can be done on it in those
1344: registers. Integer move instructions can be used to move the values.
1345:
1346: On some machines, though, the converse is true: fixed-point machine
1347: modes may not go in floating registers. This is true if the floating
1348: registers normalize any value stored in them, because storing a
1349: non-floating value there would garble it. In this case,
1350: @code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in
1351: floating registers. But if the floating registers do not automatically
1352: normalize, if you can store any bit pattern in one and retrieve it
1353: unchanged without a trap, then any machine mode may go in a floating
1.1.1.3 root 1354: register, so you can define this macro to say so.
1355:
1.1 root 1356: The primary significance of special floating registers is rather that
1357: they are the registers acceptable in floating point arithmetic
1358: instructions. However, this is of no concern to
1359: @code{HARD_REGNO_MODE_OK}. You handle it by writing the proper
1360: constraints for those instructions.
1361:
1362: On some machines, the floating registers are especially slow to access,
1363: so that it is better to store a value in a stack frame than in such a
1364: register if floating point arithmetic is not being done. As long as the
1365: floating registers are not in class @code{GENERAL_REGS}, they will not
1366: be used unless some pattern's constraint asks for one.
1367:
1368: @findex MODES_TIEABLE_P
1369: @item MODES_TIEABLE_P (@var{mode1}, @var{mode2})
1370: A C expression that is nonzero if it is desirable to choose register
1371: allocation so as to avoid move instructions between a value of mode
1372: @var{mode1} and a value of mode @var{mode2}.
1373:
1374: If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
1375: @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are ever different
1376: for any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1},
1377: @var{mode2})} must be zero.
1378: @end table
1379:
1380: @node Leaf Functions
1381: @subsection Handling Leaf Functions
1382:
1383: @cindex leaf functions
1384: @cindex functions, leaf
1.1.1.4 root 1385: On some machines, a leaf function (i.e., one which makes no calls) can run
1.1 root 1386: more efficiently if it does not make its own register window. Often this
1387: means it is required to receive its arguments in the registers where they
1388: are passed by the caller, instead of the registers where they would
1.1.1.3 root 1389: normally arrive.
1390:
1391: The special treatment for leaf functions generally applies only when
1392: other conditions are met; for example, often they may use only those
1393: registers for its own variables and temporaries. We use the term ``leaf
1394: function'' to mean a function that is suitable for this special
1395: handling, so that functions with no calls are not necessarily ``leaf
1396: functions''.
1.1 root 1397:
1398: GNU CC assigns register numbers before it knows whether the function is
1399: suitable for leaf function treatment. So it needs to renumber the
1400: registers in order to output a leaf function. The following macros
1401: accomplish this.
1402:
1403: @table @code
1404: @findex LEAF_REGISTERS
1405: @item LEAF_REGISTERS
1406: A C initializer for a vector, indexed by hard register number, which
1407: contains 1 for a register that is allowable in a candidate for leaf
1408: function treatment.
1409:
1410: If leaf function treatment involves renumbering the registers, then the
1411: registers marked here should be the ones before renumbering---those that
1412: GNU CC would ordinarily allocate. The registers which will actually be
1413: used in the assembler code, after renumbering, should not be marked with 1
1414: in this vector.
1415:
1416: Define this macro only if the target machine offers a way to optimize
1417: the treatment of leaf functions.
1418:
1419: @findex LEAF_REG_REMAP
1420: @item LEAF_REG_REMAP (@var{regno})
1421: A C expression whose value is the register number to which @var{regno}
1422: should be renumbered, when a function is treated as a leaf function.
1423:
1424: If @var{regno} is a register number which should not appear in a leaf
1425: function before renumbering, then the expression should yield -1, which
1426: will cause the compiler to abort.
1427:
1428: Define this macro only if the target machine offers a way to optimize the
1429: treatment of leaf functions, and registers need to be renumbered to do
1430: this.
1431: @end table
1432:
1433: @findex leaf_function
1.1.1.5 root 1434: Normally, @code{FUNCTION_PROLOGUE} and @code{FUNCTION_EPILOGUE} must
1435: treat leaf functions specially. It can test the C variable
1436: @code{leaf_function} which is nonzero for leaf functions. (The variable
1437: @code{leaf_function} is defined only if @code{LEAF_REGISTERS} is
1438: defined.)
1439: @c changed this to fix overfull. ALSO: why the "it" at the beginning
1440: @c of the next paragraph?! --mew 2feb93
1.1 root 1441:
1442: @node Stack Registers
1443: @subsection Registers That Form a Stack
1444:
1445: There are special features to handle computers where some of the
1446: ``registers'' form a stack, as in the 80387 coprocessor for the 80386.
1447: Stack registers are normally written by pushing onto the stack, and are
1448: numbered relative to the top of the stack.
1449:
1450: Currently, GNU CC can only handle one group of stack-like registers, and
1451: they must be consecutively numbered.
1452:
1453: @table @code
1454: @findex STACK_REGS
1455: @item STACK_REGS
1456: Define this if the machine has any stack-like registers.
1457:
1458: @findex FIRST_STACK_REG
1459: @item FIRST_STACK_REG
1460: The number of the first stack-like register. This one is the top
1461: of the stack.
1462:
1463: @findex LAST_STACK_REG
1464: @item LAST_STACK_REG
1465: The number of the last stack-like register. This one is the bottom of
1466: the stack.
1467: @end table
1468:
1469: @node Obsolete Register Macros
1470: @subsection Obsolete Macros for Controlling Register Usage
1471:
1472: These features do not work very well. They exist because they used to
1473: be required to generate correct code for the 80387 coprocessor of the
1474: 80386. They are no longer used by that machine description and may be
1475: removed in a later version of the compiler. Don't use them!
1476:
1477: @table @code
1478: @findex OVERLAPPING_REGNO_P
1479: @item OVERLAPPING_REGNO_P (@var{regno})
1480: If defined, this is a C expression whose value is nonzero if hard
1481: register number @var{regno} is an overlapping register. This means a
1482: hard register which overlaps a hard register with a different number.
1483: (Such overlap is undesirable, but occasionally it allows a machine to
1484: be supported which otherwise could not be.) This macro must return
1485: nonzero for @emph{all} the registers which overlap each other. GNU CC
1486: can use an overlapping register only in certain limited ways. It can
1487: be used for allocation within a basic block, and may be spilled for
1488: reloading; that is all.
1489:
1490: If this macro is not defined, it means that none of the hard registers
1491: overlap each other. This is the usual situation.
1492:
1493: @findex INSN_CLOBBERS_REGNO_P
1494: @item INSN_CLOBBERS_REGNO_P (@var{insn}, @var{regno})
1495: If defined, this is a C expression whose value should be nonzero if
1496: the insn @var{insn} has the effect of mysteriously clobbering the
1497: contents of hard register number @var{regno}. By ``mysterious'' we
1498: mean that the insn's RTL expression doesn't describe such an effect.
1499:
1500: If this macro is not defined, it means that no insn clobbers registers
1501: mysteriously. This is the usual situation; all else being equal,
1502: it is best for the RTL expression to show all the activity.
1503:
1504: @cindex death notes
1505: @findex PRESERVE_DEATH_INFO_REGNO_P
1506: @item PRESERVE_DEATH_INFO_REGNO_P (@var{regno})
1507: If defined, this is a C expression whose value is nonzero if accurate
1508: @code{REG_DEAD} notes are needed for hard register number @var{regno}
1509: at the time of outputting the assembler code. When this is so, a few
1510: optimizations that take place after register allocation and could
1511: invalidate the death notes are not done when this register is
1512: involved.
1513:
1514: You would arrange to preserve death info for a register when some of the
1515: code in the machine description which is executed to write the assembler
1516: code looks at the death notes. This is necessary only when the actual
1517: hardware feature which GNU CC thinks of as a register is not actually a
1518: register of the usual sort. (It might, for example, be a hardware
1519: stack.)
1520:
1521: If this macro is not defined, it means that no death notes need to be
1522: preserved. This is the usual situation.
1523: @end table
1524:
1.1.1.2 root 1525: @node Register Classes
1.1 root 1526: @section Register Classes
1527: @cindex register class definitions
1528: @cindex class definitions, register
1529:
1530: On many machines, the numbered registers are not all equivalent.
1531: For example, certain registers may not be allowed for indexed addressing;
1532: certain registers may not be allowed in some instructions. These machine
1533: restrictions are described to the compiler using @dfn{register classes}.
1534:
1535: You define a number of register classes, giving each one a name and saying
1536: which of the registers belong to it. Then you can specify register classes
1537: that are allowed as operands to particular instruction patterns.
1538:
1539: @findex ALL_REGS
1540: @findex NO_REGS
1541: In general, each register will belong to several classes. In fact, one
1542: class must be named @code{ALL_REGS} and contain all the registers. Another
1543: class must be named @code{NO_REGS} and contain no registers. Often the
1544: union of two classes will be another class; however, this is not required.
1545:
1546: @findex GENERAL_REGS
1547: One of the classes must be named @code{GENERAL_REGS}. There is nothing
1548: terribly special about the name, but the operand constraint letters
1549: @samp{r} and @samp{g} specify this class. If @code{GENERAL_REGS} is
1550: the same as @code{ALL_REGS}, just define it as a macro which expands
1551: to @code{ALL_REGS}.
1552:
1553: Order the classes so that if class @var{x} is contained in class @var{y}
1554: then @var{x} has a lower class number than @var{y}.
1555:
1556: The way classes other than @code{GENERAL_REGS} are specified in operand
1557: constraints is through machine-dependent operand constraint letters.
1558: You can define such letters to correspond to various classes, then use
1559: them in operand constraints.
1560:
1561: You should define a class for the union of two classes whenever some
1562: instruction allows both classes. For example, if an instruction allows
1563: either a floating point (coprocessor) register or a general register for a
1564: certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
1565: which includes both of them. Otherwise you will get suboptimal code.
1566:
1567: You must also specify certain redundant information about the register
1568: classes: for each class, which classes contain it and which ones are
1569: contained in it; for each pair of classes, the largest class contained
1570: in their union.
1571:
1572: When a value occupying several consecutive registers is expected in a
1573: certain class, all the registers used must belong to that class.
1574: Therefore, register classes cannot be used to enforce a requirement for
1575: a register pair to start with an even-numbered register. The way to
1576: specify this requirement is with @code{HARD_REGNO_MODE_OK}.
1577:
1578: Register classes used for input-operands of bitwise-and or shift
1579: instructions have a special requirement: each such class must have, for
1580: each fixed-point machine mode, a subclass whose registers can transfer that
1581: mode to or from memory. For example, on some machines, the operations for
1582: single-byte values (@code{QImode}) are limited to certain registers. When
1583: this is so, each register class that is used in a bitwise-and or shift
1584: instruction must have a subclass consisting of registers from which
1585: single-byte values can be loaded or stored. This is so that
1586: @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
1587:
1588: @table @code
1589: @findex enum reg_class
1590: @item enum reg_class
1591: An enumeral type that must be defined with all the register class names
1592: as enumeral values. @code{NO_REGS} must be first. @code{ALL_REGS}
1593: must be the last register class, followed by one more enumeral value,
1594: @code{LIM_REG_CLASSES}, which is not a register class but rather
1595: tells how many classes there are.
1596:
1597: Each register class has a number, which is the value of casting
1598: the class name to type @code{int}. The number serves as an index
1599: in many of the tables described below.
1600:
1601: @findex N_REG_CLASSES
1602: @item N_REG_CLASSES
1603: The number of distinct register classes, defined as follows:
1604:
1605: @example
1606: #define N_REG_CLASSES (int) LIM_REG_CLASSES
1607: @end example
1608:
1609: @findex REG_CLASS_NAMES
1610: @item REG_CLASS_NAMES
1611: An initializer containing the names of the register classes as C string
1612: constants. These names are used in writing some of the debugging dumps.
1613:
1614: @findex REG_CLASS_CONTENTS
1615: @item REG_CLASS_CONTENTS
1616: An initializer containing the contents of the register classes, as integers
1617: which are bit masks. The @var{n}th integer specifies the contents of class
1618: @var{n}. The way the integer @var{mask} is interpreted is that
1619: register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
1620:
1621: When the machine has more than 32 registers, an integer does not suffice.
1622: Then the integers are replaced by sub-initializers, braced groupings containing
1623: several integers. Each sub-initializer must be suitable as an initializer
1624: for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
1625:
1626: @findex REGNO_REG_CLASS
1627: @item REGNO_REG_CLASS (@var{regno})
1628: A C expression whose value is a register class containing hard register
1.1.1.4 root 1629: @var{regno}. In general there is more than one such class; choose a class
1.1 root 1630: which is @dfn{minimal}, meaning that no smaller class also contains the
1631: register.
1632:
1633: @findex BASE_REG_CLASS
1634: @item BASE_REG_CLASS
1635: A macro whose definition is the name of the class to which a valid
1636: base register must belong. A base register is one used in an address
1637: which is the register value plus a displacement.
1638:
1639: @findex INDEX_REG_CLASS
1640: @item INDEX_REG_CLASS
1641: A macro whose definition is the name of the class to which a valid
1642: index register must belong. An index register is one used in an
1643: address where its value is either multiplied by a scale factor or
1644: added to another register (as well as added to a displacement).
1645:
1646: @findex REG_CLASS_FROM_LETTER
1647: @item REG_CLASS_FROM_LETTER (@var{char})
1648: A C expression which defines the machine-dependent operand constraint
1649: letters for register classes. If @var{char} is such a letter, the
1650: value should be the register class corresponding to it. Otherwise,
1.1.1.2 root 1651: the value should be @code{NO_REGS}. The register letter @samp{r},
1652: corresponding to class @code{GENERAL_REGS}, will not be passed
1653: to this macro; you do not need to handle it.
1.1 root 1654:
1655: @findex REGNO_OK_FOR_BASE_P
1656: @item REGNO_OK_FOR_BASE_P (@var{num})
1657: A C expression which is nonzero if register number @var{num} is
1658: suitable for use as a base register in operand addresses. It may be
1659: either a suitable hard register or a pseudo register that has been
1660: allocated such a hard register.
1661:
1662: @findex REGNO_OK_FOR_INDEX_P
1663: @item REGNO_OK_FOR_INDEX_P (@var{num})
1664: A C expression which is nonzero if register number @var{num} is
1665: suitable for use as an index register in operand addresses. It may be
1666: either a suitable hard register or a pseudo register that has been
1667: allocated such a hard register.
1668:
1669: The difference between an index register and a base register is that
1670: the index register may be scaled. If an address involves the sum of
1671: two registers, neither one of them scaled, then either one may be
1672: labeled the ``base'' and the other the ``index''; but whichever
1673: labeling is used must fit the machine's constraints of which registers
1674: may serve in each capacity. The compiler will try both labelings,
1675: looking for one that is valid, and will reload one or both registers
1676: only if neither labeling works.
1677:
1678: @findex PREFERRED_RELOAD_CLASS
1679: @item PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
1680: A C expression that places additional restrictions on the register class
1681: to use when it is necessary to copy value @var{x} into a register in class
1682: @var{class}. The value is a register class; perhaps @var{class}, or perhaps
1.1.1.5 root 1683: another, smaller class. On many machines, the following definition is
1684: safe:
1.1 root 1685:
1686: @example
1687: #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
1688: @end example
1689:
1690: Sometimes returning a more restrictive class makes better code. For
1691: example, on the 68000, when @var{x} is an integer constant that is in range
1692: for a @samp{moveq} instruction, the value of this macro is always
1693: @code{DATA_REGS} as long as @var{class} includes the data registers.
1694: Requiring a data register guarantees that a @samp{moveq} will be used.
1695:
1696: If @var{x} is a @code{const_double}, by returning @code{NO_REGS}
1697: you can force @var{x} into a memory constant. This is useful on
1698: certain machines where immediate floating values cannot be loaded into
1699: certain kinds of registers.
1700:
1.1.1.4 root 1701: @findex PREFERRED_OUTPUT_RELOAD_CLASS
1702: @item PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class})
1703: Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of
1704: input reloads. If you don't define this macro, the default is to use
1705: @var{class}, unchanged.
1706:
1.1 root 1707: @findex LIMIT_RELOAD_CLASS
1708: @item LIMIT_RELOAD_CLASS (@var{mode}, @var{class})
1709: A C expression that places additional restrictions on the register class
1710: to use when it is necessary to be able to hold a value of mode
1711: @var{mode} in a reload register for which class @var{class} would
1712: ordinarily be used.
1713:
1714: Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when
1715: there are certain modes that simply can't go in certain reload classes.
1716:
1717: The value is a register class; perhaps @var{class}, or perhaps another,
1718: smaller class.
1719:
1720: Don't define this macro unless the target machine has limitations which
1721: require the macro to do something nontrivial.
1722:
1723: @findex SECONDARY_RELOAD_CLASS
1724: @findex SECONDARY_INPUT_RELOAD_CLASS
1725: @findex SECONDARY_OUTPUT_RELOAD_CLASS
1726: @item SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
1727: @itemx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
1728: @itemx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
1729: Many machines have some registers that cannot be copied directly to or
1730: from memory or even from other types of registers. An example is the
1731: @samp{MQ} register, which on most machines, can only be copied to or
1732: from general registers, but not memory. Some machines allow copying all
1733: registers to and from memory, but require a scratch register for stores
1734: to some memory locations (e.g., those with symbolic address on the RT,
1735: and those with certain symbolic address on the Sparc when compiling
1736: PIC). In some cases, both an intermediate and a scratch register are
1737: required.
1738:
1739: You should define these macros to indicate to the reload phase that it may
1740: need to allocate at least one register for a reload in addition to the
1741: register to contain the data. Specifically, if copying @var{x} to a
1742: register @var{class} in @var{mode} requires an intermediate register,
1743: you should define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the
1744: largest register class all of whose registers can be used as
1745: intermediate registers or scratch registers.
1746:
1747: If copying a register @var{class} in @var{mode} to @var{x} requires an
1.1.1.5 root 1748: intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS}
1749: should be defined to return the largest register class required. If the
1750: requirements for input and output reloads are the same, the macro
1751: @code{SECONDARY_RELOAD_CLASS} should be used instead of defining both
1752: macros identically.
1.1 root 1753:
1754: The values returned by these macros are often @code{GENERAL_REGS}.
1755: Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x}
1756: can be directly copied to or from a register of @var{class} in
1757: @var{mode} without requiring a scratch register. Do not define this
1758: macro if it would always return @code{NO_REGS}.
1759:
1760: If a scratch register is required (either with or without an
1761: intermediate register), you should define patterns for
1762: @samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required
1763: (@pxref{Standard Names}. These patterns, which will normally be
1764: implemented with a @code{define_expand}, should be similar to the
1765: @samp{mov@var{m}} patterns, except that operand 2 is the scratch
1766: register.
1767:
1768: Define constraints for the reload register and scratch register that
1769: contain a single register class. If the original reload register (whose
1770: class is @var{class}) can meet the constraint given in the pattern, the
1771: value returned by these macros is used for the class of the scratch
1772: register. Otherwise, two additional reload registers are required.
1773: Their classes are obtained from the constraints in the insn pattern.
1774:
1775: @var{x} might be a pseudo-register or a @code{subreg} of a
1776: pseudo-register, which could either be in a hard register or in memory.
1777: Use @code{true_regnum} to find out; it will return -1 if the pseudo is
1778: in memory and the hard register number if it is in a register.
1779:
1780: These macros should not be used in the case where a particular class of
1781: registers can only be copied to memory and not to another class of
1782: registers. In that case, secondary reload registers are not needed and
1783: would not be helpful. Instead, a stack location must be used to perform
1784: the copy and the @code{mov@var{m}} pattern should use memory as a
1785: intermediate storage. This case often occurs between floating-point and
1786: general registers.
1787:
1.1.1.4 root 1788: @findex SECONDARY_MEMORY_NEEDED
1789: @item SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m})
1790: Certain machines have the property that some registers cannot be copied
1791: to some other registers without using memory. Define this macro on
1792: those machines to be a C expression that is non-zero if objects of mode
1793: @var{m} in registers of @var{class1} can only be copied to registers of
1794: class @var{class2} by storing a register of @var{class1} into memory
1795: and loading that memory location into a register of @var{class2}.
1796:
1797: Do not define this macro if its value would always be zero.
1798:
1.1.1.5 root 1799: @findex SECONDARY_MEMORY_NEEDED_RTX
1800: @item SECONDARY_MEMORY_NEEDED_RTX (@var{mode})
1.1.1.7 root 1801: Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler
1802: allocates a stack slot for a memory location needed for register copies.
1803: If this macro is defined, the compiler instead uses the memory location
1804: defined by this macro.
1805:
1806: Do not define this macro if you do not define
1807: @code{SECONDARY_MEMORY_NEEDED}.
1808:
1809: @findex SECONDARY_MEMORY_NEEDED_MODE
1810: @item SECONDARY_MEMORY_NEEDED_MODE (@var{mode})
1811: When the compiler needs a secondary memory location to copy between two
1812: registers of mode @var{mode}, it normally allocates sufficient memory to
1813: hold a quantity of @code{BITS_PER_WORD} bits and performs the store and
1814: load operations in a mode that many bits wide and whose class is the
1815: same as that of @var{mode}.
1816:
1817: This is right thing to do on most machines because it ensures that all
1818: bits of the register are copied and prevents accesses to the registers
1819: in a narrower mode, which some machines prohibit for floating-point
1820: registers.
1821:
1822: However, this default behavior is not correct on some machines, such as
1823: the DEC Alpha, that store short integers in floating-point registers
1824: differently than in integer registers. On those machines, the default
1825: widening will not work correctly and you must define this macro to
1826: suppress that widening in some cases. See the file @file{alpha.h} for
1827: details.
1828:
1829: Do not define this macro if you do not define
1830: @code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that
1831: is @code{BITS_PER_WORD} bits wide is correct for your machine.
1.1.1.5 root 1832:
1.1 root 1833: @findex SMALL_REGISTER_CLASSES
1834: @item SMALL_REGISTER_CLASSES
1.1.1.7 root 1835: Normally the compiler avoids choosing registers that have been
1836: explicitly mentioned in the rtl as spill registers (these registers are
1.1 root 1837: normally those used to pass parameters and return values). However,
1.1.1.7 root 1838: some machines have so few registers of certain classes that there
1839: would not be enough registers to use as spill registers if this were
1840: done.
1841:
1842: Define @code{SMALL_REGISTER_CLASSES} on these machines. When it is
1843: defined, the compiler allows registers explicitly used in the rtl to be
1844: used as spill registers but avoids extending the lifetime of these
1845: registers.
1.1 root 1846:
1.1.1.7 root 1847: It is always safe to define this macro, but if you unnecessarily define
1848: it, you will reduce the amount of optimizations that can be performed in
1849: some cases. If you do not define this macro when it is required, the
1850: compiler will run out of spill registers and print a fatal error
1851: message. For most machines, you should not define this macro.
1.1 root 1852:
1.1.1.5 root 1853: @findex CLASS_LIKELY_SPILLED_P
1854: @item CLASS_LIKELY_SPILLED_P (@var{class})
1855: A C expression whose value is nonzero if pseudos that have been assigned
1856: to registers of class @var{class} would likely be spilled because
1857: registers of @var{class} are needed for spill registers.
1858:
1859: The default value of this macro returns 1 if @var{class} has exactly one
1860: register and zero otherwise. On most machines, this default should be
1861: used. Only define this macro to some other expression if pseudo
1862: allocated by @file{local-alloc.c} end up in memory because their hard
1.1.1.8 ! root 1863: registers were needed for spill registers. If this macro returns nonzero
1.1.1.5 root 1864: for those classes, those pseudos will only be allocated by
1865: @file{global.c}, which knows how to reallocate the pseudo to another
1866: register. If there would not be another register available for
1867: reallocation, you should not change the definition of this macro since
1868: the only effect of such a definition would be to slow down register
1869: allocation.
1870:
1.1 root 1871: @findex CLASS_MAX_NREGS
1872: @item CLASS_MAX_NREGS (@var{class}, @var{mode})
1873: A C expression for the maximum number of consecutive registers
1874: of class @var{class} needed to hold a value of mode @var{mode}.
1875:
1.1.1.7 root 1876: This is closely related to the macro @code{HARD_REGNO_NREGS}. In fact,
1877: the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
1878: should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno},
1879: @var{mode})} for all @var{regno} values in the class @var{class}.
1.1 root 1880:
1881: This macro helps control the handling of multiple-word values
1882: in the reload pass.
1.1.1.7 root 1883:
1884: @item CLASS_CANNOT_CHANGE_SIZE
1885: If defined, a C expression for a class that contains registers which the
1886: compiler must always access in a mode that is the same size as the mode
1.1.1.8 ! root 1887: in which it loaded the register.
1.1.1.7 root 1888:
1889: For the example, loading 32-bit integer or floating-point objects into
1890: floating-point registers on the Alpha extends them to 64-bits.
1891: Therefore loading a 64-bit object and then storing it as a 32-bit object
1892: does not store the low-order 32-bits, as would be the case for a normal
1893: register. Therefore, @file{alpha.h} defines this macro as
1894: @code{FLOAT_REGS}.
1.1 root 1895: @end table
1896:
1897: Three other special macros describe which operands fit which constraint
1898: letters.
1899:
1900: @table @code
1901: @findex CONST_OK_FOR_LETTER_P
1902: @item CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
1903: A C expression that defines the machine-dependent operand constraint letters
1904: that specify particular ranges of integer values. If @var{c} is one
1905: of those letters, the expression should check that @var{value}, an integer,
1906: is in the appropriate range and return 1 if so, 0 otherwise. If @var{c} is
1907: not one of those letters, the value should be 0 regardless of @var{value}.
1908:
1909: @findex CONST_DOUBLE_OK_FOR_LETTER_P
1910: @item CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
1911: A C expression that defines the machine-dependent operand constraint
1912: letters that specify particular ranges of @code{const_double} values.
1913:
1914: If @var{c} is one of those letters, the expression should check that
1915: @var{value}, an RTX of code @code{const_double}, is in the appropriate
1916: range and return 1 if so, 0 otherwise. If @var{c} is not one of those
1917: letters, the value should be 0 regardless of @var{value}.
1918:
1919: @code{const_double} is used for all floating-point constants and for
1920: @code{DImode} fixed-point constants. A given letter can accept either
1921: or both kinds of values. It can use @code{GET_MODE} to distinguish
1922: between these kinds.
1923:
1924: @findex EXTRA_CONSTRAINT
1925: @item EXTRA_CONSTRAINT (@var{value}, @var{c})
1926: A C expression that defines the optional machine-dependent constraint
1927: letters that can be used to segregate specific types of operands,
1928: usually memory references, for the target machine. Normally this macro
1929: will not be defined. If it is required for a particular target machine,
1930: it should return 1 if @var{value} corresponds to the operand type
1931: represented by the constraint letter @var{c}. If @var{c} is not defined
1932: as an extra constraint, the value returned should be 0 regardless of
1933: @var{value}.
1934:
1935: For example, on the ROMP, load instructions cannot have their output in r0 if
1936: the memory reference contains a symbolic address. Constraint letter
1937: @samp{Q} is defined as representing a memory address that does
1938: @emph{not} contain a symbolic address. An alternative is specified with
1939: a @samp{Q} constraint on the input and @samp{r} on the output. The next
1940: alternative specifies @samp{m} on the input and a register class that
1941: does not include r0 on the output.
1942: @end table
1943:
1.1.1.2 root 1944: @node Stack and Calling
1.1.1.5 root 1945: @section Stack Layout and Calling Conventions
1.1 root 1946: @cindex calling conventions
1947:
1.1.1.7 root 1948: @c prevent bad page break with this line
1949: This describes the stack layout and calling conventions.
1950:
1.1 root 1951: @menu
1952: * Frame Layout::
1953: * Frame Registers::
1954: * Elimination::
1955: * Stack Arguments::
1956: * Register Arguments::
1957: * Scalar Return::
1958: * Aggregate Return::
1959: * Caller Saves::
1960: * Function Entry::
1961: * Profiling::
1962: @end menu
1963:
1964: @node Frame Layout
1965: @subsection Basic Stack Layout
1966: @cindex stack frame layout
1967: @cindex frame layout
1968:
1.1.1.7 root 1969: @c prevent bad page break with this line
1970: Here is the basic stack layout.
1971:
1.1 root 1972: @table @code
1973: @findex STACK_GROWS_DOWNWARD
1974: @item STACK_GROWS_DOWNWARD
1975: Define this macro if pushing a word onto the stack moves the stack
1976: pointer to a smaller address.
1977:
1978: When we say, ``define this macro if @dots{},'' it means that the
1979: compiler checks this macro only with @code{#ifdef} so the precise
1980: definition used does not matter.
1981:
1982: @findex FRAME_GROWS_DOWNWARD
1983: @item FRAME_GROWS_DOWNWARD
1984: Define this macro if the addresses of local variable slots are at negative
1985: offsets from the frame pointer.
1986:
1987: @findex ARGS_GROW_DOWNWARD
1988: @item ARGS_GROW_DOWNWARD
1989: Define this macro if successive arguments to a function occupy decreasing
1990: addresses on the stack.
1991:
1992: @findex STARTING_FRAME_OFFSET
1993: @item STARTING_FRAME_OFFSET
1994: Offset from the frame pointer to the first local variable slot to be allocated.
1995:
1.1.1.5 root 1996: If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by
1997: subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}.
1998: Otherwise, it is found by adding the length of the first slot to the
1999: value @code{STARTING_FRAME_OFFSET}.
2000: @c i'm not sure if the above is still correct.. had to change it to get
2001: @c rid of an overfull. --mew 2feb93
1.1 root 2002:
2003: @findex STACK_POINTER_OFFSET
2004: @item STACK_POINTER_OFFSET
2005: Offset from the stack pointer register to the first location at which
2006: outgoing arguments are placed. If not specified, the default value of
2007: zero is used. This is the proper value for most machines.
2008:
2009: If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
2010: the first location at which outgoing arguments are placed.
2011:
2012: @findex FIRST_PARM_OFFSET
2013: @item FIRST_PARM_OFFSET (@var{fundecl})
2014: Offset from the argument pointer register to the first argument's
2015: address. On some machines it may depend on the data type of the
2016: function.
2017:
2018: If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
2019: the first argument's address.
2020:
2021: @findex STACK_DYNAMIC_OFFSET
2022: @item STACK_DYNAMIC_OFFSET (@var{fundecl})
2023: Offset from the stack pointer register to an item dynamically allocated
2024: on the stack, e.g., by @code{alloca}.
2025:
2026: The default value for this macro is @code{STACK_POINTER_OFFSET} plus the
2027: length of the outgoing arguments. The default is correct for most
2028: machines. See @file{function.c} for details.
2029:
2030: @findex DYNAMIC_CHAIN_ADDRESS
2031: @item DYNAMIC_CHAIN_ADDRESS (@var{frameaddr})
2032: A C expression whose value is RTL representing the address in a stack
2033: frame where the pointer to the caller's frame is stored. Assume that
2034: @var{frameaddr} is an RTL expression for the address of the stack frame
2035: itself.
2036:
2037: If you don't define this macro, the default is to return the value
2038: of @var{frameaddr}---that is, the stack frame address is also the
2039: address of the stack word that points to the previous frame.
1.1.1.5 root 2040:
2041: @findex SETUP_FRAME_ADDRESSES
1.1.1.8 ! root 2042: @item SETUP_FRAME_ADDRESSES ()
1.1.1.5 root 2043: If defined, a C expression that produces the machine-specific code to
2044: setup the stack so that arbitrary frames can be accessed. For example,
2045: on the Sparc, we must flush all of the register windows to the stack
2046: before we can access arbitrary stack frames.
2047: This macro will seldom need to be defined.
2048:
2049: @findex RETURN_ADDR_RTX
2050: @item RETURN_ADDR_RTX (@var{count}, @var{frameaddr})
2051: A C expression whose value is RTL representing the value of the return
2052: address for the frame @var{count} steps up from the current frame.
2053: @var{frameaddr} is the frame pointer of the @var{count} frame, or
2054: the frame pointer of the @var{count} @minus{} 1 frame if
2055: @code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined.
2056:
2057: @findex RETURN_ADDR_IN_PREVIOUS_FRAME
2058: @item RETURN_ADDR_IN_PREVIOUS_FRAME
2059: Define this if the return address of a particular stack frame is accessed
2060: from the frame pointer of the previous stack frame.
1.1 root 2061: @end table
2062:
1.1.1.6 root 2063: @need 2000
1.1 root 2064: @node Frame Registers
2065: @subsection Registers That Address the Stack Frame
2066:
1.1.1.7 root 2067: @c prevent bad page break with this line
2068: This discusses registers that address the stack frame.
2069:
1.1 root 2070: @table @code
2071: @findex STACK_POINTER_REGNUM
2072: @item STACK_POINTER_REGNUM
2073: The register number of the stack pointer register, which must also be a
2074: fixed register according to @code{FIXED_REGISTERS}. On most machines,
2075: the hardware determines which register this is.
2076:
2077: @findex FRAME_POINTER_REGNUM
2078: @item FRAME_POINTER_REGNUM
2079: The register number of the frame pointer register, which is used to
2080: access automatic variables in the stack frame. On some machines, the
2081: hardware determines which register this is. On other machines, you can
2082: choose any register you wish for this purpose.
2083:
1.1.1.6 root 2084: @findex HARD_FRAME_POINTER_REGNUM
2085: @item HARD_FRAME_POINTER_REGNUM
2086: On some machines the offset between the frame pointer and starting
2087: offset of the automatic variables is not known until after register
2088: allocation has been done (for example, because the saved registers are
1.1.1.7 root 2089: between these two locations). On those machines, define
2090: @code{FRAME_POINTER_REGNUM} the number of a special, fixed register to
2091: be used internally until the offset is known, and define
2092: @code{HARD_FRAME_POINTER_REGNUM} to be actual the hard register number
2093: used for the frame pointer.
1.1.1.6 root 2094:
2095: You should define this macro only in the very rare circumstances when it
2096: is not possible to calculate the offset between the frame pointer and
2097: the automatic variables until after register allocation has been
2098: completed. When this macro is defined, you must also indicate in your
2099: definition of @code{ELIMINABLE_REGS} how to eliminate
2100: @code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM}
2101: or @code{STACK_POINTER_REGNUM}.
2102:
2103: Do not define this macro if it would be the same as
2104: @code{FRAME_POINTER_REGNUM}.
2105:
1.1 root 2106: @findex ARG_POINTER_REGNUM
2107: @item ARG_POINTER_REGNUM
2108: The register number of the arg pointer register, which is used to access
2109: the function's argument list. On some machines, this is the same as the
2110: frame pointer register. On some machines, the hardware determines which
2111: register this is. On other machines, you can choose any register you
2112: wish for this purpose. If this is not the same register as the frame
2113: pointer register, then you must mark it as a fixed register according to
2114: @code{FIXED_REGISTERS}, or arrange to be able to eliminate it
2115: (@pxref{Elimination}).
2116:
2117: @findex STATIC_CHAIN_REGNUM
2118: @findex STATIC_CHAIN_INCOMING_REGNUM
2119: @item STATIC_CHAIN_REGNUM
2120: @itemx STATIC_CHAIN_INCOMING_REGNUM
1.1.1.5 root 2121: Register numbers used for passing a function's static chain pointer. If
2122: register windows are used, the register number as seen by the called
2123: function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register
2124: number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}. If
2125: these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need
2126: not be defined.@refill
1.1 root 2127:
2128: The static chain register need not be a fixed register.
2129:
2130: If the static chain is passed in memory, these macros should not be
2131: defined; instead, the next two macros should be defined.
2132:
2133: @findex STATIC_CHAIN
2134: @findex STATIC_CHAIN_INCOMING
2135: @item STATIC_CHAIN
2136: @itemx STATIC_CHAIN_INCOMING
2137: If the static chain is passed in memory, these macros provide rtx giving
2138: @code{mem} expressions that denote where they are stored.
2139: @code{STATIC_CHAIN} and @code{STATIC_CHAIN_INCOMING} give the locations
2140: as seen by the calling and called functions, respectively. Often the former
2141: will be at an offset from the stack pointer and the latter at an offset from
2142: the frame pointer.@refill
2143:
2144: @findex stack_pointer_rtx
2145: @findex frame_pointer_rtx
2146: @findex arg_pointer_rtx
2147: The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and
2148: @code{arg_pointer_rtx} will have been initialized prior to the use of these
2149: macros and should be used to refer to those items.
2150:
2151: If the static chain is passed in a register, the two previous macros should
2152: be defined instead.
2153: @end table
2154:
2155: @node Elimination
2156: @subsection Eliminating Frame Pointer and Arg Pointer
2157:
1.1.1.7 root 2158: @c prevent bad page break with this line
2159: This is about eliminating the frame pointer and arg pointer.
2160:
1.1 root 2161: @table @code
2162: @findex FRAME_POINTER_REQUIRED
2163: @item FRAME_POINTER_REQUIRED
2164: A C expression which is nonzero if a function must have and use a frame
2165: pointer. This expression is evaluated in the reload pass. If its value is
2166: nonzero the function will have a frame pointer.
2167:
2168: The expression can in principle examine the current function and decide
2169: according to the facts, but on most machines the constant 0 or the
2170: constant 1 suffices. Use 0 when the machine allows code to be generated
2171: with no frame pointer, and doing so saves some time or space. Use 1
2172: when there is no possible advantage to avoiding a frame pointer.
2173:
2174: In certain cases, the compiler does not know how to produce valid code
2175: without a frame pointer. The compiler recognizes those cases and
2176: automatically gives the function a frame pointer regardless of what
2177: @code{FRAME_POINTER_REQUIRED} says. You don't need to worry about
2178: them.@refill
2179:
2180: In a function that does not require a frame pointer, the frame pointer
2181: register can be allocated for ordinary usage, unless you mark it as a
2182: fixed register. See @code{FIXED_REGISTERS} for more information.
2183:
2184: @findex INITIAL_FRAME_POINTER_OFFSET
2185: @findex get_frame_size
2186: @item INITIAL_FRAME_POINTER_OFFSET (@var{depth-var})
2187: A C statement to store in the variable @var{depth-var} the difference
2188: between the frame pointer and the stack pointer values immediately after
2189: the function prologue. The value would be computed from information
2190: such as the result of @code{get_frame_size ()} and the tables of
2191: registers @code{regs_ever_live} and @code{call_used_regs}.
2192:
2193: If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and
2194: need not be defined. Otherwise, it must be defined even if
2195: @code{FRAME_POINTER_REQUIRED} is defined to always be true; in that
2196: case, you may set @var{depth-var} to anything.
2197:
2198: @findex ELIMINABLE_REGS
2199: @item ELIMINABLE_REGS
2200: If defined, this macro specifies a table of register pairs used to
2201: eliminate unneeded registers that point into the stack frame. If it is not
2202: defined, the only elimination attempted by the compiler is to replace
2203: references to the frame pointer with references to the stack pointer.
2204:
2205: The definition of this macro is a list of structure initializations, each
2206: of which specifies an original and replacement register.
2207:
2208: On some machines, the position of the argument pointer is not known until
2209: the compilation is completed. In such a case, a separate hard register
2210: must be used for the argument pointer. This register can be eliminated by
2211: replacing it with either the frame pointer or the argument pointer,
2212: depending on whether or not the frame pointer has been eliminated.
2213:
2214: In this case, you might specify:
2215: @example
2216: #define ELIMINABLE_REGS \
2217: @{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \
2218: @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \
2219: @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@}
2220: @end example
2221:
2222: Note that the elimination of the argument pointer with the stack pointer is
2223: specified first since that is the preferred elimination.
2224:
2225: @findex CAN_ELIMINATE
2226: @item CAN_ELIMINATE (@var{from-reg}, @var{to-reg})
2227: A C expression that returns non-zero if the compiler is allowed to try
2228: to replace register number @var{from-reg} with register number
2229: @var{to-reg}. This macro need only be defined if @code{ELIMINABLE_REGS}
2230: is defined, and will usually be the constant 1, since most of the cases
2231: preventing register elimination are things that the compiler already
2232: knows about.
2233:
2234: @findex INITIAL_ELIMINATION_OFFSET
2235: @item INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var})
2236: This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It
2237: specifies the initial difference between the specified pair of
2238: registers. This macro must be defined if @code{ELIMINABLE_REGS} is
2239: defined.
2240:
2241: @findex LONGJMP_RESTORE_FROM_STACK
2242: @item LONGJMP_RESTORE_FROM_STACK
2243: Define this macro if the @code{longjmp} function restores registers from
2244: the stack frames, rather than from those saved specifically by
2245: @code{setjmp}. Certain quantities must not be kept in registers across
2246: a call to @code{setjmp} on such machines.
2247: @end table
2248:
2249: @node Stack Arguments
2250: @subsection Passing Function Arguments on the Stack
2251: @cindex arguments on stack
2252: @cindex stack arguments
2253:
2254: The macros in this section control how arguments are passed
2255: on the stack. See the following section for other macros that
2256: control passing certain arguments in registers.
2257:
2258: @table @code
2259: @findex PROMOTE_PROTOTYPES
2260: @item PROMOTE_PROTOTYPES
1.1.1.6 root 2261: Define this macro if an argument declared in a prototype as an
2262: integral type smaller than @code{int} should actually be passed as an
1.1 root 2263: @code{int}. In addition to avoiding errors in certain cases of
2264: mismatch, it also makes for better code on certain machines.
2265:
2266: @findex PUSH_ROUNDING
2267: @item PUSH_ROUNDING (@var{npushed})
2268: A C expression that is the number of bytes actually pushed onto the
2269: stack when an instruction attempts to push @var{npushed} bytes.
2270:
2271: If the target machine does not have a push instruction, do not define
2272: this macro. That directs GNU CC to use an alternate strategy: to
2273: allocate the entire argument block and then store the arguments into
2274: it.
2275:
2276: On some machines, the definition
2277:
2278: @example
2279: #define PUSH_ROUNDING(BYTES) (BYTES)
2280: @end example
2281:
2282: @noindent
2283: will suffice. But on other machines, instructions that appear
2284: to push one byte actually push two bytes in an attempt to maintain
2285: alignment. Then the definition should be
2286:
2287: @example
2288: #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
2289: @end example
2290:
2291: @findex ACCUMULATE_OUTGOING_ARGS
2292: @findex current_function_outgoing_args_size
2293: @item ACCUMULATE_OUTGOING_ARGS
2294: If defined, the maximum amount of space required for outgoing arguments
2295: will be computed and placed into the variable
2296: @code{current_function_outgoing_args_size}. No space will be pushed
2297: onto the stack for each call; instead, the function prologue should
2298: increase the stack frame size by this amount.
2299:
1.1.1.5 root 2300: Defining both @code{PUSH_ROUNDING} and @code{ACCUMULATE_OUTGOING_ARGS}
2301: is not proper.
1.1 root 2302:
2303: @findex REG_PARM_STACK_SPACE
1.1.1.3 root 2304: @item REG_PARM_STACK_SPACE (@var{fndecl})
1.1 root 2305: Define this macro if functions should assume that stack space has been
2306: allocated for arguments even when their values are passed in
2307: registers.
2308:
2309: The value of this macro is the size, in bytes, of the area reserved for
1.1.1.4 root 2310: arguments passed in registers for the function represented by @var{fndecl}.
1.1 root 2311:
1.1.1.5 root 2312: This space can be allocated by the caller, or be a part of the
2313: machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says
2314: which.
2315: @c above is overfull. not sure what to do. --mew 5feb93 did
2316: @c something, not sure if it looks good. --mew 10feb93
1.1 root 2317:
1.1.1.3 root 2318: @findex MAYBE_REG_PARM_STACK_SPACE
2319: @findex FINAL_REG_PARM_STACK_SPACE
2320: @item MAYBE_REG_PARM_STACK_SPACE
1.1.1.5 root 2321: @itemx FINAL_REG_PARM_STACK_SPACE (@var{const_size}, @var{var_size})
1.1.1.3 root 2322: Define these macros in addition to the one above if functions might
2323: allocate stack space for arguments even when their values are passed
2324: in registers. These should be used when the stack space allocated
2325: for arguments in registers is not a simple constant independent of the
2326: function declaration.
2327:
2328: The value of the first macro is the size, in bytes, of the area that
2329: we should initially assume would be reserved for arguments passed in registers.
2330:
2331: The value of the second macro is the actual size, in bytes, of the area
2332: that will be reserved for arguments passed in registers. This takes two
2333: arguments: an integer representing the number of bytes of fixed sized
2334: arguments on the stack, and a tree representing the number of bytes of
2335: variable sized arguments on the stack.
2336:
2337: When these macros are defined, @code{REG_PARM_STACK_SPACE} will only be
2338: called for libcall functions, the current function, or for a function
2339: being called when it is known that such stack space must be allocated.
2340: In each case this value can be easily computed.
2341:
2342: When deciding whether a called function needs such stack space, and how
2343: much space to reserve, GNU CC uses these two macros instead of
2344: @code{REG_PARM_STACK_SPACE}.
2345:
1.1 root 2346: @findex OUTGOING_REG_PARM_STACK_SPACE
2347: @item OUTGOING_REG_PARM_STACK_SPACE
2348: Define this if it is the responsibility of the caller to allocate the area
2349: reserved for arguments passed in registers.
2350:
2351: If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls
2352: whether the space for these arguments counts in the value of
2353: @code{current_function_outgoing_args_size}.
2354:
2355: @findex STACK_PARMS_IN_REG_PARM_AREA
2356: @item STACK_PARMS_IN_REG_PARM_AREA
1.1.1.5 root 2357: Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the
2358: stack parameters don't skip the area specified by it.
2359: @c i changed this, makes more sens and it should have taken care of the
2360: @c overfull.. not as specific, tho. --mew 5feb93
1.1 root 2361:
2362: Normally, when a parameter is not passed in registers, it is placed on the
2363: stack beyond the @code{REG_PARM_STACK_SPACE} area. Defining this macro
2364: suppresses this behavior and causes the parameter to be passed on the
2365: stack in its natural location.
2366:
2367: @findex RETURN_POPS_ARGS
1.1.1.8 ! root 2368: @item RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size})
1.1 root 2369: A C expression that should indicate the number of bytes of its own
2370: arguments that a function pops on returning, or 0 if the
2371: function pops no arguments and the caller must therefore pop them all
2372: after the function returns.
2373:
1.1.1.8 ! root 2374: @var{fundecl} is a C variable whose value is a tree node that
! 2375: describes the function in question. Normally it is a node of type
! 2376: @code{FUNCTION_DECL} that describes the declaration of the function.
! 2377: From this it is possible to obtain the DECL_MACHINE_ATTRIBUTES of
! 2378: the function.
! 2379:
1.1 root 2380: @var{funtype} is a C variable whose value is a tree node that
2381: describes the function in question. Normally it is a node of type
2382: @code{FUNCTION_TYPE} that describes the data type of the function.
2383: From this it is possible to obtain the data types of the value and
2384: arguments (if known).
2385:
2386: When a call to a library function is being considered, @var{funtype}
2387: will contain an identifier node for the library function. Thus, if
2388: you need to distinguish among various library functions, you can do so
2389: by their names. Note that ``library function'' in this context means
2390: a function used to perform arithmetic, whose name is known specially
2391: in the compiler and was not mentioned in the C code being compiled.
2392:
2393: @var{stack-size} is the number of bytes of arguments passed on the
2394: stack. If a variable number of bytes is passed, it is zero, and
2395: argument popping will always be the responsibility of the calling function.
2396:
2397: On the Vax, all functions always pop their arguments, so the definition
2398: of this macro is @var{stack-size}. On the 68000, using the standard
2399: calling convention, no functions pop their arguments, so the value of
2400: the macro is always 0 in this case. But an alternative calling
2401: convention is available in which functions that take a fixed number of
2402: arguments pop them but other functions (such as @code{printf}) pop
2403: nothing (the caller pops all). When this convention is in use,
2404: @var{funtype} is examined to determine whether a function takes a fixed
2405: number of arguments.
2406: @end table
2407:
2408: @node Register Arguments
2409: @subsection Passing Arguments in Registers
2410: @cindex arguments in registers
2411: @cindex registers arguments
2412:
2413: This section describes the macros which let you control how various
2414: types of arguments are passed in registers or how they are arranged in
2415: the stack.
2416:
2417: @table @code
2418: @findex FUNCTION_ARG
2419: @item FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
2420: A C expression that controls whether a function argument is passed
2421: in a register, and which register.
2422:
2423: The arguments are @var{cum}, which summarizes all the previous
2424: arguments; @var{mode}, the machine mode of the argument; @var{type},
2425: the data type of the argument as a tree node or 0 if that is not known
2426: (which happens for C support library functions); and @var{named},
2427: which is 1 for an ordinary argument and 0 for nameless arguments that
2428: correspond to @samp{@dots{}} in the called function's prototype.
2429:
2430: The value of the expression should either be a @code{reg} RTX for the
2431: hard register in which to pass the argument, or zero to pass the
2432: argument on the stack.
2433:
2434: For machines like the Vax and 68000, where normally all arguments are
2435: pushed, zero suffices as a definition.
2436:
2437: @cindex @file{stdarg.h} and register arguments
2438: The usual way to make the ANSI library @file{stdarg.h} work on a machine
2439: where some arguments are usually passed in registers, is to cause
2440: nameless arguments to be passed on the stack instead. This is done
2441: by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0.
2442:
2443: @cindex @code{MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG}
2444: @cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG}
2445: You may use the macro @code{MUST_PASS_IN_STACK (@var{mode}, @var{type})}
2446: in the definition of this macro to determine if this argument is of a
2447: type that must be passed in the stack. If @code{REG_PARM_STACK_SPACE}
2448: is not defined and @code{FUNCTION_ARG} returns non-zero for such an
2449: argument, the compiler will abort. If @code{REG_PARM_STACK_SPACE} is
2450: defined, the argument will be computed in the stack and then loaded into
2451: a register.
2452:
2453: @findex FUNCTION_INCOMING_ARG
2454: @item FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
2455: Define this macro if the target machine has ``register windows'', so
2456: that the register in which a function sees an arguments is not
2457: necessarily the same as the one in which the caller passed the
2458: argument.
2459:
2460: For such machines, @code{FUNCTION_ARG} computes the register in which
2461: the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
2462: be defined in a similar fashion to tell the function being called
2463: where the arguments will arrive.
2464:
2465: If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
2466: serves both purposes.@refill
2467:
2468: @findex FUNCTION_ARG_PARTIAL_NREGS
2469: @item FUNCTION_ARG_PARTIAL_NREGS (@var{cum}, @var{mode}, @var{type}, @var{named})
2470: A C expression for the number of words, at the beginning of an
2471: argument, must be put in registers. The value must be zero for
2472: arguments that are passed entirely in registers or that are entirely
2473: pushed on the stack.
2474:
2475: On some machines, certain arguments must be passed partially in
2476: registers and partially in memory. On these machines, typically the
2477: first @var{n} words of arguments are passed in registers, and the rest
2478: on the stack. If a multi-word argument (a @code{double} or a
2479: structure) crosses that boundary, its first few words must be passed
2480: in registers and the rest must be pushed. This macro tells the
2481: compiler when this occurs, and how many of the words should go in
2482: registers.
2483:
2484: @code{FUNCTION_ARG} for these arguments should return the first
2485: register to be used by the caller for this argument; likewise
2486: @code{FUNCTION_INCOMING_ARG}, for the called function.
2487:
2488: @findex FUNCTION_ARG_PASS_BY_REFERENCE
2489: @item FUNCTION_ARG_PASS_BY_REFERENCE (@var{cum}, @var{mode}, @var{type}, @var{named})
2490: A C expression that indicates when an argument must be passed by reference.
2491: If nonzero for an argument, a copy of that argument is made in memory and a
2492: pointer to the argument is passed instead of the argument itself.
2493: The pointer is passed in whatever way is appropriate for passing a pointer
2494: to that type.
2495:
2496: On machines where @code{REG_PARM_STACK_SPACE} is not defined, a suitable
2497: definition of this macro might be
1.1.1.5 root 2498: @smallexample
2499: #define FUNCTION_ARG_PASS_BY_REFERENCE\
2500: (CUM, MODE, TYPE, NAMED) \
1.1 root 2501: MUST_PASS_IN_STACK (MODE, TYPE)
1.1.1.5 root 2502: @end smallexample
2503: @c this is *still* too long. --mew 5feb93
2504:
2505: @findex FUNCTION_ARG_CALLEE_COPIES
2506: @item FUNCTION_ARG_CALLEE_COPIES (@var{cum}, @var{mode}, @var{type}, @var{named})
2507: If defined, a C expression that indicates when it is the called function's
2508: responsibility to make a copy of arguments passed by invisible reference.
2509: Normally, the caller makes a copy and passes the address of the copy to the
2510: routine being called. When FUNCTION_ARG_CALLEE_COPIES is defined and is
2511: nonzero, the caller does not make a copy. Instead, it passes a pointer to the
2512: ``live'' value. The called function must not modify this value. If it can be
2513: determined that the value won't be modified, it need not make a copy;
2514: otherwise a copy must be made.
1.1 root 2515:
2516: @findex CUMULATIVE_ARGS
2517: @item CUMULATIVE_ARGS
2518: A C type for declaring a variable that is used as the first argument of
2519: @code{FUNCTION_ARG} and other related values. For some target machines,
2520: the type @code{int} suffices and can hold the number of bytes of
2521: argument so far.
2522:
2523: There is no need to record in @code{CUMULATIVE_ARGS} anything about the
2524: arguments that have been passed on the stack. The compiler has other
2525: variables to keep track of that. For target machines on which all
2526: arguments are passed on the stack, there is no need to store anything in
2527: @code{CUMULATIVE_ARGS}; however, the data structure must exist and
2528: should not be empty, so use @code{int}.
2529:
2530: @findex INIT_CUMULATIVE_ARGS
2531: @item INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname})
2532: A C statement (sans semicolon) for initializing the variable @var{cum}
2533: for the state at the beginning of the argument list. The variable has
2534: type @code{CUMULATIVE_ARGS}. The value of @var{fntype} is the tree node
2535: for the data type of the function which will receive the args, or 0
2536: if the args are to a compiler support library function.
2537:
2538: When processing a call to a compiler support library function,
2539: @var{libname} identifies which one. It is a @code{symbol_ref} rtx which
2540: contains the name of the function, as a string. @var{libname} is 0 when
2541: an ordinary C function call is being processed. Thus, each time this
2542: macro is called, either @var{libname} or @var{fntype} is nonzero, but
2543: never both of them at once.
2544:
2545: @findex INIT_CUMULATIVE_INCOMING_ARGS
2546: @item INIT_CUMULATIVE_INCOMING_ARGS (@var{cum}, @var{fntype}, @var{libname})
2547: Like @code{INIT_CUMULATIVE_ARGS} but overrides it for the purposes of
2548: finding the arguments for the function being compiled. If this macro is
2549: undefined, @code{INIT_CUMULATIVE_ARGS} is used instead.
2550:
1.1.1.5 root 2551: The value passed for @var{libname} is always 0, since library routines
2552: with special calling conventions are never compiled with GNU CC. The
2553: argument @var{libname} exists for symmetry with
2554: @code{INIT_CUMULATIVE_ARGS}.
2555: @c could use "this macro" in place of @code{INIT_CUMULATIVE_ARGS}, maybe.
2556: @c --mew 5feb93 i switched the order of the sentences. --mew 10feb93
1.1 root 2557:
2558: @findex FUNCTION_ARG_ADVANCE
2559: @item FUNCTION_ARG_ADVANCE (@var{cum}, @var{mode}, @var{type}, @var{named})
2560: A C statement (sans semicolon) to update the summarizer variable
2561: @var{cum} to advance past an argument in the argument list. The
2562: values @var{mode}, @var{type} and @var{named} describe that argument.
2563: Once this is done, the variable @var{cum} is suitable for analyzing
2564: the @emph{following} argument with @code{FUNCTION_ARG}, etc.@refill
2565:
2566: This macro need not do anything if the argument in question was passed
2567: on the stack. The compiler knows how to track the amount of stack space
2568: used for arguments without any special help.
2569:
2570: @findex FUNCTION_ARG_PADDING
2571: @item FUNCTION_ARG_PADDING (@var{mode}, @var{type})
2572: If defined, a C expression which determines whether, and in which direction,
2573: to pad out an argument with extra space. The value should be of type
2574: @code{enum direction}: either @code{upward} to pad above the argument,
2575: @code{downward} to pad below, or @code{none} to inhibit padding.
2576:
1.1.1.5 root 2577: The @emph{amount} of padding is always just enough to reach the next
2578: multiple of @code{FUNCTION_ARG_BOUNDARY}; this macro does not control
2579: it.
1.1 root 2580:
2581: This macro has a default definition which is right for most systems.
2582: For little-endian machines, the default is to pad upward. For
2583: big-endian machines, the default is to pad downward for an argument of
2584: constant size shorter than an @code{int}, and upward otherwise.
2585:
2586: @findex FUNCTION_ARG_BOUNDARY
2587: @item FUNCTION_ARG_BOUNDARY (@var{mode}, @var{type})
2588: If defined, a C expression that gives the alignment boundary, in bits,
2589: of an argument with the specified mode and type. If it is not defined,
2590: @code{PARM_BOUNDARY} is used for all arguments.
2591:
2592: @findex FUNCTION_ARG_REGNO_P
2593: @item FUNCTION_ARG_REGNO_P (@var{regno})
2594: A C expression that is nonzero if @var{regno} is the number of a hard
2595: register in which function arguments are sometimes passed. This does
2596: @emph{not} include implicit arguments such as the static chain and
2597: the structure-value address. On many machines, no registers can be
2598: used for this purpose since all function arguments are pushed on the
2599: stack.
2600: @end table
2601:
2602: @node Scalar Return
2603: @subsection How Scalar Function Values Are Returned
2604: @cindex return values in registers
2605: @cindex values, returned by functions
2606: @cindex scalars, returned as values
2607:
2608: This section discusses the macros that control returning scalars as
2609: values---values that can fit in registers.
2610:
2611: @table @code
2612: @findex TRADITIONAL_RETURN_FLOAT
2613: @item TRADITIONAL_RETURN_FLOAT
2614: Define this macro if @samp{-traditional} should not cause functions
2615: declared to return @code{float} to convert the value to @code{double}.
2616:
2617: @findex FUNCTION_VALUE
2618: @item FUNCTION_VALUE (@var{valtype}, @var{func})
2619: A C expression to create an RTX representing the place where a
2620: function returns a value of data type @var{valtype}. @var{valtype} is
2621: a tree node representing a data type. Write @code{TYPE_MODE
2622: (@var{valtype})} to get the machine mode used to represent that type.
2623: On many machines, only the mode is relevant. (Actually, on most
2624: machines, scalar values are returned in the same place regardless of
2625: mode).@refill
2626:
1.1.1.4 root 2627: If @code{PROMOTE_FUNCTION_RETURN} is defined, you must apply the same
2628: promotion rules specified in @code{PROMOTE_MODE} if @var{valtype} is a
2629: scalar type.
2630:
1.1 root 2631: If the precise function being called is known, @var{func} is a tree
2632: node (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
2633: pointer. This makes it possible to use a different value-returning
2634: convention for specific functions when all their calls are
2635: known.@refill
2636:
2637: @code{FUNCTION_VALUE} is not used for return vales with aggregate data
2638: types, because these are returned in another way. See
2639: @code{STRUCT_VALUE_REGNUM} and related macros, below.
2640:
2641: @findex FUNCTION_OUTGOING_VALUE
2642: @item FUNCTION_OUTGOING_VALUE (@var{valtype}, @var{func})
2643: Define this macro if the target machine has ``register windows''
2644: so that the register in which a function returns its value is not
2645: the same as the one in which the caller sees the value.
2646:
1.1.1.5 root 2647: For such machines, @code{FUNCTION_VALUE} computes the register in which
2648: the caller will see the value. @code{FUNCTION_OUTGOING_VALUE} should be
2649: defined in a similar fashion to tell the function where to put the
2650: value.@refill
1.1 root 2651:
2652: If @code{FUNCTION_OUTGOING_VALUE} is not defined,
2653: @code{FUNCTION_VALUE} serves both purposes.@refill
2654:
2655: @code{FUNCTION_OUTGOING_VALUE} is not used for return vales with
2656: aggregate data types, because these are returned in another way. See
2657: @code{STRUCT_VALUE_REGNUM} and related macros, below.
2658:
2659: @findex LIBCALL_VALUE
2660: @item LIBCALL_VALUE (@var{mode})
2661: A C expression to create an RTX representing the place where a library
2662: function returns a value of mode @var{mode}. If the precise function
2663: being called is known, @var{func} is a tree node
2664: (@code{FUNCTION_DECL}) for it; otherwise, @var{func} is a null
2665: pointer. This makes it possible to use a different value-returning
2666: convention for specific functions when all their calls are
2667: known.@refill
2668:
2669: Note that ``library function'' in this context means a compiler
2670: support routine, used to perform arithmetic, whose name is known
2671: specially by the compiler and was not mentioned in the C code being
2672: compiled.
2673:
2674: The definition of @code{LIBRARY_VALUE} need not be concerned aggregate
2675: data types, because none of the library functions returns such types.
2676:
2677: @findex FUNCTION_VALUE_REGNO_P
2678: @item FUNCTION_VALUE_REGNO_P (@var{regno})
2679: A C expression that is nonzero if @var{regno} is the number of a hard
2680: register in which the values of called function may come back.
2681:
2682: A register whose use for returning values is limited to serving as the
2683: second of a pair (for a value of type @code{double}, say) need not be
2684: recognized by this macro. So for most machines, this definition
2685: suffices:
2686:
2687: @example
2688: #define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
2689: @end example
2690:
2691: If the machine has register windows, so that the caller and the called
2692: function use different registers for the return value, this macro
2693: should recognize only the caller's register numbers.
1.1.1.5 root 2694:
2695: @findex APPLY_RESULT_SIZE
2696: @item APPLY_RESULT_SIZE
2697: Define this macro if @samp{untyped_call} and @samp{untyped_return}
2698: need more space than is implied by @code{FUNCTION_VALUE_REGNO_P} for
2699: saving and restoring an arbitrary return value.
1.1 root 2700: @end table
2701:
2702: @node Aggregate Return
1.1.1.2 root 2703: @subsection How Large Values Are Returned
1.1 root 2704: @cindex aggregates as return values
2705: @cindex large return values
2706: @cindex returning aggregate values
2707: @cindex structure value address
2708:
2709: When a function value's mode is @code{BLKmode} (and in some other
2710: cases), the value is not returned according to @code{FUNCTION_VALUE}
2711: (@pxref{Scalar Return}). Instead, the caller passes the address of a
2712: block of memory in which the value should be stored. This address
2713: is called the @dfn{structure value address}.
2714:
2715: This section describes how to control returning structure values in
2716: memory.
2717:
2718: @table @code
2719: @findex RETURN_IN_MEMORY
2720: @item RETURN_IN_MEMORY (@var{type})
2721: A C expression which can inhibit the returning of certain function
2722: values in registers, based on the type of value. A nonzero value says
2723: to return the function value in memory, just as large structures are
2724: always returned. Here @var{type} will be a C expression of type
2725: @code{tree}, representing the data type of the value.
2726:
1.1.1.5 root 2727: Note that values of mode @code{BLKmode} must be explicitly handled
2728: by this macro. Also, the option @samp{-fpcc-struct-return}
1.1 root 2729: takes effect regardless of this macro. On most systems, it is
2730: possible to leave the macro undefined; this causes a default
1.1.1.5 root 2731: definition to be used, whose value is the constant 1 for @code{BLKmode}
2732: values, and 0 otherwise.
2733:
2734: Do not use this macro to indicate that structures and unions should always
2735: be returned in memory. You should instead use @code{DEFAULT_PCC_STRUCT_RETURN}
2736: to indicate this.
2737:
2738: @findex DEFAULT_PCC_STRUCT_RETURN
2739: @item DEFAULT_PCC_STRUCT_RETURN
2740: Define this macro to be 1 if all structure and union return values must be
2741: in memory. Since this results in slower code, this should be defined
2742: only if needed for compatibility with other compilers or with an ABI.
2743: If you define this macro to be 0, then the conventions used for structure
2744: and union return values are decided by the @code{RETURN_IN_MEMORY} macro.
2745:
2746: If not defined, this defaults to the value 1.
1.1 root 2747:
2748: @findex STRUCT_VALUE_REGNUM
2749: @item STRUCT_VALUE_REGNUM
2750: If the structure value address is passed in a register, then
2751: @code{STRUCT_VALUE_REGNUM} should be the number of that register.
2752:
2753: @findex STRUCT_VALUE
2754: @item STRUCT_VALUE
2755: If the structure value address is not passed in a register, define
2756: @code{STRUCT_VALUE} as an expression returning an RTX for the place
2757: where the address is passed. If it returns 0, the address is passed as
2758: an ``invisible'' first argument.
2759:
2760: @findex STRUCT_VALUE_INCOMING_REGNUM
2761: @item STRUCT_VALUE_INCOMING_REGNUM
2762: On some architectures the place where the structure value address
2763: is found by the called function is not the same place that the
2764: caller put it. This can be due to register windows, or it could
2765: be because the function prologue moves it to a different place.
2766:
2767: If the incoming location of the structure value address is in a
2768: register, define this macro as the register number.
2769:
2770: @findex STRUCT_VALUE_INCOMING
2771: @item STRUCT_VALUE_INCOMING
1.1.1.5 root 2772: If the incoming location is not a register, then you should define
1.1 root 2773: @code{STRUCT_VALUE_INCOMING} as an expression for an RTX for where the
2774: called function should find the value. If it should find the value on
2775: the stack, define this to create a @code{mem} which refers to the frame
2776: pointer. A definition of 0 means that the address is passed as an
2777: ``invisible'' first argument.
2778:
2779: @findex PCC_STATIC_STRUCT_RETURN
2780: @item PCC_STATIC_STRUCT_RETURN
2781: Define this macro if the usual system convention on the target machine
2782: for returning structures and unions is for the called function to return
1.1.1.6 root 2783: the address of a static variable containing the value.
1.1 root 2784:
2785: Do not define this if the usual system convention is for the caller to
2786: pass an address to the subroutine.
1.1.1.6 root 2787:
2788: This macro has effect in @samp{-fpcc-struct-return} mode, but it does
2789: nothing when you use @samp{-freg-struct-return} mode.
1.1 root 2790: @end table
2791:
2792: @node Caller Saves
2793: @subsection Caller-Saves Register Allocation
2794:
2795: If you enable it, GNU CC can save registers around function calls. This
2796: makes it possible to use call-clobbered registers to hold variables that
2797: must live across calls.
2798:
2799: @table @code
2800: @findex DEFAULT_CALLER_SAVES
2801: @item DEFAULT_CALLER_SAVES
2802: Define this macro if function calls on the target machine do not preserve
2803: any registers; in other words, if @code{CALL_USED_REGISTERS} has 1
2804: for all registers. This macro enables @samp{-fcaller-saves} by default.
2805: Eventually that option will be enabled by default on all machines and both
2806: the option and this macro will be eliminated.
2807:
2808: @findex CALLER_SAVE_PROFITABLE
2809: @item CALLER_SAVE_PROFITABLE (@var{refs}, @var{calls})
2810: A C expression to determine whether it is worthwhile to consider placing
2811: a pseudo-register in a call-clobbered hard register and saving and
2812: restoring it around each function call. The expression should be 1 when
2813: this is worth doing, and 0 otherwise.
2814:
2815: If you don't define this macro, a default is used which is good on most
2816: machines: @code{4 * @var{calls} < @var{refs}}.
2817: @end table
2818:
2819: @node Function Entry
2820: @subsection Function Entry and Exit
2821: @cindex function entry and exit
2822: @cindex prologue
2823: @cindex epilogue
2824:
2825: This section describes the macros that output function entry
2826: (@dfn{prologue}) and exit (@dfn{epilogue}) code.
2827:
2828: @table @code
2829: @findex FUNCTION_PROLOGUE
2830: @item FUNCTION_PROLOGUE (@var{file}, @var{size})
2831: A C compound statement that outputs the assembler code for entry to a
2832: function. The prologue is responsible for setting up the stack frame,
2833: initializing the frame pointer register, saving registers that must be
2834: saved, and allocating @var{size} additional bytes of storage for the
2835: local variables. @var{size} is an integer. @var{file} is a stdio
2836: stream to which the assembler code should be output.
2837:
2838: The label for the beginning of the function need not be output by this
2839: macro. That has already been done when the macro is run.
2840:
2841: @findex regs_ever_live
2842: To determine which registers to save, the macro can refer to the array
2843: @code{regs_ever_live}: element @var{r} is nonzero if hard register
2844: @var{r} is used anywhere within the function. This implies the function
2845: prologue should save register @var{r}, provided it is not one of the
2846: call-used registers. (@code{FUNCTION_EPILOGUE} must likewise use
2847: @code{regs_ever_live}.)
2848:
2849: On machines that have ``register windows'', the function entry code does
2850: not save on the stack the registers that are in the windows, even if
2851: they are supposed to be preserved by function calls; instead it takes
2852: appropriate steps to ``push'' the register stack, if any non-call-used
2853: registers are used in the function.
2854:
2855: @findex frame_pointer_needed
2856: On machines where functions may or may not have frame-pointers, the
2857: function entry code must vary accordingly; it must set up the frame
2858: pointer if one is wanted, and not otherwise. To determine whether a
2859: frame pointer is in wanted, the macro can refer to the variable
2860: @code{frame_pointer_needed}. The variable's value will be 1 at run
2861: time in a function that needs a frame pointer. @xref{Elimination}.
2862:
2863: The function entry code is responsible for allocating any stack space
2864: required for the function. This stack space consists of the regions
2865: listed below. In most cases, these regions are allocated in the
2866: order listed, with the last listed region closest to the top of the
2867: stack (the lowest address if @code{STACK_GROWS_DOWNWARD} is defined, and
2868: the highest address if it is not defined). You can use a different order
2869: for a machine if doing so is more convenient or required for
2870: compatibility reasons. Except in cases where required by standard
2871: or by a debugger, there is no reason why the stack layout used by GCC
2872: need agree with that used by other compilers for a machine.
2873:
2874: @itemize @bullet
2875: @item
2876: @findex current_function_pretend_args_size
2877: A region of @code{current_function_pretend_args_size} bytes of
2878: uninitialized space just underneath the first argument arriving on the
2879: stack. (This may not be at the very start of the allocated stack region
2880: if the calling sequence has pushed anything else since pushing the stack
2881: arguments. But usually, on such machines, nothing else has been pushed
2882: yet, because the function prologue itself does all the pushing.) This
2883: region is used on machines where an argument may be passed partly in
2884: registers and partly in memory, and, in some cases to support the
2885: features in @file{varargs.h} and @file{stdargs.h}.
2886:
2887: @item
2888: An area of memory used to save certain registers used by the function.
2889: The size of this area, which may also include space for such things as
2890: the return address and pointers to previous stack frames, is
2891: machine-specific and usually depends on which registers have been used
2892: in the function. Machines with register windows often do not require
2893: a save area.
2894:
2895: @item
2896: A region of at least @var{size} bytes, possibly rounded up to an allocation
2897: boundary, to contain the local variables of the function. On some machines,
2898: this region and the save area may occur in the opposite order, with the
2899: save area closer to the top of the stack.
2900:
2901: @item
2902: @cindex @code{ACCUMULATE_OUTGOING_ARGS} and stack frames
1.1.1.5 root 2903: Optionally, when @code{ACCUMULATE_OUTGOING_ARGS} is defined, a region of
2904: @code{current_function_outgoing_args_size} bytes to be used for outgoing
2905: argument lists of the function. @xref{Stack Arguments}.
1.1 root 2906: @end itemize
2907:
1.1.1.5 root 2908: Normally, it is necessary for the macros @code{FUNCTION_PROLOGUE} and
1.1 root 2909: @code{FUNCTION_EPILOGUE} to treat leaf functions specially. The C
2910: variable @code{leaf_function} is nonzero for such a function.
2911:
2912: @findex EXIT_IGNORE_STACK
2913: @item EXIT_IGNORE_STACK
2914: Define this macro as a C expression that is nonzero if the return
2915: instruction or the function epilogue ignores the value of the stack
2916: pointer; in other words, if it is safe to delete an instruction to
2917: adjust the stack pointer before a return from the function.
2918:
2919: Note that this macro's value is relevant only for functions for which
2920: frame pointers are maintained. It is never safe to delete a final
2921: stack adjustment in a function that has no frame pointer, and the
2922: compiler knows this regardless of @code{EXIT_IGNORE_STACK}.
2923:
2924: @findex FUNCTION_EPILOGUE
2925: @item FUNCTION_EPILOGUE (@var{file}, @var{size})
2926: A C compound statement that outputs the assembler code for exit from a
2927: function. The epilogue is responsible for restoring the saved
2928: registers and stack pointer to their values when the function was
2929: called, and returning control to the caller. This macro takes the
2930: same arguments as the macro @code{FUNCTION_PROLOGUE}, and the
2931: registers to restore are determined from @code{regs_ever_live} and
2932: @code{CALL_USED_REGISTERS} in the same way.
2933:
2934: On some machines, there is a single instruction that does all the work
2935: of returning from the function. On these machines, give that
2936: instruction the name @samp{return} and do not define the macro
2937: @code{FUNCTION_EPILOGUE} at all.
2938:
2939: Do not define a pattern named @samp{return} if you want the
2940: @code{FUNCTION_EPILOGUE} to be used. If you want the target switches
2941: to control whether return instructions or epilogues are used, define a
2942: @samp{return} pattern with a validity condition that tests the target
2943: switches appropriately. If the @samp{return} pattern's validity
2944: condition is false, epilogues will be used.
2945:
2946: On machines where functions may or may not have frame-pointers, the
1.1.1.4 root 2947: function exit code must vary accordingly. Sometimes the code for these
2948: two cases is completely different. To determine whether a frame pointer
2949: is wanted, the macro can refer to the variable
1.1.1.6 root 2950: @code{frame_pointer_needed}. The variable's value will be 1 when compiling
2951: a function that needs a frame pointer.
1.1 root 2952:
1.1.1.5 root 2953: Normally, @code{FUNCTION_PROLOGUE} and @code{FUNCTION_EPILOGUE} must
2954: treat leaf functions specially. The C variable @code{leaf_function} is
2955: nonzero for such a function. @xref{Leaf Functions}.
1.1 root 2956:
2957: On some machines, some functions pop their arguments on exit while
2958: others leave that for the caller to do. For example, the 68020 when
2959: given @samp{-mrtd} pops arguments in functions that take a fixed
2960: number of arguments.
2961:
2962: @findex current_function_pops_args
2963: Your definition of the macro @code{RETURN_POPS_ARGS} decides which
2964: functions pop their own arguments. @code{FUNCTION_EPILOGUE} needs to
1.1.1.5 root 2965: know what was decided. The variable that is called
2966: @code{current_function_pops_args} is the number of bytes of its
2967: arguments that a function should pop. @xref{Scalar Return}.
2968: @c what is the "its arguments" in the above sentence referring to, pray
2969: @c tell? --mew 5feb93
1.1 root 2970:
2971: @findex DELAY_SLOTS_FOR_EPILOGUE
2972: @item DELAY_SLOTS_FOR_EPILOGUE
2973: Define this macro if the function epilogue contains delay slots to which
2974: instructions from the rest of the function can be ``moved''. The
2975: definition should be a C expression whose value is an integer
2976: representing the number of delay slots there.
2977:
2978: @findex ELIGIBLE_FOR_EPILOGUE_DELAY
2979: @item ELIGIBLE_FOR_EPILOGUE_DELAY (@var{insn}, @var{n})
2980: A C expression that returns 1 if @var{insn} can be placed in delay
2981: slot number @var{n} of the epilogue.
2982:
2983: The argument @var{n} is an integer which identifies the delay slot now
2984: being considered (since different slots may have different rules of
2985: eligibility). It is never negative and is always less than the number
2986: of epilogue delay slots (what @code{DELAY_SLOTS_FOR_EPILOGUE} returns).
2987: If you reject a particular insn for a given delay slot, in principle, it
2988: may be reconsidered for a subsequent delay slot. Also, other insns may
2989: (at least in principle) be considered for the so far unfilled delay
2990: slot.
2991:
2992: @findex current_function_epilogue_delay_list
2993: @findex final_scan_insn
2994: The insns accepted to fill the epilogue delay slots are put in an RTL
2995: list made with @code{insn_list} objects, stored in the variable
2996: @code{current_function_epilogue_delay_list}. The insn for the first
2997: delay slot comes first in the list. Your definition of the macro
2998: @code{FUNCTION_EPILOGUE} should fill the delay slots by outputting the
2999: insns in this list, usually by calling @code{final_scan_insn}.
3000:
3001: You need not define this macro if you did not define
3002: @code{DELAY_SLOTS_FOR_EPILOGUE}.
3003: @end table
3004:
3005: @node Profiling
3006: @subsection Generating Code for Profiling
3007: @cindex profiling, code generation
3008:
1.1.1.5 root 3009: These macros will help you generate code for profiling.
3010:
1.1 root 3011: @table @code
3012: @findex FUNCTION_PROFILER
3013: @item FUNCTION_PROFILER (@var{file}, @var{labelno})
3014: A C statement or compound statement to output to @var{file} some
3015: assembler code to call the profiling subroutine @code{mcount}.
3016: Before calling, the assembler code must load the address of a
3017: counter variable into a register where @code{mcount} expects to
3018: find the address. The name of this variable is @samp{LP} followed
3019: by the number @var{labelno}, so you would generate the name using
3020: @samp{LP%d} in a @code{fprintf}.
3021:
3022: @findex mcount
3023: The details of how the address should be passed to @code{mcount} are
3024: determined by your operating system environment, not by GNU CC. To
3025: figure them out, compile a small program for profiling using the
3026: system's installed C compiler and look at the assembler code that
3027: results.
3028:
3029: @findex PROFILE_BEFORE_PROLOGUE
3030: @item PROFILE_BEFORE_PROLOGUE
3031: Define this macro if the code for function profiling should come before
3032: the function prologue. Normally, the profiling code comes after.
3033:
3034: @findex FUNCTION_BLOCK_PROFILER
3035: @findex __bb_init_func
3036: @item FUNCTION_BLOCK_PROFILER (@var{file}, @var{labelno})
3037: A C statement or compound statement to output to @var{file} some
3038: assembler code to initialize basic-block profiling for the current
3039: object module. This code should call the subroutine
3040: @code{__bb_init_func} once per object module, passing it as its sole
3041: argument the address of a block allocated in the object module.
3042:
3043: The name of the block is a local symbol made with this statement:
3044:
3045: @example
3046: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0);
3047: @end example
3048:
3049: Of course, since you are writing the definition of
3050: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
3051: can take a short cut in the definition of this macro and use the name
3052: that you know will result.
3053:
3054: The first word of this block is a flag which will be nonzero if the
3055: object module has already been initialized. So test this word first,
3056: and do not call @code{__bb_init_func} if the flag is nonzero.
3057:
3058: @findex BLOCK_PROFILER
3059: @item BLOCK_PROFILER (@var{file}, @var{blockno})
3060: A C statement or compound statement to increment the count associated
3061: with the basic block number @var{blockno}. Basic blocks are numbered
3062: separately from zero within each compilation. The count associated
3063: with block number @var{blockno} is at index @var{blockno} in a vector
3064: of words; the name of this array is a local symbol made with this
3065: statement:
3066:
3067: @example
3068: ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 2);
3069: @end example
3070:
1.1.1.5 root 3071: @c This paragraph is the same as one a few paragraphs up.
3072: @c That is not an error.
1.1 root 3073: Of course, since you are writing the definition of
3074: @code{ASM_GENERATE_INTERNAL_LABEL} as well as that of this macro, you
3075: can take a short cut in the definition of this macro and use the name
3076: that you know will result.
1.1.1.6 root 3077:
3078: @findex BLOCK_PROFILER_CODE
3079: @item BLOCK_PROFILER_CODE
3080: A C function or functions which are needed in the library to
3081: support block profiling.
1.1 root 3082: @end table
3083:
1.1.1.2 root 3084: @node Varargs
1.1 root 3085: @section Implementing the Varargs Macros
3086: @cindex varargs implementation
3087:
3088: GNU CC comes with an implementation of @file{varargs.h} and
3089: @file{stdarg.h} that work without change on machines that pass arguments
3090: on the stack. Other machines require their own implementations of
3091: varargs, and the two machine independent header files must have
3092: conditionals to include it.
3093:
3094: ANSI @file{stdarg.h} differs from traditional @file{varargs.h} mainly in
3095: the calling convention for @code{va_start}. The traditional
3096: implementation takes just one argument, which is the variable in which
1.1.1.3 root 3097: to store the argument pointer. The ANSI implementation of
3098: @code{va_start} takes an additional second argument. The user is
3099: supposed to write the last named argument of the function here.
3100:
3101: However, @code{va_start} should not use this argument. The way to find
1.1 root 3102: the end of the named arguments is with the built-in functions described
3103: below.
3104:
3105: @table @code
3106: @findex __builtin_saveregs
3107: @item __builtin_saveregs ()
3108: Use this built-in function to save the argument registers in memory so
3109: that the varargs mechanism can access them. Both ANSI and traditional
3110: versions of @code{va_start} must use @code{__builtin_saveregs}, unless
3111: you use @code{SETUP_INCOMING_VARARGS} (see below) instead.
3112:
3113: On some machines, @code{__builtin_saveregs} is open-coded under the
3114: control of the macro @code{EXPAND_BUILTIN_SAVEREGS}. On other machines,
3115: it calls a routine written in assembler language, found in
3116: @file{libgcc2.c}.
3117:
1.1.1.5 root 3118: Code generated for the call to @code{__builtin_saveregs} appears at the
3119: beginning of the function, as opposed to where the call to
3120: @code{__builtin_saveregs} is written, regardless of what the code is.
3121: This is because the registers must be saved before the function starts
3122: to use them for its own purposes.
3123: @c i rewrote the first sentence above to fix an overfull hbox. --mew
3124: @c 10feb93
1.1 root 3125:
3126: @findex __builtin_args_info
3127: @item __builtin_args_info (@var{category})
3128: Use this built-in function to find the first anonymous arguments in
3129: registers.
3130:
3131: In general, a machine may have several categories of registers used for
3132: arguments, each for a particular category of data types. (For example,
3133: on some machines, floating-point registers are used for floating-point
3134: arguments while other arguments are passed in the general registers.)
3135: To make non-varargs functions use the proper calling convention, you
3136: have defined the @code{CUMULATIVE_ARGS} data type to record how many
3137: registers in each category have been used so far
3138:
3139: @code{__builtin_args_info} accesses the same data structure of type
3140: @code{CUMULATIVE_ARGS} after the ordinary argument layout is finished
3141: with it, with @var{category} specifying which word to access. Thus, the
3142: value indicates the first unused register in a given category.
3143:
3144: Normally, you would use @code{__builtin_args_info} in the implementation
3145: of @code{va_start}, accessing each category just once and storing the
3146: value in the @code{va_list} object. This is because @code{va_list} will
3147: have to update the values, and there is no way to alter the
3148: values accessed by @code{__builtin_args_info}.
3149:
3150: @findex __builtin_next_arg
1.1.1.7 root 3151: @item __builtin_next_arg (@var{lastarg})
1.1 root 3152: This is the equivalent of @code{__builtin_args_info}, for stack
3153: arguments. It returns the address of the first anonymous stack
3154: argument, as type @code{void *}. If @code{ARGS_GROW_DOWNWARD}, it
3155: returns the address of the location above the first anonymous stack
1.1.1.7 root 3156: argument. Use it in @code{va_start} to initialize the pointer for
3157: fetching arguments from the stack. Also use it in @code{va_start} to
3158: verify that the second parameter @var{lastarg} is the last named argument
3159: of the current function.
1.1 root 3160:
3161: @findex __builtin_classify_type
3162: @item __builtin_classify_type (@var{object})
3163: Since each machine has its own conventions for which data types are
3164: passed in which kind of register, your implementation of @code{va_arg}
3165: has to embody these conventions. The easiest way to categorize the
3166: specified data type is to use @code{__builtin_classify_type} together
3167: with @code{sizeof} and @code{__alignof__}.
3168:
3169: @code{__builtin_classify_type} ignores the value of @var{object},
3170: considering only its data type. It returns an integer describing what
3171: kind of type that is---integer, floating, pointer, structure, and so on.
3172:
3173: The file @file{typeclass.h} defines an enumeration that you can use to
3174: interpret the values of @code{__builtin_classify_type}.
3175: @end table
3176:
3177: These machine description macros help implement varargs:
3178:
3179: @table @code
3180: @findex EXPAND_BUILTIN_SAVEREGS
3181: @item EXPAND_BUILTIN_SAVEREGS (@var{args})
3182: If defined, is a C expression that produces the machine-specific code
3183: for a call to @code{__builtin_saveregs}. This code will be moved to the
3184: very beginning of the function, before any parameter access are made.
3185: The return value of this function should be an RTX that contains the
3186: value to use as the return of @code{__builtin_saveregs}.
3187:
3188: The argument @var{args} is a @code{tree_list} containing the arguments
3189: that were passed to @code{__builtin_saveregs}.
3190:
3191: If this macro is not defined, the compiler will output an ordinary
3192: call to the library function @samp{__builtin_saveregs}.
3193:
1.1.1.5 root 3194: @c !!! a bug in texinfo; how to make the entry on the @item line allow
3195: @c more than one line of text... help... --mew 10feb93
1.1 root 3196: @findex SETUP_INCOMING_VARARGS
1.1.1.5 root 3197: @item SETUP_INCOMING_VARARGS (@var{args_so_far}, @var{mode}, @var{type},
3198: @var{pretend_args_size}, @var{second_time})
1.1 root 3199: This macro offers an alternative to using @code{__builtin_saveregs} and
3200: defining the macro @code{EXPAND_BUILTIN_SAVEREGS}. Use it to store the
3201: anonymous register arguments into the stack so that all the arguments
3202: appear to have been passed consecutively on the stack. Once this is
3203: done, you can use the standard implementation of varargs that works for
3204: machines that pass all their arguments on the stack.
3205:
3206: The argument @var{args_so_far} is the @code{CUMULATIVE_ARGS} data
3207: structure, containing the values that obtain after processing of the
3208: named arguments. The arguments @var{mode} and @var{type} describe the
3209: last named argument---its machine mode and its data type as a tree node.
3210:
3211: The macro implementation should do two things: first, push onto the
3212: stack all the argument registers @emph{not} used for the named
3213: arguments, and second, store the size of the data thus pushed into the
3214: @code{int}-valued variable whose name is supplied as the argument
3215: @var{pretend_args_size}. The value that you store here will serve as
3216: additional offset for setting up the stack frame.
3217:
3218: Because you must generate code to push the anonymous arguments at
3219: compile time without knowing their data types,
3220: @code{SETUP_INCOMING_VARARGS} is only useful on machines that have just
3221: a single category of argument register and use it uniformly for all data
3222: types.
3223:
3224: If the argument @var{second_time} is nonzero, it means that the
3225: arguments of the function are being analyzed for the second time. This
3226: happens for an inline function, which is not actually compiled until the
3227: end of the source file. The macro @code{SETUP_INCOMING_VARARGS} should
3228: not generate any instructions in this case.
1.1.1.8 ! root 3229:
! 3230: @findex STRICT_ARGUMENT_NAMING
! 3231: @item STRICT_ARGUMENT_NAMING
! 3232: Define this macro if the location where a function argument is passed
! 3233: depends on whether or not it is a named argument.
! 3234:
! 3235: This macro controls how the @var{named} argument to @code{FUNCTION_ARG}
! 3236: is set for varargs and stdarg functions. With this macro defined,
! 3237: the @var{named} argument is always true for named arguments, and false for
! 3238: unnamed arguments. If this is not defined, but @code{SETUP_INCOMING_VARARGS}
! 3239: is defined, then all arguments are treated as named. Otherwise, all named
! 3240: arguments except the last are treated as named.
1.1 root 3241: @end table
3242:
1.1.1.2 root 3243: @node Trampolines
1.1 root 3244: @section Trampolines for Nested Functions
3245: @cindex trampolines for nested functions
3246: @cindex nested functions, trampolines for
3247:
3248: A @dfn{trampoline} is a small piece of code that is created at run time
3249: when the address of a nested function is taken. It normally resides on
3250: the stack, in the stack frame of the containing function. These macros
3251: tell GNU CC how to generate code to allocate and initialize a
3252: trampoline.
3253:
3254: The instructions in the trampoline must do two things: load a constant
3255: address into the static chain register, and jump to the real address of
3256: the nested function. On CISC machines such as the m68k, this requires
3257: two instructions, a move immediate and a jump. Then the two addresses
3258: exist in the trampoline as word-long immediate operands. On RISC
3259: machines, it is often necessary to load each address into a register in
3260: two parts. Then pieces of each address form separate immediate
3261: operands.
3262:
3263: The code generated to initialize the trampoline must store the variable
3264: parts---the static chain value and the function address---into the
3265: immediate operands of the instructions. On a CISC machine, this is
3266: simply a matter of copying each address to a memory reference at the
3267: proper offset from the start of the trampoline. On a RISC machine, it
3268: may be necessary to take out pieces of the address and store them
3269: separately.
3270:
3271: @table @code
3272: @findex TRAMPOLINE_TEMPLATE
3273: @item TRAMPOLINE_TEMPLATE (@var{file})
3274: A C statement to output, on the stream @var{file}, assembler code for a
3275: block of data that contains the constant parts of a trampoline. This
3276: code should not include a label---the label is taken care of
3277: automatically.
3278:
1.1.1.4 root 3279: @findex TRAMPOLINE_SECTION
3280: @item TRAMPOLINE_SECTION
3281: The name of a subroutine to switch to the section in which the
3282: trampoline template is to be placed (@pxref{Sections}). The default is
3283: a value of @samp{readonly_data_section}, which places the trampoline in
3284: the section containing read-only data.
3285:
1.1 root 3286: @findex TRAMPOLINE_SIZE
3287: @item TRAMPOLINE_SIZE
3288: A C expression for the size in bytes of the trampoline, as an integer.
3289:
3290: @findex TRAMPOLINE_ALIGNMENT
3291: @item TRAMPOLINE_ALIGNMENT
3292: Alignment required for trampolines, in bits.
3293:
3294: If you don't define this macro, the value of @code{BIGGEST_ALIGNMENT}
3295: is used for aligning trampolines.
3296:
3297: @findex INITIALIZE_TRAMPOLINE
3298: @item INITIALIZE_TRAMPOLINE (@var{addr}, @var{fnaddr}, @var{static_chain})
3299: A C statement to initialize the variable parts of a trampoline.
3300: @var{addr} is an RTX for the address of the trampoline; @var{fnaddr} is
3301: an RTX for the address of the nested function; @var{static_chain} is an
3302: RTX for the static chain value that should be passed to the function
3303: when it is called.
3304:
3305: @findex ALLOCATE_TRAMPOLINE
3306: @item ALLOCATE_TRAMPOLINE (@var{fp})
3307: A C expression to allocate run-time space for a trampoline. The
3308: expression value should be an RTX representing a memory reference to the
3309: space for the trampoline.
3310:
3311: @cindex @code{FUNCTION_EPILOGUE} and trampolines
3312: @cindex @code{FUNCTION_PROLOGUE} and trampolines
3313: If this macro is not defined, by default the trampoline is allocated as
3314: a stack slot. This default is right for most machines. The exceptions
3315: are machines where it is impossible to execute instructions in the stack
3316: area. On such machines, you may have to implement a separate stack,
3317: using this macro in conjunction with @code{FUNCTION_PROLOGUE} and
3318: @code{FUNCTION_EPILOGUE}.
3319:
3320: @var{fp} points to a data structure, a @code{struct function}, which
3321: describes the compilation status of the immediate containing function of
3322: the function which the trampoline is for. Normally (when
3323: @code{ALLOCATE_TRAMPOLINE} is not defined), the stack slot for the
3324: trampoline is in the stack frame of this containing function. Other
3325: allocation strategies probably must do something analogous with this
3326: information.
3327: @end table
3328:
3329: Implementing trampolines is difficult on many machines because they have
3330: separate instruction and data caches. Writing into a stack location
3331: fails to clear the memory in the instruction cache, so when the program
3332: jumps to that location, it executes the old contents.
3333:
3334: Here are two possible solutions. One is to clear the relevant parts of
3335: the instruction cache whenever a trampoline is set up. The other is to
3336: make all trampolines identical, by having them jump to a standard
3337: subroutine. The former technique makes trampoline execution faster; the
3338: latter makes initialization faster.
3339:
3340: To clear the instruction cache when a trampoline is initialized, define
3341: the following macros which describe the shape of the cache.
3342:
3343: @table @code
3344: @findex INSN_CACHE_SIZE
3345: @item INSN_CACHE_SIZE
3346: The total size in bytes of the cache.
3347:
3348: @findex INSN_CACHE_LINE_WIDTH
3349: @item INSN_CACHE_LINE_WIDTH
3350: The length in bytes of each cache line. The cache is divided into cache
3351: lines which are disjoint slots, each holding a contiguous chunk of data
3352: fetched from memory. Each time data is brought into the cache, an
3353: entire line is read at once. The data loaded into a cache line is
3354: always aligned on a boundary equal to the line size.
3355:
3356: @findex INSN_CACHE_DEPTH
3357: @item INSN_CACHE_DEPTH
3358: The number of alternative cache lines that can hold any particular memory
3359: location.
3360: @end table
3361:
1.1.1.6 root 3362: Alternatively, if the machine has system calls or instructions to clear
3363: the instruction cache directly, you can define the following macro.
3364:
3365: @table @code
1.1.1.7 root 3366: @findex CLEAR_INSN_CACHE
3367: @item CLEAR_INSN_CACHE (@var{BEG}, @var{END})
1.1.1.6 root 3368: If defined, expands to a C expression clearing the @emph{instruction
3369: cache} in the specified interval. If it is not defined, and the macro
3370: INSN_CACHE_SIZE is defined, some generic code is generated to clear the
3371: cache. The definition of this macro would typically be a series of
3372: @code{asm} statements. Both @var{BEG} and @var{END} are both pointer
3373: expressions.
3374: @end table
3375:
1.1 root 3376: To use a standard subroutine, define the following macro. In addition,
3377: you must make sure that the instructions in a trampoline fill an entire
3378: cache line with identical instructions, or else ensure that the
3379: beginning of the trampoline code is always aligned at the same point in
3380: its cache line. Look in @file{m68k.h} as a guide.
3381:
3382: @table @code
3383: @findex TRANSFER_FROM_TRAMPOLINE
3384: @item TRANSFER_FROM_TRAMPOLINE
3385: Define this macro if trampolines need a special subroutine to do their
3386: work. The macro should expand to a series of @code{asm} statements
3387: which will be compiled with GNU CC. They go in a library function named
3388: @code{__transfer_from_trampoline}.
3389:
3390: If you need to avoid executing the ordinary prologue code of a compiled
3391: C function when you jump to the subroutine, you can do so by placing a
3392: special label of your own in the assembler code. Use one @code{asm}
3393: statement to generate an assembler label, and another to make the label
3394: global. Then trampolines can use that label to jump directly to your
3395: special assembler code.
3396: @end table
3397:
1.1.1.2 root 3398: @node Library Calls
1.1 root 3399: @section Implicit Calls to Library Routines
3400: @cindex library subroutine names
3401: @cindex @file{libgcc.a}
3402:
1.1.1.7 root 3403: @c prevent bad page break with this line
3404: Here is an explanation of implicit calls to library routines.
3405:
1.1 root 3406: @table @code
3407: @findex MULSI3_LIBCALL
3408: @item MULSI3_LIBCALL
3409: A C string constant giving the name of the function to call for
3410: multiplication of one signed full-word by another. If you do not
3411: define this macro, the default name is used, which is @code{__mulsi3},
3412: a function defined in @file{libgcc.a}.
3413:
3414: @findex DIVSI3_LIBCALL
3415: @item DIVSI3_LIBCALL
3416: A C string constant giving the name of the function to call for
3417: division of one signed full-word by another. If you do not define
3418: this macro, the default name is used, which is @code{__divsi3}, a
3419: function defined in @file{libgcc.a}.
3420:
3421: @findex UDIVSI3_LIBCALL
3422: @item UDIVSI3_LIBCALL
3423: A C string constant giving the name of the function to call for
3424: division of one unsigned full-word by another. If you do not define
3425: this macro, the default name is used, which is @code{__udivsi3}, a
3426: function defined in @file{libgcc.a}.
3427:
3428: @findex MODSI3_LIBCALL
3429: @item MODSI3_LIBCALL
3430: A C string constant giving the name of the function to call for the
3431: remainder in division of one signed full-word by another. If you do
3432: not define this macro, the default name is used, which is
3433: @code{__modsi3}, a function defined in @file{libgcc.a}.
3434:
3435: @findex UMODSI3_LIBCALL
3436: @item UMODSI3_LIBCALL
3437: A C string constant giving the name of the function to call for the
3438: remainder in division of one unsigned full-word by another. If you do
3439: not define this macro, the default name is used, which is
3440: @code{__umodsi3}, a function defined in @file{libgcc.a}.
3441:
3442: @findex MULDI3_LIBCALL
3443: @item MULDI3_LIBCALL
3444: A C string constant giving the name of the function to call for
3445: multiplication of one signed double-word by another. If you do not
3446: define this macro, the default name is used, which is @code{__muldi3},
3447: a function defined in @file{libgcc.a}.
3448:
3449: @findex DIVDI3_LIBCALL
3450: @item DIVDI3_LIBCALL
3451: A C string constant giving the name of the function to call for
3452: division of one signed double-word by another. If you do not define
3453: this macro, the default name is used, which is @code{__divdi3}, a
3454: function defined in @file{libgcc.a}.
3455:
3456: @findex UDIVDI3_LIBCALL
3457: @item UDIVDI3_LIBCALL
3458: A C string constant giving the name of the function to call for
3459: division of one unsigned full-word by another. If you do not define
3460: this macro, the default name is used, which is @code{__udivdi3}, a
3461: function defined in @file{libgcc.a}.
3462:
3463: @findex MODDI3_LIBCALL
3464: @item MODDI3_LIBCALL
3465: A C string constant giving the name of the function to call for the
3466: remainder in division of one signed double-word by another. If you do
3467: not define this macro, the default name is used, which is
3468: @code{__moddi3}, a function defined in @file{libgcc.a}.
3469:
3470: @findex UMODDI3_LIBCALL
3471: @item UMODDI3_LIBCALL
3472: A C string constant giving the name of the function to call for the
3473: remainder in division of one unsigned full-word by another. If you do
3474: not define this macro, the default name is used, which is
3475: @code{__umoddi3}, a function defined in @file{libgcc.a}.
3476:
1.1.1.7 root 3477: @findex INIT_TARGET_OPTABS
3478: @item INIT_TARGET_OPTABS
3479: Define this macro as a C statement that declares additional library
3480: routines renames existing ones. @code{init_optabs} calls this macro after
3481: initializing all the normal library routines.
3482:
1.1.1.4 root 3483: @findex TARGET_EDOM
3484: @cindex @code{EDOM}, implicit usage
3485: @item TARGET_EDOM
3486: The value of @code{EDOM} on the target machine, as a C integer constant
3487: expression. If you don't define this macro, GNU CC does not attempt to
3488: deposit the value of @code{EDOM} into @code{errno} directly. Look in
3489: @file{/usr/include/errno.h} to find the value of @code{EDOM} on your
3490: system.
3491:
3492: If you do not define @code{TARGET_EDOM}, then compiled code reports
3493: domain errors by calling the library function and letting it report the
3494: error. If mathematical functions on your system use @code{matherr} when
3495: there is an error, then you should leave @code{TARGET_EDOM} undefined so
3496: that @code{matherr} is used normally.
3497:
3498: @findex GEN_ERRNO_RTX
3499: @cindex @code{errno}, implicit usage
3500: @item GEN_ERRNO_RTX
3501: Define this macro as a C expression to create an rtl expression that
3502: refers to the global ``variable'' @code{errno}. (On certain systems,
3503: @code{errno} may not actually be a variable.) If you don't define this
3504: macro, a reasonable default is used.
3505:
1.1 root 3506: @findex TARGET_MEM_FUNCTIONS
3507: @cindex @code{bcopy}, implicit usage
3508: @cindex @code{memcpy}, implicit usage
3509: @cindex @code{bzero}, implicit usage
3510: @cindex @code{memset}, implicit usage
3511: @item TARGET_MEM_FUNCTIONS
3512: Define this macro if GNU CC should generate calls to the System V
3513: (and ANSI C) library functions @code{memcpy} and @code{memset}
3514: rather than the BSD functions @code{bcopy} and @code{bzero}.
3515:
3516: @findex LIBGCC_NEEDS_DOUBLE
3517: @item LIBGCC_NEEDS_DOUBLE
3518: Define this macro if only @code{float} arguments cannot be passed to
3519: library routines (so they must be converted to @code{double}). This
3520: macro affects both how library calls are generated and how the library
3521: routines in @file{libgcc1.c} accept their arguments. It is useful on
3522: machines where floating and fixed point arguments are passed
3523: differently, such as the i860.
3524:
3525: @findex FLOAT_ARG_TYPE
3526: @item FLOAT_ARG_TYPE
3527: Define this macro to override the type used by the library routines to
3528: pick up arguments of type @code{float}. (By default, they use a union
3529: of @code{float} and @code{int}.)
3530:
3531: The obvious choice would be @code{float}---but that won't work with
3532: traditional C compilers that expect all arguments declared as @code{float}
3533: to arrive as @code{double}. To avoid this conversion, the library routines
3534: ask for the value as some other type and then treat it as a @code{float}.
3535:
3536: On some systems, no other type will work for this. For these systems,
3537: you must use @code{LIBGCC_NEEDS_DOUBLE} instead, to force conversion of
3538: the values @code{double} before they are passed.
3539:
3540: @findex FLOATIFY
3541: @item FLOATIFY (@var{passed-value})
3542: Define this macro to override the way library routines redesignate a
3543: @code{float} argument as a @code{float} instead of the type it was
3544: passed as. The default is an expression which takes the @code{float}
3545: field of the union.
3546:
3547: @findex FLOAT_VALUE_TYPE
3548: @item FLOAT_VALUE_TYPE
3549: Define this macro to override the type used by the library routines to
3550: return values that ought to have type @code{float}. (By default, they
3551: use @code{int}.)
3552:
3553: The obvious choice would be @code{float}---but that won't work with
3554: traditional C compilers gratuitously convert values declared as
3555: @code{float} into @code{double}.
3556:
3557: @findex INTIFY
3558: @item INTIFY (@var{float-value})
3559: Define this macro to override the way the value of a
3560: @code{float}-returning library routine should be packaged in order to
3561: return it. These functions are actually declared to return type
3562: @code{FLOAT_VALUE_TYPE} (normally @code{int}).
3563:
3564: These values can't be returned as type @code{float} because traditional
3565: C compilers would gratuitously convert the value to a @code{double}.
3566:
3567: A local variable named @code{intify} is always available when the macro
3568: @code{INTIFY} is used. It is a union of a @code{float} field named
3569: @code{f} and a field named @code{i} whose type is
3570: @code{FLOAT_VALUE_TYPE} or @code{int}.
3571:
3572: If you don't define this macro, the default definition works by copying
3573: the value through that union.
3574:
1.1.1.3 root 3575: @findex nongcc_SI_type
3576: @item nongcc_SI_type
1.1 root 3577: Define this macro as the name of the data type corresponding to
3578: @code{SImode} in the system's own C compiler.
3579:
1.1.1.5 root 3580: You need not define this macro if that type is @code{long int}, as it usually
3581: is.
3582:
3583: @findex nongcc_word_type
3584: @item nongcc_word_type
3585: Define this macro as the name of the data type corresponding to the
3586: word_mode in the system's own C compiler.
3587:
3588: You need not define this macro if that type is @code{long int}, as it usually
1.1 root 3589: is.
3590:
3591: @findex perform_@dots{}
3592: @item perform_@dots{}
3593: Define these macros to supply explicit C statements to carry out various
3594: arithmetic operations on types @code{float} and @code{double} in the
3595: library routines in @file{libgcc1.c}. See that file for a full list
3596: of these macros and their arguments.
3597:
3598: On most machines, you don't need to define any of these macros, because
3599: the C compiler that comes with the system takes care of doing them.
3600:
3601: @findex NEXT_OBJC_RUNTIME
3602: @item NEXT_OBJC_RUNTIME
3603: Define this macro to generate code for Objective C message sending using
3604: the calling convention of the NeXT system. This calling convention
3605: involves passing the object, the selector and the method arguments all
3606: at once to the method-lookup library function.
3607:
3608: The default calling convention passes just the object and the selector
3609: to the lookup function, which returns a pointer to the method.
3610: @end table
3611:
1.1.1.2 root 3612: @node Addressing Modes
1.1 root 3613: @section Addressing Modes
3614: @cindex addressing modes
3615:
1.1.1.7 root 3616: @c prevent bad page break with this line
3617: This is about addressing modes.
3618:
1.1 root 3619: @table @code
3620: @findex HAVE_POST_INCREMENT
3621: @item HAVE_POST_INCREMENT
3622: Define this macro if the machine supports post-increment addressing.
3623:
3624: @findex HAVE_PRE_INCREMENT
3625: @findex HAVE_POST_DECREMENT
3626: @findex HAVE_PRE_DECREMENT
3627: @item HAVE_PRE_INCREMENT
3628: @itemx HAVE_POST_DECREMENT
3629: @itemx HAVE_PRE_DECREMENT
3630: Similar for other kinds of addressing.
3631:
3632: @findex CONSTANT_ADDRESS_P
3633: @item CONSTANT_ADDRESS_P (@var{x})
3634: A C expression that is 1 if the RTX @var{x} is a constant which
3635: is a valid address. On most machines, this can be defined as
3636: @code{CONSTANT_P (@var{x})}, but a few machines are more restrictive
3637: in which constant addresses are supported.
3638:
3639: @findex CONSTANT_P
3640: @code{CONSTANT_P} accepts integer-values expressions whose values are
3641: not explicitly known, such as @code{symbol_ref}, @code{label_ref}, and
3642: @code{high} expressions and @code{const} arithmetic expressions, in
3643: addition to @code{const_int} and @code{const_double} expressions.
3644:
3645: @findex MAX_REGS_PER_ADDRESS
3646: @item MAX_REGS_PER_ADDRESS
3647: A number, the maximum number of registers that can appear in a valid
3648: memory address. Note that it is up to you to specify a value equal to
3649: the maximum number that @code{GO_IF_LEGITIMATE_ADDRESS} would ever
3650: accept.
3651:
3652: @findex GO_IF_LEGITIMATE_ADDRESS
3653: @item GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{label})
3654: A C compound statement with a conditional @code{goto @var{label};}
3655: executed if @var{x} (an RTX) is a legitimate memory address on the
3656: target machine for a memory operand of mode @var{mode}.
3657:
3658: It usually pays to define several simpler macros to serve as
3659: subroutines for this one. Otherwise it may be too complicated to
3660: understand.
3661:
3662: This macro must exist in two variants: a strict variant and a
3663: non-strict one. The strict variant is used in the reload pass. It
3664: must be defined so that any pseudo-register that has not been
3665: allocated a hard register is considered a memory reference. In
3666: contexts where some kind of register is required, a pseudo-register
3667: with no hard register must be rejected.
3668:
3669: The non-strict variant is used in other passes. It must be defined to
3670: accept all pseudo-registers in every context where some kind of
3671: register is required.
3672:
3673: @findex REG_OK_STRICT
3674: Compiler source files that want to use the strict variant of this
3675: macro define the macro @code{REG_OK_STRICT}. You should use an
3676: @code{#ifdef REG_OK_STRICT} conditional to define the strict variant
3677: in that case and the non-strict variant otherwise.
3678:
1.1.1.5 root 3679: Subroutines to check for acceptable registers for various purposes (one
3680: for base registers, one for index registers, and so on) are typically
3681: among the subroutines used to define @code{GO_IF_LEGITIMATE_ADDRESS}.
3682: Then only these subroutine macros need have two variants; the higher
3683: levels of macros may be the same whether strict or not.@refill
1.1 root 3684:
3685: Normally, constant addresses which are the sum of a @code{symbol_ref}
3686: and an integer are stored inside a @code{const} RTX to mark them as
3687: constant. Therefore, there is no need to recognize such sums
3688: specifically as legitimate addresses. Normally you would simply
3689: recognize any @code{const} as legitimate.
3690:
3691: Usually @code{PRINT_OPERAND_ADDRESS} is not prepared to handle constant
3692: sums that are not marked with @code{const}. It assumes that a naked
3693: @code{plus} indicates indexing. If so, then you @emph{must} reject such
3694: naked constant sums as illegitimate addresses, so that none of them will
3695: be given to @code{PRINT_OPERAND_ADDRESS}.
3696:
3697: @cindex @code{ENCODE_SECTION_INFO} and address validation
3698: On some machines, whether a symbolic address is legitimate depends on
3699: the section that the address refers to. On these machines, define the
3700: macro @code{ENCODE_SECTION_INFO} to store the information into the
3701: @code{symbol_ref}, and then check for it here. When you see a
3702: @code{const}, you will have to look inside it to find the
3703: @code{symbol_ref} in order to determine the section. @xref{Assembler
3704: Format}.
3705:
3706: @findex saveable_obstack
3707: The best way to modify the name string is by adding text to the
3708: beginning, with suitable punctuation to prevent any ambiguity. Allocate
3709: the new name in @code{saveable_obstack}. You will have to modify
3710: @code{ASM_OUTPUT_LABELREF} to remove and decode the added text and
1.1.1.4 root 3711: output the name accordingly, and define @code{STRIP_NAME_ENCODING} to
3712: access the original name string.
1.1 root 3713:
3714: You can check the information stored here into the @code{symbol_ref} in
1.1.1.5 root 3715: the definitions of the macros @code{GO_IF_LEGITIMATE_ADDRESS} and
1.1 root 3716: @code{PRINT_OPERAND_ADDRESS}.
3717:
3718: @findex REG_OK_FOR_BASE_P
3719: @item REG_OK_FOR_BASE_P (@var{x})
3720: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
3721: RTX) is valid for use as a base register. For hard registers, it
3722: should always accept those which the hardware permits and reject the
3723: others. Whether the macro accepts or rejects pseudo registers must be
3724: controlled by @code{REG_OK_STRICT} as described above. This usually
3725: requires two variant definitions, of which @code{REG_OK_STRICT}
3726: controls the one actually used.
3727:
3728: @findex REG_OK_FOR_INDEX_P
3729: @item REG_OK_FOR_INDEX_P (@var{x})
3730: A C expression that is nonzero if @var{x} (assumed to be a @code{reg}
3731: RTX) is valid for use as an index register.
3732:
3733: The difference between an index register and a base register is that
3734: the index register may be scaled. If an address involves the sum of
3735: two registers, neither one of them scaled, then either one may be
3736: labeled the ``base'' and the other the ``index''; but whichever
3737: labeling is used must fit the machine's constraints of which registers
3738: may serve in each capacity. The compiler will try both labelings,
3739: looking for one that is valid, and will reload one or both registers
3740: only if neither labeling works.
3741:
3742: @findex LEGITIMIZE_ADDRESS
3743: @item LEGITIMIZE_ADDRESS (@var{x}, @var{oldx}, @var{mode}, @var{win})
3744: A C compound statement that attempts to replace @var{x} with a valid
3745: memory address for an operand of mode @var{mode}. @var{win} will be a
3746: C statement label elsewhere in the code; the macro definition may use
3747:
3748: @example
3749: GO_IF_LEGITIMATE_ADDRESS (@var{mode}, @var{x}, @var{win});
3750: @end example
3751:
3752: @noindent
3753: to avoid further processing if the address has become legitimate.
3754:
3755: @findex break_out_memory_refs
3756: @var{x} will always be the result of a call to @code{break_out_memory_refs},
3757: and @var{oldx} will be the operand that was given to that function to produce
3758: @var{x}.
3759:
3760: The code generated by this macro should not alter the substructure of
3761: @var{x}. If it transforms @var{x} into a more legitimate form, it
3762: should assign @var{x} (which will always be a C variable) a new value.
3763:
3764: It is not necessary for this macro to come up with a legitimate
3765: address. The compiler has standard ways of doing so in all cases. In
3766: fact, it is safe for this macro to do nothing. But often a
3767: machine-dependent strategy can generate better code.
3768:
3769: @findex GO_IF_MODE_DEPENDENT_ADDRESS
3770: @item GO_IF_MODE_DEPENDENT_ADDRESS (@var{addr}, @var{label})
3771: A C statement or compound statement with a conditional @code{goto
3772: @var{label};} executed if memory address @var{x} (an RTX) can have
3773: different meanings depending on the machine mode of the memory
1.1.1.4 root 3774: reference it is used for or if the address is valid for some modes
3775: but not others.
1.1 root 3776:
3777: Autoincrement and autodecrement addresses typically have mode-dependent
3778: effects because the amount of the increment or decrement is the size
3779: of the operand being addressed. Some machines have other mode-dependent
3780: addresses. Many RISC machines have no mode-dependent addresses.
3781:
3782: You may assume that @var{addr} is a valid address for the machine.
3783:
3784: @findex LEGITIMATE_CONSTANT_P
3785: @item LEGITIMATE_CONSTANT_P (@var{x})
3786: A C expression that is nonzero if @var{x} is a legitimate constant for
3787: an immediate operand on the target machine. You can assume that
3788: @var{x} satisfies @code{CONSTANT_P}, so you need not check this. In fact,
3789: @samp{1} is a suitable definition for this macro on machines where
3790: anything @code{CONSTANT_P} is valid.@refill
3791: @end table
3792:
1.1.1.2 root 3793: @node Condition Code
1.1 root 3794: @section Condition Code Status
3795: @cindex condition code status
3796:
1.1.1.7 root 3797: @c prevent bad page break with this line
3798: This describes the condition code status.
3799:
1.1 root 3800: @findex cc_status
3801: The file @file{conditions.h} defines a variable @code{cc_status} to
3802: describe how the condition code was computed (in case the interpretation of
3803: the condition code depends on the instruction that it was set by). This
3804: variable contains the RTL expressions on which the condition code is
3805: currently based, and several standard flags.
3806:
3807: Sometimes additional machine-specific flags must be defined in the machine
3808: description header file. It can also add additional machine-specific
3809: information by defining @code{CC_STATUS_MDEP}.
3810:
3811: @table @code
3812: @findex CC_STATUS_MDEP
3813: @item CC_STATUS_MDEP
3814: C code for a data type which is used for declaring the @code{mdep}
3815: component of @code{cc_status}. It defaults to @code{int}.
3816:
3817: This macro is not used on machines that do not use @code{cc0}.
3818:
3819: @findex CC_STATUS_MDEP_INIT
3820: @item CC_STATUS_MDEP_INIT
3821: A C expression to initialize the @code{mdep} field to ``empty''.
3822: The default definition does nothing, since most machines don't use
3823: the field anyway. If you want to use the field, you should probably
3824: define this macro to initialize it.
3825:
3826: This macro is not used on machines that do not use @code{cc0}.
3827:
3828: @findex NOTICE_UPDATE_CC
3829: @item NOTICE_UPDATE_CC (@var{exp}, @var{insn})
3830: A C compound statement to set the components of @code{cc_status}
3831: appropriately for an insn @var{insn} whose body is @var{exp}. It is
3832: this macro's responsibility to recognize insns that set the condition
3833: code as a byproduct of other activity as well as those that explicitly
3834: set @code{(cc0)}.
3835:
3836: This macro is not used on machines that do not use @code{cc0}.
3837:
3838: If there are insns that do not set the condition code but do alter
3839: other machine registers, this macro must check to see whether they
3840: invalidate the expressions that the condition code is recorded as
3841: reflecting. For example, on the 68000, insns that store in address
3842: registers do not set the condition code, which means that usually
3843: @code{NOTICE_UPDATE_CC} can leave @code{cc_status} unaltered for such
3844: insns. But suppose that the previous insn set the condition code
3845: based on location @samp{a4@@(102)} and the current insn stores a new
3846: value in @samp{a4}. Although the condition code is not changed by
3847: this, it will no longer be true that it reflects the contents of
3848: @samp{a4@@(102)}. Therefore, @code{NOTICE_UPDATE_CC} must alter
3849: @code{cc_status} in this case to say that nothing is known about the
3850: condition code value.
3851:
3852: The definition of @code{NOTICE_UPDATE_CC} must be prepared to deal
3853: with the results of peephole optimization: insns whose patterns are
3854: @code{parallel} RTXs containing various @code{reg}, @code{mem} or
3855: constants which are just the operands. The RTL structure of these
3856: insns is not sufficient to indicate what the insns actually do. What
3857: @code{NOTICE_UPDATE_CC} should do when it sees one is just to run
3858: @code{CC_STATUS_INIT}.
3859:
3860: A possible definition of @code{NOTICE_UPDATE_CC} is to call a function
3861: that looks at an attribute (@pxref{Insn Attributes}) named, for example,
3862: @samp{cc}. This avoids having detailed information about patterns in
3863: two places, the @file{md} file and in @code{NOTICE_UPDATE_CC}.
3864:
3865: @findex EXTRA_CC_MODES
3866: @item EXTRA_CC_MODES
3867: A list of names to be used for additional modes for condition code
3868: values in registers (@pxref{Jump Patterns}). These names are added
3869: to @code{enum machine_mode} and all have class @code{MODE_CC}. By
3870: convention, they should start with @samp{CC} and end with @samp{mode}.
3871:
3872: You should only define this macro if your machine does not use @code{cc0}
3873: and only if additional modes are required.
3874:
3875: @findex EXTRA_CC_NAMES
3876: @item EXTRA_CC_NAMES
3877: A list of C strings giving the names for the modes listed in
3878: @code{EXTRA_CC_MODES}. For example, the Sparc defines this macro and
3879: @code{EXTRA_CC_MODES} as
3880:
1.1.1.5 root 3881: @smallexample
1.1.1.7 root 3882: #define EXTRA_CC_MODES CC_NOOVmode, CCFPmode, CCFPEmode
3883: #define EXTRA_CC_NAMES "CC_NOOV", "CCFP", "CCFPE"
1.1.1.5 root 3884: @end smallexample
1.1 root 3885:
3886: This macro is not required if @code{EXTRA_CC_MODES} is not defined.
3887:
3888: @findex SELECT_CC_MODE
1.1.1.4 root 3889: @item SELECT_CC_MODE (@var{op}, @var{x}, @var{y})
3890: Returns a mode from class @code{MODE_CC} to be used when comparison
3891: operation code @var{op} is applied to rtx @var{x} and @var{y}. For
3892: example, on the Sparc, @code{SELECT_CC_MODE} is defined as (see
3893: @pxref{Jump Patterns} for a description of the reason for this
3894: definition)
1.1 root 3895:
1.1.1.5 root 3896: @smallexample
1.1.1.4 root 3897: #define SELECT_CC_MODE(OP,X,Y) \
1.1.1.5 root 3898: (GET_MODE_CLASS (GET_MODE (X)) == MODE_FLOAT \
3899: ? ((OP == EQ || OP == NE) ? CCFPmode : CCFPEmode) \
3900: : ((GET_CODE (X) == PLUS || GET_CODE (X) == MINUS \
3901: || GET_CODE (X) == NEG) \
1.1.1.4 root 3902: ? CC_NOOVmode : CCmode))
1.1.1.5 root 3903: @end smallexample
1.1 root 3904:
1.1.1.7 root 3905: You need not define this macro if @code{EXTRA_CC_MODES} is not defined.
3906:
3907: @findex CANONICALIZE_COMPARISON
3908: @item CANONICALIZE_COMPARISON (@var{code}, @var{op0}, @var{op1})
3909: One some machines not all possible comparisons are defined, but you can
3910: convert an invalid comparison into a valid one. For example, the Alpha
3911: does not have a @code{GT} comparison, but you can use an @code{LT}
3912: comparison instead and swap the order of the operands.
3913:
3914: On such machines, define this macro to be a C statement to do any
3915: required conversions. @var{code} is the initial comparison code
3916: and @var{op0} and @var{op1} are the left and right operands of the
3917: comparison, respectively. You should modify @var{code}, @var{op0}, and
3918: @var{op1} as required.
3919:
3920: GNU CC will not assume that the comparison resulting from this macro is
3921: valid but will see if the resulting insn matches a pattern in the
3922: @file{md} file.
3923:
3924: You need not define this macro if it would never change the comparison
3925: code or operands.
3926:
3927: @findex REVERSIBLE_CC_MODE
3928: @item REVERSIBLE_CC_MODE (@var{mode})
3929: A C expression whose value is one if it is always safe to reverse a
3930: comparison whose mode is @var{mode}. If @code{SELECT_CC_MODE}
3931: can ever return @var{mode} for a floating-point inequality comparison,
3932: then @code{REVERSIBLE_CC_MODE (@var{mode})} must be zero.
3933:
3934: You need not define this macro if it would always returns zero or if the
3935: floating-point format is anything other than @code{IEEE_FLOAT_FORMAT}.
3936: For example, here is the definition used on the Sparc, where floating-point
3937: inequality comparisons are always given @code{CCFPEmode}:
3938:
3939: @smallexample
3940: #define REVERSIBLE_CC_MODE(MODE) ((MODE) != CCFPEmode)
3941: @end smallexample
3942:
1.1 root 3943: @end table
3944:
1.1.1.2 root 3945: @node Costs
1.1 root 3946: @section Describing Relative Costs of Operations
3947: @cindex costs of instructions
3948: @cindex relative costs
3949: @cindex speed of instructions
3950:
3951: These macros let you describe the relative speed of various operations
3952: on the target machine.
3953:
3954: @table @code
3955: @findex CONST_COSTS
1.1.1.3 root 3956: @item CONST_COSTS (@var{x}, @var{code}, @var{outer_code})
1.1 root 3957: A part of a C @code{switch} statement that describes the relative costs
3958: of constant RTL expressions. It must contain @code{case} labels for
3959: expression codes @code{const_int}, @code{const}, @code{symbol_ref},
3960: @code{label_ref} and @code{const_double}. Each case must ultimately
3961: reach a @code{return} statement to return the relative cost of the use
3962: of that kind of constant value in an expression. The cost may depend on
3963: the precise value of the constant, which is available for examination in
1.1.1.3 root 3964: @var{x}, and the rtx code of the expression in which it is contained,
3965: found in @var{outer_code}.
1.1 root 3966:
3967: @var{code} is the expression code---redundant, since it can be
3968: obtained with @code{GET_CODE (@var{x})}.
3969:
3970: @findex RTX_COSTS
3971: @findex COSTS_N_INSNS
1.1.1.3 root 3972: @item RTX_COSTS (@var{x}, @var{code}, @var{outer_code})
1.1 root 3973: Like @code{CONST_COSTS} but applies to nonconstant RTL expressions.
3974: This can be used, for example, to indicate how costly a multiply
3975: instruction is. In writing this macro, you can use the construct
3976: @code{COSTS_N_INSNS (@var{n})} to specify a cost equal to @var{n} fast
1.1.1.3 root 3977: instructions. @var{outer_code} is the code of the expression in which
3978: @var{x} is contained.
1.1 root 3979:
3980: This macro is optional; do not define it if the default cost assumptions
3981: are adequate for the target machine.
3982:
3983: @findex ADDRESS_COST
3984: @item ADDRESS_COST (@var{address})
3985: An expression giving the cost of an addressing mode that contains
3986: @var{address}. If not defined, the cost is computed from
3987: the @var{address} expression and the @code{CONST_COSTS} values.
3988:
3989: For most CISC machines, the default cost is a good approximation of the
3990: true cost of the addressing mode. However, on RISC machines, all
3991: instructions normally have the same length and execution time. Hence
3992: all addresses will have equal costs.
3993:
3994: In cases where more than one form of an address is known, the form with
3995: the lowest cost will be used. If multiple forms have the same, lowest,
3996: cost, the one that is the most complex will be used.
3997:
3998: For example, suppose an address that is equal to the sum of a register
3999: and a constant is used twice in the same basic block. When this macro
4000: is not defined, the address will be computed in a register and memory
4001: references will be indirect through that register. On machines where
4002: the cost of the addressing mode containing the sum is no higher than
4003: that of a simple indirect reference, this will produce an additional
4004: instruction and possibly require an additional register. Proper
4005: specification of this macro eliminates this overhead for such machines.
4006:
4007: Similar use of this macro is made in strength reduction of loops.
4008:
4009: @var{address} need not be valid as an address. In such a case, the cost
4010: is not relevant and can be any value; invalid addresses need not be
4011: assigned a different cost.
4012:
4013: On machines where an address involving more than one register is as
4014: cheap as an address computation involving only one register, defining
4015: @code{ADDRESS_COST} to reflect this can cause two registers to be live
4016: over a region of code where only one would have been if
4017: @code{ADDRESS_COST} were not defined in that manner. This effect should
4018: be considered in the definition of this macro. Equivalent costs should
4019: probably only be given to addresses with different numbers of registers
4020: on machines with lots of registers.
4021:
4022: This macro will normally either not be defined or be defined as a
4023: constant.
4024:
4025: @findex REGISTER_MOVE_COST
4026: @item REGISTER_MOVE_COST (@var{from}, @var{to})
4027: A C expression for the cost of moving data from a register in class
4028: @var{from} to one in class @var{to}. The classes are expressed using
1.1.1.5 root 4029: the enumeration values such as @code{GENERAL_REGS}. A value of 4 is the
1.1 root 4030: default; other values are interpreted relative to that.
4031:
4032: It is not required that the cost always equal 2 when @var{from} is the
4033: same as @var{to}; on some machines it is expensive to move between
4034: registers if they are not general registers.
4035:
4036: If reload sees an insn consisting of a single @code{set} between two
4037: hard registers, and if @code{REGISTER_MOVE_COST} applied to their
4038: classes returns a value of 2, reload does not check to ensure that the
4039: constraints of the insn are met. Setting a cost of other than 2 will
4040: allow reload to verify that the constraints are met. You should do this
4041: if the @samp{mov@var{m}} pattern's constraints do not allow such copying.
4042:
4043: @findex MEMORY_MOVE_COST
4044: @item MEMORY_MOVE_COST (@var{m})
4045: A C expression for the cost of moving data of mode @var{m} between a
4046: register and memory. A value of 2 is the default; this cost is relative
4047: to those in @code{REGISTER_MOVE_COST}.
4048:
4049: If moving between registers and memory is more expensive than between
4050: two registers, you should define this macro to express the relative cost.
4051:
4052: @findex BRANCH_COST
4053: @item BRANCH_COST
4054: A C expression for the cost of a branch instruction. A value of 1 is
4055: the default; other values are interpreted relative to that.
4056: @end table
4057:
4058: Here are additional macros which do not specify precise relative costs,
4059: but only that certain actions are more expensive than GNU CC would
4060: ordinarily expect.
4061:
4062: @table @code
4063: @findex SLOW_BYTE_ACCESS
4064: @item SLOW_BYTE_ACCESS
4065: Define this macro as a C expression which is nonzero if accessing less
4066: than a word of memory (i.e. a @code{char} or a @code{short}) is no
4067: faster than accessing a word of memory, i.e., if such access
4068: require more than one instruction or if there is no difference in cost
4069: between byte and (aligned) word loads.
4070:
4071: When this macro is not defined, the compiler will access a field by
4072: finding the smallest containing object; when it is defined, a fullword
4073: load will be used if alignment permits. Unless bytes accesses are
4074: faster than word accesses, using word accesses is preferable since it
4075: may eliminate subsequent memory access if subsequent accesses occur to
4076: other fields in the same word of the structure, but to different bytes.
4077:
4078: @findex SLOW_ZERO_EXTEND
4079: @item SLOW_ZERO_EXTEND
4080: Define this macro if zero-extension (of a @code{char} or @code{short}
4081: to an @code{int}) can be done faster if the destination is a register
4082: that is known to be zero.
4083:
4084: If you define this macro, you must have instruction patterns that
4085: recognize RTL structures like this:
4086:
1.1.1.5 root 4087: @smallexample
1.1 root 4088: (set (strict_low_part (subreg:QI (reg:SI @dots{}) 0)) @dots{})
1.1.1.5 root 4089: @end smallexample
1.1 root 4090:
4091: @noindent
4092: and likewise for @code{HImode}.
4093:
4094: @findex SLOW_UNALIGNED_ACCESS
4095: @item SLOW_UNALIGNED_ACCESS
1.1.1.2 root 4096: Define this macro to be the value 1 if unaligned accesses have a cost
4097: many times greater than aligned accesses, for example if they are
4098: emulated in a trap handler.
1.1 root 4099:
1.1.1.2 root 4100: When this macro is non-zero, the compiler will act as if
4101: @code{STRICT_ALIGNMENT} were non-zero when generating code for block
1.1 root 4102: moves. This can cause significantly more instructions to be produced.
1.1.1.2 root 4103: Therefore, do not set this macro non-zero if unaligned accesses only add a
1.1 root 4104: cycle or two to the time for a memory access.
4105:
1.1.1.2 root 4106: If the value of this macro is always zero, it need not be defined.
4107:
1.1 root 4108: @findex DONT_REDUCE_ADDR
4109: @item DONT_REDUCE_ADDR
4110: Define this macro to inhibit strength reduction of memory addresses.
4111: (On some machines, such strength reduction seems to do harm rather
4112: than good.)
4113:
4114: @findex MOVE_RATIO
4115: @item MOVE_RATIO
4116: The number of scalar move insns which should be generated instead of a
4117: string move insn or a library call. Increasing the value will always
4118: make code faster, but eventually incurs high cost in increased code size.
4119:
4120: If you don't define this, a reasonable default is used.
4121:
4122: @findex NO_FUNCTION_CSE
4123: @item NO_FUNCTION_CSE
4124: Define this macro if it is as good or better to call a constant
4125: function address than to call an address kept in a register.
4126:
4127: @findex NO_RECURSIVE_FUNCTION_CSE
4128: @item NO_RECURSIVE_FUNCTION_CSE
4129: Define this macro if it is as good or better for a function to call
4130: itself with an explicit address than to call an address kept in a
4131: register.
1.1.1.4 root 4132:
4133: @findex ADJUST_COST
4134: @item ADJUST_COST (@var{insn}, @var{link}, @var{dep_insn}, @var{cost})
4135: A C statement (sans semicolon) to update the integer variable @var{cost}
4136: based on the relationship between @var{insn} that is dependent on
4137: @var{dep_insn} through the dependence @var{link}. The default is to
4138: make no adjustment to @var{cost}. This can be used for example to
4139: specify to the scheduler that an output- or anti-dependence does not
4140: incur the same cost as a data-dependence.
1.1 root 4141: @end table
4142:
1.1.1.2 root 4143: @node Sections
1.1 root 4144: @section Dividing the Output into Sections (Texts, Data, @dots{})
1.1.1.5 root 4145: @c the above section title is WAY too long. maybe cut the part between
4146: @c the (...)? --mew 10feb93
1.1 root 4147:
4148: An object file is divided into sections containing different types of
4149: data. In the most common case, there are three sections: the @dfn{text
4150: section}, which holds instructions and read-only data; the @dfn{data
4151: section}, which holds initialized writable data; and the @dfn{bss
4152: section}, which holds uninitialized data. Some systems have other kinds
4153: of sections.
4154:
4155: The compiler must tell the assembler when to switch sections. These
4156: macros control what commands to output to tell the assembler this. You
4157: can also define additional sections.
4158:
4159: @table @code
4160: @findex TEXT_SECTION_ASM_OP
4161: @item TEXT_SECTION_ASM_OP
1.1.1.4 root 4162: A C expression whose value is a string containing the assembler
4163: operation that should precede instructions and read-only data. Normally
4164: @code{".text"} is right.
1.1 root 4165:
4166: @findex DATA_SECTION_ASM_OP
4167: @item DATA_SECTION_ASM_OP
1.1.1.4 root 4168: A C expression whose value is a string containing the assembler
4169: operation to identify the following data as writable initialized data.
4170: Normally @code{".data"} is right.
1.1 root 4171:
4172: @findex SHARED_SECTION_ASM_OP
4173: @item SHARED_SECTION_ASM_OP
1.1.1.4 root 4174: if defined, a C expression whose value is a string containing the
4175: assembler operation to identify the following data as shared data. If
4176: not defined, @code{DATA_SECTION_ASM_OP} will be used.
1.1 root 4177:
4178: @findex INIT_SECTION_ASM_OP
4179: @item INIT_SECTION_ASM_OP
1.1.1.4 root 4180: if defined, a C expression whose value is a string containing the
4181: assembler operation to identify the following data as initialization
4182: code. If not defined, GNU CC will assume such a section does not
4183: exist.
1.1 root 4184:
4185: @findex EXTRA_SECTIONS
4186: @findex in_text
4187: @findex in_data
4188: @item EXTRA_SECTIONS
4189: A list of names for sections other than the standard two, which are
4190: @code{in_text} and @code{in_data}. You need not define this macro
4191: on a system with no other sections (that GCC needs to use).
4192:
4193: @findex EXTRA_SECTION_FUNCTIONS
4194: @findex text_section
4195: @findex data_section
4196: @item EXTRA_SECTION_FUNCTIONS
4197: One or more functions to be defined in @file{varasm.c}. These
4198: functions should do jobs analogous to those of @code{text_section} and
4199: @code{data_section}, for your additional sections. Do not define this
4200: macro if you do not define @code{EXTRA_SECTIONS}.
4201:
4202: @findex READONLY_DATA_SECTION
4203: @item READONLY_DATA_SECTION
4204: On most machines, read-only variables, constants, and jump tables are
4205: placed in the text section. If this is not the case on your machine,
4206: this macro should be defined to be the name of a function (either
4207: @code{data_section} or a function defined in @code{EXTRA_SECTIONS}) that
4208: switches to the section to be used for read-only items.
4209:
4210: If these items should be placed in the text section, this macro should
4211: not be defined.
4212:
4213: @findex SELECT_SECTION
4214: @item SELECT_SECTION (@var{exp}, @var{reloc})
4215: A C statement or statements to switch to the appropriate section for
4216: output of @var{exp}. You can assume that @var{exp} is either a
4217: @code{VAR_DECL} node or a constant of some sort. @var{reloc}
4218: indicates whether the initial value of @var{exp} requires link-time
4219: relocations. Select the section by calling @code{text_section} or one
4220: of the alternatives for other sections.
4221:
4222: Do not define this macro if you put all read-only variables and
4223: constants in the read-only data section (usually the text section).
4224:
4225: @findex SELECT_RTX_SECTION
4226: @item SELECT_RTX_SECTION (@var{mode}, @var{rtx})
4227: A C statement or statements to switch to the appropriate section for
4228: output of @var{rtx} in mode @var{mode}. You can assume that @var{rtx}
4229: is some kind of constant in RTL. The argument @var{mode} is redundant
4230: except in the case of a @code{const_int} rtx. Select the section by
4231: calling @code{text_section} or one of the alternatives for other
4232: sections.
4233:
4234: Do not define this macro if you put all constants in the read-only
4235: data section.
4236:
4237: @findex JUMP_TABLES_IN_TEXT_SECTION
4238: @item JUMP_TABLES_IN_TEXT_SECTION
4239: Define this macro if jump tables (for @code{tablejump} insns) should be
4240: output in the text section, along with the assembler instructions.
4241: Otherwise, the readonly data section is used.
4242:
4243: This macro is irrelevant if there is no separate readonly data section.
4244:
4245: @findex ENCODE_SECTION_INFO
4246: @item ENCODE_SECTION_INFO (@var{decl})
4247: Define this macro if references to a symbol must be treated differently
4248: depending on something about the variable or function named by the
4249: symbol (such as what section it is in).
4250:
4251: The macro definition, if any, is executed immediately after the rtl for
4252: @var{decl} has been created and stored in @code{DECL_RTL (@var{decl})}.
4253: The value of the rtl will be a @code{mem} whose address is a
4254: @code{symbol_ref}.
4255:
4256: @cindex @code{SYMBOL_REF_FLAG}, in @code{ENCODE_SECTION_INFO}
4257: The usual thing for this macro to do is to record a flag in the
4258: @code{symbol_ref} (such as @code{SYMBOL_REF_FLAG}) or to store a
4259: modified name string in the @code{symbol_ref} (if one bit is not enough
4260: information).
1.1.1.4 root 4261:
4262: @findex STRIP_NAME_ENCODING
4263: @item STRIP_NAME_ENCODING (@var{var}, @var{sym_name})
4264: Decode @var{sym_name} and store the real name part in @var{var}, sans
4265: the characters that encode section info. Define this macro if
4266: @code{ENCODE_SECTION_INFO} alters the symbol's name string.
1.1 root 4267: @end table
4268:
1.1.1.2 root 4269: @node PIC
1.1 root 4270: @section Position Independent Code
4271: @cindex position independent code
4272: @cindex PIC
4273:
4274: This section describes macros that help implement generation of position
4275: independent code. Simply defining these macros is not enough to
4276: generate valid PIC; you must also add support to the macros
1.1.1.5 root 4277: @code{GO_IF_LEGITIMATE_ADDRESS} and @code{PRINT_OPERAND_ADDRESS}, as
4278: well as @code{LEGITIMIZE_ADDRESS}. You must modify the definition of
1.1 root 4279: @samp{movsi} to do something appropriate when the source operand
4280: contains a symbolic address. You may also need to alter the handling of
4281: switch statements so that they use relative addresses.
1.1.1.5 root 4282: @c i rearranged the order of the macros above to try to force one of
4283: @c them to the next line, to eliminate an overfull hbox. --mew 10feb93
1.1 root 4284:
4285: @table @code
4286: @findex PIC_OFFSET_TABLE_REGNUM
4287: @item PIC_OFFSET_TABLE_REGNUM
4288: The register number of the register used to address a table of static
4289: data addresses in memory. In some cases this register is defined by a
4290: processor's ``application binary interface'' (ABI). When this macro
4291: is defined, RTL is generated for this register once, as with the stack
4292: pointer and frame pointer registers. If this macro is not defined, it
4293: is up to the machine-dependent files to allocate such a register (if
4294: necessary).
4295:
1.1.1.8 ! root 4296: @findex PIC_OFFSET_TABLE_REG_CALL_CLOBBERED
1.1.1.7 root 4297: @item PIC_OFFSET_TABLE_REG_CALL_CLOBBERED
4298: Define this macro if the register defined by
4299: @code{PIC_OFFSET_TABLE_REGNUM} is clobbered by calls. Do not define
4300: this macro if @code{PPIC_OFFSET_TABLE_REGNUM} is not defined.
4301:
1.1 root 4302: @findex FINALIZE_PIC
4303: @item FINALIZE_PIC
4304: By generating position-independent code, when two different programs (A
4305: and B) share a common library (libC.a), the text of the library can be
4306: shared whether or not the library is linked at the same address for both
4307: programs. In some of these environments, position-independent code
4308: requires not only the use of different addressing modes, but also
4309: special code to enable the use of these addressing modes.
4310:
4311: The @code{FINALIZE_PIC} macro serves as a hook to emit these special
4312: codes once the function is being compiled into assembly code, but not
4313: before. (It is not done before, because in the case of compiling an
4314: inline function, it would lead to multiple PIC prologues being
4315: included in functions which used inline functions and were compiled to
4316: assembly language.)
4317:
1.1.1.4 root 4318: @findex LEGITIMATE_PIC_OPERAND_P
4319: @item LEGITIMATE_PIC_OPERAND_P (@var{x})
4320: A C expression that is nonzero if @var{x} is a legitimate immediate
4321: operand on the target machine when generating position independent code.
4322: You can assume that @var{x} satisfies @code{CONSTANT_P}, so you need not
4323: check this. You can also assume @var{flag_pic} is true, so you need not
4324: check it either. You need not define this macro if all constants
4325: (including @code{SYMBOL_REF}) can be immediate operands when generating
4326: position independent code.
1.1 root 4327: @end table
4328:
1.1.1.2 root 4329: @node Assembler Format
1.1 root 4330: @section Defining the Output Assembler Language
4331:
4332: This section describes macros whose principal purpose is to describe how
4333: to write instructions in assembler language--rather than what the
4334: instructions do.
4335:
4336: @menu
4337: * File Framework:: Structural information for the assembler file.
4338: * Data Output:: Output of constants (numbers, strings, addresses).
4339: * Uninitialized Data:: Output of uninitialized variables.
4340: * Label Output:: Output and generation of labels.
1.1.1.4 root 4341: * Initialization:: General principles of initialization
4342: and termination routines.
4343: * Macros for Initialization::
4344: Specific macros that control the handling of
4345: initialization and termination routines.
1.1 root 4346: * Instruction Output:: Output of actual instructions.
4347: * Dispatch Tables:: Output of jump tables.
4348: * Alignment Output:: Pseudo ops for alignment and skipping data.
4349: @end menu
4350:
1.1.1.2 root 4351: @node File Framework
1.1 root 4352: @subsection The Overall Framework of an Assembler File
4353: @cindex assembler format
4354: @cindex output of assembler code
4355:
1.1.1.7 root 4356: @c prevent bad page break with this line
4357: This describes the overall framework of an assembler file.
4358:
1.1 root 4359: @table @code
4360: @findex ASM_FILE_START
4361: @item ASM_FILE_START (@var{stream})
4362: A C expression which outputs to the stdio stream @var{stream}
4363: some appropriate text to go at the start of an assembler file.
4364:
4365: Normally this macro is defined to output a line containing
4366: @samp{#NO_APP}, which is a comment that has no effect on most
4367: assemblers but tells the GNU assembler that it can save time by not
4368: checking for certain assembler constructs.
4369:
4370: On systems that use SDB, it is necessary to output certain commands;
4371: see @file{attasm.h}.
4372:
4373: @findex ASM_FILE_END
4374: @item ASM_FILE_END (@var{stream})
4375: A C expression which outputs to the stdio stream @var{stream}
4376: some appropriate text to go at the end of an assembler file.
4377:
4378: If this macro is not defined, the default is to output nothing
4379: special at the end of the file. Most systems don't require any
4380: definition.
4381:
4382: On systems that use SDB, it is necessary to output certain commands;
4383: see @file{attasm.h}.
4384:
4385: @findex ASM_IDENTIFY_GCC
4386: @item ASM_IDENTIFY_GCC (@var{file})
4387: A C statement to output assembler commands which will identify
4388: the object file as having been compiled with GNU CC (or another
4389: GNU compiler).
4390:
4391: If you don't define this macro, the string @samp{gcc_compiled.:}
4392: is output. This string is calculated to define a symbol which,
4393: on BSD systems, will never be defined for any other reason.
4394: GDB checks for the presence of this symbol when reading the
4395: symbol table of an executable.
4396:
4397: On non-BSD systems, you must arrange communication with GDB in
4398: some other fashion. If GDB is not used on your system, you can
4399: define this macro with an empty body.
4400:
4401: @findex ASM_COMMENT_START
4402: @item ASM_COMMENT_START
4403: A C string constant describing how to begin a comment in the target
4404: assembler language. The compiler assumes that the comment will end at
4405: the end of the line.
4406:
4407: @findex ASM_APP_ON
4408: @item ASM_APP_ON
4409: A C string constant for text to be output before each @code{asm}
4410: statement or group of consecutive ones. Normally this is
4411: @code{"#APP"}, which is a comment that has no effect on most
4412: assemblers but tells the GNU assembler that it must check the lines
4413: that follow for all valid assembler constructs.
4414:
4415: @findex ASM_APP_OFF
4416: @item ASM_APP_OFF
4417: A C string constant for text to be output after each @code{asm}
4418: statement or group of consecutive ones. Normally this is
4419: @code{"#NO_APP"}, which tells the GNU assembler to resume making the
4420: time-saving assumptions that are valid for ordinary compiler output.
4421:
4422: @findex ASM_OUTPUT_SOURCE_FILENAME
4423: @item ASM_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name})
4424: A C statement to output COFF information or DWARF debugging information
4425: which indicates that filename @var{name} is the current source file to
4426: the stdio stream @var{stream}.
4427:
4428: This macro need not be defined if the standard form of output
4429: for the file format in use is appropriate.
4430:
4431: @findex ASM_OUTPUT_SOURCE_LINE
4432: @item ASM_OUTPUT_SOURCE_LINE (@var{stream}, @var{line})
4433: A C statement to output DBX or SDB debugging information before code
4434: for line number @var{line} of the current source file to the
4435: stdio stream @var{stream}.
4436:
4437: This macro need not be defined if the standard form of debugging
4438: information for the debugger in use is appropriate.
4439:
4440: @findex ASM_OUTPUT_IDENT
4441: @item ASM_OUTPUT_IDENT (@var{stream}, @var{string})
4442: A C statement to output something to the assembler file to handle a
4443: @samp{#ident} directive containing the text @var{string}. If this
4444: macro is not defined, nothing is output for a @samp{#ident} directive.
4445:
1.1.1.7 root 4446: @findex ASM_OUTPUT_SECTION_NAME
1.1.1.8 ! root 4447: @item ASM_OUTPUT_SECTION_NAME (@var{stream}, @var{decl}, @var{name})
! 4448: A C statement to output something to the assembler file to switch to section
! 4449: @var{name} for object @var{decl} which is either a @code{FUNCTION_DECL}, a
! 4450: @code{VAR_DECL} or @code{NULL_TREE}. Some target formats do not support
1.1.1.7 root 4451: arbitrary sections. Do not define this macro in such cases.
4452:
4453: At present this macro is only used to support section attributes.
4454: When this macro is undefined, section attributes are disabled.
4455:
1.1 root 4456: @findex OBJC_PROLOGUE
4457: @item OBJC_PROLOGUE
4458: A C statement to output any assembler statements which are required to
4459: precede any Objective C object definitions or message sending. The
4460: statement is executed only when compiling an Objective C program.
4461: @end table
4462:
1.1.1.6 root 4463: @need 2000
1.1.1.2 root 4464: @node Data Output
1.1 root 4465: @subsection Output of Data
4466:
1.1.1.7 root 4467: @c prevent bad page break with this line
4468: This describes data output.
4469:
1.1 root 4470: @table @code
4471: @findex ASM_OUTPUT_LONG_DOUBLE
4472: @findex ASM_OUTPUT_DOUBLE
4473: @findex ASM_OUTPUT_FLOAT
4474: @item ASM_OUTPUT_LONG_DOUBLE (@var{stream}, @var{value})
1.1.1.5 root 4475: @itemx ASM_OUTPUT_DOUBLE (@var{stream}, @var{value})
4476: @itemx ASM_OUTPUT_FLOAT (@var{stream}, @var{value})
1.1.1.7 root 4477: @itemx ASM_OUTPUT_THREE_QUARTER_FLOAT (@var{stream}, @var{value})
4478: @itemx ASM_OUTPUT_SHORT_FLOAT (@var{stream}, @var{value})
4479: @itemx ASM_OUTPUT_BYTE_FLOAT (@var{stream}, @var{value})
1.1 root 4480: A C statement to output to the stdio stream @var{stream} an assembler
4481: instruction to assemble a floating-point constant of @code{TFmode},
1.1.1.7 root 4482: @code{DFmode}, @code{SFmode}, @code{TQFmode}, @code{HFmode}, or
4483: @code{QFmode}, respectively, whose value is @var{value}. @var{value}
4484: will be a C expression of type @code{REAL_VALUE_TYPE}. Macros such as
1.1.1.5 root 4485: @code{REAL_VALUE_TO_TARGET_DOUBLE} are useful for writing these
4486: definitions.
1.1 root 4487:
4488: @findex ASM_OUTPUT_QUADRUPLE_INT
4489: @findex ASM_OUTPUT_DOUBLE_INT
4490: @findex ASM_OUTPUT_INT
4491: @findex ASM_OUTPUT_SHORT
4492: @findex ASM_OUTPUT_CHAR
4493: @findex output_addr_const
4494: @item ASM_OUTPUT_QUADRUPLE_INT (@var{stream}, @var{exp})
1.1.1.5 root 4495: @itemx ASM_OUTPUT_DOUBLE_INT (@var{stream}, @var{exp})
4496: @itemx ASM_OUTPUT_INT (@var{stream}, @var{exp})
1.1 root 4497: @itemx ASM_OUTPUT_SHORT (@var{stream}, @var{exp})
4498: @itemx ASM_OUTPUT_CHAR (@var{stream}, @var{exp})
4499: A C statement to output to the stdio stream @var{stream} an assembler
4500: instruction to assemble an integer of 16, 8, 4, 2 or 1 bytes,
4501: respectively, whose value is @var{value}. The argument @var{exp} will
4502: be an RTL expression which represents a constant value. Use
4503: @samp{output_addr_const (@var{stream}, @var{exp})} to output this value
4504: as an assembler expression.@refill
4505:
4506: For sizes larger than @code{UNITS_PER_WORD}, if the action of a macro
4507: would be identical to repeatedly calling the macro corresponding to
4508: a size of @code{UNITS_PER_WORD}, once for each word, you need not define
4509: the macro.
4510:
4511: @findex ASM_OUTPUT_BYTE
4512: @item ASM_OUTPUT_BYTE (@var{stream}, @var{value})
4513: A C statement to output to the stdio stream @var{stream} an assembler
4514: instruction to assemble a single byte containing the number @var{value}.
4515:
4516: @findex ASM_BYTE_OP
4517: @item ASM_BYTE_OP
4518: A C string constant giving the pseudo-op to use for a sequence of
4519: single-byte constants. If this macro is not defined, the default is
4520: @code{"byte"}.
4521:
4522: @findex ASM_OUTPUT_ASCII
4523: @item ASM_OUTPUT_ASCII (@var{stream}, @var{ptr}, @var{len})
4524: A C statement to output to the stdio stream @var{stream} an assembler
4525: instruction to assemble a string constant containing the @var{len}
4526: bytes at @var{ptr}. @var{ptr} will be a C expression of type
4527: @code{char *} and @var{len} a C expression of type @code{int}.
4528:
4529: If the assembler has a @code{.ascii} pseudo-op as found in the
4530: Berkeley Unix assembler, do not define the macro
4531: @code{ASM_OUTPUT_ASCII}.
4532:
4533: @findex ASM_OUTPUT_POOL_PROLOGUE
4534: @item ASM_OUTPUT_POOL_PROLOGUE (@var{file} @var{funname} @var{fundecl} @var{size})
4535: A C statement to output assembler commands to define the start of the
4536: constant pool for a function. @var{funname} is a string giving
4537: the name of the function. Should the return type of the function
4538: be required, it can be obtained via @var{fundecl}. @var{size}
4539: is the size, in bytes, of the constant pool that will be written
4540: immediately after this call.
4541:
4542: If no constant-pool prefix is required, the usual case, this macro need
4543: not be defined.
4544:
4545: @findex ASM_OUTPUT_SPECIAL_POOL_ENTRY
4546: @item ASM_OUTPUT_SPECIAL_POOL_ENTRY (@var{file}, @var{x}, @var{mode}, @var{align}, @var{labelno}, @var{jumpto})
4547: A C statement (with or without semicolon) to output a constant in the
4548: constant pool, if it needs special treatment. (This macro need not do
4549: anything for RTL expressions that can be output normally.)
4550:
4551: The argument @var{file} is the standard I/O stream to output the
4552: assembler code on. @var{x} is the RTL expression for the constant to
4553: output, and @var{mode} is the machine mode (in case @var{x} is a
4554: @samp{const_int}). @var{align} is the required alignment for the value
4555: @var{x}; you should output an assembler directive to force this much
4556: alignment.
4557:
4558: The argument @var{labelno} is a number to use in an internal label for
4559: the address of this pool entry. The definition of this macro is
4560: responsible for outputting the label definition at the proper place.
4561: Here is how to do this:
4562:
4563: @example
4564: ASM_OUTPUT_INTERNAL_LABEL (@var{file}, "LC", @var{labelno});
4565: @end example
4566:
4567: When you output a pool entry specially, you should end with a
4568: @code{goto} to the label @var{jumpto}. This will prevent the same pool
4569: entry from being output a second time in the usual manner.
4570:
4571: You need not define this macro if it would do nothing.
4572:
1.1.1.7 root 4573: @findex IS_ASM_LOGICAL_LINE_SEPARATOR
4574: @item IS_ASM_LOGICAL_LINE_SEPARATOR (@var{C})
4575: Define this macro as a C expression which is nonzero if @var{C} is
4576: used as a logical line separator by the assembler.
4577:
4578: If you do not define this macro, the default is that only
4579: the character @samp{;} is treated as a logical line separator.
4580:
4581:
1.1 root 4582: @findex ASM_OPEN_PAREN
4583: @findex ASM_CLOSE_PAREN
4584: @item ASM_OPEN_PAREN
4585: @itemx ASM_CLOSE_PAREN
4586: These macros are defined as C string constant, describing the syntax
4587: in the assembler for grouping arithmetic expressions. The following
4588: definitions are correct for most assemblers:
4589:
4590: @example
4591: #define ASM_OPEN_PAREN "("
4592: #define ASM_CLOSE_PAREN ")"
4593: @end example
4594: @end table
4595:
1.1.1.5 root 4596: These macros are provided by @file{real.h} for writing the definitions
4597: of @code{ASM_OUTPUT_DOUBLE} and the like:
4598:
4599: @table @code
4600: @item REAL_VALUE_TO_TARGET_SINGLE (@var{x}, @var{l})
4601: @itemx REAL_VALUE_TO_TARGET_DOUBLE (@var{x}, @var{l})
4602: @itemx REAL_VALUE_TO_TARGET_LONG_DOUBLE (@var{x}, @var{l})
4603: @findex REAL_VALUE_TO_TARGET_SINGLE
4604: @findex REAL_VALUE_TO_TARGET_DOUBLE
4605: @findex REAL_VALUE_TO_TARGET_LONG_DOUBLE
4606: These translate @var{x}, of type @code{REAL_VALUE_TYPE}, to the target's
4607: floating point representation, and store its bit pattern in the array of
4608: @code{long int} whose address is @var{l}. The number of elements in the
4609: output array is determined by the size of the desired target floating
4610: point data type: 32 bits of it go in each @code{long int} array
4611: element. Each array element holds 32 bits of the result, even if
4612: @code{long int} is wider than 32 bits on the host machine.
4613:
4614: The array element values are designed so that you can print them out
4615: using @code{fprintf} in the order they should appear in the target
4616: machine's memory.
4617:
4618: @item REAL_VALUE_TO_DECIMAL (@var{x}, @var{format}, @var{string})
4619: @findex REAL_VALUE_TO_DECIMAL
4620: This macro converts @var{x}, of type @code{REAL_VALUE_TYPE}, to a
4621: decimal number and stores it as a string into @var{string}.
4622: You must pass, as @var{string}, the address of a long enough block
4623: of space to hold the result.
4624:
4625: The argument @var{format} is a @code{printf}-specification that serves
4626: as a suggestion for how to format the output string.
4627: @end table
4628:
1.1.1.2 root 4629: @node Uninitialized Data
1.1 root 4630: @subsection Output of Uninitialized Variables
4631:
4632: Each of the macros in this section is used to do the whole job of
4633: outputting a single uninitialized variable.
4634:
4635: @table @code
4636: @findex ASM_OUTPUT_COMMON
4637: @item ASM_OUTPUT_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
4638: A C statement (sans semicolon) to output to the stdio stream
4639: @var{stream} the assembler definition of a common-label named
4640: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
4641: is the size rounded up to whatever alignment the caller wants.
4642:
4643: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
4644: output the name itself; before and after that, output the additional
4645: assembler syntax for defining the name, and a newline.
4646:
4647: This macro controls how the assembler definitions of uninitialized
4648: global variables are output.
4649:
4650: @findex ASM_OUTPUT_ALIGNED_COMMON
4651: @item ASM_OUTPUT_ALIGNED_COMMON (@var{stream}, @var{name}, @var{size}, @var{alignment})
4652: Like @code{ASM_OUTPUT_COMMON} except takes the required alignment as a
4653: separate, explicit argument. If you define this macro, it is used in
4654: place of @code{ASM_OUTPUT_COMMON}, and gives you more flexibility in
1.1.1.7 root 4655: handling the required alignment of the variable. The alignment is specified
4656: as the number of bits.
1.1 root 4657:
4658: @findex ASM_OUTPUT_SHARED_COMMON
4659: @item ASM_OUTPUT_SHARED_COMMON (@var{stream}, @var{name}, @var{size}, @var{rounded})
4660: If defined, it is similar to @code{ASM_OUTPUT_COMMON}, except that it
4661: is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_COMMON}
4662: will be used.
4663:
4664: @findex ASM_OUTPUT_LOCAL
4665: @item ASM_OUTPUT_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
4666: A C statement (sans semicolon) to output to the stdio stream
4667: @var{stream} the assembler definition of a local-common-label named
4668: @var{name} whose size is @var{size} bytes. The variable @var{rounded}
4669: is the size rounded up to whatever alignment the caller wants.
4670:
4671: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
4672: output the name itself; before and after that, output the additional
4673: assembler syntax for defining the name, and a newline.
4674:
4675: This macro controls how the assembler definitions of uninitialized
4676: static variables are output.
4677:
4678: @findex ASM_OUTPUT_ALIGNED_LOCAL
4679: @item ASM_OUTPUT_ALIGNED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{alignment})
4680: Like @code{ASM_OUTPUT_LOCAL} except takes the required alignment as a
4681: separate, explicit argument. If you define this macro, it is used in
4682: place of @code{ASM_OUTPUT_LOCAL}, and gives you more flexibility in
1.1.1.7 root 4683: handling the required alignment of the variable. The alignment is specified
4684: as the number of bits.
1.1 root 4685:
4686: @findex ASM_OUTPUT_SHARED_LOCAL
4687: @item ASM_OUTPUT_SHARED_LOCAL (@var{stream}, @var{name}, @var{size}, @var{rounded})
4688: If defined, it is similar to @code{ASM_OUTPUT_LOCAL}, except that it
4689: is used when @var{name} is shared. If not defined, @code{ASM_OUTPUT_LOCAL}
4690: will be used.
4691: @end table
4692:
1.1.1.2 root 4693: @node Label Output
1.1 root 4694: @subsection Output and Generation of Labels
4695:
1.1.1.7 root 4696: @c prevent bad page break with this line
4697: This is about outputting labels.
4698:
1.1 root 4699: @table @code
4700: @findex ASM_OUTPUT_LABEL
4701: @findex assemble_name
4702: @item ASM_OUTPUT_LABEL (@var{stream}, @var{name})
4703: A C statement (sans semicolon) to output to the stdio stream
4704: @var{stream} the assembler definition of a label named @var{name}.
4705: Use the expression @code{assemble_name (@var{stream}, @var{name})} to
4706: output the name itself; before and after that, output the additional
4707: assembler syntax for defining the name, and a newline.
4708:
4709: @findex ASM_DECLARE_FUNCTION_NAME
4710: @item ASM_DECLARE_FUNCTION_NAME (@var{stream}, @var{name}, @var{decl})
4711: A C statement (sans semicolon) to output to the stdio stream
4712: @var{stream} any text necessary for declaring the name @var{name} of a
4713: function which is being defined. This macro is responsible for
4714: outputting the label definition (perhaps using
4715: @code{ASM_OUTPUT_LABEL}). The argument @var{decl} is the
4716: @code{FUNCTION_DECL} tree node representing the function.
4717:
4718: If this macro is not defined, then the function name is defined in the
4719: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
4720:
4721: @findex ASM_DECLARE_FUNCTION_SIZE
4722: @item ASM_DECLARE_FUNCTION_SIZE (@var{stream}, @var{name}, @var{decl})
4723: A C statement (sans semicolon) to output to the stdio stream
4724: @var{stream} any text necessary for declaring the size of a function
4725: which is being defined. The argument @var{name} is the name of the
4726: function. The argument @var{decl} is the @code{FUNCTION_DECL} tree node
4727: representing the function.
4728:
4729: If this macro is not defined, then the function size is not defined.
4730:
4731: @findex ASM_DECLARE_OBJECT_NAME
4732: @item ASM_DECLARE_OBJECT_NAME (@var{stream}, @var{name}, @var{decl})
4733: A C statement (sans semicolon) to output to the stdio stream
4734: @var{stream} any text necessary for declaring the name @var{name} of an
4735: initialized variable which is being defined. This macro must output the
4736: label definition (perhaps using @code{ASM_OUTPUT_LABEL}). The argument
4737: @var{decl} is the @code{VAR_DECL} tree node representing the variable.
4738:
4739: If this macro is not defined, then the variable name is defined in the
4740: usual manner as a label (by means of @code{ASM_OUTPUT_LABEL}).
4741:
1.1.1.6 root 4742: @findex ASM_FINISH_DECLARE_OBJECT
4743: @item ASM_FINISH_DECLARE_OBJECT (@var{stream}, @var{decl}, @var{toplevel}, @var{atend})
4744: A C statement (sans semicolon) to finish up declaring a variable name
4745: once the compiler has processed its initializer fully and thus has had a
4746: chance to determine the size of an array when controlled by an
4747: initializer. This is used on systems where it's necessary to declare
4748: something about the size of the object.
4749:
4750: If you don't define this macro, that is equivalent to defining it to do
4751: nothing.
4752:
1.1 root 4753: @findex ASM_GLOBALIZE_LABEL
4754: @item ASM_GLOBALIZE_LABEL (@var{stream}, @var{name})
4755: A C statement (sans semicolon) to output to the stdio stream
4756: @var{stream} some commands that will make the label @var{name} global;
4757: that is, available for reference from other files. Use the expression
4758: @code{assemble_name (@var{stream}, @var{name})} to output the name
4759: itself; before and after that, output the additional assembler syntax
4760: for making that name global, and a newline.
4761:
1.1.1.8 ! root 4762: @findex ASM_WEAKEN_LABEL
! 4763: @item ASM_WEAKEN_LABEL
! 4764: A C statement (sans semicolon) to output to the stdio stream
! 4765: @var{stream} some commands that will make the label @var{name} weak;
! 4766: that is, available for reference from other files but only used if
! 4767: no other definition is available. Use the expression
! 4768: @code{assemble_name (@var{stream}, @var{name})} to output the name
! 4769: itself; before and after that, output the additional assembler syntax
! 4770: for making that name weak, and a newline.
! 4771:
! 4772: If you don't define this macro, GNU CC will not support weak
! 4773: symbols and you should not define the @code{SUPPORTS_WEAK} macro.
! 4774:
! 4775: @findex SUPPORTS_WEAK
! 4776: @item SUPPORTS_WEAK
! 4777: A C expression which evaluates to true if the target supports weak symbols.
! 4778:
! 4779: If you don't define this macro, @file{defaults.h} provides a default
! 4780: definition. If @code{ASM_WEAKEN_LABEL} is defined, the default
! 4781: definition is @samp{1}; otherwise, it is @samp{0}. Define this macro if
! 4782: you want to control weak symbol support with a compiler flag such as
! 4783: @samp{-melf}.
! 4784:
1.1 root 4785: @findex ASM_OUTPUT_EXTERNAL
4786: @item ASM_OUTPUT_EXTERNAL (@var{stream}, @var{decl}, @var{name})
4787: A C statement (sans semicolon) to output to the stdio stream
4788: @var{stream} any text necessary for declaring the name of an external
4789: symbol named @var{name} which is referenced in this compilation but
4790: not defined. The value of @var{decl} is the tree node for the
4791: declaration.
4792:
4793: This macro need not be defined if it does not need to output anything.
4794: The GNU assembler and most Unix assemblers don't require anything.
4795:
4796: @findex ASM_OUTPUT_EXTERNAL_LIBCALL
4797: @item ASM_OUTPUT_EXTERNAL_LIBCALL (@var{stream}, @var{symref})
4798: A C statement (sans semicolon) to output on @var{stream} an assembler
4799: pseudo-op to declare a library function name external. The name of the
4800: library function is given by @var{symref}, which has type @code{rtx} and
4801: is a @code{symbol_ref}.
4802:
4803: This macro need not be defined if it does not need to output anything.
4804: The GNU assembler and most Unix assemblers don't require anything.
4805:
4806: @findex ASM_OUTPUT_LABELREF
4807: @item ASM_OUTPUT_LABELREF (@var{stream}, @var{name})
4808: A C statement (sans semicolon) to output to the stdio stream
4809: @var{stream} a reference in assembler syntax to a label named
4810: @var{name}. This should add @samp{_} to the front of the name, if that
4811: is customary on your operating system, as it is in most Berkeley Unix
4812: systems. This macro is used in @code{assemble_name}.
4813:
1.1.1.6 root 4814: @ignore @c Seems not to exist anymore.
1.1 root 4815: @findex ASM_OUTPUT_LABELREF_AS_INT
4816: @item ASM_OUTPUT_LABELREF_AS_INT (@var{file}, @var{label})
4817: Define this macro for systems that use the program @code{collect2}.
4818: The definition should be a C statement to output a word containing
4819: a reference to the label @var{label}.
1.1.1.6 root 4820: @end ignore
1.1 root 4821:
4822: @findex ASM_OUTPUT_INTERNAL_LABEL
4823: @item ASM_OUTPUT_INTERNAL_LABEL (@var{stream}, @var{prefix}, @var{num})
4824: A C statement to output to the stdio stream @var{stream} a label whose
4825: name is made from the string @var{prefix} and the number @var{num}.
1.1.1.2 root 4826:
4827: It is absolutely essential that these labels be distinct from the labels
4828: used for user-level functions and variables. Otherwise, certain programs
4829: will have name conflicts with internal labels.
4830:
4831: It is desirable to exclude internal labels from the symbol table of the
4832: object file. Most assemblers have a naming convention for labels that
4833: should be excluded; on many systems, the letter @samp{L} at the
4834: beginning of a label has this effect. You should find out what
4835: convention your system uses, and follow it.
4836:
4837: The usual definition of this macro is as follows:
1.1 root 4838:
4839: @example
4840: fprintf (@var{stream}, "L%s%d:\n", @var{prefix}, @var{num})
4841: @end example
4842:
1.1.1.2 root 4843: @findex ASM_GENERATE_INTERNAL_LABEL
4844: @item ASM_GENERATE_INTERNAL_LABEL (@var{string}, @var{prefix}, @var{num})
4845: A C statement to store into the string @var{string} a label whose name
4846: is made from the string @var{prefix} and the number @var{num}.
4847:
1.1.1.5 root 4848: This string, when output subsequently by @code{assemble_name}, should
4849: produce the output that @code{ASM_OUTPUT_INTERNAL_LABEL} would produce
4850: with the same @var{prefix} and @var{num}.
1.1.1.2 root 4851:
4852: If the string begins with @samp{*}, then @code{assemble_name} will
4853: output the rest of the string unchanged. It is often convenient for
4854: @code{ASM_GENERATE_INTERNAL_LABEL} to use @samp{*} in this way. If the
4855: string doesn't start with @samp{*}, then @code{ASM_OUTPUT_LABELREF} gets
4856: to output the string, and may change it. (Of course,
4857: @code{ASM_OUTPUT_LABELREF} is also part of your machine description, so
4858: you should know what it does on your machine.)
4859:
1.1 root 4860: @findex ASM_FORMAT_PRIVATE_NAME
4861: @item ASM_FORMAT_PRIVATE_NAME (@var{outvar}, @var{name}, @var{number})
4862: A C expression to assign to @var{outvar} (which is a variable of type
4863: @code{char *}) a newly allocated string made from the string
4864: @var{name} and the number @var{number}, with some suitable punctuation
4865: added. Use @code{alloca} to get space for the string.
4866:
1.1.1.5 root 4867: The string will be used as an argument to @code{ASM_OUTPUT_LABELREF} to
4868: produce an assembler label for an internal static variable whose name is
4869: @var{name}. Therefore, the string must be such as to result in valid
4870: assembler code. The argument @var{number} is different each time this
4871: macro is executed; it prevents conflicts between similarly-named
4872: internal static variables in different scopes.
1.1 root 4873:
4874: Ideally this string should not be a valid C identifier, to prevent any
4875: conflict with the user's own symbols. Most assemblers allow periods
4876: or percent signs in assembler symbols; putting at least one of these
4877: between the name and the number will suffice.
4878:
1.1.1.7 root 4879: @findex ASM_OUTPUT_DEF
4880: @item ASM_OUTPUT_DEF (@var{stream}, @var{name}, @var{value})
4881: A C statement to output to the stdio stream @var{stream} assembler code
4882: which defines (equates) the symbol @var{name} to have the value @var{value}.
4883:
4884: If SET_ASM_OP is defined, a default definition is provided which is
4885: correct for most systems.
1.1 root 4886: @findex OBJC_GEN_METHOD_LABEL
4887: @item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name})
4888: Define this macro to override the default assembler names used for
4889: Objective C methods.
4890:
4891: The default name is a unique method number followed by the name of the
4892: class (e.g.@: @samp{_1_Foo}). For methods in categories, the name of
4893: the category is also included in the assembler name (e.g.@:
4894: @samp{_1_Foo_Bar}).
4895:
4896: These names are safe on most systems, but make debugging difficult since
4897: the method's selector is not present in the name. Therefore, particular
4898: systems define other ways of computing names.
4899:
1.1.1.2 root 4900: @var{buf} is an expression of type @code{char *} which gives you a
4901: buffer in which to store the name; its length is as long as
4902: @var{class_name}, @var{cat_name} and @var{sel_name} put together, plus
4903: 50 characters extra.
4904:
4905: The argument @var{is_inst} specifies whether the method is an instance
4906: method or a class method; @var{class_name} is the name of the class;
4907: @var{cat_name} is the name of the category (or NULL if the method is not
4908: in a category); and @var{sel_name} is the name of the selector.
1.1 root 4909:
4910: On systems where the assembler can handle quoted names, you can use this
4911: macro to provide more human-readable names.
4912: @end table
4913:
1.1.1.4 root 4914: @node Initialization
4915: @subsection How Initialization Functions Are Handled
1.1 root 4916: @cindex initialization routines
4917: @cindex termination routines
4918: @cindex constructors, output of
4919: @cindex destructors, output of
4920:
4921: The compiled code for certain languages includes @dfn{constructors}
4922: (also called @dfn{initialization routines})---functions to initialize
4923: data in the program when the program is started. These functions need
4924: to be called before the program is ``started''---that is to say, before
4925: @code{main} is called.
4926:
4927: Compiling some languages generates @dfn{destructors} (also called
4928: @dfn{termination routines}) that should be called when the program
4929: terminates.
4930:
4931: To make the initialization and termination functions work, the compiler
4932: must output something in the assembler code to cause those functions to
4933: be called at the appropriate time. When you port the compiler to a new
1.1.1.4 root 4934: system, you need to specify how to do this.
1.1 root 4935:
1.1.1.4 root 4936: There are two major ways that GCC currently supports the execution of
4937: initialization and termination functions. Each way has two variants.
4938: Much of the structure is common to all four variations.
4939:
4940: @findex __CTOR_LIST__
4941: @findex __DTOR_LIST__
4942: The linker must build two lists of these functions---a list of
4943: initialization functions, called @code{__CTOR_LIST__}, and a list of
4944: termination functions, called @code{__DTOR_LIST__}.
4945:
4946: Each list always begins with an ignored function pointer (which may hold
4947: 0, @minus{}1, or a count of the function pointers after it, depending on
4948: the environment). This is followed by a series of zero or more function
4949: pointers to constructors (or destructors), followed by a function
4950: pointer containing zero.
4951:
4952: Depending on the operating system and its executable file format, either
4953: @file{crtstuff.c} or @file{libgcc2.c} traverses these lists at startup
1.1.1.8 ! root 4954: time and exit time. Constructors are called in reverse order of the
! 4955: list; destructors in forward order.
1.1.1.4 root 4956:
4957: The best way to handle static constructors works only for object file
4958: formats which provide arbitrarily-named sections. A section is set
4959: aside for a list of constructors, and another for a list of destructors.
4960: Traditionally these are called @samp{.ctors} and @samp{.dtors}. Each
4961: object file that defines an initialization function also puts a word in
4962: the constructor section to point to that function. The linker
4963: accumulates all these words into one contiguous @samp{.ctors} section.
4964: Termination functions are handled similarly.
4965:
4966: To use this method, you need appropriate definitions of the macros
4967: @code{ASM_OUTPUT_CONSTRUCTOR} and @code{ASM_OUTPUT_DESTRUCTOR}. Usually
4968: you can get them by including @file{svr4.h}.
4969:
4970: When arbitrary sections are available, there are two variants, depending
4971: upon how the code in @file{crtstuff.c} is called. On systems that
4972: support an @dfn{init} section which is executed at program startup,
4973: parts of @file{crtstuff.c} are compiled into that section. The
4974: program is linked by the @code{gcc} driver like this:
4975:
4976: @example
4977: ld -o @var{output_file} crtbegin.o @dots{} crtend.o -lgcc
4978: @end example
4979:
4980: The head of a function (@code{__do_global_ctors}) appears in the init
4981: section of @file{crtbegin.o}; the remainder of the function appears in
4982: the init section of @file{crtend.o}. The linker will pull these two
4983: parts of the section together, making a whole function. If any of the
4984: user's object files linked into the middle of it contribute code, then that
4985: code will be executed as part of the body of @code{__do_global_ctors}.
4986:
4987: To use this variant, you must define the @code{INIT_SECTION_ASM_OP}
4988: macro properly.
4989:
4990: If no init section is available, do not define
4991: @code{INIT_SECTION_ASM_OP}. Then @code{__do_global_ctors} is built into
4992: the text section like all other functions, and resides in
4993: @file{libgcc.a}. When GCC compiles any function called @code{main}, it
4994: inserts a procedure call to @code{__main} as the first executable code
4995: after the function prologue. The @code{__main} function, also defined
4996: in @file{libgcc2.c}, simply calls @file{__do_global_ctors}.
4997:
4998: In file formats that don't support arbitrary sections, there are again
4999: two variants. In the simplest variant, the GNU linker (GNU @code{ld})
5000: and an `a.out' format must be used. In this case,
5001: @code{ASM_OUTPUT_CONSTRUCTOR} is defined to produce a @code{.stabs}
5002: entry of type @samp{N_SETT}, referencing the name @code{__CTOR_LIST__},
5003: and with the address of the void function containing the initialization
5004: code as its value. The GNU linker recognizes this as a request to add
5005: the value to a ``set''; the values are accumulated, and are eventually
5006: placed in the executable as a vector in the format described above, with
5007: a leading (ignored) count and a trailing zero element.
5008: @code{ASM_OUTPUT_DESTRUCTOR} is handled similarly. Since no init
5009: section is available, the absence of @code{INIT_SECTION_ASM_OP} causes
5010: the compilation of @code{main} to call @code{__main} as above, starting
5011: the initialization process.
5012:
5013: The last variant uses neither arbitrary sections nor the GNU linker.
5014: This is preferable when you want to do dynamic linking and when using
5015: file formats which the GNU linker does not support, such as `ECOFF'. In
5016: this case, @code{ASM_OUTPUT_CONSTRUCTOR} does not produce an
5017: @code{N_SETT} symbol; initialization and termination functions are
5018: recognized simply by their names. This requires an extra program in the
5019: linkage step, called @code{collect2}. This program pretends to be the
5020: linker, for use with GNU CC; it does its job by running the ordinary
5021: linker, but also arranges to include the vectors of initialization and
5022: termination functions. These functions are called via @code{__main} as
5023: described above.
5024:
5025: Choosing among these configuration options has been simplified by a set
5026: of operating-system-dependent files in the @file{config} subdirectory.
5027: These files define all of the relevant parameters. Usually it is
5028: sufficient to include one into your specific machine-dependent
5029: configuration file. These files are:
5030:
5031: @table @file
5032: @item aoutos.h
5033: For operating systems using the `a.out' format.
5034:
5035: @item next.h
5036: For operating systems using the `MachO' format.
5037:
5038: @item svr3.h
5039: For System V Release 3 and similar systems using `COFF' format.
5040:
5041: @item svr4.h
5042: For System V Release 4 and similar systems using `ELF' format.
5043:
5044: @item vms.h
5045: For the VMS operating system.
5046: @end table
5047:
5048: @ifinfo
5049: The following section describes the specific macros that control and
5050: customize the handling of initialization and termination functions.
5051: @end ifinfo
5052:
5053: @node Macros for Initialization
5054: @subsection Macros Controlling Initialization Routines
5055:
5056: Here are the macros that control how the compiler handles initialization
5057: and termination functions:
1.1 root 5058:
5059: @table @code
1.1.1.4 root 5060: @findex INIT_SECTION_ASM_OP
5061: @item INIT_SECTION_ASM_OP
5062: If defined, a C string constant for the assembler operation to identify
5063: the following data as initialization code. If not defined, GNU CC will
5064: assume such a section does not exist. When you are using special
5065: sections for initialization and termination functions, this macro also
5066: controls how @file{crtstuff.c} and @file{libgcc2.c} arrange to run the
5067: initialization functions.
5068:
1.1.1.7 root 5069: @item HAS_INIT_SECTION
5070: @findex HAS_INIT_SECTION
5071: If defined, @code{main} will not call @code{__main} as described above.
5072: This macro should be defined for systems that control the contents of the
5073: init section on a symbol-by-symbol basis, such as OSF/1, and should not
5074: be defined explicitly for systems that support
5075: @code{INIT_SECTION_ASM_OP}.
5076:
1.1.1.8 ! root 5077: @item LD_INIT_SWITCH
! 5078: @findex LD_INIT_SWITCH
! 5079: If defined, a C string constant for a switch that tells the linker that
! 5080: the following symbol is an initialization routine.
! 5081:
! 5082: @item LD_FINI_SWITCH
! 5083: @findex LD_FINI_SWITCH
! 5084: If defined, a C string constant for a switch that tells the linker that
! 5085: the following symbol is a finalization routine.
! 5086:
1.1.1.7 root 5087: @item INVOKE__main
5088: @findex INVOKE__main
5089: If defined, @code{main} will call @code{__main} despite the presence of
5090: @code{INIT_SECTION_ASM_OP}. This macro should be defined for systems
5091: where the init section is not actually run automatically, but is still
5092: useful for collecting the lists of constructors and destructors.
5093:
1.1 root 5094: @item ASM_OUTPUT_CONSTRUCTOR (@var{stream}, @var{name})
5095: @findex ASM_OUTPUT_CONSTRUCTOR
5096: Define this macro as a C statement to output on the stream @var{stream}
5097: the assembler code to arrange to call the function named @var{name} at
5098: initialization time.
5099:
5100: Assume that @var{name} is the name of a C function generated
5101: automatically by the compiler. This function takes no arguments. Use
5102: the function @code{assemble_name} to output the name @var{name}; this
5103: performs any system-specific syntactic transformations such as adding an
5104: underscore.
5105:
5106: If you don't define this macro, nothing special is output to arrange to
5107: call the function. This is correct when the function will be called in
1.1.1.4 root 5108: some other manner---for example, by means of the @code{collect2} program,
1.1 root 5109: which looks through the symbol table to find these functions by their
1.1.1.5 root 5110: names.
1.1 root 5111:
5112: @item ASM_OUTPUT_DESTRUCTOR (@var{stream}, @var{name})
5113: @findex ASM_OUTPUT_DESTRUCTOR
5114: This is like @code{ASM_OUTPUT_CONSTRUCTOR} but used for termination
5115: functions rather than initialization functions.
5116: @end table
5117:
1.1.1.3 root 5118: If your system uses @code{collect2} as the means of processing
5119: constructors, then that program normally uses @code{nm} to scan an
5120: object file for constructor functions to be called. On certain kinds of
5121: systems, you can define these macros to make @code{collect2} work faster
5122: (and, in some cases, make it work at all):
5123:
5124: @table @code
5125: @findex OBJECT_FORMAT_COFF
5126: @item OBJECT_FORMAT_COFF
5127: Define this macro if the system uses COFF (Common Object File Format)
5128: object files, so that @code{collect2} can assume this format and scan
5129: object files directly for dynamic constructor/destructor functions.
5130:
5131: @findex OBJECT_FORMAT_ROSE
5132: @item OBJECT_FORMAT_ROSE
5133: Define this macro if the system uses ROSE format object files, so that
5134: @code{collect2} can assume this format and scan object files directly
5135: for dynamic constructor/destructor functions.
5136:
1.1.1.8 ! root 5137: These macros are effective only in a native compiler; @code{collect2} as
! 5138: part of a cross compiler always uses @code{nm} for the target machine.
! 5139:
1.1.1.3 root 5140: @findex REAL_NM_FILE_NAME
5141: @item REAL_NM_FILE_NAME
5142: Define this macro as a C string constant containing the file name to use
5143: to execute @code{nm}. The default is to search the path normally for
5144: @code{nm}.
5145:
1.1.1.8 ! root 5146: If your system supports shared libraries and has a program to list the
! 5147: dynamic dependencies of a given library or executable, you can define
! 5148: these macros to enable support for running initialization and
! 5149: termination functions in shared libraries:
! 5150:
! 5151: @findex LDD_SUFFIX
! 5152: @item LDD_SUFFIX
! 5153: Define this macro to a C string constant containing the name of the
! 5154: program which lists dynamic dependencies, like @code{"ldd"} under SunOS 4.
! 5155:
! 5156: @findex PARSE_LDD_OUTPUT
! 5157: @item PARSE_LDD_OUTPUT (@var{PTR})
! 5158: Define this macro to be C code that extracts filenames from the output
! 5159: of the program denoted by @code{LDD_SUFFIX}. @var{PTR} is a variable
! 5160: of type @code{char *} that points to the beginning of a line of output
! 5161: from @code{LDD_SUFFIX}. If the line lists a dynamic dependency, the
! 5162: code must advance @var{PTR} to the beginning of the filename on that
! 5163: line. Otherwise, it must set @var{PTR} to @code{NULL}.
! 5164:
! 5165: @end table
1.1.1.7 root 5166:
1.1.1.2 root 5167: @node Instruction Output
1.1 root 5168: @subsection Output of Assembler Instructions
5169:
1.1.1.7 root 5170: @c prevent bad page break with this line
5171: This describes assembler instruction output.
5172:
1.1 root 5173: @table @code
5174: @findex REGISTER_NAMES
5175: @item REGISTER_NAMES
5176: A C initializer containing the assembler's names for the machine
5177: registers, each one as a C string constant. This is what translates
5178: register numbers in the compiler into assembler language.
5179:
5180: @findex ADDITIONAL_REGISTER_NAMES
5181: @item ADDITIONAL_REGISTER_NAMES
5182: If defined, a C initializer for an array of structures containing a name
5183: and a register number. This macro defines additional names for hard
5184: registers, thus allowing the @code{asm} option in declarations to refer
5185: to registers using alternate names.
5186:
5187: @findex ASM_OUTPUT_OPCODE
5188: @item ASM_OUTPUT_OPCODE (@var{stream}, @var{ptr})
5189: Define this macro if you are using an unusual assembler that
5190: requires different names for the machine instructions.
5191:
5192: The definition is a C statement or statements which output an
5193: assembler instruction opcode to the stdio stream @var{stream}. The
5194: macro-operand @var{ptr} is a variable of type @code{char *} which
5195: points to the opcode name in its ``internal'' form---the form that is
5196: written in the machine description. The definition should output the
5197: opcode name to @var{stream}, performing any translation you desire, and
5198: increment the variable @var{ptr} to point at the end of the opcode
5199: so that it will not be output twice.
5200:
5201: In fact, your macro definition may process less than the entire opcode
5202: name, or more than the opcode name; but if you want to process text
5203: that includes @samp{%}-sequences to substitute operands, you must take
5204: care of the substitution yourself. Just be sure to increment
5205: @var{ptr} over whatever text should not be output normally.
5206:
5207: @findex recog_operand
5208: If you need to look at the operand values, they can be found as the
5209: elements of @code{recog_operand}.
5210:
5211: If the macro definition does nothing, the instruction is output
5212: in the usual way.
5213:
5214: @findex FINAL_PRESCAN_INSN
5215: @item FINAL_PRESCAN_INSN (@var{insn}, @var{opvec}, @var{noperands})
5216: If defined, a C statement to be executed just prior to the output of
5217: assembler code for @var{insn}, to modify the extracted operands so
5218: they will be output differently.
5219:
5220: Here the argument @var{opvec} is the vector containing the operands
5221: extracted from @var{insn}, and @var{noperands} is the number of
5222: elements of the vector which contain meaningful data for this insn.
5223: The contents of this vector are what will be used to convert the insn
5224: template into assembler code, so you can change the assembler output
5225: by changing the contents of the vector.
5226:
5227: This macro is useful when various assembler syntaxes share a single
5228: file of instruction patterns; by defining this macro differently, you
5229: can cause a large class of instructions to be output differently (such
5230: as with rearranged operands). Naturally, variations in assembler
5231: syntax affecting individual insn patterns ought to be handled by
5232: writing conditional output routines in those patterns.
5233:
5234: If this macro is not defined, it is equivalent to a null statement.
5235:
5236: @findex PRINT_OPERAND
5237: @item PRINT_OPERAND (@var{stream}, @var{x}, @var{code})
5238: A C compound statement to output to stdio stream @var{stream} the
5239: assembler syntax for an instruction operand @var{x}. @var{x} is an
5240: RTL expression.
5241:
5242: @var{code} is a value that can be used to specify one of several ways
5243: of printing the operand. It is used when identical operands must be
5244: printed differently depending on the context. @var{code} comes from
5245: the @samp{%} specification that was used to request printing of the
5246: operand. If the specification was just @samp{%@var{digit}} then
5247: @var{code} is 0; if the specification was @samp{%@var{ltr}
5248: @var{digit}} then @var{code} is the ASCII code for @var{ltr}.
5249:
5250: @findex reg_names
5251: If @var{x} is a register, this macro should print the register's name.
5252: The names can be found in an array @code{reg_names} whose type is
5253: @code{char *[]}. @code{reg_names} is initialized from
5254: @code{REGISTER_NAMES}.
5255:
5256: When the machine description has a specification @samp{%@var{punct}}
5257: (a @samp{%} followed by a punctuation character), this macro is called
5258: with a null pointer for @var{x} and the punctuation character for
5259: @var{code}.
5260:
5261: @findex PRINT_OPERAND_PUNCT_VALID_P
5262: @item PRINT_OPERAND_PUNCT_VALID_P (@var{code})
5263: A C expression which evaluates to true if @var{code} is a valid
5264: punctuation character for use in the @code{PRINT_OPERAND} macro. If
5265: @code{PRINT_OPERAND_PUNCT_VALID_P} is not defined, it means that no
5266: punctuation characters (except for the standard one, @samp{%}) are used
5267: in this way.
5268:
5269: @findex PRINT_OPERAND_ADDRESS
5270: @item PRINT_OPERAND_ADDRESS (@var{stream}, @var{x})
5271: A C compound statement to output to stdio stream @var{stream} the
5272: assembler syntax for an instruction operand that is a memory reference
5273: whose address is @var{x}. @var{x} is an RTL expression.
5274:
5275: @cindex @code{ENCODE_SECTION_INFO} usage
5276: On some machines, the syntax for a symbolic address depends on the
5277: section that the address refers to. On these machines, define the macro
5278: @code{ENCODE_SECTION_INFO} to store the information into the
5279: @code{symbol_ref}, and then check for it here. @xref{Assembler Format}.
5280:
5281: @findex DBR_OUTPUT_SEQEND
5282: @findex dbr_sequence_length
5283: @item DBR_OUTPUT_SEQEND(@var{file})
5284: A C statement, to be executed after all slot-filler instructions have
5285: been output. If necessary, call @code{dbr_sequence_length} to
5286: determine the number of slots filled in a sequence (zero if not
5287: currently outputting a sequence), to decide how many no-ops to output,
5288: or whatever.
5289:
5290: Don't define this macro if it has nothing to do, but it is helpful in
5291: reading assembly output if the extent of the delay sequence is made
5292: explicit (e.g. with white space).
5293:
5294: @findex final_sequence
5295: Note that output routines for instructions with delay slots must be
5296: prepared to deal with not being output as part of a sequence (i.e.
5297: when the scheduling pass is not run, or when no slot fillers could be
5298: found.) The variable @code{final_sequence} is null when not
5299: processing a sequence, otherwise it contains the @code{sequence} rtx
5300: being output.
5301:
5302: @findex REGISTER_PREFIX
5303: @findex LOCAL_LABEL_PREFIX
5304: @findex USER_LABEL_PREFIX
5305: @findex IMMEDIATE_PREFIX
5306: @findex asm_fprintf
5307: @item REGISTER_PREFIX
5308: @itemx LOCAL_LABEL_PREFIX
5309: @itemx USER_LABEL_PREFIX
5310: @itemx IMMEDIATE_PREFIX
5311: If defined, C string expressions to be used for the @samp{%R}, @samp{%L},
5312: @samp{%U}, and @samp{%I} options of @code{asm_fprintf} (see
5313: @file{final.c}). These are useful when a single @file{md} file must
5314: support multiple assembler formats. In that case, the various @file{tm.h}
5315: files can define these macros differently.
5316:
1.1.1.6 root 5317: @findex ASSEMBLER_DIALECT
5318: @item ASSEMBLER_DIALECT
5319: If your target supports multiple dialects of assembler language (such as
5320: different opcodes), define this macro as a C expression that gives the
1.1.1.8 ! root 5321: numeric index of the assembler language dialect to use, with zero as the
1.1.1.6 root 5322: first variant.
5323:
5324: If this macro is defined, you may use
5325: @samp{@{option0|option1|option2@dots{}@}} constructs in the output
5326: templates of patterns (@pxref{Output Template}) or in the first argument
5327: of @code{asm_fprintf}. This construct outputs @samp{option0},
5328: @samp{option1} or @samp{option2}, etc., if the value of
5329: @code{ASSEMBLER_DIALECT} is zero, one or two, etc. Any special
5330: characters within these strings retain their usual meaning.
5331:
5332: If you do not define this macro, the characters @samp{@{}, @samp{|} and
5333: @samp{@}} do not have any special meaning when used in templates or
5334: operands to @code{asm_fprintf}.
5335:
5336: Define the macros @code{REGISTER_PREFIX}, @code{LOCAL_LABEL_PREFIX},
5337: @code{USER_LABEL_PREFIX} and @code{IMMEDIATE_PREFIX} if you can express
5338: the variations in assemble language syntax with that mechanism. Define
5339: @code{ASSEMBLER_DIALECT} and use the @samp{@{option0|option1@}} syntax
5340: if the syntax variant are larger and involve such things as different
5341: opcodes or operand order.
5342:
1.1 root 5343: @findex ASM_OUTPUT_REG_PUSH
5344: @item ASM_OUTPUT_REG_PUSH (@var{stream}, @var{regno})
5345: A C expression to output to @var{stream} some assembler code
5346: which will push hard register number @var{regno} onto the stack.
5347: The code need not be optimal, since this macro is used only when
5348: profiling.
5349:
5350: @findex ASM_OUTPUT_REG_POP
5351: @item ASM_OUTPUT_REG_POP (@var{stream}, @var{regno})
5352: A C expression to output to @var{stream} some assembler code
5353: which will pop hard register number @var{regno} off of the stack.
5354: The code need not be optimal, since this macro is used only when
5355: profiling.
5356: @end table
5357:
1.1.1.2 root 5358: @node Dispatch Tables
1.1 root 5359: @subsection Output of Dispatch Tables
5360:
1.1.1.7 root 5361: @c prevent bad page break with this line
5362: This concerns dispatch tables.
5363:
1.1 root 5364: @table @code
5365: @cindex dispatch table
5366: @findex ASM_OUTPUT_ADDR_DIFF_ELT
5367: @item ASM_OUTPUT_ADDR_DIFF_ELT (@var{stream}, @var{value}, @var{rel})
5368: This macro should be provided on machines where the addresses
5369: in a dispatch table are relative to the table's own address.
5370:
5371: The definition should be a C statement to output to the stdio stream
5372: @var{stream} an assembler pseudo-instruction to generate a difference
5373: between two labels. @var{value} and @var{rel} are the numbers of two
5374: internal labels. The definitions of these labels are output using
5375: @code{ASM_OUTPUT_INTERNAL_LABEL}, and they must be printed in the same
5376: way here. For example,
5377:
5378: @example
5379: fprintf (@var{stream}, "\t.word L%d-L%d\n",
5380: @var{value}, @var{rel})
5381: @end example
5382:
5383: @findex ASM_OUTPUT_ADDR_VEC_ELT
5384: @item ASM_OUTPUT_ADDR_VEC_ELT (@var{stream}, @var{value})
5385: This macro should be provided on machines where the addresses
5386: in a dispatch table are absolute.
5387:
5388: The definition should be a C statement to output to the stdio stream
5389: @var{stream} an assembler pseudo-instruction to generate a reference to
5390: a label. @var{value} is the number of an internal label whose
5391: definition is output using @code{ASM_OUTPUT_INTERNAL_LABEL}.
5392: For example,
5393:
5394: @example
5395: fprintf (@var{stream}, "\t.word L%d\n", @var{value})
5396: @end example
5397:
5398: @findex ASM_OUTPUT_CASE_LABEL
5399: @item ASM_OUTPUT_CASE_LABEL (@var{stream}, @var{prefix}, @var{num}, @var{table})
5400: Define this if the label before a jump-table needs to be output
5401: specially. The first three arguments are the same as for
5402: @code{ASM_OUTPUT_INTERNAL_LABEL}; the fourth argument is the
5403: jump-table which follows (a @code{jump_insn} containing an
5404: @code{addr_vec} or @code{addr_diff_vec}).
5405:
5406: This feature is used on system V to output a @code{swbeg} statement
5407: for the table.
5408:
5409: If this macro is not defined, these labels are output with
5410: @code{ASM_OUTPUT_INTERNAL_LABEL}.
5411:
5412: @findex ASM_OUTPUT_CASE_END
5413: @item ASM_OUTPUT_CASE_END (@var{stream}, @var{num}, @var{table})
5414: Define this if something special must be output at the end of a
5415: jump-table. The definition should be a C statement to be executed
5416: after the assembler code for the table is written. It should write
5417: the appropriate code to stdio stream @var{stream}. The argument
5418: @var{table} is the jump-table insn, and @var{num} is the label-number
5419: of the preceding label.
5420:
5421: If this macro is not defined, nothing special is output at the end of
5422: the jump-table.
5423: @end table
5424:
1.1.1.2 root 5425: @node Alignment Output
1.1 root 5426: @subsection Assembler Commands for Alignment
5427:
1.1.1.7 root 5428: @c prevent bad page break with this line
5429: This describes commands for alignment.
5430:
1.1 root 5431: @table @code
5432: @findex ASM_OUTPUT_ALIGN_CODE
5433: @item ASM_OUTPUT_ALIGN_CODE (@var{file})
5434: A C expression to output text to align the location counter in the way
5435: that is desirable at a point in the code that is reached only by
5436: jumping.
5437:
5438: This macro need not be defined if you don't want any special alignment
5439: to be done at such a time. Most machine descriptions do not currently
5440: define the macro.
5441:
5442: @findex ASM_OUTPUT_LOOP_ALIGN
5443: @item ASM_OUTPUT_LOOP_ALIGN (@var{file})
5444: A C expression to output text to align the location counter in the way
5445: that is desirable at the beginning of a loop.
5446:
5447: This macro need not be defined if you don't want any special alignment
5448: to be done at such a time. Most machine descriptions do not currently
5449: define the macro.
5450:
5451: @findex ASM_OUTPUT_SKIP
5452: @item ASM_OUTPUT_SKIP (@var{stream}, @var{nbytes})
5453: A C statement to output to the stdio stream @var{stream} an assembler
5454: instruction to advance the location counter by @var{nbytes} bytes.
5455: Those bytes should be zero when loaded. @var{nbytes} will be a C
5456: expression of type @code{int}.
5457:
5458: @findex ASM_NO_SKIP_IN_TEXT
5459: @item ASM_NO_SKIP_IN_TEXT
5460: Define this macro if @code{ASM_OUTPUT_SKIP} should not be used in the
5461: text section because it fails put zeros in the bytes that are skipped.
5462: This is true on many Unix systems, where the pseudo--op to skip bytes
5463: produces no-op instructions rather than zeros when used in the text
5464: section.
5465:
5466: @findex ASM_OUTPUT_ALIGN
5467: @item ASM_OUTPUT_ALIGN (@var{stream}, @var{power})
5468: A C statement to output to the stdio stream @var{stream} an assembler
5469: command to advance the location counter to a multiple of 2 to the
5470: @var{power} bytes. @var{power} will be a C expression of type @code{int}.
5471: @end table
5472:
1.1.1.6 root 5473: @need 3000
1.1.1.2 root 5474: @node Debugging Info
1.1 root 5475: @section Controlling Debugging Information Format
1.1.1.7 root 5476:
5477: @c prevent bad page break with this line
5478: This describes how to specify debugging information.
1.1 root 5479:
1.1.1.3 root 5480: @menu
5481: * All Debuggers:: Macros that affect all debugging formats uniformly.
5482: * DBX Options:: Macros enabling specific options in DBX format.
5483: * DBX Hooks:: Hook macros for varying DBX format.
5484: * File Names and DBX:: Macros controlling output of file names in DBX format.
5485: * SDB and DWARF:: Macros for SDB (COFF) and DWARF formats.
5486: @end menu
5487:
5488: @node All Debuggers
5489: @subsection Macros Affecting All Debugging Formats
5490:
1.1.1.7 root 5491: @c prevent bad page break with this line
5492: These macros affect all debugging formats.
5493:
1.1 root 5494: @table @code
5495: @findex DBX_REGISTER_NUMBER
5496: @item DBX_REGISTER_NUMBER (@var{regno})
5497: A C expression that returns the DBX register number for the compiler
5498: register number @var{regno}. In simple cases, the value of this
5499: expression may be @var{regno} itself. But sometimes there are some
5500: registers that the compiler knows about and DBX does not, or vice
5501: versa. In such cases, some register may need to have one number in
5502: the compiler and another for DBX.
5503:
5504: If two registers have consecutive numbers inside GNU CC, and they can be
5505: used as a pair to hold a multiword value, then they @emph{must} have
5506: consecutive numbers after renumbering with @code{DBX_REGISTER_NUMBER}.
5507: Otherwise, debuggers will be unable to access such a pair, because they
5508: expect register pairs to be consecutive in their own numbering scheme.
5509:
5510: If you find yourself defining @code{DBX_REGISTER_NUMBER} in way that
5511: does not preserve register pairs, then what you must do instead is
5512: redefine the actual register numbering scheme.
5513:
1.1.1.3 root 5514: @findex DEBUGGER_AUTO_OFFSET
5515: @item DEBUGGER_AUTO_OFFSET (@var{x})
5516: A C expression that returns the integer offset value for an automatic
5517: variable having address @var{x} (an RTL expression). The default
5518: computation assumes that @var{x} is based on the frame-pointer and
5519: gives the offset from the frame-pointer. This is required for targets
5520: that produce debugging output for DBX or COFF-style debugging output
5521: for SDB and allow the frame-pointer to be eliminated when the
5522: @samp{-g} options is used.
5523:
5524: @findex DEBUGGER_ARG_OFFSET
5525: @item DEBUGGER_ARG_OFFSET (@var{offset}, @var{x})
5526: A C expression that returns the integer offset value for an argument
5527: having address @var{x} (an RTL expression). The nominal offset is
5528: @var{offset}.
1.1.1.6 root 5529:
5530: @findex PREFERRED_DEBUGGING_TYPE
5531: @item PREFERRED_DEBUGGING_TYPE
5532: A C expression that returns the type of debugging output GNU CC produces
5533: when the user specifies @samp{-g} or @samp{-ggdb}. Define this if you
5534: have arranged for GNU CC to support more than one format of debugging
5535: output. Currently, the allowable values are @code{DBX_DEBUG},
5536: @code{SDB_DEBUG}, @code{DWARF_DEBUG}, and @code{XCOFF_DEBUG}.
5537:
5538: The value of this macro only affects the default debugging output; the
5539: user can always get a specific type of output by using @samp{-gstabs},
5540: @samp{-gcoff}, @samp{-gdwarf}, or @samp{-gxcoff}.
1.1.1.3 root 5541: @end table
5542:
5543: @node DBX Options
5544: @subsection Specific Options for DBX Output
5545:
1.1.1.7 root 5546: @c prevent bad page break with this line
5547: These are specific options for DBX output.
5548:
1.1.1.3 root 5549: @table @code
1.1 root 5550: @findex DBX_DEBUGGING_INFO
5551: @item DBX_DEBUGGING_INFO
5552: Define this macro if GNU CC should produce debugging output for DBX
5553: in response to the @samp{-g} option.
5554:
1.1.1.2 root 5555: @findex XCOFF_DEBUGGING_INFO
5556: @item XCOFF_DEBUGGING_INFO
5557: Define this macro if GNU CC should produce XCOFF format debugging output
1.1.1.3 root 5558: in response to the @samp{-g} option. This is a variant of DBX format.
1.1.1.2 root 5559:
1.1 root 5560: @findex DEFAULT_GDB_EXTENSIONS
5561: @item DEFAULT_GDB_EXTENSIONS
5562: Define this macro to control whether GNU CC should by default generate
5563: GDB's extended version of DBX debugging information (assuming DBX-format
5564: debugging information is enabled at all). If you don't define the
1.1.1.3 root 5565: macro, the default is 1: always generate the extended information
5566: if there is any occasion to.
1.1 root 5567:
5568: @findex DEBUG_SYMS_TEXT
5569: @item DEBUG_SYMS_TEXT
5570: Define this macro if all @code{.stabs} commands should be output while
5571: in the text section.
5572:
5573: @findex ASM_STABS_OP
5574: @item ASM_STABS_OP
5575: A C string constant naming the assembler pseudo op to use instead of
5576: @code{.stabs} to define an ordinary debugging symbol. If you don't
5577: define this macro, @code{.stabs} is used. This macro applies only to
5578: DBX debugging information format.
5579:
5580: @findex ASM_STABD_OP
5581: @item ASM_STABD_OP
5582: A C string constant naming the assembler pseudo op to use instead of
5583: @code{.stabd} to define a debugging symbol whose value is the current
5584: location. If you don't define this macro, @code{.stabd} is used.
5585: This macro applies only to DBX debugging information format.
5586:
5587: @findex ASM_STABN_OP
5588: @item ASM_STABN_OP
5589: A C string constant naming the assembler pseudo op to use instead of
5590: @code{.stabn} to define a debugging symbol with no name. If you don't
5591: define this macro, @code{.stabn} is used. This macro applies only to
5592: DBX debugging information format.
5593:
5594: @findex DBX_NO_XREFS
5595: @item DBX_NO_XREFS
5596: Define this macro if DBX on your system does not support the construct
5597: @samp{xs@var{tagname}}. On some systems, this construct is used to
5598: describe a forward reference to a structure named @var{tagname}.
5599: On other systems, this construct is not supported at all.
5600:
5601: @findex DBX_CONTIN_LENGTH
5602: @item DBX_CONTIN_LENGTH
5603: A symbol name in DBX-format debugging information is normally
5604: continued (split into two separate @code{.stabs} directives) when it
5605: exceeds a certain length (by default, 80 characters). On some
5606: operating systems, DBX requires this splitting; on others, splitting
5607: must not be done. You can inhibit splitting by defining this macro
5608: with the value zero. You can override the default splitting-length by
5609: defining this macro as an expression for the length you desire.
5610:
5611: @findex DBX_CONTIN_CHAR
5612: @item DBX_CONTIN_CHAR
5613: Normally continuation is indicated by adding a @samp{\} character to
5614: the end of a @code{.stabs} string when a continuation follows. To use
5615: a different character instead, define this macro as a character
5616: constant for the character you want to use. Do not define this macro
5617: if backslash is correct for your system.
5618:
5619: @findex DBX_STATIC_STAB_DATA_SECTION
5620: @item DBX_STATIC_STAB_DATA_SECTION
5621: Define this macro if it is necessary to go to the data section before
5622: outputting the @samp{.stabs} pseudo-op for a non-global static
5623: variable.
5624:
1.1.1.3 root 5625: @findex DBX_TYPE_DECL_STABS_CODE
5626: @item DBX_TYPE_DECL_STABS_CODE
5627: The value to use in the ``code'' field of the @code{.stabs} directive
5628: for a typedef. The default is @code{N_LSYM}.
5629:
5630: @findex DBX_STATIC_CONST_VAR_CODE
5631: @item DBX_STATIC_CONST_VAR_CODE
5632: The value to use in the ``code'' field of the @code{.stabs} directive
5633: for a static variable located in the text section. DBX format does not
5634: provide any ``right'' way to do this. The default is @code{N_FUN}.
5635:
5636: @findex DBX_REGPARM_STABS_CODE
5637: @item DBX_REGPARM_STABS_CODE
5638: The value to use in the ``code'' field of the @code{.stabs} directive
5639: for a parameter passed in registers. DBX format does not provide any
5640: ``right'' way to do this. The default is @code{N_RSYM}.
5641:
5642: @findex DBX_REGPARM_STABS_LETTER
5643: @item DBX_REGPARM_STABS_LETTER
5644: The letter to use in DBX symbol data to identify a symbol as a parameter
5645: passed in registers. DBX format does not customarily provide any way to
5646: do this. The default is @code{'P'}.
5647:
5648: @findex DBX_MEMPARM_STABS_LETTER
5649: @item DBX_MEMPARM_STABS_LETTER
5650: The letter to use in DBX symbol data to identify a symbol as a stack
5651: parameter. The default is @code{'p'}.
1.1 root 5652:
5653: @findex DBX_FUNCTION_FIRST
5654: @item DBX_FUNCTION_FIRST
5655: Define this macro if the DBX information for a function and its
5656: arguments should precede the assembler code for the function. Normally,
5657: in DBX format, the debugging information entirely follows the assembler
5658: code.
5659:
1.1.1.3 root 5660: @findex DBX_LBRAC_FIRST
5661: @item DBX_LBRAC_FIRST
5662: Define this macro if the @code{N_LBRAC} symbol for a block should
5663: precede the debugging information for variables and functions defined in
5664: that block. Normally, in DBX format, the @code{N_LBRAC} symbol comes
5665: first.
1.1.1.7 root 5666:
5667: @findex DBX_BLOCKS_FUNCTION_RELATIVE
5668: @item DBX_BLOCKS_FUNCTION_RELATIVE
5669: Define this macro if the value of a symbol describing the scope of a
5670: block (@code{N_LBRAC} or @code{N_RBRAC}) should be relative to the start
5671: of the enclosing function. Normally, GNU C uses an absolute address.
1.1.1.3 root 5672: @end table
5673:
5674: @node DBX Hooks
5675: @subsection Open-Ended Hooks for DBX Format
5676:
1.1.1.7 root 5677: @c prevent bad page break with this line
5678: These are hooks for DBX format.
5679:
1.1.1.3 root 5680: @table @code
5681: @findex DBX_OUTPUT_LBRAC
5682: @item DBX_OUTPUT_LBRAC (@var{stream}, @var{name})
5683: Define this macro to say how to output to @var{stream} the debugging
5684: information for the start of a scope level for variable names. The
5685: argument @var{name} is the name of an assembler symbol (for use with
5686: @code{assemble_name}) whose value is the address where the scope begins.
5687:
5688: @findex DBX_OUTPUT_RBRAC
5689: @item DBX_OUTPUT_RBRAC (@var{stream}, @var{name})
5690: Like @code{DBX_OUTPUT_LBRAC}, but for the end of a scope level.
5691:
5692: @findex DBX_OUTPUT_ENUM
5693: @item DBX_OUTPUT_ENUM (@var{stream}, @var{type})
5694: Define this macro if the target machine requires special handling to
5695: output an enumeration type. The definition should be a C statement
5696: (sans semicolon) to output the appropriate information to @var{stream}
5697: for the type @var{type}.
5698:
1.1 root 5699: @findex DBX_OUTPUT_FUNCTION_END
5700: @item DBX_OUTPUT_FUNCTION_END (@var{stream}, @var{function})
5701: Define this macro if the target machine requires special output at the
5702: end of the debugging information for a function. The definition should
5703: be a C statement (sans semicolon) to output the appropriate information
5704: to @var{stream}. @var{function} is the @code{FUNCTION_DECL} node for
5705: the function.
5706:
5707: @findex DBX_OUTPUT_STANDARD_TYPES
5708: @item DBX_OUTPUT_STANDARD_TYPES (@var{syms})
5709: Define this macro if you need to control the order of output of the
5710: standard data types at the beginning of compilation. The argument
5711: @var{syms} is a @code{tree} which is a chain of all the predefined
5712: global symbols, including names of data types.
5713:
5714: Normally, DBX output starts with definitions of the types for integers
5715: and characters, followed by all the other predefined types of the
5716: particular language in no particular order.
5717:
5718: On some machines, it is necessary to output different particular types
5719: first. To do this, define @code{DBX_OUTPUT_STANDARD_TYPES} to output
5720: those symbols in the necessary order. Any predefined types that you
5721: don't explicitly output will be output afterward in no particular order.
5722:
5723: Be careful not to define this macro so that it works only for C. There
5724: are no global variables to access most of the built-in types, because
5725: another language may have another set of types. The way to output a
5726: particular type is to look through @var{syms} to see if you can find it.
5727: Here is an example:
5728:
1.1.1.5 root 5729: @smallexample
1.1 root 5730: @{
5731: tree decl;
5732: for (decl = syms; decl; decl = TREE_CHAIN (decl))
1.1.1.5 root 5733: if (!strcmp (IDENTIFIER_POINTER (DECL_NAME (decl)),
5734: "long int"))
1.1 root 5735: dbxout_symbol (decl);
5736: @dots{}
5737: @}
1.1.1.5 root 5738: @end smallexample
1.1 root 5739:
5740: @noindent
5741: This does nothing if the expected type does not exist.
5742:
1.1.1.5 root 5743: See the function @code{init_decl_processing} in @file{c-decl.c} to find
5744: the names to use for all the built-in C types.
1.1 root 5745:
1.1.1.3 root 5746: Here is another way of finding a particular type:
5747:
1.1.1.5 root 5748: @c this is still overfull. --mew 10feb93
5749: @smallexample
1.1.1.3 root 5750: @{
5751: tree decl;
5752: for (decl = syms; decl; decl = TREE_CHAIN (decl))
5753: if (TREE_CODE (decl) == TYPE_DECL
1.1.1.5 root 5754: && (TREE_CODE (TREE_TYPE (decl))
5755: == INTEGER_CST)
1.1.1.3 root 5756: && TYPE_PRECISION (TREE_TYPE (decl)) == 16
5757: && TYPE_UNSIGNED (TREE_TYPE (decl)))
1.1.1.6 root 5758: @group
1.1.1.3 root 5759: /* @r{This must be @code{unsigned short}.} */
5760: dbxout_symbol (decl);
5761: @dots{}
5762: @}
1.1.1.6 root 5763: @end group
1.1.1.5 root 5764: @end smallexample
1.1.1.3 root 5765: @end table
5766:
5767: @node File Names and DBX
5768: @subsection File Names in DBX Format
5769:
1.1.1.7 root 5770: @c prevent bad page break with this line
5771: This describes file names in DBX format.
5772:
1.1.1.3 root 5773: @table @code
5774: @findex DBX_WORKING_DIRECTORY
5775: @item DBX_WORKING_DIRECTORY
5776: Define this if DBX wants to have the current directory recorded in each
5777: object file.
5778:
5779: Note that the working directory is always recorded if GDB extensions are
5780: enabled.
5781:
1.1 root 5782: @findex DBX_OUTPUT_MAIN_SOURCE_FILENAME
5783: @item DBX_OUTPUT_MAIN_SOURCE_FILENAME (@var{stream}, @var{name})
5784: A C statement to output DBX debugging information to the stdio stream
5785: @var{stream} which indicates that file @var{name} is the main source
5786: file---the file specified as the input file for compilation.
5787: This macro is called only once, at the beginning of compilation.
5788:
5789: This macro need not be defined if the standard form of output
5790: for DBX debugging information is appropriate.
5791:
5792: @findex DBX_OUTPUT_MAIN_SOURCE_DIRECTORY
5793: @item DBX_OUTPUT_MAIN_SOURCE_DIRECTORY (@var{stream}, @var{name})
5794: A C statement to output DBX debugging information to the stdio stream
5795: @var{stream} which indicates that the current directory during
5796: compilation is named @var{name}.
5797:
5798: This macro need not be defined if the standard form of output
5799: for DBX debugging information is appropriate.
5800:
5801: @findex DBX_OUTPUT_MAIN_SOURCE_FILE_END
5802: @item DBX_OUTPUT_MAIN_SOURCE_FILE_END (@var{stream}, @var{name})
5803: A C statement to output DBX debugging information at the end of
5804: compilation of the main source file @var{name}.
5805:
5806: If you don't define this macro, nothing special is output at the end
5807: of compilation, which is correct for most machines.
5808:
5809: @findex DBX_OUTPUT_SOURCE_FILENAME
5810: @item DBX_OUTPUT_SOURCE_FILENAME (@var{stream}, @var{name})
5811: A C statement to output DBX debugging information to the stdio stream
5812: @var{stream} which indicates that file @var{name} is the current source
5813: file. This output is generated each time input shifts to a different
5814: source file as a result of @samp{#include}, the end of an included file,
5815: or a @samp{#line} command.
5816:
5817: This macro need not be defined if the standard form of output
5818: for DBX debugging information is appropriate.
5819: @end table
5820:
1.1.1.6 root 5821: @need 2000
1.1.1.3 root 5822: @node SDB and DWARF
5823: @subsection Macros for SDB and DWARF Output
5824:
1.1.1.7 root 5825: @c prevent bad page break with this line
5826: Here are macros for SDB and DWARF output.
5827:
1.1.1.3 root 5828: @table @code
5829: @findex SDB_DEBUGGING_INFO
5830: @item SDB_DEBUGGING_INFO
5831: Define this macro if GNU CC should produce COFF-style debugging output
5832: for SDB in response to the @samp{-g} option.
5833:
5834: @findex DWARF_DEBUGGING_INFO
5835: @item DWARF_DEBUGGING_INFO
5836: Define this macro if GNU CC should produce dwarf format debugging output
5837: in response to the @samp{-g} option.
5838:
5839: @findex PUT_SDB_@dots{}
5840: @item PUT_SDB_@dots{}
5841: Define these macros to override the assembler syntax for the special
5842: SDB assembler directives. See @file{sdbout.c} for a list of these
5843: macros and their arguments. If the standard syntax is used, you need
5844: not define them yourself.
5845:
5846: @findex SDB_DELIM
5847: @item SDB_DELIM
5848: Some assemblers do not support a semicolon as a delimiter, even between
5849: SDB assembler directives. In that case, define this macro to be the
5850: delimiter to use (usually @samp{\n}). It is not necessary to define
5851: a new set of @code{PUT_SDB_@var{op}} macros if this is the only change
5852: required.
5853:
5854: @findex SDB_GENERATE_FAKE
5855: @item SDB_GENERATE_FAKE
5856: Define this macro to override the usual method of constructing a dummy
5857: name for anonymous structure and union types. See @file{sdbout.c} for
5858: more information.
5859:
5860: @findex SDB_ALLOW_UNKNOWN_REFERENCES
5861: @item SDB_ALLOW_UNKNOWN_REFERENCES
5862: Define this macro to allow references to unknown structure,
5863: union, or enumeration tags to be emitted. Standard COFF does not
5864: allow handling of unknown references, MIPS ECOFF has support for
5865: it.
5866:
5867: @findex SDB_ALLOW_FORWARD_REFERENCES
5868: @item SDB_ALLOW_FORWARD_REFERENCES
5869: Define this macro to allow references to structure, union, or
5870: enumeration tags that have not yet been seen to be handled. Some
5871: assemblers choke if forward tags are used, while some require it.
5872: @end table
5873:
1.1.1.2 root 5874: @node Cross-compilation
1.1.1.5 root 5875: @section Cross Compilation and Floating Point
1.1 root 5876: @cindex cross compilation and floating point
1.1.1.5 root 5877: @cindex floating point and cross compilation
1.1 root 5878:
5879: While all modern machines use 2's complement representation for integers,
5880: there are a variety of representations for floating point numbers. This
5881: means that in a cross-compiler the representation of floating point numbers
5882: in the compiled program may be different from that used in the machine
5883: doing the compilation.
5884:
5885: @findex atof
5886: Because different representation systems may offer different amounts of
5887: range and precision, the cross compiler cannot safely use the host
5888: machine's floating point arithmetic. Therefore, floating point constants
5889: must be represented in the target machine's format. This means that the
5890: cross compiler cannot use @code{atof} to parse a floating point constant;
5891: it must have its own special routine to use instead. Also, constant
5892: folding must emulate the target machine's arithmetic (or must not be done
5893: at all).
5894:
5895: The macros in the following table should be defined only if you are cross
5896: compiling between different floating point formats.
5897:
1.1.1.5 root 5898: Otherwise, don't define them. Then default definitions will be set up which
1.1 root 5899: use @code{double} as the data type, @code{==} to test for equality, etc.
5900:
5901: You don't need to worry about how many times you use an operand of any
5902: of these macros. The compiler never uses operands which have side effects.
5903:
5904: @table @code
5905: @findex REAL_VALUE_TYPE
5906: @item REAL_VALUE_TYPE
5907: A macro for the C data type to be used to hold a floating point value
5908: in the target machine's format. Typically this would be a
5909: @code{struct} containing an array of @code{int}.
5910:
5911: @findex REAL_VALUES_EQUAL
5912: @item REAL_VALUES_EQUAL (@var{x}, @var{y})
5913: A macro for a C expression which compares for equality the two values,
5914: @var{x} and @var{y}, both of type @code{REAL_VALUE_TYPE}.
5915:
5916: @findex REAL_VALUES_LESS
5917: @item REAL_VALUES_LESS (@var{x}, @var{y})
5918: A macro for a C expression which tests whether @var{x} is less than
5919: @var{y}, both values being of type @code{REAL_VALUE_TYPE} and
5920: interpreted as floating point numbers in the target machine's
5921: representation.
5922:
5923: @findex REAL_VALUE_LDEXP
5924: @findex ldexp
5925: @item REAL_VALUE_LDEXP (@var{x}, @var{scale})
5926: A macro for a C expression which performs the standard library
5927: function @code{ldexp}, but using the target machine's floating point
5928: representation. Both @var{x} and the value of the expression have
5929: type @code{REAL_VALUE_TYPE}. The second argument, @var{scale}, is an
5930: integer.
5931:
5932: @findex REAL_VALUE_FIX
5933: @item REAL_VALUE_FIX (@var{x})
5934: A macro whose definition is a C expression to convert the target-machine
5935: floating point value @var{x} to a signed integer. @var{x} has type
5936: @code{REAL_VALUE_TYPE}.
5937:
5938: @findex REAL_VALUE_UNSIGNED_FIX
5939: @item REAL_VALUE_UNSIGNED_FIX (@var{x})
5940: A macro whose definition is a C expression to convert the target-machine
5941: floating point value @var{x} to an unsigned integer. @var{x} has type
5942: @code{REAL_VALUE_TYPE}.
5943:
1.1.1.5 root 5944: @findex REAL_VALUE_RNDZINT
5945: @item REAL_VALUE_RNDZINT (@var{x})
5946: A macro whose definition is a C expression to round the target-machine
5947: floating point value @var{x} towards zero to an integer value (but still
5948: as a floating point number). @var{x} has type @code{REAL_VALUE_TYPE},
5949: and so does the value.
5950:
5951: @findex REAL_VALUE_UNSIGNED_RNDZINT
5952: @item REAL_VALUE_UNSIGNED_RNDZINT (@var{x})
5953: A macro whose definition is a C expression to round the target-machine
5954: floating point value @var{x} towards zero to an unsigned integer value
5955: (but still represented as a floating point number). @var{x} has type
5956: @code{REAL_VALUE_TYPE}, and so does the value.
1.1 root 5957:
5958: @findex REAL_VALUE_ATOF
1.1.1.5 root 5959: @item REAL_VALUE_ATOF (@var{string}, @var{mode})
5960: A macro for a C expression which converts @var{string}, an expression of
5961: type @code{char *}, into a floating point number in the target machine's
5962: representation for mode @var{mode}. The value has type
5963: @code{REAL_VALUE_TYPE}.
1.1 root 5964:
5965: @findex REAL_INFINITY
5966: @item REAL_INFINITY
5967: Define this macro if infinity is a possible floating point value, and
5968: therefore division by 0 is legitimate.
5969:
5970: @findex REAL_VALUE_ISINF
5971: @findex isinf
5972: @item REAL_VALUE_ISINF (@var{x})
5973: A macro for a C expression which determines whether @var{x}, a floating
5974: point value, is infinity. The value has type @code{int}.
5975: By default, this is defined to call @code{isinf}.
5976:
5977: @findex REAL_VALUE_ISNAN
5978: @findex isnan
5979: @item REAL_VALUE_ISNAN (@var{x})
5980: A macro for a C expression which determines whether @var{x}, a floating
5981: point value, is a ``nan'' (not-a-number). The value has type
5982: @code{int}. By default, this is defined to call @code{isnan}.
5983: @end table
5984:
5985: @cindex constant folding and floating point
5986: Define the following additional macros if you want to make floating
5987: point constant folding work while cross compiling. If you don't
5988: define them, cross compilation is still possible, but constant folding
5989: will not happen for floating point values.
5990:
5991: @table @code
5992: @findex REAL_ARITHMETIC
5993: @item REAL_ARITHMETIC (@var{output}, @var{code}, @var{x}, @var{y})
5994: A macro for a C statement which calculates an arithmetic operation of
5995: the two floating point values @var{x} and @var{y}, both of type
5996: @code{REAL_VALUE_TYPE} in the target machine's representation, to
5997: produce a result of the same type and representation which is stored
5998: in @var{output} (which will be a variable).
5999:
6000: The operation to be performed is specified by @var{code}, a tree code
6001: which will always be one of the following: @code{PLUS_EXPR},
6002: @code{MINUS_EXPR}, @code{MULT_EXPR}, @code{RDIV_EXPR},
6003: @code{MAX_EXPR}, @code{MIN_EXPR}.@refill
6004:
6005: @cindex overflow while constant folding
6006: The expansion of this macro is responsible for checking for overflow.
6007: If overflow happens, the macro expansion should execute the statement
6008: @code{return 0;}, which indicates the inability to perform the
6009: arithmetic operation requested.
6010:
6011: @findex REAL_VALUE_NEGATE
6012: @item REAL_VALUE_NEGATE (@var{x})
6013: A macro for a C expression which returns the negative of the floating
6014: point value @var{x}. Both @var{x} and the value of the expression
6015: have type @code{REAL_VALUE_TYPE} and are in the target machine's
6016: floating point representation.
6017:
6018: There is no way for this macro to report overflow, since overflow
6019: can't happen in the negation operation.
6020:
6021: @findex REAL_VALUE_TRUNCATE
1.1.1.4 root 6022: @item REAL_VALUE_TRUNCATE (@var{mode}, @var{x})
6023: A macro for a C expression which converts the floating point value
6024: @var{x} to mode @var{mode}.
1.1 root 6025:
1.1.1.5 root 6026: Both @var{x} and the value of the expression are in the target machine's
6027: floating point representation and have type @code{REAL_VALUE_TYPE}.
6028: However, the value should have an appropriate bit pattern to be output
6029: properly as a floating constant whose precision accords with mode
6030: @var{mode}.
1.1 root 6031:
6032: There is no way for this macro to report overflow.
6033:
6034: @findex REAL_VALUE_TO_INT
6035: @item REAL_VALUE_TO_INT (@var{low}, @var{high}, @var{x})
6036: A macro for a C expression which converts a floating point value
6037: @var{x} into a double-precision integer which is then stored into
6038: @var{low} and @var{high}, two variables of type @var{int}.
6039:
6040: @item REAL_VALUE_FROM_INT (@var{x}, @var{low}, @var{high})
6041: @findex REAL_VALUE_FROM_INT
6042: A macro for a C expression which converts a double-precision integer
6043: found in @var{low} and @var{high}, two variables of type @var{int},
6044: into a floating point value which is then stored into @var{x}.
6045: @end table
6046:
1.1.1.2 root 6047: @node Misc
1.1 root 6048: @section Miscellaneous Parameters
6049: @cindex parameters, miscellaneous
6050:
1.1.1.7 root 6051: @c prevent bad page break with this line
6052: Here are several miscellaneous parameters.
6053:
1.1 root 6054: @table @code
6055: @item PREDICATE_CODES
6056: @findex PREDICATE_CODES
1.1.1.5 root 6057: Define this if you have defined special-purpose predicates in the file
1.1 root 6058: @file{@var{machine}.c}. This macro is called within an initializer of an
6059: array of structures. The first field in the structure is the name of a
1.1.1.2 root 6060: predicate and the second field is an array of rtl codes. For each
1.1 root 6061: predicate, list all rtl codes that can be in expressions matched by the
6062: predicate. The list should have a trailing comma. Here is an example
6063: of two entries in the list for a typical RISC machine:
6064:
1.1.1.5 root 6065: @smallexample
1.1 root 6066: #define PREDICATE_CODES \
6067: @{"gen_reg_rtx_operand", @{SUBREG, REG@}@}, \
6068: @{"reg_or_short_cint_operand", @{SUBREG, REG, CONST_INT@}@},
1.1.1.5 root 6069: @end smallexample
1.1 root 6070:
6071: Defining this macro does not affect the generated code (however,
6072: incorrect definitions that omit an rtl code that may be matched by the
6073: predicate can cause the compiler to malfunction). Instead, it allows
6074: the table built by @file{genrecog} to be more compact and efficient,
6075: thus speeding up the compiler. The most important predicates to include
6076: in the list specified by this macro are thoses used in the most insn
6077: patterns.
6078:
6079: @findex CASE_VECTOR_MODE
6080: @item CASE_VECTOR_MODE
6081: An alias for a machine mode name. This is the machine mode that
6082: elements of a jump-table should have.
6083:
6084: @findex CASE_VECTOR_PC_RELATIVE
6085: @item CASE_VECTOR_PC_RELATIVE
6086: Define this macro if jump-tables should contain relative addresses.
6087:
6088: @findex CASE_DROPS_THROUGH
6089: @item CASE_DROPS_THROUGH
6090: Define this if control falls through a @code{case} insn when the index
6091: value is out of range. This means the specified default-label is
6092: actually ignored by the @code{case} insn proper.
6093:
1.1.1.4 root 6094: @findex CASE_VALUES_THRESHOLD
6095: @item CASE_VALUES_THRESHOLD
6096: Define this to be the smallest number of different values for which it
6097: is best to use a jump-table instead of a tree of conditional branches.
6098: The default is four for machines with a @code{casesi} instruction and
6099: five otherwise. This is best for most machines.
6100:
1.1.1.6 root 6101: @findex WORD_REGISTER_OPERATIONS
6102: @item WORD_REGISTER_OPERATIONS
6103: Define this macro if operations between registers with integral mode
6104: smaller than a word are always performed on the entire register.
6105: Most RISC machines have this property and most CISC machines do not.
6106:
6107: @findex LOAD_EXTEND_OP
6108: @item LOAD_EXTEND_OP (@var{mode})
6109: Define this macro to be a C expression indicating when insns that read
6110: memory in @var{mode}, an integral mode narrower than a word, set the
6111: bits outside of @var{mode} to be either the sign-extension or the
6112: zero-extension of the data read. Return @code{SIGN_EXTEND} for values
6113: of @var{mode} for which the
6114: insn sign-extends, @code{ZERO_EXTEND} for which it zero-extends, and
6115: @code{NIL} for other modes.
6116:
6117: This macro is not called with @var{mode} non-integral or with a width
6118: greater than or equal to @code{BITS_PER_WORD}, so you may return any
6119: value in this case. Do not define this macro if it would always return
6120: @code{NIL}. On machines where this macro is defined, you will normally
6121: define it as the constant @code{SIGN_EXTEND} or @code{ZERO_EXTEND}.
1.1.1.4 root 6122:
1.1 root 6123: @findex IMPLICIT_FIX_EXPR
6124: @item IMPLICIT_FIX_EXPR
6125: An alias for a tree code that should be used by default for conversion
6126: of floating point values to fixed point. Normally,
6127: @code{FIX_ROUND_EXPR} is used.@refill
6128:
6129: @findex FIXUNS_TRUNC_LIKE_FIX_TRUNC
6130: @item FIXUNS_TRUNC_LIKE_FIX_TRUNC
6131: Define this macro if the same instructions that convert a floating
6132: point number to a signed fixed point number also convert validly to an
6133: unsigned one.
6134:
6135: @findex EASY_DIV_EXPR
6136: @item EASY_DIV_EXPR
6137: An alias for a tree code that is the easiest kind of division to
6138: compile code for in the general case. It may be
6139: @code{TRUNC_DIV_EXPR}, @code{FLOOR_DIV_EXPR}, @code{CEIL_DIV_EXPR} or
6140: @code{ROUND_DIV_EXPR}. These four division operators differ in how
6141: they round the result to an integer. @code{EASY_DIV_EXPR} is used
6142: when it is permissible to use any of those kinds of division and the
6143: choice should be made on the basis of efficiency.@refill
6144:
6145: @findex MOVE_MAX
6146: @item MOVE_MAX
6147: The maximum number of bytes that a single instruction can move quickly
6148: from memory to memory.
6149:
1.1.1.6 root 6150: @findex MAX_MOVE_MAX
6151: @item MAX_MOVE_MAX
6152: The maximum number of bytes that a single instruction can move quickly
6153: from memory to memory. If this is undefined, the default is
6154: @code{MOVE_MAX}. Otherwise, it is the constant value that is the
6155: largest value that @code{MOVE_MAX} can have at run-time.
6156:
1.1 root 6157: @findex SHIFT_COUNT_TRUNCATED
6158: @item SHIFT_COUNT_TRUNCATED
1.1.1.6 root 6159: A C expression that is nonzero if on this machine the number of bits
6160: actually used for the count of a shift operation is equal to the number
6161: of bits needed to represent the size of the object being shifted. When
6162: this macro is non-zero, the compiler will assume that it is safe to omit
6163: a sign-extend, zero-extend, and certain bitwise `and' instructions that
6164: truncates the count of a shift operation. On machines that have
1.1.1.4 root 6165: instructions that act on bitfields at variable positions, which may
1.1.1.6 root 6166: include `bit test' instructions, a nonzero @code{SHIFT_COUNT_TRUNCATED}
1.1.1.4 root 6167: also enables deletion of truncations of the values that serve as
6168: arguments to bitfield instructions.
1.1 root 6169:
6170: If both types of instructions truncate the count (for shifts) and
6171: position (for bitfield operations), or if no variable-position bitfield
6172: instructions exist, you should define this macro.
6173:
1.1.1.2 root 6174: However, on some machines, such as the 80386 and the 680x0, truncation
6175: only applies to shift operations and not the (real or pretended)
1.1.1.6 root 6176: bitfield operations. Define @code{SHIFT_COUNT_TRUNCATED} to be zero on
6177: such machines. Instead, add patterns to the @file{md} file that include
6178: the implied truncation of the shift instructions.
6179:
6180: You need not define this macro if it would always have the value of zero.
1.1 root 6181:
6182: @findex TRULY_NOOP_TRUNCATION
6183: @item TRULY_NOOP_TRUNCATION (@var{outprec}, @var{inprec})
6184: A C expression which is nonzero if on this machine it is safe to
6185: ``convert'' an integer of @var{inprec} bits to one of @var{outprec}
6186: bits (where @var{outprec} is smaller than @var{inprec}) by merely
6187: operating on it as if it had only @var{outprec} bits.
6188:
6189: On many machines, this expression can be 1.
6190:
1.1.1.5 root 6191: @c rearranged this, removed the phrase "it is reported that". this was
6192: @c to fix an overfull hbox. --mew 10feb93
6193: When @code{TRULY_NOOP_TRUNCATION} returns 1 for a pair of sizes for
6194: modes for which @code{MODES_TIEABLE_P} is 0, suboptimal code can result.
6195: If this is the case, making @code{TRULY_NOOP_TRUNCATION} return 0 in
6196: such cases may improve things.
1.1 root 6197:
6198: @findex STORE_FLAG_VALUE
6199: @item STORE_FLAG_VALUE
6200: A C expression describing the value returned by a comparison operator
1.1.1.4 root 6201: with an integral mode and stored by a store-flag instruction
6202: (@samp{s@var{cond}}) when the condition is true. This description must
6203: apply to @emph{all} the @samp{s@var{cond}} patterns and all the
6204: comparison operators whose results have a @code{MODE_INT} mode.
1.1 root 6205:
6206: A value of 1 or -1 means that the instruction implementing the
6207: comparison operator returns exactly 1 or -1 when the comparison is true
6208: and 0 when the comparison is false. Otherwise, the value indicates
6209: which bits of the result are guaranteed to be 1 when the comparison is
6210: true. This value is interpreted in the mode of the comparison
6211: operation, which is given by the mode of the first operand in the
6212: @samp{s@var{cond}} pattern. Either the low bit or the sign bit of
6213: @code{STORE_FLAG_VALUE} be on. Presently, only those bits are used by
6214: the compiler.
6215:
6216: If @code{STORE_FLAG_VALUE} is neither 1 or -1, the compiler will
6217: generate code that depends only on the specified bits. It can also
6218: replace comparison operators with equivalent operations if they cause
6219: the required bits to be set, even if the remaining bits are undefined.
6220: For example, on a machine whose comparison operators return an
6221: @code{SImode} value and where @code{STORE_FLAG_VALUE} is defined as
6222: @samp{0x80000000}, saying that just the sign bit is relevant, the
6223: expression
6224:
1.1.1.5 root 6225: @smallexample
1.1 root 6226: (ne:SI (and:SI @var{x} (const_int @var{power-of-2})) (const_int 0))
1.1.1.5 root 6227: @end smallexample
1.1 root 6228:
6229: @noindent
6230: can be converted to
6231:
1.1.1.5 root 6232: @smallexample
1.1 root 6233: (ashift:SI @var{x} (const_int @var{n}))
1.1.1.5 root 6234: @end smallexample
1.1 root 6235:
6236: @noindent
6237: where @var{n} is the appropriate shift count to move the bit being
6238: tested into the sign bit.
6239:
6240: There is no way to describe a machine that always sets the low-order bit
6241: for a true value, but does not guarantee the value of any other bits,
6242: but we do not know of any machine that has such an instruction. If you
6243: are trying to port GNU CC to such a machine, include an instruction to
6244: perform a logical-and of the result with 1 in the pattern for the
1.1.1.5 root 6245: comparison operators and let us know
6246: @ifset USING
6247: (@pxref{Bug Reporting,,How to Report Bugs}).
6248: @end ifset
6249: @ifclear USING
6250: (@pxref{Bug Reporting,,How to Report Bugs,gcc.info,Using GCC}).
6251: @end ifclear
1.1 root 6252:
6253: Often, a machine will have multiple instructions that obtain a value
6254: from a comparison (or the condition codes). Here are rules to guide the
6255: choice of value for @code{STORE_FLAG_VALUE}, and hence the instructions
6256: to be used:
6257:
6258: @itemize @bullet
6259: @item
6260: Use the shortest sequence that yields a valid definition for
1.1.1.3 root 6261: @code{STORE_FLAG_VALUE}. It is more efficient for the compiler to
1.1 root 6262: ``normalize'' the value (convert it to, e.g., 1 or 0) than for the
6263: comparison operators to do so because there may be opportunities to
6264: combine the normalization with other operations.
6265:
6266: @item
6267: For equal-length sequences, use a value of 1 or -1, with -1 being
6268: slightly preferred on machines with expensive jumps and 1 preferred on
6269: other machines.
6270:
6271: @item
6272: As a second choice, choose a value of @samp{0x80000001} if instructions
6273: exist that set both the sign and low-order bits but do not define the
6274: others.
6275:
6276: @item
6277: Otherwise, use a value of @samp{0x80000000}.
6278: @end itemize
6279:
1.1.1.5 root 6280: Many machines can produce both the value chosen for
6281: @code{STORE_FLAG_VALUE} and its negation in the same number of
6282: instructions. On those machines, you should also define a pattern for
6283: those cases, e.g., one matching
6284:
6285: @smallexample
6286: (set @var{A} (neg:@var{m} (ne:@var{m} @var{B} @var{C})))
6287: @end smallexample
6288:
6289: Some machines can also perform @code{and} or @code{plus} operations on
6290: condition code values with less instructions than the corresponding
6291: @samp{s@var{cond}} insn followed by @code{and} or @code{plus}. On those
6292: machines, define the appropriate patterns. Use the names @code{incscc}
6293: and @code{decscc}, respectively, for the the patterns which perform
6294: @code{plus} or @code{minus} operations on condition code values. See
6295: @file{rs6000.md} for some examples. The GNU Superoptizer can be used to
6296: find such instruction sequences on other machines.
6297:
1.1 root 6298: You need not define @code{STORE_FLAG_VALUE} if the machine has no store-flag
6299: instructions.
6300:
1.1.1.4 root 6301: @findex FLOAT_STORE_FLAG_VALUE
6302: @item FLOAT_STORE_FLAG_VALUE
6303: A C expression that gives a non-zero floating point value that is
6304: returned when comparison operators with floating-point results are true.
6305: Define this macro on machine that have comparison operations that return
6306: floating-point values. If there are no such operations, do not define
6307: this macro.
6308:
1.1 root 6309: @findex Pmode
6310: @item Pmode
1.1.1.8 ! root 6311: An alias for the machine mode for pointers. On most machines, define
! 6312: this to be the integer mode corresponding to the width of a hardware
! 6313: pointer; @code{SImode} on 32-bit machine or @code{DImode} on 64-bit machines.
! 6314: On some machines you must define this to be one of the partial integer
! 6315: modes, such as @code{PSImode}.
! 6316:
! 6317: The width of @code{Pmode} must be at least as large as the value of
! 6318: @code{POINTER_SIZE}. If it is not equal, you must define the macro
! 6319: @code{POINTERS_EXTEND_UNSIGNED} to specify how pointers are extended
! 6320: to @code{Pmode}.
1.1 root 6321:
6322: @findex FUNCTION_MODE
6323: @item FUNCTION_MODE
6324: An alias for the machine mode used for memory references to functions
6325: being called, in @code{call} RTL expressions. On most machines this
6326: should be @code{QImode}.
6327:
6328: @findex INTEGRATE_THRESHOLD
6329: @item INTEGRATE_THRESHOLD (@var{decl})
6330: A C expression for the maximum number of instructions above which the
6331: function @var{decl} should not be inlined. @var{decl} is a
6332: @code{FUNCTION_DECL} node.
6333:
6334: The default definition of this macro is 64 plus 8 times the number of
6335: arguments that the function accepts. Some people think a larger
6336: threshold should be used on RISC machines.
6337:
6338: @findex SCCS_DIRECTIVE
6339: @item SCCS_DIRECTIVE
6340: Define this if the preprocessor should ignore @code{#sccs} directives
6341: and print no error message.
6342:
1.1.1.6 root 6343: @findex NO_IMPLICIT_EXTERN_C
6344: @item NO_IMPLICIT_EXTERN_C
6345: Define this macro if the system header files support C++ as well as C.
6346: This macro inhibits the usual method of using system header files in
6347: C++, which is to pretend that the file's contents are enclosed in
6348: @samp{extern "C" @{@dots{}@}}.
6349:
1.1 root 6350: @findex HANDLE_PRAGMA
6351: @findex #pragma
6352: @findex pragma
6353: @item HANDLE_PRAGMA (@var{stream})
6354: Define this macro if you want to implement any pragmas. If defined, it
6355: should be a C statement to be executed when @code{#pragma} is seen. The
6356: argument @var{stream} is the stdio input stream from which the source
6357: text can be read.
6358:
6359: It is generally a bad idea to implement new uses of @code{#pragma}. The
6360: only reason to define this macro is for compatibility with other
6361: compilers that do support @code{#pragma} for the sake of any user
6362: programs which already use it.
6363:
1.1.1.8 ! root 6364: @findex VALID_MACHINE_DECL_ATTRIBUTE
! 6365: @item VALID_MACHINE_DECL_ATTRIBUTE (@var{decl}, @var{attributes}, @var{identifier}, @var{args})
! 6366: If defined, a C expression whose value is nonzero if @var{identifier} with
! 6367: arguments @var{args} is a valid machine specific attribute for @var{decl}.
! 6368: The attributes in @var{attributes} have previously been assigned to @var{decl}.
! 6369:
! 6370: @findex VALID_MACHINE_TYPE_ATTRIBUTE
! 6371: @item VALID_MACHINE_TYPE_ATTRIBUTE (@var{type}, @var{attributes}, @var{identifier}, @var{args})
! 6372: If defined, a C expression whose value is nonzero if @var{identifier} with
! 6373: arguments @var{args} is a valid machine specific attribute for @var{type}.
! 6374: The attributes in @var{attributes} have previously been assigned to @var{type}.
1.1.1.7 root 6375:
6376: @findex COMP_TYPE_ATTRIBUTES
6377: @item COMP_TYPE_ATTRIBUTES (@var{type1}, @var{type2})
1.1.1.8 ! root 6378: If defined, a C expression whose value is zero if the attributes on
! 6379: @var{type1} and @var{type2} are incompatible, one if they are compatible,
! 6380: and two if they are nearly compatible (which causes a warning to be
! 6381: generated).
1.1.1.7 root 6382:
6383: @findex SET_DEFAULT_TYPE_ATTRIBUTES
6384: @item SET_DEFAULT_TYPE_ATTRIBUTES (@var{type})
1.1.1.8 ! root 6385: If defined, a C statement that assigns default attributes to
! 6386: newly defined @var{type}.
1.1.1.7 root 6387:
1.1 root 6388: @findex DOLLARS_IN_IDENTIFIERS
6389: @item DOLLARS_IN_IDENTIFIERS
6390: Define this macro to control use of the character @samp{$} in identifier
6391: names. The value should be 0, 1, or 2. 0 means @samp{$} is not allowed
6392: by default; 1 means it is allowed by default if @samp{-traditional} is
6393: used; 2 means it is allowed by default provided @samp{-ansi} is not used.
6394: 1 is the default; there is no need to define this macro in that case.
6395:
1.1.1.2 root 6396: @findex NO_DOLLAR_IN_LABEL
6397: @item NO_DOLLAR_IN_LABEL
6398: Define this macro if the assembler does not accept the character
6399: @samp{$} in label names. By default constructors and destructors in
6400: G++ have @samp{$} in the identifiers. If this macro is defined,
6401: @samp{.} is used instead.
6402:
1.1.1.6 root 6403: @findex NO_DOT_IN_LABEL
6404: @item NO_DOT_IN_LABEL
6405: Define this macro if the assembler does not accept the character
6406: @samp{.} in label names. By default constructors and destructors in G++
6407: have names that use @samp{.}. If this macro is defined, these names
6408: are rewritten to avoid @samp{.}.
6409:
1.1 root 6410: @findex DEFAULT_MAIN_RETURN
6411: @item DEFAULT_MAIN_RETURN
6412: Define this macro if the target system expects every program's @code{main}
6413: function to return a standard ``success'' value by default (if no other
6414: value is explicitly returned).
6415:
6416: The definition should be a C statement (sans semicolon) to generate the
6417: appropriate rtl instructions. It is used only when compiling the end of
6418: @code{main}.
6419:
6420: @item HAVE_ATEXIT
6421: @findex HAVE_ATEXIT
6422: Define this if the target system supports the function
6423: @code{atexit} from the ANSI C standard. If this is not defined,
6424: and @code{INIT_SECTION_ASM_OP} is not defined, a default
6425: @code{exit} function will be provided to support C++.
6426:
6427: @item EXIT_BODY
6428: @findex EXIT_BODY
6429: Define this if your @code{exit} function needs to do something
6430: besides calling an external function @code{_cleanup} before
6431: terminating with @code{_exit}. The @code{EXIT_BODY} macro is
6432: only needed if netiher @code{HAVE_ATEXIT} nor
6433: @code{INIT_SECTION_ASM_OP} are defined.
1.1.1.5 root 6434:
6435: @findex INSN_SETS_ARE_DELAYED
6436: @item INSN_SETS_ARE_DELAYED (@var{insn})
6437: Define this macro as a C expression that is nonzero if it is safe for the
6438: delay slot scheduler to place instructions in the delay slot of @var{insn},
6439: even if they appear to use a resource set or clobbered in @var{insn}.
6440: @var{insn} is always a @code{jump_insn} or an @code{insn}; GNU CC knows that
6441: every @code{call_insn} has this behavior. On machines where some @code{insn}
6442: or @code{jump_insn} is really a function call and hence has this behavior,
6443: you should define this macro.
6444:
6445: You need not define this macro if it would always return zero.
6446:
6447: @findex INSN_REFERENCES_ARE_DELAYED
6448: @item INSN_REFERENCES_ARE_DELAYED (@var{insn})
6449: Define this macro as a C expression that is nonzero if it is safe for the
6450: delay slot scheduler to place instructions in the delay slot of @var{insn},
6451: even if they appear to set or clobber a resource referenced in @var{insn}.
6452: @var{insn} is always a @code{jump_insn} or an @code{insn}. On machines where
6453: some @code{insn} or @code{jump_insn} is really a function call and its operands
6454: are registers whose use is actually in the subroutine it calls, you should
6455: define this macro. Doing so allows the delay slot scheduler to move
6456: instructions which copy arguments into the argument registers into the delay
6457: slot of @var{insn}.
6458:
6459: You need not define this macro if it would always return zero.
1.1.1.7 root 6460:
6461: @findex MACHINE_DEPENDENT_REORG
6462: @item MACHINE_DEPENDENT_REORG (@var{insn})
6463: In rare cases, correct code generation requires extra machine
6464: dependent processing between the second jump optimization pass and
6465: delayed branch scheduling. On those machines, define this macro as a C
6466: statement to act on the code starting at @var{insn}.
1.1 root 6467: @end table
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.