gcc/doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/aarch64-function-attributes.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _aarch64-function-attributes:
   7
   8 AArch64 Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 The following target-specific function attributes are available for the
  12 AArch64 target.  For the most part, these options mirror the behavior of
  13 similar command-line options (see :ref:`aarch64-options`), but on a
  14 per-function basis.
  15
  16 .. index:: general-regs-only function attribute, AArch64
  17
  18 .. aarch64-fn-attr:: general-regs-only
  19
  20   Indicates that no floating-point or Advanced SIMD registers should be
  21   used when generating code for this function.  If the function explicitly
  22   uses floating-point code, then the compiler gives an error.  This is
  23   the same behavior as that of the command-line option
  24   :option:`-mgeneral-regs-only`.
  25
  26 .. index:: fix-cortex-a53-835769 function attribute, AArch64
  27
  28 .. aarch64-fn-attr:: fix-cortex-a53-835769
  29
  30   Indicates that the workaround for the Cortex-A53 erratum 835769 should be
  31   applied to this function.  To explicitly disable the workaround for this
  32   function specify the negated form: ``no-fix-cortex-a53-835769``.
  33   This corresponds to the behavior of the command line options
  34   :option:`-mfix-cortex-a53-835769` and :option:`-mno-fix-cortex-a53-835769`.
  35
  36 .. index:: cmodel= function attribute, AArch64
  37
  38 .. aarch64-fn-attr:: cmodel=
  39
  40   Indicates that code should be generated for a particular code model for
  41   this function.  The behavior and permissible arguments are the same as
  42   for the command line option :option:`-mcmodel=`.
  43
  44 .. index:: strict-align function attribute, AArch64
  45
  46 .. aarch64-fn-attr:: strict-align, no-strict-align
  47
  48   :aarch64-fn-attr:`strict-align` indicates that the compiler should not assume that unaligned
  49   memory references are handled by the system.  To allow the compiler to assume
  50   that aligned memory references are handled by the system, the inverse attribute
  51   ``no-strict-align`` can be specified.  The behavior is same as for the
  52   command-line option :option:`-mstrict-align` and :option:`-mno-strict-align`.
  53
  54 .. index:: omit-leaf-frame-pointer function attribute, AArch64
  55
  56 .. aarch64-fn-attr:: omit-leaf-frame-pointer
  57
  58   Indicates that the frame pointer should be omitted for a leaf function call.
  59   To keep the frame pointer, the inverse attribute
  60   ``no-omit-leaf-frame-pointer`` can be specified.  These attributes have
  61   the same behavior as the command-line options :option:`-momit-leaf-frame-pointer`
  62   and :option:`-mno-omit-leaf-frame-pointer`.
  63
  64 .. index:: tls-dialect= function attribute, AArch64
  65
  66 .. aarch64-fn-attr:: tls-dialect=
  67
  68   Specifies the TLS dialect to use for this function.  The behavior and
  69   permissible arguments are the same as for the command-line option
  70   :option:`-mtls-dialect=`.
  71
  72 .. index:: arch= function attribute, AArch64
  73
  74 .. aarch64-fn-attr:: arch=
  75
  76   Specifies the architecture version and architectural extensions to use
  77   for this function.  The behavior and permissible arguments are the same as
  78   for the :option:`-march=` command-line option.
  79
  80 .. index:: tune= function attribute, AArch64
  81
  82 .. aarch64-fn-attr:: tune=
  83
  84   Specifies the core for which to tune the performance of this function.
  85   The behavior and permissible arguments are the same as for the :option:`-mtune=`
  86   command-line option.
  87
  88 .. index:: cpu= function attribute, AArch64
  89
  90 .. aarch64-fn-attr:: cpu=
  91
  92   Specifies the core for which to tune the performance of this function and also
  93   whose architectural features to use.  The behavior and valid arguments are the
  94   same as for the :option:`-mcpu=` command-line option.
  95
  96 .. index:: sign-return-address function attribute, AArch64
  97
  98 .. aarch64-fn-attr:: sign-return-address
  99
 100   Select the function scope on which return address signing will be applied.  The
 101   behavior and permissible arguments are the same as for the command-line option
 102   :option:`-msign-return-address=`.  The default value is ``none``.  This
 103   attribute is deprecated.  The :gcc-attr:`branch-protection` attribute should
 104   be used instead.
 105
 106 .. index:: branch-protection function attribute, AArch64
 107
 108 .. aarch64-fn-attr:: branch-protection
 109
 110   Select the function scope on which branch protection will be applied.  The
 111   behavior and permissible arguments are the same as for the command-line option
 112   :option:`-mbranch-protection=`.  The default value is ``none``.
 113
 114 .. index:: outline-atomics function attribute, AArch64
 115
 116 .. aarch64-fn-attr:: outline-atomics
 117
 118   Enable or disable calls to out-of-line helpers to implement atomic operations.
 119   This corresponds to the behavior of the command line options
 120   :option:`-moutline-atomics` and :option:`-mno-outline-atomics`.
 121
 122 The above target attributes can be specified as follows:
 123
 124 .. code-block:: c++
 125
 126   __attribute__((target("attr-string")))
 127   int
 128   f (int a)
 129   {
 130     return a + 5;
 131   }
 132
 133 where ``attr-string`` is one of the attribute strings specified above.
 134
 135 Additionally, the architectural extension string may be specified on its
 136 own.  This can be used to turn on and off particular architectural extensions
 137 without having to specify a particular architecture version or core.  Example:
 138
 139 .. code-block:: c++
 140
 141   __attribute__((target("+crc+nocrypto")))
 142   int
 143   foo (int a)
 144   {
 145     return a + 5;
 146   }
 147
 148 In this example ``target("+crc+nocrypto")`` enables the ``crc``
 149 extension and disables the ``crypto`` extension for the function ``foo``
 150 without modifying an existing :option:`-march=` or :option:`-mcpu` option.
 151
 152 Multiple target function attributes can be specified by separating them with
 153 a comma.  For example:
 154
 155 .. code-block:: c++
 156
 157   __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53")))
 158   int
 159   foo (int a)
 160   {
 161     return a + 5;
 162   }
 163
 164 is valid and compiles function ``foo`` for ARMv8-A with ``crc``
 165 and ``crypto`` extensions and tunes it for ``cortex-a53``.
 166
 167 Inlining rules
 168 ~~~~~~~~~~~~~~
 169
 170 Specifying target attributes on individual functions or performing link-time
 171 optimization across translation units compiled with different target options
 172 can affect function inlining rules:
 173
 174 In particular, a caller function can inline a callee function only if the
 175 architectural features available to the callee are a subset of the features
 176 available to the caller.
 177 For example: A function ``foo`` compiled with :option:`-march=armv8-a+crc`,
 178 or tagged with the equivalent ``arch=armv8-a+crc`` attribute,
 179 can inline a function ``bar`` compiled with :option:`-march=armv8-a+nocrc`
 180 because the all the architectural features that function ``bar`` requires
 181 are available to function ``foo``.  Conversely, function ``bar`` cannot
 182 inline function ``foo``.
 183
 184 Additionally inlining a function compiled with :option:`-mstrict-align` into a
 185 function compiled without ``-mstrict-align`` is not allowed.
 186 However, inlining a function compiled without :option:`-mstrict-align` into a
 187 function compiled with :option:`-mstrict-align` is allowed.
 188
 189 Note that CPU tuning options and attributes such as the :option:`-mcpu=`,
 190 :option:`-mtune=` do not inhibit inlining unless the CPU specified by the
 191 :option:`-mcpu=` option or the :gcc-attr:`cpu=` attribute conflicts with the
 192 architectural feature rules specified above.