This is gccint.info, produced by makeinfo version 7.1 from gccint.texi. Copyright © 1988-2024 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.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "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. INFO-DIR-SECTION Software development 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. Copyright © 1988-2024 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.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "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.  File: gccint.info, Node: Sections, Next: PIC, Prev: Scheduling, Up: Target Macros 18.18 Dividing the Output into Sections (Texts, Data, ...) ========================================================== An object file is divided into sections containing different types of data. In the most common case, there are three sections: the “text section”, which holds instructions and read-only data; the “data section”, which holds initialized writable data; and the “bss section”, which holds uninitialized data. Some systems have other kinds of sections. ‘varasm.cc’ provides several well-known sections, such as ‘text_section’, ‘data_section’ and ‘bss_section’. The normal way of controlling a ‘FOO_section’ variable is to define the associated ‘FOO_SECTION_ASM_OP’ macro, as described below. The macros are only read once, when ‘varasm.cc’ initializes itself, so their values must be run-time constants. They may however depend on command-line flags. _Note:_ Some run-time files, such ‘crtstuff.c’, also make use of the ‘FOO_SECTION_ASM_OP’ macros, and expect them to be string literals. Some assemblers require a different string to be written every time a section is selected. If your assembler falls into this category, you should define the ‘TARGET_ASM_INIT_SECTIONS’ hook and use ‘get_unnamed_section’ to set up the sections. You must always create a ‘text_section’, either by defining ‘TEXT_SECTION_ASM_OP’ or by initializing ‘text_section’ in ‘TARGET_ASM_INIT_SECTIONS’. The same is true of ‘data_section’ and ‘DATA_SECTION_ASM_OP’. If you do not create a distinct ‘readonly_data_section’, the default is to reuse ‘text_section’. All the other ‘varasm.cc’ sections are optional, and are null if the target does not provide them. -- Macro: TEXT_SECTION_ASM_OP A C expression whose value is a string, including spacing, containing the assembler operation that should precede instructions and read-only data. Normally ‘"\t.text"’ is right. -- Macro: HOT_TEXT_SECTION_NAME If defined, a C string constant for the name of the section containing most frequently executed functions of the program. If not defined, GCC will provide a default definition if the target supports named sections. -- Macro: UNLIKELY_EXECUTED_TEXT_SECTION_NAME If defined, a C string constant for the name of the section containing unlikely executed functions in the program. -- Macro: DATA_SECTION_ASM_OP A C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as writable initialized data. Normally ‘"\t.data"’ is right. -- Macro: SDATA_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as initialized, writable small data. -- Macro: READONLY_DATA_SECTION_ASM_OP A C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as read-only initialized data. -- Macro: BSS_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as uninitialized global data. If not defined, and ‘ASM_OUTPUT_ALIGNED_BSS’ not defined, uninitialized global data will be output in the data section if ‘-fno-common’ is passed, otherwise ‘ASM_OUTPUT_COMMON’ will be used. -- Macro: SBSS_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as uninitialized, writable small data. -- Macro: TLS_COMMON_ASM_OP If defined, a C expression whose value is a string containing the assembler operation to identify the following data as thread-local common data. The default is ‘".tls_common"’. -- Macro: TLS_SECTION_ASM_FLAG If defined, a C expression whose value is a character constant containing the flag used to mark a section as a TLS section. The default is ‘'T'’. -- Macro: INIT_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as initialization code. If not defined, GCC will assume such a section does not exist. This section has no corresponding ‘init_section’ variable; it is used entirely in runtime code. -- Macro: FINI_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as finalization code. If not defined, GCC will assume such a section does not exist. This section has no corresponding ‘fini_section’ variable; it is used entirely in runtime code. -- Macro: INIT_ARRAY_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as part of the ‘.init_array’ (or equivalent) section. If not defined, GCC will assume such a section does not exist. Do not define both this macro and ‘INIT_SECTION_ASM_OP’. -- Macro: FINI_ARRAY_SECTION_ASM_OP If defined, a C expression whose value is a string, including spacing, containing the assembler operation to identify the following data as part of the ‘.fini_array’ (or equivalent) section. If not defined, GCC will assume such a section does not exist. Do not define both this macro and ‘FINI_SECTION_ASM_OP’. -- Macro: MACH_DEP_SECTION_ASM_FLAG If defined, a C expression whose value is a character constant containing the flag used to mark a machine-dependent section. This corresponds to the ‘SECTION_MACH_DEP’ section flag. -- Macro: CRT_CALL_STATIC_FUNCTION (SECTION_OP, FUNCTION) If defined, an ASM statement that switches to a different section via SECTION_OP, calls FUNCTION, and switches back to the text section. This is used in ‘crtstuff.c’ if ‘INIT_SECTION_ASM_OP’ or ‘FINI_SECTION_ASM_OP’ to calls to initialization and finalization functions from the init and fini sections. By default, this macro uses a simple function call. Some ports need hand-crafted assembly code to avoid dependencies on registers initialized in the function prologue or to ensure that constant pools don't end up too far way in the text section. -- Macro: TARGET_LIBGCC_SDATA_SECTION If defined, a string which names the section into which small variables defined in crtstuff and libgcc should go. This is useful when the target has options for optimizing access to small data, and you want the crtstuff and libgcc routines to be conservative in what they expect of your application yet liberal in what your application expects. For example, for targets with a ‘.sdata’ section (like MIPS), you could compile crtstuff with ‘-G 0’ so that it doesn't require small data support from your application, but use this macro to put small data into ‘.sdata’ so that your application can access these variables whether it uses small data or not. -- Macro: FORCE_CODE_SECTION_ALIGN If defined, an ASM statement that aligns a code section to some arbitrary boundary. This is used to force all fragments of the ‘.init’ and ‘.fini’ sections to have to same alignment and thus prevent the linker from having to add any padding. -- Macro: JUMP_TABLES_IN_TEXT_SECTION Define this macro to be an expression with a nonzero value if jump tables (for ‘tablejump’ insns) should be output in the text section, along with the assembler instructions. Otherwise, the readonly data section is used. This macro is irrelevant if there is no separate readonly data section. -- Target Hook: void TARGET_ASM_INIT_SECTIONS (void) Define this hook if you need to do something special to set up the ‘varasm.cc’ sections, or if your target has some special sections of its own that you need to create. GCC calls this hook after processing the command line, but before writing any assembly code, and before calling any of the section-returning hooks described below. -- Target Hook: int TARGET_ASM_RELOC_RW_MASK (void) Return a mask describing how relocations should be treated when selecting sections. Bit 1 should be set if global relocations should be placed in a read-write section; bit 0 should be set if local relocations should be placed in a read-write section. The default version of this function returns 3 when ‘-fpic’ is in effect, and 0 otherwise. The hook is typically redefined when the target cannot support (some kinds of) dynamic relocations in read-only sections even in executables. -- Target Hook: bool TARGET_ASM_GENERATE_PIC_ADDR_DIFF_VEC (void) Return true to generate ADDR_DIF_VEC table or false to generate ADDR_VEC table for jumps in case of -fPIC. The default version of this function returns true if flag_pic equals true and false otherwise -- Target Hook: section * TARGET_ASM_SELECT_SECTION (tree EXP, int RELOC, unsigned HOST_WIDE_INT ALIGN) Return the section into which EXP should be placed. You can assume that EXP is either a ‘VAR_DECL’ node or a constant of some sort. RELOC indicates whether the initial value of EXP requires link-time relocations. Bit 0 is set when variable contains local relocations only, while bit 1 is set for global relocations. ALIGN is the constant alignment in bits. The default version of this function takes care of putting read-only variables in ‘readonly_data_section’. See also USE_SELECT_SECTION_FOR_FUNCTIONS. -- Macro: USE_SELECT_SECTION_FOR_FUNCTIONS Define this macro if you wish TARGET_ASM_SELECT_SECTION to be called for ‘FUNCTION_DECL’s as well as for variables and constants. In the case of a ‘FUNCTION_DECL’, RELOC will be zero if the function has been determined to be likely to be called, and nonzero if it is unlikely to be called. -- Target Hook: void TARGET_ASM_UNIQUE_SECTION (tree DECL, int RELOC) Build up a unique section name, expressed as a ‘STRING_CST’ node, and assign it to ‘DECL_SECTION_NAME (DECL)’. As with ‘TARGET_ASM_SELECT_SECTION’, RELOC indicates whether the initial value of EXP requires link-time relocations. The default version of this function appends the symbol name to the ELF section name that would normally be used for the symbol. For example, the function ‘foo’ would be placed in ‘.text.foo’. Whatever the actual target object format, this is often good enough. -- Target Hook: section * TARGET_ASM_FUNCTION_RODATA_SECTION (tree DECL, bool RELOCATABLE) Return the readonly data or reloc readonly data section associated with ‘DECL_SECTION_NAME (DECL)’. RELOCATABLE selects the latter over the former. The default version of this function selects ‘.gnu.linkonce.r.name’ if the function's section is ‘.gnu.linkonce.t.name’, ‘.rodata.name’ or ‘.data.rel.ro.name’ if function is in ‘.text.name’, and the normal readonly-data or reloc readonly data section otherwise. -- Target Hook: const char * TARGET_ASM_MERGEABLE_RODATA_PREFIX Usually, the compiler uses the prefix ‘".rodata"’ to construct section names for mergeable constant data. Define this macro to override the string if a different section name should be used. -- Target Hook: section * TARGET_ASM_TM_CLONE_TABLE_SECTION (void) Return the section that should be used for transactional memory clone tables. -- Target Hook: section * TARGET_ASM_SELECT_RTX_SECTION (machine_mode MODE, rtx X, unsigned HOST_WIDE_INT ALIGN) Return the section into which a constant X, of mode MODE, should be placed. You can assume that X is some kind of constant in RTL. The argument MODE is redundant except in the case of a ‘const_int’ rtx. ALIGN is the constant alignment in bits. The default version of this function takes care of putting symbolic constants in ‘flag_pic’ mode in ‘data_section’ and everything else in ‘readonly_data_section’. -- Target Hook: tree TARGET_MANGLE_DECL_ASSEMBLER_NAME (tree DECL, tree ID) Define this hook if you need to postprocess the assembler name generated by target-independent code. The ID provided to this hook will be the computed name (e.g., the macro ‘DECL_NAME’ of the DECL in C, or the mangled name of the DECL in C++). The return value of the hook is an ‘IDENTIFIER_NODE’ for the appropriate mangled name on your target system. The default implementation of this hook just returns the ID provided. -- Target Hook: void TARGET_ENCODE_SECTION_INFO (tree DECL, rtx RTL, int NEW_DECL_P) Define this hook if references to a symbol or a constant must be treated differently depending on something about the variable or function named by the symbol (such as what section it is in). The hook is executed immediately after rtl has been created for DECL, which may be a variable or function declaration or an entry in the constant pool. In either case, RTL is the rtl in question. Do _not_ use ‘DECL_RTL (DECL)’ in this hook; that field may not have been initialized yet. In the case of a constant, it is safe to assume that the rtl is a ‘mem’ whose address is a ‘symbol_ref’. Most decls will also have this form, but that is not guaranteed. Global register variables, for instance, will have a ‘reg’ for their rtl. (Normally the right thing to do with such unusual rtl is leave it alone.) The NEW_DECL_P argument will be true if this is the first time that ‘TARGET_ENCODE_SECTION_INFO’ has been invoked on this decl. It will be false for subsequent invocations, which will happen for duplicate declarations. Whether or not anything must be done for the duplicate declaration depends on whether the hook examines ‘DECL_ATTRIBUTES’. NEW_DECL_P is always true when the hook is called for a constant. The usual thing for this hook to do is to record flags in the ‘symbol_ref’, using ‘SYMBOL_REF_FLAG’ or ‘SYMBOL_REF_FLAGS’. Historically, the name string was modified if it was necessary to encode more than one bit of information, but this practice is now discouraged; use ‘SYMBOL_REF_FLAGS’. The default definition of this hook, ‘default_encode_section_info’ in ‘varasm.cc’, sets a number of commonly-useful bits in ‘SYMBOL_REF_FLAGS’. Check whether the default does what you need before overriding it. -- Target Hook: const char * TARGET_STRIP_NAME_ENCODING (const char *NAME) Decode NAME and return the real name part, sans the characters that ‘TARGET_ENCODE_SECTION_INFO’ may have added. -- Target Hook: bool TARGET_IN_SMALL_DATA_P (const_tree EXP) Returns true if EXP should be placed into a "small data" section. The default version of this hook always returns false. -- Target Hook: bool TARGET_HAVE_SRODATA_SECTION Contains the value true if the target places read-only "small data" into a separate section. The default value is false. -- Target Hook: bool TARGET_PROFILE_BEFORE_PROLOGUE (void) It returns true if target wants profile code emitted before prologue. The default version of this hook use the target macro ‘PROFILE_BEFORE_PROLOGUE’. -- Target Hook: bool TARGET_BINDS_LOCAL_P (const_tree EXP) Returns true if EXP names an object for which name resolution rules must resolve to the current "module" (dynamic shared library or executable image). The default version of this hook implements the name resolution rules for ELF, which has a looser model of global name binding than other currently supported object file formats. -- Target Hook: bool TARGET_HAVE_TLS Contains the value true if the target supports thread-local storage. The default value is false.  File: gccint.info, Node: PIC, Next: Assembler Format, Prev: Sections, Up: Target Macros 18.19 Position Independent Code =============================== This section describes macros that help implement generation of position independent code. Simply defining these macros is not enough to generate valid PIC; you must also add support to the hook ‘TARGET_LEGITIMATE_ADDRESS_P’ and to the macro ‘PRINT_OPERAND_ADDRESS’, as well as ‘LEGITIMIZE_ADDRESS’. You must modify the definition of ‘movsi’ to do something appropriate when the source operand contains a symbolic address. You may also need to alter the handling of switch statements so that they use relative addresses. -- Macro: PIC_OFFSET_TABLE_REGNUM The register number of the register used to address a table of static data addresses in memory. In some cases this register is defined by a processor's "application binary interface" (ABI). When this macro is defined, RTL is generated for this register once, as with the stack pointer and frame pointer registers. If this macro is not defined, it is up to the machine-dependent files to allocate such a register (if necessary). Note that this register must be fixed when in use (e.g. when ‘flag_pic’ is true). -- Macro: PIC_OFFSET_TABLE_REG_CALL_CLOBBERED A C expression that is nonzero if the register defined by ‘PIC_OFFSET_TABLE_REGNUM’ is clobbered by calls. If not defined, the default is zero. Do not define this macro if ‘PIC_OFFSET_TABLE_REGNUM’ is not defined. -- Macro: LEGITIMATE_PIC_OPERAND_P (X) A C expression that is nonzero if X is a legitimate immediate operand on the target machine when generating position independent code. You can assume that X satisfies ‘CONSTANT_P’, so you need not check this. You can also assume FLAG_PIC is true, so you need not check it either. You need not define this macro if all constants (including ‘SYMBOL_REF’) can be immediate operands when generating position independent code.  File: gccint.info, Node: Assembler Format, Next: Debugging Info, Prev: PIC, Up: Target Macros 18.20 Defining the Output Assembler Language ============================================ This section describes macros whose principal purpose is to describe how to write instructions in assembler language--rather than what the instructions do. * Menu: * File Framework:: Structural information for the assembler file. * Data Output:: Output of constants (numbers, strings, addresses). * Uninitialized Data:: Output of uninitialized variables. * Label Output:: Output and generation of labels. * Initialization:: General principles of initialization and termination routines. * Macros for Initialization:: Specific macros that control the handling of initialization and termination routines. * Instruction Output:: Output of actual instructions. * Dispatch Tables:: Output of jump tables. * Exception Region Output:: Output of exception region code. * Alignment Output:: Pseudo ops for alignment and skipping data.  File: gccint.info, Node: File Framework, Next: Data Output, Up: Assembler Format 18.20.1 The Overall Framework of an Assembler File -------------------------------------------------- This describes the overall framework of an assembly file. -- Target Hook: void TARGET_ASM_FILE_START (void) Output to ‘asm_out_file’ any text which the assembler expects to find at the beginning of a file. The default behavior is controlled by two flags, documented below. Unless your target's assembler is quite unusual, if you override the default, you should call ‘default_file_start’ at some point in your target hook. This lets other target files rely on these variables. -- Target Hook: bool TARGET_ASM_FILE_START_APP_OFF If this flag is true, the text of the macro ‘ASM_APP_OFF’ will be printed as the very first line in the assembly file, unless ‘-fverbose-asm’ is in effect. (If that macro has been defined to the empty string, this variable has no effect.) With the normal definition of ‘ASM_APP_OFF’, the effect is to notify the GNU assembler that it need not bother stripping comments or extra whitespace from its input. This allows it to work a bit faster. The default is false. You should not set it to true unless you have verified that your port does not generate any extra whitespace or comments that will cause GAS to issue errors in NO_APP mode. -- Target Hook: bool TARGET_ASM_FILE_START_FILE_DIRECTIVE If this flag is true, ‘output_file_directive’ will be called for the primary source file, immediately after printing ‘ASM_APP_OFF’ (if that is enabled). Most ELF assemblers expect this to be done. The default is false. -- Target Hook: void TARGET_ASM_FILE_END (void) Output to ‘asm_out_file’ any text which the assembler expects to find at the end of a file. The default is to output nothing. -- Function: void file_end_indicate_exec_stack () Some systems use a common convention, the ‘.note.GNU-stack’ special section, to indicate whether or not an object file relies on the stack being executable. If your system uses this convention, you should define ‘TARGET_ASM_FILE_END’ to this function. If you need to do other things in that hook, have your hook function call this function. -- Target Hook: void TARGET_ASM_LTO_START (void) Output to ‘asm_out_file’ any text which the assembler expects to find at the start of an LTO section. The default is to output nothing. -- Target Hook: void TARGET_ASM_LTO_END (void) Output to ‘asm_out_file’ any text which the assembler expects to find at the end of an LTO section. The default is to output nothing. -- Target Hook: void TARGET_ASM_CODE_END (void) Output to ‘asm_out_file’ any text which is needed before emitting unwind info and debug info at the end of a file. Some targets emit here PIC setup thunks that cannot be emitted at the end of file, because they couldn't have unwind info then. The default is to output nothing. -- Macro: ASM_COMMENT_START A C string constant describing how to begin a comment in the target assembler language. The compiler assumes that the comment will end at the end of the line. -- Macro: ASM_APP_ON A C string constant for text to be output before each ‘asm’ statement or group of consecutive ones. Normally this is ‘"#APP"’, which is a comment that has no effect on most assemblers but tells the GNU assembler that it must check the lines that follow for all valid assembler constructs. -- Macro: ASM_APP_OFF A C string constant for text to be output after each ‘asm’ statement or group of consecutive ones. Normally this is ‘"#NO_APP"’, which tells the GNU assembler to resume making the time-saving assumptions that are valid for ordinary compiler output. -- Macro: ASM_OUTPUT_SOURCE_FILENAME (STREAM, NAME) A C statement to output COFF information or DWARF debugging information which indicates that filename NAME is the current source file to the stdio stream STREAM. This macro need not be defined if the standard form of output for the file format in use is appropriate. -- Target Hook: void TARGET_ASM_OUTPUT_SOURCE_FILENAME (FILE *FILE, const char *NAME) Output DWARF debugging information which indicates that filename NAME is the current source file to the stdio stream FILE. This target hook need not be defined if the standard form of output for the file format in use is appropriate. -- Target Hook: void TARGET_ASM_OUTPUT_IDENT (const char *NAME) Output a string based on NAME, suitable for the ‘#ident’ directive, or the equivalent directive or pragma in non-C-family languages. If this hook is not defined, nothing is output for the ‘#ident’ directive. -- Macro: OUTPUT_QUOTED_STRING (STREAM, STRING) A C statement to output the string STRING to the stdio stream STREAM. If you do not call the function ‘output_quoted_string’ in your config files, GCC will only call it to output filenames to the assembler source. So you can use it to canonicalize the format of the filename using this macro. -- Target Hook: void TARGET_ASM_NAMED_SECTION (const char *NAME, unsigned int FLAGS, tree DECL) Output assembly directives to switch to section NAME. The section should have attributes as specified by FLAGS, which is a bit mask of the ‘SECTION_*’ flags defined in ‘output.h’. If DECL is non-NULL, it is the ‘VAR_DECL’ or ‘FUNCTION_DECL’ with which this section is associated. -- Target Hook: bool TARGET_ASM_ELF_FLAGS_NUMERIC (unsigned int FLAGS, unsigned int *NUM) This hook can be used to encode ELF section flags for which no letter code has been defined in the assembler. It is called by ‘default_asm_named_section’ whenever the section flags need to be emitted in the assembler output. If the hook returns true, then the numerical value for ELF section flags should be calculated from FLAGS and saved in *NUM; the value is printed out instead of the normal sequence of letter codes. If the hook is not defined, or if it returns false, then NUM is ignored and the traditional letter sequence is emitted. -- Target Hook: section * TARGET_ASM_FUNCTION_SECTION (tree DECL, enum node_frequency FREQ, bool STARTUP, bool EXIT) Return preferred text (sub)section for function DECL. Main purpose of this function is to separate cold, normal and hot functions. STARTUP is true when function is known to be used only at startup (from static constructors or it is ‘main()’). EXIT is true when function is known to be used only at exit (from static destructors). Return NULL if function should go to default text section. -- Target Hook: void TARGET_ASM_FUNCTION_SWITCHED_TEXT_SECTIONS (FILE *FILE, tree DECL, bool NEW_IS_COLD) Used by the target to emit any assembler directives or additional labels needed when a function is partitioned between different sections. Output should be written to FILE. The function decl is available as DECL and the new section is 'cold' if NEW_IS_COLD is ‘true’. -- Common Target Hook: bool TARGET_HAVE_NAMED_SECTIONS This flag is true if the target supports ‘TARGET_ASM_NAMED_SECTION’. It must not be modified by command-line option processing. -- Target Hook: bool TARGET_HAVE_SWITCHABLE_BSS_SECTIONS This flag is true if we can create zeroed data by switching to a BSS section and then using ‘ASM_OUTPUT_SKIP’ to allocate the space. This is true on most ELF targets. -- Target Hook: unsigned int TARGET_SECTION_TYPE_FLAGS (tree DECL, const char *NAME, int RELOC) Choose a set of section attributes for use by ‘TARGET_ASM_NAMED_SECTION’ based on a variable or function decl, a section name, and whether or not the declaration's initializer may contain runtime relocations. DECL may be null, in which case read-write data should be assumed. The default version of this function handles choosing code vs data, read-only vs read-write data, and ‘flag_pic’. You should only need to override this if your target has special flags that might be set via ‘__attribute__’. -- Target Hook: void TARGET_ASM_RECORD_GCC_SWITCHES (const char *) Provides the target with the ability to record the gcc command line switches provided as argument. By default this hook is set to NULL, but an example implementation is provided for ELF based targets. Called ELF_RECORD_GCC_SWITCHES, it records the switches as ASCII text inside a new, string mergeable section in the assembler output file. The name of the new section is provided by the ‘TARGET_ASM_RECORD_GCC_SWITCHES_SECTION’ target hook. -- Target Hook: const char * TARGET_ASM_RECORD_GCC_SWITCHES_SECTION This is the name of the section that will be created by the example ELF implementation of the ‘TARGET_ASM_RECORD_GCC_SWITCHES’ target hook.  File: gccint.info, Node: Data Output, Next: Uninitialized Data, Prev: File Framework, Up: Assembler Format 18.20.2 Output of Data ---------------------- -- Target Hook: const char * TARGET_ASM_BYTE_OP -- Target Hook: const char * TARGET_ASM_ALIGNED_HI_OP -- Target Hook: const char * TARGET_ASM_ALIGNED_PSI_OP -- Target Hook: const char * TARGET_ASM_ALIGNED_SI_OP -- Target Hook: const char * TARGET_ASM_ALIGNED_PDI_OP -- Target Hook: const char * TARGET_ASM_ALIGNED_DI_OP -- Target Hook: const char * TARGET_ASM_ALIGNED_PTI_OP -- Target Hook: const char * TARGET_ASM_ALIGNED_TI_OP -- Target Hook: const char * TARGET_ASM_UNALIGNED_HI_OP -- Target Hook: const char * TARGET_ASM_UNALIGNED_PSI_OP -- Target Hook: const char * TARGET_ASM_UNALIGNED_SI_OP -- Target Hook: const char * TARGET_ASM_UNALIGNED_PDI_OP -- Target Hook: const char * TARGET_ASM_UNALIGNED_DI_OP -- Target Hook: const char * TARGET_ASM_UNALIGNED_PTI_OP -- Target Hook: const char * TARGET_ASM_UNALIGNED_TI_OP These hooks specify assembly directives for creating certain kinds of integer object. The ‘TARGET_ASM_BYTE_OP’ directive creates a byte-sized object, the ‘TARGET_ASM_ALIGNED_HI_OP’ one creates an aligned two-byte object, and so on. Any of the hooks may be ‘NULL’, indicating that no suitable directive is available. The compiler will print these strings at the start of a new line, followed immediately by the object's initial value. In most cases, the string should contain a tab, a pseudo-op, and then another tab. -- Target Hook: bool TARGET_ASM_INTEGER (rtx X, unsigned int SIZE, int ALIGNED_P) The ‘assemble_integer’ function uses this hook to output an integer object. X is the object's value, SIZE is its size in bytes and ALIGNED_P indicates whether it is aligned. The function should return ‘true’ if it was able to output the object. If it returns false, ‘assemble_integer’ will try to split the object into smaller parts. The default implementation of this hook will use the ‘TARGET_ASM_BYTE_OP’ family of strings, returning ‘false’ when the relevant string is ‘NULL’. -- Target Hook: void TARGET_ASM_DECL_END (void) Define this hook if the target assembler requires a special marker to terminate an initialized variable declaration. -- Target Hook: bool TARGET_ASM_OUTPUT_ADDR_CONST_EXTRA (FILE *FILE, rtx X) A target hook to recognize RTX patterns that ‘output_addr_const’ can't deal with, and output assembly code to FILE corresponding to the pattern X. This may be used to allow machine-dependent ‘UNSPEC’s to appear within constants. If target hook fails to recognize a pattern, it must return ‘false’, so that a standard error message is printed. If it prints an error message itself, by calling, for example, ‘output_operand_lossage’, it may just return ‘true’. -- Macro: ASM_OUTPUT_ASCII (STREAM, PTR, LEN) A C statement to output to the stdio stream STREAM an assembler instruction to assemble a string constant containing the LEN bytes at PTR. PTR will be a C expression of type ‘char *’ and LEN a C expression of type ‘int’. If the assembler has a ‘.ascii’ pseudo-op as found in the Berkeley Unix assembler, do not define the macro ‘ASM_OUTPUT_ASCII’. -- Macro: ASM_OUTPUT_FDESC (STREAM, DECL, N) A C statement to output word N of a function descriptor for DECL. This must be defined if ‘TARGET_VTABLE_USES_DESCRIPTORS’ is defined, and is otherwise unused. -- Macro: CONSTANT_POOL_BEFORE_FUNCTION You may define this macro as a C expression. You should define the expression to have a nonzero value if GCC should output the constant pool for a function before the code for the function, or a zero value if GCC should output the constant pool after the function. If you do not define this macro, the usual case, GCC will output the constant pool before the function. -- Macro: ASM_OUTPUT_POOL_PROLOGUE (FILE, FUNNAME, FUNDECL, SIZE) A C statement to output assembler commands to define the start of the constant pool for a function. FUNNAME is a string giving the name of the function. Should the return type of the function be required, it can be obtained via FUNDECL. SIZE is the size, in bytes, of the constant pool that will be written immediately after this call. If no constant-pool prefix is required, the usual case, this macro need not be defined. -- Macro: ASM_OUTPUT_SPECIAL_POOL_ENTRY (FILE, X, MODE, ALIGN, LABELNO, JUMPTO) A C statement (with or without semicolon) to output a constant in the constant pool, if it needs special treatment. (This macro need not do anything for RTL expressions that can be output normally.) The argument FILE is the standard I/O stream to output the assembler code on. X is the RTL expression for the constant to output, and MODE is the machine mode (in case X is a ‘const_int’). ALIGN is the required alignment for the value X; you should output an assembler directive to force this much alignment. The argument LABELNO is a number to use in an internal label for the address of this pool entry. The definition of this macro is responsible for outputting the label definition at the proper place. Here is how to do this: (*targetm.asm_out.internal_label) (FILE, "LC", LABELNO); When you output a pool entry specially, you should end with a ‘goto’ to the label JUMPTO. This will prevent the same pool entry from being output a second time in the usual manner. You need not define this macro if it would do nothing. -- Macro: ASM_OUTPUT_POOL_EPILOGUE (FILE FUNNAME FUNDECL SIZE) A C statement to output assembler commands to at the end of the constant pool for a function. FUNNAME is a string giving the name of the function. Should the return type of the function be required, you can obtain it via FUNDECL. SIZE is the size, in bytes, of the constant pool that GCC wrote immediately before this call. If no constant-pool epilogue is required, the usual case, you need not define this macro. -- Macro: IS_ASM_LOGICAL_LINE_SEPARATOR (C, STR) Define this macro as a C expression which is nonzero if C is used as a logical line separator by the assembler. STR points to the position in the string where C was found; this can be used if a line separator uses multiple characters. If you do not define this macro, the default is that only the character ‘;’ is treated as a logical line separator. -- Target Hook: const char * TARGET_ASM_OPEN_PAREN -- Target Hook: const char * TARGET_ASM_CLOSE_PAREN These target hooks are C string constants, describing the syntax in the assembler for grouping arithmetic expressions. If not overridden, they default to normal parentheses, which is correct for most assemblers. These macros are provided by ‘real.h’ for writing the definitions of ‘ASM_OUTPUT_DOUBLE’ and the like: -- Macro: REAL_VALUE_TO_TARGET_SINGLE (X, L) -- Macro: REAL_VALUE_TO_TARGET_DOUBLE (X, L) -- Macro: REAL_VALUE_TO_TARGET_LONG_DOUBLE (X, L) -- Macro: REAL_VALUE_TO_TARGET_DECIMAL32 (X, L) -- Macro: REAL_VALUE_TO_TARGET_DECIMAL64 (X, L) -- Macro: REAL_VALUE_TO_TARGET_DECIMAL128 (X, L) These translate X, of type ‘REAL_VALUE_TYPE’, to the target's floating point representation, and store its bit pattern in the variable L. For ‘REAL_VALUE_TO_TARGET_SINGLE’ and ‘REAL_VALUE_TO_TARGET_DECIMAL32’, this variable should be a simple ‘long int’. For the others, it should be an array of ‘long int’. The number of elements in this array is determined by the size of the desired target floating point data type: 32 bits of it go in each ‘long int’ array element. Each array element holds 32 bits of the result, even if ‘long int’ is wider than 32 bits on the host machine. The array element values are designed so that you can print them out using ‘fprintf’ in the order they should appear in the target machine's memory.  File: gccint.info, Node: Uninitialized Data, Next: Label Output, Prev: Data Output, Up: Assembler Format 18.20.3 Output of Uninitialized Variables ----------------------------------------- Each of the macros in this section is used to do the whole job of outputting a single uninitialized variable. -- Macro: ASM_OUTPUT_COMMON (STREAM, NAME, SIZE, ROUNDED) A C statement (sans semicolon) to output to the stdio stream STREAM the assembler definition of a common-label named NAME whose size is SIZE bytes. The variable ROUNDED is the size rounded up to whatever alignment the caller wants. It is possible that SIZE may be zero, for instance if a struct with no other member than a zero-length array is defined. In this case, the backend must output a symbol definition that allocates at least one byte, both so that the address of the resulting object does not compare equal to any other, and because some object formats cannot even express the concept of a zero-sized common symbol, as that is how they represent an ordinary undefined external. Use the expression ‘assemble_name (STREAM, NAME)’ to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. This macro controls how the assembler definitions of uninitialized common global variables are output. -- Macro: ASM_OUTPUT_ALIGNED_COMMON (STREAM, NAME, SIZE, ALIGNMENT) Like ‘ASM_OUTPUT_COMMON’ except takes the required alignment as a separate, explicit argument. If you define this macro, it is used in place of ‘ASM_OUTPUT_COMMON’, and gives you more flexibility in handling the required alignment of the variable. The alignment is specified as the number of bits. -- Macro: ASM_OUTPUT_ALIGNED_DECL_COMMON (STREAM, DECL, NAME, SIZE, ALIGNMENT) Like ‘ASM_OUTPUT_ALIGNED_COMMON’ except that DECL of the variable to be output, if there is one, or ‘NULL_TREE’ if there is no corresponding variable. If you define this macro, GCC will use it in place of both ‘ASM_OUTPUT_COMMON’ and ‘ASM_OUTPUT_ALIGNED_COMMON’. Define this macro when you need to see the variable's decl in order to chose what to output. -- Macro: ASM_OUTPUT_ALIGNED_BSS (STREAM, DECL, NAME, SIZE, ALIGNMENT) A C statement (sans semicolon) to output to the stdio stream STREAM the assembler definition of uninitialized global DECL named NAME whose size is SIZE bytes. The variable ALIGNMENT is the alignment specified as the number of bits. Try to use function ‘asm_output_aligned_bss’ defined in file ‘varasm.cc’ when defining this macro. If unable, use the expression ‘assemble_name (STREAM, NAME)’ to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. There are two ways of handling global BSS. One is to define this macro. The other is to have ‘TARGET_ASM_SELECT_SECTION’ return a switchable BSS section (*note TARGET_HAVE_SWITCHABLE_BSS_SECTIONS::). You do not need to do both. Some languages do not have ‘common’ data, and require a non-common form of global BSS in order to handle uninitialized globals efficiently. C++ is one example of this. However, if the target does not support global BSS, the front end may choose to make globals common in order to save space in the object file. -- Macro: ASM_OUTPUT_LOCAL (STREAM, NAME, SIZE, ROUNDED) A C statement (sans semicolon) to output to the stdio stream STREAM the assembler definition of a local-common-label named NAME whose size is SIZE bytes. The variable ROUNDED is the size rounded up to whatever alignment the caller wants. Use the expression ‘assemble_name (STREAM, NAME)’ to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. This macro controls how the assembler definitions of uninitialized static variables are output. -- Macro: ASM_OUTPUT_ALIGNED_LOCAL (STREAM, NAME, SIZE, ALIGNMENT) Like ‘ASM_OUTPUT_LOCAL’ except takes the required alignment as a separate, explicit argument. If you define this macro, it is used in place of ‘ASM_OUTPUT_LOCAL’, and gives you more flexibility in handling the required alignment of the variable. The alignment is specified as the number of bits. -- Macro: ASM_OUTPUT_ALIGNED_DECL_LOCAL (STREAM, DECL, NAME, SIZE, ALIGNMENT) Like ‘ASM_OUTPUT_ALIGNED_LOCAL’ except that DECL of the variable to be output, if there is one, or ‘NULL_TREE’ if there is no corresponding variable. If you define this macro, GCC will use it in place of both ‘ASM_OUTPUT_LOCAL’ and ‘ASM_OUTPUT_ALIGNED_LOCAL’. Define this macro when you need to see the variable's decl in order to chose what to output.  File: gccint.info, Node: Label Output, Next: Initialization, Prev: Uninitialized Data, Up: Assembler Format 18.20.4 Output and Generation of Labels --------------------------------------- This is about outputting labels. -- Macro: ASM_OUTPUT_LABEL (STREAM, NAME) A C statement (sans semicolon) to output to the stdio stream STREAM the assembler definition of a label named NAME. Use the expression ‘assemble_name (STREAM, NAME)’ to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. A default definition of this macro is provided which is correct for most systems. -- Macro: ASM_OUTPUT_FUNCTION_LABEL (STREAM, NAME, DECL) A C statement (sans semicolon) to output to the stdio stream STREAM the assembler definition of a label named NAME of a function. Use the expression ‘assemble_name (STREAM, NAME)’ to output the name itself; before and after that, output the additional assembler syntax for defining the name, and a newline. A default definition of this macro is provided which is correct for most systems. If this macro is not defined, then the function name is defined in the usual manner as a label (by means of ‘ASM_OUTPUT_LABEL’). -- Macro: ASM_OUTPUT_INTERNAL_LABEL (STREAM, NAME) Identical to ‘ASM_OUTPUT_LABEL’, except that NAME is known to refer to a compiler-generated label. The default definition uses ‘assemble_name_raw’, which is like ‘assemble_name’ except that it is more efficient. -- Macro: SIZE_ASM_OP A C string containing the appropriate assembler directive to specify the size of a symbol, without any arguments. On systems that use ELF, the default (in ‘config/elfos.h’) is ‘"\t.size\t"’; on other systems, the default is not to define this macro. Define this macro only if it is correct to use the default definitions of ‘ASM_OUTPUT_SIZE_DIRECTIVE’ and ‘ASM_OUTPUT_MEASURED_SIZE’ for your system. If you need your own custom definitions of those macros, or if you do not need explicit symbol sizes at all, do not define this macro. -- Macro: ASM_OUTPUT_SIZE_DIRECTIVE (STREAM, NAME, SIZE) A C statement (sans semicolon) to output to the stdio stream STREAM a directive telling the assembler that the size of the symbol NAME is SIZE. SIZE is a ‘HOST_WIDE_INT’. If you define ‘SIZE_ASM_OP’, a default definition of this macro is provided. -- Macro: ASM_OUTPUT_MEASURED_SIZE (STREAM, NAME) A C statement (sans semicolon) to output to the stdio stream STREAM a directive telling the assembler to calculate the size of the symbol NAME by subtracting its address from the current address. If you define ‘SIZE_ASM_OP’, a default definition of this macro is provided. The default assumes that the assembler recognizes a special ‘.’ symbol as referring to the current address, and can calculate the difference between this and another symbol. If your assembler does not recognize ‘.’ or cannot do calculations with it, you will need to redefine ‘ASM_OUTPUT_MEASURED_SIZE’ to use some other technique. -- Macro: NO_DOLLAR_IN_LABEL Define this macro if the assembler does not accept the character ‘$’ in label names. By default constructors and destructors in G++ have ‘$’ in the identifiers. If this macro is defined, ‘.’ is used instead. -- Macro: NO_DOT_IN_LABEL Define this macro if the assembler does not accept the character ‘.’ in label names. By default constructors and destructors in G++ have names that use ‘.’. If this macro is defined, these names are rewritten to avoid ‘.’. -- Macro: TYPE_ASM_OP A C string containing the appropriate assembler directive to specify the type of a symbol, without any arguments. On systems that use ELF, the default (in ‘config/elfos.h’) is ‘"\t.type\t"’; on other systems, the default is not to define this macro. Define this macro only if it is correct to use the default definition of ‘ASM_OUTPUT_TYPE_DIRECTIVE’ for your system. If you need your own custom definition of this macro, or if you do not need explicit symbol types at all, do not define this macro. -- Macro: TYPE_OPERAND_FMT A C string which specifies (using ‘printf’ syntax) the format of the second operand to ‘TYPE_ASM_OP’. On systems that use ELF, the default (in ‘config/elfos.h’) is ‘"@%s"’; on other systems, the default is not to define this macro. Define this macro only if it is correct to use the default definition of ‘ASM_OUTPUT_TYPE_DIRECTIVE’ for your system. If you need your own custom definition of this macro, or if you do not need explicit symbol types at all, do not define this macro. -- Macro: ASM_OUTPUT_TYPE_DIRECTIVE (STREAM, TYPE) A C statement (sans semicolon) to output to the stdio stream STREAM a directive telling the assembler that the type of the symbol NAME is TYPE. TYPE is a C string; currently, that string is always either ‘"function"’ or ‘"object"’, but you should not count on this. If you define ‘TYPE_ASM_OP’ and ‘TYPE_OPERAND_FMT’, a default definition of this macro is provided. -- Macro: ASM_DECLARE_FUNCTION_NAME (STREAM, NAME, DECL) A C statement (sans semicolon) to output to the stdio stream STREAM any text necessary for declaring the name NAME of a function which is being defined. This macro is responsible for outputting the label definition (perhaps using ‘ASM_OUTPUT_FUNCTION_LABEL’). The argument DECL is the ‘FUNCTION_DECL’ tree node representing the function. If this macro is not defined, then the function name is defined in the usual manner as a label (by means of ‘ASM_OUTPUT_FUNCTION_LABEL’). You may wish to use ‘ASM_OUTPUT_TYPE_DIRECTIVE’ in the definition of this macro. -- Macro: ASM_DECLARE_FUNCTION_SIZE (STREAM, NAME, DECL) A C statement (sans semicolon) to output to the stdio stream STREAM any text necessary for declaring the size of a function which is being defined. The argument NAME is the name of the function. The argument DECL is the ‘FUNCTION_DECL’ tree node representing the function. If this macro is not defined, then the function size is not defined. You may wish to use ‘ASM_OUTPUT_MEASURED_SIZE’ in the definition of this macro. -- Macro: ASM_DECLARE_COLD_FUNCTION_NAME (STREAM, NAME, DECL) A C statement (sans semicolon) to output to the stdio stream STREAM any text necessary for declaring the name NAME of a cold function partition which is being defined. This macro is responsible for outputting the label definition (perhaps using ‘ASM_OUTPUT_FUNCTION_LABEL’). The argument DECL is the ‘FUNCTION_DECL’ tree node representing the function. If this macro is not defined, then the cold partition name is defined in the usual manner as a label (by means of ‘ASM_OUTPUT_LABEL’). You may wish to use ‘ASM_OUTPUT_TYPE_DIRECTIVE’ in the definition of this macro. -- Macro: ASM_DECLARE_COLD_FUNCTION_SIZE (STREAM, NAME, DECL) A C statement (sans semicolon) to output to the stdio stream STREAM any text necessary for declaring the size of a cold function partition which is being defined. The argument NAME is the name of the cold partition of the function. The argument DECL is the ‘FUNCTION_DECL’ tree node representing the function. If this macro is not defined, then the partition size is not defined. You may wish to use ‘ASM_OUTPUT_MEASURED_SIZE’ in the definition of this macro. -- Macro: ASM_DECLARE_OBJECT_NAME (STREAM, NAME, DECL) A C statement (sans semicolon) to output to the stdio stream STREAM any text necessary for declaring the name NAME of an initialized variable which is being defined. This macro must output the label definition (perhaps using ‘ASM_OUTPUT_LABEL’). The argument DECL is the ‘VAR_DECL’ tree node representing the variable. If this macro is not defined, then the variable name is defined in the usual manner as a label (by means of ‘ASM_OUTPUT_LABEL’). You may wish to use ‘ASM_OUTPUT_TYPE_DIRECTIVE’ and/or ‘ASM_OUTPUT_SIZE_DIRECTIVE’ in the definition of this macro. -- Target Hook: void TARGET_ASM_DECLARE_CONSTANT_NAME (FILE *FILE, const char *NAME, const_tree EXPR, HOST_WIDE_INT SIZE) A target hook to output to the stdio stream FILE any text necessary for declaring the name NAME of a constant which is being defined. This target hook is responsible for outputting the label definition (perhaps using ‘assemble_label’). The argument EXP is the value of the constant, and SIZE is the size of the constant in bytes. The NAME will be an internal label. The default version of this target hook, define the NAME in the usual manner as a label (by means of ‘assemble_label’). You may wish to use ‘ASM_OUTPUT_TYPE_DIRECTIVE’ in this target hook. -- Macro: ASM_DECLARE_REGISTER_GLOBAL (STREAM, DECL, REGNO, NAME) A C statement (sans semicolon) to output to the stdio stream STREAM any text necessary for claiming a register REGNO for a global variable DECL with name NAME. If you don't define this macro, that is equivalent to defining it to do nothing. -- Macro: ASM_FINISH_DECLARE_OBJECT (STREAM, DECL, TOPLEVEL, ATEND) A C statement (sans semicolon) to finish up declaring a variable name once the compiler has processed its initializer fully and thus has had a chance to determine the size of an array when controlled by an initializer. This is used on systems where it's necessary to declare something about the size of the object. If you don't define this macro, that is equivalent to defining it to do nothing. You may wish to use ‘ASM_OUTPUT_SIZE_DIRECTIVE’ and/or ‘ASM_OUTPUT_MEASURED_SIZE’ in the definition of this macro. -- Target Hook: void TARGET_ASM_GLOBALIZE_LABEL (FILE *STREAM, const char *NAME) This target hook is a function to output to the stdio stream STREAM some commands that will make the label NAME global; that is, available for reference from other files. The default implementation relies on a proper definition of ‘GLOBAL_ASM_OP’. -- Target Hook: void TARGET_ASM_GLOBALIZE_DECL_NAME (FILE *STREAM, tree DECL) This target hook is a function to output to the stdio stream STREAM some commands that will make the name associated with DECL global; that is, available for reference from other files. The default implementation uses the TARGET_ASM_GLOBALIZE_LABEL target hook. -- Target Hook: void TARGET_ASM_ASSEMBLE_UNDEFINED_DECL (FILE *STREAM, const char *NAME, const_tree DECL) This target hook is a function to output to the stdio stream STREAM some commands that will declare the name associated with DECL which is not defined in the current translation unit. Most assemblers do not require anything to be output in this case. -- Macro: ASM_WEAKEN_LABEL (STREAM, NAME) A C statement (sans semicolon) to output to the stdio stream STREAM some commands that will make the label NAME weak; that is, available for reference from other files but only used if no other definition is available. Use the expression ‘assemble_name (STREAM, NAME)’ to output the name itself; before and after that, output the additional assembler syntax for making that name weak, and a newline. If you don't define this macro or ‘ASM_WEAKEN_DECL’, GCC will not support weak symbols and you should not define the ‘SUPPORTS_WEAK’ macro. -- Macro: ASM_WEAKEN_DECL (STREAM, DECL, NAME, VALUE) Combines (and replaces) the function of ‘ASM_WEAKEN_LABEL’ and ‘ASM_OUTPUT_WEAK_ALIAS’, allowing access to the associated function or variable decl. If VALUE is not ‘NULL’, this C statement should output to the stdio stream STREAM assembler code which defines (equates) the weak symbol NAME to have the value VALUE. If VALUE is ‘NULL’, it should output commands to make NAME weak. -- Macro: ASM_OUTPUT_WEAKREF (STREAM, DECL, NAME, VALUE) Outputs a directive that enables NAME to be used to refer to symbol VALUE with weak-symbol semantics. ‘decl’ is the declaration of ‘name’. -- Macro: SUPPORTS_WEAK A preprocessor constant expression which evaluates to true if the target supports weak symbols. If you don't define this macro, ‘defaults.h’ provides a default definition. If either ‘ASM_WEAKEN_LABEL’ or ‘ASM_WEAKEN_DECL’ is defined, the default definition is ‘1’; otherwise, it is ‘0’. -- Macro: TARGET_SUPPORTS_WEAK A C expression which evaluates to true if the target supports weak symbols. If you don't define this macro, ‘defaults.h’ provides a default definition. The default definition is ‘(SUPPORTS_WEAK)’. Define this macro if you want to control weak symbol support with a compiler flag such as ‘-melf’. -- Macro: MAKE_DECL_ONE_ONLY (DECL) A C statement (sans semicolon) to mark DECL to be emitted as a public symbol such that extra copies in multiple translation units will be discarded by the linker. Define this macro if your object file format provides support for this concept, such as the ‘COMDAT’ section flags in the Microsoft Windows PE/COFF format, and this support requires changes to DECL, such as putting it in a separate section. -- Macro: SUPPORTS_ONE_ONLY A C expression which evaluates to true if the target supports one-only semantics. If you don't define this macro, ‘varasm.cc’ provides a default definition. If ‘MAKE_DECL_ONE_ONLY’ is defined, the default definition is ‘1’; otherwise, it is ‘0’. Define this macro if you want to control one-only symbol support with a compiler flag, or if setting the ‘DECL_ONE_ONLY’ flag is enough to mark a declaration to be emitted as one-only. -- Target Hook: void TARGET_ASM_ASSEMBLE_VISIBILITY (tree DECL, int VISIBILITY) This target hook is a function to output to ASM_OUT_FILE some commands that will make the symbol(s) associated with DECL have hidden, protected or internal visibility as specified by VISIBILITY. -- Macro: TARGET_WEAK_NOT_IN_ARCHIVE_TOC A C expression that evaluates to true if the target's linker expects that weak symbols do not appear in a static archive's table of contents. The default is ‘0’. Leaving weak symbols out of an archive's table of contents means that, if a symbol will only have a definition in one translation unit and will have undefined references from other translation units, that symbol should not be weak. Defining this macro to be nonzero will thus have the effect that certain symbols that would normally be weak (explicit template instantiations, and vtables for polymorphic classes with noninline key methods) will instead be nonweak. The C++ ABI requires this macro to be zero. Define this macro for targets where full C++ ABI compliance is impossible and where linker restrictions require weak symbols to be left out of a static archive's table of contents. -- Macro: ASM_OUTPUT_EXTERNAL (STREAM, DECL, NAME) A C statement (sans semicolon) to output to the stdio stream STREAM any text necessary for declaring the name of an external symbol named NAME which is referenced in this compilation but not defined. The value of DECL is the tree node for the declaration. This macro need not be defined if it does not need to output anything. The GNU assembler and most Unix assemblers don't require anything. -- Target Hook: void TARGET_ASM_EXTERNAL_LIBCALL (rtx SYMREF) This target hook is a function to output to ASM_OUT_FILE an assembler pseudo-op to declare a library function name external. The name of the library function is given by SYMREF, which is a ‘symbol_ref’. -- Target Hook: void TARGET_ASM_MARK_DECL_PRESERVED (const char *SYMBOL) This target hook is a function to output to ASM_OUT_FILE an assembler directive to annotate SYMBOL as used. The Darwin target uses the .no_dead_code_strip directive. -- Macro: ASM_OUTPUT_LABELREF (STREAM, NAME) A C statement (sans semicolon) to output to the stdio stream STREAM a reference in assembler syntax to a label named NAME. This should add ‘_’ to the front of the name, if that is customary on your operating system, as it is in most Berkeley Unix systems. This macro is used in ‘assemble_name’. -- Target Hook: tree TARGET_MANGLE_ASSEMBLER_NAME (const char *NAME) Given a symbol NAME, perform same mangling as ‘varasm.cc’'s ‘assemble_name’, but in memory rather than to a file stream, returning result as an ‘IDENTIFIER_NODE’. Required for correct LTO symtabs. The default implementation calls the ‘TARGET_STRIP_NAME_ENCODING’ hook and then prepends the ‘USER_LABEL_PREFIX’, if any. -- Macro: ASM_OUTPUT_SYMBOL_REF (STREAM, SYM) A C statement (sans semicolon) to output a reference to ‘SYMBOL_REF’ SYM. If not defined, ‘assemble_name’ will be used to output the name of the symbol. This macro may be used to modify the way a symbol is referenced depending on information encoded by ‘TARGET_ENCODE_SECTION_INFO’. -- Macro: ASM_OUTPUT_LABEL_REF (STREAM, BUF) A C statement (sans semicolon) to output a reference to BUF, the result of ‘ASM_GENERATE_INTERNAL_LABEL’. If not defined, ‘assemble_name’ will be used to output the name of the symbol. This macro is not used by ‘output_asm_label’, or the ‘%l’ specifier that calls it; the intention is that this macro should be set when it is necessary to output a label differently when its address is being taken. -- Target Hook: void TARGET_ASM_INTERNAL_LABEL (FILE *STREAM, const char *PREFIX, unsigned long LABELNO) A function to output to the stdio stream STREAM a label whose name is made from the string PREFIX and the number LABELNO. It is absolutely essential that these labels be distinct from the labels used for user-level functions and variables. Otherwise, certain programs will have name conflicts with internal labels. It is desirable to exclude internal labels from the symbol table of the object file. Most assemblers have a naming convention for labels that should be excluded; on many systems, the letter ‘L’ at the beginning of a label has this effect. You should find out what convention your system uses, and follow it. The default version of this function utilizes ‘ASM_GENERATE_INTERNAL_LABEL’. -- Macro: ASM_OUTPUT_DEBUG_LABEL (STREAM, PREFIX, NUM) A C statement to output to the stdio stream STREAM a debug info label whose name is made from the string PREFIX and the number NUM. This is useful for VLIW targets, where debug info labels may need to be treated differently than branch target labels. On some systems, branch target labels must be at the beginning of instruction bundles, but debug info labels can occur in the middle of instruction bundles. If this macro is not defined, then ‘(*targetm.asm_out.internal_label)’ will be used. -- Macro: ASM_GENERATE_INTERNAL_LABEL (STRING, PREFIX, NUM) A C statement to store into the string STRING a label whose name is made from the string PREFIX and the number NUM. This string, when output subsequently by ‘assemble_name’, should produce the output that ‘(*targetm.asm_out.internal_label)’ would produce with the same PREFIX and NUM. If the string begins with ‘*’, then ‘assemble_name’ will output the rest of the string unchanged. It is often convenient for ‘ASM_GENERATE_INTERNAL_LABEL’ to use ‘*’ in this way. If the string doesn't start with ‘*’, then ‘ASM_OUTPUT_LABELREF’ gets to output the string, and may change it. (Of course, ‘ASM_OUTPUT_LABELREF’ is also part of your machine description, so you should know what it does on your machine.) -- Macro: ASM_FORMAT_PRIVATE_NAME (OUTVAR, NAME, NUMBER) A C expression to assign to OUTVAR (which is a variable of type ‘char *’) a newly allocated string made from the string NAME and the number NUMBER, with some suitable punctuation added. Use ‘alloca’ to get space for the string. The string will be used as an argument to ‘ASM_OUTPUT_LABELREF’ to produce an assembler label for an internal static variable whose name is NAME. Therefore, the string must be such as to result in valid assembler code. The argument NUMBER is different each time this macro is executed; it prevents conflicts between similarly-named internal static variables in different scopes. Ideally this string should not be a valid C identifier, to prevent any conflict with the user's own symbols. Most assemblers allow periods or percent signs in assembler symbols; putting at least one of these between the name and the number will suffice. If this macro is not defined, a default definition will be provided which is correct for most systems. -- Macro: ASM_OUTPUT_DEF (STREAM, NAME, VALUE) A C statement to output to the stdio stream STREAM assembler code which defines (equates) the symbol NAME to have the value VALUE. If ‘SET_ASM_OP’ is defined, a default definition is provided which is correct for most systems. -- Macro: ASM_OUTPUT_DEF_FROM_DECLS (STREAM, DECL_OF_NAME, DECL_OF_VALUE) A C statement to output to the stdio stream STREAM assembler code which defines (equates) the symbol whose tree node is DECL_OF_NAME to have the value of the tree node DECL_OF_VALUE. This macro will be used in preference to ‘ASM_OUTPUT_DEF’ if it is defined and if the tree nodes are available. If ‘SET_ASM_OP’ is defined, a default definition is provided which is correct for most systems. -- Macro: TARGET_DEFERRED_OUTPUT_DEFS (DECL_OF_NAME, DECL_OF_VALUE) A C statement that evaluates to true if the assembler code which defines (equates) the symbol whose tree node is DECL_OF_NAME to have the value of the tree node DECL_OF_VALUE should be emitted near the end of the current compilation unit. The default is to not defer output of defines. This macro affects defines output by ‘ASM_OUTPUT_DEF’ and ‘ASM_OUTPUT_DEF_FROM_DECLS’. -- Macro: ASM_OUTPUT_WEAK_ALIAS (STREAM, NAME, VALUE) A C statement to output to the stdio stream STREAM assembler code which defines (equates) the weak symbol NAME to have the value VALUE. If VALUE is ‘NULL’, it defines NAME as an undefined weak symbol. Define this macro if the target only supports weak aliases; define ‘ASM_OUTPUT_DEF’ instead if possible. -- Macro: OBJC_GEN_METHOD_LABEL (BUF, IS_INST, CLASS_NAME, CAT_NAME, SEL_NAME) Define this macro to override the default assembler names used for Objective-C methods. The default name is a unique method number followed by the name of the class (e.g. ‘_1_Foo’). For methods in categories, the name of the category is also included in the assembler name (e.g. ‘_1_Foo_Bar’). These names are safe on most systems, but make debugging difficult since the method's selector is not present in the name. Therefore, particular systems define other ways of computing names. BUF is an expression of type ‘char *’ which gives you a buffer in which to store the name; its length is as long as CLASS_NAME, CAT_NAME and SEL_NAME put together, plus 50 characters extra. The argument IS_INST specifies whether the method is an instance method or a class method; CLASS_NAME is the name of the class; CAT_NAME is the name of the category (or ‘NULL’ if the method is not in a category); and SEL_NAME is the name of the selector. On systems where the assembler can handle quoted names, you can use this macro to provide more human-readable names.  File: gccint.info, Node: Initialization, Next: Macros for Initialization, Prev: Label Output, Up: Assembler Format 18.20.5 How Initialization Functions Are Handled ------------------------------------------------ The compiled code for certain languages includes “constructors” (also called “initialization routines”)--functions to initialize data in the program when the program is started. These functions need to be called before the program is "started"--that is to say, before ‘main’ is called. Compiling some languages generates “destructors” (also called “termination routines”) that should be called when the program terminates. To make the initialization and termination functions work, the compiler must output something in the assembler code to cause those functions to be called at the appropriate time. When you port the compiler to a new system, you need to specify how to do this. There are two major ways that GCC currently supports the execution of initialization and termination functions. Each way has two variants. Much of the structure is common to all four variations. The linker must build two lists of these functions--a list of initialization functions, called ‘__CTOR_LIST__’, and a list of termination functions, called ‘__DTOR_LIST__’. Each list always begins with an ignored function pointer (which may hold 0, −1, or a count of the function pointers after it, depending on the environment). This is followed by a series of zero or more function pointers to constructors (or destructors), followed by a function pointer containing zero. Depending on the operating system and its executable file format, either ‘crtstuff.c’ or ‘libgcc2.c’ traverses these lists at startup time and exit time. Constructors are called in reverse order of the list; destructors in forward order. The best way to handle static constructors works only for object file formats which provide arbitrarily-named sections. A section is set aside for a list of constructors, and another for a list of destructors. Traditionally these are called ‘.ctors’ and ‘.dtors’. Each object file that defines an initialization function also puts a word in the constructor section to point to that function. The linker accumulates all these words into one contiguous ‘.ctors’ section. Termination functions are handled similarly. This method will be chosen as the default by ‘target-def.h’ if ‘TARGET_ASM_NAMED_SECTION’ is defined. A target that does not support arbitrary sections, but does support special designated constructor and destructor sections may define ‘CTORS_SECTION_ASM_OP’ and ‘DTORS_SECTION_ASM_OP’ to achieve the same effect. When arbitrary sections are available, there are two variants, depending upon how the code in ‘crtstuff.c’ is called. On systems that support a “.init” section which is executed at program startup, parts of ‘crtstuff.c’ are compiled into that section. The program is linked by the ‘gcc’ driver like this: ld -o OUTPUT_FILE crti.o crtbegin.o ... -lgcc crtend.o crtn.o The prologue of a function (‘__init’) appears in the ‘.init’ section of ‘crti.o’; the epilogue appears in ‘crtn.o’. Likewise for the function ‘__fini’ in the “.fini” section. Normally these files are provided by the operating system or by the GNU C library, but are provided by GCC for a few targets. The objects ‘crtbegin.o’ and ‘crtend.o’ are (for most targets) compiled from ‘crtstuff.c’. They contain, among other things, code fragments within the ‘.init’ and ‘.fini’ sections that branch to routines in the ‘.text’ section. The linker will pull all parts of a section together, which results in a complete ‘__init’ function that invokes the routines we need at startup. To use this variant, you must define the ‘INIT_SECTION_ASM_OP’ macro properly. If no init section is available, when GCC compiles any function called ‘main’ (or more accurately, any function designated as a program entry point by the language front end calling ‘expand_main_function’), it inserts a procedure call to ‘__main’ as the first executable code after the function prologue. The ‘__main’ function is defined in ‘libgcc2.c’ and runs the global constructors. In file formats that don't support arbitrary sections, there are again two variants. In the simplest variant, the GNU linker (GNU ‘ld’) and an 'a.out' format must be used. In this case, ‘TARGET_ASM_CONSTRUCTOR’ is defined to produce a ‘.stabs’ entry of type ‘N_SETT’, referencing the name ‘__CTOR_LIST__’, and with the address of the void function containing the initialization code as its value. The GNU linker recognizes this as a request to add the value to a “set”; the values are accumulated, and are eventually placed in the executable as a vector in the format described above, with a leading (ignored) count and a trailing zero element. ‘TARGET_ASM_DESTRUCTOR’ is handled similarly. Since no init section is available, the absence of ‘INIT_SECTION_ASM_OP’ causes the compilation of ‘main’ to call ‘__main’ as above, starting the initialization process. The last variant uses neither arbitrary sections nor the GNU linker. This is preferable when you want to do dynamic linking and when using file formats which the GNU linker does not support, such as 'ECOFF'. In this case, ‘TARGET_HAVE_CTORS_DTORS’ is false, initialization and termination functions are recognized simply by their names. This requires an extra program in the linkage step, called ‘collect2’. This program pretends to be the linker, for use with GCC; it does its job by running the ordinary linker, but also arranges to include the vectors of initialization and termination functions. These functions are called via ‘__main’ as described above. In order to use this method, ‘use_collect2’ must be defined in the target in ‘config.gcc’. The following section describes the specific macros that control and customize the handling of initialization and termination functions.  File: gccint.info, Node: Macros for Initialization, Next: Instruction Output, Prev: Initialization, Up: Assembler Format 18.20.6 Macros Controlling Initialization Routines -------------------------------------------------- Here are the macros that control how the compiler handles initialization and termination functions: -- Macro: INIT_SECTION_ASM_OP If defined, a C string constant, including spacing, for the assembler operation to identify the following data as initialization code. If not defined, GCC will assume such a section does not exist. When you are using special sections for initialization and termination functions, this macro also controls how ‘crtstuff.c’ and ‘libgcc2.c’ arrange to run the initialization functions. -- Macro: HAS_INIT_SECTION If defined, ‘main’ will not call ‘__main’ as described above. This macro should be defined for systems that control start-up code on a symbol-by-symbol basis, such as OSF/1, and should not be defined explicitly for systems that support ‘INIT_SECTION_ASM_OP’. -- Macro: LD_INIT_SWITCH If defined, a C string constant for a switch that tells the linker that the following symbol is an initialization routine. -- Macro: LD_FINI_SWITCH If defined, a C string constant for a switch that tells the linker that the following symbol is a finalization routine. -- Macro: COLLECT_SHARED_INIT_FUNC (STREAM, FUNC) If defined, a C statement that will write a function that can be automatically called when a shared library is loaded. The function should call FUNC, which takes no arguments. If not defined, and the object format requires an explicit initialization function, then a function called ‘_GLOBAL__DI’ will be generated. This function and the following one are used by collect2 when linking a shared library that needs constructors or destructors, or has DWARF2 exception tables embedded in the code. -- Macro: COLLECT_SHARED_FINI_FUNC (STREAM, FUNC) If defined, a C statement that will write a function that can be automatically called when a shared library is unloaded. The function should call FUNC, which takes no arguments. If not defined, and the object format requires an explicit finalization function, then a function called ‘_GLOBAL__DD’ will be generated. -- Macro: INVOKE__main If defined, ‘main’ will call ‘__main’ despite the presence of ‘INIT_SECTION_ASM_OP’. This macro should be defined for systems where the init section is not actually run automatically, but is still useful for collecting the lists of constructors and destructors. -- Macro: SUPPORTS_INIT_PRIORITY If nonzero, the C++ ‘init_priority’ attribute is supported and the compiler should emit instructions to control the order of initialization of objects. If zero, the compiler will issue an error message upon encountering an ‘init_priority’ attribute. -- Target Hook: bool TARGET_HAVE_CTORS_DTORS This value is true if the target supports some "native" method of collecting constructors and destructors to be run at startup and exit. It is false if we must use ‘collect2’. -- Target Hook: bool TARGET_DTORS_FROM_CXA_ATEXIT This value is true if the target wants destructors to be queued to be run from __cxa_atexit. If this is the case then, for each priority level, a new constructor will be entered that registers the destructors for that level with __cxa_atexit (and there will be no destructors emitted). It is false the method implied by ‘have_ctors_dtors’ is used. -- Target Hook: void TARGET_ASM_CONSTRUCTOR (rtx SYMBOL, int PRIORITY) If defined, a function that outputs assembler code to arrange to call the function referenced by SYMBOL at initialization time. Assume that SYMBOL is a ‘SYMBOL_REF’ for a function taking no arguments and with no return value. If the target supports initialization priorities, PRIORITY is a value between 0 and ‘MAX_INIT_PRIORITY’; otherwise it must be ‘DEFAULT_INIT_PRIORITY’. If this macro is not defined by the target, a suitable default will be chosen if (1) the target supports arbitrary section names, (2) the target defines ‘CTORS_SECTION_ASM_OP’, or (3) ‘USE_COLLECT2’ is not defined. -- Target Hook: void TARGET_ASM_DESTRUCTOR (rtx SYMBOL, int PRIORITY) This is like ‘TARGET_ASM_CONSTRUCTOR’ but used for termination functions rather than initialization functions. If ‘TARGET_HAVE_CTORS_DTORS’ is true, the initialization routine generated for the generated object file will have static linkage. If your system uses ‘collect2’ as the means of processing constructors, then that program normally uses ‘nm’ to scan an object file for constructor functions to be called. On certain kinds of systems, you can define this macro to make ‘collect2’ work faster (and, in some cases, make it work at all): -- Macro: OBJECT_FORMAT_COFF Define this macro if the system uses COFF (Common Object File Format) object files, so that ‘collect2’ can assume this format and scan object files directly for dynamic constructor/destructor functions. This macro is effective only in a native compiler; ‘collect2’ as part of a cross compiler always uses ‘nm’ for the target machine. -- Macro: REAL_NM_FILE_NAME Define this macro as a C string constant containing the file name to use to execute ‘nm’. The default is to search the path normally for ‘nm’. -- Macro: NM_FLAGS ‘collect2’ calls ‘nm’ to scan object files for static constructors and destructors and LTO info. By default, ‘-n’ is passed. Define ‘NM_FLAGS’ to a C string constant if other options are needed to get the same output format as GNU ‘nm -n’ produces. If your system supports shared libraries and has a program to list the dynamic dependencies of a given library or executable, you can define these macros to enable support for running initialization and termination functions in shared libraries: -- Macro: LDD_SUFFIX Define this macro to a C string constant containing the name of the program which lists dynamic dependencies, like ‘ldd’ under SunOS 4. -- Macro: PARSE_LDD_OUTPUT (PTR) Define this macro to be C code that extracts filenames from the output of the program denoted by ‘LDD_SUFFIX’. PTR is a variable of type ‘char *’ that points to the beginning of a line of output from ‘LDD_SUFFIX’. If the line lists a dynamic dependency, the code must advance PTR to the beginning of the filename on that line. Otherwise, it must set PTR to ‘NULL’. -- Macro: SHLIB_SUFFIX Define this macro to a C string constant containing the default shared library extension of the target (e.g., ‘".so"’). ‘collect2’ strips version information after this suffix when generating global constructor and destructor names. This define is only needed on targets that use ‘collect2’ to process constructors and destructors.  File: gccint.info, Node: Instruction Output, Next: Dispatch Tables, Prev: Macros for Initialization, Up: Assembler Format 18.20.7 Output of Assembler Instructions ---------------------------------------- This describes assembler instruction output. -- Macro: REGISTER_NAMES A C initializer containing the assembler's names for the machine registers, each one as a C string constant. This is what translates register numbers in the compiler into assembler language. -- Macro: ADDITIONAL_REGISTER_NAMES If defined, a C initializer for an array of structures containing a name and a register number. This macro defines additional names for hard registers, thus allowing the ‘asm’ option in declarations to refer to registers using alternate names. -- Macro: OVERLAPPING_REGISTER_NAMES If defined, a C initializer for an array of structures containing a name, a register number and a count of the number of consecutive machine registers the name overlaps. This macro defines additional names for hard registers, thus allowing the ‘asm’ option in declarations to refer to registers using alternate names. Unlike ‘ADDITIONAL_REGISTER_NAMES’, this macro should be used when the register name implies multiple underlying registers. This macro should be used when it is important that a clobber in an ‘asm’ statement clobbers all the underlying values implied by the register name. For example, on ARM, clobbering the double-precision VFP register "d0" implies clobbering both single-precision registers "s0" and "s1". -- Macro: ASM_OUTPUT_OPCODE (STREAM, PTR) Define this macro if you are using an unusual assembler that requires different names for the machine instructions. The definition is a C statement or statements which output an assembler instruction opcode to the stdio stream STREAM. The macro-operand PTR is a variable of type ‘char *’ which points to the opcode name in its "internal" form--the form that is written in the machine description. The definition should output the opcode name to STREAM, performing any translation you desire, and increment the variable PTR to point at the end of the opcode so that it will not be output twice. In fact, your macro definition may process less than the entire opcode name, or more than the opcode name; but if you want to process text that includes ‘%’-sequences to substitute operands, you must take care of the substitution yourself. Just be sure to increment PTR over whatever text should not be output normally. If you need to look at the operand values, they can be found as the elements of ‘recog_data.operand’. If the macro definition does nothing, the instruction is output in the usual way. -- Macro: FINAL_PRESCAN_INSN (INSN, OPVEC, NOPERANDS) If defined, a C statement to be executed just prior to the output of assembler code for INSN, to modify the extracted operands so they will be output differently. Here the argument OPVEC is the vector containing the operands extracted from INSN, and NOPERANDS is the number of elements of the vector which contain meaningful data for this insn. The contents of this vector are what will be used to convert the insn template into assembler code, so you can change the assembler output by changing the contents of the vector. This macro is useful when various assembler syntaxes share a single file of instruction patterns; by defining this macro differently, you can cause a large class of instructions to be output differently (such as with rearranged operands). Naturally, variations in assembler syntax affecting individual insn patterns ought to be handled by writing conditional output routines in those patterns. If this macro is not defined, it is equivalent to a null statement. -- Target Hook: void TARGET_ASM_FINAL_POSTSCAN_INSN (FILE *FILE, rtx_insn *INSN, rtx *OPVEC, int NOPERANDS) If defined, this target hook is a function which is executed just after the output of assembler code for INSN, to change the mode of the assembler if necessary. Here the argument OPVEC is the vector containing the operands extracted from INSN, and NOPERANDS is the number of elements of the vector which contain meaningful data for this insn. The contents of this vector are what was used to convert the insn template into assembler code, so you can change the assembler mode by checking the contents of the vector. -- Macro: PRINT_OPERAND (STREAM, X, CODE) A C compound statement to output to stdio stream STREAM the assembler syntax for an instruction operand X. X is an RTL expression. CODE is a value that can be used to specify one of several ways of printing the operand. It is used when identical operands must be printed differently depending on the context. CODE comes from the ‘%’ specification that was used to request printing of the operand. If the specification was just ‘%DIGIT’ then CODE is 0; if the specification was ‘%LTR DIGIT’ then CODE is the ASCII code for LTR. If X is a register, this macro should print the register's name. The names can be found in an array ‘reg_names’ whose type is ‘char *[]’. ‘reg_names’ is initialized from ‘REGISTER_NAMES’. When the machine description has a specification ‘%PUNCT’ (a ‘%’ followed by a punctuation character), this macro is called with a null pointer for X and the punctuation character for CODE. -- Macro: PRINT_OPERAND_PUNCT_VALID_P (CODE) A C expression which evaluates to true if CODE is a valid punctuation character for use in the ‘PRINT_OPERAND’ macro. If ‘PRINT_OPERAND_PUNCT_VALID_P’ is not defined, it means that no punctuation characters (except for the standard one, ‘%’) are used in this way. -- Macro: PRINT_OPERAND_ADDRESS (STREAM, X) A C compound statement to output to stdio stream STREAM the assembler syntax for an instruction operand that is a memory reference whose address is X. X is an RTL expression. On some machines, the syntax for a symbolic address depends on the section that the address refers to. On these machines, define the hook ‘TARGET_ENCODE_SECTION_INFO’ to store the information into the ‘symbol_ref’, and then check for it here. *Note Assembler Format::. -- Macro: DBR_OUTPUT_SEQEND (FILE) A C statement, to be executed after all slot-filler instructions have been output. If necessary, call ‘dbr_sequence_length’ to determine the number of slots filled in a sequence (zero if not currently outputting a sequence), to decide how many no-ops to output, or whatever. Don't define this macro if it has nothing to do, but it is helpful in reading assembly output if the extent of the delay sequence is made explicit (e.g. with white space). Note that output routines for instructions with delay slots must be prepared to deal with not being output as part of a sequence (i.e. when the scheduling pass is not run, or when no slot fillers could be found.) The variable ‘final_sequence’ is null when not processing a sequence, otherwise it contains the ‘sequence’ rtx being output. -- Macro: REGISTER_PREFIX -- Macro: LOCAL_LABEL_PREFIX -- Macro: USER_LABEL_PREFIX -- Macro: IMMEDIATE_PREFIX If defined, C string expressions to be used for the ‘%R’, ‘%L’, ‘%U’, and ‘%I’ options of ‘asm_fprintf’ (see ‘final.cc’). These are useful when a single ‘md’ file must support multiple assembler formats. In that case, the various ‘tm.h’ files can define these macros differently. -- Macro: ASM_FPRINTF_EXTENSIONS (FILE, ARGPTR, FORMAT) If defined this macro should expand to a series of ‘case’ statements which will be parsed inside the ‘switch’ statement of the ‘asm_fprintf’ function. This allows targets to define extra printf formats which may useful when generating their assembler statements. Note that uppercase letters are reserved for future generic extensions to asm_fprintf, and so are not available to target specific code. The output file is given by the parameter FILE. The varargs input pointer is ARGPTR and the rest of the format string, starting the character after the one that is being switched upon, is pointed to by FORMAT. -- Macro: ASSEMBLER_DIALECT If your target supports multiple dialects of assembler language (such as different opcodes), define this macro as a C expression that gives the numeric index of the assembler language dialect to use, with zero as the first variant. If this macro is defined, you may use constructs of the form ‘{option0|option1|option2...}’ in the output templates of patterns (*note Output Template::) or in the first argument of ‘asm_fprintf’. This construct outputs ‘option0’, ‘option1’, ‘option2’, etc., if the value of ‘ASSEMBLER_DIALECT’ is zero, one, two, etc. Any special characters within these strings retain their usual meaning. If there are fewer alternatives within the braces than the value of ‘ASSEMBLER_DIALECT’, the construct outputs nothing. If it's needed to print curly braces or ‘|’ character in assembler output directly, ‘%{’, ‘%}’ and ‘%|’ can be used. If you do not define this macro, the characters ‘{’, ‘|’ and ‘}’ do not have any special meaning when used in templates or operands to ‘asm_fprintf’. Define the macros ‘REGISTER_PREFIX’, ‘LOCAL_LABEL_PREFIX’, ‘USER_LABEL_PREFIX’ and ‘IMMEDIATE_PREFIX’ if you can express the variations in assembler language syntax with that mechanism. Define ‘ASSEMBLER_DIALECT’ and use the ‘{option0|option1}’ syntax if the syntax variant are larger and involve such things as different opcodes or operand order. -- Macro: ASM_OUTPUT_REG_PUSH (STREAM, REGNO) A C expression to output to STREAM some assembler code which will push hard register number REGNO onto the stack. The code need not be optimal, since this macro is used only when profiling. -- Macro: ASM_OUTPUT_REG_POP (STREAM, REGNO) A C expression to output to STREAM some assembler code which will pop hard register number REGNO off of the stack. The code need not be optimal, since this macro is used only when profiling.  File: gccint.info, Node: Dispatch Tables, Next: Exception Region Output, Prev: Instruction Output, Up: Assembler Format 18.20.8 Output of Dispatch Tables --------------------------------- This concerns dispatch tables. -- Macro: ASM_OUTPUT_ADDR_DIFF_ELT (STREAM, BODY, VALUE, REL) A C statement to output to the stdio stream STREAM an assembler pseudo-instruction to generate a difference between two labels. VALUE and REL are the numbers of two internal labels. The definitions of these labels are output using ‘(*targetm.asm_out.internal_label)’, and they must be printed in the same way here. For example, fprintf (STREAM, "\t.word L%d-L%d\n", VALUE, REL) You must provide this macro on machines where the addresses in a dispatch table are relative to the table's own address. If defined, GCC will also use this macro on all machines when producing PIC. BODY is the body of the ‘ADDR_DIFF_VEC’; it is provided so that the mode and flags can be read. -- Macro: ASM_OUTPUT_ADDR_VEC_ELT (STREAM, VALUE) This macro should be provided on machines where the addresses in a dispatch table are absolute. The definition should be a C statement to output to the stdio stream STREAM an assembler pseudo-instruction to generate a reference to a label. VALUE is the number of an internal label whose definition is output using ‘(*targetm.asm_out.internal_label)’. For example, fprintf (STREAM, "\t.word L%d\n", VALUE) -- Macro: ASM_OUTPUT_CASE_LABEL (STREAM, PREFIX, NUM, TABLE) Define this if the label before a jump-table needs to be output specially. The first three arguments are the same as for ‘(*targetm.asm_out.internal_label)’; the fourth argument is the jump-table which follows (a ‘jump_table_data’ containing an ‘addr_vec’ or ‘addr_diff_vec’). This feature is used on system V to output a ‘swbeg’ statement for the table. If this macro is not defined, these labels are output with ‘(*targetm.asm_out.internal_label)’. -- Macro: ASM_OUTPUT_CASE_END (STREAM, NUM, TABLE) Define this if something special must be output at the end of a jump-table. The definition should be a C statement to be executed after the assembler code for the table is written. It should write the appropriate code to stdio stream STREAM. The argument TABLE is the jump-table insn, and NUM is the label-number of the preceding label. If this macro is not defined, nothing special is output at the end of the jump-table. -- Target Hook: void TARGET_ASM_POST_CFI_STARTPROC (FILE *, TREE) This target hook is used to emit assembly strings required by the target after the .cfi_startproc directive. The first argument is the file stream to write the strings to and the second argument is the function's declaration. The expected use is to add more .cfi_* directives. The default is to not output any assembly strings. -- Target Hook: void TARGET_ASM_EMIT_UNWIND_LABEL (FILE *STREAM, tree DECL, int FOR_EH, int EMPTY) This target hook emits a label at the beginning of each FDE. It should be defined on targets where FDEs need special labels, and it should write the appropriate label, for the FDE associated with the function declaration DECL, to the stdio stream STREAM. The third argument, FOR_EH, is a boolean: true if this is for an exception table. The fourth argument, EMPTY, is a boolean: true if this is a placeholder label for an omitted FDE. The default is that FDEs are not given nonlocal labels. -- Target Hook: void TARGET_ASM_EMIT_EXCEPT_TABLE_LABEL (FILE *STREAM) This target hook emits a label at the beginning of the exception table. It should be defined on targets where it is desirable for the table to be broken up according to function. The default is that no label is emitted. -- Target Hook: void TARGET_ASM_EMIT_EXCEPT_PERSONALITY (rtx PERSONALITY) If the target implements ‘TARGET_ASM_UNWIND_EMIT’, this hook may be used to emit a directive to install a personality hook into the unwind info. This hook should not be used if dwarf2 unwind info is used. -- Target Hook: void TARGET_ASM_UNWIND_EMIT (FILE *STREAM, rtx_insn *INSN) This target hook emits assembly directives required to unwind the given instruction. This is only used when ‘TARGET_EXCEPT_UNWIND_INFO’ returns ‘UI_TARGET’. -- Target Hook: rtx TARGET_ASM_MAKE_EH_SYMBOL_INDIRECT (rtx ORIGSYMBOL, bool PUBVIS) If necessary, modify personality and LSDA references to handle indirection. The original symbol is in ‘origsymbol’ and if ‘pubvis’ is true the symbol is visible outside the TU. -- Target Hook: bool TARGET_ASM_UNWIND_EMIT_BEFORE_INSN True if the ‘TARGET_ASM_UNWIND_EMIT’ hook should be called before the assembly for INSN has been emitted, false if the hook should be called afterward. -- Target Hook: bool TARGET_ASM_SHOULD_RESTORE_CFA_STATE (void) For DWARF-based unwind frames, two CFI instructions provide for save and restore of register state. GCC maintains the current frame address (CFA) separately from the register bank but the unwinder in libgcc preserves this state along with the registers (and this is expected by the code that writes the unwind frames). This hook allows the target to specify that the CFA data is not saved/restored along with the registers by the target unwinder so that suitable additional instructions should be emitted to restore it.  File: gccint.info, Node: Exception Region Output, Next: Alignment Output, Prev: Dispatch Tables, Up: Assembler Format 18.20.9 Assembler Commands for Exception Regions ------------------------------------------------ This describes commands marking the start and the end of an exception region. -- Macro: EH_FRAME_SECTION_NAME If defined, a C string constant for the name of the section containing exception handling frame unwind information. If not defined, GCC will provide a default definition if the target supports named sections. ‘crtstuff.c’ uses this macro to switch to the appropriate section. You should define this symbol if your target supports DWARF 2 frame unwind information and the default definition does not work. -- Macro: EH_FRAME_THROUGH_COLLECT2 If defined, DWARF 2 frame unwind information will identified by specially named labels. The collect2 process will locate these labels and generate code to register the frames. This might be necessary, for instance, if the system linker will not place the eh_frames in-between the sentinals from ‘crtstuff.c’, or if the system linker does garbage collection and sections cannot be marked as not to be collected. -- Macro: EH_TABLES_CAN_BE_READ_ONLY Define this macro to 1 if your target is such that no frame unwind information encoding used with non-PIC code will ever require a runtime relocation, but the linker may not support merging read-only and read-write sections into a single read-write section. -- Macro: MASK_RETURN_ADDR An rtx used to mask the return address found via ‘RETURN_ADDR_RTX’, so that it does not contain any extraneous set bits in it. -- Macro: DWARF2_UNWIND_INFO Define this macro to 0 if your target supports DWARF 2 frame unwind information, but it does not yet work with exception handling. Otherwise, if your target supports this information (if it defines ‘INCOMING_RETURN_ADDR_RTX’ and ‘OBJECT_FORMAT_ELF’), GCC will provide a default definition of 1. -- Common Target Hook: enum unwind_info_type TARGET_EXCEPT_UNWIND_INFO (struct gcc_options *OPTS) This hook defines the mechanism that will be used for exception handling by the target. If the target has ABI specified unwind tables, the hook should return ‘UI_TARGET’. If the target is to use the ‘setjmp’/‘longjmp’-based exception handling scheme, the hook should return ‘UI_SJLJ’. If the target supports DWARF 2 frame unwind information, the hook should return ‘UI_DWARF2’. A target may, if exceptions are disabled, choose to return ‘UI_NONE’. This may end up simplifying other parts of target-specific code. The default implementation of this hook never returns ‘UI_NONE’. Note that the value returned by this hook should be constant. It should not depend on anything except the command-line switches described by OPTS. In particular, the setting ‘UI_SJLJ’ must be fixed at compiler start-up as C pre-processor macros and builtin functions related to exception handling are set up depending on this setting. The default implementation of the hook first honors the ‘--enable-sjlj-exceptions’ configure option, then ‘DWARF2_UNWIND_INFO’, and finally defaults to ‘UI_SJLJ’. If ‘DWARF2_UNWIND_INFO’ depends on command-line options, the target must define this hook so that OPTS is used correctly. -- Common Target Hook: bool TARGET_UNWIND_TABLES_DEFAULT This variable should be set to ‘true’ if the target ABI requires unwinding tables even when exceptions are not used. It must not be modified by command-line option processing. -- Macro: DONT_USE_BUILTIN_SETJMP Define this macro to 1 if the ‘setjmp’/‘longjmp’-based scheme should use the ‘setjmp’/‘longjmp’ functions from the C library instead of the ‘__builtin_setjmp’/‘__builtin_longjmp’ machinery. -- Macro: JMP_BUF_SIZE This macro has no effect unless ‘DONT_USE_BUILTIN_SETJMP’ is also defined. Define this macro if the default size of ‘jmp_buf’ buffer for the ‘setjmp’/‘longjmp’-based exception handling mechanism is not large enough, or if it is much too large. The default size is ‘FIRST_PSEUDO_REGISTER * sizeof(void *)’. -- Macro: DWARF_CIE_DATA_ALIGNMENT This macro need only be defined if the target might save registers in the function prologue at an offset to the stack pointer that is not aligned to ‘UNITS_PER_WORD’. The definition should be the negative minimum alignment if ‘STACK_GROWS_DOWNWARD’ is true, and the positive minimum alignment otherwise. *Note DWARF::. Only applicable if the target supports DWARF 2 frame unwind information. -- Target Hook: bool TARGET_TERMINATE_DW2_EH_FRAME_INFO Contains the value true if the target should add a zero word onto the end of a Dwarf-2 frame info section when used for exception handling. Default value is false if ‘EH_FRAME_SECTION_NAME’ is defined, and true otherwise. -- Target Hook: rtx TARGET_DWARF_REGISTER_SPAN (rtx REG) Given a register, this hook should return a parallel of registers to represent where to find the register pieces. Define this hook if the register and its mode are represented in Dwarf in non-contiguous locations, or if the register should be represented in more than one register in Dwarf. Otherwise, this hook should return ‘NULL_RTX’. If not defined, the default is to return ‘NULL_RTX’. -- Target Hook: machine_mode TARGET_DWARF_FRAME_REG_MODE (int REGNO) Given a register, this hook should return the mode which the corresponding Dwarf frame register should have. This is normally used to return a smaller mode than the raw mode to prevent call clobbered parts of a register altering the frame register size -- Target Hook: void TARGET_INIT_DWARF_REG_SIZES_EXTRA (tree ADDRESS) If some registers are represented in Dwarf-2 unwind information in multiple pieces, define this hook to fill in information about the sizes of those pieces in the table used by the unwinder at runtime. It will be called by ‘expand_builtin_init_dwarf_reg_sizes’ after filling in a single size corresponding to each hard register; ADDRESS is the address of the table. -- Target Hook: bool TARGET_ASM_TTYPE (rtx SYM) This hook is used to output a reference from a frame unwinding table to the type_info object identified by SYM. It should return ‘true’ if the reference was output. Returning ‘false’ will cause the reference to be output using the normal Dwarf2 routines. -- Target Hook: bool TARGET_ARM_EABI_UNWINDER This flag should be set to ‘true’ on targets that use an ARM EABI based unwinding library, and ‘false’ on other targets. This effects the format of unwinding tables, and how the unwinder in entered after running a cleanup. The default is ‘false’.  File: gccint.info, Node: Alignment Output, Prev: Exception Region Output, Up: Assembler Format 18.20.10 Assembler Commands for Alignment ----------------------------------------- This describes commands for alignment. -- Macro: JUMP_ALIGN (LABEL) The alignment (log base 2) to put in front of LABEL, which is a common destination of jumps and has no fallthru incoming edge. This macro need not be defined if you don't want any special alignment to be done at such a time. Most machine descriptions do not currently define the macro. Unless it's necessary to inspect the LABEL parameter, it is better to set the variable ALIGN_JUMPS in the target's ‘TARGET_OPTION_OVERRIDE’. Otherwise, you should try to honor the user's selection in ALIGN_JUMPS in a ‘JUMP_ALIGN’ implementation. -- Macro: LABEL_ALIGN_AFTER_BARRIER (LABEL) The alignment (log base 2) to put in front of LABEL, which follows a ‘BARRIER’. This macro need not be defined if you don't want any special alignment to be done at such a time. Most machine descriptions do not currently define the macro. -- Macro: LOOP_ALIGN (LABEL) The alignment (log base 2) to put in front of LABEL that heads a frequently executed basic block (usually the header of a loop). This macro need not be defined if you don't want any special alignment to be done at such a time. Most machine descriptions do not currently define the macro. Unless it's necessary to inspect the LABEL parameter, it is better to set the variable ‘align_loops’ in the target's ‘TARGET_OPTION_OVERRIDE’. Otherwise, you should try to honor the user's selection in ‘align_loops’ in a ‘LOOP_ALIGN’ implementation. -- Macro: LABEL_ALIGN (LABEL) The alignment (log base 2) to put in front of LABEL. If ‘LABEL_ALIGN_AFTER_BARRIER’ / ‘LOOP_ALIGN’ specify a different alignment, the maximum of the specified values is used. Unless it's necessary to inspect the LABEL parameter, it is better to set the variable ‘align_labels’ in the target's ‘TARGET_OPTION_OVERRIDE’. Otherwise, you should try to honor the user's selection in ‘align_labels’ in a ‘LABEL_ALIGN’ implementation. -- Macro: ASM_OUTPUT_SKIP (STREAM, NBYTES) A C statement to output to the stdio stream STREAM an assembler instruction to advance the location counter by NBYTES bytes. Those bytes should be zero when loaded. NBYTES will be a C expression of type ‘unsigned HOST_WIDE_INT’. -- Macro: ASM_NO_SKIP_IN_TEXT Define this macro if ‘ASM_OUTPUT_SKIP’ should not be used in the text section because it fails to put zeros in the bytes that are skipped. This is true on many Unix systems, where the pseudo-op to skip bytes produces no-op instructions rather than zeros when used in the text section. -- Macro: ASM_OUTPUT_ALIGN (STREAM, POWER) A C statement to output to the stdio stream STREAM an assembler command to advance the location counter to a multiple of 2 to the POWER bytes. POWER will be a C expression of type ‘int’. -- Macro: ASM_OUTPUT_ALIGN_WITH_NOP (STREAM, POWER) Like ‘ASM_OUTPUT_ALIGN’, except that the "nop" instruction is used for padding, if necessary. -- Macro: ASM_OUTPUT_MAX_SKIP_ALIGN (STREAM, POWER, MAX_SKIP) A C statement to output to the stdio stream STREAM an assembler command to advance the location counter to a multiple of 2 to the POWER bytes, but only if MAX_SKIP or fewer bytes are needed to satisfy the alignment request. POWER and MAX_SKIP will be a C expression of type ‘int’.  File: gccint.info, Node: Debugging Info, Next: Floating Point, Prev: Assembler Format, Up: Target Macros 18.21 Controlling Debugging Information Format ============================================== This describes how to specify debugging information. * Menu: * All Debuggers:: Macros that affect all debugging formats uniformly. * DWARF:: Macros for DWARF format. * VMS Debug:: Macros for VMS debug format. * CTF Debug:: Macros for CTF debug format. * BTF Debug:: Macros for BTF debug format.  File: gccint.info, Node: All Debuggers, Next: DWARF, Up: Debugging Info 18.21.1 Macros Affecting All Debugging Formats ---------------------------------------------- These macros affect all debugging formats. -- Macro: DEBUGGER_REGNO (REGNO) A C expression that returns the debugger register number for the compiler register number REGNO. In the default macro provided, the value of this expression will be REGNO itself. But sometimes there are some registers that the compiler knows about and debugger does not, or vice versa. In such cases, some register may need to have one number in the compiler and another for debugger. If two registers have consecutive numbers inside GCC, and they can be used as a pair to hold a multiword value, then they _must_ have consecutive numbers after renumbering with ‘DEBUGGER_REGNO’. Otherwise, debuggers will be unable to access such a pair, because they expect register pairs to be consecutive in their own numbering scheme. If you find yourself defining ‘DEBUGGER_REGNO’ in way that does not preserve register pairs, then what you must do instead is redefine the actual register numbering scheme. -- Macro: DEBUGGER_AUTO_OFFSET (X) A C expression that returns the integer offset value for an automatic variable having address X (an RTL expression). The default computation assumes that X is based on the frame-pointer and gives the offset from the frame-pointer. This is required for targets that produce debugging output for debugger and allow the frame-pointer to be eliminated when the ‘-g’ option is used. -- Macro: DEBUGGER_ARG_OFFSET (OFFSET, X) A C expression that returns the integer offset value for an argument having address X (an RTL expression). The nominal offset is OFFSET. -- Macro: PREFERRED_DEBUGGING_TYPE A C expression that returns the type of debugging output GCC should produce when the user specifies just ‘-g’. Define this if you have arranged for GCC to support more than one format of debugging output. Currently, the allowable values are ‘DWARF2_DEBUG’, ‘VMS_DEBUG’, and ‘VMS_AND_DWARF2_DEBUG’. When the user specifies ‘-ggdb’, GCC normally also uses the value of this macro to select the debugging output format, but with two exceptions. If ‘DWARF2_DEBUGGING_INFO’ is defined, GCC uses the value ‘DWARF2_DEBUG’. The value of this macro only affects the default debugging output; the user can always get a specific type of output by using ‘-gdwarf-2’, or ‘-gvms’. -- Macro: DEFAULT_GDB_EXTENSIONS Define this macro to control whether GCC should by default generate GDB's extended version of debugging information. If you don't define the macro, the default is 1: always generate the extended information if there is any occasion to.  File: gccint.info, Node: DWARF, Next: VMS Debug, Prev: All Debuggers, Up: Debugging Info 18.21.2 Macros for DWARF Output ------------------------------- Here are macros for DWARF output. -- Macro: DWARF2_DEBUGGING_INFO Define this macro if GCC should produce dwarf version 2 format debugging output in response to the ‘-g’ option. To support optional call frame debugging information, you must also define ‘INCOMING_RETURN_ADDR_RTX’ and either set ‘RTX_FRAME_RELATED_P’ on the prologue insns if you use RTL for the prologue, or call ‘dwarf2out_def_cfa’ and ‘dwarf2out_reg_save’ as appropriate from ‘TARGET_ASM_FUNCTION_PROLOGUE’ if you don't. -- Target Hook: int TARGET_DWARF_CALLING_CONVENTION (const_tree FUNCTION) Define this to enable the dwarf attribute ‘DW_AT_calling_convention’ to be emitted for each function. Instead of an integer return the enum value for the ‘DW_CC_’ tag. -- Macro: DWARF2_FRAME_INFO Define this macro to a nonzero value if GCC should always output Dwarf 2 frame information. If ‘TARGET_EXCEPT_UNWIND_INFO’ (*note Exception Region Output::) returns ‘UI_DWARF2’, and exceptions are enabled, GCC will output this information not matter how you define ‘DWARF2_FRAME_INFO’. -- Target Hook: enum unwind_info_type TARGET_DEBUG_UNWIND_INFO (void) This hook defines the mechanism that will be used for describing frame unwind information to the debugger. Normally the hook will return ‘UI_DWARF2’ if DWARF 2 debug information is enabled, and return ‘UI_NONE’ otherwise. A target may return ‘UI_DWARF2’ even when DWARF 2 debug information is disabled in order to always output DWARF 2 frame information. A target may return ‘UI_TARGET’ if it has ABI specified unwind tables. This will suppress generation of the normal debug frame unwind information. -- Macro: DWARF2_ASM_LINE_DEBUG_INFO Define this macro to be a nonzero value if the assembler can generate Dwarf 2 line debug info sections. This will result in much more compact line number tables, and hence is desirable if it works. -- Macro: DWARF2_ASM_VIEW_DEBUG_INFO Define this macro to be a nonzero value if the assembler supports view assignment and verification in ‘.loc’. If it does not, but the user enables location views, the compiler may have to fallback to internal line number tables. -- Target Hook: int TARGET_RESET_LOCATION_VIEW (rtx_insn *) This hook, if defined, enables -ginternal-reset-location-views, and uses its result to override cases in which the estimated min insn length might be nonzero even when a PC advance (i.e., a view reset) cannot be taken for granted. If the hook is defined, it must return a positive value to indicate the insn definitely advances the PC, and so the view number can be safely assumed to be reset; a negative value to mean the insn definitely does not advance the PC, and os the view number must not be reset; or zero to decide based on the estimated insn length. If insn length is to be regarded as reliable, set the hook to ‘hook_int_rtx_insn_0’. -- Target Hook: bool TARGET_WANT_DEBUG_PUB_SECTIONS True if the ‘.debug_pubtypes’ and ‘.debug_pubnames’ sections should be emitted. These sections are not used on most platforms, and in particular GDB does not use them. -- Target Hook: bool TARGET_DELAY_SCHED2 True if sched2 is not to be run at its normal place. This usually means it will be run as part of machine-specific reorg. -- Target Hook: bool TARGET_DELAY_VARTRACK True if vartrack is not to be run at its normal place. This usually means it will be run as part of machine-specific reorg. -- Target Hook: bool TARGET_NO_REGISTER_ALLOCATION True if register allocation and the passes following it should not be run. Usually true only for virtual assembler targets. -- Macro: ASM_OUTPUT_DWARF_DELTA (STREAM, SIZE, LABEL1, LABEL2) A C statement to issue assembly directives that create a difference LAB1 minus LAB2, using an integer of the given SIZE. -- Macro: ASM_OUTPUT_DWARF_VMS_DELTA (STREAM, SIZE, LABEL1, LABEL2) A C statement to issue assembly directives that create a difference between the two given labels in system defined units, e.g. instruction slots on IA64 VMS, using an integer of the given size. -- Macro: ASM_OUTPUT_DWARF_OFFSET (STREAM, SIZE, LABEL, OFFSET, SECTION) A C statement to issue assembly directives that create a section-relative reference to the given LABEL plus OFFSET, using an integer of the given SIZE. The label is known to be defined in the given SECTION. -- Macro: ASM_OUTPUT_DWARF_PCREL (STREAM, SIZE, LABEL) A C statement to issue assembly directives that create a self-relative reference to the given LABEL, using an integer of the given SIZE. -- Macro: ASM_OUTPUT_DWARF_DATAREL (STREAM, SIZE, LABEL) A C statement to issue assembly directives that create a reference to the given LABEL relative to the dbase, using an integer of the given SIZE. -- Macro: ASM_OUTPUT_DWARF_TABLE_REF (LABEL) A C statement to issue assembly directives that create a reference to the DWARF table identifier LABEL from the current section. This is used on some systems to avoid garbage collecting a DWARF table which is referenced by a function. -- Target Hook: void TARGET_ASM_OUTPUT_DWARF_DTPREL (FILE *FILE, int SIZE, rtx X) If defined, this target hook is a function which outputs a DTP-relative reference to the given TLS symbol of the specified size.  File: gccint.info, Node: VMS Debug, Next: CTF Debug, Prev: DWARF, Up: Debugging Info 18.21.3 Macros for VMS Debug Format ----------------------------------- Here are macros for VMS debug format. -- Macro: VMS_DEBUGGING_INFO Define this macro if GCC should produce debugging output for VMS in response to the ‘-g’ option. The default behavior for VMS is to generate minimal debug info for a traceback in the absence of ‘-g’ unless explicitly overridden with ‘-g0’. This behavior is controlled by ‘TARGET_OPTION_OPTIMIZATION’ and ‘TARGET_OPTION_OVERRIDE’.  File: gccint.info, Node: CTF Debug, Next: BTF Debug, Prev: VMS Debug, Up: Debugging Info 18.21.4 Macros for CTF Debug Format ----------------------------------- Here are macros for CTF debug format. -- Macro: CTF_DEBUGGING_INFO Define this macro if GCC should produce debugging output in CTF debug format in response to the ‘-gctf’ option.  File: gccint.info, Node: BTF Debug, Prev: CTF Debug, Up: Debugging Info 18.21.5 Macros for BTF Debug Format ----------------------------------- Here are macros for BTF debug format. -- Macro: BTF_DEBUGGING_INFO Define this macro if GCC should produce debugging output in BTF debug format in response to the ‘-gbtf’ option.  File: gccint.info, Node: Floating Point, Next: Mode Switching, Prev: Debugging Info, Up: Target Macros 18.22 Cross Compilation and Floating Point ========================================== While all modern machines use twos-complement representation for integers, there are a variety of representations for floating point numbers. This means that in a cross-compiler the representation of floating point numbers in the compiled program may be different from that used in the machine doing the compilation. Because different representation systems may offer different amounts of range and precision, all floating point constants must be represented in the target machine's format. Therefore, the cross compiler cannot safely use the host machine's floating point arithmetic; it must emulate the target's arithmetic. To ensure consistency, GCC always uses emulation to work with floating point values, even when the host and target floating point formats are identical. The following macros are provided by ‘real.h’ for the compiler to use. All parts of the compiler which generate or optimize floating-point calculations must use these macros. They may evaluate their operands more than once, so operands must not have side effects. -- Macro: REAL_VALUE_TYPE The C data type to be used to hold a floating point value in the target machine's format. Typically this is a ‘struct’ containing an array of ‘HOST_WIDE_INT’, but all code should treat it as an opaque quantity. -- Macro: HOST_WIDE_INT REAL_VALUE_FIX (REAL_VALUE_TYPE X) Truncates X to a signed integer, rounding toward zero. -- Macro: unsigned HOST_WIDE_INT REAL_VALUE_UNSIGNED_FIX (REAL_VALUE_TYPE X) Truncates X to an unsigned integer, rounding toward zero. If X is negative, returns zero. -- Macro: REAL_VALUE_TYPE REAL_VALUE_ATOF (const char *STRING, machine_mode MODE) Converts STRING into a floating point number in the target machine's representation for mode MODE. This routine can handle both decimal and hexadecimal floating point constants, using the syntax defined by the C language for both. -- Macro: int REAL_VALUE_NEGATIVE (REAL_VALUE_TYPE X) Returns 1 if X is negative (including negative zero), 0 otherwise. -- Macro: int REAL_VALUE_ISINF (REAL_VALUE_TYPE X) Determines whether X represents infinity (positive or negative). -- Macro: int REAL_VALUE_ISNAN (REAL_VALUE_TYPE X) Determines whether X represents a "NaN" (not-a-number). -- Macro: REAL_VALUE_TYPE REAL_VALUE_NEGATE (REAL_VALUE_TYPE X) Returns the negative of the floating point value X. -- Macro: REAL_VALUE_TYPE REAL_VALUE_ABS (REAL_VALUE_TYPE X) Returns the absolute value of X.  File: gccint.info, Node: Mode Switching, Next: Target Attributes, Prev: Floating Point, Up: Target Macros 18.23 Mode Switching Instructions ================================= The following macros control mode switching optimizations: -- Macro: OPTIMIZE_MODE_SWITCHING (ENTITY) Define this macro if the port needs extra instructions inserted for mode switching. For an example, the SH4 can perform both single and double precision floating point operations, but to perform a single precision operation, the FPSCR PR bit has to be cleared, while for a double precision operation, this bit has to be set. Changing the PR bit requires a general purpose register as a scratch register, hence these FPSCR sets have to be inserted before reload, i.e. you cannot put this into instruction emitting or ‘TARGET_MACHINE_DEPENDENT_REORG’. You can have multiple entities that are mode-switched, some of which might only be needed conditionally. The entities are identified by their index into the ‘NUM_MODES_FOR_MODE_SWITCHING’ initializer, with the length of the initializer determining the number of entities. ‘OPTIMIZE_MODE_SWITCHING’ should return nonzero for any ENTITY that needs mode-switching. If you define this macro, you also have to define ‘NUM_MODES_FOR_MODE_SWITCHING’, ‘TARGET_MODE_NEEDED’, ‘TARGET_MODE_PRIORITY’ and ‘TARGET_MODE_EMIT’. The other macros in this section are optional. -- Macro: NUM_MODES_FOR_MODE_SWITCHING If you define ‘OPTIMIZE_MODE_SWITCHING’, you have to define this as initializer for an array of integers. Each initializer element N refers to an entity that needs mode switching, and specifies the number of different modes that are defined for that entity. The position of the element in the initializer--starting counting at zero--determines the integer that is used to refer to the mode-switched entity in question. Modes are represented as numbers 0 ... N − 1. In mode arguments and return values, N either represents an unknown mode or "no mode", depending on context. -- Target Hook: void TARGET_MODE_EMIT (int ENTITY, int MODE, int PREV_MODE, HARD_REG_SET REGS_LIVE) Generate one or more insns to set ENTITY to MODE. HARD_REG_LIVE is the set of hard registers live at the point where the insn(s) are to be inserted. PREV_MOXDE indicates the mode to switch from, or is the number of modes if the previous mode is not known. Sets of a lower numbered entity will be emitted before sets of a higher numbered entity to a mode of the same or lower priority. -- Target Hook: int TARGET_MODE_NEEDED (int ENTITY, rtx_insn *INSN, HARD_REG_SET REGS_LIVE) ENTITY is an integer specifying a mode-switched entity. If ‘OPTIMIZE_MODE_SWITCHING’ is defined, you must define this hook to return the mode that ENTITY must be switched into prior to the execution of INSN, or the number of modes if INSN has no such requirement. REGS_LIVE contains the set of hard registers that are live before INSN. -- Target Hook: int TARGET_MODE_AFTER (int ENTITY, int MODE, rtx_insn *INSN, HARD_REG_SET REGS_LIVE) ENTITY is an integer specifying a mode-switched entity. If this hook is defined, it is evaluated for every INSN during mode switching. It returns the mode that ENTITY is in after INSN has been executed. MODE is the mode that ENTITY was in before INSN was executed, taking account of TARGET_MODE_NEEDED. REGS_LIVE is the set of hard registers that are live after INSN has been executed. MODE is equal to the number of modes defined for ENTITY if the mode before INSN is unknown. The hook should likewise return the number of modes if it does not know what mode ENTITY has after INSN. Not defining the hook is equivalent to returning MODE. -- Target Hook: int TARGET_MODE_CONFLUENCE (int ENTITY, int MODE1, int MODE2) By default, the mode-switching pass assumes that a given entity's modes are mutually exclusive. This means that the pass can only tell ‘TARGET_MODE_EMIT’ about an entity's previous mode if all incoming paths of execution leave the entity in the same state. However, some entities might have overlapping, non-exclusive modes, so that it is sometimes possible to represent "mode MODE1 or mode MODE2" with something more specific than "mode not known". If this is true for at least one entity, you should define this hook and make it return a mode that includes MODE1 and MODE2 as possibilities. (The mode can include other possibilities too.) The hook should return the number of modes if no suitable mode exists for the given arguments. -- Target Hook: int TARGET_MODE_BACKPROP (int ENTITY, int MODE1, int MODE2) If defined, the mode-switching pass uses this hook to back-propagate mode requirements through blocks that have no mode requirements of their own. Specifically, MODE1 is the mode that ENTITY has on exit from a block B1 (say) and MODE2 is the mode that the next block requires ENTITY to have. B1 does not have any mode requirements of its own. The hook should return the mode that it prefers or requires ENTITY to have in B1, or the number of modes if there is no such requirement. If the hook returns a required mode for more than one of B1's outgoing edges, those modes are combined as for ‘TARGET_MODE_CONFLUENCE’. For example, suppose there is a "one-shot" entity that, for a given execution of a function, either stays off or makes exactly one transition from off to on. It is safe to make the transition at any time, but it is better not to do so unnecessarily. This hook allows the function to manage such an entity without having to track its state at runtime. Specifically. the entity would have two modes, 0 for off and 1 for on, with 2 representing "don't know". The system is forbidden from transitioning from 2 to 1, since 2 represents the possibility that the entity is already on (and the aim is to avoid having to emit code to check for that case). This hook would therefore return 1 when MODE1 is 2 and MODE2 is 1, which would force the entity to be on in the source block. Applying this inductively would remove all transitions in which the previous state is unknown. -- Target Hook: int TARGET_MODE_ENTRY (int ENTITY) If this hook is defined, it is evaluated for every ENTITY that needs mode switching. It should return the mode that ENTITY is guaranteed to be in on entry to the function, or the number of modes if there is no such guarantee. If ‘TARGET_MODE_ENTRY’ is defined then ‘TARGET_MODE_EXIT’ must be defined. -- Target Hook: int TARGET_MODE_EXIT (int ENTITY) If this hook is defined, it is evaluated for every ENTITY that needs mode switching. It should return the mode that ENTITY must be in on return from the function, or the number of modes if there is no such requirement. If ‘TARGET_MODE_EXIT’ is defined then ‘TARGET_MODE_ENTRY’ must be defined. -- Target Hook: int TARGET_MODE_EH_HANDLER (int ENTITY) If this hook is defined, it should return the mode that ENTITY is guaranteed to be in on entry to an exception handler, or the number of modes if there is no such guarantee. -- Target Hook: int TARGET_MODE_PRIORITY (int ENTITY, int N) This hook specifies the order in which modes for ENTITY are processed. 0 is the highest priority, ‘NUM_MODES_FOR_MODE_SWITCHING[ENTITY] - 1’ the lowest. The hook returns an integer designating a mode for ENTITY. For any fixed ENTITY, ‘mode_priority’ (ENTITY, N) shall be a bijection in 0 ... ‘num_modes_for_mode_switching[ENTITY] - 1’.  File: gccint.info, Node: Target Attributes, Next: Emulated TLS, Prev: Mode Switching, Up: Target Macros 18.24 Defining target-specific uses of ‘__attribute__’ ====================================================== Target-specific attributes may be defined for functions, data and types. These are described using the following target hooks; they also need to be documented in ‘extend.texi’. -- Target Hook: array_slice TARGET_ATTRIBUTE_TABLE If defined, this target hook provides an array of ‘scoped_attribute_spec’s (defined in ‘attribs.h’) that specify the machine-specific attributes for this target. The information includes some of the restrictions on the entities to which these attributes are applied and the arguments that the attributes take. In C and C++, these attributes are associated with two syntaxes: the traditional GNU ‘__attribute__’ syntax and the standard ‘[[]]’ syntax. Attributes that support the GNU syntax must be placed in the ‘gnu’ namespace. Such attributes can then also be written ‘[[gnu::...]]’. Attributes that use only the standard syntax should be placed in whichever namespace the attribute specification requires. For example, a target might choose to support vendor-specific ‘[[]]’ attributes that the vendor places in their own namespace. Targets that only define attributes in the ‘gnu’ namespace can uase the following shorthand to define the table: TARGET_GNU_ATTRIBUTES (CPU_ATTRIBUTE_TABLE, { { "ATTRIBUTE1", ... }, { "ATTRIBUTE2", ... }, ..., { "ATTRIBUTEN", ... }, }); -- Target Hook: bool TARGET_ATTRIBUTE_TAKES_IDENTIFIER_P (const_tree NAME) If defined, this target hook is a function which returns true if the machine-specific attribute named NAME expects an identifier given as its first argument to be passed on as a plain identifier, not subjected to name lookup. If this is not defined, the default is false for all machine-specific attributes. -- Target Hook: int TARGET_COMP_TYPE_ATTRIBUTES (const_tree TYPE1, const_tree TYPE2) If defined, this target hook is a function which returns zero if the attributes on TYPE1 and TYPE2 are incompatible, one if they are compatible, and two if they are nearly compatible (which causes a warning to be generated). If this is not defined, machine-specific attributes are supposed always to be compatible. -- Target Hook: void TARGET_SET_DEFAULT_TYPE_ATTRIBUTES (tree TYPE) If defined, this target hook is a function which assigns default attributes to the newly defined TYPE. -- Target Hook: tree TARGET_MERGE_TYPE_ATTRIBUTES (tree TYPE1, tree TYPE2) Define this target hook if the merging of type attributes needs special handling. If defined, the result is a list of the combined ‘TYPE_ATTRIBUTES’ of TYPE1 and TYPE2. It is assumed that ‘comptypes’ has already been called and returned 1. This function may call ‘merge_attributes’ to handle machine-independent merging. -- Target Hook: tree TARGET_MERGE_DECL_ATTRIBUTES (tree OLDDECL, tree NEWDECL) Define this target hook if the merging of decl attributes needs special handling. If defined, the result is a list of the combined ‘DECL_ATTRIBUTES’ of OLDDECL and NEWDECL. NEWDECL is a duplicate declaration of OLDDECL. Examples of when this is needed are when one attribute overrides another, or when an attribute is nullified by a subsequent definition. This function may call ‘merge_attributes’ to handle machine-independent merging. If the only target-specific handling you require is ‘dllimport’ for Microsoft Windows targets, you should define the macro ‘TARGET_DLLIMPORT_DECL_ATTRIBUTES’ to ‘1’. The compiler will then define a function called ‘merge_dllimport_decl_attributes’ which can then be defined as the expansion of ‘TARGET_MERGE_DECL_ATTRIBUTES’. You can also add ‘handle_dll_attribute’ in the attribute table for your port to perform initial processing of the ‘dllimport’ and ‘dllexport’ attributes. This is done in ‘i386/cygwin.h’ and ‘i386/i386.cc’, for example. -- Target Hook: bool TARGET_VALID_DLLIMPORT_ATTRIBUTE_P (const_tree DECL) DECL is a variable or function with ‘__attribute__((dllimport))’ specified. Use this hook if the target needs to add extra validation checks to ‘handle_dll_attribute’. -- Macro: TARGET_DECLSPEC Define this macro to a nonzero value if you want to treat ‘__declspec(X)’ as equivalent to ‘__attribute((X))’. By default, this behavior is enabled only for targets that define ‘TARGET_DLLIMPORT_DECL_ATTRIBUTES’. The current implementation of ‘__declspec’ is via a built-in macro, but you should not rely on this implementation detail. -- Target Hook: void TARGET_INSERT_ATTRIBUTES (tree NODE, tree *ATTR_PTR) Define this target hook if you want to be able to add attributes to a decl when it is being created. This is normally useful for back ends which wish to implement a pragma by using the attributes which correspond to the pragma's effect. The NODE argument is the decl which is being created. The ATTR_PTR argument is a pointer to the attribute list for this decl. The list itself should not be modified, since it may be shared with other decls, but attributes may be chained on the head of the list and ‘*ATTR_PTR’ modified to point to the new attributes, or a copy of the list may be made if further changes are needed. -- Target Hook: tree TARGET_HANDLE_GENERIC_ATTRIBUTE (tree *NODE, tree NAME, tree ARGS, int FLAGS, bool *NO_ADD_ATTRS) Define this target hook if you want to be able to perform additional target-specific processing of an attribute which is handled generically by a front end. The arguments are the same as those which are passed to attribute handlers. So far this only affects the NOINIT and SECTION attribute. -- Target Hook: bool TARGET_FUNCTION_ATTRIBUTE_INLINABLE_P (const_tree FNDECL) This target hook returns ‘true’ if it is OK to inline FNDECL into the current function, despite its having target-specific attributes, ‘false’ otherwise. By default, if a function has a target specific attribute attached to it, it will not be inlined. -- Target Hook: bool TARGET_OPTION_VALID_ATTRIBUTE_P (tree FNDECL, tree NAME, tree ARGS, int FLAGS) This hook is called to parse ‘attribute(target("..."))’, which allows setting target-specific options on individual functions. These function-specific options may differ from the options specified on the command line. The hook should return ‘true’ if the options are valid. The hook should set the ‘DECL_FUNCTION_SPECIFIC_TARGET’ field in the function declaration to hold a pointer to a target-specific ‘struct cl_target_option’ structure. -- Target Hook: bool TARGET_OPTION_VALID_VERSION_ATTRIBUTE_P (tree FNDECL, tree NAME, tree ARGS, int FLAGS) This hook is called to parse ‘attribute(target_version("..."))’, which allows setting target-specific options on individual function versions. These function-specific options may differ from the options specified on the command line. The hook should return ‘true’ if the options are valid. The hook should set the ‘DECL_FUNCTION_SPECIFIC_TARGET’ field in the function declaration to hold a pointer to a target-specific ‘struct cl_target_option’ structure. -- Target Hook: void TARGET_OPTION_SAVE (struct cl_target_option *PTR, struct gcc_options *OPTS, struct gcc_options *OPTS_SET) This hook is called to save any additional target-specific information in the ‘struct cl_target_option’ structure for function-specific options from the ‘struct gcc_options’ structure. *Note Option file format::. -- Target Hook: void TARGET_OPTION_RESTORE (struct gcc_options *OPTS, struct gcc_options *OPTS_SET, struct cl_target_option *PTR) This hook is called to restore any additional target-specific information in the ‘struct cl_target_option’ structure for function-specific options to the ‘struct gcc_options’ structure. -- Target Hook: void TARGET_OPTION_POST_STREAM_IN (struct cl_target_option *PTR) This hook is called to update target-specific information in the ‘struct cl_target_option’ structure after it is streamed in from LTO bytecode. -- Target Hook: void TARGET_OPTION_PRINT (FILE *FILE, int INDENT, struct cl_target_option *PTR) This hook is called to print any additional target-specific information in the ‘struct cl_target_option’ structure for function-specific options. -- Target Hook: bool TARGET_OPTION_PRAGMA_PARSE (tree ARGS, tree POP_TARGET) This target hook parses the options for ‘#pragma GCC target’, which sets the target-specific options for functions that occur later in the input stream. The options accepted should be the same as those handled by the ‘TARGET_OPTION_VALID_ATTRIBUTE_P’ hook. -- Target Hook: void TARGET_OPTION_OVERRIDE (void) Sometimes certain combinations of command options do not make sense on a particular target machine. You can override the hook ‘TARGET_OPTION_OVERRIDE’ to take account of this. This hooks is called once just after all the command options have been parsed. Don't use this hook to turn on various extra optimizations for ‘-O’. That is what ‘TARGET_OPTION_OPTIMIZATION’ is for. If you need to do something whenever the optimization level is changed via the optimize attribute or pragma, see ‘TARGET_OVERRIDE_OPTIONS_AFTER_CHANGE’ -- Target Hook: bool TARGET_OPTION_FUNCTION_VERSIONS (tree DECL1, tree DECL2) This target hook returns ‘true’ if DECL1 and DECL2 are versions of the same function. DECL1 and DECL2 are function versions if and only if they have the same function signature and different target specific attributes, that is, they are compiled for different target machines. -- Target Hook: bool TARGET_CAN_INLINE_P (tree CALLER, tree CALLEE) This target hook returns ‘false’ if the CALLER function cannot inline CALLEE, based on target specific information. By default, inlining is not allowed if the callee function has function specific target options and the caller does not use the same options. -- Target Hook: bool TARGET_UPDATE_IPA_FN_TARGET_INFO (unsigned int& INFO, const gimple* STMT) Allow target to analyze all gimple statements for the given function to record and update some target specific information for inlining. A typical example is that a caller with one isa feature disabled is normally not allowed to inline a callee with that same isa feature enabled even which is attributed by always_inline, but with the conservative analysis on all statements of the callee if we are able to guarantee the callee does not exploit any instructions from the mismatch isa feature, it would be safe to allow the caller to inline the callee. INFO is one ‘unsigned int’ value to record information in which one set bit indicates one corresponding feature is detected in the analysis, STMT is the statement being analyzed. Return true if target still need to analyze the subsequent statements, otherwise return false to stop subsequent analysis. The default version of this hook returns false. -- Target Hook: bool TARGET_NEED_IPA_FN_TARGET_INFO (const_tree DECL, unsigned int& INFO) Allow target to check early whether it is necessary to analyze all gimple statements in the given function to update target specific information for inlining. See hook ‘update_ipa_fn_target_info’ for usage example of target specific information. This hook is expected to be invoked ahead of the iterating with hook ‘update_ipa_fn_target_info’. DECL is the function being analyzed, INFO is the same as what in hook ‘update_ipa_fn_target_info’, target can do one time update into INFO without iterating for some case. Return true if target decides to analyze all gimple statements to collect information, otherwise return false. The default version of this hook returns false. -- Target Hook: void TARGET_RELAYOUT_FUNCTION (tree FNDECL) This target hook fixes function FNDECL after attributes are processed. Default does nothing. On ARM, the default function's alignment is updated with the attribute target.  File: gccint.info, Node: Emulated TLS, Next: MIPS Coprocessors, Prev: Target Attributes, Up: Target Macros 18.25 Emulating TLS =================== For targets whose psABI does not provide Thread Local Storage via specific relocations and instruction sequences, an emulation layer is used. A set of target hooks allows this emulation layer to be configured for the requirements of a particular target. For instance the psABI may in fact specify TLS support in terms of an emulation layer. The emulation layer works by creating a control object for every TLS object. To access the TLS object, a lookup function is provided which, when given the address of the control object, will return the address of the current thread's instance of the TLS object. -- Target Hook: const char * TARGET_EMUTLS_GET_ADDRESS Contains the name of the helper function that uses a TLS control object to locate a TLS instance. The default causes libgcc's emulated TLS helper function to be used. -- Target Hook: const char * TARGET_EMUTLS_REGISTER_COMMON Contains the name of the helper function that should be used at program startup to register TLS objects that are implicitly initialized to zero. If this is ‘NULL’, all TLS objects will have explicit initializers. The default causes libgcc's emulated TLS registration function to be used. -- Target Hook: const char * TARGET_EMUTLS_VAR_SECTION Contains the name of the section in which TLS control variables should be placed. The default of ‘NULL’ allows these to be placed in any section. -- Target Hook: const char * TARGET_EMUTLS_TMPL_SECTION Contains the name of the section in which TLS initializers should be placed. The default of ‘NULL’ allows these to be placed in any section. -- Target Hook: const char * TARGET_EMUTLS_VAR_PREFIX Contains the prefix to be prepended to TLS control variable names. The default of ‘NULL’ uses a target-specific prefix. -- Target Hook: const char * TARGET_EMUTLS_TMPL_PREFIX Contains the prefix to be prepended to TLS initializer objects. The default of ‘NULL’ uses a target-specific prefix. -- Target Hook: tree TARGET_EMUTLS_VAR_FIELDS (tree TYPE, tree *NAME) Specifies a function that generates the FIELD_DECLs for a TLS control object type. TYPE is the RECORD_TYPE the fields are for and NAME should be filled with the structure tag, if the default of ‘__emutls_object’ is unsuitable. The default creates a type suitable for libgcc's emulated TLS function. -- Target Hook: tree TARGET_EMUTLS_VAR_INIT (tree VAR, tree DECL, tree TMPL_ADDR) Specifies a function that generates the CONSTRUCTOR to initialize a TLS control object. VAR is the TLS control object, DECL is the TLS object and TMPL_ADDR is the address of the initializer. The default initializes libgcc's emulated TLS control object. -- Target Hook: bool TARGET_EMUTLS_VAR_ALIGN_FIXED Specifies whether the alignment of TLS control variable objects is fixed and should not be increased as some backends may do to optimize single objects. The default is false. -- Target Hook: bool TARGET_EMUTLS_DEBUG_FORM_TLS_ADDRESS Specifies whether a DWARF ‘DW_OP_form_tls_address’ location descriptor may be used to describe emulated TLS control objects.  File: gccint.info, Node: MIPS Coprocessors, Next: PCH Target, Prev: Emulated TLS, Up: Target Macros 18.26 Defining coprocessor specifics for MIPS targets. ====================================================== The MIPS specification allows MIPS implementations to have as many as 4 coprocessors, each with as many as 32 private registers. GCC supports accessing these registers and transferring values between the registers and memory using asm-ized variables. For example: register unsigned int cp0count asm ("c0r1"); unsigned int d; d = cp0count + 3; ("c0r1" is the default name of register 1 in coprocessor 0; alternate names may be added as described below, or the default names may be overridden entirely in ‘SUBTARGET_CONDITIONAL_REGISTER_USAGE’.) Coprocessor registers are assumed to be epilogue-used; sets to them will be preserved even if it does not appear that the register is used again later in the function. Another note: according to the MIPS spec, coprocessor 1 (if present) is the FPU. One accesses COP1 registers through standard mips floating-point support; they are not included in this mechanism.  File: gccint.info, Node: PCH Target, Next: C++ ABI, Prev: MIPS Coprocessors, Up: Target Macros 18.27 Parameters for Precompiled Header Validity Checking ========================================================= -- Target Hook: void * TARGET_GET_PCH_VALIDITY (size_t *SZ) This hook returns a pointer to the data needed by ‘TARGET_PCH_VALID_P’ and sets ‘*SZ’ to the size of the data in bytes. -- Target Hook: const char * TARGET_PCH_VALID_P (const void *DATA, size_t SZ) This hook checks whether the options used to create a PCH file are compatible with the current settings. It returns ‘NULL’ if so and a suitable error message if not. Error messages will be presented to the user and must be localized using ‘_(MSG)’. DATA is the data that was returned by ‘TARGET_GET_PCH_VALIDITY’ when the PCH file was created and SZ is the size of that data in bytes. It's safe to assume that the data was created by the same version of the compiler, so no format checking is needed. The default definition of ‘default_pch_valid_p’ should be suitable for most targets. -- Target Hook: const char * TARGET_CHECK_PCH_TARGET_FLAGS (int PCH_FLAGS) If this hook is nonnull, the default implementation of ‘TARGET_PCH_VALID_P’ will use it to check for compatible values of ‘target_flags’. PCH_FLAGS specifies the value that ‘target_flags’ had when the PCH file was created. The return value is the same as for ‘TARGET_PCH_VALID_P’. -- Target Hook: void TARGET_PREPARE_PCH_SAVE (void) Called before writing out a PCH file. If the target has some garbage-collected data that needs to be in a particular state on PCH loads, it can use this hook to enforce that state. Very few targets need to do anything here.  File: gccint.info, Node: C++ ABI, Next: D Language and ABI, Prev: PCH Target, Up: Target Macros 18.28 C++ ABI parameters ======================== -- Target Hook: tree TARGET_CXX_GUARD_TYPE (void) Define this hook to override the integer type used for guard variables. These are used to implement one-time construction of static objects. The default is long_long_integer_type_node. -- Target Hook: bool TARGET_CXX_GUARD_MASK_BIT (void) This hook determines how guard variables are used. It should return ‘false’ (the default) if the first byte should be used. A return value of ‘true’ indicates that only the least significant bit should be used. -- Target Hook: tree TARGET_CXX_GET_COOKIE_SIZE (tree TYPE) This hook returns the size of the cookie to use when allocating an array whose elements have the indicated TYPE. Assumes that it is already known that a cookie is needed. The default is ‘max(sizeof (size_t), alignof(type))’, as defined in section 2.7 of the IA64/Generic C++ ABI. -- Target Hook: bool TARGET_CXX_COOKIE_HAS_SIZE (void) This hook should return ‘true’ if the element size should be stored in array cookies. The default is to return ‘false’. -- Target Hook: int TARGET_CXX_IMPORT_EXPORT_CLASS (tree TYPE, int IMPORT_EXPORT) If defined by a backend this hook allows the decision made to export class TYPE to be overruled. Upon entry IMPORT_EXPORT will contain 1 if the class is going to be exported, −1 if it is going to be imported and 0 otherwise. This function should return the modified value and perform any other actions necessary to support the backend's targeted operating system. -- Target Hook: bool TARGET_CXX_CDTOR_RETURNS_THIS (void) This hook should return ‘true’ if constructors and destructors return the address of the object created/destroyed. The default is to return ‘false’. -- Target Hook: bool TARGET_CXX_KEY_METHOD_MAY_BE_INLINE (void) This hook returns true if the key method for a class (i.e., the method which, if defined in the current translation unit, causes the virtual table to be emitted) may be an inline function. Under the standard Itanium C++ ABI the key method may be an inline function so long as the function is not declared inline in the class definition. Under some variants of the ABI, an inline function can never be the key method. The default is to return ‘true’. -- Target Hook: void TARGET_CXX_DETERMINE_CLASS_DATA_VISIBILITY (tree DECL) DECL is a virtual table, virtual table table, typeinfo object, or other similar implicit class data object that will be emitted with external linkage in this translation unit. No ELF visibility has been explicitly specified. If the target needs to specify a visibility other than that of the containing class, use this hook to set ‘DECL_VISIBILITY’ and ‘DECL_VISIBILITY_SPECIFIED’. -- Target Hook: bool TARGET_CXX_CLASS_DATA_ALWAYS_COMDAT (void) This hook returns true (the default) if virtual tables and other similar implicit class data objects are always COMDAT if they have external linkage. If this hook returns false, then class data for classes whose virtual table will be emitted in only one translation unit will not be COMDAT. -- Target Hook: bool TARGET_CXX_LIBRARY_RTTI_COMDAT (void) This hook returns true (the default) if the RTTI information for the basic types which is defined in the C++ runtime should always be COMDAT, false if it should not be COMDAT. -- Target Hook: bool TARGET_CXX_USE_AEABI_ATEXIT (void) This hook returns true if ‘__aeabi_atexit’ (as defined by the ARM EABI) should be used to register static destructors when ‘-fuse-cxa-atexit’ is in effect. The default is to return false to use ‘__cxa_atexit’. -- Target Hook: bool TARGET_CXX_USE_ATEXIT_FOR_CXA_ATEXIT (void) This hook returns true if the target ‘atexit’ function can be used in the same manner as ‘__cxa_atexit’ to register C++ static destructors. This requires that ‘atexit’-registered functions in shared libraries are run in the correct order when the libraries are unloaded. The default is to return false. -- Target Hook: void TARGET_CXX_ADJUST_CLASS_AT_DEFINITION (tree TYPE) TYPE is a C++ class (i.e., RECORD_TYPE or UNION_TYPE) that has just been defined. Use this hook to make adjustments to the class (eg, tweak visibility or perform any other required target modifications). -- Target Hook: tree TARGET_CXX_DECL_MANGLING_CONTEXT (const_tree DECL) Return target-specific mangling context of DECL or ‘NULL_TREE’.  File: gccint.info, Node: D Language and ABI, Next: Rust Language and ABI, Prev: C++ ABI, Up: Target Macros 18.29 D ABI parameters ====================== -- D Target Hook: void TARGET_D_CPU_VERSIONS (void) Declare all environmental version identifiers relating to the target CPU using the function ‘builtin_version’, which takes a string representing the name of the version. Version identifiers predefined by this hook apply to all modules that are being compiled and imported. -- D Target Hook: void TARGET_D_OS_VERSIONS (void) Similarly to ‘TARGET_D_CPU_VERSIONS’, but is used for versions relating to the target operating system. -- D Target Hook: void TARGET_D_REGISTER_CPU_TARGET_INFO (void) Register all target information keys relating to the target CPU using the function ‘d_add_target_info_handlers’, which takes a ‘struct d_target_info_spec’ (defined in ‘d/d-target.h’). The keys added by this hook are made available at compile time by the ‘__traits(getTargetInfo)’ extension, the result is an expression describing the requested target information. -- D Target Hook: void TARGET_D_REGISTER_OS_TARGET_INFO (void) Same as ‘TARGET_D_CPU_TARGET_INFO’, but is used for keys relating to the target operating system. -- D Target Hook: const char * TARGET_D_MINFO_SECTION Contains the name of the section in which module info references should be placed. By default, the compiler puts all module info symbols in the ‘"minfo"’ section. Define this macro to override the string if a different section name should be used. This section is expected to be bracketed by two symbols ‘TARGET_D_MINFO_SECTION_START’ and ‘TARGET_D_MINFO_SECTION_END’ to indicate the start and end address of the section, so that the runtime library can collect all modules for each loaded shared library and executable. Setting the value to ‘NULL’ disables the use of sections for storing module info altogether. -- D Target Hook: const char * TARGET_D_MINFO_SECTION_START If ‘TARGET_D_MINFO_SECTION’ is defined, then this must also be defined as the name of the symbol indicating the start address of the module info section -- D Target Hook: const char * TARGET_D_MINFO_SECTION_END If ‘TARGET_D_MINFO_SECTION’ is defined, then this must also be defined as the name of the symbol indicating the end address of the module info section -- D Target Hook: bool TARGET_D_HAS_STDCALL_CONVENTION (unsigned int *LINK_SYSTEM, unsigned int *LINK_WINDOWS) Returns ‘true’ if the target supports the stdcall calling convention. The hook should also set LINK_SYSTEM to ‘1’ if the ‘stdcall’ attribute should be applied to functions with ‘extern(System)’ linkage, and LINK_WINDOWS to ‘1’ to apply ‘stdcall’ to functions with ‘extern(Windows)’ linkage. -- D Target Hook: bool TARGET_D_TEMPLATES_ALWAYS_COMDAT This flag is true if instantiated functions and variables are always COMDAT if they have external linkage. If this flag is false, then instantiated decls will be emitted as weak symbols. The default is ‘false’.  File: gccint.info, Node: Rust Language and ABI, Next: Named Address Spaces, Prev: D Language and ABI, Up: Target Macros 18.30 Rust ABI parameters ========================= -- Rust Target Hook: void TARGET_RUST_CPU_INFO (void) Declare all environmental CPU info and features relating to the target CPU using the function ‘rust_add_target_info’, which takes a string representing the feature key and a string representing the feature value. Configuration pairs predefined by this hook apply to all files that are being compiled. -- Rust Target Hook: void TARGET_RUST_OS_INFO (void) Similar to ‘TARGET_RUST_CPU_INFO’, but is used for configuration info relating to the target operating system.  File: gccint.info, Node: Named Address Spaces, Next: Misc, Prev: Rust Language and ABI, Up: Target Macros 18.31 Adding support for named address spaces ============================================= The draft technical report of the ISO/IEC JTC1 S22 WG14 N1275 standards committee, ‘Programming Languages - C - Extensions to support embedded processors’, specifies a syntax for embedded processors to specify alternate address spaces. You can configure a GCC port to support section 5.1 of the draft report to add support for address spaces other than the default address space. These address spaces are new keywords that are similar to the ‘volatile’ and ‘const’ type attributes. Pointers to named address spaces can have a different size than pointers to the generic address space. For example, the SPU port uses the ‘__ea’ address space to refer to memory in the host processor, rather than memory local to the SPU processor. Access to memory in the ‘__ea’ address space involves issuing DMA operations to move data between the host processor and the local processor memory address space. Pointers in the ‘__ea’ address space are either 32 bits or 64 bits based on the ‘-mea32’ or ‘-mea64’ switches (native SPU pointers are always 32 bits). Internally, address spaces are represented as a small integer in the range 0 to 15 with address space 0 being reserved for the generic address space. To register a named address space qualifier keyword with the C front end, the target may call the ‘c_register_addr_space’ routine. For example, the SPU port uses the following to declare ‘__ea’ as the keyword for named address space #1: #define ADDR_SPACE_EA 1 c_register_addr_space ("__ea", ADDR_SPACE_EA); -- Target Hook: scalar_int_mode TARGET_ADDR_SPACE_POINTER_MODE (addr_space_t ADDRESS_SPACE) Define this to return the machine mode to use for pointers to ADDRESS_SPACE if the target supports named address spaces. The default version of this hook returns ‘ptr_mode’. -- Target Hook: scalar_int_mode TARGET_ADDR_SPACE_ADDRESS_MODE (addr_space_t ADDRESS_SPACE) Define this to return the machine mode to use for addresses in ADDRESS_SPACE if the target supports named address spaces. The default version of this hook returns ‘Pmode’. -- Target Hook: bool TARGET_ADDR_SPACE_VALID_POINTER_MODE (scalar_int_mode MODE, addr_space_t AS) Define this to return nonzero if the port can handle pointers with machine mode MODE to address space AS. This target hook is the same as the ‘TARGET_VALID_POINTER_MODE’ target hook, except that it includes explicit named address space support. The default version of this hook returns true for the modes returned by either the ‘TARGET_ADDR_SPACE_POINTER_MODE’ or ‘TARGET_ADDR_SPACE_ADDRESS_MODE’ target hooks for the given address space. -- Target Hook: bool TARGET_ADDR_SPACE_LEGITIMATE_ADDRESS_P (machine_mode MODE, rtx EXP, bool STRICT, addr_space_t AS, code_helper CH) Define this to return true if EXP is a valid address for mode MODE in the named address space AS with the use context CH. The STRICT parameter says whether strict addressing is in effect after reload has finished. The CH indicates what context EXP will be used for. This target hook is the same as the ‘TARGET_LEGITIMATE_ADDRESS_P’ target hook, except that it includes explicit named address space support. -- Target Hook: rtx TARGET_ADDR_SPACE_LEGITIMIZE_ADDRESS (rtx X, rtx OLDX, machine_mode MODE, addr_space_t AS) Define this to modify an invalid address X to be a valid address with mode MODE in the named address space AS. This target hook is the same as the ‘TARGET_LEGITIMIZE_ADDRESS’ target hook, except that it includes explicit named address space support. -- Target Hook: bool TARGET_ADDR_SPACE_SUBSET_P (addr_space_t SUBSET, addr_space_t SUPERSET) Define this to return whether the SUBSET named address space is contained within the SUPERSET named address space. Pointers to a named address space that is a subset of another named address space will be converted automatically without a cast if used together in arithmetic operations. Pointers to a superset address space can be converted to pointers to a subset address space via explicit casts. -- Target Hook: bool TARGET_ADDR_SPACE_ZERO_ADDRESS_VALID (addr_space_t AS) Define this to modify the default handling of address 0 for the address space. Return true if 0 should be considered a valid address. -- Target Hook: rtx TARGET_ADDR_SPACE_CONVERT (rtx OP, tree FROM_TYPE, tree TO_TYPE) Define this to convert the pointer expression represented by the RTL OP with type FROM_TYPE that points to a named address space to a new pointer expression with type TO_TYPE that points to a different named address space. When this hook it called, it is guaranteed that one of the two address spaces is a subset of the other, as determined by the ‘TARGET_ADDR_SPACE_SUBSET_P’ target hook. -- Target Hook: int TARGET_ADDR_SPACE_DEBUG (addr_space_t AS) Define this to define how the address space is encoded in dwarf. The result is the value to be used with ‘DW_AT_address_class’. -- Target Hook: void TARGET_ADDR_SPACE_DIAGNOSE_USAGE (addr_space_t AS, location_t LOC) Define this hook if the availability of an address space depends on command line options and some diagnostics should be printed when the address space is used. This hook is called during parsing and allows to emit a better diagnostic compared to the case where the address space was not registered with ‘c_register_addr_space’. AS is the address space as registered with ‘c_register_addr_space’. LOC is the location of the address space qualifier token. The default implementation does nothing.  File: gccint.info, Node: Misc, Prev: Named Address Spaces, Up: Target Macros 18.32 Miscellaneous Parameters ============================== Here are several miscellaneous parameters. -- Macro: HAS_LONG_COND_BRANCH Define this boolean macro to indicate whether or not your architecture has conditional branches that can span all of memory. It is used in conjunction with an optimization that partitions hot and cold basic blocks into separate sections of the executable. If this macro is set to false, gcc will convert any conditional branches that attempt to cross between sections into unconditional branches or indirect jumps. -- Macro: HAS_LONG_UNCOND_BRANCH Define this boolean macro to indicate whether or not your architecture has unconditional branches that can span all of memory. It is used in conjunction with an optimization that partitions hot and cold basic blocks into separate sections of the executable. If this macro is set to false, gcc will convert any unconditional branches that attempt to cross between sections into indirect jumps. -- Macro: CASE_VECTOR_MODE An alias for a machine mode name. This is the machine mode that elements of a jump-table should have. -- Macro: CASE_VECTOR_SHORTEN_MODE (MIN_OFFSET, MAX_OFFSET, BODY) Optional: return the preferred mode for an ‘addr_diff_vec’ when the minimum and maximum offset are known. If you define this, it enables extra code in branch shortening to deal with ‘addr_diff_vec’. To make this work, you also have to define ‘INSN_ALIGN’ and make the alignment for ‘addr_diff_vec’ explicit. The BODY argument is provided so that the offset_unsigned and scale flags can be updated. -- Macro: CASE_VECTOR_PC_RELATIVE Define this macro to be a C expression to indicate when jump-tables should contain relative addresses. You need not define this macro if jump-tables never contain relative addresses, or jump-tables should contain relative addresses only when ‘-fPIC’ or ‘-fPIC’ is in effect. -- Target Hook: unsigned int TARGET_CASE_VALUES_THRESHOLD (void) This function return the smallest number of different values for which it is best to use a jump-table instead of a tree of conditional branches. The default is four for machines with a ‘casesi’ instruction and five otherwise. This is best for most machines. -- Macro: WORD_REGISTER_OPERATIONS Define this macro to 1 if operations between registers with integral mode smaller than a word are always performed on the entire register. To be more explicit, if you start with a pair of ‘word_mode’ registers with known values and you do a subword, for example ‘QImode’, addition on the low part of the registers, then the compiler may consider that the result has a known value in ‘word_mode’ too if the macro is defined to 1. Most RISC machines have this property and most CISC machines do not. -- Target Hook: unsigned int TARGET_MIN_ARITHMETIC_PRECISION (void) On some RISC architectures with 64-bit registers, the processor also maintains 32-bit condition codes that make it possible to do real 32-bit arithmetic, although the operations are performed on the full registers. On such architectures, defining this hook to 32 tells the compiler to try using 32-bit arithmetical operations setting the condition codes instead of doing full 64-bit arithmetic. More generally, define this hook on RISC architectures if you want the compiler to try using arithmetical operations setting the condition codes with a precision lower than the word precision. You need not define this hook if ‘WORD_REGISTER_OPERATIONS’ is not defined to 1. -- Macro: LOAD_EXTEND_OP (MEM_MODE) Define this macro to be a C expression indicating when insns that read memory in MEM_MODE, an integral mode narrower than a word, set the bits outside of MEM_MODE to be either the sign-extension or the zero-extension of the data read. Return ‘SIGN_EXTEND’ for values of MEM_MODE for which the insn sign-extends, ‘ZERO_EXTEND’ for which it zero-extends, and ‘UNKNOWN’ for other modes. This macro is not called with MEM_MODE non-integral or with a width greater than or equal to ‘BITS_PER_WORD’, so you may return any value in this case. Do not define this macro if it would always return ‘UNKNOWN’. On machines where this macro is defined, you will normally define it as the constant ‘SIGN_EXTEND’ or ‘ZERO_EXTEND’. You may return a non-‘UNKNOWN’ value even if for some hard registers the sign extension is not performed, if for the ‘REGNO_REG_CLASS’ of these hard registers ‘TARGET_CAN_CHANGE_MODE_CLASS’ returns false when the FROM mode is MEM_MODE and the TO mode is any integral mode larger than this but not larger than ‘word_mode’. You must return ‘UNKNOWN’ if for some hard registers that allow this mode, ‘TARGET_CAN_CHANGE_MODE_CLASS’ says that they cannot change to ‘word_mode’, but that they can change to another integral mode that is larger then MEM_MODE but still smaller than ‘word_mode’. -- Macro: SHORT_IMMEDIATES_SIGN_EXTEND Define this macro to 1 if loading short immediate values into registers sign extends. -- Target Hook: unsigned int TARGET_MIN_DIVISIONS_FOR_RECIP_MUL (machine_mode MODE) When ‘-ffast-math’ is in effect, GCC tries to optimize divisions by the same divisor, by turning them into multiplications by the reciprocal. This target hook specifies the minimum number of divisions that should be there for GCC to perform the optimization for a variable of mode MODE. The default implementation returns 3 if the machine has an instruction for the division, and 2 if it does not. -- Macro: MOVE_MAX The maximum number of bytes that a single instruction can move quickly between memory and registers or between two memory locations. -- Macro: MAX_MOVE_MAX The maximum number of bytes that a single instruction can move quickly between memory and registers or between two memory locations. If this is undefined, the default is ‘MOVE_MAX’. Otherwise, it is the constant value that is the largest value that ‘MOVE_MAX’ can have at run-time. -- Macro: SHIFT_COUNT_TRUNCATED A C expression that is nonzero if on this machine the number of bits actually used for the count of a shift operation is equal to the number of bits needed to represent the size of the object being shifted. When this macro is nonzero, the compiler will assume that it is safe to omit a sign-extend, zero-extend, and certain bitwise 'and' instructions that truncates the count of a shift operation. On machines that have instructions that act on bit-fields at variable positions, which may include 'bit test' instructions, a nonzero ‘SHIFT_COUNT_TRUNCATED’ also enables deletion of truncations of the values that serve as arguments to bit-field instructions. If both types of instructions truncate the count (for shifts) and position (for bit-field operations), or if no variable-position bit-field instructions exist, you should define this macro. However, on some machines, such as the 80386 and the 680x0, truncation only applies to shift operations and not the (real or pretended) bit-field operations. Define ‘SHIFT_COUNT_TRUNCATED’ to be zero on such machines. Instead, add patterns to the ‘md’ file that include the implied truncation of the shift instructions. You need not define this macro if it would always have the value of zero. -- Target Hook: unsigned HOST_WIDE_INT TARGET_SHIFT_TRUNCATION_MASK (machine_mode MODE) This function describes how the standard shift patterns for MODE deal with shifts by negative amounts or by more than the width of the mode. *Note shift patterns::. On many machines, the shift patterns will apply a mask M to the shift count, meaning that a fixed-width shift of X by Y is equivalent to an arbitrary-width shift of X by Y & M. If this is true for mode MODE, the function should return M, otherwise it should return 0. A return value of 0 indicates that no particular behavior is guaranteed. Note that, unlike ‘SHIFT_COUNT_TRUNCATED’, this function does _not_ apply to general shift rtxes; it applies only to instructions that are generated by the named shift patterns. The default implementation of this function returns ‘GET_MODE_BITSIZE (MODE) - 1’ if ‘SHIFT_COUNT_TRUNCATED’ and 0 otherwise. This definition is always safe, but if ‘SHIFT_COUNT_TRUNCATED’ is false, and some shift patterns nevertheless truncate the shift count, you may get better code by overriding it. -- Target Hook: bool TARGET_TRULY_NOOP_TRUNCATION (poly_uint64 OUTPREC, poly_uint64 INPREC) This hook returns true if it is safe to "convert" a value of INPREC bits to one of OUTPREC bits (where OUTPREC is smaller than INPREC) by merely operating on it as if it had only OUTPREC bits. The default returns true unconditionally, which is correct for most machines. When ‘TARGET_TRULY_NOOP_TRUNCATION’ returns false, the machine description should provide a ‘trunc’ optab to specify the RTL that performs the required truncation. If ‘TARGET_MODES_TIEABLE_P’ returns false for a pair of modes, suboptimal code can result if this hook returns true for the corresponding mode sizes. Making this hook return false in such cases may improve things. -- Target Hook: int TARGET_MODE_REP_EXTENDED (scalar_int_mode MODE, scalar_int_mode REP_MODE) The representation of an integral mode can be such that the values are always extended to a wider integral mode. Return ‘SIGN_EXTEND’ if values of MODE are represented in sign-extended form to REP_MODE. Return ‘UNKNOWN’ otherwise. (Currently, none of the targets use zero-extended representation this way so unlike ‘LOAD_EXTEND_OP’, ‘TARGET_MODE_REP_EXTENDED’ is expected to return either ‘SIGN_EXTEND’ or ‘UNKNOWN’. Also no target extends MODE to REP_MODE so that REP_MODE is not the next widest integral mode and currently we take advantage of this fact.) Similarly to ‘LOAD_EXTEND_OP’ you may return a non-‘UNKNOWN’ value even if the extension is not performed on certain hard registers as long as for the ‘REGNO_REG_CLASS’ of these hard registers ‘TARGET_CAN_CHANGE_MODE_CLASS’ returns false. Note that ‘TARGET_MODE_REP_EXTENDED’ and ‘LOAD_EXTEND_OP’ describe two related properties. If you define ‘TARGET_MODE_REP_EXTENDED (mode, word_mode)’ you probably also want to define ‘LOAD_EXTEND_OP (mode)’ to return the same type of extension. In order to enforce the representation of ‘mode’, ‘TARGET_TRULY_NOOP_TRUNCATION’ should return false when truncating to ‘mode’. -- Target Hook: bool TARGET_SETJMP_PRESERVES_NONVOLATILE_REGS_P (void) On some targets, it is assumed that the compiler will spill all pseudos that are live across a call to ‘setjmp’, while other targets treat ‘setjmp’ calls as normal function calls. This hook returns false if ‘setjmp’ calls do not preserve all non-volatile registers so that gcc that must spill all pseudos that are live across ‘setjmp’ calls. Define this to return true if the target does not need to spill all pseudos live across ‘setjmp’ calls. The default implementation conservatively assumes all pseudos must be spilled across ‘setjmp’ calls. -- Macro: STORE_FLAG_VALUE A C expression describing the value returned by a comparison operator with an integral mode and stored by a store-flag instruction (‘cstoreMODE4’) when the condition is true. This description must apply to _all_ the ‘cstoreMODE4’ patterns and all the comparison operators whose results have a ‘MODE_INT’ mode. A value of 1 or −1 means that the instruction implementing the comparison operator returns exactly 1 or −1 when the comparison is true and 0 when the comparison is false. Otherwise, the value indicates which bits of the result are guaranteed to be 1 when the comparison is true. This value is interpreted in the mode of the comparison operation, which is given by the mode of the first operand in the ‘cstoreMODE4’ pattern. Either the low bit or the sign bit of ‘STORE_FLAG_VALUE’ be on. Presently, only those bits are used by the compiler. If ‘STORE_FLAG_VALUE’ is neither 1 or −1, the compiler will generate code that depends only on the specified bits. It can also replace comparison operators with equivalent operations if they cause the required bits to be set, even if the remaining bits are undefined. For example, on a machine whose comparison operators return an ‘SImode’ value and where ‘STORE_FLAG_VALUE’ is defined as ‘0x80000000’, saying that just the sign bit is relevant, the expression (ne:SI (and:SI X (const_int POWER-OF-2)) (const_int 0)) can be converted to (ashift:SI X (const_int N)) where N is the appropriate shift count to move the bit being tested into the sign bit. There is no way to describe a machine that always sets the low-order bit for a true value, but does not guarantee the value of any other bits, but we do not know of any machine that has such an instruction. If you are trying to port GCC to such a machine, include an instruction to perform a logical-and of the result with 1 in the pattern for the comparison operators and let us know at . Often, a machine will have multiple instructions that obtain a value from a comparison (or the condition codes). Here are rules to guide the choice of value for ‘STORE_FLAG_VALUE’, and hence the instructions to be used: • Use the shortest sequence that yields a valid definition for ‘STORE_FLAG_VALUE’. It is more efficient for the compiler to "normalize" the value (convert it to, e.g., 1 or 0) than for the comparison operators to do so because there may be opportunities to combine the normalization with other operations. • For equal-length sequences, use a value of 1 or −1, with −1 being slightly preferred on machines with expensive jumps and 1 preferred on other machines. • As a second choice, choose a value of ‘0x80000001’ if instructions exist that set both the sign and low-order bits but do not define the others. • Otherwise, use a value of ‘0x80000000’. Many machines can produce both the value chosen for ‘STORE_FLAG_VALUE’ and its negation in the same number of instructions. On those machines, you should also define a pattern for those cases, e.g., one matching (set A (neg:M (ne:M B C))) Some machines can also perform ‘and’ or ‘plus’ operations on condition code values with less instructions than the corresponding ‘cstoreMODE4’ insn followed by ‘and’ or ‘plus’. On those machines, define the appropriate patterns. Use the names ‘incscc’ and ‘decscc’, respectively, for the patterns which perform ‘plus’ or ‘minus’ operations on condition code values. See ‘rs6000.md’ for some examples. The GNU Superoptimizer can be used to find such instruction sequences on other machines. If this macro is not defined, the default value, 1, is used. You need not define ‘STORE_FLAG_VALUE’ if the machine has no store-flag instructions, or if the value generated by these instructions is 1. -- Macro: FLOAT_STORE_FLAG_VALUE (MODE) A C expression that gives a nonzero ‘REAL_VALUE_TYPE’ value that is returned when comparison operators with floating-point results are true. Define this macro on machines that have comparison operations that return floating-point values. If there are no such operations, do not define this macro. -- Macro: VECTOR_STORE_FLAG_VALUE (MODE) A C expression that gives an rtx representing the nonzero true element for vector comparisons. The returned rtx should be valid for the inner mode of MODE which is guaranteed to be a vector mode. Define this macro on machines that have vector comparison operations that return a vector result. If there are no such operations, do not define this macro. Typically, this macro is defined as ‘const1_rtx’ or ‘constm1_rtx’. This macro may return ‘NULL_RTX’ to prevent the compiler optimizing such vector comparison operations for the given mode. -- Macro: CLZ_DEFINED_VALUE_AT_ZERO (MODE, VALUE) -- Macro: CTZ_DEFINED_VALUE_AT_ZERO (MODE, VALUE) A C expression that indicates whether the architecture defines a value for ‘clz’ or ‘ctz’ with a zero operand. A result of ‘0’ indicates the value is undefined. If the value is defined for only the RTL expression, the macro should evaluate to ‘1’; if the value applies also to the corresponding optab entry (which is normally the case if it expands directly into the corresponding RTL), then the macro should evaluate to ‘2’. In the cases where the value is defined, VALUE should be set to this value. If this macro is not defined, the value of ‘clz’ or ‘ctz’ at zero is assumed to be undefined. This macro must be defined if the target's expansion for ‘ffs’ relies on a particular value to get correct results. Otherwise it is not necessary, though it may be used to optimize some corner cases, and to provide a default expansion for the ‘ffs’ optab. Note that regardless of this macro the "definedness" of ‘clz’ and ‘ctz’ at zero do _not_ extend to the builtin functions visible to the user. Thus one may be free to adjust the value at will to match the target expansion of these operations without fear of breaking the API. -- Macro: Pmode An alias for the machine mode for pointers. On most machines, define this to be the integer mode corresponding to the width of a hardware pointer; ‘SImode’ on 32-bit machine or ‘DImode’ on 64-bit machines. On some machines you must define this to be one of the partial integer modes, such as ‘PSImode’. The width of ‘Pmode’ must be at least as large as the value of ‘POINTER_SIZE’. If it is not equal, you must define the macro ‘POINTERS_EXTEND_UNSIGNED’ to specify how pointers are extended to ‘Pmode’. -- Macro: FUNCTION_MODE An alias for the machine mode used for memory references to functions being called, in ‘call’ RTL expressions. On most CISC machines, where an instruction can begin at any byte address, this should be ‘QImode’. On most RISC machines, where all instructions have fixed size and alignment, this should be a mode with the same size and alignment as the machine instruction words - typically ‘SImode’ or ‘HImode’. -- Macro: STDC_0_IN_SYSTEM_HEADERS In normal operation, the preprocessor expands ‘__STDC__’ to the constant 1, to signify that GCC conforms to ISO Standard C. On some hosts, like Solaris, the system compiler uses a different convention, where ‘__STDC__’ is normally 0, but is 1 if the user specifies strict conformance to the C Standard. Defining ‘STDC_0_IN_SYSTEM_HEADERS’ makes GNU CPP follows the host convention when processing system header files, but when processing user files ‘__STDC__’ will always expand to 1. -- C Target Hook: const char * TARGET_C_PREINCLUDE (void) Define this hook to return the name of a header file to be included at the start of all compilations, as if it had been included with ‘#include ’. If this hook returns ‘NULL’, or is not defined, or the header is not found, or if the user specifies ‘-ffreestanding’ or ‘-nostdinc’, no header is included. This hook can be used together with a header provided by the system C library to implement ISO C requirements for certain macros to be predefined that describe properties of the whole implementation rather than just the compiler. -- C Target Hook: bool TARGET_CXX_IMPLICIT_EXTERN_C (const char*) Define this hook to add target-specific C++ implicit extern C functions. If this function returns true for the name of a file-scope function, that function implicitly gets extern "C" linkage rather than whatever language linkage the declaration would normally have. An example of such function is WinMain on Win32 targets. -- Macro: SYSTEM_IMPLICIT_EXTERN_C Define this macro if the system header files do not support C++. This macro handles system header files by pretending that system header files are enclosed in ‘extern "C" {...}’. -- Macro: REGISTER_TARGET_PRAGMAS () Define this macro if you want to implement any target-specific pragmas. If defined, it is a C expression which makes a series of calls to ‘c_register_pragma’ or ‘c_register_pragma_with_expansion’ for each pragma. The macro may also do any setup required for the pragmas. The primary reason to define this macro is to provide compatibility with other compilers for the same target. In general, we discourage definition of target-specific pragmas for GCC. If the pragma can be implemented by attributes then you should consider defining the target hook ‘TARGET_INSERT_ATTRIBUTES’ as well. Preprocessor macros that appear on pragma lines are not expanded. All ‘#pragma’ directives that do not match any registered pragma are silently ignored, unless the user specifies ‘-Wunknown-pragmas’. -- Function: void c_register_pragma (const char *SPACE, const char *NAME, void (*CALLBACK) (struct cpp_reader *)) -- Function: void c_register_pragma_with_expansion (const char *SPACE, const char *NAME, void (*CALLBACK) (struct cpp_reader *)) Each call to ‘c_register_pragma’ or ‘c_register_pragma_with_expansion’ establishes one pragma. The CALLBACK routine will be called when the preprocessor encounters a pragma of the form #pragma [SPACE] NAME ... SPACE is the case-sensitive namespace of the pragma, or ‘NULL’ to put the pragma in the global namespace. The callback routine receives PFILE as its first argument, which can be passed on to cpplib's functions if necessary. You can lex tokens after the NAME by calling ‘pragma_lex’. Tokens that are not read by the callback will be silently ignored. The end of the line is indicated by a token of type ‘CPP_EOF’. Macro expansion occurs on the arguments of pragmas registered with ‘c_register_pragma_with_expansion’ but not on the arguments of pragmas registered with ‘c_register_pragma’. Note that the use of ‘pragma_lex’ is specific to the C and C++ compilers. It will not work in the Java or Fortran compilers, or any other language compilers for that matter. Thus if ‘pragma_lex’ is going to be called from target-specific code, it must only be done so when building the C and C++ compilers. This can be done by defining the variables ‘c_target_objs’ and ‘cxx_target_objs’ in the target entry in the ‘config.gcc’ file. These variables should name the target-specific, language-specific object file which contains the code that uses ‘pragma_lex’. Note it will also be necessary to add a rule to the makefile fragment pointed to by ‘tmake_file’ that shows how to build this object file. -- Macro: HANDLE_PRAGMA_PACK_WITH_EXPANSION Define this macro if macros should be expanded in the arguments of ‘#pragma pack’. -- Macro: TARGET_DEFAULT_PACK_STRUCT If your target requires a structure packing default other than 0 (meaning the machine default), define this macro to the necessary value (in bytes). This must be a value that would also be valid to use with ‘#pragma pack()’ (that is, a small power of two). -- Macro: DOLLARS_IN_IDENTIFIERS Define this macro to control use of the character ‘$’ in identifier names for the C family of languages. 0 means ‘$’ is not allowed by default; 1 means it is allowed. 1 is the default; there is no need to define this macro in that case. -- Macro: INSN_SETS_ARE_DELAYED (INSN) Define this macro as a C expression that is nonzero if it is safe for the delay slot scheduler to place instructions in the delay slot of INSN, even if they appear to use a resource set or clobbered in INSN. INSN is always a ‘jump_insn’ or an ‘insn’; GCC knows that every ‘call_insn’ has this behavior. On machines where some ‘insn’ or ‘jump_insn’ is really a function call and hence has this behavior, you should define this macro. You need not define this macro if it would always return zero. -- Macro: INSN_REFERENCES_ARE_DELAYED (INSN) Define this macro as a C expression that is nonzero if it is safe for the delay slot scheduler to place instructions in the delay slot of INSN, even if they appear to set or clobber a resource referenced in INSN. INSN is always a ‘jump_insn’ or an ‘insn’. On machines where some ‘insn’ or ‘jump_insn’ is really a function call and its operands are registers whose use is actually in the subroutine it calls, you should define this macro. Doing so allows the delay slot scheduler to move instructions which copy arguments into the argument registers into the delay slot of INSN. You need not define this macro if it would always return zero. -- Macro: MULTIPLE_SYMBOL_SPACES Define this macro as a C expression that is nonzero if, in some cases, global symbols from one translation unit may not be bound to undefined symbols in another translation unit without user intervention. For instance, under Microsoft Windows symbols must be explicitly imported from shared libraries (DLLs). You need not define this macro if it would always evaluate to zero. -- Target Hook: rtx_insn * TARGET_MD_ASM_ADJUST (vec& OUTPUTS, vec& INPUTS, vec& INPUT_MODES, vec& CONSTRAINTS, vec& USESS, vec& CLOBBERS, HARD_REG_SET& CLOBBERED_REGS, location_t LOC) This target hook may add “clobbers” to CLOBBERS and CLOBBERED_REGS for any hard regs the port wishes to automatically clobber for an asm. It can also add hard registers that are used by the asm to USES. The OUTPUTS and INPUTS may be inspected to avoid clobbering a register that is already used by the asm. LOC is the source location of the asm. It may modify the OUTPUTS, INPUTS, INPUT_MODES, and CONSTRAINTS as necessary for other pre-processing. In this case the return value is a sequence of insns to emit after the asm. Note that changes to INPUTS must be accompanied by the corresponding changes to INPUT_MODES. -- Macro: MATH_LIBRARY Define this macro as a C string constant for the linker argument to link in the system math library, minus the initial ‘"-l"’, or ‘""’ if the target does not have a separate math library. You need only define this macro if the default of ‘"m"’ is wrong. -- Macro: LIBRARY_PATH_ENV Define this macro as a C string constant for the environment variable that specifies where the linker should look for libraries. You need only define this macro if the default of ‘"LIBRARY_PATH"’ is wrong. -- Macro: TARGET_POSIX_IO Define this macro if the target supports the following POSIX file functions, access, mkdir and file locking with fcntl / F_SETLKW. Defining ‘TARGET_POSIX_IO’ will enable the test coverage code to use file locking when exiting a program, which avoids race conditions if the program has forked. It will also create directories at run-time for cross-profiling. -- Macro: MAX_CONDITIONAL_EXECUTE A C expression for the maximum number of instructions to execute via conditional execution instructions instead of a branch. A value of ‘BRANCH_COST’+1 is the default. -- Macro: IFCVT_MODIFY_TESTS (CE_INFO, TRUE_EXPR, FALSE_EXPR) Used if the target needs to perform machine-dependent modifications on the conditionals used for turning basic blocks into conditionally executed code. CE_INFO points to a data structure, ‘struct ce_if_block’, which contains information about the currently processed blocks. TRUE_EXPR and FALSE_EXPR are the tests that are used for converting the then-block and the else-block, respectively. Set either TRUE_EXPR or FALSE_EXPR to a null pointer if the tests cannot be converted. -- Macro: IFCVT_MODIFY_MULTIPLE_TESTS (CE_INFO, BB, TRUE_EXPR, FALSE_EXPR) Like ‘IFCVT_MODIFY_TESTS’, but used when converting more complicated if-statements into conditions combined by ‘and’ and ‘or’ operations. BB contains the basic block that contains the test that is currently being processed and about to be turned into a condition. -- Macro: IFCVT_MODIFY_INSN (CE_INFO, PATTERN, INSN) A C expression to modify the PATTERN of an INSN that is to be converted to conditional execution format. CE_INFO points to a data structure, ‘struct ce_if_block’, which contains information about the currently processed blocks. -- Macro: IFCVT_MODIFY_FINAL (CE_INFO) A C expression to perform any final machine dependent modifications in converting code to conditional execution. The involved basic blocks can be found in the ‘struct ce_if_block’ structure that is pointed to by CE_INFO. -- Macro: IFCVT_MODIFY_CANCEL (CE_INFO) A C expression to cancel any machine dependent modifications in converting code to conditional execution. The involved basic blocks can be found in the ‘struct ce_if_block’ structure that is pointed to by CE_INFO. -- Macro: IFCVT_MACHDEP_INIT (CE_INFO) A C expression to initialize any machine specific data for if-conversion of the if-block in the ‘struct ce_if_block’ structure that is pointed to by CE_INFO. -- Target Hook: bool TARGET_USE_LATE_PROLOGUE_EPILOGUE () Return true if the current function's prologue and epilogue should be emitted late in the pass pipeline, instead of at the usual point. Normally, the prologue and epilogue sequences are introduced soon after register allocation is complete. The advantage of this approach is that it allows the prologue and epilogue instructions to be optimized and scheduled with other code in the function. However, some targets require the prologue and epilogue to be the first and last sequences executed by the function, with no variation allowed. This hook should return true on such targets. The default implementation returns false, which is correct for most targets. The hook should only return true if there is a specific target limitation that cannot be described in RTL. For example, the hook might return true if the prologue and epilogue need to switch between instruction sets. -- Target Hook: void TARGET_EMIT_EPILOGUE_FOR_SIBCALL (rtx_call_insn *CALL) If defined, this hook emits an epilogue sequence for sibling (tail) call instruction CALL. Another way of providing epilogues for sibling calls is to define the ‘sibcall_epilogue’ instruction pattern; the main advantage of this hook over the pattern is that it has access to the call instruction. -- Target Hook: void TARGET_MACHINE_DEPENDENT_REORG (void) If non-null, this hook performs a target-specific pass over the instruction stream. The compiler will run it at all optimization levels, just before the point at which it normally does delayed-branch scheduling. The exact purpose of the hook varies from target to target. Some use it to do transformations that are necessary for correctness, such as laying out in-function constant pools or avoiding hardware hazards. Others use it as an opportunity to do some machine-dependent optimizations. You need not implement the hook if it has nothing to do. The default definition is null. -- Target Hook: void TARGET_INIT_BUILTINS (void) Define this hook if you have any machine-specific built-in functions that need to be defined. It should be a function that performs the necessary setup. Machine specific built-in functions can be useful to expand special machine instructions that would otherwise not normally be generated because they have no equivalent in the source language (for example, SIMD vector instructions or prefetch instructions). To create a built-in function, call the function ‘lang_hooks.builtin_function’ which is defined by the language front end. You can use any type nodes set up by ‘build_common_tree_nodes’; only language front ends that use those two functions will call ‘TARGET_INIT_BUILTINS’. -- Target Hook: tree TARGET_BUILTIN_DECL (unsigned CODE, bool INITIALIZE_P) Define this hook if you have any machine-specific built-in functions that need to be defined. It should be a function that returns the builtin function declaration for the builtin function code CODE. If there is no such builtin and it cannot be initialized at this time if INITIALIZE_P is true the function should return ‘NULL_TREE’. If CODE is out of range the function should return ‘error_mark_node’. -- Target Hook: rtx TARGET_EXPAND_BUILTIN (tree EXP, rtx TARGET, rtx SUBTARGET, machine_mode MODE, int IGNORE) Expand a call to a machine specific built-in function that was set up by ‘TARGET_INIT_BUILTINS’. EXP is the expression for the function call; the result should go to TARGET if that is convenient, and have mode MODE if that is convenient. SUBTARGET may be used as the target for computing one of EXP's operands. IGNORE is nonzero if the value is to be ignored. This function should return the result of the call to the built-in function. -- Target Hook: tree TARGET_RESOLVE_OVERLOADED_BUILTIN (unsigned int LOC, tree FNDECL, void *ARGLIST) Select a replacement for a machine specific built-in function that was set up by ‘TARGET_INIT_BUILTINS’. This is done _before_ regular type checking, and so allows the target to implement a crude form of function overloading. FNDECL is the declaration of the built-in function. ARGLIST is the list of arguments passed to the built-in function. The result is a complete expression that implements the operation, usually another ‘CALL_EXPR’. ARGLIST really has type ‘VEC(tree,gc)*’ -- Target Hook: bool TARGET_CHECK_BUILTIN_CALL (location_t LOC, vec ARG_LOC, tree FNDECL, tree ORIG_FNDECL, unsigned int NARGS, tree *ARGS) Perform semantic checking on a call to a machine-specific built-in function after its arguments have been constrained to the function signature. Return true if the call is valid, otherwise report an error and return false. This hook is called after ‘TARGET_RESOLVE_OVERLOADED_BUILTIN’. The call was originally to built-in function ORIG_FNDECL, but after the optional ‘TARGET_RESOLVE_OVERLOADED_BUILTIN’ step is now to built-in function FNDECL. LOC is the location of the call and ARGS is an array of function arguments, of which there are NARGS. ARG_LOC specifies the location of each argument. -- Target Hook: tree TARGET_FOLD_BUILTIN (tree FNDECL, int N_ARGS, tree *ARGP, bool IGNORE) Fold a call to a machine specific built-in function that was set up by ‘TARGET_INIT_BUILTINS’. FNDECL is the declaration of the built-in function. N_ARGS is the number of arguments passed to the function; the arguments themselves are pointed to by ARGP. The result is another tree, valid for both GIMPLE and GENERIC, containing a simplified expression for the call's result. If IGNORE is true the value will be ignored. -- Target Hook: bool TARGET_GIMPLE_FOLD_BUILTIN (gimple_stmt_iterator *GSI) Fold a call to a machine specific built-in function that was set up by ‘TARGET_INIT_BUILTINS’. GSI points to the gimple statement holding the function call. Returns true if any change was made to the GIMPLE stream. -- Target Hook: int TARGET_COMPARE_VERSION_PRIORITY (tree DECL1, tree DECL2) This hook is used to compare the target attributes in two functions to determine which function's features get higher priority. This is used during function multi-versioning to figure out the order in which two versions must be dispatched. A function version with a higher priority is checked for dispatching earlier. DECL1 and DECL2 are the two function decls that will be compared. -- Target Hook: tree TARGET_GET_FUNCTION_VERSIONS_DISPATCHER (void *DECL) This hook is used to get the dispatcher function for a set of function versions. The dispatcher function is called to invoke the right function version at run-time. DECL is one version from a set of semantically identical versions. -- Target Hook: tree TARGET_GENERATE_VERSION_DISPATCHER_BODY (void *ARG) This hook is used to generate the dispatcher logic to invoke the right function version at run-time for a given set of function versions. ARG points to the callgraph node of the dispatcher function whose body must be generated. -- Target Hook: bool TARGET_PREDICT_DOLOOP_P (class loop *LOOP) Return true if we can predict it is possible to use a low-overhead loop for a particular loop. The parameter LOOP is a pointer to the loop. This target hook is required only when the target supports low-overhead loops, and will help ivopts to make some decisions. The default version of this hook returns false. -- Target Hook: bool TARGET_HAVE_COUNT_REG_DECR_P Return true if the target supports hardware count register for decrement and branch. The default value is false. -- Target Hook: int64_t TARGET_DOLOOP_COST_FOR_GENERIC One IV candidate dedicated for doloop is introduced in IVOPTs, we can calculate the computation cost of adopting it to any generic IV use by function get_computation_cost as before. But for targets which have hardware count register support for decrement and branch, it may have to move IV value from hardware count register to general purpose register while doloop IV candidate is used for generic IV uses. It probably takes expensive penalty. This hook allows target owners to define the cost for this especially for generic IV uses. The default value is zero. -- Target Hook: int64_t TARGET_DOLOOP_COST_FOR_ADDRESS One IV candidate dedicated for doloop is introduced in IVOPTs, we can calculate the computation cost of adopting it to any address IV use by function get_computation_cost as before. But for targets which have hardware count register support for decrement and branch, it may have to move IV value from hardware count register to general purpose register while doloop IV candidate is used for address IV uses. It probably takes expensive penalty. This hook allows target owners to define the cost for this escpecially for address IV uses. The default value is zero. -- Target Hook: bool TARGET_CAN_USE_DOLOOP_P (const widest_int &ITERATIONS, const widest_int &ITERATIONS_MAX, unsigned int LOOP_DEPTH, bool ENTERED_AT_TOP) Return true if it is possible to use low-overhead loops (‘doloop_end’ and ‘doloop_begin’) for a particular loop. ITERATIONS gives the exact number of iterations, or 0 if not known. ITERATIONS_MAX gives the maximum number of iterations, or 0 if not known. LOOP_DEPTH is the nesting depth of the loop, with 1 for innermost loops, 2 for loops that contain innermost loops, and so on. ENTERED_AT_TOP is true if the loop is only entered from the top. This hook is only used if ‘doloop_end’ is available. The default implementation returns true. You can use ‘can_use_doloop_if_innermost’ if the loop must be the innermost, and if there are no other restrictions. -- Target Hook: const char * TARGET_INVALID_WITHIN_DOLOOP (const rtx_insn *INSN) Take an instruction in INSN and return NULL if it is valid within a low-overhead loop, otherwise return a string explaining why doloop could not be applied. Many targets use special registers for low-overhead looping. For any instruction that clobbers these this function should return a string indicating the reason why the doloop could not be applied. By default, the RTL loop optimizer does not use a present doloop pattern for loops containing function calls or branch on table instructions. -- Target Hook: machine_mode TARGET_PREFERRED_DOLOOP_MODE (machine_mode MODE) This hook takes a MODE for a doloop IV, where ‘mode’ is the original mode for the operation. If the target prefers an alternate ‘mode’ for the operation, then this hook should return that mode; otherwise the original ‘mode’ should be returned. For example, on a 64-bit target, ‘DImode’ might be preferred over ‘SImode’. Both the original and the returned modes should be ‘MODE_INT’. -- Target Hook: bool TARGET_LEGITIMATE_COMBINED_INSN (rtx_insn *INSN) Take an instruction in INSN and return ‘false’ if the instruction is not appropriate as a combination of two or more instructions. The default is to accept all instructions. -- Target Hook: bool TARGET_CAN_FOLLOW_JUMP (const rtx_insn *FOLLOWER, const rtx_insn *FOLLOWEE) FOLLOWER and FOLLOWEE are JUMP_INSN instructions; return true if FOLLOWER may be modified to follow FOLLOWEE; false, if it can't. For example, on some targets, certain kinds of branches can't be made to follow through a hot/cold partitioning. -- Target Hook: bool TARGET_COMMUTATIVE_P (const_rtx X, int OUTER_CODE) This target hook returns ‘true’ if X is considered to be commutative. Usually, this is just COMMUTATIVE_P (X), but the HP PA doesn't consider PLUS to be commutative inside a MEM. OUTER_CODE is the rtx code of the enclosing rtl, if known, otherwise it is UNKNOWN. -- Target Hook: rtx TARGET_ALLOCATE_INITIAL_VALUE (rtx HARD_REG) When the initial value of a hard register has been copied in a pseudo register, it is often not necessary to actually allocate another register to this pseudo register, because the original hard register or a stack slot it has been saved into can be used. ‘TARGET_ALLOCATE_INITIAL_VALUE’ is called at the start of register allocation once for each hard register that had its initial value copied by using ‘get_func_hard_reg_initial_val’ or ‘get_hard_reg_initial_val’. Possible values are ‘NULL_RTX’, if you don't want to do any special allocation, a ‘REG’ rtx--that would typically be the hard register itself, if it is known not to be clobbered--or a ‘MEM’. If you are returning a ‘MEM’, this is only a hint for the allocator; it might decide to use another register anyways. You may use ‘current_function_is_leaf’ or ‘REG_N_SETS’ in the hook to determine if the hard register in question will not be clobbered. The default value of this hook is ‘NULL’, which disables any special allocation. -- Target Hook: int TARGET_UNSPEC_MAY_TRAP_P (const_rtx X, unsigned FLAGS) This target hook returns nonzero if X, an ‘unspec’ or ‘unspec_volatile’ operation, might cause a trap. Targets can use this hook to enhance precision of analysis for ‘unspec’ and ‘unspec_volatile’ operations. You may call ‘may_trap_p_1’ to analyze inner elements of X in which case FLAGS should be passed along. -- Target Hook: void TARGET_SET_CURRENT_FUNCTION (tree DECL) The compiler invokes this hook whenever it changes its current function context (‘cfun’). You can define this function if the back end needs to perform any initialization or reset actions on a per-function basis. For example, it may be used to implement function attributes that affect register usage or code generation patterns. The argument DECL is the declaration for the new function context, and may be null to indicate that the compiler has left a function context and is returning to processing at the top level. The default hook function does nothing. GCC sets ‘cfun’ to a dummy function context during initialization of some parts of the back end. The hook function is not invoked in this situation; you need not worry about the hook being invoked recursively, or when the back end is in a partially-initialized state. ‘cfun’ might be ‘NULL’ to indicate processing at top level, outside of any function scope. -- Macro: TARGET_OBJECT_SUFFIX Define this macro to be a C string representing the suffix for object files on your target machine. If you do not define this macro, GCC will use ‘.o’ as the suffix for object files. -- Macro: TARGET_EXECUTABLE_SUFFIX Define this macro to be a C string representing the suffix to be automatically added to executable files on your target machine. If you do not define this macro, GCC will use the null string as the suffix for executable files. -- Macro: COLLECT_EXPORT_LIST If defined, ‘collect2’ will scan the individual object files specified on its command line and create an export list for the linker. Define this macro for systems like AIX, where the linker discards object files that are not referenced from ‘main’ and uses export lists. -- Target Hook: bool TARGET_CANNOT_MODIFY_JUMPS_P (void) This target hook returns ‘true’ past the point in which new jump instructions could be created. On machines that require a register for every jump such as the SHmedia ISA of SH5, this point would typically be reload, so this target hook should be defined to a function such as: static bool cannot_modify_jumps_past_reload_p () { return (reload_completed || reload_in_progress); } -- Target Hook: bool TARGET_HAVE_CONDITIONAL_EXECUTION (void) This target hook returns true if the target supports conditional execution. This target hook is required only when the target has several different modes and they have different conditional execution capability, such as ARM. -- Target Hook: rtx TARGET_GEN_CCMP_FIRST (rtx_insn **PREP_SEQ, rtx_insn **GEN_SEQ, rtx_code CODE, tree OP0, tree OP1) This function prepares to emit a comparison insn for the first compare in a sequence of conditional comparisions. It returns an appropriate comparison with ‘CC’ for passing to ‘gen_ccmp_next’ or ‘cbranch_optab’. The insns to prepare the compare are saved in PREP_SEQ and the compare insns are saved in GEN_SEQ. They will be emitted when all the compares in the conditional comparision are generated without error. CODE is the ‘rtx_code’ of the compare for OP0 and OP1. -- Target Hook: rtx TARGET_GEN_CCMP_NEXT (rtx_insn **PREP_SEQ, rtx_insn **GEN_SEQ, rtx PREV, rtx_code CMP_CODE, tree OP0, tree OP1, rtx_code BIT_CODE) This function prepares to emit a conditional comparison within a sequence of conditional comparisons. It returns an appropriate comparison with ‘CC’ for passing to ‘gen_ccmp_next’ or ‘cbranch_optab’. The insns to prepare the compare are saved in PREP_SEQ and the compare insns are saved in GEN_SEQ. They will be emitted when all the compares in the conditional comparision are generated without error. The PREV expression is the result of a prior call to ‘gen_ccmp_first’ or ‘gen_ccmp_next’. It may return ‘NULL’ if the combination of PREV and this comparison is not supported, otherwise the result must be appropriate for passing to ‘gen_ccmp_next’ or ‘cbranch_optab’. CODE is the ‘rtx_code’ of the compare for OP0 and OP1. BIT_CODE is ‘AND’ or ‘IOR’, which is the op on the compares. -- Target Hook: unsigned TARGET_LOOP_UNROLL_ADJUST (unsigned NUNROLL, class loop *LOOP) This target hook returns a new value for the number of times LOOP should be unrolled. The parameter NUNROLL is the number of times the loop is to be unrolled. The parameter LOOP is a pointer to the loop, which is going to be checked for unrolling. This target hook is required only when the target has special constraints like maximum number of memory accesses. -- Macro: POWI_MAX_MULTS If defined, this macro is interpreted as a signed integer C expression that specifies the maximum number of floating point multiplications that should be emitted when expanding exponentiation by an integer constant inline. When this value is defined, exponentiation requiring more than this number of multiplications is implemented by calling the system library's ‘pow’, ‘powf’ or ‘powl’ routines. The default value places no upper bound on the multiplication count. -- Macro: void TARGET_EXTRA_INCLUDES (const char *SYSROOT, const char *IPREFIX, int STDINC) This target hook should register any extra include files for the target. The parameter STDINC indicates if normal include files are present. The parameter SYSROOT is the system root directory. The parameter IPREFIX is the prefix for the gcc directory. -- Macro: void TARGET_EXTRA_PRE_INCLUDES (const char *SYSROOT, const char *IPREFIX, int STDINC) This target hook should register any extra include files for the target before any standard headers. The parameter STDINC indicates if normal include files are present. The parameter SYSROOT is the system root directory. The parameter IPREFIX is the prefix for the gcc directory. -- Macro: void TARGET_OPTF (char *PATH) This target hook should register special include paths for the target. The parameter PATH is the include to register. On Darwin systems, this is used for Framework includes, which have semantics that are different from ‘-I’. -- Macro: bool TARGET_USE_LOCAL_THUNK_ALIAS_P (tree FNDECL) This target macro returns ‘true’ if it is safe to use a local alias for a virtual function FNDECL when constructing thunks, ‘false’ otherwise. By default, the macro returns ‘true’ for all functions, if a target supports aliases (i.e. defines ‘ASM_OUTPUT_DEF’), ‘false’ otherwise, -- Macro: TARGET_FORMAT_TYPES If defined, this macro is the name of a global variable containing target-specific format checking information for the ‘-Wformat’ option. The default is to have no target-specific format checks. -- Macro: TARGET_N_FORMAT_TYPES If defined, this macro is the number of entries in ‘TARGET_FORMAT_TYPES’. -- Macro: TARGET_OVERRIDES_FORMAT_ATTRIBUTES If defined, this macro is the name of a global variable containing target-specific format overrides for the ‘-Wformat’ option. The default is to have no target-specific format overrides. If defined, ‘TARGET_FORMAT_TYPES’ and ‘TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT’ must be defined, too. -- Macro: TARGET_OVERRIDES_FORMAT_ATTRIBUTES_COUNT If defined, this macro specifies the number of entries in ‘TARGET_OVERRIDES_FORMAT_ATTRIBUTES’. -- Macro: TARGET_OVERRIDES_FORMAT_INIT If defined, this macro specifies the optional initialization routine for target specific customizations of the system printf and scanf formatter settings. -- Target Hook: const char * TARGET_INVALID_ARG_FOR_UNPROTOTYPED_FN (const_tree TYPELIST, const_tree FUNCDECL, const_tree VAL) If defined, this macro returns the diagnostic message when it is illegal to pass argument VAL to function FUNCDECL with prototype TYPELIST. -- Target Hook: const char * TARGET_INVALID_CONVERSION (const_tree FROMTYPE, const_tree TOTYPE) If defined, this macro returns the diagnostic message when it is invalid to convert from FROMTYPE to TOTYPE, or ‘NULL’ if validity should be determined by the front end. -- Target Hook: const char * TARGET_INVALID_UNARY_OP (int OP, const_tree TYPE) If defined, this macro returns the diagnostic message when it is invalid to apply operation OP (where unary plus is denoted by ‘CONVERT_EXPR’) to an operand of type TYPE, or ‘NULL’ if validity should be determined by the front end. -- Target Hook: const char * TARGET_INVALID_BINARY_OP (int OP, const_tree TYPE1, const_tree TYPE2) If defined, this macro returns the diagnostic message when it is invalid to apply operation OP to operands of types TYPE1 and TYPE2, or ‘NULL’ if validity should be determined by the front end. -- Target Hook: tree TARGET_PROMOTED_TYPE (const_tree TYPE) If defined, this target hook returns the type to which values of TYPE should be promoted when they appear in expressions, analogous to the integer promotions, or ‘NULL_TREE’ to use the front end's normal promotion rules. This hook is useful when there are target-specific types with special promotion rules. This is currently used only by the C and C++ front ends. -- Target Hook: tree TARGET_CONVERT_TO_TYPE (tree TYPE, tree EXPR) If defined, this hook returns the result of converting EXPR to TYPE. It should return the converted expression, or ‘NULL_TREE’ to apply the front end's normal conversion rules. This hook is useful when there are target-specific types with special conversion rules. This is currently used only by the C and C++ front ends. -- Target Hook: bool TARGET_VERIFY_TYPE_CONTEXT (location_t LOC, type_context_kind CONTEXT, const_tree TYPE, bool SILENT_P) If defined, this hook returns false if there is a target-specific reason why type TYPE cannot be used in the source language context described by CONTEXT. When SILENT_P is false, the hook also reports an error against LOC for invalid uses of TYPE. Calls to this hook should be made through the global function ‘verify_type_context’, which makes the SILENT_P parameter default to false and also handles ‘error_mark_node’. The default implementation always returns true. -- Macro: OBJC_JBLEN This macro determines the size of the objective C jump buffer for the NeXT runtime. By default, OBJC_JBLEN is defined to an innocuous value. -- Macro: LIBGCC2_UNWIND_ATTRIBUTE Define this macro if any target-specific attributes need to be attached to the functions in ‘libgcc’ that provide low-level support for call stack unwinding. It is used in declarations in ‘unwind-generic.h’ and the associated definitions of those functions. -- Target Hook: void TARGET_UPDATE_STACK_BOUNDARY (void) Define this macro to update the current function stack boundary if necessary. -- Target Hook: rtx TARGET_GET_DRAP_RTX (void) This hook should return an rtx for Dynamic Realign Argument Pointer (DRAP) if a different argument pointer register is needed to access the function's argument list due to stack realignment. Return ‘NULL’ if no DRAP is needed. -- Target Hook: HARD_REG_SET TARGET_ZERO_CALL_USED_REGS (HARD_REG_SET SELECTED_REGS) This target hook emits instructions to zero the subset of SELECTED_REGS that could conceivably contain values that are useful to an attacker. Return the set of registers that were actually cleared. For most targets, the returned set of registers is a subset of SELECTED_REGS, however, for some of the targets (for example MIPS), clearing some registers that are in the SELECTED_REGS requires clearing other call used registers that are not in the SELECTED_REGS, under such situation, the returned set of registers must be a subset of all call used registers. The default implementation uses normal move instructions to zero all the registers in SELECTED_REGS. Define this hook if the target has more efficient ways of zeroing certain registers, or if you believe that certain registers would never contain values that are useful to an attacker. -- Target Hook: bool TARGET_ALLOCATE_STACK_SLOTS_FOR_ARGS (void) When optimization is disabled, this hook indicates whether or not arguments should be allocated to stack slots. Normally, GCC allocates stacks slots for arguments when not optimizing in order to make debugging easier. However, when a function is declared with ‘__attribute__((naked))’, there is no stack frame, and the compiler cannot safely move arguments from the registers in which they are passed to the stack. Therefore, this hook should return true in general, but false for naked functions. The default implementation always returns true. -- Target Hook: unsigned HOST_WIDE_INT TARGET_CONST_ANCHOR On some architectures it can take multiple instructions to synthesize a constant. If there is another constant already in a register that is close enough in value then it is preferable that the new constant is computed from this register using immediate addition or subtraction. We accomplish this through CSE. Besides the value of the constant we also add a lower and an upper constant anchor to the available expressions. These are then queried when encountering new constants. The anchors are computed by rounding the constant up and down to a multiple of the value of ‘TARGET_CONST_ANCHOR’. ‘TARGET_CONST_ANCHOR’ should be the maximum positive value accepted by immediate-add plus one. We currently assume that the value of ‘TARGET_CONST_ANCHOR’ is a power of 2. For example, on MIPS, where add-immediate takes a 16-bit signed value, ‘TARGET_CONST_ANCHOR’ is set to ‘0x8000’. The default value is zero, which disables this optimization. -- Target Hook: unsigned HOST_WIDE_INT TARGET_ASAN_SHADOW_OFFSET (void) Return the offset bitwise ored into shifted address to get corresponding Address Sanitizer shadow memory address. NULL if Address Sanitizer is not supported by the target. May return 0 if Address Sanitizer is not supported by a subtarget. -- Target Hook: unsigned HOST_WIDE_INT TARGET_MEMMODEL_CHECK (unsigned HOST_WIDE_INT VAL) Validate target specific memory model mask bits. When NULL no target specific memory model bits are allowed. -- Target Hook: unsigned char TARGET_ATOMIC_TEST_AND_SET_TRUEVAL This value should be set if the result written by ‘atomic_test_and_set’ is not exactly 1, i.e. the ‘bool’ ‘true’. -- Target Hook: bool TARGET_HAS_IFUNC_P (void) It returns true if the target supports GNU indirect functions. The support includes the assembler, linker and dynamic linker. The default value of this hook is based on target's libc. -- Target Hook: bool TARGET_IFUNC_REF_LOCAL_OK (void) Return true if it is OK to reference indirect function resolvers locally. The default is to return false. -- Target Hook: unsigned int TARGET_ATOMIC_ALIGN_FOR_MODE (machine_mode MODE) If defined, this function returns an appropriate alignment in bits for an atomic object of machine_mode MODE. If 0 is returned then the default alignment for the specified mode is used. -- Target Hook: void TARGET_ATOMIC_ASSIGN_EXPAND_FENV (tree *HOLD, tree *CLEAR, tree *UPDATE) ISO C11 requires atomic compound assignments that may raise floating-point exceptions to raise exceptions corresponding to the arithmetic operation whose result was successfully stored in a compare-and-exchange sequence. This requires code equivalent to calls to ‘feholdexcept’, ‘feclearexcept’ and ‘feupdateenv’ to be generated at appropriate points in the compare-and-exchange sequence. This hook should set ‘*HOLD’ to an expression equivalent to the call to ‘feholdexcept’, ‘*CLEAR’ to an expression equivalent to the call to ‘feclearexcept’ and ‘*UPDATE’ to an expression equivalent to the call to ‘feupdateenv’. The three expressions are ‘NULL_TREE’ on entry to the hook and may be left as ‘NULL_TREE’ if no code is required in a particular place. The default implementation leaves all three expressions as ‘NULL_TREE’. The ‘__atomic_feraiseexcept’ function from ‘libatomic’ may be of use as part of the code generated in ‘*UPDATE’. -- Target Hook: void TARGET_RECORD_OFFLOAD_SYMBOL (tree) Used when offloaded functions are seen in the compilation unit and no named sections are available. It is called once for each symbol that must be recorded in the offload function and variable table. -- Target Hook: char * TARGET_OFFLOAD_OPTIONS (void) Used when writing out the list of options into an LTO file. It should translate any relevant target-specific options (such as the ABI in use) into one of the ‘-foffload’ options that exist as a common interface to express such options. It should return a string containing these options, separated by spaces, which the caller will free. -- Macro: TARGET_SUPPORTS_WIDE_INT On older ports, large integers are stored in ‘CONST_DOUBLE’ rtl objects. Newer ports define ‘TARGET_SUPPORTS_WIDE_INT’ to be nonzero to indicate that large integers are stored in ‘CONST_WIDE_INT’ rtl objects. The ‘CONST_WIDE_INT’ allows very large integer constants to be represented. ‘CONST_DOUBLE’ is limited to twice the size of the host's ‘HOST_WIDE_INT’ representation. Converting a port mostly requires looking for the places where ‘CONST_DOUBLE’s are used with ‘VOIDmode’ and replacing that code with code that accesses ‘CONST_WIDE_INT’s. ‘"grep -i const_double"’ at the port level gets you to 95% of the changes that need to be made. There are a few places that require a deeper look. • There is no equivalent to ‘hval’ and ‘lval’ for ‘CONST_WIDE_INT’s. This would be difficult to express in the md language since there are a variable number of elements. Most ports only check that ‘hval’ is either 0 or -1 to see if the value is small. As mentioned above, this will no longer be necessary since small constants are always ‘CONST_INT’. Of course there are still a few exceptions, the alpha's constraint used by the zap instruction certainly requires careful examination by C code. However, all the current code does is pass the hval and lval to C code, so evolving the c code to look at the ‘CONST_WIDE_INT’ is not really a large change. • Because there is no standard template that ports use to materialize constants, there is likely to be some futzing that is unique to each port in this code. • The rtx costs may have to be adjusted to properly account for larger constants that are represented as ‘CONST_WIDE_INT’. All and all it does not take long to convert ports that the maintainer is familiar with. -- Target Hook: bool TARGET_HAVE_SPECULATION_SAFE_VALUE (bool ACTIVE) This hook is used to determine the level of target support for ‘__builtin_speculation_safe_value’. If called with an argument of false, it returns true if the target has been modified to support this builtin. If called with an argument of true, it returns true if the target requires active mitigation execution might be speculative. The default implementation returns false if the target does not define a pattern named ‘speculation_barrier’. Else it returns true for the first case and whether the pattern is enabled for the current compilation for the second case. For targets that have no processors that can execute instructions speculatively an alternative implemenation of this hook is available: simply redefine this hook to ‘speculation_safe_value_not_needed’ along with your other target hooks. -- Target Hook: rtx TARGET_SPECULATION_SAFE_VALUE (machine_mode MODE, rtx RESULT, rtx VAL, rtx FAILVAL) This target hook can be used to generate a target-specific code sequence that implements the ‘__builtin_speculation_safe_value’ built-in function. The function must always return VAL in RESULT in mode MODE when the cpu is not executing speculatively, but must never return that when speculating until it is known that the speculation will not be unwound. The hook supports two primary mechanisms for implementing the requirements. The first is to emit a speculation barrier which forces the processor to wait until all prior speculative operations have been resolved; the second is to use a target-specific mechanism that can track the speculation state and to return FAILVAL if it can determine that speculation must be unwound at a later time. The default implementation simply copies VAL to RESULT and emits a ‘speculation_barrier’ instruction if that is defined. -- Target Hook: void TARGET_RUN_TARGET_SELFTESTS (void) If selftests are enabled, run any selftests for this target. -- Target Hook: bool TARGET_MEMTAG_CAN_TAG_ADDRESSES () True if the backend architecture naturally supports ignoring some region of pointers. This feature means that ‘-fsanitize=hwaddress’ can work. At preset, this feature does not support address spaces. It also requires ‘Pmode’ to be the same as ‘ptr_mode’. -- Target Hook: uint8_t TARGET_MEMTAG_TAG_SIZE () Return the size of a tag (in bits) for this platform. The default returns 8. -- Target Hook: uint8_t TARGET_MEMTAG_GRANULE_SIZE () Return the size in real memory that each byte in shadow memory refers to. I.e. if a variable is X bytes long in memory, then this hook should return the value Y such that the tag in shadow memory spans X/Y bytes. Most variables will need to be aligned to this amount since two variables that are neighbors in memory and share a tag granule would need to share the same tag. The default returns 16. -- Target Hook: rtx TARGET_MEMTAG_INSERT_RANDOM_TAG (rtx UNTAGGED, rtx TARGET) Return an RTX representing the value of UNTAGGED but with a (possibly) random tag in it. Put that value into TARGET if it is convenient to do so. This function is used to generate a tagged base for the current stack frame. -- Target Hook: rtx TARGET_MEMTAG_ADD_TAG (rtx BASE, poly_int64 ADDR_OFFSET, uint8_t TAG_OFFSET) Return an RTX that represents the result of adding ADDR_OFFSET to the address in pointer BASE and TAG_OFFSET to the tag in pointer BASE. The resulting RTX must either be a valid memory address or be able to get put into an operand with ‘force_operand’. Unlike other memtag hooks, this must return an expression and not emit any RTL. -- Target Hook: rtx TARGET_MEMTAG_SET_TAG (rtx UNTAGGED_BASE, rtx TAG, rtx TARGET) Return an RTX representing UNTAGGED_BASE but with the tag TAG. Try and store this in TARGET if convenient. UNTAGGED_BASE is required to have a zero tag when this hook is called. The default of this hook is to set the top byte of UNTAGGED_BASE to TAG. -- Target Hook: rtx TARGET_MEMTAG_EXTRACT_TAG (rtx TAGGED_POINTER, rtx TARGET) Return an RTX representing the tag stored in TAGGED_POINTER. Store the result in TARGET if it is convenient. The default represents the top byte of the original pointer. -- Target Hook: rtx TARGET_MEMTAG_UNTAGGED_POINTER (rtx TAGGED_POINTER, rtx TARGET) Return an RTX representing TAGGED_POINTER with its tag set to zero. Store the result in TARGET if convenient. The default clears the top byte of the original pointer. -- Target Hook: bool TARGET_HAVE_SHADOW_CALL_STACK This value is true if the target platform supports ‘-fsanitize=shadow-call-stack’. The default value is false. -- Target Hook: bool TARGET_HAVE_LIBATOMIC This value is true if the target platform supports libatomic. The default value is false.  File: gccint.info, Node: Host Config, Next: Fragments, Prev: Target Macros, Up: Top 19 Host Configuration ********************* Most details about the machine and system on which the compiler is actually running are detected by the ‘configure’ script. Some things are impossible for ‘configure’ to detect; these are described in two ways, either by macros defined in a file named ‘xm-MACHINE.h’ or by hook functions in the file specified by the OUT_HOST_HOOK_OBJ variable in ‘config.gcc’. (The intention is that very few hosts will need a header file but nearly every fully supported host will need to override some hooks.) If you need to define only a few macros, and they have simple definitions, consider using the ‘xm_defines’ variable in your ‘config.gcc’ entry instead of creating a host configuration header. *Note System Config::. * Menu: * Host Common:: Things every host probably needs implemented. * Filesystem:: Your host cannot have the letter 'a' in filenames? * Host Misc:: Rare configuration options for hosts.  File: gccint.info, Node: Host Common, Next: Filesystem, Up: Host Config 19.1 Host Common ================ Some things are just not portable, even between similar operating systems, and are too difficult for autoconf to detect. They get implemented using hook functions in the file specified by the HOST_HOOK_OBJ variable in ‘config.gcc’. -- Host Hook: void HOST_HOOKS_EXTRA_SIGNALS (void) This host hook is used to set up handling for extra signals. The most common thing to do in this hook is to detect stack overflow. -- Host Hook: void * HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t SIZE, int FD) This host hook returns the address of some space that is likely to be free in some subsequent invocation of the compiler. We intend to load the PCH data at this address such that the data need not be relocated. The area should be able to hold SIZE bytes. If the host uses ‘mmap’, FD is an open file descriptor that can be used for probing. -- Host Hook: int HOST_HOOKS_GT_PCH_USE_ADDRESS (void * ADDRESS, size_t SIZE, int FD, size_t OFFSET) This host hook is called when a PCH file is about to be loaded. We want to load SIZE bytes from FD at OFFSET into memory at ADDRESS. The given address will be the result of a previous invocation of ‘HOST_HOOKS_GT_PCH_GET_ADDRESS’. Return −1 if we couldn't allocate SIZE bytes at ADDRESS. Return 0 if the memory is allocated but the data is not loaded. Return 1 if the hook has performed everything. If the implementation uses reserved address space, free any reserved space beyond SIZE, regardless of the return value. If no PCH will be loaded, this hook may be called with SIZE zero, in which case all reserved address space should be freed. Do not try to handle values of ADDRESS that could not have been returned by this executable; just return −1. Such values usually indicate an out-of-date PCH file (built by some other GCC executable), and such a PCH file won't work. -- Host Hook: size_t HOST_HOOKS_GT_PCH_ALLOC_GRANULARITY (void); This host hook returns the alignment required for allocating virtual memory. Usually this is the same as getpagesize, but on some hosts the alignment for reserving memory differs from the pagesize for committing memory.  File: gccint.info, Node: Filesystem, Next: Host Misc, Prev: Host Common, Up: Host Config 19.2 Host Filesystem ==================== GCC needs to know a number of things about the semantics of the host machine's filesystem. Filesystems with Unix and MS-DOS semantics are automatically detected. For other systems, you can define the following macros in ‘xm-MACHINE.h’. ‘HAVE_DOS_BASED_FILE_SYSTEM’ This macro is automatically defined by ‘system.h’ if the host file system obeys the semantics defined by MS-DOS instead of Unix. DOS file systems are case insensitive, file specifications may begin with a drive letter, and both forward slash and backslash (‘/’ and ‘\’) are directory separators. ‘DIR_SEPARATOR’ ‘DIR_SEPARATOR_2’ If defined, these macros expand to character constants specifying separators for directory names within a file specification. ‘system.h’ will automatically give them appropriate values on Unix and MS-DOS file systems. If your file system is neither of these, define one or both appropriately in ‘xm-MACHINE.h’. However, operating systems like VMS, where constructing a pathname is more complicated than just stringing together directory names separated by a special character, should not define either of these macros. ‘PATH_SEPARATOR’ If defined, this macro should expand to a character constant specifying the separator for elements of search paths. The default value is a colon (‘:’). DOS-based systems usually, but not always, use semicolon (‘;’). ‘VMS’ Define this macro if the host system is VMS. ‘HOST_OBJECT_SUFFIX’ Define this macro to be a C string representing the suffix for object files on your host machine. If you do not define this macro, GCC will use ‘.o’ as the suffix for object files. ‘HOST_EXECUTABLE_SUFFIX’ Define this macro to be a C string representing the suffix for executable files on your host machine. If you do not define this macro, GCC will use the null string as the suffix for executable files. ‘HOST_BIT_BUCKET’ A pathname defined by the host operating system, which can be opened as a file and written to, but all the information written is discarded. This is commonly known as a “bit bucket” or “null device”. If you do not define this macro, GCC will use ‘/dev/null’ as the bit bucket. If the host does not support a bit bucket, define this macro to an invalid filename. ‘UPDATE_PATH_HOST_CANONICALIZE (PATH)’ If defined, a C statement (sans semicolon) that performs host-dependent canonicalization when a path used in a compilation driver or preprocessor is canonicalized. PATH is a malloc-ed path to be canonicalized. If the C statement does canonicalize PATH into a different buffer, the old path should be freed and the new buffer should have been allocated with malloc. ‘DUMPFILE_FORMAT’ Define this macro to be a C string representing the format to use for constructing the index part of debugging dump file names. The resultant string must fit in fifteen bytes. The full filename will be the concatenation of: the prefix of the assembler file name, the string resulting from applying this format to an index number, and a string unique to each dump file kind, e.g. ‘rtl’. If you do not define this macro, GCC will use ‘.%02d.’. You should define this macro if using the default will create an invalid file name. ‘DELETE_IF_ORDINARY’ Define this macro to be a C statement (sans semicolon) that performs host-dependent removal of ordinary temp files in the compilation driver. If you do not define this macro, GCC will use the default version. You should define this macro if the default version does not reliably remove the temp file as, for example, on VMS which allows multiple versions of a file. ‘HOST_LACKS_INODE_NUMBERS’ Define this macro if the host filesystem does not report meaningful inode numbers in struct stat.  File: gccint.info, Node: Host Misc, Prev: Filesystem, Up: Host Config 19.3 Host Misc ============== ‘FATAL_EXIT_CODE’ A C expression for the status code to be returned when the compiler exits after serious errors. The default is the system-provided macro ‘EXIT_FAILURE’, or ‘1’ if the system doesn't define that macro. Define this macro only if these defaults are incorrect. ‘SUCCESS_EXIT_CODE’ A C expression for the status code to be returned when the compiler exits without serious errors. (Warnings are not serious errors.) The default is the system-provided macro ‘EXIT_SUCCESS’, or ‘0’ if the system doesn't define that macro. Define this macro only if these defaults are incorrect. ‘USE_C_ALLOCA’ Define this macro if GCC should use the C implementation of ‘alloca’ provided by ‘libiberty.a’. This only affects how some parts of the compiler itself allocate memory. It does not change code generation. When GCC is built with a compiler other than itself, the C ‘alloca’ is always used. This is because most other implementations have serious bugs. You should define this macro only on a system where no stack-based ‘alloca’ can possibly work. For instance, if a system has a small limit on the size of the stack, GCC's builtin ‘alloca’ will not work reliably. ‘COLLECT2_HOST_INITIALIZATION’ If defined, a C statement (sans semicolon) that performs host-dependent initialization when ‘collect2’ is being initialized. ‘GCC_DRIVER_HOST_INITIALIZATION’ If defined, a C statement (sans semicolon) that performs host-dependent initialization when a compilation driver is being initialized. ‘HOST_LONG_LONG_FORMAT’ If defined, the string used to indicate an argument of type ‘long long’ to functions like ‘printf’. The default value is ‘"ll"’. ‘HOST_LONG_FORMAT’ If defined, the string used to indicate an argument of type ‘long’ to functions like ‘printf’. The default value is ‘"l"’. ‘HOST_PTR_PRINTF’ If defined, the string used to indicate an argument of type ‘void *’ to functions like ‘printf’. The default value is ‘"%p"’. In addition, if ‘configure’ generates an incorrect definition of any of the macros in ‘auto-host.h’, you can override that definition in a host configuration header. If you need to do this, first see if it is possible to fix ‘configure’.  File: gccint.info, Node: Fragments, Next: Collect2, Prev: Host Config, Up: Top 20 Makefile Fragments ********************* When you configure GCC using the ‘configure’ script, it will construct the file ‘Makefile’ from the template file ‘Makefile.in’. When it does this, it can incorporate makefile fragments from the ‘config’ directory. These are used to set Makefile parameters that are not amenable to being calculated by autoconf. The list of fragments to incorporate is set by ‘config.gcc’ (and occasionally ‘config.build’ and ‘config.host’); *Note System Config::. Fragments are named either ‘t-TARGET’ or ‘x-HOST’, depending on whether they are relevant to configuring GCC to produce code for a particular target, or to configuring GCC to run on a particular host. Here TARGET and HOST are mnemonics which usually have some relationship to the canonical system name, but no formal connection. If these files do not exist, it means nothing needs to be added for a given target or host. Most targets need a few ‘t-TARGET’ fragments, but needing ‘x-HOST’ fragments is rare. * Menu: * Target Fragment:: Writing ‘t-TARGET’ files. * Host Fragment:: Writing ‘x-HOST’ files.  File: gccint.info, Node: Target Fragment, Next: Host Fragment, Up: Fragments 20.1 Target Makefile Fragments ============================== Target makefile fragments can set these Makefile variables. ‘LIBGCC2_CFLAGS’ Compiler flags to use when compiling ‘libgcc2.c’. ‘LIB2FUNCS_EXTRA’ A list of source file names to be compiled or assembled and inserted into ‘libgcc.a’. ‘CRTSTUFF_T_CFLAGS’ Special flags used when compiling ‘crtstuff.c’. *Note Initialization::. ‘CRTSTUFF_T_CFLAGS_S’ Special flags used when compiling ‘crtstuff.c’ for shared linking. Used if you use ‘crtbeginS.o’ and ‘crtendS.o’ in ‘EXTRA-PARTS’. *Note Initialization::. ‘MULTILIB_OPTIONS’ For some targets, invoking GCC in different ways produces objects that cannot be linked together. For example, for some targets GCC produces both big and little endian code. For these targets, you must arrange for multiple versions of ‘libgcc.a’ to be compiled, one for each set of incompatible options. When GCC invokes the linker, it arranges to link in the right version of ‘libgcc.a’, based on the command line options used. The ‘MULTILIB_OPTIONS’ macro lists the set of options for which special versions of ‘libgcc.a’ must be built. Write options that are mutually incompatible side by side, separated by a slash. Write options that may be used together separated by a space. The build procedure will build all combinations of compatible options. For example, if you set ‘MULTILIB_OPTIONS’ to ‘m68000/m68020 msoft-float’, ‘Makefile’ will build special versions of ‘libgcc.a’ using the following sets of options: ‘-m68000’, ‘-m68020’, ‘-msoft-float’, ‘-m68000 -msoft-float’, and ‘-m68020 -msoft-float’. ‘MULTILIB_DIRNAMES’ If ‘MULTILIB_OPTIONS’ is used, this variable specifies the directory names that should be used to hold the various libraries. Write one element in ‘MULTILIB_DIRNAMES’ for each element in ‘MULTILIB_OPTIONS’. If ‘MULTILIB_DIRNAMES’ is not used, the default value will be ‘MULTILIB_OPTIONS’, with all slashes treated as spaces. ‘MULTILIB_DIRNAMES’ describes the multilib directories using GCC conventions and is applied to directories that are part of the GCC installation. When multilib-enabled, the compiler will add a subdirectory of the form PREFIX/MULTILIB before each directory in the search path for libraries and crt files. For example, if ‘MULTILIB_OPTIONS’ is set to ‘m68000/m68020 msoft-float’, then the default value of ‘MULTILIB_DIRNAMES’ is ‘m68000 m68020 msoft-float’. You may specify a different value if you desire a different set of directory names. ‘MULTILIB_MATCHES’ Sometimes the same option may be written in two different ways. If an option is listed in ‘MULTILIB_OPTIONS’, GCC needs to know about any synonyms. In that case, set ‘MULTILIB_MATCHES’ to a list of items of the form ‘option=option’ to describe all relevant synonyms. For example, ‘m68000=mc68000 m68020=mc68020’. ‘MULTILIB_EXCEPTIONS’ Sometimes when there are multiple sets of ‘MULTILIB_OPTIONS’ being specified, there are combinations that should not be built. In that case, set ‘MULTILIB_EXCEPTIONS’ to be all of the switch exceptions in shell case syntax that should not be built. For example the ARM processor cannot execute both hardware floating point instructions and the reduced size THUMB instructions at the same time, so there is no need to build libraries with both of these options enabled. Therefore ‘MULTILIB_EXCEPTIONS’ is set to: *mthumb/*mhard-float* ‘MULTILIB_REQUIRED’ Sometimes when there are only a few combinations are required, it would be a big effort to come up with a ‘MULTILIB_EXCEPTIONS’ list to cover all undesired ones. In such a case, just listing all the required combinations in ‘MULTILIB_REQUIRED’ would be more straightforward. The way to specify the entries in ‘MULTILIB_REQUIRED’ is same with the way used for ‘MULTILIB_EXCEPTIONS’, only this time what are required will be specified. Suppose there are multiple sets of ‘MULTILIB_OPTIONS’ and only two combinations are required, one for ARMv7-M and one for ARMv7-R with hard floating-point ABI and FPU, the ‘MULTILIB_REQUIRED’ can be set to: MULTILIB_REQUIRED = mthumb/march=armv7-m MULTILIB_REQUIRED += march=armv7-r/mfloat-abi=hard/mfpu=vfpv3-d16 The ‘MULTILIB_REQUIRED’ can be used together with ‘MULTILIB_EXCEPTIONS’. The option combinations generated from ‘MULTILIB_OPTIONS’ will be filtered by ‘MULTILIB_EXCEPTIONS’ and then by ‘MULTILIB_REQUIRED’. ‘MULTILIB_REUSE’ Sometimes it is desirable to reuse one existing multilib for different sets of options. Such kind of reuse can minimize the number of multilib variants. And for some targets it is better to reuse an existing multilib than to fall back to default multilib when there is no corresponding multilib. This can be done by adding reuse rules to ‘MULTILIB_REUSE’. A reuse rule is comprised of two parts connected by equality sign. The left part is the option set used to build multilib and the right part is the option set that will reuse this multilib. Both parts should only use options specified in ‘MULTILIB_OPTIONS’ and the equality signs found in options name should be replaced with periods. An explicit period in the rule can be escaped by preceding it with a backslash. The order of options in the left part matters and should be same with those specified in ‘MULTILIB_REQUIRED’ or aligned with the order in ‘MULTILIB_OPTIONS’. There is no such limitation for options in the right part as we don't build multilib from them. ‘MULTILIB_REUSE’ is different from ‘MULTILIB_MATCHES’ in that it sets up relations between two option sets rather than two options. Here is an example to demo how we reuse libraries built in Thumb mode for applications built in ARM mode: MULTILIB_REUSE = mthumb/march.armv7-r=marm/march.armv7-r Before the advent of ‘MULTILIB_REUSE’, GCC select multilib by comparing command line options with options used to build multilib. The ‘MULTILIB_REUSE’ is complementary to that way. Only when the original comparison matches nothing it will work to see if it is OK to reuse some existing multilib. ‘MULTILIB_EXTRA_OPTS’ Sometimes it is desirable that when building multiple versions of ‘libgcc.a’ certain options should always be passed on to the compiler. In that case, set ‘MULTILIB_EXTRA_OPTS’ to be the list of options to be used for all builds. If you set this, you should probably set ‘CRTSTUFF_T_CFLAGS’ to a dash followed by it. ‘MULTILIB_OSDIRNAMES’ If ‘MULTILIB_OPTIONS’ is used, this variable specifies a list of subdirectory names, that are used to modify the search path depending on the chosen multilib. Unlike ‘MULTILIB_DIRNAMES’, ‘MULTILIB_OSDIRNAMES’ describes the multilib directories using operating systems conventions, and is applied to the directories such as ‘lib’ or those in the ‘LIBRARY_PATH’ environment variable. The format is either the same as of ‘MULTILIB_DIRNAMES’, or a set of mappings. When it is the same as ‘MULTILIB_DIRNAMES’, it describes the multilib directories using operating system conventions, rather than GCC conventions. When it is a set of mappings of the form GCCDIR=OSDIR, the left side gives the GCC convention and the right gives the equivalent OS defined location. If the OSDIR part begins with a ‘!’, GCC will not search in the non-multilib directory and use exclusively the multilib directory. Otherwise, the compiler will examine the search path for libraries and crt files twice; the first time it will add MULTILIB to each directory in the search path, the second it will not. For configurations that support both multilib and multiarch, ‘MULTILIB_OSDIRNAMES’ also encodes the multiarch name, thus subsuming ‘MULTIARCH_DIRNAME’. The multiarch name is appended to each directory name, separated by a colon (e.g. ‘../lib32:i386-linux-gnu’). Each multiarch subdirectory will be searched before the corresponding OS multilib directory, for example ‘/lib/i386-linux-gnu’ before ‘/lib/../lib32’. The multiarch name will also be used to modify the system header search path, as explained for ‘MULTIARCH_DIRNAME’. ‘MULTIARCH_DIRNAME’ This variable specifies the multiarch name for configurations that are multiarch-enabled but not multilibbed configurations. The multiarch name is used to augment the search path for libraries, crt files and system header files with additional locations. The compiler will add a multiarch subdirectory of the form PREFIX/MULTIARCH before each directory in the library and crt search path. It will also add two directories ‘LOCAL_INCLUDE_DIR’/MULTIARCH and ‘NATIVE_SYSTEM_HEADER_DIR’/MULTIARCH) to the system header search path, respectively before ‘LOCAL_INCLUDE_DIR’ and ‘NATIVE_SYSTEM_HEADER_DIR’. ‘MULTIARCH_DIRNAME’ is not used for configurations that support both multilib and multiarch. In that case, multiarch names are encoded in ‘MULTILIB_OSDIRNAMES’ instead. More documentation about multiarch can be found at . ‘SPECS’ Unfortunately, setting ‘MULTILIB_EXTRA_OPTS’ is not enough, since it does not affect the build of target libraries, at least not the build of the default multilib. One possible work-around is to use ‘DRIVER_SELF_SPECS’ to bring options from the ‘specs’ file as if they had been passed in the compiler driver command line. However, you don't want to be adding these options after the toolchain is installed, so you can instead tweak the ‘specs’ file that will be used during the toolchain build, while you still install the original, built-in ‘specs’. The trick is to set ‘SPECS’ to some other filename (say ‘specs.install’), that will then be created out of the built-in specs, and introduce a ‘Makefile’ rule to generate the ‘specs’ file that's going to be used at build time out of your ‘specs.install’. ‘T_CFLAGS’ These are extra flags to pass to the C compiler. They are used both when building GCC, and when compiling things with the just-built GCC. This variable is deprecated and should not be used.  File: gccint.info, Node: Host Fragment, Prev: Target Fragment, Up: Fragments 20.2 Host Makefile Fragments ============================ The use of ‘x-HOST’ fragments is discouraged. You should only use it for makefile dependencies.  File: gccint.info, Node: Collect2, Next: Header Dirs, Prev: Fragments, Up: Top 21 ‘collect2’ ************* GCC uses a utility called ‘collect2’ on nearly all systems to arrange to call various initialization functions at start time. The program ‘collect2’ works by linking the program once and looking through the linker output file for symbols with particular names indicating they are constructor functions. If it finds any, it creates a new temporary ‘.c’ file containing a table of them, compiles it, and links the program a second time including that file. The actual calls to the constructors are carried out by a subroutine called ‘__main’, which is called (automatically) at the beginning of the body of ‘main’ (provided ‘main’ was compiled with GNU CC). Calling ‘__main’ is necessary, even when compiling C code, to allow linking C and C++ object code together. (If you use ‘-nostdlib’, you get an unresolved reference to ‘__main’, since it's defined in the standard GCC library. Include ‘-lgcc’ at the end of your compiler command line to resolve this reference.) The program ‘collect2’ is installed as ‘ld’ in the directory where the passes of the compiler are installed. When ‘collect2’ needs to find the _real_ ‘ld’, it tries the following file names: • a hard coded linker file name, if GCC was configured with the ‘--with-ld’ option. • ‘real-ld’ in the directories listed in the compiler's search directories. • ‘real-ld’ in the directories listed in the environment variable ‘PATH’. • The file specified in the ‘REAL_LD_FILE_NAME’ configuration macro, if specified. • ‘ld’ in the compiler's search directories, except that ‘collect2’ will not execute itself recursively. • ‘ld’ in ‘PATH’. "The compiler's search directories" means all the directories where ‘gcc’ searches for passes of the compiler. This includes directories that you specify with ‘-B’. Cross-compilers search a little differently: • ‘real-ld’ in the compiler's search directories. • ‘TARGET-real-ld’ in ‘PATH’. • The file specified in the ‘REAL_LD_FILE_NAME’ configuration macro, if specified. • ‘ld’ in the compiler's search directories. • ‘TARGET-ld’ in ‘PATH’. ‘collect2’ explicitly avoids running ‘ld’ using the file name under which ‘collect2’ itself was invoked. In fact, it remembers up a list of such names--in case one copy of ‘collect2’ finds another copy (or version) of ‘collect2’ installed as ‘ld’ in a second place in the search path. ‘collect2’ searches for the utilities ‘nm’ and ‘strip’ using the same algorithm as above for ‘ld’.  File: gccint.info, Node: Header Dirs, Next: Type Information, Prev: Collect2, Up: Top 22 Standard Header File Directories *********************************** ‘GCC_INCLUDE_DIR’ means the same thing for native and cross. It is where GCC stores its private include files, and also where GCC stores the fixed include files. A cross compiled GCC runs ‘fixincludes’ on the header files in ‘$(tooldir)/include’. (If the cross compilation header files need to be fixed, they must be installed before GCC is built. If the cross compilation header files are already suitable for GCC, nothing special need be done). ‘GPLUSPLUS_INCLUDE_DIR’ means the same thing for native and cross. It is where ‘g++’ looks first for header files. The C++ library installs only target independent header files in that directory. ‘LOCAL_INCLUDE_DIR’ is used only by native compilers. GCC doesn't install anything there. It is normally ‘/usr/local/include’. This is where local additions to a packaged system should place header files. ‘CROSS_INCLUDE_DIR’ is used only by cross compilers. GCC doesn't install anything there. ‘TOOL_INCLUDE_DIR’ is used for both native and cross compilers. It is the place for other packages to install header files that GCC will use. For a cross-compiler, this is the equivalent of ‘/usr/include’. When you build a cross-compiler, ‘fixincludes’ processes any header files in this directory.  File: gccint.info, Node: Type Information, Next: Plugins, Prev: Header Dirs, Up: Top 23 Memory Management and Type Information ***************************************** GCC uses some fairly sophisticated memory management techniques, which involve determining information about GCC's data structures from GCC's source code and using this information to perform garbage collection and implement precompiled headers. A full C++ parser would be too complicated for this task, so a limited subset of C++ is interpreted and special markers are used to determine what parts of the source to look at. All ‘struct’, ‘union’ and ‘template’ structure declarations that define data structures that are allocated under control of the garbage collector must be marked. All global variables that hold pointers to garbage-collected memory must also be marked. Finally, all global variables that need to be saved and restored by a precompiled header must be marked. (The precompiled header mechanism can only save static variables if they're scalar. Complex data structures must be allocated in garbage-collected memory to be saved in a precompiled header.) The full format of a marker is GTY (([OPTION] [(PARAM)], [OPTION] [(PARAM)] ...)) but in most cases no options are needed. The outer double parentheses are still necessary, though: ‘GTY(())’. Markers can appear: • In a structure definition, before the open brace; • In a global variable declaration, after the keyword ‘static’ or ‘extern’; and • In a structure field definition, before the name of the field. Here are some examples of marking simple data structures and globals. struct GTY(()) TAG { FIELDS... }; typedef struct GTY(()) TAG { FIELDS... } *TYPENAME; static GTY(()) struct TAG *LIST; /* points to GC memory */ static GTY(()) int COUNTER; /* save counter in a PCH */ The parser understands simple typedefs such as ‘typedef struct TAG *NAME;’ and ‘typedef int NAME;’. These don't need to be marked. However, in combination with GTY, avoid using typedefs such as ‘typedef int_hash<...> NAME;’ for these generate infinite-recursion code. See PR103157 (https://gcc.gnu.org/PR103157). Instead, you may use ‘struct NAME : int_hash<...> {};’, for example. Since ‘gengtype’'s understanding of C++ is limited, there are several constructs and declarations that are not supported inside classes/structures marked for automatic GC code generation. The following C++ constructs produce a ‘gengtype’ error on structures/classes marked for automatic GC code generation: • Type definitions inside classes/structures are not supported. • Enumerations inside classes/structures are not supported. If you have a class or structure using any of the above constructs, you need to mark that class as ‘GTY ((user))’ and provide your own marking routines (see section *note User GC:: for details). It is always valid to include function definitions inside classes. Those are always ignored by ‘gengtype’, as it only cares about data members. * Menu: * GTY Options:: What goes inside a ‘GTY(())’. * Inheritance and GTY:: Adding GTY to a class hierarchy. * User GC:: Adding user-provided GC marking routines. * GGC Roots:: Making global variables GGC roots. * Files:: How the generated files work. * Invoking the garbage collector:: How to invoke the garbage collector. * Troubleshooting:: When something does not work as expected.  File: gccint.info, Node: GTY Options, Next: Inheritance and GTY, Up: Type Information 23.1 The Inside of a ‘GTY(())’ ============================== Sometimes the C code is not enough to fully describe the type structure. Extra information can be provided with ‘GTY’ options and additional markers. Some options take a parameter, which may be either a string or a type name, depending on the parameter. If an option takes no parameter, it is acceptable either to omit the parameter entirely, or to provide an empty string as a parameter. For example, ‘GTY ((skip))’ and ‘GTY ((skip ("")))’ are equivalent. When the parameter is a string, often it is a fragment of C code. Four special escapes may be used in these strings, to refer to pieces of the data structure being marked: ‘%h’ The current structure. ‘%1’ The structure that immediately contains the current structure. ‘%0’ The outermost structure that contains the current structure. ‘%a’ A partial expression of the form ‘[i1][i2]...’ that indexes the array item currently being marked. For instance, suppose that you have a structure of the form struct A { ... }; struct B { struct A foo[12]; }; and ‘b’ is a variable of type ‘struct B’. When marking ‘b.foo[11]’, ‘%h’ would expand to ‘b.foo[11]’, ‘%0’ and ‘%1’ would both expand to ‘b’, and ‘%a’ would expand to ‘[11]’. As in ordinary C, adjacent strings will be concatenated; this is helpful when you have a complicated expression. GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE" " ? TYPE_NEXT_VARIANT (&%h.generic)" " : TREE_CHAIN (&%h.generic)"))) The available options are: ‘length ("EXPRESSION")’ There are two places the type machinery will need to be explicitly told the length of an array of non-atomic objects. The first case is when a structure ends in a variable-length array, like this: struct GTY(()) rtvec_def { int num_elem; /* number of elements */ rtx GTY ((length ("%h.num_elem"))) elem[1]; }; In this case, the ‘length’ option is used to override the specified array length (which should usually be ‘1’). The parameter of the option is a fragment of C code that calculates the length. The second case is when a structure or a global variable contains a pointer to an array, like this: struct gimple_omp_for_iter * GTY((length ("%h.collapse"))) iter; In this case, ‘iter’ has been allocated by writing something like x->iter = ggc_alloc_cleared_vec_gimple_omp_for_iter (collapse); and the ‘collapse’ provides the length of the field. This second use of ‘length’ also works on global variables, like: static GTY((length("reg_known_value_size"))) rtx *reg_known_value; Note that the ‘length’ option is only meant for use with arrays of non-atomic objects, that is, objects that contain pointers pointing to other GTY-managed objects. For other GC-allocated arrays and strings you should use ‘atomic’ or ‘string_length’. ‘string_length ("EXPRESSION")’ In order to simplify production of PCH, a structure member that is a plain array of bytes (an optionally ‘const’ and/or ‘unsigned’ ‘char *’) is treated specially by the infrastructure. Even if such an array has not been allocated in GC-controlled memory, it will still be written properly into a PCH. The machinery responsible for this needs to know the length of the data; by default, the length is determined by calling ‘strlen’ on the pointer. The ‘string_length’ option specifies an alternate way to determine the length, such as by inspecting another struct member: struct GTY(()) non_terminated_string { size_t sz; const char * GTY((string_length ("%h.sz"))) data; }; Similarly, this is useful for (regular NUL-terminated) strings with NUL characters embedded (that the default ‘strlen’ use would run afoul of): struct GTY(()) multi_string { const char * GTY((string_length ("%h.len + 1"))) str; size_t len; }; The ‘string_length’ option currently is not supported for (fields in) global variables. ‘skip’ If ‘skip’ is applied to a field, the type machinery will ignore it. This is somewhat dangerous; the only safe use is in a union when one field really isn't ever used. ‘callback’ ‘callback’ should be applied to fields with pointer to function type and causes the field to be ignored similarly to ‘skip’, except when writing PCH and the field is non-NULL it will remember the field's address for relocation purposes if the process writing PCH has different load base from a process reading PCH. ‘for_user’ Use this to mark types that need to be marked by user gc routines, but are not refered to in a template argument. So if you have some user gc type T1 and a non user gc type T2 you can give T2 the for_user option so that the marking functions for T1 can call non mangled functions to mark T2. ‘desc ("EXPRESSION")’ ‘tag ("CONSTANT")’ ‘default’ The type machinery needs to be told which field of a ‘union’ is currently active. This is done by giving each field a constant ‘tag’ value, and then specifying a discriminator using ‘desc’. The value of the expression given by ‘desc’ is compared against each ‘tag’ value, each of which should be different. If no ‘tag’ is matched, the field marked with ‘default’ is used if there is one, otherwise no field in the union will be marked. In the ‘desc’ option, the "current structure" is the union that it discriminates. Use ‘%1’ to mean the structure containing it. There are no escapes available to the ‘tag’ option, since it is a constant. For example, struct GTY(()) tree_binding { struct tree_common common; union tree_binding_u { tree GTY ((tag ("0"))) scope; struct cp_binding_level * GTY ((tag ("1"))) level; } GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope; tree value; }; In this example, the value of BINDING_HAS_LEVEL_P when applied to a ‘struct tree_binding *’ is presumed to be 0 or 1. If 1, the type mechanism will treat the field ‘level’ as being present and if 0, will treat the field ‘scope’ as being present. The ‘desc’ and ‘tag’ options can also be used for inheritance to denote which subclass an instance is. See *note Inheritance and GTY:: for more information. ‘cache’ When the ‘cache’ option is applied to a global variable gt_cleare_cache is called on that variable between the mark and sweep phases of garbage collection. The gt_clear_cache function is free to mark blocks as used, or to clear pointers in the variable. In a hash table, the ‘gt_cleare_cache’ function discards entries if the key is not marked, or marks the value if the key is marked. Note that caches should generally use ‘deletable’ instead; ‘cache’ is only preferable if the value is impractical to recompute from the key when needed. ‘deletable’ ‘deletable’, when applied to a global variable, indicates that when garbage collection runs, there's no need to mark anything pointed to by this variable, it can just be set to ‘NULL’ instead. This is used to keep a list of free structures around for re-use. ‘maybe_undef’ When applied to a field, ‘maybe_undef’ indicates that it's OK if the structure that this fields points to is never defined, so long as this field is always ‘NULL’. This is used to avoid requiring backends to define certain optional structures. It doesn't work with language frontends. ‘nested_ptr (TYPE, "TO EXPRESSION", "FROM EXPRESSION")’ The type machinery expects all pointers to point to the start of an object. Sometimes for abstraction purposes it's convenient to have a pointer which points inside an object. So long as it's possible to convert the original object to and from the pointer, such pointers can still be used. TYPE is the type of the original object, the TO EXPRESSION returns the pointer given the original object, and the FROM EXPRESSION returns the original object given the pointer. The pointer will be available using the ‘%h’ escape. ‘chain_next ("EXPRESSION")’ ‘chain_prev ("EXPRESSION")’ ‘chain_circular ("EXPRESSION")’ It's helpful for the type machinery to know if objects are often chained together in long lists; this lets it generate code that uses less stack space by iterating along the list instead of recursing down it. ‘chain_next’ is an expression for the next item in the list, ‘chain_prev’ is an expression for the previous item. For singly linked lists, use only ‘chain_next’; for doubly linked lists, use both. The machinery requires that taking the next item of the previous item gives the original item. ‘chain_circular’ is similar to ‘chain_next’, but can be used for circular single linked lists. ‘reorder ("FUNCTION NAME")’ Some data structures depend on the relative ordering of pointers. If the precompiled header machinery needs to change that ordering, it will call the function referenced by the ‘reorder’ option, before changing the pointers in the object that's pointed to by the field the option applies to. The function must take four arguments, with the signature ‘void *, void *, gt_pointer_operator, void *’. The first parameter is a pointer to the structure that contains the object being updated, or the object itself if there is no containing structure. The second parameter is a cookie that should be ignored. The third parameter is a routine that, given a pointer, will update it to its correct new value. The fourth parameter is a cookie that must be passed to the second parameter. PCH cannot handle data structures that depend on the absolute values of pointers. ‘reorder’ functions can be expensive. When possible, it is better to depend on properties of the data, like an ID number or the hash of a string instead. ‘atomic’ The ‘atomic’ option can only be used with pointers. It informs the GC machinery that the memory that the pointer points to does not contain any pointers, and hence it should be treated by the GC and PCH machinery as an "atomic" block of memory that does not need to be examined when scanning memory for pointers. In particular, the machinery will not scan that memory for pointers to mark them as reachable (when marking pointers for GC) or to relocate them (when writing a PCH file). The ‘atomic’ option differs from the ‘skip’ option. ‘atomic’ keeps the memory under Garbage Collection, but makes the GC ignore the contents of the memory. ‘skip’ is more drastic in that it causes the pointer and the memory to be completely ignored by the Garbage Collector. So, memory marked as ‘atomic’ is automatically freed when no longer reachable, while memory marked as ‘skip’ is not. The ‘atomic’ option must be used with great care, because all sorts of problem can occur if used incorrectly, that is, if the memory the pointer points to does actually contain a pointer. Here is an example of how to use it: struct GTY(()) my_struct { int number_of_elements; unsigned int * GTY ((atomic)) elements; }; In this case, ‘elements’ is a pointer under GC, and the memory it points to needs to be allocated using the Garbage Collector, and will be freed automatically by the Garbage Collector when it is no longer referenced. But the memory that the pointer points to is an array of ‘unsigned int’ elements, and the GC must not try to scan it to find pointers to mark or relocate, which is why it is marked with the ‘atomic’ option. Note that, currently, global variables cannot be marked with ‘atomic’; only fields of a struct can. This is a known limitation. It would be useful to be able to mark global pointers with ‘atomic’ to make the PCH machinery aware of them so that they are saved and restored correctly to PCH files. ‘special ("NAME")’ The ‘special’ option is used to mark types that have to be dealt with by special case machinery. The parameter is the name of the special case. See ‘gengtype.cc’ for further details. Avoid adding new special cases unless there is no other alternative. ‘user’ The ‘user’ option indicates that the code to mark structure fields is completely handled by user-provided routines. See section *note User GC:: for details on what functions need to be provided.  File: gccint.info, Node: Inheritance and GTY, Next: User GC, Prev: GTY Options, Up: Type Information 23.2 Support for inheritance ============================ gengtype has some support for simple class hierarchies. You can use this to have gengtype autogenerate marking routines, provided: • There must be a concrete base class, with a discriminator expression that can be used to identify which subclass an instance is. • Only single inheritance is used. • None of the classes within the hierarchy are templates. If your class hierarchy does not fit in this pattern, you must use *note User GC:: instead. The base class and its discriminator must be identified using the "desc" option. Each concrete subclass must use the "tag" option to identify which value of the discriminator it corresponds to. Every class in the hierarchy must have a ‘GTY(())’ marker, as gengtype will only attempt to parse classes that have such a marker (1). class GTY((desc("%h.kind"), tag("0"))) example_base { public: int kind; tree a; }; class GTY((tag("1"))) some_subclass : public example_base { public: tree b; }; class GTY((tag("2"))) some_other_subclass : public example_base { public: tree c; }; The generated marking routines for the above will contain a "switch" on "kind", visiting all appropriate fields. For example, if kind is 2, it will cast to "some_other_subclass" and visit fields a, b, and c. ---------- Footnotes ---------- (1) Classes lacking such a marker will not be identified as being part of the hierarchy, and so the marking routines will not handle them, leading to a assertion failure within the marking routines due to an unknown tag value (assuming that assertions are enabled).  File: gccint.info, Node: User GC, Next: GGC Roots, Prev: Inheritance and GTY, Up: Type Information 23.3 Support for user-provided GC marking routines ================================================== The garbage collector supports types for which no automatic marking code is generated. For these types, the user is required to provide three functions: one to act as a marker for garbage collection, and two functions to act as marker and pointer walker for pre-compiled headers. Given a structure ‘struct GTY((user)) my_struct’, the following functions should be defined to mark ‘my_struct’: void gt_ggc_mx (my_struct *p) { /* This marks field 'fld'. */ gt_ggc_mx (p->fld); } void gt_pch_nx (my_struct *p) { /* This marks field 'fld'. */ gt_pch_nx (tp->fld); } void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie) { /* For every field 'fld', call the given pointer operator. */ op (&(tp->fld), NULL, cookie); } In general, each marker ‘M’ should call ‘M’ for every pointer field in the structure. Fields that are not allocated in GC or are not pointers must be ignored. For embedded lists (e.g., structures with a ‘next’ or ‘prev’ pointer), the marker must follow the chain and mark every element in it. Note that the rules for the pointer walker ‘gt_pch_nx (my_struct *, gt_pointer_operator, void *)’ are slightly different. In this case, the operation ‘op’ must be applied to the _address_ of every pointer field. 23.3.1 User-provided marking routines for template types -------------------------------------------------------- When a template type ‘TP’ is marked with ‘GTY’, all instances of that type are considered user-provided types. This means that the individual instances of ‘TP’ do not need to be marked with ‘GTY’. The user needs to provide template functions to mark all the fields of the type. The following code snippets represent all the functions that need to be provided. Note that type ‘TP’ may reference to more than one type. In these snippets, there is only one type ‘T’, but there could be more. template void gt_ggc_mx (TP *tp) { extern void gt_ggc_mx (T&); /* This marks field 'fld' of type 'T'. */ gt_ggc_mx (tp->fld); } template void gt_pch_nx (TP *tp) { extern void gt_pch_nx (T&); /* This marks field 'fld' of type 'T'. */ gt_pch_nx (tp->fld); } template void gt_pch_nx (TP *tp, gt_pointer_operator op, void *cookie) { /* For every field 'fld' of 'tp' with type 'T *', call the given pointer operator. */ op (&(tp->fld), NULL, cookie); } template void gt_pch_nx (TP *tp, gt_pointer_operator, void *cookie) { extern void gt_pch_nx (T *, gt_pointer_operator, void *); /* For every field 'fld' of 'tp' with type 'T', call the pointer walker for all the fields of T. */ gt_pch_nx (&(tp->fld), op, cookie); } Support for user-defined types is currently limited. The following restrictions apply: 1. Type ‘TP’ and all the argument types ‘T’ must be marked with ‘GTY’. 2. Type ‘TP’ can only have type names in its argument list. 3. The pointer walker functions are different for ‘TP’ and ‘TP’. In the case of ‘TP’, references to ‘T’ must be handled by calling ‘gt_pch_nx’ (which will, in turn, walk all the pointers inside fields of ‘T’). In the case of ‘TP’, references to ‘T *’ must be handled by calling the ‘op’ function on the address of the pointer (see the code snippets above).