OSDN Git Service

gcc/
[pf3gnuchains/gcc-fork.git] / gcc / doc / tm.texi.in
1 @c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000,2001,
2 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
3 @c Free Software Foundation, Inc.
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
6
7 @node Target Macros
8 @chapter Target Description Macros and Functions
9 @cindex machine description macros
10 @cindex target description macros
11 @cindex macros, target description
12 @cindex @file{tm.h} macros
13
14 In addition to the file @file{@var{machine}.md}, a machine description
15 includes a C header file conventionally given the name
16 @file{@var{machine}.h} and a C source file named @file{@var{machine}.c}.
17 The header file defines numerous macros that convey the information
18 about the target machine that does not fit into the scheme of the
19 @file{.md} file.  The file @file{tm.h} should be a link to
20 @file{@var{machine}.h}.  The header file @file{config.h} includes
21 @file{tm.h} and most compiler source files include @file{config.h}.  The
22 source file defines a variable @code{targetm}, which is a structure
23 containing pointers to functions and data relating to the target
24 machine.  @file{@var{machine}.c} should also contain their definitions,
25 if they are not defined elsewhere in GCC, and other functions called
26 through the macros defined in the @file{.h} file.
27
28 @menu
29 * Target Structure::    The @code{targetm} variable.
30 * Driver::              Controlling how the driver runs the compilation passes.
31 * Run-time Target::     Defining @samp{-m} options like @option{-m68000} and @option{-m68020}.
32 * Per-Function Data::   Defining data structures for per-function information.
33 * Storage Layout::      Defining sizes and alignments of data.
34 * Type Layout::         Defining sizes and properties of basic user data types.
35 * Registers::           Naming and describing the hardware registers.
36 * Register Classes::    Defining the classes of hardware registers.
37 * Old Constraints::     The old way to define machine-specific constraints.
38 * Stack and Calling::   Defining which way the stack grows and by how much.
39 * Varargs::             Defining the varargs macros.
40 * Trampolines::         Code set up at run time to enter a nested function.
41 * Library Calls::       Controlling how library routines are implicitly called.
42 * Addressing Modes::    Defining addressing modes valid for memory operands.
43 * Anchored Addresses::  Defining how @option{-fsection-anchors} should work.
44 * Condition Code::      Defining how insns update the condition code.
45 * Costs::               Defining relative costs of different operations.
46 * Scheduling::          Adjusting the behavior of the instruction scheduler.
47 * Sections::            Dividing storage into text, data, and other sections.
48 * PIC::                 Macros for position independent code.
49 * Assembler Format::    Defining how to write insns and pseudo-ops to output.
50 * Debugging Info::      Defining the format of debugging output.
51 * Floating Point::      Handling floating point for cross-compilers.
52 * Mode Switching::      Insertion of mode-switching instructions.
53 * Target Attributes::   Defining target-specific uses of @code{__attribute__}.
54 * Emulated TLS::        Emulated TLS support.
55 * MIPS Coprocessors::   MIPS coprocessor support and how to customize it.
56 * PCH Target::          Validity checking for precompiled headers.
57 * C++ ABI::             Controlling C++ ABI changes.
58 * Named Address Spaces:: Adding support for named address spaces
59 * Misc::                Everything else.
60 @end menu
61
62 @node Target Structure
63 @section The Global @code{targetm} Variable
64 @cindex target hooks
65 @cindex target functions
66
67 @deftypevar {struct gcc_target} targetm
68 The target @file{.c} file must define the global @code{targetm} variable
69 which contains pointers to functions and data relating to the target
70 machine.  The variable is declared in @file{target.h};
71 @file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is
72 used to initialize the variable, and macros for the default initializers
73 for elements of the structure.  The @file{.c} file should override those
74 macros for which the default definition is inappropriate.  For example:
75 @smallexample
76 #include "target.h"
77 #include "target-def.h"
78
79 /* @r{Initialize the GCC target structure.}  */
80
81 #undef TARGET_COMP_TYPE_ATTRIBUTES
82 #define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes
83
84 struct gcc_target targetm = TARGET_INITIALIZER;
85 @end smallexample
86 @end deftypevar
87
88 Where a macro should be defined in the @file{.c} file in this manner to
89 form part of the @code{targetm} structure, it is documented below as a
90 ``Target Hook'' with a prototype.  Many macros will change in future
91 from being defined in the @file{.h} file to being part of the
92 @code{targetm} structure.
93
94 @node Driver
95 @section Controlling the Compilation Driver, @file{gcc}
96 @cindex driver
97 @cindex controlling the compilation driver
98
99 @c prevent bad page break with this line
100 You can control the compilation driver.
101
102 @defmac SWITCH_TAKES_ARG (@var{char})
103 A C expression which determines whether the option @option{-@var{char}}
104 takes arguments.  The value should be the number of arguments that
105 option takes--zero, for many options.
106
107 By default, this macro is defined as
108 @code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options
109 properly.  You need not define @code{SWITCH_TAKES_ARG} unless you
110 wish to add additional options which take arguments.  Any redefinition
111 should call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for
112 additional options.
113 @end defmac
114
115 @defmac WORD_SWITCH_TAKES_ARG (@var{name})
116 A C expression which determines whether the option @option{-@var{name}}
117 takes arguments.  The value should be the number of arguments that
118 option takes--zero, for many options.  This macro rather than
119 @code{SWITCH_TAKES_ARG} is used for multi-character option names.
120
121 By default, this macro is defined as
122 @code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options
123 properly.  You need not define @code{WORD_SWITCH_TAKES_ARG} unless you
124 wish to add additional options which take arguments.  Any redefinition
125 should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for
126 additional options.
127 @end defmac
128
129 @defmac TARGET_OPTION_TRANSLATE_TABLE
130 If defined, a list of pairs of strings, the first of which is a
131 potential command line target to the @file{gcc} driver program, and the
132 second of which is a space-separated (tabs and other whitespace are not
133 supported) list of options with which to replace the first option.  The
134 target defining this list is responsible for assuring that the results
135 are valid.  Replacement options may not be the @code{--opt} style, they
136 must be the @code{-opt} style.  It is the intention of this macro to
137 provide a mechanism for substitution that affects the multilibs chosen,
138 such as one option that enables many options, some of which select
139 multilibs.  Example nonsensical definition, where @option{-malt-abi},
140 @option{-EB}, and @option{-mspoo} cause different multilibs to be chosen:
141
142 @smallexample
143 #define TARGET_OPTION_TRANSLATE_TABLE \
144 @{ "-fast",   "-march=fast-foo -malt-abi -I/usr/fast-foo" @}, \
145 @{ "-compat", "-EB -malign=4 -mspoo" @}
146 @end smallexample
147 @end defmac
148
149 @defmac DRIVER_SELF_SPECS
150 A list of specs for the driver itself.  It should be a suitable
151 initializer for an array of strings, with no surrounding braces.
152
153 The driver applies these specs to its own command line between loading
154 default @file{specs} files (but not command-line specified ones) and
155 choosing the multilib directory or running any subcommands.  It
156 applies them in the order given, so each spec can depend on the
157 options added by earlier ones.  It is also possible to remove options
158 using @samp{%<@var{option}} in the usual way.
159
160 This macro can be useful when a port has several interdependent target
161 options.  It provides a way of standardizing the command line so
162 that the other specs are easier to write.
163
164 Do not define this macro if it does not need to do anything.
165 @end defmac
166
167 @defmac OPTION_DEFAULT_SPECS
168 A list of specs used to support configure-time default options (i.e.@:
169 @option{--with} options) in the driver.  It should be a suitable initializer
170 for an array of structures, each containing two strings, without the
171 outermost pair of surrounding braces.
172
173 The first item in the pair is the name of the default.  This must match
174 the code in @file{config.gcc} for the target.  The second item is a spec
175 to apply if a default with this name was specified.  The string
176 @samp{%(VALUE)} in the spec will be replaced by the value of the default
177 everywhere it occurs.
178
179 The driver will apply these specs to its own command line between loading
180 default @file{specs} files and processing @code{DRIVER_SELF_SPECS}, using
181 the same mechanism as @code{DRIVER_SELF_SPECS}.
182
183 Do not define this macro if it does not need to do anything.
184 @end defmac
185
186 @defmac CPP_SPEC
187 A C string constant that tells the GCC driver program options to
188 pass to CPP@.  It can also specify how to translate options you
189 give to GCC into options for GCC to pass to the CPP@.
190
191 Do not define this macro if it does not need to do anything.
192 @end defmac
193
194 @defmac CPLUSPLUS_CPP_SPEC
195 This macro is just like @code{CPP_SPEC}, but is used for C++, rather
196 than C@.  If you do not define this macro, then the value of
197 @code{CPP_SPEC} (if any) will be used instead.
198 @end defmac
199
200 @defmac CC1_SPEC
201 A C string constant that tells the GCC driver program options to
202 pass to @code{cc1}, @code{cc1plus}, @code{f771}, and the other language
203 front ends.
204 It can also specify how to translate options you give to GCC into options
205 for GCC to pass to front ends.
206
207 Do not define this macro if it does not need to do anything.
208 @end defmac
209
210 @defmac CC1PLUS_SPEC
211 A C string constant that tells the GCC driver program options to
212 pass to @code{cc1plus}.  It can also specify how to translate options you
213 give to GCC into options for GCC to pass to the @code{cc1plus}.
214
215 Do not define this macro if it does not need to do anything.
216 Note that everything defined in CC1_SPEC is already passed to
217 @code{cc1plus} so there is no need to duplicate the contents of
218 CC1_SPEC in CC1PLUS_SPEC@.
219 @end defmac
220
221 @defmac ASM_SPEC
222 A C string constant that tells the GCC driver program options to
223 pass to the assembler.  It can also specify how to translate options
224 you give to GCC into options for GCC to pass to the assembler.
225 See the file @file{sun3.h} for an example of this.
226
227 Do not define this macro if it does not need to do anything.
228 @end defmac
229
230 @defmac ASM_FINAL_SPEC
231 A C string constant that tells the GCC driver program how to
232 run any programs which cleanup after the normal assembler.
233 Normally, this is not needed.  See the file @file{mips.h} for
234 an example of this.
235
236 Do not define this macro if it does not need to do anything.
237 @end defmac
238
239 @defmac AS_NEEDS_DASH_FOR_PIPED_INPUT
240 Define this macro, with no value, if the driver should give the assembler
241 an argument consisting of a single dash, @option{-}, to instruct it to
242 read from its standard input (which will be a pipe connected to the
243 output of the compiler proper).  This argument is given after any
244 @option{-o} option specifying the name of the output file.
245
246 If you do not define this macro, the assembler is assumed to read its
247 standard input if given no non-option arguments.  If your assembler
248 cannot read standard input at all, use a @samp{%@{pipe:%e@}} construct;
249 see @file{mips.h} for instance.
250 @end defmac
251
252 @defmac LINK_SPEC
253 A C string constant that tells the GCC driver program options to
254 pass to the linker.  It can also specify how to translate options you
255 give to GCC into options for GCC to pass to the linker.
256
257 Do not define this macro if it does not need to do anything.
258 @end defmac
259
260 @defmac LIB_SPEC
261 Another C string constant used much like @code{LINK_SPEC}.  The difference
262 between the two is that @code{LIB_SPEC} is used at the end of the
263 command given to the linker.
264
265 If this macro is not defined, a default is provided that
266 loads the standard C library from the usual place.  See @file{gcc.c}.
267 @end defmac
268
269 @defmac LIBGCC_SPEC
270 Another C string constant that tells the GCC driver program
271 how and when to place a reference to @file{libgcc.a} into the
272 linker command line.  This constant is placed both before and after
273 the value of @code{LIB_SPEC}.
274
275 If this macro is not defined, the GCC driver provides a default that
276 passes the string @option{-lgcc} to the linker.
277 @end defmac
278
279 @defmac REAL_LIBGCC_SPEC
280 By default, if @code{ENABLE_SHARED_LIBGCC} is defined, the
281 @code{LIBGCC_SPEC} is not directly used by the driver program but is
282 instead modified to refer to different versions of @file{libgcc.a}
283 depending on the values of the command line flags @option{-static},
284 @option{-shared}, @option{-static-libgcc}, and @option{-shared-libgcc}.  On
285 targets where these modifications are inappropriate, define
286 @code{REAL_LIBGCC_SPEC} instead.  @code{REAL_LIBGCC_SPEC} tells the
287 driver how to place a reference to @file{libgcc} on the link command
288 line, but, unlike @code{LIBGCC_SPEC}, it is used unmodified.
289 @end defmac
290
291 @defmac USE_LD_AS_NEEDED
292 A macro that controls the modifications to @code{LIBGCC_SPEC}
293 mentioned in @code{REAL_LIBGCC_SPEC}.  If nonzero, a spec will be
294 generated that uses --as-needed and the shared libgcc in place of the
295 static exception handler library, when linking without any of
296 @code{-static}, @code{-static-libgcc}, or @code{-shared-libgcc}.
297 @end defmac
298
299 @defmac LINK_EH_SPEC
300 If defined, this C string constant is added to @code{LINK_SPEC}.
301 When @code{USE_LD_AS_NEEDED} is zero or undefined, it also affects
302 the modifications to @code{LIBGCC_SPEC} mentioned in
303 @code{REAL_LIBGCC_SPEC}.
304 @end defmac
305
306 @defmac STARTFILE_SPEC
307 Another C string constant used much like @code{LINK_SPEC}.  The
308 difference between the two is that @code{STARTFILE_SPEC} is used at
309 the very beginning of the command given to the linker.
310
311 If this macro is not defined, a default is provided that loads the
312 standard C startup file from the usual place.  See @file{gcc.c}.
313 @end defmac
314
315 @defmac ENDFILE_SPEC
316 Another C string constant used much like @code{LINK_SPEC}.  The
317 difference between the two is that @code{ENDFILE_SPEC} is used at
318 the very end of the command given to the linker.
319
320 Do not define this macro if it does not need to do anything.
321 @end defmac
322
323 @defmac THREAD_MODEL_SPEC
324 GCC @code{-v} will print the thread model GCC was configured to use.
325 However, this doesn't work on platforms that are multilibbed on thread
326 models, such as AIX 4.3.  On such platforms, define
327 @code{THREAD_MODEL_SPEC} such that it evaluates to a string without
328 blanks that names one of the recognized thread models.  @code{%*}, the
329 default value of this macro, will expand to the value of
330 @code{thread_file} set in @file{config.gcc}.
331 @end defmac
332
333 @defmac SYSROOT_SUFFIX_SPEC
334 Define this macro to add a suffix to the target sysroot when GCC is
335 configured with a sysroot.  This will cause GCC to search for usr/lib,
336 et al, within sysroot+suffix.
337 @end defmac
338
339 @defmac SYSROOT_HEADERS_SUFFIX_SPEC
340 Define this macro to add a headers_suffix to the target sysroot when
341 GCC is configured with a sysroot.  This will cause GCC to pass the
342 updated sysroot+headers_suffix to CPP, causing it to search for
343 usr/include, et al, within sysroot+headers_suffix.
344 @end defmac
345
346 @defmac EXTRA_SPECS
347 Define this macro to provide additional specifications to put in the
348 @file{specs} file that can be used in various specifications like
349 @code{CC1_SPEC}.
350
351 The definition should be an initializer for an array of structures,
352 containing a string constant, that defines the specification name, and a
353 string constant that provides the specification.
354
355 Do not define this macro if it does not need to do anything.
356
357 @code{EXTRA_SPECS} is useful when an architecture contains several
358 related targets, which have various @code{@dots{}_SPECS} which are similar
359 to each other, and the maintainer would like one central place to keep
360 these definitions.
361
362 For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} to
363 define either @code{_CALL_SYSV} when the System V calling sequence is
364 used or @code{_CALL_AIX} when the older AIX-based calling sequence is
365 used.
366
367 The @file{config/rs6000/rs6000.h} target file defines:
368
369 @smallexample
370 #define EXTRA_SPECS \
371   @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @},
372
373 #define CPP_SYS_DEFAULT ""
374 @end smallexample
375
376 The @file{config/rs6000/sysv.h} target file defines:
377 @smallexample
378 #undef CPP_SPEC
379 #define CPP_SPEC \
380 "%@{posix: -D_POSIX_SOURCE @} \
381 %@{mcall-sysv: -D_CALL_SYSV @} \
382 %@{!mcall-sysv: %(cpp_sysv_default) @} \
383 %@{msoft-float: -D_SOFT_FLOAT@} %@{mcpu=403: -D_SOFT_FLOAT@}"
384
385 #undef CPP_SYSV_DEFAULT
386 #define CPP_SYSV_DEFAULT "-D_CALL_SYSV"
387 @end smallexample
388
389 while the @file{config/rs6000/eabiaix.h} target file defines
390 @code{CPP_SYSV_DEFAULT} as:
391
392 @smallexample
393 #undef CPP_SYSV_DEFAULT
394 #define CPP_SYSV_DEFAULT "-D_CALL_AIX"
395 @end smallexample
396 @end defmac
397
398 @defmac LINK_LIBGCC_SPECIAL_1
399 Define this macro if the driver program should find the library
400 @file{libgcc.a}.  If you do not define this macro, the driver program will pass
401 the argument @option{-lgcc} to tell the linker to do the search.
402 @end defmac
403
404 @defmac LINK_GCC_C_SEQUENCE_SPEC
405 The sequence in which libgcc and libc are specified to the linker.
406 By default this is @code{%G %L %G}.
407 @end defmac
408
409 @defmac LINK_COMMAND_SPEC
410 A C string constant giving the complete command line need to execute the
411 linker.  When you do this, you will need to update your port each time a
412 change is made to the link command line within @file{gcc.c}.  Therefore,
413 define this macro only if you need to completely redefine the command
414 line for invoking the linker and there is no other way to accomplish
415 the effect you need.  Overriding this macro may be avoidable by overriding
416 @code{LINK_GCC_C_SEQUENCE_SPEC} instead.
417 @end defmac
418
419 @defmac LINK_ELIMINATE_DUPLICATE_LDIRECTORIES
420 A nonzero value causes @command{collect2} to remove duplicate @option{-L@var{directory}} search
421 directories from linking commands.  Do not give it a nonzero value if
422 removing duplicate search directories changes the linker's semantics.
423 @end defmac
424
425 @defmac MULTILIB_DEFAULTS
426 Define this macro as a C expression for the initializer of an array of
427 string to tell the driver program which options are defaults for this
428 target and thus do not need to be handled specially when using
429 @code{MULTILIB_OPTIONS}.
430
431 Do not define this macro if @code{MULTILIB_OPTIONS} is not defined in
432 the target makefile fragment or if none of the options listed in
433 @code{MULTILIB_OPTIONS} are set by default.
434 @xref{Target Fragment}.
435 @end defmac
436
437 @defmac RELATIVE_PREFIX_NOT_LINKDIR
438 Define this macro to tell @command{gcc} that it should only translate
439 a @option{-B} prefix into a @option{-L} linker option if the prefix
440 indicates an absolute file name.
441 @end defmac
442
443 @defmac MD_EXEC_PREFIX
444 If defined, this macro is an additional prefix to try after
445 @code{STANDARD_EXEC_PREFIX}.  @code{MD_EXEC_PREFIX} is not searched
446 when the compiler is built as a cross
447 compiler.  If you define @code{MD_EXEC_PREFIX}, then be sure to add it
448 to the list of directories used to find the assembler in @file{configure.in}.
449 @end defmac
450
451 @defmac STANDARD_STARTFILE_PREFIX
452 Define this macro as a C string constant if you wish to override the
453 standard choice of @code{libdir} as the default prefix to
454 try when searching for startup files such as @file{crt0.o}.
455 @code{STANDARD_STARTFILE_PREFIX} is not searched when the compiler
456 is built as a cross compiler.
457 @end defmac
458
459 @defmac STANDARD_STARTFILE_PREFIX_1
460 Define this macro as a C string constant if you wish to override the
461 standard choice of @code{/lib} as a prefix to try after the default prefix
462 when searching for startup files such as @file{crt0.o}.
463 @code{STANDARD_STARTFILE_PREFIX_1} is not searched when the compiler
464 is built as a cross compiler.
465 @end defmac
466
467 @defmac STANDARD_STARTFILE_PREFIX_2
468 Define this macro as a C string constant if you wish to override the
469 standard choice of @code{/lib} as yet another prefix to try after the
470 default prefix when searching for startup files such as @file{crt0.o}.
471 @code{STANDARD_STARTFILE_PREFIX_2} is not searched when the compiler
472 is built as a cross compiler.
473 @end defmac
474
475 @defmac MD_STARTFILE_PREFIX
476 If defined, this macro supplies an additional prefix to try after the
477 standard prefixes.  @code{MD_EXEC_PREFIX} is not searched when the
478 compiler is built as a cross compiler.
479 @end defmac
480
481 @defmac MD_STARTFILE_PREFIX_1
482 If defined, this macro supplies yet another prefix to try after the
483 standard prefixes.  It is not searched when the compiler is built as a
484 cross compiler.
485 @end defmac
486
487 @defmac INIT_ENVIRONMENT
488 Define this macro as a C string constant if you wish to set environment
489 variables for programs called by the driver, such as the assembler and
490 loader.  The driver passes the value of this macro to @code{putenv} to
491 initialize the necessary environment variables.
492 @end defmac
493
494 @defmac LOCAL_INCLUDE_DIR
495 Define this macro as a C string constant if you wish to override the
496 standard choice of @file{/usr/local/include} as the default prefix to
497 try when searching for local header files.  @code{LOCAL_INCLUDE_DIR}
498 comes before @code{SYSTEM_INCLUDE_DIR} in the search order.
499
500 Cross compilers do not search either @file{/usr/local/include} or its
501 replacement.
502 @end defmac
503
504 @defmac SYSTEM_INCLUDE_DIR
505 Define this macro as a C string constant if you wish to specify a
506 system-specific directory to search for header files before the standard
507 directory.  @code{SYSTEM_INCLUDE_DIR} comes before
508 @code{STANDARD_INCLUDE_DIR} in the search order.
509
510 Cross compilers do not use this macro and do not search the directory
511 specified.
512 @end defmac
513
514 @defmac STANDARD_INCLUDE_DIR
515 Define this macro as a C string constant if you wish to override the
516 standard choice of @file{/usr/include} as the default prefix to
517 try when searching for header files.
518
519 Cross compilers ignore this macro and do not search either
520 @file{/usr/include} or its replacement.
521 @end defmac
522
523 @defmac STANDARD_INCLUDE_COMPONENT
524 The ``component'' corresponding to @code{STANDARD_INCLUDE_DIR}.
525 See @code{INCLUDE_DEFAULTS}, below, for the description of components.
526 If you do not define this macro, no component is used.
527 @end defmac
528
529 @defmac INCLUDE_DEFAULTS
530 Define this macro if you wish to override the entire default search path
531 for include files.  For a native compiler, the default search path
532 usually consists of @code{GCC_INCLUDE_DIR}, @code{LOCAL_INCLUDE_DIR},
533 @code{SYSTEM_INCLUDE_DIR}, @code{GPLUSPLUS_INCLUDE_DIR}, and
534 @code{STANDARD_INCLUDE_DIR}.  In addition, @code{GPLUSPLUS_INCLUDE_DIR}
535 and @code{GCC_INCLUDE_DIR} are defined automatically by @file{Makefile},
536 and specify private search areas for GCC@.  The directory
537 @code{GPLUSPLUS_INCLUDE_DIR} is used only for C++ programs.
538
539 The definition should be an initializer for an array of structures.
540 Each array element should have four elements: the directory name (a
541 string constant), the component name (also a string constant), a flag
542 for C++-only directories,
543 and a flag showing that the includes in the directory don't need to be
544 wrapped in @code{extern @samp{C}} when compiling C++.  Mark the end of
545 the array with a null element.
546
547 The component name denotes what GNU package the include file is part of,
548 if any, in all uppercase letters.  For example, it might be @samp{GCC}
549 or @samp{BINUTILS}.  If the package is part of a vendor-supplied
550 operating system, code the component name as @samp{0}.
551
552 For example, here is the definition used for VAX/VMS:
553
554 @smallexample
555 #define INCLUDE_DEFAULTS \
556 @{                                       \
557   @{ "GNU_GXX_INCLUDE:", "G++", 1, 1@},   \
558   @{ "GNU_CC_INCLUDE:", "GCC", 0, 0@},    \
559   @{ "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0@},  \
560   @{ ".", 0, 0, 0@},                      \
561   @{ 0, 0, 0, 0@}                         \
562 @}
563 @end smallexample
564 @end defmac
565
566 Here is the order of prefixes tried for exec files:
567
568 @enumerate
569 @item
570 Any prefixes specified by the user with @option{-B}.
571
572 @item
573 The environment variable @code{GCC_EXEC_PREFIX} or, if @code{GCC_EXEC_PREFIX}
574 is not set and the compiler has not been installed in the configure-time 
575 @var{prefix}, the location in which the compiler has actually been installed.
576
577 @item
578 The directories specified by the environment variable @code{COMPILER_PATH}.
579
580 @item
581 The macro @code{STANDARD_EXEC_PREFIX}, if the compiler has been installed
582 in the configured-time @var{prefix}. 
583
584 @item
585 The location @file{/usr/libexec/gcc/}, but only if this is a native compiler. 
586
587 @item
588 The location @file{/usr/lib/gcc/}, but only if this is a native compiler. 
589
590 @item
591 The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 
592 compiler.
593 @end enumerate
594
595 Here is the order of prefixes tried for startfiles:
596
597 @enumerate
598 @item
599 Any prefixes specified by the user with @option{-B}.
600
601 @item
602 The environment variable @code{GCC_EXEC_PREFIX} or its automatically determined
603 value based on the installed toolchain location.
604
605 @item
606 The directories specified by the environment variable @code{LIBRARY_PATH}
607 (or port-specific name; native only, cross compilers do not use this).
608
609 @item
610 The macro @code{STANDARD_EXEC_PREFIX}, but only if the toolchain is installed
611 in the configured @var{prefix} or this is a native compiler. 
612
613 @item
614 The location @file{/usr/lib/gcc/}, but only if this is a native compiler.
615
616 @item
617 The macro @code{MD_EXEC_PREFIX}, if defined, but only if this is a native 
618 compiler.
619
620 @item
621 The macro @code{MD_STARTFILE_PREFIX}, if defined, but only if this is a 
622 native compiler, or we have a target system root.
623
624 @item
625 The macro @code{MD_STARTFILE_PREFIX_1}, if defined, but only if this is a 
626 native compiler, or we have a target system root.
627
628 @item
629 The macro @code{STANDARD_STARTFILE_PREFIX}, with any sysroot modifications.
630 If this path is relative it will be prefixed by @code{GCC_EXEC_PREFIX} and
631 the machine suffix or @code{STANDARD_EXEC_PREFIX} and the machine suffix.
632
633 @item
634 The macro @code{STANDARD_STARTFILE_PREFIX_1}, but only if this is a native
635 compiler, or we have a target system root. The default for this macro is
636 @file{/lib/}.
637
638 @item
639 The macro @code{STANDARD_STARTFILE_PREFIX_2}, but only if this is a native
640 compiler, or we have a target system root. The default for this macro is
641 @file{/usr/lib/}.
642 @end enumerate
643
644 @node Run-time Target
645 @section Run-time Target Specification
646 @cindex run-time target specification
647 @cindex predefined macros
648 @cindex target specifications
649
650 @c prevent bad page break with this line
651 Here are run-time target specifications.
652
653 @defmac TARGET_CPU_CPP_BUILTINS ()
654 This function-like macro expands to a block of code that defines
655 built-in preprocessor macros and assertions for the target CPU, using
656 the functions @code{builtin_define}, @code{builtin_define_std} and
657 @code{builtin_assert}.  When the front end
658 calls this macro it provides a trailing semicolon, and since it has
659 finished command line option processing your code can use those
660 results freely.
661
662 @code{builtin_assert} takes a string in the form you pass to the
663 command-line option @option{-A}, such as @code{cpu=mips}, and creates
664 the assertion.  @code{builtin_define} takes a string in the form
665 accepted by option @option{-D} and unconditionally defines the macro.
666
667 @code{builtin_define_std} takes a string representing the name of an
668 object-like macro.  If it doesn't lie in the user's namespace,
669 @code{builtin_define_std} defines it unconditionally.  Otherwise, it
670 defines a version with two leading underscores, and another version
671 with two leading and trailing underscores, and defines the original
672 only if an ISO standard was not requested on the command line.  For
673 example, passing @code{unix} defines @code{__unix}, @code{__unix__}
674 and possibly @code{unix}; passing @code{_mips} defines @code{__mips},
675 @code{__mips__} and possibly @code{_mips}, and passing @code{_ABI64}
676 defines only @code{_ABI64}.
677
678 You can also test for the C dialect being compiled.  The variable
679 @code{c_language} is set to one of @code{clk_c}, @code{clk_cplusplus}
680 or @code{clk_objective_c}.  Note that if we are preprocessing
681 assembler, this variable will be @code{clk_c} but the function-like
682 macro @code{preprocessing_asm_p()} will return true, so you might want
683 to check for that first.  If you need to check for strict ANSI, the
684 variable @code{flag_iso} can be used.  The function-like macro
685 @code{preprocessing_trad_p()} can be used to check for traditional
686 preprocessing.
687 @end defmac
688
689 @defmac TARGET_OS_CPP_BUILTINS ()
690 Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
691 and is used for the target operating system instead.
692 @end defmac
693
694 @defmac TARGET_OBJFMT_CPP_BUILTINS ()
695 Similarly to @code{TARGET_CPU_CPP_BUILTINS} but this macro is optional
696 and is used for the target object format.  @file{elfos.h} uses this
697 macro to define @code{__ELF__}, so you probably do not need to define
698 it yourself.
699 @end defmac
700
701 @deftypevar {extern int} target_flags
702 This variable is declared in @file{options.h}, which is included before
703 any target-specific headers.
704 @end deftypevar
705
706 @hook TARGET_DEFAULT_TARGET_FLAGS
707 This variable specifies the initial value of @code{target_flags}.
708 Its default setting is 0.
709 @end deftypevr
710
711 @cindex optional hardware or system features
712 @cindex features, optional, in system conventions
713
714 @hook TARGET_HANDLE_OPTION
715 This hook is called whenever the user specifies one of the
716 target-specific options described by the @file{.opt} definition files
717 (@pxref{Options}).  It has the opportunity to do some option-specific
718 processing and should return true if the option is valid.  The default
719 definition does nothing but return true.
720
721 @var{code} specifies the @code{OPT_@var{name}} enumeration value
722 associated with the selected option; @var{name} is just a rendering of
723 the option name in which non-alphanumeric characters are replaced by
724 underscores.  @var{arg} specifies the string argument and is null if
725 no argument was given.  If the option is flagged as a @code{UInteger}
726 (@pxref{Option properties}), @var{value} is the numeric value of the
727 argument.  Otherwise @var{value} is 1 if the positive form of the
728 option was used and 0 if the ``no-'' form was.
729 @end deftypefn
730
731 @hook TARGET_HANDLE_C_OPTION
732 This target hook is called whenever the user specifies one of the
733 target-specific C language family options described by the @file{.opt}
734 definition files(@pxref{Options}).  It has the opportunity to do some
735 option-specific processing and should return true if the option is
736 valid.  The arguments are like for @code{TARGET_HANDLE_OPTION}.  The
737 default definition does nothing but return false.
738
739 In general, you should use @code{TARGET_HANDLE_OPTION} to handle
740 options.  However, if processing an option requires routines that are
741 only available in the C (and related language) front ends, then you
742 should use @code{TARGET_HANDLE_C_OPTION} instead.
743 @end deftypefn
744
745 @hook TARGET_OBJC_CONSTRUCT_STRING
746
747 @defmac TARGET_VERSION
748 This macro is a C statement to print on @code{stderr} a string
749 describing the particular machine description choice.  Every machine
750 description should define @code{TARGET_VERSION}.  For example:
751
752 @smallexample
753 #ifdef MOTOROLA
754 #define TARGET_VERSION \
755   fprintf (stderr, " (68k, Motorola syntax)");
756 #else
757 #define TARGET_VERSION \
758   fprintf (stderr, " (68k, MIT syntax)");
759 #endif
760 @end smallexample
761 @end defmac
762
763 @hook TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE
764 This target function is similar to the hook @code{TARGET_OPTION_OVERRIDE}
765 but is called when the optimize level is changed via an attribute or
766 pragma or when it is reset at the end of the code affected by the
767 attribute or pragma.  It is not called at the beginning of compilation
768 when @code{TARGET_OPTION_OVERRIDE} is called so if you want to perform these
769 actions then, you should have @code{TARGET_OPTION_OVERRIDE} call
770 @code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}.
771 @end deftypefn
772
773 @defmac C_COMMON_OVERRIDE_OPTIONS
774 This is similar to the @code{TARGET_OPTION_OVERRIDE} hook
775 but is only used in the C
776 language frontends (C, Objective-C, C++, Objective-C++) and so can be
777 used to alter option flag variables which only exist in those
778 frontends.
779 @end defmac
780
781 @hook TARGET_OPTION_OPTIMIZATION_TABLE
782 Some machines may desire to change what optimizations are performed for
783 various optimization levels.   This variable, if defined, describes
784 options to enable at particular sets of optimization levels.  These
785 options are processed once
786 just after the optimization level is determined and before the remainder
787 of the command options have been parsed, so may be overridden by other
788 options passed explicily.
789
790 This processing is run once at program startup and when the optimization
791 options are changed via @code{#pragma GCC optimize} or by using the
792 @code{optimize} attribute.
793 @end deftypevr
794
795 @hook TARGET_OPTION_INIT_STRUCT
796
797 @hook TARGET_OPTION_DEFAULT_PARAMS
798
799 @hook TARGET_HELP
800 This hook is called in response to the user invoking
801 @option{--target-help} on the command line.  It gives the target a
802 chance to display extra information on the target specific command
803 line options found in its @file{.opt} file.
804 @end deftypefn
805
806 @defmac SWITCHABLE_TARGET
807 Some targets need to switch between substantially different subtargets
808 during compilation.  For example, the MIPS target has one subtarget for
809 the traditional MIPS architecture and another for MIPS16.  Source code
810 can switch between these two subarchitectures using the @code{mips16}
811 and @code{nomips16} attributes.
812
813 Such subtargets can differ in things like the set of available
814 registers, the set of available instructions, the costs of various
815 operations, and so on.  GCC caches a lot of this type of information
816 in global variables, and recomputing them for each subtarget takes a
817 significant amount of time.  The compiler therefore provides a facility
818 for maintaining several versions of the global variables and quickly
819 switching between them; see @file{target-globals.h} for details.
820
821 Define this macro to 1 if your target needs this facility.  The default
822 is 0.
823 @end defmac
824
825 @node Per-Function Data
826 @section Defining data structures for per-function information.
827 @cindex per-function data
828 @cindex data structures
829
830 If the target needs to store information on a per-function basis, GCC
831 provides a macro and a couple of variables to allow this.  Note, just
832 using statics to store the information is a bad idea, since GCC supports
833 nested functions, so you can be halfway through encoding one function
834 when another one comes along.
835
836 GCC defines a data structure called @code{struct function} which
837 contains all of the data specific to an individual function.  This
838 structure contains a field called @code{machine} whose type is
839 @code{struct machine_function *}, which can be used by targets to point
840 to their own specific data.
841
842 If a target needs per-function specific data it should define the type
843 @code{struct machine_function} and also the macro @code{INIT_EXPANDERS}.
844 This macro should be used to initialize the function pointer
845 @code{init_machine_status}.  This pointer is explained below.
846
847 One typical use of per-function, target specific data is to create an
848 RTX to hold the register containing the function's return address.  This
849 RTX can then be used to implement the @code{__builtin_return_address}
850 function, for level 0.
851
852 Note---earlier implementations of GCC used a single data area to hold
853 all of the per-function information.  Thus when processing of a nested
854 function began the old per-function data had to be pushed onto a
855 stack, and when the processing was finished, it had to be popped off the
856 stack.  GCC used to provide function pointers called
857 @code{save_machine_status} and @code{restore_machine_status} to handle
858 the saving and restoring of the target specific information.  Since the
859 single data area approach is no longer used, these pointers are no
860 longer supported.
861
862 @defmac INIT_EXPANDERS
863 Macro called to initialize any target specific information.  This macro
864 is called once per function, before generation of any RTL has begun.
865 The intention of this macro is to allow the initialization of the
866 function pointer @code{init_machine_status}.
867 @end defmac
868
869 @deftypevar {void (*)(struct function *)} init_machine_status
870 If this function pointer is non-@code{NULL} it will be called once per
871 function, before function compilation starts, in order to allow the
872 target to perform any target specific initialization of the
873 @code{struct function} structure.  It is intended that this would be
874 used to initialize the @code{machine} of that structure.
875
876 @code{struct machine_function} structures are expected to be freed by GC@.
877 Generally, any memory that they reference must be allocated by using
878 GC allocation, including the structure itself.
879 @end deftypevar
880
881 @node Storage Layout
882 @section Storage Layout
883 @cindex storage layout
884
885 Note that the definitions of the macros in this table which are sizes or
886 alignments measured in bits do not need to be constant.  They can be C
887 expressions that refer to static variables, such as the @code{target_flags}.
888 @xref{Run-time Target}.
889
890 @defmac BITS_BIG_ENDIAN
891 Define this macro to have the value 1 if the most significant bit in a
892 byte has the lowest number; otherwise define it to have the value zero.
893 This means that bit-field instructions count from the most significant
894 bit.  If the machine has no bit-field instructions, then this must still
895 be defined, but it doesn't matter which value it is defined to.  This
896 macro need not be a constant.
897
898 This macro does not affect the way structure fields are packed into
899 bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.
900 @end defmac
901
902 @defmac BYTES_BIG_ENDIAN
903 Define this macro to have the value 1 if the most significant byte in a
904 word has the lowest number.  This macro need not be a constant.
905 @end defmac
906
907 @defmac WORDS_BIG_ENDIAN
908 Define this macro to have the value 1 if, in a multiword object, the
909 most significant word has the lowest number.  This applies to both
910 memory locations and registers; GCC fundamentally assumes that the
911 order of words in memory is the same as the order in registers.  This
912 macro need not be a constant.
913 @end defmac
914
915 @defmac FLOAT_WORDS_BIG_ENDIAN
916 Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or
917 @code{TFmode} floating point numbers are stored in memory with the word
918 containing the sign bit at the lowest address; otherwise define it to
919 have the value 0.  This macro need not be a constant.
920
921 You need not define this macro if the ordering is the same as for
922 multi-word integers.
923 @end defmac
924
925 @defmac BITS_PER_UNIT
926 Define this macro to be the number of bits in an addressable storage
927 unit (byte).  If you do not define this macro the default is 8.
928 @end defmac
929
930 @defmac BITS_PER_WORD
931 Number of bits in a word.  If you do not define this macro, the default
932 is @code{BITS_PER_UNIT * UNITS_PER_WORD}.
933 @end defmac
934
935 @defmac MAX_BITS_PER_WORD
936 Maximum number of bits in a word.  If this is undefined, the default is
937 @code{BITS_PER_WORD}.  Otherwise, it is the constant value that is the
938 largest value that @code{BITS_PER_WORD} can have at run-time.
939 @end defmac
940
941 @defmac UNITS_PER_WORD
942 Number of storage units in a word; normally the size of a general-purpose
943 register, a power of two from 1 or 8.
944 @end defmac
945
946 @defmac MIN_UNITS_PER_WORD
947 Minimum number of units in a word.  If this is undefined, the default is
948 @code{UNITS_PER_WORD}.  Otherwise, it is the constant value that is the
949 smallest value that @code{UNITS_PER_WORD} can have at run-time.
950 @end defmac
951
952 @defmac POINTER_SIZE
953 Width of a pointer, in bits.  You must specify a value no wider than the
954 width of @code{Pmode}.  If it is not equal to the width of @code{Pmode},
955 you must define @code{POINTERS_EXTEND_UNSIGNED}.  If you do not specify
956 a value the default is @code{BITS_PER_WORD}.
957 @end defmac
958
959 @defmac POINTERS_EXTEND_UNSIGNED
960 A C expression that determines how pointers should be extended from
961 @code{ptr_mode} to either @code{Pmode} or @code{word_mode}.  It is
962 greater than zero if pointers should be zero-extended, zero if they
963 should be sign-extended, and negative if some other sort of conversion
964 is needed.  In the last case, the extension is done by the target's
965 @code{ptr_extend} instruction.
966
967 You need not define this macro if the @code{ptr_mode}, @code{Pmode}
968 and @code{word_mode} are all the same width.
969 @end defmac
970
971 @defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type})
972 A macro to update @var{m} and @var{unsignedp} when an object whose type
973 is @var{type} and which has the specified mode and signedness is to be
974 stored in a register.  This macro is only called when @var{type} is a
975 scalar type.
976
977 On most RISC machines, which only have operations that operate on a full
978 register, define this macro to set @var{m} to @code{word_mode} if
979 @var{m} is an integer mode narrower than @code{BITS_PER_WORD}.  In most
980 cases, only integer modes should be widened because wider-precision
981 floating-point operations are usually more expensive than their narrower
982 counterparts.
983
984 For most machines, the macro definition does not change @var{unsignedp}.
985 However, some machines, have instructions that preferentially handle
986 either signed or unsigned quantities of certain modes.  For example, on
987 the DEC Alpha, 32-bit loads from memory and 32-bit add instructions
988 sign-extend the result to 64 bits.  On such machines, set
989 @var{unsignedp} according to which kind of extension is more efficient.
990
991 Do not define this macro if it would never modify @var{m}.
992 @end defmac
993
994 @hook TARGET_PROMOTE_FUNCTION_MODE
995 Like @code{PROMOTE_MODE}, but it is applied to outgoing function arguments or
996 function return values.  The target hook should return the new mode
997 and possibly change @code{*@var{punsignedp}} if the promotion should
998 change signedness.  This function is called only for scalar @emph{or
999 pointer} types.
1000
1001 @var{for_return} allows to distinguish the promotion of arguments and
1002 return values.  If it is @code{1}, a return value is being promoted and
1003 @code{TARGET_FUNCTION_VALUE} must perform the same promotions done here.
1004 If it is @code{2}, the returned mode should be that of the register in
1005 which an incoming parameter is copied, or the outgoing result is computed;
1006 then the hook should return the same mode as @code{promote_mode}, though
1007 the signedness may be different.
1008
1009 The default is to not promote arguments and return values.  You can
1010 also define the hook to @code{default_promote_function_mode_always_promote}
1011 if you would like to apply the same rules given by @code{PROMOTE_MODE}.
1012 @end deftypefn
1013
1014 @defmac PARM_BOUNDARY
1015 Normal alignment required for function parameters on the stack, in
1016 bits.  All stack parameters receive at least this much alignment
1017 regardless of data type.  On most machines, this is the same as the
1018 size of an integer.
1019 @end defmac
1020
1021 @defmac STACK_BOUNDARY
1022 Define this macro to the minimum alignment enforced by hardware for the
1023 stack pointer on this machine.  The definition is a C expression for the
1024 desired alignment (measured in bits).  This value is used as a default
1025 if @code{PREFERRED_STACK_BOUNDARY} is not defined.  On most machines,
1026 this should be the same as @code{PARM_BOUNDARY}.
1027 @end defmac
1028
1029 @defmac PREFERRED_STACK_BOUNDARY
1030 Define this macro if you wish to preserve a certain alignment for the
1031 stack pointer, greater than what the hardware enforces.  The definition
1032 is a C expression for the desired alignment (measured in bits).  This
1033 macro must evaluate to a value equal to or larger than
1034 @code{STACK_BOUNDARY}.
1035 @end defmac
1036
1037 @defmac INCOMING_STACK_BOUNDARY
1038 Define this macro if the incoming stack boundary may be different
1039 from @code{PREFERRED_STACK_BOUNDARY}.  This macro must evaluate
1040 to a value equal to or larger than @code{STACK_BOUNDARY}.
1041 @end defmac
1042
1043 @defmac FUNCTION_BOUNDARY
1044 Alignment required for a function entry point, in bits.
1045 @end defmac
1046
1047 @defmac BIGGEST_ALIGNMENT
1048 Biggest alignment that any data type can require on this machine, in
1049 bits.  Note that this is not the biggest alignment that is supported,
1050 just the biggest alignment that, when violated, may cause a fault.
1051 @end defmac
1052
1053 @defmac MALLOC_ABI_ALIGNMENT
1054 Alignment, in bits, a C conformant malloc implementation has to
1055 provide.  If not defined, the default value is @code{BITS_PER_WORD}.
1056 @end defmac
1057
1058 @defmac ATTRIBUTE_ALIGNED_VALUE
1059 Alignment used by the @code{__attribute__ ((aligned))} construct.  If
1060 not defined, the default value is @code{BIGGEST_ALIGNMENT}.
1061 @end defmac
1062
1063 @defmac MINIMUM_ATOMIC_ALIGNMENT
1064 If defined, the smallest alignment, in bits, that can be given to an
1065 object that can be referenced in one operation, without disturbing any
1066 nearby object.  Normally, this is @code{BITS_PER_UNIT}, but may be larger
1067 on machines that don't have byte or half-word store operations.
1068 @end defmac
1069
1070 @defmac BIGGEST_FIELD_ALIGNMENT
1071 Biggest alignment that any structure or union field can require on this
1072 machine, in bits.  If defined, this overrides @code{BIGGEST_ALIGNMENT} for
1073 structure and union fields only, unless the field alignment has been set
1074 by the @code{__attribute__ ((aligned (@var{n})))} construct.
1075 @end defmac
1076
1077 @defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed})
1078 An expression for the alignment of a structure field @var{field} if the
1079 alignment computed in the usual way (including applying of
1080 @code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the
1081 alignment) is @var{computed}.  It overrides alignment only if the
1082 field alignment has not been set by the
1083 @code{__attribute__ ((aligned (@var{n})))} construct.
1084 @end defmac
1085
1086 @defmac MAX_STACK_ALIGNMENT
1087 Biggest stack alignment guaranteed by the backend.  Use this macro
1088 to specify the maximum alignment of a variable on stack.
1089
1090 If not defined, the default value is @code{STACK_BOUNDARY}.
1091
1092 @c FIXME: The default should be @code{PREFERRED_STACK_BOUNDARY}.
1093 @c But the fix for PR 32893 indicates that we can only guarantee
1094 @c maximum stack alignment on stack up to @code{STACK_BOUNDARY}, not
1095 @c @code{PREFERRED_STACK_BOUNDARY}, if stack alignment isn't supported.
1096 @end defmac
1097
1098 @defmac MAX_OFILE_ALIGNMENT
1099 Biggest alignment supported by the object file format of this machine.
1100 Use this macro to limit the alignment which can be specified using the
1101 @code{__attribute__ ((aligned (@var{n})))} construct.  If not defined,
1102 the default value is @code{BIGGEST_ALIGNMENT}.
1103
1104 On systems that use ELF, the default (in @file{config/elfos.h}) is
1105 the largest supported 32-bit ELF section alignment representable on
1106 a 32-bit host e.g. @samp{(((unsigned HOST_WIDEST_INT) 1 << 28) * 8)}.
1107 On 32-bit ELF the largest supported section alignment in bits is
1108 @samp{(0x80000000 * 8)}, but this is not representable on 32-bit hosts.
1109 @end defmac
1110
1111 @defmac DATA_ALIGNMENT (@var{type}, @var{basic-align})
1112 If defined, a C expression to compute the alignment for a variable in
1113 the static store.  @var{type} is the data type, and @var{basic-align} is
1114 the alignment that the object would ordinarily have.  The value of this
1115 macro is used instead of that alignment to align the object.
1116
1117 If this macro is not defined, then @var{basic-align} is used.
1118
1119 @findex strcpy
1120 One use of this macro is to increase alignment of medium-size data to
1121 make it all fit in fewer cache lines.  Another is to cause character
1122 arrays to be word-aligned so that @code{strcpy} calls that copy
1123 constants to character arrays can be done inline.
1124 @end defmac
1125
1126 @defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align})
1127 If defined, a C expression to compute the alignment given to a constant
1128 that is being placed in memory.  @var{constant} is the constant and
1129 @var{basic-align} is the alignment that the object would ordinarily
1130 have.  The value of this macro is used instead of that alignment to
1131 align the object.
1132
1133 If this macro is not defined, then @var{basic-align} is used.
1134
1135 The typical use of this macro is to increase alignment for string
1136 constants to be word aligned so that @code{strcpy} calls that copy
1137 constants can be done inline.
1138 @end defmac
1139
1140 @defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align})
1141 If defined, a C expression to compute the alignment for a variable in
1142 the local store.  @var{type} is the data type, and @var{basic-align} is
1143 the alignment that the object would ordinarily have.  The value of this
1144 macro is used instead of that alignment to align the object.
1145
1146 If this macro is not defined, then @var{basic-align} is used.
1147
1148 One use of this macro is to increase alignment of medium-size data to
1149 make it all fit in fewer cache lines.
1150 @end defmac
1151
1152 @defmac STACK_SLOT_ALIGNMENT (@var{type}, @var{mode}, @var{basic-align})
1153 If defined, a C expression to compute the alignment for stack slot.
1154 @var{type} is the data type, @var{mode} is the widest mode available,
1155 and @var{basic-align} is the alignment that the slot would ordinarily
1156 have.  The value of this macro is used instead of that alignment to
1157 align the slot.
1158
1159 If this macro is not defined, then @var{basic-align} is used when
1160 @var{type} is @code{NULL}.  Otherwise, @code{LOCAL_ALIGNMENT} will
1161 be used.
1162
1163 This macro is to set alignment of stack slot to the maximum alignment
1164 of all possible modes which the slot may have.
1165 @end defmac
1166
1167 @defmac LOCAL_DECL_ALIGNMENT (@var{decl})
1168 If defined, a C expression to compute the alignment for a local
1169 variable @var{decl}.
1170
1171 If this macro is not defined, then
1172 @code{LOCAL_ALIGNMENT (TREE_TYPE (@var{decl}), DECL_ALIGN (@var{decl}))}
1173 is used.
1174
1175 One use of this macro is to increase alignment of medium-size data to
1176 make it all fit in fewer cache lines.
1177 @end defmac
1178
1179 @defmac MINIMUM_ALIGNMENT (@var{exp}, @var{mode}, @var{align})
1180 If defined, a C expression to compute the minimum required alignment
1181 for dynamic stack realignment purposes for @var{exp} (a type or decl),
1182 @var{mode}, assuming normal alignment @var{align}.
1183
1184 If this macro is not defined, then @var{align} will be used.
1185 @end defmac
1186
1187 @defmac EMPTY_FIELD_BOUNDARY
1188 Alignment in bits to be given to a structure bit-field that follows an
1189 empty field such as @code{int : 0;}.
1190
1191 If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro.
1192 @end defmac
1193
1194 @defmac STRUCTURE_SIZE_BOUNDARY
1195 Number of bits which any structure or union's size must be a multiple of.
1196 Each structure or union's size is rounded up to a multiple of this.
1197
1198 If you do not define this macro, the default is the same as
1199 @code{BITS_PER_UNIT}.
1200 @end defmac
1201
1202 @defmac STRICT_ALIGNMENT
1203 Define this macro to be the value 1 if instructions will fail to work
1204 if given data not on the nominal alignment.  If instructions will merely
1205 go slower in that case, define this macro as 0.
1206 @end defmac
1207
1208 @defmac PCC_BITFIELD_TYPE_MATTERS
1209 Define this if you wish to imitate the way many other C compilers handle
1210 alignment of bit-fields and the structures that contain them.
1211
1212 The behavior is that the type written for a named bit-field (@code{int},
1213 @code{short}, or other integer type) imposes an alignment for the entire
1214 structure, as if the structure really did contain an ordinary field of
1215 that type.  In addition, the bit-field is placed within the structure so
1216 that it would fit within such a field, not crossing a boundary for it.
1217
1218 Thus, on most machines, a named bit-field whose type is written as
1219 @code{int} would not cross a four-byte boundary, and would force
1220 four-byte alignment for the whole structure.  (The alignment used may
1221 not be four bytes; it is controlled by the other alignment parameters.)
1222
1223 An unnamed bit-field will not affect the alignment of the containing
1224 structure.
1225
1226 If the macro is defined, its definition should be a C expression;
1227 a nonzero value for the expression enables this behavior.
1228
1229 Note that if this macro is not defined, or its value is zero, some
1230 bit-fields may cross more than one alignment boundary.  The compiler can
1231 support such references if there are @samp{insv}, @samp{extv}, and
1232 @samp{extzv} insns that can directly reference memory.
1233
1234 The other known way of making bit-fields work is to define
1235 @code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}.
1236 Then every structure can be accessed with fullwords.
1237
1238 Unless the machine has bit-field instructions or you define
1239 @code{STRUCTURE_SIZE_BOUNDARY} that way, you must define
1240 @code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value.
1241
1242 If your aim is to make GCC use the same conventions for laying out
1243 bit-fields as are used by another compiler, here is how to investigate
1244 what the other compiler does.  Compile and run this program:
1245
1246 @smallexample
1247 struct foo1
1248 @{
1249   char x;
1250   char :0;
1251   char y;
1252 @};
1253
1254 struct foo2
1255 @{
1256   char x;
1257   int :0;
1258   char y;
1259 @};
1260
1261 main ()
1262 @{
1263   printf ("Size of foo1 is %d\n",
1264           sizeof (struct foo1));
1265   printf ("Size of foo2 is %d\n",
1266           sizeof (struct foo2));
1267   exit (0);
1268 @}
1269 @end smallexample
1270
1271 If this prints 2 and 5, then the compiler's behavior is what you would
1272 get from @code{PCC_BITFIELD_TYPE_MATTERS}.
1273 @end defmac
1274
1275 @defmac BITFIELD_NBYTES_LIMITED
1276 Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited
1277 to aligning a bit-field within the structure.
1278 @end defmac
1279
1280 @hook TARGET_ALIGN_ANON_BITFIELD
1281 When @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine
1282 whether unnamed bitfields affect the alignment of the containing
1283 structure.  The hook should return true if the structure should inherit
1284 the alignment requirements of an unnamed bitfield's type.
1285 @end deftypefn
1286
1287 @hook TARGET_NARROW_VOLATILE_BITFIELD
1288 This target hook should return @code{true} if accesses to volatile bitfields
1289 should use the narrowest mode possible.  It should return @code{false} if
1290 these accesses should use the bitfield container type.
1291
1292 The default is @code{!TARGET_STRICT_ALIGN}.
1293 @end deftypefn
1294
1295 @defmac MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode})
1296 Return 1 if a structure or array containing @var{field} should be accessed using
1297 @code{BLKMODE}.
1298
1299 If @var{field} is the only field in the structure, @var{mode} is its
1300 mode, otherwise @var{mode} is VOIDmode.  @var{mode} is provided in the
1301 case where structures of one field would require the structure's mode to
1302 retain the field's mode.
1303
1304 Normally, this is not needed.
1305 @end defmac
1306
1307 @defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified})
1308 Define this macro as an expression for the alignment of a type (given
1309 by @var{type} as a tree node) if the alignment computed in the usual
1310 way is @var{computed} and the alignment explicitly specified was
1311 @var{specified}.
1312
1313 The default is to use @var{specified} if it is larger; otherwise, use
1314 the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT}
1315 @end defmac
1316
1317 @defmac MAX_FIXED_MODE_SIZE
1318 An integer expression for the size in bits of the largest integer
1319 machine mode that should actually be used.  All integer machine modes of
1320 this size or smaller can be used for structures and unions with the
1321 appropriate sizes.  If this macro is undefined, @code{GET_MODE_BITSIZE
1322 (DImode)} is assumed.
1323 @end defmac
1324
1325 @defmac STACK_SAVEAREA_MODE (@var{save_level})
1326 If defined, an expression of type @code{enum machine_mode} that
1327 specifies the mode of the save area operand of a
1328 @code{save_stack_@var{level}} named pattern (@pxref{Standard Names}).
1329 @var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or
1330 @code{SAVE_NONLOCAL} and selects which of the three named patterns is
1331 having its mode specified.
1332
1333 You need not define this macro if it always returns @code{Pmode}.  You
1334 would most commonly define this macro if the
1335 @code{save_stack_@var{level}} patterns need to support both a 32- and a
1336 64-bit mode.
1337 @end defmac
1338
1339 @defmac STACK_SIZE_MODE
1340 If defined, an expression of type @code{enum machine_mode} that
1341 specifies the mode of the size increment operand of an
1342 @code{allocate_stack} named pattern (@pxref{Standard Names}).
1343
1344 You need not define this macro if it always returns @code{word_mode}.
1345 You would most commonly define this macro if the @code{allocate_stack}
1346 pattern needs to support both a 32- and a 64-bit mode.
1347 @end defmac
1348
1349 @hook TARGET_LIBGCC_CMP_RETURN_MODE
1350 This target hook should return the mode to be used for the return value
1351 of compare instructions expanded to libgcc calls.  If not defined
1352 @code{word_mode} is returned which is the right choice for a majority of
1353 targets.
1354 @end deftypefn
1355
1356 @hook TARGET_LIBGCC_SHIFT_COUNT_MODE
1357 This target hook should return the mode to be used for the shift count operand
1358 of shift instructions expanded to libgcc calls.  If not defined
1359 @code{word_mode} is returned which is the right choice for a majority of
1360 targets.
1361 @end deftypefn
1362
1363 @hook TARGET_UNWIND_WORD_MODE
1364 Return machine mode to be used for @code{_Unwind_Word} type.
1365 The default is to use @code{word_mode}.
1366 @end deftypefn
1367
1368 @defmac ROUND_TOWARDS_ZERO
1369 If defined, this macro should be true if the prevailing rounding
1370 mode is towards zero.
1371
1372 Defining this macro only affects the way @file{libgcc.a} emulates
1373 floating-point arithmetic.
1374
1375 Not defining this macro is equivalent to returning zero.
1376 @end defmac
1377
1378 @defmac LARGEST_EXPONENT_IS_NORMAL (@var{size})
1379 This macro should return true if floats with @var{size}
1380 bits do not have a NaN or infinity representation, but use the largest
1381 exponent for normal numbers instead.
1382
1383 Defining this macro only affects the way @file{libgcc.a} emulates
1384 floating-point arithmetic.
1385
1386 The default definition of this macro returns false for all sizes.
1387 @end defmac
1388
1389 @hook TARGET_MS_BITFIELD_LAYOUT_P
1390 This target hook returns @code{true} if bit-fields in the given
1391 @var{record_type} are to be laid out following the rules of Microsoft
1392 Visual C/C++, namely: (i) a bit-field won't share the same storage
1393 unit with the previous bit-field if their underlying types have
1394 different sizes, and the bit-field will be aligned to the highest
1395 alignment of the underlying types of itself and of the previous
1396 bit-field; (ii) a zero-sized bit-field will affect the alignment of
1397 the whole enclosing structure, even if it is unnamed; except that
1398 (iii) a zero-sized bit-field will be disregarded unless it follows
1399 another bit-field of nonzero size.  If this hook returns @code{true},
1400 other macros that control bit-field layout are ignored.
1401
1402 When a bit-field is inserted into a packed record, the whole size
1403 of the underlying type is used by one or more same-size adjacent
1404 bit-fields (that is, if its long:3, 32 bits is used in the record,
1405 and any additional adjacent long bit-fields are packed into the same
1406 chunk of 32 bits.  However, if the size changes, a new field of that
1407 size is allocated).  In an unpacked record, this is the same as using
1408 alignment, but not equivalent when packing.
1409
1410 If both MS bit-fields and @samp{__attribute__((packed))} are used,
1411 the latter will take precedence.  If @samp{__attribute__((packed))} is
1412 used on a single field when MS bit-fields are in use, it will take
1413 precedence for that field, but the alignment of the rest of the structure
1414 may affect its placement.
1415 @end deftypefn
1416
1417 @hook TARGET_DECIMAL_FLOAT_SUPPORTED_P
1418 Returns true if the target supports decimal floating point.
1419 @end deftypefn
1420
1421 @hook TARGET_FIXED_POINT_SUPPORTED_P
1422 Returns true if the target supports fixed-point arithmetic.
1423 @end deftypefn
1424
1425 @hook TARGET_EXPAND_TO_RTL_HOOK
1426 This hook is called just before expansion into rtl, allowing the target
1427 to perform additional initializations or analysis before the expansion.
1428 For example, the rs6000 port uses it to allocate a scratch stack slot
1429 for use in copying SDmode values between memory and floating point
1430 registers whenever the function being expanded has any SDmode
1431 usage.
1432 @end deftypefn
1433
1434 @hook TARGET_INSTANTIATE_DECLS
1435 This hook allows the backend to perform additional instantiations on rtl
1436 that are not actually in any insns yet, but will be later.
1437 @end deftypefn
1438
1439 @hook TARGET_MANGLE_TYPE
1440 If your target defines any fundamental types, or any types your target
1441 uses should be mangled differently from the default, define this hook
1442 to return the appropriate encoding for these types as part of a C++
1443 mangled name.  The @var{type} argument is the tree structure representing
1444 the type to be mangled.  The hook may be applied to trees which are
1445 not target-specific fundamental types; it should return @code{NULL}
1446 for all such types, as well as arguments it does not recognize.  If the
1447 return value is not @code{NULL}, it must point to a statically-allocated
1448 string constant.
1449
1450 Target-specific fundamental types might be new fundamental types or
1451 qualified versions of ordinary fundamental types.  Encode new
1452 fundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name}
1453 is the name used for the type in source code, and @var{n} is the
1454 length of @var{name} in decimal.  Encode qualified versions of
1455 ordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where
1456 @var{name} is the name used for the type qualifier in source code,
1457 @var{n} is the length of @var{name} as above, and @var{code} is the
1458 code used to represent the unqualified version of this type.  (See
1459 @code{write_builtin_type} in @file{cp/mangle.c} for the list of
1460 codes.)  In both cases the spaces are for clarity; do not include any
1461 spaces in your string.
1462
1463 This hook is applied to types prior to typedef resolution.  If the mangled
1464 name for a particular type depends only on that type's main variant, you
1465 can perform typedef resolution yourself using @code{TYPE_MAIN_VARIANT}
1466 before mangling.
1467
1468 The default version of this hook always returns @code{NULL}, which is
1469 appropriate for a target that does not define any new fundamental
1470 types.
1471 @end deftypefn
1472
1473 @node Type Layout
1474 @section Layout of Source Language Data Types
1475
1476 These macros define the sizes and other characteristics of the standard
1477 basic data types used in programs being compiled.  Unlike the macros in
1478 the previous section, these apply to specific features of C and related
1479 languages, rather than to fundamental aspects of storage layout.
1480
1481 @defmac INT_TYPE_SIZE
1482 A C expression for the size in bits of the type @code{int} on the
1483 target machine.  If you don't define this, the default is one word.
1484 @end defmac
1485
1486 @defmac SHORT_TYPE_SIZE
1487 A C expression for the size in bits of the type @code{short} on the
1488 target machine.  If you don't define this, the default is half a word.
1489 (If this would be less than one storage unit, it is rounded up to one
1490 unit.)
1491 @end defmac
1492
1493 @defmac LONG_TYPE_SIZE
1494 A C expression for the size in bits of the type @code{long} on the
1495 target machine.  If you don't define this, the default is one word.
1496 @end defmac
1497
1498 @defmac ADA_LONG_TYPE_SIZE
1499 On some machines, the size used for the Ada equivalent of the type
1500 @code{long} by a native Ada compiler differs from that used by C@.  In
1501 that situation, define this macro to be a C expression to be used for
1502 the size of that type.  If you don't define this, the default is the
1503 value of @code{LONG_TYPE_SIZE}.
1504 @end defmac
1505
1506 @defmac LONG_LONG_TYPE_SIZE
1507 A C expression for the size in bits of the type @code{long long} on the
1508 target machine.  If you don't define this, the default is two
1509 words.  If you want to support GNU Ada on your machine, the value of this
1510 macro must be at least 64.
1511 @end defmac
1512
1513 @defmac CHAR_TYPE_SIZE
1514 A C expression for the size in bits of the type @code{char} on the
1515 target machine.  If you don't define this, the default is
1516 @code{BITS_PER_UNIT}.
1517 @end defmac
1518
1519 @defmac BOOL_TYPE_SIZE
1520 A C expression for the size in bits of the C++ type @code{bool} and
1521 C99 type @code{_Bool} on the target machine.  If you don't define
1522 this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}.
1523 @end defmac
1524
1525 @defmac FLOAT_TYPE_SIZE
1526 A C expression for the size in bits of the type @code{float} on the
1527 target machine.  If you don't define this, the default is one word.
1528 @end defmac
1529
1530 @defmac DOUBLE_TYPE_SIZE
1531 A C expression for the size in bits of the type @code{double} on the
1532 target machine.  If you don't define this, the default is two
1533 words.
1534 @end defmac
1535
1536 @defmac LONG_DOUBLE_TYPE_SIZE
1537 A C expression for the size in bits of the type @code{long double} on
1538 the target machine.  If you don't define this, the default is two
1539 words.
1540 @end defmac
1541
1542 @defmac SHORT_FRACT_TYPE_SIZE
1543 A C expression for the size in bits of the type @code{short _Fract} on
1544 the target machine.  If you don't define this, the default is
1545 @code{BITS_PER_UNIT}.
1546 @end defmac
1547
1548 @defmac FRACT_TYPE_SIZE
1549 A C expression for the size in bits of the type @code{_Fract} on
1550 the target machine.  If you don't define this, the default is
1551 @code{BITS_PER_UNIT * 2}.
1552 @end defmac
1553
1554 @defmac LONG_FRACT_TYPE_SIZE
1555 A C expression for the size in bits of the type @code{long _Fract} on
1556 the target machine.  If you don't define this, the default is
1557 @code{BITS_PER_UNIT * 4}.
1558 @end defmac
1559
1560 @defmac LONG_LONG_FRACT_TYPE_SIZE
1561 A C expression for the size in bits of the type @code{long long _Fract} on
1562 the target machine.  If you don't define this, the default is
1563 @code{BITS_PER_UNIT * 8}.
1564 @end defmac
1565
1566 @defmac SHORT_ACCUM_TYPE_SIZE
1567 A C expression for the size in bits of the type @code{short _Accum} on
1568 the target machine.  If you don't define this, the default is
1569 @code{BITS_PER_UNIT * 2}.
1570 @end defmac
1571
1572 @defmac ACCUM_TYPE_SIZE
1573 A C expression for the size in bits of the type @code{_Accum} on
1574 the target machine.  If you don't define this, the default is
1575 @code{BITS_PER_UNIT * 4}.
1576 @end defmac
1577
1578 @defmac LONG_ACCUM_TYPE_SIZE
1579 A C expression for the size in bits of the type @code{long _Accum} on
1580 the target machine.  If you don't define this, the default is
1581 @code{BITS_PER_UNIT * 8}.
1582 @end defmac
1583
1584 @defmac LONG_LONG_ACCUM_TYPE_SIZE
1585 A C expression for the size in bits of the type @code{long long _Accum} on
1586 the target machine.  If you don't define this, the default is
1587 @code{BITS_PER_UNIT * 16}.
1588 @end defmac
1589
1590 @defmac LIBGCC2_LONG_DOUBLE_TYPE_SIZE
1591 Define this macro if @code{LONG_DOUBLE_TYPE_SIZE} is not constant or
1592 if you want routines in @file{libgcc2.a} for a size other than
1593 @code{LONG_DOUBLE_TYPE_SIZE}.  If you don't define this, the
1594 default is @code{LONG_DOUBLE_TYPE_SIZE}.
1595 @end defmac
1596
1597 @defmac LIBGCC2_HAS_DF_MODE
1598 Define this macro if neither @code{DOUBLE_TYPE_SIZE} nor
1599 @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is
1600 @code{DFmode} but you want @code{DFmode} routines in @file{libgcc2.a}
1601 anyway.  If you don't define this and either @code{DOUBLE_TYPE_SIZE}
1602 or @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64 then the default is 1,
1603 otherwise it is 0.
1604 @end defmac
1605
1606 @defmac LIBGCC2_HAS_XF_MODE
1607 Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not
1608 @code{XFmode} but you want @code{XFmode} routines in @file{libgcc2.a}
1609 anyway.  If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE}
1610 is 80 then the default is 1, otherwise it is 0.
1611 @end defmac
1612
1613 @defmac LIBGCC2_HAS_TF_MODE
1614 Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not
1615 @code{TFmode} but you want @code{TFmode} routines in @file{libgcc2.a}
1616 anyway.  If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE}
1617 is 128 then the default is 1, otherwise it is 0.
1618 @end defmac
1619
1620 @defmac SF_SIZE
1621 @defmacx DF_SIZE
1622 @defmacx XF_SIZE
1623 @defmacx TF_SIZE
1624 Define these macros to be the size in bits of the mantissa of
1625 @code{SFmode}, @code{DFmode}, @code{XFmode} and @code{TFmode} values,
1626 if the defaults in @file{libgcc2.h} are inappropriate.  By default,
1627 @code{FLT_MANT_DIG} is used for @code{SF_SIZE}, @code{LDBL_MANT_DIG}
1628 for @code{XF_SIZE} and @code{TF_SIZE}, and @code{DBL_MANT_DIG} or
1629 @code{LDBL_MANT_DIG} for @code{DF_SIZE} according to whether
1630 @code{DOUBLE_TYPE_SIZE} or
1631 @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64.
1632 @end defmac
1633
1634 @defmac TARGET_FLT_EVAL_METHOD
1635 A C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h},
1636 assuming, if applicable, that the floating-point control word is in its
1637 default state.  If you do not define this macro the value of
1638 @code{FLT_EVAL_METHOD} will be zero.
1639 @end defmac
1640
1641 @defmac WIDEST_HARDWARE_FP_SIZE
1642 A C expression for the size in bits of the widest floating-point format
1643 supported by the hardware.  If you define this macro, you must specify a
1644 value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}.
1645 If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE}
1646 is the default.
1647 @end defmac
1648
1649 @defmac DEFAULT_SIGNED_CHAR
1650 An expression whose value is 1 or 0, according to whether the type
1651 @code{char} should be signed or unsigned by default.  The user can
1652 always override this default with the options @option{-fsigned-char}
1653 and @option{-funsigned-char}.
1654 @end defmac
1655
1656 @hook TARGET_DEFAULT_SHORT_ENUMS
1657 This target hook should return true if the compiler should give an
1658 @code{enum} type only as many bytes as it takes to represent the range
1659 of possible values of that type.  It should return false if all
1660 @code{enum} types should be allocated like @code{int}.
1661
1662 The default is to return false.
1663 @end deftypefn
1664
1665 @defmac SIZE_TYPE
1666 A C expression for a string describing the name of the data type to use
1667 for size values.  The typedef name @code{size_t} is defined using the
1668 contents of the string.
1669
1670 The string can contain more than one keyword.  If so, separate them with
1671 spaces, and write first any length keyword, then @code{unsigned} if
1672 appropriate, and finally @code{int}.  The string must exactly match one
1673 of the data type names defined in the function
1674 @code{init_decl_processing} in the file @file{c-decl.c}.  You may not
1675 omit @code{int} or change the order---that would cause the compiler to
1676 crash on startup.
1677
1678 If you don't define this macro, the default is @code{"long unsigned
1679 int"}.
1680 @end defmac
1681
1682 @defmac PTRDIFF_TYPE
1683 A C expression for a string describing the name of the data type to use
1684 for the result of subtracting two pointers.  The typedef name
1685 @code{ptrdiff_t} is defined using the contents of the string.  See
1686 @code{SIZE_TYPE} above for more information.
1687
1688 If you don't define this macro, the default is @code{"long int"}.
1689 @end defmac
1690
1691 @defmac WCHAR_TYPE
1692 A C expression for a string describing the name of the data type to use
1693 for wide characters.  The typedef name @code{wchar_t} is defined using
1694 the contents of the string.  See @code{SIZE_TYPE} above for more
1695 information.
1696
1697 If you don't define this macro, the default is @code{"int"}.
1698 @end defmac
1699
1700 @defmac WCHAR_TYPE_SIZE
1701 A C expression for the size in bits of the data type for wide
1702 characters.  This is used in @code{cpp}, which cannot make use of
1703 @code{WCHAR_TYPE}.
1704 @end defmac
1705
1706 @defmac WINT_TYPE
1707 A C expression for a string describing the name of the data type to
1708 use for wide characters passed to @code{printf} and returned from
1709 @code{getwc}.  The typedef name @code{wint_t} is defined using the
1710 contents of the string.  See @code{SIZE_TYPE} above for more
1711 information.
1712
1713 If you don't define this macro, the default is @code{"unsigned int"}.
1714 @end defmac
1715
1716 @defmac INTMAX_TYPE
1717 A C expression for a string describing the name of the data type that
1718 can represent any value of any standard or extended signed integer type.
1719 The typedef name @code{intmax_t} is defined using the contents of the
1720 string.  See @code{SIZE_TYPE} above for more information.
1721
1722 If you don't define this macro, the default is the first of
1723 @code{"int"}, @code{"long int"}, or @code{"long long int"} that has as
1724 much precision as @code{long long int}.
1725 @end defmac
1726
1727 @defmac UINTMAX_TYPE
1728 A C expression for a string describing the name of the data type that
1729 can represent any value of any standard or extended unsigned integer
1730 type.  The typedef name @code{uintmax_t} is defined using the contents
1731 of the string.  See @code{SIZE_TYPE} above for more information.
1732
1733 If you don't define this macro, the default is the first of
1734 @code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long
1735 unsigned int"} that has as much precision as @code{long long unsigned
1736 int}.
1737 @end defmac
1738
1739 @defmac SIG_ATOMIC_TYPE
1740 @defmacx INT8_TYPE
1741 @defmacx INT16_TYPE
1742 @defmacx INT32_TYPE
1743 @defmacx INT64_TYPE
1744 @defmacx UINT8_TYPE
1745 @defmacx UINT16_TYPE
1746 @defmacx UINT32_TYPE
1747 @defmacx UINT64_TYPE
1748 @defmacx INT_LEAST8_TYPE
1749 @defmacx INT_LEAST16_TYPE
1750 @defmacx INT_LEAST32_TYPE
1751 @defmacx INT_LEAST64_TYPE
1752 @defmacx UINT_LEAST8_TYPE
1753 @defmacx UINT_LEAST16_TYPE
1754 @defmacx UINT_LEAST32_TYPE
1755 @defmacx UINT_LEAST64_TYPE
1756 @defmacx INT_FAST8_TYPE
1757 @defmacx INT_FAST16_TYPE
1758 @defmacx INT_FAST32_TYPE
1759 @defmacx INT_FAST64_TYPE
1760 @defmacx UINT_FAST8_TYPE
1761 @defmacx UINT_FAST16_TYPE
1762 @defmacx UINT_FAST32_TYPE
1763 @defmacx UINT_FAST64_TYPE
1764 @defmacx INTPTR_TYPE
1765 @defmacx UINTPTR_TYPE
1766 C expressions for the standard types @code{sig_atomic_t},
1767 @code{int8_t}, @code{int16_t}, @code{int32_t}, @code{int64_t},
1768 @code{uint8_t}, @code{uint16_t}, @code{uint32_t}, @code{uint64_t},
1769 @code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
1770 @code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
1771 @code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
1772 @code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
1773 @code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
1774 @code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t}.  See
1775 @code{SIZE_TYPE} above for more information.
1776
1777 If any of these macros evaluates to a null pointer, the corresponding
1778 type is not supported; if GCC is configured to provide
1779 @code{<stdint.h>} in such a case, the header provided may not conform
1780 to C99, depending on the type in question.  The defaults for all of
1781 these macros are null pointers.
1782 @end defmac
1783
1784 @defmac TARGET_PTRMEMFUNC_VBIT_LOCATION
1785 The C++ compiler represents a pointer-to-member-function with a struct
1786 that looks like:
1787
1788 @smallexample
1789   struct @{
1790     union @{
1791       void (*fn)();
1792       ptrdiff_t vtable_index;
1793     @};
1794     ptrdiff_t delta;
1795   @};
1796 @end smallexample
1797
1798 @noindent
1799 The C++ compiler must use one bit to indicate whether the function that
1800 will be called through a pointer-to-member-function is virtual.
1801 Normally, we assume that the low-order bit of a function pointer must
1802 always be zero.  Then, by ensuring that the vtable_index is odd, we can
1803 distinguish which variant of the union is in use.  But, on some
1804 platforms function pointers can be odd, and so this doesn't work.  In
1805 that case, we use the low-order bit of the @code{delta} field, and shift
1806 the remainder of the @code{delta} field to the left.
1807
1808 GCC will automatically make the right selection about where to store
1809 this bit using the @code{FUNCTION_BOUNDARY} setting for your platform.
1810 However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY}
1811 set such that functions always start at even addresses, but the lowest
1812 bit of pointers to functions indicate whether the function at that
1813 address is in ARM or Thumb mode.  If this is the case of your
1814 architecture, you should define this macro to
1815 @code{ptrmemfunc_vbit_in_delta}.
1816
1817 In general, you should not have to define this macro.  On architectures
1818 in which function addresses are always even, according to
1819 @code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to
1820 @code{ptrmemfunc_vbit_in_pfn}.
1821 @end defmac
1822
1823 @defmac TARGET_VTABLE_USES_DESCRIPTORS
1824 Normally, the C++ compiler uses function pointers in vtables.  This
1825 macro allows the target to change to use ``function descriptors''
1826 instead.  Function descriptors are found on targets for whom a
1827 function pointer is actually a small data structure.  Normally the
1828 data structure consists of the actual code address plus a data
1829 pointer to which the function's data is relative.
1830
1831 If vtables are used, the value of this macro should be the number
1832 of words that the function descriptor occupies.
1833 @end defmac
1834
1835 @defmac TARGET_VTABLE_ENTRY_ALIGN
1836 By default, the vtable entries are void pointers, the so the alignment
1837 is the same as pointer alignment.  The value of this macro specifies
1838 the alignment of the vtable entry in bits.  It should be defined only
1839 when special alignment is necessary. */
1840 @end defmac
1841
1842 @defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE
1843 There are a few non-descriptor entries in the vtable at offsets below
1844 zero.  If these entries must be padded (say, to preserve the alignment
1845 specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number
1846 of words in each data entry.
1847 @end defmac
1848
1849 @node Registers
1850 @section Register Usage
1851 @cindex register usage
1852
1853 This section explains how to describe what registers the target machine
1854 has, and how (in general) they can be used.
1855
1856 The description of which registers a specific instruction can use is
1857 done with register classes; see @ref{Register Classes}.  For information
1858 on using registers to access a stack frame, see @ref{Frame Registers}.
1859 For passing values in registers, see @ref{Register Arguments}.
1860 For returning values in registers, see @ref{Scalar Return}.
1861
1862 @menu
1863 * Register Basics::             Number and kinds of registers.
1864 * Allocation Order::            Order in which registers are allocated.
1865 * Values in Registers::         What kinds of values each reg can hold.
1866 * Leaf Functions::              Renumbering registers for leaf functions.
1867 * Stack Registers::             Handling a register stack such as 80387.
1868 @end menu
1869
1870 @node Register Basics
1871 @subsection Basic Characteristics of Registers
1872
1873 @c prevent bad page break with this line
1874 Registers have various characteristics.
1875
1876 @defmac FIRST_PSEUDO_REGISTER
1877 Number of hardware registers known to the compiler.  They receive
1878 numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
1879 pseudo register's number really is assigned the number
1880 @code{FIRST_PSEUDO_REGISTER}.
1881 @end defmac
1882
1883 @defmac FIXED_REGISTERS
1884 @cindex fixed register
1885 An initializer that says which registers are used for fixed purposes
1886 all throughout the compiled code and are therefore not available for
1887 general allocation.  These would include the stack pointer, the frame
1888 pointer (except on machines where that can be used as a general
1889 register when no frame pointer is needed), the program counter on
1890 machines where that is considered one of the addressable registers,
1891 and any other numbered register with a standard use.
1892
1893 This information is expressed as a sequence of numbers, separated by
1894 commas and surrounded by braces.  The @var{n}th number is 1 if
1895 register @var{n} is fixed, 0 otherwise.
1896
1897 The table initialized from this macro, and the table initialized by
1898 the following one, may be overridden at run time either automatically,
1899 by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
1900 the user with the command options @option{-ffixed-@var{reg}},
1901 @option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}.
1902 @end defmac
1903
1904 @defmac CALL_USED_REGISTERS
1905 @cindex call-used register
1906 @cindex call-clobbered register
1907 @cindex call-saved register
1908 Like @code{FIXED_REGISTERS} but has 1 for each register that is
1909 clobbered (in general) by function calls as well as for fixed
1910 registers.  This macro therefore identifies the registers that are not
1911 available for general allocation of values that must live across
1912 function calls.
1913
1914 If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
1915 automatically saves it on function entry and restores it on function
1916 exit, if the register is used within the function.
1917 @end defmac
1918
1919 @defmac CALL_REALLY_USED_REGISTERS
1920 @cindex call-used register
1921 @cindex call-clobbered register
1922 @cindex call-saved register
1923 Like @code{CALL_USED_REGISTERS} except this macro doesn't require
1924 that the entire set of @code{FIXED_REGISTERS} be included.
1925 (@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}).
1926 This macro is optional.  If not specified, it defaults to the value
1927 of @code{CALL_USED_REGISTERS}.
1928 @end defmac
1929
1930 @defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode})
1931 @cindex call-used register
1932 @cindex call-clobbered register
1933 @cindex call-saved register
1934 A C expression that is nonzero if it is not permissible to store a
1935 value of mode @var{mode} in hard register number @var{regno} across a
1936 call without some part of it being clobbered.  For most machines this
1937 macro need not be defined.  It is only required for machines that do not
1938 preserve the entire contents of a register across a call.
1939 @end defmac
1940
1941 @findex fixed_regs
1942 @findex call_used_regs
1943 @findex global_regs
1944 @findex reg_names
1945 @findex reg_class_contents
1946 @defmac CONDITIONAL_REGISTER_USAGE
1947 Zero or more C statements that may conditionally modify five variables
1948 @code{fixed_regs}, @code{call_used_regs}, @code{global_regs},
1949 @code{reg_names}, and @code{reg_class_contents}, to take into account
1950 any dependence of these register sets on target flags.  The first three
1951 of these are of type @code{char []} (interpreted as Boolean vectors).
1952 @code{global_regs} is a @code{const char *[]}, and
1953 @code{reg_class_contents} is a @code{HARD_REG_SET}.  Before the macro is
1954 called, @code{fixed_regs}, @code{call_used_regs},
1955 @code{reg_class_contents}, and @code{reg_names} have been initialized
1956 from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS},
1957 @code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively.
1958 @code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}},
1959 @option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}
1960 command options have been applied.
1961
1962 You need not define this macro if it has no work to do.
1963
1964 @cindex disabling certain registers
1965 @cindex controlling register usage
1966 If the usage of an entire class of registers depends on the target
1967 flags, you may indicate this to GCC by using this macro to modify
1968 @code{fixed_regs} and @code{call_used_regs} to 1 for each of the
1969 registers in the classes which should not be used by GCC@.  Also define
1970 the macro @code{REG_CLASS_FROM_LETTER} / @code{REG_CLASS_FROM_CONSTRAINT}
1971 to return @code{NO_REGS} if it
1972 is called with a letter for a class that shouldn't be used.
1973
1974 (However, if this class is not included in @code{GENERAL_REGS} and all
1975 of the insn patterns whose constraints permit this class are
1976 controlled by target switches, then GCC will automatically avoid using
1977 these registers when the target switches are opposed to them.)
1978 @end defmac
1979
1980 @defmac INCOMING_REGNO (@var{out})
1981 Define this macro if the target machine has register windows.  This C
1982 expression returns the register number as seen by the called function
1983 corresponding to the register number @var{out} as seen by the calling
1984 function.  Return @var{out} if register number @var{out} is not an
1985 outbound register.
1986 @end defmac
1987
1988 @defmac OUTGOING_REGNO (@var{in})
1989 Define this macro if the target machine has register windows.  This C
1990 expression returns the register number as seen by the calling function
1991 corresponding to the register number @var{in} as seen by the called
1992 function.  Return @var{in} if register number @var{in} is not an inbound
1993 register.
1994 @end defmac
1995
1996 @defmac LOCAL_REGNO (@var{regno})
1997 Define this macro if the target machine has register windows.  This C
1998 expression returns true if the register is call-saved but is in the
1999 register window.  Unlike most call-saved registers, such registers
2000 need not be explicitly restored on function exit or during non-local
2001 gotos.
2002 @end defmac
2003
2004 @defmac PC_REGNUM
2005 If the program counter has a register number, define this as that
2006 register number.  Otherwise, do not define it.
2007 @end defmac
2008
2009 @node Allocation Order
2010 @subsection Order of Allocation of Registers
2011 @cindex order of register allocation
2012 @cindex register allocation order
2013
2014 @c prevent bad page break with this line
2015 Registers are allocated in order.
2016
2017 @defmac REG_ALLOC_ORDER
2018 If defined, an initializer for a vector of integers, containing the
2019 numbers of hard registers in the order in which GCC should prefer
2020 to use them (from most preferred to least).
2021
2022 If this macro is not defined, registers are used lowest numbered first
2023 (all else being equal).
2024
2025 One use of this macro is on machines where the highest numbered
2026 registers must always be saved and the save-multiple-registers
2027 instruction supports only sequences of consecutive registers.  On such
2028 machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists
2029 the highest numbered allocable register first.
2030 @end defmac
2031
2032 @defmac ADJUST_REG_ALLOC_ORDER
2033 A C statement (sans semicolon) to choose the order in which to allocate
2034 hard registers for pseudo-registers local to a basic block.
2035
2036 Store the desired register order in the array @code{reg_alloc_order}.
2037 Element 0 should be the register to allocate first; element 1, the next
2038 register; and so on.
2039
2040 The macro body should not assume anything about the contents of
2041 @code{reg_alloc_order} before execution of the macro.
2042
2043 On most machines, it is not necessary to define this macro.
2044 @end defmac
2045
2046 @defmac HONOR_REG_ALLOC_ORDER
2047 Normally, IRA tries to estimate the costs for saving a register in the
2048 prologue and restoring it in the epilogue.  This discourages it from
2049 using call-saved registers.  If a machine wants to ensure that IRA
2050 allocates registers in the order given by REG_ALLOC_ORDER even if some
2051 call-saved registers appear earlier than call-used ones, this macro
2052 should be defined.
2053 @end defmac
2054
2055 @defmac IRA_HARD_REGNO_ADD_COST_MULTIPLIER (@var{regno})
2056 In some case register allocation order is not enough for the
2057 Integrated Register Allocator (@acronym{IRA}) to generate a good code.
2058 If this macro is defined, it should return a floating point value
2059 based on @var{regno}.  The cost of using @var{regno} for a pseudo will
2060 be increased by approximately the pseudo's usage frequency times the
2061 value returned by this macro.  Not defining this macro is equivalent
2062 to having it always return @code{0.0}.
2063
2064 On most machines, it is not necessary to define this macro.
2065 @end defmac
2066
2067 @node Values in Registers
2068 @subsection How Values Fit in Registers
2069
2070 This section discusses the macros that describe which kinds of values
2071 (specifically, which machine modes) each register can hold, and how many
2072 consecutive registers are needed for a given mode.
2073
2074 @defmac HARD_REGNO_NREGS (@var{regno}, @var{mode})
2075 A C expression for the number of consecutive hard registers, starting
2076 at register number @var{regno}, required to hold a value of mode
2077 @var{mode}.  This macro must never return zero, even if a register
2078 cannot hold the requested mode - indicate that with HARD_REGNO_MODE_OK
2079 and/or CANNOT_CHANGE_MODE_CLASS instead.
2080
2081 On a machine where all registers are exactly one word, a suitable
2082 definition of this macro is
2083
2084 @smallexample
2085 #define HARD_REGNO_NREGS(REGNO, MODE)            \
2086    ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1)  \
2087     / UNITS_PER_WORD)
2088 @end smallexample
2089 @end defmac
2090
2091 @defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode})
2092 A C expression that is nonzero if a value of mode @var{mode}, stored
2093 in memory, ends with padding that causes it to take up more space than
2094 in registers starting at register number @var{regno} (as determined by
2095 multiplying GCC's notion of the size of the register when containing
2096 this mode by the number of registers returned by
2097 @code{HARD_REGNO_NREGS}).  By default this is zero.
2098
2099 For example, if a floating-point value is stored in three 32-bit
2100 registers but takes up 128 bits in memory, then this would be
2101 nonzero.
2102
2103 This macros only needs to be defined if there are cases where
2104 @code{subreg_get_info}
2105 would otherwise wrongly determine that a @code{subreg} can be
2106 represented by an offset to the register number, when in fact such a
2107 @code{subreg} would contain some of the padding not stored in
2108 registers and so not be representable.
2109 @end defmac
2110
2111 @defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode})
2112 For values of @var{regno} and @var{mode} for which
2113 @code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression
2114 returning the greater number of registers required to hold the value
2115 including any padding.  In the example above, the value would be four.
2116 @end defmac
2117
2118 @defmac REGMODE_NATURAL_SIZE (@var{mode})
2119 Define this macro if the natural size of registers that hold values
2120 of mode @var{mode} is not the word size.  It is a C expression that
2121 should give the natural size in bytes for the specified mode.  It is
2122 used by the register allocator to try to optimize its results.  This
2123 happens for example on SPARC 64-bit where the natural size of
2124 floating-point registers is still 32-bit.
2125 @end defmac
2126
2127 @defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
2128 A C expression that is nonzero if it is permissible to store a value
2129 of mode @var{mode} in hard register number @var{regno} (or in several
2130 registers starting with that one).  For a machine where all registers
2131 are equivalent, a suitable definition is
2132
2133 @smallexample
2134 #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
2135 @end smallexample
2136
2137 You need not include code to check for the numbers of fixed registers,
2138 because the allocation mechanism considers them to be always occupied.
2139
2140 @cindex register pairs
2141 On some machines, double-precision values must be kept in even/odd
2142 register pairs.  You can implement that by defining this macro to reject
2143 odd register numbers for such modes.
2144
2145 The minimum requirement for a mode to be OK in a register is that the
2146 @samp{mov@var{mode}} instruction pattern support moves between the
2147 register and other hard register in the same class and that moving a
2148 value into the register and back out not alter it.
2149
2150 Since the same instruction used to move @code{word_mode} will work for
2151 all narrower integer modes, it is not necessary on any machine for
2152 @code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided
2153 you define patterns @samp{movhi}, etc., to take advantage of this.  This
2154 is useful because of the interaction between @code{HARD_REGNO_MODE_OK}
2155 and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes
2156 to be tieable.
2157
2158 Many machines have special registers for floating point arithmetic.
2159 Often people assume that floating point machine modes are allowed only
2160 in floating point registers.  This is not true.  Any registers that
2161 can hold integers can safely @emph{hold} a floating point machine
2162 mode, whether or not floating arithmetic can be done on it in those
2163 registers.  Integer move instructions can be used to move the values.
2164
2165 On some machines, though, the converse is true: fixed-point machine
2166 modes may not go in floating registers.  This is true if the floating
2167 registers normalize any value stored in them, because storing a
2168 non-floating value there would garble it.  In this case,
2169 @code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in
2170 floating registers.  But if the floating registers do not automatically
2171 normalize, if you can store any bit pattern in one and retrieve it
2172 unchanged without a trap, then any machine mode may go in a floating
2173 register, so you can define this macro to say so.
2174
2175 The primary significance of special floating registers is rather that
2176 they are the registers acceptable in floating point arithmetic
2177 instructions.  However, this is of no concern to
2178 @code{HARD_REGNO_MODE_OK}.  You handle it by writing the proper
2179 constraints for those instructions.
2180
2181 On some machines, the floating registers are especially slow to access,
2182 so that it is better to store a value in a stack frame than in such a
2183 register if floating point arithmetic is not being done.  As long as the
2184 floating registers are not in class @code{GENERAL_REGS}, they will not
2185 be used unless some pattern's constraint asks for one.
2186 @end defmac
2187
2188 @defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to})
2189 A C expression that is nonzero if it is OK to rename a hard register
2190 @var{from} to another hard register @var{to}.
2191
2192 One common use of this macro is to prevent renaming of a register to
2193 another register that is not saved by a prologue in an interrupt
2194 handler.
2195
2196 The default is always nonzero.
2197 @end defmac
2198
2199 @defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2})
2200 A C expression that is nonzero if a value of mode
2201 @var{mode1} is accessible in mode @var{mode2} without copying.
2202
2203 If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
2204 @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for
2205 any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})}
2206 should be nonzero.  If they differ for any @var{r}, you should define
2207 this macro to return zero unless some other mechanism ensures the
2208 accessibility of the value in a narrower mode.
2209
2210 You should define this macro to return nonzero in as many cases as
2211 possible since doing so will allow GCC to perform better register
2212 allocation.
2213 @end defmac
2214
2215 @hook TARGET_HARD_REGNO_SCRATCH_OK
2216 This target hook should return @code{true} if it is OK to use a hard register
2217 @var{regno} as scratch reg in peephole2.
2218
2219 One common use of this macro is to prevent using of a register that
2220 is not saved by a prologue in an interrupt handler.
2221
2222 The default version of this hook always returns @code{true}.
2223 @end deftypefn
2224
2225 @defmac AVOID_CCMODE_COPIES
2226 Define this macro if the compiler should avoid copies to/from @code{CCmode}
2227 registers.  You should only define this macro if support for copying to/from
2228 @code{CCmode} is incomplete.
2229 @end defmac
2230
2231 @node Leaf Functions
2232 @subsection Handling Leaf Functions
2233
2234 @cindex leaf functions
2235 @cindex functions, leaf
2236 On some machines, a leaf function (i.e., one which makes no calls) can run
2237 more efficiently if it does not make its own register window.  Often this
2238 means it is required to receive its arguments in the registers where they
2239 are passed by the caller, instead of the registers where they would
2240 normally arrive.
2241
2242 The special treatment for leaf functions generally applies only when
2243 other conditions are met; for example, often they may use only those
2244 registers for its own variables and temporaries.  We use the term ``leaf
2245 function'' to mean a function that is suitable for this special
2246 handling, so that functions with no calls are not necessarily ``leaf
2247 functions''.
2248
2249 GCC assigns register numbers before it knows whether the function is
2250 suitable for leaf function treatment.  So it needs to renumber the
2251 registers in order to output a leaf function.  The following macros
2252 accomplish this.
2253
2254 @defmac LEAF_REGISTERS
2255 Name of a char vector, indexed by hard register number, which
2256 contains 1 for a register that is allowable in a candidate for leaf
2257 function treatment.
2258
2259 If leaf function treatment involves renumbering the registers, then the
2260 registers marked here should be the ones before renumbering---those that
2261 GCC would ordinarily allocate.  The registers which will actually be
2262 used in the assembler code, after renumbering, should not be marked with 1
2263 in this vector.
2264
2265 Define this macro only if the target machine offers a way to optimize
2266 the treatment of leaf functions.
2267 @end defmac
2268
2269 @defmac LEAF_REG_REMAP (@var{regno})
2270 A C expression whose value is the register number to which @var{regno}
2271 should be renumbered, when a function is treated as a leaf function.
2272
2273 If @var{regno} is a register number which should not appear in a leaf
2274 function before renumbering, then the expression should yield @minus{}1, which
2275 will cause the compiler to abort.
2276
2277 Define this macro only if the target machine offers a way to optimize the
2278 treatment of leaf functions, and registers need to be renumbered to do
2279 this.
2280 @end defmac
2281
2282 @findex current_function_is_leaf
2283 @findex current_function_uses_only_leaf_regs
2284 @code{TARGET_ASM_FUNCTION_PROLOGUE} and
2285 @code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions
2286 specially.  They can test the C variable @code{current_function_is_leaf}
2287 which is nonzero for leaf functions.  @code{current_function_is_leaf} is
2288 set prior to local register allocation and is valid for the remaining
2289 compiler passes.  They can also test the C variable
2290 @code{current_function_uses_only_leaf_regs} which is nonzero for leaf
2291 functions which only use leaf registers.
2292 @code{current_function_uses_only_leaf_regs} is valid after all passes
2293 that modify the instructions have been run and is only useful if
2294 @code{LEAF_REGISTERS} is defined.
2295 @c changed this to fix overfull.  ALSO:  why the "it" at the beginning
2296 @c of the next paragraph?!  --mew 2feb93
2297
2298 @node Stack Registers
2299 @subsection Registers That Form a Stack
2300
2301 There are special features to handle computers where some of the
2302 ``registers'' form a stack.  Stack registers are normally written by
2303 pushing onto the stack, and are numbered relative to the top of the
2304 stack.
2305
2306 Currently, GCC can only handle one group of stack-like registers, and
2307 they must be consecutively numbered.  Furthermore, the existing
2308 support for stack-like registers is specific to the 80387 floating
2309 point coprocessor.  If you have a new architecture that uses
2310 stack-like registers, you will need to do substantial work on
2311 @file{reg-stack.c} and write your machine description to cooperate
2312 with it, as well as defining these macros.
2313
2314 @defmac STACK_REGS
2315 Define this if the machine has any stack-like registers.
2316 @end defmac
2317
2318 @defmac STACK_REG_COVER_CLASS
2319 This is a cover class containing the stack registers.  Define this if
2320 the machine has any stack-like registers.
2321 @end defmac
2322
2323 @defmac FIRST_STACK_REG
2324 The number of the first stack-like register.  This one is the top
2325 of the stack.
2326 @end defmac
2327
2328 @defmac LAST_STACK_REG
2329 The number of the last stack-like register.  This one is the bottom of
2330 the stack.
2331 @end defmac
2332
2333 @node Register Classes
2334 @section Register Classes
2335 @cindex register class definitions
2336 @cindex class definitions, register
2337
2338 On many machines, the numbered registers are not all equivalent.
2339 For example, certain registers may not be allowed for indexed addressing;
2340 certain registers may not be allowed in some instructions.  These machine
2341 restrictions are described to the compiler using @dfn{register classes}.
2342
2343 You define a number of register classes, giving each one a name and saying
2344 which of the registers belong to it.  Then you can specify register classes
2345 that are allowed as operands to particular instruction patterns.
2346
2347 @findex ALL_REGS
2348 @findex NO_REGS
2349 In general, each register will belong to several classes.  In fact, one
2350 class must be named @code{ALL_REGS} and contain all the registers.  Another
2351 class must be named @code{NO_REGS} and contain no registers.  Often the
2352 union of two classes will be another class; however, this is not required.
2353
2354 @findex GENERAL_REGS
2355 One of the classes must be named @code{GENERAL_REGS}.  There is nothing
2356 terribly special about the name, but the operand constraint letters
2357 @samp{r} and @samp{g} specify this class.  If @code{GENERAL_REGS} is
2358 the same as @code{ALL_REGS}, just define it as a macro which expands
2359 to @code{ALL_REGS}.
2360
2361 Order the classes so that if class @var{x} is contained in class @var{y}
2362 then @var{x} has a lower class number than @var{y}.
2363
2364 The way classes other than @code{GENERAL_REGS} are specified in operand
2365 constraints is through machine-dependent operand constraint letters.
2366 You can define such letters to correspond to various classes, then use
2367 them in operand constraints.
2368
2369 You should define a class for the union of two classes whenever some
2370 instruction allows both classes.  For example, if an instruction allows
2371 either a floating point (coprocessor) register or a general register for a
2372 certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
2373 which includes both of them.  Otherwise you will get suboptimal code.
2374
2375 You must also specify certain redundant information about the register
2376 classes: for each class, which classes contain it and which ones are
2377 contained in it; for each pair of classes, the largest class contained
2378 in their union.
2379
2380 When a value occupying several consecutive registers is expected in a
2381 certain class, all the registers used must belong to that class.
2382 Therefore, register classes cannot be used to enforce a requirement for
2383 a register pair to start with an even-numbered register.  The way to
2384 specify this requirement is with @code{HARD_REGNO_MODE_OK}.
2385
2386 Register classes used for input-operands of bitwise-and or shift
2387 instructions have a special requirement: each such class must have, for
2388 each fixed-point machine mode, a subclass whose registers can transfer that
2389 mode to or from memory.  For example, on some machines, the operations for
2390 single-byte values (@code{QImode}) are limited to certain registers.  When
2391 this is so, each register class that is used in a bitwise-and or shift
2392 instruction must have a subclass consisting of registers from which
2393 single-byte values can be loaded or stored.  This is so that
2394 @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
2395
2396 @deftp {Data type} {enum reg_class}
2397 An enumerated type that must be defined with all the register class names
2398 as enumerated values.  @code{NO_REGS} must be first.  @code{ALL_REGS}
2399 must be the last register class, followed by one more enumerated value,
2400 @code{LIM_REG_CLASSES}, which is not a register class but rather
2401 tells how many classes there are.
2402
2403 Each register class has a number, which is the value of casting
2404 the class name to type @code{int}.  The number serves as an index
2405 in many of the tables described below.
2406 @end deftp
2407
2408 @defmac N_REG_CLASSES
2409 The number of distinct register classes, defined as follows:
2410
2411 @smallexample
2412 #define N_REG_CLASSES (int) LIM_REG_CLASSES
2413 @end smallexample
2414 @end defmac
2415
2416 @defmac REG_CLASS_NAMES
2417 An initializer containing the names of the register classes as C string
2418 constants.  These names are used in writing some of the debugging dumps.
2419 @end defmac
2420
2421 @defmac REG_CLASS_CONTENTS
2422 An initializer containing the contents of the register classes, as integers
2423 which are bit masks.  The @var{n}th integer specifies the contents of class
2424 @var{n}.  The way the integer @var{mask} is interpreted is that
2425 register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
2426
2427 When the machine has more than 32 registers, an integer does not suffice.
2428 Then the integers are replaced by sub-initializers, braced groupings containing
2429 several integers.  Each sub-initializer must be suitable as an initializer
2430 for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
2431 In this situation, the first integer in each sub-initializer corresponds to
2432 registers 0 through 31, the second integer to registers 32 through 63, and
2433 so on.
2434 @end defmac
2435
2436 @defmac REGNO_REG_CLASS (@var{regno})
2437 A C expression whose value is a register class containing hard register
2438 @var{regno}.  In general there is more than one such class; choose a class
2439 which is @dfn{minimal}, meaning that no smaller class also contains the
2440 register.
2441 @end defmac
2442
2443 @defmac BASE_REG_CLASS
2444 A macro whose definition is the name of the class to which a valid
2445 base register must belong.  A base register is one used in an address
2446 which is the register value plus a displacement.
2447 @end defmac
2448
2449 @defmac MODE_BASE_REG_CLASS (@var{mode})
2450 This is a variation of the @code{BASE_REG_CLASS} macro which allows
2451 the selection of a base register in a mode dependent manner.  If
2452 @var{mode} is VOIDmode then it should return the same value as
2453 @code{BASE_REG_CLASS}.
2454 @end defmac
2455
2456 @defmac MODE_BASE_REG_REG_CLASS (@var{mode})
2457 A C expression whose value is the register class to which a valid
2458 base register must belong in order to be used in a base plus index
2459 register address.  You should define this macro if base plus index
2460 addresses have different requirements than other base register uses.
2461 @end defmac
2462
2463 @defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{outer_code}, @var{index_code})
2464 A C expression whose value is the register class to which a valid
2465 base register must belong.  @var{outer_code} and @var{index_code} define the
2466 context in which the base register occurs.  @var{outer_code} is the code of
2467 the immediately enclosing expression (@code{MEM} for the top level of an
2468 address, @code{ADDRESS} for something that occurs in an
2469 @code{address_operand}).  @var{index_code} is the code of the corresponding
2470 index expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise.
2471 @end defmac
2472
2473 @defmac INDEX_REG_CLASS
2474 A macro whose definition is the name of the class to which a valid
2475 index register must belong.  An index register is one used in an
2476 address where its value is either multiplied by a scale factor or
2477 added to another register (as well as added to a displacement).
2478 @end defmac
2479
2480 @defmac REGNO_OK_FOR_BASE_P (@var{num})
2481 A C expression which is nonzero if register number @var{num} is
2482 suitable for use as a base register in operand addresses.
2483 Like @code{TARGET_LEGITIMATE_ADDRESS_P}, this macro should also
2484 define a strict and a non-strict variant.  Both variants behave
2485 the same for hard register; for pseudos, the strict variant will
2486 pass only those that have been allocated to a valid hard registers,
2487 while the non-strict variant will pass all pseudos.
2488
2489 @findex REG_OK_STRICT
2490 Compiler source files that want to use the strict variant of this and
2491 other macros define the macro @code{REG_OK_STRICT}.  You should use an
2492 @code{#ifdef REG_OK_STRICT} conditional to define the strict variant in
2493 that case and the non-strict variant otherwise.
2494 @end defmac
2495
2496 @defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode})
2497 A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that
2498 that expression may examine the mode of the memory reference in
2499 @var{mode}.  You should define this macro if the mode of the memory
2500 reference affects whether a register may be used as a base register.  If
2501 you define this macro, the compiler will use it instead of
2502 @code{REGNO_OK_FOR_BASE_P}.  The mode may be @code{VOIDmode} for
2503 addresses that appear outside a @code{MEM}, i.e., as an
2504 @code{address_operand}.
2505
2506 This macro also has strict and non-strict variants.
2507 @end defmac
2508
2509 @defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode})
2510 A C expression which is nonzero if register number @var{num} is suitable for
2511 use as a base register in base plus index operand addresses, accessing
2512 memory in mode @var{mode}.  It may be either a suitable hard register or a
2513 pseudo register that has been allocated such a hard register.  You should
2514 define this macro if base plus index addresses have different requirements
2515 than other base register uses.
2516
2517 Use of this macro is deprecated; please use the more general
2518 @code{REGNO_MODE_CODE_OK_FOR_BASE_P}.
2519
2520 This macro also has strict and non-strict variants.
2521 @end defmac
2522
2523 @defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{outer_code}, @var{index_code})
2524 A C expression that is just like @code{REGNO_MODE_OK_FOR_BASE_P}, except
2525 that that expression may examine the context in which the register
2526 appears in the memory reference.  @var{outer_code} is the code of the
2527 immediately enclosing expression (@code{MEM} if at the top level of the
2528 address, @code{ADDRESS} for something that occurs in an
2529 @code{address_operand}).  @var{index_code} is the code of the
2530 corresponding index expression if @var{outer_code} is @code{PLUS};
2531 @code{SCRATCH} otherwise.  The mode may be @code{VOIDmode} for addresses
2532 that appear outside a @code{MEM}, i.e., as an @code{address_operand}.
2533
2534 This macro also has strict and non-strict variants.
2535 @end defmac
2536
2537 @defmac REGNO_OK_FOR_INDEX_P (@var{num})
2538 A C expression which is nonzero if register number @var{num} is
2539 suitable for use as an index register in operand addresses.  It may be
2540 either a suitable hard register or a pseudo register that has been
2541 allocated such a hard register.
2542
2543 The difference between an index register and a base register is that
2544 the index register may be scaled.  If an address involves the sum of
2545 two registers, neither one of them scaled, then either one may be
2546 labeled the ``base'' and the other the ``index''; but whichever
2547 labeling is used must fit the machine's constraints of which registers
2548 may serve in each capacity.  The compiler will try both labelings,
2549 looking for one that is valid, and will reload one or both registers
2550 only if neither labeling works.
2551
2552 This macro also has strict and non-strict variants.
2553 @end defmac
2554
2555 @hook TARGET_PREFERRED_RELOAD_CLASS
2556 A target hook that places additional restrictions on the register class
2557 to use when it is necessary to copy value @var{x} into a register in class
2558 @var{rclass}.  The value is a register class; perhaps @var{rclass}, or perhaps
2559 another, smaller class.
2560
2561 The default version of this hook always returns value of @code{rclass} argument.
2562
2563 Sometimes returning a more restrictive class makes better code.  For
2564 example, on the 68000, when @var{x} is an integer constant that is in range
2565 for a @samp{moveq} instruction, the value of this macro is always
2566 @code{DATA_REGS} as long as @var{rclass} includes the data registers.
2567 Requiring a data register guarantees that a @samp{moveq} will be used.
2568
2569 One case where @code{TARGET_PREFERRED_RELOAD_CLASS} must not return
2570 @var{rclass} is if @var{x} is a legitimate constant which cannot be
2571 loaded into some register class.  By returning @code{NO_REGS} you can
2572 force @var{x} into a memory location.  For example, rs6000 can load
2573 immediate values into general-purpose registers, but does not have an
2574 instruction for loading an immediate value into a floating-point
2575 register, so @code{TARGET_PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when
2576 @var{x} is a floating-point constant.  If the constant can't be loaded
2577 into any kind of register, code generation will be better if
2578 @code{LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead
2579 of using @code{TARGET_PREFERRED_RELOAD_CLASS}.
2580
2581 If an insn has pseudos in it after register allocation, reload will go
2582 through the alternatives and call repeatedly @code{TARGET_PREFERRED_RELOAD_CLASS}
2583 to find the best one.  Returning @code{NO_REGS}, in this case, makes
2584 reload add a @code{!} in front of the constraint: the x86 back-end uses
2585 this feature to discourage usage of 387 registers when math is done in
2586 the SSE registers (and vice versa).
2587 @end deftypefn
2588
2589 @defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
2590 A C expression that places additional restrictions on the register class
2591 to use when it is necessary to copy value @var{x} into a register in class
2592 @var{class}.  The value is a register class; perhaps @var{class}, or perhaps
2593 another, smaller class.  On many machines, the following definition is
2594 safe:
2595
2596 @smallexample
2597 #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
2598 @end smallexample
2599
2600 Sometimes returning a more restrictive class makes better code.  For
2601 example, on the 68000, when @var{x} is an integer constant that is in range
2602 for a @samp{moveq} instruction, the value of this macro is always
2603 @code{DATA_REGS} as long as @var{class} includes the data registers.
2604 Requiring a data register guarantees that a @samp{moveq} will be used.
2605
2606 One case where @code{PREFERRED_RELOAD_CLASS} must not return
2607 @var{class} is if @var{x} is a legitimate constant which cannot be
2608 loaded into some register class.  By returning @code{NO_REGS} you can
2609 force @var{x} into a memory location.  For example, rs6000 can load
2610 immediate values into general-purpose registers, but does not have an
2611 instruction for loading an immediate value into a floating-point
2612 register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when
2613 @var{x} is a floating-point constant.  If the constant can't be loaded
2614 into any kind of register, code generation will be better if
2615 @code{LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead
2616 of using @code{PREFERRED_RELOAD_CLASS}.
2617
2618 If an insn has pseudos in it after register allocation, reload will go
2619 through the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS}
2620 to find the best one.  Returning @code{NO_REGS}, in this case, makes
2621 reload add a @code{!} in front of the constraint: the x86 back-end uses
2622 this feature to discourage usage of 387 registers when math is done in
2623 the SSE registers (and vice versa).
2624 @end defmac
2625
2626 @defmac PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class})
2627 Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of
2628 input reloads.  If you don't define this macro, the default is to use
2629 @var{class}, unchanged.
2630
2631 You can also use @code{PREFERRED_OUTPUT_RELOAD_CLASS} to discourage
2632 reload from using some alternatives, like @code{PREFERRED_RELOAD_CLASS}.
2633 @end defmac
2634
2635 @hook TARGET_PREFERRED_OUTPUT_RELOAD_CLASS
2636 Like @code{TARGET_PREFERRED_RELOAD_CLASS}, but for output reloads instead of
2637 input reloads.
2638
2639 The default version of this hook always returns value of @code{rclass}
2640 argument.
2641
2642 You can also use @code{TARGET_PREFERRED_OUTPUT_RELOAD_CLASS} to discourage
2643 reload from using some alternatives, like @code{TARGET_PREFERRED_RELOAD_CLASS}.
2644 @end deftypefn
2645
2646 @defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class})
2647 A C expression that places additional restrictions on the register class
2648 to use when it is necessary to be able to hold a value of mode
2649 @var{mode} in a reload register for which class @var{class} would
2650 ordinarily be used.
2651
2652 Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when
2653 there are certain modes that simply can't go in certain reload classes.
2654
2655 The value is a register class; perhaps @var{class}, or perhaps another,
2656 smaller class.
2657
2658 Don't define this macro unless the target machine has limitations which
2659 require the macro to do something nontrivial.
2660 @end defmac
2661
2662 @hook TARGET_SECONDARY_RELOAD
2663 Many machines have some registers that cannot be copied directly to or
2664 from memory or even from other types of registers.  An example is the
2665 @samp{MQ} register, which on most machines, can only be copied to or
2666 from general registers, but not memory.  Below, we shall be using the
2667 term 'intermediate register' when a move operation cannot be performed
2668 directly, but has to be done by copying the source into the intermediate
2669 register first, and then copying the intermediate register to the
2670 destination.  An intermediate register always has the same mode as
2671 source and destination.  Since it holds the actual value being copied,
2672 reload might apply optimizations to re-use an intermediate register
2673 and eliding the copy from the source when it can determine that the
2674 intermediate register still holds the required value.
2675
2676 Another kind of secondary reload is required on some machines which
2677 allow copying all registers to and from memory, but require a scratch
2678 register for stores to some memory locations (e.g., those with symbolic
2679 address on the RT, and those with certain symbolic address on the SPARC
2680 when compiling PIC)@.  Scratch registers need not have the same mode
2681 as the value being copied, and usually hold a different value than
2682 that being copied.  Special patterns in the md file are needed to
2683 describe how the copy is performed with the help of the scratch register;
2684 these patterns also describe the number, register class(es) and mode(s)
2685 of the scratch register(s).
2686
2687 In some cases, both an intermediate and a scratch register are required.
2688
2689 For input reloads, this target hook is called with nonzero @var{in_p},
2690 and @var{x} is an rtx that needs to be copied to a register of class
2691 @var{reload_class} in @var{reload_mode}.  For output reloads, this target
2692 hook is called with zero @var{in_p}, and a register of class @var{reload_class}
2693 needs to be copied to rtx @var{x} in @var{reload_mode}.
2694
2695 If copying a register of @var{reload_class} from/to @var{x} requires
2696 an intermediate register, the hook @code{secondary_reload} should
2697 return the register class required for this intermediate register.
2698 If no intermediate register is required, it should return NO_REGS.
2699 If more than one intermediate register is required, describe the one
2700 that is closest in the copy chain to the reload register.
2701
2702 If scratch registers are needed, you also have to describe how to
2703 perform the copy from/to the reload register to/from this
2704 closest intermediate register.  Or if no intermediate register is
2705 required, but still a scratch register is needed, describe the
2706 copy  from/to the reload register to/from the reload operand @var{x}.
2707
2708 You do this by setting @code{sri->icode} to the instruction code of a pattern
2709 in the md file which performs the move.  Operands 0 and 1 are the output
2710 and input of this copy, respectively.  Operands from operand 2 onward are
2711 for scratch operands.  These scratch operands must have a mode, and a
2712 single-register-class
2713 @c [later: or memory]
2714 output constraint.
2715
2716 When an intermediate register is used, the @code{secondary_reload}
2717 hook will be called again to determine how to copy the intermediate
2718 register to/from the reload operand @var{x}, so your hook must also
2719 have code to handle the register class of the intermediate operand.
2720
2721 @c [For later: maybe we'll allow multi-alternative reload patterns -
2722 @c   the port maintainer could name a mov<mode> pattern that has clobbers -
2723 @c   and match the constraints of input and output to determine the required
2724 @c   alternative.  A restriction would be that constraints used to match
2725 @c   against reloads registers would have to be written as register class
2726 @c   constraints, or we need a new target macro / hook that tells us if an
2727 @c   arbitrary constraint can match an unknown register of a given class.
2728 @c   Such a macro / hook would also be useful in other places.]
2729
2730
2731 @var{x} might be a pseudo-register or a @code{subreg} of a
2732 pseudo-register, which could either be in a hard register or in memory.
2733 Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is
2734 in memory and the hard register number if it is in a register.
2735
2736 Scratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are
2737 currently not supported.  For the time being, you will have to continue
2738 to use @code{SECONDARY_MEMORY_NEEDED} for that purpose.
2739
2740 @code{copy_cost} also uses this target hook to find out how values are
2741 copied.  If you want it to include some extra cost for the need to allocate
2742 (a) scratch register(s), set @code{sri->extra_cost} to the additional cost.
2743 Or if two dependent moves are supposed to have a lower cost than the sum
2744 of the individual moves due to expected fortuitous scheduling and/or special
2745 forwarding logic, you can set @code{sri->extra_cost} to a negative amount.
2746 @end deftypefn
2747
2748 @defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
2749 @defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
2750 @defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
2751 These macros are obsolete, new ports should use the target hook
2752 @code{TARGET_SECONDARY_RELOAD} instead.
2753
2754 These are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD}
2755 target hook.  Older ports still define these macros to indicate to the
2756 reload phase that it may
2757 need to allocate at least one register for a reload in addition to the
2758 register to contain the data.  Specifically, if copying @var{x} to a
2759 register @var{class} in @var{mode} requires an intermediate register,
2760 you were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the
2761 largest register class all of whose registers can be used as
2762 intermediate registers or scratch registers.
2763
2764 If copying a register @var{class} in @var{mode} to @var{x} requires an
2765 intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS}
2766 was supposed to be defined be defined to return the largest register
2767 class required.  If the
2768 requirements for input and output reloads were the same, the macro
2769 @code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both
2770 macros identically.
2771
2772 The values returned by these macros are often @code{GENERAL_REGS}.
2773 Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x}
2774 can be directly copied to or from a register of @var{class} in
2775 @var{mode} without requiring a scratch register.  Do not define this
2776 macro if it would always return @code{NO_REGS}.
2777
2778 If a scratch register is required (either with or without an
2779 intermediate register), you were supposed to define patterns for
2780 @samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required
2781 (@pxref{Standard Names}.  These patterns, which were normally
2782 implemented with a @code{define_expand}, should be similar to the
2783 @samp{mov@var{m}} patterns, except that operand 2 is the scratch
2784 register.
2785
2786 These patterns need constraints for the reload register and scratch
2787 register that
2788 contain a single register class.  If the original reload register (whose
2789 class is @var{class}) can meet the constraint given in the pattern, the
2790 value returned by these macros is used for the class of the scratch
2791 register.  Otherwise, two additional reload registers are required.
2792 Their classes are obtained from the constraints in the insn pattern.
2793
2794 @var{x} might be a pseudo-register or a @code{subreg} of a
2795 pseudo-register, which could either be in a hard register or in memory.
2796 Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is
2797 in memory and the hard register number if it is in a register.
2798
2799 These macros should not be used in the case where a particular class of
2800 registers can only be copied to memory and not to another class of
2801 registers.  In that case, secondary reload registers are not needed and
2802 would not be helpful.  Instead, a stack location must be used to perform
2803 the copy and the @code{mov@var{m}} pattern should use memory as an
2804 intermediate storage.  This case often occurs between floating-point and
2805 general registers.
2806 @end defmac
2807
2808 @defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m})
2809 Certain machines have the property that some registers cannot be copied
2810 to some other registers without using memory.  Define this macro on
2811 those machines to be a C expression that is nonzero if objects of mode
2812 @var{m} in registers of @var{class1} can only be copied to registers of
2813 class @var{class2} by storing a register of @var{class1} into memory
2814 and loading that memory location into a register of @var{class2}.
2815
2816 Do not define this macro if its value would always be zero.
2817 @end defmac
2818
2819 @defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode})
2820 Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler
2821 allocates a stack slot for a memory location needed for register copies.
2822 If this macro is defined, the compiler instead uses the memory location
2823 defined by this macro.
2824
2825 Do not define this macro if you do not define
2826 @code{SECONDARY_MEMORY_NEEDED}.
2827 @end defmac
2828
2829 @defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode})
2830 When the compiler needs a secondary memory location to copy between two
2831 registers of mode @var{mode}, it normally allocates sufficient memory to
2832 hold a quantity of @code{BITS_PER_WORD} bits and performs the store and
2833 load operations in a mode that many bits wide and whose class is the
2834 same as that of @var{mode}.
2835
2836 This is right thing to do on most machines because it ensures that all
2837 bits of the register are copied and prevents accesses to the registers
2838 in a narrower mode, which some machines prohibit for floating-point
2839 registers.
2840
2841 However, this default behavior is not correct on some machines, such as
2842 the DEC Alpha, that store short integers in floating-point registers
2843 differently than in integer registers.  On those machines, the default
2844 widening will not work correctly and you must define this macro to
2845 suppress that widening in some cases.  See the file @file{alpha.h} for
2846 details.
2847
2848 Do not define this macro if you do not define
2849 @code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that
2850 is @code{BITS_PER_WORD} bits wide is correct for your machine.
2851 @end defmac
2852
2853 @hook TARGET_CLASS_LIKELY_SPILLED_P
2854 A target hook which returns @code{true} if pseudos that have been assigned
2855 to registers of class @var{rclass} would likely be spilled because
2856 registers of @var{rclass} are needed for spill registers.
2857
2858 The default version of this target hook returns @code{true} if @var{rclass}
2859 has exactly one register and @code{false} otherwise.  On most machines, this
2860 default should be used.  Only use this target hook to some other expression
2861 if pseudos allocated by @file{local-alloc.c} end up in memory because their
2862 hard registers were needed for spill registers.  If this target hook returns
2863 @code{false} for those classes, those pseudos will only be allocated by
2864 @file{global.c}, which knows how to reallocate the pseudo to another
2865 register.  If there would not be another register available for reallocation,
2866 you should not change the implementation of this target hook since
2867 the only effect of such implementation would be to slow down register
2868 allocation.
2869 @end deftypefn
2870
2871 @defmac CLASS_MAX_NREGS (@var{class}, @var{mode})
2872 A C expression for the maximum number of consecutive registers
2873 of class @var{class} needed to hold a value of mode @var{mode}.
2874
2875 This is closely related to the macro @code{HARD_REGNO_NREGS}.  In fact,
2876 the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
2877 should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno},
2878 @var{mode})} for all @var{regno} values in the class @var{class}.
2879
2880 This macro helps control the handling of multiple-word values
2881 in the reload pass.
2882 @end defmac
2883
2884 @defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class})
2885 If defined, a C expression that returns nonzero for a @var{class} for which
2886 a change from mode @var{from} to mode @var{to} is invalid.
2887
2888 For the example, loading 32-bit integer or floating-point objects into
2889 floating-point registers on the Alpha extends them to 64 bits.
2890 Therefore loading a 64-bit object and then storing it as a 32-bit object
2891 does not store the low-order 32 bits, as would be the case for a normal
2892 register.  Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS}
2893 as below:
2894
2895 @smallexample
2896 #define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \
2897   (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \
2898    ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0)
2899 @end smallexample
2900 @end defmac
2901
2902 @hook TARGET_IRA_COVER_CLASSES
2903 Return an array of cover classes for the Integrated Register Allocator
2904 (@acronym{IRA}).  Cover classes are a set of non-intersecting register
2905 classes covering all hard registers used for register allocation
2906 purposes.  If a move between two registers in the same cover class is
2907 possible, it should be cheaper than a load or store of the registers.
2908 The array is terminated by a @code{LIM_REG_CLASSES} element.
2909
2910 The order of cover classes in the array is important.  If two classes
2911 have the same cost of usage for a pseudo, the class occurred first in
2912 the array is chosen for the pseudo.
2913
2914 This hook is called once at compiler startup, after the command-line
2915 options have been processed. It is then re-examined by every call to
2916 @code{target_reinit}.
2917
2918 The default implementation returns @code{IRA_COVER_CLASSES}, if defined,
2919 otherwise there is no default implementation.  You must define either this
2920 macro or @code{IRA_COVER_CLASSES} in order to use the integrated register
2921 allocator with Chaitin-Briggs coloring. If the macro is not defined,
2922 the only available coloring algorithm is Chow's priority coloring.
2923 @end deftypefn
2924
2925 @defmac IRA_COVER_CLASSES
2926 See the documentation for @code{TARGET_IRA_COVER_CLASSES}.
2927 @end defmac
2928
2929 @node Old Constraints
2930 @section Obsolete Macros for Defining Constraints
2931 @cindex defining constraints, obsolete method
2932 @cindex constraints, defining, obsolete method
2933
2934 Machine-specific constraints can be defined with these macros instead
2935 of the machine description constructs described in @ref{Define
2936 Constraints}.  This mechanism is obsolete.  New ports should not use
2937 it; old ports should convert to the new mechanism.
2938
2939 @defmac CONSTRAINT_LEN (@var{char}, @var{str})
2940 For the constraint at the start of @var{str}, which starts with the letter
2941 @var{c}, return the length.  This allows you to have register class /
2942 constant / extra constraints that are longer than a single letter;
2943 you don't need to define this macro if you can do with single-letter
2944 constraints only.  The definition of this macro should use
2945 DEFAULT_CONSTRAINT_LEN for all the characters that you don't want
2946 to handle specially.
2947 There are some sanity checks in genoutput.c that check the constraint lengths
2948 for the md file, so you can also use this macro to help you while you are
2949 transitioning from a byzantine single-letter-constraint scheme: when you
2950 return a negative length for a constraint you want to re-use, genoutput
2951 will complain about every instance where it is used in the md file.
2952 @end defmac
2953
2954 @defmac REG_CLASS_FROM_LETTER (@var{char})
2955 A C expression which defines the machine-dependent operand constraint
2956 letters for register classes.  If @var{char} is such a letter, the
2957 value should be the register class corresponding to it.  Otherwise,
2958 the value should be @code{NO_REGS}.  The register letter @samp{r},
2959 corresponding to class @code{GENERAL_REGS}, will not be passed
2960 to this macro; you do not need to handle it.
2961 @end defmac
2962
2963 @defmac REG_CLASS_FROM_CONSTRAINT (@var{char}, @var{str})
2964 Like @code{REG_CLASS_FROM_LETTER}, but you also get the constraint string
2965 passed in @var{str}, so that you can use suffixes to distinguish between
2966 different variants.
2967 @end defmac
2968
2969 @defmac CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
2970 A C expression that defines the machine-dependent operand constraint
2971 letters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify
2972 particular ranges of integer values.  If @var{c} is one of those
2973 letters, the expression should check that @var{value}, an integer, is in
2974 the appropriate range and return 1 if so, 0 otherwise.  If @var{c} is
2975 not one of those letters, the value should be 0 regardless of
2976 @var{value}.
2977 @end defmac
2978
2979 @defmac CONST_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str})
2980 Like @code{CONST_OK_FOR_LETTER_P}, but you also get the constraint
2981 string passed in @var{str}, so that you can use suffixes to distinguish
2982 between different variants.
2983 @end defmac
2984
2985 @defmac CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
2986 A C expression that defines the machine-dependent operand constraint
2987 letters that specify particular ranges of @code{const_double} values
2988 (@samp{G} or @samp{H}).
2989
2990 If @var{c} is one of those letters, the expression should check that
2991 @var{value}, an RTX of code @code{const_double}, is in the appropriate
2992 range and return 1 if so, 0 otherwise.  If @var{c} is not one of those
2993 letters, the value should be 0 regardless of @var{value}.
2994
2995 @code{const_double} is used for all floating-point constants and for
2996 @code{DImode} fixed-point constants.  A given letter can accept either
2997 or both kinds of values.  It can use @code{GET_MODE} to distinguish
2998 between these kinds.
2999 @end defmac
3000
3001 @defmac CONST_DOUBLE_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str})
3002 Like @code{CONST_DOUBLE_OK_FOR_LETTER_P}, but you also get the constraint
3003 string passed in @var{str}, so that you can use suffixes to distinguish
3004 between different variants.
3005 @end defmac
3006
3007 @defmac EXTRA_CONSTRAINT (@var{value}, @var{c})
3008 A C expression that defines the optional machine-dependent constraint
3009 letters that can be used to segregate specific types of operands, usually
3010 memory references, for the target machine.  Any letter that is not
3011 elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} /
3012 @code{REG_CLASS_FROM_CONSTRAINT}
3013 may be used.  Normally this macro will not be defined.
3014
3015 If it is required for a particular target machine, it should return 1
3016 if @var{value} corresponds to the operand type represented by the
3017 constraint letter @var{c}.  If @var{c} is not defined as an extra
3018 constraint, the value returned should be 0 regardless of @var{value}.
3019
3020 For example, on the ROMP, load instructions cannot have their output
3021 in r0 if the memory reference contains a symbolic address.  Constraint
3022 letter @samp{Q} is defined as representing a memory address that does
3023 @emph{not} contain a symbolic address.  An alternative is specified with
3024 a @samp{Q} constraint on the input and @samp{r} on the output.  The next
3025 alternative specifies @samp{m} on the input and a register class that
3026 does not include r0 on the output.
3027 @end defmac
3028
3029 @defmac EXTRA_CONSTRAINT_STR (@var{value}, @var{c}, @var{str})
3030 Like @code{EXTRA_CONSTRAINT}, but you also get the constraint string passed
3031 in @var{str}, so that you can use suffixes to distinguish between different
3032 variants.
3033 @end defmac
3034
3035 @defmac EXTRA_MEMORY_CONSTRAINT (@var{c}, @var{str})
3036 A C expression that defines the optional machine-dependent constraint
3037 letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should
3038 be treated like memory constraints by the reload pass.
3039
3040 It should return 1 if the operand type represented by the constraint
3041 at the start of @var{str}, the first letter of which is the letter @var{c},
3042 comprises a subset of all memory references including
3043 all those whose address is simply a base register.  This allows the reload
3044 pass to reload an operand, if it does not directly correspond to the operand
3045 type of @var{c}, by copying its address into a base register.
3046
3047 For example, on the S/390, some instructions do not accept arbitrary
3048 memory references, but only those that do not make use of an index
3049 register.  The constraint letter @samp{Q} is defined via
3050 @code{EXTRA_CONSTRAINT} as representing a memory address of this type.
3051 If the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT},
3052 a @samp{Q} constraint can handle any memory operand, because the
3053 reload pass knows it can be reloaded by copying the memory address
3054 into a base register if required.  This is analogous to the way
3055 an @samp{o} constraint can handle any memory operand.
3056 @end defmac
3057
3058 @defmac EXTRA_ADDRESS_CONSTRAINT (@var{c}, @var{str})
3059 A C expression that defines the optional machine-dependent constraint
3060 letters, amongst those accepted by @code{EXTRA_CONSTRAINT} /
3061 @code{EXTRA_CONSTRAINT_STR}, that should
3062 be treated like address constraints by the reload pass.
3063
3064 It should return 1 if the operand type represented by the constraint
3065 at the start of @var{str}, which starts with the letter @var{c}, comprises
3066 a subset of all memory addresses including
3067 all those that consist of just a base register.  This allows the reload
3068 pass to reload an operand, if it does not directly correspond to the operand
3069 type of @var{str}, by copying it into a base register.
3070
3071 Any constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only
3072 be used with the @code{address_operand} predicate.  It is treated
3073 analogously to the @samp{p} constraint.
3074 @end defmac
3075
3076 @node Stack and Calling
3077 @section Stack Layout and Calling Conventions
3078 @cindex calling conventions
3079
3080 @c prevent bad page break with this line
3081 This describes the stack layout and calling conventions.
3082
3083 @menu
3084 * Frame Layout::
3085 * Exception Handling::
3086 * Stack Checking::
3087 * Frame Registers::
3088 * Elimination::
3089 * Stack Arguments::
3090 * Register Arguments::
3091 * Scalar Return::
3092 * Aggregate Return::
3093 * Caller Saves::
3094 * Function Entry::
3095 * Profiling::
3096 * Tail Calls::
3097 * Stack Smashing Protection::
3098 @end menu
3099
3100 @node Frame Layout
3101 @subsection Basic Stack Layout
3102 @cindex stack frame layout
3103 @cindex frame layout
3104
3105 @c prevent bad page break with this line
3106 Here is the basic stack layout.
3107
3108 @defmac STACK_GROWS_DOWNWARD
3109 Define this macro if pushing a word onto the stack moves the stack
3110 pointer to a smaller address.
3111
3112 When we say, ``define this macro if @dots{}'', it means that the
3113 compiler checks this macro only with @code{#ifdef} so the precise
3114 definition used does not matter.
3115 @end defmac
3116
3117 @defmac STACK_PUSH_CODE
3118 This macro defines the operation used when something is pushed
3119 on the stack.  In RTL, a push operation will be
3120 @code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})}
3121
3122 The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC},
3123 and @code{POST_INC}.  Which of these is correct depends on
3124 the stack direction and on whether the stack pointer points
3125 to the last item on the stack or whether it points to the
3126 space for the next item on the stack.
3127
3128 The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is
3129 defined, which is almost always right, and @code{PRE_INC} otherwise,
3130 which is often wrong.
3131 @end defmac
3132
3133 @defmac FRAME_GROWS_DOWNWARD
3134 Define this macro to nonzero value if the addresses of local variable slots
3135 are at negative offsets from the frame pointer.
3136 @end defmac
3137
3138 @defmac ARGS_GROW_DOWNWARD
3139 Define this macro if successive arguments to a function occupy decreasing
3140 addresses on the stack.
3141 @end defmac
3142
3143 @defmac STARTING_FRAME_OFFSET
3144 Offset from the frame pointer to the first local variable slot to be allocated.
3145
3146 If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by
3147 subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}.
3148 Otherwise, it is found by adding the length of the first slot to the
3149 value @code{STARTING_FRAME_OFFSET}.
3150 @c i'm not sure if the above is still correct.. had to change it to get
3151 @c rid of an overfull.  --mew 2feb93
3152 @end defmac
3153
3154 @defmac STACK_ALIGNMENT_NEEDED
3155 Define to zero to disable final alignment of the stack during reload.
3156 The nonzero default for this macro is suitable for most ports.
3157
3158 On ports where @code{STARTING_FRAME_OFFSET} is nonzero or where there
3159 is a register save block following the local block that doesn't require
3160 alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable
3161 stack alignment and do it in the backend.
3162 @end defmac
3163
3164 @defmac STACK_POINTER_OFFSET
3165 Offset from the stack pointer register to the first location at which
3166 outgoing arguments are placed.  If not specified, the default value of
3167 zero is used.  This is the proper value for most machines.
3168
3169 If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
3170 the first location at which outgoing arguments are placed.
3171 @end defmac
3172
3173 @defmac FIRST_PARM_OFFSET (@var{fundecl})
3174 Offset from the argument pointer register to the first argument's
3175 address.  On some machines it may depend on the data type of the
3176 function.
3177
3178 If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
3179 the first argument's address.
3180 @end defmac
3181
3182 @defmac STACK_DYNAMIC_OFFSET (@var{fundecl})
3183 Offset from the stack pointer register to an item dynamically allocated
3184 on the stack, e.g., by @code{alloca}.
3185
3186 The default value for this macro is @code{STACK_POINTER_OFFSET} plus the
3187 length of the outgoing arguments.  The default is correct for most
3188 machines.  See @file{function.c} for details.
3189 @end defmac
3190
3191 @defmac INITIAL_FRAME_ADDRESS_RTX
3192 A C expression whose value is RTL representing the address of the initial
3193 stack frame. This address is passed to @code{RETURN_ADDR_RTX} and
3194 @code{DYNAMIC_CHAIN_ADDRESS}.  If you don't define this macro, a reasonable
3195 default value will be used.  Define this macro in order to make frame pointer
3196 elimination work in the presence of @code{__builtin_frame_address (count)} and
3197 @code{__builtin_return_address (count)} for @code{count} not equal to zero.
3198 @end defmac
3199
3200 @defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr})
3201 A C expression whose value is RTL representing the address in a stack
3202 frame where the pointer to the caller's frame is stored.  Assume that
3203 @var{frameaddr} is an RTL expression for the address of the stack frame
3204 itself.
3205
3206 If you don't define this macro, the default is to return the value
3207 of @var{frameaddr}---that is, the stack frame address is also the
3208 address of the stack word that points to the previous frame.
3209 @end defmac
3210
3211 @defmac SETUP_FRAME_ADDRESSES
3212 If defined, a C expression that produces the machine-specific code to
3213 setup the stack so that arbitrary frames can be accessed.  For example,
3214 on the SPARC, we must flush all of the register windows to the stack
3215 before we can access arbitrary stack frames.  You will seldom need to
3216 define this macro.
3217 @end defmac
3218
3219 @hook TARGET_BUILTIN_SETJMP_FRAME_VALUE
3220 This target hook should return an rtx that is used to store
3221 the address of the current frame into the built in @code{setjmp} buffer.
3222 The default value, @code{virtual_stack_vars_rtx}, is correct for most
3223 machines.  One reason you may need to define this target hook is if
3224 @code{hard_frame_pointer_rtx} is the appropriate value on your machine.
3225 @end deftypefn
3226
3227 @defmac FRAME_ADDR_RTX (@var{frameaddr})
3228 A C expression whose value is RTL representing the value of the frame
3229 address for the current frame.  @var{frameaddr} is the frame pointer
3230 of the current frame.  This is used for __builtin_frame_address.
3231 You need only define this macro if the frame address is not the same
3232 as the frame pointer.  Most machines do not need to define it.
3233 @end defmac
3234
3235 @defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr})
3236 A C expression whose value is RTL representing the value of the return
3237 address for the frame @var{count} steps up from the current frame, after
3238 the prologue.  @var{frameaddr} is the frame pointer of the @var{count}
3239 frame, or the frame pointer of the @var{count} @minus{} 1 frame if
3240 @code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined.
3241
3242 The value of the expression must always be the correct address when
3243 @var{count} is zero, but may be @code{NULL_RTX} if there is no way to
3244 determine the return address of other frames.
3245 @end defmac
3246
3247 @defmac RETURN_ADDR_IN_PREVIOUS_FRAME
3248 Define this if the return address of a particular stack frame is accessed
3249 from the frame pointer of the previous stack frame.
3250 @end defmac
3251
3252 @defmac INCOMING_RETURN_ADDR_RTX
3253 A C expression whose value is RTL representing the location of the
3254 incoming return address at the beginning of any function, before the
3255 prologue.  This RTL is either a @code{REG}, indicating that the return
3256 value is saved in @samp{REG}, or a @code{MEM} representing a location in
3257 the stack.
3258
3259 You only need to define this macro if you want to support call frame
3260 debugging information like that provided by DWARF 2.
3261
3262 If this RTL is a @code{REG}, you should also define
3263 @code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}.
3264 @end defmac
3265
3266 @defmac DWARF_ALT_FRAME_RETURN_COLUMN
3267 A C expression whose value is an integer giving a DWARF 2 column
3268 number that may be used as an alternative return column.  The column
3269 must not correspond to any gcc hard register (that is, it must not
3270 be in the range of @code{DWARF_FRAME_REGNUM}).
3271
3272 This macro can be useful if @code{DWARF_FRAME_RETURN_COLUMN} is set to a
3273 general register, but an alternative column needs to be used for signal
3274 frames.  Some targets have also used different frame return columns
3275 over time.
3276 @end defmac
3277
3278 @defmac DWARF_ZERO_REG
3279 A C expression whose value is an integer giving a DWARF 2 register
3280 number that is considered to always have the value zero.  This should
3281 only be defined if the target has an architected zero register, and
3282 someone decided it was a good idea to use that register number to
3283 terminate the stack backtrace.  New ports should avoid this.
3284 @end defmac
3285
3286 @hook TARGET_DWARF_HANDLE_FRAME_UNSPEC
3287 This target hook allows the backend to emit frame-related insns that
3288 contain UNSPECs or UNSPEC_VOLATILEs.  The DWARF 2 call frame debugging
3289 info engine will invoke it on insns of the form
3290 @smallexample
3291 (set (reg) (unspec [@dots{}] UNSPEC_INDEX))
3292 @end smallexample
3293 and
3294 @smallexample
3295 (set (reg) (unspec_volatile [@dots{}] UNSPECV_INDEX)).
3296 @end smallexample
3297 to let the backend emit the call frame instructions.  @var{label} is
3298 the CFI label attached to the insn, @var{pattern} is the pattern of
3299 the insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}.
3300 @end deftypefn
3301
3302 @defmac INCOMING_FRAME_SP_OFFSET
3303 A C expression whose value is an integer giving the offset, in bytes,
3304 from the value of the stack pointer register to the top of the stack
3305 frame at the beginning of any function, before the prologue.  The top of
3306 the frame is defined to be the value of the stack pointer in the
3307 previous frame, just before the call instruction.
3308
3309 You only need to define this macro if you want to support call frame
3310 debugging information like that provided by DWARF 2.
3311 @end defmac
3312
3313 @defmac ARG_POINTER_CFA_OFFSET (@var{fundecl})
3314 A C expression whose value is an integer giving the offset, in bytes,
3315 from the argument pointer to the canonical frame address (cfa).  The
3316 final value should coincide with that calculated by
3317 @code{INCOMING_FRAME_SP_OFFSET}.  Which is unfortunately not usable
3318 during virtual register instantiation.
3319
3320 The default value for this macro is
3321 @code{FIRST_PARM_OFFSET (fundecl) + crtl->args.pretend_args_size},
3322 which is correct for most machines; in general, the arguments are found
3323 immediately before the stack frame.  Note that this is not the case on
3324 some targets that save registers into the caller's frame, such as SPARC
3325 and rs6000, and so such targets need to define this macro.
3326
3327 You only need to define this macro if the default is incorrect, and you
3328 want to support call frame debugging information like that provided by
3329 DWARF 2.
3330 @end defmac
3331
3332 @defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl})
3333 If defined, a C expression whose value is an integer giving the offset
3334 in bytes from the frame pointer to the canonical frame address (cfa).
3335 The final value should coincide with that calculated by
3336 @code{INCOMING_FRAME_SP_OFFSET}.
3337
3338 Normally the CFA is calculated as an offset from the argument pointer,
3339 via @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is
3340 variable due to the ABI, this may not be possible.  If this macro is
3341 defined, it implies that the virtual register instantiation should be
3342 based on the frame pointer instead of the argument pointer.  Only one
3343 of @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET}
3344 should be defined.
3345 @end defmac
3346
3347 @defmac CFA_FRAME_BASE_OFFSET (@var{fundecl})
3348 If defined, a C expression whose value is an integer giving the offset
3349 in bytes from the canonical frame address (cfa) to the frame base used
3350 in DWARF 2 debug information.  The default is zero.  A different value
3351 may reduce the size of debug information on some ports.
3352 @end defmac
3353
3354 @node Exception Handling
3355 @subsection Exception Handling Support
3356 @cindex exception handling
3357
3358 @defmac EH_RETURN_DATA_REGNO (@var{N})
3359 A C expression whose value is the @var{N}th register number used for
3360 data by exception handlers, or @code{INVALID_REGNUM} if fewer than
3361 @var{N} registers are usable.
3362
3363 The exception handling library routines communicate with the exception
3364 handlers via a set of agreed upon registers.  Ideally these registers
3365 should be call-clobbered; it is possible to use call-saved registers,
3366 but may negatively impact code size.  The target must support at least
3367 2 data registers, but should define 4 if there are enough free registers.
3368
3369 You must define this macro if you want to support call frame exception
3370 handling like that provided by DWARF 2.
3371 @end defmac
3372
3373 @defmac EH_RETURN_STACKADJ_RTX
3374 A C expression whose value is RTL representing a location in which
3375 to store a stack adjustment to be applied before function return.
3376 This is used to unwind the stack to an exception handler's call frame.
3377 It will be assigned zero on code paths that return normally.
3378
3379 Typically this is a call-clobbered hard register that is otherwise
3380 untouched by the epilogue, but could also be a stack slot.
3381
3382 Do not define this macro if the stack pointer is saved and restored
3383 by the regular prolog and epilog code in the call frame itself; in
3384 this case, the exception handling library routines will update the
3385 stack location to be restored in place.  Otherwise, you must define
3386 this macro if you want to support call frame exception handling like
3387 that provided by DWARF 2.
3388 @end defmac
3389
3390 @defmac EH_RETURN_HANDLER_RTX
3391 A C expression whose value is RTL representing a location in which
3392 to store the address of an exception handler to which we should
3393 return.  It will not be assigned on code paths that return normally.
3394
3395 Typically this is the location in the call frame at which the normal
3396 return address is stored.  For targets that return by popping an
3397 address off the stack, this might be a memory address just below
3398 the @emph{target} call frame rather than inside the current call
3399 frame.  If defined, @code{EH_RETURN_STACKADJ_RTX} will have already
3400 been assigned, so it may be used to calculate the location of the
3401 target call frame.
3402
3403 Some targets have more complex requirements than storing to an
3404 address calculable during initial code generation.  In that case
3405 the @code{eh_return} instruction pattern should be used instead.
3406
3407 If you want to support call frame exception handling, you must
3408 define either this macro or the @code{eh_return} instruction pattern.
3409 @end defmac
3410
3411 @defmac RETURN_ADDR_OFFSET
3412 If defined, an integer-valued C expression for which rtl will be generated
3413 to add it to the exception handler address before it is searched in the
3414 exception handling tables, and to subtract it again from the address before
3415 using it to return to the exception handler.
3416 @end defmac
3417
3418 @defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global})
3419 This macro chooses the encoding of pointers embedded in the exception
3420 handling sections.  If at all possible, this should be defined such
3421 that the exception handling section will not require dynamic relocations,
3422 and so may be read-only.
3423
3424 @var{code} is 0 for data, 1 for code labels, 2 for function pointers.
3425 @var{global} is true if the symbol may be affected by dynamic relocations.
3426 The macro should return a combination of the @code{DW_EH_PE_*} defines
3427 as found in @file{dwarf2.h}.
3428
3429 If this macro is not defined, pointers will not be encoded but
3430 represented directly.
3431 @end defmac
3432
3433 @defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done})
3434 This macro allows the target to emit whatever special magic is required
3435 to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}.
3436 Generic code takes care of pc-relative and indirect encodings; this must
3437 be defined if the target uses text-relative or data-relative encodings.
3438
3439 This is a C statement that branches to @var{done} if the format was
3440 handled.  @var{encoding} is the format chosen, @var{size} is the number
3441 of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF}
3442 to be emitted.
3443 @end defmac
3444
3445 @defmac MD_UNWIND_SUPPORT
3446 A string specifying a file to be #include'd in unwind-dw2.c.  The file
3447 so included typically defines @code{MD_FALLBACK_FRAME_STATE_FOR}.
3448 @end defmac
3449
3450 @defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs})
3451 This macro allows the target to add CPU and operating system specific
3452 code to the call-frame unwinder for use when there is no unwind data
3453 available.  The most common reason to implement this macro is to unwind
3454 through signal frames.
3455
3456 This macro is called from @code{uw_frame_state_for} in
3457 @file{unwind-dw2.c}, @file{unwind-dw2-xtensa.c} and
3458 @file{unwind-ia64.c}.  @var{context} is an @code{_Unwind_Context};
3459 @var{fs} is an @code{_Unwind_FrameState}.  Examine @code{context->ra}
3460 for the address of the code being executed and @code{context->cfa} for
3461 the stack pointer value.  If the frame can be decoded, the register
3462 save addresses should be updated in @var{fs} and the macro should
3463 evaluate to @code{_URC_NO_REASON}.  If the frame cannot be decoded,
3464 the macro should evaluate to @code{_URC_END_OF_STACK}.
3465
3466 For proper signal handling in Java this macro is accompanied by
3467 @code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers.
3468 @end defmac
3469
3470 @defmac MD_HANDLE_UNWABI (@var{context}, @var{fs})
3471 This macro allows the target to add operating system specific code to the
3472 call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive,
3473 usually used for signal or interrupt frames.
3474
3475 This macro is called from @code{uw_update_context} in @file{unwind-ia64.c}.
3476 @var{context} is an @code{_Unwind_Context};
3477 @var{fs} is an @code{_Unwind_FrameState}.  Examine @code{fs->unwabi}
3478 for the abi and context in the @code{.unwabi} directive.  If the
3479 @code{.unwabi} directive can be handled, the register save addresses should
3480 be updated in @var{fs}.
3481 @end defmac
3482
3483 @defmac TARGET_USES_WEAK_UNWIND_INFO
3484 A C expression that evaluates to true if the target requires unwind
3485 info to be given comdat linkage.  Define it to be @code{1} if comdat
3486 linkage is necessary.  The default is @code{0}.
3487 @end defmac
3488
3489 @node Stack Checking
3490 @subsection Specifying How Stack Checking is Done
3491
3492 GCC will check that stack references are within the boundaries of the
3493 stack, if the option @option{-fstack-check} is specified, in one of
3494 three ways:
3495
3496 @enumerate
3497 @item
3498 If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC
3499 will assume that you have arranged for full stack checking to be done
3500 at appropriate places in the configuration files.  GCC will not do
3501 other special processing.
3502
3503 @item
3504 If @code{STACK_CHECK_BUILTIN} is zero and the value of the
3505 @code{STACK_CHECK_STATIC_BUILTIN} macro is nonzero, GCC will assume
3506 that you have arranged for static stack checking (checking of the
3507 static stack frame of functions) to be done at appropriate places
3508 in the configuration files.  GCC will only emit code to do dynamic
3509 stack checking (checking on dynamic stack allocations) using the third
3510 approach below.
3511
3512 @item
3513 If neither of the above are true, GCC will generate code to periodically
3514 ``probe'' the stack pointer using the values of the macros defined below.
3515 @end enumerate
3516
3517 If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined,
3518 GCC will change its allocation strategy for large objects if the option
3519 @option{-fstack-check} is specified: they will always be allocated
3520 dynamically if their size exceeds @code{STACK_CHECK_MAX_VAR_SIZE} bytes.
3521
3522 @defmac STACK_CHECK_BUILTIN
3523 A nonzero value if stack checking is done by the configuration files in a
3524 machine-dependent manner.  You should define this macro if stack checking
3525 is required by the ABI of your machine or if you would like to do stack
3526 checking in some more efficient way than the generic approach.  The default
3527 value of this macro is zero.
3528 @end defmac
3529
3530 @defmac STACK_CHECK_STATIC_BUILTIN
3531 A nonzero value if static stack checking is done by the configuration files
3532 in a machine-dependent manner.  You should define this macro if you would
3533 like to do static stack checking in some more efficient way than the generic
3534 approach.  The default value of this macro is zero.
3535 @end defmac
3536
3537 @defmac STACK_CHECK_PROBE_INTERVAL_EXP
3538 An integer specifying the interval at which GCC must generate stack probe
3539 instructions, defined as 2 raised to this integer.  You will normally
3540 define this macro so that the interval be no larger than the size of
3541 the ``guard pages'' at the end of a stack area.  The default value
3542 of 12 (4096-byte interval) is suitable for most systems.
3543 @end defmac
3544
3545 @defmac STACK_CHECK_MOVING_SP