gas/doc/c-arm.texi

   1 @c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2003
   2 @c Free Software Foundation, Inc.
   3 @c This is part of the GAS manual.
   4 @c For copying conditions, see the file as.texinfo.
   5
   6 @ifset GENERIC
   7 @page
   8 @node ARM-Dependent
   9 @chapter ARM Dependent Features
  10 @end ifset
  11
  12 @ifclear GENERIC
  13 @node Machine Dependencies
  14 @chapter ARM Dependent Features
  15 @end ifclear
  16
  17 @cindex ARM support
  18 @cindex Thumb support
  19 @menu
  20 * ARM Options::              Options
  21 * ARM Syntax::               Syntax
  22 * ARM Floating Point::       Floating Point
  23 * ARM Directives::           ARM Machine Directives
  24 * ARM Opcodes::              Opcodes
  25 * ARM Mapping Symbols::      Mapping Symbols
  26 @end menu
  27
  28 @node ARM Options
  29 @section Options
  30 @cindex ARM options (none)
  31 @cindex options for ARM (none)
  32
  33 @table @code
  34
  35 @cindex @code{-mcpu=} command line option, ARM
  36 @item -mcpu=@var{processor}[+@var{extension}@dots{}]
  37 This option specifies the target processor.  The assembler will issue an
  38 error message if an attempt is made to assemble an instruction which
  39 will not execute on the target processor.  The following processor names are
  40 recognized:
  41 @code{arm1},
  42 @code{arm2},
  43 @code{arm250},
  44 @code{arm3},
  45 @code{arm6},
  46 @code{arm60},
  47 @code{arm600},
  48 @code{arm610},
  49 @code{arm620},
  50 @code{arm7},
  51 @code{arm7m},
  52 @code{arm7d},
  53 @code{arm7dm},
  54 @code{arm7di},
  55 @code{arm7dmi},
  56 @code{arm70},
  57 @code{arm700},
  58 @code{arm700i},
  59 @code{arm710},
  60 @code{arm710t},
  61 @code{arm720},
  62 @code{arm720t},
  63 @code{arm740t},
  64 @code{arm710c},
  65 @code{arm7100},
  66 @code{arm7500},
  67 @code{arm7500fe},
  68 @code{arm7t},
  69 @code{arm7tdmi},
  70 @code{arm7tdmi-s},
  71 @code{arm8},
  72 @code{arm810},
  73 @code{strongarm},
  74 @code{strongarm1},
  75 @code{strongarm110},
  76 @code{strongarm1100},
  77 @code{strongarm1110},
  78 @code{arm9},
  79 @code{arm920},
  80 @code{arm920t},
  81 @code{arm922t},
  82 @code{arm940t},
  83 @code{arm9tdmi},
  84 @code{arm9e},
  85 @code{arm926e},
  86 @code{arm926ej-s},
  87 @code{arm946e-r0},
  88 @code{arm946e},
  89 @code{arm966e-r0},
  90 @code{arm966e},
  91 @code{arm10t},
  92 @code{arm10e},
  93 @code{arm1020},
  94 @code{arm1020t},
  95 @code{arm1020e},
  96 @code{arm1026ej-s},
  97 @code{arm1136j-s},
  98 @code{arm1136jf-s},
  99 @code{ep9312} (ARM920 with Cirrus Maverick coprocessor),
 100 @code{i80200} (Intel XScale processor)
 101 @code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor)
 102 and
 103 @code{xscale}.
 104 The special name @code{all} may be used to allow the
 105 assembler to accept instructions valid for any ARM processor.
 106
 107 In addition to the basic instruction set, the assembler can be told to
 108 accept various extension mnemonics that extend the processor using the
 109 co-processor instruction space.  For example, @code{-mcpu=arm920+maverick}
 110 is equivalent to specifying @code{-mcpu=ep9312}.  The following extensions
 111 are currently supported:
 112 @code{+maverick}
 113 @code{+iwmmxt}
 114 and
 115 @code{+xscale}.
 116
 117 @cindex @code{-march=} command line option, ARM
 118 @item -march=@var{architecture}[+@var{extension}@dots{}]
 119 This option specifies the target architecture.  The assembler will issue
 120 an error message if an attempt is made to assemble an instruction which
 121 will not execute on the target architecture.  The following architecture
 122 names are recognized:
 123 @code{armv1},
 124 @code{armv2},
 125 @code{armv2a},
 126 @code{armv2s},
 127 @code{armv3},
 128 @code{armv3m},
 129 @code{armv4},
 130 @code{armv4xm},
 131 @code{armv4t},
 132 @code{armv4txm},
 133 @code{armv5},
 134 @code{armv5t},
 135 @code{armv5txm},
 136 @code{armv5te},
 137 @code{armv5texp},
 138 @code{armv6},
 139 @code{armv6j},
 140 @code{iwmmxt}
 141 and
 142 @code{xscale}.
 143 If both @code{-mcpu} and
 144 @code{-march} are specified, the assembler will use
 145 the setting for @code{-mcpu}.
 146
 147 The architecture option can be extended with the same instruction set
 148 extension options as the @code{-mcpu} option.
 149
 150 @cindex @code{-mfpu=} command line option, ARM
 151 @item -mfpu=@var{floating-point-format}
 152
 153 This option specifies the floating point format to assemble for.  The
 154 assembler will issue an error message if an attempt is made to assemble
 155 an instruction which will not execute on the target floating point unit.
 156 The following format options are recognized:
 157 @code{softfpa},
 158 @code{fpe},
 159 @code{fpe2},
 160 @code{fpe3},
 161 @code{fpa},
 162 @code{fpa10},
 163 @code{fpa11},
 164 @code{arm7500fe},
 165 @code{softvfp},
 166 @code{softvfp+vfp},
 167 @code{vfp},
 168 @code{vfp10},
 169 @code{vfp10-r0},
 170 @code{vfp9},
 171 @code{vfpxd},
 172 @code{arm1020t},
 173 @code{arm1020e},
 174 @code{arm1136jf-s}
 175 and
 176 @code{maverick}.
 177
 178 In addition to determining which instructions are assembled, this option
 179 also affects the way in which the @code{.double} assembler directive behaves
 180 when assembling little-endian code.
 181
 182 The default is dependent on the processor selected.  For Architecture 5 or
 183 later, the default is to assembler for VFP instructions; for earlier
 184 architectures the default is to assemble for FPA instructions.
 185
 186 @cindex @code{-mthumb} command line option, ARM
 187 @item -mthumb
 188 This option specifies that the assembler should start assembling Thumb
 189 instructions; that is, it should behave as though the file starts with a
 190 @code{.code 16} directive.
 191
 192 @cindex @code{-mthumb-interwork} command line option, ARM
 193 @item -mthumb-interwork
 194 This option specifies that the output generated by the assembler should
 195 be marked as supporting interworking.
 196
 197 @cindex @code{-mapcs} command line option, ARM
 198 @item -mapcs @code{[26|32]}
 199 This option specifies that the output generated by the assembler should
 200 be marked as supporting the indicated version of the Arm Procedure.
 201 Calling Standard.
 202
 203 @cindex @code{-matpcs} command line option, ARM
 204 @item -matpcs
 205 This option specifies that the output generated by the assembler should
 206 be marked as supporting the Arm/Thumb Procedure Calling Standard.  If
 207 enabled this option will cause the assembler to create an empty
 208 debugging section in the object file called .arm.atpcs.  Debuggers can
 209 use this to determine the ABI being used by.
 210
 211 @cindex @code{-mapcs-float} command line option, ARM
 212 @item -mapcs-float
 213 This indicates the floating point variant of the APCS should be
 214 used.  In this variant floating point arguments are passed in FP
 215 registers rather than integer registers.
 216
 217 @cindex @code{-mapcs-reentrant} command line option, ARM
 218 @item -mapcs-reentrant
 219 This indicates that the reentrant variant of the APCS should be used.
 220 This variant supports position independent code.
 221
 222 @cindex @code{-mfloat-abi=} command line option, ARM
 223 @item -mfloat-abi=@var{abi}
 224 This option specifies that the output generated by the assembler should be
 225 marked as using specified floating point ABI.
 226 The following values are recognized:
 227 @code{soft},
 228 @code{softfp}
 229 and
 230 @code{hard}.
 231
 232 @cindex @code{-eabi=} command line option, ARM
 233 @item -meabi=@var{ver}
 234 This option specifies which EABI version the produced object files should
 235 conform to.
 236 The following values are recognised:
 237 @code{gnu}
 238 and
 239 @code{3}.
 240
 241 @cindex @code{-EB} command line option, ARM
 242 @item -EB
 243 This option specifies that the output generated by the assembler should
 244 be marked as being encoded for a big-endian processor.
 245
 246 @cindex @code{-EL} command line option, ARM
 247 @item -EL
 248 This option specifies that the output generated by the assembler should
 249 be marked as being encoded for a little-endian processor.
 250
 251 @cindex @code{-k} command line option, ARM
 252 @cindex PIC code generation for ARM
 253 @item -k
 254 This option specifies that the output of the assembler should be marked
 255 as position-independent code (PIC).
 256
 257 @cindex @code{-moabi} command line option, ARM
 258 @item -moabi
 259 This indicates that the code should be assembled using the old ARM ELF
 260 conventions, based on a beta release release of the ARM-ELF
 261 specifications, rather than the default conventions which are based on
 262 the final release of the ARM-ELF specifications.
 263
 264 @end table
 265
 266
 267 @node ARM Syntax
 268 @section Syntax
 269 @menu
 270 * ARM-Chars::                Special Characters
 271 * ARM-Regs::                 Register Names
 272 @end menu
 273
 274 @node ARM-Chars
 275 @subsection Special Characters
 276
 277 @cindex line comment character, ARM
 278 @cindex ARM line comment character
 279 The presence of a @samp{@@} on a line indicates the start of a comment
 280 that extends to the end of the current line.  If a @samp{#} appears as
 281 the first character of a line, the whole line is treated as a comment.
 282
 283 @cindex line separator, ARM
 284 @cindex statement separator, ARM
 285 @cindex ARM line separator
 286 The @samp{;} character can be used instead of a newline to separate
 287 statements.
 288
 289 @cindex immediate character, ARM
 290 @cindex ARM immediate character
 291 Either @samp{#} or @samp{$} can be used to indicate immediate operands.
 292
 293 @cindex identifiers, ARM
 294 @cindex ARM identifiers
 295 *TODO* Explain about /data modifier on symbols.
 296
 297 @node ARM-Regs
 298 @subsection Register Names
 299
 300 @cindex ARM register names
 301 @cindex register names, ARM
 302 *TODO* Explain about ARM register naming, and the predefined names.
 303
 304 @node ARM Floating Point
 305 @section Floating Point
 306
 307 @cindex floating point, ARM (@sc{ieee})
 308 @cindex ARM floating point (@sc{ieee})
 309 The ARM family uses @sc{ieee} floating-point numbers.
 310
 311
 312
 313 @node ARM Directives
 314 @section ARM Machine Directives
 315
 316 @cindex machine directives, ARM
 317 @cindex ARM machine directives
 318 @table @code
 319
 320 @cindex @code{align} directive, ARM
 321 @item .align @var{expression} [, @var{expression}]
 322 This is the generic @var{.align} directive.  For the ARM however if the
 323 first argument is zero (ie no alignment is needed) the assembler will
 324 behave as if the argument had been 2 (ie pad to the next four byte
 325 boundary).  This is for compatibility with ARM's own assembler.
 326
 327 @cindex @code{req} directive, ARM
 328 @item @var{name} .req @var{register name}
 329 This creates an alias for @var{register name} called @var{name}.  For
 330 example:
 331
 332 @smallexample
 333         foo .req r0
 334 @end smallexample
 335
 336 @cindex @code{unreq} directive, ARM
 337 @item .unreq @var{alias-name}
 338 This undefines a register alias which was previously defined using the
 339 @code{req} directive.  For example:
 340
 341 @smallexample
 342         foo .req r0
 343         .unreq foo
 344 @end smallexample
 345
 346 An error occurs if the name is undefined.  Note - this pseudo op can
 347 be used to delete builtin in register name aliases (eg 'r0').  This
 348 should only be done if it is really necessary.
 349
 350 @cindex @code{code} directive, ARM
 351 @item .code @code{[16|32]}
 352 This directive selects the instruction set being generated. The value 16
 353 selects Thumb, with the value 32 selecting ARM.
 354
 355 @cindex @code{thumb} directive, ARM
 356 @item .thumb
 357 This performs the same action as @var{.code 16}.
 358
 359 @cindex @code{arm} directive, ARM
 360 @item .arm
 361 This performs the same action as @var{.code 32}.
 362
 363 @cindex @code{force_thumb} directive, ARM
 364 @item .force_thumb
 365 This directive forces the selection of Thumb instructions, even if the
 366 target processor does not support those instructions
 367
 368 @cindex @code{thumb_func} directive, ARM
 369 @item .thumb_func
 370 This directive specifies that the following symbol is the name of a
 371 Thumb encoded function.  This information is necessary in order to allow
 372 the assembler and linker to generate correct code for interworking
 373 between Arm and Thumb instructions and should be used even if
 374 interworking is not going to be performed.  The presence of this
 375 directive also implies @code{.thumb}
 376
 377 @cindex @code{thumb_set} directive, ARM
 378 @item .thumb_set
 379 This performs the equivalent of a @code{.set} directive in that it
 380 creates a symbol which is an alias for another symbol (possibly not yet
 381 defined).  This directive also has the added property in that it marks
 382 the aliased symbol as being a thumb function entry point, in the same
 383 way that the @code{.thumb_func} directive does.
 384
 385 @cindex @code{.ltorg} directive, ARM
 386 @item .ltorg
 387 This directive causes the current contents of the literal pool to be
 388 dumped into the current section (which is assumed to be the .text
 389 section) at the current location (aligned to a word boundary).
 390 @code{GAS} maintains a separate literal pool for each section and each
 391 sub-section.  The @code{.ltorg} directive will only affect the literal
 392 pool of the current section and sub-section.  At the end of assembly
 393 all remaining, un-empty literal pools will automatically be dumped.
 394
 395 Note - older versions of @code{GAS} would dump the current literal
 396 pool any time a section change occurred.  This is no longer done, since
 397 it prevents accurate control of the placement of literal pools.
 398
 399 @cindex @code{.pool} directive, ARM
 400 @item .pool
 401 This is a synonym for .ltorg.
 402
 403 @end table
 404
 405 @node ARM Opcodes
 406 @section Opcodes
 407
 408 @cindex ARM opcodes
 409 @cindex opcodes for ARM
 410 @code{@value{AS}} implements all the standard ARM opcodes.  It also
 411 implements several pseudo opcodes, including several synthetic load
 412 instructions.
 413
 414 @table @code
 415
 416 @cindex @code{NOP} pseudo op, ARM
 417 @item NOP
 418 @smallexample
 419   nop
 420 @end smallexample
 421
 422 This pseudo op will always evaluate to a legal ARM instruction that does
 423 nothing.  Currently it will evaluate to MOV r0, r0.
 424
 425 @cindex @code{LDR reg,=<label>} pseudo op, ARM
 426 @item LDR
 427 @smallexample
 428   ldr <register> , = <expression>
 429 @end smallexample
 430
 431 If expression evaluates to a numeric constant then a MOV or MVN
 432 instruction will be used in place of the LDR instruction, if the
 433 constant can be generated by either of these instructions.  Otherwise
 434 the constant will be placed into the nearest literal pool (if it not
 435 already there) and a PC relative LDR instruction will be generated.
 436
 437 @cindex @code{ADR reg,<label>} pseudo op, ARM
 438 @item ADR
 439 @smallexample
 440   adr <register> <label>
 441 @end smallexample
 442
 443 This instruction will load the address of @var{label} into the indicated
 444 register.  The instruction will evaluate to a PC relative ADD or SUB
 445 instruction depending upon where the label is located.  If the label is
 446 out of range, or if it is not defined in the same file (and section) as
 447 the ADR instruction, then an error will be generated.  This instruction
 448 will not make use of the literal pool.
 449
 450 @cindex @code{ADRL reg,<label>} pseudo op, ARM
 451 @item ADRL
 452 @smallexample
 453   adrl <register> <label>
 454 @end smallexample
 455
 456 This instruction will load the address of @var{label} into the indicated
 457 register.  The instruction will evaluate to one or two PC relative ADD
 458 or SUB instructions depending upon where the label is located.  If a
 459 second instruction is not needed a NOP instruction will be generated in
 460 its place, so that this instruction is always 8 bytes long.
 461
 462 If the label is out of range, or if it is not defined in the same file
 463 (and section) as the ADRL instruction, then an error will be generated.
 464 This instruction will not make use of the literal pool.
 465
 466 @end table
 467
 468 For information on the ARM or Thumb instruction sets, see @cite{ARM
 469 Software Development Toolkit Reference Manual}, Advanced RISC Machines
 470 Ltd.
 471
 472 @node ARM Mapping Symbols
 473 @section Mapping Symbols
 474
 475 The ARM ELF specification requires that special symbols be inserted
 476 into object files to mark certain features:
 477
 478 @table @code
 479
 480 @cindex @code{$a}
 481 @item $a
 482 At the start of a region of code containing ARM instructions.
 483
 484 @cindex @code{$t}
 485 @item $t
 486 At the start of a region of code containing THUMB instructions.
 487
 488 @cindex @code{$d}
 489 @item $d
 490 At the start of a region of data.
 491
 492 @end table
 493
 494 The assembler will automatically insert these symbols for you - there
 495 is no need to code them yourself.  Support for tagging symbols ($b,
 496 $f, $p and $m) which is also mentioned in the current ARM ELF
 497 specification is not implemented.  This is because they have been
 498 dropped from the new EABI and so tools cannot rely upon their
 499 presence.
 500