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),
131 @code{cortex-m0plus},
133 @code{marvell-whitney},
136 @code{ep9312} (ARM920 with Cirrus Maverick coprocessor),
137 @code{i80200} (Intel XScale processor)
138 @code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor)
141 The special name @code{all} may be used to allow the
142 assembler to accept instructions valid for any ARM processor.
144 In addition to the basic instruction set, the assembler can be told to
145 accept various extension mnemonics that extend the processor using the
146 co-processor instruction space. For example, @code{-mcpu=arm920+maverick}
147 is equivalent to specifying @code{-mcpu=ep9312}.
149 Multiple extensions may be specified, separated by a @code{+}. The
150 extensions should be specified in ascending alphabetical order.
152 Some extensions may be restricted to particular architectures; this is
153 documented in the list of extensions below.
155 Extension mnemonics may also be removed from those the assembler accepts.
156 This is done be prepending @code{no} to the option that adds the extension.
157 Extensions that are removed should be listed after all extensions which have
158 been added, again in ascending alphabetical order. For example,
159 @code{-mcpu=ep9312+nomaverick} is equivalent to specifying @code{-mcpu=arm920}.
162 The following extensions are currently supported:
164 @code{crypto} (Cryptography Extensions for v8-A architecture, implies @code{fp+simd}),
165 @code{fp} (Floating Point Extensions for v8-A architecture),
166 @code{idiv} (Integer Divide Extensions for v7-A and v7-R architectures),
171 @code{mp} (Multiprocessing Extensions for v7-A and v7-R
173 @code{os} (Operating System for v6M architecture),
174 @code{sec} (Security Extensions for v6K and v7-A architectures),
175 @code{simd} (Advanced SIMD Extensions for v8-A architecture, implies @code{fp}),
176 @code{virt} (Virtualization Extensions for v7-A architecture, implies
181 @cindex @code{-march=} command line option, ARM
182 @item -march=@var{architecture}[+@var{extension}@dots{}]
183 This option specifies the target architecture. The assembler will issue
184 an error message if an attempt is made to assemble an instruction which
185 will not execute on the target architecture. The following architecture
186 names are recognized:
220 If both @code{-mcpu} and
221 @code{-march} are specified, the assembler will use
222 the setting for @code{-mcpu}.
224 The architecture option can be extended with the same instruction set
225 extension options as the @code{-mcpu} option.
227 @cindex @code{-mfpu=} command line option, ARM
228 @item -mfpu=@var{floating-point-format}
230 This option specifies the floating point format to assemble for. The
231 assembler will issue an error message if an attempt is made to assemble
232 an instruction which will not execute on the target floating point unit.
233 The following format options are recognized:
253 @code{vfpv3-d16-fp16},
268 @code{neon-fp-armv8},
270 @code{crypto-neon-fp-armv8}.
272 In addition to determining which instructions are assembled, this option
273 also affects the way in which the @code{.double} assembler directive behaves
274 when assembling little-endian code.
276 The default is dependent on the processor selected. For Architecture 5 or
277 later, the default is to assembler for VFP instructions; for earlier
278 architectures the default is to assemble for FPA instructions.
280 @cindex @code{-mthumb} command line option, ARM
282 This option specifies that the assembler should start assembling Thumb
283 instructions; that is, it should behave as though the file starts with a
284 @code{.code 16} directive.
286 @cindex @code{-mthumb-interwork} command line option, ARM
287 @item -mthumb-interwork
288 This option specifies that the output generated by the assembler should
289 be marked as supporting interworking.
291 @cindex @code{-mimplicit-it} command line option, ARM
292 @item -mimplicit-it=never
293 @itemx -mimplicit-it=always
294 @itemx -mimplicit-it=arm
295 @itemx -mimplicit-it=thumb
296 The @code{-mimplicit-it} option controls the behavior of the assembler when
297 conditional instructions are not enclosed in IT blocks.
298 There are four possible behaviors.
299 If @code{never} is specified, such constructs cause a warning in ARM
300 code and an error in Thumb-2 code.
301 If @code{always} is specified, such constructs are accepted in both
302 ARM and Thumb-2 code, where the IT instruction is added implicitly.
303 If @code{arm} is specified, such constructs are accepted in ARM code
304 and cause an error in Thumb-2 code.
305 If @code{thumb} is specified, such constructs cause a warning in ARM
306 code and are accepted in Thumb-2 code. If you omit this option, the
307 behavior is equivalent to @code{-mimplicit-it=arm}.
309 @cindex @code{-mapcs-26} command line option, ARM
310 @cindex @code{-mapcs-32} command line option, ARM
313 These options specify that the output generated by the assembler should
314 be marked as supporting the indicated version of the Arm Procedure.
317 @cindex @code{-matpcs} command line option, ARM
319 This option specifies that the output generated by the assembler should
320 be marked as supporting the Arm/Thumb Procedure Calling Standard. If
321 enabled this option will cause the assembler to create an empty
322 debugging section in the object file called .arm.atpcs. Debuggers can
323 use this to determine the ABI being used by.
325 @cindex @code{-mapcs-float} command line option, ARM
327 This indicates the floating point variant of the APCS should be
328 used. In this variant floating point arguments are passed in FP
329 registers rather than integer registers.
331 @cindex @code{-mapcs-reentrant} command line option, ARM
332 @item -mapcs-reentrant
333 This indicates that the reentrant variant of the APCS should be used.
334 This variant supports position independent code.
336 @cindex @code{-mfloat-abi=} command line option, ARM
337 @item -mfloat-abi=@var{abi}
338 This option specifies that the output generated by the assembler should be
339 marked as using specified floating point ABI.
340 The following values are recognized:
346 @cindex @code{-eabi=} command line option, ARM
347 @item -meabi=@var{ver}
348 This option specifies which EABI version the produced object files should
350 The following values are recognized:
356 @cindex @code{-EB} command line option, ARM
358 This option specifies that the output generated by the assembler should
359 be marked as being encoded for a big-endian processor.
361 @cindex @code{-EL} command line option, ARM
363 This option specifies that the output generated by the assembler should
364 be marked as being encoded for a little-endian processor.
366 @cindex @code{-k} command line option, ARM
367 @cindex PIC code generation for ARM
369 This option specifies that the output of the assembler should be marked
370 as position-independent code (PIC).
372 @cindex @code{--fix-v4bx} command line option, ARM
374 Allow @code{BX} instructions in ARMv4 code. This is intended for use with
375 the linker option of the same name.
377 @cindex @code{-mwarn-deprecated} command line option, ARM
378 @item -mwarn-deprecated
379 @itemx -mno-warn-deprecated
380 Enable or disable warnings about using deprecated options or
381 features. The default is to warn.
383 @cindex @code{-mccs} command line option, ARM
385 Turns on CodeComposer Studio assembly syntax compatibility mode.
393 * ARM-Instruction-Set:: Instruction Set
394 * ARM-Chars:: Special Characters
395 * ARM-Regs:: Register Names
396 * ARM-Relocations:: Relocations
397 * ARM-Neon-Alignment:: NEON Alignment Specifiers
400 @node ARM-Instruction-Set
401 @subsection Instruction Set Syntax
402 Two slightly different syntaxes are support for ARM and THUMB
403 instructions. The default, @code{divided}, uses the old style where
404 ARM and THUMB instructions had their own, separate syntaxes. The new,
405 @code{unified} syntax, which can be selected via the @code{.syntax}
406 directive, and has the following main features:
410 Immediate operands do not require a @code{#} prefix.
413 The @code{IT} instruction may appear, and if it does it is validated
414 against subsequent conditional affixes. In ARM mode it does not
415 generate machine code, in THUMB mode it does.
418 For ARM instructions the conditional affixes always appear at the end
419 of the instruction. For THUMB instructions conditional affixes can be
420 used, but only inside the scope of an @code{IT} instruction.
423 All of the instructions new to the V6T2 architecture (and later) are
424 available. (Only a few such instructions can be written in the
425 @code{divided} syntax).
428 The @code{.N} and @code{.W} suffixes are recognized and honored.
431 All instructions set the flags if and only if they have an @code{s}
436 @subsection Special Characters
438 @cindex line comment character, ARM
439 @cindex ARM line comment character
440 The presence of a @samp{@@} anywhere on a line indicates the start of
441 a comment that extends to the end of that line.
443 If a @samp{#} appears as the first character of a line then the whole
444 line is treated as a comment, but in this case the line could also be
445 a logical line number directive (@pxref{Comments}) or a preprocessor
446 control command (@pxref{Preprocessing}).
448 @cindex line separator, ARM
449 @cindex statement separator, ARM
450 @cindex ARM line separator
451 The @samp{;} character can be used instead of a newline to separate
454 @cindex immediate character, ARM
455 @cindex ARM immediate character
456 Either @samp{#} or @samp{$} can be used to indicate immediate operands.
458 @cindex identifiers, ARM
459 @cindex ARM identifiers
460 *TODO* Explain about /data modifier on symbols.
463 @subsection Register Names
465 @cindex ARM register names
466 @cindex register names, ARM
467 *TODO* Explain about ARM register naming, and the predefined names.
469 @node ARM-Relocations
470 @subsection ARM relocation generation
472 @cindex data relocations, ARM
473 @cindex ARM data relocations
474 Specific data relocations can be generated by putting the relocation name
475 in parentheses after the symbol name. For example:
481 This will generate an @samp{R_ARM_TARGET1} relocation against the symbol
483 The following relocations are supported:
499 For compatibility with older toolchains the assembler also accepts
500 @code{(PLT)} after branch targets. On legacy targets this will
501 generate the deprecated @samp{R_ARM_PLT32} relocation. On EABI
502 targets it will encode either the @samp{R_ARM_CALL} or
503 @samp{R_ARM_JUMP24} relocation, as appropriate.
505 @cindex MOVW and MOVT relocations, ARM
506 Relocations for @samp{MOVW} and @samp{MOVT} instructions can be generated
507 by prefixing the value with @samp{#:lower16:} and @samp{#:upper16}
508 respectively. For example to load the 32-bit address of foo into r0:
511 MOVW r0, #:lower16:foo
512 MOVT r0, #:upper16:foo
515 @node ARM-Neon-Alignment
516 @subsection NEON Alignment Specifiers
518 @cindex alignment for NEON instructions
519 Some NEON load/store instructions allow an optional address
521 The ARM documentation specifies that this is indicated by
522 @samp{@@ @var{align}}. However GAS already interprets
523 the @samp{@@} character as a "line comment" start,
524 so @samp{: @var{align}} is used instead. For example:
527 vld1.8 @{q0@}, [r0, :128]
530 @node ARM Floating Point
531 @section Floating Point
533 @cindex floating point, ARM (@sc{ieee})
534 @cindex ARM floating point (@sc{ieee})
535 The ARM family uses @sc{ieee} floating-point numbers.
538 @section ARM Machine Directives
540 @cindex machine directives, ARM
541 @cindex ARM machine directives
544 @c AAAAAAAAAAAAAAAAAAAAAAAAA
546 @cindex @code{.2byte} directive, ARM
547 @cindex @code{.4byte} directive, ARM
548 @cindex @code{.8byte} directive, ARM
549 @item .2byte @var{expression} [, @var{expression}]*
550 @itemx .4byte @var{expression} [, @var{expression}]*
551 @itemx .8byte @var{expression} [, @var{expression}]*
552 These directives write 2, 4 or 8 byte values to the output section.
554 @cindex @code{.align} directive, ARM
555 @item .align @var{expression} [, @var{expression}]
556 This is the generic @var{.align} directive. For the ARM however if the
557 first argument is zero (ie no alignment is needed) the assembler will
558 behave as if the argument had been 2 (ie pad to the next four byte
559 boundary). This is for compatibility with ARM's own assembler.
561 @cindex @code{.arch} directive, ARM
562 @item .arch @var{name}
563 Select the target architecture. Valid values for @var{name} are the same as
564 for the @option{-march} commandline option.
566 Specifying @code{.arch} clears any previously selected architecture
569 @cindex @code{.arch_extension} directive, ARM
570 @item .arch_extension @var{name}
571 Add or remove an architecture extension to the target architecture. Valid
572 values for @var{name} are the same as those accepted as architectural
573 extensions by the @option{-mcpu} commandline option.
575 @code{.arch_extension} may be used multiple times to add or remove extensions
576 incrementally to the architecture being compiled for.
578 @cindex @code{.arm} directive, ARM
580 This performs the same action as @var{.code 32}.
582 @c BBBBBBBBBBBBBBBBBBBBBBBBBB
584 @cindex @code{.bss} directive, ARM
586 This directive switches to the @code{.bss} section.
588 @c CCCCCCCCCCCCCCCCCCCCCCCCCC
590 @cindex @code{.cantunwind} directive, ARM
592 Prevents unwinding through the current function. No personality routine
593 or exception table data is required or permitted.
595 @cindex @code{.code} directive, ARM
596 @item .code @code{[16|32]}
597 This directive selects the instruction set being generated. The value 16
598 selects Thumb, with the value 32 selecting ARM.
600 @cindex @code{.cpu} directive, ARM
601 @item .cpu @var{name}
602 Select the target processor. Valid values for @var{name} are the same as
603 for the @option{-mcpu} commandline option.
605 Specifying @code{.cpu} clears any previously selected architecture
608 @c DDDDDDDDDDDDDDDDDDDDDDDDDD
610 @cindex @code{.dn} and @code{.qn} directives, ARM
611 @item @var{name} .dn @var{register name} [@var{.type}] [[@var{index}]]
612 @itemx @var{name} .qn @var{register name} [@var{.type}] [[@var{index}]]
614 The @code{dn} and @code{qn} directives are used to create typed
615 and/or indexed register aliases for use in Advanced SIMD Extension
616 (Neon) instructions. The former should be used to create aliases
617 of double-precision registers, and the latter to create aliases of
618 quad-precision registers.
620 If these directives are used to create typed aliases, those aliases can
621 be used in Neon instructions instead of writing types after the mnemonic
622 or after each operand. For example:
631 This is equivalent to writing the following:
637 Aliases created using @code{dn} or @code{qn} can be destroyed using
640 @c EEEEEEEEEEEEEEEEEEEEEEEEEE
642 @cindex @code{.eabi_attribute} directive, ARM
643 @item .eabi_attribute @var{tag}, @var{value}
644 Set the EABI object attribute @var{tag} to @var{value}.
646 The @var{tag} is either an attribute number, or one of the following:
647 @code{Tag_CPU_raw_name}, @code{Tag_CPU_name}, @code{Tag_CPU_arch},
648 @code{Tag_CPU_arch_profile}, @code{Tag_ARM_ISA_use},
649 @code{Tag_THUMB_ISA_use}, @code{Tag_FP_arch}, @code{Tag_WMMX_arch},
650 @code{Tag_Advanced_SIMD_arch}, @code{Tag_PCS_config},
651 @code{Tag_ABI_PCS_R9_use}, @code{Tag_ABI_PCS_RW_data},
652 @code{Tag_ABI_PCS_RO_data}, @code{Tag_ABI_PCS_GOT_use},
653 @code{Tag_ABI_PCS_wchar_t}, @code{Tag_ABI_FP_rounding},
654 @code{Tag_ABI_FP_denormal}, @code{Tag_ABI_FP_exceptions},
655 @code{Tag_ABI_FP_user_exceptions}, @code{Tag_ABI_FP_number_model},
656 @code{Tag_ABI_align_needed}, @code{Tag_ABI_align_preserved},
657 @code{Tag_ABI_enum_size}, @code{Tag_ABI_HardFP_use},
658 @code{Tag_ABI_VFP_args}, @code{Tag_ABI_WMMX_args},
659 @code{Tag_ABI_optimization_goals}, @code{Tag_ABI_FP_optimization_goals},
660 @code{Tag_compatibility}, @code{Tag_CPU_unaligned_access},
661 @code{Tag_FP_HP_extension}, @code{Tag_ABI_FP_16bit_format},
662 @code{Tag_MPextension_use}, @code{Tag_DIV_use},
663 @code{Tag_nodefaults}, @code{Tag_also_compatible_with},
664 @code{Tag_conformance}, @code{Tag_T2EE_use},
665 @code{Tag_Virtualization_use}
667 The @var{value} is either a @code{number}, @code{"string"}, or
668 @code{number, "string"} depending on the tag.
670 Note - the following legacy values are also accepted by @var{tag}:
671 @code{Tag_VFP_arch}, @code{Tag_ABI_align8_needed},
672 @code{Tag_ABI_align8_preserved}, @code{Tag_VFP_HP_extension},
674 @cindex @code{.even} directive, ARM
676 This directive aligns to an even-numbered address.
678 @cindex @code{.extend} directive, ARM
679 @cindex @code{.ldouble} directive, ARM
680 @item .extend @var{expression} [, @var{expression}]*
681 @itemx .ldouble @var{expression} [, @var{expression}]*
682 These directives write 12byte long double floating-point values to the
683 output section. These are not compatible with current ARM processors
686 @c FFFFFFFFFFFFFFFFFFFFFFFFFF
689 @cindex @code{.fnend} directive, ARM
691 Marks the end of a function with an unwind table entry. The unwind index
692 table entry is created when this directive is processed.
694 If no personality routine has been specified then standard personality
695 routine 0 or 1 will be used, depending on the number of unwind opcodes
699 @cindex @code{.fnstart} directive, ARM
701 Marks the start of a function with an unwind table entry.
703 @cindex @code{.force_thumb} directive, ARM
705 This directive forces the selection of Thumb instructions, even if the
706 target processor does not support those instructions
708 @cindex @code{.fpu} directive, ARM
709 @item .fpu @var{name}
710 Select the floating-point unit to assemble for. Valid values for @var{name}
711 are the same as for the @option{-mfpu} commandline option.
713 @c GGGGGGGGGGGGGGGGGGGGGGGGGG
714 @c HHHHHHHHHHHHHHHHHHHHHHHHHH
716 @cindex @code{.handlerdata} directive, ARM
718 Marks the end of the current function, and the start of the exception table
719 entry for that function. Anything between this directive and the
720 @code{.fnend} directive will be added to the exception table entry.
722 Must be preceded by a @code{.personality} or @code{.personalityindex}
725 @c IIIIIIIIIIIIIIIIIIIIIIIIII
727 @cindex @code{.inst} directive, ARM
728 @item .inst @var{opcode} [ , @dots{} ]
729 @itemx .inst.n @var{opcode} [ , @dots{} ]
730 @itemx .inst.w @var{opcode} [ , @dots{} ]
731 Generates the instruction corresponding to the numerical value @var{opcode}.
732 @code{.inst.n} and @code{.inst.w} allow the Thumb instruction size to be
733 specified explicitly, overriding the normal encoding rules.
735 @c JJJJJJJJJJJJJJJJJJJJJJJJJJ
736 @c KKKKKKKKKKKKKKKKKKKKKKKKKK
737 @c LLLLLLLLLLLLLLLLLLLLLLLLLL
739 @item .ldouble @var{expression} [, @var{expression}]*
742 @cindex @code{.ltorg} directive, ARM
744 This directive causes the current contents of the literal pool to be
745 dumped into the current section (which is assumed to be the .text
746 section) at the current location (aligned to a word boundary).
747 @code{GAS} maintains a separate literal pool for each section and each
748 sub-section. The @code{.ltorg} directive will only affect the literal
749 pool of the current section and sub-section. At the end of assembly
750 all remaining, un-empty literal pools will automatically be dumped.
752 Note - older versions of @code{GAS} would dump the current literal
753 pool any time a section change occurred. This is no longer done, since
754 it prevents accurate control of the placement of literal pools.
756 @c MMMMMMMMMMMMMMMMMMMMMMMMMM
758 @cindex @code{.movsp} directive, ARM
759 @item .movsp @var{reg} [, #@var{offset}]
760 Tell the unwinder that @var{reg} contains an offset from the current
761 stack pointer. If @var{offset} is not specified then it is assumed to be
764 @c NNNNNNNNNNNNNNNNNNNNNNNNNN
765 @c OOOOOOOOOOOOOOOOOOOOOOOOOO
767 @cindex @code{.object_arch} directive, ARM
768 @item .object_arch @var{name}
769 Override the architecture recorded in the EABI object attribute section.
770 Valid values for @var{name} are the same as for the @code{.arch} directive.
771 Typically this is useful when code uses runtime detection of CPU features.
773 @c PPPPPPPPPPPPPPPPPPPPPPPPPP
775 @cindex @code{.packed} directive, ARM
776 @item .packed @var{expression} [, @var{expression}]*
777 This directive writes 12-byte packed floating-point values to the
778 output section. These are not compatible with current ARM processors
782 @cindex @code{.pad} directive, ARM
783 @item .pad #@var{count}
784 Generate unwinder annotations for a stack adjustment of @var{count} bytes.
785 A positive value indicates the function prologue allocated stack space by
786 decrementing the stack pointer.
788 @cindex @code{.personality} directive, ARM
789 @item .personality @var{name}
790 Sets the personality routine for the current function to @var{name}.
792 @cindex @code{.personalityindex} directive, ARM
793 @item .personalityindex @var{index}
794 Sets the personality routine for the current function to the EABI standard
795 routine number @var{index}
797 @cindex @code{.pool} directive, ARM
799 This is a synonym for .ltorg.
801 @c QQQQQQQQQQQQQQQQQQQQQQQQQQ
802 @c RRRRRRRRRRRRRRRRRRRRRRRRRR
804 @cindex @code{.req} directive, ARM
805 @item @var{name} .req @var{register name}
806 This creates an alias for @var{register name} called @var{name}. For
813 @c SSSSSSSSSSSSSSSSSSSSSSSSSS
816 @cindex @code{.save} directive, ARM
817 @item .save @var{reglist}
818 Generate unwinder annotations to restore the registers in @var{reglist}.
819 The format of @var{reglist} is the same as the corresponding store-multiple
823 @exdent @emph{core registers}
824 .save @{r4, r5, r6, lr@}
825 stmfd sp!, @{r4, r5, r6, lr@}
826 @exdent @emph{FPA registers}
829 @exdent @emph{VFP registers}
830 .save @{d8, d9, d10@}
831 fstmdx sp!, @{d8, d9, d10@}
832 @exdent @emph{iWMMXt registers}
834 wstrd wr11, [sp, #-8]!
835 wstrd wr10, [sp, #-8]!
838 wstrd wr11, [sp, #-8]!
840 wstrd wr10, [sp, #-8]!
844 @cindex @code{.setfp} directive, ARM
845 @item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}]
846 Make all unwinder annotations relative to a frame pointer. Without this
847 the unwinder will use offsets from the stack pointer.
849 The syntax of this directive is the same as the @code{add} or @code{mov}
850 instruction used to set the frame pointer. @var{spreg} must be either
851 @code{sp} or mentioned in a previous @code{.movsp} directive.
861 @cindex @code{.secrel32} directive, ARM
862 @item .secrel32 @var{expression} [, @var{expression}]*
863 This directive emits relocations that evaluate to the section-relative
864 offset of each expression's symbol. This directive is only supported
867 @cindex @code{.syntax} directive, ARM
868 @item .syntax [@code{unified} | @code{divided}]
869 This directive sets the Instruction Set Syntax as described in the
870 @ref{ARM-Instruction-Set} section.
872 @c TTTTTTTTTTTTTTTTTTTTTTTTTT
874 @cindex @code{.thumb} directive, ARM
876 This performs the same action as @var{.code 16}.
878 @cindex @code{.thumb_func} directive, ARM
880 This directive specifies that the following symbol is the name of a
881 Thumb encoded function. This information is necessary in order to allow
882 the assembler and linker to generate correct code for interworking
883 between Arm and Thumb instructions and should be used even if
884 interworking is not going to be performed. The presence of this
885 directive also implies @code{.thumb}
887 This directive is not neccessary when generating EABI objects. On these
888 targets the encoding is implicit when generating Thumb code.
890 @cindex @code{.thumb_set} directive, ARM
892 This performs the equivalent of a @code{.set} directive in that it
893 creates a symbol which is an alias for another symbol (possibly not yet
894 defined). This directive also has the added property in that it marks
895 the aliased symbol as being a thumb function entry point, in the same
896 way that the @code{.thumb_func} directive does.
898 @cindex @code{.tlsdescseq} directive, ARM
899 @item .tlsdescseq @var{tls-variable}
900 This directive is used to annotate parts of an inlined TLS descriptor
901 trampoline. Normally the trampoline is provided by the linker, and
902 this directive is not needed.
904 @c UUUUUUUUUUUUUUUUUUUUUUUUUU
906 @cindex @code{.unreq} directive, ARM
907 @item .unreq @var{alias-name}
908 This undefines a register alias which was previously defined using the
909 @code{req}, @code{dn} or @code{qn} directives. For example:
916 An error occurs if the name is undefined. Note - this pseudo op can
917 be used to delete builtin in register name aliases (eg 'r0'). This
918 should only be done if it is really necessary.
920 @cindex @code{.unwind_raw} directive, ARM
921 @item .unwind_raw @var{offset}, @var{byte1}, @dots{}
922 Insert one of more arbitary unwind opcode bytes, which are known to adjust
923 the stack pointer by @var{offset} bytes.
925 For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to
928 @c VVVVVVVVVVVVVVVVVVVVVVVVVV
930 @cindex @code{.vsave} directive, ARM
931 @item .vsave @var{vfp-reglist}
932 Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist}
933 using FLDMD. Also works for VFPv3 registers
934 that are to be restored using VLDM.
935 The format of @var{vfp-reglist} is the same as the corresponding store-multiple
939 @exdent @emph{VFP registers}
940 .vsave @{d8, d9, d10@}
941 fstmdd sp!, @{d8, d9, d10@}
942 @exdent @emph{VFPv3 registers}
943 .vsave @{d15, d16, d17@}
944 vstm sp!, @{d15, d16, d17@}
947 Since FLDMX and FSTMX are now deprecated, this directive should be
948 used in favour of @code{.save} for saving VFP registers for ARMv6 and above.
950 @c WWWWWWWWWWWWWWWWWWWWWWWWWW
951 @c XXXXXXXXXXXXXXXXXXXXXXXXXX
952 @c YYYYYYYYYYYYYYYYYYYYYYYYYY
953 @c ZZZZZZZZZZZZZZZZZZZZZZZZZZ
961 @cindex opcodes for ARM
962 @code{@value{AS}} implements all the standard ARM opcodes. It also
963 implements several pseudo opcodes, including several synthetic load
968 @cindex @code{NOP} pseudo op, ARM
974 This pseudo op will always evaluate to a legal ARM instruction that does
975 nothing. Currently it will evaluate to MOV r0, r0.
977 @cindex @code{LDR reg,=<label>} pseudo op, ARM
980 ldr <register> , = <expression>
983 If expression evaluates to a numeric constant then a MOV or MVN
984 instruction will be used in place of the LDR instruction, if the
985 constant can be generated by either of these instructions. Otherwise
986 the constant will be placed into the nearest literal pool (if it not
987 already there) and a PC relative LDR instruction will be generated.
989 @cindex @code{ADR reg,<label>} pseudo op, ARM
992 adr <register> <label>
995 This instruction will load the address of @var{label} into the indicated
996 register. The instruction will evaluate to a PC relative ADD or SUB
997 instruction depending upon where the label is located. If the label is
998 out of range, or if it is not defined in the same file (and section) as
999 the ADR instruction, then an error will be generated. This instruction
1000 will not make use of the literal pool.
1002 @cindex @code{ADRL reg,<label>} pseudo op, ARM
1005 adrl <register> <label>
1008 This instruction will load the address of @var{label} into the indicated
1009 register. The instruction will evaluate to one or two PC relative ADD
1010 or SUB instructions depending upon where the label is located. If a
1011 second instruction is not needed a NOP instruction will be generated in
1012 its place, so that this instruction is always 8 bytes long.
1014 If the label is out of range, or if it is not defined in the same file
1015 (and section) as the ADRL instruction, then an error will be generated.
1016 This instruction will not make use of the literal pool.
1020 For information on the ARM or Thumb instruction sets, see @cite{ARM
1021 Software Development Toolkit Reference Manual}, Advanced RISC Machines
1024 @node ARM Mapping Symbols
1025 @section Mapping Symbols
1027 The ARM ELF specification requires that special symbols be inserted
1028 into object files to mark certain features:
1034 At the start of a region of code containing ARM instructions.
1038 At the start of a region of code containing THUMB instructions.
1042 At the start of a region of data.
1046 The assembler will automatically insert these symbols for you - there
1047 is no need to code them yourself. Support for tagging symbols ($b,
1048 $f, $p and $m) which is also mentioned in the current ARM ELF
1049 specification is not implemented. This is because they have been
1050 dropped from the new EABI and so tools cannot rely upon their
1053 @node ARM Unwinding Tutorial
1056 The ABI for the ARM Architecture specifies a standard format for
1057 exception unwind information. This information is used when an
1058 exception is thrown to determine where control should be transferred.
1059 In particular, the unwind information is used to determine which
1060 function called the function that threw the exception, and which
1061 function called that one, and so forth. This information is also used
1062 to restore the values of callee-saved registers in the function
1063 catching the exception.
1065 If you are writing functions in assembly code, and those functions
1066 call other functions that throw exceptions, you must use assembly
1067 pseudo ops to ensure that appropriate exception unwind information is
1068 generated. Otherwise, if one of the functions called by your assembly
1069 code throws an exception, the run-time library will be unable to
1070 unwind the stack through your assembly code and your program will not
1073 To illustrate the use of these pseudo ops, we will examine the code
1074 that G++ generates for the following C++ input:
1077 void callee (int *);
1088 This example does not show how to throw or catch an exception from
1089 assembly code. That is a much more complex operation and should
1090 always be done in a high-level language, such as C++, that directly
1091 supports exceptions.
1093 The code generated by one particular version of G++ when compiling the
1100 @ Function supports interworking.
1101 @ args = 0, pretend = 0, frame = 8
1102 @ frame_needed = 1, uses_anonymous_args = 0
1124 Of course, the sequence of instructions varies based on the options
1125 you pass to GCC and on the version of GCC in use. The exact
1126 instructions are not important since we are focusing on the pseudo ops
1127 that are used to generate unwind information.
1129 An important assumption made by the unwinder is that the stack frame
1130 does not change during the body of the function. In particular, since
1131 we assume that the assembly code does not itself throw an exception,
1132 the only point where an exception can be thrown is from a call, such
1133 as the @code{bl} instruction above. At each call site, the same saved
1134 registers (including @code{lr}, which indicates the return address)
1135 must be located in the same locations relative to the frame pointer.
1137 The @code{.fnstart} (@pxref{arm_fnstart,,.fnstart pseudo op}) pseudo
1138 op appears immediately before the first instruction of the function
1139 while the @code{.fnend} (@pxref{arm_fnend,,.fnend pseudo op}) pseudo
1140 op appears immediately after the last instruction of the function.
1141 These pseudo ops specify the range of the function.
1143 Only the order of the other pseudos ops (e.g., @code{.setfp} or
1144 @code{.pad}) matters; their exact locations are irrelevant. In the
1145 example above, the compiler emits the pseudo ops with particular
1146 instructions. That makes it easier to understand the code, but it is
1147 not required for correctness. It would work just as well to emit all
1148 of the pseudo ops other than @code{.fnend} in the same order, but
1149 immediately after @code{.fnstart}.
1151 The @code{.save} (@pxref{arm_save,,.save pseudo op}) pseudo op
1152 indicates registers that have been saved to the stack so that they can
1153 be restored before the function returns. The argument to the
1154 @code{.save} pseudo op is a list of registers to save. If a register
1155 is ``callee-saved'' (as specified by the ABI) and is modified by the
1156 function you are writing, then your code must save the value before it
1157 is modified and restore the original value before the function
1158 returns. If an exception is thrown, the run-time library restores the
1159 values of these registers from their locations on the stack before
1160 returning control to the exception handler. (Of course, if an
1161 exception is not thrown, the function that contains the @code{.save}
1162 pseudo op restores these registers in the function epilogue, as is
1163 done with the @code{ldmfd} instruction above.)
1165 You do not have to save callee-saved registers at the very beginning
1166 of the function and you do not need to use the @code{.save} pseudo op
1167 immediately following the point at which the registers are saved.
1168 However, if you modify a callee-saved register, you must save it on
1169 the stack before modifying it and before calling any functions which
1170 might throw an exception. And, you must use the @code{.save} pseudo
1171 op to indicate that you have done so.
1173 The @code{.pad} (@pxref{arm_pad,,.pad}) pseudo op indicates a
1174 modification of the stack pointer that does not save any registers.
1175 The argument is the number of bytes (in decimal) that are subtracted
1176 from the stack pointer. (On ARM CPUs, the stack grows downwards, so
1177 subtracting from the stack pointer increases the size of the stack.)
1179 The @code{.setfp} (@pxref{arm_setfp,,.setfp pseudo op}) pseudo op
1180 indicates the register that contains the frame pointer. The first
1181 argument is the register that is set, which is typically @code{fp}.
1182 The second argument indicates the register from which the frame
1183 pointer takes its value. The third argument, if present, is the value
1184 (in decimal) added to the register specified by the second argument to
1185 compute the value of the frame pointer. You should not modify the
1186 frame pointer in the body of the function.
1188 If you do not use a frame pointer, then you should not use the
1189 @code{.setfp} pseudo op. If you do not use a frame pointer, then you
1190 should avoid modifying the stack pointer outside of the function
1191 prologue. Otherwise, the run-time library will be unable to find
1192 saved registers when it is unwinding the stack.
1194 The pseudo ops described above are sufficient for writing assembly
1195 code that calls functions which may throw exceptions. If you need to
1196 know more about the object-file format used to represent unwind
1197 information, you may consult the @cite{Exception Handling ABI for the
1198 ARM Architecture} available from @uref{http://infocenter.arm.com}.
projects / deliverable / binutils-gdb.git / blob