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