| 1 | @c Copyright (C) 2009-2015 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. |
| 5 | @c man end |
| 6 | |
| 7 | @ifset GENERIC |
| 8 | @page |
| 9 | @node AArch64-Dependent |
| 10 | @chapter AArch64 Dependent Features |
| 11 | @end ifset |
| 12 | |
| 13 | @ifclear GENERIC |
| 14 | @node Machine Dependencies |
| 15 | @chapter AArch64 Dependent Features |
| 16 | @end ifclear |
| 17 | |
| 18 | @cindex AArch64 support |
| 19 | @menu |
| 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 |
| 27 | @end menu |
| 28 | |
| 29 | @node AArch64 Options |
| 30 | @section Options |
| 31 | @cindex AArch64 options (none) |
| 32 | @cindex options for AArch64 (none) |
| 33 | |
| 34 | @c man begin OPTIONS |
| 35 | @table @gcctabopt |
| 36 | |
| 37 | @cindex @option{-EB} command line option, AArch64 |
| 38 | @item -EB |
| 39 | This option specifies that the output generated by the assembler should |
| 40 | be marked as being encoded for a big-endian processor. |
| 41 | |
| 42 | @cindex @option{-EL} command line option, AArch64 |
| 43 | @item -EL |
| 44 | This option specifies that the output generated by the assembler should |
| 45 | be marked as being encoded for a little-endian processor. |
| 46 | |
| 47 | @cindex @option{-mabi=} command line option, AArch64 |
| 48 | @item -mabi=@var{abi} |
| 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}. |
| 52 | |
| 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: |
| 58 | @code{cortex-a35}, |
| 59 | @code{cortex-a53}, |
| 60 | @code{cortex-a57}, |
| 61 | @code{cortex-a72}, |
| 62 | @code{exynos-m1}, |
| 63 | @code{qdf24xx}, |
| 64 | @code{thunderx}, |
| 65 | @code{xgene1} |
| 66 | and |
| 67 | @code{xgene2}. |
| 68 | The special name @code{all} may be used to allow the assembler to accept |
| 69 | instructions valid for any supported processor, including all optional |
| 70 | extensions. |
| 71 | |
| 72 | In addition to the basic instruction set, the assembler can be told to |
| 73 | accept, or restrict, various extension mnemonics that extend the |
| 74 | processor. @xref{AArch64 Extensions}. |
| 75 | |
| 76 | If some implementations of a particular processor can have an |
| 77 | extension, then then those extensions are automatically enabled. |
| 78 | Consequently, you will not normally have to specify any additional |
| 79 | extensions. |
| 80 | |
| 81 | @cindex @option{-march=} command line option, AArch64 |
| 82 | @item -march=@var{architecture}[+@var{extension}@dots{}] |
| 83 | This option specifies the target architecture. The assembler will |
| 84 | issue an error message if an attempt is made to assemble an |
| 85 | instruction which will not execute on the target architecture. The |
| 86 | following architecture names are recognized: @code{armv8-a} and |
| 87 | @code{armv8.1-a}. |
| 88 | |
| 89 | If both @option{-mcpu} and @option{-march} are specified, the |
| 90 | assembler will use the setting for @option{-mcpu}. If neither are |
| 91 | specified, the assembler will default to @option{-mcpu=all}. |
| 92 | |
| 93 | The architecture option can be extended with the same instruction set |
| 94 | extension options as the @option{-mcpu} option. Unlike |
| 95 | @option{-mcpu}, extensions are not always enabled by default, |
| 96 | @xref{AArch64 Extensions}. |
| 97 | |
| 98 | @cindex @code{-mverbose-error} command line option, AArch64 |
| 99 | @item -mverbose-error |
| 100 | This option enables verbose error messages for AArch64 gas. This option |
| 101 | is enabled by default. |
| 102 | |
| 103 | @cindex @code{-mno-verbose-error} command line option, AArch64 |
| 104 | @item -mno-verbose-error |
| 105 | This option disables verbose error messages in AArch64 gas. |
| 106 | |
| 107 | @end table |
| 108 | @c man end |
| 109 | |
| 110 | @node AArch64 Extensions |
| 111 | @section Architecture Extensions |
| 112 | |
| 113 | The table below lists the permitted architecture extensions that are |
| 114 | supported by the assembler and the conditions under which they are |
| 115 | automatically enabled. |
| 116 | |
| 117 | Multiple extensions may be specified, separated by a @code{+}. |
| 118 | Extension mnemonics may also be removed from those the assembler |
| 119 | accepts. This is done by prepending @code{no} to the option that adds |
| 120 | the extension. Extensions that are removed must be listed after all |
| 121 | extensions that have been added. |
| 122 | |
| 123 | Enabling an extension that requires other extensions will |
| 124 | automatically cause those extensions to be enabled. Similarly, |
| 125 | disabling an extension that is required by other extensions will |
| 126 | automatically cause those extensions to be disabled. |
| 127 | |
| 128 | @multitable @columnfractions .12 .17 .17 .54 |
| 129 | @headitem Extension @tab Minimum Architecture @tab Enabled by default |
| 130 | @tab Description |
| 131 | @item @code{crc} @tab ARMv8-A @tab No |
| 132 | @tab Enable CRC instructions. |
| 133 | @item @code{crypto} @tab ARMv8-A @tab No |
| 134 | @tab Enable cryptographic extensions. This implies @code{fp} and @code{simd}. |
| 135 | @item @code{fp} @tab ARMv8-A @tab ARMv8-A or later |
| 136 | @tab Enable floating-point extensions. |
| 137 | @item @code{simd} @tab ARMv8-A @tab ARMv8-A or later |
| 138 | @tab Enable Advanced SIMD extensions. This implies @code{fp}. |
| 139 | @item @code{pan} @tab ARMv8-A @tab ARMv8-A or later |
| 140 | @tab Enable Privileged Access Never support. |
| 141 | @item @code{lor} @tab ARMv8-A @tab ARMv8-A or later |
| 142 | @tab Enable Limited Ordering Regions extensions. |
| 143 | @item @code{rdma} @tab ARMv8-A @tab ARMv8-A or later |
| 144 | @tab Enable ARMv8.1 Advanced SIMD extensions. This implies @code{simd}. |
| 145 | @end multitable |
| 146 | |
| 147 | @node AArch64 Syntax |
| 148 | @section Syntax |
| 149 | @menu |
| 150 | * AArch64-Chars:: Special Characters |
| 151 | * AArch64-Regs:: Register Names |
| 152 | * AArch64-Relocations:: Relocations |
| 153 | @end menu |
| 154 | |
| 155 | @node AArch64-Chars |
| 156 | @subsection Special Characters |
| 157 | |
| 158 | @cindex line comment character, AArch64 |
| 159 | @cindex AArch64 line comment character |
| 160 | The presence of a @samp{//} on a line indicates the start of a comment |
| 161 | that extends to the end of the current line. If a @samp{#} appears as |
| 162 | the first character of a line, the whole line is treated as a comment. |
| 163 | |
| 164 | @cindex line separator, AArch64 |
| 165 | @cindex statement separator, AArch64 |
| 166 | @cindex AArch64 line separator |
| 167 | The @samp{;} character can be used instead of a newline to separate |
| 168 | statements. |
| 169 | |
| 170 | @cindex immediate character, AArch64 |
| 171 | @cindex AArch64 immediate character |
| 172 | The @samp{#} can be optionally used to indicate immediate operands. |
| 173 | |
| 174 | @node AArch64-Regs |
| 175 | @subsection Register Names |
| 176 | |
| 177 | @cindex AArch64 register names |
| 178 | @cindex register names, AArch64 |
| 179 | Please refer to the section @samp{4.4 Register Names} of |
| 180 | @samp{ARMv8 Instruction Set Overview}, which is available at |
| 181 | @uref{http://infocenter.arm.com}. |
| 182 | |
| 183 | @node AArch64-Relocations |
| 184 | @subsection Relocations |
| 185 | |
| 186 | @cindex relocations, AArch64 |
| 187 | @cindex AArch64 relocations |
| 188 | @cindex MOVN, MOVZ and MOVK group relocations, AArch64 |
| 189 | Relocations for @samp{MOVZ} and @samp{MOVK} instructions can be generated |
| 190 | by prefixing the label with @samp{#:abs_g2:} etc. |
| 191 | For example to load the 48-bit absolute address of @var{foo} into x0: |
| 192 | |
| 193 | @smallexample |
| 194 | movz x0, #:abs_g2:foo // bits 32-47, overflow check |
| 195 | movk x0, #:abs_g1_nc:foo // bits 16-31, no overflow check |
| 196 | movk x0, #:abs_g0_nc:foo // bits 0-15, no overflow check |
| 197 | @end smallexample |
| 198 | |
| 199 | @cindex ADRP, ADD, LDR/STR group relocations, AArch64 |
| 200 | Relocations for @samp{ADRP}, and @samp{ADD}, @samp{LDR} or @samp{STR} |
| 201 | instructions can be generated by prefixing the label with |
| 202 | @samp{:pg_hi21:} and @samp{#:lo12:} respectively. |
| 203 | |
| 204 | For example to use 33-bit (+/-4GB) pc-relative addressing to |
| 205 | load the address of @var{foo} into x0: |
| 206 | |
| 207 | @smallexample |
| 208 | adrp x0, :pg_hi21:foo |
| 209 | add x0, x0, #:lo12:foo |
| 210 | @end smallexample |
| 211 | |
| 212 | Or to load the value of @var{foo} into x0: |
| 213 | |
| 214 | @smallexample |
| 215 | adrp x0, :pg_hi21:foo |
| 216 | ldr x0, [x0, #:lo12:foo] |
| 217 | @end smallexample |
| 218 | |
| 219 | Note that @samp{:pg_hi21:} is optional. |
| 220 | |
| 221 | @smallexample |
| 222 | adrp x0, foo |
| 223 | @end smallexample |
| 224 | |
| 225 | is equivalent to |
| 226 | |
| 227 | @smallexample |
| 228 | adrp x0, :pg_hi21:foo |
| 229 | @end smallexample |
| 230 | |
| 231 | @node AArch64 Floating Point |
| 232 | @section Floating Point |
| 233 | |
| 234 | @cindex floating point, AArch64 (@sc{ieee}) |
| 235 | @cindex AArch64 floating point (@sc{ieee}) |
| 236 | The AArch64 architecture uses @sc{ieee} floating-point numbers. |
| 237 | |
| 238 | @node AArch64 Directives |
| 239 | @section AArch64 Machine Directives |
| 240 | |
| 241 | @cindex machine directives, AArch64 |
| 242 | @cindex AArch64 machine directives |
| 243 | @table @code |
| 244 | |
| 245 | @c AAAAAAAAAAAAAAAAAAAAAAAAA |
| 246 | |
| 247 | @cindex @code{.arch} directive, AArch64 |
| 248 | @item .arch @var{name} |
| 249 | Select the target architecture. Valid values for @var{name} are the same as |
| 250 | for the @option{-march} commandline option. |
| 251 | |
| 252 | Specifying @code{.arch} clears any previously selected architecture |
| 253 | extensions. |
| 254 | |
| 255 | @cindex @code{.arch_extension} directive, AArch64 |
| 256 | @item .arch_extension @var{name} |
| 257 | Add or remove an architecture extension to the target architecture. Valid |
| 258 | values for @var{name} are the same as those accepted as architectural |
| 259 | extensions by the @option{-mcpu} commandline option. |
| 260 | |
| 261 | @code{.arch_extension} may be used multiple times to add or remove extensions |
| 262 | incrementally to the architecture being compiled for. |
| 263 | |
| 264 | @c BBBBBBBBBBBBBBBBBBBBBBBBBB |
| 265 | |
| 266 | @cindex @code{.bss} directive, AArch64 |
| 267 | @item .bss |
| 268 | This directive switches to the @code{.bss} section. |
| 269 | |
| 270 | @c CCCCCCCCCCCCCCCCCCCCCCCCCC |
| 271 | @c DDDDDDDDDDDDDDDDDDDDDDDDDD |
| 272 | @c EEEEEEEEEEEEEEEEEEEEEEEEEE |
| 273 | @c FFFFFFFFFFFFFFFFFFFFFFFFFF |
| 274 | @c GGGGGGGGGGGGGGGGGGGGGGGGGG |
| 275 | @c HHHHHHHHHHHHHHHHHHHHHHHHHH |
| 276 | @c IIIIIIIIIIIIIIIIIIIIIIIIII |
| 277 | @c JJJJJJJJJJJJJJJJJJJJJJJJJJ |
| 278 | @c KKKKKKKKKKKKKKKKKKKKKKKKKK |
| 279 | @c LLLLLLLLLLLLLLLLLLLLLLLLLL |
| 280 | |
| 281 | @cindex @code{.ltorg} directive, AArch64 |
| 282 | @item .ltorg |
| 283 | This directive causes the current contents of the literal pool to be |
| 284 | dumped into the current section (which is assumed to be the .text |
| 285 | section) at the current location (aligned to a word boundary). |
| 286 | GAS maintains a separate literal pool for each section and each |
| 287 | sub-section. The @code{.ltorg} directive will only affect the literal |
| 288 | pool of the current section and sub-section. At the end of assembly |
| 289 | all remaining, un-empty literal pools will automatically be dumped. |
| 290 | |
| 291 | Note - older versions of GAS would dump the current literal |
| 292 | pool any time a section change occurred. This is no longer done, since |
| 293 | it prevents accurate control of the placement of literal pools. |
| 294 | |
| 295 | @c MMMMMMMMMMMMMMMMMMMMMMMMMM |
| 296 | |
| 297 | @c NNNNNNNNNNNNNNNNNNNNNNNNNN |
| 298 | @c OOOOOOOOOOOOOOOOOOOOOOOOOO |
| 299 | |
| 300 | @c PPPPPPPPPPPPPPPPPPPPPPPPPP |
| 301 | |
| 302 | @cindex @code{.pool} directive, AArch64 |
| 303 | @item .pool |
| 304 | This is a synonym for .ltorg. |
| 305 | |
| 306 | @c QQQQQQQQQQQQQQQQQQQQQQQQQQ |
| 307 | @c RRRRRRRRRRRRRRRRRRRRRRRRRR |
| 308 | |
| 309 | @cindex @code{.req} directive, AArch64 |
| 310 | @item @var{name} .req @var{register name} |
| 311 | This creates an alias for @var{register name} called @var{name}. For |
| 312 | example: |
| 313 | |
| 314 | @smallexample |
| 315 | foo .req w0 |
| 316 | @end smallexample |
| 317 | |
| 318 | @c SSSSSSSSSSSSSSSSSSSSSSSSSS |
| 319 | |
| 320 | @c TTTTTTTTTTTTTTTTTTTTTTTTTT |
| 321 | |
| 322 | @c UUUUUUUUUUUUUUUUUUUUUUUUUU |
| 323 | |
| 324 | @cindex @code{.unreq} directive, AArch64 |
| 325 | @item .unreq @var{alias-name} |
| 326 | This undefines a register alias which was previously defined using the |
| 327 | @code{req} directive. For example: |
| 328 | |
| 329 | @smallexample |
| 330 | foo .req w0 |
| 331 | .unreq foo |
| 332 | @end smallexample |
| 333 | |
| 334 | An error occurs if the name is undefined. Note - this pseudo op can |
| 335 | be used to delete builtin in register name aliases (eg 'w0'). This |
| 336 | should only be done if it is really necessary. |
| 337 | |
| 338 | @c VVVVVVVVVVVVVVVVVVVVVVVVVV |
| 339 | |
| 340 | @c WWWWWWWWWWWWWWWWWWWWWWWWWW |
| 341 | @c XXXXXXXXXXXXXXXXXXXXXXXXXX |
| 342 | @c YYYYYYYYYYYYYYYYYYYYYYYYYY |
| 343 | @c ZZZZZZZZZZZZZZZZZZZZZZZZZZ |
| 344 | |
| 345 | @cindex @code{.xword} directive, AArch64 |
| 346 | @item .xword |
| 347 | The @code{.xword} directive produces 64 bit values. |
| 348 | |
| 349 | @end table |
| 350 | |
| 351 | @node AArch64 Opcodes |
| 352 | @section Opcodes |
| 353 | |
| 354 | @cindex AArch64 opcodes |
| 355 | @cindex opcodes for AArch64 |
| 356 | GAS implements all the standard AArch64 opcodes. It also |
| 357 | implements several pseudo opcodes, including several synthetic load |
| 358 | instructions. |
| 359 | |
| 360 | @table @code |
| 361 | |
| 362 | @cindex @code{LDR reg,=<expr>} pseudo op, AArch64 |
| 363 | @item LDR = |
| 364 | @smallexample |
| 365 | ldr <register> , =<expression> |
| 366 | @end smallexample |
| 367 | |
| 368 | The constant expression will be placed into the nearest literal pool (if it not |
| 369 | already there) and a PC-relative LDR instruction will be generated. |
| 370 | |
| 371 | @end table |
| 372 | |
| 373 | For more information on the AArch64 instruction set and assembly language |
| 374 | notation, see @samp{ARMv8 Instruction Set Overview} available at |
| 375 | @uref{http://infocenter.arm.com}. |
| 376 | |
| 377 | |
| 378 | @node AArch64 Mapping Symbols |
| 379 | @section Mapping Symbols |
| 380 | |
| 381 | The AArch64 ELF specification requires that special symbols be inserted |
| 382 | into object files to mark certain features: |
| 383 | |
| 384 | @table @code |
| 385 | |
| 386 | @cindex @code{$x} |
| 387 | @item $x |
| 388 | At the start of a region of code containing AArch64 instructions. |
| 389 | |
| 390 | @cindex @code{$d} |
| 391 | @item $d |
| 392 | At the start of a region of data. |
| 393 | |
| 394 | @end table |