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