OSDN Git Service

222117d8207bc032d59ddda3bee6a2700f4a3ed3
[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, 2010
3 @c Free Software Foundation, Inc.
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
6
7 @node Target Macros
8 @chapter Target Description Macros and Functions
9 @cindex machine description macros
10 @cindex target description macros
11 @cindex macros, target description
12 @cindex @file{tm.h} macros
13
14 In addition to the file @file{@var{machine}.md}, a machine description
15 includes a C header file conventionally given the name
16 @file{@var{machine}.h} and a C source file named @file{@var{machine}.c}.
17 The header file defines numerous macros that convey the information
18 about the target machine that does not fit into the scheme of the
19 @file{.md} file.  The file @file{tm.h} should be a link to
20 @file{@var{machine}.h}.  The header file @file{config.h} includes
21 @file{tm.h} and most compiler source files include @file{config.h}.  The
22 source file defines a variable @code{targetm}, which is a structure
23 containing pointers to functions and data relating to the target
24 machine.  @file{@var{machine}.c} should also contain their definitions,
25 if they are not defined elsewhere in GCC, and other functions called
26 through the macros defined in the @file{.h} file.
27
28 @menu
29 * Target Structure::    The @code{targetm} variable.
30 * Driver::              Controlling how the driver runs the compilation passes.
31 * Run-time Target::     Defining @samp{-m} options like @option{-m68000} and @option{-m68020}.
32 * Per-Function Data::   Defining data structures for per-function information.
33 * Storage Layout::      Defining sizes and alignments of data.
34 * Type Layout::         Defining sizes and properties of basic user data types.
35 * Registers::           Naming and describing the hardware registers.
36 * Register Classes::    Defining the classes of hardware registers.
37 * Old Constraints::     The old way to define machine-specific constraints.
38 * Stack and Calling::   Defining which way the stack grows and by how much.
39 * Varargs::             Defining the varargs macros.
40 * Trampolines::         Code set up at run time to enter a nested function.
41 * Library Calls::       Controlling how library routines are implicitly called.
42 * Addressing Modes::    Defining addressing modes valid for memory operands.
43 * Anchored Addresses::  Defining how @option{-fsection-anchors} should work.
44 * Condition Code::      Defining how insns update the condition code.
45 * Costs::               Defining relative costs of different operations.
46 * Scheduling::          Adjusting the behavior of the instruction scheduler.
47 * Sections::            Dividing storage into text, data, and other sections.
48 * PIC::                 Macros for position independent code.
49 * Assembler Format::    Defining how to write insns and pseudo-ops to output.
50 * Debugging Info::      Defining the format of debugging output.
51 * Floating Point::      Handling floating point for cross-compilers.
52 * Mode Switching::      Insertion of mode-switching instructions.
53 * Target Attributes::   Defining target-specific uses of @code{__attribute__}.
54 * Emulated TLS::        Emulated TLS support.
55 * MIPS Coprocessors::   MIPS coprocessor support and how to customize it.
56 * PCH Target::          Validity checking for precompiled headers.
57 * C++ ABI::             Controlling C++ ABI changes.
58 * Named Address Spaces:: Adding support for named address spaces
59 * Misc::                Everything else.
60 @end menu
61
62 @node Target Structure
63 @section The Global @code{targetm} Variable
64 @cindex target hooks
65 @cindex target functions
66
67 @deftypevar {struct gcc_target} targetm
68 The target @file{.c} file must define the global @code{targetm} variable
69 which contains pointers to functions and data relating to the target
70 machine.  The variable is declared in @file{target.h};
71 @file{target-def.h} defines the macro @code{TARGET_INITIALIZER} which is
72 used to initialize the variable, and macros for the default initializers
73 for elements of the structure.  The @file{.c} file should override those
74 macros for which the default definition is inappropriate.  For example:
75 @smallexample
76 #include "target.h"
77 #include "target-def.h"
78
79 /* @r{Initialize the GCC target structure.}  */
80
81 #undef TARGET_COMP_TYPE_ATTRIBUTES
82 #define TARGET_COMP_TYPE_ATTRIBUTES @var{machine}_comp_type_attributes
83
84 struct gcc_target targetm = TARGET_INITIALIZER;
85 @end smallexample
86 @end deftypevar
87
88 Where a macro should be defined in the @file{.c} file in this manner to
89 form part of the @code{targetm} structure, it is documented below as a
90 ``Target Hook'' with a prototype.  Many macros will change in future
91 from being defined in the @file{.h} file to being part of the
92 @code{targetm} structure.
93
94 @node Driver
95 @section Controlling the Compilation Driver, @file{gcc}
96 @cindex driver
97 @cindex controlling the compilation driver
98
99 @c prevent bad page break with this line
100 You can control the compilation driver.
101
102 @defmac SWITCH_TAKES_ARG (@var{char})
103 A C expression which determines whether the option @option{-@var{char}}
104 takes arguments.  The value should be the number of arguments that
105 option takes--zero, for many options.
106
107 By default, this macro is defined as
108 @code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard options
109 properly.  You need not define @code{SWITCH_TAKES_ARG} unless you
110 wish to add additional options which take arguments.  Any redefinition
111 should call @code{DEFAULT_SWITCH_TAKES_ARG} and then check for
112 additional options.
113 @end defmac
114
115 @defmac WORD_SWITCH_TAKES_ARG (@var{name})
116 A C expression which determines whether the option @option{-@var{name}}
117 takes arguments.  The value should be the number of arguments that
118 option takes--zero, for many options.  This macro rather than
119 @code{SWITCH_TAKES_ARG} is used for multi-character option names.
120
121 By default, this macro is defined as
122 @code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard options
123 properly.  You need not define @code{WORD_SWITCH_TAKES_ARG} unless you
124 wish to add additional options which take arguments.  Any redefinition
125 should call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check for
126 additional options.
127 @end defmac
128
129 @defmac 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 arguments are like for @code{TARGET_HANDLE_OPTION}.  The
785 default definition does nothing but return false.
786
787 In general, you should use @code{TARGET_HANDLE_OPTION} to handle
788 options.  However, if processing an option requires routines that are
789 only available in the C (and related language) front ends, then you
790 should use @code{TARGET_HANDLE_C_OPTION} instead.
791 @end deftypefn
792
793 @defmac TARGET_VERSION
794 This macro is a C statement to print on @code{stderr} a string
795 describing the particular machine description choice.  Every machine
796 description should define @code{TARGET_VERSION}.  For example:
797
798 @smallexample
799 #ifdef MOTOROLA
800 #define TARGET_VERSION \
801   fprintf (stderr, " (68k, Motorola syntax)");
802 #else
803 #define TARGET_VERSION \
804   fprintf (stderr, " (68k, MIT syntax)");
805 #endif
806 @end smallexample
807 @end defmac
808
809 @defmac OVERRIDE_OPTIONS
810 Sometimes certain combinations of command options do not make sense on
811 a particular target machine.  You can define a macro
812 @code{OVERRIDE_OPTIONS} to take account of this.  This macro, if
813 defined, is executed once just after all the command options have been
814 parsed.
815
816 Don't use this macro to turn on various extra optimizations for
817 @option{-O}.  That is what @code{OPTIMIZATION_OPTIONS} is for.
818
819 If you need to do something whenever the optimization level is
820 changed via the optimize attribute or pragma, see
821 @code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}
822 @end defmac
823
824 @deftypefn {Target Hook} void TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE (void)
825 This target function is similar to the macro @code{OVERRIDE_OPTIONS}
826 but is called when the optimize level is changed via an attribute or
827 pragma or when it is reset at the end of the code affected by the
828 attribute or pragma.  It is not called at the beginning of compilation
829 when @code{OVERRIDE_OPTIONS} is called so if you want to perform these
830 actions then, you should have @code{OVERRIDE_OPTIONS} call
831 @code{TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE}.
832 @end deftypefn
833
834 @defmac C_COMMON_OVERRIDE_OPTIONS
835 This is similar to @code{OVERRIDE_OPTIONS} but is only used in the C
836 language frontends (C, Objective-C, C++, Objective-C++) and so can be
837 used to alter option flag variables which only exist in those
838 frontends.
839 @end defmac
840
841 @defmac OPTIMIZATION_OPTIONS (@var{level}, @var{size})
842 Some machines may desire to change what optimizations are performed for
843 various optimization levels.   This macro, if defined, is executed once
844 just after the optimization level is determined and before the remainder
845 of the command options have been parsed.  Values set in this macro are
846 used as the default values for the other command line options.
847
848 @var{level} is the optimization level specified; 2 if @option{-O2} is
849 specified, 1 if @option{-O} is specified, and 0 if neither is specified.
850
851 @var{size} is nonzero if @option{-Os} is specified and zero otherwise.
852
853 This macro is run once at program startup and when the optimization
854 options are changed via @code{#pragma GCC optimize} or by using the
855 @code{optimize} attribute.
856
857 @strong{Do not examine @code{write_symbols} in
858 this macro!} The debugging options are not supposed to alter the
859 generated code.
860 @end defmac
861
862 @deftypefn {Target Hook} void TARGET_HELP (void)
863 This hook is called in response to the user invoking
864 @option{--target-help} on the command line.  It gives the target a
865 chance to display extra information on the target specific command
866 line options found in its @file{.opt} file.
867 @end deftypefn
868
869 @defmac CAN_DEBUG_WITHOUT_FP
870 Define this macro if debugging can be performed even without a frame
871 pointer.  If this macro is defined, GCC will turn on the
872 @option{-fomit-frame-pointer} option whenever @option{-O} is specified.
873 @end defmac
874
875 @node Per-Function Data
876 @section Defining data structures for per-function information.
877 @cindex per-function data
878 @cindex data structures
879
880 If the target needs to store information on a per-function basis, GCC
881 provides a macro and a couple of variables to allow this.  Note, just
882 using statics to store the information is a bad idea, since GCC supports
883 nested functions, so you can be halfway through encoding one function
884 when another one comes along.
885
886 GCC defines a data structure called @code{struct function} which
887 contains all of the data specific to an individual function.  This
888 structure contains a field called @code{machine} whose type is
889 @code{struct machine_function *}, which can be used by targets to point
890 to their own specific data.
891
892 If a target needs per-function specific data it should define the type
893 @code{struct machine_function} and also the macro @code{INIT_EXPANDERS}.
894 This macro should be used to initialize the function pointer
895 @code{init_machine_status}.  This pointer is explained below.
896
897 One typical use of per-function, target specific data is to create an
898 RTX to hold the register containing the function's return address.  This
899 RTX can then be used to implement the @code{__builtin_return_address}
900 function, for level 0.
901
902 Note---earlier implementations of GCC used a single data area to hold
903 all of the per-function information.  Thus when processing of a nested
904 function began the old per-function data had to be pushed onto a
905 stack, and when the processing was finished, it had to be popped off the
906 stack.  GCC used to provide function pointers called
907 @code{save_machine_status} and @code{restore_machine_status} to handle
908 the saving and restoring of the target specific information.  Since the
909 single data area approach is no longer used, these pointers are no
910 longer supported.
911
912 @defmac INIT_EXPANDERS
913 Macro called to initialize any target specific information.  This macro
914 is called once per function, before generation of any RTL has begun.
915 The intention of this macro is to allow the initialization of the
916 function pointer @code{init_machine_status}.
917 @end defmac
918
919 @deftypevar {void (*)(struct function *)} init_machine_status
920 If this function pointer is non-@code{NULL} it will be called once per
921 function, before function compilation starts, in order to allow the
922 target to perform any target specific initialization of the
923 @code{struct function} structure.  It is intended that this would be
924 used to initialize the @code{machine} of that structure.
925
926 @code{struct machine_function} structures are expected to be freed by GC@.
927 Generally, any memory that they reference must be allocated by using
928 @code{ggc_alloc}, including the structure itself.
929 @end deftypevar
930
931 @node Storage Layout
932 @section Storage Layout
933 @cindex storage layout
934
935 Note that the definitions of the macros in this table which are sizes or
936 alignments measured in bits do not need to be constant.  They can be C
937 expressions that refer to static variables, such as the @code{target_flags}.
938 @xref{Run-time Target}.
939
940 @defmac BITS_BIG_ENDIAN
941 Define this macro to have the value 1 if the most significant bit in a
942 byte has the lowest number; otherwise define it to have the value zero.
943 This means that bit-field instructions count from the most significant
944 bit.  If the machine has no bit-field instructions, then this must still
945 be defined, but it doesn't matter which value it is defined to.  This
946 macro need not be a constant.
947
948 This macro does not affect the way structure fields are packed into
949 bytes or words; that is controlled by @code{BYTES_BIG_ENDIAN}.
950 @end defmac
951
952 @defmac BYTES_BIG_ENDIAN
953 Define this macro to have the value 1 if the most significant byte in a
954 word has the lowest number.  This macro need not be a constant.
955 @end defmac
956
957 @defmac WORDS_BIG_ENDIAN
958 Define this macro to have the value 1 if, in a multiword object, the
959 most significant word has the lowest number.  This applies to both
960 memory locations and registers; GCC fundamentally assumes that the
961 order of words in memory is the same as the order in registers.  This
962 macro need not be a constant.
963 @end defmac
964
965 @defmac LIBGCC2_WORDS_BIG_ENDIAN
966 Define this macro if @code{WORDS_BIG_ENDIAN} is not constant.  This must be a
967 constant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be
968 used only when compiling @file{libgcc2.c}.  Typically the value will be set
969 based on preprocessor defines.
970 @end defmac
971
972 @defmac FLOAT_WORDS_BIG_ENDIAN
973 Define this macro to have the value 1 if @code{DFmode}, @code{XFmode} or
974 @code{TFmode} floating point numbers are stored in memory with the word
975 containing the sign bit at the lowest address; otherwise define it to
976 have the value 0.  This macro need not be a constant.
977
978 You need not define this macro if the ordering is the same as for
979 multi-word integers.
980 @end defmac
981
982 @defmac BITS_PER_UNIT
983 Define this macro to be the number of bits in an addressable storage
984 unit (byte).  If you do not define this macro the default is 8.
985 @end defmac
986
987 @defmac BITS_PER_WORD
988 Number of bits in a word.  If you do not define this macro, the default
989 is @code{BITS_PER_UNIT * UNITS_PER_WORD}.
990 @end defmac
991
992 @defmac MAX_BITS_PER_WORD
993 Maximum number of bits in a word.  If this is undefined, the default is
994 @code{BITS_PER_WORD}.  Otherwise, it is the constant value that is the
995 largest value that @code{BITS_PER_WORD} can have at run-time.
996 @end defmac
997
998 @defmac UNITS_PER_WORD
999 Number of storage units in a word; normally the size of a general-purpose
1000 register, a power of two from 1 or 8.
1001 @end defmac
1002
1003 @defmac MIN_UNITS_PER_WORD
1004 Minimum number of units in a word.  If this is undefined, the default is
1005 @code{UNITS_PER_WORD}.  Otherwise, it is the constant value that is the
1006 smallest value that @code{UNITS_PER_WORD} can have at run-time.
1007 @end defmac
1008
1009 @defmac UNITS_PER_SIMD_WORD (@var{mode})
1010 Number of units in the vectors that the vectorizer can produce for
1011 scalar mode @var{mode}.  The default is equal to @code{UNITS_PER_WORD},
1012 because the vectorizer can do some transformations even in absence of
1013 specialized @acronym{SIMD} hardware.
1014 @end defmac
1015
1016 @defmac POINTER_SIZE
1017 Width of a pointer, in bits.  You must specify a value no wider than the
1018 width of @code{Pmode}.  If it is not equal to the width of @code{Pmode},
1019 you must define @code{POINTERS_EXTEND_UNSIGNED}.  If you do not specify
1020 a value the default is @code{BITS_PER_WORD}.
1021 @end defmac
1022
1023 @defmac POINTERS_EXTEND_UNSIGNED
1024 A C expression that determines how pointers should be extended from
1025 @code{ptr_mode} to either @code{Pmode} or @code{word_mode}.  It is
1026 greater than zero if pointers should be zero-extended, zero if they
1027 should be sign-extended, and negative if some other sort of conversion
1028 is needed.  In the last case, the extension is done by the target's
1029 @code{ptr_extend} instruction.
1030
1031 You need not define this macro if the @code{ptr_mode}, @code{Pmode}
1032 and @code{word_mode} are all the same width.
1033 @end defmac
1034
1035 @defmac PROMOTE_MODE (@var{m}, @var{unsignedp}, @var{type})
1036 A macro to update @var{m} and @var{unsignedp} when an object whose type
1037 is @var{type} and which has the specified mode and signedness is to be
1038 stored in a register.  This macro is only called when @var{type} is a
1039 scalar type.
1040
1041 On most RISC machines, which only have operations that operate on a full
1042 register, define this macro to set @var{m} to @code{word_mode} if
1043 @var{m} is an integer mode narrower than @code{BITS_PER_WORD}.  In most
1044 cases, only integer modes should be widened because wider-precision
1045 floating-point operations are usually more expensive than their narrower
1046 counterparts.
1047
1048 For most machines, the macro definition does not change @var{unsignedp}.
1049 However, some machines, have instructions that preferentially handle
1050 either signed or unsigned quantities of certain modes.  For example, on
1051 the DEC Alpha, 32-bit loads from memory and 32-bit add instructions
1052 sign-extend the result to 64 bits.  On such machines, set
1053 @var{unsignedp} according to which kind of extension is more efficient.
1054
1055 Do not define this macro if it would never modify @var{m}.
1056 @end defmac
1057
1058 @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})
1059 Like @code{PROMOTE_MODE}, but it is applied to outgoing function arguments or
1060 function return values.  The target hook should return the new mode
1061 and possibly change @code{*@var{punsignedp}} if the promotion should
1062 change signedness.  This function is called only for scalar @emph{or
1063 pointer} types.
1064
1065 @var{for_return} allows to distinguish the promotion of arguments and
1066 return values.  If it is @code{1}, a return value is being promoted and
1067 @code{TARGET_FUNCTION_VALUE} must perform the same promotions done here.
1068 If it is @code{2}, the returned mode should be that of the register in
1069 which an incoming parameter is copied, or the outgoing result is computed;
1070 then the hook should return the same mode as @code{promote_mode}, though
1071 the signedness may be different.
1072
1073 The default is to not promote arguments and return values.  You can
1074 also define the hook to @code{default_promote_function_mode_always_promote}
1075 if you would like to apply the same rules given by @code{PROMOTE_MODE}.
1076 @end deftypefn
1077
1078 @defmac PARM_BOUNDARY
1079 Normal alignment required for function parameters on the stack, in
1080 bits.  All stack parameters receive at least this much alignment
1081 regardless of data type.  On most machines, this is the same as the
1082 size of an integer.
1083 @end defmac
1084
1085 @defmac STACK_BOUNDARY
1086 Define this macro to the minimum alignment enforced by hardware for the
1087 stack pointer on this machine.  The definition is a C expression for the
1088 desired alignment (measured in bits).  This value is used as a default
1089 if @code{PREFERRED_STACK_BOUNDARY} is not defined.  On most machines,
1090 this should be the same as @code{PARM_BOUNDARY}.
1091 @end defmac
1092
1093 @defmac PREFERRED_STACK_BOUNDARY
1094 Define this macro if you wish to preserve a certain alignment for the
1095 stack pointer, greater than what the hardware enforces.  The definition
1096 is a C expression for the desired alignment (measured in bits).  This
1097 macro must evaluate to a value equal to or larger than
1098 @code{STACK_BOUNDARY}.
1099 @end defmac
1100
1101 @defmac INCOMING_STACK_BOUNDARY
1102 Define this macro if the incoming stack boundary may be different
1103 from @code{PREFERRED_STACK_BOUNDARY}.  This macro must evaluate
1104 to a value equal to or larger than @code{STACK_BOUNDARY}.
1105 @end defmac
1106
1107 @defmac FUNCTION_BOUNDARY
1108 Alignment required for a function entry point, in bits.
1109 @end defmac
1110
1111 @defmac BIGGEST_ALIGNMENT
1112 Biggest alignment that any data type can require on this machine, in
1113 bits.  Note that this is not the biggest alignment that is supported,
1114 just the biggest alignment that, when violated, may cause a fault.
1115 @end defmac
1116
1117 @defmac MALLOC_ABI_ALIGNMENT
1118 Alignment, in bits, a C conformant malloc implementation has to
1119 provide.  If not defined, the default value is @code{BITS_PER_WORD}.
1120 @end defmac
1121
1122 @defmac ATTRIBUTE_ALIGNED_VALUE
1123 Alignment used by the @code{__attribute__ ((aligned))} construct.  If
1124 not defined, the default value is @code{BIGGEST_ALIGNMENT}.
1125 @end defmac
1126
1127 @defmac MINIMUM_ATOMIC_ALIGNMENT
1128 If defined, the smallest alignment, in bits, that can be given to an
1129 object that can be referenced in one operation, without disturbing any
1130 nearby object.  Normally, this is @code{BITS_PER_UNIT}, but may be larger
1131 on machines that don't have byte or half-word store operations.
1132 @end defmac
1133
1134 @defmac BIGGEST_FIELD_ALIGNMENT
1135 Biggest alignment that any structure or union field can require on this
1136 machine, in bits.  If defined, this overrides @code{BIGGEST_ALIGNMENT} for
1137 structure and union fields only, unless the field alignment has been set
1138 by the @code{__attribute__ ((aligned (@var{n})))} construct.
1139 @end defmac
1140
1141 @defmac ADJUST_FIELD_ALIGN (@var{field}, @var{computed})
1142 An expression for the alignment of a structure field @var{field} if the
1143 alignment computed in the usual way (including applying of
1144 @code{BIGGEST_ALIGNMENT} and @code{BIGGEST_FIELD_ALIGNMENT} to the
1145 alignment) is @var{computed}.  It overrides alignment only if the
1146 field alignment has not been set by the
1147 @code{__attribute__ ((aligned (@var{n})))} construct.
1148 @end defmac
1149
1150 @defmac MAX_STACK_ALIGNMENT
1151 Biggest stack alignment guaranteed by the backend.  Use this macro
1152 to specify the maximum alignment of a variable on stack.
1153
1154 If not defined, the default value is @code{STACK_BOUNDARY}.
1155
1156 @c FIXME: The default should be @code{PREFERRED_STACK_BOUNDARY}.
1157 @c But the fix for PR 32893 indicates that we can only guarantee
1158 @c maximum stack alignment on stack up to @code{STACK_BOUNDARY}, not
1159 @c @code{PREFERRED_STACK_BOUNDARY}, if stack alignment isn't supported.
1160 @end defmac
1161
1162 @defmac MAX_OFILE_ALIGNMENT
1163 Biggest alignment supported by the object file format of this machine.
1164 Use this macro to limit the alignment which can be specified using the
1165 @code{__attribute__ ((aligned (@var{n})))} construct.  If not defined,
1166 the default value is @code{BIGGEST_ALIGNMENT}.
1167
1168 On systems that use ELF, the default (in @file{config/elfos.h}) is
1169 the largest supported 32-bit ELF section alignment representable on
1170 a 32-bit host e.g. @samp{(((unsigned HOST_WIDEST_INT) 1 << 28) * 8)}.
1171 On 32-bit ELF the largest supported section alignment in bits is
1172 @samp{(0x80000000 * 8)}, but this is not representable on 32-bit hosts.
1173 @end defmac
1174
1175 @defmac DATA_ALIGNMENT (@var{type}, @var{basic-align})
1176 If defined, a C expression to compute the alignment for a variable in
1177 the static store.  @var{type} is the data type, and @var{basic-align} is
1178 the alignment that the object would ordinarily have.  The value of this
1179 macro is used instead of that alignment to align the object.
1180
1181 If this macro is not defined, then @var{basic-align} is used.
1182
1183 @findex strcpy
1184 One use of this macro is to increase alignment of medium-size data to
1185 make it all fit in fewer cache lines.  Another is to cause character
1186 arrays to be word-aligned so that @code{strcpy} calls that copy
1187 constants to character arrays can be done inline.
1188 @end defmac
1189
1190 @defmac CONSTANT_ALIGNMENT (@var{constant}, @var{basic-align})
1191 If defined, a C expression to compute the alignment given to a constant
1192 that is being placed in memory.  @var{constant} is the constant and
1193 @var{basic-align} is the alignment that the object would ordinarily
1194 have.  The value of this macro is used instead of that alignment to
1195 align the object.
1196
1197 If this macro is not defined, then @var{basic-align} is used.
1198
1199 The typical use of this macro is to increase alignment for string
1200 constants to be word aligned so that @code{strcpy} calls that copy
1201 constants can be done inline.
1202 @end defmac
1203
1204 @defmac LOCAL_ALIGNMENT (@var{type}, @var{basic-align})
1205 If defined, a C expression to compute the alignment for a variable in
1206 the local store.  @var{type} is the data type, and @var{basic-align} is
1207 the alignment that the object would ordinarily have.  The value of this
1208 macro is used instead of that alignment to align the object.
1209
1210 If this macro is not defined, then @var{basic-align} is used.
1211
1212 One use of this macro is to increase alignment of medium-size data to
1213 make it all fit in fewer cache lines.
1214 @end defmac
1215
1216 @defmac STACK_SLOT_ALIGNMENT (@var{type}, @var{mode}, @var{basic-align})
1217 If defined, a C expression to compute the alignment for stack slot.
1218 @var{type} is the data type, @var{mode} is the widest mode available,
1219 and @var{basic-align} is the alignment that the slot would ordinarily
1220 have.  The value of this macro is used instead of that alignment to
1221 align the slot.
1222
1223 If this macro is not defined, then @var{basic-align} is used when
1224 @var{type} is @code{NULL}.  Otherwise, @code{LOCAL_ALIGNMENT} will
1225 be used.
1226
1227 This macro is to set alignment of stack slot to the maximum alignment
1228 of all possible modes which the slot may have.
1229 @end defmac
1230
1231 @defmac LOCAL_DECL_ALIGNMENT (@var{decl})
1232 If defined, a C expression to compute the alignment for a local
1233 variable @var{decl}.
1234
1235 If this macro is not defined, then
1236 @code{LOCAL_ALIGNMENT (TREE_TYPE (@var{decl}), DECL_ALIGN (@var{decl}))}
1237 is used.
1238
1239 One use of this macro is to increase alignment of medium-size data to
1240 make it all fit in fewer cache lines.
1241 @end defmac
1242
1243 @defmac MINIMUM_ALIGNMENT (@var{exp}, @var{mode}, @var{align})
1244 If defined, a C expression to compute the minimum required alignment
1245 for dynamic stack realignment purposes for @var{exp} (a type or decl),
1246 @var{mode}, assuming normal alignment @var{align}.
1247
1248 If this macro is not defined, then @var{align} will be used.
1249 @end defmac
1250
1251 @defmac EMPTY_FIELD_BOUNDARY
1252 Alignment in bits to be given to a structure bit-field that follows an
1253 empty field such as @code{int : 0;}.
1254
1255 If @code{PCC_BITFIELD_TYPE_MATTERS} is true, it overrides this macro.
1256 @end defmac
1257
1258 @defmac STRUCTURE_SIZE_BOUNDARY
1259 Number of bits which any structure or union's size must be a multiple of.
1260 Each structure or union's size is rounded up to a multiple of this.
1261
1262 If you do not define this macro, the default is the same as
1263 @code{BITS_PER_UNIT}.
1264 @end defmac
1265
1266 @defmac STRICT_ALIGNMENT
1267 Define this macro to be the value 1 if instructions will fail to work
1268 if given data not on the nominal alignment.  If instructions will merely
1269 go slower in that case, define this macro as 0.
1270 @end defmac
1271
1272 @defmac PCC_BITFIELD_TYPE_MATTERS
1273 Define this if you wish to imitate the way many other C compilers handle
1274 alignment of bit-fields and the structures that contain them.
1275
1276 The behavior is that the type written for a named bit-field (@code{int},
1277 @code{short}, or other integer type) imposes an alignment for the entire
1278 structure, as if the structure really did contain an ordinary field of
1279 that type.  In addition, the bit-field is placed within the structure so
1280 that it would fit within such a field, not crossing a boundary for it.
1281
1282 Thus, on most machines, a named bit-field whose type is written as
1283 @code{int} would not cross a four-byte boundary, and would force
1284 four-byte alignment for the whole structure.  (The alignment used may
1285 not be four bytes; it is controlled by the other alignment parameters.)
1286
1287 An unnamed bit-field will not affect the alignment of the containing
1288 structure.
1289
1290 If the macro is defined, its definition should be a C expression;
1291 a nonzero value for the expression enables this behavior.
1292
1293 Note that if this macro is not defined, or its value is zero, some
1294 bit-fields may cross more than one alignment boundary.  The compiler can
1295 support such references if there are @samp{insv}, @samp{extv}, and
1296 @samp{extzv} insns that can directly reference memory.
1297
1298 The other known way of making bit-fields work is to define
1299 @code{STRUCTURE_SIZE_BOUNDARY} as large as @code{BIGGEST_ALIGNMENT}.
1300 Then every structure can be accessed with fullwords.
1301
1302 Unless the machine has bit-field instructions or you define
1303 @code{STRUCTURE_SIZE_BOUNDARY} that way, you must define
1304 @code{PCC_BITFIELD_TYPE_MATTERS} to have a nonzero value.
1305
1306 If your aim is to make GCC use the same conventions for laying out
1307 bit-fields as are used by another compiler, here is how to investigate
1308 what the other compiler does.  Compile and run this program:
1309
1310 @smallexample
1311 struct foo1
1312 @{
1313   char x;
1314   char :0;
1315   char y;
1316 @};
1317
1318 struct foo2
1319 @{
1320   char x;
1321   int :0;
1322   char y;
1323 @};
1324
1325 main ()
1326 @{
1327   printf ("Size of foo1 is %d\n",
1328           sizeof (struct foo1));
1329   printf ("Size of foo2 is %d\n",
1330           sizeof (struct foo2));
1331   exit (0);
1332 @}
1333 @end smallexample
1334
1335 If this prints 2 and 5, then the compiler's behavior is what you would
1336 get from @code{PCC_BITFIELD_TYPE_MATTERS}.
1337 @end defmac
1338
1339 @defmac BITFIELD_NBYTES_LIMITED
1340 Like @code{PCC_BITFIELD_TYPE_MATTERS} except that its effect is limited
1341 to aligning a bit-field within the structure.
1342 @end defmac
1343
1344 @deftypefn {Target Hook} bool TARGET_ALIGN_ANON_BITFIELD (void)
1345 When @code{PCC_BITFIELD_TYPE_MATTERS} is true this hook will determine
1346 whether unnamed bitfields affect the alignment of the containing
1347 structure.  The hook should return true if the structure should inherit
1348 the alignment requirements of an unnamed bitfield's type.
1349 @end deftypefn
1350
1351 @deftypefn {Target Hook} bool TARGET_NARROW_VOLATILE_BITFIELD (void)
1352 This target hook should return @code{true} if accesses to volatile bitfields
1353 should use the narrowest mode possible.  It should return @code{false} if
1354 these accesses should use the bitfield container type.
1355
1356 The default is @code{!TARGET_STRICT_ALIGN}.
1357 @end deftypefn
1358
1359 @defmac MEMBER_TYPE_FORCES_BLK (@var{field}, @var{mode})
1360 Return 1 if a structure or array containing @var{field} should be accessed using
1361 @code{BLKMODE}.
1362
1363 If @var{field} is the only field in the structure, @var{mode} is its
1364 mode, otherwise @var{mode} is VOIDmode.  @var{mode} is provided in the
1365 case where structures of one field would require the structure's mode to
1366 retain the field's mode.
1367
1368 Normally, this is not needed.
1369 @end defmac
1370
1371 @defmac ROUND_TYPE_ALIGN (@var{type}, @var{computed}, @var{specified})
1372 Define this macro as an expression for the alignment of a type (given
1373 by @var{type} as a tree node) if the alignment computed in the usual
1374 way is @var{computed} and the alignment explicitly specified was
1375 @var{specified}.
1376
1377 The default is to use @var{specified} if it is larger; otherwise, use
1378 the smaller of @var{computed} and @code{BIGGEST_ALIGNMENT}
1379 @end defmac
1380
1381 @defmac MAX_FIXED_MODE_SIZE
1382 An integer expression for the size in bits of the largest integer
1383 machine mode that should actually be used.  All integer machine modes of
1384 this size or smaller can be used for structures and unions with the
1385 appropriate sizes.  If this macro is undefined, @code{GET_MODE_BITSIZE
1386 (DImode)} is assumed.
1387 @end defmac
1388
1389 @defmac STACK_SAVEAREA_MODE (@var{save_level})
1390 If defined, an expression of type @code{enum machine_mode} that
1391 specifies the mode of the save area operand of a
1392 @code{save_stack_@var{level}} named pattern (@pxref{Standard Names}).
1393 @var{save_level} is one of @code{SAVE_BLOCK}, @code{SAVE_FUNCTION}, or
1394 @code{SAVE_NONLOCAL} and selects which of the three named patterns is
1395 having its mode specified.
1396
1397 You need not define this macro if it always returns @code{Pmode}.  You
1398 would most commonly define this macro if the
1399 @code{save_stack_@var{level}} patterns need to support both a 32- and a
1400 64-bit mode.
1401 @end defmac
1402
1403 @defmac STACK_SIZE_MODE
1404 If defined, an expression of type @code{enum machine_mode} that
1405 specifies the mode of the size increment operand of an
1406 @code{allocate_stack} named pattern (@pxref{Standard Names}).
1407
1408 You need not define this macro if it always returns @code{word_mode}.
1409 You would most commonly define this macro if the @code{allocate_stack}
1410 pattern needs to support both a 32- and a 64-bit mode.
1411 @end defmac
1412
1413 @deftypefn {Target Hook} {enum machine_mode} TARGET_LIBGCC_CMP_RETURN_MODE (void)
1414 This target hook should return the mode to be used for the return value
1415 of compare instructions expanded to libgcc calls.  If not defined
1416 @code{word_mode} is returned which is the right choice for a majority of
1417 targets.
1418 @end deftypefn
1419
1420 @deftypefn {Target Hook} {enum machine_mode} TARGET_LIBGCC_SHIFT_COUNT_MODE (void)
1421 This target hook should return the mode to be used for the shift count operand
1422 of shift instructions expanded to libgcc calls.  If not defined
1423 @code{word_mode} is returned which is the right choice for a majority of
1424 targets.
1425 @end deftypefn
1426
1427 @deftypefn {Target Hook} {enum machine_mode} TARGET_UNWIND_WORD_MODE (void)
1428 Return machine mode to be used for @code{_Unwind_Word} type.
1429 The default is to use @code{word_mode}.
1430 @end deftypefn
1431
1432 @defmac ROUND_TOWARDS_ZERO
1433 If defined, this macro should be true if the prevailing rounding
1434 mode is towards zero.
1435
1436 Defining this macro only affects the way @file{libgcc.a} emulates
1437 floating-point arithmetic.
1438
1439 Not defining this macro is equivalent to returning zero.
1440 @end defmac
1441
1442 @defmac LARGEST_EXPONENT_IS_NORMAL (@var{size})
1443 This macro should return true if floats with @var{size}
1444 bits do not have a NaN or infinity representation, but use the largest
1445 exponent for normal numbers instead.
1446
1447 Defining this macro only affects the way @file{libgcc.a} emulates
1448 floating-point arithmetic.
1449
1450 The default definition of this macro returns false for all sizes.
1451 @end defmac
1452
1453 @deftypefn {Target Hook} bool TARGET_MS_BITFIELD_LAYOUT_P (const_tree @var{record_type})
1454 This target hook returns @code{true} if bit-fields in the given
1455 @var{record_type} are to be laid out following the rules of Microsoft
1456 Visual C/C++, namely: (i) a bit-field won't share the same storage
1457 unit with the previous bit-field if their underlying types have
1458 different sizes, and the bit-field will be aligned to the highest
1459 alignment of the underlying types of itself and of the previous
1460 bit-field; (ii) a zero-sized bit-field will affect the alignment of
1461 the whole enclosing structure, even if it is unnamed; except that
1462 (iii) a zero-sized bit-field will be disregarded unless it follows
1463 another bit-field of nonzero size.  If this hook returns @code{true},
1464 other macros that control bit-field layout are ignored.
1465
1466 When a bit-field is inserted into a packed record, the whole size
1467 of the underlying type is used by one or more same-size adjacent
1468 bit-fields (that is, if its long:3, 32 bits is used in the record,
1469 and any additional adjacent long bit-fields are packed into the same
1470 chunk of 32 bits.  However, if the size changes, a new field of that
1471 size is allocated).  In an unpacked record, this is the same as using
1472 alignment, but not equivalent when packing.
1473
1474 If both MS bit-fields and @samp{__attribute__((packed))} are used,
1475 the latter will take precedence.  If @samp{__attribute__((packed))} is
1476 used on a single field when MS bit-fields are in use, it will take
1477 precedence for that field, but the alignment of the rest of the structure
1478 may affect its placement.
1479 @end deftypefn
1480
1481 @deftypefn {Target Hook} bool TARGET_DECIMAL_FLOAT_SUPPORTED_P (void)
1482 Returns true if the target supports decimal floating point.
1483 @end deftypefn
1484
1485 @deftypefn {Target Hook} bool TARGET_FIXED_POINT_SUPPORTED_P (void)
1486 Returns true if the target supports fixed-point arithmetic.
1487 @end deftypefn
1488
1489 @deftypefn {Target Hook} void TARGET_EXPAND_TO_RTL_HOOK (void)
1490 This hook is called just before expansion into rtl, allowing the target
1491 to perform additional initializations or analysis before the expansion.
1492 For example, the rs6000 port uses it to allocate a scratch stack slot
1493 for use in copying SDmode values between memory and floating point
1494 registers whenever the function being expanded has any SDmode
1495 usage.
1496 @end deftypefn
1497
1498 @deftypefn {Target Hook} void TARGET_INSTANTIATE_DECLS (void)
1499 This hook allows the backend to perform additional instantiations on rtl
1500 that are not actually in any insns yet, but will be later.
1501 @end deftypefn
1502
1503 @deftypefn {Target Hook} {const char *} TARGET_MANGLE_TYPE (const_tree @var{type})
1504 If your target defines any fundamental types, or any types your target
1505 uses should be mangled differently from the default, define this hook
1506 to return the appropriate encoding for these types as part of a C++
1507 mangled name.  The @var{type} argument is the tree structure representing
1508 the type to be mangled.  The hook may be applied to trees which are
1509 not target-specific fundamental types; it should return @code{NULL}
1510 for all such types, as well as arguments it does not recognize.  If the
1511 return value is not @code{NULL}, it must point to a statically-allocated
1512 string constant.
1513
1514 Target-specific fundamental types might be new fundamental types or
1515 qualified versions of ordinary fundamental types.  Encode new
1516 fundamental types as @samp{@w{u @var{n} @var{name}}}, where @var{name}
1517 is the name used for the type in source code, and @var{n} is the
1518 length of @var{name} in decimal.  Encode qualified versions of
1519 ordinary types as @samp{@w{U @var{n} @var{name} @var{code}}}, where
1520 @var{name} is the name used for the type qualifier in source code,
1521 @var{n} is the length of @var{name} as above, and @var{code} is the
1522 code used to represent the unqualified version of this type.  (See
1523 @code{write_builtin_type} in @file{cp/mangle.c} for the list of
1524 codes.)  In both cases the spaces are for clarity; do not include any
1525 spaces in your string.
1526
1527 This hook is applied to types prior to typedef resolution.  If the mangled
1528 name for a particular type depends only on that type's main variant, you
1529 can perform typedef resolution yourself using @code{TYPE_MAIN_VARIANT}
1530 before mangling.
1531
1532 The default version of this hook always returns @code{NULL}, which is
1533 appropriate for a target that does not define any new fundamental
1534 types.
1535 @end deftypefn
1536
1537 @node Type Layout
1538 @section Layout of Source Language Data Types
1539
1540 These macros define the sizes and other characteristics of the standard
1541 basic data types used in programs being compiled.  Unlike the macros in
1542 the previous section, these apply to specific features of C and related
1543 languages, rather than to fundamental aspects of storage layout.
1544
1545 @defmac INT_TYPE_SIZE
1546 A C expression for the size in bits of the type @code{int} on the
1547 target machine.  If you don't define this, the default is one word.
1548 @end defmac
1549
1550 @defmac SHORT_TYPE_SIZE
1551 A C expression for the size in bits of the type @code{short} on the
1552 target machine.  If you don't define this, the default is half a word.
1553 (If this would be less than one storage unit, it is rounded up to one
1554 unit.)
1555 @end defmac
1556
1557 @defmac LONG_TYPE_SIZE
1558 A C expression for the size in bits of the type @code{long} on the
1559 target machine.  If you don't define this, the default is one word.
1560 @end defmac
1561
1562 @defmac ADA_LONG_TYPE_SIZE
1563 On some machines, the size used for the Ada equivalent of the type
1564 @code{long} by a native Ada compiler differs from that used by C@.  In
1565 that situation, define this macro to be a C expression to be used for
1566 the size of that type.  If you don't define this, the default is the
1567 value of @code{LONG_TYPE_SIZE}.
1568 @end defmac
1569
1570 @defmac LONG_LONG_TYPE_SIZE
1571 A C expression for the size in bits of the type @code{long long} on the
1572 target machine.  If you don't define this, the default is two
1573 words.  If you want to support GNU Ada on your machine, the value of this
1574 macro must be at least 64.
1575 @end defmac
1576
1577 @defmac CHAR_TYPE_SIZE
1578 A C expression for the size in bits of the type @code{char} on the
1579 target machine.  If you don't define this, the default is
1580 @code{BITS_PER_UNIT}.
1581 @end defmac
1582
1583 @defmac BOOL_TYPE_SIZE
1584 A C expression for the size in bits of the C++ type @code{bool} and
1585 C99 type @code{_Bool} on the target machine.  If you don't define
1586 this, and you probably shouldn't, the default is @code{CHAR_TYPE_SIZE}.
1587 @end defmac
1588
1589 @defmac FLOAT_TYPE_SIZE
1590 A C expression for the size in bits of the type @code{float} on the
1591 target machine.  If you don't define this, the default is one word.
1592 @end defmac
1593
1594 @defmac DOUBLE_TYPE_SIZE
1595 A C expression for the size in bits of the type @code{double} on the
1596 target machine.  If you don't define this, the default is two
1597 words.
1598 @end defmac
1599
1600 @defmac LONG_DOUBLE_TYPE_SIZE
1601 A C expression for the size in bits of the type @code{long double} on
1602 the target machine.  If you don't define this, the default is two
1603 words.
1604 @end defmac
1605
1606 @defmac SHORT_FRACT_TYPE_SIZE
1607 A C expression for the size in bits of the type @code{short _Fract} on
1608 the target machine.  If you don't define this, the default is
1609 @code{BITS_PER_UNIT}.
1610 @end defmac
1611
1612 @defmac FRACT_TYPE_SIZE
1613 A C expression for the size in bits of the type @code{_Fract} on
1614 the target machine.  If you don't define this, the default is
1615 @code{BITS_PER_UNIT * 2}.
1616 @end defmac
1617
1618 @defmac LONG_FRACT_TYPE_SIZE
1619 A C expression for the size in bits of the type @code{long _Fract} on
1620 the target machine.  If you don't define this, the default is
1621 @code{BITS_PER_UNIT * 4}.
1622 @end defmac
1623
1624 @defmac LONG_LONG_FRACT_TYPE_SIZE
1625 A C expression for the size in bits of the type @code{long long _Fract} on
1626 the target machine.  If you don't define this, the default is
1627 @code{BITS_PER_UNIT * 8}.
1628 @end defmac
1629
1630 @defmac SHORT_ACCUM_TYPE_SIZE
1631 A C expression for the size in bits of the type @code{short _Accum} on
1632 the target machine.  If you don't define this, the default is
1633 @code{BITS_PER_UNIT * 2}.
1634 @end defmac
1635
1636 @defmac ACCUM_TYPE_SIZE
1637 A C expression for the size in bits of the type @code{_Accum} on
1638 the target machine.  If you don't define this, the default is
1639 @code{BITS_PER_UNIT * 4}.
1640 @end defmac
1641
1642 @defmac LONG_ACCUM_TYPE_SIZE
1643 A C expression for the size in bits of the type @code{long _Accum} on
1644 the target machine.  If you don't define this, the default is
1645 @code{BITS_PER_UNIT * 8}.
1646 @end defmac
1647
1648 @defmac LONG_LONG_ACCUM_TYPE_SIZE
1649 A C expression for the size in bits of the type @code{long long _Accum} on
1650 the target machine.  If you don't define this, the default is
1651 @code{BITS_PER_UNIT * 16}.
1652 @end defmac
1653
1654 @defmac LIBGCC2_LONG_DOUBLE_TYPE_SIZE
1655 Define this macro if @code{LONG_DOUBLE_TYPE_SIZE} is not constant or
1656 if you want routines in @file{libgcc2.a} for a size other than
1657 @code{LONG_DOUBLE_TYPE_SIZE}.  If you don't define this, the
1658 default is @code{LONG_DOUBLE_TYPE_SIZE}.
1659 @end defmac
1660
1661 @defmac LIBGCC2_HAS_DF_MODE
1662 Define this macro if neither @code{LIBGCC2_DOUBLE_TYPE_SIZE} nor
1663 @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is
1664 @code{DFmode} but you want @code{DFmode} routines in @file{libgcc2.a}
1665 anyway.  If you don't define this and either @code{LIBGCC2_DOUBLE_TYPE_SIZE}
1666 or @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64 then the default is 1,
1667 otherwise it is 0.
1668 @end defmac
1669
1670 @defmac LIBGCC2_HAS_XF_MODE
1671 Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not
1672 @code{XFmode} but you want @code{XFmode} routines in @file{libgcc2.a}
1673 anyway.  If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE}
1674 is 80 then the default is 1, otherwise it is 0.
1675 @end defmac
1676
1677 @defmac LIBGCC2_HAS_TF_MODE
1678 Define this macro if @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is not
1679 @code{TFmode} but you want @code{TFmode} routines in @file{libgcc2.a}
1680 anyway.  If you don't define this and @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE}
1681 is 128 then the default is 1, otherwise it is 0.
1682 @end defmac
1683
1684 @defmac SF_SIZE
1685 @defmacx DF_SIZE
1686 @defmacx XF_SIZE
1687 @defmacx TF_SIZE
1688 Define these macros to be the size in bits of the mantissa of
1689 @code{SFmode}, @code{DFmode}, @code{XFmode} and @code{TFmode} values,
1690 if the defaults in @file{libgcc2.h} are inappropriate.  By default,
1691 @code{FLT_MANT_DIG} is used for @code{SF_SIZE}, @code{LDBL_MANT_DIG}
1692 for @code{XF_SIZE} and @code{TF_SIZE}, and @code{DBL_MANT_DIG} or
1693 @code{LDBL_MANT_DIG} for @code{DF_SIZE} according to whether
1694 @code{LIBGCC2_DOUBLE_TYPE_SIZE} or
1695 @code{LIBGCC2_LONG_DOUBLE_TYPE_SIZE} is 64.
1696 @end defmac
1697
1698 @defmac TARGET_FLT_EVAL_METHOD
1699 A C expression for the value for @code{FLT_EVAL_METHOD} in @file{float.h},
1700 assuming, if applicable, that the floating-point control word is in its
1701 default state.  If you do not define this macro the value of
1702 @code{FLT_EVAL_METHOD} will be zero.
1703 @end defmac
1704
1705 @defmac WIDEST_HARDWARE_FP_SIZE
1706 A C expression for the size in bits of the widest floating-point format
1707 supported by the hardware.  If you define this macro, you must specify a
1708 value less than or equal to the value of @code{LONG_DOUBLE_TYPE_SIZE}.
1709 If you do not define this macro, the value of @code{LONG_DOUBLE_TYPE_SIZE}
1710 is the default.
1711 @end defmac
1712
1713 @defmac DEFAULT_SIGNED_CHAR
1714 An expression whose value is 1 or 0, according to whether the type
1715 @code{char} should be signed or unsigned by default.  The user can
1716 always override this default with the options @option{-fsigned-char}
1717 and @option{-funsigned-char}.
1718 @end defmac
1719
1720 @deftypefn {Target Hook} bool TARGET_DEFAULT_SHORT_ENUMS (void)
1721 This target hook should return true if the compiler should give an
1722 @code{enum} type only as many bytes as it takes to represent the range
1723 of possible values of that type.  It should return false if all
1724 @code{enum} types should be allocated like @code{int}.
1725
1726 The default is to return false.
1727 @end deftypefn
1728
1729 @defmac SIZE_TYPE
1730 A C expression for a string describing the name of the data type to use
1731 for size values.  The typedef name @code{size_t} is defined using the
1732 contents of the string.
1733
1734 The string can contain more than one keyword.  If so, separate them with
1735 spaces, and write first any length keyword, then @code{unsigned} if
1736 appropriate, and finally @code{int}.  The string must exactly match one
1737 of the data type names defined in the function
1738 @code{init_decl_processing} in the file @file{c-decl.c}.  You may not
1739 omit @code{int} or change the order---that would cause the compiler to
1740 crash on startup.
1741
1742 If you don't define this macro, the default is @code{"long unsigned
1743 int"}.
1744 @end defmac
1745
1746 @defmac PTRDIFF_TYPE
1747 A C expression for a string describing the name of the data type to use
1748 for the result of subtracting two pointers.  The typedef name
1749 @code{ptrdiff_t} is defined using the contents of the string.  See
1750 @code{SIZE_TYPE} above for more information.
1751
1752 If you don't define this macro, the default is @code{"long int"}.
1753 @end defmac
1754
1755 @defmac WCHAR_TYPE
1756 A C expression for a string describing the name of the data type to use
1757 for wide characters.  The typedef name @code{wchar_t} is defined using
1758 the contents of the string.  See @code{SIZE_TYPE} above for more
1759 information.
1760
1761 If you don't define this macro, the default is @code{"int"}.
1762 @end defmac
1763
1764 @defmac WCHAR_TYPE_SIZE
1765 A C expression for the size in bits of the data type for wide
1766 characters.  This is used in @code{cpp}, which cannot make use of
1767 @code{WCHAR_TYPE}.
1768 @end defmac
1769
1770 @defmac WINT_TYPE
1771 A C expression for a string describing the name of the data type to
1772 use for wide characters passed to @code{printf} and returned from
1773 @code{getwc}.  The typedef name @code{wint_t} is defined using the
1774 contents of the string.  See @code{SIZE_TYPE} above for more
1775 information.
1776
1777 If you don't define this macro, the default is @code{"unsigned int"}.
1778 @end defmac
1779
1780 @defmac INTMAX_TYPE
1781 A C expression for a string describing the name of the data type that
1782 can represent any value of any standard or extended signed integer type.
1783 The typedef name @code{intmax_t} is defined using the contents of the
1784 string.  See @code{SIZE_TYPE} above for more information.
1785
1786 If you don't define this macro, the default is the first of
1787 @code{"int"}, @code{"long int"}, or @code{"long long int"} that has as
1788 much precision as @code{long long int}.
1789 @end defmac
1790
1791 @defmac UINTMAX_TYPE
1792 A C expression for a string describing the name of the data type that
1793 can represent any value of any standard or extended unsigned integer
1794 type.  The typedef name @code{uintmax_t} is defined using the contents
1795 of the string.  See @code{SIZE_TYPE} above for more information.
1796
1797 If you don't define this macro, the default is the first of
1798 @code{"unsigned int"}, @code{"long unsigned int"}, or @code{"long long
1799 unsigned int"} that has as much precision as @code{long long unsigned
1800 int}.
1801 @end defmac
1802
1803 @defmac SIG_ATOMIC_TYPE
1804 @defmacx INT8_TYPE
1805 @defmacx INT16_TYPE
1806 @defmacx INT32_TYPE
1807 @defmacx INT64_TYPE
1808 @defmacx UINT8_TYPE
1809 @defmacx UINT16_TYPE
1810 @defmacx UINT32_TYPE
1811 @defmacx UINT64_TYPE
1812 @defmacx INT_LEAST8_TYPE
1813 @defmacx INT_LEAST16_TYPE
1814 @defmacx INT_LEAST32_TYPE
1815 @defmacx INT_LEAST64_TYPE
1816 @defmacx UINT_LEAST8_TYPE
1817 @defmacx UINT_LEAST16_TYPE
1818 @defmacx UINT_LEAST32_TYPE
1819 @defmacx UINT_LEAST64_TYPE
1820 @defmacx INT_FAST8_TYPE
1821 @defmacx INT_FAST16_TYPE
1822 @defmacx INT_FAST32_TYPE
1823 @defmacx INT_FAST64_TYPE
1824 @defmacx UINT_FAST8_TYPE
1825 @defmacx UINT_FAST16_TYPE
1826 @defmacx UINT_FAST32_TYPE
1827 @defmacx UINT_FAST64_TYPE
1828 @defmacx INTPTR_TYPE
1829 @defmacx UINTPTR_TYPE
1830 C expressions for the standard types @code{sig_atomic_t},
1831 @code{int8_t}, @code{int16_t}, @code{int32_t}, @code{int64_t},
1832 @code{uint8_t}, @code{uint16_t}, @code{uint32_t}, @code{uint64_t},
1833 @code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
1834 @code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
1835 @code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
1836 @code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
1837 @code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
1838 @code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t}.  See
1839 @code{SIZE_TYPE} above for more information.
1840
1841 If any of these macros evaluates to a null pointer, the corresponding
1842 type is not supported; if GCC is configured to provide
1843 @code{<stdint.h>} in such a case, the header provided may not conform
1844 to C99, depending on the type in question.  The defaults for all of
1845 these macros are null pointers.
1846 @end defmac
1847
1848 @defmac TARGET_PTRMEMFUNC_VBIT_LOCATION
1849 The C++ compiler represents a pointer-to-member-function with a struct
1850 that looks like:
1851
1852 @smallexample
1853   struct @{
1854     union @{
1855       void (*fn)();
1856       ptrdiff_t vtable_index;
1857     @};
1858     ptrdiff_t delta;
1859   @};
1860 @end smallexample
1861
1862 @noindent
1863 The C++ compiler must use one bit to indicate whether the function that
1864 will be called through a pointer-to-member-function is virtual.
1865 Normally, we assume that the low-order bit of a function pointer must
1866 always be zero.  Then, by ensuring that the vtable_index is odd, we can
1867 distinguish which variant of the union is in use.  But, on some
1868 platforms function pointers can be odd, and so this doesn't work.  In
1869 that case, we use the low-order bit of the @code{delta} field, and shift
1870 the remainder of the @code{delta} field to the left.
1871
1872 GCC will automatically make the right selection about where to store
1873 this bit using the @code{FUNCTION_BOUNDARY} setting for your platform.
1874 However, some platforms such as ARM/Thumb have @code{FUNCTION_BOUNDARY}
1875 set such that functions always start at even addresses, but the lowest
1876 bit of pointers to functions indicate whether the function at that
1877 address is in ARM or Thumb mode.  If this is the case of your
1878 architecture, you should define this macro to
1879 @code{ptrmemfunc_vbit_in_delta}.
1880
1881 In general, you should not have to define this macro.  On architectures
1882 in which function addresses are always even, according to
1883 @code{FUNCTION_BOUNDARY}, GCC will automatically define this macro to
1884 @code{ptrmemfunc_vbit_in_pfn}.
1885 @end defmac
1886
1887 @defmac TARGET_VTABLE_USES_DESCRIPTORS
1888 Normally, the C++ compiler uses function pointers in vtables.  This
1889 macro allows the target to change to use ``function descriptors''
1890 instead.  Function descriptors are found on targets for whom a
1891 function pointer is actually a small data structure.  Normally the
1892 data structure consists of the actual code address plus a data
1893 pointer to which the function's data is relative.
1894
1895 If vtables are used, the value of this macro should be the number
1896 of words that the function descriptor occupies.
1897 @end defmac
1898
1899 @defmac TARGET_VTABLE_ENTRY_ALIGN
1900 By default, the vtable entries are void pointers, the so the alignment
1901 is the same as pointer alignment.  The value of this macro specifies
1902 the alignment of the vtable entry in bits.  It should be defined only
1903 when special alignment is necessary. */
1904 @end defmac
1905
1906 @defmac TARGET_VTABLE_DATA_ENTRY_DISTANCE
1907 There are a few non-descriptor entries in the vtable at offsets below
1908 zero.  If these entries must be padded (say, to preserve the alignment
1909 specified by @code{TARGET_VTABLE_ENTRY_ALIGN}), set this to the number
1910 of words in each data entry.
1911 @end defmac
1912
1913 @node Registers
1914 @section Register Usage
1915 @cindex register usage
1916
1917 This section explains how to describe what registers the target machine
1918 has, and how (in general) they can be used.
1919
1920 The description of which registers a specific instruction can use is
1921 done with register classes; see @ref{Register Classes}.  For information
1922 on using registers to access a stack frame, see @ref{Frame Registers}.
1923 For passing values in registers, see @ref{Register Arguments}.
1924 For returning values in registers, see @ref{Scalar Return}.
1925
1926 @menu
1927 * Register Basics::             Number and kinds of registers.
1928 * Allocation Order::            Order in which registers are allocated.
1929 * Values in Registers::         What kinds of values each reg can hold.
1930 * Leaf Functions::              Renumbering registers for leaf functions.
1931 * Stack Registers::             Handling a register stack such as 80387.
1932 @end menu
1933
1934 @node Register Basics
1935 @subsection Basic Characteristics of Registers
1936
1937 @c prevent bad page break with this line
1938 Registers have various characteristics.
1939
1940 @defmac FIRST_PSEUDO_REGISTER
1941 Number of hardware registers known to the compiler.  They receive
1942 numbers 0 through @code{FIRST_PSEUDO_REGISTER-1}; thus, the first
1943 pseudo register's number really is assigned the number
1944 @code{FIRST_PSEUDO_REGISTER}.
1945 @end defmac
1946
1947 @defmac FIXED_REGISTERS
1948 @cindex fixed register
1949 An initializer that says which registers are used for fixed purposes
1950 all throughout the compiled code and are therefore not available for
1951 general allocation.  These would include the stack pointer, the frame
1952 pointer (except on machines where that can be used as a general
1953 register when no frame pointer is needed), the program counter on
1954 machines where that is considered one of the addressable registers,
1955 and any other numbered register with a standard use.
1956
1957 This information is expressed as a sequence of numbers, separated by
1958 commas and surrounded by braces.  The @var{n}th number is 1 if
1959 register @var{n} is fixed, 0 otherwise.
1960
1961 The table initialized from this macro, and the table initialized by
1962 the following one, may be overridden at run time either automatically,
1963 by the actions of the macro @code{CONDITIONAL_REGISTER_USAGE}, or by
1964 the user with the command options @option{-ffixed-@var{reg}},
1965 @option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}.
1966 @end defmac
1967
1968 @defmac CALL_USED_REGISTERS
1969 @cindex call-used register
1970 @cindex call-clobbered register
1971 @cindex call-saved register
1972 Like @code{FIXED_REGISTERS} but has 1 for each register that is
1973 clobbered (in general) by function calls as well as for fixed
1974 registers.  This macro therefore identifies the registers that are not
1975 available for general allocation of values that must live across
1976 function calls.
1977
1978 If a register has 0 in @code{CALL_USED_REGISTERS}, the compiler
1979 automatically saves it on function entry and restores it on function
1980 exit, if the register is used within the function.
1981 @end defmac
1982
1983 @defmac CALL_REALLY_USED_REGISTERS
1984 @cindex call-used register
1985 @cindex call-clobbered register
1986 @cindex call-saved register
1987 Like @code{CALL_USED_REGISTERS} except this macro doesn't require
1988 that the entire set of @code{FIXED_REGISTERS} be included.
1989 (@code{CALL_USED_REGISTERS} must be a superset of @code{FIXED_REGISTERS}).
1990 This macro is optional.  If not specified, it defaults to the value
1991 of @code{CALL_USED_REGISTERS}.
1992 @end defmac
1993
1994 @defmac HARD_REGNO_CALL_PART_CLOBBERED (@var{regno}, @var{mode})
1995 @cindex call-used register
1996 @cindex call-clobbered register
1997 @cindex call-saved register
1998 A C expression that is nonzero if it is not permissible to store a
1999 value of mode @var{mode} in hard register number @var{regno} across a
2000 call without some part of it being clobbered.  For most machines this
2001 macro need not be defined.  It is only required for machines that do not
2002 preserve the entire contents of a register across a call.
2003 @end defmac
2004
2005 @findex fixed_regs
2006 @findex call_used_regs
2007 @findex global_regs
2008 @findex reg_names
2009 @findex reg_class_contents
2010 @defmac CONDITIONAL_REGISTER_USAGE
2011 Zero or more C statements that may conditionally modify five variables
2012 @code{fixed_regs}, @code{call_used_regs}, @code{global_regs},
2013 @code{reg_names}, and @code{reg_class_contents}, to take into account
2014 any dependence of these register sets on target flags.  The first three
2015 of these are of type @code{char []} (interpreted as Boolean vectors).
2016 @code{global_regs} is a @code{const char *[]}, and
2017 @code{reg_class_contents} is a @code{HARD_REG_SET}.  Before the macro is
2018 called, @code{fixed_regs}, @code{call_used_regs},
2019 @code{reg_class_contents}, and @code{reg_names} have been initialized
2020 from @code{FIXED_REGISTERS}, @code{CALL_USED_REGISTERS},
2021 @code{REG_CLASS_CONTENTS}, and @code{REGISTER_NAMES}, respectively.
2022 @code{global_regs} has been cleared, and any @option{-ffixed-@var{reg}},
2023 @option{-fcall-used-@var{reg}} and @option{-fcall-saved-@var{reg}}
2024 command options have been applied.
2025
2026 You need not define this macro if it has no work to do.
2027
2028 @cindex disabling certain registers
2029 @cindex controlling register usage
2030 If the usage of an entire class of registers depends on the target
2031 flags, you may indicate this to GCC by using this macro to modify
2032 @code{fixed_regs} and @code{call_used_regs} to 1 for each of the
2033 registers in the classes which should not be used by GCC@.  Also define
2034 the macro @code{REG_CLASS_FROM_LETTER} / @code{REG_CLASS_FROM_CONSTRAINT}
2035 to return @code{NO_REGS} if it
2036 is called with a letter for a class that shouldn't be used.
2037
2038 (However, if this class is not included in @code{GENERAL_REGS} and all
2039 of the insn patterns whose constraints permit this class are
2040 controlled by target switches, then GCC will automatically avoid using
2041 these registers when the target switches are opposed to them.)
2042 @end defmac
2043
2044 @defmac INCOMING_REGNO (@var{out})
2045 Define this macro if the target machine has register windows.  This C
2046 expression returns the register number as seen by the called function
2047 corresponding to the register number @var{out} as seen by the calling
2048 function.  Return @var{out} if register number @var{out} is not an
2049 outbound register.
2050 @end defmac
2051
2052 @defmac OUTGOING_REGNO (@var{in})
2053 Define this macro if the target machine has register windows.  This C
2054 expression returns the register number as seen by the calling function
2055 corresponding to the register number @var{in} as seen by the called
2056 function.  Return @var{in} if register number @var{in} is not an inbound
2057 register.
2058 @end defmac
2059
2060 @defmac LOCAL_REGNO (@var{regno})
2061 Define this macro if the target machine has register windows.  This C
2062 expression returns true if the register is call-saved but is in the
2063 register window.  Unlike most call-saved registers, such registers
2064 need not be explicitly restored on function exit or during non-local
2065 gotos.
2066 @end defmac
2067
2068 @defmac PC_REGNUM
2069 If the program counter has a register number, define this as that
2070 register number.  Otherwise, do not define it.
2071 @end defmac
2072
2073 @node Allocation Order
2074 @subsection Order of Allocation of Registers
2075 @cindex order of register allocation
2076 @cindex register allocation order
2077
2078 @c prevent bad page break with this line
2079 Registers are allocated in order.
2080
2081 @defmac REG_ALLOC_ORDER
2082 If defined, an initializer for a vector of integers, containing the
2083 numbers of hard registers in the order in which GCC should prefer
2084 to use them (from most preferred to least).
2085
2086 If this macro is not defined, registers are used lowest numbered first
2087 (all else being equal).
2088
2089 One use of this macro is on machines where the highest numbered
2090 registers must always be saved and the save-multiple-registers
2091 instruction supports only sequences of consecutive registers.  On such
2092 machines, define @code{REG_ALLOC_ORDER} to be an initializer that lists
2093 the highest numbered allocable register first.
2094 @end defmac
2095
2096 @defmac ORDER_REGS_FOR_LOCAL_ALLOC
2097 A C statement (sans semicolon) to choose the order in which to allocate
2098 hard registers for pseudo-registers local to a basic block.
2099
2100 Store the desired register order in the array @code{reg_alloc_order}.
2101 Element 0 should be the register to allocate first; element 1, the next
2102 register; and so on.
2103
2104 The macro body should not assume anything about the contents of
2105 @code{reg_alloc_order} before execution of the macro.
2106
2107 On most machines, it is not necessary to define this macro.
2108 @end defmac
2109
2110 @defmac IRA_HARD_REGNO_ADD_COST_MULTIPLIER (@var{regno})
2111 In some case register allocation order is not enough for the
2112 Integrated Register Allocator (@acronym{IRA}) to generate a good code.
2113 If this macro is defined, it should return a floating point value
2114 based on @var{regno}.  The cost of using @var{regno} for a pseudo will
2115 be increased by approximately the pseudo's usage frequency times the
2116 value returned by this macro.  Not defining this macro is equivalent
2117 to having it always return @code{0.0}.
2118
2119 On most machines, it is not necessary to define this macro.
2120 @end defmac
2121
2122 @node Values in Registers
2123 @subsection How Values Fit in Registers
2124
2125 This section discusses the macros that describe which kinds of values
2126 (specifically, which machine modes) each register can hold, and how many
2127 consecutive registers are needed for a given mode.
2128
2129 @defmac HARD_REGNO_NREGS (@var{regno}, @var{mode})
2130 A C expression for the number of consecutive hard registers, starting
2131 at register number @var{regno}, required to hold a value of mode
2132 @var{mode}.  This macro must never return zero, even if a register
2133 cannot hold the requested mode - indicate that with HARD_REGNO_MODE_OK
2134 and/or CANNOT_CHANGE_MODE_CLASS instead.
2135
2136 On a machine where all registers are exactly one word, a suitable
2137 definition of this macro is
2138
2139 @smallexample
2140 #define HARD_REGNO_NREGS(REGNO, MODE)            \
2141    ((GET_MODE_SIZE (MODE) + UNITS_PER_WORD - 1)  \
2142     / UNITS_PER_WORD)
2143 @end smallexample
2144 @end defmac
2145
2146 @defmac HARD_REGNO_NREGS_HAS_PADDING (@var{regno}, @var{mode})
2147 A C expression that is nonzero if a value of mode @var{mode}, stored
2148 in memory, ends with padding that causes it to take up more space than
2149 in registers starting at register number @var{regno} (as determined by
2150 multiplying GCC's notion of the size of the register when containing
2151 this mode by the number of registers returned by
2152 @code{HARD_REGNO_NREGS}).  By default this is zero.
2153
2154 For example, if a floating-point value is stored in three 32-bit
2155 registers but takes up 128 bits in memory, then this would be
2156 nonzero.
2157
2158 This macros only needs to be defined if there are cases where
2159 @code{subreg_get_info}
2160 would otherwise wrongly determine that a @code{subreg} can be
2161 represented by an offset to the register number, when in fact such a
2162 @code{subreg} would contain some of the padding not stored in
2163 registers and so not be representable.
2164 @end defmac
2165
2166 @defmac HARD_REGNO_NREGS_WITH_PADDING (@var{regno}, @var{mode})
2167 For values of @var{regno} and @var{mode} for which
2168 @code{HARD_REGNO_NREGS_HAS_PADDING} returns nonzero, a C expression
2169 returning the greater number of registers required to hold the value
2170 including any padding.  In the example above, the value would be four.
2171 @end defmac
2172
2173 @defmac REGMODE_NATURAL_SIZE (@var{mode})
2174 Define this macro if the natural size of registers that hold values
2175 of mode @var{mode} is not the word size.  It is a C expression that
2176 should give the natural size in bytes for the specified mode.  It is
2177 used by the register allocator to try to optimize its results.  This
2178 happens for example on SPARC 64-bit where the natural size of
2179 floating-point registers is still 32-bit.
2180 @end defmac
2181
2182 @defmac HARD_REGNO_MODE_OK (@var{regno}, @var{mode})
2183 A C expression that is nonzero if it is permissible to store a value
2184 of mode @var{mode} in hard register number @var{regno} (or in several
2185 registers starting with that one).  For a machine where all registers
2186 are equivalent, a suitable definition is
2187
2188 @smallexample
2189 #define HARD_REGNO_MODE_OK(REGNO, MODE) 1
2190 @end smallexample
2191
2192 You need not include code to check for the numbers of fixed registers,
2193 because the allocation mechanism considers them to be always occupied.
2194
2195 @cindex register pairs
2196 On some machines, double-precision values must be kept in even/odd
2197 register pairs.  You can implement that by defining this macro to reject
2198 odd register numbers for such modes.
2199
2200 The minimum requirement for a mode to be OK in a register is that the
2201 @samp{mov@var{mode}} instruction pattern support moves between the
2202 register and other hard register in the same class and that moving a
2203 value into the register and back out not alter it.
2204
2205 Since the same instruction used to move @code{word_mode} will work for
2206 all narrower integer modes, it is not necessary on any machine for
2207 @code{HARD_REGNO_MODE_OK} to distinguish between these modes, provided
2208 you define patterns @samp{movhi}, etc., to take advantage of this.  This
2209 is useful because of the interaction between @code{HARD_REGNO_MODE_OK}
2210 and @code{MODES_TIEABLE_P}; it is very desirable for all integer modes
2211 to be tieable.
2212
2213 Many machines have special registers for floating point arithmetic.
2214 Often people assume that floating point machine modes are allowed only
2215 in floating point registers.  This is not true.  Any registers that
2216 can hold integers can safely @emph{hold} a floating point machine
2217 mode, whether or not floating arithmetic can be done on it in those
2218 registers.  Integer move instructions can be used to move the values.
2219
2220 On some machines, though, the converse is true: fixed-point machine
2221 modes may not go in floating registers.  This is true if the floating
2222 registers normalize any value stored in them, because storing a
2223 non-floating value there would garble it.  In this case,
2224 @code{HARD_REGNO_MODE_OK} should reject fixed-point machine modes in
2225 floating registers.  But if the floating registers do not automatically
2226 normalize, if you can store any bit pattern in one and retrieve it
2227 unchanged without a trap, then any machine mode may go in a floating
2228 register, so you can define this macro to say so.
2229
2230 The primary significance of special floating registers is rather that
2231 they are the registers acceptable in floating point arithmetic
2232 instructions.  However, this is of no concern to
2233 @code{HARD_REGNO_MODE_OK}.  You handle it by writing the proper
2234 constraints for those instructions.
2235
2236 On some machines, the floating registers are especially slow to access,
2237 so that it is better to store a value in a stack frame than in such a
2238 register if floating point arithmetic is not being done.  As long as the
2239 floating registers are not in class @code{GENERAL_REGS}, they will not
2240 be used unless some pattern's constraint asks for one.
2241 @end defmac
2242
2243 @defmac HARD_REGNO_RENAME_OK (@var{from}, @var{to})
2244 A C expression that is nonzero if it is OK to rename a hard register
2245 @var{from} to another hard register @var{to}.
2246
2247 One common use of this macro is to prevent renaming of a register to
2248 another register that is not saved by a prologue in an interrupt
2249 handler.
2250
2251 The default is always nonzero.
2252 @end defmac
2253
2254 @defmac MODES_TIEABLE_P (@var{mode1}, @var{mode2})
2255 A C expression that is nonzero if a value of mode
2256 @var{mode1} is accessible in mode @var{mode2} without copying.
2257
2258 If @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode1})} and
2259 @code{HARD_REGNO_MODE_OK (@var{r}, @var{mode2})} are always the same for
2260 any @var{r}, then @code{MODES_TIEABLE_P (@var{mode1}, @var{mode2})}
2261 should be nonzero.  If they differ for any @var{r}, you should define
2262 this macro to return zero unless some other mechanism ensures the
2263 accessibility of the value in a narrower mode.
2264
2265 You should define this macro to return nonzero in as many cases as
2266 possible since doing so will allow GCC to perform better register
2267 allocation.
2268 @end defmac
2269
2270 @deftypefn {Target Hook} bool TARGET_HARD_REGNO_SCRATCH_OK (unsigned int @var{regno})
2271 This target hook should return @code{true} if it is OK to use a hard register
2272 @var{regno} as scratch reg in peephole2.
2273
2274 One common use of this macro is to prevent using of a register that
2275 is not saved by a prologue in an interrupt handler.
2276
2277 The default version of this hook always returns @code{true}.
2278 @end deftypefn
2279
2280 @defmac AVOID_CCMODE_COPIES
2281 Define this macro if the compiler should avoid copies to/from @code{CCmode}
2282 registers.  You should only define this macro if support for copying to/from
2283 @code{CCmode} is incomplete.
2284 @end defmac
2285
2286 @node Leaf Functions
2287 @subsection Handling Leaf Functions
2288
2289 @cindex leaf functions
2290 @cindex functions, leaf
2291 On some machines, a leaf function (i.e., one which makes no calls) can run
2292 more efficiently if it does not make its own register window.  Often this
2293 means it is required to receive its arguments in the registers where they
2294 are passed by the caller, instead of the registers where they would
2295 normally arrive.
2296
2297 The special treatment for leaf functions generally applies only when
2298 other conditions are met; for example, often they may use only those
2299 registers for its own variables and temporaries.  We use the term ``leaf
2300 function'' to mean a function that is suitable for this special
2301 handling, so that functions with no calls are not necessarily ``leaf
2302 functions''.
2303
2304 GCC assigns register numbers before it knows whether the function is
2305 suitable for leaf function treatment.  So it needs to renumber the
2306 registers in order to output a leaf function.  The following macros
2307 accomplish this.
2308
2309 @defmac LEAF_REGISTERS
2310 Name of a char vector, indexed by hard register number, which
2311 contains 1 for a register that is allowable in a candidate for leaf
2312 function treatment.
2313
2314 If leaf function treatment involves renumbering the registers, then the
2315 registers marked here should be the ones before renumbering---those that
2316 GCC would ordinarily allocate.  The registers which will actually be
2317 used in the assembler code, after renumbering, should not be marked with 1
2318 in this vector.
2319
2320 Define this macro only if the target machine offers a way to optimize
2321 the treatment of leaf functions.
2322 @end defmac
2323
2324 @defmac LEAF_REG_REMAP (@var{regno})
2325 A C expression whose value is the register number to which @var{regno}
2326 should be renumbered, when a function is treated as a leaf function.
2327
2328 If @var{regno} is a register number which should not appear in a leaf
2329 function before renumbering, then the expression should yield @minus{}1, which
2330 will cause the compiler to abort.
2331
2332 Define this macro only if the target machine offers a way to optimize the
2333 treatment of leaf functions, and registers need to be renumbered to do
2334 this.
2335 @end defmac
2336
2337 @findex current_function_is_leaf
2338 @findex current_function_uses_only_leaf_regs
2339 @code{TARGET_ASM_FUNCTION_PROLOGUE} and
2340 @code{TARGET_ASM_FUNCTION_EPILOGUE} must usually treat leaf functions
2341 specially.  They can test the C variable @code{current_function_is_leaf}
2342 which is nonzero for leaf functions.  @code{current_function_is_leaf} is
2343 set prior to local register allocation and is valid for the remaining
2344 compiler passes.  They can also test the C variable
2345 @code{current_function_uses_only_leaf_regs} which is nonzero for leaf
2346 functions which only use leaf registers.
2347 @code{current_function_uses_only_leaf_regs} is valid after all passes
2348 that modify the instructions have been run and is only useful if
2349 @code{LEAF_REGISTERS} is defined.
2350 @c changed this to fix overfull.  ALSO:  why the "it" at the beginning
2351 @c of the next paragraph?!  --mew 2feb93
2352
2353 @node Stack Registers
2354 @subsection Registers That Form a Stack
2355
2356 There are special features to handle computers where some of the
2357 ``registers'' form a stack.  Stack registers are normally written by
2358 pushing onto the stack, and are numbered relative to the top of the
2359 stack.
2360
2361 Currently, GCC can only handle one group of stack-like registers, and
2362 they must be consecutively numbered.  Furthermore, the existing
2363 support for stack-like registers is specific to the 80387 floating
2364 point coprocessor.  If you have a new architecture that uses
2365 stack-like registers, you will need to do substantial work on
2366 @file{reg-stack.c} and write your machine description to cooperate
2367 with it, as well as defining these macros.
2368
2369 @defmac STACK_REGS
2370 Define this if the machine has any stack-like registers.
2371 @end defmac
2372
2373 @defmac STACK_REG_COVER_CLASS
2374 This is a cover class containing the stack registers.  Define this if
2375 the machine has any stack-like registers.
2376 @end defmac
2377
2378 @defmac FIRST_STACK_REG
2379 The number of the first stack-like register.  This one is the top
2380 of the stack.
2381 @end defmac
2382
2383 @defmac LAST_STACK_REG
2384 The number of the last stack-like register.  This one is the bottom of
2385 the stack.
2386 @end defmac
2387
2388 @node Register Classes
2389 @section Register Classes
2390 @cindex register class definitions
2391 @cindex class definitions, register
2392
2393 On many machines, the numbered registers are not all equivalent.
2394 For example, certain registers may not be allowed for indexed addressing;
2395 certain registers may not be allowed in some instructions.  These machine
2396 restrictions are described to the compiler using @dfn{register classes}.
2397
2398 You define a number of register classes, giving each one a name and saying
2399 which of the registers belong to it.  Then you can specify register classes
2400 that are allowed as operands to particular instruction patterns.
2401
2402 @findex ALL_REGS
2403 @findex NO_REGS
2404 In general, each register will belong to several classes.  In fact, one
2405 class must be named @code{ALL_REGS} and contain all the registers.  Another
2406 class must be named @code{NO_REGS} and contain no registers.  Often the
2407 union of two classes will be another class; however, this is not required.
2408
2409 @findex GENERAL_REGS
2410 One of the classes must be named @code{GENERAL_REGS}.  There is nothing
2411 terribly special about the name, but the operand constraint letters
2412 @samp{r} and @samp{g} specify this class.  If @code{GENERAL_REGS} is
2413 the same as @code{ALL_REGS}, just define it as a macro which expands
2414 to @code{ALL_REGS}.
2415
2416 Order the classes so that if class @var{x} is contained in class @var{y}
2417 then @var{x} has a lower class number than @var{y}.
2418
2419 The way classes other than @code{GENERAL_REGS} are specified in operand
2420 constraints is through machine-dependent operand constraint letters.
2421 You can define such letters to correspond to various classes, then use
2422 them in operand constraints.
2423
2424 You should define a class for the union of two classes whenever some
2425 instruction allows both classes.  For example, if an instruction allows
2426 either a floating point (coprocessor) register or a general register for a
2427 certain operand, you should define a class @code{FLOAT_OR_GENERAL_REGS}
2428 which includes both of them.  Otherwise you will get suboptimal code.
2429
2430 You must also specify certain redundant information about the register
2431 classes: for each class, which classes contain it and which ones are
2432 contained in it; for each pair of classes, the largest class contained
2433 in their union.
2434
2435 When a value occupying several consecutive registers is expected in a
2436 certain class, all the registers used must belong to that class.
2437 Therefore, register classes cannot be used to enforce a requirement for
2438 a register pair to start with an even-numbered register.  The way to
2439 specify this requirement is with @code{HARD_REGNO_MODE_OK}.
2440
2441 Register classes used for input-operands of bitwise-and or shift
2442 instructions have a special requirement: each such class must have, for
2443 each fixed-point machine mode, a subclass whose registers can transfer that
2444 mode to or from memory.  For example, on some machines, the operations for
2445 single-byte values (@code{QImode}) are limited to certain registers.  When
2446 this is so, each register class that is used in a bitwise-and or shift
2447 instruction must have a subclass consisting of registers from which
2448 single-byte values can be loaded or stored.  This is so that
2449 @code{PREFERRED_RELOAD_CLASS} can always have a possible value to return.
2450
2451 @deftp {Data type} {enum reg_class}
2452 An enumerated type that must be defined with all the register class names
2453 as enumerated values.  @code{NO_REGS} must be first.  @code{ALL_REGS}
2454 must be the last register class, followed by one more enumerated value,
2455 @code{LIM_REG_CLASSES}, which is not a register class but rather
2456 tells how many classes there are.
2457
2458 Each register class has a number, which is the value of casting
2459 the class name to type @code{int}.  The number serves as an index
2460 in many of the tables described below.
2461 @end deftp
2462
2463 @defmac N_REG_CLASSES
2464 The number of distinct register classes, defined as follows:
2465
2466 @smallexample
2467 #define N_REG_CLASSES (int) LIM_REG_CLASSES
2468 @end smallexample
2469 @end defmac
2470
2471 @defmac REG_CLASS_NAMES
2472 An initializer containing the names of the register classes as C string
2473 constants.  These names are used in writing some of the debugging dumps.
2474 @end defmac
2475
2476 @defmac REG_CLASS_CONTENTS
2477 An initializer containing the contents of the register classes, as integers
2478 which are bit masks.  The @var{n}th integer specifies the contents of class
2479 @var{n}.  The way the integer @var{mask} is interpreted is that
2480 register @var{r} is in the class if @code{@var{mask} & (1 << @var{r})} is 1.
2481
2482 When the machine has more than 32 registers, an integer does not suffice.
2483 Then the integers are replaced by sub-initializers, braced groupings containing
2484 several integers.  Each sub-initializer must be suitable as an initializer
2485 for the type @code{HARD_REG_SET} which is defined in @file{hard-reg-set.h}.
2486 In this situation, the first integer in each sub-initializer corresponds to
2487 registers 0 through 31, the second integer to registers 32 through 63, and
2488 so on.
2489 @end defmac
2490
2491 @defmac REGNO_REG_CLASS (@var{regno})
2492 A C expression whose value is a register class containing hard register
2493 @var{regno}.  In general there is more than one such class; choose a class
2494 which is @dfn{minimal}, meaning that no smaller class also contains the
2495 register.
2496 @end defmac
2497
2498 @defmac BASE_REG_CLASS
2499 A macro whose definition is the name of the class to which a valid
2500 base register must belong.  A base register is one used in an address
2501 which is the register value plus a displacement.
2502 @end defmac
2503
2504 @defmac MODE_BASE_REG_CLASS (@var{mode})
2505 This is a variation of the @code{BASE_REG_CLASS} macro which allows
2506 the selection of a base register in a mode dependent manner.  If
2507 @var{mode} is VOIDmode then it should return the same value as
2508 @code{BASE_REG_CLASS}.
2509 @end defmac
2510
2511 @defmac MODE_BASE_REG_REG_CLASS (@var{mode})
2512 A C expression whose value is the register class to which a valid
2513 base register must belong in order to be used in a base plus index
2514 register address.  You should define this macro if base plus index
2515 addresses have different requirements than other base register uses.
2516 @end defmac
2517
2518 @defmac MODE_CODE_BASE_REG_CLASS (@var{mode}, @var{outer_code}, @var{index_code})
2519 A C expression whose value is the register class to which a valid
2520 base register must belong.  @var{outer_code} and @var{index_code} define the
2521 context in which the base register occurs.  @var{outer_code} is the code of
2522 the immediately enclosing expression (@code{MEM} for the top level of an
2523 address, @code{ADDRESS} for something that occurs in an
2524 @code{address_operand}).  @var{index_code} is the code of the corresponding
2525 index expression if @var{outer_code} is @code{PLUS}; @code{SCRATCH} otherwise.
2526 @end defmac
2527
2528 @defmac INDEX_REG_CLASS
2529 A macro whose definition is the name of the class to which a valid
2530 index register must belong.  An index register is one used in an
2531 address where its value is either multiplied by a scale factor or
2532 added to another register (as well as added to a displacement).
2533 @end defmac
2534
2535 @defmac REGNO_OK_FOR_BASE_P (@var{num})
2536 A C expression which is nonzero if register number @var{num} is
2537 suitable for use as a base register in operand addresses.
2538 Like @code{TARGET_LEGITIMATE_ADDRESS_P}, this macro should also
2539 define a strict and a non-strict variant.  Both variants behave
2540 the same for hard register; for pseudos, the strict variant will
2541 pass only those that have been allocated to a valid hard registers,
2542 while the non-strict variant will pass all pseudos.
2543
2544 @findex REG_OK_STRICT
2545 Compiler source files that want to use the strict variant of this and
2546 other macros define the macro @code{REG_OK_STRICT}.  You should use an
2547 @code{#ifdef REG_OK_STRICT} conditional to define the strict variant in
2548 that case and the non-strict variant otherwise.
2549 @end defmac
2550
2551 @defmac REGNO_MODE_OK_FOR_BASE_P (@var{num}, @var{mode})
2552 A C expression that is just like @code{REGNO_OK_FOR_BASE_P}, except that
2553 that expression may examine the mode of the memory reference in
2554 @var{mode}.  You should define this macro if the mode of the memory
2555 reference affects whether a register may be used as a base register.  If
2556 you define this macro, the compiler will use it instead of
2557 @code{REGNO_OK_FOR_BASE_P}.  The mode may be @code{VOIDmode} for
2558 addresses that appear outside a @code{MEM}, i.e., as an
2559 @code{address_operand}.
2560
2561 This macro also has strict and non-strict variants.
2562 @end defmac
2563
2564 @defmac REGNO_MODE_OK_FOR_REG_BASE_P (@var{num}, @var{mode})
2565 A C expression which is nonzero if register number @var{num} is suitable for
2566 use as a base register in base plus index operand addresses, accessing
2567 memory in mode @var{mode}.  It may be either a suitable hard register or a
2568 pseudo register that has been allocated such a hard register.  You should
2569 define this macro if base plus index addresses have different requirements
2570 than other base register uses.
2571
2572 Use of this macro is deprecated; please use the more general
2573 @code{REGNO_MODE_CODE_OK_FOR_BASE_P}.
2574
2575 This macro also has strict and non-strict variants.
2576 @end defmac
2577
2578 @defmac REGNO_MODE_CODE_OK_FOR_BASE_P (@var{num}, @var{mode}, @var{outer_code}, @var{index_code})
2579 A C expression that is just like @code{REGNO_MODE_OK_FOR_BASE_P}, except
2580 that that expression may examine the context in which the register
2581 appears in the memory reference.  @var{outer_code} is the code of the
2582 immediately enclosing expression (@code{MEM} if at the top level of the
2583 address, @code{ADDRESS} for something that occurs in an
2584 @code{address_operand}).  @var{index_code} is the code of the
2585 corresponding index expression if @var{outer_code} is @code{PLUS};
2586 @code{SCRATCH} otherwise.  The mode may be @code{VOIDmode} for addresses
2587 that appear outside a @code{MEM}, i.e., as an @code{address_operand}.
2588
2589 This macro also has strict and non-strict variants.
2590 @end defmac
2591
2592 @defmac REGNO_OK_FOR_INDEX_P (@var{num})
2593 A C expression which is nonzero if register number @var{num} is
2594 suitable for use as an index register in operand addresses.  It may be
2595 either a suitable hard register or a pseudo register that has been
2596 allocated such a hard register.
2597
2598 The difference between an index register and a base register is that
2599 the index register may be scaled.  If an address involves the sum of
2600 two registers, neither one of them scaled, then either one may be
2601 labeled the ``base'' and the other the ``index''; but whichever
2602 labeling is used must fit the machine's constraints of which registers
2603 may serve in each capacity.  The compiler will try both labelings,
2604 looking for one that is valid, and will reload one or both registers
2605 only if neither labeling works.
2606
2607 This macro also has strict and non-strict variants.
2608 @end defmac
2609
2610 @defmac PREFERRED_RELOAD_CLASS (@var{x}, @var{class})
2611 A C expression that places additional restrictions on the register class
2612 to use when it is necessary to copy value @var{x} into a register in class
2613 @var{class}.  The value is a register class; perhaps @var{class}, or perhaps
2614 another, smaller class.  On many machines, the following definition is
2615 safe:
2616
2617 @smallexample
2618 #define PREFERRED_RELOAD_CLASS(X,CLASS) CLASS
2619 @end smallexample
2620
2621 Sometimes returning a more restrictive class makes better code.  For
2622 example, on the 68000, when @var{x} is an integer constant that is in range
2623 for a @samp{moveq} instruction, the value of this macro is always
2624 @code{DATA_REGS} as long as @var{class} includes the data registers.
2625 Requiring a data register guarantees that a @samp{moveq} will be used.
2626
2627 One case where @code{PREFERRED_RELOAD_CLASS} must not return
2628 @var{class} is if @var{x} is a legitimate constant which cannot be
2629 loaded into some register class.  By returning @code{NO_REGS} you can
2630 force @var{x} into a memory location.  For example, rs6000 can load
2631 immediate values into general-purpose registers, but does not have an
2632 instruction for loading an immediate value into a floating-point
2633 register, so @code{PREFERRED_RELOAD_CLASS} returns @code{NO_REGS} when
2634 @var{x} is a floating-point constant.  If the constant can't be loaded
2635 into any kind of register, code generation will be better if
2636 @code{LEGITIMATE_CONSTANT_P} makes the constant illegitimate instead
2637 of using @code{PREFERRED_RELOAD_CLASS}.
2638
2639 If an insn has pseudos in it after register allocation, reload will go
2640 through the alternatives and call repeatedly @code{PREFERRED_RELOAD_CLASS}
2641 to find the best one.  Returning @code{NO_REGS}, in this case, makes
2642 reload add a @code{!} in front of the constraint: the x86 back-end uses
2643 this feature to discourage usage of 387 registers when math is done in
2644 the SSE registers (and vice versa).
2645 @end defmac
2646
2647 @defmac PREFERRED_OUTPUT_RELOAD_CLASS (@var{x}, @var{class})
2648 Like @code{PREFERRED_RELOAD_CLASS}, but for output reloads instead of
2649 input reloads.  If you don't define this macro, the default is to use
2650 @var{class}, unchanged.
2651
2652 You can also use @code{PREFERRED_OUTPUT_RELOAD_CLASS} to discourage
2653 reload from using some alternatives, like @code{PREFERRED_RELOAD_CLASS}.
2654 @end defmac
2655
2656 @defmac LIMIT_RELOAD_CLASS (@var{mode}, @var{class})
2657 A C expression that places additional restrictions on the register class
2658 to use when it is necessary to be able to hold a value of mode
2659 @var{mode} in a reload register for which class @var{class} would
2660 ordinarily be used.
2661
2662 Unlike @code{PREFERRED_RELOAD_CLASS}, this macro should be used when
2663 there are certain modes that simply can't go in certain reload classes.
2664
2665 The value is a register class; perhaps @var{class}, or perhaps another,
2666 smaller class.
2667
2668 Don't define this macro unless the target machine has limitations which
2669 require the macro to do something nontrivial.
2670 @end defmac
2671
2672 @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})
2673 Many machines have some registers that cannot be copied directly to or
2674 from memory or even from other types of registers.  An example is the
2675 @samp{MQ} register, which on most machines, can only be copied to or
2676 from general registers, but not memory.  Below, we shall be using the
2677 term 'intermediate register' when a move operation cannot be performed
2678 directly, but has to be done by copying the source into the intermediate
2679 register first, and then copying the intermediate register to the
2680 destination.  An intermediate register always has the same mode as
2681 source and destination.  Since it holds the actual value being copied,
2682 reload might apply optimizations to re-use an intermediate register
2683 and eliding the copy from the source when it can determine that the
2684 intermediate register still holds the required value.
2685
2686 Another kind of secondary reload is required on some machines which
2687 allow copying all registers to and from memory, but require a scratch
2688 register for stores to some memory locations (e.g., those with symbolic
2689 address on the RT, and those with certain symbolic address on the SPARC
2690 when compiling PIC)@.  Scratch registers need not have the same mode
2691 as the value being copied, and usually hold a different value than
2692 that being copied.  Special patterns in the md file are needed to
2693 describe how the copy is performed with the help of the scratch register;
2694 these patterns also describe the number, register class(es) and mode(s)
2695 of the scratch register(s).
2696
2697 In some cases, both an intermediate and a scratch register are required.
2698
2699 For input reloads, this target hook is called with nonzero @var{in_p},
2700 and @var{x} is an rtx that needs to be copied to a register of class
2701 @var{reload_class} in @var{reload_mode}.  For output reloads, this target
2702 hook is called with zero @var{in_p}, and a register of class @var{reload_class}
2703 needs to be copied to rtx @var{x} in @var{reload_mode}.
2704
2705 If copying a register of @var{reload_class} from/to @var{x} requires
2706 an intermediate register, the hook @code{secondary_reload} should
2707 return the register class required for this intermediate register.
2708 If no intermediate register is required, it should return NO_REGS.
2709 If more than one intermediate register is required, describe the one
2710 that is closest in the copy chain to the reload register.
2711
2712 If scratch registers are needed, you also have to describe how to
2713 perform the copy from/to the reload register to/from this
2714 closest intermediate register.  Or if no intermediate register is
2715 required, but still a scratch register is needed, describe the
2716 copy  from/to the reload register to/from the reload operand @var{x}.
2717
2718 You do this by setting @code{sri->icode} to the instruction code of a pattern
2719 in the md file which performs the move.  Operands 0 and 1 are the output
2720 and input of this copy, respectively.  Operands from operand 2 onward are
2721 for scratch operands.  These scratch operands must have a mode, and a
2722 single-register-class
2723 @c [later: or memory]
2724 output constraint.
2725
2726 When an intermediate register is used, the @code{secondary_reload}
2727 hook will be called again to determine how to copy the intermediate
2728 register to/from the reload operand @var{x}, so your hook must also
2729 have code to handle the register class of the intermediate operand.
2730
2731 @c [For later: maybe we'll allow multi-alternative reload patterns -
2732 @c   the port maintainer could name a mov<mode> pattern that has clobbers -
2733 @c   and match the constraints of input and output to determine the required
2734 @c   alternative.  A restriction would be that constraints used to match
2735 @c   against reloads registers would have to be written as register class
2736 @c   constraints, or we need a new target macro / hook that tells us if an
2737 @c   arbitrary constraint can match an unknown register of a given class.
2738 @c   Such a macro / hook would also be useful in other places.]
2739
2740
2741 @var{x} might be a pseudo-register or a @code{subreg} of a
2742 pseudo-register, which could either be in a hard register or in memory.
2743 Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is
2744 in memory and the hard register number if it is in a register.
2745
2746 Scratch operands in memory (constraint @code{"=m"} / @code{"=&m"}) are
2747 currently not supported.  For the time being, you will have to continue
2748 to use @code{SECONDARY_MEMORY_NEEDED} for that purpose.
2749
2750 @code{copy_cost} also uses this target hook to find out how values are
2751 copied.  If you want it to include some extra cost for the need to allocate
2752 (a) scratch register(s), set @code{sri->extra_cost} to the additional cost.
2753 Or if two dependent moves are supposed to have a lower cost than the sum
2754 of the individual moves due to expected fortuitous scheduling and/or special
2755 forwarding logic, you can set @code{sri->extra_cost} to a negative amount.
2756 @end deftypefn
2757
2758 @defmac SECONDARY_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
2759 @defmacx SECONDARY_INPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
2760 @defmacx SECONDARY_OUTPUT_RELOAD_CLASS (@var{class}, @var{mode}, @var{x})
2761 These macros are obsolete, new ports should use the target hook
2762 @code{TARGET_SECONDARY_RELOAD} instead.
2763
2764 These are obsolete macros, replaced by the @code{TARGET_SECONDARY_RELOAD}
2765 target hook.  Older ports still define these macros to indicate to the
2766 reload phase that it may
2767 need to allocate at least one register for a reload in addition to the
2768 register to contain the data.  Specifically, if copying @var{x} to a
2769 register @var{class} in @var{mode} requires an intermediate register,
2770 you were supposed to define @code{SECONDARY_INPUT_RELOAD_CLASS} to return the
2771 largest register class all of whose registers can be used as
2772 intermediate registers or scratch registers.
2773
2774 If copying a register @var{class} in @var{mode} to @var{x} requires an
2775 intermediate or scratch register, @code{SECONDARY_OUTPUT_RELOAD_CLASS}
2776 was supposed to be defined be defined to return the largest register
2777 class required.  If the
2778 requirements for input and output reloads were the same, the macro
2779 @code{SECONDARY_RELOAD_CLASS} should have been used instead of defining both
2780 macros identically.
2781
2782 The values returned by these macros are often @code{GENERAL_REGS}.
2783 Return @code{NO_REGS} if no spare register is needed; i.e., if @var{x}
2784 can be directly copied to or from a register of @var{class} in
2785 @var{mode} without requiring a scratch register.  Do not define this
2786 macro if it would always return @code{NO_REGS}.
2787
2788 If a scratch register is required (either with or without an
2789 intermediate register), you were supposed to define patterns for
2790 @samp{reload_in@var{m}} or @samp{reload_out@var{m}}, as required
2791 (@pxref{Standard Names}.  These patterns, which were normally
2792 implemented with a @code{define_expand}, should be similar to the
2793 @samp{mov@var{m}} patterns, except that operand 2 is the scratch
2794 register.
2795
2796 These patterns need constraints for the reload register and scratch
2797 register that
2798 contain a single register class.  If the original reload register (whose
2799 class is @var{class}) can meet the constraint given in the pattern, the
2800 value returned by these macros is used for the class of the scratch
2801 register.  Otherwise, two additional reload registers are required.
2802 Their classes are obtained from the constraints in the insn pattern.
2803
2804 @var{x} might be a pseudo-register or a @code{subreg} of a
2805 pseudo-register, which could either be in a hard register or in memory.
2806 Use @code{true_regnum} to find out; it will return @minus{}1 if the pseudo is
2807 in memory and the hard register number if it is in a register.
2808
2809 These macros should not be used in the case where a particular class of
2810 registers can only be copied to memory and not to another class of
2811 registers.  In that case, secondary reload registers are not needed and
2812 would not be helpful.  Instead, a stack location must be used to perform
2813 the copy and the @code{mov@var{m}} pattern should use memory as an
2814 intermediate storage.  This case often occurs between floating-point and
2815 general registers.
2816 @end defmac
2817
2818 @defmac SECONDARY_MEMORY_NEEDED (@var{class1}, @var{class2}, @var{m})
2819 Certain machines have the property that some registers cannot be copied
2820 to some other registers without using memory.  Define this macro on
2821 those machines to be a C expression that is nonzero if objects of mode
2822 @var{m} in registers of @var{class1} can only be copied to registers of
2823 class @var{class2} by storing a register of @var{class1} into memory
2824 and loading that memory location into a register of @var{class2}.
2825
2826 Do not define this macro if its value would always be zero.
2827 @end defmac
2828
2829 @defmac SECONDARY_MEMORY_NEEDED_RTX (@var{mode})
2830 Normally when @code{SECONDARY_MEMORY_NEEDED} is defined, the compiler
2831 allocates a stack slot for a memory location needed for register copies.
2832 If this macro is defined, the compiler instead uses the memory location
2833 defined by this macro.
2834
2835 Do not define this macro if you do not define
2836 @code{SECONDARY_MEMORY_NEEDED}.
2837 @end defmac
2838
2839 @defmac SECONDARY_MEMORY_NEEDED_MODE (@var{mode})
2840 When the compiler needs a secondary memory location to copy between two
2841 registers of mode @var{mode}, it normally allocates sufficient memory to
2842 hold a quantity of @code{BITS_PER_WORD} bits and performs the store and
2843 load operations in a mode that many bits wide and whose class is the
2844 same as that of @var{mode}.
2845
2846 This is right thing to do on most machines because it ensures that all
2847 bits of the register are copied and prevents accesses to the registers
2848 in a narrower mode, which some machines prohibit for floating-point
2849 registers.
2850
2851 However, this default behavior is not correct on some machines, such as
2852 the DEC Alpha, that store short integers in floating-point registers
2853 differently than in integer registers.  On those machines, the default
2854 widening will not work correctly and you must define this macro to
2855 suppress that widening in some cases.  See the file @file{alpha.h} for
2856 details.
2857
2858 Do not define this macro if you do not define
2859 @code{SECONDARY_MEMORY_NEEDED} or if widening @var{mode} to a mode that
2860 is @code{BITS_PER_WORD} bits wide is correct for your machine.
2861 @end defmac
2862
2863 @defmac SMALL_REGISTER_CLASSES
2864 On some machines, it is risky to let hard registers live across arbitrary
2865 insns.  Typically, these machines have instructions that require values
2866 to be in specific registers (like an accumulator), and reload will fail
2867 if the required hard register is used for another purpose across such an
2868 insn.
2869
2870 Define @code{SMALL_REGISTER_CLASSES} to be an expression with a nonzero
2871 value on these machines.  When this macro has a nonzero value, the
2872 compiler will try to minimize the lifetime of hard registers.
2873
2874 It is always safe to define this macro with a nonzero value, but if you
2875 unnecessarily define it, you will reduce the amount of optimizations
2876 that can be performed in some cases.  If you do not define this macro
2877 with a nonzero value when it is required, the compiler will run out of
2878 spill registers and print a fatal error message.  For most machines, you
2879 should not define this macro at all.
2880 @end defmac
2881
2882 @defmac CLASS_LIKELY_SPILLED_P (@var{class})
2883 A C expression whose value is nonzero if pseudos that have been assigned
2884 to registers of class @var{class} would likely be spilled because
2885 registers of @var{class} are needed for spill registers.
2886
2887 The default value of this macro returns 1 if @var{class} has exactly one
2888 register and zero otherwise.  On most machines, this default should be
2889 used.  Only define this macro to some other expression if pseudos
2890 allocated by @file{local-alloc.c} end up in memory because their hard
2891 registers were needed for spill registers.  If this macro returns nonzero
2892 for those classes, those pseudos will only be allocated by
2893 @file{global.c}, which knows how to reallocate the pseudo to another
2894 register.  If there would not be another register available for
2895 reallocation, you should not change the definition of this macro since
2896 the only effect of such a definition would be to slow down register
2897 allocation.
2898 @end defmac
2899
2900 @defmac CLASS_MAX_NREGS (@var{class}, @var{mode})
2901 A C expression for the maximum number of consecutive registers
2902 of class @var{class} needed to hold a value of mode @var{mode}.
2903
2904 This is closely related to the macro @code{HARD_REGNO_NREGS}.  In fact,
2905 the value of the macro @code{CLASS_MAX_NREGS (@var{class}, @var{mode})}
2906 should be the maximum value of @code{HARD_REGNO_NREGS (@var{regno},
2907 @var{mode})} for all @var{regno} values in the class @var{class}.
2908
2909 This macro helps control the handling of multiple-word values
2910 in the reload pass.
2911 @end defmac
2912
2913 @defmac CANNOT_CHANGE_MODE_CLASS (@var{from}, @var{to}, @var{class})
2914 If defined, a C expression that returns nonzero for a @var{class} for which
2915 a change from mode @var{from} to mode @var{to} is invalid.
2916
2917 For the example, loading 32-bit integer or floating-point objects into
2918 floating-point registers on the Alpha extends them to 64 bits.
2919 Therefore loading a 64-bit object and then storing it as a 32-bit object
2920 does not store the low-order 32 bits, as would be the case for a normal
2921 register.  Therefore, @file{alpha.h} defines @code{CANNOT_CHANGE_MODE_CLASS}
2922 as below:
2923
2924 @smallexample
2925 #define CANNOT_CHANGE_MODE_CLASS(FROM, TO, CLASS) \
2926   (GET_MODE_SIZE (FROM) != GET_MODE_SIZE (TO) \
2927    ? reg_classes_intersect_p (FLOAT_REGS, (CLASS)) : 0)
2928 @end smallexample
2929 @end defmac
2930
2931 @deftypefn {Target Hook} {const enum reg_class *} TARGET_IRA_COVER_CLASSES (void)
2932 Return an array of cover classes for the Integrated Register Allocator
2933 (@acronym{IRA}).  Cover classes are a set of non-intersecting register
2934 classes covering all hard registers used for register allocation
2935 purposes.  If a move between two registers in the same cover class is
2936 possible, it should be cheaper than a load or store of the registers.
2937 The array is terminated by a @code{LIM_REG_CLASSES} element.
2938
2939 The order of cover classes in the array is important.  If two classes
2940 have the same cost of usage for a pseudo, the class occurred first in
2941 the array is chosen for the pseudo.
2942
2943 This hook is called once at compiler startup, after the command-line
2944 options have been processed. It is then re-examined by every call to
2945 @code{target_reinit}.
2946
2947 The default implementation returns @code{IRA_COVER_CLASSES}, if defined,
2948 otherwise there is no default implementation.  You must define either this
2949 macro or @code{IRA_COVER_CLASSES} in order to use the integrated register
2950 allocator with Chaitin-Briggs coloring. If the macro is not defined,
2951 the only available coloring algorithm is Chow's priority coloring.
2952 @end deftypefn
2953
2954 @defmac IRA_COVER_CLASSES
2955 See the documentation for @code{TARGET_IRA_COVER_CLASSES}.
2956 @end defmac
2957
2958 @node Old Constraints
2959 @section Obsolete Macros for Defining Constraints
2960 @cindex defining constraints, obsolete method
2961 @cindex constraints, defining, obsolete method
2962
2963 Machine-specific constraints can be defined with these macros instead
2964 of the machine description constructs described in @ref{Define
2965 Constraints}.  This mechanism is obsolete.  New ports should not use
2966 it; old ports should convert to the new mechanism.
2967
2968 @defmac CONSTRAINT_LEN (@var{char}, @var{str})
2969 For the constraint at the start of @var{str}, which starts with the letter
2970 @var{c}, return the length.  This allows you to have register class /
2971 constant / extra constraints that are longer than a single letter;
2972 you don't need to define this macro if you can do with single-letter
2973 constraints only.  The definition of this macro should use
2974 DEFAULT_CONSTRAINT_LEN for all the characters that you don't want
2975 to handle specially.
2976 There are some sanity checks in genoutput.c that check the constraint lengths
2977 for the md file, so you can also use this macro to help you while you are
2978 transitioning from a byzantine single-letter-constraint scheme: when you
2979 return a negative length for a constraint you want to re-use, genoutput
2980 will complain about every instance where it is used in the md file.
2981 @end defmac
2982
2983 @defmac REG_CLASS_FROM_LETTER (@var{char})
2984 A C expression which defines the machine-dependent operand constraint
2985 letters for register classes.  If @var{char} is such a letter, the
2986 value should be the register class corresponding to it.  Otherwise,
2987 the value should be @code{NO_REGS}.  The register letter @samp{r},
2988 corresponding to class @code{GENERAL_REGS}, will not be passed
2989 to this macro; you do not need to handle it.
2990 @end defmac
2991
2992 @defmac REG_CLASS_FROM_CONSTRAINT (@var{char}, @var{str})
2993 Like @code{REG_CLASS_FROM_LETTER}, but you also get the constraint string
2994 passed in @var{str}, so that you can use suffixes to distinguish between
2995 different variants.
2996 @end defmac
2997
2998 @defmac CONST_OK_FOR_LETTER_P (@var{value}, @var{c})
2999 A C expression that defines the machine-dependent operand constraint
3000 letters (@samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}) that specify
3001 particular ranges of integer values.  If @var{c} is one of those
3002 letters, the expression should check that @var{value}, an integer, is in
3003 the appropriate range and return 1 if so, 0 otherwise.  If @var{c} is
3004 not one of those letters, the value should be 0 regardless of
3005 @var{value}.
3006 @end defmac
3007
3008 @defmac CONST_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str})
3009 Like @code{CONST_OK_FOR_LETTER_P}, but you also get the constraint
3010 string passed in @var{str}, so that you can use suffixes to distinguish
3011 between different variants.
3012 @end defmac
3013
3014 @defmac CONST_DOUBLE_OK_FOR_LETTER_P (@var{value}, @var{c})
3015 A C expression that defines the machine-dependent operand constraint
3016 letters that specify particular ranges of @code{const_double} values
3017 (@samp{G} or @samp{H}).
3018
3019 If @var{c} is one of those letters, the expression should check that
3020 @var{value}, an RTX of code @code{const_double}, is in the appropriate
3021 range and return 1 if so, 0 otherwise.  If @var{c} is not one of those
3022 letters, the value should be 0 regardless of @var{value}.
3023
3024 @code{const_double} is used for all floating-point constants and for
3025 @code{DImode} fixed-point constants.  A given letter can accept either
3026 or both kinds of values.  It can use @code{GET_MODE} to distinguish
3027 between these kinds.
3028 @end defmac
3029
3030 @defmac CONST_DOUBLE_OK_FOR_CONSTRAINT_P (@var{value}, @var{c}, @var{str})
3031 Like @code{CONST_DOUBLE_OK_FOR_LETTER_P}, but you also get the constraint
3032 string passed in @var{str}, so that you can use suffixes to distinguish
3033 between different variants.
3034 @end defmac
3035
3036 @defmac EXTRA_CONSTRAINT (@var{value}, @var{c})
3037 A C expression that defines the optional machine-dependent constraint
3038 letters that can be used to segregate specific types of operands, usually
3039 memory references, for the target machine.  Any letter that is not
3040 elsewhere defined and not matched by @code{REG_CLASS_FROM_LETTER} /
3041 @code{REG_CLASS_FROM_CONSTRAINT}
3042 may be used.  Normally this macro will not be defined.
3043
3044 If it is required for a particular target machine, it should return 1
3045 if @var{value} corresponds to the operand type represented by the
3046 constraint letter @var{c}.  If @var{c} is not defined as an extra
3047 constraint, the value returned should be 0 regardless of @var{value}.
3048
3049 For example, on the ROMP, load instructions cannot have their output
3050 in r0 if the memory reference contains a symbolic address.  Constraint
3051 letter @samp{Q} is defined as representing a memory address that does
3052 @emph{not} contain a symbolic address.  An alternative is specified with
3053 a @samp{Q} constraint on the input and @samp{r} on the output.  The next
3054 alternative specifies @samp{m} on the input and a register class that
3055 does not include r0 on the output.
3056 @end defmac
3057
3058 @defmac EXTRA_CONSTRAINT_STR (@var{value}, @var{c}, @var{str})
3059 Like @code{EXTRA_CONSTRAINT}, but you also get the constraint string passed
3060 in @var{str}, so that you can use suffixes to distinguish between different
3061 variants.
3062 @end defmac
3063
3064 @defmac EXTRA_MEMORY_CONSTRAINT (@var{c}, @var{str})
3065 A C expression that defines the optional machine-dependent constraint
3066 letters, amongst those accepted by @code{EXTRA_CONSTRAINT}, that should
3067 be treated like memory constraints by the reload pass.
3068
3069 It should return 1 if the operand type represented by the constraint
3070 at the start of @var{str}, the first letter of which is the letter @var{c},
3071 comprises a subset of all memory references including
3072 all those whose address is simply a base register.  This allows the reload
3073 pass to reload an operand, if it does not directly correspond to the operand
3074 type of @var{c}, by copying its address into a base register.
3075
3076 For example, on the S/390, some instructions do not accept arbitrary
3077 memory references, but only those that do not make use of an index
3078 register.  The constraint letter @samp{Q} is defined via
3079 @code{EXTRA_CONSTRAINT} as representing a memory address of this type.
3080 If the letter @samp{Q} is marked as @code{EXTRA_MEMORY_CONSTRAINT},
3081 a @samp{Q} constraint can handle any memory operand, because the
3082 reload pass knows it can be reloaded by copying the memory address
3083 into a base register if required.  This is analogous to the way
3084 an @samp{o} constraint can handle any memory operand.
3085 @end defmac
3086
3087 @defmac EXTRA_ADDRESS_CONSTRAINT (@var{c}, @var{str})
3088 A C expression that defines the optional machine-dependent constraint
3089 letters, amongst those accepted by @code{EXTRA_CONSTRAINT} /
3090 @code{EXTRA_CONSTRAINT_STR}, that should
3091 be treated like address constraints by the reload pass.
3092
3093 It should return 1 if the operand type represented by the constraint
3094 at the start of @var{str}, which starts with the letter @var{c}, comprises
3095 a subset of all memory addresses including
3096 all those that consist of just a base register.  This allows the reload
3097 pass to reload an operand, if it does not directly correspond to the operand
3098 type of @var{str}, by copying it into a base register.
3099
3100 Any constraint marked as @code{EXTRA_ADDRESS_CONSTRAINT} can only
3101 be used with the @code{address_operand} predicate.  It is treated
3102 analogously to the @samp{p} constraint.
3103 @end defmac
3104
3105 @node Stack and Calling
3106 @section Stack Layout and Calling Conventions
3107 @cindex calling conventions
3108
3109 @c prevent bad page break with this line
3110 This describes the stack layout and calling conventions.
3111
3112 @menu
3113 * Frame Layout::
3114 * Exception Handling::
3115 * Stack Checking::
3116 * Frame Registers::
3117 * Elimination::
3118 * Stack Arguments::
3119 * Register Arguments::
3120 * Scalar Return::
3121 * Aggregate Return::
3122 * Caller Saves::
3123 * Function Entry::
3124 * Profiling::
3125 * Tail Calls::
3126 * Stack Smashing Protection::
3127 @end menu
3128
3129 @node Frame Layout
3130 @subsection Basic Stack Layout
3131 @cindex stack frame layout
3132 @cindex frame layout
3133
3134 @c prevent bad page break with this line
3135 Here is the basic stack layout.
3136
3137 @defmac STACK_GROWS_DOWNWARD
3138 Define this macro if pushing a word onto the stack moves the stack
3139 pointer to a smaller address.
3140
3141 When we say, ``define this macro if @dots{}'', it means that the
3142 compiler checks this macro only with @code{#ifdef} so the precise
3143 definition used does not matter.
3144 @end defmac
3145
3146 @defmac STACK_PUSH_CODE
3147 This macro defines the operation used when something is pushed
3148 on the stack.  In RTL, a push operation will be
3149 @code{(set (mem (STACK_PUSH_CODE (reg sp))) @dots{})}
3150
3151 The choices are @code{PRE_DEC}, @code{POST_DEC}, @code{PRE_INC},
3152 and @code{POST_INC}.  Which of these is correct depends on
3153 the stack direction and on whether the stack pointer points
3154 to the last item on the stack or whether it points to the
3155 space for the next item on the stack.
3156
3157 The default is @code{PRE_DEC} when @code{STACK_GROWS_DOWNWARD} is
3158 defined, which is almost always right, and @code{PRE_INC} otherwise,
3159 which is often wrong.
3160 @end defmac
3161
3162 @defmac FRAME_GROWS_DOWNWARD
3163 Define this macro to nonzero value if the addresses of local variable slots
3164 are at negative offsets from the frame pointer.
3165 @end defmac
3166
3167 @defmac ARGS_GROW_DOWNWARD
3168 Define this macro if successive arguments to a function occupy decreasing
3169 addresses on the stack.
3170 @end defmac
3171
3172 @defmac STARTING_FRAME_OFFSET
3173 Offset from the frame pointer to the first local variable slot to be allocated.
3174
3175 If @code{FRAME_GROWS_DOWNWARD}, find the next slot's offset by
3176 subtracting the first slot's length from @code{STARTING_FRAME_OFFSET}.
3177 Otherwise, it is found by adding the length of the first slot to the
3178 value @code{STARTING_FRAME_OFFSET}.
3179 @c i'm not sure if the above is still correct.. had to change it to get
3180 @c rid of an overfull.  --mew 2feb93
3181 @end defmac
3182
3183 @defmac STACK_ALIGNMENT_NEEDED
3184 Define to zero to disable final alignment of the stack during reload.
3185 The nonzero default for this macro is suitable for most ports.
3186
3187 On ports where @code{STARTING_FRAME_OFFSET} is nonzero or where there
3188 is a register save block following the local block that doesn't require
3189 alignment to @code{STACK_BOUNDARY}, it may be beneficial to disable
3190 stack alignment and do it in the backend.
3191 @end defmac
3192
3193 @defmac STACK_POINTER_OFFSET
3194 Offset from the stack pointer register to the first location at which
3195 outgoing arguments are placed.  If not specified, the default value of
3196 zero is used.  This is the proper value for most machines.
3197
3198 If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
3199 the first location at which outgoing arguments are placed.
3200 @end defmac
3201
3202 @defmac FIRST_PARM_OFFSET (@var{fundecl})
3203 Offset from the argument pointer register to the first argument's
3204 address.  On some machines it may depend on the data type of the
3205 function.
3206
3207 If @code{ARGS_GROW_DOWNWARD}, this is the offset to the location above
3208 the first argument's address.
3209 @end defmac
3210
3211 @defmac STACK_DYNAMIC_OFFSET (@var{fundecl})
3212 Offset from the stack pointer register to an item dynamically allocated
3213 on the stack, e.g., by @code{alloca}.
3214
3215 The default value for this macro is @code{STACK_POINTER_OFFSET} plus the
3216 length of the outgoing arguments.  The default is correct for most
3217 machines.  See @file{function.c} for details.
3218 @end defmac
3219
3220 @defmac INITIAL_FRAME_ADDRESS_RTX
3221 A C expression whose value is RTL representing the address of the initial
3222 stack frame. This address is passed to @code{RETURN_ADDR_RTX} and
3223 @code{DYNAMIC_CHAIN_ADDRESS}.  If you don't define this macro, a reasonable
3224 default value will be used.  Define this macro in order to make frame pointer
3225 elimination work in the presence of @code{__builtin_frame_address (count)} and
3226 @code{__builtin_return_address (count)} for @code{count} not equal to zero.
3227 @end defmac
3228
3229 @defmac DYNAMIC_CHAIN_ADDRESS (@var{frameaddr})
3230 A C expression whose value is RTL representing the address in a stack
3231 frame where the pointer to the caller's frame is stored.  Assume that
3232 @var{frameaddr} is an RTL expression for the address of the stack frame
3233 itself.
3234
3235 If you don't define this macro, the default is to return the value
3236 of @var{frameaddr}---that is, the stack frame address is also the
3237 address of the stack word that points to the previous frame.
3238 @end defmac
3239
3240 @defmac SETUP_FRAME_ADDRESSES
3241 If defined, a C expression that produces the machine-specific code to
3242 setup the stack so that arbitrary frames can be accessed.  For example,
3243 on the SPARC, we must flush all of the register windows to the stack
3244 before we can access arbitrary stack frames.  You will seldom need to
3245 define this macro.
3246 @end defmac
3247
3248 @deftypefn {Target Hook} rtx TARGET_BUILTIN_SETJMP_FRAME_VALUE (void)
3249 This target hook should return an rtx that is used to store
3250 the address of the current frame into the built in @code{setjmp} buffer.
3251 The default value, @code{virtual_stack_vars_rtx}, is correct for most
3252 machines.  One reason you may need to define this target hook is if
3253 @code{hard_frame_pointer_rtx} is the appropriate value on your machine.
3254 @end deftypefn
3255
3256 @defmac FRAME_ADDR_RTX (@var{frameaddr})
3257 A C expression whose value is RTL representing the value of the frame
3258 address for the current frame.  @var{frameaddr} is the frame pointer
3259 of the current frame.  This is used for __builtin_frame_address.
3260 You need only define this macro if the frame address is not the same
3261 as the frame pointer.  Most machines do not need to define it.
3262 @end defmac
3263
3264 @defmac RETURN_ADDR_RTX (@var{count}, @var{frameaddr})
3265 A C expression whose value is RTL representing the value of the return
3266 address for the frame @var{count} steps up from the current frame, after
3267 the prologue.  @var{frameaddr} is the frame pointer of the @var{count}
3268 frame, or the frame pointer of the @var{count} @minus{} 1 frame if
3269 @code{RETURN_ADDR_IN_PREVIOUS_FRAME} is defined.
3270
3271 The value of the expression must always be the correct address when
3272 @var{count} is zero, but may be @code{NULL_RTX} if there is no way to
3273 determine the return address of other frames.
3274 @end defmac
3275
3276 @defmac RETURN_ADDR_IN_PREVIOUS_FRAME
3277 Define this if the return address of a particular stack frame is accessed
3278 from the frame pointer of the previous stack frame.
3279 @end defmac
3280
3281 @defmac INCOMING_RETURN_ADDR_RTX
3282 A C expression whose value is RTL representing the location of the
3283 incoming return address at the beginning of any function, before the
3284 prologue.  This RTL is either a @code{REG}, indicating that the return
3285 value is saved in @samp{REG}, or a @code{MEM} representing a location in
3286 the stack.
3287
3288 You only need to define this macro if you want to support call frame
3289 debugging information like that provided by DWARF 2.
3290
3291 If this RTL is a @code{REG}, you should also define
3292 @code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}.
3293 @end defmac
3294
3295 @defmac DWARF_ALT_FRAME_RETURN_COLUMN
3296 A C expression whose value is an integer giving a DWARF 2 column
3297 number that may be used as an alternative return column.  The column
3298 must not correspond to any gcc hard register (that is, it must not
3299 be in the range of @code{DWARF_FRAME_REGNUM}).
3300
3301 This macro can be useful if @code{DWARF_FRAME_RETURN_COLUMN} is set to a
3302 general register, but an alternative column needs to be used for signal
3303 frames.  Some targets have also used different frame return columns
3304 over time.
3305 @end defmac
3306
3307 @defmac DWARF_ZERO_REG
3308 A C expression whose value is an integer giving a DWARF 2 register
3309 number that is considered to always have the value zero.  This should
3310 only be defined if the target has an architected zero register, and
3311 someone decided it was a good idea to use that register number to
3312 terminate the stack backtrace.  New ports should avoid this.
3313 @end defmac
3314
3315 @deftypefn {Target Hook} void TARGET_DWARF_HANDLE_FRAME_UNSPEC (const char *@var{label}, rtx @var{pattern}, int @var{index})
3316 This target hook allows the backend to emit frame-related insns that
3317 contain UNSPECs or UNSPEC_VOLATILEs.  The DWARF 2 call frame debugging
3318 info engine will invoke it on insns of the form
3319 @smallexample
3320 (set (reg) (unspec [@dots{}] UNSPEC_INDEX))
3321 @end smallexample
3322 and
3323 @smallexample
3324 (set (reg) (unspec_volatile [@dots{}] UNSPECV_INDEX)).
3325 @end smallexample
3326 to let the backend emit the call frame instructions.  @var{label} is
3327 the CFI label attached to the insn, @var{pattern} is the pattern of
3328 the insn and @var{index} is @code{UNSPEC_INDEX} or @code{UNSPECV_INDEX}.
3329 @end deftypefn
3330
3331 @defmac INCOMING_FRAME_SP_OFFSET
3332 A C expression whose value is an integer giving the offset, in bytes,
3333 from the value of the stack pointer register to the top of the stack
3334 frame at the beginning of any function, before the prologue.  The top of
3335 the frame is defined to be the value of the stack pointer in the
3336 previous frame, just before the call instruction.
3337
3338 You only need to define this macro if you want to support call frame
3339 debugging information like that provided by DWARF 2.
3340 @end defmac
3341
3342 @defmac ARG_POINTER_CFA_OFFSET (@var{fundecl})
3343 A C expression whose value is an integer giving the offset, in bytes,
3344 from the argument pointer to the canonical frame address (cfa).  The
3345 final value should coincide with that calculated by
3346 @code{INCOMING_FRAME_SP_OFFSET}.  Which is unfortunately not usable
3347 during virtual register instantiation.
3348
3349 The default value for this macro is
3350 @code{FIRST_PARM_OFFSET (fundecl) + crtl->args.pretend_args_size},
3351 which is correct for most machines; in general, the arguments are found
3352 immediately before the stack frame.  Note that this is not the case on
3353 some targets that save registers into the caller's frame, such as SPARC
3354 and rs6000, and so such targets need to define this macro.
3355
3356 You only need to define this macro if the default is incorrect, and you
3357 want to support call frame debugging information like that provided by
3358 DWARF 2.
3359 @end defmac
3360
3361 @defmac FRAME_POINTER_CFA_OFFSET (@var{fundecl})
3362 If defined, a C expression whose value is an integer giving the offset
3363 in bytes from the frame pointer to the canonical frame address (cfa).
3364 The final value should coincide with that calculated by
3365 @code{INCOMING_FRAME_SP_OFFSET}.
3366
3367 Normally the CFA is calculated as an offset from the argument pointer,
3368 via @code{ARG_POINTER_CFA_OFFSET}, but if the argument pointer is
3369 variable due to the ABI, this may not be possible.  If this macro is
3370 defined, it implies that the virtual register instantiation should be
3371 based on the frame pointer instead of the argument pointer.  Only one
3372 of @code{FRAME_POINTER_CFA_OFFSET} and @code{ARG_POINTER_CFA_OFFSET}
3373 should be defined.
3374 @end defmac
3375
3376 @defmac CFA_FRAME_BASE_OFFSET (@var{fundecl})
3377 If defined, a C expression whose value is an integer giving the offset
3378 in bytes from the canonical frame address (cfa) to the frame base used
3379 in DWARF 2 debug information.  The default is zero.  A different value
3380 may reduce the size of debug information on some ports.
3381 @end defmac
3382
3383 @node Exception Handling
3384 @subsection Exception Handling Support
3385 @cindex exception handling
3386
3387 @defmac EH_RETURN_DATA_REGNO (@var{N})
3388 A C expression whose value is the @var{N}th register number used for
3389 data by exception handlers, or @code{INVALID_REGNUM} if fewer than
3390 @var{N} registers are usable.
3391
3392 The exception handling library routines communicate with the exception
3393 handlers via a set of agreed upon registers.  Ideally these registers
3394 should be call-clobbered; it is possible to use call-saved registers,
3395 but may negatively impact code size.  The target must support at least
3396 2 data registers, but should define 4 if there are enough free registers.
3397
3398 You must define this macro if you want to support call frame exception
3399 handling like that provided by DWARF 2.
3400 @end defmac
3401
3402 @defmac EH_RETURN_STACKADJ_RTX
3403 A C expression whose value is RTL representing a location in which
3404 to store a stack adjustment to be applied before function return.
3405 This is used to unwind the stack to an exception handler's call frame.
3406 It will be assigned zero on code paths that return normally.
3407
3408 Typically this is a call-clobbered hard register that is otherwise
3409 untouched by the epilogue, but could also be a stack slot.
3410
3411 Do not define this macro if the stack pointer is saved and restored
3412 by the regular prolog and epilog code in the call frame itself; in
3413 this case, the exception handling library routines will update the
3414 stack location to be restored in place.  Otherwise, you must define
3415 this macro if you want to support call frame exception handling like
3416 that provided by DWARF 2.
3417 @end defmac
3418
3419 @defmac EH_RETURN_HANDLER_RTX
3420 A C expression whose value is RTL representing a location in which
3421 to store the address of an exception handler to which we should
3422 return.  It will not be assigned on code paths that return normally.
3423
3424 Typically this is the location in the call frame at which the normal
3425 return address is stored.  For targets that return by popping an
3426 address off the stack, this might be a memory address just below
3427 the @emph{target} call frame rather than inside the current call
3428 frame.  If defined, @code{EH_RETURN_STACKADJ_RTX} will have already
3429 been assigned, so it may be used to calculate the location of the
3430 target call frame.
3431
3432 Some targets have more complex requirements than storing to an
3433 address calculable during initial code generation.  In that case
3434 the @code{eh_return} instruction pattern should be used instead.
3435
3436 If you want to support call frame exception handling, you must
3437 define either this macro or the @code{eh_return} instruction pattern.
3438 @end defmac
3439
3440 @defmac RETURN_ADDR_OFFSET
3441 If defined, an integer-valued C expression for which rtl will be generated
3442 to add it to the exception handler address before it is searched in the
3443 exception handling tables, and to subtract it again from the address before
3444 using it to return to the exception handler.
3445 @end defmac
3446
3447 @defmac ASM_PREFERRED_EH_DATA_FORMAT (@var{code}, @var{global})
3448 This macro chooses the encoding of pointers embedded in the exception
3449 handling sections.  If at all possible, this should be defined such
3450 that the exception handling section will not require dynamic relocations,
3451 and so may be read-only.
3452
3453 @var{code} is 0 for data, 1 for code labels, 2 for function pointers.
3454 @var{global} is true if the symbol may be affected by dynamic relocations.
3455 The macro should return a combination of the @code{DW_EH_PE_*} defines
3456 as found in @file{dwarf2.h}.
3457
3458 If this macro is not defined, pointers will not be encoded but
3459 represented directly.
3460 @end defmac
3461
3462 @defmac ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX (@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done})
3463 This macro allows the target to emit whatever special magic is required
3464 to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}.
3465 Generic code takes care of pc-relative and indirect encodings; this must
3466 be defined if the target uses text-relative or data-relative encodings.
3467
3468 This is a C statement that branches to @var{done} if the format was
3469 handled.  @var{encoding} is the format chosen, @var{size} is the number
3470 of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF}
3471 to be emitted.
3472 @end defmac
3473
3474 @defmac MD_UNWIND_SUPPORT
3475 A string specifying a file to be #include'd in unwind-dw2.c.  The file
3476 so included typically defines @code{MD_FALLBACK_FRAME_STATE_FOR}.
3477 @end defmac
3478
3479 @defmac MD_FALLBACK_FRAME_STATE_FOR (@var{context}, @var{fs})
3480 This macro allows the target to add CPU and operating system specific
3481 code to the call-frame unwinder for use when there is no unwind data
3482 available.  The most common reason to implement this macro is to unwind
3483 through signal frames.
3484
3485 This macro is called from @code{uw_frame_state_for} in
3486 @file{unwind-dw2.c}, @file{unwind-dw2-xtensa.c} and
3487 @file{unwind-ia64.c}.  @var{context} is an @code{_Unwind_Context};
3488 @var{fs} is an @code{_Unwind_FrameState}.  Examine @code{context->ra}
3489 for the address of the code being executed and @code{context->cfa} for
3490 the stack pointer value.  If the frame can be decoded, the register
3491 save addresses should be updated in @var{fs} and the macro should
3492 evaluate to @code{_URC_NO_REASON}.  If the frame cannot be decoded,
3493 the macro should evaluate to @code{_URC_END_OF_STACK}.
3494
3495 For proper signal handling in Java this macro is accompanied by
3496 @code{MAKE_THROW_FRAME}, defined in @file{libjava/include/*-signal.h} headers.
3497 @end defmac
3498
3499 @defmac MD_HANDLE_UNWABI (@var{context}, @var{fs})
3500 This macro allows the target to add operating system specific code to the
3501 call-frame unwinder to handle the IA-64 @code{.unwabi} unwinding directive,
3502 usually used for signal or interrupt frames.
3503
3504 This macro is called from @code{uw_update_context} in @file{unwind-ia64.c}.
3505 @var{context} is an @code{_Unwind_Context};
3506 @var{fs} is an @code{_Unwind_FrameState}.  Examine @code{fs->unwabi}
3507 for the abi and context in the @code{.unwabi} directive.  If the
3508 @code{.unwabi} directive can be handled, the register save addresses should
3509 be updated in @var{fs}.
3510 @end defmac
3511
3512 @defmac TARGET_USES_WEAK_UNWIND_INFO
3513 A C expression that evaluates to true if the target requires unwind
3514 info to be given comdat linkage.  Define it to be @code{1} if comdat
3515 linkage is necessary.  The default is @code{0}.
3516 @end defmac
3517
3518 @node Stack Checking
3519 @subsection Specifying How Stack Checking is Done
3520
3521 GCC will check that stack references are within the boundaries of the
3522 stack, if the option @option{-fstack-check} is specified, in one of
3523 three ways:
3524
3525 @enumerate
3526 @item
3527 If the value of the @code{STACK_CHECK_BUILTIN} macro is nonzero, GCC
3528 will assume that you have arranged for full stack checking to be done
3529 at appropriate places in the configuration files.  GCC will not do
3530 other special processing.
3531
3532 @item
3533 If @code{STACK_CHECK_BUILTIN} is zero and the value of the
3534 @code{STACK_CHECK_STATIC_BUILTIN} macro is nonzero, GCC will assume
3535 that you have arranged for static stack checking (checking of the
3536 static stack frame of functions) to be done at appropriate places
3537 in the configuration files.  GCC will only emit code to do dynamic
3538 stack checking (checking on dynamic stack allocations) using the third
3539 approach below.
3540
3541 @item
3542 If neither of the above are true, GCC will generate code to periodically
3543 ``probe'' the stack pointer using the values of the macros defined below.
3544 @end enumerate
3545
3546 If neither STACK_CHECK_BUILTIN nor STACK_CHECK_STATIC_BUILTIN is defined,
3547 GCC will change its allocation strategy for large objects if the option
3548 @option{-fstack-check} is specified: they will always be allocated
3549 dynamically if their size exceeds @code{STACK_CHECK_MAX_VAR_SIZE} bytes.
3550
3551 @defmac STACK_CHECK_BUILTIN
3552 A nonzero value if stack checking is done by the configuration files in a
3553 machine-dependent manner.  You should define this macro if stack checking
3554 is required by the ABI of your machine or if you would like to do stack
3555 checking in some more efficient way than the generic approach.  The default
3556 value of this macro is zero.
3557 @end defmac
3558
3559 @defmac STACK_CHECK_STATIC_BUILTIN
3560 A nonzero value if static stack checking is done by the configuration files
3561 in a machine-dependent manner.  You should define this macro if you would
3562 like to do static stack checking in some more efficient way than the generic
3563 approach.  The default value of this macro is zero.
3564 @end defmac
3565
3566 @defmac STACK_CHECK_PROBE_INTERVAL_EXP
3567 An integer specifying the interval at which GCC must generate stack probe
3568 instructions, defined as 2 raised to this integer.  You will normally
3569 define this macro so that the interval be no larger than the size of
3570 the ``guard pages'' at the end of a stack area.  The default value
3571 of 12 (4096-byte interval) is suitable for most systems.
3572 @end defmac
3573
3574 @defmac STACK_CHECK_MOVING_SP
3575 An integer which is nonzero if GCC should move the stack pointer page by page
3576 when doing probes.  This can be necessary on systems where the stack pointer
3577 contains the bottom address of the memory area accessible to the executing
3578 thread at any point in time.  In this situation an alternate signal stack
3579 is required in order to be able to recover from a stack overflow.  The
3580 default value of this macro is zero.
3581 @end defmac
3582
3583 @defmac STACK_CHECK_PROTECT
3584 The number of bytes of stack needed to recover from a stack overflow, for
3585 languages where such a recovery is supported.  The default value of 75 words
3586 with the @code{setjmp}/@code{longjmp}-based exception handling mechanism and
3587 8192 bytes with other exception handling mechanisms should be adequate for
3588 most machines.
3589 @end defmac
3590
3591 The following macros are relevant only if neither STACK_CHECK_BUILTIN
3592 nor STACK_CHECK_STATIC_BUILTIN is defined; you can omit them altogether
3593 in the opposite case.
3594
3595 @defmac STACK_CHECK_MAX_FRAME_SIZE
3596 The maximum size of a stack frame, in bytes.  GCC will generate probe
3597 instructions in non-leaf functions to ensure at least this many bytes of
3598 stack are available.  If a stack frame is larger than this size, stack
3599 checking will not be reliable and GCC will issue a warning.  The
3600 default is chosen so that GCC only generates one instruction on most
3601 systems.  You should normally not change the default value of this macro.
3602 @end defmac
3603
3604 @defmac STACK_CHECK_FIXED_FRAME_SIZE
3605 GCC uses this value to generate the above warning message.  It
3606 represents the amount of fixed frame used by a function, not including
3607 space for any callee-saved registers, temporaries and user variables.
3608 You need only specify an upper bound for this amount and will normally
3609 use the default of four words.
3610 @end defmac
3611
3612 @defmac STACK_CHECK_MAX_VAR_SIZE
3613 The maximum size, in bytes, of an object that GCC will place in the
3614 fixed area of the stack frame when the user specifies
3615 @option{-fstack-check}.
3616 GCC computed the default from the values of the above macros and you will
3617 normally not need to override that default.
3618 @end defmac
3619
3620 @need 2000
3621 @node Frame Registers
3622 @subsection Registers That Address the Stack Frame
3623
3624 @c prevent bad page break with this line
3625 This discusses registers that address the stack frame.
3626
3627 @defmac STACK_POINTER_REGNUM
3628 The register number of the stack pointer register, which must also be a
3629 fixed register according to @code{FIXED_REGISTERS}.  On most machines,
3630 the hardware determines which register this is.
3631 @end defmac
3632
3633 @defmac FRAME_POINTER_REGNUM
3634 The register number of the frame pointer register, which is used to
3635 access automatic variables in the stack frame.  On some machines, the
3636 hardware determines which register this is.  On other machines, you can
3637 choose any register you wish for this purpose.
3638 @end defmac
3639
3640 @defmac HARD_FRAME_POINTER_REGNUM
3641 On some machines the offset between the frame pointer and starting
3642 offset of the automatic variables is not known until after register
3643 allocation has been done (for example, because the saved registers are
3644 between these two locations).  On those machines, define
3645 @code{FRAME_POINTER_REGNUM} the number of a special, fixed register to
3646 be used internally until the offset is known, and define
3647 @code{HARD_FRAME_POINTER_REGNUM} to be the actual hard register number
3648 used for the frame pointer.
3649
3650 You should define this macro only in the very rare circumstances when it
3651 is not possible to calculate the offset between the frame pointer and
3652 the automatic variables until after register allocation has been
3653 completed.  When this macro is defined, you must also indicate in your
3654 definition of @code{ELIMINABLE_REGS} how to eliminate
3655 @code{FRAME_POINTER_REGNUM} into either @code{HARD_FRAME_POINTER_REGNUM}
3656 or @code{STACK_POINTER_REGNUM}.
3657
3658 Do not define this macro if it would be the same as
3659 @code{FRAME_POINTER_REGNUM}.
3660 @end defmac
3661
3662 @defmac ARG_POINTER_REGNUM
3663 The register number of the arg pointer register, which is used to access
3664 the function's argument list.  On some machines, this is the same as the
3665 frame pointer register.  On some machines, the hardware determines which
3666 register this is.  On other machines, you can choose any register you
3667 wish for this purpose.  If this is not the same register as the frame
3668 pointer register, then you must mark it as a fixed register according to
3669 @code{FIXED_REGISTERS}, or arrange to be able to eliminate it
3670 (@pxref{Elimination}).
3671 @end defmac
3672
3673 @defmac RETURN_ADDRESS_POINTER_REGNUM
3674 The register number of the return address pointer register, which is used to
3675 access the current function's return address from the stack.  On some
3676 machines, the return address is not at a fixed offset from the frame
3677 pointer or stack pointer or argument pointer.  This register can be defined
3678 to point to the return address on the stack, and then be converted by
3679 @code{ELIMINABLE_REGS} into either the frame pointer or stack pointer.
3680
3681 Do not define this macro unless there is no other way to get the return
3682 address from the stack.
3683 @end defmac
3684
3685 @defmac STATIC_CHAIN_REGNUM
3686 @defmacx STATIC_CHAIN_INCOMING_REGNUM
3687 Register numbers used for passing a function's static chain pointer.  If
3688 register windows are used, the register number as seen by the called
3689 function is @code{STATIC_CHAIN_INCOMING_REGNUM}, while the register
3690 number as seen by the calling function is @code{STATIC_CHAIN_REGNUM}.  If
3691 these registers are the same, @code{STATIC_CHAIN_INCOMING_REGNUM} need
3692 not be defined.
3693
3694 The static chain register need not be a fixed register.
3695
3696 If the static chain is passed in memory, these macros should not be
3697 defined; instead, the @code{TARGET_STATIC_CHAIN} hook should be used.
3698 @end defmac
3699
3700 @deftypefn {Target Hook} rtx TARGET_STATIC_CHAIN (const_tree @var{fndecl}, bool @var{incoming_p})
3701 This hook replaces the use of @code{STATIC_CHAIN_REGNUM} et al for
3702 targets that may use different static chain locations for different
3703 nested functions.  This may be required if the target has function
3704 attributes that affect the calling conventions of the function and
3705 those calling conventions use different static chain locations.
3706
3707 The default version of this hook uses @code{STATIC_CHAIN_REGNUM} et al.
3708
3709 If the static chain is passed in memory, this hook should be used to
3710 provide rtx giving @code{mem} expressions that denote where they are stored.
3711 Often the @code{mem} expression as seen by the caller will be at an offset
3712 from the stack pointer and the @code{mem} expression as seen by the callee
3713 will be at an offset from the frame pointer.
3714 @findex stack_pointer_rtx
3715 @findex frame_pointer_rtx
3716 @findex arg_pointer_rtx
3717 The variables @code{stack_pointer_rtx}, @code{frame_pointer_rtx}, and
3718 @code{arg_pointer_rtx} will have been initialized and should be used
3719 to refer to those items.
3720 @end deftypefn
3721
3722 @defmac DWARF_FRAME_REGISTERS
3723 This macro specifies the maximum number of hard registers that can be
3724 saved in a call frame.  This is used to size data structures used in
3725 DWARF2 exception handling.
3726
3727 Prior to GCC 3.0, this macro was needed in order to establish a stable
3728 exception handling ABI in the face of adding new hard registers for ISA
3729 extensions.  In GCC 3.0 and later, the EH ABI is insulated from changes
3730 in the number of hard registers.  Nevertheless, this macro can still be
3731 used to reduce the runtime memory requirements of the exception handling
3732 routines, which can be substantial if the ISA contains a lot of
3733 registers that are not call-saved.
3734
3735 If this macro is not defined, it defaults to
3736 @code{FIRST_PSEUDO_REGISTER}.
3737 @end defmac
3738
3739 @defmac PRE_GCC3_DWARF_FRAME_REGISTERS
3740
3741 This macro is similar to @code{DWARF_FRAME_REGISTERS}, but is provided
3742 for backward compatibility in pre GCC 3.0 compiled code.
3743
3744 If this macro is not defined, it defaults to
3745 @code{DWARF_FRAME_REGISTERS}.
3746 @end defmac
3747
3748 @defmac DWARF_REG_TO_UNWIND_COLUMN (@var{regno})
3749
3750 Define this macro if the target's representation for dwarf registers
3751 is different than the internal representation for unwind column.
3752 Given a dwarf register, this macro should return the internal unwind
3753 column number to use instead.
3754
3755 See the PowerPC's SPE target for an example.
3756 @end defmac
3757
3758 @defmac DWARF_FRAME_REGNUM (@var{regno})
3759
3760 Define this macro if the target's representation for dwarf registers
3761 used in .eh_frame or .debug_frame is different from that used in other
3762 debug info sections.  Given a GCC hard register number, this macro
3763 should return the .eh_frame register number.  The default is
3764 @code{DBX_REGISTER_NUMBER (@var{regno})}.
3765
3766 @end defmac
3767
3768 @defmac DWARF2_FRAME_REG_OUT (@var{regno}, @var{for_eh})
3769
3770 Define this macro to map register numbers held in the call frame info
3771 that GCC has collected using @code{DWARF_FRAME_REGNUM} to those that
3772 should be output in .debug_frame (@code{@var{for_eh}} is zero) and
3773 .eh_frame (@code{@var{for_eh}} is nonzero).  The default is to
3774 return @code{@var{regno}}.
3775
3776 @end defmac
3777
3778 @node Elimination
3779 @subsection Eliminating Frame Pointer and Arg Pointer
3780
3781 @c prevent bad page break with this line
3782 This is about eliminating the frame pointer and arg pointer.
3783
3784 @deftypefn {Target Hook} bool TARGET_FRAME_POINTER_REQUIRED (void)
3785 This target hook should return @code{true} if a function must have and use
3786 a frame pointer.  This target hook is called in the reload pass.  If its return
3787 value is @code{true} the function will have a frame pointer.
3788
3789 This target hook can in principle examine the current function and decide
3790 according to the facts, but on most machines the constant @code{false} or the
3791 constant @code{true} suffices.  Use @code{false} when the machine allows code
3792 to be generated with no frame pointer, and doing so saves some time or space.
3793 Use @code{true} when there is no possible advantage to avoiding a frame
3794 pointer.
3795
3796 In certain cases, the compiler does not know how to produce valid code
3797 without a frame pointer.  The compiler recognizes those cases and
3798 automatically gives the function a frame pointer regardless of what
3799 @code{TARGET_FRAME_POINTER_REQUIRED} returns.  You don't need to worry about
3800 them.
3801
3802 In a function that does not require a frame pointer, the frame pointer
3803 register can be allocated for ordinary usage, unless you mark it as a
3804 fixed register.  See @code{FIXED_REGISTERS} for more information.
3805
3806 Default return value is @code{false}.
3807 @end deftypefn
3808
3809 @findex get_frame_size
3810 @defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var})
3811 A C statement to store in the variable @var{depth-var} the difference
3812 between the frame pointer and the stack pointer values immediately after
3813 the function prologue.  The value would be computed from information
3814 such as the result of @code{get_frame_size ()} and the tables of
3815 registers @code{regs_ever_live} and @code{call_used_regs}.
3816
3817 If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and
3818 need not be defined.  Otherwise, it must be defined even if
3819 @code{TARGET_FRAME_POINTER_REQUIRED} always returns true; in that
3820 case, you may set @var{depth-var} to anything.
3821 @end defmac
3822
3823 @defmac ELIMINABLE_REGS
3824 If defined, this macro specifies a table of register pairs used to
3825 eliminate unneeded registers that point into the stack frame.  If it is not
3826 defined, the only elimination attempted by the compiler is to replace
3827 references to the frame pointer with references to the stack pointer.
3828
3829 The definition of this macro is a list of structure initializations, each
3830 of which specifies an original and replacement register.
3831
3832 On some machines, the position of the argument pointer is not known until
3833 the compilation is completed.  In such a case, a separate hard register
3834 must be used for the argument pointer.  This register can be eliminated by
3835 replacing it with either the frame pointer or the argument pointer,
3836 depending on whether or not the frame pointer has been eliminated.
3837
3838 In this case, you might specify:
3839 @smallexample
3840 #define ELIMINABLE_REGS  \
3841 @{@{ARG_POINTER_REGNUM, STACK_POINTER_REGNUM@}, \
3842  @{ARG_POINTER_REGNUM, FRAME_POINTER_REGNUM@}, \
3843  @{FRAME_POINTER_REGNUM, STACK_POINTER_REGNUM@}@}
3844 @end smallexample
3845
3846 Note that the elimination of the argument pointer with the stack pointer is
3847 specified first since that is the preferred elimination.
3848 @end defmac
3849
3850 @deftypefn {Target Hook} bool TARGET_CAN_ELIMINATE (const int @var{from_reg}, const int @var{to_reg})
3851 This target hook should returns @code{true} if the compiler is allowed to
3852 try to replace register number @var{from_reg} with register number
3853 @var{to_reg}.  This target hook need only be defined if @code{ELIMINABLE_REGS}
3854 is defined, and will usually be @code{true}, since most of the cases
3855 preventing register elimination are things that the compiler already
3856 knows about.
3857
3858 Default return value is @code{true}.
3859 @end deftypefn
3860
3861 @defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var})
3862 This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}.  It
3863 specifies the initial difference between the specified pair of
3864 registers.  This macro must be defined if @code{ELIMINABLE_REGS} is
3865 defined.
3866 @end defmac
3867
3868 @node Stack Arguments
3869 @subsection Passing Function Arguments on the Stack
3870 @cindex arguments on stack
3871 @cindex stack arguments
3872
3873 The macros in this section control how arguments are passed
3874 on the stack.  See the following section for other macros that
3875 control passing certain arguments in registers.
3876
3877 @deftypefn {Target Hook} bool TARGET_PROMOTE_PROTOTYPES (const_tree @var{fntype})
3878 This target hook returns @code{true} if an argument declared in a
3879 prototype as an integral type smaller than @code{int} should actually be
3880 passed as an @code{int}.  In addition to avoiding errors in certain
3881 cases of mismatch, it also makes for better code on certain machines.
3882 The default is to not promote prototypes.
3883 @end deftypefn
3884
3885 @defmac PUSH_ARGS
3886 A C expression.  If nonzero, push insns will be used to pass
3887 outgoing arguments.
3888 If the target machine does not have a push instruction, set it to zero.
3889 That directs GCC to use an alternate strategy: to
3890 allocate the entire argument block and then store the arguments into
3891 it.  When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too.
3892 @end defmac
3893
3894 @defmac PUSH_ARGS_REVERSED
3895 A C expression.  If nonzero, function arguments will be evaluated from
3896 last to first, rather than from first to last.  If this macro is not
3897 defined, it defaults to @code{PUSH_ARGS} on targets where the stack
3898 and args grow in opposite directions, and 0 otherwise.
3899 @end defmac
3900
3901 @defmac PUSH_ROUNDING (@var{npushed})
3902 A C expression that is the number of bytes actually pushed onto the
3903 stack when an instruction attempts to push @var{npushed} bytes.
3904
3905 On some machines, the definition
3906
3907 @smallexample
3908 #define PUSH_ROUNDING(BYTES) (BYTES)
3909 @end smallexample
3910
3911 @noindent
3912 will suffice.  But on other machines, instructions that appear
3913 to push one byte actually push two bytes in an attempt to maintain
3914 alignment.  Then the definition should be
3915
3916 @smallexample
3917 #define PUSH_ROUNDING(BYTES) (((BYTES) + 1) & ~1)
3918 @end smallexample
3919 @end defmac
3920
3921 @findex current_function_outgoing_args_size
3922 @defmac ACCUMULATE_OUTGOING_ARGS
3923 A C expression.  If nonzero, the maximum amount of space required for outgoing arguments
3924 will be computed and placed into the variable
3925 @code{current_function_outgoing_args_size}.  No space will be pushed
3926 onto the stack for each call; instead, the function prologue should
3927 increase the stack frame size by this amount.
3928
3929 Setting both @code{PUSH_ARGS} and @code{ACCUMULATE_OUTGOING_ARGS}
3930 is not proper.
3931 @end defmac
3932
3933 @defmac REG_PARM_STACK_SPACE (@var{fndecl})
3934 Define this macro if functions should assume that stack space has been
3935 allocated for arguments even when their values are passed in
3936 registers.
3937
3938 The value of this macro is the size, in bytes, of the area reserved for
3939 arguments passed in registers for the function represented by @var{fndecl},
3940 which can be zero if GCC is calling a library function.
3941 The argument @var{fndecl} can be the FUNCTION_DECL, or the type itself
3942 of the function.
3943
3944 This space can be allocated by the caller, or be a part of the
3945 machine-dependent stack frame: @code{OUTGOING_REG_PARM_STACK_SPACE} says
3946 which.
3947 @end defmac
3948 @c above is overfull.  not sure what to do.  --mew 5feb93  did
3949 @c something, not sure if it looks good.  --mew 10feb93
3950
3951 @defmac OUTGOING_REG_PARM_STACK_SPACE (@var{fntype})
3952 Define this to a nonzero value if it is the responsibility of the
3953 caller to allocate the area reserved for arguments passed in registers
3954 when calling a function of @var{fntype}.  @var{fntype} may be NULL
3955 if the function called is a library function.
3956
3957 If @code{ACCUMULATE_OUTGOING_ARGS} is defined, this macro controls
3958 whether the space for these arguments counts in the value of
3959 @code{current_function_outgoing_args_size}.
3960 @end defmac
3961
3962 @defmac STACK_PARMS_IN_REG_PARM_AREA
3963 Define this macro if @code{REG_PARM_STACK_SPACE} is defined, but the
3964 stack parameters don't skip the area specified by it.
3965 @c i changed this, makes more sens and it should have taken care of the
3966 @c overfull.. not as specific, tho.  --mew 5feb93
3967
3968 Normally, when a parameter is not passed in registers, it is placed on the
3969 stack beyond the @code{REG_PARM_STACK_SPACE} area.  Defining this macro
3970 suppresses this behavior and causes the parameter to be passed on the
3971 stack in its natural location.
3972 @end defmac
3973
3974 @defmac RETURN_POPS_ARGS (@var{fundecl}, @var{funtype}, @var{stack-size})
3975 A C expression that should indicate the number of bytes of its own
3976 arguments that a function pops on returning, or 0 if the
3977 function pops no arguments and the caller must therefore pop them all
3978 after the function returns.
3979
3980 @var{fundecl} is a C variable whose value is a tree node that describes
3981 the function in question.  Normally it is a node of type
3982 @code{FUNCTION_DECL} that describes the declaration of the function.
3983 From this you can obtain the @code{DECL_ATTRIBUTES} of the function.
3984
3985 @var{funtype} is a C variable whose value is a tree node that
3986 describes the function in question.  Normally it is a node of type
3987 @code{FUNCTION_TYPE} that describes the data type of the function.
3988 From this it is possible to obtain the data types of the value and
3989 arguments (if known).
3990
3991 When a call to a library function is being considered, @var{fundecl}
3992 will contain an identifier node for the library function.  Thus, if
3993 you need to distinguish among various library functions, you can do so
3994 by their names.  Note that ``library function'' in this context means
3995 a function used to perform arithmetic, whose name is known specially
3996 in the compiler and was not mentioned in the C code being compiled.
3997
3998 @var{stack-size} is the number of bytes of arguments passed on the
3999 stack.  If a variable number of bytes is passed, it is zero, and
4000 argument popping will always be the responsibility of the calling function.
4001
4002 On the VAX, all functions always pop their arguments, so the definition
4003 of this macro is @var{stack-size}.  On the 68000, using the standard
4004 calling convention, no functions pop their arguments, so the value of
4005 the macro is always 0 in this case.  But an alternative calling
4006 convention is available in which functions that take a fixed number of
4007 arguments pop them but other functions (such as @code{printf}) pop
4008 nothing (the caller pops all).  When this convention is in use,
4009 @var{funtype} is examined to determine whether a function takes a fixed
4010 number of arguments.
4011 @end defmac
4012
4013 @defmac CALL_POPS_ARGS (@var{cum})
4014 A C expression that should indicate the number of bytes a call sequence
4015 pops off the stack.  It is added to the value of @code{RETURN_POPS_ARGS}
4016 when compiling a function call.
4017
4018 @var{cum} is the variable in which all arguments to the called function
4019 have been accumulated.
4020
4021 On certain architectures, such as the SH5, a call trampoline is used
4022 that pops certain registers off the stack, depending on the arguments
4023 that have been passed to the function.  Since this is a property of the
4024 call site, not of the called function, @code{RETURN_POPS_ARGS} is not
4025 appropriate.
4026 @end defmac
4027
4028 @node Register Arguments
4029 @subsection Passing Arguments in Registers
4030 @cindex arguments in registers
4031 @cindex registers arguments
4032
4033 This section describes the macros which let you control how various
4034 types of arguments are passed in registers or how they are arranged in
4035 the stack.
4036
4037 @defmac FUNCTION_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
4038 A C expression that controls whether a function argument is passed
4039 in a register, and which register.
4040
4041 The arguments are @var{cum}, which summarizes all the previous
4042 arguments; @var{mode}, the machine mode of the argument; @var{type},
4043 the data type of the argument as a tree node or 0 if that is not known
4044 (which happens for C support library functions); and @var{named},
4045 which is 1 for an ordinary argument and 0 for nameless arguments that
4046 correspond to @samp{@dots{}} in the called function's prototype.
4047 @var{type} can be an incomplete type if a syntax error has previously
4048 occurred.
4049
4050 The value of the expression is usually either a @code{reg} RTX for the
4051 hard register in which to pass the argument, or zero to pass the
4052 argument on the stack.
4053
4054 For machines like the VAX and 68000, where normally all arguments are
4055 pushed, zero suffices as a definition.
4056
4057 The value of the expression can also be a @code{parallel} RTX@.  This is
4058 used when an argument is passed in multiple locations.  The mode of the
4059 @code{parallel} should be the mode of the entire argument.  The
4060 @code{parallel} holds any number of @code{expr_list} pairs; each one
4061 describes where part of the argument is passed.  In each
4062 @code{expr_list} the first operand must be a @code{reg} RTX for the hard
4063 register in which to pass this part of the argument, and the mode of the
4064 register RTX indicates how large this part of the argument is.  The
4065 second operand of the @code{expr_list} is a @code{const_int} which gives
4066 the offset in bytes into the entire argument of where this part starts.
4067 As a special exception the first @code{expr_list} in the @code{parallel}
4068 RTX may have a first operand of zero.  This indicates that the entire
4069 argument is also stored on the stack.
4070
4071 The last time this macro is called, it is called with @code{MODE ==
4072 VOIDmode}, and its result is passed to the @code{call} or @code{call_value}
4073 pattern as operands 2 and 3 respectively.
4074
4075 @cindex @file{stdarg.h} and register arguments
4076 The usual way to make the ISO library @file{stdarg.h} work on a machine
4077 where some arguments are usually passed in registers, is to cause
4078 nameless arguments to be passed on the stack instead.  This is done
4079 by making @code{FUNCTION_ARG} return 0 whenever @var{named} is 0.
4080
4081 @cindex @code{TARGET_MUST_PASS_IN_STACK}, and @code{FUNCTION_ARG}
4082 @cindex @code{REG_PARM_STACK_SPACE}, and @code{FUNCTION_ARG}
4083 You may use the hook @code{targetm.calls.must_pass_in_stack}
4084 in the definition of this macro to determine if this argument is of a
4085 type that must be passed in the stack.  If @code{REG_PARM_STACK_SPACE}
4086 is not defined and @code{FUNCTION_ARG} returns nonzero for such an
4087 argument, the compiler will abort.  If @code{REG_PARM_STACK_SPACE} is
4088 defined, the argument will be computed in the stack and then loaded into
4089 a register.
4090 @end defmac
4091
4092 @deftypefn {Target Hook} bool TARGET_MUST_PASS_IN_STACK (enum machine_mode @var{mode}, const_tree @var{type})
4093 This target hook should return @code{true} if we should not pass @var{type}
4094 solely in registers.  The file @file{expr.h} defines a
4095 definition that is usually appropriate, refer to @file{expr.h} for additional
4096 documentation.
4097 @end deftypefn
4098
4099 @defmac FUNCTION_INCOMING_ARG (@var{cum}, @var{mode}, @var{type}, @var{named})
4100 Define this macro if the target machine has ``register windows'', so
4101 that the register in which a function sees an arguments is not
4102 necessarily the same as the one in which the caller passed the
4103 argument.
4104
4105 For such machines, @code{FUNCTION_ARG} computes the register in which
4106 the caller passes the value, and @code{FUNCTION_INCOMING_ARG} should
4107 be defined in a similar fashion to tell the function being called
4108 where the arguments will arrive.
4109
4110 If @code{FUNCTION_INCOMING_ARG} is not defined, @code{FUNCTION_ARG}
4111 serves both purposes.
4112 @end defmac
4113
4114 @deftypefn {Target Hook} int TARGET_ARG_PARTIAL_BYTES (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named})
4115 This target hook returns the number of bytes at the beginning of an
4116 argument that must be put in registers.  The value must be zero for
4117 arguments that are passed entirely in registers or that are entirely
4118 pushed on the stack.
4119
4120 On some machines, certain arguments must be passed partially in
4121 registers and partially in memory.  On these machines, typically the
4122 first few words of arguments are passed in registers, and the rest
4123 on the stack.  If a multi-word argument (a @code{double} or a
4124 structure) crosses that boundary, its first few words must be passed
4125 in registers and the rest must be pushed.  This macro tells the
4126 compiler when this occurs, and how many bytes should go in registers.
4127
4128 @code{FUNCTION_ARG} for these arguments should return the first
4129 register to be used by the caller for this argument; likewise
4130 @code{FUNCTION_INCOMING_ARG}, for the called function.
4131 @end deftypefn
4132
4133 @deftypefn {Target Hook} bool TARGET_PASS_BY_REFERENCE (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, tree @var{type}, bool @var{named})
4134 This target hook should return @code{true} if an argument at the
4135 position indicated by @var{cum} should be passed by reference.  This
4136 predicate is queried after target independent reasons for being
4137 passed by reference, such as @code{TREE_ADDRESSABLE (type)}.
4138
4139 If the hook returns true, a copy of that argument is made in memory and a
4140 pointer to the argument is passed instead of the argument itself.
4141 The pointer is passed in whatever way is appropriate for passing a pointer
4142 to that type.
4143 @end deftypefn
4144
4145 @deftypefn {Target Hook} bool TARGET_CALLEE_COPIES (CUMULATIVE_ARGS *@var{cum}, enum machine_mode @var{mode}, const_tree @var{type}, bool @var{named})
4146 The function argument described by the parameters to this hook is
4147 known to be passed by reference.  The hook should return true if the
4148 function argument should be copied by the callee instead of copied
4149 by the caller.
4150
4151 For any argument for which the hook returns true, if it can be
4152 determined that the argument is not modified, then a copy need
4153 not be generated.
4154
4155 The default version of this hook always returns false.
4156 @end deftypefn
4157
4158 @defmac CUMULATIVE_ARGS
4159 A C type for declaring a variable that is used as the first argument of
4160 @code{FUNCTION_ARG} and other related values.  For some target machines,
4161 the type @code{int} suffices and can hold the number of bytes of
4162 argument so far.
4163
4164 There is no need to record in @code{CUMULATIVE_ARGS} anything about the
4165 arguments that have been passed on the stack.  The compiler has other
4166 variables to keep track of that.  For target machines on which all
4167 arguments are passed on the stack, there is no need to store anything in
4168 @code{CUMULATIVE_ARGS}; however, the data structure must exist and
4169 should not be empty, so use @code{int}.
4170 @end defmac
4171
4172 @defmac OVERRIDE_ABI_FORMAT (@var{fndecl})
4173 If defined, this macro is called before generating any code for a
4174 function, but after the @var{cfun} descriptor for the function has been
4175 created.  The back end may use this macro to update @var{cfun} to
4176 reflect an ABI other than that which would normally be used by default.
4177 If the compiler is generating code for a compiler-generated function,
4178 @var{fndecl} may be @code{NULL}.
4179 @end defmac
4180
4181 @defmac INIT_CUMULATIVE_ARGS (@var{cum}, @var{fntype}, @var{libname}, @var{fndecl}, @var{n_named_args})
4182 A C statement (sans semicolon) for initializing the variable
4183 @var{cum} for the state at the beginning of the argument list.  The
4184 variable has type @code{CUMULATIVE_ARGS}.  The value of @var{fntype}
4185 is the tree node for the data type of the function which will receive
4186 the args, or 0 if the args are to a compiler support library function.
4187 For direct calls that are not libcalls, @var{fndecl} contain the
4188 declaration node of the function.  @var{fndecl} is also set when
4189 @code{INIT_CUMULATIVE_ARGS} is used to find arguments for the function
4190 being compiled.  @var{n_named_args} is set to the number of named
4191 arguments, including a structure return address if it is passed as a
4192 parameter, when making a call.  When processing incoming arguments,
4193 @var{n_named_args} is set to @minus{}1.
4194
4195 When processing a call to a compiler support library function,
4196 @var{libname} identifies which one.  It is a @code{symbol_ref} rtx which
4197 contains the name of the function, as a string.  @var{libname} is 0 when
4198 an ordinary C function call is being processed.  Thus, each time this
4199 macro is called, either @var{libname} or @var{fntype} is nonzero, but
4200 never both of them at once.
4201 @end defmac
4202
4203 @defmac INIT_CUMULATIVE_LIBCALL_ARGS (@var{cum}, @var{mode}, @var{libname})
4204 Like @code{INIT_CUMULATIVE_ARGS} but only used for outgoing libcalls,