]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
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. |