-@c Copyright (C) 1988-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2015 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
* Escaped Newlines:: Slightly looser rules for escaped newlines.
* Subscripting:: Any array can be subscripted, even if not an lvalue.
* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
+* Pointers to Arrays:: Pointers to arrays with qualifiers work as expected.
* Initializers:: Non-constant initializers.
* Compound Literals:: Compound literals give structures, unions
or arrays as values.
* Mixed Declarations:: Mixing declarations and code.
* Function Attributes:: Declaring that functions have no side effects,
or that they can never return.
+* Label Attributes:: Specifying attributes on labels.
* Attribute Syntax:: Formal syntax for attributes.
* Function Prototypes:: Prototype declarations and old-style definitions.
* C++ Comments:: C++ comments are recognized.
* Alignment:: Inquiring about the alignment of a type or variable.
* Inline:: Defining inline functions (as fast as macros).
* Volatiles:: What constitutes an access to a volatile object.
-* Extended Asm:: Assembler instructions with C expressions as operands.
- (With them you can define ``built-in'' functions.)
-* Constraints:: Constraints for asm operands
-* Asm Labels:: Specifying the assembler name to use for a C symbol.
-* Explicit Reg Vars:: Defining variables residing in specified registers.
+* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler.
* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
* Incomplete Enums:: @code{enum foo;}, with details to follow.
* Function Names:: Printable strings which are the name of the current
* Offsetof:: Special syntax for implementing @code{offsetof}.
* __sync Builtins:: Legacy built-in functions for atomic memory access.
* __atomic Builtins:: Atomic built-in functions with memory model.
+* Integer Overflow Builtins:: Built-in functions to perform arithmetics and
+ arithmetic overflow checking.
* x86 specific memory model extensions for transactional memory:: x86 memory models.
* Object Size Checking:: Built-in functions for limited buffer overflow
checking.
+* Pointer Bounds Checker builtins:: Built-in functions for Pointer Bounds Checker.
* Cilk Plus Builtins:: Built-in functions for the Cilk Plus language extension.
* Other Builtins:: Other built-in functions.
* Target Builtins:: Built-in functions specific to particular targets.
This is more friendly to code living in shared libraries, as it reduces
the number of dynamic relocations that are needed, and by consequence,
allows the data to be read-only.
+This alternative with label differences is not supported for the AVR target,
+please use the first approach for AVR programs.
The @code{&&foo} expressions for the same label might have different
values if the containing function is inlined or cloned. If a program
struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.}
struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.}
-struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
+struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.}
@end smallexample
@node Empty Structures
storage. Jumping into the scope is not allowed; you get an error
message for it.
+@cindex variable-length array in a structure
+As an extension, GCC accepts variable-length arrays as a member of
+a structure or a union. For example:
+
+@smallexample
+void
+foo (int n)
+@{
+ struct S @{ int x[n]; @};
+@}
+@end smallexample
+
@cindex @code{alloca} vs variable-length arrays
You can use the function @code{alloca} to get an effect much like
variable-length arrays. The function @code{alloca} is available in
The option @option{-Wpointer-arith} requests a warning if these extensions
are used.
+@node Pointers to Arrays
+@section Pointers to arrays with qualifiers work as expected
+@cindex pointers to arrays
+@cindex const qualifier
+
+In GNU C, pointers to arrays with qualifiers work similar to pointers
+to other qualified types. For example, a value of type @code{int (*)[5]}
+can be used to initialize a variable of type @code{const int (*)[5]}.
+These types are incompatible in ISO C because the @code{const} qualifier
+is formally attached to the element type of the array and not the
+array itself.
+
+@smallexample
+extern void
+transpose (int N, int M, double out[M][N], const double in[N][M]);
+double x[3][2];
+double y[2][3];
+@r{@dots{}}
+transpose(3, 2, y, x);
+@end smallexample
+
@node Initializers
@section Non-Constant Initializers
@cindex initializers, non-constant
struct point p = @{ y: yvalue, x: xvalue @};
@end smallexample
+Omitted field members are implicitly initialized the same as objects
+that have static storage duration.
+
@cindex designators
The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a
@dfn{designator}. You can also use a designator (or the obsolete colon
attributes when making a declaration. This keyword is followed by an
attribute specification inside double parentheses. The following
attributes are currently defined for functions on all targets:
-@code{aligned}, @code{alloc_size}, @code{noreturn},
-@code{returns_twice}, @code{noinline}, @code{noclone},
+@code{aligned}, @code{alloc_size}, @code{alloc_align}, @code{assume_aligned},
+@code{noreturn}, @code{returns_twice}, @code{noinline}, @code{noclone},
@code{always_inline}, @code{flatten}, @code{pure}, @code{const},
@code{nothrow}, @code{sentinel}, @code{format}, @code{format_arg},
@code{no_instrument_function}, @code{no_split_stack},
@code{returns_nonnull}, @code{gnu_inline},
@code{externally_visible}, @code{hot}, @code{cold}, @code{artificial},
@code{no_sanitize_address}, @code{no_address_safety_analysis},
-@code{no_sanitize_undefined},
+@code{no_sanitize_undefined}, @code{no_reorder}, @code{bnd_legacy},
+@code{bnd_instrument},
@code{error} and @code{warning}.
Several other attributes are defined for functions on particular
target systems. Other attributes, including @code{section} are
-supported for variables declarations (@pxref{Variable Attributes})
+supported for variables declarations (@pxref{Variable Attributes}),
+labels (@pxref{Label Attributes})
and for types (@pxref{Type Attributes}).
GCC plugins may provide their own attributes.
@smallexample
void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2)))
-void my_realloc(void*, size_t) __attribute__((alloc_size(2)))
+void* my_realloc(void*, size_t) __attribute__((alloc_size(2)))
@end smallexample
@noindent
the product of parameter 1 and 2 and that @code{my_realloc} returns memory
of the size given by parameter 2.
+@item alloc_align
+@cindex @code{alloc_align} attribute
+The @code{alloc_align} attribute is used to tell the compiler that the
+function return value points to memory, where the returned pointer minimum
+alignment is given by one of the functions parameters. GCC uses this
+information to improve pointer alignment analysis.
+
+The function parameter denoting the allocated alignment is specified by
+one integer argument, whose number is the argument of the attribute.
+Argument numbering starts at one.
+
+For instance,
+
+@smallexample
+void* my_memalign(size_t, size_t) __attribute__((alloc_align(1)))
+@end smallexample
+
+@noindent
+declares that @code{my_memalign} returns memory with minimum alignment
+given by parameter 1.
+
+@item assume_aligned
+@cindex @code{assume_aligned} attribute
+The @code{assume_aligned} attribute is used to tell the compiler that the
+function return value points to memory, where the returned pointer minimum
+alignment is given by the first argument.
+If the attribute has two arguments, the second argument is misalignment offset.
+
+For instance
+
+@smallexample
+void* my_alloc1(size_t) __attribute__((assume_aligned(16)))
+void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8)))
+@end smallexample
+
+@noindent
+declares that @code{my_alloc1} returns 16-byte aligned pointer and
+that @code{my_alloc2} returns a pointer whose value modulo 32 is equal
+to 8.
+
@item always_inline
@cindex @code{always_inline} function attribute
Generally, functions are not inlined unless optimization is specified.
-For functions declared inline, this attribute inlines the function even
-if no optimization level is specified.
+For functions declared inline, this attribute inlines the function
+independent of any restrictions that otherwise apply to inlining.
+Failure to inline such a function is diagnosed as an error.
+Note that if such a function is called indirectly the compiler may
+or may not inline it depending on optimization level and a failure
+to inline an indirect call may or may not be diagnosed.
@item gnu_inline
@cindex @code{gnu_inline} function attribute
@item interrupt
@cindex interrupt handler functions
Use this attribute on the ARC, ARM, AVR, CR16, Epiphany, M32C, M32R/D,
-m68k, MeP, MIPS, MSP430, RL78, RX and Xstormy16 ports 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. With Epiphany targets it may also generate a special section with
-code to initialize the interrupt vector table.
+m68k, MeP, MIPS, MSP430, RL78, RX, Visium and Xstormy16 ports 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. With Epiphany targets it may also generate
+a special section with code to initialize the interrupt vector table.
Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze,
and SH processors can be specified via the @code{interrupt_handler} attribute.
handlers intended to be used with the @code{BRK} opcode (i.e.@: those
that must end with @code{RETB} instead of @code{RETI}).
+On RX 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
+
@item interrupt_handler
@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors
Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to
@item malloc
@cindex @code{malloc} attribute
-The @code{malloc} attribute is used to tell the compiler that a function
-may be treated as if any non-@code{NULL} pointer it returns cannot
-alias any other pointer valid when the function returns and that the memory
-has undefined content.
-This often improves optimization.
-Standard functions with this property include @code{malloc} and
-@code{calloc}. @code{realloc}-like functions do not have this
-property as the memory pointed to does not have undefined content.
+This tells the compiler that a function is @code{malloc}-like, i.e.,
+that the pointer @var{P} returned by the function cannot alias any
+other pointer valid when the function returns, and moreover no
+pointers to valid objects occur in any storage addressed by @var{P}.
+
+Using this attribute can improve optimization. Functions like
+@code{malloc} and @code{calloc} have this property because they return
+a pointer to uninitialized or zeroed-out storage. However, functions
+like @code{realloc} do not have this property, as they can return a
+pointer to storage containing pointers.
@item mips16/nomips16
@cindex @code{mips16} attribute
@item naked
@cindex function without a prologue/epilogue code
-Use this attribute on the ARM, AVR, MCORE, MSP430, NDS32, RL78, RX and SPU
-ports to indicate that the specified function does not need prologue/epilogue
-sequences generated by the compiler.
-It is up to the programmer to provide these sequences. The
-only statements that can be safely included in naked functions are
-@code{asm} statements that do not have operands. All other statements,
-including declarations of local variables, @code{if} statements, and so
-forth, should be avoided. Naked functions should be used to implement the
-body of an assembly function, while allowing the compiler to construct
-the requisite function declaration for the assembler.
+This attribute is available on the ARM, AVR, MCORE, MSP430, NDS32,
+RL78, RX and SPU ports. It 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 near
@cindex functions that do not handle memory bank switching on 68HC11/68HC12
__attribute__((nonnull));
@end smallexample
+@item no_reorder
+@cindex @code{no_reorder} function or variable attribute
+Do not reorder functions or variables marked @code{no_reorder}
+against each other or top level assembler statements the executable.
+The actual order in the program will depend on the linker command
+line. Static variables marked like this are also not removed.
+This has a similar effect
+as the @option{-fno-toplevel-reorder} option, but only applies to the
+marked symbols.
+
@item returns_nonnull
@cindex @code{returns_nonnull} function attribute
The @code{returns_nonnull} attribute specifies that the function
@cindex @code{hot} function attribute
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 target it is placed into special
-subsection of the text section so all hot functions appears close together
+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.
When profile feedback is available, via @option{-fprofile-use}, hot functions
The @code{hot} attribute on functions is not implemented in GCC versions
earlier than 4.3.
-@cindex @code{hot} label attribute
-The @code{hot} attribute on a label is used to inform the compiler that
-path following the label are 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}.
-
-The @code{hot} attribute on labels is not implemented in GCC versions
-earlier than 4.8.
-
@item cold
@cindex @code{cold} function attribute
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 special
-subsection of the text section so all cold functions appears close together
+size rather than speed and on many targets it is placed into a special
+subsection of the text section so all cold functions appear close together,
improving code locality of non-cold parts of program. The paths leading
-to call of cold functions within code are marked as unlikely by the branch
+to calls of cold functions within code are marked as unlikely by the branch
prediction mechanism. It is thus useful to mark functions used to handle
unlikely conditions, such as @code{perror}, as cold to improve optimization
of hot functions that do call marked functions in rare occasions.
The @code{cold} attribute on functions is not implemented in GCC versions
earlier than 4.3.
-@cindex @code{cold} label attribute
-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}.
-
-The @code{cold} attribute on labels is not implemented in GCC versions
-earlier than 4.8.
-
@item no_sanitize_address
@itemx no_address_safety_analysis
@cindex @code{no_sanitize_address} function attribute
to inform the compiler that it should not check for undefined behavior
in the function when compiling with the @option{-fsanitize=undefined} option.
+@item bnd_legacy
+@cindex @code{bnd_legacy} function attribute
+The @code{bnd_legacy} attribute on functions is used to inform
+compiler that function should not be instrumented when compiled
+with @option{-fcheck-pointer-bounds} option.
+
+@item bnd_instrument
+@cindex @code{bnd_instrument} function attribute
+The @code{bnd_instrument} attribute on functions is used to inform
+compiler that function should be instrumented when compiled
+with @option{-fchkp-instrument-marked-only} option.
+
@item regparm (@var{number})
@cindex @code{regparm} attribute
@cindex functions that are passed arguments in registers on the 386
function, only volatiles used by the function are saved. A normal function
return is generated instead of a return from interrupt.
+@item break_handler
+@cindex break handler functions
+Use this attribute on the MicroBlaze ports to indicate that
+the specified function is an 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}.
+
+@smallexample
+void f () __attribute__ ((break_handler));
+@end smallexample
+
@item section ("@var{section-name}")
@cindex @code{section} function attribute
Normally, the compiler places the code it generates in the @code{text} section.
int sse3_func (void) __attribute__ ((__target__ ("sse3")));
@end smallexample
+You can either use multiple
+strings to specify multiple options, or separate the options
+with a comma (@samp{,}).
+
+The @code{target} attribute is presently implemented for
+i386/x86_64, PowerPC, and Nios II targets only.
+The options supported are specific to each target.
+
On the 386, the following options are allowed:
@table @samp
default tuning specified on the command line.
@end table
-On the 386/x86_64 and PowerPC back ends, you can use either multiple
-strings to specify multiple options, or you can separate the option
-with a comma (@code{,}).
+When compiling for Nios II, the following options are allowed:
+
+@table @samp
+@item custom-@var{insn}=@var{N}
+@itemx no-custom-@var{insn}
+@cindex @code{target("custom-@var{insn}=@var{N}")} attribute
+@cindex @code{target("no-custom-@var{insn}")} attribute
+Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a
+custom instruction with encoding @var{N} when generating code that uses
+@var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of
+the custom instruction @var{insn}.
+These target attributes correspond to the
+@option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}}
+command-line options, and support the same set of @var{insn} keywords.
+@xref{Nios II Options}, for more information.
+
+@item custom-fpu-cfg=@var{name}
+@cindex @code{target("custom-fpu-cfg=@var{name}")} attribute
+This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}}
+command-line option, to select a predefined set of custom instructions
+named @var{name}.
+@xref{Nios II Options}, for more information.
+@end table
On the 386/x86_64 and PowerPC back ends, the inliner does not inline a
function that has different target options than the caller, unless the
a function declared with @code{target("sse3")} can inline a function
with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}.
-The @code{target} attribute is not implemented in GCC versions earlier
-than 4.4 for the i386/x86_64 and 4.6 for the PowerPC back ends. It is
-not currently implemented for other back ends.
-
@item tiny_data
@cindex tiny data section on the H8/300H and H8S
Use this attribute on the H8/300H and H8S to indicate that the specified
attribute also means that the function is instantiated if the
class itself is instantiated.
+@item vector
+@cindex @code{vector} attribute
+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.
+
@item version_id
@cindex @code{version_id} attribute
This IA-64 HP-UX attribute, attached to a global variable or function, renames a
@code{#pragma GCC} is of use for constructs that do not naturally form
part of the grammar. @xref{Pragmas,,Pragmas Accepted by GCC}.
+@node Label Attributes
+@section Label Attributes
+@cindex Label Attributes
+
+GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for
+details of the exact syntax for using attributes. Other attributes are
+available for functions (@pxref{Function Attributes}), variables
+(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}).
+
+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 fallthru 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
+@item unused
+@cindex @code{unused} label attribute
+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 in it 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.
+
+@item hot
+@cindex @code{hot} label attribute
+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}.
+
+The @code{hot} attribute on labels is not implemented in GCC versions
+earlier than 4.8.
+
+@item cold
+@cindex @code{cold} label attribute
+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}.
+
+The @code{cold} attribute on labels is not implemented in GCC versions
+earlier than 4.8.
+
+@end table
+
@node Attribute Syntax
@section Attribute Syntax
@cindex attribute syntax
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.
An @dfn{attribute specifier} is of the form
@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list}
An @dfn{attribute specifier list} is a sequence of one or more attribute
specifiers, not separated by any other tokens.
+@subsubheading Label Attributes
+
In GNU C, an attribute specifier list may appear after the colon following a
-label, other than a @code{case} or @code{default} label. The only
-attribute it makes sense to use after a label is @code{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 in it 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. GNU C++ only permits
+label, other than a @code{case} or @code{default} label. GNU C++ only permits
attributes on labels if the attribute specifier is immediately
followed by a semicolon (i.e., the label applies to an empty
statement). If the semicolon is missing, C++ label attributes are
with an attribute list, to be labelled in C++. Declarations cannot be
labelled in C90 or C99, so the ambiguity does not arise there.
+@subsubheading Type Attributes
+
An attribute specifier list may appear as part of a @code{struct},
@code{union} or @code{enum} specifier. It may go either immediately
after the @code{struct}, @code{union} or @code{enum} keyword, or after
@c attributes could use sizeof for the structure, but the size could be
@c changed later by "packed" attributes.
+
+@subsubheading All other attributes
+
Otherwise, an attribute specifier appears as part of a declaration,
counting declarations of unnamed parameters and type names, and relates
to that declaration (which may be nested in another declaration, for
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}) and for types (@pxref{Type Attributes}).
+(@pxref{Function Attributes}), labels (@pxref{Label Attributes}) and for
+types (@pxref{Type Attributes}).
Other front ends might define more attributes
(@pxref{C++ Extensions,,Extensions to the C++ Language}).
See also the @ref{AVR Named Address Spaces} section for
an alternate way to locate and access data in flash memory.
+
+@item io
+@itemx io (@var{addr})
+Variables with the @code{io} attribute are used to address
+memory-mapped peripherals in the io address range.
+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:
+
+@smallexample
+volatile int porta __attribute__((io (0x22)));
+@end smallexample
+
+The address specified in the address in the data address range.
+
+Otherwise, the variable it is not assigned an address, but the
+compiler will still use in/out instructions where applicable,
+assuming some other module assigns an address in the io address range.
+Example:
+
+@smallexample
+extern volatile int porta __attribute__((io));
+@end smallexample
+
+@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.
+
+@item address
+@itemx address (@var{addr})
+Variables with the @code{address} attribute are used to address
+memory-mapped peripherals that may lie outside the io address range.
+
+@smallexample
+volatile int porta __attribute__((address (0x600)));
+@end smallexample
+
@end table
@subsection Blackfin Variable Attributes
The keyword @code{__attribute__} allows you to specify special
attributes of @code{struct} and @code{union} types when you define
such types. This keyword is followed by an attribute specification
-inside double parentheses. Seven attributes are currently defined for
+inside double parentheses. Eight attributes are currently defined for
types: @code{aligned}, @code{packed}, @code{transparent_union},
-@code{unused}, @code{deprecated}, @code{visibility}, and
-@code{may_alias}. Other attributes are defined for functions
-(@pxref{Function Attributes}) and for variables (@pxref{Variable
-Attributes}).
+@code{unused}, @code{deprecated}, @code{visibility}, @code{may_alias}
+and @code{bnd_variable_size}. Other attributes are defined for
+functions (@pxref{Function Attributes}), labels (@pxref{Label
+Attributes}) and for variables (@pxref{Variable Attributes}).
You may also specify any one of these attributes with @samp{__}
preceding and following its keyword. This allows you to use these
also define the enumerated type, structure or union.
@item transparent_union
+@cindex @code{transparent_union} attribute
+
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.
Otherwise the two shared objects are unable to use the same
typeinfo node and exception handling will break.
+@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.
+
+@item bnd_variable_size
+When applied to a structure field, this attribute tells Pointer
+Bounds Checker that the size of this field should not be computed
+using static type information. It may be used to mark variable
+sized static array fields placed at the end of a structure.
+
+@smallexample
+struct S
+@{
+ int size;
+ char data[1];
+@}
+S *p = (S *)malloc (sizeof(S) + 100);
+p->data[10] = 0; //Bounds violation
+@end smallexample
+
+By using an attribute for a field we may avoid bound violation
+we most probably do not want to see:
+
+@smallexample
+struct S
+@{
+ int size;
+ char data[1] __attribute__((bnd_variable_size));
+@}
+S *p = (S *)malloc (sizeof(S) + 100);
+p->data[10] = 0; //OK
+@end smallexample
+
@end table
To specify multiple attributes, separate them by commas within the
boundary. For these reasons it is unwise to use volatile bit-fields to
access hardware.
+@node Using Assembly Language with C
+@section How to Use Inline Assembly Language in C Code
+
+GCC provides various extensions that allow you to embed assembler within
+C code.
+
+@menu
+* Basic Asm:: Inline assembler with no operands.
+* Extended Asm:: Inline assembler with operands.
+* Constraints:: Constraints for @code{asm} operands
+* Asm Labels:: Specifying the assembler name to use for a C symbol.
+* Explicit Reg Vars:: Defining variables residing in specified registers.
+* Size of an asm:: How GCC calculates the size of an @code{asm} block.
+@end menu
+
+@node Basic Asm
+@subsection Basic Asm --- Assembler Instructions with No Operands
+@cindex basic @code{asm}
+
+The @code{asm} keyword allows you to embed assembler instructions within
+C code.
+
+@example
+asm [ volatile ] ( AssemblerInstructions )
+@end example
+
+To create headers compatible with ISO C, write @code{__asm__} instead of
+@code{asm} (@pxref{Alternate Keywords}).
+
+By definition, a Basic @code{asm} statement is one with no operands.
+@code{asm} statements that contain one or more colons (used to delineate
+operands) are considered to be Extended (for example, @code{asm("int $3")}
+is Basic, and @code{asm("int $3" : )} is Extended). @xref{Extended Asm}.
+
+@subsubheading Qualifiers
+@emph{volatile}
+@*
+This optional qualifier has no effect. All Basic @code{asm} blocks are
+implicitly volatile.
+
+@subsubheading Parameters
+@emph{AssemblerInstructions}
+@*
+This is a literal string that specifies the assembler code. The string can
+contain any instructions recognized by the assembler, including directives.
+GCC does not parse the assembler instructions themselves and
+does not know what they mean or even whether they are valid assembler input.
+The compiler copies it verbatim to the assembly language output file, without
+processing dialects or any of the "%" operators that are available with
+Extended @code{asm}. This results in minor differences between Basic
+@code{asm} strings and Extended @code{asm} templates. For example, to refer to
+registers you might use %%eax in Extended @code{asm} and %eax in Basic
+@code{asm}.
+
+You may place multiple assembler instructions together in a single @code{asm}
+string, separated by the characters normally used in assembly code for the
+system. A combination that works in most places is a newline to break the
+line, plus a tab character (written as "\n\t").
+Some assemblers allow semicolons as a line separator. However,
+note that some assembler dialects use semicolons to start a comment.
+
+Do not expect a sequence of @code{asm} statements to remain perfectly
+consecutive after compilation. If certain instructions need to remain
+consecutive in the output, put them in a single multi-instruction asm
+statement. Note that GCC's optimizers can move @code{asm} statements
+relative to other code, including across jumps.
+
+@code{asm} statements may not perform jumps into other @code{asm} statements.
+GCC does not know about these jumps, and therefore cannot take
+account of them when deciding how to optimize. Jumps from @code{asm} to C
+labels are only supported in Extended @code{asm}.
+
+@subsubheading Remarks
+Using Extended @code{asm} will typically produce smaller, safer, and more
+efficient code, and in most cases it is a better solution. When writing
+inline assembly language outside of C functions, however, you must use Basic
+@code{asm}. Extended @code{asm} statements have to be inside a C function.
+Functions declared with the @code{naked} attribute also require Basic
+@code{asm} (@pxref{Function Attributes}).
+
+Under certain circumstances, GCC may duplicate (or remove duplicates of) your
+assembly code when optimizing. This can lead to unexpected duplicate
+symbol errors during compilation if your assembly code defines symbols or
+labels.
+
+Safely accessing C data and calling functions from Basic @code{asm} is more
+complex than it may appear. To access C data, it is better to use Extended
+@code{asm}.
+
+Since GCC does not parse the AssemblerInstructions, it has no
+visibility of any symbols it references. This may result in GCC discarding
+those symbols as unreferenced.
+
+Unlike Extended @code{asm}, all Basic @code{asm} blocks are implicitly
+volatile. @xref{Volatile}. Similarly, Basic @code{asm} blocks are not treated
+as though they used a "memory" clobber (@pxref{Clobbers}).
+
+All Basic @code{asm} blocks use the assembler dialect specified by the
+@option{-masm} command-line option. Basic @code{asm} provides no
+mechanism to provide different assembler strings for different dialects.
+
+Here is an example of Basic @code{asm} for i386:
+
+@example
+/* Note that this code will not compile with -masm=intel */
+#define DebugBreak() asm("int $3")
+@end example
+
@node Extended Asm
-@section Assembler Instructions with C Expression Operands
+@subsection Extended Asm - Assembler Instructions with C Expression Operands
+@cindex @code{asm} keyword
@cindex extended @code{asm}
-@cindex @code{asm} expressions
@cindex assembler instructions
-@cindex registers
-In an assembler instruction using @code{asm}, you can specify the
-operands of the instruction using C expressions. This means you need not
-guess which registers or memory locations contain the data you want
-to use.
+The @code{asm} keyword allows you to embed assembler instructions within C
+code. With Extended @code{asm} you can read and write C variables from
+assembler and perform jumps from assembler code to C labels.
-You must specify an assembler instruction template much like what
-appears in a machine description, plus an operand constraint string for
-each operand.
+@example
+@ifhtml
+asm [volatile] ( AssemblerTemplate : [OutputOperands] [ : [InputOperands] [ : [Clobbers] ] ] )
+
+asm [volatile] goto ( AssemblerTemplate : : [InputOperands] : [Clobbers] : GotoLabels )
+@end ifhtml
+@ifnothtml
+asm [volatile] ( AssemblerTemplate
+ : [OutputOperands]
+ [ : [InputOperands]
+ [ : [Clobbers] ] ])
+
+asm [volatile] goto ( AssemblerTemplate
+ :
+ : [InputOperands]
+ : [Clobbers]
+ : GotoLabels)
+@end ifnothtml
+@end example
-For example, here is how to use the 68881's @code{fsinx} instruction:
+To create headers compatible with ISO C, write @code{__asm__} instead of
+@code{asm} and @code{__volatile__} instead of @code{volatile}
+(@pxref{Alternate Keywords}). There is no alternate for @code{goto}.
+
+By definition, Extended @code{asm} is an @code{asm} statement that contains
+operands. To separate the classes of operands, you use colons. Basic
+@code{asm} statements contain no colons. (So, for example,
+@code{asm("int $3")} is Basic @code{asm}, and @code{asm("int $3" : )} is
+Extended @code{asm}. @pxref{Basic Asm}.)
+
+@subsubheading Qualifiers
+@emph{volatile}
+@*
+The typical use of Extended @code{asm} statements is to manipulate input
+values to produce output values. However, your @code{asm} statements may
+also produce side effects. If so, you may need to use the @code{volatile}
+qualifier to disable certain optimizations. @xref{Volatile}.
+
+@emph{goto}
+@*
+This qualifier informs the compiler that the @code{asm} statement may
+perform a jump to one of the labels listed in the GotoLabels section.
+@xref{GotoLabels}.
+
+@subsubheading Parameters
+@emph{AssemblerTemplate}
+@*
+This is a literal string that contains the assembler code. It is a
+combination of fixed text and tokens that refer to the input, output,
+and goto parameters. @xref{AssemblerTemplate}.
+
+@emph{OutputOperands}
+@*
+A comma-separated list of the C variables modified by the instructions in the
+AssemblerTemplate. @xref{OutputOperands}.
+
+@emph{InputOperands}
+@*
+A comma-separated list of C expressions read by the instructions in the
+AssemblerTemplate. @xref{InputOperands}.
+
+@emph{Clobbers}
+@*
+A comma-separated list of registers or other values changed by the
+AssemblerTemplate, beyond those listed as outputs. @xref{Clobbers}.
+
+@emph{GotoLabels}
+@*
+When you are using the @code{goto} form of @code{asm}, this section contains
+the list of all C labels to which the AssemblerTemplate may jump.
+@xref{GotoLabels}.
+
+@subsubheading Remarks
+The @code{asm} statement allows you to include assembly instructions directly
+within C code. This may help you to maximize performance in time-sensitive
+code or to access assembly instructions that are not readily available to C
+programs.
+
+Note that Extended @code{asm} statements must be inside a function. Only
+Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
+Functions declared with the @code{naked} attribute also require Basic
+@code{asm} (@pxref{Function 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
+parameters to output parameters. So a simple (if not particularly useful)
+example for i386 using @code{asm} might look like this:
-@smallexample
-asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
-@end smallexample
+@example
+int src = 1;
+int dst;
-@noindent
-Here @code{angle} is the C expression for the input operand while
-@code{result} is that of the output operand. Each has @samp{"f"} as its
-operand constraint, saying that a floating-point register is required.
-The @samp{=} in @samp{=f} indicates that the operand is an output; all
-output operands' constraints must use @samp{=}. The constraints use the
-same language used in the machine description (@pxref{Constraints}).
-
-Each operand is described by an operand-constraint string followed by
-the C expression in parentheses. A colon separates the assembler
-template from the first output operand and another separates the last
-output operand from the first input, if any. Commas separate the
-operands within each group. The total number of operands is currently
-limited to 30; this limitation may be lifted in some future version of
-GCC@.
-
-If there are no output operands but there are input operands, you must
-place two consecutive colons surrounding the place where the output
-operands would go.
-
-As of GCC version 3.1, it is also possible to specify input and output
-operands using symbolic names which can be referenced within the
-assembler code. These names are specified inside square brackets
-preceding the constraint string, and can be referenced inside the
-assembler code using @code{%[@var{name}]} instead of a percentage sign
-followed by the operand number. Using named operands the above example
-could look like:
-
-@smallexample
-asm ("fsinx %[angle],%[output]"
- : [output] "=f" (result)
- : [angle] "f" (angle));
-@end smallexample
+asm ("mov %1, %0\n\t"
+ "add $1, %0"
+ : "=r" (dst)
+ : "r" (src));
-@noindent
-Note that the symbolic operand names have no relation whatsoever to
-other C identifiers. You may use any name you like, even those of
-existing C symbols, but you must ensure that no two operands within the same
-assembler construct use the same symbolic name.
-
-Output operand expressions must be lvalues; the compiler can check this.
-The input operands need not be lvalues. The compiler cannot check
-whether the operands have data types that are reasonable for the
-instruction being executed. It does not parse the assembler instruction
-template and does not know what it means or even whether it is valid
-assembler input. The extended @code{asm} feature is most often used for
-machine instructions the compiler itself does not know exist. If
-the output expression cannot be directly addressed (for example, it is a
-bit-field), your constraint must allow a register. In that case, GCC
-uses the register as the output of the @code{asm}, and then stores
-that register into the output.
-
-The ordinary output operands must be write-only; GCC assumes that
-the values in these operands before the instruction are dead and need
-not be generated. Extended asm supports input-output or read-write
-operands. Use the constraint character @samp{+} to indicate such an
-operand and list it with the output operands.
-
-You may, as an alternative, logically split its function into two
-separate operands, one input operand and one write-only output
-operand. The connection between them is expressed by constraints
-that say they need to be in the same location when the instruction
-executes. You can use the same C expression for both operands, or
-different expressions. For example, here we write the (fictitious)
-@samp{combine} instruction with @code{bar} as its read-only source
-operand and @code{foo} as its read-write destination:
-
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
-@end smallexample
+printf("%d\n", dst);
+@end example
-@noindent
-The constraint @samp{"0"} for operand 1 says that it must occupy the
-same location as operand 0. A number in constraint is allowed only in
-an input operand and it must refer to an output operand.
+This code will copy @var{src} to @var{dst} and add 1 to @var{dst}.
-Only a number in the constraint can guarantee that one operand is in
-the same place as another. The mere fact that @code{foo} is the value
-of both operands is not enough to guarantee that they are in the
-same place in the generated assembler code. The following does not
-work reliably:
+@anchor{Volatile}
+@subsubsection Volatile
+@cindex volatile @code{asm}
+@cindex @code{asm} volatile
-@smallexample
-asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
-@end smallexample
+GCC's optimizers sometimes discard @code{asm} statements if they determine
+there is no need for the output variables. Also, the optimizers may move
+code out of loops if they believe that the code will always return the same
+result (i.e. none of its input values change between calls). Using the
+@code{volatile} qualifier disables these optimizations. @code{asm} statements
+that have no output operands are implicitly volatile.
-Various optimizations or reloading could cause operands 0 and 1 to be in
-different registers; GCC knows no reason not to do so. For example, the
-compiler might find a copy of the value of @code{foo} in one register and
-use it for operand 1, but generate the output operand 0 in a different
-register (copying it afterward to @code{foo}'s own address). Of course,
-since the register for operand 1 is not even mentioned in the assembler
-code, the result will not work, but GCC can't tell that.
+Examples:
-As of GCC version 3.1, one may write @code{[@var{name}]} instead of
-the operand number for a matching constraint. For example:
+This i386 code demonstrates a case that does not use (or require) the
+@code{volatile} qualifier. If it is performing assertion checking, this code
+uses @code{asm} to perform the validation. Otherwise, @var{dwRes} is
+unreferenced by any code. As a result, the optimizers can discard the
+@code{asm} statement, which in turn removes the need for the entire
+@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it
+isn't needed you allow the optimizers to produce the most efficient code
+possible.
-@smallexample
-asm ("cmoveq %1,%2,%[result]"
- : [result] "=r"(result)
- : "r" (test), "r"(new), "[result]"(old));
-@end smallexample
+@example
+void DoCheck(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
-Sometimes you need to make an @code{asm} operand be a specific register,
-but there's no matching constraint letter for that register @emph{by
-itself}. To force the operand into that register, use a local variable
-for the operand and specify the register in the variable declaration.
-@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any
-register constraint letter that matches the register:
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
-@smallexample
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = @dots{};
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
-@end smallexample
+ assert(dwRes > 3);
+@}
+@end example
-@anchor{Example of asm with clobbered asm reg}
-In the above example, beware that a register that is call-clobbered by
-the target ABI will be overwritten by any function call in the
-assignment, including library calls for arithmetic operators.
-Also a register may be clobbered when generating some operations,
-like variable shift, memory copy or memory move on x86.
-Assuming it is a call-clobbered register, this may happen to @code{r0}
-above by the assignment to @code{p2}. If you have to use such a
-register, use temporary variables for expressions between the register
-assignment and use:
+The next example shows a case where the optimizers can recognize that the input
+(@var{dwSomeValue}) never changes during the execution of the function and can
+therefore move the @code{asm} outside the loop to produce more efficient code.
+Again, using @code{volatile} disables this type of optimization.
-@smallexample
-int t1 = @dots{};
-register int *p1 asm ("r0") = @dots{};
-register int *p2 asm ("r1") = t1;
-register int *result asm ("r0");
-asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
-@end smallexample
+@example
+void do_print(uint32_t dwSomeValue)
+@{
+ uint32_t dwRes;
+
+ for (uint32_t x=0; x < 5; x++)
+ @{
+ // Assumes dwSomeValue is not zero.
+ asm ("bsfl %1,%0"
+ : "=r" (dwRes)
+ : "r" (dwSomeValue)
+ : "cc");
+
+ printf("%u: %u %u\n", x, dwSomeValue, dwRes);
+ @}
+@}
+@end example
-Some instructions clobber specific hard registers. To describe this,
-write a third colon after the input operands, followed by the names of
-the clobbered hard registers (given as strings). Here is a realistic
-example for the VAX:
+The following example demonstrates a case where you need to use the
+@code{volatile} qualifier. It uses the i386 RDTSC instruction, which reads
+the computer's time-stamp counter. Without the @code{volatile} qualifier,
+the optimizers might assume that the @code{asm} block will always return the
+same value and therefore optimize away the second call.
-@smallexample
-asm volatile ("movc3 %0,%1,%2"
- : /* @r{no outputs} */
- : "g" (from), "g" (to), "g" (count)
- : "r0", "r1", "r2", "r3", "r4", "r5");
-@end smallexample
+@example
+uint64_t msr;
-You may not write a clobber description in a way that overlaps with an
-input or output operand. For example, you may not have an operand
-describing a register class with one member if you mention that register
-in the clobber list. Variables declared to live in specific registers
-(@pxref{Explicit Reg Vars}), and used as asm input or output operands must
-have no part mentioned in the clobber description.
-There is no way for you to specify that an input
-operand is modified without also specifying it as an output
-operand. Note that if all the output operands you specify are for this
-purpose (and hence unused), you then also need to specify
-@code{volatile} for the @code{asm} construct, as described below, to
-prevent GCC from deleting the @code{asm} statement as unused.
+asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
+ "shl $32, %%rdx\n\t" // Shift the upper bits left.
+ "or %%rdx, %0" // 'Or' in the lower bits.
+ : "=a" (msr)
+ :
+ : "rdx");
-If you refer to a particular hardware register from the assembler code,
-you probably have to list the register after the third colon to
-tell the compiler the register's value is modified. In some assemblers,
-the register names begin with @samp{%}; to produce one @samp{%} in the
-assembler code, you must write @samp{%%} in the input.
+printf("msr: %llx\n", msr);
-If your assembler instruction can alter the condition code register, add
-@samp{cc} to the list of clobbered registers. GCC on some machines
-represents the condition codes as a specific hardware register;
-@samp{cc} serves to name this register. On other machines, the
-condition code is handled differently, and specifying @samp{cc} has no
-effect. But it is valid no matter what the machine.
+// Do other work...
-If your assembler instructions access memory in an unpredictable
-fashion, add @samp{memory} to the list of clobbered registers. This
-causes GCC to not keep memory values cached in registers across the
-assembler instruction and not optimize stores or loads to that memory.
-You also should add the @code{volatile} keyword if the memory
-affected is not listed in the inputs or outputs of the @code{asm}, as
-the @samp{memory} clobber does not count as a side-effect of the
-@code{asm}. If you know how large the accessed memory is, you can add
-it as input or output but if this is not known, you should add
-@samp{memory}. As an example, if you access ten bytes of a string, you
-can use a memory input like:
+// Reprint the timestamp
+asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX.
+ "shl $32, %%rdx\n\t" // Shift the upper bits left.
+ "or %%rdx, %0" // 'Or' in the lower bits.
+ : "=a" (msr)
+ :
+ : "rdx");
-@smallexample
-@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}.
-@end smallexample
+printf("msr: %llx\n", msr);
+@end example
-Note that in the following example the memory input is necessary,
-otherwise GCC might optimize the store to @code{x} away:
-@smallexample
-int foo ()
-@{
- int x = 42;
- int *y = &x;
- int result;
- asm ("magic stuff accessing an 'int' pointed to by '%1'"
- : "=&d" (r) : "a" (y), "m" (*y));
- return result;
-@}
-@end smallexample
+GCC's optimizers will not treat this code like the non-volatile code in the
+earlier examples. They do not move it out of loops or omit it on the
+assumption that the result from a previous call is still valid.
+
+Note that the compiler can move even volatile @code{asm} instructions relative
+to other code, including across jump instructions. For example, on many
+targets there is a system register that controls the rounding mode of
+floating-point operations. Setting it with a volatile @code{asm}, as in the
+following PowerPC example, will not work reliably.
+
+@example
+asm volatile("mtfsf 255, %0" : : "f" (fpenv));
+sum = x + y;
+@end example
+
+The compiler may move the addition back before the volatile @code{asm}. To
+make it work as expected, add an artificial dependency to the @code{asm} by
+referencing a variable in the subsequent code, for example:
+
+@example
+asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv));
+sum = x + y;
+@end example
+
+Under certain circumstances, GCC may duplicate (or remove duplicates of) your
+assembly code when optimizing. This can lead to unexpected duplicate symbol
+errors during compilation if your asm code defines symbols or labels. Using %=
+(@pxref{AssemblerTemplate}) may help resolve this problem.
+
+@anchor{AssemblerTemplate}
+@subsubsection Assembler Template
+@cindex @code{asm} assembler template
+
+An assembler template is a literal string containing assembler instructions.
+The compiler will replace any references to inputs, outputs, and goto labels
+in the template, and then output the resulting string to the assembler. The
+string can contain any instructions recognized by the assembler, including
+directives. GCC does not parse the assembler instructions
+themselves and does not know what they mean or even whether they are valid
+assembler input. However, it does count the statements
+(@pxref{Size of an asm}).
+
+You may place multiple assembler instructions together in a single @code{asm}
+string, separated by the characters normally used in assembly code for the
+system. A combination that works in most places is a newline to break the
+line, plus a tab character to move to the instruction field (written as
+"\n\t"). Some assemblers allow semicolons as a line separator. However, note
+that some assembler dialects use semicolons to start a comment.
+
+Do not expect a sequence of @code{asm} statements to remain perfectly
+consecutive after compilation, even when you are using the @code{volatile}
+qualifier. If certain instructions need to remain consecutive in the output,
+put them in a single multi-instruction asm statement.
+
+Accessing data from C programs without using input/output operands (such as
+by using global symbols directly from the assembler template) may not work as
+expected. Similarly, calling functions directly from an assembler template
+requires a detailed understanding of the target assembler and ABI.
+
+Since GCC does not parse the AssemblerTemplate, it has no visibility of any
+symbols it references. This may result in GCC discarding those symbols as
+unreferenced unless they are also listed as input, output, or goto operands.
+
+GCC can support multiple assembler dialects (for example, GCC for i386
+supports "att" and "intel" dialects) for inline assembler. In builds that
+support this capability, the @option{-masm} option controls which dialect
+GCC uses as its default. The hardware-specific documentation for the
+@option{-masm} option contains the list of supported dialects, as well as the
+default dialect if the option is not specified. This information may be
+important to understand, since assembler code that works correctly when
+compiled using one dialect will likely fail if compiled using another.
+
+@subsubheading Using braces in @code{asm} templates
+
+If your code needs to support multiple assembler dialects (for example, if
+you are writing public headers that need to support a variety of compilation
+options), use constructs of this form:
+
+@example
+@{ dialect0 | dialect1 | dialect2... @}
+@end example
+
+This construct outputs 'dialect0' when using dialect #0 to compile the code,
+'dialect1' for dialect #1, etc. If there are fewer alternatives within the
+braces than the number of dialects the compiler supports, the construct
+outputs nothing.
+
+For example, if an i386 compiler supports two dialects (att, intel), an
+assembler template such as this:
+
+@example
+"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2"
+@end example
+
+would produce the output:
+
+@example
+For att: "btl %[Offset],%[Base] ; jc %l2"
+For intel: "bt %[Base],%[Offset]; jc %l2"
+@end example
+
+Using that same compiler, this code:
+
+@example
+"xchg@{l@}\t@{%%@}ebx, %1"
+@end example
+
+would produce
+
+@example
+For att: "xchgl\t%%ebx, %1"
+For intel: "xchg\tebx, %1"
+@end example
+
+There is no support for nesting dialect alternatives. Also, there is no
+``escape'' for an open brace (@{), so do not use open braces in an Extended
+@code{asm} template other than as a dialect indicator.
+
+@subsubheading Other format strings
+
+In addition to the tokens described by the input, output, and goto operands,
+there are a few special cases:
+
+@itemize
+@item
+"%%" outputs a single "%" into the assembler code.
+
+@item
+"%=" outputs a number that is unique to each instance of the @code{asm}
+statement in the entire compilation. This option is useful when creating local
+labels and referring to them multiple times in a single template that
+generates multiple assembler instructions.
+
+@end itemize
+
+@anchor{OutputOperands}
+@subsubsection Output Operands
+@cindex @code{asm} output operands
+
+An @code{asm} statement has zero or more output operands indicating the names
+of C variables modified by the assembler code.
+
+In this i386 example, @var{old} (referred to in the template string as
+@code{%0}) and @var{*Base} (as @code{%1}) are outputs and @var{Offset}
+(@code{%2}) is an input:
+
+@example
+bool old;
+
+__asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base.
+ "sbb %0,%0" // Use the CF to calculate old.
+ : "=r" (old), "+rm" (*Base)
+ : "Ir" (Offset)
+ : "cc");
+
+return old;
+@end example
+
+Operands use this format:
+
+@example
+[ [asmSymbolicName] ] "constraint" (cvariablename)
+@end example
+
+@emph{asmSymbolicName}
+@*
+
+When not using asmSymbolicNames, use the (zero-based) position of the operand
+in the list of operands in the assembler template. For example if there are
+three output operands, use @code{%0} in the template to refer to the first,
+@code{%1} for the second, and @code{%2} for the third. When using an
+asmSymbolicName, reference it by enclosing the name in square brackets
+(i.e. @code{%[Value]}). The scope of the name is the @code{asm} statement
+that contains the definition. Any valid C variable name is acceptable,
+including names already defined in the surrounding code. No two operands
+within the same @code{asm} statement can use the same symbolic name.
+
+@emph{constraint}
+@*
+Output constraints must begin with either @code{"="} (a variable overwriting an
+existing value) or @code{"+"} (when reading and writing). When using
+@code{"="}, do not assume the location will contain the existing value (except
+when tying the variable to an input; @pxref{InputOperands,,Input Operands}).
+
+After the prefix, there must be one or more additional constraints
+(@pxref{Constraints}) that describe where the value resides. Common
+constraints include @code{"r"} for register and @code{"m"} for memory.
+When you list more than one possible location (for example @code{"=rm"}), the
+compiler chooses the most efficient one based on the current context. If you
+list as many alternates as the @code{asm} statement allows, you will permit
+the optimizers to produce the best possible code. If you must use a specific
+register, but your Machine Constraints do not provide sufficient
+control to select the specific register you want, Local Reg Vars may provide
+a solution (@pxref{Local Reg Vars}).
+
+@emph{cvariablename}
+@*
+Specifies the C variable name of the output (enclosed by parentheses). Accepts
+any (non-constant) variable within scope.
+
+Remarks:
+
+The total number of input + output + goto operands has a limit of 30. Commas
+separate the operands. When the compiler selects the registers to use to
+represent the output operands, it will not use any of the clobbered registers
+(@pxref{Clobbers}).
+
+Output operand expressions must be lvalues. The compiler cannot check whether
+the operands have data types that are reasonable for the instruction being
+executed. For output expressions that are not directly addressable (for
+example a bit-field), the constraint must allow a register. In that case, GCC
+uses the register as the output of the @code{asm}, and then stores that
+register into the output.
+
+Unless an output operand has the '@code{&}' constraint modifier
+(@pxref{Modifiers}), GCC may allocate it in the same register as an unrelated
+input operand, on the assumption that the assembler code will consume its
+inputs before producing outputs. This assumption may be false if the assembler
+code actually consists of more than one instruction. In this case, use
+'@code{&}' on each output operand that must not overlap an input.
+
+The same problem can occur if one output parameter (@var{a}) allows a register
+constraint and another output parameter (@var{b}) allows a memory constraint.
+The code generated by GCC to access the memory address in @var{b} can contain
+registers which @emph{might} be shared by @var{a}, and GCC considers those
+registers to be inputs to the asm. As above, GCC assumes that such input
+registers are consumed before any outputs are written. This assumption may
+result in incorrect behavior if the asm writes to @var{a} before using
+@var{b}. Combining the `@code{&}' constraint with the register constraint
+ensures that modifying @var{a} will not affect what address is referenced by
+@var{b}. Omitting the `@code{&}' constraint means that the location of @var{b}
+will be undefined if @var{a} is modified before using @var{b}.
+
+@code{asm} supports operand modifiers on operands (for example @code{%k2}
+instead of simply @code{%2}). Typically these qualifiers are hardware
+dependent. The list of supported modifiers for i386 is found at
+@ref{i386Operandmodifiers,i386 Operand modifiers}.
+
+If the C code that follows the @code{asm} makes no use of any of the output
+operands, use @code{volatile} for the @code{asm} statement to prevent the
+optimizers from discarding the @code{asm} statement as unneeded
+(see @ref{Volatile}).
+
+Examples:
+
+This code makes no use of the optional asmSymbolicName. Therefore it
+references the first output operand as @code{%0} (were there a second, it
+would be @code{%1}, etc). The number of the first input operand is one greater
+than that of the last output operand. In this i386 example, that makes
+@var{Mask} @code{%1}:
+
+@example
+uint32_t Mask = 1234;
+uint32_t Index;
+
+ asm ("bsfl %1, %0"
+ : "=r" (Index)
+ : "r" (Mask)
+ : "cc");
+@end example
+
+That code overwrites the variable Index ("="), placing the value in a register
+("r"). The generic "r" constraint instead of a constraint for a specific
+register allows the compiler to pick the register to use, which can result
+in more efficient code. This may not be possible if an assembler instruction
+requires a specific register.
+
+The following i386 example uses the asmSymbolicName operand. It produces the
+same result as the code above, but some may consider it more readable or more
+maintainable since reordering index numbers is not necessary when adding or
+removing operands. The names aIndex and aMask are only used to emphasize which
+names get used where. It is acceptable to reuse the names Index and Mask.
+
+@example
+uint32_t Mask = 1234;
+uint32_t Index;
+
+ asm ("bsfl %[aMask], %[aIndex]"
+ : [aIndex] "=r" (Index)
+ : [aMask] "r" (Mask)
+ : "cc");
+@end example
+
+Here are some more examples of output operands.
-You can put multiple assembler instructions together in a single
-@code{asm} template, separated by the characters normally used in assembly
-code for the system. A combination that works in most places is a newline
-to break the line, plus a tab character to move to the instruction field
-(written as @samp{\n\t}). Sometimes semicolons can be used, if the
-assembler allows semicolons as a line-breaking character. Note that some
-assembler dialects use semicolons to start a comment.
-The input operands are guaranteed not to use any of the clobbered
-registers, and neither do the output operands' addresses, so you can
-read and write the clobbered registers as many times as you like. Here
-is an example of multiple instructions in a template; it assumes the
-subroutine @code{_foo} accepts arguments in registers 9 and 10:
+@example
+uint32_t c = 1;
+uint32_t d;
+uint32_t *e = &c;
-@smallexample
-asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo"
- : /* no outputs */
- : "g" (from), "g" (to)
- : "r9", "r10");
-@end smallexample
+asm ("mov %[e], %[d]"
+ : [d] "=rm" (d)
+ : [e] "rm" (*e));
+@end example
-Unless an output operand has the @samp{&} constraint modifier, GCC
-may allocate it in the same register as an unrelated input operand, on
-the assumption the inputs are consumed before the outputs are produced.
-This assumption may be false if the assembler code actually consists of
-more than one instruction. In such a case, use @samp{&} for each output
-operand that may not overlap an input. @xref{Modifiers}.
+Here, @var{d} may either be in a register or in memory. Since the compiler
+might already have the current value of the uint32_t pointed to by @var{e}
+in a register, you can enable it to choose the best location
+for @var{d} by specifying both constraints.
-If you want to test the condition code produced by an assembler
-instruction, you must include a branch and a label in the @code{asm}
-construct, as follows:
+@anchor{InputOperands}
+@subsubsection Input Operands
+@cindex @code{asm} input operands
+@cindex @code{asm} expressions
-@smallexample
-asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:"
- : "g" (result)
- : "g" (input));
-@end smallexample
+Input operands make inputs from C variables and expressions available to the
+assembly code.
-@noindent
-This assumes your assembler supports local labels, as the GNU assembler
-and most Unix assemblers do.
+Specify input operands by using the format:
-Speaking of labels, jumps from one @code{asm} to another are not
-supported. The compiler's optimizers do not know about these jumps, and
-therefore they cannot take account of them when deciding how to
-optimize. @xref{Extended asm with goto}.
+@example
+[ [asmSymbolicName] ] "constraint" (cexpression)
+@end example
-@cindex macros containing @code{asm}
-Usually the most convenient way to use these @code{asm} instructions is to
-encapsulate them in macros that look like functions. For example,
+@emph{asmSymbolicName}
+@*
+When not using asmSymbolicNames, use the (zero-based) position of the operand
+in the list of operands, including outputs, in the assembler template. For
+example, if there are two output parameters and three inputs, @code{%2} refers
+to the first input, @code{%3} to the second, and @code{%4} to the third.
+When using an asmSymbolicName, reference it by enclosing the name in square
+brackets (e.g. @code{%[Value]}). The scope of the name is the @code{asm}
+statement that contains the definition. Any valid C variable name is
+acceptable, including names already defined in the surrounding code. No two
+operands within the same @code{asm} statement can use the same symbolic name.
+
+@emph{constraint}
+@*
+Input constraints must be a string containing one or more constraints
+(@pxref{Constraints}). When you give more than one possible constraint
+(for example, @code{"irm"}), the compiler will choose the most efficient
+method based on the current context. Input constraints may not begin with
+either "=" or "+". If you must use a specific register, but your Machine
+Constraints do not provide sufficient control to select the specific
+register you want, Local Reg Vars may provide a solution
+(@pxref{Local Reg Vars}).
+
+Input constraints can also be digits (for example, @code{"0"}). This indicates
+that the specified input will be in the same place as the output constraint
+at the (zero-based) index in the output constraint list. When using
+asmSymbolicNames for the output operands, you may use these names (enclosed
+in brackets []) instead of digits.
+
+@emph{cexpression}
+@*
+This is the C variable or expression being passed to the @code{asm} statement
+as input.
+
+When the compiler selects the registers to use to represent the input
+operands, it will not use any of the clobbered registers (@pxref{Clobbers}).
+
+If there are no output operands but there are input operands, place two
+consecutive colons where the output operands would go:
-@smallexample
-#define sin(x) \
-(@{ double __value, __arg = (x); \
- asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
- __value; @})
-@end smallexample
+@example
+__asm__ ("some instructions"
+ : /* No outputs. */
+ : "r" (Offset / 8);
+@end example
-@noindent
-Here the variable @code{__arg} is used to make sure that the instruction
-operates on a proper @code{double} value, and to accept only those
-arguments @code{x} that can convert automatically to a @code{double}.
-
-Another way to make sure the instruction operates on the correct data
-type is to use a cast in the @code{asm}. This is different from using a
-variable @code{__arg} in that it converts more different types. For
-example, if the desired type is @code{int}, casting the argument to
-@code{int} accepts a pointer with no complaint, while assigning the
-argument to an @code{int} variable named @code{__arg} warns about
-using a pointer unless the caller explicitly casts it.
-
-If an @code{asm} has output operands, GCC assumes for optimization
-purposes the instruction has no side effects except to change the output
-operands. This does not mean instructions with a side effect cannot be
-used, but you must be careful, because the compiler may eliminate them
-if the output operands aren't used, or move them out of loops, or
-replace two with one if they constitute a common subexpression. Also,
-if your instruction does have a side effect on a variable that otherwise
-appears not to change, the old value of the variable may be reused later
-if it happens to be found in a register.
-
-You can prevent an @code{asm} instruction from being deleted
-by writing the keyword @code{volatile} after
-the @code{asm}. For example:
-
-@smallexample
-#define get_and_set_priority(new) \
-(@{ int __old; \
- asm volatile ("get_and_set_priority %0, %1" \
- : "=g" (__old) : "g" (new)); \
- __old; @})
-@end smallexample
+@strong{Warning:} Do @emph{not} modify the contents of input-only operands
+(except for inputs tied to outputs). The compiler assumes that on exit from
+the @code{asm} statement these operands will contain the same values as they
+had before executing the assembler. It is @emph{not} possible to use Clobbers
+to inform the compiler that the values in these inputs are changing. One
+common work-around is to tie the changing input variable to an output variable
+that never gets used. Note, however, that if the code that follows the
+@code{asm} statement makes no use of any of the output operands, the GCC
+optimizers may discard the @code{asm} statement as unneeded
+(see @ref{Volatile}).
+
+Remarks:
+
+The total number of input + output + goto operands has a limit of 30.
+
+@code{asm} supports operand modifiers on operands (for example @code{%k2}
+instead of simply @code{%2}). Typically these qualifiers are hardware
+dependent. The list of supported modifiers for i386 is found at
+@ref{i386Operandmodifiers,i386 Operand modifiers}.
+
+Examples:
+
+In this example using the fictitious @code{combine} instruction, the
+constraint @code{"0"} for input operand 1 says that it must occupy the same
+location as output operand 0. Only input operands may use numbers in
+constraints, and they must each refer to an output operand. Only a number (or
+the symbolic assembler name) in the constraint can guarantee that one operand
+is in the same place as another. The mere fact that @var{foo} is the value of
+both operands is not enough to guarantee that they are in the same place in
+the generated assembler code.
-@noindent
-The @code{volatile} keyword indicates that the instruction has
-important side-effects. GCC does not delete a volatile @code{asm} if
-it is reachable. (The instruction can still be deleted if GCC can
-prove that control flow never reaches the location of the
-instruction.) Note that even a volatile @code{asm} instruction
-can be moved relative to other code, including across jump
-instructions. For example, on many targets there is a system
-register that can be set to control the rounding mode of
-floating-point operations. You might try
-setting it with a volatile @code{asm}, like this PowerPC example:
+@example
+asm ("combine %2, %0"
+ : "=r" (foo)
+ : "0" (foo), "g" (bar));
+@end example
-@smallexample
- asm volatile("mtfsf 255,%0" : : "f" (fpenv));
- sum = x + y;
-@end smallexample
+Here is an example using symbolic names.
-@noindent
-This does not work reliably, as the compiler may move the addition back
-before the volatile @code{asm}. To make it work you need to add an
-artificial dependency to the @code{asm} referencing a variable in the code
-you don't want moved, for example:
+@example
+asm ("cmoveq %1, %2, %[result]"
+ : [result] "=r"(result)
+ : "r" (test), "r" (new), "[result]" (old));
+@end example
-@smallexample
- asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv));
- sum = x + y;
-@end smallexample
+@anchor{Clobbers}
+@subsubsection Clobbers
+@cindex @code{asm} clobbers
+
+While the compiler is aware of changes to entries listed in the output
+operands, the assembler code may modify more than just the outputs. For
+example, calculations may require additional registers, or the processor may
+overwrite a register as a side effect of a particular assembler instruction.
+In order to inform the compiler of these changes, list them in the clobber
+list. Clobber list items are either register names or the special clobbers
+(listed below). Each clobber list item is enclosed in double quotes and
+separated by commas.
+
+Clobber descriptions may not in any way overlap with an input or output
+operand. For example, you may not have an operand describing a register class
+with one member when listing that register in the clobber list. Variables
+declared to live in specific registers (@pxref{Explicit Reg Vars}), and used
+as @code{asm} input or output operands, must have no part mentioned in the
+clobber description. In particular, there is no way to specify that input
+operands get modified without also specifying them as output operands.
+
+When the compiler selects which registers to use to represent input and output
+operands, it will not use any of the clobbered registers. As a result,
+clobbered registers are available for any use in the assembler code.
+
+Here is a realistic example for the VAX showing the use of clobbered
+registers:
-Similarly, you can't expect a
-sequence of volatile @code{asm} instructions to remain perfectly
-consecutive. If you want consecutive output, use a single @code{asm}.
-Also, GCC performs some optimizations across a volatile @code{asm}
-instruction; GCC does not ``forget everything'' when it encounters
-a volatile @code{asm} instruction the way some other compilers do.
+@example
+asm volatile ("movc3 %0, %1, %2"
+ : /* No outputs. */
+ : "g" (from), "g" (to), "g" (count)
+ : "r0", "r1", "r2", "r3", "r4", "r5");
+@end example
-An @code{asm} instruction without any output operands is treated
-identically to a volatile @code{asm} instruction.
+Also, there are two special clobber arguments:
-It is a natural idea to look for a way to give access to the condition
-code left by the assembler instruction. However, when we attempted to
-implement this, we found no way to make it work reliably. The problem
-is that output operands might need reloading, which result in
-additional following ``store'' instructions. On most machines, these
-instructions alter the condition code before there is time to
-test it. This problem doesn't arise for ordinary ``test'' and
-``compare'' instructions because they don't have any output operands.
+@enumerate
+@item
+The @code{"cc"} clobber indicates that the assembler code modifies the flags
+register. On some machines, GCC represents the condition codes as a specific
+hardware register; "cc" serves to name this register. On other machines,
+condition code handling is different, and specifying "cc" has no effect. But
+it is valid no matter what the machine.
-For reasons similar to those described above, it is not possible to give
-an assembler instruction access to the condition code left by previous
-instructions.
+@item
+The "memory" clobber tells the compiler that the assembly code performs memory
+reads or writes to items other than those listed in the input and output
+operands (for example accessing the memory pointed to by one of the input
+parameters). To ensure memory contains correct values, GCC may need to flush
+specific register values to memory before executing the @code{asm}. Further,
+the compiler will not assume that any values read from memory before an
+@code{asm} will remain unchanged after that @code{asm}; it will reload them as
+needed. This effectively forms a read/write memory barrier for the compiler.
+
+Note that this clobber does not prevent the @emph{processor} from doing
+speculative reads past the @code{asm} statement. To prevent that, you need
+processor-specific fence instructions.
+
+Flushing registers to memory has performance implications and may be an issue
+for time-sensitive code. One trick to avoid this is available if the size of
+the memory being accessed is known at compile time. For example, if accessing
+ten bytes of a string, use a memory input like:
+
+@code{@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}}.
-@anchor{Extended asm with goto}
-As of GCC version 4.5, @code{asm goto} may be used to have the assembly
-jump to one or more C labels. In this form, a fifth section after the
-clobber list contains a list of all C labels to which the assembly may jump.
-Each label operand is implicitly self-named. The @code{asm} is also assumed
-to fall through to the next statement.
+@end enumerate
-This form of @code{asm} is restricted to not have outputs. This is due
-to a internal restriction in the compiler that control transfer instructions
-cannot have outputs. This restriction on @code{asm goto} may be lifted
-in some future version of the compiler. In the meantime, @code{asm goto}
-may include a memory clobber, and so leave outputs in memory.
+@anchor{GotoLabels}
+@subsubsection Goto Labels
+@cindex @code{asm} goto labels
+
+@code{asm goto} allows assembly code to jump to one or more C labels. The
+GotoLabels section in an @code{asm goto} statement contains a comma-separated
+list of all C labels to which the assembler code may jump. GCC assumes that
+@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
+Attributes}). The total number of input + output + goto operands has
+a limit of 30.
+
+An @code{asm goto} statement can not have outputs (which means that the
+statement is implicitly volatile). This is due to an internal restriction of
+the compiler: control transfer instructions cannot have outputs. If the
+assembler code does modify anything, use the "memory" clobber to force the
+optimizers to flush all register values to memory, and reload them if
+necessary, after the @code{asm} statement.
+
+To reference a label, prefix it with @code{%l} (that's a lowercase L) followed
+by its (zero-based) position in GotoLabels plus the number of input
+arguments. For example, if the @code{asm} has three inputs and references two
+labels, refer to the first label as @code{%l3} and the second as @code{%l4}).
+
+@code{asm} statements may not perform jumps into other @code{asm} statements.
+GCC's optimizers do not know about these jumps; therefore they cannot take
+account of them when deciding how to optimize.
+
+Example code for i386 might look like:
-@smallexample
+@example
+asm goto (
+ "btl %1, %0\n\t"
+ "jc %l2"
+ : /* No outputs. */
+ : "r" (p1), "r" (p2)
+ : "cc"
+ : carry);
+
+return 0;
+
+carry:
+return 1;
+@end example
+
+The following example shows an @code{asm goto} that uses the memory clobber.
+
+@example
int frob(int x)
@{
int y;
asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5"
- : : "r"(x), "r"(&y) : "r5", "memory" : error);
+ : /* No outputs. */
+ : "r"(x), "r"(&y)
+ : "r5", "memory"
+ : error);
return y;
- error:
+error:
return -1;
@}
-@end smallexample
+@end example
-@noindent
-In this (inefficient) example, the @code{frob} instruction sets the
-carry bit to indicate an error. The @code{jc} instruction detects
-this and branches to the @code{error} label. Finally, the output
-of the @code{frob} instruction (@code{%r5}) is stored into the memory
-for variable @code{y}, which is later read by the @code{return} statement.
+@anchor{i386Operandmodifiers}
+@subsubsection i386 Operand modifiers
-@smallexample
-void doit(void)
+Input, output, and goto operands for extended @code{asm} statements can use
+modifiers to affect the code output to the assembler. For example, the
+following code uses the "h" and "b" modifiers for i386:
+
+@example
+uint16_t num;
+asm volatile ("xchg %h0, %b0" : "+a" (num) );
+@end example
+
+These modifiers generate this assembler code:
+
+@example
+xchg %ah, %al
+@end example
+
+The rest of this discussion uses the following code for illustrative purposes.
+
+@example
+int main()
@{
- int i = 0;
- asm goto ("mfsr %%r1, 123; jmp %%r1;"
- ".pushsection doit_table;"
- ".long %l0, %l1, %l2, %l3;"
- ".popsection"
- : : : "r1" : label1, label2, label3, label4);
- __builtin_unreachable ();
-
- label1:
- f1();
- return;
- label2:
- f2();
- return;
- label3:
- i = 1;
- label4:
- f3(i);
-@}
-@end smallexample
+ int iInt = 1;
-@noindent
-In this (also inefficient) example, the @code{mfsr} instruction reads
-an address from some out-of-band machine register, and the following
-@code{jmp} instruction branches to that address. The address read by
-the @code{mfsr} instruction is assumed to have been previously set via
-some application-specific mechanism to be one of the four values stored
-in the @code{doit_table} section. Finally, the @code{asm} is followed
-by a call to @code{__builtin_unreachable} to indicate that the @code{asm}
-does not in fact fall through.
-
-@smallexample
-#define TRACE1(NUM) \
- do @{ \
- asm goto ("0: nop;" \
- ".pushsection trace_table;" \
- ".long 0b, %l0;" \
- ".popsection" \
- : : : : trace#NUM); \
- if (0) @{ trace#NUM: trace(); @} \
- @} while (0)
-#define TRACE TRACE1(__COUNTER__)
-@end smallexample
+top:
-@noindent
-In this example (which in fact inspired the @code{asm goto} feature)
-we want on rare occasions to call the @code{trace} function; on other
-occasions we'd like to keep the overhead to the absolute minimum.
-The normal code path consists of a single @code{nop} instruction.
-However, we record the address of this @code{nop} together with the
-address of a label that calls the @code{trace} function. This allows
-the @code{nop} instruction to be patched at run time to be an
-unconditional branch to the stored label. It is assumed that an
-optimizing compiler moves the labeled block out of line, to
-optimize the fall through path from the @code{asm}.
-
-If you are writing a header file that should be includable in ISO C
-programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
-Keywords}.
+ asm volatile goto ("some assembler instructions here"
+ : /* No outputs. */
+ : "q" (iInt), "X" (sizeof(unsigned char) + 1)
+ : /* No clobbers. */
+ : top);
+@}
+@end example
-@subsection Size of an @code{asm}
+With no modifiers, this is what the output from the operands would be for the
+att and intel dialects of assembler:
+
+@multitable {Operand} {masm=att} {OFFSET FLAT:.L2}
+@headitem Operand @tab masm=att @tab masm=intel
+@item @code{%0}
+@tab @code{%eax}
+@tab @code{eax}
+@item @code{%1}
+@tab @code{$2}
+@tab @code{2}
+@item @code{%2}
+@tab @code{$.L2}
+@tab @code{OFFSET FLAT:.L2}
+@end multitable
-Some targets require that GCC track the size of each instruction used in
-order to generate correct code. Because the final length of an
-@code{asm} is only known by the assembler, GCC must make an estimate as
-to how big it will be. The estimate is formed by counting the number of
-statements in the pattern of the @code{asm} and multiplying that by the
-length of the longest instruction on that processor. Statements in the
-@code{asm} are identified by newline characters and whatever statement
-separator characters are supported by the assembler; on most processors
-this is the @samp{;} character.
-
-Normally, GCC's estimate is perfectly adequate to ensure that correct
-code is generated, but it is possible to confuse the compiler if you use
-pseudo instructions or assembler macros that expand into multiple real
-instructions or if you use assembler directives that expand to more
-space in the object file than is needed for a single instruction.
-If this happens then the assembler produces a diagnostic saying that
-a label is unreachable.
+The table below shows the list of supported modifiers and their effects.
+
+@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {masm=att} {masm=intel}
+@headitem Modifier @tab Description @tab Operand @tab @option{masm=att} @tab @option{masm=intel}
+@item @code{z}
+@tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}).
+@tab @code{%z0}
+@tab @code{l}
+@tab
+@item @code{b}
+@tab Print the QImode name of the register.
+@tab @code{%b0}
+@tab @code{%al}
+@tab @code{al}
+@item @code{h}
+@tab Print the QImode name for a ``high'' register.
+@tab @code{%h0}
+@tab @code{%ah}
+@tab @code{ah}
+@item @code{w}
+@tab Print the HImode name of the register.
+@tab @code{%w0}
+@tab @code{%ax}
+@tab @code{ax}
+@item @code{k}
+@tab Print the SImode name of the register.
+@tab @code{%k0}
+@tab @code{%eax}
+@tab @code{eax}
+@item @code{q}
+@tab Print the DImode name of the register.
+@tab @code{%q0}
+@tab @code{%rax}
+@tab @code{rax}
+@item @code{l}
+@tab Print the label name with no punctuation.
+@tab @code{%l2}
+@tab @code{.L2}
+@tab @code{.L2}
+@item @code{c}
+@tab Require a constant operand and print the constant expression with no punctuation.
+@tab @code{%c1}
+@tab @code{2}
+@tab @code{2}
+@end multitable
-@subsection i386 floating-point asm operands
+@anchor{i386floatingpointasmoperands}
+@subsubsection i386 floating-point asm operands
On i386 targets, there are several rules on the usage of stack-like registers
in the operands of an @code{asm}. These rules apply only to the operands
asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
@end smallexample
+@lowersections
@include md.texi
+@raisesections
@node Asm Labels
-@section Controlling Names Used in Assembler Code
+@subsection Controlling Names Used in Assembler Code
@cindex assembler names for identifiers
@cindex names used in assembler code
@cindex identifiers, names in assembler code
Perhaps that will be added.
@node Explicit Reg Vars
-@section Variables in Specified Registers
+@subsection Variables in Specified Registers
@cindex explicit register variables
@cindex variables in specified registers
@cindex specified registers
@end menu
@node Global Reg Vars
-@subsection Defining Global Register Variables
+@subsubsection Defining Global Register Variables
@cindex global register variables
@cindex registers, global variables in
Of course, it does not do to use more than a few of those.
@node Local Reg Vars
-@subsection Specifying Registers for Local Variables
+@subsubsection Specifying Registers for Local Variables
@cindex local variables, specifying registers
@cindex specifying registers for local variables
@cindex registers for local variables
according to dataflow analysis. References to local register variables may
be deleted or moved or simplified.
-As for global register variables, it's recommended that you choose a
+As with global register variables, it is recommended that you choose a
register that is normally saved and restored by function calls on
-your machine, so that library routines will not clobber it. A common
-pitfall is to initialize multiple call-clobbered registers with
-arbitrary expressions, where a function call or library call for an
-arithmetic operator overwrites a register value from a previous
-assignment, for example @code{r0} below:
+your machine, so that library routines will not clobber it.
+
+Sometimes when writing inline @code{asm} code, you need to make an operand be a
+specific register, but there's no matching constraint letter for that
+register. To force the operand into that register, create a local variable
+and specify the register in the variable's declaration. Then use the local
+variable for the asm operand and specify any constraint letter that matches
+the register:
+
@smallexample
register int *p1 asm ("r0") = @dots{};
register int *p2 asm ("r1") = @dots{};
+register int *result asm ("r0");
+asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
@end smallexample
-@noindent
-In those cases, a solution is to use a temporary variable for
-each arbitrary expression. @xref{Example of asm with clobbered asm reg}.
+@emph{Warning:} In the above example, be aware that a register (for example r0) can be
+call-clobbered by subsequent code, including function calls and library calls
+for arithmetic operators on other variables (for example the initialization
+of p2). In this case, use temporary variables for expressions between the
+register assignments:
+
+@smallexample
+int t1 = @dots{};
+register int *p1 asm ("r0") = @dots{};
+register int *p2 asm ("r1") = t1;
+register int *result asm ("r0");
+asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2));
+@end smallexample
+
+@node Size of an asm
+@subsection Size of an @code{asm}
+
+Some targets require that GCC track the size of each instruction used
+in order to generate correct code. Because the final length of the
+code produced by an @code{asm} statement is only known by the
+assembler, GCC must make an estimate as to how big it will be. It
+does this by counting the number of instructions in the pattern of the
+@code{asm} and multiplying that by the length of the longest
+instruction supported by that processor. (When working out the number
+of instructions, it assumes that any occurrence of a newline or of
+whatever statement separator character is supported by the assembler --
+typically @samp{;} --- indicates the end of an instruction.)
+
+Normally, GCC's estimate is adequate to ensure that correct
+code is generated, but it is possible to confuse the compiler if you use
+pseudo instructions or assembler macros that expand into multiple real
+instructions, or if you use assembler directives that expand to more
+space in the object file than is needed for a single instruction.
+If this happens then the assembler may produce a diagnostic saying that
+a label is unreachable.
@node Alternate Keywords
@section Alternate Keywords
c = a == b; /* The result would be @{0,-1, 0,-1@} */
@end smallexample
+In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where
+@code{b} and @code{c} are vectors of the same type and @code{a} is an
+integer vector with the same number of elements of the same size as @code{b}
+and @code{c}, computes all three arguments and creates a vector
+@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in
+OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}.
+As in the case of binary operations, this syntax is also accepted when
+one of @code{b} or @code{c} is a scalar that is then transformed into a
+vector. If both @code{b} and @code{c} are scalars and the type of
+@code{true?b:c} has the same size as the element type of @code{a}, then
+@code{b} and @code{c} are converted to a vector type whose elements have
+this type and with the same number of elements as @code{a}.
+
+In C++, the logic operators @code{!, &&, ||} are available for vectors.
+@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to
+@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}.
+For mixed operations between a scalar @code{s} and a vector @code{v},
+@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is
+short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}.
+
Vector shuffling is available using functions
@code{__builtin_shuffle (vec, mask)} and
@code{__builtin_shuffle (vec0, vec1, mask)}.
compiler may also ignore this parameter.
@end deftypefn
+@node Integer Overflow Builtins
+@section Built-in functions to perform arithmetics and arithmetic overflow checking.
+
+The following built-in functions allow performing simple arithmetic operations
+together with checking whether the operations overflowed.
+
+@deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
+@deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res)
+@deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res)
+@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long int *res)
+@deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res)
+@deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
+@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res)
+
+These built-in functions promote the first two operands into infinite precision signed
+type and perform addition on those promoted operands. The result is then
+cast to the type the third pointer argument points to and stored there.
+If the stored result is equal to the infinite precision result, the built-in
+functions return false, otherwise they return true. As the addition is
+performed in infinite signed precision, these built-in functions have fully defined
+behavior for all argument values.
+
+The first built-in function allows arbitrary integral types for operands and
+the result type must be pointer to some integer type, the rest of the built-in
+functions have explicit integer types.
+
+The compiler will attempt to use hardware instructions to implement
+these built-in functions where possible, like conditional jump on overflow
+after addition, conditional jump on carry etc.
+
+@end deftypefn
+
+@deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
+@deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res)
+@deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res)
+@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long int *res)
+@deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res)
+@deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
+@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res)
+
+These built-in functions are similar to the add overflow checking built-in
+functions above, except they perform subtraction, subtract the second argument
+from the first one, instead of addition.
+
+@end deftypefn
+
+@deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res)
+@deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res)
+@deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res)
+@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long int *res)
+@deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res)
+@deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)
+@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res)
+
+These built-in functions are similar to the add overflow checking built-in
+functions above, except they perform multiplication, instead of addition.
+
+@end deftypefn
+
@node x86 specific memory model extensions for transactional memory
@section x86 specific memory model extensions for transactional memory
@code{fputc} etc.@: functions, it does, otherwise the checking function
is called and the @var{flag} argument passed to it.
+@node Pointer Bounds Checker builtins
+@section Pointer Bounds Checker Built-in Functions
+@findex __builtin___bnd_set_ptr_bounds
+@findex __builtin___bnd_narrow_ptr_bounds
+@findex __builtin___bnd_copy_ptr_bounds
+@findex __builtin___bnd_init_ptr_bounds
+@findex __builtin___bnd_null_ptr_bounds
+@findex __builtin___bnd_store_ptr_bounds
+@findex __builtin___bnd_chk_ptr_lbounds
+@findex __builtin___bnd_chk_ptr_ubounds
+@findex __builtin___bnd_chk_ptr_bounds
+@findex __builtin___bnd_get_ptr_lbound
+@findex __builtin___bnd_get_ptr_ubound
+
+GCC provides a set of built-in functions to control Pointer Bounds Checker
+instrumentation. Note that all Pointer Bounds Checker builtins are allowed
+to use even if you compile with Pointer Bounds Checker off. The builtins
+behavior may differ in such case as documented below.
+
+@deftypefn {Built-in Function} void * __builtin___bnd_set_ptr_bounds (const void * @var{q}, size_t @var{size})
+
+This built-in function returns a new pointer with the value of @var{q}, and
+associate it with the bounds [@var{q}, @var{q}+@var{size}-1]. With Pointer
+Bounds Checker off built-in function just returns the first argument.
+
+@smallexample
+extern void *__wrap_malloc (size_t n)
+@{
+ void *p = (void *)__real_malloc (n);
+ if (!p) return __builtin___bnd_null_ptr_bounds (p);
+ return __builtin___bnd_set_ptr_bounds (p, n);
+@}
+@end smallexample
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void * __builtin___bnd_narrow_ptr_bounds (const void * @var{p}, const void * @var{q}, size_t @var{size})
+
+This built-in function returns a new pointer with the value of @var{p}
+and associate it with the narrowed bounds formed by the intersection
+of bounds associated with @var{q} and the [@var{p}, @var{p} + @var{size} - 1].
+With Pointer Bounds Checker off built-in function just returns the first
+argument.
+
+@smallexample
+void init_objects (object *objs, size_t size)
+@{
+ size_t i;
+ /* Initialize objects one-by-one passing pointers with bounds of an object,
+ not the full array of objects. */
+ for (i = 0; i < size; i++)
+ init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs, sizeof(object)));
+@}
+@end smallexample
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void * __builtin___bnd_copy_ptr_bounds (const void * @var{q}, const void * @var{r})
+
+This built-in function returns a new pointer with the value of @var{q},
+and associate it with the bounds already associated with pointer @var{r}.
+With Pointer Bounds Checker off built-in function just returns the first
+argument.
+
+@smallexample
+/* Here is a way to get pointer to object's field but
+ still with the full object's bounds. */
+int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_filed, objptr);
+@end smallexample
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void * __builtin___bnd_init_ptr_bounds (const void * @var{q})
+
+This built-in function returns a new pointer with the value of @var{q}, and
+associate it with INIT (allowing full memory access) bounds. With Pointer
+Bounds Checker off built-in function just returns the first argument.
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void * __builtin___bnd_null_ptr_bounds (const void * @var{q})
+
+This built-in function returns a new pointer with the value of @var{q}, and
+associate it with NULL (allowing no memory access) bounds. With Pointer
+Bounds Checker off built-in function just returns the first argument.
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void ** @var{ptr_addr}, const void * @var{ptr_val})
+
+This built-in function stores the bounds associated with pointer @var{ptr_val}
+and location @var{ptr_addr} into Bounds Table. This can be useful to propagate
+bounds from legacy code without touching the associated pointer's memory when
+pointers were copied as integers. With Pointer Bounds Checker off built-in
+function call is ignored.
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void * @var{q})
+
+This built-in function checks if the pointer @var{q} is within the lower
+bound of its associated bounds. With Pointer Bounds Checker off built-in
+function call is ignored.
+
+@smallexample
+extern void *__wrap_memset (void *dst, int c, size_t len)
+@{
+ if (len > 0)
+ @{
+ __builtin___bnd_chk_ptr_lbounds (dst);
+ __builtin___bnd_chk_ptr_ubounds ((char *)dst + len - 1);
+ __real_memset (dst, c, len);
+ @}
+ return dst;
+@}
+@end smallexample
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void * @var{q})
+
+This built-in function checks if the pointer @var{q} is within the upper
+bound of its associated bounds. With Pointer Bounds Checker off built-in
+function call is ignored.
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void * @var{q}, size_t @var{size})
+
+This built-in function checks if [@var{q}, @var{q} + @var{size} - 1] is within
+the lower and upper bounds associated with @var{q}. With Pointer Bounds Checker
+off built-in function call is ignored.
+
+@smallexample
+extern void *__wrap_memcpy (void *dst, const void *src, size_t n)
+@{
+ if (n > 0)
+ @{
+ __bnd_chk_ptr_bounds (dst, n);
+ __bnd_chk_ptr_bounds (src, n);
+ __real_memcpy (dst, src, n);
+ @}
+ return dst;
+@}
+@end smallexample
+
+@end deftypefn
+
+@deftypefn {Built-in Function} const void * __builtin___bnd_get_ptr_lbound (const void * @var{q})
+
+This built-in function returns the lower bound (which is a pointer) associated
+with the pointer @var{q}. This is at least useful for debugging using printf.
+With Pointer Bounds Checker off built-in function returns 0.
+
+@smallexample
+void *lb = __builtin___bnd_get_ptr_lbound (q);
+void *ub = __builtin___bnd_get_ptr_ubound (q);
+printf ("q = %p lb(q) = %p ub(q) = %p", q, lb, ub);
+@end smallexample
+
+@end deftypefn
+
+@deftypefn {Built-in Function} const void * __builtin___bnd_get_ptr_ubound (const void * @var{q})
+
+This built-in function returns the upper bound (which is a pointer) associated
+with the pointer @var{q}. With Pointer Bounds Checker off built-in function
+returns -1.
+
+@end deftypefn
+
@node Cilk Plus Builtins
@section Cilk Plus C/C++ language extension Built-in Functions.
@node Other Builtins
@section Other Built-in Functions Provided by GCC
@cindex built-in functions
+@findex __builtin_call_with_static_chain
@findex __builtin_fpclassify
@findex __builtin_isfinite
@findex __builtin_isnormal
@end deftypefn
+@deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp})
+
+The @var{call_exp} expression must be a function call, and the
+@var{pointer_exp} expression must be a pointer. The @var{pointer_exp}
+is passed to the function call in the target's static chain location.
+The result of builtin is the result of the function call.
+
+@emph{Note:} This builtin is only available for C@.
+This builtin can be used to call Go closures from C.
+
+@end deftypefn
+
@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})
You can use the built-in function @code{__builtin_choose_expr} to
@deftypefn {Built-in Function} int __builtin_LINE ()
This function is the equivalent to the preprocessor @code{__LINE__}
macro and returns the line number of the invocation of the built-in.
+In a C++ default argument for a function @var{F}, it gets the line number of
+the call to @var{F}.
@end deftypefn
-@deftypefn {Built-in Function} int __builtin_FUNCTION ()
+@deftypefn {Built-in Function} {const char *} __builtin_FUNCTION ()
This function is the equivalent to the preprocessor @code{__FUNCTION__}
macro and returns the function name the invocation of the built-in is in.
@end deftypefn
-@deftypefn {Built-in Function} int __builtin_FILE ()
+@deftypefn {Built-in Function} {const char *} __builtin_FILE ()
This function is the equivalent to the preprocessor @code{__FILE__}
macro and returns the file name the invocation of the built-in is in.
+In a C++ default argument for a function @var{F}, it gets the file name of
+the call to @var{F}.
@end deftypefn
@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end})
Similar to @code{__builtin_nans}, except the return type is @code{long double}.
@end deftypefn
-@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x)
+@deftypefn {Built-in Function} int __builtin_ffs (int x)
Returns one plus the index of the least significant 1-bit of @var{x}, or
if @var{x} is zero, returns zero.
@end deftypefn
modulo 2.
@end deftypefn
-@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long)
+@deftypefn {Built-in Function} int __builtin_ffsl (long)
Similar to @code{__builtin_ffs}, except the argument type is
-@code{unsigned long}.
+@code{long}.
@end deftypefn
@deftypefn {Built-in Function} int __builtin_clzl (unsigned long)
@code{unsigned long}.
@end deftypefn
-@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long)
+@deftypefn {Built-in Function} int __builtin_ffsll (long long)
Similar to @code{__builtin_ffs}, except the argument type is
-@code{unsigned long long}.
+@code{long long}.
@end deftypefn
@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long)
instructions, but allow the compiler to schedule those calls.
@menu
+* AArch64 Built-in Functions::
* Alpha Built-in Functions::
+* Altera Nios II Built-in Functions::
* ARC Built-in Functions::
* ARC SIMD Built-in Functions::
* ARM iWMMXt Built-in Functions::
-* ARM NEON Intrinsics::
-* ARM ACLE Intrinsics::
+* ARM C Language Extensions (ACLE)::
+* ARM Floating Point Status and Control Intrinsics::
* AVR Built-in Functions::
* Blackfin Built-in Functions::
* FR-V Built-in Functions::
* TILEPro Built-in Functions::
@end menu
+@node AArch64 Built-in Functions
+@subsection AArch64 Built-in Functions
+
+These built-in functions are available for the AArch64 family of
+processors.
+@smallexample
+unsigned int __builtin_aarch64_get_fpcr ()
+void __builtin_aarch64_set_fpcr (unsigned int)
+unsigned int __builtin_aarch64_get_fpsr ()
+void __builtin_aarch64_set_fpsr (unsigned int)
+@end smallexample
+
@node Alpha Built-in Functions
@subsection Alpha Built-in Functions
void __builtin_set_thread_pointer (void *)
@end smallexample
+@node Altera Nios II Built-in Functions
+@subsection Altera Nios II Built-in Functions
+
+These built-in functions are available for the Altera Nios II
+family of processors.
+
+The following built-in functions are always available. They
+all generate the machine instruction that is part of the name.
+
+@example
+int __builtin_ldbio (volatile const void *)
+int __builtin_ldbuio (volatile const void *)
+int __builtin_ldhio (volatile const void *)
+int __builtin_ldhuio (volatile const void *)
+int __builtin_ldwio (volatile const void *)
+void __builtin_stbio (volatile void *, int)
+void __builtin_sthio (volatile void *, int)
+void __builtin_stwio (volatile void *, int)
+void __builtin_sync (void)
+int __builtin_rdctl (int)
+void __builtin_wrctl (int, int)
+@end example
+
+The following built-in functions are always available. They
+all generate a Nios II Custom Instruction. The name of the
+function represents the types that the function takes and
+returns. The letter before the @code{n} is the return type
+or void if absent. The @code{n} represents the first parameter
+to all the custom instructions, the custom instruction number.
+The two letters after the @code{n} represent the up to two
+parameters to the function.
+
+The letters represent the following data types:
+@table @code
+@item <no letter>
+@code{void} for return type and no parameter for parameter types.
+
+@item i
+@code{int} for return type and parameter type
+
+@item f
+@code{float} for return type and parameter type
+
+@item p
+@code{void *} for return type and parameter type
+
+@end table
+
+And the function names are:
+@example
+void __builtin_custom_n (void)
+void __builtin_custom_ni (int)
+void __builtin_custom_nf (float)
+void __builtin_custom_np (void *)
+void __builtin_custom_nii (int, int)
+void __builtin_custom_nif (int, float)
+void __builtin_custom_nip (int, void *)
+void __builtin_custom_nfi (float, int)
+void __builtin_custom_nff (float, float)
+void __builtin_custom_nfp (float, void *)
+void __builtin_custom_npi (void *, int)
+void __builtin_custom_npf (void *, float)
+void __builtin_custom_npp (void *, void *)
+int __builtin_custom_in (void)
+int __builtin_custom_ini (int)
+int __builtin_custom_inf (float)
+int __builtin_custom_inp (void *)
+int __builtin_custom_inii (int, int)
+int __builtin_custom_inif (int, float)
+int __builtin_custom_inip (int, void *)
+int __builtin_custom_infi (float, int)
+int __builtin_custom_inff (float, float)
+int __builtin_custom_infp (float, void *)
+int __builtin_custom_inpi (void *, int)
+int __builtin_custom_inpf (void *, float)
+int __builtin_custom_inpp (void *, void *)
+float __builtin_custom_fn (void)
+float __builtin_custom_fni (int)
+float __builtin_custom_fnf (float)
+float __builtin_custom_fnp (void *)
+float __builtin_custom_fnii (int, int)
+float __builtin_custom_fnif (int, float)
+float __builtin_custom_fnip (int, void *)
+float __builtin_custom_fnfi (float, int)
+float __builtin_custom_fnff (float, float)
+float __builtin_custom_fnfp (float, void *)
+float __builtin_custom_fnpi (void *, int)
+float __builtin_custom_fnpf (void *, float)
+float __builtin_custom_fnpp (void *, void *)
+void * __builtin_custom_pn (void)
+void * __builtin_custom_pni (int)
+void * __builtin_custom_pnf (float)
+void * __builtin_custom_pnp (void *)
+void * __builtin_custom_pnii (int, int)
+void * __builtin_custom_pnif (int, float)
+void * __builtin_custom_pnip (int, void *)
+void * __builtin_custom_pnfi (float, int)
+void * __builtin_custom_pnff (float, float)
+void * __builtin_custom_pnfp (float, void *)
+void * __builtin_custom_pnpi (void *, int)
+void * __builtin_custom_pnpf (void *, float)
+void * __builtin_custom_pnpp (void *, void *)
+@end example
+
@node ARC Built-in Functions
@subsection ARC Built-in Functions
long long __builtin_arm_wzero ()
@end smallexample
-@node ARM NEON Intrinsics
-@subsection ARM NEON Intrinsics
-These built-in intrinsics for the ARM Advanced SIMD extension are available
-when the @option{-mfpu=neon} switch is used:
+@node ARM C Language Extensions (ACLE)
+@subsection ARM C Language Extensions (ACLE)
+
+GCC implements extensions for C as described in the ARM C Language
+Extensions (ACLE) specification, which can be found at
+@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}.
+
+As a part of ACLE, GCC implements extensions for Advanced SIMD as described in
+the ARM C Language Extensions Specification. The complete list of Advanced SIMD
+intrinsics can be found at
+@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}.
+The built-in intrinsics for the Advanced SIMD extension are available when
+NEON is enabled.
-@include arm-neon-intrinsics.texi
+Currently, ARM and AArch64 back-ends do not support ACLE 2.0 fully. Both
+back-ends support CRC32 intrinsics from @file{arm_acle.h}. The ARM backend's
+16-bit floating-point Advanded SIMD Intrinsics currently comply to ACLE v1.1.
+AArch64's backend does not have support for 16-bit floating point Advanced SIMD
+Intrinsics yet.
-@node ARM ACLE Intrinsics
-@subsection ARM ACLE Intrinsics
+See @ref{ARM Options} and @ref{AArch64 Options} for more information on the
+availability of extensions.
-These built-in intrinsics for the ARMv8-A CRC32 extension are available when
-the @option{-march=armv8-a+crc} switch is used:
+@node ARM Floating Point Status and Control Intrinsics
+@subsection ARM Floating Point Status and Control Intrinsics
-@include arm-acle-intrinsics.texi
+These built-in functions are available for the ARM family of
+processors with floating-point unit.
+
+@smallexample
+unsigned int __builtin_arm_get_fpscr ()
+void __builtin_arm_set_fpscr (unsigned int)
+@end smallexample
@node AVR Built-in Functions
@subsection AVR Built-in Functions
AVX instructions.
@item avx2
AVX2 instructions.
+@item avx512f
+AVX512F instructions.
@end table
Here is an example:
name.
@smallexample
-v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,v32qi,int)
+v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int)
v32qi __builtin_ia32_pabsb256 (v32qi)
v16hi __builtin_ia32_pabsw256 (v16hi)
v8si __builtin_ia32_pabsd256 (v8si)
@smallexample
v2df __builtin_ia32_vfrczpd (v2df)
v4sf __builtin_ia32_vfrczps (v4sf)
-v2df __builtin_ia32_vfrczsd (v2df, v2df)
-v4sf __builtin_ia32_vfrczss (v4sf, v4sf)
+v2df __builtin_ia32_vfrczsd (v2df)
+v4sf __builtin_ia32_vfrczss (v4sf)
v4df __builtin_ia32_vfrczpd256 (v4df)
v8sf __builtin_ia32_vfrczps256 (v8sf)
v2di __builtin_ia32_vpcmov (v2di, v2di, v2di)
Insert a @samp{cache} instruction with operands @var{op} and @var{addr}.
GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE}
when this function is available.
+
+@item unsigned int __builtin_mips_get_fcsr (void)
+@itemx void __builtin_mips_set_fcsr (unsigned int @var{value})
+Get and set the contents of the floating-point control and status register
+(FPU control register 31). These functions are only available in hard-float
+code but can be called in both MIPS16 and non-MIPS16 contexts.
+
+@code{__builtin_mips_set_fcsr} can be used to change any bit of the
+register except the condition codes, which GCC assumes are preserved.
@end table
@node MSP430 Built-in Functions
currently residing on the stack. This only works inside interrupt
handlers and the changes to the status register will only take affect
once the handler returns.
+
+@item __delay_cycles (long long @var{cycles})
+This inserts an instruction sequence that takes exactly @var{cycles}
+cycles (between 0 and about 17E9) to complete. The inserted sequence
+may use jumps, loops, or no-ops, and does not interfere with any other
+instructions. Note that @var{cycles} must be a compile-time constant
+integer - that is, you must pass a number, not a variable that may be
+optimized to a constant later. The number of cycles delayed by this
+builtin is exact.
@end table
@node NDS32 Built-in Functions
float __builtin_rsqrtf (float);
double __builtin_recipdiv (double, double);
double __builtin_rsqrt (double);
-long __builtin_bpermd (long, long);
uint64_t __builtin_ppc_get_timebase ();
unsigned long __builtin_ppc_mftb ();
+double __builtin_unpack_longdouble (long double, int);
+long double __builtin_pack_longdouble (double, double);
@end smallexample
The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and
returns the Time Base Register value as an unsigned long, throwing away
the most significant word on 32-bit environments.
+The following built-in functions are available for the PowerPC family
+of processors, starting with ISA 2.06 or later (@option{-mcpu=power7}
+or @option{-mpopcntd}):
+@smallexample
+long __builtin_bpermd (long, long);
+int __builtin_divwe (int, int);
+int __builtin_divweo (int, int);
+unsigned int __builtin_divweu (unsigned int, unsigned int);
+unsigned int __builtin_divweuo (unsigned int, unsigned int);
+long __builtin_divde (long, long);
+long __builtin_divdeo (long, long);
+unsigned long __builtin_divdeu (unsigned long, unsigned long);
+unsigned long __builtin_divdeuo (unsigned long, unsigned long);
+unsigned int cdtbcd (unsigned int);
+unsigned int cbcdtd (unsigned int);
+unsigned int addg6s (unsigned int, unsigned int);
+@end smallexample
+
+The @code{__builtin_divde}, @code{__builtin_divdeo},
+@code{__builitin_divdeu}, @code{__builtin_divdeou} functions require a
+64-bit environment support ISA 2.06 or later.
+
+The following built-in functions are available for the PowerPC family
+of processors when hardware decimal floating point
+(@option{-mhard-dfp}) is available:
+@smallexample
+_Decimal64 __builtin_dxex (_Decimal64);
+_Decimal128 __builtin_dxexq (_Decimal128);
+_Decimal64 __builtin_ddedpd (int, _Decimal64);
+_Decimal128 __builtin_ddedpdq (int, _Decimal128);
+_Decimal64 __builtin_denbcd (int, _Decimal64);
+_Decimal128 __builtin_denbcdq (int, _Decimal128);
+_Decimal64 __builtin_diex (_Decimal64, _Decimal64);
+_Decimal128 _builtin_diexq (_Decimal128, _Decimal128);
+_Decimal64 __builtin_dscli (_Decimal64, int);
+_Decimal128 __builitn_dscliq (_Decimal128, int);
+_Decimal64 __builtin_dscri (_Decimal64, int);
+_Decimal128 __builitn_dscriq (_Decimal128, int);
+unsigned long long __builtin_unpack_dec128 (_Decimal128, int);
+_Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long);
+@end smallexample
+
+The following built-in functions are available for the PowerPC family
+of processors when the Vector Scalar (vsx) instruction set is
+available:
+@smallexample
+unsigned long long __builtin_unpack_vector_int128 (vector __int128_t, int);
+vector __int128_t __builtin_pack_vector_int128 (unsigned long long,
+ unsigned long long);
+@end smallexample
+
@node PowerPC AltiVec/VSX Built-in Functions
@subsection PowerPC AltiVec Built-in Functions
vector bool int vec_cmplt (vector signed int, vector signed int);
vector bool int vec_cmplt (vector float, vector float);
+vector float vec_cpsgn (vector float, vector float);
+
vector float vec_ctf (vector unsigned int, const int);
vector float vec_ctf (vector signed int, const int);
+vector double vec_ctf (vector unsigned long, const int);
+vector double vec_ctf (vector signed long, const int);
vector float vec_vcfsx (vector signed int, const int);
vector float vec_vcfux (vector unsigned int, const int);
vector signed int vec_cts (vector float, const int);
+vector signed long vec_cts (vector double, const int);
vector unsigned int vec_ctu (vector float, const int);
+vector unsigned long vec_ctu (vector double, const int);
void vec_dss (const int);
vector signed int vec_splat (vector signed int, const int);
vector unsigned int vec_splat (vector unsigned int, const int);
vector bool int vec_splat (vector bool int, const int);
+vector signed long vec_splat (vector signed long, const int);
+vector unsigned long vec_splat (vector unsigned long, const int);
+
+vector signed char vec_splats (signed char);
+vector unsigned char vec_splats (unsigned char);
+vector signed short vec_splats (signed short);
+vector unsigned short vec_splats (unsigned short);
+vector signed int vec_splats (signed int);
+vector unsigned int vec_splats (unsigned int);
+vector float vec_splats (float);
vector float vec_vspltw (vector float, const int);
vector signed int vec_vspltw (vector signed int, const int);
vector double vec_and (vector double, vector double);
vector double vec_and (vector double, vector bool long);
vector double vec_and (vector bool long, vector double);
+vector long vec_and (vector long, vector long);
+vector long vec_and (vector long, vector bool long);
+vector long vec_and (vector bool long, vector long);
+vector unsigned long vec_and (vector unsigned long, vector unsigned long);
+vector unsigned long vec_and (vector unsigned long, vector bool long);
+vector unsigned long vec_and (vector bool long, vector unsigned long);
vector double vec_andc (vector double, vector double);
vector double vec_andc (vector double, vector bool long);
vector double vec_andc (vector bool long, vector double);
+vector long vec_andc (vector long, vector long);
+vector long vec_andc (vector long, vector bool long);
+vector long vec_andc (vector bool long, vector long);
+vector unsigned long vec_andc (vector unsigned long, vector unsigned long);
+vector unsigned long vec_andc (vector unsigned long, vector bool long);
+vector unsigned long vec_andc (vector bool long, vector unsigned long);
vector double vec_ceil (vector double);
vector bool long vec_cmpeq (vector double, vector double);
vector bool long vec_cmpge (vector double, vector double);
vector bool long vec_cmpgt (vector double, vector double);
vector bool long vec_cmple (vector double, vector double);
vector bool long vec_cmplt (vector double, vector double);
+vector double vec_cpsgn (vector double, vector double);
vector float vec_div (vector float, vector float);
vector double vec_div (vector double, vector double);
+vector long vec_div (vector long, vector long);
+vector unsigned long vec_div (vector unsigned long, vector unsigned long);
vector double vec_floor (vector double);
vector double vec_ld (int, const vector double *);
vector double vec_ld (int, const double *);
vector unsigned char vec_lvsr (int, const volatile double *);
vector double vec_madd (vector double, vector double, vector double);
vector double vec_max (vector double, vector double);
+vector signed long vec_mergeh (vector signed long, vector signed long);
+vector signed long vec_mergeh (vector signed long, vector bool long);
+vector signed long vec_mergeh (vector bool long, vector signed long);
+vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long);
+vector unsigned long vec_mergeh (vector unsigned long, vector bool long);
+vector unsigned long vec_mergeh (vector bool long, vector unsigned long);
+vector signed long vec_mergel (vector signed long, vector signed long);
+vector signed long vec_mergel (vector signed long, vector bool long);
+vector signed long vec_mergel (vector bool long, vector signed long);
+vector unsigned long vec_mergel (vector unsigned long, vector unsigned long);
+vector unsigned long vec_mergel (vector unsigned long, vector bool long);
+vector unsigned long vec_mergel (vector bool long, vector unsigned long);
vector double vec_min (vector double, vector double);
vector float vec_msub (vector float, vector float, vector float);
vector double vec_msub (vector double, vector double, vector double);
vector float vec_mul (vector float, vector float);
vector double vec_mul (vector double, vector double);
+vector long vec_mul (vector long, vector long);
+vector unsigned long vec_mul (vector unsigned long, vector unsigned long);
vector float vec_nearbyint (vector float);
vector double vec_nearbyint (vector double);
vector float vec_nmadd (vector float, vector float, vector float);
vector double vec_nmadd (vector double, vector double, vector double);
vector double vec_nmsub (vector double, vector double, vector double);
vector double vec_nor (vector double, vector double);
+vector long vec_nor (vector long, vector long);
+vector long vec_nor (vector long, vector bool long);
+vector long vec_nor (vector bool long, vector long);
+vector unsigned long vec_nor (vector unsigned long, vector unsigned long);
+vector unsigned long vec_nor (vector unsigned long, vector bool long);
+vector unsigned long vec_nor (vector bool long, vector unsigned long);
vector double vec_or (vector double, vector double);
vector double vec_or (vector double, vector bool long);
vector double vec_or (vector bool long, vector double);
-vector double vec_perm (vector double,
- vector double,
- vector unsigned char);
+vector long vec_or (vector long, vector long);
+vector long vec_or (vector long, vector bool long);
+vector long vec_or (vector bool long, vector long);
+vector unsigned long vec_or (vector unsigned long, vector unsigned long);
+vector unsigned long vec_or (vector unsigned long, vector bool long);
+vector unsigned long vec_or (vector bool long, vector unsigned long);
+vector double vec_perm (vector double, vector double, vector unsigned char);
+vector long vec_perm (vector long, vector long, vector unsigned char);
+vector unsigned long vec_perm (vector unsigned long, vector unsigned long,
+ vector unsigned char);
vector double vec_rint (vector double);
vector double vec_recip (vector double, vector double);
vector double vec_rsqrt (vector double);
vector double vec_rsqrte (vector double);
vector double vec_sel (vector double, vector double, vector bool long);
vector double vec_sel (vector double, vector double, vector unsigned long);
-vector double vec_sub (vector double, vector double);
+vector long vec_sel (vector long, vector long, vector long);
+vector long vec_sel (vector long, vector long, vector unsigned long);
+vector long vec_sel (vector long, vector long, vector bool long);
+vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
+ vector long);
+vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
+ vector unsigned long);
+vector unsigned long vec_sel (vector unsigned long, vector unsigned long,
+ vector bool long);
+vector double vec_splats (double);
+vector signed long vec_splats (signed long);
+vector unsigned long vec_splats (unsigned long);
vector float vec_sqrt (vector float);
vector double vec_sqrt (vector double);
void vec_st (vector double, int, vector double *);
void vec_st (vector double, int, double *);
+vector double vec_sub (vector double, vector double);
vector double vec_trunc (vector double);
vector double vec_xor (vector double, vector double);
vector double vec_xor (vector double, vector bool long);
vector double vec_xor (vector bool long, vector double);
+vector long vec_xor (vector long, vector long);
+vector long vec_xor (vector long, vector bool long);
+vector long vec_xor (vector bool long, vector long);
+vector unsigned long vec_xor (vector unsigned long, vector unsigned long);
+vector unsigned long vec_xor (vector unsigned long, vector bool long);
+vector unsigned long vec_xor (vector bool long, vector unsigned long);
int vec_all_eq (vector double, vector double);
int vec_all_ge (vector double, vector double);
int vec_all_gt (vector double, vector double);
void vec_vsx_st (vector bool char, int, vector bool char *);
void vec_vsx_st (vector bool char, int, unsigned char *);
void vec_vsx_st (vector bool char, int, signed char *);
+
+vector double vec_xxpermdi (vector double, vector double, int);
+vector float vec_xxpermdi (vector float, vector float, int);
+vector long long vec_xxpermdi (vector long long, vector long long, int);
+vector unsigned long long vec_xxpermdi (vector unsigned long long,
+ vector unsigned long long, int);
+vector int vec_xxpermdi (vector int, vector int, int);
+vector unsigned int vec_xxpermdi (vector unsigned int,
+ vector unsigned int, int);
+vector short vec_xxpermdi (vector short, vector short, int);
+vector unsigned short vec_xxpermdi (vector unsigned short,
+ vector unsigned short, int);
+vector signed char vec_xxpermdi (vector signed char, vector signed char, int);
+vector unsigned char vec_xxpermdi (vector unsigned char,
+ vector unsigned char, int);
+
+vector double vec_xxsldi (vector double, vector double, int);
+vector float vec_xxsldi (vector float, vector float, int);
+vector long long vec_xxsldi (vector long long, vector long long, int);
+vector unsigned long long vec_xxsldi (vector unsigned long long,
+ vector unsigned long long, int);
+vector int vec_xxsldi (vector int, vector int, int);
+vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int);
+vector short vec_xxsldi (vector short, vector short, int);
+vector unsigned short vec_xxsldi (vector unsigned short,
+ vector unsigned short, int);
+vector signed char vec_xxsldi (vector signed char, vector signed char, int);
+vector unsigned char vec_xxsldi (vector unsigned char,
+ vector unsigned char, int);
@end smallexample
Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always
vector unsigned long long);
int vec_all_eq (vector long long, vector long long);
+int vec_all_eq (vector unsigned long long, vector unsigned long long);
int vec_all_ge (vector long long, vector long long);
+int vec_all_ge (vector unsigned long long, vector unsigned long long);
int vec_all_gt (vector long long, vector long long);
+int vec_all_gt (vector unsigned long long, vector unsigned long long);
int vec_all_le (vector long long, vector long long);
+int vec_all_le (vector unsigned long long, vector unsigned long long);
int vec_all_lt (vector long long, vector long long);
+int vec_all_lt (vector unsigned long long, vector unsigned long long);
int vec_all_ne (vector long long, vector long long);
+int vec_all_ne (vector unsigned long long, vector unsigned long long);
+
int vec_any_eq (vector long long, vector long long);
+int vec_any_eq (vector unsigned long long, vector unsigned long long);
int vec_any_ge (vector long long, vector long long);
+int vec_any_ge (vector unsigned long long, vector unsigned long long);
int vec_any_gt (vector long long, vector long long);
+int vec_any_gt (vector unsigned long long, vector unsigned long long);
int vec_any_le (vector long long, vector long long);
+int vec_any_le (vector unsigned long long, vector unsigned long long);
int vec_any_lt (vector long long, vector long long);
+int vec_any_lt (vector unsigned long long, vector unsigned long long);
int vec_any_ne (vector long long, vector long long);
+int vec_any_ne (vector unsigned long long, vector unsigned long long);
vector long long vec_eqv (vector long long, vector long long);
vector long long vec_eqv (vector bool long long, vector long long);
vector unsigned long long vec_max (vector unsigned long long,
vector unsigned long long);
+vector signed int vec_mergee (vector signed int, vector signed int);
+vector unsigned int vec_mergee (vector unsigned int, vector unsigned int);
+vector bool int vec_mergee (vector bool int, vector bool int);
+
+vector signed int vec_mergeo (vector signed int, vector signed int);
+vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int);
+vector bool int vec_mergeo (vector bool int, vector bool int);
+
vector long long vec_min (vector long long, vector long long);
vector unsigned long long vec_min (vector unsigned long long,
vector unsigned long long);
vector unsigned long long);
vector unsigned int vec_packsu (vector long long, vector long long);
+vector unsigned int vec_packsu (vector unsigned long long,
+ vector unsigned long long);
vector long long vec_rl (vector long long,
vector unsigned long long);
vector unsigned long long vec_vaddudm (vector unsigned long long,
vector bool unsigned long long);
+vector long long vec_vbpermq (vector signed char, vector signed char);
+vector long long vec_vbpermq (vector unsigned char, vector unsigned char);
+
+vector long long vec_cntlz (vector long long);
+vector unsigned long long vec_cntlz (vector unsigned long long);
+vector int vec_cntlz (vector int);
+vector unsigned int vec_cntlz (vector int);
+vector short vec_cntlz (vector short);
+vector unsigned short vec_cntlz (vector unsigned short);
+vector signed char vec_cntlz (vector signed char);
+vector unsigned char vec_cntlz (vector unsigned char);
+
vector long long vec_vclz (vector long long);
vector unsigned long long vec_vclz (vector unsigned long long);
vector int vec_vclz (vector int);
vector int vec_vclzw (vector int);
vector unsigned int vec_vclzw (vector int);
+vector signed char vec_vgbbd (vector signed char);
+vector unsigned char vec_vgbbd (vector unsigned char);
+
vector long long vec_vmaxsd (vector long long, vector long long);
vector unsigned long long vec_vmaxud (vector unsigned long long,
vector unsigned long long vec_vupklsw (vector int);
@end smallexample
+If the ISA 2.07 additions to the vector/scalar (power8-vector)
+instruction set is available, the following additional functions are
+available for 64-bit targets. New vector types
+(@var{vector __int128_t} and @var{vector __uint128_t}) are available
+to hold the @var{__int128_t} and @var{__uint128_t} types to use these
+builtins.
+
+The normal vector extract, and set operations work on
+@var{vector __int128_t} and @var{vector __uint128_t} types,
+but the index value must be 0.
+
+@smallexample
+vector __int128_t vec_vaddcuq (vector __int128_t, vector __int128_t);
+vector __uint128_t vec_vaddcuq (vector __uint128_t, vector __uint128_t);
+
+vector __int128_t vec_vadduqm (vector __int128_t, vector __int128_t);
+vector __uint128_t vec_vadduqm (vector __uint128_t, vector __uint128_t);
+
+vector __int128_t vec_vaddecuq (vector __int128_t, vector __int128_t,
+ vector __int128_t);
+vector __uint128_t vec_vaddecuq (vector __uint128_t, vector __uint128_t,
+ vector __uint128_t);
+
+vector __int128_t vec_vaddeuqm (vector __int128_t, vector __int128_t,
+ vector __int128_t);
+vector __uint128_t vec_vaddeuqm (vector __uint128_t, vector __uint128_t,
+ vector __uint128_t);
+
+vector __int128_t vec_vsubecuq (vector __int128_t, vector __int128_t,
+ vector __int128_t);
+vector __uint128_t vec_vsubecuq (vector __uint128_t, vector __uint128_t,
+ vector __uint128_t);
+
+vector __int128_t vec_vsubeuqm (vector __int128_t, vector __int128_t,
+ vector __int128_t);
+vector __uint128_t vec_vsubeuqm (vector __uint128_t, vector __uint128_t,
+ vector __uint128_t);
+
+vector __int128_t vec_vsubcuq (vector __int128_t, vector __int128_t);
+vector __uint128_t vec_vsubcuq (vector __uint128_t, vector __uint128_t);
+
+__int128_t vec_vsubuqm (__int128_t, __int128_t);
+__uint128_t vec_vsubuqm (__uint128_t, __uint128_t);
+
+vector __int128_t __builtin_bcdadd (vector __int128_t, vector__int128_t);
+int __builtin_bcdadd_lt (vector __int128_t, vector__int128_t);
+int __builtin_bcdadd_eq (vector __int128_t, vector__int128_t);
+int __builtin_bcdadd_gt (vector __int128_t, vector__int128_t);
+int __builtin_bcdadd_ov (vector __int128_t, vector__int128_t);
+vector __int128_t bcdsub (vector __int128_t, vector__int128_t);
+int __builtin_bcdsub_lt (vector __int128_t, vector__int128_t);
+int __builtin_bcdsub_eq (vector __int128_t, vector__int128_t);
+int __builtin_bcdsub_gt (vector __int128_t, vector__int128_t);
+int __builtin_bcdsub_ov (vector __int128_t, vector__int128_t);
+@end smallexample
+
If the cryptographic instructions are enabled (@option{-mcrypto} or
@option{-mcpu=power8}), the following builtins are enabled.
@end smallexample
@end deftypefn
+@deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void)
+Returns the value that is currently set in the @samp{FPSCR} register.
+@end deftypefn
+
+@deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val})
+Sets the @samp{FPSCR} register to the specified value @var{val}, while
+preserving the current values of the FR, SZ and PR bits.
+@end deftypefn
+
@node SPARC VIS Built-in Functions
@subsection SPARC VIS Built-in Functions
@node Symbol-Renaming Pragmas
@subsection Symbol-Renaming Pragmas
-For compatibility with the Solaris system headers, GCC
-supports two @code{#pragma} directives that change the name used in
-assembly for a given declaration. To get this effect
-on all platforms supported by GCC, use the asm labels extension (@pxref{Asm
-Labels}).
+GCC supports a @code{#pragma} directive that changes the name used in
+assembly for a given declaration. This effect can also be achieved
+using the asm labels extension (@pxref{Asm Labels}).
@table @code
@item redefine_extname @var{oldname} @var{newname}
@end table
This pragma and the asm labels extension interact in a complicated
-manner. Here are some corner cases you may want to be aware of.
+manner. Here are some corner cases you may want to be aware of:
@enumerate
-@item Both pragmas silently apply only to declarations with external
+@item This pragma silently applies only to declarations with external
linkage. Asm labels do not have this restriction.
-@item In C++, both pragmas silently apply only to declarations with
+@item In C++, this pragma silently applies only to declarations with
``C'' linkage. Again, asm labels do not have this restriction.
-@item If any of the three ways of changing the assembly name of a
-declaration is applied to a declaration whose assembly name has
+@item If either of the ways of changing the assembly name of a
+declaration are applied to a declaration whose assembly name has
already been determined (either by a previous use of one of these
features, or because the compiler needed the assembly name in order to
generate code), and the new name is different, a warning issues and
This pragma allows the user to set the visibility for multiple
declarations without having to give each a visibility attribute
-@xref{Function Attributes}, for more information about visibility and
-the attribute syntax.
+(@pxref{Function Attributes}).
In C++, @samp{#pragma GCC visibility} affects only namespace-scope
declarations. Class members and template specializations are not
@xref{Function Attributes}, for more information about the
@code{target} attribute and the attribute syntax.
-The @code{#pragma GCC target} attribute is not implemented in GCC versions earlier
-than 4.4 for the i386/x86_64 and 4.6 for the PowerPC back ends. At
-present, it is not implemented for other back ends.
+The @code{#pragma GCC target} pragma is presently implemented for
+i386/x86_64, PowerPC, and Nios II targets only.
@end table
@table @code
template class (i.e.@: the vtable) without instantiating any of its
members (with @code{inline}), and instantiation of only the static data
members of a template class, without the support data or member
-functions (with (@code{static}):
+functions (with @code{static}):
@smallexample
extern template int max (int, int);
A redeclaration of a function or class must not add new ABI tags,
since doing so would change the mangled name.
+The ABI tags apply to a name, so all instantiations and
+specializations of a template have the same tags. The attribute will
+be ignored if applied to an explicit specialization or instantiation.
+
The @option{-Wabi-tag} flag enables a warning about a class which does
not have all the ABI tags used by its subobjects and virtual functions; for users with code
that needs to coexist with an earlier ABI, using this option can help
projects / thirdparty / gcc.git / blobdiff