Devices belonging to @code{avrtiny} and @code{avrxmega3} can access
flash memory by means of @code{LD*} instructions because the flash
memory is mapped into the RAM address space. There is @emph{no need}
-for language extensions like @code{__flash} or attribute
-@ref{AVR Variable Attributes,,@code{progmem}}.
+for language extensions like @code{__flash} or attribute @code{progmem}.
The default linker description files for these devices cater for that
feature and @code{.rodata} stays in flash: The compiler just generates
@code{LD*} instructions, and the linker script adds core specific
@end smallexample
@noindent
-Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}}
+Notice that attribute @code{progmem}
locates data in flash but
accesses to these data read from generic address space, i.e.@:
from RAM,
@item
On the reduced Tiny devices like ATtiny40, no address spaces are supported.
Just use vanilla C / C++ code without overhead as outlined above.
-Attribute @code{progmem} is supported but works differently,
-see @ref{AVR Variable Attributes}.
+Attribute @code{progmem} is supported but works differently.
@end itemize
library header files in case they are included into files that have
redefined the base name of the attribute as a preprocessor macro.
-@menu
-* Function Attributes:: Declaring that functions have no side effects,
- or that they can never return.
-* Variable Attributes:: Specifying attributes of variables.
-* Type Attributes:: Specifying attributes of types.
-* Label Attributes:: Specifying attributes on labels.
-* Enumerator Attributes:: Specifying attributes on enumerators.
-* Statement Attributes:: Specifying attributes on statements.
-* GNU Attribute Syntax:: Formal syntax for attributes.
-@end menu
-
-@node Function Attributes
-@subsection Declaring Attributes of Functions
-@cindex function attributes
-@cindex declaring attributes of functions
-
-In GNU C and C++, you can use function attributes to specify certain
-function properties that may help the compiler optimize calls or
-check code more carefully for correctness. For example, you
-can use attributes to specify that a function never returns
-(@code{noreturn}), returns a value depending only on the values of
-its arguments (@code{const}), or has @code{printf}-style arguments
-(@code{format}).
-
-You can also use attributes to control memory placement, code
-generation options or call/return conventions within the function
-being annotated. Many of these attributes are target-specific. For
-example, many targets support attributes for defining interrupt
-handler functions, which typically must follow special register usage
-and return conventions. Such attributes are described in the subsection
-for each target. However, a considerable number of attributes are
-supported by most, if not all targets. Those are described in
-the @ref{Common Function Attributes} section.
-
-GCC provides two different ways to specify attributes: the traditional
-GNU syntax using @samp{__attribute__ ((...))} annotations, and the
-newer standard C and C++ syntax using @samp{[[...]]} with the
-@samp{gnu::} prefix on attribute names. Note that the exact rules for
-placement of attributes in your source code are different depending on
-which syntax you use. @xref{GNU Attribute Syntax}, for details.
-
-Compatible attribute specifications on distinct declarations
-of the same function are merged. An attribute specification that is not
-compatible with attributes already applied to a declaration of the same
-function is ignored with a warning.
-
Some function attributes take one or more arguments that refer to
the function's parameters by their positions within the function parameter
list. Such attribute arguments are referred to as @dfn{positional arguments}.
of parameters of reference to a pointer type. For ordinary functions,
position one refers to the first parameter on the list. In C++ non-static
member functions, position one refers to the implicit @code{this} pointer.
+
The same restrictions and effects apply to function attributes used with
ordinary functions or C++ member functions.
-GCC also supports attributes on
-variable declarations (@pxref{Variable Attributes}),
-labels (@pxref{Label Attributes}),
-enumerators (@pxref{Enumerator Attributes}),
-statements (@pxref{Statement Attributes}),
-types (@pxref{Type Attributes}),
-and on field declarations (for @code{tainted_args}).
-
-There is some overlap between the purposes of attributes and pragmas
-(@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been
-found convenient to use @code{__attribute__} to achieve a natural
-attachment of attributes to their corresponding declarations, whereas
-@code{#pragma} is of use for compatibility with other compilers
-or constructs that do not naturally form part of the grammar.
-
-In addition to the attributes documented here,
-GCC plugins may provide their own attributes.
-
@menu
-* Common Function Attributes::
-* AArch64 Function Attributes::
-* AMD GCN Function Attributes::
-* ARC Function Attributes::
-* ARM Function Attributes::
-* AVR Function Attributes::
-* Blackfin Function Attributes::
-* BPF Function Attributes::
-* C-SKY Function Attributes::
-* Epiphany Function Attributes::
-* H8/300 Function Attributes::
-* IA-64 Function Attributes::
-* LoongArch Function Attributes::
-* M32C Function Attributes::
-* M32R/D Function Attributes::
-* m68k Function Attributes::
-* MCORE Function Attributes::
-* MicroBlaze Function Attributes::
-* Microsoft Windows Function Attributes::
-* MIPS Function Attributes::
-* MSP430 Function Attributes::
-* NDS32 Function Attributes::
-* Nvidia PTX Function Attributes::
-* PowerPC Function Attributes::
-* RISC-V Function Attributes::
-* RL78 Function Attributes::
-* RX Function Attributes::
-* S/390 Function Attributes::
-* SH Function Attributes::
-* Symbian OS Function Attributes::
-* V850 Function Attributes::
-* Visium Function Attributes::
-* x86 Function Attributes::
-* Xstormy16 Function Attributes::
+* Common Attributes:: Attributes supported on most targets.
+* Target-Specific Attributes:: Attributes supported on particular targets.
+* GNU Attribute Syntax:: Formal syntax for attributes.
@end menu
-@node Common Function Attributes
-@subsubsection Common Function Attributes
+@node Common Attributes
+@subsection Common Attributes
The following GNU-specific attributes are supported on most targets in
both C and C++. When using the standard syntax, you must prefix their
documented later in this section, for more information and
caveats.
-@cindex @code{alias} function attribute
+@cindex @code{alias} attribute
@item alias ("@var{target}")
-The @code{alias} attribute causes the declaration to be emitted as an alias
-for another symbol, which must have been previously declared with the same
-type, and for variables, also the same size and alignment. Declaring an alias
-with a different type than the target is undefined and may be diagnosed. As
-an example, the following declarations:
+The @code{alias} attribute for variables and functions
+causes the declaration to be emitted
+as an alias for another symbol known as an @dfn{alias target}.
+
+For instance, the following
+
+@smallexample
+int var_target;
+extern int __attribute__ ((alias ("var_target"))) var_alias;
+@end smallexample
+
+@noindent
+defines @code{var_alias} to be an alias for the @code{var_target} variable,
+and
@smallexample
void __f () @{ /* @r{Do something.} */; @}
@end smallexample
@noindent
-define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name
-for the target must be used. It is an error if @samp{__f} is not defined in
-the same translation unit.
+defines @samp{f} to be a weak alias for @samp{__f}.
+
+Except for top-level qualifiers the alias target must have the same type as
+the alias. For variables, it must also have the same size and alignment.
+
+The alias target must be defined in the same translation
+unit as the alias. In C++, the mangled name for the target must be used.
+
+Note that in the absence of the attribute GCC assumes that distinct
+declarations with external linkage denote distinct objects. Using both
+the alias and the alias target to access the same object is undefined
+in a translation unit without a declaration of the alias with the attribute.
This attribute requires assembler and object file support,
and may not be available on all targets.
-@cindex @code{aligned} function attribute
+@cindex @code{aligned} attribute
@item aligned
@itemx aligned (@var{alignment})
-The @code{aligned} attribute specifies a minimum alignment for
-the first instruction of the function, measured in bytes. When specified,
-@var{alignment} must be an integer constant power of 2. Specifying no
+The @code{aligned} attribute specifies a minimum alignment for a function,
+variable, typedef, struct, or structure field, measured in bytes.
+When specified, @var{alignment} must be an integer constant power of 2.
+
+For example, the declaration:
+
+@smallexample
+int x __attribute__ ((aligned (16))) = 0;
+@end smallexample
+
+@noindent
+causes the compiler to allocate the global variable @code{x} on a
+16-byte boundary.
+
+These declarations:
+
+@smallexample
+struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
+typedef int more_aligned_int __attribute__ ((aligned (8)));
+@end smallexample
+
+@noindent
+force the compiler to ensure (as far as it can) that each variable whose
+type is @code{struct S} or @code{more_aligned_int} is allocated and
+aligned @emph{at least} on a 8-byte boundary.
+
+When applied to a function, specifying no
@var{alignment} argument implies the ideal alignment for the target.
The @code{__alignof__} operator can be used to determine what that is
(@pxref{Alignment}). The attribute has no effect when a definition for
Using the attribute overrides the effect of the @option{-falign-functions}
(@pxref{Optimize Options}) option for this function.
+For variables, types, and structure fields, increasing the alignment from
+the default can allow object copying to use larger chunks and make pointer
+arithmetic and array addressing more efficient. For example, some
+architectures can load and store 64-bit values only if they are
+aligned on 8-byte boundaries in memory. Explicitly aligning a
+structure type that contains two 32-bit fields on an 8-byte boundary
+allows it to be copied with a single pair of 64-bit load and store
+instructures instead of 2 pairs of 32-bit operations.
+
+Omitting the alignment from the attribute implies the default
+maximum alignment for the target architecture you are compiling for.
+This is sufficient for all scalar types, but may not be
+enough for all vector types on a target that supports vector operations.
+The default alignment is fixed for a particular target ABI.
+
+GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
+which is the largest alignment ever used for any data type on the
+target machine you are compiling for. For example, you could write:
+
+@smallexample
+short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
+@end smallexample
+
+@noindent
+This makes the compiler set the alignment for @code{array}
+to @code{__BIGGEST_ALIGNMENT__}. Note that the value of @code{__BIGGEST_ALIGNMENT__}
+may change depending on command-line options.
+
+When used on a struct, or struct member, the @code{aligned} attribute can
+only increase the alignment; in order to decrease it, the @code{packed}
+attribute must be specified as well. When used as part of a typedef, the
+@code{aligned} attribute can both increase and decrease alignment, and
+specifying the @code{packed} attribute generates a warning.
+
+The alignment of any given @code{struct} or @code{union} type
+is required by the ISO C standard to be at least a perfect multiple of
+the lowest common multiple of the alignments of all of the members of
+the @code{struct} or @code{union} in question. This means that you @emph{can}
+effectively adjust the alignment of a @code{struct} or @code{union}
+type by attaching an @code{aligned} attribute to any one of the members
+of such a type, but the notation illustrated in the example above is a
+more obvious, intuitive, and readable way to request the compiler to
+adjust the alignment of an entire @code{struct} or @code{union} type.
+
Note that the effectiveness of @code{aligned} attributes may be
limited by inherent limitations in the system linker
and/or object file format. On some systems, the
-linker is only able to arrange for functions to be aligned up to a
+linker is only able to arrange for functions or data to be aligned up to a
certain maximum alignment. (For some linkers, the maximum supported
alignment may be very very small.) See your linker documentation for
further information.
-The @code{aligned} attribute can also be used for variables and fields
-(@pxref{Variable Attributes}.)
+Stack variables are not affected by linker restrictions; GCC can properly
+align them on any target.
@cindex @code{alloc_align} function attribute
@item alloc_align (@var{position})
declares that @code{my_memalign} returns memory with minimum alignment
given by parameter 1.
-@cindex @code{alloc_size} function attribute
+@cindex @code{alloc_size} attribute
@item alloc_size (@var{position})
@itemx alloc_size (@var{position-1}, @var{position-2})
The @code{alloc_size} attribute may be applied to a function that
returns a pointer and takes at least one argument of an integer or
-enumerated type.
+enumerated type, or to the declaration of the type of such a function,
+or a type or variable with a type of pointer to such a function.
+
It indicates that the returned pointer points to memory whose size is
given by the function argument at @var{position-1}, or by the product
of the arguments at @var{position-1} and @var{position-2}. Meaningful
the product of parameter 1 and 2 and that @code{my_realloc} returns memory
of the size given by parameter 2.
+Similarly, the following declarations
+
+@smallexample
+typedef __attribute__ ((alloc_size (1, 2))) void*
+ (*calloc_ptr) (size_t, size_t);
+typedef __attribute__ ((alloc_size (1))) void*
+ (*malloc_ptr) (size_t);
+@end smallexample
+
+@noindent
+specify that @code{calloc_ptr} is a pointer to a function that, like
+the standard C function @code{calloc}, returns an object whose size
+is given by the product of arguments 1 and 2, and similarly, that
+@code{malloc_ptr}, like the standard C function @code{malloc},
+is a pointer to a function that returns an object whose size is
+given by argument 1 to the function.
+
@cindex @code{always_inline} function attribute
@item always_inline
Generally, functions are not inlined unless optimization is specified.
@cindex @code{artificial} function attribute
@item artificial
-This attribute is useful for small inline wrappers that if possible
+This function attribute is useful for small inline wrappers that if possible
should appear during debugging as a unit. Depending on the debug
info format it either means marking the function as artificial
or using the caller location for all instructions within the inlined
body.
+@cindex @code{assume} statement attribute
+@item assume
+The @code{assume} attribute with a null statement serves as portable
+assumption. It should have a single argument, a conditional expression,
+which is not evaluated. If the argument would evaluate to true
+at the point where it appears, it has no effect, otherwise there
+is undefined behavior. This is a GNU variant of the ISO C++23
+standard @code{assume} attribute, but it can be used in any version of
+both C and C++.
+
+@smallexample
+int
+foo (int x, int y)
+@{
+ __attribute__((assume(x == 42)));
+ __attribute__((assume(++y == 43)));
+ return x + y;
+@}
+@end smallexample
+
+@code{y} is not actually incremented and the compiler can but does not
+have to optimize it to just @code{return 42 + 42;}.
+
@cindex @code{assume_aligned} function attribute
@item assume_aligned (@var{alignment})
@itemx assume_aligned (@var{alignment}, @var{offset})
that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
to 8.
-@cindex @code{btf_decl_tag} function attribute
+@cindex @code{btf_decl_tag} attribute
@item btf_decl_tag
The @code{btf_decl_tag} attribute may be used to associate function
-declarations with arbitrary strings by recording those strings in DWARF
-and/or BTF information in the same way that it is used for variables.
-See @ref{Common Variable Attributes}.
+declarations, variable
+declarations, struct or union member declarations, function
+declarations, and function parameter declarations with arbitrary strings.
+These strings are not interpreted by the compiler in any way, and have
+no effect on code generation. Instead, these user-provided strings
+are recorded in DWARF (via @code{DW_AT_GNU_annotation} and
+@code{DW_TAG_GNU_annotation} extensions) and BTF information (via
+@code{BTF_KIND_DECL_TAG} records), and associated to the attributed
+declaration. If neither DWARF nor BTF information is generated, the
+attribute has no effect.
+
+The argument is treated as a null-terminated sequence of zero or more
+non-null bytes. Wide character strings are not supported.
+
+The attribute may be supplied multiple times for a single declaration,
+in which case each distinct argument string will be recorded in a
+separate DIE or BTF record, each associated to the declaration. For
+a single declaration with multiple @code{btf_decl_tag} attributes,
+the order of the @code{DW_TAG_GNU_annotation} DIEs produced is not
+guaranteed to maintain the order of attributes in the source code.
+
+For example:
+
+@smallexample
+int *foo __attribute__ ((btf_decl_tag ("__percpu")));
+@end smallexample
+
+@noindent
+when compiled with @option{-gbtf} results in an additional
+@code{BTF_KIND_DECL_TAG} BTF record to be emitted in the BTF info,
+associating the string @samp{__percpu} with the @code{BTF_KIND_VAR}
+record for the variable @code{foo}.
+
+@cindex @code{btf_type_tag} type attribute
+@item btf_type_tag (@var{argument})
+The @code{btf_type_tag} attribute may be used to associate (to ``tag'')
+particular types with arbitrary string annotations. These annotations
+are recorded in debugging info by supported debug formats, currently
+DWARF (via @code{DW_AT_GNU_annotation} and @code{DW_TAG_GNU_annotation}
+extensions) and BTF (via @code{BTF_KIND_TYPE_TAG} records). These
+annotation strings are not interpreted by the compiler in any way, and
+have no effect on code generation. If neither DWARF nor BTF
+information is generated, the attribute has no effect.
+
+The argument is treated as a null-terminated sequence of zero or more
+non-null bytes. Wide character strings are not supported.
+
+The attribute may be supplied multiple times for a single type, in
+which case each distinct argument string will be recorded in a
+separate DIE or BTF record, each associated to the type. For a single
+type with multiple @code{btf_type_tag} attributes, the order of the
+@code{DW_TAG_GNU_annotation} DIEs produced is not guaranteed to
+maintain the order of attributes in the source code.
+
+For example the following code:
+
+@smallexample
+int * __attribute__ ((btf_type_tag ("__user"))) foo;
+@end smallexample
+
+@noindent
+when compiled with @option{-gbtf} results in an additional
+@code{BTF_KIND_TYPE_TAG} BTF record to be emitted in the BTF info,
+associating the string @samp{__user} with the normal @code{BTF_KIND_PTR}
+record for the pointer-to-integer type used in the declaration.
+
+Note that the BTF format currently only has a representation for type
+tags associated with pointer types. Type tags on non-pointer types
+may be silently skipped when generating BTF.
+
+@cindex @code{cleanup} variable attribute
+@item cleanup (@var{cleanup_function})
+The @code{cleanup} attribute runs a function when the variable goes
+out of scope. This attribute can only be applied to auto function
+scope variables; it may not be applied to parameters or variables
+with static storage duration. The function must take one parameter,
+a pointer to a type compatible with the variable. The return value
+of the function (if any) is ignored.
+
+When multiple variables in the same scope have @code{cleanup}
+attributes, at exit from the scope their associated cleanup functions
+are run in reverse order of definition (last defined, first
+cleanup).
+
+If @option{-fexceptions} is enabled, then @var{cleanup_function}
+is run during the stack unwinding that happens during the
+processing of the exception. Note that the @code{cleanup} attribute
+does not allow the exception to be caught, only to perform an action.
+It is undefined what happens if @var{cleanup_function} does not
+return normally.
-@cindex @code{cold} function attribute
+@cindex @code{cold} attribute
@item cold
+The @code{cold} attribute can apply to functions or labels.
+
The @code{cold} attribute on functions is used to inform the compiler that
the function is unlikely to be executed. The function is optimized for
size rather than speed and on many targets it is placed into a special
When profile feedback is available, via @option{-fprofile-use}, cold functions
are automatically detected and this attribute is ignored.
+Used as a statement attribute associated with a label,
+the @code{cold} attribute informs the compiler that
+the path following the label is unlikely to be executed. This attribute
+is used in cases where @code{__builtin_expect} cannot be used, for instance
+with computed goto or @code{asm goto}.
+
+@cindex @code{common} variable attribute
+@cindex @code{nocommon} variable attribute
+@opindex fcommon
+@opindex fno-common
+@item common
+@itemx nocommon
+The @code{common} attribute requests GCC to place a variable in
+``common'' storage. The @code{nocommon} attribute requests the
+opposite---to allocate space for it directly.
+
+These attributes override the default chosen by the
+@option{-fno-common} and @option{-fcommon} flags respectively.
+
@cindex @code{const} function attribute
@cindex functions that have no side effects
@item const
those not using ELF object format, or the GNU linker) reject this
usage.
-@cindex @code{copy} function attribute
+@cindex @code{copy} attribute
@item copy
-@itemx copy (@var{function})
-The @code{copy} attribute applies the set of attributes with which
-@var{function} has been declared to the declaration of the function
-to which the attribute is applied. The attribute is designed for
+@itemx copy (@var{name})
+The @code{copy} attribute for function, variable, and type declarations
+applies the set of attributes with which
+@var{name} has been declared to the declaration of the function, variable,
+or type to which the attribute is applied. The attribute is designed for
libraries that define aliases or function resolvers that are expected
to specify the same set of attributes as their targets. The @code{copy}
attribute can be used with functions, variables, or types. However,
but not attributes that affect a symbol's linkage or visibility such as
@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
and @code{target_clones} attribute are also not copied.
-@xref{Common Type Attributes}.
-@xref{Common Variable Attributes}.
For example, the @var{StrongAlias} macro below makes use of the @code{alias}
and @code{copy} attributes to define an alias named @var{alloc} for function
StrongAlias (allocate, alloc);
@end smallexample
-@cindex @code{deprecated} function attribute
-@item deprecated
-@itemx deprecated (@var{msg})
-The @code{deprecated} attribute results in a warning if the function
-is used anywhere in the source file. This is useful when identifying
-functions that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated function, to enable users to easily find further
-information about why the function is deprecated, or what they should
-do instead. Note that the warnings only occurs for uses:
+As another example, suppose @code{struct A} below is defined in some
+third-party library header to have the alignment requirement @code{N} and
+to force a warning whenever a variable of the type is not so aligned
+due to attribute @code{packed}. Specifying the @code{copy} attribute
+on the definition on the unrelated @code{struct B} has the effect of
+copying all relevant attributes from the type referenced by the pointer
+expression to @code{struct B}.
@smallexample
-int old_fn () __attribute__ ((deprecated));
-int old_fn ();
-int (*fn_ptr)() = old_fn;
+struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
+A @{ /* @r{@dots{}} */ @};
+struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
@end smallexample
-@noindent
-results in a warning on line 3 but not line 2. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present.
-
-The @code{deprecated} attribute can also be used for variables and
-types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
-
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
-
-@cindex @code{error} function attribute
-@cindex @code{warning} function attribute
+@cindex @code{counted_by} variable attribute
+@item counted_by (@var{count})
+The @code{counted_by} attribute may be attached to the C99 flexible array
+member, or a pointer field of a structure. It indicates that the number
+of the elements of the array that is held by the flexible array member
+field, or is pointed to by the pointer field, is given by the field
+"@var{count}" in the same structure as the flexible array member or the
+pointer field.
+
+This attribute is available only in C for now.
+In C++ this attribute is ignored.
+
+GCC may use this information to improve detection of object size information
+for such structures and provide better results in compile-time diagnostics
+and runtime features like the array bound sanitizer and
+the @code{__builtin_dynamic_object_size}.
+
+For instance, the following code:
+
+@smallexample
+struct P @{
+ size_t count;
+ char other;
+ char array[] __attribute__ ((counted_by (count)));
+@} *p;
+@end smallexample
+
+@noindent
+specifies that the @code{array} is a flexible array member whose number
+of elements is given by the field @code{count} in the same structure.
+
+@smallexample
+struct PP @{
+ size_t count2;
+ char other1;
+ char *array2 __attribute__ ((counted_by (count2)));
+ int other2;
+@} *pp;
+@end smallexample
+
+@noindent
+specifies that the @code{array2} is an array that is pointed by the
+pointer field, and its number of elements is given by the field
+@code{count2} in the same structure.
+
+The field that represents the number of the elements should have an
+integer type. Otherwise, the compiler reports an error and ignores
+the attribute.
+
+When the field that represents the number of the elements is assigned a
+negative integer value, the compiler treats the value as zero.
+
+The @code{counted_by} attribute is not allowed for a pointer to function,
+or a pointer to a structure or union that includes a flexible array member.
+However, it is allowed for a pointer to non-void incomplete structure
+or union types, as long as the type could be completed before the first
+reference to the pointer.
+
+The attribute is allowed for a pointer to @code{void}. However,
+warnings will be issued for such cases when @option{-Wpointer-arith} is
+specified. When this attribute is applied on a pointer to @code{void},
+the size of each element of this pointer array is treated as 1.
+
+An explicit @code{counted_by} annotation defines a relationship between
+two objects, @code{p->array} and @code{p->count}, and there are the
+following requirements on the relationship between this pair:
+
+@itemize @bullet
+@item
+@code{p->count} must be initialized before the first reference to
+@code{p->array};
+
+@item
+@code{p->array} has @emph{at least} @code{p->count} number of elements
+available all the time. This relationship must hold even after any of
+these related objects are updated during the program.
+@end itemize
+
+In addition to the above requirements, there is one more requirement
+between this pair if and only if @code{p->array} is an array that is
+pointed by the pointer field:
+
+@code{p->array} and @code{p->count} can only be changed by changing the
+whole structure at the same time.
+
+It's the programmer's responsibility to make sure the above requirements to
+be kept all the time. Otherwise the compiler reports warnings and
+the results of the array bound sanitizer and the
+@code{__builtin_dynamic_object_size} built-in are undefined.
+
+One important feature of the attribute is that a reference to the flexible
+array member field uses the latest value assigned to the field that
+represents the number of the elements before that reference. For example,
+
+@smallexample
+ p->count = val1;
+ p->array[20] = 0; // ref1 to p->array
+ p->count = val2;
+ p->array[30] = 0; // ref2 to p->array
+@end smallexample
+
+@noindent
+In the above, @code{ref1} uses @code{val1} as the number of the elements in
+@code{p->array}, and @code{ref2} uses @code{val2} as the number of elements
+in @code{p->array}.
+
+Note, however, the above feature is not valid for the pointer field.
+
+@cindex @code{deprecated} attribute
+@item deprecated
+@itemx deprecated (@var{msg})
+The @code{deprecated} attribute results in a warning if the function,
+variable, type, or enumerator it applies to
+is used anywhere in the source file. This is useful when identifying
+functions that are expected to be removed in a future version of a
+program. The warning also includes the location of the declaration
+of the deprecated entity, to enable users to easily find further
+information about why it is deprecated, or what they should
+do instead. Note that the warnings only occurs for uses:
+
+@smallexample
+int old_fn () __attribute__ ((deprecated));
+int old_fn ();
+int (*fn_ptr)() = old_fn;
+@end smallexample
+
+@noindent
+results in a warning on line 3 but not line 2. The optional @var{msg}
+argument, which must be a string, is printed in the warning if
+present.
+
+When applied to a type, warnings only occur for uses and also only if
+the type is being applied to an identifier that itself is not being
+declared as deprecated.
+@smallexample
+typedef int T1 __attribute__ ((deprecated));
+T1 x;
+typedef T1 T2;
+T2 y;
+typedef T1 T3 __attribute__ ((deprecated));
+T3 z __attribute__ ((deprecated));
+@end smallexample
+
+@noindent
+results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
+warning is issued for line 4 because @code{T2} is not explicitly
+deprecated. Line 5 has no warning because @code{T3} is explicitly
+deprecated. Similarly for line 6.
+
+This example uses the @code{deprecated} enumerator attribute to indicate the
+@code{oldval} enumerator is deprecated:
+
+@smallexample
+enum E @{
+ oldval __attribute__((deprecated)),
+ newval
+@};
+
+int
+fn (void)
+@{
+ return oldval;
+@}
+@end smallexample
+
+The optional @var{msg}
+argument, which must be a string, is printed in the warning if
+present.
+The @var{msg} string is affected by the setting of
+the @option{-fmessage-length} option.
+Control characters in the @var{msg} string are replaced with
+escape sequences, and if the @option{-fmessage-length} option is set
+to 0 (its default value) then any newline characters are ignored.
+
+@cindex @code{designated_init} type attribute
+@item designated_init
+This attribute may only be applied to structure types. It indicates
+that any initialization of an object of this type must use designated
+initializers rather than positional initializers. The intent of this
+attribute is to allow the programmer to indicate that a structure's
+layout may change, and that therefore relying on positional
+initialization will result in future breakage.
+
+GCC emits warnings based on this attribute by default; use
+@option{-Wno-designated-init} to suppress them.
+
+@cindex @code{error} function attribute
+@cindex @code{warning} function attribute
@item error ("@var{message}")
@itemx warning ("@var{message}")
If the @code{error} or @code{warning} attribute
@samp{-fharden-control-flow-redundancy} is enabled, and
@samp{-fhardcfr-check-noreturn-calls=not-always} is not overridden.
-@cindex @code{externally_visible} function attribute
+@cindex @code{externally_visible} attribute
@item externally_visible
This attribute, attached to a global variable or function, nullifies
the effect of the @option{-fwhole-program} command-line option, so the
For other linkers that cannot generate resolution file,
explicit @code{externally_visible} attributes are still necessary.
+@cindex @code{fallthrough} statement attribute
+@item fallthrough
+The @code{fallthrough} attribute, which attaches to a null statement,
+serves as a
+fallthrough statement. It hints to the compiler that a statement
+that falls through to another case label, or user-defined label
+in a switch statement is intentional and thus the
+@option{-Wimplicit-fallthrough} warning must not trigger. The
+fallthrough attribute may appear at most once in each attribute
+list, and may not be mixed with other attributes. It can only
+be used in a switch statement (the compiler issues an error
+otherwise), after a preceding statement and before a logically
+succeeding case label, or user-defined label.
+
+This example uses the @code{fallthrough} statement attribute to indicate that
+the @option{-Wimplicit-fallthrough} warning should not be emitted:
+
+@smallexample
+switch (cond)
+ @{
+ case 1:
+ bar (1);
+ __attribute__((fallthrough));
+ case 2:
+ @dots{}
+ @}
+@end smallexample
+
@cindex @code{fd_arg} function attribute
@item fd_arg
@itemx fd_arg (@var{N})
The @code{fd_arg} attribute may be applied to a function that takes an open
file descriptor at referenced argument @var{N}.
-It indicates that the passed filedescriptor must not have been closed.
+It indicates that the passed file descriptor must not have been closed.
Therefore, when the analyzer is enabled with @option{-fanalyzer}, the
analyzer may emit a @option{-Wanalyzer-fd-use-after-close} diagnostic
if it detects a code path in which a function with this attribute is
it detects a code path in which a function with this attribute is called on a
file descriptor opened with @code{O_RDONLY}.
+@cindex @code{flag_enum} type attribute
+@item flag_enum
+This attribute may be applied to an enumerated type to indicate that
+its enumerators are used in bitwise operations, so e.g. @option{-Wswitch}
+should not warn about a @code{case} that corresponds to a bitwise
+combination of enumerators.
+
@cindex @code{flatten} function attribute
@item flatten
Generally, inlining into a function is limited. For a function marked with
but it still requires the @code{inline} keyword to enable its special
behavior.
-@cindex @code{hot} function attribute
-@item hot
-The @code{hot} attribute on a function is used to inform the compiler that
-the function is a hot spot of the compiled program. The function is
-optimized more aggressively and on many targets it is placed into a special
-subsection of the text section so all hot functions appear close together,
-improving locality. In C++, the @code{hot} attribute can be applied to types
-with the effect of being propagated to member functions. See
-@ref{C++ Attributes}.
+@cindex @code{hardbool} type attribute
+@item hardbool
+@itemx hardbool (@var{false_value})
+@itemx hardbool (@var{false_value}, @var{true_value})
+This attribute may only be applied to integral types in C, to introduce
+hardened boolean types. It turns the integral type into a boolean-like
+type with the same size and precision, that uses the specified values as
+representations for @code{false} and @code{true}. Underneath, it is
+actually an enumerated type, but its observable behavior is like that of
+@code{_Bool}, except for the strict internal representations, verified
+by runtime checks.
-When profile feedback is available, via @option{-fprofile-use}, hot functions
-are automatically detected and this attribute is ignored.
+If @var{true_value} is omitted, the bitwise negation of
+@var{false_value} is used. If @var{false_value} is omitted, zero is
+used. The named representation values must be different when converted
+to the original integral type. Narrower bitfields are rejected if the
+representations become indistinguishable.
-@cindex @code{ifunc} function attribute
-@cindex indirect functions
-@cindex functions that are dynamically resolved
-@item ifunc ("@var{resolver}")
-The @code{ifunc} attribute is used to mark a function as an indirect
-function using the STT_GNU_IFUNC symbol type extension to the ELF
-standard. This allows the resolution of the symbol value to be
-determined dynamically at load time, and an optimized version of the
-routine to be selected for the particular processor or other system
-characteristics determined then. To use this attribute, first define
-the implementation functions available, and a resolver function that
-returns a pointer to the selected implementation function. The
-implementation functions' declarations must match the API of the
-function being implemented. The resolver should be declared to
-be a function taking no arguments and returning a pointer to
-a function of the same type as the implementation. For example:
+Values of such types automatically decay to @code{_Bool}, at which
+point, the selected representation values are mapped to the
+corresponding @code{_Bool} values. When the represented value is not
+determined, at compile time, to be either @var{false_value} or
+@var{true_value}, runtime verification calls @code{__builtin_trap} if it
+is neither. This is what makes them hardened boolean types.
-@smallexample
-void *my_memcpy (void *dst, const void *src, size_t len)
+When converting scalar types to such hardened boolean types, implicitly
+or explicitly, behavior corresponds to a conversion to @code{_Bool},
+followed by a mapping from @code{false} and @code{true} to
+@var{false_value} and @var{true_value}, respectively.
+
+@smallexample
+typedef char __attribute__ ((__hardbool__ (0x5a))) hbool;
+hbool first = 0; /* False, stored as (char)0x5a. */
+hbool second = !first; /* True, stored as ~(char)0x5a. */
+
+static hbool zeroinit; /* False, stored as (char)0x5a. */
+auto hbool uninit; /* Undefined, may trap. */
+@end smallexample
+
+When zero-initializing a variable or field of hardened boolean type
+(presumably held in static storage) the implied zero initializer gets
+converted to @code{_Bool}, and then to the hardened boolean type, so
+that the initial value is the hardened representation for @code{false}.
+Using that value is well defined. This is @emph{not} the case when
+variables and fields of such types are uninitialized (presumably held in
+automatic or dynamic storage): their values are indeterminate, and using
+them invokes undefined behavior. Using them may trap or not, depending
+on the bits held in the storage (re)used for the variable, if any, and
+on optimizations the compiler may perform on the grounds that using
+uninitialized values invokes undefined behavior.
+
+Users of @option{-ftrivial-auto-var-init} should be aware that the bit
+patterns used as initializers are @emph{not} converted to
+@code{hardbool} types, so using a @code{hardbool} variable that is
+implicitly initialized by the @option{-ftrivial-auto-var-init} may trap
+if the representations values chosen for @code{false} and @code{true} do
+not match the initializer.
+
+Since this is a language extension only available in C, interoperation
+with other languages may pose difficulties. It should interoperate with
+Ada Booleans defined with the same size and equivalent representation
+clauses, and with enumerations or other languages' integral types that
+correspond to C's chosen integral type.
+
+@cindex @code{hot} attribute
+@item hot
+This attribute can appear as a function attribute or as a statement
+attribute applying to a label.
+
+The @code{hot} attribute on a function is used to inform the compiler that
+the function is a hot spot of the compiled program. The function is
+optimized more aggressively and on many targets it is placed into a special
+subsection of the text section so all hot functions appear close together,
+improving locality. In C++, the @code{hot} attribute can be applied to types
+with the effect of being propagated to member functions. See
+@ref{C++ Attributes}.
+
+When profile feedback is available, via @option{-fprofile-use}, hot functions
+are automatically detected and this attribute is ignored.
+
+The @code{hot} attribute on a label is used to inform the compiler that
+the path following the label is more likely than paths that are not so
+annotated. This attribute is used in cases where @code{__builtin_expect}
+cannot be used, for instance with computed goto or @code{asm goto}.
+
+@cindex @code{ifunc} function attribute
+@cindex indirect functions
+@cindex functions that are dynamically resolved
+@item ifunc ("@var{resolver}")
+The @code{ifunc} attribute is used to mark a function as an indirect
+function using the STT_GNU_IFUNC symbol type extension to the ELF
+standard. This allows the resolution of the symbol value to be
+determined dynamically at load time, and an optimized version of the
+routine to be selected for the particular processor or other system
+characteristics determined then. To use this attribute, first define
+the implementation functions available, and a resolver function that
+returns a pointer to the selected implementation function. The
+implementation functions' declarations must match the API of the
+function being implemented. The resolver should be declared to
+be a function taking no arguments and returning a pointer to
+a function of the same type as the implementation. For example:
+
+@smallexample
+void *my_memcpy (void *dst, const void *src, size_t len)
@{
@dots{}
return dst;
a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths
in which the deallocator is called with null.
-@cindex @code{no_icf} function attribute
+@cindex @code{may_alias} type attribute
+@item may_alias
+The @code{may_alias} attribute applies to pointer type declarations.
+
+Accesses through pointers to types with this attribute are not subject
+to type-based alias analysis, but are instead assumed to be able to alias
+any other type of objects.
+In the context of section 6.5 paragraph 7 of the C99 standard,
+an lvalue expression
+dereferencing such a pointer is treated like having a character type.
+See @option{-fstrict-aliasing} for more information on aliasing issues.
+This extension exists to support some vector APIs, in which pointers to
+one vector type are permitted to alias pointers to a different vector type.
+
+Note that an object of a type with this attribute does not have any
+special semantics.
+
+Example of use:
+
+@smallexample
+typedef short __attribute__ ((__may_alias__)) short_a;
+
+int
+main (void)
+@{
+ int a = 0x12345678;
+ short_a *b = (short_a *) &a;
+
+ b[1] = 0;
+
+ if (a == 0x12345678)
+ abort();
+
+ exit(0);
+@}
+@end smallexample
+
+@noindent
+If you replaced @code{short_a} with @code{short} in the variable
+declaration, the above program would abort when compiled with
+@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
+above.
+
+@cindex @code{mode} attribute
+@item mode (@var{mode})
+This attribute can apply to a variable or type declaration.
+It specifies the data type for the declaration---whichever
+type corresponds to the mode @var{mode}. This in effect lets you
+request an integer or floating-point type according to its width.
+
+@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
+for a list of the possible keywords for @var{mode}.
+You may also specify a mode of @code{byte} or @code{__byte__} to
+indicate the mode corresponding to a one-byte integer, @code{word} or
+@code{__word__} for the mode of a one-word integer, and @code{pointer}
+or @code{__pointer__} for the mode used to represent pointers.
+
+@cindex @code{musttail} statement attribute
+@item musttail
+
+The @code{gnu::musttail} or @code{clang::musttail} standard attribute
+or @code{musttail} GNU attribute can be applied to a @code{return} statement
+with a return-value expression that is a function call. It asserts that the
+call must be a tail call that does not allocate extra stack space, so it is
+safe to use tail recursion to implement long-running loops.
+
+@smallexample
+[[gnu::musttail]] return foo();
+@end smallexample
+
+@smallexample
+__attribute__((musttail)) return bar();
+@end smallexample
+
+If the compiler cannot generate a @code{musttail} tail call it reports
+an error. On some targets, tail calls may not be supported at all.
+The @code{musttail} attribute asserts that the lifetime of automatic
+variables, function parameters and temporaries (unless they have non-trivial
+destruction) can end before the actual call instruction, and that any access
+to those from inside of the called function results is considered undefined
+behavior. Enabling @option{-O1} or @option{-O2} can improve the success of
+tail calls.
+
+@smallexample
+int foo (int *);
+void bar (int *);
+struct S @{ S (); ~S (); int s; @};
+
+int
+baz (int *x)
+@{
+ if (*x == 1)
+ @{
+ int a = 42;
+ /* The call is a tail call (would not be without the
+ attribute). Dereferencing the pointer in the callee is
+ undefined behavior, and there is a warning emitted
+ for this by default (@option{-Wmusttail-local-addr}). */
+ [[gnu::musttail]] return foo (&a);
+ @}
+ else if (*x == 2)
+ @{
+ int a = 42;
+ bar (&a);
+ /* The call is a tail call (would not be without the
+ attribute). If bar stores the pointer anywhere, dereferencing
+ it in foo is undefined behavior. There is a warning
+ emitted for this with @option{-Wextra}, which implies
+ @option{-Wmaybe-musttail-local-addr}. */
+ [[gnu::musttail]] return foo (nullptr);
+ @}
+ else
+ @{
+ S s;
+ /* The s variable requires non-trivial destruction which ought
+ to be performed after the foo call returns, so this is
+ rejected. */
+ [[gnu::musttail]] return foo (&s.s);
+ @}
+@}
+@end smallexample
+
+To avoid the @option{-Wmaybe-musttail-local-addr} warning in the
+above @code{*x == 2} case and similar code, consider defining the
+maybe-escaped variables in a separate scope that ends before the
+return statement, if that is possible, to make it clear that the
+variable is not live during the call. So:
+
+@smallexample
+ else if (*x == 2)
+ @{
+ @{
+ int a = 42;
+ bar (&a);
+ @}
+ /* The call is a tail call (would not be without the
+ attribute). If bar stores the pointer anywhere, dereferencing
+ it in foo is undefined behavior even without tail call
+ optimization, and there is no warning. */
+ [[gnu::musttail]] return foo (nullptr);
+ @}
+@end smallexample
+
+It is not possible to avoid the warning in this way if the maybe-escaped
+variable is a function argument, because those are in scope
+for the whole function.
+
+@cindex @code{no_icf} attribute
@item no_icf
-This function attribute prevents a functions from being merged with another
-semantically equivalent function.
+This function attribute prevents a function or variable from being
+merged with another semantically equivalent function or variable.
@cindex @code{no_instrument_function} function attribute
@opindex finstrument-functions
to inform the compiler that it should not process any profile feedback based
optimization code instrumentation.
-@cindex @code{no_reorder} function attribute
+@cindex @code{no_reorder} attribute
@item no_reorder
Do not reorder functions or variables marked @code{no_reorder}
against each other or top level assembler statements the executable.
and which is (currently) performed by interprocedural constant
propagation.
+@cindex @code{noinit} variable attribute
+@item noinit
+Variables with the @code{noinit} attribute are not initialized by
+the C runtime startup code, or the program loader. Not initializing
+data in this way can reduce program startup times.
+
+This attribute is specific to ELF targets and relies on the linker
+script to place sections with the @code{.noinit} prefix in the right
+location.
+
@cindex @code{noinline} function attribute
@item noinline
This function attribute prevents a function from being considered for
@item nonnull_if_nonzero
@itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index})
@itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index}, @var{arg3-index})
-The @code{nonnull_if_nonzero} attribute is a conditional version of the
+The @code{nonnull_if_nonzero} function attribute is a conditional version
+of the
@code{nonnull} attribute. It has two or three arguments, the first argument
shall be argument index of a pointer argument which must be in some
cases non-null and the second argument shall be argument index of an
used on declarations which have e.g.@: an exception for zero sizes,
in which case null may be passed.
-@cindex @code{noplt} function attribute
-@item noplt
-The @code{noplt} attribute is the counterpart to option @option{-fno-plt}.
-Calls to functions marked with this attribute in position-independent code
-do not use the PLT.
+@cindex @code{nonstring} variable attribute
+@item nonstring
+The @code{nonstring} variable attribute specifies that an object or member
+declaration with type array of @code{char}, @code{signed char}, or
+@code{unsigned char}, or pointer to such a type is intended to store
+character arrays that do not necessarily contain a terminating @code{NUL}.
+This is useful in detecting uses of such arrays or pointers with functions
+that expect @code{NUL}-terminated strings, and to avoid warnings when such
+an array or pointer is used as an argument to a bounded string manipulation
+function such as @code{strncpy}. For example, without the attribute, GCC
+will issue a warning for the @code{strncpy} call below because it may
+truncate the copy without appending the terminating @code{NUL} character.
+Using the attribute makes it possible to suppress the warning. However,
+when the array is declared with the attribute the call to @code{strlen} is
+diagnosed because when the array doesn't contain a @code{NUL}-terminated
+string the call is undefined. To copy, compare, or search non-string
+character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
+and other functions that operate on arrays of bytes. In addition,
+calling @code{strnlen} and @code{strndup} with such arrays is safe
+provided a suitable bound is specified, and not diagnosed.
@smallexample
-@group
-/* Externally defined function foo. */
-int foo () __attribute__ ((noplt));
-
+struct Data
+@{
+ char name [32] __attribute__ ((nonstring));
+@};
+
+int f (struct Data *pd, const char *s)
+@{
+ strncpy (pd->name, s, sizeof pd->name);
+ @dots{}
+ return strlen (pd->name); // unsafe, gets a warning
+@}
+@end smallexample
+
+@cindex @code{noplt} function attribute
+@item noplt
+The @code{noplt} function attribute is the counterpart to option
+@option{-fno-plt}.
+Calls to functions marked with this attribute in position-independent code
+do not use the PLT.
+
+@smallexample
+@group
+/* Externally defined function foo. */
+int foo () __attribute__ ((noplt));
+
int
main (/* @r{@dots{}} */)
@{
be validly null-terminated, or validly readable up to the size specified by
the second parameter.
+@cindex @code{objc_nullability} variable attribute
+@item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
+This attribute applies to pointer variables only. It allows marking the
+pointer with one of four possible values describing the conditions under
+which the pointer might have a @code{nil} value. In most cases, the
+attribute is intended to be an internal representation for property and
+method nullability (specified by language keywords); it is not recommended
+to use it directly.
+
+When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
+known about the conditions in which the pointer might be @code{nil}. Making
+this state specific serves to avoid false positives in diagnostics.
+
+When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
+no meaning if it is @code{nil} and thus the compiler is free to emit
+diagnostics if it can be determined that the value will be @code{nil}.
+
+When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
+be @code{nil} and carry meaning as such.
+
+When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
+the context of property attribute lists) this describes the case in which a
+property setter may take the value @code{nil} (which perhaps causes the
+property to be reset in some manner to a default) but for which the property
+getter will never validly return @code{nil}.
+
+@cindex @code{objc_root_class} type attribute
+@item objc_root_class @r{(Objective-C and Objective-C++ only)}
+This attribute marks a class as being a root class, and thus allows
+the compiler to elide any warnings about a missing superclass and to
+make additional checks for mandatory methods as needed.
+
@cindex @code{optimize} function attribute
@item optimize (@var{level}, @dots{})
@item optimize (@var{string}, @dots{})
The @code{optimize} attribute should be used for debugging purposes only.
It is not suitable in production code.
+@cindex @code{packed} attribute
+@item packed
+This attribute can be attached to a @code{struct}, @code{union}, or
+C++ @code{class} definition, to a member of one, or to an @code{enum}
+definition.
+
+The @code{packed} attribute on a structure member specifies that the
+member should have
+the smallest possible alignment---one bit for a bit-field and one byte
+otherwise, unless a larger value is specified with the @code{aligned}
+attribute. The attribute does not apply to non-member objects.
+
+For example in the structure below, the member array @code{x} is packed
+so that it immediately follows @code{a} with no intervening padding:
+
+@smallexample
+struct foo
+@{
+ char a;
+ int x[2] __attribute__ ((packed));
+@};
+@end smallexample
+
+@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
+@code{packed} attribute on bit-fields of type @code{char}. This has
+been fixed in GCC 4.4 but the change can lead to differences in the
+structure layout. See the documentation of
+@option{-Wpacked-bitfield-compat} for more information.
+
+Applied to a @code{struct}, @code{union}, or C++ @code{class} definition
+as a whole, it specifies that each of its members (other
+than zero-width
+bit-fields) is placed to minimize the memory required. This is equivalent
+to specifying the @code{packed} attribute on each of the members.
+
+In the following example @code{struct my_packed_struct}'s members are
+packed closely together, but the internal layout of its @code{s} member
+is not packed---to do that, @code{struct my_unpacked_struct} needs to
+be packed too.
+
+@smallexample
+struct my_unpacked_struct
+ @{
+ char c;
+ int i;
+ @};
+
+struct __attribute__ ((__packed__)) my_packed_struct
+ @{
+ char c;
+ int i;
+ struct my_unpacked_struct s;
+ @};
+@end smallexample
+
+@opindex fshort-enums
+When attached to an @code{enum} definition, the @code{packed} attribute
+indicates that the smallest integral type should be used to represent the type.
+Specifying the @option{-fshort-enums} flag on the command line
+is equivalent to specifying the @code{packed}
+attribute on all @code{enum} definitions.
+
+You may only specify the @code{packed} attribute on the definition
+of an @code{enum}, @code{struct}, @code{union}, or @code{class},
+not on a @code{typedef} that does not also define the enumerated type,
+structure, union, or class.
+
@cindex @code{patchable_function_entry} function attribute
@cindex extra NOP instructions at the function entry point
@item patchable_function_entry
framework with the attribute @code{patchable_function_entry (0)}
to prevent recursion.
+@cindex @code{persistent} variable attribute
+@item persistent
+Any variables with the @code{persistent} attribute will not be initialized by
+the C runtime startup code, but will be initialized by the program
+loader. This enables the value of the variable to persist
+between processor resets.
+
+This attribute is specific to ELF targets and relies on the linker
+script to place the sections with the @code{.persistent} prefix in the
+right location. Specifically, some type of non-volatile, writable
+memory is required.
+
@cindex @code{pure} function attribute
@cindex functions that have no side effects
@item pure
effects it does not make sense for such a function to return @code{void}.
Declaring such a function is diagnosed.
-@cindex @code{unsequenced} function type attribute
-@cindex functions that have no side effects
-@item unsequenced
-
-This attribute is a GNU counterpart of the C23 @code{[[unsequenced]]}
-attribute, used to specify function pointers to effectless, idempotent,
-stateless and independent functions according to the C23 definition.
-
-Unlike the standard C23 attribute it can be also specified in attributes
-which appertain to function declarations and applies to the their function
-type even in that case.
-
-Unsequenced functions without pointer or reference arguments are similar
-to functions with the @code{const} attribute, except that @code{const}
-attribute also requires finiteness. So, both functions with @code{const}
-and with @code{unsequenced} attributes can be optimized by common
-subexpression elimination, but only functions with @code{const}
-attribute can be optimized by dead code elimination if their result is
-unused or is used only by dead code. Unsequenced functions without pointer
-or reference arguments with @code{void} return type are diagnosed because
-they can't store any results and don't have other observable side-effects
-either.
-
-Unsequenced functions with pointer or reference arguments can inspect
-objects through the passed pointers or references or references to pointers
-or can store additional results through those pointers or references or
-references to pointers.
-
-The @code{unsequenced} attribute imposes greater restrictions than
-the similar @code{reproducible} attribute and fewer restrictions than
-the @code{const} attribute, so during optimization @code{const} has
-precedence over @code{unsequenced} which has precedence over
-@code{reproducible}.
-
@cindex @code{reproducible} function type attribute
@cindex functions that have no side effects
@item reproducible
additional results through those pointers or references or references to
pointers.
-@cindex @code{retain} function attribute
+@cindex @code{retain} attribute
@item retain
For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
-will save the function from linker garbage collection. To support
-this behavior, functions that have not been placed in specific sections
+protects the function or variable it applies to
+from linker garbage collection. To support this behavior,
+functions and variables that have not been placed in specific sections
(e.g. by the @code{section} attribute, or the @code{-ffunction-sections}
-option), will be placed in new, unique sections.
+or @code{-fdata-sections} options) are placed in new, unique sections.
This additional functionality requires Binutils version 2.36 or later.
@cindex @code{returns_nonnull} function attribute
@item returns_nonnull
-The @code{returns_nonnull} attribute specifies that the function
+The @code{returns_nonnull} function attribute specifies that the function
return value should be a non-null pointer. For instance, the declaration:
@smallexample
The @code{longjmp}-like counterpart of such function, if any, might need
to be marked with the @code{noreturn} attribute.
-@cindex @code{section} function attribute
+@cindex @code{scalar_storage_order} type attribute
+@item scalar_storage_order ("@var{endianness}")
+When attached to a @code{union} or a @code{struct}, this attribute sets
+the storage order, aka endianness, of the scalar fields of the type, as
+well as the array fields whose component is scalar. The supported
+endiannesses are @code{big-endian} and @code{little-endian}. The attribute
+has no effects on fields which are themselves a @code{union}, a @code{struct}
+or an array whose component is a @code{union} or a @code{struct}, and it is
+possible for these fields to have a different scalar storage order than the
+enclosing type.
+
+Note that neither pointer nor vector fields are considered scalar fields in
+this context, so the attribute has no effects on these fields.
+
+This attribute is supported only for targets that use a uniform default
+scalar storage order (fortunately, most of them), i.e.@: targets that store
+the scalars either all in big-endian or all in little-endian.
+
+Additional restrictions are enforced for types with the reverse scalar
+storage order with regard to the scalar storage order of the target:
+
+@itemize
+@item Taking the address of a scalar field of a @code{union} or a
+@code{struct} with reverse scalar storage order is not permitted and yields
+an error.
+@item Taking the address of an array field, whose component is scalar, of
+a @code{union} or a @code{struct} with reverse scalar storage order is
+permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
+is specified.
+@item Taking the address of a @code{union} or a @code{struct} with reverse
+scalar storage order is permitted.
+@end itemize
+
+These restrictions exist because the storage order attribute is lost when
+the address of a scalar or the address of an array with scalar component is
+taken, so storing indirectly through this address generally does not work.
+The second case is nevertheless allowed to be able to perform a block copy
+from or to the array.
+
+Moreover, the use of type punning or aliasing to toggle the storage order
+is not supported; that is to say, if a given scalar object can be accessed
+through distinct types that assign a different storage order to it, then the
+behavior is undefined.
+
+@cindex @code{section} attribute
@cindex functions in arbitrary sections
+@cindex variables in arbitrary sections
@item section ("@var{section-name}")
-Normally, the compiler places the code it generates in the @code{text} section.
+Normally, the compiler places the code it generates in the @code{text} section,
+and variables in @code{data} or @code{bss}.
Sometimes, however, you need additional sections, or you need certain
-particular functions to appear in special sections. The @code{section}
-attribute specifies that a function lives in a particular section.
+particular functions or variables to appear in special sections.
+The @code{section} attribute specifies that the function or variable
+it applies to lives in a particular section.
For example, the declaration:
@smallexample
@noindent
puts the function @code{foobar} in the @code{bar} section.
+Here's a more complicated example:
+@smallexample
+struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
+struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
+char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
+int init_data __attribute__ ((section ("INITDATA")));
+
+main()
+@{
+ /* @r{Initialize stack pointer} */
+ init_sp (stack + sizeof (stack));
+
+ /* @r{Initialize initialized data} */
+ memcpy (&init_data, &data, &edata - &data);
+
+ /* @r{Turn on the serial ports} */
+ init_duart (&a);
+ init_duart (&b);
+@}
+@end smallexample
+
+@noindent
+Use the @code{section} attribute with
+@emph{global} variables and not @emph{local} variables,
+as shown in the example.
+
+You may use the @code{section} attribute with initialized or
+uninitialized global variables but the linker requires
+each object be defined once, with the exception that uninitialized
+variables tentatively go in the @code{common} (or @code{bss}) section
+and can be multiply ``defined''. Using the @code{section} attribute
+changes what section the variable goes into and may cause the
+linker to issue an error if an uninitialized variable has multiple
+definitions. You can force a variable to be initialized with the
+@option{-fno-common} flag or the @code{nocommon} attribute.
+
Some file formats do not support arbitrary sections so the @code{section}
attribute is not available on all platforms.
If you need to map the entire contents of a module to a particular
@cindex @code{stack_protect} function attribute
@item stack_protect
-This attribute adds stack protection code to the function if
+This attribute adds stack protection code to the function it applies to if
flags @option{-fstack-protector}, @option{-fstack-protector-strong}
or @option{-fstack-protector-explicit} are set.
-@cindex @code{symver} function attribute
-@item symver ("@var{name2}@@@var{nodename}")
-On ELF targets this attribute creates a symbol version. The @var{name2} part
-of the parameter is the actual name of the symbol by which it will be
-externally referenced. The @code{nodename} portion should be the name of a
-node specified in the version script supplied to the linker when building a
-shared library. Versioned symbol must be defined and must be exported with
-default visibility.
+@cindex @code{strict_flex_array} variable attribute
+@item strict_flex_array (@var{level})
+The @code{strict_flex_array} attribute can be attached to the trailing
+array field of a structure. It controls when to treat the trailing array
+field of a structure as a flexible array member for the purposes of accessing
+the elements of such an array.
+@var{level} must be an integer between 0 to 3.
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_1"))) int
-foo_v1 (void)
-@{
-@}
-@end smallexample
+@var{level}=0 is the least strict level, all trailing arrays of structures
+are treated as flexible array members. @var{level}=3 is the strictest level,
+only when the trailing array is declared as a flexible array member per C99
+standard onwards (@samp{[]}), it is treated as a flexible array member.
-Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
-output.
+There are two more levels in between 0 and 3, which are provided to
+support older code that uses the GCC zero-length array extension
+(@samp{[0]}) or one-element array as flexible array members
+(@samp{[1]}). When @var{level} is 1, the trailing array is treated as
+a flexible array member when it is declared as either @samp{[]},
+@samp{[0]}, or @samp{[1]}. When @var{level} is 2, the trailing array
+is treated as a flexible array member when it is declared as either
+@samp{[]}, or @samp{[0]}.
-One can also define multiple version for a given symbol
-(starting from binutils 2.35).
+This attribute can be used with or without the
+@option{-fstrict-flex-arrays} command-line option. When both the
+attribute and the option are present at the same time, the level of
+the strictness for the specific trailing array field is determined by
+the attribute.
-@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
-int symver_foo_v1 (void)
-@{
-@}
-@end smallexample
+The @code{strict_flex_array} attribute interacts with the
+@option{-Wstrict-flex-arrays} option. @xref{Warning Options}, for more
+information.
-This example creates a symbol name @code{symver_foo_v1}
-which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
+@cindex @code{strub} type attribute
+@item strub
+This attribute defines stack-scrubbing properties of functions and
+variables, so that functions that access sensitive data can have their
+stack frames zeroed-out upon returning or propagating exceptions. This
+may be enabled explicitly, by selecting certain @code{strub} modes for
+specific functions, or implicitly, by means of @code{strub} variables.
-If you have an older release of binutils, then symbol alias needs to
-be used:
+Being a type attribute, it attaches to types, even when specified in
+function and variable declarations. When applied to function types, it
+takes an optional string argument. When applied to a
+pointer-to-function type, if the optional argument is given, it gets
+propagated to the function type.
@smallexample
-__attribute__ ((__symver__ ("foo@@VERS_2")))
-int foo_v1 (void)
-@{
- return 0;
-@}
+/* A strub variable. */
+int __attribute__ ((strub)) var;
+/* A strub variable that happens to be a pointer. */
+__attribute__ ((strub)) int *strub_ptr_to_int;
+/* A pointer type that may point to a strub variable. */
+typedef int __attribute__ ((strub)) *ptr_to_strub_int_type;
-__attribute__ ((__symver__ ("foo@@VERS_3")))
-__attribute__ ((alias ("foo_v1")))
-int symver_foo_v1 (void);
+/* A declaration of a strub function. */
+extern int __attribute__ ((strub)) foo (void);
+/* A pointer to that strub function. */
+int __attribute__ ((strub ("at-calls"))) (*ptr_to_strub_fn)(void) = foo;
@end smallexample
-Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
-addition to creating a symbol version (as if
-@code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
-to resolve @var{name2} by the linker.
-
-@cindex @code{tainted_args} function attribute
-@item tainted_args
-The @code{tainted_args} attribute is used to specify that a function is called
-in a way that requires sanitization of its arguments, such as a system
-call in an operating system kernel. Such a function can be considered part
-of the ``attack surface'' of the program. The attribute can be used both
-on function declarations, and on field declarations containing function
-pointers. In the latter case, any function used as an initializer of
-such a callback field will be treated as being called with tainted
-arguments.
-
-The analyzer will pay particular attention to such functions when
-@option{-fanalyzer} is supplied, potentially issuing warnings guarded by
-@option{-Wanalyzer-tainted-allocation-size},
-@option{-Wanalyzer-tainted-array-index},
-@option{-Wanalyzer-tainted-divisor},
-@option{-Wanalyzer-tainted-offset},
-and @option{-Wanalyzer-tainted-size}.
-
-@cindex @code{target} function attribute
-@item target (@var{string}, @dots{})
-Multiple target back ends implement the @code{target} attribute
-to specify that a function is to
-be compiled with different target options than specified on the
-command line. The original target command-line options are ignored.
-One or more strings can be provided as arguments.
-Each string consists of one or more comma-separated suffixes to
-the @code{-m} prefix jointly forming the name of a machine-dependent
-option. @xref{Submodel Options,,Machine-Dependent Options}.
-
-The @code{target} attribute can be used for instance to have a function
-compiled with a different ISA (instruction set architecture) than the
-default. @samp{#pragma GCC target} can be used to specify target-specific
-options for more than one function. @xref{Function Specific Option Pragmas},
-for details about the pragma.
+A function associated with @code{at-calls} @code{strub} mode
+(@code{strub("at-calls")}, or just @code{strub}) undergoes interface
+changes. Its callers are adjusted to match the changes, and to scrub
+(overwrite with zeros) the stack space used by the called function after
+it returns. The interface change makes the function type incompatible
+with an unadorned but otherwise equivalent type, so @emph{every}
+declaration and every type that may be used to call the function must be
+associated with this strub mode.
-For instance, on an x86, you could declare one function with the
-@code{target("sse4.1,arch=core2")} attribute and another with
-@code{target("sse4a,arch=amdfam10")}. This is equivalent to
-compiling the first function with @option{-msse4.1} and
-@option{-march=core2} options, and the second function with
-@option{-msse4a} and @option{-march=amdfam10} options. It is up to you
-to make sure that a function is only invoked on a machine that
-supports the particular ISA it is compiled for (for example by using
-@code{cpuid} on x86 to determine what feature bits and architecture
-family are used).
+A function associated with @code{internal} @code{strub} mode
+(@code{strub("internal")}) retains an unmodified, type-compatible
+interface, but it may be turned into a wrapper that calls the wrapped
+body using a custom interface. The wrapper then scrubs the stack space
+used by the wrapped body. Though the wrapped body has its stack space
+scrubbed, the wrapper does not, so arguments and return values may
+remain unscrubbed even when such a function is called by another
+function that enables @code{strub}. This is why, when compiling with
+@option{-fstrub=strict}, a @code{strub} context is not allowed to call
+@code{internal} @code{strub} functions.
@smallexample
-int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
-int sse3_func (void) __attribute__ ((__target__ ("sse3")));
+/* A declaration of an internal-strub function. */
+extern int __attribute__ ((strub ("internal"))) bar (void);
+
+int __attribute__ ((strub))
+baz (void)
+@{
+ /* Ok, foo was declared above as an at-calls strub function. */
+ foo ();
+ /* Not allowed in strict mode, otherwise allowed. */
+ bar ();
+@}
@end smallexample
-Providing multiple strings as arguments separated by commas to specify
-multiple options is equivalent to separating the option suffixes with
-a comma (@samp{,}) within a single string. Spaces are not permitted
-within the strings.
+An automatically-allocated variable associated with the @code{strub}
+attribute causes the (immediately) enclosing function to have
+@code{strub} enabled.
-The options supported are specific to each target; refer to @ref{x86
-Function Attributes}, @ref{PowerPC Function Attributes},
-@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes},
-and @ref{S/390 Function Attributes} for details.
+A statically-allocated variable associated with the @code{strub}
+attribute causes functions that @emph{read} it, through its @code{strub}
+data type, to have @code{strub} enabled. Reading data by dereferencing
+a pointer to a @code{strub} data type has the same effect. Note: The
+attribute does not carry over from a composite type to the types of its
+components, so the intended effect may not be obtained with non-scalar
+types.
-On targets supporting @code{target} function multiversioning (x86), when using
-C++, you can declare multiple functions with the same signatures but different
-@code{target} attribute values, and the correct version is chosen by the
-dynamic linker. In the example below, two function versions are produced
-with differing mangling. Additionally an ifunc resolver is created to
-select the correct version to populate the @code{func} symbol.
+When selecting a @code{strub}-enabled mode for a function that is not
+explicitly associated with one, because of @code{strub} variables or
+data pointers, the function must satisfy @code{internal} mode viability
+requirements (see below), even when @code{at-calls} mode is also viable
+and, being more efficient, ends up selected as an optimization.
@smallexample
-int func (void) __attribute__ ((target ("arch=core2"))) @{ return 1; @}
-int func (void) __attribute__ ((target ("sse3"))) @{ return 2; @}
+/* zapme is implicitly strub-enabled because of strub variables.
+ Optimization may change its strub mode, but not the requirements. */
+static int
+zapme (int i)
+@{
+ /* A local strub variable enables strub. */
+ int __attribute__ ((strub)) lvar;
+ /* Reading strub data through a pointer-to-strub enables strub. */
+ lvar = * (ptr_to_strub_int_type) &i;
+ /* Writing to a global strub variable does not enable strub. */
+ var = lvar;
+ /* Reading from a global strub variable enables strub. */
+ return var;
+@}
@end smallexample
-Declarations annotated with @code{target} cannot be used in combination with
-declarations annotated with @code{target_clones} in a single multiversioned
-function definition.
+A @code{strub} context is the body (as opposed to the interface) of a
+function that has @code{strub} enabled, be it explicitly, by
+@code{at-calls} or @code{internal} mode, or implicitly, due to
+@code{strub} variables or command-line options.
-@xref{Function Multiversioning} for more details.
+A function of a type associated with the @code{disabled} @code{strub}
+mode (@code{strub("disabled")} will not have its own stack space
+scrubbed. Such functions @emph{cannot} be called from within
+@code{strub} contexts.
-@cindex @code{target_version} function attribute
-@item target_version (@var{option})
-On targets with @code{target_version} function multiversioning (AArch64 and
-RISC-V) in C or C++, you can declare multiple functions with
-@code{target_version} or @code{target_clones} attributes to define a function
-version set.
+In order to enable a function to be called from within @code{strub}
+contexts without having its stack space scrubbed, associate it with the
+@code{callable} @code{strub} mode (@code{strub("callable")}).
-@xref{Function Multiversioning} for more details.
+When a function is not assigned a @code{strub} mode, explicitly or
+implicitly, the mode defaults to @code{callable}, except when compiling
+with @option{-fstrub=strict}, that causes @code{strub} mode to default
+to @code{disabled}.
-@cindex @code{target_clones} function attribute
-@item target_clones (@var{options})
-The @code{target_clones} attribute is used to specify that a function
-be cloned into multiple versions compiled with different target options
-than specified on the command line.
+@example
+extern int __attribute__ ((strub ("callable"))) bac (void);
+extern int __attribute__ ((strub ("disabled"))) bad (void);
+ /* Implicitly disabled with -fstrub=strict, otherwise callable. */
+extern int bah (void);
-For the x86 and PowerPC targets, the supported options and restrictions
-are the same as for the @code{target} attribute.
+int __attribute__ ((strub))
+bal (void)
+@{
+ /* Not allowed, bad is not strub-callable. */
+ bad ();
+ /* Ok, bac is strub-callable. */
+ bac ();
+ /* Not allowed with -fstrub=strict, otherwise allowed. */
+ bah ();
+@}
+@end example
-For instance, on an x86, you could compile a function with
-@code{target_clones("sse4.1,avx")}. GCC creates two function clones,
-one compiled with @option{-msse4.1} and another with @option{-mavx}.
+Function types marked @code{callable} and @code{disabled} are not
+mutually compatible types, but the underlying interfaces are compatible,
+so it is safe to convert pointers between them, and to use such pointers
+or alternate declarations to call them. Interfaces are also
+interchangeable between them and @code{internal} (but not
+@code{at-calls}!), but adding @code{internal} to a pointer type will not
+cause the pointed-to function to perform stack scrubbing.
-On a PowerPC, you can compile a function with
-@code{target_clones("cpu=power9,default")}. GCC will create two
-function clones, one compiled with @option{-mcpu=power9} and another
-with the default options. GCC must be configured to use GLIBC 2.23 or
-newer in order to use the @code{target_clones} attribute.
+@example
+void __attribute__ ((strub))
+bap (void)
+@{
+ /* Assign a callable function to pointer-to-disabled.
+ Flagged as not quite compatible with -Wpedantic. */
+ int __attribute__ ((strub ("disabled"))) (*d_p) (void) = bac;
+ /* Not allowed: calls disabled type in a strub context. */
+ d_p ();
-@code{target_clones} works similarly for targets that support the
-@code{target_version} attribute (AArch64 and RISC-V). The attribute takes
-multiple arguments, and generates a versioned clone for each. A function
-annotated with @code{target_clones} is equivalent to the same function
-duplicated for each valid version string in the argument, where each
-version is instead annotated with @code{target_version}. This means that a
-@code{target_clones} annotated function definition can be used in combination
-with @code{target_version} annotated functions definitions and other
-@code{target_clones} annotated function definitions.
+ /* Assign a disabled function to pointer-to-callable.
+ Flagged as not quite compatible with -Wpedantic. */
+ int __attribute__ ((strub ("callable"))) (*c_p) (void) = bad;
+ /* Ok, safe. */
+ c_p ();
-For these targets the supported options and restrictions are the same as for
-the @code{target_version} attribute.
+ /* Assign an internal function to pointer-to-callable.
+ Flagged as not quite compatible with -Wpedantic. */
+ c_p = bar;
+ /* Ok, safe. */
+ c_p ();
-@xref{Function Multiversioning} for more details.
+ /* Assign an at-calls function to pointer-to-callable.
+ Flaggged as incompatible. */
+ c_p = bal;
+ /* The call through an interface-incompatible type will not use the
+ modified interface expected by the at-calls function, so it is
+ likely to misbehave at runtime. */
+ c_p ();
+@}
+@end example
-@cindex @code{unavailable} function attribute
-@item unavailable
-@itemx unavailable (@var{msg})
-The @code{unavailable} attribute results in an error if the function
-is used anywhere in the source file. This is useful when identifying
-functions that have been removed from a particular variation of an
-interface. Other than emitting an error rather than a warning, the
-@code{unavailable} attribute behaves in the same manner as
-@code{deprecated}.
+@code{Strub} contexts are never inlined into non-@code{strub} contexts.
+When an @code{internal}-strub function is split up, the wrapper can
+often be inlined, but the wrapped body @emph{never} is. A function
+marked as @code{always_inline}, even if explicitly assigned
+@code{internal} strub mode, will not undergo wrapping, so its body gets
+inlined as required.
-The @code{unavailable} attribute can also be used for variables and
-types (@pxref{Variable Attributes}, @pxref{Type Attributes}.)
+@example
+inline int __attribute__ ((strub ("at-calls")))
+inl_atc (void)
+@{
+ /* This body may get inlined into strub contexts. */
+@}
-@cindex @code{unused} function attribute
-@item unused
-This attribute, attached to a function, means that the function is meant
-to be possibly unused. GCC does not produce a warning for this
-function.
+inline int __attribute__ ((strub ("internal")))
+inl_int (void)
+@{
+ /* This body NEVER gets inlined, though its wrapper may. */
+@}
-@cindex @code{used} function attribute
-@item used
-This attribute, attached to a function, means that code must be emitted
-for the function even if it appears that the function is not referenced.
-This is useful, for example, when the function is referenced only in
-inline assembly.
+inline int __attribute__ ((strub ("internal"), always_inline))
+inl_int_ali (void)
+@{
+ /* No internal wrapper, so this body ALWAYS gets inlined,
+ but it cannot be called from non-strub contexts. */
+@}
-When applied to a member function of a C++ class template, the
-attribute also means that the function is instantiated if the
-class itself is instantiated.
+void __attribute__ ((strub ("disabled")))
+bat (void)
+@{
+ /* Not allowed, cannot inline into a non-strub context. */
+ inl_int_ali ();
+@}
+@end example
-@cindex @code{visibility} function attribute
-@item visibility ("@var{visibility_type}")
-This attribute affects the linkage of the declaration to which it is attached.
-It can be applied to variables (@pxref{Common Variable Attributes}) and types
-(@pxref{Common Type Attributes}) as well as functions.
+@cindex strub eligibility and viability
+Some @option{-fstrub=*} command-line options enable @code{strub} modes
+implicitly where viable. A @code{strub} mode is only viable for a
+function if the function is eligible for that mode, and if other
+conditions, detailed below, are satisfied. If it's not eligible for a
+mode, attempts to explicitly associate it with that mode are rejected
+with an error message. If it is eligible, that mode may be assigned
+explicitly through this attribute, but implicit assignment through
+command-line options may involve additional viability requirements.
-There are four supported @var{visibility_type} values: default,
-hidden, protected or internal visibility.
+A function is ineligible for @code{at-calls} @code{strub} mode if a
+different @code{strub} mode is explicitly requested, if attribute
+@code{noipa} is present, or if it calls @code{__builtin_apply_args}.
+@code{At-calls} @code{strub} mode, if not requested through the function
+type, is only viable for an eligible function if the function is not
+visible to other translation units, if it doesn't have its address
+taken, and if it is never called with a function type overrider.
@smallexample
-void __attribute__ ((visibility ("protected")))
-f () @{ /* @r{Do something.} */; @}
-int i __attribute__ ((visibility ("hidden")));
-@end smallexample
-
-The possible values of @var{visibility_type} correspond to the
-visibility settings in the ELF gABI.
-
-@table @code
-@c keep this list of visibilities in alphabetical order.
-
-@item default
-Default visibility is the normal case for the object file format.
-This value is available for the visibility attribute to override other
-options that may change the assumed visibility of entities.
-
-On ELF, default visibility means that the declaration is visible to other
-modules and, in shared libraries, means that the declared entity may be
-overridden.
-
-On Darwin, default visibility means that the declaration is visible to
-other modules.
-
-Default visibility corresponds to ``external linkage'' in the language.
+/* bar is eligible for at-calls strub mode,
+ but not viable for that mode because it is visible to other units.
+ It is eligible and viable for internal strub mode. */
+void bav () @{@}
-@item hidden
-Hidden visibility indicates that the entity declared has a new
-form of linkage, which we call ``hidden linkage''. Two
-declarations of an object with hidden linkage refer to the same object
-if they are in the same shared object.
+/* setp is eligible for at-calls strub mode,
+ but not viable for that mode because its address is taken.
+ It is eligible and viable for internal strub mode. */
+void setp (void) @{ static void (*p)(void); = setp; @}
+@end smallexample
-@item internal
-Internal visibility is like hidden visibility, but with additional
-processor specific semantics. Unless otherwise specified by the
-psABI, GCC defines internal visibility to mean that a function is
-@emph{never} called from another module. Compare this with hidden
-functions which, while they cannot be referenced directly by other
-modules, can be referenced indirectly via function pointers. By
-indicating that a function cannot be called from outside the module,
-GCC may for instance omit the load of a PIC register since it is known
-that the calling function loaded the correct value.
+A function is ineligible for @code{internal} @code{strub} mode if a
+different @code{strub} mode is explicitly requested, or if attribute
+@code{noipa} is present. For an @code{always_inline} function, meeting
+these requirements is enough to make it eligible. Any function that has
+attribute @code{noclone}, that uses such extensions as non-local labels,
+computed gotos, alternate variable argument passing interfaces,
+@code{__builtin_next_arg}, or @code{__builtin_return_address}, or that
+takes too many (about 64Ki) arguments is ineligible, unless it is
+@code{always_inline}. For @code{internal} @code{strub} mode, all
+eligible functions are viable.
-@item protected
-Protected visibility is like default visibility except that it
-indicates that references within the defining module bind to the
-definition in that module. That is, the declared entity cannot be
-overridden by another module.
+@smallexample
+/* flop is not eligible, thus not viable, for at-calls strub mode.
+ Likewise for internal strub mode. */
+__attribute__ ((noipa)) void flop (void) @{@}
-@end table
+/* flip is eligible and viable for at-calls strub mode.
+ It would be ineligible for internal strub mode, because of noclone,
+ if it weren't for always_inline. With always_inline, noclone is not
+ an obstacle, so it is also eligible and viable for internal strub mode. */
+inline __attribute__ ((noclone, always_inline)) void flip (void) @{@}
+@end smallexample
-All visibilities are supported on many, but not all, ELF targets
-(supported when the assembler supports the @samp{.visibility}
-pseudo-op). Default visibility is supported everywhere. Hidden
-visibility is supported on Darwin targets.
+@cindex @code{symver} function attribute
+@item symver ("@var{name2}@@@var{nodename}")
+On ELF targets this function attribute creates a symbol version.
+The @var{name2} part
+of the parameter is the actual name of the symbol by which it will be
+externally referenced. The @code{nodename} portion should be the name of a
+node specified in the version script supplied to the linker when building a
+shared library. The versioned symbol must be defined and must be exported with
+default visibility.
-The visibility attribute should be applied only to declarations that
-would otherwise have external linkage. The attribute should be applied
-consistently, so that the same entity should not be declared with
-different settings of the attribute.
+This example produces a @code{.symver foo_v1, foo@@VERS_1}
+directive in the assembler output.:
-In C++, the visibility attribute applies to types as well as functions
-and objects, because in C++ types have linkage. A class must not have
-greater visibility than its non-static data member types and bases,
-and class members default to the visibility of their class. Also, a
-declaration without explicit visibility is limited to the visibility
-of its type.
+@smallexample
+__attribute__ ((__symver__ ("foo@@VERS_1"))) int
+foo_v1 (void)
+@{
+@}
+@end smallexample
-In C++, you can mark member functions and static member variables of a
-class with the visibility attribute. This is useful if you know a
-particular method or static member variable should only be used from
-one shared object; then you can mark it hidden while the rest of the
-class has default visibility. Care must be taken to avoid breaking
-the One Definition Rule; for example, it is usually not useful to mark
-an inline method as hidden without marking the whole class as hidden.
+Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler
+output.
-A C++ namespace declaration can also have the visibility attribute.
+One can also define multiple version for a given symbol
+(starting from binutils 2.35).
@smallexample
-namespace nspace1 __attribute__ ((visibility ("protected")))
-@{ /* @r{Do something.} */; @}
+__attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3")))
+int symver_foo_v1 (void)
+@{
+@}
@end smallexample
-This attribute applies only to the particular namespace body, not to
-other definitions of the same namespace; it is equivalent to using
-@samp{#pragma GCC visibility} before and after the namespace
-definition (@pxref{Visibility Pragmas}).
-
-In C++, if a template argument has limited visibility, this
-restriction is implicitly propagated to the template instantiation.
-Otherwise, template instantiations and specializations default to the
-visibility of their template.
-
-If both the template and enclosing class have explicit visibility, the
-visibility from the template is used.
+This example creates a symbol name @code{symver_foo_v1}
+which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}.
-@cindex @code{warn_unused_result} function attribute
-@item warn_unused_result
-The @code{warn_unused_result} attribute causes a warning to be emitted
-if a caller of the function with this attribute does not use its
-return value. This is useful for functions where not checking
-the result is either a security problem or always a bug, such as
-@code{realloc}.
+If you have an older release of binutils, then symbol alias needs to
+be used:
@smallexample
-int fn () __attribute__ ((warn_unused_result));
-int foo ()
+__attribute__ ((__symver__ ("foo@@VERS_2")))
+int foo_v1 (void)
@{
- if (fn () < 0) return -1;
- fn ();
return 0;
@}
+
+__attribute__ ((__symver__ ("foo@@VERS_3")))
+__attribute__ ((alias ("foo_v1")))
+int symver_foo_v1 (void);
@end smallexample
-@noindent
-results in warning on line 5.
+Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in
+addition to creating a symbol version (as if
+@code{"@var{name2}@@@var{nodename}"} was used) the version will be also used
+to resolve @var{name2} by the linker.
-@cindex @code{weak} function attribute
-@item weak
-The @code{weak} attribute causes a declaration of an external symbol
-to be emitted as a weak symbol rather than a global. This is primarily
-useful in defining library functions that can be overridden in user code,
-though it can also be used with non-function declarations. The overriding
-symbol must have the same type as the weak symbol. In addition, if it
-designates a variable it must also have the same size and alignment as
-the weak symbol. Weak symbols are supported for ELF targets, and also
-for a.out targets when using the GNU assembler and linker.
+@cindex @code{tainted_args} function attribute
+@item tainted_args
+The @code{tainted_args} attribute is used to specify that a function is called
+in a way that requires sanitization of its arguments, such as a system
+call in an operating system kernel. Such a function can be considered part
+of the ``attack surface'' of the program. The attribute can be used both
+on function declarations, and on field declarations containing function
+pointers. In the latter case, any function used as an initializer of
+such a callback field will be treated as being called with tainted
+arguments.
-@cindex @code{weakref} function attribute
-@item weakref
-@itemx weakref ("@var{target}")
-The @code{weakref} attribute marks a declaration as a weak reference.
-Without arguments, it should be accompanied by an @code{alias} attribute
-naming the target symbol. Alternatively, @var{target} may be given as
-an argument to @code{weakref} itself, naming the target definition of
-the alias. The @var{target} must have the same type as the declaration.
-In addition, if it designates a variable it must also have the same size
-and alignment as the declaration. In either form of the declaration
-@code{weakref} implicitly marks the declared symbol as @code{weak}. Without
-a @var{target} given as an argument to @code{weakref} or to @code{alias},
-@code{weakref} is equivalent to @code{weak} (in that case the declaration
-may be @code{extern}).
+The analyzer will pay particular attention to such functions when
+@option{-fanalyzer} is supplied, potentially issuing warnings guarded by
+@option{-Wanalyzer-tainted-allocation-size},
+@option{-Wanalyzer-tainted-array-index},
+@option{-Wanalyzer-tainted-divisor},
+@option{-Wanalyzer-tainted-offset},
+and @option{-Wanalyzer-tainted-size}.
-@smallexample
-/* Given the declaration: */
-extern int y (void);
+@cindex @code{target} function attribute
+@item target (@var{string}, @dots{})
+Multiple target back ends implement the @code{target} attribute
+to specify that a function is to
+be compiled with different target options than specified on the
+command line. The original target command-line options are ignored.
+One or more strings can be provided as arguments.
+Each string consists of one or more comma-separated suffixes to
+the @code{-m} prefix jointly forming the name of a machine-dependent
+option. @xref{Submodel Options,,Machine-Dependent Options}.
-/* the following... */
-static int x (void) __attribute__ ((weakref ("y")));
+The @code{target} attribute can be used for instance to have a function
+compiled with a different ISA (instruction set architecture) than the
+default. @samp{#pragma GCC target} can be used to specify target-specific
+options for more than one function. @xref{Function Specific Option Pragmas},
+for details about the pragma.
-/* is equivalent to... */
-static int x (void) __attribute__ ((weakref, alias ("y")));
+For instance, on an x86, you could declare one function with the
+@code{target("sse4.1,arch=core2")} attribute and another with
+@code{target("sse4a,arch=amdfam10")}. This is equivalent to
+compiling the first function with @option{-msse4.1} and
+@option{-march=core2} options, and the second function with
+@option{-msse4a} and @option{-march=amdfam10} options. It is up to you
+to make sure that a function is only invoked on a machine that
+supports the particular ISA it is compiled for (for example by using
+@code{cpuid} on x86 to determine what feature bits and architecture
+family are used).
-/* or, alternatively, to... */
-static int x (void) __attribute__ ((weakref));
-static int x (void) __attribute__ ((alias ("y")));
+@smallexample
+int core2_func (void) __attribute__ ((__target__ ("arch=core2")));
+int sse3_func (void) __attribute__ ((__target__ ("sse3")));
@end smallexample
-A weak reference is an alias that does not by itself require a
-definition to be given for the target symbol. If the target symbol is
-only referenced through weak references, then it becomes a @code{weak}
-undefined symbol. If it is directly referenced, however, then such
-strong references prevail, and a definition is required for the
-symbol, not necessarily in the same translation unit.
-
-The effect is equivalent to moving all references to the alias to a
-separate translation unit, renaming the alias to the aliased symbol,
-declaring it as weak, compiling the two separate translation units and
-performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
+Providing multiple strings as arguments separated by commas to specify
+multiple options is equivalent to separating the option suffixes with
+a comma (@samp{,}) within a single string. Spaces are not permitted
+within the strings.
-A declaration to which @code{weakref} is attached and that is associated
-with a named @code{target} must be @code{static}.
+The options supported are specific to each target; refer to @ref{x86
+Attributes}, @ref{PowerPC Attributes},
+@ref{ARM Attributes}, @ref{AArch64 Attributes},
+and @ref{S/390 Attributes} for details.
-@cindex @code{zero_call_used_regs} function attribute
-@item zero_call_used_regs ("@var{choice}")
+On targets supporting @code{target} function multiversioning (x86), when using
+C++, you can declare multiple functions with the same signatures but different
+@code{target} attribute values, and the correct version is chosen by the
+dynamic linker. In the example below, two function versions are produced
+with differing mangling. Additionally an ifunc resolver is created to
+select the correct version to populate the @code{func} symbol.
-The @code{zero_call_used_regs} attribute causes the compiler to zero
-a subset of all call-used registers@footnote{A ``call-used'' register
-is a register whose contents can be changed by a function call;
-therefore, a caller cannot assume that the register has the same contents
-on return from the function as it had before calling the function. Such
-registers are also called ``call-clobbered'', ``caller-saved'', or
-``volatile''.} at function return.
-This is used to increase program security by either mitigating
-Return-Oriented Programming (ROP) attacks or preventing information leakage
-through registers.
+@smallexample
+int func (void) __attribute__ ((target ("arch=core2"))) @{ return 1; @}
+int func (void) __attribute__ ((target ("sse3"))) @{ return 2; @}
+@end smallexample
-In order to satisfy users with different security needs and control the
-run-time overhead at the same time, the @var{choice} parameter provides a
-flexible way to choose the subset of the call-used registers to be zeroed.
-The four basic values of @var{choice} are:
+Declarations annotated with @code{target} cannot be used in combination with
+declarations annotated with @code{target_clones} in a single multiversioned
+function definition.
-@itemize @bullet
-@item
-@samp{skip} doesn't zero any call-used registers.
+@xref{Function Multiversioning} for more details.
-@item
-@samp{used} only zeros call-used registers that are used in the function.
-A ``used'' register is one whose content has been set or referenced in
-the function.
+@cindex @code{target_version} function attribute
+@item target_version (@var{option})
+On targets with @code{target_version} function multiversioning (AArch64 and
+RISC-V) in C or C++, you can declare multiple functions with
+@code{target_version} or @code{target_clones} attributes to define a function
+version set.
-@item
-@samp{all} zeros all call-used registers.
+@xref{Function Multiversioning} for more details.
-@item
-@samp{leafy} behaves like @samp{used} in a leaf function, and like
-@samp{all} in a nonleaf function. This makes for leaner zeroing in leaf
-functions, where the set of used registers is known, and that may be
-enough for some purposes of register zeroing.
-@end itemize
+@cindex @code{target_clones} function attribute
+@item target_clones (@var{options})
+The @code{target_clones} attribute is used to specify that a function
+be cloned into multiple versions compiled with different target options
+than specified on the command line.
-In addition to these three basic choices, it is possible to modify
-@samp{used}, @samp{all}, and @samp{leafy} as follows:
+For the x86 and PowerPC targets, the supported options and restrictions
+are the same as for the @code{target} attribute.
-@itemize @bullet
-@item
-Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
+For instance, on an x86, you could compile a function with
+@code{target_clones("sse4.1,avx")}. GCC creates two function clones,
+one compiled with @option{-msse4.1} and another with @option{-mavx}.
-@item
-Adding @samp{-arg} restricts the zeroing to registers that can sometimes
-be used to pass function arguments. This includes all argument registers
-defined by the platform's calling conversion, regardless of whether the
-function uses those registers for function arguments or not.
-@end itemize
+On a PowerPC, you can compile a function with
+@code{target_clones("cpu=power9,default")}. GCC will create two
+function clones, one compiled with @option{-mcpu=power9} and another
+with the default options. GCC must be configured to use GLIBC 2.23 or
+newer in order to use the @code{target_clones} attribute.
-The modifiers can be used individually or together. If they are used
-together, they must appear in the order above.
+@code{target_clones} works similarly for targets that support the
+@code{target_version} attribute (AArch64 and RISC-V). The attribute takes
+multiple arguments, and generates a versioned clone for each. A function
+annotated with @code{target_clones} is equivalent to the same function
+duplicated for each valid version string in the argument, where each
+version is instead annotated with @code{target_version}. This means that a
+@code{target_clones} annotated function definition can be used in combination
+with @code{target_version} annotated functions definitions and other
+@code{target_clones} annotated function definitions.
-The full list of @var{choice}s is therefore:
+For these targets the supported options and restrictions are the same as for
+the @code{target_version} attribute.
-@table @code
-@item skip
-doesn't zero any call-used register.
+@xref{Function Multiversioning} for more details.
-@item used
-only zeros call-used registers that are used in the function.
+@cindex @code{tls_model} variable attribute
+@item tls_model ("@var{tls_model}")
+The @code{tls_model} variable attribute sets thread-local storage model
+(@pxref{Thread-Local}) of a particular @code{__thread} variable,
+overriding @option{-ftls-model=} command-line switch on a per-variable
+basis.
+The @var{tls_model} argument should be one of @code{global-dynamic},
+@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
-@item used-gpr
-only zeros call-used general purpose registers that are used in the function.
+Not all targets support this attribute.
-@item used-arg
-only zeros call-used registers that are used in the function and pass arguments.
+@cindex @code{transparent_union} type attribute
+@item transparent_union
-@item used-gpr-arg
-only zeros call-used general purpose registers that are used in the function
-and pass arguments.
+This attribute, attached to a @code{union} type definition, indicates
+that any function parameter having that union type causes calls to that
+function to be treated in a special way.
-@item all
-zeros all call-used registers.
+First, the argument corresponding to a transparent union type can be of
+any type in the union; no cast is required. Also, if the union contains
+a pointer type, the corresponding argument can be a null pointer
+constant or a void pointer expression; and if the union contains a void
+pointer type, the corresponding argument can be any pointer expression.
+If the union member type is a pointer, qualifiers like @code{const} on
+the referenced type must be respected, just as with normal pointer
+conversions.
-@item all-gpr
-zeros all call-used general purpose registers.
+Second, the argument is passed to the function using the calling
+conventions of the first member of the transparent union, not the calling
+conventions of the union itself. All members of the union must have the
+same machine representation; this is necessary for this argument passing
+to work properly.
-@item all-arg
-zeros all call-used registers that pass arguments.
+Transparent unions are designed for library functions that have multiple
+interfaces for compatibility reasons. For example, suppose the
+@code{wait} function must accept either a value of type @code{int *} to
+comply with POSIX, or a value of type @code{union wait *} to comply with
+the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
+@code{wait} would accept both kinds of arguments, but it would also
+accept any other pointer type and this would make argument type checking
+less useful. Instead, @code{<sys/wait.h>} might define the interface
+as follows:
-@item all-gpr-arg
-zeros all call-used general purpose registers that pass
-arguments.
+@smallexample
+typedef union __attribute__ ((__transparent_union__))
+ @{
+ int *__ip;
+ union wait *__up;
+ @} wait_status_ptr_t;
-@item leafy
-Same as @samp{used} in a leaf function, and same as @samp{all} in a
-nonleaf function.
+pid_t wait (wait_status_ptr_t);
+@end smallexample
-@item leafy-gpr
-Same as @samp{used-gpr} in a leaf function, and same as @samp{all-gpr}
-in a nonleaf function.
+@noindent
+This interface allows either @code{int *} or @code{union wait *}
+arguments to be passed, using the @code{int *} calling convention.
+The program can call @code{wait} with arguments of either type:
-@item leafy-arg
-Same as @samp{used-arg} in a leaf function, and same as @samp{all-arg}
-in a nonleaf function.
-
-@item leafy-gpr-arg
-Same as @samp{used-gpr-arg} in a leaf function, and same as
-@samp{all-gpr-arg} in a nonleaf function.
-
-@end table
-
-Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
-@samp{all-gpr-arg}, @samp{leafy-arg}, and @samp{leafy-gpr-arg} are
-mainly used for ROP mitigation.
+@smallexample
+int w1 () @{ int w; return wait (&w); @}
+int w2 () @{ union wait w; return wait (&w); @}
+@end smallexample
-The default for the attribute is controlled by @option{-fzero-call-used-regs}.
-@end table
+@noindent
+With this interface, @code{wait}'s implementation might look like this:
-@c This is the end of the target-independent attribute table
+@smallexample
+pid_t wait (wait_status_ptr_t p)
+@{
+ return waitpid (-1, p.__ip, 0);
+@}
+@end smallexample
-@node AArch64 Function Attributes
-@subsubsection AArch64 Function Attributes
+@cindex @code{unavailable} attribute
+@item unavailable
+@itemx unavailable (@var{msg})
+The @code{unavailable} attribute can apply to functions, variables, types,
+or enumerators.
+It results in an error if the entity it applies to
+is used anywhere in the source file. This is useful when identifying
+entities that have been removed from a particular
+variation of an
+interface. Other than emitting an error rather than a warning, the
+@code{unavailable} attribute behaves in the same manner as
+@code{deprecated}.
-The following target-specific function attributes are available for the
-AArch64 target. For the most part, these options mirror the behavior of
-similar command-line options (@pxref{AArch64 Options}), but on a
-per-function basis.
+@cindex @code{uninitialized} variable attribute
+@item uninitialized
+This attribute, attached to a variable with automatic storage, means that
+the variable should not be automatically initialized by the compiler when
+the option @code{-ftrivial-auto-var-init} presents.
-@table @code
-@cindex @code{general-regs-only} function attribute, AArch64
-@item general-regs-only
-Indicates that no floating-point or Advanced SIMD registers should be
-used when generating code for this function. If the function explicitly
-uses floating-point code, then the compiler gives an error. This is
-the same behavior as that of the command-line option
-@option{-mgeneral-regs-only}.
+With the option @code{-ftrivial-auto-var-init}, all the automatic variables
+that do not have explicit initializers are initialized by the compiler.
+These additional compiler initializations might incur run-time overhead,
+sometimes dramatically. This attribute can be used to mark some variables
+to be excluded from such automatic initialization in order to reduce runtime
+overhead.
-@cindex @code{fix-cortex-a53-835769} function attribute, AArch64
-@item fix-cortex-a53-835769
-Indicates that the workaround for the Cortex-A53 erratum 835769 should be
-applied to this function. To explicitly disable the workaround for this
-function specify the negated form: @code{no-fix-cortex-a53-835769}.
-This corresponds to the behavior of the command-line options
-@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
+This attribute has no effect when the option @code{-ftrivial-auto-var-init}
+is not present.
-@cindex @code{cmodel=} function attribute, AArch64
-@item cmodel=
-Indicates that code should be generated for a particular code model for
-this function. The behavior and permissible arguments are the same as
-for the command-line option @option{-mcmodel=}.
+@cindex @code{unsequenced} function type attribute
+@cindex functions that have no side effects
+@item unsequenced
-@cindex @code{strict-align} function attribute, AArch64
-@item strict-align
-@itemx no-strict-align
-@code{strict-align} indicates that the compiler should not assume that unaligned
-memory references are handled by the system. To allow the compiler to assume
-that aligned memory references are handled by the system, the inverse attribute
-@code{no-strict-align} can be specified. The behavior is same as for the
-command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
+This attribute is a GNU counterpart of the C23 @code{[[unsequenced]]}
+attribute, used to specify function pointers to effectless, idempotent,
+stateless and independent functions according to the C23 definition.
-@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
-@item omit-leaf-frame-pointer
-Indicates that the frame pointer should be omitted for a leaf function call.
-To keep the frame pointer, the inverse attribute
-@code{no-omit-leaf-frame-pointer} can be specified. These attributes have
-the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
-and @option{-mno-omit-leaf-frame-pointer}.
+Unlike the standard C23 attribute it can be also specified in attributes
+which appertain to function declarations and applies to the their function
+type even in that case.
-@cindex @code{tls-dialect=} function attribute, AArch64
-@item tls-dialect=
-Specifies the TLS dialect to use for this function. The behavior and
-permissible arguments are the same as for the command-line option
-@option{-mtls-dialect=}.
+Unsequenced functions without pointer or reference arguments are similar
+to functions with the @code{const} attribute, except that @code{const}
+attribute also requires finiteness. So, both functions with @code{const}
+and with @code{unsequenced} attributes can be optimized by common
+subexpression elimination, but only functions with @code{const}
+attribute can be optimized by dead code elimination if their result is
+unused or is used only by dead code. Unsequenced functions without pointer
+or reference arguments with @code{void} return type are diagnosed because
+they can't store any results and don't have other observable side-effects
+either.
-@cindex @code{arch=} function attribute, AArch64
-@item arch=
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option.
+Unsequenced functions with pointer or reference arguments can inspect
+objects through the passed pointers or references or references to pointers
+or can store additional results through those pointers or references or
+references to pointers.
-@cindex @code{tune=} function attribute, AArch64
-@item tune=
-Specifies the core for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mtune=}
-command-line option.
+The @code{unsequenced} attribute imposes greater restrictions than
+the similar @code{reproducible} attribute and fewer restrictions than
+the @code{const} attribute, so during optimization @code{const} has
+precedence over @code{unsequenced} which has precedence over
+@code{reproducible}.
-@cindex @code{cpu=} function attribute, AArch64
-@item cpu=
-Specifies the core for which to tune the performance of this function and also
-whose architectural features to use. The behavior and valid arguments are the
-same as for the @option{-mcpu=} command-line option.
+@cindex @code{unused} attribute
+@item unused
+This attribute can be attached to a function, variable, structure field,
+type declaration, or label.
-@cindex @code{sign-return-address} function attribute, AArch64
-@item sign-return-address
-Select the function scope on which return address signing will be applied. The
-behavior and permissible arguments are the same as for the command-line option
-@option{-msign-return-address=}. The default value is @code{none}. This
-attribute is deprecated. The @code{branch-protection} attribute should
-be used instead.
+When applied to a function, variable, structure field, or label
+it means that the
+entity it applies to is meant to be possibly unused. It suppresses GCC's
+normal warnings about unused entities.
-@cindex @code{branch-protection} function attribute, AArch64
-@item branch-protection
-Select the function scope on which branch protection will be applied. The
-behavior and permissible arguments are the same as for the command-line option
-@option{-mbranch-protection=}. The default value is @code{none}.
+When attached to a type (including a @code{union} or a @code{struct}),
+this attribute means that variables of that type are meant to appear
+possibly unused. GCC does not produce a warning for any variables of
+that type, even if the variable appears to do nothing. This is often
+the case with lock or thread classes, which are usually defined and then
+not referenced, but contain constructors and destructors that have
+nontrivial bookkeeping functions.
-@cindex @code{outline-atomics} function attribute, AArch64
-@item outline-atomics
-@itemx no-outline-atomics
-Enable or disable calls to out-of-line helpers to implement atomic operations.
-This corresponds to the behavior of the command-line options
-@option{-moutline-atomics} and @option{-mno-outline-atomics}.
+The @code{unused} label attribute
+is intended for program-generated code that may contain
+unused labels, but which is compiled with @option{-Wall}. It is
+not normally appropriate to use it in human-written code, though it
+could be useful in cases where the code that jumps to the label is
+contained within an @code{#ifdef} conditional.
-@cindex @code{max-vectorization} function attribute, AArch64
-@item max-vectorization
-@itemx no-max-vectorization
-@code{max-vectorization} tells GCC's vectorizer to treat all vector
-loops as being more profitable than the original scalar loops when
-optimizing the current function. @code{no-max-vectorization} disables
-this behavior.
-This corresponds to the behavior of the command-line options
-@option{-mmax-vectorization} and @option{-mno-max-vectorization}.
+@cindex @code{used} attribute
+@item used
+The @code{used} attribute applies to functions and variables.
-@cindex @code{indirect_return} function attribute, AArch64
-@item indirect_return
-The @code{indirect_return} attribute can be applied to a function type
-to indicate that the function may return via an indirect branch instead
-of via a normal return instruction. For example, this can be true of
-functions that implement manual context switching between user space
-threads, such as the POSIX @code{swapcontext} function. This attribute
-adds a @code{BTI J} instruction when BTI is enabled e.g. via
-@option{-mbranch-protection}.
+When attached to a function, this attribute means that code must be emitted
+for the function even if it appears that the function is not referenced.
+This is useful, for example, when the function is referenced only in
+inline assembly.
-@cindex @code{preserve_none} function attribute, AArch64
-@item preserve_none
-Use this attribute to change the procedure call standard of the specified
-function to the preserve-none variant.
+When applied to a member function of a C++ class template, the
+attribute also means that the function is instantiated if the
+class itself is instantiated.
-The preserve-none ABI variant modifies the AAPCS such that it has no
-callee-saved registers (including SIMD and floating-point registers). That is,
-with the exception of the stack register, link register (r30), and frame pointer
-(r29), all registers are changed to caller saved, and can be used as scratch
-registers by the callee.
+This attribute, attached to a variable with static storage, means that
+the variable must be emitted even if it appears that the variable is not
+referenced.
-Additionally, registers r20--r28, r0--r7, r10--r14, r9 and r15 are used for
-argument passing, in that order. For Microsoft Windows targets
-r15 is not used for argument passing.
+When applied to a static data member of a C++ class template, the
+attribute also means that the member is instantiated if the
+class itself is instantiated.
-The return value registers remain r0 and r1 in both cases.
+@cindex @code{vector_size} attribute
+@item vector_size (@var{bytes})
+The @code{vector_size} attribute can be attached to type, variable,
+and function declarations.
+When attached to a variable declaration, it applies to the type of the
+variable; when attached to a function declaration, it applies to the
+return type.
-All other details are the same as for the AAPCS ABI.
+This attribute specifies the vector size for the type, measured in bytes.
+The type to which it applies is known as the @dfn{base type}. The @var{bytes}
+argument must be a positive power-of-two multiple of the base type size. For
+example, the following declarations:
-This ABI has not been stabilized, and may be subject to change in future
-versions.
-@end table
+@smallexample
+typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
+typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
+typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
+@end smallexample
-The above target attributes can be specified as follows:
+@noindent
+define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
+sized units. With @code{int} having a size of 4 bytes, the type defines
+a vector of eight units, four bytes each. The mode of variables of type
+@code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
+to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
+an array of three such vectors.
+Here is an example involving a function declaration:
@smallexample
-__attribute__((target("@var{attr-string}")))
-int
-f (int a)
-@{
- return a + 5;
-@}
+__attribute__ ((vector_size (16))) float get_flt_vec16 (void);
@end smallexample
-where @code{@var{attr-string}} is one of the attribute strings specified above.
-
-Additionally, the architectural extension string may be specified on its
-own. This can be used to turn on and off particular architectural extensions
-without having to specify a particular architecture version or core. Example:
+@noindent
+This code declares @code{get_flt_vec16} to be a function returning
+a 16-byte vector with the base type @code{float}.
+This example:
@smallexample
-__attribute__((target("+crc+nocrypto")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
+int foo __attribute__ ((vector_size (16)));
@end smallexample
-In this example @code{target("+crc+nocrypto")} enables the @code{crc}
-extension and disables the @code{crypto} extension for the function @code{foo}
-without modifying an existing @option{-march=} or @option{-mcpu} option.
+@noindent
+causes the compiler to set the mode for @code{foo} to be 16 bytes,
+divided into @code{int} sized units. Assuming a 32-bit @code{int},
+@code{foo}'s type is a vector of four units of four bytes each, and
+the corresponding mode of @code{foo} is @code{V4SI}.
+
+This attribute is only applicable to integral and floating scalar base types,
+although arrays, pointers, and function return values are allowed in
+conjunction with this construct.
+
+Aggregates with this attribute are invalid, even if they are of the same
+size as a corresponding scalar. For example, the declaration:
-Multiple target function attributes can be specified by separating them with
-a comma. For example:
@smallexample
-__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
+struct S @{ int a; @};
+struct S __attribute__ ((vector_size (16))) foo;
@end smallexample
-is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
-and @code{crypto} extensions and tunes it for @code{cortex-a53}.
-
-@subsubheading Inlining rules
-Specifying target attributes on individual functions or performing link-time
-optimization across translation units compiled with different target options
-can affect function inlining rules:
+@noindent
+is invalid even if the size of the structure is the same as the size of
+the @code{int}.
-In particular, a caller function can inline a callee function only if the
-architectural features available to the callee are a subset of the features
-available to the caller.
-For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
-or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
-can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
-because the all the architectural features that function @code{bar} requires
-are available to function @code{foo}. Conversely, function @code{bar} cannot
-inline function @code{foo}.
+@xref{Vector Extensions}, for details of manipulating objects of vector types.
-Additionally inlining a function compiled with @option{-mstrict-align} into a
-function compiled without @code{-mstrict-align} is not allowed.
-However, inlining a function compiled without @option{-mstrict-align} into a
-function compiled with @option{-mstrict-align} is allowed.
+@cindex @code{visibility} attribute
+@item visibility ("@var{visibility_type}")
+This attribute affects the linkage of the declaration to which it is attached.
+It can be applied to functions, variables, and types.
-Note that CPU tuning options and attributes such as the @option{-mcpu=},
-@option{-mtune=} do not inhibit inlining unless the CPU specified by the
-@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
-architectural feature rules specified above.
+There are four supported @var{visibility_type} values: @code{default},
+@code{hidden}, @code{protected}, or @code{internal} visibility.
-@node AMD GCN Function Attributes
-@subsubsection AMD GCN Function Attributes
+@smallexample
+void __attribute__ ((visibility ("protected")))
+f () @{ /* @r{Do something.} */; @}
+int i __attribute__ ((visibility ("hidden")));
+@end smallexample
-These function attributes are supported by the AMD GCN back end:
+The possible values of @var{visibility_type} correspond to the
+visibility settings in the ELF gABI.
@table @code
-@cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
-@item amdgpu_hsa_kernel
-This attribute indicates that the corresponding function should be compiled as
-a kernel function, that is an entry point that can be invoked from the host
-via the HSA runtime library. By default functions are only callable only from
-other GCN functions.
+@c keep this list of visibilities in alphabetical order.
-This attribute is implicitly applied to any function named @code{main}, using
-default parameters.
+@item default
+Default visibility is the normal case for the object file format.
+This value is available for the visibility attribute to override other
+options that may change the assumed visibility of entities.
-Kernel functions may return an integer value, which will be written to a
-conventional place within the HSA "kernargs" region.
+On ELF, default visibility means that the declaration is visible to other
+modules and, in shared libraries, means that the declared entity may be
+overridden.
-The attribute parameters configure what values are passed into the kernel
-function by the GPU drivers, via the initial register state. Some values are
-used by the compiler, and therefore forced on. Enabling other options may
-break assumptions in the compiler and/or run-time libraries.
+On Darwin, default visibility means that the declaration is visible to
+other modules.
-@table @code
-@item private_segment_buffer
-Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
-locate the stack).
+Default visibility corresponds to ``external linkage'' in the language.
-@item dispatch_ptr
-Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
-launch dimensions).
+@item hidden
+Hidden visibility indicates that the entity declared has a new
+form of linkage, which we call ``hidden linkage''. Two
+declarations of an object with hidden linkage refer to the same object
+if they are in the same shared object.
-@item queue_ptr
-Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
-spaces).
+@item internal
+Internal visibility is like hidden visibility, but with additional
+processor specific semantics. Unless otherwise specified by the
+psABI, GCC defines internal visibility to mean that a function is
+@emph{never} called from another module. Compare this with hidden
+functions which, while they cannot be referenced directly by other
+modules, can be referenced indirectly via function pointers. By
+indicating that a function cannot be called from outside the module,
+GCC may for instance omit the load of a PIC register since it is known
+that the calling function loaded the correct value.
-@item kernarg_segment_ptr
-Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
-locate the kernel arguments, "kernargs").
+@item protected
+Protected visibility is like default visibility except that it
+indicates that references within the defining module bind to the
+definition in that module. That is, the declared entity cannot be
+overridden by another module.
-@item dispatch_id
-Set @code{enable_sgpr_dispatch_id} flag.
+@end table
-@item flat_scratch_init
-Set @code{enable_sgpr_flat_scratch_init} flag.
+All visibilities are supported on many, but not all, ELF targets
+(supported when the assembler supports the @samp{.visibility}
+pseudo-op). Default visibility is supported everywhere. Hidden
+visibility is supported on Darwin targets.
-@item private_segment_size
-Set @code{enable_sgpr_private_segment_size} flag.
+The visibility attribute should be applied only to declarations that
+would otherwise have external linkage. The attribute should be applied
+consistently, so that the same entity should not be declared with
+different settings of the attribute.
-@item grid_workgroup_count_X
-Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
-use OpenACC/OpenMP).
+In C++, the visibility attribute applies to types as well as functions
+and objects, because in C++ types have linkage. A class must not have
+greater visibility than its non-static data member types and bases,
+and class members default to the visibility of their class. Also, a
+declaration without explicit visibility is limited to the visibility
+of its type.
-@item grid_workgroup_count_Y
-Set @code{enable_sgpr_grid_workgroup_count_y} flag.
+In C++, you can mark member functions and static member variables of a
+class with the visibility attribute. This is useful if you know a
+particular method or static member variable should only be used from
+one shared object; then you can mark it hidden while the rest of the
+class has default visibility. Care must be taken to avoid breaking
+the One Definition Rule; for example, it is usually not useful to mark
+an inline method as hidden without marking the whole class as hidden.
-@item grid_workgroup_count_Z
-Set @code{enable_sgpr_grid_workgroup_count_z} flag.
+A C++ namespace declaration can also have the visibility attribute.
-@item workgroup_id_X
-Set @code{enable_sgpr_workgroup_id_x} flag.
+@smallexample
+namespace nspace1 __attribute__ ((visibility ("protected")))
+@{ /* @r{Do something.} */; @}
+@end smallexample
-@item workgroup_id_Y
-Set @code{enable_sgpr_workgroup_id_y} flag.
+This attribute applies only to the particular namespace body, not to
+other definitions of the same namespace; it is equivalent to using
+@samp{#pragma GCC visibility} before and after the namespace
+definition (@pxref{Visibility Pragmas}).
-@item workgroup_id_Z
-Set @code{enable_sgpr_workgroup_id_z} flag.
+In C++, if a template argument has limited visibility, this
+restriction is implicitly propagated to the template instantiation.
+Otherwise, template instantiations and specializations default to the
+visibility of their template.
-@item workgroup_info
-Set @code{enable_sgpr_workgroup_info} flag.
+If both the template and enclosing class have explicit visibility, the
+visibility from the template is used.
-@item private_segment_wave_offset
-Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
-(required to locate the stack).
+In C++, attribute visibility can also be
+applied to class, struct, union and enum types. Unlike other type
+attributes, the attribute must appear between the initial keyword and
+the name of the type; it cannot appear after the body of the type.
-@item work_item_id_X
-Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
+Note that the type visibility is applied to vague linkage entities
+associated with the class (vtable, typeinfo node, etc.). In
+particular, if a class is thrown as an exception in one shared object
+and caught in another, the class must have default visibility.
+Otherwise the two shared objects are unable to use the same
+typeinfo node and exception handling will break.
-@item work_item_id_Y
-Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
-vectorization.)
+@cindex @code{warn_if_not_aligned} attribute
+@item warn_if_not_aligned (@var{alignment})
-@item work_item_id_Z
-Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
-OpenACC/OpenMP).
+This attribute specifies an alignment threshold, measured in bytes,
+for structure fields.
+If the structure field is aligned below the threshold, a
+warning is issued.
-@end table
-@end table
+For example, the declaration:
+
+@smallexample
+struct foo
+@{
+ int i1;
+ int i2;
+ unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
+@};
+@end smallexample
-@node ARC Function Attributes
-@subsubsection ARC Function Attributes
+@noindent
+causes the compiler to issue an warning on @code{struct foo}, like
+@samp{warning: alignment 8 of 'struct foo' is less than 16}.
+The compiler also issues a warning, like @samp{warning: 'x' offset
+8 in 'struct foo' isn't aligned to 16}, when the structure field has
+the misaligned offset:
-These function attributes are supported by the ARC back end:
+@smallexample
+struct __attribute__ ((aligned (16))) foo
+@{
+ int i1;
+ int i2;
+ unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
+@};
+@end smallexample
-@table @code
-@cindex @code{interrupt} function attribute, ARC
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+This attribute can also be applied to a typedef, in which case it applies
+to all structure fields of that type.
-On the ARC, you must specify the kind of interrupt to be handled
-in a parameter to the interrupt attribute like this:
+For example, this code:
@smallexample
-void f () __attribute__ ((interrupt ("ilink1")));
+typedef unsigned long long __u64
+ __attribute__((aligned (4), warn_if_not_aligned (8)));
+
+struct foo
+@{
+ int i1;
+ int i2;
+ __u64 x;
+@};
@end smallexample
-Permissible values for this parameter are: @w{@code{ilink1}} and
-@w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
-@w{@code{firq}} for ARCv2 architecture.
+@noindent
+has similar behavior to the first example above.
-@cindex @code{long_call} function attribute, ARC
-@cindex @code{medium_call} function attribute, ARC
-@cindex @code{short_call} function attribute, ARC
-@cindex indirect calls, ARC
-@item long_call
-@itemx medium_call
-@itemx short_call
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
-command-line switches and @code{#pragma long_calls} settings.
+This warning can be disabled by @option{-Wno-if-not-aligned}.
-For ARC, a function marked with the @code{long_call} attribute is
-always called using register-indirect jump-and-link instructions,
-thereby enabling the called function to be placed anywhere within the
-32-bit address space. A function marked with the @code{medium_call}
-attribute will always be close enough to be called with an unconditional
-branch-and-link instruction, which has a 25-bit offset from
-the call site. A function marked with the @code{short_call}
-attribute will always be close enough to be called with a conditional
-branch-and-link instruction, which has a 21-bit offset from
-the call site.
+@cindex @code{warn_unused_result} function attribute
+@item warn_unused_result
+The @code{warn_unused_result} attribute causes a warning to be emitted
+if a caller of the function with this attribute does not use its
+return value. This is useful for functions where not checking
+the result is either a security problem or always a bug, such as
+@code{realloc}.
-@cindex @code{jli_always} function attribute, ARC
-@item jli_always
-Forces a particular function to be called using @code{jli}
-instruction. The @code{jli} instruction makes use of a table stored
-into @code{.jlitab} section, which holds the location of the functions
-which are addressed using this instruction.
+@smallexample
+int fn () __attribute__ ((warn_unused_result));
+int foo ()
+@{
+ if (fn () < 0) return -1;
+ fn ();
+ return 0;
+@}
+@end smallexample
-@cindex @code{jli_fixed} function attribute, ARC
-@item jli_fixed
-Identical like the above one, but the location of the function in the
-@code{jli} table is known and given as an attribute parameter.
+@noindent
+results in warning on line 5.
-@cindex @code{secure_call} function attribute, ARC
-@item secure_call
-This attribute allows one to mark secure-code functions that are
-callable from normal mode. The location of the secure call function
-into the @code{sjli} table needs to be passed as argument.
+@cindex @code{weak} attribute
+@item weak
+The @code{weak} attribute causes a declaration of an external symbol
+to be emitted as a weak symbol rather than a global. This is primarily
+useful in defining library functions that can be overridden in user code,
+though it can also be used with non-function declarations. The overriding
+symbol must have the same type as the weak symbol. In addition, if it
+designates a variable it must also have the same size and alignment as
+the weak symbol. Weak symbols are supported for ELF targets, and also
+for a.out targets when using the GNU assembler and linker.
-@cindex @code{naked} function attribute, ARC
-@item naked
-This attribute allows the compiler to construct the requisite function
-declaration, while allowing the body of the function to be assembly
-code. The specified function will not have prologue/epilogue
-sequences generated by the compiler. Only basic @code{asm} statements
-can safely be included in naked functions (@pxref{Basic Asm}). While
-using extended @code{asm} or a mixture of basic @code{asm} and C code
-may appear to work, they cannot be depended upon to work reliably and
-are not supported.
+@cindex @code{weakref} attribute
+@item weakref
+@itemx weakref ("@var{target}")
+The @code{weakref} attribute marks a declaration of a function or
+variable as a weak reference.
+Without arguments, it should be accompanied by an @code{alias} attribute
+naming the target symbol. Alternatively, @var{target} may be given as
+an argument to @code{weakref} itself, naming the target definition of
+the alias. The @var{target} must have the same type as the declaration.
+In addition, if it designates a variable it must also have the same size
+and alignment as the declaration. In either form of the declaration
+@code{weakref} implicitly marks the declared symbol as @code{weak}. Without
+a @var{target} given as an argument to @code{weakref} or to @code{alias},
+@code{weakref} is equivalent to @code{weak} (in that case the declaration
+may be @code{extern}).
-@end table
+@smallexample
+/* Given the declaration: */
+extern int y (void);
-@node ARM Function Attributes
-@subsubsection ARM Function Attributes
+/* the following... */
+static int x (void) __attribute__ ((weakref ("y")));
-These function attributes are supported for ARM targets:
+/* is equivalent to... */
+static int x (void) __attribute__ ((weakref, alias ("y")));
-@table @code
+/* or, alternatively, to... */
+static int x (void) __attribute__ ((weakref));
+static int x (void) __attribute__ ((alias ("y")));
+@end smallexample
-@cindex @code{general-regs-only} function attribute, ARM
-@item general-regs-only
-Indicates that no floating-point or Advanced SIMD registers should be
-used when generating code for this function. If the function explicitly
-uses floating-point code, then the compiler gives an error. This is
-the same behavior as that of the command-line option
-@option{-mgeneral-regs-only}.
+A weak reference is an alias that does not by itself require a
+definition to be given for the target symbol. If the target symbol is
+only referenced through weak references, then it becomes a @code{weak}
+undefined symbol. If it is directly referenced, however, then such
+strong references prevail, and a definition is required for the
+symbol, not necessarily in the same translation unit.
-@cindex @code{interrupt} function attribute, ARM
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+The effect is equivalent to moving all references to the alias to a
+separate translation unit, renaming the alias to the aliased symbol,
+declaring it as weak, compiling the two separate translation units and
+performing a link with relocatable output (i.e.@: @code{ld -r}) on them.
-You can specify the kind of interrupt to be handled by
-adding an optional parameter to the interrupt attribute like this:
+A declaration to which @code{weakref} is attached and that is associated
+with a named @code{target} must be @code{static}.
-@smallexample
-void f () __attribute__ ((interrupt ("IRQ")));
-@end smallexample
+@cindex @code{zero_call_used_regs} function attribute
+@item zero_call_used_regs ("@var{choice}")
-@noindent
-Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
-@code{SWI}, @code{ABORT} and @code{UNDEF}.
+The @code{zero_call_used_regs} function attribute causes the compiler to zero
+a subset of all call-used registers@footnote{A ``call-used'' register
+is a register whose contents can be changed by a function call;
+therefore, a caller cannot assume that the register has the same contents
+on return from the function as it had before calling the function. Such
+registers are also called ``call-clobbered'', ``caller-saved'', or
+``volatile''.} at function return.
+This is used to increase program security by either mitigating
+Return-Oriented Programming (ROP) attacks or preventing information leakage
+through registers.
-On ARMv7-M the interrupt type is ignored, and the attribute means the function
-may be called with a word-aligned stack pointer.
+In order to satisfy users with different security needs and control the
+run-time overhead at the same time, the @var{choice} parameter provides a
+flexible way to choose the subset of the call-used registers to be zeroed.
+The four basic values of @var{choice} are:
-@cindex @code{isr} function attribute, ARM
-@item isr
-Use this attribute on ARM to write Interrupt Service Routines. This is an
-alias to the @code{interrupt} attribute above.
+@itemize @bullet
+@item
+@samp{skip} doesn't zero any call-used registers.
-@cindex @code{long_call} function attribute, ARM
-@cindex @code{short_call} function attribute, ARM
-@cindex indirect calls, ARM
-@item long_call
-@itemx short_call
-These attributes specify how a particular function is called.
-These attributes override the
-@option{-mlong-calls} (@pxref{ARM Options})
-command-line switch and @code{#pragma long_calls} settings. For ARM, the
-@code{long_call} attribute indicates that the function might be far
-away from the call site and require a different (more expensive)
-calling sequence. The @code{short_call} attribute always places
-the offset to the function from the call site into the @samp{BL}
-instruction directly.
+@item
+@samp{used} only zeros call-used registers that are used in the function.
+A ``used'' register is one whose content has been set or referenced in
+the function.
-@cindex @code{naked} function attribute, ARM
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
+@item
+@samp{all} zeros all call-used registers.
-@cindex @code{pcs} function attribute, ARM
-@item pcs
+@item
+@samp{leafy} behaves like @samp{used} in a leaf function, and like
+@samp{all} in a nonleaf function. This makes for leaner zeroing in leaf
+functions, where the set of used registers is known, and that may be
+enough for some purposes of register zeroing.
+@end itemize
-The @code{pcs} attribute can be used to control the calling convention
-used for a function on ARM. The attribute takes an argument that specifies
-the calling convention to use.
+In addition to these three basic choices, it is possible to modify
+@samp{used}, @samp{all}, and @samp{leafy} as follows:
-When compiling using the AAPCS ABI (or a variant of it) then valid
-values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
-order to use a variant other than @code{"aapcs"} then the compiler must
-be permitted to use the appropriate co-processor registers (i.e., the
-VFP registers must be available in order to use @code{"aapcs-vfp"}).
-For example,
+@itemize @bullet
+@item
+Adding @samp{-gpr} restricts the zeroing to general-purpose registers.
-@smallexample
-/* Argument passed in r0, and result returned in r0+r1. */
-double f2d (float) __attribute__((pcs("aapcs")));
-@end smallexample
+@item
+Adding @samp{-arg} restricts the zeroing to registers that can sometimes
+be used to pass function arguments. This includes all argument registers
+defined by the platform's calling conversion, regardless of whether the
+function uses those registers for function arguments or not.
+@end itemize
-Variadic functions always use the @code{"aapcs"} calling convention and
-the compiler rejects attempts to specify an alternative.
+The modifiers can be used individually or together. If they are used
+together, they must appear in the order above.
-@cindex @code{target} function attribute
-@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
+The full list of @var{choice}s is therefore:
-On ARM, the following options are allowed:
+@table @code
+@item skip
+doesn't zero any call-used register.
-@table @samp
-@cindex @code{target("thumb")} function attribute, ARM
-@item thumb
-Force code generation in the Thumb (T16/T32) ISA, depending on the
-architecture level.
+@item used
+only zeros call-used registers that are used in the function.
-@cindex @code{target("arm")} function attribute, ARM
-@item arm
-Force code generation in the ARM (A32) ISA.
+@item used-gpr
+only zeros call-used general purpose registers that are used in the function.
-Functions from different modes can be inlined in the caller's mode.
+@item used-arg
+only zeros call-used registers that are used in the function and pass arguments.
-@cindex @code{target("fpu=")} function attribute, ARM
-@item fpu=
-Specifies the fpu for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mfpu=}
-command-line option.
+@item used-gpr-arg
+only zeros call-used general purpose registers that are used in the function
+and pass arguments.
-@cindex @code{arch=} function attribute, ARM
-@item arch=
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option.
+@item all
+zeros all call-used registers.
-The above target attributes can be specified as follows:
+@item all-gpr
+zeros all call-used general purpose registers.
-@smallexample
-__attribute__((target("arch=armv8-a+crc")))
-int
-f (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+@item all-arg
+zeros all call-used registers that pass arguments.
-Additionally, the architectural extension string may be specified on its
-own. This can be used to turn on and off particular architectural extensions
-without having to specify a particular architecture version or core. Example:
+@item all-gpr-arg
+zeros all call-used general purpose registers that pass
+arguments.
-@smallexample
-__attribute__((target("+crc+nocrypto")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+@item leafy
+Same as @samp{used} in a leaf function, and same as @samp{all} in a
+nonleaf function.
-In this example @code{target("+crc+nocrypto")} enables the @code{crc}
-extension and disables the @code{crypto} extension for the function @code{foo}
-without modifying an existing @option{-march=} or @option{-mcpu} option.
+@item leafy-gpr
+Same as @samp{used-gpr} in a leaf function, and same as @samp{all-gpr}
+in a nonleaf function.
+
+@item leafy-arg
+Same as @samp{used-arg} in a leaf function, and same as @samp{all-arg}
+in a nonleaf function.
+
+@item leafy-gpr-arg
+Same as @samp{used-gpr-arg} in a leaf function, and same as
+@samp{all-gpr-arg} in a nonleaf function.
@end table
+Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg},
+@samp{all-gpr-arg}, @samp{leafy-arg}, and @samp{leafy-gpr-arg} are
+mainly used for ROP mitigation.
+
+The default for the attribute is controlled by @option{-fzero-call-used-regs}.
@end table
-@node AVR Function Attributes
-@subsubsection AVR Function Attributes
+@c This is the end of the target-independent attribute table
+
+@node Target-Specific Attributes
+@subsection Target-Specific Attributes
+
+@menu
+* AArch64 Attributes::
+* AMD GCN Attributes::
+* ARC Attributes::
+* ARM Attributes::
+* AVR Attributes::
+* Blackfin Attributes::
+* BPF Attributes::
+* C-SKY Attributes::
+* Epiphany Attributes::
+* H8/300 Attributes::
+* IA-64 Attributes::
+* LoongArch Attributes::
+* M32C Attributes::
+* M32R/D Attributes::
+* m68k Attributes::
+* MCORE Attributes::
+* MicroBlaze Attributes::
+* Microsoft Windows Attributes::
+* MIPS Attributes::
+* MSP430 Attributes::
+* NDS32 Attributes::
+* Nvidia PTX Attributes::
+* PowerPC Attributes::
+* RISC-V Attributes::
+* RL78 Attributes::
+* RX Attributes::
+* S/390 Attributes::
+* SH Attributes::
+* Symbian OS Attributes::
+* V850 Attributes::
+* Visium Attributes::
+* x86 Attributes::
+* Xstormy16 Attributes::
+@end menu
+
+@node AArch64 Attributes
+@subsubsection AArch64 Attributes
-These function attributes are supported by the AVR back end:
+The following target-specific function attributes are available for the
+AArch64 target. For the most part, these options mirror the behavior of
+similar command-line options (@pxref{AArch64 Options}), but on a
+per-function basis.
@table @code
-@cindex @code{signal} function attribute, AVR
-@cindex @code{interrupt} function attribute, AVR
-@item signal
-@itemx interrupt
-The function is an interrupt service routine (ISR). The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when one of the attributes is present.
+@cindex @code{general-regs-only} function attribute, AArch64
+@item general-regs-only
+Indicates that no floating-point or Advanced SIMD registers should be
+used when generating code for this function. If the function explicitly
+uses floating-point code, then the compiler gives an error. This is
+the same behavior as that of the command-line option
+@option{-mgeneral-regs-only}.
-The AVR hardware globally disables interrupts when an interrupt is executed.
+@cindex @code{fix-cortex-a53-835769} function attribute, AArch64
+@item fix-cortex-a53-835769
+Indicates that the workaround for the Cortex-A53 erratum 835769 should be
+applied to this function. To explicitly disable the workaround for this
+function specify the negated form: @code{no-fix-cortex-a53-835769}.
+This corresponds to the behavior of the command-line options
+@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}.
-@itemize @bullet
-@item ISRs with the @code{signal} attribute do not re-enable interrupts.
-It is save to enable interrupts in a @code{signal} handler.
-This ``save'' only applies to the code
-generated by the compiler and not to the IRQ layout of the
-application which is responsibility of the application.
+@cindex @code{cmodel=} function attribute, AArch64
+@item cmodel=
+Indicates that code should be generated for a particular code model for
+this function. The behavior and permissible arguments are the same as
+for the command-line option @option{-mcmodel=}.
-@item ISRs with the @code{interrupt} attribute re-enable interrupts.
-The first instruction of the routine is a @code{SEI} instruction to
-globally enable interrupts.
-@end itemize
+@cindex @code{strict-align} function attribute, AArch64
+@item strict-align
+@itemx no-strict-align
+@code{strict-align} indicates that the compiler should not assume that unaligned
+memory references are handled by the system. To allow the compiler to assume
+that aligned memory references are handled by the system, the inverse attribute
+@code{no-strict-align} can be specified. The behavior is same as for the
+command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
-The recommended way to use these attributes is by means of the
-@code{ISR} macro provided by @code{avr/interrupt.h} from
-@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
-@example
-#include <avr/interrupt.h>
+@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64
+@item omit-leaf-frame-pointer
+Indicates that the frame pointer should be omitted for a leaf function call.
+To keep the frame pointer, the inverse attribute
+@code{no-omit-leaf-frame-pointer} can be specified. These attributes have
+the same behavior as the command-line options @option{-momit-leaf-frame-pointer}
+and @option{-mno-omit-leaf-frame-pointer}.
-ISR (INT0_vect) // Uses the "signal" attribute.
-@{
- // Code
-@}
+@cindex @code{tls-dialect=} function attribute, AArch64
+@item tls-dialect=
+Specifies the TLS dialect to use for this function. The behavior and
+permissible arguments are the same as for the command-line option
+@option{-mtls-dialect=}.
-ISR (ADC_vect, ISR_NOBLOCK) // Uses the "interrupt" attribute.
-@{
- // Code
-@}
-@end example
+@cindex @code{arch=} function attribute, AArch64
+@item arch=
+Specifies the architecture version and architectural extensions to use
+for this function. The behavior and permissible arguments are the same as
+for the @option{-march=} command-line option.
-When both @code{signal} and @code{interrupt} are specified for the same
-function, then @code{signal} is silently ignored.
+@cindex @code{tune=} function attribute, AArch64
+@item tune=
+Specifies the core for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mtune=}
+command-line option.
-@cindex @code{signal(@var{num})} function attribute, AVR
-@cindex @code{interrupt(@var{num})} function attribute, AVR
-@item signal(@var{num})
-@itemx interrupt(@var{num})
+@cindex @code{cpu=} function attribute, AArch64
+@item cpu=
+Specifies the core for which to tune the performance of this function and also
+whose architectural features to use. The behavior and valid arguments are the
+same as for the @option{-mcpu=} command-line option.
-Similar to the @code{signal} resp. @code{interrupt} attribute without
-argument, but the IRQ number is supplied as an argument @var{num} to
-the attribute, rather than providing the ISR name itself as the function name:
+@cindex @code{sign-return-address} function attribute, AArch64
+@item sign-return-address
+Select the function scope on which return address signing will be applied. The
+behavior and permissible arguments are the same as for the command-line option
+@option{-msign-return-address=}. The default value is @code{none}. This
+attribute is deprecated. The @code{branch-protection} attribute should
+be used instead.
-@example
-__attribute__((signal(1)))
-static void my_handler (void)
-@{
- // Code for __vector_1
-@}
-@end example
+@cindex @code{branch-protection} function attribute, AArch64
+@item branch-protection
+Select the function scope on which branch protection will be applied. The
+behavior and permissible arguments are the same as for the command-line option
+@option{-mbranch-protection=}. The default value is @code{none}.
-Notice that the handler function needs not to be externally visible.
-The recommended way to use these attributes is by means of the
-@code{ISR_N} macro provided by @code{avr/interrupt.h} from
-@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
+@cindex @code{outline-atomics} function attribute, AArch64
+@item outline-atomics
+@itemx no-outline-atomics
+Enable or disable calls to out-of-line helpers to implement atomic operations.
+This corresponds to the behavior of the command-line options
+@option{-moutline-atomics} and @option{-mno-outline-atomics}.
-@example
-#include <avr/interrupt.h>
+@cindex @code{max-vectorization} function attribute, AArch64
+@item max-vectorization
+@itemx no-max-vectorization
+@code{max-vectorization} tells GCC's vectorizer to treat all vector
+loops as being more profitable than the original scalar loops when
+optimizing the current function. @code{no-max-vectorization} disables
+this behavior.
+This corresponds to the behavior of the command-line options
+@option{-mmax-vectorization} and @option{-mno-max-vectorization}.
-ISR_N (PCINT0_vect_num)
-static void my_pcint0_handler (void)
-@{
- // Code
-@}
+@cindex @code{indirect_return} function attribute, AArch64
+@item indirect_return
+The @code{indirect_return} attribute can be applied to a function type
+to indicate that the function may return via an indirect branch instead
+of via a normal return instruction. For example, this can be true of
+functions that implement manual context switching between user space
+threads, such as the POSIX @code{swapcontext} function. This attribute
+adds a @code{BTI J} instruction when BTI is enabled e.g. via
+@option{-mbranch-protection}.
-ISR_N (ADC_vect_num, ISR_NOBLOCK)
-static void my_adc_handler (void)
+@cindex @code{preserve_none} function attribute, AArch64
+@item preserve_none
+Use this attribute to change the procedure call standard of the specified
+function to the preserve-none variant.
+
+The preserve-none ABI variant modifies the AAPCS such that it has no
+callee-saved registers (including SIMD and floating-point registers). That is,
+with the exception of the stack register, link register (r30), and frame pointer
+(r29), all registers are changed to caller saved, and can be used as scratch
+registers by the callee.
+
+Additionally, registers r20--r28, r0--r7, r10--r14, r9 and r15 are used for
+argument passing, in that order. For Microsoft Windows targets
+r15 is not used for argument passing.
+
+The return value registers remain r0 and r1 in both cases.
+
+All other details are the same as for the AAPCS ABI.
+
+This ABI has not been stabilized, and may be subject to change in future
+versions.
+@end table
+
+The above target attributes can be specified as follows:
+
+@smallexample
+__attribute__((target("@var{attr-string}")))
+int
+f (int a)
@{
- // Code
+ return a + 5;
@}
-@end example
+@end smallexample
-@code{ISR_N} can be specified more than once, in which case several
-interrupt vectors are pointing to the same handler function. This
-is similar to the @code{ISR_ALIASOF} macro provided by AVR-LibC, but
-without the overhead introduced by @code{ISR_ALIASOF}.
+where @code{@var{attr-string}} is one of the attribute strings specified above.
+Additionally, the architectural extension string may be specified on its
+own. This can be used to turn on and off particular architectural extensions
+without having to specify a particular architecture version or core. Example:
-@cindex @code{noblock} function attribute, AVR
-@item noblock
+@smallexample
+__attribute__((target("+crc+nocrypto")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-This attribute can be used together with the @code{signal} attribute
-to indicate that an interrupt service routine should start with a @code{SEI}
-instruction to globally re-enable interrupts. Using attributes @code{signal}
-and @code{noblock} together has the same effect like using the @code{interrupt}
-attribute. Using the @code{noblock} attribute without @code{signal} has no
-effect.
+In this example @code{target("+crc+nocrypto")} enables the @code{crc}
+extension and disables the @code{crypto} extension for the function @code{foo}
+without modifying an existing @option{-march=} or @option{-mcpu} option.
-@cindex @code{naked} function attribute, AVR
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
+Multiple target function attributes can be specified by separating them with
+a comma. For example:
+@smallexample
+__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-@cindex @code{no_gccisr} function attribute, AVR
-@item no_gccisr
-Do not use the @code{__gcc_isr}
-@uref{https://sourceware.org/binutils/docs/as/AVR-Pseudo-Instructions.html,pseudo instruction}
-in a function with
-the @code{interrupt} or @code{signal} attribute aka. interrupt
-service routine (ISR).
-Use this attribute if the preamble of the ISR prologue should always read
-@example
-push __zero_reg__
-push __tmp_reg__
-in __tmp_reg__, __SREG__
-push __tmp_reg__
-clr __zero_reg__
-@end example
-and accordingly for the postamble of the epilogue --- no matter whether
-the mentioned registers are actually used in the ISR or not.
-Situations where you might want to use this attribute include:
-@itemize @bullet
-@item
-Code that (effectively) clobbers bits of @code{SREG} other than the
-@code{I}-flag by writing to the memory location of @code{SREG}.
-@item
-Code that uses inline assembler to jump to a different function which
-expects (parts of) the prologue code as outlined above to be present.
-@end itemize
-To disable @code{__gcc_isr} generation for the whole compilation unit,
-there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
+is valid and compiles function @code{foo} for ARMv8-A with @code{crc}
+and @code{crypto} extensions and tunes it for @code{cortex-a53}.
-@cindex @code{OS_main} function attribute, AVR
-@cindex @code{OS_task} function attribute, AVR
-@item OS_main
-@itemx OS_task
-On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
-do not save/restore any call-saved register in their prologue/epilogue.
+@subsubheading Inlining rules
+Specifying target attributes on individual functions or performing link-time
+optimization across translation units compiled with different target options
+can affect function inlining rules:
-The @code{OS_main} attribute can be used when there @emph{is
-guarantee} that interrupts are disabled at the time when the function
-is entered. This saves resources when the stack pointer has to be
-changed to set up a frame for local variables.
+In particular, a caller function can inline a callee function only if the
+architectural features available to the callee are a subset of the features
+available to the caller.
+For example: A function @code{foo} compiled with @option{-march=armv8-a+crc},
+or tagged with the equivalent @code{arch=armv8-a+crc} attribute,
+can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc}
+because the all the architectural features that function @code{bar} requires
+are available to function @code{foo}. Conversely, function @code{bar} cannot
+inline function @code{foo}.
-The @code{OS_task} attribute can be used when there is @emph{no
-guarantee} that interrupts are disabled at that time when the function
-is entered like for, e@.g@. task functions in a multi-threading operating
-system. In that case, changing the stack pointer register is
-guarded by save/clear/restore of the global interrupt enable flag.
+Additionally inlining a function compiled with @option{-mstrict-align} into a
+function compiled without @code{-mstrict-align} is not allowed.
+However, inlining a function compiled without @option{-mstrict-align} into a
+function compiled with @option{-mstrict-align} is allowed.
-The differences to the @code{naked} function attribute are:
-@itemize @bullet
-@item @code{naked} functions do not have a return instruction whereas
-@code{OS_main} and @code{OS_task} functions have a @code{RET} or
-@code{RETI} return instruction.
-@item @code{naked} functions do not set up a frame for local variables
-or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
-as needed.
-@end itemize
+Note that CPU tuning options and attributes such as the @option{-mcpu=},
+@option{-mtune=} do not inhibit inlining unless the CPU specified by the
+@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the
+architectural feature rules specified above.
-@end table
+@node AMD GCN Attributes
+@subsubsection AMD GCN Attributes
-@node Blackfin Function Attributes
-@subsubsection Blackfin Function Attributes
+These function attributes are supported by the AMD GCN back end:
+
+@table @code
+@cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN
+@item amdgpu_hsa_kernel
+This attribute indicates that the corresponding function should be compiled as
+a kernel function, that is an entry point that can be invoked from the host
+via the HSA runtime library. By default functions are only callable only from
+other GCN functions.
+
+This attribute is implicitly applied to any function named @code{main}, using
+default parameters.
-These function attributes are supported by the Blackfin back end:
+Kernel functions may return an integer value, which will be written to a
+conventional place within the HSA "kernargs" region.
+
+The attribute parameters configure what values are passed into the kernel
+function by the GPU drivers, via the initial register state. Some values are
+used by the compiler, and therefore forced on. Enabling other options may
+break assumptions in the compiler and/or run-time libraries.
@table @code
+@item private_segment_buffer
+Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to
+locate the stack).
-@cindex @code{exception_handler} function attribute
-@cindex exception handler functions, Blackfin
-@item exception_handler
-Use this attribute on the Blackfin to indicate that the specified function
-is an exception handler. The compiler generates function entry and
-exit sequences suitable for use in an exception handler when this
-attribute is present.
+@item dispatch_ptr
+Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the
+launch dimensions).
-@cindex @code{interrupt_handler} function attribute, Blackfin
-@item interrupt_handler
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
+@item queue_ptr
+Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address
+spaces).
-@cindex @code{kspisusp} function attribute, Blackfin
-@cindex User stack pointer in interrupts on the Blackfin
-@item kspisusp
-When used together with @code{interrupt_handler}, @code{exception_handler}
-or @code{nmi_handler}, code is generated to load the stack pointer
-from the USP register in the function prologue.
+@item kernarg_segment_ptr
+Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to
+locate the kernel arguments, "kernargs").
-@cindex @code{l1_text} function attribute, Blackfin
-@item l1_text
-This attribute specifies a function to be placed into L1 Instruction
-SRAM@. The function is put into a specific section named @code{.l1.text}.
-With @option{-mfdpic}, function calls with a such function as the callee
-or caller uses inlined PLT.
+@item dispatch_id
+Set @code{enable_sgpr_dispatch_id} flag.
-@cindex @code{l2} function attribute, Blackfin
-@item l2
-This attribute specifies a function to be placed into L2
-SRAM. The function is put into a specific section named
-@code{.l2.text}. With @option{-mfdpic}, callers of such functions use
-an inlined PLT.
+@item flat_scratch_init
+Set @code{enable_sgpr_flat_scratch_init} flag.
-@cindex indirect calls, Blackfin
-@cindex @code{longcall} function attribute, Blackfin
-@cindex @code{shortcall} function attribute, Blackfin
-@item longcall
-@itemx shortcall
-The @code{longcall} attribute
-indicates that the function might be far away from the call site and
-require a different (more expensive) calling sequence. The
-@code{shortcall} attribute indicates that the function is always close
-enough for the shorter calling sequence to be used. These attributes
-override the @option{-mlongcall} switch.
+@item private_segment_size
+Set @code{enable_sgpr_private_segment_size} flag.
-@cindex @code{nesting} function attribute, Blackfin
-@cindex Allow nesting in an interrupt handler on the Blackfin processor
-@item nesting
-Use this attribute together with @code{interrupt_handler},
-@code{exception_handler} or @code{nmi_handler} to indicate that the function
-entry code should enable nested interrupts or exceptions.
+@item grid_workgroup_count_X
+Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to
+use OpenACC/OpenMP).
-@cindex @code{nmi_handler} function attribute, Blackfin
-@cindex NMI handler functions on the Blackfin processor
-@item nmi_handler
-Use this attribute on the Blackfin to indicate that the specified function
-is an NMI handler. The compiler generates function entry and
-exit sequences suitable for use in an NMI handler when this
-attribute is present.
+@item grid_workgroup_count_Y
+Set @code{enable_sgpr_grid_workgroup_count_y} flag.
-@cindex @code{saveall} function attribute, Blackfin
-@cindex save all registers on the Blackfin
-@item saveall
-Use this attribute to indicate that
-all registers except the stack pointer should be saved in the prologue
-regardless of whether they are used or not.
-@end table
+@item grid_workgroup_count_Z
+Set @code{enable_sgpr_grid_workgroup_count_z} flag.
-@node BPF Function Attributes
-@subsubsection BPF Function Attributes
+@item workgroup_id_X
+Set @code{enable_sgpr_workgroup_id_x} flag.
-These function attributes are supported by the BPF back end:
+@item workgroup_id_Y
+Set @code{enable_sgpr_workgroup_id_y} flag.
-@table @code
-@cindex @code{kernel helper}, function attribute, BPF
-@item kernel_helper
-use this attribute to indicate the specified function declaration is a
-kernel helper. The helper function is passed as an argument to the
-attribute. Example:
+@item workgroup_id_Z
+Set @code{enable_sgpr_workgroup_id_z} flag.
-@smallexample
-int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
- __attribute__ ((kernel_helper (4)));
-@end smallexample
+@item workgroup_info
+Set @code{enable_sgpr_workgroup_info} flag.
+
+@item private_segment_wave_offset
+Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on
+(required to locate the stack).
+
+@item work_item_id_X
+Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled).
+
+@item work_item_id_Y
+Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable
+vectorization.)
+
+@item work_item_id_Z
+Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use
+OpenACC/OpenMP).
-@cindex @code{naked} function attribute, BPF
-@item naked
-This attribute allows the compiler to construct the requisite function
-declaration, while allowing the body of the function to be assembly
-code. The specified function will not have prologue/epilogue
-sequences generated by the compiler. Only basic @code{asm} statements
-can safely be included in naked functions (@pxref{Basic Asm}). While
-using extended @code{asm} or a mixture of basic @code{asm} and C code
-may appear to work, they cannot be depended upon to work reliably and
-are not supported.
+@end table
@end table
-@node C-SKY Function Attributes
-@subsubsection C-SKY Function Attributes
+@node ARC Attributes
+@subsubsection ARC Attributes
-These function attributes are supported by the C-SKY back end:
+These attributes are supported by the ARC back end:
@table @code
-@cindex @code{interrupt} function attribute, C-SKY
-@cindex @code{isr} function attribute, C-SKY
+@cindex @code{interrupt} function attribute, ARC
@item interrupt
-@itemx isr
-Use these attributes to indicate that the specified function
-is an interrupt handler.
-The compiler generates function entry and exit sequences suitable for
-use in an interrupt handler when either of these attributes are present.
+Use this function attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-Use of these options requires the @option{-mistack} command-line option
-to enable support for the necessary interrupt stack instructions. They
-are ignored with a warning otherwise. @xref{C-SKY Options}.
+On the ARC, you must specify the kind of interrupt to be handled
+in a parameter to the interrupt attribute like this:
-@cindex @code{naked} function attribute, C-SKY
+@smallexample
+void f () __attribute__ ((interrupt ("ilink1")));
+@end smallexample
+
+Permissible values for this parameter are: @w{@code{ilink1}} and
+@w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and
+@w{@code{firq}} for ARCv2 architecture.
+
+@cindex @code{long_call} function attribute, ARC
+@cindex @code{medium_call} function attribute, ARC
+@cindex @code{short_call} function attribute, ARC
+@cindex indirect calls, ARC
+@item long_call
+@itemx medium_call
+@itemx short_call
+These attributes specify how a particular function is called.
+These attributes override the
+@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options})
+command-line switches and @code{#pragma long_calls} settings.
+
+For ARC, a function marked with the @code{long_call} attribute is
+always called using register-indirect jump-and-link instructions,
+thereby enabling the called function to be placed anywhere within the
+32-bit address space. A function marked with the @code{medium_call}
+attribute will always be close enough to be called with an unconditional
+branch-and-link instruction, which has a 25-bit offset from
+the call site. A function marked with the @code{short_call}
+attribute will always be close enough to be called with a conditional
+branch-and-link instruction, which has a 21-bit offset from
+the call site.
+
+@cindex @code{jli_always} function attribute, ARC
+@item jli_always
+Forces a particular function to be called using @code{jli}
+instruction. The @code{jli} instruction makes use of a table stored
+into @code{.jlitab} section, which holds the location of the functions
+which are addressed using this instruction.
+
+@cindex @code{jli_fixed} function attribute, ARC
+@item jli_fixed
+Identical like the above one, but the location of the function in the
+@code{jli} table is known and given as an attribute parameter.
+
+@cindex @code{secure_call} function attribute, ARC
+@item secure_call
+This attribute allows one to mark secure-code functions that are
+callable from normal mode. The location of the secure call function
+into the @code{sjli} table needs to be passed as argument.
+
+@cindex @code{naked} function attribute, ARC
@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-@end table
+This attribute allows the compiler to construct the requisite function
+declaration, while allowing the body of the function to be assembly
+code. The specified function will not have prologue/epilogue
+sequences generated by the compiler. Only basic @code{asm} statements
+can safely be included in naked functions (@pxref{Basic Asm}). While
+using extended @code{asm} or a mixture of basic @code{asm} and C code
+may appear to work, they cannot be depended upon to work reliably and
+are not supported.
+
+@cindex @code{aux} variable attribute, ARC
+@item aux
+The @code{aux} variable attribute is used to directly access the ARC's
+auxiliary register space from C. The auxiliary register number is
+given via attribute argument.
+@item uncached
+@cindex @code{uncached} type attribute, ARC
+Declaring objects with the @code{uncached} type attribute
+allows you to exclude
+data-cache participation in load and store operations on those objects
+without involving the additional semantic implications of
+@code{volatile}. The @code{.di} instruction suffix is used for all
+loads and stores of data declared @code{uncached}.
+@end table
-@node Epiphany Function Attributes
-@subsubsection Epiphany Function Attributes
+@node ARM Attributes
+@subsubsection ARM Attributes
-These function attributes are supported by the Epiphany back end:
+These function attributes are supported for ARM targets:
@table @code
-@cindex @code{disinterrupt} function attribute, Epiphany
-@item disinterrupt
-This attribute causes the compiler to emit
-instructions to disable interrupts for the duration of the given
-function.
-@cindex @code{forwarder_section} function attribute, Epiphany
-@item forwarder_section
-This attribute modifies the behavior of an interrupt handler.
-The interrupt handler may be in external memory which cannot be
-reached by a branch instruction, so generate a local memory trampoline
-to transfer control. The single parameter identifies the section where
-the trampoline is placed.
+@cindex @code{general-regs-only} function attribute, ARM
+@item general-regs-only
+Indicates that no floating-point or Advanced SIMD registers should be
+used when generating code for this function. If the function explicitly
+uses floating-point code, then the compiler gives an error. This is
+the same behavior as that of the command-line option
+@option{-mgeneral-regs-only}.
-@cindex @code{interrupt} function attribute, Epiphany
+@cindex @code{interrupt} function attribute, ARM
@item interrupt
Use this attribute to indicate
that the specified function is an interrupt handler. The compiler generates
function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present. It may also generate
-a special section with code to initialize the interrupt vector table.
+when this attribute is present.
-On Epiphany targets one or more optional parameters can be added like this:
+You can specify the kind of interrupt to be handled by
+adding an optional parameter to the interrupt attribute like this:
@smallexample
-void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
+void f () __attribute__ ((interrupt ("IRQ")));
@end smallexample
-Permissible values for these parameters are: @w{@code{reset}},
-@w{@code{software_exception}}, @w{@code{page_miss}},
-@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
-@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
-Multiple parameters indicate that multiple entries in the interrupt
-vector table should be initialized for this function, i.e.@: for each
-parameter @w{@var{name}}, a jump to the function is emitted in
-the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
-entirely, in which case no interrupt vector table entry is provided.
+@noindent
+Permissible values for this parameter are: @code{IRQ}, @code{FIQ},
+@code{SWI}, @code{ABORT} and @code{UNDEF}.
-Note that interrupts are enabled inside the function
-unless the @code{disinterrupt} attribute is also specified.
+On ARMv7-M the interrupt type is ignored, and the attribute means the function
+may be called with a word-aligned stack pointer.
-The following examples are all valid uses of these attributes on
-Epiphany targets:
-@smallexample
-void __attribute__ ((interrupt)) universal_handler ();
-void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
-void __attribute__ ((interrupt ("dma0, dma1")))
- universal_dma_handler ();
-void __attribute__ ((interrupt ("timer0"), disinterrupt))
- fast_timer_handler ();
-void __attribute__ ((interrupt ("dma0, dma1"),
- forwarder_section ("tramp")))
- external_dma_handler ();
-@end smallexample
+@cindex @code{isr} function attribute, ARM
+@item isr
+Use this attribute on ARM to write Interrupt Service Routines. This is an
+alias to the @code{interrupt} attribute above.
-@cindex @code{long_call} function attribute, Epiphany
-@cindex @code{short_call} function attribute, Epiphany
-@cindex indirect calls, Epiphany
+@cindex @code{long_call} function attribute, ARM
+@cindex @code{short_call} function attribute, ARM
+@cindex indirect calls, ARM
@item long_call
@itemx short_call
These attributes specify how a particular function is called.
These attributes override the
-@option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
-command-line switch and @code{#pragma long_calls} settings.
-@end table
-
+@option{-mlong-calls} (@pxref{ARM Options})
+command-line switch and @code{#pragma long_calls} settings. For ARM, the
+@code{long_call} attribute indicates that the function might be far
+away from the call site and require a different (more expensive)
+calling sequence. The @code{short_call} attribute always places
+the offset to the function from the call site into the @samp{BL}
+instruction directly.
-@node H8/300 Function Attributes
-@subsubsection H8/300 Function Attributes
+@cindex @code{naked} function attribute, ARM
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-These function attributes are available for H8/300 targets:
+@cindex @code{pcs} function attribute, ARM
+@item pcs
-@table @code
-@cindex @code{function_vector} function attribute, H8/300
-@item function_vector
-Use this attribute on the H8/300, H8/300H, and H8S to indicate
-that the specified function should be called through the function vector.
-Calling a function through the function vector reduces code size; however,
-the function vector has a limited size (maximum 128 entries on the H8/300
-and 64 entries on the H8/300H and H8S)
-and shares space with the interrupt vector.
+The @code{pcs} attribute can be used to control the calling convention
+used for a function on ARM. The attribute takes an argument that specifies
+the calling convention to use.
-@cindex @code{interrupt_handler} function attribute, H8/300
-@item interrupt_handler
-Use this attribute on the H8/300, H8/300H, and H8S to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
+When compiling using the AAPCS ABI (or a variant of it) then valid
+values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In
+order to use a variant other than @code{"aapcs"} then the compiler must
+be permitted to use the appropriate co-processor registers (i.e., the
+VFP registers must be available in order to use @code{"aapcs-vfp"}).
+For example,
-@cindex @code{saveall} function attribute, H8/300
-@cindex save all registers on the H8/300, H8/300H, and H8S
-@item saveall
-Use this attribute on the H8/300, H8/300H, and H8S to indicate that
-all registers except the stack pointer should be saved in the prologue
-regardless of whether they are used or not.
+@smallexample
+/* Argument passed in r0, and result returned in r0+r1. */
+double f2d (float) __attribute__((pcs("aapcs")));
+@end smallexample
-@cindex @code{monitor} function attribute, H8/300
-@item monitor
-Use this attribute to indicate a monitor function. It tells GCC
-to generate entry and exit sequences that disable interrupts during
-execution of the function.
+Variadic functions always use the @code{"aapcs"} calling convention and
+the compiler rejects attempts to specify an alternative.
-@cindex @code{OS_Task} function attribute, H8/300
-@item OS_Task
-Use this attribute to disable the normal register and stack save and
-restore sequences on function entry and exit. The function epilogue
-generated by GCC includes only a return instruction.
-@end table
+@cindex @code{target} function attribute
+@item target (@var{options})
+As discussed in @ref{Common Attributes}, this attribute
+allows specification of target-specific compilation options.
-@node IA-64 Function Attributes
-@subsubsection IA-64 Function Attributes
+On ARM, the following options are allowed:
-These function attributes are supported on IA-64 targets:
+@table @samp
+@cindex @code{target("thumb")} function attribute, ARM
+@item thumb
+Force code generation in the Thumb (T16/T32) ISA, depending on the
+architecture level.
-@table @code
-@cindex @code{syscall_linkage} function attribute, IA-64
-@item syscall_linkage
-This attribute is used to modify the IA-64 calling convention by marking
-all input registers as live at all function exits. This makes it possible
-to restart a system call after an interrupt without having to save/restore
-the input registers. This also prevents kernel data from leaking into
-application code.
+@cindex @code{target("arm")} function attribute, ARM
+@item arm
+Force code generation in the ARM (A32) ISA.
-@cindex @code{version_id} function attribute, IA-64
-@item version_id
-This IA-64 HP-UX attribute, attached to a global variable or function, renames a
-symbol to contain a version string, thus allowing for function level
-versioning. HP-UX system header files may use function level versioning
-for some system calls.
+Functions from different modes can be inlined in the caller's mode.
-@smallexample
-extern int foo () __attribute__((version_id ("20040821")));
-@end smallexample
+@cindex @code{target("fpu=")} function attribute, ARM
+@item fpu=
+Specifies the fpu for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mfpu=}
+command-line option.
-@noindent
-Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
-@end table
-
-@node LoongArch Function Attributes
-@subsubsection LoongArch Function Attributes
-
-The following attributes are supported by LoongArch end:
-
-@table @code
-
-@cindex @code{target (option,...)} loongarch function attribute target
-@item target (option,...)
-
-The following target-specific function attributes are available for the
-LoongArch target. These options mirror the behavior of similar
-command-line options (@pxref{LoongArch Options}), but on a per-function basis.
-
-@table @code
-@cindex @code{strict-align} function attribute, LoongArch
-@item strict-align
-@itemx no-strict-align
-@code{strict-align} indicates that the compiler should not assume that unaligned
-memory references are handled by the system. To allow the compiler to assume
-that aligned memory references are handled by the system, the inverse attribute
-@code{no-strict-align} can be specified. The behavior is same as for the
-command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
-
-@cindex @code{cmodel=} function attribute, LoongArch
-@item cmodel=
-Indicates that code should be generated for a particular code model for
-this function. The behavior and permissible arguments are the same as
-for the command-line option @option{-mcmodel=}.
-
-@cindex @code{arch=} function attribute, LoongArch
+@cindex @code{arch=} function attribute, ARM
@item arch=
Specifies the architecture version and architectural extensions to use
for this function. The behavior and permissible arguments are the same as
for the @option{-march=} command-line option.
-@cindex @code{tune=} function attribute, LoongArch
-@item tune=
-Specifies the core for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mtune=}
-command-line option.
-
-@cindex @code{lsx} function attribute, LoongArch
-@item lsx
-@itemx no-lsx
-@code{lsx} indicates that vector instruction generation is allowed (not allowed)
-when compiling the function. The behavior is same as for the command-line option
-@option{-mlsx} and @option{-mno-lsx}.
-
-@cindex @code{lasx} function attribute, LoongArch
-@item lasx
-@itemx no-lasx
-@code{lasx} indicates that lasx instruction generation is allowed (not allowed)
-when compiling the function. The behavior is slightly different from the
-command-line option @option{-mno-lasx}.
-Example:
+The above target attributes can be specified as follows:
@smallexample
-test.c:
-typedef int v4i32 __attribute__ ((vector_size(16), aligned(16)));
-
-v4i32 a, b, c;
-#ifdef WITH_ATTR
-__attribute__ ((target("no-lasx"))) void
-#else
-void
-#endif
-test ()
+__attribute__((target("arch=armv8-a+crc")))
+int
+f (int a)
@{
- c = a + b;
+ return a + 5;
@}
@end smallexample
-@smallexample
-$ gcc test.c -o test.s -O2 -mlasx -DWITH_ATTR
-@end smallexample
-Compiled as above, 128-bit vectorization is possible.
-But the following method cannot perform 128-bit vectorization.
-@smallexample
-$ gcc test.c -o test.s -O2 -mlasx -mno-lasx
-@end smallexample
-
-@cindex @code{recipe} function attribute, LoongArch
-@item recipe
-@itemx no-recipe
-@code{recipe} indicates that frecipe.@{s/d@} and frsqrt.@{s/d@}instruction generation
-is allowed (not allowed) when compiling the function. The behavior is same as for
-the command-line option
-@option{-mrecipe} and @option{-mno-recipe}.
-
-@cindex @code{div32} function attribute, LoongArch
-@item div32
-@itemx no-div32
-@code{div32} determines whether div.w[u] and mod.w[u] instructions on 64-bit machines
-are evaluated based only on the lower 32 bits of the input registers.
-@option{-mdiv32} and @option{-mno-div32}.
-
-@cindex @code{lam-bh} function attribute, LoongArch
-@item lam-bh
-@itemx no-lam-bh
-@code{lam-bh} indicates that am@{swap/add@}[_db].@{b/h@} instruction generation
-is allowed (not allowed) when compiling the function. The behavior is same as for
-the command-line option
-@option{-mlam-bh} and @option{-mno-lam-bh}.
-
-@cindex @code{lamcas} function attribute, LoongArch
-@item lamcas
-@itemx no-lamcas
-@code{lamcas} indicates that amcas[_db].@{b/h/w/d@} instruction generation
-is allowed (not allowed) when compiling the function. The behavior is same as for
-the command-line option
-@option{-mlamcas} and @option{-mno-lamcas}.
-
-@cindex @code{scq} function attribute, LoongArch
-@item scq
-@itemx no-scq
-@code{scq} indicates that sc.q instruction generation is allowed (not allowed) when
-compiling the function. The behavior is same as for the command-line option
-@option{-mscq} and @option{-mno-scq}.
-
-@cindex @code{ld-seq-sa} function attribute, LoongArch
-@item ld-seq-sa
-@itemx no-ld-seq-sa
-@code{ld-seq-sa} indicates that whether need load-load barries (dbar 0x700)
-@option{-mld-seq-sa} and @option{-mno-ld-seq-sa}.
-@end table
-
-Multiple target function attributes can be specified by separating them with
-a comma. For example:
+Additionally, the architectural extension string may be specified on its
+own. This can be used to turn on and off particular architectural extensions
+without having to specify a particular architecture version or core. Example:
@smallexample
-__attribute__((target("arch=la64v1.1,lasx")))
+__attribute__((target("+crc+nocrypto")))
int
foo (int a)
@{
@}
@end smallexample
-is valid and compiles function @code{foo} for LA64V1.1 with @code{lasx}.
+In this example @code{target("+crc+nocrypto")} enables the @code{crc}
+extension and disables the @code{crypto} extension for the function @code{foo}
+without modifying an existing @option{-march=} or @option{-mcpu} option.
-@subsubheading Inlining rules
-Specifying target attributes on individual functions or performing link-time
-optimization across translation units compiled with different target options
-can affect function inlining rules:
+@end table
-In particular, a caller function can inline a callee function only if the
-architectural features available to the callee are a subset of the features
-available to the caller.
+@cindex @code{notshared} type attribute, ARM
+@item notshared
+On those ARM targets that support @code{dllimport} (such as Symbian
+OS), you can use the @code{notshared} type attribute to indicate that the
+virtual table and other similar data for a class should not be
+exported from a DLL@. For example:
-Note that when the callee function does not have the always_inline attribute,
-it will not be inlined if the code model of the caller function is different
-from the code model of the callee function.
+@smallexample
+class __declspec(notshared) C @{
+public:
+ __declspec(dllimport) C();
+ virtual void f();
+@}
-@cindex @code{target_clones (string,...)} loongarch function attribute target_clones
-@item target_clones (string,...)
+__declspec(dllexport)
+C::C() @{@}
+@end smallexample
-Like attribute @code{target}, these options also reflect the behavior of
-similar command line options.
+@noindent
+In this code, @code{C::C} is exported from the current DLL, but the
+virtual table for @code{C} is not exported. (You can use
+@code{__attribute__} instead of @code{__declspec} if you prefer, but
+most Symbian OS code uses @code{__declspec}.)
-@code{string} can take the following values:
+@end table
-@itemize @bullet
-@item default
-@item strict-align
-@item arch=
-@item lsx
-@item lasx
-@item frecipe
-@item div32
-@item lam-bh
-@item lamcas
-@item scq
-@item ld-seq-sa
-@end itemize
-You can set the priority of attributes in target_clones (except @code{default}).
-For example:
+@node AVR Attributes
+@subsubsection AVR Attributes
-@smallexample
-__attribute__((target_clones ("default","arch=la64v1.1","lsx;priority=1")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+These attributes are supported by the AVR back end:
-The priority is from low to high:
-@itemize @bullet
-@item default
-@item arch=loongarch64
-@item strict-align
-@item frecipe = div32 = lam-bh = lamcas = scq = ld-seq-sa
-@item lsx
-@item arch=la64v1.0
-@item arch=la64v1.1
-@item lasx
-@end itemize
+@table @code
+@cindex @code{signal} function attribute, AVR
+@cindex @code{interrupt} function attribute, AVR
+@item signal
+@itemx interrupt
+The function is an interrupt service routine (ISR). The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when one of the attributes is present.
-Note that the option values on the gcc command line are not considered when
-calculating the priority.
+The AVR hardware globally disables interrupts when an interrupt is executed.
-If a priority is set for a feature in target_clones, then the priority of this
-feature will be higher than @code{lasx}.
+@itemize @bullet
+@item ISRs with the @code{signal} attribute do not re-enable interrupts.
+It is save to enable interrupts in a @code{signal} handler.
+This ``save'' only applies to the code
+generated by the compiler and not to the IRQ layout of the
+application which is responsibility of the application.
-For example:
+@item ISRs with the @code{interrupt} attribute re-enable interrupts.
+The first instruction of the routine is a @code{SEI} instruction to
+globally enable interrupts.
+@end itemize
-@smallexample
-__attribute__((target_clones ("default","arch=la64v1.1","lsx;priority=1")))
-int
-foo (int a)
+The recommended way to use these attributes is by means of the
+@code{ISR} macro provided by @code{avr/interrupt.h} from
+@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
+@example
+#include <avr/interrupt.h>
+
+ISR (INT0_vect) // Uses the "signal" attribute.
@{
- return a + 5;
+ // Code
@}
-@end smallexample
-In this test case, the priority of @code{lsx} is higher than that of
-@code{arch=la64v1.1}.
+ISR (ADC_vect, ISR_NOBLOCK) // Uses the "interrupt" attribute.
+@{
+ // Code
+@}
+@end example
-If the same priority is explicitly set for two features, the priority is still
-calculated according to the priority list above.
+When both @code{signal} and @code{interrupt} are specified for the same
+function, then @code{signal} is silently ignored.
-For example:
+@cindex @code{signal(@var{num})} function attribute, AVR
+@cindex @code{interrupt(@var{num})} function attribute, AVR
+@item signal(@var{num})
+@itemx interrupt(@var{num})
-@smallexample
-__attribute__((target_clones ("default","arch=la64v1.1;priority=1","lsx;priority=1")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-In this test case, the priority of @code{arch=la64v1.1;priority=1} is higher
-than that of @code{lsx;priority=1}.
-
-@cindex @code{target_version (string)} loongarch function attribute target_versions
-@item target_version (string)
-Support attributes and priorities are the same as @code{target_clones}.
-Note that this attribute requires GLIBC2.38 and newer that support HWCAP.
-
-For example:
-
-@code{test1.C}
-@smallexample
-__attribute__((target_clones ("default","arch=la64v1.1","lsx;priority=1")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
+Similar to the @code{signal} resp. @code{interrupt} attribute without
+argument, but the IRQ number is supplied as an argument @var{num} to
+the attribute, rather than providing the ISR name itself as the function name:
-@code{test2.C}
-@smallexample
-__attribute__((target_version ("default")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-__attribute__((target_version ("arch=la64v1.1")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-__attribute__((target_version ("lsx;priority=1")))
-int
-foo (int a)
+@example
+__attribute__((signal(1)))
+static void my_handler (void)
@{
- return a + 5;
+ // Code for __vector_1
@}
-@end smallexample
-The implementations of @code{test1.C} and @code{test2.C} are equivalent.
-@end table
-
-@node M32C Function Attributes
-@subsubsection M32C Function Attributes
-
-These function attributes are supported by the M32C back end:
-
-@table @code
-@cindex @code{bank_switch} function attribute, M32C
-@item bank_switch
-When added to an interrupt handler with the M32C port, causes the
-prologue and epilogue to use bank switching to preserve the registers
-rather than saving them on the stack.
-
-@cindex @code{fast_interrupt} function attribute, M32C
-@item fast_interrupt
-Use this attribute on the M32C port to indicate that the specified
-function is a fast interrupt handler. This is just like the
-@code{interrupt} attribute, except that @code{freit} is used to return
-instead of @code{reit}.
+@end example
-@cindex @code{function_vector} function attribute, M16C/M32C
-@item function_vector
-On M16C/M32C targets, the @code{function_vector} attribute declares a
-special page subroutine call function. Use of this attribute reduces
-the code size by 2 bytes for each call generated to the
-subroutine. The argument to the attribute is the vector number entry
-from the special page vector table which contains the 16 low-order
-bits of the subroutine's entry address. Each vector table has special
-page number (18 to 255) that is used in @code{jsrs} instructions.
-Jump addresses of the routines are generated by adding 0x0F0000 (in
-case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
-2-byte addresses set in the vector table. Therefore you need to ensure
-that all the special page vector routines should get mapped within the
-address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
-(for M32C).
+Notice that the handler function needs not to be externally visible.
+The recommended way to use these attributes is by means of the
+@code{ISR_N} macro provided by @code{avr/interrupt.h} from
+@w{@uref{https://avrdudes.github.io/avr-libc/avr-libc-user-manual/group__avr__interrupts.html,,AVR-LibC}}:
-In the following example 2 bytes are saved for each call to
-function @code{foo}.
+@example
+#include <avr/interrupt.h>
-@smallexample
-void foo (void) __attribute__((function_vector(0x18)));
-void foo (void)
+ISR_N (PCINT0_vect_num)
+static void my_pcint0_handler (void)
@{
+ // Code
@}
-void bar (void)
+ISR_N (ADC_vect_num, ISR_NOBLOCK)
+static void my_adc_handler (void)
@{
- foo();
+ // Code
@}
-@end smallexample
-
-If functions are defined in one file and are called in another file,
-then be sure to write this declaration in both files.
-
-This attribute is ignored for R8C target.
-
-@cindex @code{interrupt} function attribute, M32C
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
-
-@node M32R/D Function Attributes
-@subsubsection M32R/D Function Attributes
-
-These function attributes are supported by the M32R/D back end:
-
-@table @code
-@cindex @code{interrupt} function attribute, M32R/D
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-@cindex @code{model} function attribute, M32R/D
-@cindex function addressability on the M32R/D
-@item model (@var{model-name})
-
-On the M32R/D, use this attribute to set the addressability of an
-object, and of the code generated for a function. The identifier
-@var{model-name} is one of @code{small}, @code{medium}, or
-@code{large}, representing each of the code models.
-
-Small model objects live in the lower 16MB of memory (so that their
-addresses can be loaded with the @code{ld24} instruction), and are
-callable with the @code{bl} instruction.
-
-Medium model objects may live anywhere in the 32-bit address space (the
-compiler generates @code{seth/add3} instructions to load their addresses),
-and are callable with the @code{bl} instruction.
-
-Large model objects may live anywhere in the 32-bit address space (the
-compiler generates @code{seth/add3} instructions to load their addresses),
-and may not be reachable with the @code{bl} instruction (the compiler
-generates the much slower @code{seth/add3/jl} instruction sequence).
-@end table
-
-@node m68k Function Attributes
-@subsubsection m68k Function Attributes
-
-These function attributes are supported by the m68k back end:
+@end example
-@table @code
-@cindex @code{interrupt} function attribute, m68k
-@cindex @code{interrupt_handler} function attribute, m68k
-@item interrupt
-@itemx interrupt_handler
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present. Either name may be used.
+@code{ISR_N} can be specified more than once, in which case several
+interrupt vectors are pointing to the same handler function. This
+is similar to the @code{ISR_ALIASOF} macro provided by AVR-LibC, but
+without the overhead introduced by @code{ISR_ALIASOF}.
-@cindex @code{interrupt_thread} function attribute, fido
-@item interrupt_thread
-Use this attribute on fido, a subarchitecture of the m68k, to indicate
-that the specified function is an interrupt handler that is designed
-to run as a thread. The compiler omits generate prologue/epilogue
-sequences and replaces the return instruction with a @code{sleep}
-instruction. This attribute is available only on fido.
-@end table
-@node MCORE Function Attributes
-@subsubsection MCORE Function Attributes
+@cindex @code{noblock} function attribute, AVR
+@item noblock
-These function attributes are supported by the MCORE back end:
+This attribute can be used together with the @code{signal} attribute
+to indicate that an interrupt service routine should start with a @code{SEI}
+instruction to globally re-enable interrupts. Using attributes @code{signal}
+and @code{noblock} together has the same effect like using the @code{interrupt}
+attribute. Using the @code{noblock} attribute without @code{signal} has no
+effect.
-@table @code
-@cindex @code{naked} function attribute, MCORE
+@cindex @code{naked} function attribute, AVR
@item naked
This attribute allows the compiler to construct the
requisite function declaration, while allowing the body of the
(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported.
-@end table
-@node MicroBlaze Function Attributes
-@subsubsection MicroBlaze Function Attributes
-
-These function attributes are supported on MicroBlaze targets:
+@cindex @code{no_gccisr} function attribute, AVR
+@item no_gccisr
+Do not use the @code{__gcc_isr}
+@uref{https://sourceware.org/binutils/docs/as/AVR-Pseudo-Instructions.html,pseudo instruction}
+in a function with
+the @code{interrupt} or @code{signal} attribute aka. interrupt
+service routine (ISR).
+Use this attribute if the preamble of the ISR prologue should always read
+@example
+push __zero_reg__
+push __tmp_reg__
+in __tmp_reg__, __SREG__
+push __tmp_reg__
+clr __zero_reg__
+@end example
+and accordingly for the postamble of the epilogue --- no matter whether
+the mentioned registers are actually used in the ISR or not.
+Situations where you might want to use this attribute include:
+@itemize @bullet
+@item
+Code that (effectively) clobbers bits of @code{SREG} other than the
+@code{I}-flag by writing to the memory location of @code{SREG}.
+@item
+Code that uses inline assembler to jump to a different function which
+expects (parts of) the prologue code as outlined above to be present.
+@end itemize
+To disable @code{__gcc_isr} generation for the whole compilation unit,
+there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}.
-@table @code
-@cindex @code{save_volatiles} function attribute, MicroBlaze
-@item save_volatiles
-Use this attribute to indicate that the function is
-an interrupt handler. All volatile registers (in addition to non-volatile
-registers) are saved in the function prologue. If the function is a leaf
-function, only volatiles used by the function are saved. A normal function
-return is generated instead of a return from interrupt.
+@cindex @code{OS_main} function attribute, AVR
+@cindex @code{OS_task} function attribute, AVR
+@item OS_main
+@itemx OS_task
+On AVR, functions with the @code{OS_main} or @code{OS_task} attribute
+do not save/restore any call-saved register in their prologue/epilogue.
-@cindex @code{break_handler} function attribute, MicroBlaze
-@cindex break handler functions
-@item break_handler
-Use this attribute to indicate that
-the specified function is a break handler. The compiler generates function
-entry and exit sequences suitable for use in an break handler when this
-attribute is present. The return from @code{break_handler} is done through
-the @code{rtbd} instead of @code{rtsd}.
+The @code{OS_main} attribute can be used when there @emph{is
+guarantee} that interrupts are disabled at the time when the function
+is entered. This saves resources when the stack pointer has to be
+changed to set up a frame for local variables.
-@smallexample
-void f () __attribute__ ((break_handler));
-@end smallexample
+The @code{OS_task} attribute can be used when there is @emph{no
+guarantee} that interrupts are disabled at that time when the function
+is entered like for, e@.g@. task functions in a multi-threading operating
+system. In that case, changing the stack pointer register is
+guarded by save/clear/restore of the global interrupt enable flag.
-@cindex @code{interrupt_handler} function attribute, MicroBlaze
-@cindex @code{fast_interrupt} function attribute, MicroBlaze
-@item interrupt_handler
-@itemx fast_interrupt
-These attributes indicate that the specified function is an interrupt
-handler. Use the @code{fast_interrupt} attribute to indicate handlers
-used in low-latency interrupt mode, and @code{interrupt_handler} for
-interrupts that do not use low-latency handlers. In both cases, GCC
-emits appropriate prologue code and generates a return from the handler
-using @code{rtid} instead of @code{rtsd}.
-@end table
-
-@node Microsoft Windows Function Attributes
-@subsubsection Microsoft Windows Function Attributes
-
-The following attributes are available on Microsoft Windows and Symbian OS
-targets.
-
-@table @code
-@cindex @code{dllexport} function attribute
-@cindex @code{__declspec(dllexport)}
-@item dllexport
-On Microsoft Windows targets and Symbian OS targets the
-@code{dllexport} attribute causes the compiler to provide a global
-pointer to a pointer in a DLL, so that it can be referenced with the
-@code{dllimport} attribute. On Microsoft Windows targets, the pointer
-name is formed by combining @code{_imp__} and the function or variable
-name.
+The differences to the @code{naked} function attribute are:
+@itemize @bullet
+@item @code{naked} functions do not have a return instruction whereas
+@code{OS_main} and @code{OS_task} functions have a @code{RET} or
+@code{RETI} return instruction.
+@item @code{naked} functions do not set up a frame for local variables
+or a frame pointer whereas @code{OS_main} and @code{OS_task} do this
+as needed.
+@end itemize
-You can use @code{__declspec(dllexport)} as a synonym for
-@code{__attribute__ ((dllexport))} for compatibility with other
-compilers.
+@cindex @code{progmem} variable attribute, AVR
+@item progmem
+The @code{progmem} variable attribute is used on the AVR to place read-only
+data in the non-volatile program memory (flash). The @code{progmem}
+attribute accomplishes this by putting respective variables into a
+section whose name starts with @code{.progmem}.
-On systems that support the @code{visibility} attribute, this
-attribute also implies ``default'' visibility. It is an error to
-explicitly specify any other visibility.
+This attribute works similar to the @code{section} attribute
+but adds additional checking.
-GCC's default behavior is to emit all inline functions with the
-@code{dllexport} attribute. Since this can cause object file-size bloat,
-you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
-ignore the attribute for inlined functions unless the
-@option{-fkeep-inline-functions} flag is used instead.
+@table @asis
+@item @bullet{} Ordinary AVR cores with 32 general purpose registers:
+@code{progmem} affects the location
+of the data but not how this data is accessed.
+In order to read data located with the @code{progmem} attribute
+(inline) assembler must be used.
+@smallexample
+/* Use custom macros from AVR-LibC */
+#include <avr/pgmspace.h>
-The attribute is ignored for undefined symbols.
+/* Locate var in flash memory */
+const int var[2] PROGMEM = @{ 1, 2 @};
-When applied to C++ classes, the attribute marks defined non-inlined
-member functions and static data members as exports. Static consts
-initialized in-class are not marked unless they are also defined
-out-of-class.
+int read_var (int i)
+@{
+ /* Access var[] by accessor macro from avr/pgmspace.h */
+ return (int) pgm_read_word (& var[i]);
+@}
+@end smallexample
-For Microsoft Windows targets there are alternative methods for
-including the symbol in the DLL's export table such as using a
-@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
-the @option{--export-all} linker flag.
+AVR is a Harvard architecture processor and data and read-only data
+normally resides in the data memory (RAM).
-@cindex @code{dllimport} function attribute
-@cindex @code{__declspec(dllimport)}
-@item dllimport
-On Microsoft Windows and Symbian OS targets, the @code{dllimport}
-attribute causes the compiler to reference a function or variable via
-a global pointer to a pointer that is set up by the DLL exporting the
-symbol. The attribute implies @code{extern}. On Microsoft Windows
-targets, the pointer name is formed by combining @code{_imp__} and the
-function or variable name.
+See also the @ref{AVR Named Address Spaces} section for
+an alternate way to locate and access data in flash memory.
-You can use @code{__declspec(dllimport)} as a synonym for
-@code{__attribute__ ((dllimport))} for compatibility with other
-compilers.
+@item @bullet{} AVR cores with flash memory visible in the RAM address range:
+On such devices, there is no need for attribute @code{progmem} or
+@ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
+Just use standard C / C++. The compiler will generate @code{LD*}
+instructions. As flash memory is visible in the RAM address range,
+and the default linker script does @emph{not} locate @code{.rodata} in
+RAM, no special features are needed in order not to waste RAM for
+read-only data or to read from flash. You might even get slightly better
+performance by
+avoiding @code{progmem} and @code{__flash}. This applies to devices from
+families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
+an overview.
-On systems that support the @code{visibility} attribute, this
-attribute also implies ``default'' visibility. It is an error to
-explicitly specify any other visibility.
+@item @bullet{} Reduced AVR Tiny cores like ATtiny40:
+The compiler adds @code{0x4000}
+to the addresses of objects and declarations in @code{progmem} and locates
+the objects in flash memory, namely in section @code{.progmem.data}.
+The offset is needed because the flash memory is visible in the RAM
+address space starting at address @code{0x4000}.
-Currently, the attribute is ignored for inlined functions. If the
-attribute is applied to a symbol @emph{definition}, an error is reported.
-If a symbol previously declared @code{dllimport} is later defined, the
-attribute is ignored in subsequent references, and a warning is emitted.
-The attribute is also overridden by a subsequent declaration as
-@code{dllexport}.
+Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
+no special functions or macros are needed.
-When applied to C++ classes, the attribute marks non-inlined
-member functions and static data members as imports. However, the
-attribute is ignored for virtual methods to allow creation of vtables
-using thunks.
+@smallexample
+/* var is located in flash memory */
+extern const int var[2] __attribute__((progmem));
-On the SH Symbian OS target the @code{dllimport} attribute also has
-another affect---it can cause the vtable and run-time type information
-for a class to be exported. This happens when the class has a
-dllimported constructor or a non-inline, non-pure virtual function
-and, for either of those two conditions, the class also has an inline
-constructor or destructor and has a key function that is defined in
-the current translation unit.
+int read_var (int i)
+@{
+ return var[i];
+@}
+@end smallexample
-For Microsoft Windows targets the use of the @code{dllimport}
-attribute on functions is not necessary, but provides a small
-performance benefit by eliminating a thunk in the DLL@. The use of the
-@code{dllimport} attribute on imported variables can be avoided by passing the
-@option{--enable-auto-import} switch to the GNU linker. As with
-functions, using the attribute for a variable eliminates a thunk in
-the DLL@.
+Please notice that on these devices, there is no need for @code{progmem}
+at all.
-One drawback to using this attribute is that a pointer to a
-@emph{variable} marked as @code{dllimport} cannot be used as a constant
-address. However, a pointer to a @emph{function} with the
-@code{dllimport} attribute can be used as a constant initializer; in
-this case, the address of a stub function in the import lib is
-referenced. On Microsoft Windows targets, the attribute can be disabled
-for functions by setting the @option{-mnop-fun-dllimport} flag.
@end table
-@node MIPS Function Attributes
-@subsubsection MIPS Function Attributes
+@cindex @code{io} variable attribute, AVR
+@item io
+@itemx io (@var{addr})
+Variables with the @code{io} attribute are used to address
+memory-mapped peripherals in the I/O address range.
+No memory is allocated.
+If an address is specified, the variable
+is assigned that address, and the value is interpreted as an
+address in the data address space.
+Example:
-These function attributes are supported by the MIPS back end:
+@smallexample
+volatile int porta __attribute__((io (__AVR_SFR_OFFSET__ + 0x2)));
+@end smallexample
-@table @code
-@cindex @code{interrupt} function attribute, MIPS
-@item interrupt
-Use this attribute to indicate that the specified function is an interrupt
-handler. The compiler generates function entry and exit sequences suitable
-for use in an interrupt handler when this attribute is present.
-An optional argument is supported for the interrupt attribute which allows
-the interrupt mode to be described. By default GCC assumes the external
-interrupt controller (EIC) mode is in use, this can be explicitly set using
-@code{eic}. When interrupts are non-masked then the requested Interrupt
-Priority Level (IPL) is copied to the current IPL which has the effect of only
-enabling higher priority interrupts. To use vectored interrupt mode use
-the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
-the behavior of the non-masked interrupt support and GCC will arrange to mask
-all interrupts from sw0 up to and including the specified interrupt vector.
+Otherwise, the variable is not assigned an address, but the
+compiler will still use @code{in} and @code{out} instructions where applicable,
+assuming some other module assigns an address in the I/O address range.
+Example:
-You can use the following attributes to modify the behavior
-of an interrupt handler:
-@table @code
-@cindex @code{use_shadow_register_set} function attribute, MIPS
-@item use_shadow_register_set
-Assume that the handler uses a shadow register set, instead of
-the main general-purpose registers. An optional argument @code{intstack} is
-supported to indicate that the shadow register set contains a valid stack
-pointer.
+@smallexample
+extern volatile int porta __attribute__((io));
+@end smallexample
-@cindex @code{keep_interrupts_masked} function attribute, MIPS
-@item keep_interrupts_masked
-Keep interrupts masked for the whole function. Without this attribute,
-GCC tries to reenable interrupts for as much of the function as it can.
+@cindex @code{io_low} variable attribute, AVR
+@item io_low
+@itemx io_low (@var{addr})
+This is like the @code{io} attribute, but additionally it informs the
+compiler that the object lies in the lower half of the I/O area,
+allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
+instructions.
-@cindex @code{use_debug_exception_return} function attribute, MIPS
-@item use_debug_exception_return
-Return using the @code{deret} instruction. Interrupt handlers that don't
-have this attribute return using @code{eret} instead.
-@end table
+@cindex @code{address} variable attribute, AVR
+@item address (@var{addr})
+Variables with the @code{address} attribute can be used to address
+memory-mapped peripherals that may lie outside the I/O address range.
+Just like with the @code{io} and @code{io_low} attributes, no memory is
+allocated.
-You can use any combination of these attributes, as shown below:
@smallexample
-void __attribute__ ((interrupt)) v0 ();
-void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
-void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
-void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- keep_interrupts_masked)) v4 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- use_debug_exception_return)) v5 ();
-void __attribute__ ((interrupt, keep_interrupts_masked,
- use_debug_exception_return)) v6 ();
-void __attribute__ ((interrupt, use_shadow_register_set,
- keep_interrupts_masked,
- use_debug_exception_return)) v7 ();
-void __attribute__ ((interrupt("eic"))) v8 ();
-void __attribute__ ((interrupt("vector=hw3"))) v9 ();
+volatile int porta __attribute__((address (0x600)));
@end smallexample
-@cindex indirect calls, MIPS
-@cindex @code{long_call} function attribute, MIPS
-@cindex @code{short_call} function attribute, MIPS
-@cindex @code{near} function attribute, MIPS
-@cindex @code{far} function attribute, MIPS
-@item long_call
-@itemx short_call
-@itemx near
-@itemx far
-These attributes specify how a particular function is called on MIPS@.
-The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
-command-line switch. The @code{long_call} and @code{far} attributes are
-synonyms, and cause the compiler to always call
-the function by first loading its address into a register, and then using
-the contents of that register. The @code{short_call} and @code{near}
-attributes are synonyms, and have the opposite
-effect; they specify that non-PIC calls should be made using the more
-efficient @code{jal} instruction.
+This attribute can also be used to define symbols in C/C++
+code which otherwise would require assembly, a linker description file
+or command-line options like @code{-Wl,--defsym,a_symbol=@var{value}}.
+For example,
+@smallexample
+int a_symbol __attribute__((weak, address (1234)));
+@end smallexample
+will be compiled to
+@smallexample
+.weak a_symbol
+a_symbol = 1234
+@end smallexample
-@cindex @code{mips16} function attribute, MIPS
-@cindex @code{nomips16} function attribute, MIPS
-@item mips16
-@itemx nomips16
+@cindex @code{absdata} variable attribute, AVR
+@item absdata
+Variables in static storage and with the @code{absdata} attribute can
+be accessed by the @code{LDS} and @code{STS} instructions which take
+absolute addresses.
-On MIPS targets, you can use the @code{mips16} and @code{nomips16}
-function attributes to locally select or turn off MIPS16 code generation.
-A function with the @code{mips16} attribute is emitted as MIPS16 code,
-while MIPS16 code generation is disabled for functions with the
-@code{nomips16} attribute. These attributes override the
-@option{-mips16} and @option{-mno-mips16} options on the command line
-(@pxref{MIPS Options}).
+@itemize @bullet
+@item
+This attribute is only supported for the reduced AVR Tiny core
+like ATtiny40.
-When compiling files containing mixed MIPS16 and non-MIPS16 code, the
-preprocessor symbol @code{__mips16} reflects the setting on the command line,
-not that within individual functions. Mixed MIPS16 and non-MIPS16 code
-may interact badly with some GCC extensions such as @code{__builtin_apply}
-(@pxref{Constructing Calls}).
+@item
+You must make sure that respective data is located in the
+address range @code{0x40}@dots{}@code{0xbf} accessible by
+@code{LDS} and @code{STS}. One way to achieve this as an
+appropriate linker description file.
-@cindex @code{micromips} function attribute
-@cindex @code{nomicromips} function attribute
-@item micromips, MIPS
-@itemx nomicromips, MIPS
+@item
+If the location does not fit the address range of @code{LDS}
+and @code{STS}, there is currently (Binutils 2.26) just an unspecific
+warning like
+@quotation
+@code{module.cc:(.text+0x1c): warning: internal error: out of range error}
+@end quotation
-On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
-function attributes to locally select or turn off microMIPS code generation.
-A function with the @code{micromips} attribute is emitted as microMIPS code,
-while microMIPS code generation is disabled for functions with the
-@code{nomicromips} attribute. These attributes override the
-@option{-mmicromips} and @option{-mno-micromips} options on the command line
-(@pxref{MIPS Options}).
+@end itemize
-When compiling files containing mixed microMIPS and non-microMIPS code, the
-preprocessor symbol @code{__mips_micromips} reflects the setting on the
-command line,
-not that within individual functions. Mixed microMIPS and non-microMIPS code
-may interact badly with some GCC extensions such as @code{__builtin_apply}
-(@pxref{Constructing Calls}).
+See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
-@cindex @code{nocompression} function attribute, MIPS
-@item nocompression
-On MIPS targets, you can use the @code{nocompression} function attribute
-to locally turn off MIPS16 and microMIPS code generation. This attribute
-overrides the @option{-mips16} and @option{-mmicromips} options on the
-command line (@pxref{MIPS Options}).
+@end table
-@cindex @code{use_hazard_barrier_return} function attribute, MIPS
-@item use_hazard_barrier_return
-This function attribute instructs the compiler to generate a hazard barrier
-return that clears all execution and instruction hazards while returning,
-instead of generating a normal return instruction.
+@node Blackfin Attributes
+@subsubsection Blackfin Attributes
-@item code_readable
-@cindex @code{code_readable} function attribute, MIPS
-For MIPS targets that support PC-relative addressing modes, this attribute
-can be used to control how an object is addressed. The attribute takes
-a single optional argument:
+These attributes are supported by the Blackfin back end:
-@table @samp
-@item no
-The function should not read the instruction stream as data.
-@item yes
-The function can read the instruction stream as data.
-@item pcrel
-The function can read the instruction stream in a pc-relative mode.
-@end table
+@table @code
-If there is no argument supplied, the default of @code{"yes"} applies.
+@cindex @code{exception_handler} function attribute
+@cindex exception handler functions, Blackfin
+@item exception_handler
+Use this attribute on the Blackfin to indicate that the specified function
+is an exception handler. The compiler generates function entry and
+exit sequences suitable for use in an exception handler when this
+attribute is present.
+
+@cindex @code{interrupt_handler} function attribute, Blackfin
+@item interrupt_handler
+Use this attribute to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present.
+
+@cindex @code{kspisusp} function attribute, Blackfin
+@cindex User stack pointer in interrupts on the Blackfin
+@item kspisusp
+When used together with @code{interrupt_handler}, @code{exception_handler}
+or @code{nmi_handler}, code is generated to load the stack pointer
+from the USP register in the function prologue.
+
+@cindex @code{l1_text} function attribute, Blackfin
+@item l1_text
+This attribute specifies a function to be placed into L1 Instruction
+SRAM@. The function is put into a specific section named @code{.l1.text}.
+With @option{-mfdpic}, function calls with a such function as the callee
+or caller uses inlined PLT.
+
+@cindex @code{l2} attribute, Blackfin
+@item l2
+This attribute specifies a function or variable to be placed into L2
+SRAM.
+
+Functions with this attribute are put into a specific section named
+@code{.l2.text}. With @option{-mfdpic}, callers of such functions use
+an inlined PLT.
+
+Variables with @code{l2} attribute are put into the specific section
+named @code{.l2.data}.
+
+@cindex indirect calls, Blackfin
+@cindex @code{longcall} function attribute, Blackfin
+@cindex @code{shortcall} function attribute, Blackfin
+@item longcall
+@itemx shortcall
+The @code{longcall} attribute
+indicates that the function might be far away from the call site and
+require a different (more expensive) calling sequence. The
+@code{shortcall} attribute indicates that the function is always close
+enough for the shorter calling sequence to be used. These attributes
+override the @option{-mlongcall} switch.
+
+@cindex @code{nesting} function attribute, Blackfin
+@cindex Allow nesting in an interrupt handler on the Blackfin processor
+@item nesting
+Use this attribute together with @code{interrupt_handler},
+@code{exception_handler} or @code{nmi_handler} to indicate that the function
+entry code should enable nested interrupts or exceptions.
+
+@cindex @code{nmi_handler} function attribute, Blackfin
+@cindex NMI handler functions on the Blackfin processor
+@item nmi_handler
+Use this attribute on the Blackfin to indicate that the specified function
+is an NMI handler. The compiler generates function entry and
+exit sequences suitable for use in an NMI handler when this
+attribute is present.
+
+@cindex @code{saveall} function attribute, Blackfin
+@cindex save all registers on the Blackfin
+@item saveall
+Use this attribute to indicate that
+all registers except the stack pointer should be saved in the prologue
+regardless of whether they are used or not.
+
+@cindex @code{l1_data} variable attribute, Blackfin
+@cindex @code{l1_data_A} variable attribute, Blackfin
+@cindex @code{l1_data_B} variable attribute, Blackfin
+@item l1_data
+@itemx l1_data_A
+@itemx l1_data_B
+This attribute applies to variable declarations.
+Use these attributes on the Blackfin to place the
+variable into L1 Data SRAM.
+Variables with @code{l1_data} attribute are put into the specific section
+named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
+the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
+attribute are put into the specific section named @code{.l1.data.B}.
@end table
-@node MSP430 Function Attributes
-@subsubsection MSP430 Function Attributes
+@node BPF Attributes
+@subsubsection BPF Attributes
-These function attributes are supported by the MSP430 back end:
+These attributes are supported by the BPF back end:
@table @code
-@cindex @code{critical} function attribute, MSP430
-@item critical
-Critical functions disable interrupts upon entry and restore the
-previous interrupt state upon exit. Critical functions cannot also
-have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
+@cindex @code{kernel helper}, function attribute, BPF
+@item kernel_helper
+Use this attribute to indicate the specified function declaration is a
+kernel helper. The helper function is passed as an argument to the
+attribute. Example:
-The MSP430 hardware ensures that interrupts are disabled on entry to
-@code{interrupt} functions, and restores the previous interrupt state
-on exit. The @code{critical} attribute is therefore redundant on
-@code{interrupt} functions.
+@smallexample
+int bpf_probe_read (void *dst, int size, const void *unsafe_ptr)
+ __attribute__ ((kernel_helper (4)));
+@end smallexample
-@cindex @code{interrupt} function attribute, MSP430
+@cindex @code{naked} function attribute, BPF
+@item naked
+This attribute allows the compiler to construct the requisite function
+declaration, while allowing the body of the function to be assembly
+code. The specified function will not have prologue/epilogue
+sequences generated by the compiler. Only basic @code{asm} statements
+can safely be included in naked functions (@pxref{Basic Asm}). While
+using extended @code{asm} or a mixture of basic @code{asm} and C code
+may appear to work, they cannot be depended upon to work reliably and
+are not supported.
+
+@cindex @code{preserve_access_index} type attribute, BPF
+@item preserve_access_index
+Type attribute for BPF Compile Once - Run Everywhere (CO-RE) support.
+When attached to a
+@code{struct} or @code{union} type definition, indicates that CO-RE
+relocation information should be generated for any access to a variable
+of that type. The behavior is equivalent to the programmer manually
+wrapping every such access with @code{__builtin_preserve_access_index}.
+@end table
+
+@node C-SKY Attributes
+@subsubsection C-SKY Attributes
+
+These function attributes are supported by the C-SKY back end:
+
+@table @code
+@cindex @code{interrupt} function attribute, C-SKY
+@cindex @code{isr} function attribute, C-SKY
@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
+@itemx isr
+Use these attributes to indicate that the specified function
+is an interrupt handler.
+The compiler generates function entry and exit sequences suitable for
+use in an interrupt handler when either of these attributes are present.
-You can provide an argument to the interrupt
-attribute which specifies a name or number. If the argument is a
-number it indicates the slot in the interrupt vector table (0 - 31) to
-which this handler should be assigned. If the argument is a name it
-is treated as a symbolic name for the vector slot. These names should
-match up with appropriate entries in the linker script. By default
-the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
-@code{reset} for vector 31 are recognized.
+Use of these options requires the @option{-mistack} command-line option
+to enable support for the necessary interrupt stack instructions. They
+are ignored with a warning otherwise. @xref{C-SKY Options}.
-@cindex @code{naked} function attribute, MSP430
+@cindex @code{naked} function attribute, C-SKY
@item naked
This attribute allows the compiler to construct the
requisite function declaration, while allowing the body of the
(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
basic @code{asm} and C code may appear to work, they cannot be
depended upon to work reliably and are not supported.
+@end table
-@cindex @code{reentrant} function attribute, MSP430
-@item reentrant
-Reentrant functions disable interrupts upon entry and enable them
-upon exit. Reentrant functions cannot also have the @code{naked}
-or @code{critical} attributes. They can have the @code{interrupt}
-attribute.
-@cindex @code{wakeup} function attribute, MSP430
-@item wakeup
-This attribute only applies to interrupt functions. It is silently
-ignored if applied to a non-interrupt function. A wakeup interrupt
-function will rouse the processor from any low-power state that it
-might be in when the function exits.
+@node Epiphany Attributes
+@subsubsection Epiphany Attributes
-@cindex @code{lower} function attribute, MSP430
-@cindex @code{upper} function attribute, MSP430
-@cindex @code{either} function attribute, MSP430
-@item lower
-@itemx upper
-@itemx either
-On the MSP430 target these attributes can be used to specify whether
-the function or variable should be placed into low memory, high
-memory, or the placement should be left to the linker to decide. The
-attributes are only significant if compiling for the MSP430X
-architecture in the large memory model.
-
-The attributes work in conjunction with a linker script that has been
-augmented to specify where to place sections with a @code{.lower} and
-a @code{.upper} prefix. So, for example, as well as placing the
-@code{.data} section, the script also specifies the placement of a
-@code{.lower.data} and a @code{.upper.data} section. The intention
-is that @code{lower} sections are placed into a small but easier to
-access memory region and the upper sections are placed into a larger, but
-slower to access, region.
-
-The @code{either} attribute is special. It tells the linker to place
-the object into the corresponding @code{lower} section if there is
-room for it. If there is insufficient room then the object is placed
-into the corresponding @code{upper} section instead. Note that the
-placement algorithm is not very sophisticated. It does not attempt to
-find an optimal packing of the @code{lower} sections. It just makes
-one pass over the objects and does the best that it can. Using the
-@option{-ffunction-sections} and @option{-fdata-sections} command-line
-options can help the packing, however, since they produce smaller,
-easier to pack regions.
-@end table
-
-@node NDS32 Function Attributes
-@subsubsection NDS32 Function Attributes
-
-These function attributes are supported by the NDS32 back end:
+These function attributes are supported by the Epiphany back end:
@table @code
-@cindex @code{exception} function attribute
-@cindex exception handler functions, NDS32
-@item exception
-Use this attribute on the NDS32 target to indicate that the specified function
-is an exception handler. The compiler will generate corresponding sections
-for use in an exception handler.
+@cindex @code{disinterrupt} function attribute, Epiphany
+@item disinterrupt
+This attribute causes the compiler to emit
+instructions to disable interrupts for the duration of the given
+function.
-@cindex @code{interrupt} function attribute, NDS32
+@cindex @code{forwarder_section} function attribute, Epiphany
+@item forwarder_section
+This attribute modifies the behavior of an interrupt handler.
+The interrupt handler may be in external memory which cannot be
+reached by a branch instruction, so generate a local memory trampoline
+to transfer control. The single parameter identifies the section where
+the trampoline is placed.
+
+@cindex @code{interrupt} function attribute, Epiphany
@item interrupt
-On NDS32 target, this attribute indicates that the specified function
-is an interrupt handler. The compiler generates corresponding sections
-for use in an interrupt handler. You can use the following attributes
-to modify the behavior:
-@table @code
-@cindex @code{nested} function attribute, NDS32
-@item nested
-This interrupt service routine is interruptible.
-@cindex @code{not_nested} function attribute, NDS32
-@item not_nested
-This interrupt service routine is not interruptible.
-@cindex @code{nested_ready} function attribute, NDS32
-@item nested_ready
-This interrupt service routine is interruptible after @code{PSW.GIE}
-(global interrupt enable) is set. This allows interrupt service routine to
-finish some short critical code before enabling interrupts.
-@cindex @code{save_all} function attribute, NDS32
-@item save_all
-The system will help save all registers into stack before entering
-interrupt handler.
-@cindex @code{partial_save} function attribute, NDS32
-@item partial_save
-The system will help save caller registers into stack before entering
-interrupt handler.
-@end table
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present. It may also generate
+a special section with code to initialize the interrupt vector table.
-@cindex @code{naked} function attribute, NDS32
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
+On Epiphany targets one or more optional parameters can be added like this:
-@cindex @code{reset} function attribute, NDS32
-@cindex reset handler functions
-@item reset
-Use this attribute on the NDS32 target to indicate that the specified function
-is a reset handler. The compiler will generate corresponding sections
-for use in a reset handler. You can use the following attributes
-to provide extra exception handling:
-@table @code
-@cindex @code{nmi} function attribute, NDS32
-@item nmi
-Provide a user-defined function to handle NMI exception.
-@cindex @code{warm} function attribute, NDS32
-@item warm
-Provide a user-defined function to handle warm reset exception.
-@end table
-@end table
+@smallexample
+void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler ();
+@end smallexample
-@node Nvidia PTX Function Attributes
-@subsubsection Nvidia PTX Function Attributes
+Permissible values for these parameters are: @w{@code{reset}},
+@w{@code{software_exception}}, @w{@code{page_miss}},
+@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}},
+@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}.
+Multiple parameters indicate that multiple entries in the interrupt
+vector table should be initialized for this function, i.e.@: for each
+parameter @w{@var{name}}, a jump to the function is emitted in
+the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted
+entirely, in which case no interrupt vector table entry is provided.
-These function attributes are supported by the Nvidia PTX back end:
+Note that interrupts are enabled inside the function
+unless the @code{disinterrupt} attribute is also specified.
-@table @code
-@cindex @code{kernel} function attribute, Nvidia PTX
-@item kernel
-This attribute indicates that the corresponding function should be compiled
-as a kernel function, which can be invoked from the host via the CUDA RT
-library.
-By default functions are only callable only from other PTX functions.
+The following examples are all valid uses of these attributes on
+Epiphany targets:
+@smallexample
+void __attribute__ ((interrupt)) universal_handler ();
+void __attribute__ ((interrupt ("dma1"))) dma1_handler ();
+void __attribute__ ((interrupt ("dma0, dma1")))
+ universal_dma_handler ();
+void __attribute__ ((interrupt ("timer0"), disinterrupt))
+ fast_timer_handler ();
+void __attribute__ ((interrupt ("dma0, dma1"),
+ forwarder_section ("tramp")))
+ external_dma_handler ();
+@end smallexample
-Kernel functions must have @code{void} return type.
+@cindex @code{long_call} function attribute, Epiphany
+@cindex @code{short_call} function attribute, Epiphany
+@cindex indirect calls, Epiphany
+@item long_call
+@itemx short_call
+These attributes specify how a particular function is called.
+These attributes override the
+@option{-mlong-calls} (@pxref{Adapteva Epiphany Options})
+command-line switch and @code{#pragma long_calls} settings.
@end table
-@node PowerPC Function Attributes
-@subsubsection PowerPC Function Attributes
-
-These function attributes are supported by the PowerPC back end:
-
-@table @code
-@cindex indirect calls, PowerPC
-@cindex @code{longcall} function attribute, PowerPC
-@cindex @code{shortcall} function attribute, PowerPC
-@item longcall
-@itemx shortcall
-The @code{longcall} attribute
-indicates that the function might be far away from the call site and
-require a different (more expensive) calling sequence. The
-@code{shortcall} attribute indicates that the function is always close
-enough for the shorter calling sequence to be used. These attributes
-override both the @option{-mlongcall} switch and
-the @code{#pragma longcall} setting.
-
-@xref{RS/6000 and PowerPC Options}, for more information on whether long
-calls are necessary.
-
-@cindex @code{target} function attribute
-@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On the PowerPC, the following options are allowed:
-
-@table @samp
-@cindex @code{target("altivec")} function attribute, PowerPC
-@item altivec
-@itemx no-altivec
-Generate code that uses (does not use) AltiVec instructions. In
-32-bit code, you cannot enable AltiVec instructions unless
-@option{-mabi=altivec} is used on the command line.
-
-@cindex @code{target("cmpb")} function attribute, PowerPC
-@item cmpb
-@itemx no-cmpb
-Generate code that uses (does not use) the compare bytes instruction
-implemented on the POWER6 processor and other processors that support
-the PowerPC V2.05 architecture.
-
-@cindex @code{target("dlmzb")} function attribute, PowerPC
-@item dlmzb
-@itemx no-dlmzb
-Generate code that uses (does not use) the string-search @samp{dlmzb}
-instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
-generated by default when targeting those processors.
-
-@cindex @code{target("fprnd")} function attribute, PowerPC
-@item fprnd
-@itemx no-fprnd
-Generate code that uses (does not use) the FP round to integer
-instructions implemented on the POWER5+ processor and other processors
-that support the PowerPC V2.03 architecture.
-
-@cindex @code{target("hard-dfp")} function attribute, PowerPC
-@item hard-dfp
-@itemx no-hard-dfp
-Generate code that uses (does not use) the decimal floating-point
-instructions implemented on some POWER processors.
-
-@cindex @code{target("isel")} function attribute, PowerPC
-@item isel
-@itemx no-isel
-Generate code that uses (does not use) ISEL instruction.
-
-@cindex @code{target("mfcrf")} function attribute, PowerPC
-@item mfcrf
-@itemx no-mfcrf
-Generate code that uses (does not use) the move from condition
-register field instruction implemented on the POWER4 processor and
-other processors that support the PowerPC V2.01 architecture.
-
-@cindex @code{target("mulhw")} function attribute, PowerPC
-@item mulhw
-@itemx no-mulhw
-Generate code that uses (does not use) the half-word multiply and
-multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
-These instructions are generated by default when targeting those
-processors.
-
-@cindex @code{target("multiple")} function attribute, PowerPC
-@item multiple
-@itemx no-multiple
-Generate code that uses (does not use) the load multiple word
-instructions and the store multiple word instructions.
-@cindex @code{target("update")} function attribute, PowerPC
-@item update
-@itemx no-update
-Generate code that uses (does not use) the load or store instructions
-that update the base register to the address of the calculated memory
-location.
+@node H8/300 Attributes
+@subsubsection H8/300 Attributes
-@cindex @code{target("popcntb")} function attribute, PowerPC
-@item popcntb
-@itemx no-popcntb
-Generate code that uses (does not use) the popcount and double-precision
-FP reciprocal estimate instruction implemented on the POWER5
-processor and other processors that support the PowerPC V2.02
-architecture.
-
-@cindex @code{target("popcntd")} function attribute, PowerPC
-@item popcntd
-@itemx no-popcntd
-Generate code that uses (does not use) the popcount instruction
-implemented on the POWER7 processor and other processors that support
-the PowerPC V2.06 architecture.
-
-@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
-@item powerpc-gfxopt
-@itemx no-powerpc-gfxopt
-Generate code that uses (does not use) the optional PowerPC
-architecture instructions in the Graphics group, including
-floating-point select.
-
-@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
-@item powerpc-gpopt
-@itemx no-powerpc-gpopt
-Generate code that uses (does not use) the optional PowerPC
-architecture instructions in the General Purpose group, including
-floating-point square root.
-
-@cindex @code{target("recip-precision")} function attribute, PowerPC
-@item recip-precision
-@itemx no-recip-precision
-Assume (do not assume) that the reciprocal estimate instructions
-provide higher-precision estimates than is mandated by the PowerPC
-ABI.
-
-@cindex @code{target("string")} function attribute, PowerPC
-@item string
-@itemx no-string
-Generate code that uses (does not use) the load string instructions
-and the store string word instructions to save multiple registers and
-do small block moves.
-
-@cindex @code{target("vsx")} function attribute, PowerPC
-@item vsx
-@itemx no-vsx
-Generate code that uses (does not use) vector/scalar (VSX)
-instructions, and also enable the use of built-in functions that allow
-more direct access to the VSX instruction set. In 32-bit code, you
-cannot enable VSX or AltiVec instructions unless
-@option{-mabi=altivec} is used on the command line.
-
-@cindex @code{target("friz")} function attribute, PowerPC
-@item friz
-@itemx no-friz
-Generate (do not generate) the @code{friz} instruction when the
-@option{-funsafe-math-optimizations} option is used to optimize
-rounding a floating-point value to 64-bit integer and back to floating
-point. The @code{friz} instruction does not return the same value if
-the floating-point number is too large to fit in an integer.
-
-@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
-@item avoid-indexed-addresses
-@itemx no-avoid-indexed-addresses
-Generate code that tries to avoid (not avoid) the use of indexed load
-or store instructions.
-
-@cindex @code{target("paired")} function attribute, PowerPC
-@item paired
-@itemx no-paired
-Generate code that uses (does not use) the generation of PAIRED simd
-instructions.
-
-@cindex @code{target("longcall")} function attribute, PowerPC
-@item longcall
-@itemx no-longcall
-Generate code that assumes (does not assume) that all calls are far
-away so that a longer more expensive calling sequence is required.
-
-@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
-@item cpu=@var{CPU}
-Specify the architecture to generate code for when compiling the
-function. If you select the @code{target("cpu=power7")} attribute when
-generating 32-bit code, VSX and AltiVec instructions are not generated
-unless you use the @option{-mabi=altivec} option on the command line.
-
-@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
-@item tune=@var{TUNE}
-Specify the architecture to tune for when compiling the function. If
-you do not specify the @code{target("tune=@var{TUNE}")} attribute and
-you do specify the @code{target("cpu=@var{CPU}")} attribute,
-compilation tunes for the @var{CPU} architecture, and not the
-default tuning specified on the command line.
-@end table
-
-On the PowerPC, the inliner does not inline a
-function that has different target options than the caller, unless the
-callee has a subset of the target options of the caller.
-@end table
-
-@node RISC-V Function Attributes
-@subsubsection RISC-V Function Attributes
-
-These function attributes are supported by the RISC-V back end:
-
-@table @code
-@cindex @code{naked} function attribute, RISC-V
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@cindex @code{interrupt} function attribute, RISC-V
-@item interrupt
-Use this attribute to indicate that the specified function is an interrupt
-handler. The compiler generates function entry and exit sequences suitable
-for use in an interrupt handler when this attribute is present.
-
-You can specify the kind of interrupt to be handled by adding an optional
-parameter to the interrupt attribute like this:
-
-@smallexample
-void f (void) __attribute__ ((interrupt ("supervisor")));
-@end smallexample
-
-Permissible values for this parameter are @code{supervisor},
-@code{machine}, and @code{rnmi}. If there is no parameter, then it
-defaults to @code{machine}.
-
-@cindex @code{riscv_vector_cc} function attribute, RISC-V
-@item riscv_vector_cc
-Use this attribute to force the function to use the vector calling
-convention variant.
-
-@smallexample
-void foo() __attribute__((riscv_vector_cc));
-[[riscv::vector_cc]] void foo(); // For C++11 and C23
-@end smallexample
-
-@end table
-
-The following target-specific function attributes are available for the
-RISC-V target. For the most part, these options mirror the behavior of
-similar command-line options (@pxref{RISC-V Options}), but on a
-per-function basis.
-
-@table @code
-@cindex @code{arch=} function attribute, RISC-V
-@item arch=
-Specifies the architecture version and architectural extensions to use
-for this function. The behavior and permissible arguments are the same as
-for the @option{-march=} command-line option, in addtion, it also support
-extension enablement list, a list of extension name and prefixed with @code{+},
-like @code{arch=+zba} means enable @code{zba} extension.
-Multiple extension can be enabled by separating them with a comma. For example:
-@code{arch=+zba,+zbb}.
-
-@cindex @code{tune=} function attribute, RISC-V
-@item tune=
-Specifies the core for which to tune the performance of this function.
-The behavior and permissible arguments are the same as for the @option{-mtune=}
-command-line option.
-
-@cindex @code{cpu=} function attribute, RISC-V
-@item cpu=
-Specifies the core for which to tune the performance of this function and also
-whose architectural features to use. The behavior and valid arguments are the
-same as for the @option{-mcpu=} command-line option.
-
-@cindex @code{max-vectorization} function attribute, RISC-V
-@item max-vectorization
-@itemx no-max-vectorization
-@code{max-vectorization} tells GCC's vectorizer to treat all vector
-loops as being more profitable than the original scalar loops when
-optimizing the current function. @code{no-max-vectorization} disables
-this behavior.
-This corresponds to the behavior of the command-line options
-@option{-mmax-vectorization} and @option{-mno-max-vectorization}.
-
-@end table
-
-The above target attributes can be specified as follows:
-
-@smallexample
-__attribute__((target("@var{attr-string}")))
-int
-f (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-where @code{@var{attr-string}} is one of the attribute strings specified above.
-
-Multiple target function attributes can be specified by separating them with
-a semicolon. For example:
-@smallexample
-__attribute__((target("arch=+zba,+zbb;tune=rocket")))
-int
-foo (int a)
-@{
- return a + 5;
-@}
-@end smallexample
-
-is valid and compiles function @code{foo} with @code{zba}
-and @code{zbb} extensions and tunes it for @code{rocket}.
-
-@node RL78 Function Attributes
-@subsubsection RL78 Function Attributes
-
-These function attributes are supported by the RL78 back end:
-
-@table @code
-@cindex @code{interrupt} function attribute, RL78
-@cindex @code{brk_interrupt} function attribute, RL78
-@item interrupt
-@itemx brk_interrupt
-These attributes indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-Use @code{brk_interrupt} instead of @code{interrupt} for
-handlers intended to be used with the @code{BRK} opcode (i.e.@: those
-that must end with @code{RETB} instead of @code{RETI}).
-
-@cindex @code{naked} function attribute, RL78
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-@end table
-
-@node RX Function Attributes
-@subsubsection RX Function Attributes
-
-These function attributes are supported by the RX back end:
+These attributes are available for H8/300 targets:
@table @code
-@cindex @code{fast_interrupt} function attribute, RX
-@item fast_interrupt
-Use this attribute on the RX port to indicate that the specified
-function is a fast interrupt handler. This is just like the
-@code{interrupt} attribute, except that @code{freit} is used to return
-instead of @code{reit}.
-
-@cindex @code{interrupt} function attribute, RX
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-
-On RX and RL78 targets, you may specify one or more vector numbers as arguments
-to the attribute, as well as naming an alternate table name.
-Parameters are handled sequentially, so one handler can be assigned to
-multiple entries in multiple tables. One may also pass the magic
-string @code{"$default"} which causes the function to be used for any
-unfilled slots in the current table.
-
-This example shows a simple assignment of a function to one vector in
-the default table (note that preprocessor macros may be used for
-chip-specific symbolic vector names):
-@smallexample
-void __attribute__ ((interrupt (5))) txd1_handler ();
-@end smallexample
-
-This example assigns a function to two slots in the default table
-(using preprocessor macros defined elsewhere) and makes it the default
-for the @code{dct} table:
-@smallexample
-void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
- txd1_handler ();
-@end smallexample
-
-@cindex @code{naked} function attribute, RX
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@cindex @code{vector} function attribute, RX
-@item vector
-This RX attribute is similar to the @code{interrupt} attribute, including its
-parameters, but does not make the function an interrupt-handler type
-function (i.e.@: it retains the normal C function calling ABI). See the
-@code{interrupt} attribute for a description of its arguments.
-@end table
-
-@node S/390 Function Attributes
-@subsubsection S/390 Function Attributes
-
-These function attributes are supported on the S/390:
-
-@table @code
-@cindex @code{hotpatch} function attribute, S/390
-@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
-
-On S/390 System z targets, you can use this function attribute to
-make GCC generate a ``hot-patching'' function prologue. If the
-@option{-mhotpatch=} command-line option is used at the same time,
-the @code{hotpatch} attribute takes precedence. The first of the
-two arguments specifies the number of halfwords to be added before
-the function label. A second argument can be used to specify the
-number of halfwords to be added after the function label. For
-both arguments the maximum allowed value is 1000000.
-
-If both arguments are zero, hotpatching is disabled.
-
-@cindex @code{target} function attribute
-@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On S/390, the following options are supported:
-
-@table @samp
-@item arch=
-@item tune=
-@item stack-guard=
-@item stack-size=
-@item branch-cost=
-@item warn-framesize=
-@item backchain
-@itemx no-backchain
-@item hard-dfp
-@itemx no-hard-dfp
-@item hard-float
-@itemx soft-float
-@item htm
-@itemx no-htm
-@item vx
-@itemx no-vx
-@item packed-stack
-@itemx no-packed-stack
-@item small-exec
-@itemx no-small-exec
-@item mvcle
-@itemx no-mvcle
-@item warn-dynamicstack
-@itemx no-warn-dynamicstack
-@end table
-
-The options work exactly like the S/390 specific command line
-options (without the prefix @option{-m}) except that they do not
-change any feature macros. For example,
-
-@smallexample
-@code{target("no-vx")}
-@end smallexample
-
-does not undefine the @code{__VEC__} macro.
-@end table
-
-@node SH Function Attributes
-@subsubsection SH Function Attributes
-
-These function attributes are supported on the SH family of processors:
-
-@table @code
-@cindex @code{function_vector} function attribute, SH
-@cindex calling functions through the function vector on SH2A
+@cindex @code{function_vector} function attribute, H8/300
@item function_vector
-On SH2A targets, this attribute declares a function to be called using the
-TBR relative addressing mode. The argument to this attribute is the entry
-number of the same function in a vector table containing all the TBR
-relative addressable functions. For correct operation the TBR must be setup
-accordingly to point to the start of the vector table before any functions with
-this attribute are invoked. Usually a good place to do the initialization is
-the startup routine. The TBR relative vector table can have at max 256 function
-entries. The jumps to these functions are generated using a SH2A specific,
-non delayed branch instruction JSR/N @@(disp8,TBR).
-
-In an application, for a function being called once, this attribute
-saves at least 8 bytes of code; and if other successive calls are being
-made to the same function, it saves 2 bytes of code per each of these
-calls.
-
-@cindex @code{interrupt_handler} function attribute, SH
-@item interrupt_handler
-Use this attribute to
-indicate that the specified function is an interrupt handler. The compiler
-generates function entry and exit sequences suitable for use in an
-interrupt handler when this attribute is present.
-
-@cindex @code{nosave_low_regs} function attribute, SH
-@item nosave_low_regs
-Use this attribute on SH targets to indicate that an @code{interrupt_handler}
-function should not save and restore registers R0..R7. This can be used on SH3*
-and SH4* targets that have a second R0..R7 register bank for non-reentrant
-interrupt handlers.
-
-@cindex @code{renesas} function attribute, SH
-@item renesas
-On SH targets this attribute specifies that the function or struct follows the
-Renesas ABI.
-
-@cindex @code{resbank} function attribute, SH
-@item resbank
-On the SH2A target, this attribute enables the high-speed register
-saving and restoration using a register bank for @code{interrupt_handler}
-routines. Saving to the bank is performed automatically after the CPU
-accepts an interrupt that uses a register bank.
-
-The nineteen 32-bit registers comprising general register R0 to R14,
-control register GBR, and system registers MACH, MACL, and PR and the
-vector table address offset are saved into a register bank. Register
-banks are stacked in first-in last-out (FILO) sequence. Restoration
-from the bank is executed by issuing a RESBANK instruction.
-
-@cindex @code{sp_switch} function attribute, SH
-@item sp_switch
-Use this attribute on the SH to indicate an @code{interrupt_handler}
-function should switch to an alternate stack. It expects a string
-argument that names a global variable holding the address of the
-alternate stack.
-
-@smallexample
-void *alt_stack;
-void f () __attribute__ ((interrupt_handler,
- sp_switch ("alt_stack")));
-@end smallexample
-
-@cindex @code{trap_exit} function attribute, SH
-@item trap_exit
-Use this attribute on the SH for an @code{interrupt_handler} to return using
-@code{trapa} instead of @code{rte}. This attribute expects an integer
-argument specifying the trap number to be used.
-
-@cindex @code{trapa_handler} function attribute, SH
-@item trapa_handler
-On SH targets this function attribute is similar to @code{interrupt_handler}
-but it does not save and restore all registers.
-@end table
-
-@node Symbian OS Function Attributes
-@subsubsection Symbian OS Function Attributes
-
-@xref{Microsoft Windows Function Attributes}, for discussion of the
-@code{dllexport} and @code{dllimport} attributes.
-
-@node V850 Function Attributes
-@subsubsection V850 Function Attributes
-
-The V850 back end supports these function attributes:
-
-@table @code
-@cindex @code{interrupt} function attribute, V850
-@cindex @code{interrupt_handler} function attribute, V850
-@item interrupt
-@itemx interrupt_handler
-Use these attributes to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when either attribute is present.
-@end table
-
-@node Visium Function Attributes
-@subsubsection Visium Function Attributes
-
-These function attributes are supported by the Visium back end:
-
-@table @code
-@cindex @code{interrupt} function attribute, Visium
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
-
-@node x86 Function Attributes
-@subsubsection x86 Function Attributes
-
-These function attributes are supported by the x86 back end:
-
-@table @code
-@cindex @code{cdecl} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@opindex mrtd
-@item cdecl
-On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
-assume that the calling function pops off the stack space used to
-pass arguments. This is
-useful to override the effects of the @option{-mrtd} switch.
-
-@cindex @code{fastcall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@item fastcall
-On x86-32 targets, the @code{fastcall} attribute causes the compiler to
-pass the first argument (if of integral type) in the register ECX and
-the second argument (if of integral type) in the register EDX@. Subsequent
-and other typed arguments are passed on the stack. The called function
-pops the arguments off the stack. If the number of arguments is variable all
-arguments are pushed on the stack.
-
-@cindex @code{thiscall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@item thiscall
-On x86-32 targets, the @code{thiscall} attribute causes the compiler to
-pass the first argument (if of integral type) in the register ECX.
-Subsequent and other typed arguments are passed on the stack. The called
-function pops the arguments off the stack.
-If the number of arguments is variable all arguments are pushed on the
-stack.
-The @code{thiscall} attribute is intended for C++ non-static member functions.
-As a GCC extension, this calling convention can be used for C functions
-and for static member methods.
-
-@cindex @code{ms_abi} function attribute, x86
-@cindex @code{sysv_abi} function attribute, x86
-@item ms_abi
-@itemx sysv_abi
-
-On 32-bit and 64-bit x86 targets, you can use an ABI attribute
-to indicate which calling convention should be used for a function. The
-@code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
-while the @code{sysv_abi} attribute tells the compiler to use the System V
-ELF ABI, which is used on GNU/Linux and other systems. The default is to use
-the Microsoft ABI when targeting Windows. On all other systems, the default
-is the System V ELF ABI.
-
-Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
-requires the @option{-maccumulate-outgoing-args} option.
-
-@cindex @code{callee_pop_aggregate_return} function attribute, x86
-@item callee_pop_aggregate_return (@var{number})
-
-On x86-32 targets, you can use this attribute to control how
-aggregates are returned in memory. If the caller is responsible for
-popping the hidden pointer together with the rest of the arguments, specify
-@var{number} equal to zero. If callee is responsible for popping the
-hidden pointer, specify @var{number} equal to one.
-
-The default x86-32 ABI assumes that the callee pops the
-stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
-the compiler assumes that the
-caller pops the stack for hidden pointer.
-
-@cindex @code{ms_hook_prologue} function attribute, x86
-@item ms_hook_prologue
-
-On 32-bit and 64-bit x86 targets, you can use
-this function attribute to make GCC generate the ``hot-patching'' function
-prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
-and newer.
-
-@cindex @code{naked} function attribute, x86
-@item naked
-This attribute allows the compiler to construct the
-requisite function declaration, while allowing the body of the
-function to be assembly code. The specified function will not have
-prologue/epilogue sequences generated by the compiler. Only basic
-@code{asm} statements can safely be included in naked functions
-(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
-basic @code{asm} and C code may appear to work, they cannot be
-depended upon to work reliably and are not supported.
-
-@cindex @code{regparm} function attribute, x86
-@cindex functions that are passed arguments in registers on x86-32
-@item regparm (@var{number})
-On x86-32 targets, the @code{regparm} attribute causes the compiler to
-pass arguments number one to @var{number} if they are of integral type
-in registers EAX, EDX, and ECX instead of on the stack. Functions that
-take a variable number of arguments continue to be passed all of their
-arguments on the stack.
-
-Beware that on some ELF systems this attribute is unsuitable for
-global functions in shared libraries with lazy binding (which is the
-default). Lazy binding sends the first call via resolving code in
-the loader, which might assume EAX, EDX and ECX can be clobbered, as
-per the standard calling conventions. Solaris 8 is affected by this.
-Systems with the GNU C Library version 2.1 or higher
-and FreeBSD are believed to be
-safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
-disabled with the linker or the loader if desired, to avoid the
-problem.)
-
-@cindex @code{sseregparm} function attribute, x86
-@item sseregparm
-On x86-32 targets with SSE support, the @code{sseregparm} attribute
-causes the compiler to pass up to 3 floating-point arguments in
-SSE registers instead of on the stack. Functions that take a
-variable number of arguments continue to pass all of their
-floating-point arguments on the stack.
-
-@cindex @code{force_align_arg_pointer} function attribute, x86
-@item force_align_arg_pointer
-On x86 targets, the @code{force_align_arg_pointer} attribute may be
-applied to individual function definitions, generating an alternate
-prologue and epilogue that realigns the run-time stack if necessary.
-This supports mixing legacy codes that run with a 4-byte aligned stack
-with modern codes that keep a 16-byte stack for SSE compatibility.
-
-@cindex @code{stdcall} function attribute, x86-32
-@cindex functions that pop the argument stack on x86-32
-@item stdcall
-On x86-32 targets, the @code{stdcall} attribute causes the compiler to
-assume that the called function pops off the stack space used to
-pass arguments, unless it takes a variable number of arguments.
-
-@cindex @code{no_callee_saved_registers} function attribute, x86
-@item no_callee_saved_registers
-Use this attribute to indicate that the specified function has no
-callee-saved registers. That is, all registers, except for stack and
-frame pointers, can be used as scratch registers. For example, this
-attribute can be used for a function called from the interrupt handler
-assembly stub which will preserve all registers and return from
-interrupt.
-
-@cindex @code{preserve_none} function attribute, x86
-@item preserve_none
-This attribute is similar to @code{no_callee_saved_registers}, except
-on x86-64, r12, r13, r14, r15, rdi and rsi registers are used for
-integer parameter passing and this calling convention is subject to
-change.
-
-@cindex @code{no_caller_saved_registers} function attribute, x86
-@item no_caller_saved_registers
-Use this attribute to indicate that the specified function has no
-caller-saved registers. That is, all registers are callee-saved. For
-example, this attribute can be used for a function called from an
-interrupt handler. The compiler generates proper function entry and
-exit sequences to save and restore any modified registers, except for
-the EFLAGS register. Since GCC doesn't preserve YMM nor ZMM registers,
-@code{no_caller_saved_registers} attribute can't be used on functions
-with AVX enabled. Note that MMX and x87 registers aren't preserved by
-@code{no_caller_saved_registers} attribute.
-
-@cindex @code{interrupt} function attribute, x86
-@item interrupt
-Use this attribute to indicate that the specified function is an
-interrupt handler or an exception handler (depending on parameters passed
-to the function, explained further). The compiler generates function
-entry and exit sequences suitable for use in an interrupt handler when
-this attribute is present. The @code{IRET} instruction, instead of the
-@code{RET} instruction, is used to return from interrupt handlers. All
-registers, except for the EFLAGS register which is restored by the
-@code{IRET} instruction, are preserved by the compiler. Since GCC
-doesn't preserve SSE, MMX nor x87 states, the GCC option
-@option{-mgeneral-regs-only} should be used to compile interrupt and
-exception handlers.
-
-Any interruptible-without-stack-switch code must be compiled with
-@option{-mno-red-zone} since interrupt handlers can and will, because
-of the hardware design, touch the red zone.
-
-An interrupt handler must be declared with a mandatory pointer
-argument:
-
-@smallexample
-struct interrupt_frame;
-
-__attribute__ ((interrupt))
-void
-f (struct interrupt_frame *frame)
-@{
-@}
-@end smallexample
-
-@noindent
-and you must define @code{struct interrupt_frame} as described in the
-processor's manual.
-
-Exception handlers differ from interrupt handlers because the system
-pushes an error code on the stack. An exception handler declaration is
-similar to that for an interrupt handler, but with a different mandatory
-function signature. The compiler arranges to pop the error code off the
-stack before the @code{IRET} instruction.
-
-@smallexample
-#ifdef __x86_64__
-typedef unsigned long long int uword_t;
-#else
-typedef unsigned int uword_t;
-#endif
-
-struct interrupt_frame;
-
-__attribute__ ((interrupt))
-void
-f (struct interrupt_frame *frame, uword_t error_code)
-@{
- ...
-@}
-@end smallexample
-
-Exception handlers should only be used for exceptions that push an error
-code; you should use an interrupt handler in other cases. The system
-will crash if the wrong kind of handler is used.
-
-@cindex @code{target} function attribute
-@item target (@var{options})
-As discussed in @ref{Common Function Attributes}, this attribute
-allows specification of target-specific compilation options.
-
-On the x86, the following options are allowed:
-@table @samp
-@cindex @code{target("3dnow")} function attribute, x86
-@item 3dnow
-@itemx no-3dnow
-Enable/disable the generation of the 3DNow!@: instructions.
-
-@cindex @code{target("3dnowa")} function attribute, x86
-@item 3dnowa
-@itemx no-3dnowa
-Enable/disable the generation of the enhanced 3DNow!@: instructions.
-
-@cindex @code{target("abm")} function attribute, x86
-@item abm
-@itemx no-abm
-Enable/disable the generation of the advanced bit instructions.
-
-@cindex @code{target("adx")} function attribute, x86
-@item adx
-@itemx no-adx
-Enable/disable the generation of the ADX instructions.
-
-@cindex @code{target("aes")} function attribute, x86
-@item aes
-@itemx no-aes
-Enable/disable the generation of the AES instructions.
-
-@cindex @code{target("avx")} function attribute, x86
-@item avx
-@itemx no-avx
-Enable/disable the generation of the AVX instructions.
-
-@cindex @code{target("avx2")} function attribute, x86
-@item avx2
-@itemx no-avx2
-Enable/disable the generation of the AVX2 instructions.
-
-@cindex @code{target("avx512bitalg")} function attribute, x86
-@item avx512bitalg
-@itemx no-avx512bitalg
-Enable/disable the generation of the AVX512BITALG instructions.
-
-@cindex @code{target("avx512bw")} function attribute, x86
-@item avx512bw
-@itemx no-avx512bw
-Enable/disable the generation of the AVX512BW instructions.
-
-@cindex @code{target("avx512cd")} function attribute, x86
-@item avx512cd
-@itemx no-avx512cd
-Enable/disable the generation of the AVX512CD instructions.
-
-@cindex @code{target("avx512dq")} function attribute, x86
-@item avx512dq
-@itemx no-avx512dq
-Enable/disable the generation of the AVX512DQ instructions.
-
-@cindex @code{target("avx512er")} function attribute, x86
-@item avx512er
-@itemx no-avx512er
-Enable/disable the generation of the AVX512ER instructions.
-
-@cindex @code{target("avx512f")} function attribute, x86
-@item avx512f
-@itemx no-avx512f
-Enable/disable the generation of the AVX512F instructions.
-
-@cindex @code{target("avx512ifma")} function attribute, x86
-@item avx512ifma
-@itemx no-avx512ifma
-Enable/disable the generation of the AVX512IFMA instructions.
-
-@cindex @code{target("avx512vbmi")} function attribute, x86
-@item avx512vbmi
-@itemx no-avx512vbmi
-Enable/disable the generation of the AVX512VBMI instructions.
-
-@cindex @code{target("avx512vbmi2")} function attribute, x86
-@item avx512vbmi2
-@itemx no-avx512vbmi2
-Enable/disable the generation of the AVX512VBMI2 instructions.
-
-@cindex @code{target("avx512vl")} function attribute, x86
-@item avx512vl
-@itemx no-avx512vl
-Enable/disable the generation of the AVX512VL instructions.
-
-@cindex @code{target("avx512vnni")} function attribute, x86
-@item avx512vnni
-@itemx no-avx512vnni
-Enable/disable the generation of the AVX512VNNI instructions.
-
-@cindex @code{target("avx512vpopcntdq")} function attribute, x86
-@item avx512vpopcntdq
-@itemx no-avx512vpopcntdq
-Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
-
-@cindex @code{target("bmi")} function attribute, x86
-@item bmi
-@itemx no-bmi
-Enable/disable the generation of the BMI instructions.
-
-@cindex @code{target("bmi2")} function attribute, x86
-@item bmi2
-@itemx no-bmi2
-Enable/disable the generation of the BMI2 instructions.
-
-@cindex @code{target("cldemote")} function attribute, x86
-@item cldemote
-@itemx no-cldemote
-Enable/disable the generation of the CLDEMOTE instructions.
-
-@cindex @code{target("clflushopt")} function attribute, x86
-@item clflushopt
-@itemx no-clflushopt
-Enable/disable the generation of the CLFLUSHOPT instructions.
-
-@cindex @code{target("clwb")} function attribute, x86
-@item clwb
-@itemx no-clwb
-Enable/disable the generation of the CLWB instructions.
-
-@cindex @code{target("clzero")} function attribute, x86
-@item clzero
-@itemx no-clzero
-Enable/disable the generation of the CLZERO instructions.
-
-@cindex @code{target("crc32")} function attribute, x86
-@item crc32
-@itemx no-crc32
-Enable/disable the generation of the CRC32 instructions.
-
-@cindex @code{target("cx16")} function attribute, x86
-@item cx16
-@itemx no-cx16
-Enable/disable the generation of the CMPXCHG16B instructions.
-
-@cindex @code{target("default")} function attribute, x86
-@item default
-@xref{Function Multiversioning}, where it is used to specify the
-default function version.
-
-@cindex @code{target("f16c")} function attribute, x86
-@item f16c
-@itemx no-f16c
-Enable/disable the generation of the F16C instructions.
-
-@cindex @code{target("fma")} function attribute, x86
-@item fma
-@itemx no-fma
-Enable/disable the generation of the FMA instructions.
-
-@cindex @code{target("fma4")} function attribute, x86
-@item fma4
-@itemx no-fma4
-Enable/disable the generation of the FMA4 instructions.
-
-@cindex @code{target("fsgsbase")} function attribute, x86
-@item fsgsbase
-@itemx no-fsgsbase
-Enable/disable the generation of the FSGSBASE instructions.
-
-@cindex @code{target("fxsr")} function attribute, x86
-@item fxsr
-@itemx no-fxsr
-Enable/disable the generation of the FXSR instructions.
-
-@cindex @code{target("gfni")} function attribute, x86
-@item gfni
-@itemx no-gfni
-Enable/disable the generation of the GFNI instructions.
-
-@cindex @code{target("hle")} function attribute, x86
-@item hle
-@itemx no-hle
-Enable/disable the generation of the HLE instruction prefixes.
-
-@cindex @code{target("lwp")} function attribute, x86
-@item lwp
-@itemx no-lwp
-Enable/disable the generation of the LWP instructions.
-
-@cindex @code{target("lzcnt")} function attribute, x86
-@item lzcnt
-@itemx no-lzcnt
-Enable/disable the generation of the LZCNT instructions.
-
-@cindex @code{target("mmx")} function attribute, x86
-@item mmx
-@itemx no-mmx
-Enable/disable the generation of the MMX instructions.
-
-@cindex @code{target("movbe")} function attribute, x86
-@item movbe
-@itemx no-movbe
-Enable/disable the generation of the MOVBE instructions.
-
-@cindex @code{target("movdir64b")} function attribute, x86
-@item movdir64b
-@itemx no-movdir64b
-Enable/disable the generation of the MOVDIR64B instructions.
-
-@cindex @code{target("movdiri")} function attribute, x86
-@item movdiri
-@itemx no-movdiri
-Enable/disable the generation of the MOVDIRI instructions.
-
-@cindex @code{target("mwait")} function attribute, x86
-@item mwait
-@itemx no-mwait
-Enable/disable the generation of the MWAIT and MONITOR instructions.
-
-@cindex @code{target("mwaitx")} function attribute, x86
-@item mwaitx
-@itemx no-mwaitx
-Enable/disable the generation of the MWAITX instructions.
-
-@cindex @code{target("pclmul")} function attribute, x86
-@item pclmul
-@itemx no-pclmul
-Enable/disable the generation of the PCLMUL instructions.
-
-@cindex @code{target("pconfig")} function attribute, x86
-@item pconfig
-@itemx no-pconfig
-Enable/disable the generation of the PCONFIG instructions.
-
-@cindex @code{target("pku")} function attribute, x86
-@item pku
-@itemx no-pku
-Enable/disable the generation of the PKU instructions.
-
-@cindex @code{target("popcnt")} function attribute, x86
-@item popcnt
-@itemx no-popcnt
-Enable/disable the generation of the POPCNT instruction.
-
-@cindex @code{target("prfchw")} function attribute, x86
-@item prfchw
-@itemx no-prfchw
-Enable/disable the generation of the PREFETCHW instruction.
-
-@cindex @code{target("ptwrite")} function attribute, x86
-@item ptwrite
-@itemx no-ptwrite
-Enable/disable the generation of the PTWRITE instructions.
-
-@cindex @code{target("rdpid")} function attribute, x86
-@item rdpid
-@itemx no-rdpid
-Enable/disable the generation of the RDPID instructions.
-
-@cindex @code{target("rdrnd")} function attribute, x86
-@item rdrnd
-@itemx no-rdrnd
-Enable/disable the generation of the RDRND instructions.
-
-@cindex @code{target("rdseed")} function attribute, x86
-@item rdseed
-@itemx no-rdseed
-Enable/disable the generation of the RDSEED instructions.
-
-@cindex @code{target("rtm")} function attribute, x86
-@item rtm
-@itemx no-rtm
-Enable/disable the generation of the RTM instructions.
-
-@cindex @code{target("sahf")} function attribute, x86
-@item sahf
-@itemx no-sahf
-Enable/disable the generation of the SAHF instructions.
-
-@cindex @code{target("sgx")} function attribute, x86
-@item sgx
-@itemx no-sgx
-Enable/disable the generation of the SGX instructions.
-
-@cindex @code{target("sha")} function attribute, x86
-@item sha
-@itemx no-sha
-Enable/disable the generation of the SHA instructions.
-
-@cindex @code{target("shstk")} function attribute, x86
-@item shstk
-@itemx no-shstk
-Enable/disable the shadow stack built-in functions from CET.
-
-@cindex @code{target("sse")} function attribute, x86
-@item sse
-@itemx no-sse
-Enable/disable the generation of the SSE instructions.
-
-@cindex @code{target("sse2")} function attribute, x86
-@item sse2
-@itemx no-sse2
-Enable/disable the generation of the SSE2 instructions.
-
-@cindex @code{target("sse3")} function attribute, x86
-@item sse3
-@itemx no-sse3
-Enable/disable the generation of the SSE3 instructions.
-
-@cindex @code{target("sse4")} function attribute, x86
-@item sse4
-@itemx no-sse4
-Enable/disable the generation of the SSE4 instructions (both SSE4.1
-and SSE4.2).
-
-@cindex @code{target("sse4.1")} function attribute, x86
-@item sse4.1
-@itemx no-sse4.1
-Enable/disable the generation of the SSE4.1 instructions.
-
-@cindex @code{target("sse4.2")} function attribute, x86
-@item sse4.2
-@itemx no-sse4.2
-Enable/disable the generation of the SSE4.2 instructions.
-
-@cindex @code{target("sse4a")} function attribute, x86
-@item sse4a
-@itemx no-sse4a
-Enable/disable the generation of the SSE4A instructions.
-
-@cindex @code{target("ssse3")} function attribute, x86
-@item ssse3
-@itemx no-ssse3
-Enable/disable the generation of the SSSE3 instructions.
-
-@cindex @code{target("tbm")} function attribute, x86
-@item tbm
-@itemx no-tbm
-Enable/disable the generation of the TBM instructions.
-
-@cindex @code{target("vaes")} function attribute, x86
-@item vaes
-@itemx no-vaes
-Enable/disable the generation of the VAES instructions.
-
-@cindex @code{target("vpclmulqdq")} function attribute, x86
-@item vpclmulqdq
-@itemx no-vpclmulqdq
-Enable/disable the generation of the VPCLMULQDQ instructions.
-
-@cindex @code{target("waitpkg")} function attribute, x86
-@item waitpkg
-@itemx no-waitpkg
-Enable/disable the generation of the WAITPKG instructions.
-
-@cindex @code{target("wbnoinvd")} function attribute, x86
-@item wbnoinvd
-@itemx no-wbnoinvd
-Enable/disable the generation of the WBNOINVD instructions.
-
-@cindex @code{target("xop")} function attribute, x86
-@item xop
-@itemx no-xop
-Enable/disable the generation of the XOP instructions.
-
-@cindex @code{target("xsave")} function attribute, x86
-@item xsave
-@itemx no-xsave
-Enable/disable the generation of the XSAVE instructions.
-
-@cindex @code{target("xsavec")} function attribute, x86
-@item xsavec
-@itemx no-xsavec
-Enable/disable the generation of the XSAVEC instructions.
-
-@cindex @code{target("xsaveopt")} function attribute, x86
-@item xsaveopt
-@itemx no-xsaveopt
-Enable/disable the generation of the XSAVEOPT instructions.
-
-@cindex @code{target("xsaves")} function attribute, x86
-@item xsaves
-@itemx no-xsaves
-Enable/disable the generation of the XSAVES instructions.
-
-@cindex @code{target("amx-tile")} function attribute, x86
-@item amx-tile
-@itemx no-amx-tile
-Enable/disable the generation of the AMX-TILE instructions.
-
-@cindex @code{target("amx-int8")} function attribute, x86
-@item amx-int8
-@itemx no-amx-int8
-Enable/disable the generation of the AMX-INT8 instructions.
-
-@cindex @code{target("amx-bf16")} function attribute, x86
-@item amx-bf16
-@itemx no-amx-bf16
-Enable/disable the generation of the AMX-BF16 instructions.
-
-@cindex @code{target("uintr")} function attribute, x86
-@item uintr
-@itemx no-uintr
-Enable/disable the generation of the UINTR instructions.
-
-@cindex @code{target("hreset")} function attribute, x86
-@item hreset
-@itemx no-hreset
-Enable/disable the generation of the HRESET instruction.
-
-@cindex @code{target("kl")} function attribute, x86
-@item kl
-@itemx no-kl
-Enable/disable the generation of the KEYLOCKER instructions.
-
-@cindex @code{target("widekl")} function attribute, x86
-@item widekl
-@itemx no-widekl
-Enable/disable the generation of the WIDEKL instructions.
-
-@cindex @code{target("avxvnni")} function attribute, x86
-@item avxvnni
-@itemx no-avxvnni
-Enable/disable the generation of the AVXVNNI instructions.
-
-@cindex @code{target("avxifma")} function attribute, x86
-@item avxifma
-@itemx no-avxifma
-Enable/disable the generation of the AVXIFMA instructions.
-
-@cindex @code{target("avxvnniint8")} function attribute, x86
-@item avxvnniint8
-@itemx no-avxvnniint8
-Enable/disable the generation of the AVXVNNIINT8 instructions.
-
-@cindex @code{target("avxneconvert")} function attribute, x86
-@item avxneconvert
-@itemx no-avxneconvert
-Enable/disable the generation of the AVXNECONVERT instructions.
-
-@cindex @code{target("cmpccxadd")} function attribute, x86
-@item cmpccxadd
-@itemx no-cmpccxadd
-Enable/disable the generation of the CMPccXADD instructions.
-
-@cindex @code{target("amx-fp16")} function attribute, x86
-@item amx-fp16
-@itemx no-amx-fp16
-Enable/disable the generation of the AMX-FP16 instructions.
-
-@cindex @code{target("prefetchi")} function attribute, x86
-@item prefetchi
-@itemx no-prefetchi
-Enable/disable the generation of the PREFETCHI instructions.
-
-@cindex @code{target("raoint")} function attribute, x86
-@item raoint
-@itemx no-raoint
-Enable/disable the generation of the RAOINT instructions.
-
-@cindex @code{target("amx-complex")} function attribute, x86
-@item amx-complex
-@itemx no-amx-complex
-Enable/disable the generation of the AMX-COMPLEX instructions.
-
-@cindex @code{target("avxvnniint16")} function attribute, x86
-@item avxvnniint16
-@itemx no-avxvnniint16
-Enable/disable the generation of the AVXVNNIINT16 instructions.
-
-@cindex @code{target("sm3")} function attribute, x86
-@item sm3
-@itemx no-sm3
-Enable/disable the generation of the SM3 instructions.
-
-@cindex @code{target("sha512")} function attribute, x86
-@item sha512
-@itemx no-sha512
-Enable/disable the generation of the SHA512 instructions.
-
-@cindex @code{target("sm4")} function attribute, x86
-@item sm4
-@itemx no-sm4
-Enable/disable the generation of the SM4 instructions.
-
-@cindex @code{target("usermsr")} function attribute, x86
-@item usermsr
-@itemx no-usermsr
-Enable/disable the generation of the USER_MSR instructions.
-
-@cindex @code{target("apxf")} function attribute, x86
-@item apxf
-@itemx no-apxf
-Enable/disable the generation of the APX features, including
-EGPR, PUSH2POP2, NDD and PPX.
-
-@cindex @code{target("avx10.1")} function attribute, x86
-@item avx10.1
-@itemx no-avx10.1
-Enable/Disable the generation of the AVX10.1 instructions.
-
-@cindex @code{target("avx10.2")} function attribute, x86
-@item avx10.2
-@itemx no-avx10.2
-Enable/Disable the generation of the AVX10.2 instructions.
-
-@cindex @code{target("amx-avx512")} function attribute, x86
-@item amx-avx512
-@itemx no-amx-avx512
-Enable/disable the generation of the AMX-AVX512 instructions.
-
-@cindex @code{target("amx-tf32")} function attribute, x86
-@item amx-tf32
-@itemx no-amx-tf32
-Enable/disable the generation of the AMX-TF32 instructions.
-
-@cindex @code{target("amx-fp8")} function attribute, x86
-@item amx-fp8
-@itemx no-amx-fp8
-Enable/disable the generation of the AMX-FP8 instructions.
-
-@cindex @code{target("movrs")} function attribute, x86
-@item movrs
-@itemx no-movrs
-Enable/disable the generation of the MOVRS instructions.
-
-@cindex @code{target("amx-movrs")} function attribute, x86
-@item amx-movrs
-@itemx no-amx-movrs
-Enable/disable the generation of the AMX-MOVRS instructions.
-
-@cindex @code{target("cld")} function attribute, x86
-@item cld
-@itemx no-cld
-Enable/disable the generation of the CLD before string moves.
+Use this attribute on the H8/300, H8/300H, and H8S to indicate
+that the specified function should be called through the function vector.
+Calling a function through the function vector reduces code size; however,
+the function vector has a limited size (maximum 128 entries on the H8/300
+and 64 entries on the H8/300H and H8S)
+and shares space with the interrupt vector.
-@cindex @code{target("fancy-math-387")} function attribute, x86
-@item fancy-math-387
-@itemx no-fancy-math-387
-Enable/disable the generation of the @code{sin}, @code{cos}, and
-@code{sqrt} instructions on the 387 floating-point unit.
+@cindex @code{interrupt_handler} function attribute, H8/300
+@item interrupt_handler
+Use this attribute on the H8/300, H8/300H, and H8S to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present.
-@cindex @code{target("ieee-fp")} function attribute, x86
-@item ieee-fp
-@itemx no-ieee-fp
-Enable/disable the generation of floating point that depends on IEEE arithmetic.
+@cindex @code{saveall} function attribute, H8/300
+@cindex save all registers on the H8/300, H8/300H, and H8S
+@item saveall
+Use this attribute on the H8/300, H8/300H, and H8S to indicate that
+all registers except the stack pointer should be saved in the prologue
+regardless of whether they are used or not.
-@cindex @code{target("inline-all-stringops")} function attribute, x86
-@item inline-all-stringops
-@itemx no-inline-all-stringops
-Enable/disable inlining of string operations.
+@cindex @code{monitor} function attribute, H8/300
+@item monitor
+Use this attribute to indicate a monitor function. It tells GCC
+to generate entry and exit sequences that disable interrupts during
+execution of the function.
-@cindex @code{target("inline-stringops-dynamically")} function attribute, x86
-@item inline-stringops-dynamically
-@itemx no-inline-stringops-dynamically
-Enable/disable the generation of the inline code to do small string
-operations and calling the library routines for large operations.
+@cindex @code{OS_Task} function attribute, H8/300
+@item OS_Task
+Use this attribute to disable the normal register and stack save and
+restore sequences on function entry and exit. The function epilogue
+generated by GCC includes only a return instruction.
-@cindex @code{target("align-stringops")} function attribute, x86
-@item align-stringops
-@itemx no-align-stringops
-Do/do not align destination of inlined string operations.
+@cindex @code{eightbit_data} variable attribute, H8/300
+@cindex eight-bit data on the H8/300, H8/300H, and H8S
+@item eightbit_data
+This attribute applies to variable declarations.
+Use this attribute on the H8/300, H8/300H, and H8S to indicate
+that the specified
+variable should be placed into the eight-bit data section.
+The compiler generates more efficient code for certain operations
+on data in the eight-bit data area. Note the eight-bit data area is limited to
+256 bytes of data.
-@cindex @code{target("recip")} function attribute, x86
-@item recip
-@itemx no-recip
-Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
-instructions followed an additional Newton-Raphson step instead of
-doing a floating-point division.
+@cindex @code{tiny_data} variable attribute, H8/300
+@cindex tiny data section on the H8/300H and H8S
+@item tiny_data
+This attribute applies to variable declarations.
+Use this attribute on the H8/300H and H8S to indicate that the specified
+variable should be placed into the tiny data section.
+The compiler generates more efficient code for loads and stores
+on data in the tiny data section. Note the tiny data area is limited to
+slightly under 32KB of data.
+@end table
-@cindex @code{target("80387")} function attribute, x86
-@item 80387
-@itemx no-80387
-Generate code containing 80387 instructions for floating point.
+@node IA-64 Attributes
+@subsubsection IA-64 Attributes
-@cindex @code{target("general-regs-only")} function attribute, x86
-@item general-regs-only
-Generate code which uses only the general registers.
+These attributes are supported on IA-64 targets:
-@cindex @code{target("arch=@var{ARCH}")} function attribute, x86
-@item arch=@var{ARCH}
-Specify the architecture to generate code for in compiling the function.
+@table @code
+@cindex @code{syscall_linkage} function attribute, IA-64
+@item syscall_linkage
+This attribute applies to functions.
+It is used to modify the IA-64 calling convention by marking
+all input registers as live at all function exits. This makes it possible
+to restart a system call after an interrupt without having to save/restore
+the input registers. This also prevents kernel data from leaking into
+application code.
-@cindex @code{target("tune=@var{TUNE}")} function attribute, x86
-@item tune=@var{TUNE}
-Specify the architecture to tune for in compiling the function.
+@cindex @code{version_id} attribute, IA-64
+@item version_id
+This IA-64 HP-UX attribute, attached to a global variable or function, renames a
+symbol to contain a version string, thus allowing for function level
+versioning. HP-UX system header files may use function level versioning
+for some system calls.
-@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
-@item fpmath=@var{FPMATH}
-Specify which floating-point unit to use. You must specify the
-@code{target("fpmath=sse,387")} option as
-@code{target("fpmath=sse+387")} because the comma would separate
-different options.
+@smallexample
+extern int foo () __attribute__((version_id ("20040821")));
+@end smallexample
-@cindex @code{prefer-vector-width} function attribute, x86
-@item prefer-vector-width=@var{OPT}
-On x86 targets, the @code{prefer-vector-width} attribute informs the
-compiler to use @var{OPT}-bit vector width in instructions
-instead of the default on the selected platform.
+@noindent
+Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}.
-Valid @var{OPT} values are:
+@cindex @code{model} variable attribute, IA-64
+@item model (@var{model-name})
+On IA-64, use this variable attribute to set the addressability of an object.
+At present, the only supported identifier for @var{model-name} is
+@code{small}, indicating addressability via ``small'' (22-bit)
+addresses (so that their addresses can be loaded with the @code{addl}
+instruction). Caveat: such addressing is by definition not position
+independent and hence this attribute must not be used for objects
+defined by shared libraries.
+@end table
-@table @samp
-@item none
-No extra limitations applied to GCC other than defined by the selected platform.
+@node LoongArch Attributes
+@subsubsection LoongArch Attributes
-@item 128
-Prefer 128-bit vector width for instructions.
+The following attributes are supported by LoongArch end:
-@item 256
-Prefer 256-bit vector width for instructions.
+@table @code
-@item 512
-Prefer 512-bit vector width for instructions.
-@end table
+@cindex @code{target (option,...)} loongarch function attribute target
+@item target (option,...)
-@end table
+The following target-specific function attributes are available for the
+LoongArch target. These options mirror the behavior of similar
+command-line options (@pxref{LoongArch Options}), but on a per-function basis.
-@cindex @code{indirect_branch} function attribute, x86
-@item indirect_branch("@var{choice}")
-On x86 targets, the @code{indirect_branch} attribute causes the compiler
-to convert indirect call and jump with @var{choice}. @samp{keep}
-keeps indirect call and jump unmodified. @samp{thunk} converts indirect
-call and jump to call and return thunk. @samp{thunk-inline} converts
-indirect call and jump to inlined call and return thunk.
-@samp{thunk-extern} converts indirect call and jump to external call
-and return thunk provided in a separate object file.
+@table @code
+@cindex @code{strict-align} function attribute, LoongArch
+@item strict-align
+@itemx no-strict-align
+@code{strict-align} indicates that the compiler should not assume that unaligned
+memory references are handled by the system. To allow the compiler to assume
+that aligned memory references are handled by the system, the inverse attribute
+@code{no-strict-align} can be specified. The behavior is same as for the
+command-line option @option{-mstrict-align} and @option{-mno-strict-align}.
-@cindex @code{function_return} function attribute, x86
-@item function_return("@var{choice}")
-On x86 targets, the @code{function_return} attribute causes the compiler
-to convert function return with @var{choice}. @samp{keep} keeps function
-return unmodified. @samp{thunk} converts function return to call and
-return thunk. @samp{thunk-inline} converts function return to inlined
-call and return thunk. @samp{thunk-extern} converts function return to
-external call and return thunk provided in a separate object file.
+@cindex @code{cmodel=} function attribute, LoongArch
+@item cmodel=
+Indicates that code should be generated for a particular code model for
+this function. The behavior and permissible arguments are the same as
+for the command-line option @option{-mcmodel=}.
-@cindex @code{nocf_check} function attribute
-@item nocf_check
-The @code{nocf_check} attribute on a function is used to inform the
-compiler that the function's prologue should not be instrumented when
-compiled with the @option{-fcf-protection=branch} option. The
-compiler assumes that the function's address is a valid target for a
-control-flow transfer.
+@cindex @code{arch=} function attribute, LoongArch
+@item arch=
+Specifies the architecture version and architectural extensions to use
+for this function. The behavior and permissible arguments are the same as
+for the @option{-march=} command-line option.
-The @code{nocf_check} attribute on a type of pointer to function is
-used to inform the compiler that a call through the pointer should
-not be instrumented when compiled with the
-@option{-fcf-protection=branch} option. The compiler assumes
-that the function's address from the pointer is a valid target for
-a control-flow transfer. A direct function call through a function
-name is assumed to be a safe call thus direct calls are not
-instrumented by the compiler.
+@cindex @code{tune=} function attribute, LoongArch
+@item tune=
+Specifies the core for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mtune=}
+command-line option.
-The @code{nocf_check} attribute is applied to an object's type.
-In case of assignment of a function address or a function pointer to
-another pointer, the attribute is not carried over from the right-hand
-object's type; the type of left-hand object stays unchanged. The
-compiler checks for @code{nocf_check} attribute mismatch and reports
-a warning in case of mismatch.
+@cindex @code{lsx} function attribute, LoongArch
+@item lsx
+@itemx no-lsx
+@code{lsx} indicates that vector instruction generation is allowed (not allowed)
+when compiling the function. The behavior is same as for the command-line option
+@option{-mlsx} and @option{-mno-lsx}.
+
+@cindex @code{lasx} function attribute, LoongArch
+@item lasx
+@itemx no-lasx
+@code{lasx} indicates that lasx instruction generation is allowed (not allowed)
+when compiling the function. The behavior is slightly different from the
+command-line option @option{-mno-lasx}.
+Example:
@smallexample
-int foo (void) __attribute__((nocf_check));
-void (*foo1)(void) __attribute__((nocf_check));
-void (*foo2)(void);
+test.c:
+typedef int v4i32 __attribute__ ((vector_size(16), aligned(16)));
-/* foo's address is assumed to be valid. */
-int
-foo (void)
+v4i32 a, b, c;
+#ifdef WITH_ATTR
+__attribute__ ((target("no-lasx"))) void
+#else
+void
+#endif
+test ()
@{
- /* This call site is not checked for control-flow
- validity. */
- (*foo1)();
+ c = a + b;
+@}
+@end smallexample
+@smallexample
+$ gcc test.c -o test.s -O2 -mlasx -DWITH_ATTR
+@end smallexample
+Compiled as above, 128-bit vectorization is possible.
+But the following method cannot perform 128-bit vectorization.
+@smallexample
+$ gcc test.c -o test.s -O2 -mlasx -mno-lasx
+@end smallexample
+
+@cindex @code{recipe} function attribute, LoongArch
+@item recipe
+@itemx no-recipe
+@code{recipe} indicates that frecipe.@{s/d@} and frsqrt.@{s/d@}instruction generation
+is allowed (not allowed) when compiling the function. The behavior is same as for
+the command-line option
+@option{-mrecipe} and @option{-mno-recipe}.
+
+@cindex @code{div32} function attribute, LoongArch
+@item div32
+@itemx no-div32
+@code{div32} determines whether div.w[u] and mod.w[u] instructions on 64-bit machines
+are evaluated based only on the lower 32 bits of the input registers.
+@option{-mdiv32} and @option{-mno-div32}.
- /* A warning is issued about attribute mismatch. */
- foo1 = foo2;
+@cindex @code{lam-bh} function attribute, LoongArch
+@item lam-bh
+@itemx no-lam-bh
+@code{lam-bh} indicates that am@{swap/add@}[_db].@{b/h@} instruction generation
+is allowed (not allowed) when compiling the function. The behavior is same as for
+the command-line option
+@option{-mlam-bh} and @option{-mno-lam-bh}.
- /* This call site is still not checked. */
- (*foo1)();
+@cindex @code{lamcas} function attribute, LoongArch
+@item lamcas
+@itemx no-lamcas
+@code{lamcas} indicates that amcas[_db].@{b/h/w/d@} instruction generation
+is allowed (not allowed) when compiling the function. The behavior is same as for
+the command-line option
+@option{-mlamcas} and @option{-mno-lamcas}.
- /* This call site is checked. */
- (*foo2)();
+@cindex @code{scq} function attribute, LoongArch
+@item scq
+@itemx no-scq
+@code{scq} indicates that sc.q instruction generation is allowed (not allowed) when
+compiling the function. The behavior is same as for the command-line option
+@option{-mscq} and @option{-mno-scq}.
- /* A warning is issued about attribute mismatch. */
- foo2 = foo1;
+@cindex @code{ld-seq-sa} function attribute, LoongArch
+@item ld-seq-sa
+@itemx no-ld-seq-sa
+@code{ld-seq-sa} indicates that whether need load-load barries (dbar 0x700)
+@option{-mld-seq-sa} and @option{-mno-ld-seq-sa}.
- /* This call site is still checked. */
- (*foo2)();
+@end table
- return 0;
+Multiple target function attributes can be specified by separating them with
+a comma. For example:
+
+@smallexample
+__attribute__((target("arch=la64v1.1,lasx")))
+int
+foo (int a)
+@{
+ return a + 5;
@}
@end smallexample
-@cindex @code{cf_check} function attribute, x86
-@item cf_check
+is valid and compiles function @code{foo} for LA64V1.1 with @code{lasx}.
-The @code{cf_check} attribute on a function is used to inform the
-compiler that ENDBR instruction should be placed at the function
-entry when @option{-fcf-protection=branch} is enabled.
+@subsubheading Inlining rules
+Specifying target attributes on individual functions or performing link-time
+optimization across translation units compiled with different target options
+can affect function inlining rules:
-@cindex @code{indirect_return} function attribute, x86
-@item indirect_return
+In particular, a caller function can inline a callee function only if the
+architectural features available to the callee are a subset of the features
+available to the caller.
-The @code{indirect_return} attribute can be applied to a function,
-as well as variable or type of function pointer to inform the
-compiler that the function may return via indirect branch.
+Note that when the callee function does not have the always_inline attribute,
+it will not be inlined if the code model of the caller function is different
+from the code model of the callee function.
-@cindex @code{fentry_name} function attribute, x86
-@item fentry_name("@var{name}")
-On x86 targets, the @code{fentry_name} attribute sets the function to
-call on function entry when function instrumentation is enabled
-with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
-nop sequence is generated.
+@cindex @code{target_clones (string,...)} loongarch function attribute target_clones
+@item target_clones (string,...)
-@cindex @code{fentry_section} function attribute, x86
-@item fentry_section("@var{name}")
-On x86 targets, the @code{fentry_section} attribute sets the name
-of the section to record function entry instrumentation calls in when
-enabled with @option{-pg -mrecord-mcount}
+Like attribute @code{target}, these options also reflect the behavior of
+similar command line options.
-@cindex @code{nodirect_extern_access} function attribute
-@opindex mno-direct-extern-access
-@item nodirect_extern_access
-This attribute, attached to a global variable or function, is the
-counterpart to option @option{-mno-direct-extern-access}.
+@code{string} can take the following values:
-@end table
+@itemize @bullet
+@item default
+@item strict-align
+@item arch=
+@item lsx
+@item lasx
+@item frecipe
+@item div32
+@item lam-bh
+@item lamcas
+@item scq
+@item ld-seq-sa
+@end itemize
+You can set the priority of attributes in target_clones (except @code{default}).
+For example:
-@subsubheading Inlining rules
-On the x86, the inliner does not inline a
-function that has different target options than the caller, unless the
-callee has a subset of the target options of the caller. For example
-a function declared with @code{target("sse3")} can inline a function
-with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
+@smallexample
+__attribute__((target_clones ("default","arch=la64v1.1","lsx;priority=1")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-Besides the basic rule, when a function specifies
-@code{target("arch=@var{ARCH}")} or @code{target("tune=@var{TUNE}")}
-attribute, the inlining rule will be different. It allows inlining of
-a function with default @option{-march=x86-64} and
-@option{-mtune=generic} specified, or a function that has a subset
-of ISA features and marked with always_inline.
+The priority is from low to high:
+@itemize @bullet
+@item default
+@item arch=loongarch64
+@item strict-align
+@item frecipe = div32 = lam-bh = lamcas = scq = ld-seq-sa
+@item lsx
+@item arch=la64v1.0
+@item arch=la64v1.1
+@item lasx
+@end itemize
-@node Xstormy16 Function Attributes
-@subsubsection Xstormy16 Function Attributes
+Note that the option values on the gcc command line are not considered when
+calculating the priority.
-These function attributes are supported by the Xstormy16 back end:
+If a priority is set for a feature in target_clones, then the priority of this
+feature will be higher than @code{lasx}.
-@table @code
-@cindex @code{interrupt} function attribute, Xstormy16
-@item interrupt
-Use this attribute to indicate
-that the specified function is an interrupt handler. The compiler generates
-function entry and exit sequences suitable for use in an interrupt handler
-when this attribute is present.
-@end table
+For example:
-@node Variable Attributes
-@subsection Specifying Attributes of Variables
-@cindex attribute of variables
-@cindex variable attributes
-
-You can use attributes to specify special properties
-of variables, function parameters, or structure, union, and, in C++, class
-members. Some attributes are currently
-defined generically for variables. Other attributes are defined for
-variables on particular target systems. Other attributes are available
-for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
-enumerators (@pxref{Enumerator Attributes}), statements
-(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
-Other front ends might define more attributes
-(@pxref{C++ Extensions,,Extensions to the C++ Language}).
+@smallexample
+__attribute__((target_clones ("default","arch=la64v1.1","lsx;priority=1")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-GCC provides two different ways to specify attributes: the traditional
-GNU syntax using @samp{__attribute__ ((...))} annotations, and the
-newer standard C and C++ syntax using @samp{[[...]]} with the
-@samp{gnu::} prefix on attribute names. Note that the exact rules for
-placement of attributes in your source code are different depending on
-which syntax you use. @xref{GNU Attribute Syntax}, for details.
+In this test case, the priority of @code{lsx} is higher than that of
+@code{arch=la64v1.1}.
-@menu
-* Common Variable Attributes::
-* ARC Variable Attributes::
-* AVR Variable Attributes::
-* Blackfin Variable Attributes::
-* H8/300 Variable Attributes::
-* IA-64 Variable Attributes::
-* LoongArch Variable Attributes::
-* M32R/D Variable Attributes::
-* Microsoft Windows Variable Attributes::
-* MSP430 Variable Attributes::
-* Nvidia PTX Variable Attributes::
-* PowerPC Variable Attributes::
-* RL78 Variable Attributes::
-* V850 Variable Attributes::
-* x86 Variable Attributes::
-* Xstormy16 Variable Attributes::
-@end menu
+If the same priority is explicitly set for two features, the priority is still
+calculated according to the priority list above.
-@node Common Variable Attributes
-@subsubsection Common Variable Attributes
+For example:
-The following attributes are supported on most targets.
+@smallexample
+__attribute__((target_clones ("default","arch=la64v1.1;priority=1","lsx;priority=1")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-@table @code
-@c Keep this table alphabetized by attribute name. Treat _ as space.
+In this test case, the priority of @code{arch=la64v1.1;priority=1} is higher
+than that of @code{lsx;priority=1}.
-@cindex @code{alias} variable attribute
-@item alias ("@var{target}")
-The @code{alias} variable attribute causes the declaration to be emitted
-as an alias for another symbol known as an @dfn{alias target}. Except
-for top-level qualifiers the alias target must have the same type as
-the alias. For instance, the following
+@cindex @code{target_version (string)} loongarch function attribute target_versions
+@item target_version (string)
+Support attributes and priorities are the same as @code{target_clones}.
+Note that this attribute requires GLIBC2.38 and newer that support HWCAP.
+
+For example:
+@code{test1.C}
@smallexample
-int var_target;
-extern int __attribute__ ((alias ("var_target"))) var_alias;
+__attribute__((target_clones ("default","arch=la64v1.1","lsx;priority=1")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
@end smallexample
-@noindent
-defines @code{var_alias} to be an alias for the @code{var_target} variable.
+@code{test2.C}
+@smallexample
+__attribute__((target_version ("default")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+__attribute__((target_version ("arch=la64v1.1")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+__attribute__((target_version ("lsx;priority=1")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
+The implementations of @code{test1.C} and @code{test2.C} are equivalent.
-It is an error if the alias target is not defined in the same translation
-unit as the alias.
+@cindex @code{model} variable attribute, LoongArch
+@item model("@var{name}")
+Use this variable attribute on the LoongArch to use a different code model for
+addressing this variable, than the code model specified by the global
+@option{-mcmodel} option. This attribute is mostly useful if a
+@code{section} attribute and/or a linker script locates this object
+specially. Currently the only supported values of @var{name} are
+@code{normal} and @code{extreme}.
+@end table
-Note that in the absence of the attribute GCC assumes that distinct
-declarations with external linkage denote distinct objects. Using both
-the alias and the alias target to access the same object is undefined
-in a translation unit without a declaration of the alias with the attribute.
+@node M32C Attributes
+@subsubsection M32C Attributes
-This attribute requires assembler and object file support, and may not be
-available on all targets.
+These function attributes are supported by the M32C back end:
-@cindex @code{aligned} variable attribute
-@item aligned
-@itemx aligned (@var{alignment})
-The @code{aligned} attribute specifies a minimum alignment for the variable
-or structure field, measured in bytes. When specified, @var{alignment} must
-be an integer constant power of 2. Specifying no @var{alignment} argument
-implies the maximum alignment for the target, which is often, but by no
-means always, 8 or 16 bytes.
+@table @code
+@cindex @code{bank_switch} function attribute, M32C
+@item bank_switch
+When added to an interrupt handler with the M32C port, causes the
+prologue and epilogue to use bank switching to preserve the registers
+rather than saving them on the stack.
+
+@cindex @code{fast_interrupt} function attribute, M32C
+@item fast_interrupt
+Use this attribute on the M32C port to indicate that the specified
+function is a fast interrupt handler. This is just like the
+@code{interrupt} attribute, except that @code{freit} is used to return
+instead of @code{reit}.
+
+@cindex @code{function_vector} function attribute, M16C/M32C
+@item function_vector
+On M16C/M32C targets, the @code{function_vector} attribute declares a
+special page subroutine call function. Use of this attribute reduces
+the code size by 2 bytes for each call generated to the
+subroutine. The argument to the attribute is the vector number entry
+from the special page vector table which contains the 16 low-order
+bits of the subroutine's entry address. Each vector table has special
+page number (18 to 255) that is used in @code{jsrs} instructions.
+Jump addresses of the routines are generated by adding 0x0F0000 (in
+case of M16C targets) or 0xFF0000 (in case of M32C targets), to the
+2-byte addresses set in the vector table. Therefore you need to ensure
+that all the special page vector routines should get mapped within the
+address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF
+(for M32C).
-For example, the declaration:
+In the following example 2 bytes are saved for each call to
+function @code{foo}.
@smallexample
-int x __attribute__ ((aligned (16))) = 0;
-@end smallexample
-
-@noindent
-causes the compiler to allocate the global variable @code{x} on a
-16-byte boundary. On a 68040, this could be used in conjunction with
-an @code{asm} expression to access the @code{move16} instruction which
-requires 16-byte aligned operands.
-
-You can also specify the alignment of structure fields. For example, to
-create a double-word aligned @code{int} pair, you could write:
+void foo (void) __attribute__((function_vector(0x18)));
+void foo (void)
+@{
+@}
-@smallexample
-struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
+void bar (void)
+@{
+ foo();
+@}
@end smallexample
-@noindent
-This is an alternative to creating a union with a @code{double} member,
-which forces the union to be double-word aligned.
-
-As in the preceding examples, you can explicitly specify the alignment
-(in bytes) that you wish the compiler to use for a given variable or
-structure field. Alternatively, you can leave out the alignment factor
-and just ask the compiler to align a variable or field to the
-default alignment for the target architecture you are compiling for.
-The default alignment is sufficient for all scalar types, but may not be
-enough for all vector types on a target that supports vector operations.
-The default alignment is fixed for a particular target ABI.
-
-GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__},
-which is the largest alignment ever used for any data type on the
-target machine you are compiling for. For example, you could write:
+If functions are defined in one file and are called in another file,
+then be sure to write this declaration in both files.
-@smallexample
-short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));
-@end smallexample
+This attribute is ignored for R8C target.
-The compiler automatically sets the alignment for the declared
-variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can
-often make copy operations more efficient, because the compiler can
-use whatever instructions copy the biggest chunks of memory when
-performing copies to or from the variables or fields that you have
-aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__}
-may change depending on command-line options.
+@cindex @code{interrupt} function attribute, M32C
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+@end table
-When used on a struct, or struct member, the @code{aligned} attribute can
-only increase the alignment; in order to decrease it, the @code{packed}
-attribute must be specified as well. When used as part of a typedef, the
-@code{aligned} attribute can both increase and decrease alignment, and
-specifying the @code{packed} attribute generates a warning.
+@node M32R/D Attributes
+@subsubsection M32R/D Attributes
-Note that the effectiveness of @code{aligned} attributes for static
-variables may be limited by inherent limitations in the system linker
-and/or object file format. On some systems, the linker is
-only able to arrange for variables to be aligned up to a certain maximum
-alignment. (For some linkers, the maximum supported alignment may
-be very very small.) If your linker is only able to align variables
-up to a maximum of 8-byte alignment, then specifying @code{aligned(16)}
-in an @code{__attribute__} still only provides you with 8-byte
-alignment. See your linker documentation for further information.
+These attributes are supported by the M32R/D back end:
-Stack variables are not affected by linker restrictions; GCC can properly
-align them on any target.
+@table @code
+@cindex @code{interrupt} function attribute, M32R/D
+@item interrupt
+Use this function attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-The @code{aligned} attribute can also be used for functions
-(@pxref{Common Function Attributes}.)
+@cindex @code{model} attribute, M32R/D
+@cindex function addressability on the M32R/D
+@cindex variable addressability on the M32R/D
+@item model (@var{model-name})
-@cindex @code{alloc_size} variable attribute
-@item alloc_size (@var{position})
-@itemx alloc_size (@var{position-1}, @var{position-2})
-The @code{alloc_size} variable attribute may be applied to the declaration
-of a pointer to a function that returns a pointer and takes at least one
-argument of an integer type. It indicates that the returned pointer points
-to an object whose size is given by the function argument at @var{position},
-or by the product of the arguments at @var{position-1} and @var{position-2}.
-Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other
-sizes are diagnosed when detected. GCC uses this information to improve
-the results of @code{__builtin_object_size}.
+On the M32R/D, use this attribute to set the addressability of an
+object, and of the code generated for a function. The identifier
+@var{model-name} is one of @code{small}, @code{medium}, or
+@code{large}, representing each of the code models.
-For instance, the following declarations
+Small model objects live in the lower 16MB of memory (so that their
+addresses can be loaded with the @code{ld24} instruction), and are
+callable with the @code{bl} instruction.
-@smallexample
-typedef __attribute__ ((alloc_size (1, 2))) void*
- (*calloc_ptr) (size_t, size_t);
-typedef __attribute__ ((alloc_size (1))) void*
- (*malloc_ptr) (size_t);
-@end smallexample
+Medium model objects may live anywhere in the 32-bit address space (the
+compiler generates @code{seth/add3} instructions to load their addresses),
+and are callable with the @code{bl} instruction.
-@noindent
-specify that @code{calloc_ptr} is a pointer of a function that, like
-the standard C function @code{calloc}, returns an object whose size
-is given by the product of arguments 1 and 2, and similarly, that
-@code{malloc_ptr}, like the standard C function @code{malloc},
-returns an object whose size is given by argument 1 to the function.
+Large model objects may live anywhere in the 32-bit address space (the
+compiler generates @code{seth/add3} instructions to load their addresses),
+and may not be reachable with the @code{bl} instruction (the compiler
+generates the much slower @code{seth/add3/jl} instruction sequence).
+@end table
-@cindex @code{btf_decl_tag} variable attribute
-@item btf_decl_tag (@var{argument})
-The @code{btf_decl_tag} attribute may be used to associate variable
-declarations, struct or union member declarations, function
-declarations, and function parameter declarations with arbitrary strings.
-These strings are not interpreted by the compiler in any way, and have
-no effect on code generation. Instead, these user-provided strings
-are recorded in DWARF (via @code{DW_AT_GNU_annotation} and
-@code{DW_TAG_GNU_annotation} extensions) and BTF information (via
-@code{BTF_KIND_DECL_TAG} records), and associated to the attributed
-declaration. If neither DWARF nor BTF information is generated, the
-attribute has no effect.
+@node m68k Attributes
+@subsubsection m68k Attributes
-The argument is treated as a null-terminated sequence of zero or more
-non-null bytes. Wide character strings are not supported.
+These function attributes are supported by the m68k back end:
-The attribute may be supplied multiple times for a single declaration,
-in which case each distinct argument string will be recorded in a
-separate DIE or BTF record, each associated to the declaration. For
-a single declaration with multiple @code{btf_decl_tag} attributes,
-the order of the @code{DW_TAG_GNU_annotation} DIEs produced is not
-guaranteed to maintain the order of attributes in the source code.
+@table @code
+@cindex @code{interrupt} function attribute, m68k
+@cindex @code{interrupt_handler} function attribute, m68k
+@item interrupt
+@itemx interrupt_handler
+Use this attribute to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present. Either name may be used.
-For example:
+@cindex @code{interrupt_thread} function attribute, fido
+@item interrupt_thread
+Use this attribute on fido, a subarchitecture of the m68k, to indicate
+that the specified function is an interrupt handler that is designed
+to run as a thread. The compiler omits generate prologue/epilogue
+sequences and replaces the return instruction with a @code{sleep}
+instruction. This attribute is available only on fido.
+@end table
-@smallexample
-int *foo __attribute__ ((btf_decl_tag ("__percpu")));
-@end smallexample
+@node MCORE Attributes
+@subsubsection MCORE Attributes
-@noindent
-when compiled with @option{-gbtf} results in an additional
-@code{BTF_KIND_DECL_TAG} BTF record to be emitted in the BTF info,
-associating the string @samp{__percpu} with the @code{BTF_KIND_VAR}
-record for the variable @code{foo}.
+These function attributes are supported by the MCORE back end:
-@cindex @code{cleanup} variable attribute
-@item cleanup (@var{cleanup_function})
-The @code{cleanup} attribute runs a function when the variable goes
-out of scope. This attribute can only be applied to auto function
-scope variables; it may not be applied to parameters or variables
-with static storage duration. The function must take one parameter,
-a pointer to a type compatible with the variable. The return value
-of the function (if any) is ignored.
+@table @code
+@cindex @code{naked} function attribute, MCORE
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
+@end table
-When multiple variables in the same scope have @code{cleanup}
-attributes, at exit from the scope their associated cleanup functions
-are run in reverse order of definition (last defined, first
-cleanup).
+@node MicroBlaze Attributes
+@subsubsection MicroBlaze Attributes
-If @option{-fexceptions} is enabled, then @var{cleanup_function}
-is run during the stack unwinding that happens during the
-processing of the exception. Note that the @code{cleanup} attribute
-does not allow the exception to be caught, only to perform an action.
-It is undefined what happens if @var{cleanup_function} does not
-return normally.
+These function attributes are supported on MicroBlaze targets:
-@cindex @code{common} variable attribute
-@cindex @code{nocommon} variable attribute
-@opindex fcommon
-@opindex fno-common
-@item common
-@itemx nocommon
-The @code{common} attribute requests GCC to place a variable in
-``common'' storage. The @code{nocommon} attribute requests the
-opposite---to allocate space for it directly.
+@table @code
+@cindex @code{save_volatiles} function attribute, MicroBlaze
+@item save_volatiles
+Use this attribute to indicate that the function is
+an interrupt handler. All volatile registers (in addition to non-volatile
+registers) are saved in the function prologue. If the function is a leaf
+function, only volatiles used by the function are saved. A normal function
+return is generated instead of a return from interrupt.
-These attributes override the default chosen by the
-@option{-fno-common} and @option{-fcommon} flags respectively.
+@cindex @code{break_handler} function attribute, MicroBlaze
+@cindex break handler functions
+@item break_handler
+Use this attribute to indicate that
+the specified function is a break handler. The compiler generates function
+entry and exit sequences suitable for use in an break handler when this
+attribute is present. The return from @code{break_handler} is done through
+the @code{rtbd} instead of @code{rtsd}.
-@cindex @code{copy} variable attribute
-@item copy
-@itemx copy (@var{variable})
-The @code{copy} attribute applies the set of attributes with which
-@var{variable} has been declared to the declaration of the variable
-to which the attribute is applied. The attribute is designed for
-libraries that define aliases that are expected to specify the same
-set of attributes as the aliased symbols. The @code{copy} attribute
-can be used with variables, functions or types. However, the kind
-of symbol to which the attribute is applied (either varible or
-function) must match the kind of symbol to which the argument refers.
-The @code{copy} attribute copies only syntactic and semantic attributes
-but not attributes that affect a symbol's linkage or visibility such as
-@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
-attribute is also not copied. @xref{Common Function Attributes}.
-@xref{Common Type Attributes}.
+@smallexample
+void f () __attribute__ ((break_handler));
+@end smallexample
-@cindex @code{counted_by} variable attribute
-@item counted_by (@var{count})
-The @code{counted_by} attribute may be attached to the C99 flexible array
-member, or a pointer field of a structure. It indicates that the number
-of the elements of the array that is held by the flexible array member
-field, or is pointed to by the pointer field, is given by the field
-"@var{count}" in the same structure as the flexible array member or the
-pointer field.
+@cindex @code{interrupt_handler} function attribute, MicroBlaze
+@cindex @code{fast_interrupt} function attribute, MicroBlaze
+@item interrupt_handler
+@itemx fast_interrupt
+These attributes indicate that the specified function is an interrupt
+handler. Use the @code{fast_interrupt} attribute to indicate handlers
+used in low-latency interrupt mode, and @code{interrupt_handler} for
+interrupts that do not use low-latency handlers. In both cases, GCC
+emits appropriate prologue code and generates a return from the handler
+using @code{rtid} instead of @code{rtsd}.
+@end table
-This attribute is available only in C for now.
-In C++ this attribute is ignored.
+@node Microsoft Windows Attributes
+@subsubsection Microsoft Windows Attributes
-GCC may use this information to improve detection of object size information
-for such structures and provide better results in compile-time diagnostics
-and runtime features like the array bound sanitizer and
-the @code{__builtin_dynamic_object_size}.
+The following attributes are available on Microsoft Windows and Symbian OS
+targets.
-For instance, the following code:
+@table @code
+@cindex @code{dllexport} attribute
+@cindex @code{__declspec(dllexport)}
+@item dllexport
+This attribute can be applied functions, variables, and C++ classes.
-@smallexample
-struct P @{
- size_t count;
- char other;
- char array[] __attribute__ ((counted_by (count)));
-@} *p;
-@end smallexample
+On Microsoft Windows targets and Symbian OS targets the
+@code{dllexport} attribute causes the compiler to provide a global
+pointer to a pointer in a DLL, so that it can be referenced with the
+@code{dllimport} attribute. On Microsoft Windows targets, the pointer
+name is formed by combining @code{_imp__} and the function or variable
+name.
-@noindent
-specifies that the @code{array} is a flexible array member whose number
-of elements is given by the field @code{count} in the same structure.
+You can use @code{__declspec(dllexport)} as a synonym for
+@code{__attribute__ ((dllexport))} for compatibility with other
+compilers.
-@smallexample
-struct PP @{
- size_t count2;
- char other1;
- char *array2 __attribute__ ((counted_by (count2)));
- int other2;
-@} *pp;
-@end smallexample
+On systems that support the @code{visibility} attribute, this
+attribute also implies ``default'' visibility. It is an error to
+explicitly specify any other visibility.
-@noindent
-specifies that the @code{array2} is an array that is pointed by the
-pointer field, and its number of elements is given by the field
-@code{count2} in the same structure.
+GCC's default behavior is to emit all inline functions with the
+@code{dllexport} attribute. Since this can cause object file-size bloat,
+you can use @option{-fno-keep-inline-dllexport}, which tells GCC to
+ignore the attribute for inlined functions unless the
+@option{-fkeep-inline-functions} flag is used instead.
-The field that represents the number of the elements should have an
-integer type. Otherwise, the compiler reports an error and ignores
-the attribute.
+The attribute is ignored for undefined symbols.
-When the field that represents the number of the elements is assigned a
-negative integer value, the compiler treats the value as zero.
+When applied to C++ classes, the attribute marks defined non-inlined
+member functions and static data members as exports. Static consts
+initialized in-class are not marked unless they are also defined
+out-of-class.
-The @code{counted_by} attribute is not allowed for a pointer to function,
-or a pointer to a structure or union that includes a flexible array member.
-However, it is allowed for a pointer to non-void incomplete structure
-or union types, as long as the type could be completed before the first
-reference to the pointer.
+For Microsoft Windows targets there are alternative methods for
+including the symbol in the DLL's export table such as using a
+@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using
+the @option{--export-all} linker flag.
-The attribute is allowed for a pointer to @code{void}. However,
-warnings will be issued for such cases when @option{-Wpointer-arith} is
-specified. When this attribute is applied on a pointer to @code{void},
-the size of each element of this pointer array is treated as 1.
+@cindex @code{dllimport} attribute
+@cindex @code{__declspec(dllimport)}
+@item dllimport
+This attribute applies to functions, variables, and C++ classes.
+On Microsoft Windows and Symbian OS targets, the @code{dllimport}
+attribute causes the compiler to reference a function or variable via
+a global pointer to a pointer that is set up by the DLL exporting the
+symbol. The attribute implies @code{extern}. On Microsoft Windows
+targets, the pointer name is formed by combining @code{_imp__} and the
+function or variable name.
-An explicit @code{counted_by} annotation defines a relationship between
-two objects, @code{p->array} and @code{p->count}, and there are the
-following requirements on the relationship between this pair:
+You can use @code{__declspec(dllimport)} as a synonym for
+@code{__attribute__ ((dllimport))} for compatibility with other
+compilers.
-@itemize @bullet
-@item
-@code{p->count} must be initialized before the first reference to
-@code{p->array};
+On systems that support the @code{visibility} attribute, this
+attribute also implies ``default'' visibility. It is an error to
+explicitly specify any other visibility.
-@item
-@code{p->array} has @emph{at least} @code{p->count} number of elements
-available all the time. This relationship must hold even after any of
-these related objects are updated during the program.
-@end itemize
+Currently, the attribute is ignored for inlined functions. If the
+attribute is applied to a symbol @emph{definition}, an error is reported.
+If a symbol previously declared @code{dllimport} is later defined, the
+attribute is ignored in subsequent references, and a warning is emitted.
+The attribute is also overridden by a subsequent declaration as
+@code{dllexport}.
-In addition to the above requirements, there is one more requirement
-between this pair if and only if @code{p->array} is an array that is
-pointed by the pointer field:
+When applied to C++ classes, the attribute marks non-inlined
+member functions and static data members as imports. However, the
+attribute is ignored for virtual methods to allow creation of vtables
+using thunks.
-@code{p->array} and @code{p->count} can only be changed by changing the
-whole structure at the same time.
+On the SH Symbian OS target the @code{dllimport} attribute also has
+another affect---it can cause the vtable and run-time type information
+for a class to be exported. This happens when the class has a
+dllimported constructor or a non-inline, non-pure virtual function
+and, for either of those two conditions, the class also has an inline
+constructor or destructor and has a key function that is defined in
+the current translation unit.
-It's the programmer's responsibility to make sure the above requirements to
-be kept all the time. Otherwise the compiler reports warnings and
-the results of the array bound sanitizer and the
-@code{__builtin_dynamic_object_size} built-in are undefined.
+For Microsoft Windows targets the use of the @code{dllimport}
+attribute on functions is not necessary, but provides a small
+performance benefit by eliminating a thunk in the DLL@. The use of the
+@code{dllimport} attribute on imported variables can be avoided by passing the
+@option{--enable-auto-import} switch to the GNU linker. As with
+functions, using the attribute for a variable eliminates a thunk in
+the DLL@.
-One important feature of the attribute is that a reference to the flexible
-array member field uses the latest value assigned to the field that
-represents the number of the elements before that reference. For example,
+One drawback to using this attribute is that a pointer to a
+@emph{variable} marked as @code{dllimport} cannot be used as a constant
+address. However, a pointer to a @emph{function} with the
+@code{dllimport} attribute can be used as a constant initializer; in
+this case, the address of a stub function in the import lib is
+referenced. On Microsoft Windows targets, the attribute can be disabled
+for functions by setting the @option{-mnop-fun-dllimport} flag.
-@smallexample
- p->count = val1;
- p->array[20] = 0; // ref1 to p->array
- p->count = val2;
- p->array[30] = 0; // ref2 to p->array
-@end smallexample
+@cindex @code{selectany} variable attribute
+@item selectany
+The @code{selectany} attribute causes an initialized global variable to
+have link-once semantics. When multiple definitions of the variable are
+encountered by the linker, the first is selected and the remainder are
+discarded. Following usage by the Microsoft compiler, the linker is told
+@emph{not} to warn about size or content differences of the multiple
+definitions.
-@noindent
-In the above, @code{ref1} uses @code{val1} as the number of the elements in
-@code{p->array}, and @code{ref2} uses @code{val2} as the number of elements
-in @code{p->array}.
+Although the primary usage of this attribute is for POD types, the
+attribute can also be applied to global C++ objects that are initialized
+by a constructor. In this case, the static initialization and destruction
+code for the object is emitted in each translation defining the object,
+but the calls to the constructor and destructor are protected by a
+link-once guard variable.
-Note, however, the above feature is not valid for the pointer field.
+The @code{selectany} attribute is only available on Microsoft Windows
+targets. You can use @code{__declspec (selectany)} as a synonym for
+@code{__attribute__ ((selectany))} for compatibility with other
+compilers.
-@cindex @code{deprecated} variable attribute
-@item deprecated
-@itemx deprecated (@var{msg})
-The @code{deprecated} attribute results in a warning if the variable
-is used anywhere in the source file. This is useful when identifying
-variables that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated variable, to enable users to easily find further
-information about why the variable is deprecated, or what they should
-do instead. Note that the warning only occurs for uses:
+@cindex @code{shared} variable attribute
+@item shared
+On Microsoft Windows, in addition to putting variable definitions in a named
+section, the section can also be shared among all running copies of an
+executable or DLL@. For example, this small program defines shared data
+by putting it in a named section @code{shared} and marking the section
+shareable:
@smallexample
-extern int old_var __attribute__ ((deprecated));
-extern int old_var;
-int new_fn () @{ return old_var; @}
+int foo __attribute__((section ("shared"), shared)) = 0;
+
+int
+main()
+@{
+ /* @r{Read and write foo. All running
+ copies see the same value.} */
+ return 0;
+@}
@end smallexample
@noindent
-results in a warning on line 3 but not line 2. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present.
-
-The @code{deprecated} attribute can also be used for functions and
-types (@pxref{Common Function Attributes},
-@pxref{Common Type Attributes}).
+You may only use the @code{shared} attribute along with @code{section}
+attribute with a fully-initialized global definition because of the way
+linkers work. See @code{section} attribute for more information.
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
+The @code{shared} attribute is only available on Microsoft Windows@.
+@end table
-@cindex @code{mode} variable attribute
-@item mode (@var{mode})
-This attribute specifies the data type for the declaration---whichever
-type corresponds to the mode @var{mode}. This in effect lets you
-request an integer or floating-point type according to its width.
+@node MIPS Attributes
+@subsubsection MIPS Attributes
-@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
-for a list of the possible keywords for @var{mode}.
-You may also specify a mode of @code{byte} or @code{__byte__} to
-indicate the mode corresponding to a one-byte integer, @code{word} or
-@code{__word__} for the mode of a one-word integer, and @code{pointer}
-or @code{__pointer__} for the mode used to represent pointers.
+These function attributes are supported by the MIPS back end:
-@cindex @code{no_icf} variable attribute
-@item no_icf
-This variable attribute prevents a variable from being merged with another
-equivalent variable.
+@table @code
+@cindex @code{interrupt} function attribute, MIPS
+@item interrupt
+Use this attribute to indicate that the specified function is an interrupt
+handler. The compiler generates function entry and exit sequences suitable
+for use in an interrupt handler when this attribute is present.
+An optional argument is supported for the interrupt attribute which allows
+the interrupt mode to be described. By default GCC assumes the external
+interrupt controller (EIC) mode is in use, this can be explicitly set using
+@code{eic}. When interrupts are non-masked then the requested Interrupt
+Priority Level (IPL) is copied to the current IPL which has the effect of only
+enabling higher priority interrupts. To use vectored interrupt mode use
+the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change
+the behavior of the non-masked interrupt support and GCC will arrange to mask
+all interrupts from sw0 up to and including the specified interrupt vector.
-@cindex @code{noinit} variable attribute
-@item noinit
-Any data with the @code{noinit} attribute will not be initialized by
-the C runtime startup code, or the program loader. Not initializing
-data in this way can reduce program startup times.
+You can use the following attributes to modify the behavior
+of an interrupt handler:
+@table @code
+@cindex @code{use_shadow_register_set} function attribute, MIPS
+@item use_shadow_register_set
+Assume that the handler uses a shadow register set, instead of
+the main general-purpose registers. An optional argument @code{intstack} is
+supported to indicate that the shadow register set contains a valid stack
+pointer.
-This attribute is specific to ELF targets and relies on the linker
-script to place sections with the @code{.noinit} prefix in the right
-location.
+@cindex @code{keep_interrupts_masked} function attribute, MIPS
+@item keep_interrupts_masked
+Keep interrupts masked for the whole function. Without this attribute,
+GCC tries to reenable interrupts for as much of the function as it can.
-@cindex @code{nonstring} variable attribute
-@item nonstring
-The @code{nonstring} variable attribute specifies that an object or member
-declaration with type array of @code{char}, @code{signed char}, or
-@code{unsigned char}, or pointer to such a type is intended to store
-character arrays that do not necessarily contain a terminating @code{NUL}.
-This is useful in detecting uses of such arrays or pointers with functions
-that expect @code{NUL}-terminated strings, and to avoid warnings when such
-an array or pointer is used as an argument to a bounded string manipulation
-function such as @code{strncpy}. For example, without the attribute, GCC
-will issue a warning for the @code{strncpy} call below because it may
-truncate the copy without appending the terminating @code{NUL} character.
-Using the attribute makes it possible to suppress the warning. However,
-when the array is declared with the attribute the call to @code{strlen} is
-diagnosed because when the array doesn't contain a @code{NUL}-terminated
-string the call is undefined. To copy, compare, or search non-string
-character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr},
-and other functions that operate on arrays of bytes. In addition,
-calling @code{strnlen} and @code{strndup} with such arrays is safe
-provided a suitable bound is specified, and not diagnosed.
+@cindex @code{use_debug_exception_return} function attribute, MIPS
+@item use_debug_exception_return
+Return using the @code{deret} instruction. Interrupt handlers that don't
+have this attribute return using @code{eret} instead.
+@end table
+You can use any combination of these attributes, as shown below:
@smallexample
-struct Data
-@{
- char name [32] __attribute__ ((nonstring));
-@};
-
-int f (struct Data *pd, const char *s)
-@{
- strncpy (pd->name, s, sizeof pd->name);
- @dots{}
- return strlen (pd->name); // unsafe, gets a warning
-@}
+void __attribute__ ((interrupt)) v0 ();
+void __attribute__ ((interrupt, use_shadow_register_set)) v1 ();
+void __attribute__ ((interrupt, keep_interrupts_masked)) v2 ();
+void __attribute__ ((interrupt, use_debug_exception_return)) v3 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+ keep_interrupts_masked)) v4 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+ use_debug_exception_return)) v5 ();
+void __attribute__ ((interrupt, keep_interrupts_masked,
+ use_debug_exception_return)) v6 ();
+void __attribute__ ((interrupt, use_shadow_register_set,
+ keep_interrupts_masked,
+ use_debug_exception_return)) v7 ();
+void __attribute__ ((interrupt("eic"))) v8 ();
+void __attribute__ ((interrupt("vector=hw3"))) v9 ();
@end smallexample
-@cindex @code{objc_nullability} variable attribute
-@item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
-This attribute applies to pointer variables only. It allows marking the
-pointer with one of four possible values describing the conditions under
-which the pointer might have a @code{nil} value. In most cases, the
-attribute is intended to be an internal representation for property and
-method nullability (specified by language keywords); it is not recommended
-to use it directly.
-
-When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is
-known about the conditions in which the pointer might be @code{nil}. Making
-this state specific serves to avoid false positives in diagnostics.
-
-When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has
-no meaning if it is @code{nil} and thus the compiler is free to emit
-diagnostics if it can be determined that the value will be @code{nil}.
+@cindex indirect calls, MIPS
+@cindex @code{long_call} function attribute, MIPS
+@cindex @code{short_call} function attribute, MIPS
+@cindex @code{near} function attribute, MIPS
+@cindex @code{far} function attribute, MIPS
+@item long_call
+@itemx short_call
+@itemx near
+@itemx far
+These attributes specify how a particular function is called on MIPS@.
+The attributes override the @option{-mlong-calls} (@pxref{MIPS Options})
+command-line switch. The @code{long_call} and @code{far} attributes are
+synonyms, and cause the compiler to always call
+the function by first loading its address into a register, and then using
+the contents of that register. The @code{short_call} and @code{near}
+attributes are synonyms, and have the opposite
+effect; they specify that non-PIC calls should be made using the more
+efficient @code{jal} instruction.
-When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might
-be @code{nil} and carry meaning as such.
+@cindex @code{mips16} function attribute, MIPS
+@cindex @code{nomips16} function attribute, MIPS
+@item mips16
+@itemx nomips16
-When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in
-the context of property attribute lists) this describes the case in which a
-property setter may take the value @code{nil} (which perhaps causes the
-property to be reset in some manner to a default) but for which the property
-getter will never validly return @code{nil}.
+On MIPS targets, you can use the @code{mips16} and @code{nomips16}
+function attributes to locally select or turn off MIPS16 code generation.
+A function with the @code{mips16} attribute is emitted as MIPS16 code,
+while MIPS16 code generation is disabled for functions with the
+@code{nomips16} attribute. These attributes override the
+@option{-mips16} and @option{-mno-mips16} options on the command line
+(@pxref{MIPS Options}).
-@cindex @code{packed} variable attribute
-@item packed
-The @code{packed} attribute specifies that a structure member should have
-the smallest possible alignment---one bit for a bit-field and one byte
-otherwise, unless a larger value is specified with the @code{aligned}
-attribute. The attribute does not apply to non-member objects.
+When compiling files containing mixed MIPS16 and non-MIPS16 code, the
+preprocessor symbol @code{__mips16} reflects the setting on the command line,
+not that within individual functions. Mixed MIPS16 and non-MIPS16 code
+may interact badly with some GCC extensions such as @code{__builtin_apply}
+(@pxref{Constructing Calls}).
-For example in the structure below, the member array @code{x} is packed
-so that it immediately follows @code{a} with no intervening padding:
+@cindex @code{micromips} function attribute
+@cindex @code{nomicromips} function attribute
+@item micromips, MIPS
+@itemx nomicromips, MIPS
-@smallexample
-struct foo
-@{
- char a;
- int x[2] __attribute__ ((packed));
-@};
-@end smallexample
+On MIPS targets, you can use the @code{micromips} and @code{nomicromips}
+function attributes to locally select or turn off microMIPS code generation.
+A function with the @code{micromips} attribute is emitted as microMIPS code,
+while microMIPS code generation is disabled for functions with the
+@code{nomicromips} attribute. These attributes override the
+@option{-mmicromips} and @option{-mno-micromips} options on the command line
+(@pxref{MIPS Options}).
-@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the
-@code{packed} attribute on bit-fields of type @code{char}. This has
-been fixed in GCC 4.4 but the change can lead to differences in the
-structure layout. See the documentation of
-@option{-Wpacked-bitfield-compat} for more information.
+When compiling files containing mixed microMIPS and non-microMIPS code, the
+preprocessor symbol @code{__mips_micromips} reflects the setting on the
+command line,
+not that within individual functions. Mixed microMIPS and non-microMIPS code
+may interact badly with some GCC extensions such as @code{__builtin_apply}
+(@pxref{Constructing Calls}).
-@cindex @code{persistent} variable attribute
-@item persistent
-Any data with the @code{persistent} attribute will not be initialized by
-the C runtime startup code, but will be initialized by the program
-loader. This enables the value of the variable to @samp{persist}
-between processor resets.
+@cindex @code{nocompression} function attribute, MIPS
+@item nocompression
+On MIPS targets, you can use the @code{nocompression} function attribute
+to locally turn off MIPS16 and microMIPS code generation. This attribute
+overrides the @option{-mips16} and @option{-mmicromips} options on the
+command line (@pxref{MIPS Options}).
-This attribute is specific to ELF targets and relies on the linker
-script to place the sections with the @code{.persistent} prefix in the
-right location. Specifically, some type of non-volatile, writable
-memory is required.
+@cindex @code{use_hazard_barrier_return} function attribute, MIPS
+@item use_hazard_barrier_return
+This function attribute instructs the compiler to generate a hazard barrier
+return that clears all execution and instruction hazards while returning,
+instead of generating a normal return instruction.
-@cindex @code{section} variable attribute
-@item section ("@var{section-name}")
-Normally, the compiler places the objects it generates in sections like
-@code{data} and @code{bss}. Sometimes, however, you need additional sections,
-or you need certain particular variables to appear in special sections,
-for example to map to special hardware. The @code{section}
-attribute specifies that a variable (or function) lives in a particular
-section. For example, this small program uses several specific section names:
+@item code_readable
+@cindex @code{code_readable} function attribute, MIPS
+For MIPS targets that support PC-relative addressing modes, this attribute
+can be used to control how an object is addressed. The attribute takes
+a single optional argument:
-@smallexample
-struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @};
-struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @};
-char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @};
-int init_data __attribute__ ((section ("INITDATA")));
+@table @samp
+@item no
+The function should not read the instruction stream as data.
+@item yes
+The function can read the instruction stream as data.
+@item pcrel
+The function can read the instruction stream in a pc-relative mode.
+@end table
-main()
-@{
- /* @r{Initialize stack pointer} */
- init_sp (stack + sizeof (stack));
+If there is no argument supplied, the default of @code{"yes"} applies.
+@end table
- /* @r{Initialize initialized data} */
- memcpy (&init_data, &data, &edata - &data);
+@node MSP430 Attributes
+@subsubsection MSP430 Attributes
- /* @r{Turn on the serial ports} */
- init_duart (&a);
- init_duart (&b);
-@}
-@end smallexample
+These attributes are supported by the MSP430 back end:
-@noindent
-Use the @code{section} attribute with
-@emph{global} variables and not @emph{local} variables,
-as shown in the example.
+@table @code
+@cindex @code{critical} function attribute, MSP430
+@item critical
+Critical functions disable interrupts upon entry and restore the
+previous interrupt state upon exit. Critical functions cannot also
+have the @code{naked}, @code{reentrant} or @code{interrupt} attributes.
-You may use the @code{section} attribute with initialized or
-uninitialized global variables but the linker requires
-each object be defined once, with the exception that uninitialized
-variables tentatively go in the @code{common} (or @code{bss}) section
-and can be multiply ``defined''. Using the @code{section} attribute
-changes what section the variable goes into and may cause the
-linker to issue an error if an uninitialized variable has multiple
-definitions. You can force a variable to be initialized with the
-@option{-fno-common} flag or the @code{nocommon} attribute.
+The MSP430 hardware ensures that interrupts are disabled on entry to
+@code{interrupt} functions, and restores the previous interrupt state
+on exit. The @code{critical} attribute is therefore redundant on
+@code{interrupt} functions.
-Some file formats do not support arbitrary sections so the @code{section}
-attribute is not available on all platforms.
-If you need to map the entire contents of a module to a particular
-section, consider using the facilities of the linker instead.
+@cindex @code{interrupt} function attribute, MSP430
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-@cindex @code{strict_flex_array} variable attribute
-@item strict_flex_array (@var{level})
-The @code{strict_flex_array} attribute should be attached to the trailing
-array field of a structure. It controls when to treat the trailing array
-field of a structure as a flexible array member for the purposes of accessing
-the elements of such an array.
-@var{level} must be an integer between 0 to 3.
+You can provide an argument to the interrupt
+attribute which specifies a name or number. If the argument is a
+number it indicates the slot in the interrupt vector table (0 - 31) to
+which this handler should be assigned. If the argument is a name it
+is treated as a symbolic name for the vector slot. These names should
+match up with appropriate entries in the linker script. By default
+the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and
+@code{reset} for vector 31 are recognized.
-@var{level}=0 is the least strict level, all trailing arrays of structures
-are treated as flexible array members. @var{level}=3 is the strictest level,
-only when the trailing array is declared as a flexible array member per C99
-standard onwards (@samp{[]}), it is treated as a flexible array member.
+@cindex @code{naked} function attribute, MSP430
+@item naked
+This function attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-There are two more levels in between 0 and 3, which are provided to
-support older code that uses the GCC zero-length array extension
-(@samp{[0]}) or one-element array as flexible array members
-(@samp{[1]}). When @var{level} is 1, the trailing array is treated as
-a flexible array member when it is declared as either @samp{[]},
-@samp{[0]}, or @samp{[1]}. When @var{level} is 2, the trailing array
-is treated as a flexible array member when it is declared as either
-@samp{[]}, or @samp{[0]}.
+@cindex @code{reentrant} function attribute, MSP430
+@item reentrant
+Reentrant functions disable interrupts upon entry and enable them
+upon exit. Reentrant functions cannot also have the @code{naked}
+or @code{critical} attributes. They can have the @code{interrupt}
+attribute.
-This attribute can be used with or without the
-@option{-fstrict-flex-arrays} command-line option. When both the
-attribute and the option are present at the same time, the level of
-the strictness for the specific trailing array field is determined by
-the attribute.
+@cindex @code{wakeup} function attribute, MSP430
+@item wakeup
+This attribute only applies to interrupt functions. It is silently
+ignored if applied to a non-interrupt function. A wakeup interrupt
+function will rouse the processor from any low-power state that it
+might be in when the function exits.
-The @code{strict_flex_array} attribute interacts with the
-@option{-Wstrict-flex-arrays} option. @xref{Warning Options}, for more
-information.
+@cindex @code{lower} attribute, MSP430
+@cindex @code{upper} attribute, MSP430
+@cindex @code{either} attribute, MSP430
+@item lower
+@itemx upper
+@itemx either
+On the MSP430 target these attributes can be used to specify whether
+the function or variable should be placed into low memory, high
+memory, or the placement should be left to the linker to decide. The
+attributes are only significant if compiling for the MSP430X
+architecture in the large memory model.
-@cindex @code{tls_model} variable attribute
-@item tls_model ("@var{tls_model}")
-The @code{tls_model} attribute sets thread-local storage model
-(@pxref{Thread-Local}) of a particular @code{__thread} variable,
-overriding @option{-ftls-model=} command-line switch on a per-variable
-basis.
-The @var{tls_model} argument should be one of @code{global-dynamic},
-@code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
+The attributes work in conjunction with a linker script that has been
+augmented to specify where to place sections with a @code{.lower} and
+a @code{.upper} prefix. So, for example, as well as placing the
+@code{.data} section, the script also specifies the placement of a
+@code{.lower.data} and a @code{.upper.data} section. The intention
+is that @code{lower} sections are placed into a small but easier to
+access memory region and the upper sections are placed into a larger, but
+slower to access, region.
-Not all targets support this attribute.
+The @code{either} attribute is special. It tells the linker to place
+the object into the corresponding @code{lower} section if there is
+room for it. If there is insufficient room then the object is placed
+into the corresponding @code{upper} section instead. Note that the
+placement algorithm is not very sophisticated. It does not attempt to
+find an optimal packing of the @code{lower} sections. It just makes
+one pass over the objects and does the best that it can. Using the
+@option{-ffunction-sections} and @option{-fdata-sections} command-line
+options can help the packing, however, since they produce smaller,
+easier to pack regions.
-@cindex @code{unavailable} variable attribute
-@item unavailable
-@itemx unavailable (@var{msg})
-The @code{unavailable} attribute indicates that the variable so marked
-is not available, if it is used anywhere in the source file. It behaves
-in the same manner as the @code{deprecated} attribute except that the
-compiler will emit an error rather than a warning.
+The @code{lower} attribute has some additional functionality when applied
+to variables.
-It is expected that items marked as @code{deprecated} will eventually be
-withdrawn from interfaces, and then become unavailable. This attribute
-allows for marking them appropriately.
+If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
+the @code{section} attribute is applied to a variable, the compiler
+generates 430X instructions to handle it. This is because the compiler has
+to assume that the variable could get placed in the upper memory region
+(above address 0xFFFF). Marking the variable with the @code{lower} attribute
+informs the compiler that the variable is placed in lower memory so it
+is safe to use 430 instructions to handle it.
+In the case of the @code{section} attribute, the section name given
+is used, and the @code{.lower} prefix is not added.
-The @code{unavailable} attribute can also be used for functions and
-types (@pxref{Common Function Attributes},
-@pxref{Common Type Attributes}).
+@end table
-@cindex @code{unused} variable attribute
-@item unused
-This attribute, attached to a variable or structure field, means that
-the variable or field is meant to be possibly unused. GCC does not
-produce a warning for this variable or field.
+@node NDS32 Attributes
+@subsubsection NDS32 Attributes
-@cindex @code{used} variable attribute
-@item used
-This attribute, attached to a variable with static storage, means that
-the variable must be emitted even if it appears that the variable is not
-referenced.
+These function attributes are supported by the NDS32 back end:
-When applied to a static data member of a C++ class template, the
-attribute also means that the member is instantiated if the
-class itself is instantiated.
+@table @code
+@cindex @code{exception} function attribute
+@cindex exception handler functions, NDS32
+@item exception
+Use this attribute on the NDS32 target to indicate that the specified function
+is an exception handler. The compiler will generate corresponding sections
+for use in an exception handler.
-@cindex @code{retain} variable attribute
-@item retain
-For ELF targets that support the GNU or FreeBSD OSABIs, this attribute
-will save the variable from linker garbage collection. To support
-this behavior, variables that have not been placed in specific sections
-(e.g. by the @code{section} attribute, or the @code{-fdata-sections} option),
-will be placed in new, unique sections.
+@cindex @code{interrupt} function attribute, NDS32
+@item interrupt
+On NDS32 target, this attribute indicates that the specified function
+is an interrupt handler. The compiler generates corresponding sections
+for use in an interrupt handler. You can use the following attributes
+to modify the behavior:
+@table @code
+@cindex @code{nested} function attribute, NDS32
+@item nested
+This interrupt service routine is interruptible.
+@cindex @code{not_nested} function attribute, NDS32
+@item not_nested
+This interrupt service routine is not interruptible.
+@cindex @code{nested_ready} function attribute, NDS32
+@item nested_ready
+This interrupt service routine is interruptible after @code{PSW.GIE}
+(global interrupt enable) is set. This allows interrupt service routine to
+finish some short critical code before enabling interrupts.
+@cindex @code{save_all} function attribute, NDS32
+@item save_all
+The system will help save all registers into stack before entering
+interrupt handler.
+@cindex @code{partial_save} function attribute, NDS32
+@item partial_save
+The system will help save caller registers into stack before entering
+interrupt handler.
+@end table
-This additional functionality requires Binutils version 2.36 or later.
+@cindex @code{naked} function attribute, NDS32
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-@cindex @code{uninitialized} variable attribute
-@item uninitialized
-This attribute, attached to a variable with automatic storage, means that
-the variable should not be automatically initialized by the compiler when
-the option @code{-ftrivial-auto-var-init} presents.
+@cindex @code{reset} function attribute, NDS32
+@cindex reset handler functions
+@item reset
+Use this attribute on the NDS32 target to indicate that the specified function
+is a reset handler. The compiler will generate corresponding sections
+for use in a reset handler. You can use the following attributes
+to provide extra exception handling:
+@table @code
+@cindex @code{nmi} function attribute, NDS32
+@item nmi
+Provide a user-defined function to handle NMI exception.
+@cindex @code{warm} function attribute, NDS32
+@item warm
+Provide a user-defined function to handle warm reset exception.
+@end table
+@end table
-With the option @code{-ftrivial-auto-var-init}, all the automatic variables
-that do not have explicit initializers will be initialized by the compiler.
-These additional compiler initializations might incur run-time overhead,
-sometimes dramatically. This attribute can be used to mark some variables
-to be excluded from such automatic initialization in order to reduce runtime
-overhead.
+@node Nvidia PTX Attributes
+@subsubsection Nvidia PTX Attributes
-This attribute has no effect when the option @code{-ftrivial-auto-var-init}
-is not present.
+These function attributes are supported by the Nvidia PTX back end:
-@cindex @code{vector_size} variable attribute
-@item vector_size (@var{bytes})
-This attribute specifies the vector size for the type of the declared
-variable, measured in bytes. The type to which it applies is known as
-the @dfn{base type}. The @var{bytes} argument must be a positive
-power-of-two multiple of the base type size. For example, the declaration:
+@table @code
+@cindex @code{kernel} function attribute, Nvidia PTX
+@item kernel
+This attribute indicates that the corresponding function should be compiled
+as a kernel function, which can be invoked from the host via the CUDA RT
+library.
+By default functions are only callable only from other PTX functions.
-@smallexample
-int foo __attribute__ ((vector_size (16)));
-@end smallexample
+Kernel functions must have @code{void} return type.
-@noindent
-causes the compiler to set the mode for @code{foo}, to be 16 bytes,
-divided into @code{int} sized units. Assuming a 32-bit @code{int},
-@code{foo}'s type is a vector of four units of four bytes each, and
-the corresponding mode of @code{foo} is @code{V4SI}.
-@xref{Vector Extensions}, for details of manipulating vector variables.
+@cindex @code{shared} variable attribute, Nvidia PTX
+@item shared
+Use this attribute to place a variable in the @code{.shared} memory space.
+This memory space is private to each cooperative thread array; only threads
+within one thread block refer to the same instance of the variable.
+The runtime does not initialize variables in this memory space.
+@end table
-This attribute is only applicable to integral and floating scalars,
-although arrays, pointers, and function return values are allowed in
-conjunction with this construct.
+@node PowerPC Attributes
+@subsubsection PowerPC Attributes
-Aggregates with this attribute are invalid, even if they are of the same
-size as a corresponding scalar. For example, the declaration:
+These attributes are supported by the PowerPC back end:
-@smallexample
-struct S @{ int a; @};
-struct S __attribute__ ((vector_size (16))) foo;
-@end smallexample
+@table @code
+@cindex indirect calls, PowerPC
+@cindex @code{longcall} function attribute, PowerPC
+@cindex @code{shortcall} function attribute, PowerPC
+@item longcall
+@itemx shortcall
+The @code{longcall} function attribute
+indicates that the function might be far away from the call site and
+require a different (more expensive) calling sequence. The
+@code{shortcall} attribute indicates that the function is always close
+enough for the shorter calling sequence to be used. These attributes
+override both the @option{-mlongcall} switch and
+the @code{#pragma longcall} setting.
-@noindent
-is invalid even if the size of the structure is the same as the size of
-the @code{int}.
+@xref{RS/6000 and PowerPC Options}, for more information on whether long
+calls are necessary.
-@cindex @code{visibility} variable attribute
-@item visibility ("@var{visibility_type}")
-This attribute affects the linkage of the declaration to which it is attached.
-The @code{visibility} attribute is described in
-@ref{Common Function Attributes}.
+@cindex @code{target} function attribute
+@item target (@var{options})
+As discussed in @ref{Common Attributes}, this function attribute
+allows specification of target-specific compilation options.
-@cindex @code{warn_if_not_aligned} variable attribute
-@item warn_if_not_aligned (@var{alignment})
-This attribute specifies a threshold for the structure field, measured
-in bytes. If the structure field is aligned below the threshold, a
-warning will be issued. For example, the declaration:
+On the PowerPC, the following options are allowed:
-@smallexample
-struct foo
-@{
- int i1;
- int i2;
- unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
-@};
-@end smallexample
+@table @samp
+@cindex @code{target("altivec")} function attribute, PowerPC
+@item altivec
+@itemx no-altivec
+Generate code that uses (does not use) AltiVec instructions. In
+32-bit code, you cannot enable AltiVec instructions unless
+@option{-mabi=altivec} is used on the command line.
-@noindent
-causes the compiler to issue an warning on @code{struct foo}, like
-@samp{warning: alignment 8 of 'struct foo' is less than 16}.
-The compiler also issues a warning, like @samp{warning: 'x' offset
-8 in 'struct foo' isn't aligned to 16}, when the structure field has
-the misaligned offset:
+@cindex @code{target("cmpb")} function attribute, PowerPC
+@item cmpb
+@itemx no-cmpb
+Generate code that uses (does not use) the compare bytes instruction
+implemented on the POWER6 processor and other processors that support
+the PowerPC V2.05 architecture.
-@smallexample
-struct __attribute__ ((aligned (16))) foo
-@{
- int i1;
- int i2;
- unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
-@};
-@end smallexample
+@cindex @code{target("dlmzb")} function attribute, PowerPC
+@item dlmzb
+@itemx no-dlmzb
+Generate code that uses (does not use) the string-search @samp{dlmzb}
+instruction on the IBM 405, 440, 464 and 476 processors. This instruction is
+generated by default when targeting those processors.
-This warning can be disabled by @option{-Wno-if-not-aligned}.
-The @code{warn_if_not_aligned} attribute can also be used for types
-(@pxref{Common Type Attributes}.)
+@cindex @code{target("fprnd")} function attribute, PowerPC
+@item fprnd
+@itemx no-fprnd
+Generate code that uses (does not use) the FP round to integer
+instructions implemented on the POWER5+ processor and other processors
+that support the PowerPC V2.03 architecture.
-@cindex @code{weak} variable attribute
-@item weak
-The @code{weak} attribute is described in
-@ref{Common Function Attributes}.
+@cindex @code{target("hard-dfp")} function attribute, PowerPC
+@item hard-dfp
+@itemx no-hard-dfp
+Generate code that uses (does not use) the decimal floating-point
+instructions implemented on some POWER processors.
-@end table
+@cindex @code{target("isel")} function attribute, PowerPC
+@item isel
+@itemx no-isel
+Generate code that uses (does not use) ISEL instruction.
+
+@cindex @code{target("mfcrf")} function attribute, PowerPC
+@item mfcrf
+@itemx no-mfcrf
+Generate code that uses (does not use) the move from condition
+register field instruction implemented on the POWER4 processor and
+other processors that support the PowerPC V2.01 architecture.
-@node ARC Variable Attributes
-@subsubsection ARC Variable Attributes
+@cindex @code{target("mulhw")} function attribute, PowerPC
+@item mulhw
+@itemx no-mulhw
+Generate code that uses (does not use) the half-word multiply and
+multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors.
+These instructions are generated by default when targeting those
+processors.
-@table @code
-@cindex @code{aux} variable attribute, ARC
-@item aux
-The @code{aux} attribute is used to directly access the ARC's
-auxiliary register space from C. The auxiliary register number is
-given via attribute argument.
+@cindex @code{target("multiple")} function attribute, PowerPC
+@item multiple
+@itemx no-multiple
+Generate code that uses (does not use) the load multiple word
+instructions and the store multiple word instructions.
-@end table
+@cindex @code{target("update")} function attribute, PowerPC
+@item update
+@itemx no-update
+Generate code that uses (does not use) the load or store instructions
+that update the base register to the address of the calculated memory
+location.
-@node AVR Variable Attributes
-@subsubsection AVR Variable Attributes
+@cindex @code{target("popcntb")} function attribute, PowerPC
+@item popcntb
+@itemx no-popcntb
+Generate code that uses (does not use) the popcount and double-precision
+FP reciprocal estimate instruction implemented on the POWER5
+processor and other processors that support the PowerPC V2.02
+architecture.
-@table @code
-@cindex @code{progmem} variable attribute, AVR
-@item progmem
-The @code{progmem} attribute is used on the AVR to place read-only
-data in the non-volatile program memory (flash). The @code{progmem}
-attribute accomplishes this by putting respective variables into a
-section whose name starts with @code{.progmem}.
+@cindex @code{target("popcntd")} function attribute, PowerPC
+@item popcntd
+@itemx no-popcntd
+Generate code that uses (does not use) the popcount instruction
+implemented on the POWER7 processor and other processors that support
+the PowerPC V2.06 architecture.
-This attribute works similar to the @code{section} attribute
-but adds additional checking.
+@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC
+@item powerpc-gfxopt
+@itemx no-powerpc-gfxopt
+Generate code that uses (does not use) the optional PowerPC
+architecture instructions in the Graphics group, including
+floating-point select.
-@table @asis
-@item @bullet{} Ordinary AVR cores with 32 general purpose registers:
-@code{progmem} affects the location
-of the data but not how this data is accessed.
-In order to read data located with the @code{progmem} attribute
-(inline) assembler must be used.
-@smallexample
-/* Use custom macros from AVR-LibC */
-#include <avr/pgmspace.h>
+@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC
+@item powerpc-gpopt
+@itemx no-powerpc-gpopt
+Generate code that uses (does not use) the optional PowerPC
+architecture instructions in the General Purpose group, including
+floating-point square root.
-/* Locate var in flash memory */
-const int var[2] PROGMEM = @{ 1, 2 @};
+@cindex @code{target("recip-precision")} function attribute, PowerPC
+@item recip-precision
+@itemx no-recip-precision
+Assume (do not assume) that the reciprocal estimate instructions
+provide higher-precision estimates than is mandated by the PowerPC
+ABI.
-int read_var (int i)
-@{
- /* Access var[] by accessor macro from avr/pgmspace.h */
- return (int) pgm_read_word (& var[i]);
-@}
-@end smallexample
+@cindex @code{target("string")} function attribute, PowerPC
+@item string
+@itemx no-string
+Generate code that uses (does not use) the load string instructions
+and the store string word instructions to save multiple registers and
+do small block moves.
-AVR is a Harvard architecture processor and data and read-only data
-normally resides in the data memory (RAM).
+@cindex @code{target("vsx")} function attribute, PowerPC
+@item vsx
+@itemx no-vsx
+Generate code that uses (does not use) vector/scalar (VSX)
+instructions, and also enable the use of built-in functions that allow
+more direct access to the VSX instruction set. In 32-bit code, you
+cannot enable VSX or AltiVec instructions unless
+@option{-mabi=altivec} is used on the command line.
-See also the @ref{AVR Named Address Spaces} section for
-an alternate way to locate and access data in flash memory.
+@cindex @code{target("friz")} function attribute, PowerPC
+@item friz
+@itemx no-friz
+Generate (do not generate) the @code{friz} instruction when the
+@option{-funsafe-math-optimizations} option is used to optimize
+rounding a floating-point value to 64-bit integer and back to floating
+point. The @code{friz} instruction does not return the same value if
+the floating-point number is too large to fit in an integer.
-@item @bullet{} AVR cores with flash memory visible in the RAM address range:
-On such devices, there is no need for attribute @code{progmem} or
-@ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all.
-Just use standard C / C++. The compiler will generate @code{LD*}
-instructions. As flash memory is visible in the RAM address range,
-and the default linker script does @emph{not} locate @code{.rodata} in
-RAM, no special features are needed in order not to waste RAM for
-read-only data or to read from flash. You might even get slightly better
-performance by
-avoiding @code{progmem} and @code{__flash}. This applies to devices from
-families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for
-an overview.
+@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC
+@item avoid-indexed-addresses
+@itemx no-avoid-indexed-addresses
+Generate code that tries to avoid (not avoid) the use of indexed load
+or store instructions.
-@item @bullet{} Reduced AVR Tiny cores like ATtiny40:
-The compiler adds @code{0x4000}
-to the addresses of objects and declarations in @code{progmem} and locates
-the objects in flash memory, namely in section @code{.progmem.data}.
-The offset is needed because the flash memory is visible in the RAM
-address space starting at address @code{0x4000}.
+@cindex @code{target("paired")} function attribute, PowerPC
+@item paired
+@itemx no-paired
+Generate code that uses (does not use) the generation of PAIRED simd
+instructions.
-Data in @code{progmem} can be accessed by means of ordinary C@tie{}code,
-no special functions or macros are needed.
+@cindex @code{target("longcall")} function attribute, PowerPC
+@item longcall
+@itemx no-longcall
+Generate code that assumes (does not assume) that all calls are far
+away so that a longer more expensive calling sequence is required.
-@smallexample
-/* var is located in flash memory */
-extern const int var[2] __attribute__((progmem));
+@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC
+@item cpu=@var{CPU}
+Specify the architecture to generate code for when compiling the
+function. If you select the @code{target("cpu=power7")} attribute when
+generating 32-bit code, VSX and AltiVec instructions are not generated
+unless you use the @option{-mabi=altivec} option on the command line.
-int read_var (int i)
-@{
- return var[i];
-@}
-@end smallexample
+@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC
+@item tune=@var{TUNE}
+Specify the architecture to tune for when compiling the function. If
+you do not specify the @code{target("tune=@var{TUNE}")} attribute and
+you do specify the @code{target("cpu=@var{CPU}")} attribute,
+compilation tunes for the @var{CPU} architecture, and not the
+default tuning specified on the command line.
+@end table
-Please notice that on these devices, there is no need for @code{progmem}
-at all.
+On the PowerPC, the inliner does not inline a
+function that has different target options than the caller, unless the
+callee has a subset of the target options of the caller.
-@end table
+@cindex @code{ms_struct} attribute, PowerPC
+@cindex @code{gcc_struct} attribute, PowerPC
+@item ms_struct
+@itemx gcc_struct
+These attributes can be applied to variables and struct declarations.
+For full documentation of the struct attributes please see the
+documentation in @ref{x86 Attributes}.
-@cindex @code{io} variable attribute, AVR
-@item io
-@itemx io (@var{addr})
-Variables with the @code{io} attribute are used to address
-memory-mapped peripherals in the I/O address range.
-No memory is allocated.
-If an address is specified, the variable
-is assigned that address, and the value is interpreted as an
-address in the data address space.
-Example:
+@cindex @code{altivec} attribute, PowerPC
+@item altivec
+The @code{altivec} attribute applies to variables and types.
+It allows you to declare AltiVec vector data
+types supported by the AltiVec Programming Interface Manual. The
+attribute requires an argument to specify one of three vector types:
+@code{vector__}, @code{pixel__} (always followed by unsigned short),
+and @code{bool__} (always followed by unsigned).
@smallexample
-volatile int porta __attribute__((io (__AVR_SFR_OFFSET__ + 0x2)));
+__attribute__((altivec(vector__)))
+__attribute__((altivec(pixel__))) unsigned short
+__attribute__((altivec(bool__))) unsigned
@end smallexample
-Otherwise, the variable is not assigned an address, but the
-compiler will still use @code{in} and @code{out} instructions where applicable,
-assuming some other module assigns an address in the I/O address range.
-Example:
+These attributes mainly are intended to support the @code{__vector},
+@code{__pixel}, and @code{__bool} AltiVec keywords.
+@end table
-@smallexample
-extern volatile int porta __attribute__((io));
-@end smallexample
+@node RISC-V Attributes
+@subsubsection RISC-V Attributes
-@cindex @code{io_low} variable attribute, AVR
-@item io_low
-@itemx io_low (@var{addr})
-This is like the @code{io} attribute, but additionally it informs the
-compiler that the object lies in the lower half of the I/O area,
-allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis}
-instructions.
+These function attributes are supported by the RISC-V back end:
-@cindex @code{address} variable attribute, AVR
-@item address (@var{addr})
-Variables with the @code{address} attribute can be used to address
-memory-mapped peripherals that may lie outside the I/O address range.
-Just like with the @code{io} and @code{io_low} attributes, no memory is
-allocated.
+@table @code
+@cindex @code{naked} function attribute, RISC-V
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-@smallexample
-volatile int porta __attribute__((address (0x600)));
-@end smallexample
+@cindex @code{interrupt} function attribute, RISC-V
+@item interrupt
+Use this attribute to indicate that the specified function is an interrupt
+handler. The compiler generates function entry and exit sequences suitable
+for use in an interrupt handler when this attribute is present.
+
+You can specify the kind of interrupt to be handled by adding an optional
+parameter to the interrupt attribute like this:
-This attribute can also be used to define symbols in C/C++
-code which otherwise would require assembly, a linker description file
-or command-line options like @code{-Wl,--defsym,a_symbol=@var{value}}.
-For example,
-@smallexample
-int a_symbol __attribute__((weak, address (1234)));
-@end smallexample
-will be compiled to
@smallexample
-.weak a_symbol
-a_symbol = 1234
+void f (void) __attribute__ ((interrupt ("supervisor")));
@end smallexample
-@cindex @code{absdata} variable attribute, AVR
-@item absdata
-Variables in static storage and with the @code{absdata} attribute can
-be accessed by the @code{LDS} and @code{STS} instructions which take
-absolute addresses.
-
-@itemize @bullet
-@item
-This attribute is only supported for the reduced AVR Tiny core
-like ATtiny40.
+Permissible values for this parameter are @code{supervisor},
+@code{machine}, and @code{rnmi}. If there is no parameter, then it
+defaults to @code{machine}.
-@item
-You must make sure that respective data is located in the
-address range @code{0x40}@dots{}@code{0xbf} accessible by
-@code{LDS} and @code{STS}. One way to achieve this as an
-appropriate linker description file.
+@cindex @code{riscv_vector_cc} function attribute, RISC-V
+@item riscv_vector_cc
+Use this attribute to force the function to use the vector calling
+convention variant.
-@item
-If the location does not fit the address range of @code{LDS}
-and @code{STS}, there is currently (Binutils 2.26) just an unspecific
-warning like
-@quotation
-@code{module.cc:(.text+0x1c): warning: internal error: out of range error}
-@end quotation
+@smallexample
+void foo() __attribute__((riscv_vector_cc));
+[[riscv::vector_cc]] void foo(); // For C++11 and C23
+@end smallexample
-@end itemize
+@end table
-See also the @option{-mabsdata} @ref{AVR Options,command-line option}.
+The following target-specific function attributes are available for the
+RISC-V target. For the most part, these options mirror the behavior of
+similar command-line options (@pxref{RISC-V Options}), but on a
+per-function basis.
-@end table
+@table @code
+@cindex @code{arch=} function attribute, RISC-V
+@item arch=
+Specifies the architecture version and architectural extensions to use
+for this function. The behavior and permissible arguments are the same as
+for the @option{-march=} command-line option, in addtion, it also support
+extension enablement list, a list of extension name and prefixed with @code{+},
+like @code{arch=+zba} means enable @code{zba} extension.
+Multiple extension can be enabled by separating them with a comma. For example:
+@code{arch=+zba,+zbb}.
-@node Blackfin Variable Attributes
-@subsubsection Blackfin Variable Attributes
+@cindex @code{tune=} function attribute, RISC-V
+@item tune=
+Specifies the core for which to tune the performance of this function.
+The behavior and permissible arguments are the same as for the @option{-mtune=}
+command-line option.
-Three attributes are currently defined for the Blackfin.
+@cindex @code{cpu=} function attribute, RISC-V
+@item cpu=
+Specifies the core for which to tune the performance of this function and also
+whose architectural features to use. The behavior and valid arguments are the
+same as for the @option{-mcpu=} command-line option.
-@table @code
-@cindex @code{l1_data} variable attribute, Blackfin
-@cindex @code{l1_data_A} variable attribute, Blackfin
-@cindex @code{l1_data_B} variable attribute, Blackfin
-@item l1_data
-@itemx l1_data_A
-@itemx l1_data_B
-Use these attributes on the Blackfin to place the variable into L1 Data SRAM.
-Variables with @code{l1_data} attribute are put into the specific section
-named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into
-the specific section named @code{.l1.data.A}. Those with @code{l1_data_B}
-attribute are put into the specific section named @code{.l1.data.B}.
+@cindex @code{max-vectorization} function attribute, RISC-V
+@item max-vectorization
+@itemx no-max-vectorization
+@code{max-vectorization} tells GCC's vectorizer to treat all vector
+loops as being more profitable than the original scalar loops when
+optimizing the current function. @code{no-max-vectorization} disables
+this behavior.
+This corresponds to the behavior of the command-line options
+@option{-mmax-vectorization} and @option{-mno-max-vectorization}.
-@cindex @code{l2} variable attribute, Blackfin
-@item l2
-Use this attribute on the Blackfin to place the variable into L2 SRAM.
-Variables with @code{l2} attribute are put into the specific section
-named @code{.l2.data}.
@end table
-@node H8/300 Variable Attributes
-@subsubsection H8/300 Variable Attributes
+The above target attributes can be specified as follows:
-These variable attributes are available for H8/300 targets:
+@smallexample
+__attribute__((target("@var{attr-string}")))
+int
+f (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-@table @code
-@cindex @code{eightbit_data} variable attribute, H8/300
-@cindex eight-bit data on the H8/300, H8/300H, and H8S
-@item eightbit_data
-Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified
-variable should be placed into the eight-bit data section.
-The compiler generates more efficient code for certain operations
-on data in the eight-bit data area. Note the eight-bit data area is limited to
-256 bytes of data.
+where @code{@var{attr-string}} is one of the attribute strings specified above.
-@cindex @code{tiny_data} variable attribute, H8/300
-@cindex tiny data section on the H8/300H and H8S
-@item tiny_data
-Use this attribute on the H8/300H and H8S to indicate that the specified
-variable should be placed into the tiny data section.
-The compiler generates more efficient code for loads and stores
-on data in the tiny data section. Note the tiny data area is limited to
-slightly under 32KB of data.
+Multiple target function attributes can be specified by separating them with
+a semicolon. For example:
+@smallexample
+__attribute__((target("arch=+zba,+zbb;tune=rocket")))
+int
+foo (int a)
+@{
+ return a + 5;
+@}
+@end smallexample
-@end table
+is valid and compiles function @code{foo} with @code{zba}
+and @code{zbb} extensions and tunes it for @code{rocket}.
-@node IA-64 Variable Attributes
-@subsubsection IA-64 Variable Attributes
+@node RL78 Attributes
+@subsubsection RL78 Attributes
-The IA-64 back end supports the following variable attribute:
+These attributes are supported by the RL78 back end:
@table @code
-@cindex @code{model} variable attribute, IA-64
-@item model (@var{model-name})
+@cindex @code{interrupt} function attribute, RL78
+@cindex @code{brk_interrupt} function attribute, RL78
+@item interrupt
+@itemx brk_interrupt
+These attributes indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-On IA-64, use this attribute to set the addressability of an object.
-At present, the only supported identifier for @var{model-name} is
-@code{small}, indicating addressability via ``small'' (22-bit)
-addresses (so that their addresses can be loaded with the @code{addl}
-instruction). Caveat: such addressing is by definition not position
-independent and hence this attribute must not be used for objects
-defined by shared libraries.
+Use @code{brk_interrupt} instead of @code{interrupt} for
+handlers intended to be used with the @code{BRK} opcode (i.e.@: those
+that must end with @code{RETB} instead of @code{RETI}).
+
+@cindex @code{naked} function attribute, RL78
+@item naked
+This function attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
+
+@cindex @code{saddr} variable attribute, RL78
+@item saddr
+The RL78 back end supports the @code{saddr} variable attribute. This
+specifies placement of the corresponding variable in the SADDR area,
+which can be accessed more efficiently than the default memory region.
@end table
-@node LoongArch Variable Attributes
-@subsubsection LoongArch Variable Attributes
+@node RX Attributes
+@subsubsection RX Attributes
-One attribute is currently defined for the LoongArch.
+These function attributes are supported by the RX back end:
@table @code
-@cindex @code{model} variable attribute, LoongArch
-@item model("@var{name}")
-Use this attribute on the LoongArch to use a different code model for
-addressing this variable, than the code model specified by the global
-@option{-mcmodel} option. This attribute is mostly useful if a
-@code{section} attribute and/or a linker script will locate this object
-specially. Currently the only supported values of @var{name} are
-@code{normal} and @code{extreme}.
-@end table
+@cindex @code{fast_interrupt} function attribute, RX
+@item fast_interrupt
+Use this attribute on the RX port to indicate that the specified
+function is a fast interrupt handler. This is just like the
+@code{interrupt} attribute, except that @code{freit} is used to return
+instead of @code{reit}.
-@node M32R/D Variable Attributes
-@subsubsection M32R/D Variable Attributes
+@cindex @code{interrupt} function attribute, RX
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
-One attribute is currently defined for the M32R/D@.
+On RX and RL78 targets, you may specify one or more vector numbers as arguments
+to the attribute, as well as naming an alternate table name.
+Parameters are handled sequentially, so one handler can be assigned to
+multiple entries in multiple tables. One may also pass the magic
+string @code{"$default"} which causes the function to be used for any
+unfilled slots in the current table.
-@table @code
-@cindex @code{model-name} variable attribute, M32R/D
-@cindex variable addressability on the M32R/D
-@item model (@var{model-name})
-Use this attribute on the M32R/D to set the addressability of an object.
-The identifier @var{model-name} is one of @code{small}, @code{medium},
-or @code{large}, representing each of the code models.
+This example shows a simple assignment of a function to one vector in
+the default table (note that preprocessor macros may be used for
+chip-specific symbolic vector names):
+@smallexample
+void __attribute__ ((interrupt (5))) txd1_handler ();
+@end smallexample
-Small model objects live in the lower 16MB of memory (so that their
-addresses can be loaded with the @code{ld24} instruction).
+This example assigns a function to two slots in the default table
+(using preprocessor macros defined elsewhere) and makes it the default
+for the @code{dct} table:
+@smallexample
+void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default")))
+ txd1_handler ();
+@end smallexample
-Medium and large model objects may live anywhere in the 32-bit address space
-(the compiler generates @code{seth/add3} instructions to load their
-addresses).
+@cindex @code{naked} function attribute, RX
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
+
+@cindex @code{vector} function attribute, RX
+@item vector
+This RX attribute is similar to the @code{interrupt} attribute, including its
+parameters, but does not make the function an interrupt-handler type
+function (i.e.@: it retains the normal C function calling ABI). See the
+@code{interrupt} attribute for a description of its arguments.
@end table
-@node Microsoft Windows Variable Attributes
-@subsubsection Microsoft Windows Variable Attributes
+@node S/390 Attributes
+@subsubsection S/390 Attributes
-You can use these attributes on Microsoft Windows targets.
-@ref{x86 Variable Attributes} for additional Windows compatibility
-attributes available on all x86 targets.
+These function attributes are supported on the S/390:
@table @code
-@cindex @code{dllimport} variable attribute
-@cindex @code{dllexport} variable attribute
-@item dllimport
-@itemx dllexport
-The @code{dllimport} and @code{dllexport} attributes are described in
-@ref{Microsoft Windows Function Attributes}.
-
-@cindex @code{selectany} variable attribute
-@item selectany
-The @code{selectany} attribute causes an initialized global variable to
-have link-once semantics. When multiple definitions of the variable are
-encountered by the linker, the first is selected and the remainder are
-discarded. Following usage by the Microsoft compiler, the linker is told
-@emph{not} to warn about size or content differences of the multiple
-definitions.
+@cindex @code{hotpatch} function attribute, S/390
+@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label})
-Although the primary usage of this attribute is for POD types, the
-attribute can also be applied to global C++ objects that are initialized
-by a constructor. In this case, the static initialization and destruction
-code for the object is emitted in each translation defining the object,
-but the calls to the constructor and destructor are protected by a
-link-once guard variable.
+On S/390 System z targets, you can use this function attribute to
+make GCC generate a ``hot-patching'' function prologue. If the
+@option{-mhotpatch=} command-line option is used at the same time,
+the @code{hotpatch} attribute takes precedence. The first of the
+two arguments specifies the number of halfwords to be added before
+the function label. A second argument can be used to specify the
+number of halfwords to be added after the function label. For
+both arguments the maximum allowed value is 1000000.
-The @code{selectany} attribute is only available on Microsoft Windows
-targets. You can use @code{__declspec (selectany)} as a synonym for
-@code{__attribute__ ((selectany))} for compatibility with other
-compilers.
+If both arguments are zero, hotpatching is disabled.
-@cindex @code{shared} variable attribute
-@item shared
-On Microsoft Windows, in addition to putting variable definitions in a named
-section, the section can also be shared among all running copies of an
-executable or DLL@. For example, this small program defines shared data
-by putting it in a named section @code{shared} and marking the section
-shareable:
+@cindex @code{target} function attribute
+@item target (@var{options})
+As discussed in @ref{Common Attributes}, this attribute
+allows specification of target-specific compilation options.
-@smallexample
-int foo __attribute__((section ("shared"), shared)) = 0;
+On S/390, the following options are supported:
-int
-main()
-@{
- /* @r{Read and write foo. All running
- copies see the same value.} */
- return 0;
-@}
-@end smallexample
+@table @samp
+@item arch=
+@item tune=
+@item stack-guard=
+@item stack-size=
+@item branch-cost=
+@item warn-framesize=
+@item backchain
+@itemx no-backchain
+@item hard-dfp
+@itemx no-hard-dfp
+@item hard-float
+@itemx soft-float
+@item htm
+@itemx no-htm
+@item vx
+@itemx no-vx
+@item packed-stack
+@itemx no-packed-stack
+@item small-exec
+@itemx no-small-exec
+@item mvcle
+@itemx no-mvcle
+@item warn-dynamicstack
+@itemx no-warn-dynamicstack
+@end table
-@noindent
-You may only use the @code{shared} attribute along with @code{section}
-attribute with a fully-initialized global definition because of the way
-linkers work. See @code{section} attribute for more information.
+The options work exactly like the S/390 specific command line
+options (without the prefix @option{-m}) except that they do not
+change any feature macros. For example,
-The @code{shared} attribute is only available on Microsoft Windows@.
+@smallexample
+@code{target("no-vx")}
+@end smallexample
+does not undefine the @code{__VEC__} macro.
@end table
-@node MSP430 Variable Attributes
-@subsubsection MSP430 Variable Attributes
+@node SH Attributes
+@subsubsection SH Attributes
-@table @code
-@cindex @code{upper} variable attribute, MSP430
-@cindex @code{either} variable attribute, MSP430
-@item upper
-@itemx either
-These attributes are the same as the MSP430 function attributes of the
-same name (@pxref{MSP430 Function Attributes}).
+These function attributes are supported on the SH family of processors:
-@cindex @code{lower} variable attribute, MSP430
-@item lower
-This option behaves mostly the same as the MSP430 function attribute of the
-same name (@pxref{MSP430 Function Attributes}), but it has some additional
-functionality.
+@table @code
+@cindex @code{function_vector} function attribute, SH
+@cindex calling functions through the function vector on SH2A
+@item function_vector
+On SH2A targets, this attribute declares a function to be called using the
+TBR relative addressing mode. The argument to this attribute is the entry
+number of the same function in a vector table containing all the TBR
+relative addressable functions. For correct operation the TBR must be setup
+accordingly to point to the start of the vector table before any functions with
+this attribute are invoked. Usually a good place to do the initialization is
+the startup routine. The TBR relative vector table can have at max 256 function
+entries. The jumps to these functions are generated using a SH2A specific,
+non delayed branch instruction JSR/N @@(disp8,TBR).
-If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or
-the @code{section} attribute is applied to a variable, the compiler will
-generate 430X instructions to handle it. This is because the compiler has
-to assume that the variable could get placed in the upper memory region
-(above address 0xFFFF). Marking the variable with the @code{lower} attribute
-informs the compiler that the variable will be placed in lower memory so it
-is safe to use 430 instructions to handle it.
+In an application, for a function being called once, this attribute
+saves at least 8 bytes of code; and if other successive calls are being
+made to the same function, it saves 2 bytes of code per each of these
+calls.
-In the case of the @code{section} attribute, the section name given
-will be used, and the @code{.lower} prefix will not be added.
+@cindex @code{interrupt_handler} function attribute, SH
+@item interrupt_handler
+Use this attribute to
+indicate that the specified function is an interrupt handler. The compiler
+generates function entry and exit sequences suitable for use in an
+interrupt handler when this attribute is present.
-@end table
+@cindex @code{nosave_low_regs} function attribute, SH
+@item nosave_low_regs
+Use this attribute on SH targets to indicate that an @code{interrupt_handler}
+function should not save and restore registers R0..R7. This can be used on SH3*
+and SH4* targets that have a second R0..R7 register bank for non-reentrant
+interrupt handlers.
-@node Nvidia PTX Variable Attributes
-@subsubsection Nvidia PTX Variable Attributes
+@cindex @code{renesas} function attribute, SH
+@item renesas
+On SH targets this attribute specifies that the function or struct follows the
+Renesas ABI.
-These variable attributes are supported by the Nvidia PTX back end:
+@cindex @code{resbank} function attribute, SH
+@item resbank
+On the SH2A target, this attribute enables the high-speed register
+saving and restoration using a register bank for @code{interrupt_handler}
+routines. Saving to the bank is performed automatically after the CPU
+accepts an interrupt that uses a register bank.
-@table @code
-@cindex @code{shared} variable attribute, Nvidia PTX
-@item shared
-Use this attribute to place a variable in the @code{.shared} memory space.
-This memory space is private to each cooperative thread array; only threads
-within one thread block refer to the same instance of the variable.
-The runtime does not initialize variables in this memory space.
-@end table
+The nineteen 32-bit registers comprising general register R0 to R14,
+control register GBR, and system registers MACH, MACL, and PR and the
+vector table address offset are saved into a register bank. Register
+banks are stacked in first-in last-out (FILO) sequence. Restoration
+from the bank is executed by issuing a RESBANK instruction.
-@node PowerPC Variable Attributes
-@subsubsection PowerPC Variable Attributes
+@cindex @code{sp_switch} function attribute, SH
+@item sp_switch
+Use this attribute on the SH to indicate an @code{interrupt_handler}
+function should switch to an alternate stack. It expects a string
+argument that names a global variable holding the address of the
+alternate stack.
-Three attributes currently are defined for PowerPC configurations:
-@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
+@smallexample
+void *alt_stack;
+void f () __attribute__ ((interrupt_handler,
+ sp_switch ("alt_stack")));
+@end smallexample
-@cindex @code{ms_struct} variable attribute, PowerPC
-@cindex @code{gcc_struct} variable attribute, PowerPC
-For full documentation of the struct attributes please see the
-documentation in @ref{x86 Variable Attributes}.
+@cindex @code{trap_exit} function attribute, SH
+@item trap_exit
+Use this attribute on the SH for an @code{interrupt_handler} to return using
+@code{trapa} instead of @code{rte}. This attribute expects an integer
+argument specifying the trap number to be used.
-@cindex @code{altivec} variable attribute, PowerPC
-For documentation of @code{altivec} attribute please see the
-documentation in @ref{PowerPC Type Attributes}.
+@cindex @code{trapa_handler} function attribute, SH
+@item trapa_handler
+On SH targets this function attribute is similar to @code{interrupt_handler}
+but it does not save and restore all registers.
+@end table
-@node RL78 Variable Attributes
-@subsubsection RL78 Variable Attributes
+@node Symbian OS Attributes
+@subsubsection Symbian OS Attributes
-@cindex @code{saddr} variable attribute, RL78
-The RL78 back end supports the @code{saddr} variable attribute. This
-specifies placement of the corresponding variable in the SADDR area,
-which can be accessed more efficiently than the default memory region.
+@xref{Microsoft Windows Attributes}, for discussion of the
+@code{dllexport} and @code{dllimport} attributes.
-@node V850 Variable Attributes
-@subsubsection V850 Variable Attributes
+@node V850 Attributes
+@subsubsection V850 Attributes
-These variable attributes are supported by the V850 back end:
+The V850 back end supports these attributes:
@table @code
+@cindex @code{interrupt} function attribute, V850
+@cindex @code{interrupt_handler} function attribute, V850
+@item interrupt
+@itemx interrupt_handler
+Use these attributes to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when either attribute is present.
@cindex @code{sda} variable attribute, V850
@item sda
of memory.
@end table
-@node x86 Variable Attributes
-@subsubsection x86 Variable Attributes
+@node Visium Attributes
+@subsubsection Visium Attributes
-Two attributes are currently defined for x86 configurations:
-@code{ms_struct} and @code{gcc_struct}.
+These function attributes are supported by the Visium back end:
@table @code
-@cindex @code{ms_struct} variable attribute, x86
-@cindex @code{gcc_struct} variable attribute, x86
-@item ms_struct
-@itemx gcc_struct
+@cindex @code{interrupt} function attribute, Visium
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+@end table
-If @code{packed} is used on a structure, or if bit-fields are used,
-it may be that the Microsoft ABI lays out the structure differently
-than the way GCC normally does. Particularly when moving packed
-data between functions compiled with GCC and the native Microsoft compiler
-(either via function call or as data in a file), it may be necessary to access
-either format.
+@node x86 Attributes
+@subsubsection x86 Attributes
-The @code{ms_struct} and @code{gcc_struct} attributes correspond
-to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
-command-line options, respectively;
-see @ref{x86 Options}, for details of how structure layout is affected.
-@xref{x86 Type Attributes}, for information about the corresponding
-attributes on types.
+These attributes are supported by the x86 back end:
-@end table
+@table @code
+@cindex @code{cdecl} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@opindex mrtd
+@item cdecl
+On the x86-32 targets, the @code{cdecl} attribute causes the compiler to
+assume that the calling function pops off the stack space used to
+pass arguments. This is
+useful to override the effects of the @option{-mrtd} switch.
+
+@cindex @code{fastcall} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@item fastcall
+On x86-32 targets, the @code{fastcall} attribute causes the compiler to
+pass the first argument (if of integral type) in the register ECX and
+the second argument (if of integral type) in the register EDX@. Subsequent
+and other typed arguments are passed on the stack. The called function
+pops the arguments off the stack. If the number of arguments is variable all
+arguments are pushed on the stack.
+
+@cindex @code{thiscall} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@item thiscall
+On x86-32 targets, the @code{thiscall} attribute causes the compiler to
+pass the first argument (if of integral type) in the register ECX.
+Subsequent and other typed arguments are passed on the stack. The called
+function pops the arguments off the stack.
+If the number of arguments is variable all arguments are pushed on the
+stack.
+The @code{thiscall} attribute is intended for C++ non-static member functions.
+As a GCC extension, this calling convention can be used for C functions
+and for static member methods.
-@node Xstormy16 Variable Attributes
-@subsubsection Xstormy16 Variable Attributes
+@cindex @code{ms_abi} function attribute, x86
+@cindex @code{sysv_abi} function attribute, x86
+@item ms_abi
+@itemx sysv_abi
-One attribute is currently defined for xstormy16 configurations:
-@code{below100}.
+On 32-bit and 64-bit x86 targets, you can use an ABI attribute
+to indicate which calling convention should be used for a function. The
+@code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
+while the @code{sysv_abi} attribute tells the compiler to use the System V
+ELF ABI, which is used on GNU/Linux and other systems. The default is to use
+the Microsoft ABI when targeting Windows. On all other systems, the default
+is the System V ELF ABI.
-@table @code
-@cindex @code{below100} variable attribute, Xstormy16
-@item below100
+Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
+requires the @option{-maccumulate-outgoing-args} option.
-If a variable has the @code{below100} attribute (@code{BELOW100} is
-allowed also), GCC places the variable in the first 0x100 bytes of
-memory and use special opcodes to access it. Such variables are
-placed in either the @code{.bss_below100} section or the
-@code{.data_below100} section.
+@cindex @code{callee_pop_aggregate_return} function attribute, x86
+@item callee_pop_aggregate_return (@var{number})
-@end table
+On x86-32 targets, you can use this attribute to control how
+aggregates are returned in memory. If the caller is responsible for
+popping the hidden pointer together with the rest of the arguments, specify
+@var{number} equal to zero. If callee is responsible for popping the
+hidden pointer, specify @var{number} equal to one.
+
+The default x86-32 ABI assumes that the callee pops the
+stack for hidden pointer. However, on x86-32 Microsoft Windows targets,
+the compiler assumes that the
+caller pops the stack for hidden pointer.
-@node Type Attributes
-@subsection Specifying Attributes of Types
-@cindex attribute of types
-@cindex type attributes
+@cindex @code{ms_hook_prologue} function attribute, x86
+@item ms_hook_prologue
+
+On 32-bit and 64-bit x86 targets, you can use
+this function attribute to make GCC generate the ``hot-patching'' function
+prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2
+and newer.
-You can use attributes to specify various special
-properties of types. Some type attributes apply only to structure and
-union types, and in C++, also class types, while others can apply to
-any type defined via a @code{typedef} declaration. Unless otherwise
-specified, the same restrictions and effects apply to attributes regardless
-of whether a type is a trivial structure or a C++ class with user-defined
-constructors, destructors, or a copy assignment.
+@cindex @code{naked} function attribute, x86
+@item naked
+This attribute allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of
+basic @code{asm} and C code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
-Other attributes are defined for functions (@pxref{Function Attributes}),
-labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
-Attributes}), statements (@pxref{Statement Attributes}), and for variables
-(@pxref{Variable Attributes}).
+@cindex @code{regparm} function attribute, x86
+@cindex functions that are passed arguments in registers on x86-32
+@item regparm (@var{number})
+On x86-32 targets, the @code{regparm} attribute causes the compiler to
+pass arguments number one to @var{number} if they are of integral type
+in registers EAX, EDX, and ECX instead of on the stack. Functions that
+take a variable number of arguments continue to be passed all of their
+arguments on the stack.
-GCC provides two different ways to specify attributes: the traditional
-GNU syntax using @samp{__attribute__ ((...))} annotations, and the
-newer standard C and C++ syntax using @samp{[[...]]} with the
-@samp{gnu::} prefix on attribute names. Note that the exact rules for
-placement of attributes in your source code are different depending on
-which syntax you use. @xref{GNU Attribute Syntax}, for details.
-
-You may specify type attributes in an enum, struct or union type
-declaration or definition by placing them immediately after the
-@code{struct}, @code{union} or @code{enum} keyword. You can also place
-them just past the closing curly brace of the definition, but this is less
-preferred because logically the type should be fully defined at
-the closing brace. You can also include type attributes in a
-@code{typedef} declaration.
+Beware that on some ELF systems this attribute is unsuitable for
+global functions in shared libraries with lazy binding (which is the
+default). Lazy binding sends the first call via resolving code in
+the loader, which might assume EAX, EDX and ECX can be clobbered, as
+per the standard calling conventions. Solaris 8 is affected by this.
+Systems with the GNU C Library version 2.1 or higher
+and FreeBSD are believed to be
+safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be
+disabled with the linker or the loader if desired, to avoid the
+problem.)
+
+@cindex @code{sseregparm} function attribute, x86
+@item sseregparm
+On x86-32 targets with SSE support, the @code{sseregparm} attribute
+causes the compiler to pass up to 3 floating-point arguments in
+SSE registers instead of on the stack. Functions that take a
+variable number of arguments continue to pass all of their
+floating-point arguments on the stack.
+
+@cindex @code{force_align_arg_pointer} function attribute, x86
+@item force_align_arg_pointer
+On x86 targets, the @code{force_align_arg_pointer} attribute may be
+applied to individual function definitions, generating an alternate
+prologue and epilogue that realigns the run-time stack if necessary.
+This supports mixing legacy codes that run with a 4-byte aligned stack
+with modern codes that keep a 16-byte stack for SSE compatibility.
+
+@cindex @code{stdcall} function attribute, x86-32
+@cindex functions that pop the argument stack on x86-32
+@item stdcall
+On x86-32 targets, the @code{stdcall} attribute causes the compiler to
+assume that the called function pops off the stack space used to
+pass arguments, unless it takes a variable number of arguments.
-@menu
-* Common Type Attributes::
-* ARC Type Attributes::
-* ARM Type Attributes::
-* BPF Type Attributes::
-* PowerPC Type Attributes::
-* x86 Type Attributes::
-@end menu
+@cindex @code{no_callee_saved_registers} function attribute, x86
+@item no_callee_saved_registers
+Use this attribute to indicate that the specified function has no
+callee-saved registers. That is, all registers, except for stack and
+frame pointers, can be used as scratch registers. For example, this
+attribute can be used for a function called from the interrupt handler
+assembly stub which will preserve all registers and return from
+interrupt.
-@node Common Type Attributes
-@subsubsection Common Type Attributes
+@cindex @code{preserve_none} function attribute, x86
+@item preserve_none
+This attribute is similar to @code{no_callee_saved_registers}, except
+on x86-64, r12, r13, r14, r15, rdi and rsi registers are used for
+integer parameter passing and this calling convention is subject to
+change.
-The following type attributes are supported on most targets.
+@cindex @code{no_caller_saved_registers} function attribute, x86
+@item no_caller_saved_registers
+Use this attribute to indicate that the specified function has no
+caller-saved registers. That is, all registers are callee-saved. For
+example, this attribute can be used for a function called from an
+interrupt handler. The compiler generates proper function entry and
+exit sequences to save and restore any modified registers, except for
+the EFLAGS register. Since GCC doesn't preserve YMM nor ZMM registers,
+@code{no_caller_saved_registers} attribute can't be used on functions
+with AVX enabled. Note that MMX and x87 registers aren't preserved by
+@code{no_caller_saved_registers} attribute.
-@table @code
-@c Keep this table alphabetized by attribute name. Treat _ as space.
+@cindex @code{interrupt} function attribute, x86
+@item interrupt
+Use this attribute to indicate that the specified function is an
+interrupt handler or an exception handler (depending on parameters passed
+to the function, explained further). The compiler generates function
+entry and exit sequences suitable for use in an interrupt handler when
+this attribute is present. The @code{IRET} instruction, instead of the
+@code{RET} instruction, is used to return from interrupt handlers. All
+registers, except for the EFLAGS register which is restored by the
+@code{IRET} instruction, are preserved by the compiler. Since GCC
+doesn't preserve SSE, MMX nor x87 states, the GCC option
+@option{-mgeneral-regs-only} should be used to compile interrupt and
+exception handlers.
-@cindex @code{aligned} type attribute
-@item aligned
-@itemx aligned (@var{alignment})
-The @code{aligned} attribute specifies a minimum alignment (in bytes) for
-variables of the specified type. When specified, @var{alignment} must be
-a power of 2. Specifying no @var{alignment} argument implies the maximum
-alignment for the target, which is often, but by no means always, 8 or 16
-bytes. For example, the declarations:
+Any interruptible-without-stack-switch code must be compiled with
+@option{-mno-red-zone} since interrupt handlers can and will, because
+of the hardware design, touch the red zone.
+
+An interrupt handler must be declared with a mandatory pointer
+argument:
@smallexample
-struct __attribute__ ((aligned (8))) S @{ short f[3]; @};
-typedef int more_aligned_int __attribute__ ((aligned (8)));
+struct interrupt_frame;
+
+__attribute__ ((interrupt))
+void
+f (struct interrupt_frame *frame)
+@{
+@}
@end smallexample
@noindent
-force the compiler to ensure (as far as it can) that each variable whose
-type is @code{struct S} or @code{more_aligned_int} is allocated and
-aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all
-variables of type @code{struct S} aligned to 8-byte boundaries allows
-the compiler to use the @code{ldd} and @code{std} (doubleword load and
-store) instructions when copying one variable of type @code{struct S} to
-another, thus improving run-time efficiency.
-
-Note that the alignment of any given @code{struct} or @code{union} type
-is required by the ISO C standard to be at least a perfect multiple of
-the lowest common multiple of the alignments of all of the members of
-the @code{struct} or @code{union} in question. This means that you @emph{can}
-effectively adjust the alignment of a @code{struct} or @code{union}
-type by attaching an @code{aligned} attribute to any one of the members
-of such a type, but the notation illustrated in the example above is a
-more obvious, intuitive, and readable way to request the compiler to
-adjust the alignment of an entire @code{struct} or @code{union} type.
+and you must define @code{struct interrupt_frame} as described in the
+processor's manual.
-As in the preceding example, you can explicitly specify the alignment
-(in bytes) that you wish the compiler to use for a given @code{struct}
-or @code{union} type. Alternatively, you can leave out the alignment factor
-and just ask the compiler to align a type to the maximum
-useful alignment for the target machine you are compiling for. For
-example, you could write:
+Exception handlers differ from interrupt handlers because the system
+pushes an error code on the stack. An exception handler declaration is
+similar to that for an interrupt handler, but with a different mandatory
+function signature. The compiler arranges to pop the error code off the
+stack before the @code{IRET} instruction.
@smallexample
-struct __attribute__ ((aligned)) S @{ short f[3]; @};
-@end smallexample
+#ifdef __x86_64__
+typedef unsigned long long int uword_t;
+#else
+typedef unsigned int uword_t;
+#endif
-Whenever you leave out the alignment factor in an @code{aligned}
-attribute specification, the compiler automatically sets the alignment
-for the type to the largest alignment that is ever used for any data
-type on the target machine you are compiling for. Doing this can often
-make copy operations more efficient, because the compiler can use
-whatever instructions copy the biggest chunks of memory when performing
-copies to or from the variables that have types that you have aligned
-this way.
+struct interrupt_frame;
-In the example above, if the size of each @code{short} is 2 bytes, then
-the size of the entire @code{struct S} type is 6 bytes. The smallest
-power of two that is greater than or equal to that is 8, so the
-compiler sets the alignment for the entire @code{struct S} type to 8
-bytes.
-
-Note that although you can ask the compiler to select a time-efficient
-alignment for a given type and then declare only individual stand-alone
-objects of that type, the compiler's ability to select a time-efficient
-alignment is primarily useful only when you plan to create arrays of
-variables having the relevant (efficiently aligned) type. If you
-declare or use arrays of variables of an efficiently-aligned type, then
-it is likely that your program also does pointer arithmetic (or
-subscripting, which amounts to the same thing) on pointers to the
-relevant type, and the code that the compiler generates for these
-pointer arithmetic operations is often more efficient for
-efficiently-aligned types than for other types.
-
-Note that the effectiveness of @code{aligned} attributes may be limited
-by inherent limitations in your linker. On many systems, the linker is
-only able to arrange for variables to be aligned up to a certain maximum
-alignment. (For some linkers, the maximum supported alignment may
-be very very small.) If your linker is only able to align variables
-up to a maximum of 8-byte alignment, then specifying @code{aligned (16)}
-in an @code{__attribute__} still only provides you with 8-byte
-alignment. See your linker documentation for further information.
+__attribute__ ((interrupt))
+void
+f (struct interrupt_frame *frame, uword_t error_code)
+@{
+ ...
+@}
+@end smallexample
-When used on a struct, or struct member, the @code{aligned} attribute can
-only increase the alignment; in order to decrease it, the @code{packed}
-attribute must be specified as well. When used as part of a typedef, the
-@code{aligned} attribute can both increase and decrease alignment, and
-specifying the @code{packed} attribute generates a warning.
+Exception handlers should only be used for exceptions that push an error
+code; you should use an interrupt handler in other cases. The system
+will crash if the wrong kind of handler is used.
-@cindex @code{alloc_size} type attribute
-@item alloc_size (@var{position})
-@itemx alloc_size (@var{position-1}, @var{position-2})
-The @code{alloc_size} type attribute may be applied to the definition
-of a type of a function that returns a pointer and takes at least one
-argument of an integer type. It indicates that the returned pointer
-points to an object whose size is given by the function argument at
-@var{position-1}, or by the product of the arguments at @var{position-1}
-and @var{position-2}. Meaningful sizes are positive values less than
-@code{PTRDIFF_MAX}. Other sizes are diagnosed when detected. GCC uses
-this information to improve the results of @code{__builtin_object_size}.
+@cindex @code{target} function attribute
+@item target (@var{options})
+As discussed in @ref{Common Attributes}, this attribute
+allows specification of target-specific compilation options.
-For instance, the following declarations
+On the x86, the following options are allowed:
+@table @samp
+@cindex @code{target("3dnow")} function attribute, x86
+@item 3dnow
+@itemx no-3dnow
+Enable/disable the generation of the 3DNow!@: instructions.
-@smallexample
-typedef __attribute__ ((alloc_size (1, 2))) void*
- calloc_type (size_t, size_t);
-typedef __attribute__ ((alloc_size (1))) void*
- malloc_type (size_t);
-@end smallexample
+@cindex @code{target("3dnowa")} function attribute, x86
+@item 3dnowa
+@itemx no-3dnowa
+Enable/disable the generation of the enhanced 3DNow!@: instructions.
-@noindent
-specify that @code{calloc_type} is a type of a function that, like
-the standard C function @code{calloc}, returns an object whose size
-is given by the product of arguments 1 and 2, and that
-@code{malloc_type}, like the standard C function @code{malloc},
-returns an object whose size is given by argument 1 to the function.
+@cindex @code{target("abm")} function attribute, x86
+@item abm
+@itemx no-abm
+Enable/disable the generation of the advanced bit instructions.
-@cindex @code{btf_type_tag} type attribute
-@item btf_type_tag (@var{argument})
-The @code{btf_type_tag} attribute may be used to associate (to ``tag'')
-particular types with arbitrary string annotations. These annotations
-are recorded in debugging info by supported debug formats, currently
-DWARF (via @code{DW_AT_GNU_annotation} and @code{DW_TAG_GNU_annotation}
-extensions) and BTF (via @code{BTF_KIND_TYPE_TAG} records). These
-annotation strings are not interpreted by the compiler in any way, and
-have no effect on code generation. If neither DWARF nor BTF
-information is generated, the attribute has no effect.
+@cindex @code{target("adx")} function attribute, x86
+@item adx
+@itemx no-adx
+Enable/disable the generation of the ADX instructions.
-The argument is treated as a null-terminated sequence of zero or more
-non-null bytes. Wide character strings are not supported.
+@cindex @code{target("aes")} function attribute, x86
+@item aes
+@itemx no-aes
+Enable/disable the generation of the AES instructions.
-The attribute may be supplied multiple times for a single type, in
-which case each distinct argument string will be recorded in a
-separate DIE or BTF record, each associated to the type. For a single
-type with multiple @code{btf_type_tag} attributes, the order of the
-@code{DW_TAG_GNU_annotation} DIEs produced is not guaranteed to
-maintain the order of attributes in the source code.
+@cindex @code{target("avx")} function attribute, x86
+@item avx
+@itemx no-avx
+Enable/disable the generation of the AVX instructions.
-For example the following code:
+@cindex @code{target("avx2")} function attribute, x86
+@item avx2
+@itemx no-avx2
+Enable/disable the generation of the AVX2 instructions.
-@smallexample
-int * __attribute__ ((btf_type_tag ("__user"))) foo;
-@end smallexample
+@cindex @code{target("avx512bitalg")} function attribute, x86
+@item avx512bitalg
+@itemx no-avx512bitalg
+Enable/disable the generation of the AVX512BITALG instructions.
-@noindent
-when compiled with @option{-gbtf} results in an additional
-@code{BTF_KIND_TYPE_TAG} BTF record to be emitted in the BTF info,
-associating the string @samp{__user} with the normal @code{BTF_KIND_PTR}
-record for the pointer-to-integer type used in the declaration.
+@cindex @code{target("avx512bw")} function attribute, x86
+@item avx512bw
+@itemx no-avx512bw
+Enable/disable the generation of the AVX512BW instructions.
-Note that the BTF format currently only has a representation for type
-tags associated with pointer types. Type tags on non-pointer types
-may be silently skipped when generating BTF.
+@cindex @code{target("avx512cd")} function attribute, x86
+@item avx512cd
+@itemx no-avx512cd
+Enable/disable the generation of the AVX512CD instructions.
-@cindex @code{copy} type attribute
-@item copy
-@itemx copy (@var{expression})
-The @code{copy} attribute applies the set of attributes with which
-the type of the @var{expression} has been declared to the declaration
-of the type to which the attribute is applied. The attribute is
-designed for libraries that define aliases that are expected to
-specify the same set of attributes as the aliased symbols.
-The @code{copy} attribute can be used with types, variables, or
-functions. However, the kind of symbol to which the attribute is
-applied (either varible or function) must match the kind of symbol
-to which the argument refers.
-The @code{copy} attribute copies only syntactic and semantic attributes
-but not attributes that affect a symbol's linkage or visibility such as
-@code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated}
-attribute is also not copied. @xref{Common Function Attributes}.
-@xref{Common Variable Attributes}.
+@cindex @code{target("avx512dq")} function attribute, x86
+@item avx512dq
+@itemx no-avx512dq
+Enable/disable the generation of the AVX512DQ instructions.
-For example, suppose @code{struct A} below is defined in some third
-party library header to have the alignment requirement @code{N} and
-to force a warning whenever a variable of the type is not so aligned
-due to attribute @code{packed}. Specifying the @code{copy} attribute
-on the definition on the unrelated @code{struct B} has the effect of
-copying all relevant attributes from the type referenced by the pointer
-expression to @code{struct B}.
+@cindex @code{target("avx512er")} function attribute, x86
+@item avx512er
+@itemx no-avx512er
+Enable/disable the generation of the AVX512ER instructions.
-@smallexample
-struct __attribute__ ((aligned (N), warn_if_not_aligned (N)))
-A @{ /* @r{@dots{}} */ @};
-struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @};
-@end smallexample
+@cindex @code{target("avx512f")} function attribute, x86
+@item avx512f
+@itemx no-avx512f
+Enable/disable the generation of the AVX512F instructions.
-@cindex @code{deprecated} type attribute
-@item deprecated
-@itemx deprecated (@var{msg})
-The @code{deprecated} attribute results in a warning if the type
-is used anywhere in the source file. This is useful when identifying
-types that are expected to be removed in a future version of a program.
-If possible, the warning also includes the location of the declaration
-of the deprecated type, to enable users to easily find further
-information about why the type is deprecated, or what they should do
-instead. Note that the warnings only occur for uses and then only
-if the type is being applied to an identifier that itself is not being
-declared as deprecated.
+@cindex @code{target("avx512ifma")} function attribute, x86
+@item avx512ifma
+@itemx no-avx512ifma
+Enable/disable the generation of the AVX512IFMA instructions.
-@smallexample
-typedef int T1 __attribute__ ((deprecated));
-T1 x;
-typedef T1 T2;
-T2 y;
-typedef T1 T3 __attribute__ ((deprecated));
-T3 z __attribute__ ((deprecated));
-@end smallexample
+@cindex @code{target("avx512vbmi")} function attribute, x86
+@item avx512vbmi
+@itemx no-avx512vbmi
+Enable/disable the generation of the AVX512VBMI instructions.
-@noindent
-results in a warning on line 2 and 3 but not lines 4, 5, or 6. No
-warning is issued for line 4 because T2 is not explicitly
-deprecated. Line 5 has no warning because T3 is explicitly
-deprecated. Similarly for line 6. The optional @var{msg}
-argument, which must be a string, is printed in the warning if
-present. Control characters in the string will be replaced with
-escape sequences, and if the @option{-fmessage-length} option is set
-to 0 (its default value) then any newline characters will be ignored.
+@cindex @code{target("avx512vbmi2")} function attribute, x86
+@item avx512vbmi2
+@itemx no-avx512vbmi2
+Enable/disable the generation of the AVX512VBMI2 instructions.
-The @code{deprecated} attribute can also be used for functions and
-variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
+@cindex @code{target("avx512vl")} function attribute, x86
+@item avx512vl
+@itemx no-avx512vl
+Enable/disable the generation of the AVX512VL instructions.
-The message attached to the attribute is affected by the setting of
-the @option{-fmessage-length} option.
+@cindex @code{target("avx512vnni")} function attribute, x86
+@item avx512vnni
+@itemx no-avx512vnni
+Enable/disable the generation of the AVX512VNNI instructions.
-@cindex @code{designated_init} type attribute
-@item designated_init
-This attribute may only be applied to structure types. It indicates
-that any initialization of an object of this type must use designated
-initializers rather than positional initializers. The intent of this
-attribute is to allow the programmer to indicate that a structure's
-layout may change, and that therefore relying on positional
-initialization will result in future breakage.
+@cindex @code{target("avx512vpopcntdq")} function attribute, x86
+@item avx512vpopcntdq
+@itemx no-avx512vpopcntdq
+Enable/disable the generation of the AVX512VPOPCNTDQ instructions.
-GCC emits warnings based on this attribute by default; use
-@option{-Wno-designated-init} to suppress them.
+@cindex @code{target("bmi")} function attribute, x86
+@item bmi
+@itemx no-bmi
+Enable/disable the generation of the BMI instructions.
-@cindex @code{flag_enum} type attribute
-@item flag_enum
-This attribute may be applied to an enumerated type to indicate that
-its enumerators are used in bitwise operations, so e.g. @option{-Wswitch}
-should not warn about a @code{case} that corresponds to a bitwise
-combination of enumerators.
+@cindex @code{target("bmi2")} function attribute, x86
+@item bmi2
+@itemx no-bmi2
+Enable/disable the generation of the BMI2 instructions.
-@cindex @code{hardbool} type attribute
-@item hardbool
-@itemx hardbool (@var{false_value})
-@itemx hardbool (@var{false_value}, @var{true_value})
-This attribute may only be applied to integral types in C, to introduce
-hardened boolean types. It turns the integral type into a boolean-like
-type with the same size and precision, that uses the specified values as
-representations for @code{false} and @code{true}. Underneath, it is
-actually an enumerated type, but its observable behavior is like that of
-@code{_Bool}, except for the strict internal representations, verified
-by runtime checks.
+@cindex @code{target("cldemote")} function attribute, x86
+@item cldemote
+@itemx no-cldemote
+Enable/disable the generation of the CLDEMOTE instructions.
-If @var{true_value} is omitted, the bitwise negation of
-@var{false_value} is used. If @var{false_value} is omitted, zero is
-used. The named representation values must be different when converted
-to the original integral type. Narrower bitfields are rejected if the
-representations become indistinguishable.
+@cindex @code{target("clflushopt")} function attribute, x86
+@item clflushopt
+@itemx no-clflushopt
+Enable/disable the generation of the CLFLUSHOPT instructions.
-Values of such types automatically decay to @code{_Bool}, at which
-point, the selected representation values are mapped to the
-corresponding @code{_Bool} values. When the represented value is not
-determined, at compile time, to be either @var{false_value} or
-@var{true_value}, runtime verification calls @code{__builtin_trap} if it
-is neither. This is what makes them hardened boolean types.
+@cindex @code{target("clwb")} function attribute, x86
+@item clwb
+@itemx no-clwb
+Enable/disable the generation of the CLWB instructions.
-When converting scalar types to such hardened boolean types, implicitly
-or explicitly, behavior corresponds to a conversion to @code{_Bool},
-followed by a mapping from @code{false} and @code{true} to
-@var{false_value} and @var{true_value}, respectively.
+@cindex @code{target("clzero")} function attribute, x86
+@item clzero
+@itemx no-clzero
+Enable/disable the generation of the CLZERO instructions.
-@smallexample
-typedef char __attribute__ ((__hardbool__ (0x5a))) hbool;
-hbool first = 0; /* False, stored as (char)0x5a. */
-hbool second = !first; /* True, stored as ~(char)0x5a. */
+@cindex @code{target("crc32")} function attribute, x86
+@item crc32
+@itemx no-crc32
+Enable/disable the generation of the CRC32 instructions.
-static hbool zeroinit; /* False, stored as (char)0x5a. */
-auto hbool uninit; /* Undefined, may trap. */
-@end smallexample
+@cindex @code{target("cx16")} function attribute, x86
+@item cx16
+@itemx no-cx16
+Enable/disable the generation of the CMPXCHG16B instructions.
-When zero-initializing a variable or field of hardened boolean type
-(presumably held in static storage) the implied zero initializer gets
-converted to @code{_Bool}, and then to the hardened boolean type, so
-that the initial value is the hardened representation for @code{false}.
-Using that value is well defined. This is @emph{not} the case when
-variables and fields of such types are uninitialized (presumably held in
-automatic or dynamic storage): their values are indeterminate, and using
-them invokes undefined behavior. Using them may trap or not, depending
-on the bits held in the storage (re)used for the variable, if any, and
-on optimizations the compiler may perform on the grounds that using
-uninitialized values invokes undefined behavior.
+@cindex @code{target("default")} function attribute, x86
+@item default
+@xref{Function Multiversioning}, where it is used to specify the
+default function version.
-Users of @option{-ftrivial-auto-var-init} should be aware that the bit
-patterns used as initializers are @emph{not} converted to
-@code{hardbool} types, so using a @code{hardbool} variable that is
-implicitly initialized by the @option{-ftrivial-auto-var-init} may trap
-if the representations values chosen for @code{false} and @code{true} do
-not match the initializer.
+@cindex @code{target("f16c")} function attribute, x86
+@item f16c
+@itemx no-f16c
+Enable/disable the generation of the F16C instructions.
-Since this is a language extension only available in C, interoperation
-with other languages may pose difficulties. It should interoperate with
-Ada Booleans defined with the same size and equivalent representation
-clauses, and with enumerations or other languages' integral types that
-correspond to C's chosen integral type.
+@cindex @code{target("fma")} function attribute, x86
+@item fma
+@itemx no-fma
+Enable/disable the generation of the FMA instructions.
+@cindex @code{target("fma4")} function attribute, x86
+@item fma4
+@itemx no-fma4
+Enable/disable the generation of the FMA4 instructions.
-@cindex @code{may_alias} type attribute
-@item may_alias
-Accesses through pointers to types with this attribute are not subject
-to type-based alias analysis, but are instead assumed to be able to alias
-any other type of objects.
-In the context of section 6.5 paragraph 7 of the C99 standard,
-an lvalue expression
-dereferencing such a pointer is treated like having a character type.
-See @option{-fstrict-aliasing} for more information on aliasing issues.
-This extension exists to support some vector APIs, in which pointers to
-one vector type are permitted to alias pointers to a different vector type.
+@cindex @code{target("fsgsbase")} function attribute, x86
+@item fsgsbase
+@itemx no-fsgsbase
+Enable/disable the generation of the FSGSBASE instructions.
-Note that an object of a type with this attribute does not have any
-special semantics.
+@cindex @code{target("fxsr")} function attribute, x86
+@item fxsr
+@itemx no-fxsr
+Enable/disable the generation of the FXSR instructions.
-Example of use:
+@cindex @code{target("gfni")} function attribute, x86
+@item gfni
+@itemx no-gfni
+Enable/disable the generation of the GFNI instructions.
-@smallexample
-typedef short __attribute__ ((__may_alias__)) short_a;
+@cindex @code{target("hle")} function attribute, x86
+@item hle
+@itemx no-hle
+Enable/disable the generation of the HLE instruction prefixes.
-int
-main (void)
-@{
- int a = 0x12345678;
- short_a *b = (short_a *) &a;
+@cindex @code{target("lwp")} function attribute, x86
+@item lwp
+@itemx no-lwp
+Enable/disable the generation of the LWP instructions.
- b[1] = 0;
+@cindex @code{target("lzcnt")} function attribute, x86
+@item lzcnt
+@itemx no-lzcnt
+Enable/disable the generation of the LZCNT instructions.
- if (a == 0x12345678)
- abort();
+@cindex @code{target("mmx")} function attribute, x86
+@item mmx
+@itemx no-mmx
+Enable/disable the generation of the MMX instructions.
- exit(0);
-@}
-@end smallexample
+@cindex @code{target("movbe")} function attribute, x86
+@item movbe
+@itemx no-movbe
+Enable/disable the generation of the MOVBE instructions.
-@noindent
-If you replaced @code{short_a} with @code{short} in the variable
-declaration, the above program would abort when compiled with
-@option{-fstrict-aliasing}, which is on by default at @option{-O2} or
-above.
+@cindex @code{target("movdir64b")} function attribute, x86
+@item movdir64b
+@itemx no-movdir64b
+Enable/disable the generation of the MOVDIR64B instructions.
-@cindex @code{mode} type attribute
-@item mode (@var{mode})
-This attribute specifies the data type for the declaration---whichever
-type corresponds to the mode @var{mode}. This in effect lets you
-request an integer or floating-point type according to its width.
+@cindex @code{target("movdiri")} function attribute, x86
+@item movdiri
+@itemx no-movdiri
+Enable/disable the generation of the MOVDIRI instructions.
-@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals},
-for a list of the possible keywords for @var{mode}.
-You may also specify a mode of @code{byte} or @code{__byte__} to
-indicate the mode corresponding to a one-byte integer, @code{word} or
-@code{__word__} for the mode of a one-word integer, and @code{pointer}
-or @code{__pointer__} for the mode used to represent pointers.
+@cindex @code{target("mwait")} function attribute, x86
+@item mwait
+@itemx no-mwait
+Enable/disable the generation of the MWAIT and MONITOR instructions.
-@cindex @code{objc_root_class} type attribute
-@item objc_root_class @r{(Objective-C and Objective-C++ only)}
-This attribute marks a class as being a root class, and thus allows
-the compiler to elide any warnings about a missing superclass and to
-make additional checks for mandatory methods as needed.
+@cindex @code{target("mwaitx")} function attribute, x86
+@item mwaitx
+@itemx no-mwaitx
+Enable/disable the generation of the MWAITX instructions.
-@cindex @code{packed} type attribute
-@item packed
-This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class}
-type definition, specifies that each of its members (other than zero-width
-bit-fields) is placed to minimize the memory required. This is equivalent
-to specifying the @code{packed} attribute on each of the members.
+@cindex @code{target("pclmul")} function attribute, x86
+@item pclmul
+@itemx no-pclmul
+Enable/disable the generation of the PCLMUL instructions.
-@opindex fshort-enums
-When attached to an @code{enum} definition, the @code{packed} attribute
-indicates that the smallest integral type should be used.
-Specifying the @option{-fshort-enums} flag on the command line
-is equivalent to specifying the @code{packed}
-attribute on all @code{enum} definitions.
+@cindex @code{target("pconfig")} function attribute, x86
+@item pconfig
+@itemx no-pconfig
+Enable/disable the generation of the PCONFIG instructions.
-In the following example @code{struct my_packed_struct}'s members are
-packed closely together, but the internal layout of its @code{s} member
-is not packed---to do that, @code{struct my_unpacked_struct} needs to
-be packed too.
+@cindex @code{target("pku")} function attribute, x86
+@item pku
+@itemx no-pku
+Enable/disable the generation of the PKU instructions.
-@smallexample
-struct my_unpacked_struct
- @{
- char c;
- int i;
- @};
+@cindex @code{target("popcnt")} function attribute, x86
+@item popcnt
+@itemx no-popcnt
+Enable/disable the generation of the POPCNT instruction.
-struct __attribute__ ((__packed__)) my_packed_struct
- @{
- char c;
- int i;
- struct my_unpacked_struct s;
- @};
-@end smallexample
+@cindex @code{target("prfchw")} function attribute, x86
+@item prfchw
+@itemx no-prfchw
+Enable/disable the generation of the PREFETCHW instruction.
-You may only specify the @code{packed} attribute on the definition
-of an @code{enum}, @code{struct}, @code{union}, or @code{class},
-not on a @code{typedef} that does not also define the enumerated type,
-structure, union, or class.
+@cindex @code{target("ptwrite")} function attribute, x86
+@item ptwrite
+@itemx no-ptwrite
+Enable/disable the generation of the PTWRITE instructions.
-@cindex @code{scalar_storage_order} type attribute
-@item scalar_storage_order ("@var{endianness}")
-When attached to a @code{union} or a @code{struct}, this attribute sets
-the storage order, aka endianness, of the scalar fields of the type, as
-well as the array fields whose component is scalar. The supported
-endiannesses are @code{big-endian} and @code{little-endian}. The attribute
-has no effects on fields which are themselves a @code{union}, a @code{struct}
-or an array whose component is a @code{union} or a @code{struct}, and it is
-possible for these fields to have a different scalar storage order than the
-enclosing type.
+@cindex @code{target("rdpid")} function attribute, x86
+@item rdpid
+@itemx no-rdpid
+Enable/disable the generation of the RDPID instructions.
-Note that neither pointer nor vector fields are considered scalar fields in
-this context, so the attribute has no effects on these fields.
+@cindex @code{target("rdrnd")} function attribute, x86
+@item rdrnd
+@itemx no-rdrnd
+Enable/disable the generation of the RDRND instructions.
-This attribute is supported only for targets that use a uniform default
-scalar storage order (fortunately, most of them), i.e.@: targets that store
-the scalars either all in big-endian or all in little-endian.
+@cindex @code{target("rdseed")} function attribute, x86
+@item rdseed
+@itemx no-rdseed
+Enable/disable the generation of the RDSEED instructions.
-Additional restrictions are enforced for types with the reverse scalar
-storage order with regard to the scalar storage order of the target:
+@cindex @code{target("rtm")} function attribute, x86
+@item rtm
+@itemx no-rtm
+Enable/disable the generation of the RTM instructions.
-@itemize
-@item Taking the address of a scalar field of a @code{union} or a
-@code{struct} with reverse scalar storage order is not permitted and yields
-an error.
-@item Taking the address of an array field, whose component is scalar, of
-a @code{union} or a @code{struct} with reverse scalar storage order is
-permitted but yields a warning, unless @option{-Wno-scalar-storage-order}
-is specified.
-@item Taking the address of a @code{union} or a @code{struct} with reverse
-scalar storage order is permitted.
-@end itemize
+@cindex @code{target("sahf")} function attribute, x86
+@item sahf
+@itemx no-sahf
+Enable/disable the generation of the SAHF instructions.
-These restrictions exist because the storage order attribute is lost when
-the address of a scalar or the address of an array with scalar component is
-taken, so storing indirectly through this address generally does not work.
-The second case is nevertheless allowed to be able to perform a block copy
-from or to the array.
+@cindex @code{target("sgx")} function attribute, x86
+@item sgx
+@itemx no-sgx
+Enable/disable the generation of the SGX instructions.
-Moreover, the use of type punning or aliasing to toggle the storage order
-is not supported; that is to say, if a given scalar object can be accessed
-through distinct types that assign a different storage order to it, then the
-behavior is undefined.
+@cindex @code{target("sha")} function attribute, x86
+@item sha
+@itemx no-sha
+Enable/disable the generation of the SHA instructions.
-@cindex @code{strub} type attribute
-@item strub
-This attribute defines stack-scrubbing properties of functions and
-variables, so that functions that access sensitive data can have their
-stack frames zeroed-out upon returning or propagating exceptions. This
-may be enabled explicitly, by selecting certain @code{strub} modes for
-specific functions, or implicitly, by means of @code{strub} variables.
+@cindex @code{target("shstk")} function attribute, x86
+@item shstk
+@itemx no-shstk
+Enable/disable the shadow stack built-in functions from CET.
-Being a type attribute, it attaches to types, even when specified in
-function and variable declarations. When applied to function types, it
-takes an optional string argument. When applied to a
-pointer-to-function type, if the optional argument is given, it gets
-propagated to the function type.
+@cindex @code{target("sse")} function attribute, x86
+@item sse
+@itemx no-sse
+Enable/disable the generation of the SSE instructions.
-@smallexample
-/* A strub variable. */
-int __attribute__ ((strub)) var;
-/* A strub variable that happens to be a pointer. */
-__attribute__ ((strub)) int *strub_ptr_to_int;
-/* A pointer type that may point to a strub variable. */
-typedef int __attribute__ ((strub)) *ptr_to_strub_int_type;
+@cindex @code{target("sse2")} function attribute, x86
+@item sse2
+@itemx no-sse2
+Enable/disable the generation of the SSE2 instructions.
-/* A declaration of a strub function. */
-extern int __attribute__ ((strub)) foo (void);
-/* A pointer to that strub function. */
-int __attribute__ ((strub ("at-calls"))) (*ptr_to_strub_fn)(void) = foo;
-@end smallexample
+@cindex @code{target("sse3")} function attribute, x86
+@item sse3
+@itemx no-sse3
+Enable/disable the generation of the SSE3 instructions.
-A function associated with @code{at-calls} @code{strub} mode
-(@code{strub("at-calls")}, or just @code{strub}) undergoes interface
-changes. Its callers are adjusted to match the changes, and to scrub
-(overwrite with zeros) the stack space used by the called function after
-it returns. The interface change makes the function type incompatible
-with an unadorned but otherwise equivalent type, so @emph{every}
-declaration and every type that may be used to call the function must be
-associated with this strub mode.
+@cindex @code{target("sse4")} function attribute, x86
+@item sse4
+@itemx no-sse4
+Enable/disable the generation of the SSE4 instructions (both SSE4.1
+and SSE4.2).
-A function associated with @code{internal} @code{strub} mode
-(@code{strub("internal")}) retains an unmodified, type-compatible
-interface, but it may be turned into a wrapper that calls the wrapped
-body using a custom interface. The wrapper then scrubs the stack space
-used by the wrapped body. Though the wrapped body has its stack space
-scrubbed, the wrapper does not, so arguments and return values may
-remain unscrubbed even when such a function is called by another
-function that enables @code{strub}. This is why, when compiling with
-@option{-fstrub=strict}, a @code{strub} context is not allowed to call
-@code{internal} @code{strub} functions.
+@cindex @code{target("sse4.1")} function attribute, x86
+@item sse4.1
+@itemx no-sse4.1
+Enable/disable the generation of the SSE4.1 instructions.
-@smallexample
-/* A declaration of an internal-strub function. */
-extern int __attribute__ ((strub ("internal"))) bar (void);
+@cindex @code{target("sse4.2")} function attribute, x86
+@item sse4.2
+@itemx no-sse4.2
+Enable/disable the generation of the SSE4.2 instructions.
-int __attribute__ ((strub))
-baz (void)
-@{
- /* Ok, foo was declared above as an at-calls strub function. */
- foo ();
- /* Not allowed in strict mode, otherwise allowed. */
- bar ();
-@}
-@end smallexample
+@cindex @code{target("sse4a")} function attribute, x86
+@item sse4a
+@itemx no-sse4a
+Enable/disable the generation of the SSE4A instructions.
-An automatically-allocated variable associated with the @code{strub}
-attribute causes the (immediately) enclosing function to have
-@code{strub} enabled.
+@cindex @code{target("ssse3")} function attribute, x86
+@item ssse3
+@itemx no-ssse3
+Enable/disable the generation of the SSSE3 instructions.
-A statically-allocated variable associated with the @code{strub}
-attribute causes functions that @emph{read} it, through its @code{strub}
-data type, to have @code{strub} enabled. Reading data by dereferencing
-a pointer to a @code{strub} data type has the same effect. Note: The
-attribute does not carry over from a composite type to the types of its
-components, so the intended effect may not be obtained with non-scalar
-types.
+@cindex @code{target("tbm")} function attribute, x86
+@item tbm
+@itemx no-tbm
+Enable/disable the generation of the TBM instructions.
-When selecting a @code{strub}-enabled mode for a function that is not
-explicitly associated with one, because of @code{strub} variables or
-data pointers, the function must satisfy @code{internal} mode viability
-requirements (see below), even when @code{at-calls} mode is also viable
-and, being more efficient, ends up selected as an optimization.
+@cindex @code{target("vaes")} function attribute, x86
+@item vaes
+@itemx no-vaes
+Enable/disable the generation of the VAES instructions.
-@smallexample
-/* zapme is implicitly strub-enabled because of strub variables.
- Optimization may change its strub mode, but not the requirements. */
-static int
-zapme (int i)
-@{
- /* A local strub variable enables strub. */
- int __attribute__ ((strub)) lvar;
- /* Reading strub data through a pointer-to-strub enables strub. */
- lvar = * (ptr_to_strub_int_type) &i;
- /* Writing to a global strub variable does not enable strub. */
- var = lvar;
- /* Reading from a global strub variable enables strub. */
- return var;
-@}
-@end smallexample
+@cindex @code{target("vpclmulqdq")} function attribute, x86
+@item vpclmulqdq
+@itemx no-vpclmulqdq
+Enable/disable the generation of the VPCLMULQDQ instructions.
-A @code{strub} context is the body (as opposed to the interface) of a
-function that has @code{strub} enabled, be it explicitly, by
-@code{at-calls} or @code{internal} mode, or implicitly, due to
-@code{strub} variables or command-line options.
+@cindex @code{target("waitpkg")} function attribute, x86
+@item waitpkg
+@itemx no-waitpkg
+Enable/disable the generation of the WAITPKG instructions.
-A function of a type associated with the @code{disabled} @code{strub}
-mode (@code{strub("disabled")} will not have its own stack space
-scrubbed. Such functions @emph{cannot} be called from within
-@code{strub} contexts.
+@cindex @code{target("wbnoinvd")} function attribute, x86
+@item wbnoinvd
+@itemx no-wbnoinvd
+Enable/disable the generation of the WBNOINVD instructions.
-In order to enable a function to be called from within @code{strub}
-contexts without having its stack space scrubbed, associate it with the
-@code{callable} @code{strub} mode (@code{strub("callable")}).
+@cindex @code{target("xop")} function attribute, x86
+@item xop
+@itemx no-xop
+Enable/disable the generation of the XOP instructions.
-When a function is not assigned a @code{strub} mode, explicitly or
-implicitly, the mode defaults to @code{callable}, except when compiling
-with @option{-fstrub=strict}, that causes @code{strub} mode to default
-to @code{disabled}.
+@cindex @code{target("xsave")} function attribute, x86
+@item xsave
+@itemx no-xsave
+Enable/disable the generation of the XSAVE instructions.
-@example
-extern int __attribute__ ((strub ("callable"))) bac (void);
-extern int __attribute__ ((strub ("disabled"))) bad (void);
- /* Implicitly disabled with -fstrub=strict, otherwise callable. */
-extern int bah (void);
+@cindex @code{target("xsavec")} function attribute, x86
+@item xsavec
+@itemx no-xsavec
+Enable/disable the generation of the XSAVEC instructions.
-int __attribute__ ((strub))
-bal (void)
-@{
- /* Not allowed, bad is not strub-callable. */
- bad ();
- /* Ok, bac is strub-callable. */
- bac ();
- /* Not allowed with -fstrub=strict, otherwise allowed. */
- bah ();
-@}
-@end example
+@cindex @code{target("xsaveopt")} function attribute, x86
+@item xsaveopt
+@itemx no-xsaveopt
+Enable/disable the generation of the XSAVEOPT instructions.
-Function types marked @code{callable} and @code{disabled} are not
-mutually compatible types, but the underlying interfaces are compatible,
-so it is safe to convert pointers between them, and to use such pointers
-or alternate declarations to call them. Interfaces are also
-interchangeable between them and @code{internal} (but not
-@code{at-calls}!), but adding @code{internal} to a pointer type will not
-cause the pointed-to function to perform stack scrubbing.
+@cindex @code{target("xsaves")} function attribute, x86
+@item xsaves
+@itemx no-xsaves
+Enable/disable the generation of the XSAVES instructions.
-@example
-void __attribute__ ((strub))
-bap (void)
-@{
- /* Assign a callable function to pointer-to-disabled.
- Flagged as not quite compatible with -Wpedantic. */
- int __attribute__ ((strub ("disabled"))) (*d_p) (void) = bac;
- /* Not allowed: calls disabled type in a strub context. */
- d_p ();
+@cindex @code{target("amx-tile")} function attribute, x86
+@item amx-tile
+@itemx no-amx-tile
+Enable/disable the generation of the AMX-TILE instructions.
- /* Assign a disabled function to pointer-to-callable.
- Flagged as not quite compatible with -Wpedantic. */
- int __attribute__ ((strub ("callable"))) (*c_p) (void) = bad;
- /* Ok, safe. */
- c_p ();
+@cindex @code{target("amx-int8")} function attribute, x86
+@item amx-int8
+@itemx no-amx-int8
+Enable/disable the generation of the AMX-INT8 instructions.
- /* Assign an internal function to pointer-to-callable.
- Flagged as not quite compatible with -Wpedantic. */
- c_p = bar;
- /* Ok, safe. */
- c_p ();
+@cindex @code{target("amx-bf16")} function attribute, x86
+@item amx-bf16
+@itemx no-amx-bf16
+Enable/disable the generation of the AMX-BF16 instructions.
- /* Assign an at-calls function to pointer-to-callable.
- Flaggged as incompatible. */
- c_p = bal;
- /* The call through an interface-incompatible type will not use the
- modified interface expected by the at-calls function, so it is
- likely to misbehave at runtime. */
- c_p ();
-@}
-@end example
+@cindex @code{target("uintr")} function attribute, x86
+@item uintr
+@itemx no-uintr
+Enable/disable the generation of the UINTR instructions.
-@code{Strub} contexts are never inlined into non-@code{strub} contexts.
-When an @code{internal}-strub function is split up, the wrapper can
-often be inlined, but the wrapped body @emph{never} is. A function
-marked as @code{always_inline}, even if explicitly assigned
-@code{internal} strub mode, will not undergo wrapping, so its body gets
-inlined as required.
+@cindex @code{target("hreset")} function attribute, x86
+@item hreset
+@itemx no-hreset
+Enable/disable the generation of the HRESET instruction.
-@example
-inline int __attribute__ ((strub ("at-calls")))
-inl_atc (void)
-@{
- /* This body may get inlined into strub contexts. */
-@}
+@cindex @code{target("kl")} function attribute, x86
+@item kl
+@itemx no-kl
+Enable/disable the generation of the KEYLOCKER instructions.
-inline int __attribute__ ((strub ("internal")))
-inl_int (void)
-@{
- /* This body NEVER gets inlined, though its wrapper may. */
-@}
+@cindex @code{target("widekl")} function attribute, x86
+@item widekl
+@itemx no-widekl
+Enable/disable the generation of the WIDEKL instructions.
-inline int __attribute__ ((strub ("internal"), always_inline))
-inl_int_ali (void)
-@{
- /* No internal wrapper, so this body ALWAYS gets inlined,
- but it cannot be called from non-strub contexts. */
-@}
+@cindex @code{target("avxvnni")} function attribute, x86
+@item avxvnni
+@itemx no-avxvnni
+Enable/disable the generation of the AVXVNNI instructions.
-void __attribute__ ((strub ("disabled")))
-bat (void)
-@{
- /* Not allowed, cannot inline into a non-strub context. */
- inl_int_ali ();
-@}
-@end example
+@cindex @code{target("avxifma")} function attribute, x86
+@item avxifma
+@itemx no-avxifma
+Enable/disable the generation of the AVXIFMA instructions.
-@cindex strub eligibility and viability
-Some @option{-fstrub=*} command-line options enable @code{strub} modes
-implicitly where viable. A @code{strub} mode is only viable for a
-function if the function is eligible for that mode, and if other
-conditions, detailed below, are satisfied. If it's not eligible for a
-mode, attempts to explicitly associate it with that mode are rejected
-with an error message. If it is eligible, that mode may be assigned
-explicitly through this attribute, but implicit assignment through
-command-line options may involve additional viability requirements.
+@cindex @code{target("avxvnniint8")} function attribute, x86
+@item avxvnniint8
+@itemx no-avxvnniint8
+Enable/disable the generation of the AVXVNNIINT8 instructions.
-A function is ineligible for @code{at-calls} @code{strub} mode if a
-different @code{strub} mode is explicitly requested, if attribute
-@code{noipa} is present, or if it calls @code{__builtin_apply_args}.
-@code{At-calls} @code{strub} mode, if not requested through the function
-type, is only viable for an eligible function if the function is not
-visible to other translation units, if it doesn't have its address
-taken, and if it is never called with a function type overrider.
+@cindex @code{target("avxneconvert")} function attribute, x86
+@item avxneconvert
+@itemx no-avxneconvert
+Enable/disable the generation of the AVXNECONVERT instructions.
-@smallexample
-/* bar is eligible for at-calls strub mode,
- but not viable for that mode because it is visible to other units.
- It is eligible and viable for internal strub mode. */
-void bav () @{@}
+@cindex @code{target("cmpccxadd")} function attribute, x86
+@item cmpccxadd
+@itemx no-cmpccxadd
+Enable/disable the generation of the CMPccXADD instructions.
-/* setp is eligible for at-calls strub mode,
- but not viable for that mode because its address is taken.
- It is eligible and viable for internal strub mode. */
-void setp (void) @{ static void (*p)(void); = setp; @}
-@end smallexample
+@cindex @code{target("amx-fp16")} function attribute, x86
+@item amx-fp16
+@itemx no-amx-fp16
+Enable/disable the generation of the AMX-FP16 instructions.
-A function is ineligible for @code{internal} @code{strub} mode if a
-different @code{strub} mode is explicitly requested, or if attribute
-@code{noipa} is present. For an @code{always_inline} function, meeting
-these requirements is enough to make it eligible. Any function that has
-attribute @code{noclone}, that uses such extensions as non-local labels,
-computed gotos, alternate variable argument passing interfaces,
-@code{__builtin_next_arg}, or @code{__builtin_return_address}, or that
-takes too many (about 64Ki) arguments is ineligible, unless it is
-@code{always_inline}. For @code{internal} @code{strub} mode, all
-eligible functions are viable.
+@cindex @code{target("prefetchi")} function attribute, x86
+@item prefetchi
+@itemx no-prefetchi
+Enable/disable the generation of the PREFETCHI instructions.
-@smallexample
-/* flop is not eligible, thus not viable, for at-calls strub mode.
- Likewise for internal strub mode. */
-__attribute__ ((noipa)) void flop (void) @{@}
+@cindex @code{target("raoint")} function attribute, x86
+@item raoint
+@itemx no-raoint
+Enable/disable the generation of the RAOINT instructions.
-/* flip is eligible and viable for at-calls strub mode.
- It would be ineligible for internal strub mode, because of noclone,
- if it weren't for always_inline. With always_inline, noclone is not
- an obstacle, so it is also eligible and viable for internal strub mode. */
-inline __attribute__ ((noclone, always_inline)) void flip (void) @{@}
-@end smallexample
+@cindex @code{target("amx-complex")} function attribute, x86
+@item amx-complex
+@itemx no-amx-complex
+Enable/disable the generation of the AMX-COMPLEX instructions.
-@cindex @code{transparent_union} type attribute
-@item transparent_union
+@cindex @code{target("avxvnniint16")} function attribute, x86
+@item avxvnniint16
+@itemx no-avxvnniint16
+Enable/disable the generation of the AVXVNNIINT16 instructions.
-This attribute, attached to a @code{union} type definition, indicates
-that any function parameter having that union type causes calls to that
-function to be treated in a special way.
+@cindex @code{target("sm3")} function attribute, x86
+@item sm3
+@itemx no-sm3
+Enable/disable the generation of the SM3 instructions.
-First, the argument corresponding to a transparent union type can be of
-any type in the union; no cast is required. Also, if the union contains
-a pointer type, the corresponding argument can be a null pointer
-constant or a void pointer expression; and if the union contains a void
-pointer type, the corresponding argument can be any pointer expression.
-If the union member type is a pointer, qualifiers like @code{const} on
-the referenced type must be respected, just as with normal pointer
-conversions.
+@cindex @code{target("sha512")} function attribute, x86
+@item sha512
+@itemx no-sha512
+Enable/disable the generation of the SHA512 instructions.
-Second, the argument is passed to the function using the calling
-conventions of the first member of the transparent union, not the calling
-conventions of the union itself. All members of the union must have the
-same machine representation; this is necessary for this argument passing
-to work properly.
+@cindex @code{target("sm4")} function attribute, x86
+@item sm4
+@itemx no-sm4
+Enable/disable the generation of the SM4 instructions.
-Transparent unions are designed for library functions that have multiple
-interfaces for compatibility reasons. For example, suppose the
-@code{wait} function must accept either a value of type @code{int *} to
-comply with POSIX, or a value of type @code{union wait *} to comply with
-the 4.1BSD interface. If @code{wait}'s parameter were @code{void *},
-@code{wait} would accept both kinds of arguments, but it would also
-accept any other pointer type and this would make argument type checking
-less useful. Instead, @code{<sys/wait.h>} might define the interface
-as follows:
+@cindex @code{target("usermsr")} function attribute, x86
+@item usermsr
+@itemx no-usermsr
+Enable/disable the generation of the USER_MSR instructions.
-@smallexample
-typedef union __attribute__ ((__transparent_union__))
- @{
- int *__ip;
- union wait *__up;
- @} wait_status_ptr_t;
+@cindex @code{target("apxf")} function attribute, x86
+@item apxf
+@itemx no-apxf
+Enable/disable the generation of the APX features, including
+EGPR, PUSH2POP2, NDD and PPX.
-pid_t wait (wait_status_ptr_t);
-@end smallexample
+@cindex @code{target("avx10.1")} function attribute, x86
+@item avx10.1
+@itemx no-avx10.1
+Enable/Disable the generation of the AVX10.1 instructions.
-@noindent
-This interface allows either @code{int *} or @code{union wait *}
-arguments to be passed, using the @code{int *} calling convention.
-The program can call @code{wait} with arguments of either type:
+@cindex @code{target("avx10.2")} function attribute, x86
+@item avx10.2
+@itemx no-avx10.2
+Enable/Disable the generation of the AVX10.2 instructions.
+
+@cindex @code{target("amx-avx512")} function attribute, x86
+@item amx-avx512
+@itemx no-amx-avx512
+Enable/disable the generation of the AMX-AVX512 instructions.
-@smallexample
-int w1 () @{ int w; return wait (&w); @}
-int w2 () @{ union wait w; return wait (&w); @}
-@end smallexample
+@cindex @code{target("amx-tf32")} function attribute, x86
+@item amx-tf32
+@itemx no-amx-tf32
+Enable/disable the generation of the AMX-TF32 instructions.
-@noindent
-With this interface, @code{wait}'s implementation might look like this:
+@cindex @code{target("amx-fp8")} function attribute, x86
+@item amx-fp8
+@itemx no-amx-fp8
+Enable/disable the generation of the AMX-FP8 instructions.
-@smallexample
-pid_t wait (wait_status_ptr_t p)
-@{
- return waitpid (-1, p.__ip, 0);
-@}
-@end smallexample
+@cindex @code{target("movrs")} function attribute, x86
+@item movrs
+@itemx no-movrs
+Enable/disable the generation of the MOVRS instructions.
-@cindex @code{unavailable} type attribute
-@item unavailable
-@itemx unavailable (@var{msg})
-The @code{unavailable} attribute behaves in the same manner as the
-@code{deprecated} one, but emits an error rather than a warning. It is
-used to indicate that a (perhaps previously @code{deprecated}) type is
-no longer usable.
+@cindex @code{target("amx-movrs")} function attribute, x86
+@item amx-movrs
+@itemx no-amx-movrs
+Enable/disable the generation of the AMX-MOVRS instructions.
-The @code{unavailable} attribute can also be used for functions and
-variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.)
+@cindex @code{target("cld")} function attribute, x86
+@item cld
+@itemx no-cld
+Enable/disable the generation of the CLD before string moves.
-@cindex @code{unused} type attribute
-@item unused
-When attached to a type (including a @code{union} or a @code{struct}),
-this attribute means that variables of that type are meant to appear
-possibly unused. GCC does not produce a warning for any variables of
-that type, even if the variable appears to do nothing. This is often
-the case with lock or thread classes, which are usually defined and then
-not referenced, but contain constructors and destructors that have
-nontrivial bookkeeping functions.
+@cindex @code{target("fancy-math-387")} function attribute, x86
+@item fancy-math-387
+@itemx no-fancy-math-387
+Enable/disable the generation of the @code{sin}, @code{cos}, and
+@code{sqrt} instructions on the 387 floating-point unit.
-@cindex @code{vector_size} type attribute
-@item vector_size (@var{bytes})
-This attribute specifies the vector size for the type, measured in bytes.
-The type to which it applies is known as the @dfn{base type}. The @var{bytes}
-argument must be a positive power-of-two multiple of the base type size. For
-example, the following declarations:
+@cindex @code{target("ieee-fp")} function attribute, x86
+@item ieee-fp
+@itemx no-ieee-fp
+Enable/disable the generation of floating point that depends on IEEE arithmetic.
-@smallexample
-typedef __attribute__ ((vector_size (32))) int int_vec32_t ;
-typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t;
-typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3];
-@end smallexample
+@cindex @code{target("inline-all-stringops")} function attribute, x86
+@item inline-all-stringops
+@itemx no-inline-all-stringops
+Enable/disable inlining of string operations.
-@noindent
-define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int}
-sized units. With @code{int} having a size of 4 bytes, the type defines
-a vector of eight units, four bytes each. The mode of variables of type
-@code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined
-to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be
-an array of three such vectors. @xref{Vector Extensions}, for details of
-manipulating objects of vector types.
+@cindex @code{target("inline-stringops-dynamically")} function attribute, x86
+@item inline-stringops-dynamically
+@itemx no-inline-stringops-dynamically
+Enable/disable the generation of the inline code to do small string
+operations and calling the library routines for large operations.
-This attribute is only applicable to integral and floating scalar types.
-In function declarations the attribute applies to the function return
-type.
+@cindex @code{target("align-stringops")} function attribute, x86
+@item align-stringops
+@itemx no-align-stringops
+Do/do not align destination of inlined string operations.
-For example, the following:
-@smallexample
-__attribute__ ((vector_size (16))) float get_flt_vec16 (void);
-@end smallexample
-declares @code{get_flt_vec16} to be a function returning a 16-byte vector
-with the base type @code{float}.
+@cindex @code{target("recip")} function attribute, x86
+@item recip
+@itemx no-recip
+Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS
+instructions followed an additional Newton-Raphson step instead of
+doing a floating-point division.
-@cindex @code{visibility} type attribute
-@item visibility
-In C++, attribute visibility (@pxref{Function Attributes}) can also be
-applied to class, struct, union and enum types. Unlike other type
-attributes, the attribute must appear between the initial keyword and
-the name of the type; it cannot appear after the body of the type.
+@cindex @code{target("80387")} function attribute, x86
+@item 80387
+@itemx no-80387
+Generate code containing 80387 instructions for floating point.
-Note that the type visibility is applied to vague linkage entities
-associated with the class (vtable, typeinfo node, etc.). In
-particular, if a class is thrown as an exception in one shared object
-and caught in another, the class must have default visibility.
-Otherwise the two shared objects are unable to use the same
-typeinfo node and exception handling will break.
+@cindex @code{target("general-regs-only")} function attribute, x86
+@item general-regs-only
+Generate code which uses only the general registers.
-@cindex @code{warn_if_not_aligned} type attribute
-@item warn_if_not_aligned (@var{alignment})
-This attribute specifies a threshold for the structure field, measured
-in bytes. If the structure field is aligned below the threshold, a
-warning will be issued. For example, the declaration:
+@cindex @code{target("arch=@var{ARCH}")} function attribute, x86
+@item arch=@var{ARCH}
+Specify the architecture to generate code for in compiling the function.
-@smallexample
-typedef unsigned long long __u64
- __attribute__((aligned (4), warn_if_not_aligned (8)));
+@cindex @code{target("tune=@var{TUNE}")} function attribute, x86
+@item tune=@var{TUNE}
+Specify the architecture to tune for in compiling the function.
-struct foo
-@{
- int i1;
- int i2;
- __u64 x;
-@};
-@end smallexample
+@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86
+@item fpmath=@var{FPMATH}
+Specify which floating-point unit to use. You must specify the
+@code{target("fpmath=sse,387")} option as
+@code{target("fpmath=sse+387")} because the comma would separate
+different options.
-@noindent
-causes the compiler to issue an warning on @code{struct foo}, like
-@samp{warning: alignment 4 of 'struct foo' is less than 8}.
-It is used to define @code{struct foo} in such a way that
-@code{struct foo} has the same layout and the structure field @code{x}
-has the same alignment when @code{__u64} is aligned at either 4 or
-8 bytes. Align @code{struct foo} to 8 bytes:
+@cindex @code{prefer-vector-width} function attribute, x86
+@item prefer-vector-width=@var{OPT}
+On x86 targets, the @code{prefer-vector-width} attribute informs the
+compiler to use @var{OPT}-bit vector width in instructions
+instead of the default on the selected platform.
-@smallexample
-struct __attribute__ ((aligned (8))) foo
-@{
- int i1;
- int i2;
- __u64 x;
-@};
-@end smallexample
+Valid @var{OPT} values are:
-@noindent
-silences the warning. The compiler also issues a warning, like
-@samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8},
-when the structure field has the misaligned offset:
+@table @samp
+@item none
+No extra limitations applied to GCC other than defined by the selected platform.
-@smallexample
-struct __attribute__ ((aligned (8))) foo
-@{
- int i1;
- int i2;
- int i3;
- __u64 x;
-@};
-@end smallexample
+@item 128
+Prefer 128-bit vector width for instructions.
-This warning can be disabled by @option{-Wno-if-not-aligned}.
+@item 256
+Prefer 256-bit vector width for instructions.
+@item 512
+Prefer 512-bit vector width for instructions.
@end table
-To specify multiple attributes, separate them by commas within the
-double parentheses: for example, @samp{__attribute__ ((aligned (16),
-packed))}.
-
-@node ARC Type Attributes
-@subsubsection ARC Type Attributes
+@subsubheading Inlining rules
+On the x86, the inliner does not inline a
+function that has different target options than the caller, unless the
+callee has a subset of the target options of the caller. For example
+a function declared with @code{target("sse3")} can inline a function
+with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
-@cindex @code{uncached} type attribute, ARC
-Declaring objects with @code{uncached} allows you to exclude
-data-cache participation in load and store operations on those objects
-without involving the additional semantic implications of
-@code{volatile}. The @code{.di} instruction suffix is used for all
-loads and stores of data declared @code{uncached}.
+Besides the basic rule, when a function specifies
+@code{target("arch=@var{ARCH}")} or @code{target("tune=@var{TUNE}")}
+attribute, the inlining rule us different. It allows inlining of
+a function with default @option{-march=x86-64} and
+@option{-mtune=generic} specified, or a function that has a subset
+of ISA features and marked with always_inline.
+@end table
-@node ARM Type Attributes
-@subsubsection ARM Type Attributes
+@cindex @code{indirect_branch} function attribute, x86
+@item indirect_branch("@var{choice}")
+On x86 targets, the @code{indirect_branch} attribute causes the compiler
+to convert indirect call and jump with @var{choice}. @samp{keep}
+keeps indirect call and jump unmodified. @samp{thunk} converts indirect
+call and jump to call and return thunk. @samp{thunk-inline} converts
+indirect call and jump to inlined call and return thunk.
+@samp{thunk-extern} converts indirect call and jump to external call
+and return thunk provided in a separate object file.
-@cindex @code{notshared} type attribute, ARM
-On those ARM targets that support @code{dllimport} (such as Symbian
-OS), you can use the @code{notshared} attribute to indicate that the
-virtual table and other similar data for a class should not be
-exported from a DLL@. For example:
+@cindex @code{function_return} function attribute, x86
+@item function_return("@var{choice}")
+On x86 targets, the @code{function_return} attribute causes the compiler
+to convert function return with @var{choice}. @samp{keep} keeps function
+return unmodified. @samp{thunk} converts function return to call and
+return thunk. @samp{thunk-inline} converts function return to inlined
+call and return thunk. @samp{thunk-extern} converts function return to
+external call and return thunk provided in a separate object file.
-@smallexample
-class __declspec(notshared) C @{
-public:
- __declspec(dllimport) C();
- virtual void f();
-@}
+@cindex @code{nocf_check} function attribute
+@item nocf_check
+The @code{nocf_check} attribute on a function is used to inform the
+compiler that the function's prologue should not be instrumented when
+compiled with the @option{-fcf-protection=branch} option. The
+compiler assumes that the function's address is a valid target for a
+control-flow transfer.
-__declspec(dllexport)
-C::C() @{@}
-@end smallexample
+The @code{nocf_check} attribute on a type of pointer to function is
+used to inform the compiler that a call through the pointer should
+not be instrumented when compiled with the
+@option{-fcf-protection=branch} option. The compiler assumes
+that the function's address from the pointer is a valid target for
+a control-flow transfer. A direct function call through a function
+name is assumed to be a safe call thus direct calls are not
+instrumented by the compiler.
-@noindent
-In this code, @code{C::C} is exported from the current DLL, but the
-virtual table for @code{C} is not exported. (You can use
-@code{__attribute__} instead of @code{__declspec} if you prefer, but
-most Symbian OS code uses @code{__declspec}.)
+The @code{nocf_check} attribute is applied to an object's type.
+In case of assignment of a function address or a function pointer to
+another pointer, the attribute is not carried over from the right-hand
+object's type; the type of left-hand object stays unchanged. The
+compiler checks for @code{nocf_check} attribute mismatch and reports
+a warning in case of mismatch.
-@node BPF Type Attributes
-@subsubsection BPF Type Attributes
+@smallexample
+int foo (void) __attribute__((nocf_check));
+void (*foo1)(void) __attribute__((nocf_check));
+void (*foo2)(void);
-@cindex @code{preserve_access_index} type attribute, BPF
-BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a
-@code{struct} or @code{union} type definition, indicates that CO-RE
-relocation information should be generated for any access to a variable
-of that type. The behavior is equivalent to the programmer manually
-wrapping every such access with @code{__builtin_preserve_access_index}.
+/* foo's address is assumed to be valid. */
+int
+foo (void)
+@{
+ /* This call site is not checked for control-flow
+ validity. */
+ (*foo1)();
+ /* A warning is issued about attribute mismatch. */
+ foo1 = foo2;
-@node PowerPC Type Attributes
-@subsubsection PowerPC Type Attributes
+ /* This call site is still not checked. */
+ (*foo1)();
-Three attributes currently are defined for PowerPC configurations:
-@code{altivec}, @code{ms_struct} and @code{gcc_struct}.
+ /* This call site is checked. */
+ (*foo2)();
-@cindex @code{ms_struct} type attribute, PowerPC
-@cindex @code{gcc_struct} type attribute, PowerPC
-For full documentation of the @code{ms_struct} and @code{gcc_struct}
-attributes please see the documentation in @ref{x86 Type Attributes}.
+ /* A warning is issued about attribute mismatch. */
+ foo2 = foo1;
-@cindex @code{altivec} type attribute, PowerPC
-The @code{altivec} attribute allows one to declare AltiVec vector data
-types supported by the AltiVec Programming Interface Manual. The
-attribute requires an argument to specify one of three vector types:
-@code{vector__}, @code{pixel__} (always followed by unsigned short),
-and @code{bool__} (always followed by unsigned).
+ /* This call site is still checked. */
+ (*foo2)();
-@smallexample
-__attribute__((altivec(vector__)))
-__attribute__((altivec(pixel__))) unsigned short
-__attribute__((altivec(bool__))) unsigned
+ return 0;
+@}
@end smallexample
-These attributes mainly are intended to support the @code{__vector},
-@code{__pixel}, and @code{__bool} AltiVec keywords.
+@cindex @code{cf_check} function attribute, x86
+@item cf_check
+
+The @code{cf_check} attribute on a function is used to inform the
+compiler that ENDBR instruction should be placed at the function
+entry when @option{-fcf-protection=branch} is enabled.
-@node x86 Type Attributes
-@subsubsection x86 Type Attributes
+@cindex @code{indirect_return} function attribute, x86
+@item indirect_return
-Two attributes are currently defined for x86 configurations:
-@code{ms_struct} and @code{gcc_struct}.
+The @code{indirect_return} attribute can be applied to a function,
+as well as variable or type of function pointer to inform the
+compiler that the function may return via indirect branch.
-@table @code
+@cindex @code{fentry_name} function attribute, x86
+@item fentry_name("@var{name}")
+On x86 targets, the @code{fentry_name} attribute sets the function to
+call on function entry when function instrumentation is enabled
+with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte
+nop sequence is generated.
+
+@cindex @code{fentry_section} function attribute, x86
+@item fentry_section("@var{name}")
+On x86 targets, the @code{fentry_section} attribute sets the name
+of the section to record function entry instrumentation calls in when
+enabled with @option{-pg -mrecord-mcount}
+
+@cindex @code{nodirect_extern_access} function attribute
+@opindex mno-direct-extern-access
+@item nodirect_extern_access
+This attribute, attached to a global variable or function, is the
+counterpart to option @option{-mno-direct-extern-access}.
-@cindex @code{ms_struct} type attribute, x86
-@cindex @code{gcc_struct} type attribute, x86
+@cindex @code{ms_struct} attribute, x86
+@cindex @code{gcc_struct} attribute, x86
@item ms_struct
@itemx gcc_struct
+These attributes can be applied to variables and struct types.
-If @code{packed} is used on a structure, or if bit-fields are used
-it may be that the Microsoft ABI packs them differently
-than GCC normally packs them. Particularly when moving packed
+If @code{packed} is used on a structure, or if bit-fields are used,
+it may be that the Microsoft ABI lays out the structure differently
+than the way GCC normally does. Particularly when moving packed
data between functions compiled with GCC and the native Microsoft compiler
(either via function call or as data in a file), it may be necessary to access
either format.
to the @option{-mms-bitfields} and @option{-mno-ms-bitfields}
command-line options, respectively;
see @ref{x86 Options}, for details of how structure layout is affected.
-@xref{x86 Variable Attributes}, for information about the corresponding
-attributes on variables.
-
-@end table
-
-@node Label Attributes
-@subsection Label Attributes
-@cindex Label Attributes
-
-GCC allows attributes to be set on C labels. @xref{GNU Attribute Syntax}, for
-details of the exact syntax for using attributes. Other attributes are
-available for functions (@pxref{Function Attributes}), variables
-(@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}),
-statements (@pxref{Statement Attributes}), and for types
-(@pxref{Type Attributes}). A label attribute followed
-by a declaration appertains to the label and not the declaration.
-
-This example uses the @code{cold} label attribute to indicate the
-@code{ErrorHandling} branch is unlikely to be taken and that the
-@code{ErrorHandling} label is unused:
-
-@smallexample
-
- asm goto ("some asm" : : : : NoError);
-
-/* This branch (the fall-through from the asm) is less commonly used */
-ErrorHandling:
- __attribute__((cold, unused)); /* Semi-colon is required here */
- printf("error\n");
- return 0;
-
-NoError:
- printf("no error\n");
- return 1;
-@end smallexample
-
-@table @code
-@cindex @code{unused} label attribute
-@item unused
-This feature is intended for program-generated code that may contain
-unused labels, but which is compiled with @option{-Wall}. It is
-not normally appropriate to use it in human-written code, though it
-could be useful in cases where the code that jumps to the label is
-contained within an @code{#ifdef} conditional.
-
-@cindex @code{hot} label attribute
-@item hot
-The @code{hot} attribute on a label is used to inform the compiler that
-the path following the label is more likely than paths that are not so
-annotated. This attribute is used in cases where @code{__builtin_expect}
-cannot be used, for instance with computed goto or @code{asm goto}.
-
-@cindex @code{cold} label attribute
-@item cold
-The @code{cold} attribute on labels is used to inform the compiler that
-the path following the label is unlikely to be executed. This attribute
-is used in cases where @code{__builtin_expect} cannot be used, for instance
-with computed goto or @code{asm goto}.
@end table
-@node Enumerator Attributes
-@subsection Enumerator Attributes
-@cindex Enumerator Attributes
-
-GCC allows attributes to be set on enumerators. @xref{GNU Attribute Syntax}, for
-details of the exact syntax for using attributes. Other attributes are
-available for functions (@pxref{Function Attributes}), variables
-(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements
-(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
-
-This example uses the @code{deprecated} enumerator attribute to indicate the
-@code{oldval} enumerator is deprecated:
-@smallexample
-enum E @{
- oldval __attribute__((deprecated)),
- newval
-@};
+@node Xstormy16 Attributes
+@subsubsection Xstormy16 Attributes
-int
-fn (void)
-@{
- return oldval;
-@}
-@end smallexample
+These attributes are supported by the Xstormy16 back end:
@table @code
-@cindex @code{deprecated} enumerator attribute
-@item deprecated
-The @code{deprecated} attribute results in a warning if the enumerator
-is used anywhere in the source file. This is useful when identifying
-enumerators that are expected to be removed in a future version of a
-program. The warning also includes the location of the declaration
-of the deprecated enumerator, to enable users to easily find further
-information about why the enumerator is deprecated, or what they should
-do instead. Note that the warnings only occurs for uses.
-
-@cindex @code{unavailable} enumerator attribute
-@item unavailable
-The @code{unavailable} attribute results in an error if the enumerator
-is used anywhere in the source file. In other respects it behaves in the
-same manner as the @code{deprecated} attribute.
+@cindex @code{interrupt} function attribute, Xstormy16
+@item interrupt
+Use this attribute to indicate
+that the specified function is an interrupt handler. The compiler generates
+function entry and exit sequences suitable for use in an interrupt handler
+when this attribute is present.
+@cindex @code{below100} variable attribute, Xstormy16
+@item below100
+If a variable has the @code{below100} attribute (@code{BELOW100} is
+allowed also), GCC places the variable in the first 0x100 bytes of
+memory and use special opcodes to access it. Such variables are
+placed in either the @code{.bss_below100} section or the
+@code{.data_below100} section.
@end table
-@node Statement Attributes
-@subsection Statement Attributes
-@cindex Statement Attributes
-
-GCC allows attributes to be set on statements. @xref{GNU Attribute Syntax},
-for details of the exact syntax for using attributes. Other attributes are
-available for functions (@pxref{Function Attributes}), variables
-(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators
-(@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}).
-
-@table @code
-@cindex @code{fallthrough} statement attribute
-@item fallthrough
-The @code{fallthrough} attribute with a null statement serves as a
-fallthrough statement. It hints to the compiler that a statement
-that falls through to another case label, or user-defined label
-in a switch statement is intentional and thus the
-@option{-Wimplicit-fallthrough} warning must not trigger. The
-fallthrough attribute may appear at most once in each attribute
-list, and may not be mixed with other attributes. It can only
-be used in a switch statement (the compiler will issue an error
-otherwise), after a preceding statement and before a logically
-succeeding case label, or user-defined label.
-
-This example uses the @code{fallthrough} statement attribute to indicate that
-the @option{-Wimplicit-fallthrough} warning should not be emitted:
-
-@smallexample
-switch (cond)
- @{
- case 1:
- bar (1);
- __attribute__((fallthrough));
- case 2:
- @dots{}
- @}
-@end smallexample
-
-@cindex @code{assume} statement attribute
-@item assume
-The @code{assume} attribute with a null statement serves as portable
-assumption. It should have a single argument, a conditional expression,
-which is not evaluated. If the argument would evaluate to true
-at the point where it appears, it has no effect, otherwise there
-is undefined behavior. This is a GNU variant of the ISO C++23
-standard @code{assume} attribute, but it can be used in any version of
-both C and C++.
-
-@smallexample
-int
-foo (int x, int y)
-@{
- __attribute__((assume(x == 42)));
- __attribute__((assume(++y == 43)));
- return x + y;
-@}
-@end smallexample
-
-@code{y} is not actually incremented and the compiler can but does not
-have to optimize it to just @code{return 42 + 42;}.
-
-@cindex @code{musttail} statement attribute
-@item musttail
-
-The @code{gnu::musttail} or @code{clang::musttail} standard attribute
-or @code{musttail} GNU attribute can be applied to a @code{return} statement
-with a return-value expression that is a function call. It asserts that the
-call must be a tail call that does not allocate extra stack space, so it is
-safe to use tail recursion to implement long-running loops.
-
-@smallexample
-[[gnu::musttail]] return foo();
-@end smallexample
-
-@smallexample
-__attribute__((musttail)) return bar();
-@end smallexample
-
-If the compiler cannot generate a @code{musttail} tail call it reports
-an error. On some targets, tail calls may not be supported at all.
-The @code{musttail} attribute asserts that the lifetime of automatic
-variables, function parameters and temporaries (unless they have non-trivial
-destruction) can end before the actual call instruction, and that any access
-to those from inside of the called function results is considered undefined
-behavior. Enabling @option{-O1} or @option{-O2} can improve the success of
-tail calls.
-
-@smallexample
-int foo (int *);
-void bar (int *);
-struct S @{ S (); ~S (); int s; @};
-
-int
-baz (int *x)
-@{
- if (*x == 1)
- @{
- int a = 42;
- /* The call is a tail call (would not be without the
- attribute). Dereferencing the pointer in the callee is
- undefined behavior, and there is a warning emitted
- for this by default (@option{-Wmusttail-local-addr}). */
- [[gnu::musttail]] return foo (&a);
- @}
- else if (*x == 2)
- @{
- int a = 42;
- bar (&a);
- /* The call is a tail call (would not be without the
- attribute). If bar stores the pointer anywhere, dereferencing
- it in foo is undefined behavior. There is a warning
- emitted for this with @option{-Wextra}, which implies
- @option{-Wmaybe-musttail-local-addr}. */
- [[gnu::musttail]] return foo (nullptr);
- @}
- else
- @{
- S s;
- /* The s variable requires non-trivial destruction which ought
- to be performed after the foo call returns, so this is
- rejected. */
- [[gnu::musttail]] return foo (&s.s);
- @}
-@}
-@end smallexample
-
-To avoid the @option{-Wmaybe-musttail-local-addr} warning in the
-above @code{*x == 2} case and similar code, consider defining the
-maybe-escaped variables in a separate scope that ends before the
-return statement, if that is possible, to make it clear that the
-variable is not live during the call. So:
-
-@smallexample
- else if (*x == 2)
- @{
- @{
- int a = 42;
- bar (&a);
- @}
- /* The call is a tail call (would not be without the
- attribute). If bar stores the pointer anywhere, dereferencing
- it in foo is undefined behavior even without tail call
- optimization, and there is no warning. */
- [[gnu::musttail]] return foo (nullptr);
- @}
-@end smallexample
-
-It is not possible to avoid the warning in this way if the maybe-escaped
-variable is a function argument, because those are in scope
-for the whole function.
-@end table
@node GNU Attribute Syntax
@subsection GNU Attribute Syntax
for attributes in C++ may be restricted in future to attributes on
declarations only, but not on nested declarators.
-@xref{Function Attributes}, for details of the semantics of attributes
-applying to functions. @xref{Variable Attributes}, for details of the
-semantics of attributes applying to variables. @xref{Type Attributes},
-for details of the semantics of attributes applying to structure, union
-and enumerated types.
-@xref{Label Attributes}, for details of the semantics of attributes
-applying to labels.
-@xref{Enumerator Attributes}, for details of the semantics of attributes
-applying to enumerators.
-@xref{Statement Attributes}, for details of the semantics of attributes
-applying to statements.
+@xref{Attributes}, for details of the semantics of attributes.
+applying to functions.
An @dfn{attribute specifier} is of the form
@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
GCC supports several types of pragmas, primarily in order to compile
code originally written for other compilers. Note that in general
-we do not recommend the use of pragmas; @xref{Function Attributes},
-for further explanation.
+we do not recommend the use of pragmas; attributes (@pxref{Attributes})
+are usually a better and more portable solution.
The GNU C preprocessor recognizes several pragmas in addition to the
compiler pragmas documented here. Refer to the CPP manual for more
@end smallexample
where @code{@var{string}} can be any string accepted as an AArch64 target
-attribute. @xref{AArch64 Function Attributes}, for more details
+attribute. @xref{AArch64 Attributes}, for more details
on the permissible values of @code{string}.
@node ARM Pragmas
The ARM target defines pragmas for controlling the default addition of
@code{long_call} and @code{short_call} attributes to functions.
-@xref{Function Attributes}, for information about the effects of these
+@xref{Attributes}, for information about the effects of these
attributes.
@table @code
@node LoongArch Pragmas
@subsection LoongArch Pragmas
-The list of attributes supported by Pragma is the same as that of target
-function attributes. @xref{LoongArch Function Attributes}.
+The list of attributes supported by pragma is the same as that of target
+function attributes. @xref{LoongArch Attributes}.
Example:
@item align @var{alignment} (@var{variable} [, @var{variable}]...)
Increase the minimum alignment of each @var{variable} to @var{alignment}.
-This is the same as GCC's @code{aligned} attribute @pxref{Variable
+This is the same as GCC's @code{aligned} attribute (@pxref{Common
Attributes}). Macro expansion occurs on the arguments to this pragma
when compiling C and Objective-C@. It does not currently occur when
compiling C++, but this is a bug which may be fixed in a future
@end table
-You can also use the @code{packed} type attribute (@pxref{Common Type
-Attributes}) to pack a structure. However, the @code{packed}
+You can also use the @code{packed} type attribute (@pxref{Common Attributes})
+to pack a structure. However, the @code{packed}
attribute interferes with @code{#pragma pack}, and attempting to use
them together may cause spurious warnings or unexpected behavior.
@c FIXME: This is PR 60972.
Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct}
directive, which causes subsequent structure and union declarations to
be laid out in the same way as
-@code{__attribute__ ((ms_struct))}; @pxref{x86 Variable Attributes}.
+@code{__attribute__ ((ms_struct))}; @pxref{x86 Attributes}.
@table @code
@item #pragma ms_struct on
Most targets also support the @code{#pragma scalar_storage_order} directive
which lays out subsequent structure and union declarations in
in the same way as the documented
-@code{__attribute__ ((scalar_storage_order))}; @pxref{Common Type Attributes}.
+@code{__attribute__ ((scalar_storage_order))}; @pxref{Common Attributes}.
@table @code
@item #pragma scalar_storage_order big-endian
This pragma allows the user to set the visibility for multiple
declarations without having to give each a visibility attribute
-(@pxref{Function Attributes}).
+(@pxref{Attributes}).
In C++, @samp{#pragma GCC visibility} affects only namespace-scope
declarations. Class members and template specializations are not
specified. Each function that is defined after this point is treated
as if it had been declared with one @code{target(}@var{string}@code{)}
attribute for each @var{string} argument. The parentheses around
-the strings in the pragma are optional. @xref{Function Attributes},
+the strings in the pragma are optional. @xref{Common Attributes},
for more information about the @code{target} attribute and the attribute
syntax.
specified. Each function that is defined after this point is treated
as if it had been declared with one @code{optimize(}@var{string}@code{)}
attribute for each @var{string} argument. The parentheses around
-the strings in the pragma are optional. @xref{Function Attributes},
+the strings in the pragma are optional. @xref{Common Attributes},
for more information about the @code{optimize} attribute and the attribute
syntax.
smaller, safer, and more efficient code, and in most cases it is a
better solution than basic @code{asm}. However, functions declared
with the @code{naked} attribute require only basic @code{asm}
-(@pxref{Function Attributes}).
+(@pxref{Common Attributes}).
Basic @code{asm} statements may be used both inside a C function or at
file scope (``top-level''), where you can use this technique to emit
allow using any register.
Functions declared with the @code{naked} attribute require basic
-@code{asm} (@pxref{Function Attributes}).
+@code{asm} (@pxref{Common Attributes}).
While the uses of @code{asm} are many and varied, it may help to think of an
@code{asm} statement as a series of low-level instructions that convert input
@code{asm} execution falls through to the next statement (if this is not the
case, consider using the @code{__builtin_unreachable} intrinsic after the
@code{asm} statement). Optimization of @code{asm goto} may be improved by
-using the @code{hot} and @code{cold} label attributes (@pxref{Label
+using the @code{hot} and @code{cold} label attributes (@pxref{Common
Attributes}).
If the assembler code does modify anything, use the @code{"memory"} clobber
If the operand of @code{__alignof__} is an lvalue rather than a type,
its value is the required alignment for its type, taking into account
any minimum alignment specified by attribute @code{aligned}
-(@pxref{Common Variable Attributes}). For example, after this
+(@pxref{Common Attributes}). For example, after this
declaration:
@smallexample
If the operand of the @code{__alignof__} expression is a function,
the expression evaluates to the alignment of the function which may
-be specified by attribute @code{aligned} (@pxref{Common Function Attributes}).
+be specified by attribute @code{aligned} (@pxref{Common Attributes}).
@node Enum Extensions
@subsection Extensions to @code{enum} Type Declarations
GCC defines this use of the @code{const} qualifier to have the same meaning
as the GCC @code{const} function attribute, and the @code{volatile} qualifier
to be equivalent to the @code{noreturn} attribute.
-@xref{Common Function Attributes}, for more information.
+@xref{Common Attributes}, for more information.
As examples of this usage,
(if known at compile time). To determine the sizes of dynamically allocated
objects the function relies on the allocation functions called to obtain
the storage to be declared with the @code{alloc_size} attribute (@pxref{Common
-Function Attributes}). @code{__builtin_object_size} never evaluates
+Attributes}). @code{__builtin_object_size} never evaluates
its arguments for side effects. If there are any side effects in them, it
returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0}
for @var{type} 2 or 3. If there are multiple objects @var{ptr} can
Some attributes only make sense for C++ programs.
@table @code
-@cindex @code{abi_tag} function attribute
-@cindex @code{abi_tag} variable attribute
-@cindex @code{abi_tag} type attribute
+@cindex @code{abi_tag} attribute
@item abi_tag ("@var{tag}", ...)
The @code{abi_tag} attribute can be applied to a function, variable, or class
declaration. It modifies the mangled name of the entity to
order of initialization of objects defined at namespace scope with the
@code{init_priority} attribute by specifying a relative @var{priority},
with the same meaning as for the @code{constructor} attribute
-(@pxref{Common Function Attributes}).
+(@pxref{Common Attributes}).
In the following example, @code{A} would normally be created before
@code{B}, but the @code{init_priority} attribute reverses that order:
@code{init_priority} attribute. In that case the attribute is rejected
with an error rather than ignored.
-@cindex @code{no_dangling} type attribute
-@cindex @code{no_dangling} function attribute
+@cindex @code{no_dangling} attribute
@item no_dangling
This attribute can be applied on a class type, function, or member
precedence and the @code{cold} attribute is not propagated.
For the effects of the @code{cold} attribute on functions, see
-@ref{Common Function Attributes}.
+@ref{Common Attributes}.
@cindex @code{hot} type attribute
@item hot
precedence and the @code{hot} attribute is not propagated.
For the effects of the @code{hot} attribute on functions, see
-@ref{Common Function Attributes}.
+@ref{Common Attributes}.
@end table
projects / thirdparty / gcc.git / commitdiff
