OSDN Git Service

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