OSDN Git Service

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