1 @c Copyright (C) 2009-2020 Free Software Foundation, Inc.
2 @c Contributed by ARM Ltd.
3 @c This is part of the GAS manual.
4 @c For copying conditions, see the file as.texinfo.
9 @node AArch64-Dependent
10 @chapter AArch64 Dependent Features
14 @node Machine Dependencies
15 @chapter AArch64 Dependent Features
18 @cindex AArch64 support
20 * AArch64 Options:: Options
21 * AArch64 Extensions:: Extensions
22 * AArch64 Syntax:: Syntax
23 * AArch64 Floating Point:: Floating Point
24 * AArch64 Directives:: AArch64 Machine Directives
25 * AArch64 Opcodes:: Opcodes
26 * AArch64 Mapping Symbols:: Mapping Symbols
31 @cindex AArch64 options (none)
32 @cindex options for AArch64 (none)
37 @cindex @option{-EB} command-line option, AArch64
39 This option specifies that the output generated by the assembler should
40 be marked as being encoded for a big-endian processor.
42 @cindex @option{-EL} command-line option, AArch64
44 This option specifies that the output generated by the assembler should
45 be marked as being encoded for a little-endian processor.
47 @cindex @option{-mabi=} command-line option, AArch64
49 Specify which ABI the source code uses. The recognized arguments
50 are: @code{ilp32} and @code{lp64}, which decides the generated object
51 file in ELF32 and ELF64 format respectively. The default is @code{lp64}.
53 @cindex @option{-mcpu=} command-line option, AArch64
54 @item -mcpu=@var{processor}[+@var{extension}@dots{}]
55 This option specifies the target processor. The assembler will issue an error
56 message if an attempt is made to assemble an instruction which will not execute
57 on the target processor. The following processor names are recognized:
83 The special name @code{all} may be used to allow the assembler to accept
84 instructions valid for any supported processor, including all optional
87 In addition to the basic instruction set, the assembler can be told to
88 accept, or restrict, various extension mnemonics that extend the
89 processor. @xref{AArch64 Extensions}.
91 If some implementations of a particular processor can have an
92 extension, then then those extensions are automatically enabled.
93 Consequently, you will not normally have to specify any additional
96 @cindex @option{-march=} command-line option, AArch64
97 @item -march=@var{architecture}[+@var{extension}@dots{}]
98 This option specifies the target architecture. The assembler will
99 issue an error message if an attempt is made to assemble an
100 instruction which will not execute on the target architecture. The
101 following architecture names are recognized: @code{armv8-a},
102 @code{armv8.1-a}, @code{armv8.2-a}, @code{armv8.3-a}, @code{armv8.4-a}
103 @code{armv8.5-a}, and @code{armv8.6-a}.
105 If both @option{-mcpu} and @option{-march} are specified, the
106 assembler will use the setting for @option{-mcpu}. If neither are
107 specified, the assembler will default to @option{-mcpu=all}.
109 The architecture option can be extended with the same instruction set
110 extension options as the @option{-mcpu} option. Unlike
111 @option{-mcpu}, extensions are not always enabled by default,
112 @xref{AArch64 Extensions}.
114 @cindex @code{-mverbose-error} command-line option, AArch64
115 @item -mverbose-error
116 This option enables verbose error messages for AArch64 gas. This option
117 is enabled by default.
119 @cindex @code{-mno-verbose-error} command-line option, AArch64
120 @item -mno-verbose-error
121 This option disables verbose error messages in AArch64 gas.
126 @node AArch64 Extensions
127 @section Architecture Extensions
129 The table below lists the permitted architecture extensions that are
130 supported by the assembler and the conditions under which they are
131 automatically enabled.
133 Multiple extensions may be specified, separated by a @code{+}.
134 Extension mnemonics may also be removed from those the assembler
135 accepts. This is done by prepending @code{no} to the option that adds
136 the extension. Extensions that are removed must be listed after all
137 extensions that have been added.
139 Enabling an extension that requires other extensions will
140 automatically cause those extensions to be enabled. Similarly,
141 disabling an extension that is required by other extensions will
142 automatically cause those extensions to be disabled.
144 @multitable @columnfractions .12 .17 .17 .54
145 @headitem Extension @tab Minimum Architecture @tab Enabled by default
147 @item @code{i8mm} @tab ARMv8.2-A @tab ARMv8.6-A or later
148 @tab Enable Int8 Matrix Multiply extension.
149 @item @code{f32mm} @tab ARMv8.2-A @tab No
150 @tab Enable F32 Matrix Multiply extension.
151 @item @code{f64mm} @tab ARMv8.2-A @tab No
152 @tab Enable F64 Matrix Multiply extension.
153 @item @code{bf16} @tab ARMv8.2-A @tab ARMv8.6-A or later
154 @tab Enable BFloat16 extension.
155 @item @code{compnum} @tab ARMv8.2-A @tab ARMv8.3-A or later
156 @tab Enable the complex number SIMD extensions. This implies
157 @code{fp16} and @code{simd}.
158 @item @code{crc} @tab ARMv8-A @tab ARMv8.1-A or later
159 @tab Enable CRC instructions.
160 @item @code{crypto} @tab ARMv8-A @tab No
161 @tab Enable cryptographic extensions. This implies @code{fp}, @code{simd}, @code{aes} and @code{sha2}.
162 @item @code{aes} @tab ARMv8-A @tab No
163 @tab Enable the AES cryptographic extensions. This implies @code{fp} and @code{simd}.
164 @item @code{sha2} @tab ARMv8-A @tab No
165 @tab Enable the SHA2 cryptographic extensions. This implies @code{fp} and @code{simd}.
166 @item @code{sha3} @tab ARMv8.2-A @tab No
167 @tab Enable the ARMv8.2-A SHA2 and SHA3 cryptographic extensions. This implies @code{fp}, @code{simd} and @code{sha2}.
168 @item @code{sm4} @tab ARMv8.2-A @tab No
169 @tab Enable the ARMv8.2-A SM3 and SM4 cryptographic extensions. This implies @code{fp} and @code{simd}.
170 @item @code{fp} @tab ARMv8-A @tab ARMv8-A or later
171 @tab Enable floating-point extensions.
172 @item @code{fp16} @tab ARMv8.2-A @tab ARMv8.2-A or later
173 @tab Enable ARMv8.2 16-bit floating-point support. This implies
175 @item @code{lor} @tab ARMv8-A @tab ARMv8.1-A or later
176 @tab Enable Limited Ordering Regions extensions.
177 @item @code{lse} @tab ARMv8-A @tab ARMv8.1-A or later
178 @tab Enable Large System extensions.
179 @item @code{pan} @tab ARMv8-A @tab ARMv8.1-A or later
180 @tab Enable Privileged Access Never support.
181 @item @code{profile} @tab ARMv8.2-A @tab No
182 @tab Enable statistical profiling extensions.
183 @item @code{ras} @tab ARMv8-A @tab ARMv8.2-A or later
184 @tab Enable the Reliability, Availability and Serviceability
186 @item @code{rcpc} @tab ARMv8.2-A @tab ARMv8.3-A or later
187 @tab Enable the weak release consistency extension.
188 @item @code{rdma} @tab ARMv8-A @tab ARMv8.1-A or later
189 @tab Enable ARMv8.1 Advanced SIMD extensions. This implies @code{simd}.
190 @item @code{simd} @tab ARMv8-A @tab ARMv8-A or later
191 @tab Enable Advanced SIMD extensions. This implies @code{fp}.
192 @item @code{sve} @tab ARMv8.2-A @tab No
193 @tab Enable the Scalable Vector Extensions. This implies @code{fp16},
194 @code{simd} and @code{compnum}.
195 @item @code{dotprod} @tab ARMv8.2-A @tab ARMv8.4-A or later
196 @tab Enable the Dot Product extension. This implies @code{simd}.
197 @item @code{fp16fml} @tab ARMv8.2-A @tab ARMv8.4-A or later
198 @tab Enable ARMv8.2 16-bit floating-point multiplication variant support.
199 This implies @code{fp16}.
200 @item @code{sb} @tab ARMv8-A @tab ARMv8.5-A or later
201 @tab Enable the speculation barrier instruction sb.
202 @item @code{predres} @tab ARMv8-A @tab ARMv8.5-A or later
203 @tab Enable the Execution and Data and Prediction instructions.
204 @item @code{rng} @tab ARMv8.5-A @tab No
205 @tab Enable ARMv8.5-A random number instructions.
206 @item @code{ssbs} @tab ARMv8-A @tab ARMv8.5-A or later
207 @tab Enable Speculative Store Bypassing Safe state read and write.
208 @item @code{memtag} @tab ARMv8.5-A @tab No
209 @tab Enable ARMv8.5-A Memory Tagging Extensions.
210 @item @code{tme} @tab ARMv8-A @tab No
211 @tab Enable Transactional Memory Extensions.
212 @item @code{sve2} @tab ARMv8-A @tab No
213 @tab Enable the SVE2 Extension.
214 @item @code{sve2-bitperm} @tab ARMv8-A @tab No
215 @tab Enable SVE2 BITPERM Extension.
216 @item @code{sve2-sm4} @tab ARMv8-A @tab No
217 @tab Enable SVE2 SM4 Extension.
218 @item @code{sve2-aes} @tab ARMv8-A @tab No
219 @tab Enable SVE2 AES Extension. This also enables the .Q->.B form of the
220 @code{pmullt} and @code{pmullb} instructions.
221 @item @code{sve2-sha3} @tab ARMv8-A @tab No
222 @tab Enable SVE2 SHA3 Extension.
228 * AArch64-Chars:: Special Characters
229 * AArch64-Regs:: Register Names
230 * AArch64-Relocations:: Relocations
234 @subsection Special Characters
236 @cindex line comment character, AArch64
237 @cindex AArch64 line comment character
238 The presence of a @samp{//} on a line indicates the start of a comment
239 that extends to the end of the current line. If a @samp{#} appears as
240 the first character of a line, the whole line is treated as a comment.
242 @cindex line separator, AArch64
243 @cindex statement separator, AArch64
244 @cindex AArch64 line separator
245 The @samp{;} character can be used instead of a newline to separate
248 @cindex immediate character, AArch64
249 @cindex AArch64 immediate character
250 The @samp{#} can be optionally used to indicate immediate operands.
253 @subsection Register Names
255 @cindex AArch64 register names
256 @cindex register names, AArch64
257 Please refer to the section @samp{4.4 Register Names} of
258 @samp{ARMv8 Instruction Set Overview}, which is available at
259 @uref{http://infocenter.arm.com}.
261 @node AArch64-Relocations
262 @subsection Relocations
264 @cindex relocations, AArch64
265 @cindex AArch64 relocations
266 @cindex MOVN, MOVZ and MOVK group relocations, AArch64
267 Relocations for @samp{MOVZ} and @samp{MOVK} instructions can be generated
268 by prefixing the label with @samp{#:abs_g2:} etc.
269 For example to load the 48-bit absolute address of @var{foo} into x0:
272 movz x0, #:abs_g2:foo // bits 32-47, overflow check
273 movk x0, #:abs_g1_nc:foo // bits 16-31, no overflow check
274 movk x0, #:abs_g0_nc:foo // bits 0-15, no overflow check
277 @cindex ADRP, ADD, LDR/STR group relocations, AArch64
278 Relocations for @samp{ADRP}, and @samp{ADD}, @samp{LDR} or @samp{STR}
279 instructions can be generated by prefixing the label with
280 @samp{:pg_hi21:} and @samp{#:lo12:} respectively.
282 For example to use 33-bit (+/-4GB) pc-relative addressing to
283 load the address of @var{foo} into x0:
286 adrp x0, :pg_hi21:foo
287 add x0, x0, #:lo12:foo
290 Or to load the value of @var{foo} into x0:
293 adrp x0, :pg_hi21:foo
294 ldr x0, [x0, #:lo12:foo]
297 Note that @samp{:pg_hi21:} is optional.
306 adrp x0, :pg_hi21:foo
309 @node AArch64 Floating Point
310 @section Floating Point
312 @cindex floating point, AArch64 (@sc{ieee})
313 @cindex AArch64 floating point (@sc{ieee})
314 The AArch64 architecture uses @sc{ieee} floating-point numbers.
316 @node AArch64 Directives
317 @section AArch64 Machine Directives
319 @cindex machine directives, AArch64
320 @cindex AArch64 machine directives
323 @c AAAAAAAAAAAAAAAAAAAAAAAAA
325 @cindex @code{.arch} directive, AArch64
326 @item .arch @var{name}
327 Select the target architecture. Valid values for @var{name} are the same as
328 for the @option{-march} command-line option.
330 Specifying @code{.arch} clears any previously selected architecture
333 @cindex @code{.arch_extension} directive, AArch64
334 @item .arch_extension @var{name}
335 Add or remove an architecture extension to the target architecture. Valid
336 values for @var{name} are the same as those accepted as architectural
337 extensions by the @option{-mcpu} command-line option.
339 @code{.arch_extension} may be used multiple times to add or remove extensions
340 incrementally to the architecture being compiled for.
342 @c BBBBBBBBBBBBBBBBBBBBBBBBBB
344 @cindex @code{.bss} directive, AArch64
346 This directive switches to the @code{.bss} section.
348 @c CCCCCCCCCCCCCCCCCCCCCCCCCC
350 @cindex @code{.cpu} directive, AArch64
351 @item .cpu @var{name}
352 Set the target processor. Valid values for @var{name} are the same as
353 those accepted by the @option{-mcpu=} command-line option.
355 @c DDDDDDDDDDDDDDDDDDDDDDDDDD
357 @cindex @code{.dword} directive, AArch64
358 @item .dword @var{expressions}
359 The @code{.dword} directive produces 64 bit values.
361 @c EEEEEEEEEEEEEEEEEEEEEEEEEE
363 @cindex @code{.even} directive, AArch64
365 The @code{.even} directive aligns the output on the next even byte
368 @c FFFFFFFFFFFFFFFFFFFFFFFFFF
370 @cindex @code{.float16} directive, AArch64
371 @item .float16 @var{value [,...,value_n]}
372 Place the half precision floating point representation of one or more
373 floating-point values into the current section.
374 The format used to encode the floating point values is always the
375 IEEE 754-2008 half precision floating point format.
377 @c GGGGGGGGGGGGGGGGGGGGGGGGGG
378 @c HHHHHHHHHHHHHHHHHHHHHHHHHH
379 @c IIIIIIIIIIIIIIIIIIIIIIIIII
381 @cindex @code{.inst} directive, AArch64
382 @item .inst @var{expressions}
383 Inserts the expressions into the output as if they were instructions,
386 @c JJJJJJJJJJJJJJJJJJJJJJJJJJ
387 @c KKKKKKKKKKKKKKKKKKKKKKKKKK
388 @c LLLLLLLLLLLLLLLLLLLLLLLLLL
390 @cindex @code{.ltorg} directive, AArch64
392 This directive causes the current contents of the literal pool to be
393 dumped into the current section (which is assumed to be the .text
394 section) at the current location (aligned to a word boundary).
395 GAS maintains a separate literal pool for each section and each
396 sub-section. The @code{.ltorg} directive will only affect the literal
397 pool of the current section and sub-section. At the end of assembly
398 all remaining, un-empty literal pools will automatically be dumped.
400 Note - older versions of GAS would dump the current literal
401 pool any time a section change occurred. This is no longer done, since
402 it prevents accurate control of the placement of literal pools.
404 @c MMMMMMMMMMMMMMMMMMMMMMMMMM
406 @c NNNNNNNNNNNNNNNNNNNNNNNNNN
407 @c OOOOOOOOOOOOOOOOOOOOOOOOOO
409 @c PPPPPPPPPPPPPPPPPPPPPPPPPP
411 @cindex @code{.pool} directive, AArch64
413 This is a synonym for .ltorg.
415 @c QQQQQQQQQQQQQQQQQQQQQQQQQQ
416 @c RRRRRRRRRRRRRRRRRRRRRRRRRR
418 @cindex @code{.req} directive, AArch64
419 @item @var{name} .req @var{register name}
420 This creates an alias for @var{register name} called @var{name}. For
427 ip0, ip1, lr and fp are automatically defined to
428 alias to X16, X17, X30 and X29 respectively.
430 @c SSSSSSSSSSSSSSSSSSSSSSSSSS
432 @c TTTTTTTTTTTTTTTTTTTTTTTTTT
434 @cindex @code{.tlsdescadd} directive, AArch64
435 @item @code{.tlsdescadd}
436 Emits a TLSDESC_ADD reloc on the next instruction.
438 @cindex @code{.tlsdesccall} directive, AArch64
439 @item @code{.tlsdesccall}
440 Emits a TLSDESC_CALL reloc on the next instruction.
442 @cindex @code{.tlsdescldr} directive, AArch64
443 @item @code{.tlsdescldr}
444 Emits a TLSDESC_LDR reloc on the next instruction.
446 @c UUUUUUUUUUUUUUUUUUUUUUUUUU
448 @cindex @code{.unreq} directive, AArch64
449 @item .unreq @var{alias-name}
450 This undefines a register alias which was previously defined using the
451 @code{req} directive. For example:
458 An error occurs if the name is undefined. Note - this pseudo op can
459 be used to delete builtin in register name aliases (eg 'w0'). This
460 should only be done if it is really necessary.
462 @c VVVVVVVVVVVVVVVVVVVVVVVVVV
464 @cindex @code{.variant_pcs} directive, AArch64
465 @item .variant_pcs @var{symbol}
466 This directive marks @var{symbol} referencing a function that may
467 follow a variant procedure call standard with different register
468 usage convention from the base procedure call standard.
470 @c WWWWWWWWWWWWWWWWWWWWWWWWWW
471 @c XXXXXXXXXXXXXXXXXXXXXXXXXX
473 @cindex @code{.xword} directive, AArch64
474 @item .xword @var{expressions}
475 The @code{.xword} directive produces 64 bit values. This is the same
476 as the @code{.dword} directive.
478 @c YYYYYYYYYYYYYYYYYYYYYYYYYY
479 @c ZZZZZZZZZZZZZZZZZZZZZZZZZZ
481 @cindex @code{.cfi_b_key_frame} directive, AArch64
482 @item @code{.cfi_b_key_frame}
483 The @code{.cfi_b_key_frame} directive inserts a 'B' character into the CIE
484 corresponding to the current frame's FDE, meaning that its return address has
485 been signed with the B-key. If two frames are signed with differing keys then
486 they will not share the same CIE. This information is intended to be used by
487 the stack unwinder in order to properly authenticate return addresses.
491 @node AArch64 Opcodes
494 @cindex AArch64 opcodes
495 @cindex opcodes for AArch64
496 GAS implements all the standard AArch64 opcodes. It also
497 implements several pseudo opcodes, including several synthetic load
502 @cindex @code{LDR reg,=<expr>} pseudo op, AArch64
505 ldr <register> , =<expression>
508 The constant expression will be placed into the nearest literal pool (if it not
509 already there) and a PC-relative LDR instruction will be generated.
513 For more information on the AArch64 instruction set and assembly language
514 notation, see @samp{ARMv8 Instruction Set Overview} available at
515 @uref{http://infocenter.arm.com}.
518 @node AArch64 Mapping Symbols
519 @section Mapping Symbols
521 The AArch64 ELF specification requires that special symbols be inserted
522 into object files to mark certain features:
528 At the start of a region of code containing AArch64 instructions.
532 At the start of a region of data.