Target Attributes (GNU Compiler Collection (GCC) Internals)

### 19.26 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<const struct scoped_attribute_specs *const>` 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 `false` if the target-specific attributes on fndecl always block it getting inlined, `true` 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.

Macro: TARGET_HAS_FMV_TARGET_ATTRIBUTE ¶

  Define this macro to zero to use `target_version` attributes for function multiversioning (FMV) rather than `target` attributes.

  Targets using `target_version` attributes will also have "target_version" FMV semantics, which allow for FMV sets defined across TU’s and using a combination of `target_version` and `target_clones` attributed declarations in the definition of a FMV function set.

Macro: TARGET_CLONES_ATTR_SEPARATOR ¶

  Define this char-typed macro to select a character that separates each target specific attributes from the `attribute(target_clones("..."))` attribute string. This macro should be carefully chosen to avoid conflicts with the target specific attributes. The default value is `','`.

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. See 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_SAME_FUNCTION_VERSIONS `(string_slice fn1, const_tree decl1, string_slice fn2, const_tree decl2)` ¶

  This target hook returns `true` if the target/target-version strings fn1 and fn2 imply the same function version.

  If decl1 and decl2 are non `NULL` then fn1 and fn2 are from an earlier and a later declaration respectively, and the hook diagnoses any version string incompatibility for these decls. If the version strings are incompatible and the declarations can not be merged, then hook emits an error.

Target Hook: `bool` TARGET_OPTION_FUNCTIONS_B_RESOLVABLE_FROM_A `(tree decl_a, tree decl_v, tree base)` ¶

  decl_b is a function declaration with a function multi-versioning (FMV) attribute; this attribute is either `target` or `target_version`, depending on `TARGET_HAS_FMV_TARGET_ATTRIBUTE`. decl_a is a function declaration that may or may not have an FMV attribute.

  Return true if we have enough information to determine that the requirements of decl_b’s FMV attribute are met whenever decl_a is executed, given that the target supports all features required by function declaration base.

  The default implementation just checks whether decl_a has the same FMV attribute as decl_b. This is conservatively correct, but ports can do better by taking the relationships between architecture features into account. For example, on AArch64, `sve` is present whenever `sve2` is present.

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.