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