contrib/binutils-2.25/gas/doc/c-aarch64.texi

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