diff options
Diffstat (limited to 'gcc/doc/extend.texi')
| -rw-r--r-- | gcc/doc/extend.texi | 378 |
1 files changed, 308 insertions, 70 deletions
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 43f9ecf2466..34cb7d3dd22 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1988-2017 Free Software Foundation, Inc. +c Copyright (C) 1988-2017 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @@ -2984,6 +2984,19 @@ asm (""); (@pxref{Extended Asm}) in the called function, to serve as a special side-effect. +@item noipa +@cindex @code{noipa} function attribute +Disable interprocedural optimizations between the function with this +attribute and its callers, as if the body of the function is not available +when optimizing callers and the callers are unavailable when optimizing +the body. This attribute implies @code{noinline}, @code{noclone} and +@code{no_icf} attributes. However, this attribute is not equivalent +to a combination of other attributes, because its purpose is to suppress +existing and future optimizations employing interprocedural analysis, +including those that do not have an attribute suitable for disabling +them individually. This attribute is supported mainly for the purpose +of testing the compiler. + @item nonnull (@var{arg-index}, @dots{}) @cindex @code{nonnull} function attribute @cindex functions with non-null pointer arguments @@ -3105,6 +3118,27 @@ that affect more than one function. This attribute should be used for debugging purposes only. It is not suitable in production code. +@item patchable_function_entry +@cindex @code{patchable_function_entry} function attribute +@cindex extra NOP instructions at the function entry point +In case the target's text segment can be made writable at run time by +any means, padding the function entry with a number of NOPs can be +used to provide a universal tool for instrumentation. + +The @code{patchable_function_entry} function attribute can be used to +change the number of NOPs to any desired value. The two-value syntax +is the same as for the command-line switch +@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with +the function entry point before the @var{M}th NOP instruction. +@var{M} defaults to 0 if omitted e.g. function entry point is before +the first NOP. + +If patchable function entries are enabled globally using the command-line +option @option{-fpatchable-function-entry=N,M}, then you must disable +instrumentation on all functions that are part of the instrumentation +framework with the attribute @code{patchable_function_entry (0)} +to prevent recursion. + @item pure @cindex @code{pure} function attribute @cindex functions that have no side effects @@ -3278,16 +3312,17 @@ are the same as for @code{target} attribute. For instance, on an x86, you could compile a function with @code{target_clones("sse4.1,avx")}. GCC creates two function clones, one compiled with @option{-msse4.1} and another with @option{-mavx}. -It also creates a resolver function (see the @code{ifunc} attribute -above) that dynamically selects a clone suitable for current -architecture. On a PowerPC, you can compile a function with @code{target_clones("cpu=power9,default")}. GCC will create two function clones, one compiled with @option{-mcpu=power9} and another -with the default options. It also creates a resolver function (see +with the default options. GCC must be configured to use GLIBC 2.23 or +newer in order to use the @code{target_clones} attribute. + +It also creates a resolver function (see the @code{ifunc} attribute above) that dynamically selects a clone -suitable for current architecture. +suitable for current architecture. The resolver is created only if there +is a usage of a function with @code{target_clones} attribute. @item unused @cindex @code{unused} function attribute @@ -3815,6 +3850,33 @@ prologue/epilogue sequences generated by the compiler. Only basic basic @code{asm} and C code may appear to work, they cannot be depended upon to work reliably and are not supported. +@item no_gccisr +@cindex @code{no_gccisr} function attribute, AVR +Do not use @code{__gcc_isr} pseudo instructions in a function with +the @code{interrupt} or @code{signal} attribute aka. interrupt +service routine (ISR). +Use this attribute if the preamble of the ISR prologue should always read +@example +push __zero_reg__ +push __tmp_reg__ +in __tmp_reg__, __SREG__ +push __tmp_reg__ +clr __zero_reg__ +@end example +and accordingly for the postamble of the epilogue --- no matter whether +the mentioned registers are actually used in the ISR or not. +Situations where you might want to use this attribute include: +@itemize @bullet +@item +Code that (effectively) clobbers bits of @code{SREG} other than the +@code{I}-flag by writing to the memory location of @code{SREG}. +@item +Code that uses inline assembler to jump to a different function which +expects (parts of) the prologue code as outlined above to be present. +@end itemize +To disable @code{__gcc_isr} generation for the whole compilation unit, +there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}. + @item OS_main @itemx OS_task @cindex @code{OS_main} function attribute, AVR @@ -5308,6 +5370,17 @@ this function attribute to make GCC generate the ``hot-patching'' function prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 and newer. +@item naked +@cindex @code{naked} function attribute, x86 +This attribute allows the compiler to construct the +requisite function declaration, while allowing the body of the +function to be assembly code. The specified function will not have +prologue/epilogue sequences generated by the compiler. Only basic +@code{asm} statements can safely be included in naked functions +(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of +basic @code{asm} and C code may appear to work, they cannot be +depended upon to work reliably and are not supported. + @item regparm (@var{number}) @cindex @code{regparm} function attribute, x86 @cindex functions that are passed arguments in registers on x86-32 @@ -12720,54 +12793,37 @@ or if not a specific built-in is implemented or not. For example, if @code{__builtin_avr_nop} is available the macro @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. -The following built-in functions map to the respective machine +@table @code + +@item void __builtin_avr_nop (void) +@itemx void __builtin_avr_sei (void) +@itemx void __builtin_avr_cli (void) +@itemx void __builtin_avr_sleep (void) +@itemx void __builtin_avr_wdr (void) +@itemx unsigned char __builtin_avr_swap (unsigned char) +@itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char) +@itemx int __builtin_avr_fmuls (char, char) +@itemx int __builtin_avr_fmulsu (char, unsigned char) +These built-in functions map to the respective machine instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented as library call if no hardware multiplier is available. -@smallexample -void __builtin_avr_nop (void) -void __builtin_avr_sei (void) -void __builtin_avr_cli (void) -void __builtin_avr_sleep (void) -void __builtin_avr_wdr (void) -unsigned char __builtin_avr_swap (unsigned char) -unsigned int __builtin_avr_fmul (unsigned char, unsigned char) -int __builtin_avr_fmuls (char, char) -int __builtin_avr_fmulsu (char, unsigned char) -@end smallexample - -In order to delay execution for a specific number of cycles, GCC -implements -@smallexample -void __builtin_avr_delay_cycles (unsigned long ticks) -@end smallexample - -@noindent -@code{ticks} is the number of ticks to delay execution. Note that this +@item void __builtin_avr_delay_cycles (unsigned long ticks) +Delay execution for @var{ticks} cycles. Note that this built-in does not take into account the effect of interrupts that -might increase delay time. @code{ticks} must be a compile-time +might increase delay time. @var{ticks} must be a compile-time integer constant; delays with a variable number of cycles are not supported. -@smallexample -char __builtin_avr_flash_segment (const __memx void*) -@end smallexample - -@noindent +@item char __builtin_avr_flash_segment (const __memx void*) This built-in takes a byte address to the 24-bit @ref{AVR Named Address Spaces,address space} @code{__memx} and returns the number of the flash segment (the 64 KiB chunk) where the address points to. Counting starts at @code{0}. If the address does not point to flash memory, return @code{-1}. -@smallexample -unsigned char __builtin_avr_insert_bits (unsigned long map, - unsigned char bits, - unsigned char val) -@end smallexample - -@noindent +@item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val) Insert bits from @var{bits} into @var{val} and return the resulting value. The nibbles of @var{map} determine how the insertion is performed: Let @var{X} be the @var{n}-th nibble of @var{map} @@ -12812,13 +12868,29 @@ __builtin_avr_insert_bits (0xffff3210, bits, val) __builtin_avr_insert_bits (0x01234567, bits, 0) @end smallexample -@smallexample -void __builtin_avr_nops (unsigned count) -@end smallexample +@item void __builtin_avr_nops (unsigned count) +Insert @var{count} @code{NOP} instructions. +The number of instructions must be a compile-time integer constant. + +@end table @noindent -Insert @code{count} @code{NOP} instructions. -The number of instructions must be a compile-time integer constant. +There are many more AVR-specific built-in functions that are used to +implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of +section 7.18a.6. You don't need to use these built-ins directly. +Instead, use the declarations as supplied by the @code{stdfix.h} header +with GNU-C99: + +@smallexample +#include <stdfix.h> + +// Re-interpret the bit representation of unsigned 16-bit +// integer @var{uval} as Q-format 0.16 value. +unsigned fract get_bits (uint_ur_t uval) +@{ + return urbits (uval); +@} +@end smallexample @node Blackfin Built-in Functions @subsection Blackfin Built-in Functions @@ -14918,8 +14990,18 @@ to maintain API compatibility with the x86 builtins. @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) This function returns a value of @code{1} if the run-time CPU is of type -@var{cpuname} and returns @code{0} otherwise. The following CPU names can be -detected: +@var{cpuname} and returns @code{0} otherwise + +The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer +which exports the hardware capability bits. GCC defines the macro +@code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports} +built-in function is fully supported. + +If GCC was configured to use a GLIBC before 2.23, the built-in +function @code{__builtin_cpu_is} always returns a 0 and the compiler +issues a warning. + +The following CPU names can be detected: @table @samp @item power9 @@ -14956,20 +15038,33 @@ IBM PowerPC Cell Broadband Engine Architecture CPU. Here is an example: @smallexample -if (__builtin_cpu_is ("power8")) - @{ - do_power8 (); // POWER8 specific implementation. - @} -else - @{ - do_generic (); // Generic implementation. - @} +#ifdef __BUILTIN_CPU_SUPPORTS__ + if (__builtin_cpu_is ("power8")) + @{ + do_power8 (); // POWER8 specific implementation. + @} + else +#endif + @{ + do_generic (); // Generic implementation. + @} @end smallexample @end deftypefn @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) This function returns a value of @code{1} if the run-time CPU supports the HWCAP -feature @var{feature} and returns @code{0} otherwise. The following features can be +feature @var{feature} and returns @code{0} otherwise. + +The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or +newer which exports the hardware capability bits. GCC defines the +macro @code{__BUILTIN_CPU_SUPPORTS__} if the +@code{__builtin_cpu_supports} built-in function is fully supported. + +If GCC was configured to use a GLIBC before 2.23, the built-in +function @code{__builtin_cpu_suports} always returns a 0 and the +compiler issues a warning. + +The following features can be detected: @table @samp @@ -15053,14 +15148,16 @@ CPU supports the vector-scalar extension. Here is an example: @smallexample -if (__builtin_cpu_supports ("fpu")) - @{ - asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); - @} -else - @{ - dst = __fadd (src1, src2); // Software FP addition function. - @} +#ifdef __BUILTIN_CPU_SUPPORTS__ + if (__builtin_cpu_supports ("fpu")) + @{ + asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); + @} + else +#endif + @{ + dst = __fadd (src1, src2); // Software FP addition function. + @} @end smallexample @end deftypefn @@ -15176,13 +15273,21 @@ long long __builtin_darn_raw (void); int __builtin_darn_32 (void); unsigned int scalar_extract_exp (double source); +unsigned long long int scalar_extract_exp (__ieee128 source); + unsigned long long int scalar_extract_sig (double source); +unsigned __int128 scalar_extract_sig (__ieee128 source); double scalar_insert_exp (unsigned long long int significand, unsigned long long int exponent); double scalar_insert_exp (double significand, unsigned long long int exponent); +ieee_128 +scalar_insert_exp (unsigned __int128 significand, unsigned long long int exponent); +ieee_128 +scalar_insert_exp (ieee_128 significand, unsigned long long int exponent); + int scalar_cmp_exp_gt (double arg1, double arg2); int scalar_cmp_exp_lt (double arg1, double arg2); int scalar_cmp_exp_eq (double arg1, double arg2); @@ -15190,9 +15295,11 @@ int scalar_cmp_exp_unordered (double arg1, double arg2); bool scalar_test_data_class (float source, const int condition); bool scalar_test_data_class (double source, const int condition); +bool scalar_test_data_class (__ieee128 source, const int condition); bool scalar_test_neg (float source); bool scalar_test_neg (double source); +bool scalar_test_neg (__ieee128 source); int __builtin_byte_in_set (unsigned char u, unsigned long long set); int __builtin_byte_in_range (unsigned char u, unsigned int range); @@ -15232,25 +15339,38 @@ functions require a 64-bit environment supporting ISA 3.0 or later. The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in functions return the significand and the biased exponent value respectively of their @code{source} arguments. -Within the result returned by @code{scalar_extract_sig}, -the @code{0x10000000000000} bit is set if the +When supplied with a 64-bit @code{source} argument, the +result returned by @code{scalar_extract_sig} has +the @code{0x0010000000000000} bit set if the function's @code{source} argument is in normalized form. Otherwise, this bit is set to 0. +When supplied with a 128-bit @code{source} argument, the +@code{0x00010000000000000000000000000000} bit of the result is +treated similarly. Note that the sign of the significand is not represented in the result returned from the @code{scalar_extract_sig} function. Use the @code{scalar_test_neg} function to test the sign of its @code{double} argument. -The @code{scalar_insert_exp} -function requires a 64-bit environment supporting ISA 3.0 or later. -The @code{scalar_insert_exp} built-in function returns a double-precision +The @code{scalar_insert_exp} +functions require a 64-bit environment supporting ISA 3.0 or later. +When supplied with a 64-bit first argument, the +@code{scalar_insert_exp} built-in function returns a double-precision floating point value that is constructed by assembling the values of its @code{significand} and @code{exponent} arguments. The sign of the result is copied from the most significant bit of the @code{significand} argument. The significand and exponent components of the result are composed of the least significant 11 bits of the @code{exponent} argument and the least significant 52 bits of the -@code{significand} argument. +@code{significand} argument respectively. + +When supplied with a 128-bit first argument, the +@code{scalar_insert_exp} built-in function returns a quad-precision +ieee floating point value. The sign bit of the result is copied from +the most significant bit of the @code{significand} argument. +The significand and exponent components of the result are composed of +the least significant 15 bits of the @code{exponent} argument and the +least significant 112 bits of the @code{significand} argument respectively. The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt}, @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in @@ -15357,12 +15477,23 @@ vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2); vector bool int vec_cmpnez (vector unsigned int, vector unsigned int); +vector signed char vec_cnttz (vector signed char); +vector unsigned char vec_cnttz (vector unsigned char); +vector signed short vec_cnttz (vector signed short); +vector unsigned short vec_cnttz (vector unsigned short); +vector signed int vec_cnttz (vector signed int); +vector unsigned int vec_cnttz (vector unsigned int); +vector signed long long vec_cnttz (vector signed long long); +vector unsigned long long vec_cnttz (vector unsigned long long); + signed int vec_cntlz_lsbb (vector signed char); signed int vec_cntlz_lsbb (vector unsigned char); signed int vec_cnttz_lsbb (vector signed char); signed int vec_cnttz_lsbb (vector unsigned char); +vector unsigned short vec_pack_to_short_fp32 (vector float, vector float); + vector signed char vec_xl_len (signed char *addr, size_t len); vector unsigned char vec_xl_len (unsigned char *addr, size_t len); vector signed int vec_xl_len (signed int *addr, size_t len); @@ -16558,6 +16689,19 @@ vector bool char vec_perm (vector bool char, vector float vec_re (vector float); +vector bool char vec_reve (vector bool char); +vector signed char vec_reve (vector signed char); +vector unsigned char vec_reve (vector unsigned char); +vector bool int vec_reve (vector bool int); +vector signed int vec_reve (vector signed int); +vector unsigned int vec_reve (vector unsigned int); +vector bool long long vec_reve (vector bool long long); +vector signed long long vec_reve (vector signed long long); +vector unsigned long long vec_reve (vector unsigned long long); +vector bool short vec_reve (vector bool short); +vector signed short vec_reve (vector signed short); +vector unsigned short vec_reve (vector unsigned short); + vector signed char vec_rl (vector signed char, vector unsigned char); vector unsigned char vec_rl (vector unsigned char, @@ -16645,6 +16789,13 @@ vector bool char vec_sel (vector bool char, vector bool char, vector unsigned char); +vector signed long long vec_signed (vector double); +vector signed int vec_signed (vector float); + +vector signed int vec_signede (vector double); +vector signed int vec_signedo (vector double); +vector signed int vec_signed2 (vector double, vector double); + vector signed char vec_sl (vector signed char, vector unsigned char); vector unsigned char vec_sl (vector unsigned char, @@ -17096,7 +17247,34 @@ vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char); +vector signed int vec_subc (vector signed int, vector signed int); vector unsigned int vec_subc (vector unsigned int, vector unsigned int); +vector signed __int128 vec_subc (vector signed __int128, + vector signed __int128); +vector unsigned __int128 vec_subc (vector unsigned __int128, + vector unsigned __int128); + +vector signed int vec_sube (vector signed int, vector signed int, + vector signed int); +vector unsigned int vec_sube (vector unsigned int, vector unsigned int, + vector unsigned int); +vector signed __int128 vec_sube (vector signed __int128, + vector signed __int128, + vector signed __int128); +vector unsigned __int128 vec_sube (vector unsigned __int128, + vector unsigned __int128, + vector unsigned __int128); + +vector signed int vec_subec (vector signed int, vector signed int, + vector signed int); +vector unsigned int vec_subec (vector unsigned int, vector unsigned int, + vector unsigned int); +vector signed __int128 vec_subec (vector signed __int128, + vector signed __int128, + vector signed __int128); +vector unsigned __int128 vec_subec (vector unsigned __int128, + vector unsigned __int128, + vector unsigned __int128); vector unsigned char vec_subs (vector bool char, vector unsigned char); vector unsigned char vec_subs (vector unsigned char, vector bool char); @@ -17173,6 +17351,13 @@ vector signed int vec_sums (vector signed int, vector signed int); vector float vec_trunc (vector float); +vector signed long long vec_unsigned (vector double); +vector signed int vec_unsigned (vector float); + +vector signed int vec_unsignede (vector double); +vector signed int vec_unsignedo (vector double); +vector signed int vec_unsigned2 (vector double, vector double); + vector signed short vec_unpackh (vector signed char); vector bool short vec_unpackh (vector bool char); vector signed int vec_unpackh (vector signed short); @@ -18175,6 +18360,9 @@ vector bool short vec_cmpne (vector bool short, vector bool short); vector bool int vec_cmpne (vector bool int, vector bool int); vector bool long long vec_cmpne (vector bool long long, vector bool long long); +vector float vec_extract_fp32_from_shorth (vector unsigned short); +vector float vec_extract_fp32_from_shortl (vector unsigned short); + vector long long vec_vctz (vector long long); vector unsigned long long vec_vctz (vector unsigned long long); vector int vec_vctz (vector int); @@ -18205,6 +18393,13 @@ vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char, vector signed char vec_insert4b (long long, vector signed char, const int); vector unsigned char vec_insert4b (long long, vector unsigned char, const int); +vector unsigned int vec_parity_lsbb (vector signed int); +vector unsigned int vec_parity_lsbb (vector unsigned int); +vector unsigned __int128 vec_parity_lsbb (vector signed __int128); +vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128); +vector unsigned long long vec_parity_lsbb (vector signed long long); +vector unsigned long long vec_parity_lsbb (vector unsigned long long); + vector int vec_vprtyb (vector int); vector unsigned int vec_vprtyb (vector unsigned int); vector long long vec_vprtyb (vector long long); @@ -18420,13 +18615,17 @@ of each element. If the ISA 3.0 instruction set additions (@option{-mcpu=power9}) are available: @smallexample +vector signed bool char vec_revb (vector signed char); vector signed char vec_revb (vector signed char); vector unsigned char vec_revb (vector unsigned char); +vector bool short vec_revb (vector bool short); vector short vec_revb (vector short); vector unsigned short vec_revb (vector unsigned short); +vector bool int vec_revb (vector bool int); vector int vec_revb (vector int); vector unsigned int vec_revb (vector unsigned int); vector float vec_revb (vector float); +vector bool long long vec_revb (vector bool long long); vector long long vec_revb (vector long long); vector unsigned long long vec_revb (vector unsigned long long); vector double vec_revb (vector double); @@ -19199,6 +19398,45 @@ v4hi __builtin_vis_fpminu16 (v4hi, v4hi); v2si __builtin_vis_fpminu32 (v2si, v2si); @end smallexample +When you use the @option{-mvis4b} switch, the VIS version 4.0B +built-in functions also become available: + +@smallexample +v8qi __builtin_vis_dictunpack8 (double, int); +v4hi __builtin_vis_dictunpack16 (double, int); +v2si __builtin_vis_dictunpack32 (double, int); + +long __builtin_vis_fpcmple8shl (v8qi, v8qi, int); +long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int); +long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int); +long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int); + +long __builtin_vis_fpcmple16shl (v4hi, v4hi, int); +long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int); +long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int); +long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int); + +long __builtin_vis_fpcmple32shl (v2si, v2si, int); +long __builtin_vis_fpcmpgt32shl (v2si, v2si, int); +long __builtin_vis_fpcmpeq32shl (v2si, v2si, int); +long __builtin_vis_fpcmpne32shl (v2si, v2si, int); + +long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int); +long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int); +long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int); +long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int); +long __builtin_vis_fpcmpule32shl (v2si, v2si, int); +long __builtin_vis_fpcmpugt32shl (v2si, v2si, int); + +long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int); +long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int); +long __builtin_vis_fpcmpde32shl (v2si, v2si, int); + +long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int); +long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int); +long __builtin_vis_fpcmpur32shl (v2si, v2si, int); +@end smallexample + @node SPU Built-in Functions @subsection SPU Built-in Functions |