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