contrib/binutils/gas/doc/c-arm.texi

   1 @c Copyright 1996, 1997, 1998, 1999, 2000, 2001
   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 @end menu
  26
  27 @node ARM Options
  28 @section Options
  29 @cindex ARM options (none)
  30 @cindex options for ARM (none)
  31
  32 @table @code
  33
  34 @cindex @code{-mcpu=} command line option, ARM
  35 @item -mcpu=@var{processor}[+@var{extension}@dots{}]
  36 This option specifies the target processor.  The assembler will issue an
  37 error message if an attempt is made to assemble an instruction which
  38 will not execute on the target processor.  The following processor names are
  39 recognized:
  40 @code{arm1},
  41 @code{arm2},
  42 @code{arm250},
  43 @code{arm3},
  44 @code{arm6},
  45 @code{arm60},
  46 @code{arm600},
  47 @code{arm610},
  48 @code{arm620},
  49 @code{arm7},
  50 @code{arm7m},
  51 @code{arm7d},
  52 @code{arm7dm},
  53 @code{arm7di},
  54 @code{arm7dmi},
  55 @code{arm70},
  56 @code{arm700},
  57 @code{arm700i},
  58 @code{arm710},
  59 @code{arm710t},
  60 @code{arm720},
  61 @code{arm720t},
  62 @code{arm740t},
  63 @code{arm710c},
  64 @code{arm7100},
  65 @code{arm7500},
  66 @code{arm7500fe},
  67 @code{arm7t},
  68 @code{arm7tdmi},
  69 @code{arm8},
  70 @code{arm810},
  71 @code{strongarm},
  72 @code{strongarm1},
  73 @code{strongarm110},
  74 @code{strongarm1100},
  75 @code{strongarm1110},
  76 @code{arm9},
  77 @code{arm920},
  78 @code{arm920t},
  79 @code{arm922t},
  80 @code{arm940t},
  81 @code{arm9tdmi},
  82 @code{arm9e},
  83 @code{arm946e-r0},
  84 @code{arm946e},
  85 @code{arm966e-r0},
  86 @code{arm966e},
  87 @code{arm10t},
  88 @code{arm10e},
  89 @code{arm1020},
  90 @code{arm1020t},
  91 @code{arm1020e},
  92 @code{ep9312} (ARM920 with Cirrus Maverick coprocessor),
  93 @code{i80200} (Intel XScale processor)
  94 and
  95 @code{xscale}.
  96 The special name @code{all} may be used to allow the
  97 assembler to accept instructions valid for any ARM processor.
  98
  99 In addition to the basic instruction set, the assembler can be told to
 100 accept various extension mnemonics that extend the processor using the
 101 co-processor instruction space.  For example, @code{-mcpu=arm920+maverick}
 102 is equivalent to specifying @code{-mcpu=ep9312}.  The following extensions
 103 are currently supported:
 104 @code{+maverick}
 105 and
 106 @code{+xscale}.
 107
 108 @cindex @code{-march=} command line option, ARM
 109 @item -march=@var{architecture}[+@var{extension}@dots{}]
 110 This option specifies the target architecture.  The assembler will issue
 111 an error message if an attempt is made to assemble an instruction which
 112 will not execute on the target architecture.  The following architecture
 113 names are recognized:
 114 @code{armv1},
 115 @code{armv2},
 116 @code{armv2a},
 117 @code{armv2s},
 118 @code{armv3},
 119 @code{armv3m},
 120 @code{armv4},
 121 @code{armv4xm},
 122 @code{armv4t},
 123 @code{armv4txm},
 124 @code{armv5},
 125 @code{armv5t},
 126 @code{armv5txm},
 127 @code{armv5te},
 128 @code{armv5texp}
 129 and
 130 @code{xscale}.
 131 If both @code{-mcpu} and
 132 @code{-march} are specified, the assembler will use
 133 the setting for @code{-mcpu}.
 134
 135 The architecture option can be extended with the same instruction set
 136 extension options as the @code{-mcpu} option.
 137
 138 @cindex @code{-mfpu=} command line option, ARM
 139 @item -mfpu=@var{floating-point-format}
 140
 141 This option specifies the floating point format to assemble for.  The
 142 assembler will issue an error message if an attempt is made to assemble
 143 an instruction which will not execute on the target floating point unit.
 144 The following format options are recognized:
 145 @code{softfpa},
 146 @code{fpe},
 147 @code{fpe2},
 148 @code{fpe3},
 149 @code{fpa},
 150 @code{fpa10},
 151 @code{fpa11},
 152 @code{arm7500fe},
 153 @code{softvfp},
 154 @code{softvfp+vfp},
 155 @code{vfp},
 156 @code{vfp10},
 157 @code{vfp10-r0},
 158 @code{vfp9},
 159 @code{vfpxd},
 160 @code{arm1020t}
 161 and
 162 @code{arm1020e}.
 163
 164 In addition to determining which instructions are assembled, this option
 165 also affects the way in which the @code{.double} assembler directive behaves
 166 when assembling little-endian code.
 167
 168 The default is dependent on the processor selected.  For Architecture 5 or
 169 later, the default is to assembler for VFP instructions; for earlier
 170 architectures the default is to assemble for FPA instructions.
 171
 172 @cindex @code{-mthumb} command line option, ARM
 173 @item -mthumb
 174 This option specifies that the assembler should start assembling Thumb
 175 instructions; that is, it should behave as though the file starts with a
 176 @code{.code 16} directive.
 177
 178 @cindex @code{-mthumb-interwork} command line option, ARM
 179 @item -mthumb-interwork
 180 This option specifies that the output generated by the assembler should
 181 be marked as supporting interworking.
 182
 183 @cindex @code{-mapcs} command line option, ARM
 184 @item -mapcs @code{[26|32]}
 185 This option specifies that the output generated by the assembler should
 186 be marked as supporting the indicated version of the Arm Procedure.
 187 Calling Standard.
 188
 189 @cindex @code{-matpcs} command line option, ARM
 190 @item -matpcs
 191 This option specifies that the output generated by the assembler should
 192 be marked as supporting the Arm/Thumb Procedure Calling Standard.  If
 193 enabled this option will cause the assembler to create an empty
 194 debugging section in the object file called .arm.atpcs.  Debuggers can
 195 use this to determine the ABI being used by.
 196
 197 @cindex @code{-mapcs-float} command line option, ARM
 198 @item -mapcs-float
 199 This indicates the the floating point variant of the APCS should be
 200 used.  In this variant floating point arguments are passed in FP
 201 registers rather than integer registers.
 202
 203 @cindex @code{-mapcs-reentrant} command line option, ARM
 204 @item -mapcs-reentrant
 205 This indicates that the reentrant variant of the APCS should be used.
 206 This variant supports position independent code.
 207
 208 @cindex @code{-EB} command line option, ARM
 209 @item -EB
 210 This option specifies that the output generated by the assembler should
 211 be marked as being encoded for a big-endian processor.
 212
 213 @cindex @code{-EL} command line option, ARM
 214 @item -EL
 215 This option specifies that the output generated by the assembler should
 216 be marked as being encoded for a little-endian processor.
 217
 218 @cindex @code{-k} command line option, ARM
 219 @cindex PIC code generation for ARM
 220 @item -k
 221 This option specifies that the output of the assembler should be marked
 222 as position-independent code (PIC).
 223
 224 @cindex @code{-moabi} command line option, ARM
 225 @item -moabi
 226 This indicates that the code should be assembled using the old ARM ELF
 227 conventions, based on a beta release release of the ARM-ELF
 228 specifications, rather than the default conventions which are based on
 229 the final release of the ARM-ELF specifications.
 230
 231 @end table
 232
 233
 234 @node ARM Syntax
 235 @section Syntax
 236 @menu
 237 * ARM-Chars::                Special Characters
 238 * ARM-Regs::                 Register Names
 239 @end menu
 240
 241 @node ARM-Chars
 242 @subsection Special Characters
 243
 244 @cindex line comment character, ARM
 245 @cindex ARM line comment character
 246 The presence of a @samp{@@} on a line indicates the start of a comment
 247 that extends to the end of the current line.  If a @samp{#} appears as
 248 the first character of a line, the whole line is treated as a comment.
 249
 250 @cindex line separator, ARM
 251 @cindex statement separator, ARM
 252 @cindex ARM line separator
 253 The @samp{;} character can be used instead of a newline to separate
 254 statements.
 255
 256 @cindex immediate character, ARM
 257 @cindex ARM immediate character
 258 Either @samp{#} or @samp{$} can be used to indicate immediate operands.
 259
 260 @cindex identifiers, ARM
 261 @cindex ARM identifiers
 262 *TODO* Explain about /data modifier on symbols.
 263
 264 @node ARM-Regs
 265 @subsection Register Names
 266
 267 @cindex ARM register names
 268 @cindex register names, ARM
 269 *TODO* Explain about ARM register naming, and the predefined names.
 270
 271 @node ARM Floating Point
 272 @section Floating Point
 273
 274 @cindex floating point, ARM (@sc{ieee})
 275 @cindex ARM floating point (@sc{ieee})
 276 The ARM family uses @sc{ieee} floating-point numbers.
 277
 278
 279
 280 @node ARM Directives
 281 @section ARM Machine Directives
 282
 283 @cindex machine directives, ARM
 284 @cindex ARM machine directives
 285 @table @code
 286
 287 @cindex @code{align} directive, ARM
 288 @item .align @var{expression} [, @var{expression}]
 289 This is the generic @var{.align} directive.  For the ARM however if the
 290 first argument is zero (ie no alignment is needed) the assembler will
 291 behave as if the argument had been 2 (ie pad to the next four byte
 292 boundary).  This is for compatability with ARM's own assembler.
 293
 294 @cindex @code{req} directive, ARM
 295 @item @var{name} .req @var{register name}
 296 This creates an alias for @var{register name} called @var{name}.  For
 297 example:
 298
 299 @smallexample
 300         foo .req r0
 301 @end smallexample
 302
 303 @cindex @code{code} directive, ARM
 304 @item .code @code{[16|32]}
 305 This directive selects the instruction set being generated. The value 16
 306 selects Thumb, with the value 32 selecting ARM.
 307
 308 @cindex @code{thumb} directive, ARM
 309 @item .thumb
 310 This performs the same action as @var{.code 16}.
 311
 312 @cindex @code{arm} directive, ARM
 313 @item .arm
 314 This performs the same action as @var{.code 32}.
 315
 316 @cindex @code{force_thumb} directive, ARM
 317 @item .force_thumb
 318 This directive forces the selection of Thumb instructions, even if the
 319 target processor does not support those instructions
 320
 321 @cindex @code{thumb_func} directive, ARM
 322 @item .thumb_func
 323 This directive specifies that the following symbol is the name of a
 324 Thumb encoded function.  This information is necessary in order to allow
 325 the assembler and linker to generate correct code for interworking
 326 between Arm and Thumb instructions and should be used even if
 327 interworking is not going to be performed.  The presence of this
 328 directive also implies @code{.thumb}
 329
 330 @cindex @code{thumb_set} directive, ARM
 331 @item .thumb_set
 332 This performs the equivalent of a @code{.set} directive in that it
 333 creates a symbol which is an alias for another symbol (possibly not yet
 334 defined).  This directive also has the added property in that it marks
 335 the aliased symbol as being a thumb function entry point, in the same
 336 way that the @code{.thumb_func} directive does.
 337
 338 @cindex @code{.ltorg} directive, ARM
 339 @item .ltorg
 340 This directive causes the current contents of the literal pool to be
 341 dumped into the current section (which is assumed to be the .text
 342 section) at the current location (aligned to a word boundary).
 343
 344 @cindex @code{.pool} directive, ARM
 345 @item .pool
 346 This is a synonym for .ltorg.
 347
 348 @end table
 349
 350 @node ARM Opcodes
 351 @section Opcodes
 352
 353 @cindex ARM opcodes
 354 @cindex opcodes for ARM
 355 @code{@value{AS}} implements all the standard ARM opcodes.  It also
 356 implements several pseudo opcodes, including several synthetic load
 357 instructions.
 358
 359 @table @code
 360
 361 @cindex @code{NOP} pseudo op, ARM
 362 @item NOP
 363 @smallexample
 364   nop
 365 @end smallexample
 366
 367 This pseudo op will always evaluate to a legal ARM instruction that does
 368 nothing.  Currently it will evaluate to MOV r0, r0.
 369
 370 @cindex @code{LDR reg,=<label>} pseudo op, ARM
 371 @item LDR
 372 @smallexample
 373   ldr <register> , = <expression>
 374 @end smallexample
 375
 376 If expression evaluates to a numeric constant then a MOV or MVN
 377 instruction will be used in place of the LDR instruction, if the
 378 constant can be generated by either of these instructions.  Otherwise
 379 the constant will be placed into the nearest literal pool (if it not
 380 already there) and a PC relative LDR instruction will be generated.
 381
 382 @cindex @code{ADR reg,<label>} pseudo op, ARM
 383 @item ADR
 384 @smallexample
 385   adr <register> <label>
 386 @end smallexample
 387
 388 This instruction will load the address of @var{label} into the indicated
 389 register.  The instruction will evaluate to a PC relative ADD or SUB
 390 instruction depending upon where the label is located.  If the label is
 391 out of range, or if it is not defined in the same file (and section) as
 392 the ADR instruction, then an error will be generated.  This instruction
 393 will not make use of the literal pool.
 394
 395 @cindex @code{ADRL reg,<label>} pseudo op, ARM
 396 @item ADRL
 397 @smallexample
 398   adrl <register> <label>
 399 @end smallexample
 400
 401 This instruction will load the address of @var{label} into the indicated
 402 register.  The instruction will evaluate to one or two PC relative ADD
 403 or SUB instructions depending upon where the label is located.  If a
 404 second instruction is not needed a NOP instruction will be generated in
 405 its place, so that this instruction is always 8 bytes long.
 406
 407 If the label is out of range, or if it is not defined in the same file
 408 (and section) as the ADRL instruction, then an error will be generated.
 409 This instruction will not make use of the literal pool.
 410
 411 @end table
 412
 413 For information on the ARM or Thumb instruction sets, see @cite{ARM
 414 Software Development Toolkit Reference Manual}, Advanced RISC Machines
 415 Ltd.
 416