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