@c Copyright (C) 1988,89,92,93,94,96,1997 Free Software Foundation, Inc.@c This is part of the GCC manual.@c For copying conditions, see the file gcc.texi.@node Target Macros@chapter Target Description Macros@cindex machine description macros@cindex target description macros@cindex macros, target description@cindex @file{tm.h} macrosIn addition to the file @file{@var{machine}.md}, a machine descriptionincludes a C header file conventionally given the name@file{@var{machine}.h}.  This header file defines numerous macrosthat convey the information about the target machine that does not fitinto the scheme of the @file{.md} file.  The file @file{tm.h} should bea link to @file{@var{machine}.h}.  The header file @file{config.h}includes @file{tm.h} and most compiler source files include@file{config.h}.@menu* Driver::              Controlling how the driver runs the compilation passes.* Run-time Target::     Defining @samp{-m} options like @samp{-m68000} and @samp{-m68020}.* Storage Layout::      Defining sizes and alignments of data.* Type Layout::         Defining sizes and properties of basic user data types.* Registers::           Naming and describing the hardware registers.* Register Classes::    Defining the classes of hardware registers.* Stack and Calling::   Defining which way the stack grows and by how much.* Varargs::		Defining the varargs macros.* Trampolines::         Code set up at run time to enter a nested function.* Library Calls::       Controlling how library routines are implicitly called.* Addressing Modes::    Defining addressing modes valid for memory operands.* Condition Code::      Defining how insns update the condition code.* Costs::               Defining relative costs of different operations.* Sections::            Dividing storage into text, data, and other sections.* PIC::			Macros for position independent code.* Assembler Format::    Defining how to write insns and pseudo-ops to output.* Debugging Info::      Defining the format of debugging output.* Cross-compilation::   Handling floating point for cross-compilers.* Misc::                Everything else.@end menu@node Driver@section Controlling the Compilation Driver, @file{gcc}@cindex driver@cindex controlling the compilation driver@c prevent bad page break with this lineYou can control the compilation driver.@table @code@findex SWITCH_TAKES_ARG@item SWITCH_TAKES_ARG (@var{char})A C expression which determines whether the option @samp{-@var{char}}takes arguments.  The value should be the number of arguments thatoption takes--zero, for many options.By default, this macro is defined as@code{DEFAULT_SWITCH_TAKES_ARG}, which handles the standard optionsproperly.  You need not define @code{SWITCH_TAKES_ARG} unless youwish to add additional options which take arguments.  Any redefinitionshould call @code{DEFAULT_SWITCH_TAKES_ARG} and then check foradditional options.@findex WORD_SWITCH_TAKES_ARG@item WORD_SWITCH_TAKES_ARG (@var{name})A C expression which determines whether the option @samp{-@var{name}}takes arguments.  The value should be the number of arguments thatoption takes--zero, for many options.  This macro rather than@code{SWITCH_TAKES_ARG} is used for multi-character option names.By default, this macro is defined as@code{DEFAULT_WORD_SWITCH_TAKES_ARG}, which handles the standard optionsproperly.  You need not define @code{WORD_SWITCH_TAKES_ARG} unless youwish to add additional options which take arguments.  Any redefinitionshould call @code{DEFAULT_WORD_SWITCH_TAKES_ARG} and then check foradditional options.@findex SWITCHES_NEED_SPACES@item SWITCHES_NEED_SPACESA string-valued C expression which enumerates the options for whichthe linker needs a space between the option and its argument.If this macro is not defined, the default value is @code{""}.@findex CPP_SPEC@item CPP_SPECA C string constant that tells the GNU CC driver program options topass to CPP.  It can also specify how to translate options yougive to GNU CC into options for GNU CC to pass to the CPP.Do not define this macro if it does not need to do anything.@findex NO_BUILTIN_SIZE_TYPE@item NO_BUILTIN_SIZE_TYPEIf this macro is defined, the preprocessor will not define the builtin macro@code{__SIZE_TYPE__}.  The macro @code{__SIZE_TYPE__} must then be definedby @code{CPP_SPEC} instead.This should be defined if @code{SIZE_TYPE} depends on target dependent flagswhich are not accessible to the preprocessor.  Otherwise, it should notbe defined.@findex NO_BUILTIN_PTRDIFF_TYPE@item NO_BUILTIN_PTRDIFF_TYPEIf this macro is defined, the preprocessor will not define the builtin macro@code{__PTRDIFF_TYPE__}.  The macro @code{__PTRDIFF_TYPE__} must then bedefined by @code{CPP_SPEC} instead.This should be defined if @code{PTRDIFF_TYPE} depends on target dependent flagswhich are not accessible to the preprocessor.  Otherwise, it should notbe defined.@findex SIGNED_CHAR_SPEC@item SIGNED_CHAR_SPECA C string constant that tells the GNU CC driver program options topass to CPP.  By default, this macro is defined to pass the option@samp{-D__CHAR_UNSIGNED__} to CPP if @code{char} will be treated as@code{unsigned char} by @code{cc1}.Do not define this macro unless you need to override the defaultdefinition.@findex CC1_SPEC@item CC1_SPECA C string constant that tells the GNU CC driver program options topass to @code{cc1}.  It can also specify how to translate options yougive to GNU CC into options for GNU CC to pass to the @code{cc1}.Do not define this macro if it does not need to do anything.@findex CC1PLUS_SPEC@item CC1PLUS_SPECA C string constant that tells the GNU CC driver program options topass to @code{cc1plus}.  It can also specify how to translate options yougive to GNU CC into options for GNU CC to pass to the @code{cc1plus}.Do not define this macro if it does not need to do anything.@findex ASM_SPEC@item ASM_SPECA C string constant that tells the GNU CC driver program options topass to the assembler.  It can also specify how to translate optionsyou give to GNU CC into options for GNU CC to pass to the assembler.See the file @file{sun3.h} for an example of this.Do not define this macro if it does not need to do anything.@findex ASM_FINAL_SPEC@item ASM_FINAL_SPECA C string constant that tells the GNU CC driver program how torun any programs which cleanup after the normal assembler.Normally, this is not needed.  See the file @file{mips.h} foran example of this.Do not define this macro if it does not need to do anything.@findex LINK_SPEC@item LINK_SPECA C string constant that tells the GNU CC driver program options topass to the linker.  It can also specify how to translate options yougive to GNU CC into options for GNU CC to pass to the linker.Do not define this macro if it does not need to do anything.@findex LIB_SPEC@item LIB_SPECAnother C string constant used much like @code{LINK_SPEC}.  The differencebetween the two is that @code{LIB_SPEC} is used at the end of thecommand given to the linker.If this macro is not defined, a default is provided thatloads the standard C library from the usual place.  See @file{gcc.c}.@findex LIBGCC_SPEC@item LIBGCC_SPECAnother C string constant that tells the GNU CC driver programhow and when to place a reference to @file{libgcc.a} into thelinker command line.  This constant is placed both before and afterthe value of @code{LIB_SPEC}.If this macro is not defined, the GNU CC driver provides a default thatpasses the string @samp{-lgcc} to the linker unless the @samp{-shared}option is specified.@findex STARTFILE_SPEC@item STARTFILE_SPECAnother C string constant used much like @code{LINK_SPEC}.  Thedifference between the two is that @code{STARTFILE_SPEC} is used atthe very beginning of the command given to the linker.If this macro is not defined, a default is provided that loads thestandard C startup file from the usual place.  See @file{gcc.c}.@findex ENDFILE_SPEC@item ENDFILE_SPECAnother C string constant used much like @code{LINK_SPEC}.  Thedifference between the two is that @code{ENDFILE_SPEC} is used atthe very end of the command given to the linker.Do not define this macro if it does not need to do anything.@findex EXTRA_SPECS@item EXTRA_SPECSDefine this macro to provide additional specifications to put in the@file{specs} file that can be used in various specifications like@code{CC1_SPEC}.The definition should be an initializer for an array of structures,containing a string constant, that defines the specification name, and astring constant that provides the specification.Do not define this macro if it does not need to do anything.@code{EXTRA_SPECS} is useful when an architecture contains severalrelated targets, which have various @code{..._SPECS} which are similarto each other, and the maintainer would like one central place to keepthese definitions.For example, the PowerPC System V.4 targets use @code{EXTRA_SPECS} todefine either @code{_CALL_SYSV} when the System V calling sequence isused or @code{_CALL_AIX} when the older AIX-based calling sequence isused.The @file{config/rs6000/rs6000.h} target file defines:@example#define EXTRA_SPECS \  @{ "cpp_sysv_default", CPP_SYSV_DEFAULT @},#define CPP_SYS_DEFAULT ""@end exampleThe @file{config/rs6000/sysv.h} target file defines:@smallexample#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"@end smallexamplewhile the @file{config/rs6000/eabiaix.h} target file defines@code{CPP_SYSV_DEFAULT} as:@smallexample#undef CPP_SYSV_DEFAULT#define CPP_SYSV_DEFAULT "-D_CALL_AIX"@end smallexample@findex LINK_LIBGCC_SPECIAL@item LINK_LIBGCC_SPECIALDefine this macro if the driver program should find the library@file{libgcc.a} itself and should not pass @samp{-L} options to thelinker.  If you do not define this macro, the driver program will passthe argument @samp{-lgcc} to tell the linker to do the search and willpass @samp{-L} options to it.@findex LINK_LIBGCC_SPECIAL_1@item LINK_LIBGCC_SPECIAL_1Define this macro if the driver program should find the library@file{libgcc.a}.  If you do not define this macro, the driver program will passthe argument @samp{-lgcc} to tell the linker to do the search.This macro is similar to @code{LINK_LIBGCC_SPECIAL}, except that it doesnot affect @samp{-L} options.@findex MULTILIB_DEFAULTS@item MULTILIB_DEFAULTSDefine this macro as a C expression for the initializer of an array ofstring to tell the driver program which options are defaults for thistarget and thus do not need to be handled specially when using@code{MULTILIB_OPTIONS}.Do not define this macro if @code{MULTILIB_OPTIONS} is not defined inthe target makefile fragment or if none of the options listed in@code{MULTILIB_OPTIONS} are set by default.@xref{Target Fragment}.@findex RELATIVE_PREFIX_NOT_LINKDIR@item RELATIVE_PREFIX_NOT_LINKDIRDefine this macro to tell @code{gcc} that it should only translatea @samp{-B} prefix into a @samp{-L} linker option if the prefixindicates an absolute file name.@findex STANDARD_EXEC_PREFIX@item STANDARD_EXEC_PREFIXDefine this macro as a C string constant if you wish to override thestandard choice of @file{/usr/local/lib/gcc-lib/} as the default prefix totry when searching for the executable files of the compiler.@findex MD_EXEC_PREFIX@item MD_EXEC_PREFIXIf defined, this macro is an additional prefix to try after@code{STANDARD_EXEC_PREFIX}.  @code{MD_EXEC_PREFIX} is not searchedwhen the @samp{-b} option is used, or the compiler is built as a crosscompiler.@findex STANDARD_STARTFILE_PREFIX@item STANDARD_STARTFILE_PREFIXDefine this macro as a C string constant if you wish to override thestandard choice of @file{/usr/local/lib/} as the default prefix totry when searching for startup files such as @file{crt0.o}.@findex MD_STARTFILE_PREFIX@item MD_STARTFILE_PREFIXIf defined, this macro supplies an additional prefix to try after thestandard prefixes.  @code{MD_EXEC_PREFIX} is not searched when the@samp{-b} option is used, or when the compiler is built as a crosscompiler.@findex MD_STARTFILE_PREFIX_1@item MD_STARTFILE_PREFIX_1If defined, this macro supplies yet another prefix to try after thestandard prefixes.  It is not searched when the @samp{-b} option isused, or when the compiler is built as a cross compiler.@findex INIT_ENVIRONMENT@item INIT_ENVIRONMENTDefine this macro as a C string constant if you wish to set environmentvariables for programs called by the driver, such as the assembler andloader.  The driver passes the value of this macro to @code{putenv} toinitialize the necessary environment variables.@findex LOCAL_INCLUDE_DIR@item LOCAL_INCLUDE_DIRDefine this macro as a C string constant if you wish to override thestandard choice of @file{/usr/local/include} as the default prefix totry when searching for local header files.  @code{LOCAL_INCLUDE_DIR}comes before @code{SYSTEM_INCLUDE_DIR} in the search order.