1 @c Copyright (C) 1996-2015 Free Software Foundation, Inc.
2 @c This is part of the GAS manual.
3 @c For copying conditions, see the file as.texinfo.
8 @chapter ARM Dependent Features
12 @node Machine Dependencies
13 @chapter ARM Dependent Features
19 * ARM Options:: Options
21 * ARM Floating Point:: Floating Point
22 * ARM Directives:: ARM Machine Directives
23 * ARM Opcodes:: Opcodes
24 * ARM Mapping Symbols:: Mapping Symbols
25 * ARM Unwinding Tutorial:: Unwinding
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
84 @code{fa526} (Faraday FA526 processor),
85 @code{fa626} (Faraday FA626 processor),
104 @code{fa606te} (Faraday FA606TE processor),
105 @code{fa616te} (Faraday FA616TE processor),
106 @code{fa626te} (Faraday FA626TE processor),
107 @code{fmp626} (Faraday FMP626 processor),
108 @code{fa726te} (Faraday FA726TE processor),
134 @code{cortex-m0plus},
136 @code{marvell-whitney},
139 @code{ep9312} (ARM920 with Cirrus Maverick coprocessor),
140 @code{i80200} (Intel XScale processor)
141 @code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor)
144 The special name @code{all} may be used to allow the
145 assembler to accept instructions valid for any ARM processor.
147 In addition to the basic instruction set, the assembler can be told to
148 accept various extension mnemonics that extend the processor using the
149 co-processor instruction space. For example, @code{-mcpu=arm920+maverick}
150 is equivalent to specifying @code{-mcpu=ep9312}.
152 Multiple extensions may be specified, separated by a @code{+}. The
153 extensions should be specified in ascending alphabetical order.
155 Some extensions may be restricted to particular architectures; this is
156 documented in the list of extensions below.
158 Extension mnemonics may also be removed from those the assembler accepts.
159 This is done be prepending @code{no} to the option that adds the extension.
160 Extensions that are removed should be listed after all extensions which have
161 been added, again in ascending alphabetical order. For example,
162 @code{-mcpu=ep9312+nomaverick} is equivalent to specifying @code{-mcpu=arm920}.
165 The following extensions are currently supported:
167 @code{crypto} (Cryptography Extensions for v8-A architecture, implies @code{fp+simd}),
168 @code{fp} (Floating Point Extensions for v8-A architecture),
169 @code{idiv} (Integer Divide Extensions for v7-A and v7-R architectures),
174 @code{mp} (Multiprocessing Extensions for v7-A and v7-R
176 @code{os} (Operating System for v6M architecture),
177 @code{sec} (Security Extensions for v6K and v7-A architectures),
178 @code{simd} (Advanced SIMD Extensions for v8-A architecture, implies @code{fp}),
179 @code{virt} (Virtualization Extensions for v7-A architecture, implies
184 @cindex @code{-march=} command line option, ARM
185 @item -march=@var{architecture}[+@var{extension}@dots{}]
186 This option specifies the target architecture. The assembler will issue
187 an error message if an attempt is made to assemble an instruction which
188 will not execute on the target architecture. The following architecture
189 names are recognized:
223 If both @code{-mcpu} and
224 @code{-march} are specified, the assembler will use
225 the setting for @code{-mcpu}.
227 The architecture option can be extended with the same instruction set
228 extension options as the @code{-mcpu} option.
230 @cindex @code{-mfpu=} command line option, ARM
231 @item -mfpu=@var{floating-point-format}
233 This option specifies the floating point format to assemble for. The
234 assembler will issue an error message if an attempt is made to assemble
235 an instruction which will not execute on the target floating point unit.
236 The following format options are recognized:
256 @code{vfpv3-d16-fp16},
271 @code{neon-fp-armv8},
273 @code{crypto-neon-fp-armv8}.
275 In addition to determining which instructions are assembled, this option
276 also affects the way in which the @code{.double} assembler directive behaves
277 when assembling little-endian code.
279 The default is dependent on the processor selected. For Architecture 5 or
280 later, the default is to assembler for VFP instructions; for earlier
281 architectures the default is to assemble for FPA instructions.
283 @cindex @code{-mthumb} command line option, ARM
285 This option specifies that the assembler should start assembling Thumb
286 instructions; that is, it should behave as though the file starts with a
287 @code{.code 16} directive.
289 @cindex @code{-mthumb-interwork} command line option, ARM
290 @item -mthumb-interwork
291 This option specifies that the output generated by the assembler should
292 be marked as supporting interworking.
294 @cindex @code{-mimplicit-it} command line option, ARM
295 @item -mimplicit-it=never
296 @itemx -mimplicit-it=always
297 @itemx -mimplicit-it=arm
298 @itemx -mimplicit-it=thumb
299 The @code{-mimplicit-it} option controls the behavior of the assembler when
300 conditional instructions are not enclosed in IT blocks.
301 There are four possible behaviors.
302 If @code{never} is specified, such constructs cause a warning in ARM
303 code and an error in Thumb-2 code.
304 If @code{always} is specified, such constructs are accepted in both
305 ARM and Thumb-2 code, where the IT instruction is added implicitly.
306 If @code{arm} is specified, such constructs are accepted in ARM code
307 and cause an error in Thumb-2 code.
308 If @code{thumb} is specified, such constructs cause a warning in ARM
309 code and are accepted in Thumb-2 code. If you omit this option, the
310 behavior is equivalent to @code{-mimplicit-it=arm}.
312 @cindex @code{-mapcs-26} command line option, ARM
313 @cindex @code{-mapcs-32} command line option, ARM
316 These options specify that the output generated by the assembler should
317 be marked as supporting the indicated version of the Arm Procedure.
320 @cindex @code{-matpcs} command line option, ARM
322 This option specifies that the output generated by the assembler should
323 be marked as supporting the Arm/Thumb Procedure Calling Standard. If
324 enabled this option will cause the assembler to create an empty
325 debugging section in the object file called .arm.atpcs. Debuggers can
326 use this to determine the ABI being used by.
328 @cindex @code{-mapcs-float} command line option, ARM
330 This indicates the floating point variant of the APCS should be
331 used. In this variant floating point arguments are passed in FP
332 registers rather than integer registers.
334 @cindex @code{-mapcs-reentrant} command line option, ARM
335 @item -mapcs-reentrant
336 This indicates that the reentrant variant of the APCS should be used.
337 This variant supports position independent code.
339 @cindex @code{-mfloat-abi=} command line option, ARM
340 @item -mfloat-abi=@var{abi}
341 This option specifies that the output generated by the assembler should be
342 marked as using specified floating point ABI.
343 The following values are recognized:
349 @cindex @code{-eabi=} command line option, ARM
350 @item -meabi=@var{ver}
351 This option specifies which EABI version the produced object files should
353 The following values are recognized:
359 @cindex @code{-EB} command line option, ARM
361 This option specifies that the output generated by the assembler should
362 be marked as being encoded for a big-endian processor.
364 @cindex @code{-EL} command line option, ARM
366 This option specifies that the output generated by the assembler should
367 be marked as being encoded for a little-endian processor.
369 @cindex @code{-k} command line option, ARM
370 @cindex PIC code generation for ARM
372 This option specifies that the output of the assembler should be marked
373 as position-independent code (PIC).
375 @cindex @code{--fix-v4bx} command line option, ARM
377 Allow @code{BX} instructions in ARMv4 code. This is intended for use with
378 the linker option of the same name.
380 @cindex @code{-mwarn-deprecated} command line option, ARM
381 @item -mwarn-deprecated
382 @itemx -mno-warn-deprecated
383 Enable or disable warnings about using deprecated options or
384 features. The default is to warn.
386 @cindex @code{-mccs} command line option, ARM
388 Turns on CodeComposer Studio assembly syntax compatibility mode.
396 * ARM-Instruction-Set:: Instruction Set
397 * ARM-Chars:: Special Characters
398 * ARM-Regs:: Register Names
399 * ARM-Relocations:: Relocations
400 * ARM-Neon-Alignment:: NEON Alignment Specifiers
403 @node ARM-Instruction-Set
404 @subsection Instruction Set Syntax
405 Two slightly different syntaxes are support for ARM and THUMB
406 instructions. The default, @code{divided}, uses the old style where
407 ARM and THUMB instructions had their own, separate syntaxes. The new,
408 @code{unified} syntax, which can be selected via the @code{.syntax}
409 directive, and has the following main features:
413 Immediate operands do not require a @code{#} prefix.
416 The @code{IT} instruction may appear, and if it does it is validated
417 against subsequent conditional affixes. In ARM mode it does not
418 generate machine code, in THUMB mode it does.
421 For ARM instructions the conditional affixes always appear at the end
422 of the instruction. For THUMB instructions conditional affixes can be
423 used, but only inside the scope of an @code{IT} instruction.
426 All of the instructions new to the V6T2 architecture (and later) are
427 available. (Only a few such instructions can be written in the
428 @code{divided} syntax).
431 The @code{.N} and @code{.W} suffixes are recognized and honored.
434 All instructions set the flags if and only if they have an @code{s}
439 @subsection Special Characters
441 @cindex line comment character, ARM
442 @cindex ARM line comment character
443 The presence of a @samp{@@} anywhere on a line indicates the start of
444 a comment that extends to the end of that line.
446 If a @samp{#} appears as the first character of a line then the whole
447 line is treated as a comment, but in this case the line could also be
448 a logical line number directive (@pxref{Comments}) or a preprocessor
449 control command (@pxref{Preprocessing}).
451 @cindex line separator, ARM
452 @cindex statement separator, ARM
453 @cindex ARM line separator
454 The @samp{;} character can be used instead of a newline to separate
457 @cindex immediate character, ARM
458 @cindex ARM immediate character
459 Either @samp{#} or @samp{$} can be used to indicate immediate operands.
461 @cindex identifiers, ARM
462 @cindex ARM identifiers
463 *TODO* Explain about /data modifier on symbols.
466 @subsection Register Names
468 @cindex ARM register names
469 @cindex register names, ARM
470 *TODO* Explain about ARM register naming, and the predefined names.
472 @node ARM-Relocations
473 @subsection ARM relocation generation
475 @cindex data relocations, ARM
476 @cindex ARM data relocations
477 Specific data relocations can be generated by putting the relocation name
478 in parentheses after the symbol name. For example:
484 This will generate an @samp{R_ARM_TARGET1} relocation against the symbol
486 The following relocations are supported:
502 For compatibility with older toolchains the assembler also accepts
503 @code{(PLT)} after branch targets. On legacy targets this will
504 generate the deprecated @samp{R_ARM_PLT32} relocation. On EABI
505 targets it will encode either the @samp{R_ARM_CALL} or
506 @samp{R_ARM_JUMP24} relocation, as appropriate.
508 @cindex MOVW and MOVT relocations, ARM
509 Relocations for @samp{MOVW} and @samp{MOVT} instructions can be generated
510 by prefixing the value with @samp{#:lower16:} and @samp{#:upper16}
511 respectively. For example to load the 32-bit address of foo into r0:
514 MOVW r0, #:lower16:foo
515 MOVT r0, #:upper16:foo
518 @node ARM-Neon-Alignment
519 @subsection NEON Alignment Specifiers
521 @cindex alignment for NEON instructions
522 Some NEON load/store instructions allow an optional address
524 The ARM documentation specifies that this is indicated by
525 @samp{@@ @var{align}}. However GAS already interprets
526 the @samp{@@} character as a "line comment" start,
527 so @samp{: @var{align}} is used instead. For example:
530 vld1.8 @{q0@}, [r0, :128]
533 @node ARM Floating Point
534 @section Floating Point
536 @cindex floating point, ARM (@sc{ieee})
537 @cindex ARM floating point (@sc{ieee})
538 The ARM family uses @sc{ieee} floating-point numbers.
541 @section ARM Machine Directives
543 @cindex machine directives, ARM
544 @cindex ARM machine directives
547 @c AAAAAAAAAAAAAAAAAAAAAAAAA
549 @cindex @code{.2byte} directive, ARM
550 @cindex @code{.4byte} directive, ARM
551 @cindex @code{.8byte} directive, ARM
552 @item .2byte @var{expression} [, @var{expression}]*
553 @itemx .4byte @var{expression} [, @var{expression}]*
554 @itemx .8byte @var{expression} [, @var{expression}]*
555 These directives write 2, 4 or 8 byte values to the output section.
557 @cindex @code{.align} directive, ARM
558 @item .align @var{expression} [, @var{expression}]
559 This is the generic @var{.align} directive. For the ARM however if the
560 first argument is zero (ie no alignment is needed) the assembler will
561 behave as if the argument had been 2 (ie pad to the next four byte
562 boundary). This is for compatibility with ARM's own assembler.
564 @cindex @code{.arch} directive, ARM
565 @item .arch @var{name}
566 Select the target architecture. Valid values for @var{name} are the same as
567 for the @option{-march} commandline option.
569 Specifying @code{.arch} clears any previously selected architecture
572 @cindex @code{.arch_extension} directive, ARM
573 @item .arch_extension @var{name}
574 Add or remove an architecture extension to the target architecture. Valid
575 values for @var{name} are the same as those accepted as architectural
576 extensions by the @option{-mcpu} commandline option.
578 @code{.arch_extension} may be used multiple times to add or remove extensions
579 incrementally to the architecture being compiled for.
581 @cindex @code{.arm} directive, ARM
583 This performs the same action as @var{.code 32}.
585 @c BBBBBBBBBBBBBBBBBBBBBBBBBB
587 @cindex @code{.bss} directive, ARM
589 This directive switches to the @code{.bss} section.
591 @c CCCCCCCCCCCCCCCCCCCCCCCCCC
593 @cindex @code{.cantunwind} directive, ARM
595 Prevents unwinding through the current function. No personality routine
596 or exception table data is required or permitted.
598 @cindex @code{.code} directive, ARM
599 @item .code @code{[16|32]}
600 This directive selects the instruction set being generated. The value 16
601 selects Thumb, with the value 32 selecting ARM.
603 @cindex @code{.cpu} directive, ARM
604 @item .cpu @var{name}
605 Select the target processor. Valid values for @var{name} are the same as
606 for the @option{-mcpu} commandline option.
608 Specifying @code{.cpu} clears any previously selected architecture
611 @c DDDDDDDDDDDDDDDDDDDDDDDDDD
613 @cindex @code{.dn} and @code{.qn} directives, ARM
614 @item @var{name} .dn @var{register name} [@var{.type}] [[@var{index}]]
615 @itemx @var{name} .qn @var{register name} [@var{.type}] [[@var{index}]]
617 The @code{dn} and @code{qn} directives are used to create typed
618 and/or indexed register aliases for use in Advanced SIMD Extension
619 (Neon) instructions. The former should be used to create aliases
620 of double-precision registers, and the latter to create aliases of
621 quad-precision registers.
623 If these directives are used to create typed aliases, those aliases can
624 be used in Neon instructions instead of writing types after the mnemonic
625 or after each operand. For example:
634 This is equivalent to writing the following:
640 Aliases created using @code{dn} or @code{qn} can be destroyed using
643 @c EEEEEEEEEEEEEEEEEEEEEEEEEE
645 @cindex @code{.eabi_attribute} directive, ARM
646 @item .eabi_attribute @var{tag}, @var{value}
647 Set the EABI object attribute @var{tag} to @var{value}.
649 The @var{tag} is either an attribute number, or one of the following:
650 @code{Tag_CPU_raw_name}, @code{Tag_CPU_name}, @code{Tag_CPU_arch},
651 @code{Tag_CPU_arch_profile}, @code{Tag_ARM_ISA_use},
652 @code{Tag_THUMB_ISA_use}, @code{Tag_FP_arch}, @code{Tag_WMMX_arch},
653 @code{Tag_Advanced_SIMD_arch}, @code{Tag_PCS_config},
654 @code{Tag_ABI_PCS_R9_use}, @code{Tag_ABI_PCS_RW_data},
655 @code{Tag_ABI_PCS_RO_data}, @code{Tag_ABI_PCS_GOT_use},
656 @code{Tag_ABI_PCS_wchar_t}, @code{Tag_ABI_FP_rounding},
657 @code{Tag_ABI_FP_denormal}, @code{Tag_ABI_FP_exceptions},
658 @code{Tag_ABI_FP_user_exceptions}, @code{Tag_ABI_FP_number_model},
659 @code{Tag_ABI_align_needed}, @code{Tag_ABI_align_preserved},
660 @code{Tag_ABI_enum_size}, @code{Tag_ABI_HardFP_use},
661 @code{Tag_ABI_VFP_args}, @code{Tag_ABI_WMMX_args},
662 @code{Tag_ABI_optimization_goals}, @code{Tag_ABI_FP_optimization_goals},
663 @code{Tag_compatibility}, @code{Tag_CPU_unaligned_access},
664 @code{Tag_FP_HP_extension}, @code{Tag_ABI_FP_16bit_format},
665 @code{Tag_MPextension_use}, @code{Tag_DIV_use},
666 @code{Tag_nodefaults}, @code{Tag_also_compatible_with},
667 @code{Tag_conformance}, @code{Tag_T2EE_use},
668 @code{Tag_Virtualization_use}
670 The @var{value} is either a @code{number}, @code{"string"}, or
671 @code{number, "string"} depending on the tag.
673 Note - the following legacy values are also accepted by @var{tag}:
674 @code{Tag_VFP_arch}, @code{Tag_ABI_align8_needed},
675 @code{Tag_ABI_align8_preserved}, @code{Tag_VFP_HP_extension},
677 @cindex @code{.even} directive, ARM
679 This directive aligns to an even-numbered address.
681 @cindex @code{.extend} directive, ARM
682 @cindex @code{.ldouble} directive, ARM
683 @item .extend @var{expression} [, @var{expression}]*
684 @itemx .ldouble @var{expression} [, @var{expression}]*
685 These directives write 12byte long double floating-point values to the
686 output section. These are not compatible with current ARM processors
689 @c FFFFFFFFFFFFFFFFFFFFFFFFFF
692 @cindex @code{.fnend} directive, ARM
694 Marks the end of a function with an unwind table entry. The unwind index
695 table entry is created when this directive is processed.
697 If no personality routine has been specified then standard personality
698 routine 0 or 1 will be used, depending on the number of unwind opcodes
702 @cindex @code{.fnstart} directive, ARM
704 Marks the start of a function with an unwind table entry.
706 @cindex @code{.force_thumb} directive, ARM
708 This directive forces the selection of Thumb instructions, even if the
709 target processor does not support those instructions
711 @cindex @code{.fpu} directive, ARM
712 @item .fpu @var{name}
713 Select the floating-point unit to assemble for. Valid values for @var{name}
714 are the same as for the @option{-mfpu} commandline option.
716 @c GGGGGGGGGGGGGGGGGGGGGGGGGG
717 @c HHHHHHHHHHHHHHHHHHHHHHHHHH
719 @cindex @code{.handlerdata} directive, ARM
721 Marks the end of the current function, and the start of the exception table
722 entry for that function. Anything between this directive and the
723 @code{.fnend} directive will be added to the exception table entry.
725 Must be preceded by a @code{.personality} or @code{.personalityindex}
728 @c IIIIIIIIIIIIIIIIIIIIIIIIII
730 @cindex @code{.inst} directive, ARM
731 @item .inst @var{opcode} [ , @dots{} ]
732 @itemx .inst.n @var{opcode} [ , @dots{} ]
733 @itemx .inst.w @var{opcode} [ , @dots{} ]
734 Generates the instruction corresponding to the numerical value @var{opcode}.
735 @code{.inst.n} and @code{.inst.w} allow the Thumb instruction size to be
736 specified explicitly, overriding the normal encoding rules.
738 @c JJJJJJJJJJJJJJJJJJJJJJJJJJ
739 @c KKKKKKKKKKKKKKKKKKKKKKKKKK
740 @c LLLLLLLLLLLLLLLLLLLLLLLLLL
742 @item .ldouble @var{expression} [, @var{expression}]*
745 @cindex @code{.ltorg} directive, ARM
747 This directive causes the current contents of the literal pool to be
748 dumped into the current section (which is assumed to be the .text
749 section) at the current location (aligned to a word boundary).
750 @code{GAS} maintains a separate literal pool for each section and each
751 sub-section. The @code{.ltorg} directive will only affect the literal
752 pool of the current section and sub-section. At the end of assembly
753 all remaining, un-empty literal pools will automatically be dumped.
755 Note - older versions of @code{GAS} would dump the current literal
756 pool any time a section change occurred. This is no longer done, since
757 it prevents accurate control of the placement of literal pools.
759 @c MMMMMMMMMMMMMMMMMMMMMMMMMM
761 @cindex @code{.movsp} directive, ARM
762 @item .movsp @var{reg} [, #@var{offset}]
763 Tell the unwinder that @var{reg} contains an offset from the current
764 stack pointer. If @var{offset} is not specified then it is assumed to be
767 @c NNNNNNNNNNNNNNNNNNNNNNNNNN
768 @c OOOOOOOOOOOOOOOOOOOOOOOOOO
770 @cindex @code{.object_arch} directive, ARM
771 @item .object_arch @var{name}
772 Override the architecture recorded in the EABI object attribute section.
773 Valid values for @var{name} are the same as for the @code{.arch} directive.
774 Typically this is useful when code uses runtime detection of CPU features.
776 @c PPPPPPPPPPPPPPPPPPPPPPPPPP
778 @cindex @code{.packed} directive, ARM
779 @item .packed @var{expression} [, @var{expression}]*
780 This directive writes 12-byte packed floating-point values to the
781 output section. These are not compatible with current ARM processors
785 @cindex @code{.pad} directive, ARM
786 @item .pad #@var{count}
787 Generate unwinder annotations for a stack adjustment of @var{count} bytes.
788 A positive value indicates the function prologue allocated stack space by
789 decrementing the stack pointer.
791 @cindex @code{.personality} directive, ARM
792 @item .personality @var{name}
793 Sets the personality routine for the current function to @var{name}.
795 @cindex @code{.personalityindex} directive, ARM
796 @item .personalityindex @var{index}
797 Sets the personality routine for the current function to the EABI standard
798 routine number @var{index}
800 @cindex @code{.pool} directive, ARM
802 This is a synonym for .ltorg.
804 @c QQQQQQQQQQQQQQQQQQQQQQQQQQ
805 @c RRRRRRRRRRRRRRRRRRRRRRRRRR
807 @cindex @code{.req} directive, ARM
808 @item @var{name} .req @var{register name}
809 This creates an alias for @var{register name} called @var{name}. For
816 @c SSSSSSSSSSSSSSSSSSSSSSSSSS
819 @cindex @code{.save} directive, ARM
820 @item .save @var{reglist}
821 Generate unwinder annotations to restore the registers in @var{reglist}.
822 The format of @var{reglist} is the same as the corresponding store-multiple
826 @exdent @emph{core registers}
827 .save @{r4, r5, r6, lr@}
828 stmfd sp!, @{r4, r5, r6, lr@}
829 @exdent @emph{FPA registers}
832 @exdent @emph{VFP registers}
833 .save @{d8, d9, d10@}
834 fstmdx sp!, @{d8, d9, d10@}
835 @exdent @emph{iWMMXt registers}
837 wstrd wr11, [sp, #-8]!
838 wstrd wr10, [sp, #-8]!
841 wstrd wr11, [sp, #-8]!
843 wstrd wr10, [sp, #-8]!
847 @cindex @code{.setfp} directive, ARM
848 @item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}]
849 Make all unwinder annotations relative to a frame pointer. Without this
850 the unwinder will use offsets from the stack pointer.
852 The syntax of this directive is the same as the @code{add} or @code{mov}
853 instruction used to set the frame pointer. @var{spreg} must be either
854 @code{sp} or mentioned in a previous @code{.movsp} directive.
864 @cindex @code{.secrel32} directive, ARM
865 @item .secrel32 @var{expression} [, @var{expression}]*
866 This directive emits relocations that evaluate to the section-relative
867 offset of each expression's symbol. This directive is only supported
870 @cindex @code{.syntax} directive, ARM
871 @item .syntax [@code{unified} | @code{divided}]
872 This directive sets the Instruction Set Syntax as described in the
873 @ref{ARM-Instruction-Set} section.
875 @c TTTTTTTTTTTTTTTTTTTTTTTTTT
877 @cindex @code{.thumb} directive, ARM
879 This performs the same action as @var{.code 16}.
881 @cindex @code{.thumb_func} directive, ARM
883 This directive specifies that the following symbol is the name of a
884 Thumb encoded function. This information is necessary in order to allow
885 the assembler and linker to generate correct code for interworking
886 between Arm and Thumb instructions and should be used even if
887 interworking is not going to be performed. The presence of this
888 directive also implies @code{.thumb}
890 This directive is not neccessary when generating EABI objects. On these
891 targets the encoding is implicit when generating Thumb code.
893 @cindex @code{.thumb_set} directive, ARM
895 This performs the equivalent of a @code{.set} directive in that it
896 creates a symbol which is an alias for another symbol (possibly not yet
897 defined). This directive also has the added property in that it marks
898 the aliased symbol as being a thumb function entry point, in the same
899 way that the @code{.thumb_func} directive does.
901 @cindex @code{.tlsdescseq} directive, ARM
902 @item .tlsdescseq @var{tls-variable}
903 This directive is used to annotate parts of an inlined TLS descriptor
904 trampoline. Normally the trampoline is provided by the linker, and
905 this directive is not needed.
907 @c UUUUUUUUUUUUUUUUUUUUUUUUUU
909 @cindex @code{.unreq} directive, ARM
910 @item .unreq @var{alias-name}
911 This undefines a register alias which was previously defined using the
912 @code{req}, @code{dn} or @code{qn} directives. For example:
919 An error occurs if the name is undefined. Note - this pseudo op can
920 be used to delete builtin in register name aliases (eg 'r0'). This
921 should only be done if it is really necessary.
923 @cindex @code{.unwind_raw} directive, ARM
924 @item .unwind_raw @var{offset}, @var{byte1}, @dots{}
925 Insert one of more arbitary unwind opcode bytes, which are known to adjust
926 the stack pointer by @var{offset} bytes.
928 For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to
931 @c VVVVVVVVVVVVVVVVVVVVVVVVVV
933 @cindex @code{.vsave} directive, ARM
934 @item .vsave @var{vfp-reglist}
935 Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist}
936 using FLDMD. Also works for VFPv3 registers
937 that are to be restored using VLDM.
938 The format of @var{vfp-reglist} is the same as the corresponding store-multiple
942 @exdent @emph{VFP registers}
943 .vsave @{d8, d9, d10@}
944 fstmdd sp!, @{d8, d9, d10@}
945 @exdent @emph{VFPv3 registers}
946 .vsave @{d15, d16, d17@}
947 vstm sp!, @{d15, d16, d17@}
950 Since FLDMX and FSTMX are now deprecated, this directive should be
951 used in favour of @code{.save} for saving VFP registers for ARMv6 and above.
953 @c WWWWWWWWWWWWWWWWWWWWWWWWWW
954 @c XXXXXXXXXXXXXXXXXXXXXXXXXX
955 @c YYYYYYYYYYYYYYYYYYYYYYYYYY
956 @c ZZZZZZZZZZZZZZZZZZZZZZZZZZ
964 @cindex opcodes for ARM
965 @code{@value{AS}} implements all the standard ARM opcodes. It also
966 implements several pseudo opcodes, including several synthetic load
971 @cindex @code{NOP} pseudo op, ARM
977 This pseudo op will always evaluate to a legal ARM instruction that does
978 nothing. Currently it will evaluate to MOV r0, r0.
980 @cindex @code{LDR reg,=<label>} pseudo op, ARM
983 ldr <register> , = <expression>
986 If expression evaluates to a numeric constant then a MOV or MVN
987 instruction will be used in place of the LDR instruction, if the
988 constant can be generated by either of these instructions. Otherwise
989 the constant will be placed into the nearest literal pool (if it not
990 already there) and a PC relative LDR instruction will be generated.
992 @cindex @code{ADR reg,<label>} pseudo op, ARM
995 adr <register> <label>
998 This instruction will load the address of @var{label} into the indicated
999 register. The instruction will evaluate to a PC relative ADD or SUB
1000 instruction depending upon where the label is located. If the label is
1001 out of range, or if it is not defined in the same file (and section) as
1002 the ADR instruction, then an error will be generated. This instruction
1003 will not make use of the literal pool.
1005 @cindex @code{ADRL reg,<label>} pseudo op, ARM
1008 adrl <register> <label>
1011 This instruction will load the address of @var{label} into the indicated
1012 register. The instruction will evaluate to one or two PC relative ADD
1013 or SUB instructions depending upon where the label is located. If a
1014 second instruction is not needed a NOP instruction will be generated in
1015 its place, so that this instruction is always 8 bytes long.
1017 If the label is out of range, or if it is not defined in the same file
1018 (and section) as the ADRL instruction, then an error will be generated.
1019 This instruction will not make use of the literal pool.
1023 For information on the ARM or Thumb instruction sets, see @cite{ARM
1024 Software Development Toolkit Reference Manual}, Advanced RISC Machines
1027 @node ARM Mapping Symbols
1028 @section Mapping Symbols
1030 The ARM ELF specification requires that special symbols be inserted
1031 into object files to mark certain features:
1037 At the start of a region of code containing ARM instructions.
1041 At the start of a region of code containing THUMB instructions.
1045 At the start of a region of data.
1049 The assembler will automatically insert these symbols for you - there
1050 is no need to code them yourself. Support for tagging symbols ($b,
1051 $f, $p and $m) which is also mentioned in the current ARM ELF
1052 specification is not implemented. This is because they have been
1053 dropped from the new EABI and so tools cannot rely upon their
1056 @node ARM Unwinding Tutorial
1059 The ABI for the ARM Architecture specifies a standard format for
1060 exception unwind information. This information is used when an
1061 exception is thrown to determine where control should be transferred.
1062 In particular, the unwind information is used to determine which
1063 function called the function that threw the exception, and which
1064 function called that one, and so forth. This information is also used
1065 to restore the values of callee-saved registers in the function
1066 catching the exception.
1068 If you are writing functions in assembly code, and those functions
1069 call other functions that throw exceptions, you must use assembly
1070 pseudo ops to ensure that appropriate exception unwind information is
1071 generated. Otherwise, if one of the functions called by your assembly
1072 code throws an exception, the run-time library will be unable to
1073 unwind the stack through your assembly code and your program will not
1076 To illustrate the use of these pseudo ops, we will examine the code
1077 that G++ generates for the following C++ input:
1080 void callee (int *);
1091 This example does not show how to throw or catch an exception from
1092 assembly code. That is a much more complex operation and should
1093 always be done in a high-level language, such as C++, that directly
1094 supports exceptions.
1096 The code generated by one particular version of G++ when compiling the
1103 @ Function supports interworking.
1104 @ args = 0, pretend = 0, frame = 8
1105 @ frame_needed = 1, uses_anonymous_args = 0
1127 Of course, the sequence of instructions varies based on the options
1128 you pass to GCC and on the version of GCC in use. The exact
1129 instructions are not important since we are focusing on the pseudo ops
1130 that are used to generate unwind information.
1132 An important assumption made by the unwinder is that the stack frame
1133 does not change during the body of the function. In particular, since
1134 we assume that the assembly code does not itself throw an exception,
1135 the only point where an exception can be thrown is from a call, such
1136 as the @code{bl} instruction above. At each call site, the same saved
1137 registers (including @code{lr}, which indicates the return address)
1138 must be located in the same locations relative to the frame pointer.
1140 The @code{.fnstart} (@pxref{arm_fnstart,,.fnstart pseudo op}) pseudo
1141 op appears immediately before the first instruction of the function
1142 while the @code{.fnend} (@pxref{arm_fnend,,.fnend pseudo op}) pseudo
1143 op appears immediately after the last instruction of the function.
1144 These pseudo ops specify the range of the function.
1146 Only the order of the other pseudos ops (e.g., @code{.setfp} or
1147 @code{.pad}) matters; their exact locations are irrelevant. In the
1148 example above, the compiler emits the pseudo ops with particular
1149 instructions. That makes it easier to understand the code, but it is
1150 not required for correctness. It would work just as well to emit all
1151 of the pseudo ops other than @code{.fnend} in the same order, but
1152 immediately after @code{.fnstart}.
1154 The @code{.save} (@pxref{arm_save,,.save pseudo op}) pseudo op
1155 indicates registers that have been saved to the stack so that they can
1156 be restored before the function returns. The argument to the
1157 @code{.save} pseudo op is a list of registers to save. If a register
1158 is ``callee-saved'' (as specified by the ABI) and is modified by the
1159 function you are writing, then your code must save the value before it
1160 is modified and restore the original value before the function
1161 returns. If an exception is thrown, the run-time library restores the
1162 values of these registers from their locations on the stack before
1163 returning control to the exception handler. (Of course, if an
1164 exception is not thrown, the function that contains the @code{.save}
1165 pseudo op restores these registers in the function epilogue, as is
1166 done with the @code{ldmfd} instruction above.)
1168 You do not have to save callee-saved registers at the very beginning
1169 of the function and you do not need to use the @code{.save} pseudo op
1170 immediately following the point at which the registers are saved.
1171 However, if you modify a callee-saved register, you must save it on
1172 the stack before modifying it and before calling any functions which
1173 might throw an exception. And, you must use the @code{.save} pseudo
1174 op to indicate that you have done so.
1176 The @code{.pad} (@pxref{arm_pad,,.pad}) pseudo op indicates a
1177 modification of the stack pointer that does not save any registers.
1178 The argument is the number of bytes (in decimal) that are subtracted
1179 from the stack pointer. (On ARM CPUs, the stack grows downwards, so
1180 subtracting from the stack pointer increases the size of the stack.)
1182 The @code{.setfp} (@pxref{arm_setfp,,.setfp pseudo op}) pseudo op
1183 indicates the register that contains the frame pointer. The first
1184 argument is the register that is set, which is typically @code{fp}.
1185 The second argument indicates the register from which the frame
1186 pointer takes its value. The third argument, if present, is the value
1187 (in decimal) added to the register specified by the second argument to
1188 compute the value of the frame pointer. You should not modify the
1189 frame pointer in the body of the function.
1191 If you do not use a frame pointer, then you should not use the
1192 @code{.setfp} pseudo op. If you do not use a frame pointer, then you
1193 should avoid modifying the stack pointer outside of the function
1194 prologue. Otherwise, the run-time library will be unable to find
1195 saved registers when it is unwinding the stack.
1197 The pseudo ops described above are sufficient for writing assembly
1198 code that calls functions which may throw exceptions. If you need to
1199 know more about the object-file format used to represent unwind
1200 information, you may consult the @cite{Exception Handling ABI for the
1201 ARM Architecture} available from @uref{http://infocenter.arm.com}.