-This is doc/gccint.info, produced by makeinfo version 4.5 from
-doc/gccint.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* gccint: (gccint). Internals of the GNU Compiler Collection.
-END-INFO-DIR-ENTRY
- This file documents the internals of the GNU compilers.
-
- Published by the Free Software Foundation
-59 Temple Place - Suite 330
-Boston, MA 02111-1307 USA
-
- Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "Funding Free
-Software", the Front-Cover texts being (a) (see below), and with the
-Back-Cover Texts being (b) (see below). A copy of the license is
-included in the section entitled "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.
-
-\1f
-File: gccint.info, Node: Driver, Next: Run-time Target, Prev: Target Structure, Up: Target Macros
-
-Controlling the Compilation Driver, `gcc'
-=========================================
-
- You can control the compilation driver.
-
-`SWITCH_TAKES_ARG (CHAR)'
- A C expression which determines whether the option `-CHAR' takes
- arguments. The value should be the number of arguments that
- option takes-zero, for many options.
-
- By default, this macro is defined as `DEFAULT_SWITCH_TAKES_ARG',
- which handles the standard options properly. You need not define
- `SWITCH_TAKES_ARG' unless you wish to add additional options which
- take arguments. Any redefinition should call
- `DEFAULT_SWITCH_TAKES_ARG' and then check for additional options.
-
-`WORD_SWITCH_TAKES_ARG (NAME)'
- A C expression which determines whether the option `-NAME' takes
- arguments. The value should be the number of arguments that
- option takes-zero, for many options. This macro rather than
- `SWITCH_TAKES_ARG' is used for multi-character option names.
-
- By default, this macro is defined as
- `DEFAULT_WORD_SWITCH_TAKES_ARG', which handles the standard options
- properly. You need not define `WORD_SWITCH_TAKES_ARG' unless you
- wish to add additional options which take arguments. Any
- redefinition should call `DEFAULT_WORD_SWITCH_TAKES_ARG' and then
- check for additional options.
-
-`SWITCH_CURTAILS_COMPILATION (CHAR)'
- A C expression which determines whether the option `-CHAR' stops
- compilation before the generation of an executable. The value is
- boolean, nonzero if the option does stop an executable from being
- generated, zero otherwise.
-
- By default, this macro is defined as
- `DEFAULT_SWITCH_CURTAILS_COMPILATION', which handles the standard
- options properly. You need not define
- `SWITCH_CURTAILS_COMPILATION' unless you wish to add additional
- options which affect the generation of an executable. Any
- redefinition should call `DEFAULT_SWITCH_CURTAILS_COMPILATION' and
- then check for additional options.
-
-`SWITCHES_NEED_SPACES'
- A string-valued C expression which enumerates the options for which
- the linker needs a space between the option and its argument.
-
- If this macro is not defined, the default value is `""'.
-
-`TARGET_OPTION_TRANSLATE_TABLE'
- If defined, a list of pairs of strings, the first of which is a
- potential command line target to the `gcc' driver program, and the
- second of which is a space-separated (tabs and other whitespace
- are not supported) list of options with which to replace the first
- option. The target defining this list is responsible for assuring
- that the results are valid. Replacement options may not be the
- `--opt' style, they must be the `-opt' style. It is the intention
- of this macro to provide a mechanism for substitution that affects
- the multilibs chosen, such as one option that enables many
- options, some of which select multilibs. Example nonsensical
- definition, where `-malt-abi', `-EB', and `-mspoo' cause different
- multilibs to be chosen:
-
- #define TARGET_OPTION_TRANSLATE_TABLE \
- { "-fast", "-march=fast-foo -malt-abi -I/usr/fast-foo" }, \
- { "-compat", "-EB -malign=4 -mspoo" }
-
-`CPP_SPEC'
- A C string constant that tells the GCC driver program options to
- pass to CPP. It can also specify how to translate options you
- give to GCC into options for GCC to pass to the CPP.
-
- Do not define this macro if it does not need to do anything.
-
-`CPLUSPLUS_CPP_SPEC'
- This macro is just like `CPP_SPEC', but is used for C++, rather
- than C. If you do not define this macro, then the value of
- `CPP_SPEC' (if any) will be used instead.
-
-`NO_BUILTIN_SIZE_TYPE'
- If this macro is defined, the preprocessor will not define the
- built-in macro `__SIZE_TYPE__'. The macro `__SIZE_TYPE__' must
- then be defined by `CPP_SPEC' instead.
-
- This should be defined if `SIZE_TYPE' depends on target dependent
- flags which are not accessible to the preprocessor. Otherwise, it
- should not be defined.
-
-`NO_BUILTIN_PTRDIFF_TYPE'
- If this macro is defined, the preprocessor will not define the
- built-in macro `__PTRDIFF_TYPE__'. The macro `__PTRDIFF_TYPE__'
- must then be defined by `CPP_SPEC' instead.
-
- This should be defined if `PTRDIFF_TYPE' depends on target
- dependent flags which are not accessible to the preprocessor.
- Otherwise, it should not be defined.
-
-`NO_BUILTIN_WCHAR_TYPE'
- If this macro is defined, the preprocessor will not define the
- built-in macro `__WCHAR_TYPE__'. The macro `__WCHAR_TYPE__' must
- then be defined by `CPP_SPEC' instead.
-
- This should be defined if `WCHAR_TYPE' depends on target dependent
- flags which are not accessible to the preprocessor. Otherwise, it
- should not be defined.
-
-`NO_BUILTIN_WINT_TYPE'
- If this macro is defined, the preprocessor will not define the
- built-in macro `__WINT_TYPE__'. The macro `__WINT_TYPE__' must
- then be defined by `CPP_SPEC' instead.
-
- This should be defined if `WINT_TYPE' depends on target dependent
- flags which are not accessible to the preprocessor. Otherwise, it
- should not be defined.
-
-`CC1_SPEC'
- A C string constant that tells the GCC driver program options to
- pass to `cc1', `cc1plus', `f771', and the other language front
- ends. It can also specify how to translate options you give to
- GCC into options for GCC to pass to front ends.
-
- Do not define this macro if it does not need to do anything.
-
-`CC1PLUS_SPEC'
- A C string constant that tells the GCC driver program options to
- pass to `cc1plus'. It can also specify how to translate options
- you give to GCC into options for GCC to pass to the `cc1plus'.
-
- Do not define this macro if it does not need to do anything. Note
- that everything defined in CC1_SPEC is already passed to `cc1plus'
- so there is no need to duplicate the contents of CC1_SPEC in
- CC1PLUS_SPEC.
-
-`ASM_SPEC'
- A C string constant that tells the GCC driver program options to
- pass to the assembler. It can also specify how to translate
- options you give to GCC into options for GCC to pass to the
- assembler. See the file `sun3.h' for an example of this.
-
- Do not define this macro if it does not need to do anything.
-
-`ASM_FINAL_SPEC'
- A C string constant that tells the GCC driver program how to run
- any programs which cleanup after the normal assembler. Normally,
- this is not needed. See the file `mips.h' for an example of this.
-
- Do not define this macro if it does not need to do anything.
-
-`LINK_SPEC'
- A C string constant that tells the GCC driver program options to
- pass to the linker. It can also specify how to translate options
- you give to GCC into options for GCC to pass to the linker.
-
- Do not define this macro if it does not need to do anything.
-
-`LIB_SPEC'
- Another C string constant used much like `LINK_SPEC'. The
- difference between the two is that `LIB_SPEC' is used at the end
- of the command given to the linker.
-
- If this macro is not defined, a default is provided that loads the
- standard C library from the usual place. See `gcc.c'.
-
-`LIBGCC_SPEC'
- Another C string constant that tells the GCC driver program how
- and when to place a reference to `libgcc.a' into the linker
- command line. This constant is placed both before and after the
- value of `LIB_SPEC'.
-
- If this macro is not defined, the GCC driver provides a default
- that passes the string `-lgcc' to the linker.
-
-`STARTFILE_SPEC'
- Another C string constant used much like `LINK_SPEC'. The
- difference between the two is that `STARTFILE_SPEC' is used at the
- very beginning of the command given to the linker.
-
- If this macro is not defined, a default is provided that loads the
- standard C startup file from the usual place. See `gcc.c'.
-
-`ENDFILE_SPEC'
- Another C string constant used much like `LINK_SPEC'. The
- difference between the two is that `ENDFILE_SPEC' is used at the
- very end of the command given to the linker.
-
- Do not define this macro if it does not need to do anything.
-
-`THREAD_MODEL_SPEC'
- GCC `-v' will print the thread model GCC was configured to use.
- However, this doesn't work on platforms that are multilibbed on
- thread models, such as AIX 4.3. On such platforms, define
- `THREAD_MODEL_SPEC' such that it evaluates to a string without
- blanks that names one of the recognized thread models. `%*', the
- default value of this macro, will expand to the value of
- `thread_file' set in `config.gcc'.
-
-`EXTRA_SPECS'
- Define this macro to provide additional specifications to put in
- the `specs' file that can be used in various specifications like
- `CC1_SPEC'.
-
- The definition should be an initializer for an array of structures,
- containing a string constant, that defines the specification name,
- and a string constant that provides the specification.
-
- Do not define this macro if it does not need to do anything.
-
- `EXTRA_SPECS' is useful when an architecture contains several
- related targets, which have various `..._SPECS' which are similar
- to each other, and the maintainer would like one central place to
- keep these definitions.
-
- For example, the PowerPC System V.4 targets use `EXTRA_SPECS' to
- define either `_CALL_SYSV' when the System V calling sequence is
- used or `_CALL_AIX' when the older AIX-based calling sequence is
- used.
-
- The `config/rs6000/rs6000.h' target file defines:
-
- #define EXTRA_SPECS \
- { "cpp_sysv_default", CPP_SYSV_DEFAULT },
-
- #define CPP_SYS_DEFAULT ""
-
- The `config/rs6000/sysv.h' target file defines:
- #undef CPP_SPEC
- #define CPP_SPEC \
- "%{posix: -D_POSIX_SOURCE } \
- %{mcall-sysv: -D_CALL_SYSV } %{mcall-aix: -D_CALL_AIX } \
- %{!mcall-sysv: %{!mcall-aix: %(cpp_sysv_default) }} \
- %{msoft-float: -D_SOFT_FLOAT} %{mcpu=403: -D_SOFT_FLOAT}"
-
- #undef CPP_SYSV_DEFAULT
- #define CPP_SYSV_DEFAULT "-D_CALL_SYSV"
-
- while the `config/rs6000/eabiaix.h' target file defines
- `CPP_SYSV_DEFAULT' as:
-
- #undef CPP_SYSV_DEFAULT
- #define CPP_SYSV_DEFAULT "-D_CALL_AIX"
-
-`LINK_LIBGCC_SPECIAL'
- Define this macro if the driver program should find the library
- `libgcc.a' itself and should not pass `-L' options to the linker.
- If you do not define this macro, the driver program will pass the
- argument `-lgcc' to tell the linker to do the search and will pass
- `-L' options to it.
-
-`LINK_LIBGCC_SPECIAL_1'
- Define this macro if the driver program should find the library
- `libgcc.a'. If you do not define this macro, the driver program
- will pass the argument `-lgcc' to tell the linker to do the search.
- This macro is similar to `LINK_LIBGCC_SPECIAL', except that it does
- not affect `-L' options.
-
-`LINK_GCC_C_SEQUENCE_SPEC'
- The sequence in which libgcc and libc are specified to the linker.
- By default this is `%G %L %G'.
-
-`LINK_COMMAND_SPEC'
- A C string constant giving the complete command line need to
- execute the linker. When you do this, you will need to update
- your port each time a change is made to the link command line
- within `gcc.c'. Therefore, define this macro only if you need to
- completely redefine the command line for invoking the linker and
- there is no other way to accomplish the effect you need.
- Overriding this macro may be avoidable by overriding
- `LINK_GCC_C_SEQUENCE_SPEC' instead.
-
-`LINK_ELIMINATE_DUPLICATE_LDIRECTORIES'
- A nonzero value causes `collect2' to remove duplicate
- `-LDIRECTORY' search directories from linking commands. Do not
- give it a nonzero value if removing duplicate search directories
- changes the linker's semantics.
-
-`MULTILIB_DEFAULTS'
- Define this macro as a C expression for the initializer of an
- array of string to tell the driver program which options are
- defaults for this target and thus do not need to be handled
- specially when using `MULTILIB_OPTIONS'.
-
- Do not define this macro if `MULTILIB_OPTIONS' is not defined in
- the target makefile fragment or if none of the options listed in
- `MULTILIB_OPTIONS' are set by default. *Note Target Fragment::.
-
-`RELATIVE_PREFIX_NOT_LINKDIR'
- Define this macro to tell `gcc' that it should only translate a
- `-B' prefix into a `-L' linker option if the prefix indicates an
- absolute file name.
-
-`STANDARD_EXEC_PREFIX'
- Define this macro as a C string constant if you wish to override
- the standard choice of `/usr/local/lib/gcc-lib/' as the default
- prefix to try when searching for the executable files of the
- compiler.
-
-`MD_EXEC_PREFIX'
- If defined, this macro is an additional prefix to try after
- `STANDARD_EXEC_PREFIX'. `MD_EXEC_PREFIX' is not searched when the
- `-b' option is used, or the compiler is built as a cross compiler.
- If you define `MD_EXEC_PREFIX', then be sure to add it to the
- list of directories used to find the assembler in `configure.in'.
-
-`STANDARD_STARTFILE_PREFIX'
- Define this macro as a C string constant if you wish to override
- the standard choice of `/usr/local/lib/' as the default prefix to
- try when searching for startup files such as `crt0.o'.
-
-`MD_STARTFILE_PREFIX'
- If defined, this macro supplies an additional prefix to try after
- the standard prefixes. `MD_EXEC_PREFIX' is not searched when the
- `-b' option is used, or when the compiler is built as a cross
- compiler.
-
-`MD_STARTFILE_PREFIX_1'
- If defined, this macro supplies yet another prefix to try after the
- standard prefixes. It is not searched when the `-b' option is
- used, or when the compiler is built as a cross compiler.
-
-`INIT_ENVIRONMENT'
- Define this macro as a C string constant if you wish to set
- environment variables for programs called by the driver, such as
- the assembler and loader. The driver passes the value of this
- macro to `putenv' to initialize the necessary environment
- variables.
-
-`LOCAL_INCLUDE_DIR'
- Define this macro as a C string constant if you wish to override
- the standard choice of `/usr/local/include' as the default prefix
- to try when searching for local header files. `LOCAL_INCLUDE_DIR'
- comes before `SYSTEM_INCLUDE_DIR' in the search order.
-
- Cross compilers do not search either `/usr/local/include' or its
- replacement.
-
-`MODIFY_TARGET_NAME'
- Define this macro if you with to define command-line switches that
- modify the default target name
-
- For each switch, you can include a string to be appended to the
- first part of the configuration name or a string to be deleted
- from the configuration name, if present. The definition should be
- an initializer for an array of structures. Each array element
- should have three elements: the switch name (a string constant,
- including the initial dash), one of the enumeration codes `ADD' or
- `DELETE' to indicate whether the string should be inserted or
- deleted, and the string to be inserted or deleted (a string
- constant).
-
- For example, on a machine where `64' at the end of the
- configuration name denotes a 64-bit target and you want the `-32'
- and `-64' switches to select between 32- and 64-bit targets, you
- would code
-
- #define MODIFY_TARGET_NAME \
- { { "-32", DELETE, "64"}, \
- {"-64", ADD, "64"}}
-
-`SYSTEM_INCLUDE_DIR'
- Define this macro as a C string constant if you wish to specify a
- system-specific directory to search for header files before the
- standard directory. `SYSTEM_INCLUDE_DIR' comes before
- `STANDARD_INCLUDE_DIR' in the search order.
-
- Cross compilers do not use this macro and do not search the
- directory specified.
-
-`STANDARD_INCLUDE_DIR'
- Define this macro as a C string constant if you wish to override
- the standard choice of `/usr/include' as the default prefix to try
- when searching for header files.
-
- Cross compilers do not use this macro and do not search either
- `/usr/include' or its replacement.
-
-`STANDARD_INCLUDE_COMPONENT'
- The "component" corresponding to `STANDARD_INCLUDE_DIR'. See
- `INCLUDE_DEFAULTS', below, for the description of components. If
- you do not define this macro, no component is used.
-
-`INCLUDE_DEFAULTS'
- Define this macro if you wish to override the entire default
- search path for include files. For a native compiler, the default
- search path usually consists of `GCC_INCLUDE_DIR',
- `LOCAL_INCLUDE_DIR', `SYSTEM_INCLUDE_DIR',
- `GPLUSPLUS_INCLUDE_DIR', and `STANDARD_INCLUDE_DIR'. In addition,
- `GPLUSPLUS_INCLUDE_DIR' and `GCC_INCLUDE_DIR' are defined
- automatically by `Makefile', and specify private search areas for
- GCC. The directory `GPLUSPLUS_INCLUDE_DIR' is used only for C++
- programs.
-
- The definition should be an initializer for an array of structures.
- Each array element should have four elements: the directory name (a
- string constant), the component name (also a string constant), a
- flag for C++-only directories, and a flag showing that the
- includes in the directory don't need to be wrapped in `extern `C''
- when compiling C++. Mark the end of the array with a null element.
-
- The component name denotes what GNU package the include file is
- part of, if any, in all upper-case letters. For example, it might
- be `GCC' or `BINUTILS'. If the package is part of a
- vendor-supplied operating system, code the component name as `0'.
-
- For example, here is the definition used for VAX/VMS:
-
- #define INCLUDE_DEFAULTS \
- { \
- { "GNU_GXX_INCLUDE:", "G++", 1, 1}, \
- { "GNU_CC_INCLUDE:", "GCC", 0, 0}, \
- { "SYS$SYSROOT:[SYSLIB.]", 0, 0, 0}, \
- { ".", 0, 0, 0}, \
- { 0, 0, 0, 0} \
- }
-
- Here is the order of prefixes tried for exec files:
-
- 1. Any prefixes specified by the user with `-B'.
-
- 2. The environment variable `GCC_EXEC_PREFIX', if any.
-
- 3. The directories specified by the environment variable
- `COMPILER_PATH'.
-
- 4. The macro `STANDARD_EXEC_PREFIX'.
-
- 5. `/usr/lib/gcc/'.
-
- 6. The macro `MD_EXEC_PREFIX', if any.
-
- Here is the order of prefixes tried for startfiles:
-
- 1. Any prefixes specified by the user with `-B'.
-
- 2. The environment variable `GCC_EXEC_PREFIX', if any.
-
- 3. The directories specified by the environment variable
- `LIBRARY_PATH' (or port-specific name; native only, cross
- compilers do not use this).
-
- 4. The macro `STANDARD_EXEC_PREFIX'.
-
- 5. `/usr/lib/gcc/'.
-
- 6. The macro `MD_EXEC_PREFIX', if any.
-
- 7. The macro `MD_STARTFILE_PREFIX', if any.
-
- 8. The macro `STANDARD_STARTFILE_PREFIX'.
-
- 9. `/lib/'.
-
- 10. `/usr/lib/'.
-
-\1f
-File: gccint.info, Node: Run-time Target, Next: Per-Function Data, Prev: Driver, Up: Target Macros
-
-Run-time Target Specification
-=============================
-
- Here are run-time target specifications.
-
-`CPP_PREDEFINES'
- Define this to be a string constant containing `-D' options to
- define the predefined macros that identify this machine and system.
- These macros will be predefined unless the `-ansi' option (or a
- `-std' option for strict ISO C conformance) is specified.
-
- In addition, a parallel set of macros are predefined, whose names
- are made by appending `__' at the beginning and at the end. These
- `__' macros are permitted by the ISO standard, so they are
- predefined regardless of whether `-ansi' or a `-std' option is
- specified.
-
- For example, on the Sun, one can use the following value:
-
- "-Dmc68000 -Dsun -Dunix"
-
- The result is to define the macros `__mc68000__', `__sun__' and
- `__unix__' unconditionally, and the macros `mc68000', `sun' and
- `unix' provided `-ansi' is not specified.
-
-`extern int target_flags;'
- This declaration should be present.
-
-`TARGET_...'
- This series of macros is to allow compiler command arguments to
- enable or disable the use of optional features of the target
- machine. For example, one machine description serves both the
- 68000 and the 68020; a command argument tells the compiler whether
- it should use 68020-only instructions or not. This command
- argument works by means of a macro `TARGET_68020' that tests a bit
- in `target_flags'.
-
- Define a macro `TARGET_FEATURENAME' for each such option. Its
- definition should test a bit in `target_flags'. It is recommended
- that a helper macro `TARGET_MASK_FEATURENAME' is defined for each
- bit-value to test, and used in `TARGET_FEATURENAME' and
- `TARGET_SWITCHES'. For example:
-
- #define TARGET_MASK_68020 1
- #define TARGET_68020 (target_flags & TARGET_MASK_68020)
-
- One place where these macros are used is in the
- condition-expressions of instruction patterns. Note how
- `TARGET_68020' appears frequently in the 68000 machine description
- file, `m68k.md'. Another place they are used is in the
- definitions of the other macros in the `MACHINE.h' file.
-
-`TARGET_SWITCHES'
- This macro defines names of command options to set and clear bits
- in `target_flags'. Its definition is an initializer with a
- subgrouping for each command option.
-
- Each subgrouping contains a string constant, that defines the
- option name, a number, which contains the bits to set in
- `target_flags', and a second string which is the description
- displayed by `--help'. If the number is negative then the bits
- specified by the number are cleared instead of being set. If the
- description string is present but empty, then no help information
- will be displayed for that option, but it will not count as an
- undocumented option. The actual option name is made by appending
- `-m' to the specified name. Non-empty description strings should
- be marked with `N_(...)' for `xgettext'. Please do not mark empty
- strings because the empty string is reserved by GNU gettext.
- `gettext("")' returns the header entry of the message catalog with
- meta information, not the empty string.
-
- In addition to the description for `--help', more detailed
- documentation for each option should be added to `invoke.texi'.
-
- One of the subgroupings should have a null string. The number in
- this grouping is the default value for `target_flags'. Any target
- options act starting with that value.
-
- Here is an example which defines `-m68000' and `-m68020' with
- opposite meanings, and picks the latter as the default:
-
- #define TARGET_SWITCHES \
- { { "68020", TARGET_MASK_68020, "" }, \
- { "68000", -TARGET_MASK_68020, \
- N_("Compile for the 68000") }, \
- { "", TARGET_MASK_68020, "" }}
-
-`TARGET_OPTIONS'
- This macro is similar to `TARGET_SWITCHES' but defines names of
- command options that have values. Its definition is an
- initializer with a subgrouping for each command option.
-
- Each subgrouping contains a string constant, that defines the
- fixed part of the option name, the address of a variable, and a
- description string. Non-empty description strings should be
- marked with `N_(...)' for `xgettext'. Please do not mark empty
- strings because the empty string is reserved by GNU gettext.
- `gettext("")' returns the header entry of the message catalog with
- meta information, not the empty string.
-
- The variable, type `char *', is set to the variable part of the
- given option if the fixed part matches. The actual option name is
- made by appending `-m' to the specified name. Again, each option
- should also be documented in `invoke.texi'.
-
- Here is an example which defines `-mshort-data-NUMBER'. If the
- given option is `-mshort-data-512', the variable `m88k_short_data'
- will be set to the string `"512"'.
-
- extern char *m88k_short_data;
- #define TARGET_OPTIONS \
- { { "short-data-", &m88k_short_data, \
- N_("Specify the size of the short data section") } }
-
-`TARGET_VERSION'
- This macro is a C statement to print on `stderr' a string
- describing the particular machine description choice. Every
- machine description should define `TARGET_VERSION'. For example:
-
- #ifdef MOTOROLA
- #define TARGET_VERSION \
- fprintf (stderr, " (68k, Motorola syntax)");
- #else
- #define TARGET_VERSION \
- fprintf (stderr, " (68k, MIT syntax)");
- #endif
-
-`OVERRIDE_OPTIONS'
- Sometimes certain combinations of command options do not make
- sense on a particular target machine. You can define a macro
- `OVERRIDE_OPTIONS' to take account of this. This macro, if
- defined, is executed once just after all the command options have
- been parsed.
-
- Don't use this macro to turn on various extra optimizations for
- `-O'. That is what `OPTIMIZATION_OPTIONS' is for.
-
-`OPTIMIZATION_OPTIONS (LEVEL, SIZE)'
- Some machines may desire to change what optimizations are
- performed for various optimization levels. This macro, if
- defined, is executed once just after the optimization level is
- determined and before the remainder of the command options have
- been parsed. Values set in this macro are used as the default
- values for the other command line options.
-
- LEVEL is the optimization level specified; 2 if `-O2' is
- specified, 1 if `-O' is specified, and 0 if neither is specified.
-
- SIZE is nonzero if `-Os' is specified and zero otherwise.
-
- You should not use this macro to change options that are not
- machine-specific. These should uniformly selected by the same
- optimization level on all supported machines. Use this macro to
- enable machine-specific optimizations.
-
- *Do not examine `write_symbols' in this macro!* The debugging
- options are not supposed to alter the generated code.
-
-`CAN_DEBUG_WITHOUT_FP'
- Define this macro if debugging can be performed even without a
- frame pointer. If this macro is defined, GCC will turn on the
- `-fomit-frame-pointer' option whenever `-O' is specified.
-
-\1f
-File: gccint.info, Node: Per-Function Data, Next: Storage Layout, Prev: Run-time Target, Up: Target Macros
-
-Defining data structures for per-function information.
-======================================================
-
- If the target needs to store information on a per-function basis, GCC
-provides a macro and a couple of variables to allow this. Note, just
-using statics to store the information is a bad idea, since GCC supports
-nested functions, so you can be halfway through encoding one function
-when another one comes along.
-
- GCC defines a data structure called `struct function' which contains
-all of the data specific to an individual function. This structure
-contains a field called `machine' whose type is `struct
-machine_function *', which can be used by targets to point to their own
-specific data.
-
- If a target needs per-function specific data it should define the
-type `struct machine_function' and also the macro `INIT_EXPANDERS'.
-This macro should be used to initialize some or all of the function
-pointers `init_machine_status', `free_machine_status' and
-`mark_machine_status'. These pointers are explained below.
-
- One typical use of per-function, target specific data is to create an
-RTX to hold the register containing the function's return address. This
-RTX can then be used to implement the `__builtin_return_address'
-function, for level 0.
-
- Note--earlier implementations of GCC used a single data area to hold
-all of the per-function information. Thus when processing of a nested
-function began the old per-function data had to be pushed onto a stack,
-and when the processing was finished, it had to be popped off the
-stack. GCC used to provide function pointers called
-`save_machine_status' and `restore_machine_status' to handle the saving
-and restoring of the target specific information. Since the single
-data area approach is no longer used, these pointers are no longer
-supported.
-
- The macro and function pointers are described below.
-
-`INIT_EXPANDERS'
- Macro called to initialize any target specific information. This
- macro is called once per function, before generation of any RTL
- has begun. The intention of this macro is to allow the
- initialization of the function pointers below.
-
-`init_machine_status'
- This is a `void (*)(struct function *)' function pointer. If this
- pointer is non-`NULL' it will be called once per function, before
- function compilation starts, in order to allow the target to
- perform any target specific initialization of the `struct
- function' structure. It is intended that this would be used to
- initialize the `machine' of that structure.
-
-`free_machine_status'
- This is a `void (*)(struct function *)' function pointer. If this
- pointer is non-`NULL' it will be called once per function, after
- the function has been compiled, in order to allow any memory
- allocated during the `init_machine_status' function call to be
- freed.
-
-`mark_machine_status'
- This is a `void (*)(struct function *)' function pointer. If this
- pointer is non-`NULL' it will be called once per function in order
- to mark any data items in the `struct machine_function' structure
- which need garbage collection.
-
-
-\1f
-File: gccint.info, Node: Storage Layout, Next: Type Layout, Prev: Per-Function Data, Up: Target Macros
-
-Storage Layout
-==============
-
- Note that the definitions of the macros in this table which are
-sizes or alignments measured in bits do not need to be constant. They
-can be C expressions that refer to static variables, such as the
-`target_flags'. *Note Run-time Target::.
-
-`BITS_BIG_ENDIAN'
- Define this macro to have the value 1 if the most significant bit
- in a byte has the lowest number; otherwise define it to have the
- value zero. This means that bit-field instructions count from the
- most significant bit. If the machine has no bit-field
- instructions, then this must still be defined, but it doesn't
- matter which value it is defined to. This macro need not be a
- constant.
-
- This macro does not affect the way structure fields are packed into
- bytes or words; that is controlled by `BYTES_BIG_ENDIAN'.
-
-`BYTES_BIG_ENDIAN'
- Define this macro to have the value 1 if the most significant byte
- in a word has the lowest number. This macro need not be a
- constant.
-
-`WORDS_BIG_ENDIAN'
- Define this macro to have the value 1 if, in a multiword object,
- the most significant word has the lowest number. This applies to
- both memory locations and registers; GCC fundamentally assumes
- that the order of words in memory is the same as the order in
- registers. This macro need not be a constant.
-
-`LIBGCC2_WORDS_BIG_ENDIAN'
- Define this macro if `WORDS_BIG_ENDIAN' is not constant. This
- must be a constant value with the same meaning as
- `WORDS_BIG_ENDIAN', which will be used only when compiling
- `libgcc2.c'. Typically the value will be set based on
- preprocessor defines.
-
-`FLOAT_WORDS_BIG_ENDIAN'
- Define this macro to have the value 1 if `DFmode', `XFmode' or
- `TFmode' floating point numbers are stored in memory with the word
- containing the sign bit at the lowest address; otherwise define it
- to have the value 0. This macro need not be a constant.
-
- You need not define this macro if the ordering is the same as for
- multi-word integers.
-
-`BITS_PER_UNIT'
- Define this macro to be the number of bits in an addressable
- storage unit (byte); normally 8.
-
-`BITS_PER_WORD'
- Number of bits in a word; normally 32.
-
-`MAX_BITS_PER_WORD'
- Maximum number of bits in a word. If this is undefined, the
- default is `BITS_PER_WORD'. Otherwise, it is the constant value
- that is the largest value that `BITS_PER_WORD' can have at
- run-time.
-
-`UNITS_PER_WORD'
- Number of storage units in a word; normally 4.
-
-`MIN_UNITS_PER_WORD'
- Minimum number of units in a word. If this is undefined, the
- default is `UNITS_PER_WORD'. Otherwise, it is the constant value
- that is the smallest value that `UNITS_PER_WORD' can have at
- run-time.
-
-`POINTER_SIZE'
- Width of a pointer, in bits. You must specify a value no wider
- than the width of `Pmode'. If it is not equal to the width of
- `Pmode', you must define `POINTERS_EXTEND_UNSIGNED'.
-
-`POINTERS_EXTEND_UNSIGNED'
- A C expression whose value is greater than zero if pointers that
- need to be extended from being `POINTER_SIZE' bits wide to `Pmode'
- are to be zero-extended and zero if they are to be sign-extended.
- If the value is less then zero then there must be an "ptr_extend"
- instruction that extends a pointer from `POINTER_SIZE' to `Pmode'.
-
- You need not define this macro if the `POINTER_SIZE' is equal to
- the width of `Pmode'.
-
-`PROMOTE_MODE (M, UNSIGNEDP, TYPE)'
- A macro to update M and UNSIGNEDP when an object whose type is
- TYPE and which has the specified mode and signedness is to be
- stored in a register. This macro is only called when TYPE is a
- scalar type.
-
- On most RISC machines, which only have operations that operate on
- a full register, define this macro to set M to `word_mode' if M is
- an integer mode narrower than `BITS_PER_WORD'. In most cases,
- only integer modes should be widened because wider-precision
- floating-point operations are usually more expensive than their
- narrower counterparts.
-
- For most machines, the macro definition does not change UNSIGNEDP.
- However, some machines, have instructions that preferentially
- handle either signed or unsigned quantities of certain modes. For
- example, on the DEC Alpha, 32-bit loads from memory and 32-bit add
- instructions sign-extend the result to 64 bits. On such machines,
- set UNSIGNEDP according to which kind of extension is more
- efficient.
-
- Do not define this macro if it would never modify M.
-
-`PROMOTE_FUNCTION_ARGS'
- Define this macro if the promotion described by `PROMOTE_MODE'
- should also be done for outgoing function arguments.
-
-`PROMOTE_FUNCTION_RETURN'
- Define this macro if the promotion described by `PROMOTE_MODE'
- should also be done for the return value of functions.
-
- If this macro is defined, `FUNCTION_VALUE' must perform the same
- promotions done by `PROMOTE_MODE'.
-
-`PROMOTE_FOR_CALL_ONLY'
- Define this macro if the promotion described by `PROMOTE_MODE'
- should _only_ be performed for outgoing function arguments or
- function return values, as specified by `PROMOTE_FUNCTION_ARGS'
- and `PROMOTE_FUNCTION_RETURN', respectively.
-
-`PARM_BOUNDARY'
- Normal alignment required for function parameters on the stack, in
- bits. All stack parameters receive at least this much alignment
- regardless of data type. On most machines, this is the same as the
- size of an integer.
-
-`STACK_BOUNDARY'
- Define this macro to the minimum alignment enforced by hardware
- for the stack pointer on this machine. The definition is a C
- expression for the desired alignment (measured in bits). This
- value is used as a default if `PREFERRED_STACK_BOUNDARY' is not
- defined. On most machines, this should be the same as
- `PARM_BOUNDARY'.
-
-`PREFERRED_STACK_BOUNDARY'
- Define this macro if you wish to preserve a certain alignment for
- the stack pointer, greater than what the hardware enforces. The
- definition is a C expression for the desired alignment (measured
- in bits). This macro must evaluate to a value equal to or larger
- than `STACK_BOUNDARY'.
-
-`FORCE_PREFERRED_STACK_BOUNDARY_IN_MAIN'
- A C expression that evaluates true if `PREFERRED_STACK_BOUNDARY' is
- not guaranteed by the runtime and we should emit code to align the
- stack at the beginning of `main'.
-
- If `PUSH_ROUNDING' is not defined, the stack will always be aligned
- to the specified boundary. If `PUSH_ROUNDING' is defined and
- specifies a less strict alignment than `PREFERRED_STACK_BOUNDARY',
- the stack may be momentarily unaligned while pushing arguments.
-
-`FUNCTION_BOUNDARY'
- Alignment required for a function entry point, in bits.
-
-`BIGGEST_ALIGNMENT'
- Biggest alignment that any data type can require on this machine,
- in bits.
-
-`MINIMUM_ATOMIC_ALIGNMENT'
- If defined, the smallest alignment, in bits, that can be given to
- an object that can be referenced in one operation, without
- disturbing any nearby object. Normally, this is `BITS_PER_UNIT',
- but may be larger on machines that don't have byte or half-word
- store operations.
-
-`BIGGEST_FIELD_ALIGNMENT'
- Biggest alignment that any structure or union field can require on
- this machine, in bits. If defined, this overrides
- `BIGGEST_ALIGNMENT' for structure and union fields only, unless
- the field alignment has been set by the `__attribute__ ((aligned
- (N)))' construct.
-
-`ADJUST_FIELD_ALIGN (FIELD, COMPUTED)'
- An expression for the alignment of a structure field FIELD if the
- alignment computed in the usual way (including applying of
- `BIGGEST_ALIGNMENT' and `BIGGEST_FIELD_ALIGNMENT' to the
- alignment) is COMPUTED. It overrides alignment only if the field
- alignment has not been set by the `__attribute__ ((aligned (N)))'
- construct.
-
-`MAX_OFILE_ALIGNMENT'
- Biggest alignment supported by the object file format of this
- machine. Use this macro to limit the alignment which can be
- specified using the `__attribute__ ((aligned (N)))' construct. If
- not defined, the default value is `BIGGEST_ALIGNMENT'.
-
-`DATA_ALIGNMENT (TYPE, BASIC-ALIGN)'
- If defined, a C expression to compute the alignment for a variable
- in the static store. TYPE is the data type, and BASIC-ALIGN is
- the alignment that the object would ordinarily have. The value of
- this macro is used instead of that alignment to align the object.
-
- If this macro is not defined, then BASIC-ALIGN is used.
-
- One use of this macro is to increase alignment of medium-size data
- to make it all fit in fewer cache lines. Another is to cause
- character arrays to be word-aligned so that `strcpy' calls that
- copy constants to character arrays can be done inline.
-
-`CONSTANT_ALIGNMENT (CONSTANT, BASIC-ALIGN)'
- If defined, a C expression to compute the alignment given to a
- constant that is being placed in memory. CONSTANT is the constant
- and BASIC-ALIGN is the alignment that the object would ordinarily
- have. The value of this macro is used instead of that alignment to
- align the object.
-
- If this macro is not defined, then BASIC-ALIGN is used.
-
- The typical use of this macro is to increase alignment for string
- constants to be word aligned so that `strcpy' calls that copy
- constants can be done inline.
-
-`LOCAL_ALIGNMENT (TYPE, BASIC-ALIGN)'
- If defined, a C expression to compute the alignment for a variable
- in the local store. TYPE is the data type, and BASIC-ALIGN is the
- alignment that the object would ordinarily have. The value of this
- macro is used instead of that alignment to align the object.
-
- If this macro is not defined, then BASIC-ALIGN is used.
-
- One use of this macro is to increase alignment of medium-size data
- to make it all fit in fewer cache lines.
-
-`EMPTY_FIELD_BOUNDARY'
- Alignment in bits to be given to a structure bit-field that
- follows an empty field such as `int : 0;'.
-
- Note that `PCC_BITFIELD_TYPE_MATTERS' also affects the alignment
- that results from an empty field.
-
-`STRUCTURE_SIZE_BOUNDARY'
- Number of bits which any structure or union's size must be a
- multiple of. Each structure or union's size is rounded up to a
- multiple of this.
-
- If you do not define this macro, the default is the same as
- `BITS_PER_UNIT'.
-
-`STRICT_ALIGNMENT'
- Define this macro to be the value 1 if instructions will fail to
- work if given data not on the nominal alignment. If instructions
- will merely go slower in that case, define this macro as 0.
-
-`PCC_BITFIELD_TYPE_MATTERS'
- Define this if you wish to imitate the way many other C compilers
- handle alignment of bit-fields and the structures that contain
- them.
-
- The behavior is that the type written for a bit-field (`int',
- `short', or other integer type) imposes an alignment for the
- entire structure, as if the structure really did contain an
- ordinary field of that type. In addition, the bit-field is placed
- within the structure so that it would fit within such a field, not
- crossing a boundary for it.
-
- Thus, on most machines, a bit-field whose type is written as `int'
- would not cross a four-byte boundary, and would force four-byte
- alignment for the whole structure. (The alignment used may not be
- four bytes; it is controlled by the other alignment parameters.)
-
- If the macro is defined, its definition should be a C expression;
- a nonzero value for the expression enables this behavior.
-
- Note that if this macro is not defined, or its value is zero, some
- bit-fields may cross more than one alignment boundary. The
- compiler can support such references if there are `insv', `extv',
- and `extzv' insns that can directly reference memory.
-
- The other known way of making bit-fields work is to define
- `STRUCTURE_SIZE_BOUNDARY' as large as `BIGGEST_ALIGNMENT'. Then
- every structure can be accessed with fullwords.
-
- Unless the machine has bit-field instructions or you define
- `STRUCTURE_SIZE_BOUNDARY' that way, you must define
- `PCC_BITFIELD_TYPE_MATTERS' to have a nonzero value.
-
- If your aim is to make GCC use the same conventions for laying out
- bit-fields as are used by another compiler, here is how to
- investigate what the other compiler does. Compile and run this
- program:
-
- struct foo1
- {
- char x;
- char :0;
- char y;
- };
-
- struct foo2
- {
- char x;
- int :0;
- char y;
- };
-
- main ()
- {
- printf ("Size of foo1 is %d\n",
- sizeof (struct foo1));
- printf ("Size of foo2 is %d\n",
- sizeof (struct foo2));
- exit (0);
- }
-
- If this prints 2 and 5, then the compiler's behavior is what you
- would get from `PCC_BITFIELD_TYPE_MATTERS'.
-
-`BITFIELD_NBYTES_LIMITED'
- Like `PCC_BITFIELD_TYPE_MATTERS' except that its effect is limited
- to aligning a bit-field within the structure.
-
-`MEMBER_TYPE_FORCES_BLK (FIELD)'
- Return 1 if a structure or array containing FIELD should be
- accessed using `BLKMODE'.
-
- Normally, this is not needed. See the file `c4x.h' for an example
- of how to use this macro to prevent a structure having a floating
- point field from being accessed in an integer mode.
-
-`ROUND_TYPE_SIZE (TYPE, COMPUTED, SPECIFIED)'
- Define this macro as an expression for the overall size of a type
- (given by TYPE as a tree node) when the size computed in the usual
- way is COMPUTED and the alignment is SPECIFIED.
-
- The default is to round COMPUTED up to a multiple of SPECIFIED.
-
-`ROUND_TYPE_SIZE_UNIT (TYPE, COMPUTED, SPECIFIED)'
- Similar to `ROUND_TYPE_SIZE', but sizes and alignments are
- specified in units (bytes). If you define `ROUND_TYPE_SIZE', you
- must also define this macro and they must be defined consistently
- with each other.
-
-`ROUND_TYPE_ALIGN (TYPE, COMPUTED, SPECIFIED)'
- Define this macro as an expression for the alignment of a type
- (given by TYPE as a tree node) if the alignment computed in the
- usual way is COMPUTED and the alignment explicitly specified was
- SPECIFIED.
-
- The default is to use SPECIFIED if it is larger; otherwise, use
- the smaller of COMPUTED and `BIGGEST_ALIGNMENT'
-
-`MAX_FIXED_MODE_SIZE'
- An integer expression for the size in bits of the largest integer
- machine mode that should actually be used. All integer machine
- modes of this size or smaller can be used for structures and
- unions with the appropriate sizes. If this macro is undefined,
- `GET_MODE_BITSIZE (DImode)' is assumed.
-
-`VECTOR_MODE_SUPPORTED_P(MODE)'
- Define this macro to be nonzero if the port is prepared to handle
- insns involving vector mode MODE. At the very least, it must have
- move patterns for this mode.
-
-`STACK_SAVEAREA_MODE (SAVE_LEVEL)'
- If defined, an expression of type `enum machine_mode' that
- specifies the mode of the save area operand of a
- `save_stack_LEVEL' named pattern (*note Standard Names::).
- SAVE_LEVEL is one of `SAVE_BLOCK', `SAVE_FUNCTION', or
- `SAVE_NONLOCAL' and selects which of the three named patterns is
- having its mode specified.
-
- You need not define this macro if it always returns `Pmode'. You
- would most commonly define this macro if the `save_stack_LEVEL'
- patterns need to support both a 32- and a 64-bit mode.
-
-`STACK_SIZE_MODE'
- If defined, an expression of type `enum machine_mode' that
- specifies the mode of the size increment operand of an
- `allocate_stack' named pattern (*note Standard Names::).
-
- You need not define this macro if it always returns `word_mode'.
- You would most commonly define this macro if the `allocate_stack'
- pattern needs to support both a 32- and a 64-bit mode.
-
-`CHECK_FLOAT_VALUE (MODE, VALUE, OVERFLOW)'
- A C statement to validate the value VALUE (of type `double') for
- mode MODE. This means that you check whether VALUE fits within
- the possible range of values for mode MODE on this target machine.
- The mode MODE is always a mode of class `MODE_FLOAT'. OVERFLOW
- is nonzero if the value is already known to be out of range.
-
- If VALUE is not valid or if OVERFLOW is nonzero, you should set
- OVERFLOW to 1 and then assign some valid value to VALUE. Allowing
- an invalid value to go through the compiler can produce incorrect
- assembler code which may even cause Unix assemblers to crash.
-
- This macro need not be defined if there is no work for it to do.
-
-`TARGET_FLOAT_FORMAT'
- A code distinguishing the floating point format of the target
- machine. There are five defined values:
-
- `IEEE_FLOAT_FORMAT'
- This code indicates IEEE floating point. It is the default;
- there is no need to define this macro when the format is IEEE.
-
- `VAX_FLOAT_FORMAT'
- This code indicates the "D float" format used on the VAX.
-
- `IBM_FLOAT_FORMAT'
- This code indicates the format used on the IBM System/370.
-
- `C4X_FLOAT_FORMAT'
- This code indicates the format used on the TMS320C3x/C4x.
-
- `UNKNOWN_FLOAT_FORMAT'
- This code indicates any other format.
-
- The value of this macro is compared with `HOST_FLOAT_FORMAT', which
- is defined by the `configure' script, to determine whether the
- target machine has the same format as the host machine. If any
- other formats are actually in use on supported machines, new codes
- should be defined for them.
-
- The ordering of the component words of floating point values
- stored in memory is controlled by `FLOAT_WORDS_BIG_ENDIAN'.
-
-
- - Target Hook: bool TARGET_MS_BITFIELD_LAYOUT_P (tree RECORD_TYPE)
- This target hook returns `true' if bit-fields in the given
- RECORD_TYPE are to be laid out following the rules of Microsoft
- Visual C/C++, namely: (i) a bit-field won't share the same storage
- unit with the previous bit-field if their underlying types have
- different sizes, and the bit-field will be aligned to the highest
- alignment of the underlying types of itself and of the previous
- bit-field; (ii) a zero-sized bit-field will affect the alignment of
- the whole enclosing structure, even if it is unnamed; except that
- (iii) a zero-sized bit-field will be disregarded unless it follows
- another bit-field of non-zero size. If this hook returns `true',
- other macros that control bit-field layout are ignored.
-