1 @c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
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.
9 @chapter ARM Dependent Features
13 @node Machine Dependencies
14 @chapter ARM Dependent Features
20 * ARM Options:: Options
22 * ARM Floating Point:: Floating Point
23 * ARM Directives:: ARM Machine Directives
24 * ARM Opcodes:: Opcodes
25 * ARM Mapping Symbols:: Mapping Symbols
30 @cindex ARM options (none)
31 @cindex options for ARM (none)
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
113 @code{ep9312} (ARM920 with Cirrus Maverick coprocessor),
114 @code{i80200} (Intel XScale processor)
115 @code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor)
118 The special name @code{all} may be used to allow the
119 assembler to accept instructions valid for any ARM processor.
121 In addition to the basic instruction set, the assembler can be told to
122 accept various extension mnemonics that extend the processor using the
123 co-processor instruction space. For example, @code{-mcpu=arm920+maverick}
124 is equivalent to specifying @code{-mcpu=ep9312}. The following extensions
125 are currently supported:
131 @cindex @code{-march=} command line option, ARM
132 @item -march=@var{architecture}[+@var{extension}@dots{}]
133 This option specifies the target architecture. The assembler will issue
134 an error message if an attempt is made to assemble an instruction which
135 will not execute on the target architecture. The following architecture
136 names are recognized:
164 If both @code{-mcpu} and
165 @code{-march} are specified, the assembler will use
166 the setting for @code{-mcpu}.
168 The architecture option can be extended with the same instruction set
169 extension options as the @code{-mcpu} option.
171 @cindex @code{-mfpu=} command line option, ARM
172 @item -mfpu=@var{floating-point-format}
174 This option specifies the floating point format to assemble for. The
175 assembler will issue an error message if an attempt is made to assemble
176 an instruction which will not execute on the target floating point unit.
177 The following format options are recognized:
203 In addition to determining which instructions are assembled, this option
204 also affects the way in which the @code{.double} assembler directive behaves
205 when assembling little-endian code.
207 The default is dependent on the processor selected. For Architecture 5 or
208 later, the default is to assembler for VFP instructions; for earlier
209 architectures the default is to assemble for FPA instructions.
211 @cindex @code{-mthumb} command line option, ARM
213 This option specifies that the assembler should start assembling Thumb
214 instructions; that is, it should behave as though the file starts with a
215 @code{.code 16} directive.
217 @cindex @code{-mthumb-interwork} command line option, ARM
218 @item -mthumb-interwork
219 This option specifies that the output generated by the assembler should
220 be marked as supporting interworking.
222 @cindex @code{-mapcs} command line option, ARM
223 @item -mapcs @code{[26|32]}
224 This option specifies that the output generated by the assembler should
225 be marked as supporting the indicated version of the Arm Procedure.
228 @cindex @code{-matpcs} command line option, ARM
230 This option specifies that the output generated by the assembler should
231 be marked as supporting the Arm/Thumb Procedure Calling Standard. If
232 enabled this option will cause the assembler to create an empty
233 debugging section in the object file called .arm.atpcs. Debuggers can
234 use this to determine the ABI being used by.
236 @cindex @code{-mapcs-float} command line option, ARM
238 This indicates the floating point variant of the APCS should be
239 used. In this variant floating point arguments are passed in FP
240 registers rather than integer registers.
242 @cindex @code{-mapcs-reentrant} command line option, ARM
243 @item -mapcs-reentrant
244 This indicates that the reentrant variant of the APCS should be used.
245 This variant supports position independent code.
247 @cindex @code{-mfloat-abi=} command line option, ARM
248 @item -mfloat-abi=@var{abi}
249 This option specifies that the output generated by the assembler should be
250 marked as using specified floating point ABI.
251 The following values are recognized:
257 @cindex @code{-eabi=} command line option, ARM
258 @item -meabi=@var{ver}
259 This option specifies which EABI version the produced object files should
261 The following values are recognized:
267 @cindex @code{-EB} command line option, ARM
269 This option specifies that the output generated by the assembler should
270 be marked as being encoded for a big-endian processor.
272 @cindex @code{-EL} command line option, ARM
274 This option specifies that the output generated by the assembler should
275 be marked as being encoded for a little-endian processor.
277 @cindex @code{-k} command line option, ARM
278 @cindex PIC code generation for ARM
280 This option specifies that the output of the assembler should be marked
281 as position-independent code (PIC).
283 @cindex @code{--fix-v4bx} command line option, ARM
285 Allow @code{BX} instructions in ARMv4 code. This is intended for use with
286 the linker option of the same name.
294 * ARM-Chars:: Special Characters
295 * ARM-Regs:: Register Names
296 * ARM-Relocations:: Relocations
300 @subsection Special Characters
302 @cindex line comment character, ARM
303 @cindex ARM line comment character
304 The presence of a @samp{@@} on a line indicates the start of a comment
305 that extends to the end of the current line. If a @samp{#} appears as
306 the first character of a line, the whole line is treated as a comment.
308 @cindex line separator, ARM
309 @cindex statement separator, ARM
310 @cindex ARM line separator
311 The @samp{;} character can be used instead of a newline to separate
314 @cindex immediate character, ARM
315 @cindex ARM immediate character
316 Either @samp{#} or @samp{$} can be used to indicate immediate operands.
318 @cindex identifiers, ARM
319 @cindex ARM identifiers
320 *TODO* Explain about /data modifier on symbols.
323 @subsection Register Names
325 @cindex ARM register names
326 @cindex register names, ARM
327 *TODO* Explain about ARM register naming, and the predefined names.
329 @node ARM Floating Point
330 @section Floating Point
332 @cindex floating point, ARM (@sc{ieee})
333 @cindex ARM floating point (@sc{ieee})
334 The ARM family uses @sc{ieee} floating-point numbers.
336 @node ARM-Relocations
337 @subsection ARM relocation generation
339 @cindex data relocations, ARM
340 @cindex ARM data relocations
341 Specific data relocations can be generated by putting the relocation name
342 in parentheses after the symbol name. For example:
348 This will generate an @samp{R_ARM_TARGET1} relocation against the symbol
350 The following relocations are supported:
363 For compatibility with older toolchains the assembler also accepts
364 @code{(PLT)} after branch targets. This will generate the deprecated
365 @samp{R_ARM_PLT32} relocation.
367 @cindex MOVW and MOVT relocations, ARM
368 Relocations for @samp{MOVW} and @samp{MOVT} instructions can be generated
369 by prefixing the value with @samp{#:lower16:} and @samp{#:upper16}
370 respectively. For example to load the 32-bit address of foo into r0:
373 MOVW r0, #:lower16:foo
374 MOVT r0, #:upper16:foo
378 @section ARM Machine Directives
380 @cindex machine directives, ARM
381 @cindex ARM machine directives
384 @cindex @code{align} directive, ARM
385 @item .align @var{expression} [, @var{expression}]
386 This is the generic @var{.align} directive. For the ARM however if the
387 first argument is zero (ie no alignment is needed) the assembler will
388 behave as if the argument had been 2 (ie pad to the next four byte
389 boundary). This is for compatibility with ARM's own assembler.
391 @cindex @code{req} directive, ARM
392 @item @var{name} .req @var{register name}
393 This creates an alias for @var{register name} called @var{name}. For
400 @cindex @code{unreq} directive, ARM
401 @item .unreq @var{alias-name}
402 This undefines a register alias which was previously defined using the
403 @code{req}, @code{dn} or @code{qn} directives. For example:
410 An error occurs if the name is undefined. Note - this pseudo op can
411 be used to delete builtin in register name aliases (eg 'r0'). This
412 should only be done if it is really necessary.
414 @cindex @code{dn} and @code{qn} directives, ARM
415 @item @var{name} .dn @var{register name} [@var{.type}] [[@var{index}]]
416 @item @var{name} .qn @var{register name} [@var{.type}] [[@var{index}]]
418 The @code{dn} and @code{qn} directives are used to create typed
419 and/or indexed register aliases for use in Advanced SIMD Extension
420 (Neon) instructions. The former should be used to create aliases
421 of double-precision registers, and the latter to create aliases of
422 quad-precision registers.
424 If these directives are used to create typed aliases, those aliases can
425 be used in Neon instructions instead of writing types after the mnemonic
426 or after each operand. For example:
435 This is equivalent to writing the following:
441 Aliases created using @code{dn} or @code{qn} can be destroyed using
444 @cindex @code{code} directive, ARM
445 @item .code @code{[16|32]}
446 This directive selects the instruction set being generated. The value 16
447 selects Thumb, with the value 32 selecting ARM.
449 @cindex @code{thumb} directive, ARM
451 This performs the same action as @var{.code 16}.
453 @cindex @code{arm} directive, ARM
455 This performs the same action as @var{.code 32}.
457 @cindex @code{force_thumb} directive, ARM
459 This directive forces the selection of Thumb instructions, even if the
460 target processor does not support those instructions
462 @cindex @code{thumb_func} directive, ARM
464 This directive specifies that the following symbol is the name of a
465 Thumb encoded function. This information is necessary in order to allow
466 the assembler and linker to generate correct code for interworking
467 between Arm and Thumb instructions and should be used even if
468 interworking is not going to be performed. The presence of this
469 directive also implies @code{.thumb}
471 This directive is not neccessary when generating EABI objects. On these
472 targets the encoding is implicit when generating Thumb code.
474 @cindex @code{thumb_set} directive, ARM
476 This performs the equivalent of a @code{.set} directive in that it
477 creates a symbol which is an alias for another symbol (possibly not yet
478 defined). This directive also has the added property in that it marks
479 the aliased symbol as being a thumb function entry point, in the same
480 way that the @code{.thumb_func} directive does.
482 @cindex @code{.ltorg} directive, ARM
484 This directive causes the current contents of the literal pool to be
485 dumped into the current section (which is assumed to be the .text
486 section) at the current location (aligned to a word boundary).
487 @code{GAS} maintains a separate literal pool for each section and each
488 sub-section. The @code{.ltorg} directive will only affect the literal
489 pool of the current section and sub-section. At the end of assembly
490 all remaining, un-empty literal pools will automatically be dumped.
492 Note - older versions of @code{GAS} would dump the current literal
493 pool any time a section change occurred. This is no longer done, since
494 it prevents accurate control of the placement of literal pools.
496 @cindex @code{.pool} directive, ARM
498 This is a synonym for .ltorg.
500 @cindex @code{.fnstart} directive, ARM
501 @item .unwind_fnstart
502 Marks the start of a function with an unwind table entry.
504 @cindex @code{.fnend} directive, ARM
506 Marks the end of a function with an unwind table entry. The unwind index
507 table entry is created when this directive is processed.
509 If no personality routine has been specified then standard personality
510 routine 0 or 1 will be used, depending on the number of unwind opcodes
513 @cindex @code{.cantunwind} directive, ARM
515 Prevents unwinding through the current function. No personality routine
516 or exception table data is required or permitted.
518 @cindex @code{.personality} directive, ARM
519 @item .personality @var{name}
520 Sets the personality routine for the current function to @var{name}.
522 @cindex @code{.personalityindex} directive, ARM
523 @item .personalityindex @var{index}
524 Sets the personality routine for the current function to the EABI standard
525 routine number @var{index}
527 @cindex @code{.handlerdata} directive, ARM
529 Marks the end of the current function, and the start of the exception table
530 entry for that function. Anything between this directive and the
531 @code{.fnend} directive will be added to the exception table entry.
533 Must be preceded by a @code{.personality} or @code{.personalityindex}
536 @cindex @code{.save} directive, ARM
537 @item .save @var{reglist}
538 Generate unwinder annotations to restore the registers in @var{reglist}.
539 The format of @var{reglist} is the same as the corresponding store-multiple
543 @exdent @emph{core registers}
544 .save @{r4, r5, r6, lr@}
545 stmfd sp!, @{r4, r5, r6, lr@}
546 @exdent @emph{FPA registers}
549 @exdent @emph{VFP registers}
550 .save @{d8, d9, d10@}
551 fstmdx sp!, @{d8, d9, d10@}
552 @exdent @emph{iWMMXt registers}
554 wstrd wr11, [sp, #-8]!
555 wstrd wr10, [sp, #-8]!
558 wstrd wr11, [sp, #-8]!
560 wstrd wr10, [sp, #-8]!
563 @cindex @code{.vsave} directive, ARM
564 @item .vsave @var{vfp-reglist}
565 Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist}
566 using FLDMD. Also works for VFPv3 registers
567 that are to be restored using VLDM.
568 The format of @var{vfp-reglist} is the same as the corresponding store-multiple
572 @exdent @emph{VFP registers}
573 .vsave @{d8, d9, d10@}
574 fstmdd sp!, @{d8, d9, d10@}
575 @exdent @emph{VFPv3 registers}
576 .vsave @{d15, d16, d17@}
577 vstm sp!, @{d15, d16, d17@}
580 Since FLDMX and FSTMX are now deprecated, this directive should be
581 used in favour of @code{.save} for saving VFP registers for ARMv6 and above.
583 @cindex @code{.pad} directive, ARM
584 @item .pad #@var{count}
585 Generate unwinder annotations for a stack adjustment of @var{count} bytes.
586 A positive value indicates the function prologue allocated stack space by
587 decrementing the stack pointer.
589 @cindex @code{.movsp} directive, ARM
590 @item .movsp @var{reg} [, #@var{offset}]
591 Tell the unwinder that @var{reg} contains an offset from the current
592 stack pointer. If @var{offset} is not specified then it is assumed to be
595 @cindex @code{.setfp} directive, ARM
596 @item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}]
597 Make all unwinder annotations relaive to a frame pointer. Without this
598 the unwinder will use offsets from the stack pointer.
600 The syntax of this directive is the same as the @code{sub} or @code{mov}
601 instruction used to set the frame pointer. @var{spreg} must be either
602 @code{sp} or mentioned in a previous @code{.movsp} directive.
612 @cindex @code{.unwind_raw} directive, ARM
613 @item .raw @var{offset}, @var{byte1}, @dots{}
614 Insert one of more arbitary unwind opcode bytes, which are known to adjust
615 the stack pointer by @var{offset} bytes.
617 For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to
620 @cindex @code{.cpu} directive, ARM
621 @item .cpu @var{name}
622 Select the target processor. Valid values for @var{name} are the same as
623 for the @option{-mcpu} commandline option.
625 @cindex @code{.arch} directive, ARM
626 @item .arch @var{name}
627 Select the target architecture. Valid values for @var{name} are the same as
628 for the @option{-march} commandline option.
630 @cindex @code{.object_arch} directive, ARM
631 @item .object_arch @var{name}
632 Override the architecture recorded in the EABI object attribute section.
633 Valid values for @var{name} are the same as for the @code{.arch} directive.
634 Typically this is useful when code uses runtime detection of CPU features.
636 @cindex @code{.fpu} directive, ARM
637 @item .fpu @var{name}
638 Select the floating point unit to assemble for. Valid values for @var{name}
639 are the same as for the @option{-mfpu} commandline option.
641 @cindex @code{.eabi_attribute} directive, ARM
642 @item .eabi_attribute @var{tag}, @var{value}
643 Set the EABI object attribute number @var{tag} to @var{value}. The value
644 is either a @code{number}, @code{"string"}, or @code{number, "string"}
645 depending on the tag.
653 @cindex opcodes for ARM
654 @code{@value{AS}} implements all the standard ARM opcodes. It also
655 implements several pseudo opcodes, including several synthetic load
660 @cindex @code{NOP} pseudo op, ARM
666 This pseudo op will always evaluate to a legal ARM instruction that does
667 nothing. Currently it will evaluate to MOV r0, r0.
669 @cindex @code{LDR reg,=<label>} pseudo op, ARM
672 ldr <register> , = <expression>
675 If expression evaluates to a numeric constant then a MOV or MVN
676 instruction will be used in place of the LDR instruction, if the
677 constant can be generated by either of these instructions. Otherwise
678 the constant will be placed into the nearest literal pool (if it not
679 already there) and a PC relative LDR instruction will be generated.
681 @cindex @code{ADR reg,<label>} pseudo op, ARM
684 adr <register> <label>
687 This instruction will load the address of @var{label} into the indicated
688 register. The instruction will evaluate to a PC relative ADD or SUB
689 instruction depending upon where the label is located. If the label is
690 out of range, or if it is not defined in the same file (and section) as
691 the ADR instruction, then an error will be generated. This instruction
692 will not make use of the literal pool.
694 @cindex @code{ADRL reg,<label>} pseudo op, ARM
697 adrl <register> <label>
700 This instruction will load the address of @var{label} into the indicated
701 register. The instruction will evaluate to one or two PC relative ADD
702 or SUB instructions depending upon where the label is located. If a
703 second instruction is not needed a NOP instruction will be generated in
704 its place, so that this instruction is always 8 bytes long.
706 If the label is out of range, or if it is not defined in the same file
707 (and section) as the ADRL instruction, then an error will be generated.
708 This instruction will not make use of the literal pool.
712 For information on the ARM or Thumb instruction sets, see @cite{ARM
713 Software Development Toolkit Reference Manual}, Advanced RISC Machines
716 @node ARM Mapping Symbols
717 @section Mapping Symbols
719 The ARM ELF specification requires that special symbols be inserted
720 into object files to mark certain features:
726 At the start of a region of code containing ARM instructions.
730 At the start of a region of code containing THUMB instructions.
734 At the start of a region of data.
738 The assembler will automatically insert these symbols for you - there
739 is no need to code them yourself. Support for tagging symbols ($b,
740 $f, $p and $m) which is also mentioned in the current ARM ELF
741 specification is not implemented. This is because they have been
742 dropped from the new EABI and so tools cannot rely upon their