1 @c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
2 @c 2006, 2007, 2008, 2009 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
26 * ARM Unwinding Tutorial:: Unwinding
31 @cindex ARM options (none)
32 @cindex options for ARM (none)
36 @cindex @code{-mcpu=} command line option, ARM
37 @item -mcpu=@var{processor}[+@var{extension}@dots{}]
38 This option specifies the target processor. The assembler will issue an
39 error message if an attempt is made to assemble an instruction which
40 will not execute on the target processor. The following processor names are
85 @code{fa526} (Faraday FA526 processor),
86 @code{fa626} (Faraday FA626 processor),
105 @code{fa626te} (Faraday FA626TE processor),
106 @code{fa726te} (Faraday FA726TE processor),
121 @code{ep9312} (ARM920 with Cirrus Maverick coprocessor),
122 @code{i80200} (Intel XScale processor)
123 @code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor)
126 The special name @code{all} may be used to allow the
127 assembler to accept instructions valid for any ARM processor.
129 In addition to the basic instruction set, the assembler can be told to
130 accept various extension mnemonics that extend the processor using the
131 co-processor instruction space. For example, @code{-mcpu=arm920+maverick}
132 is equivalent to specifying @code{-mcpu=ep9312}. The following extensions
133 are currently supported:
139 @cindex @code{-march=} command line option, ARM
140 @item -march=@var{architecture}[+@var{extension}@dots{}]
141 This option specifies the target architecture. The assembler will issue
142 an error message if an attempt is made to assemble an instruction which
143 will not execute on the target architecture. The following architecture
144 names are recognized:
172 If both @code{-mcpu} and
173 @code{-march} are specified, the assembler will use
174 the setting for @code{-mcpu}.
176 The architecture option can be extended with the same instruction set
177 extension options as the @code{-mcpu} option.
179 @cindex @code{-mfpu=} command line option, ARM
180 @item -mfpu=@var{floating-point-format}
182 This option specifies the floating point format to assemble for. The
183 assembler will issue an error message if an attempt is made to assemble
184 an instruction which will not execute on the target floating point unit.
185 The following format options are recognized:
211 In addition to determining which instructions are assembled, this option
212 also affects the way in which the @code{.double} assembler directive behaves
213 when assembling little-endian code.
215 The default is dependent on the processor selected. For Architecture 5 or
216 later, the default is to assembler for VFP instructions; for earlier
217 architectures the default is to assemble for FPA instructions.
219 @cindex @code{-mthumb} command line option, ARM
221 This option specifies that the assembler should start assembling Thumb
222 instructions; that is, it should behave as though the file starts with a
223 @code{.code 16} directive.
225 @cindex @code{-mthumb-interwork} command line option, ARM
226 @item -mthumb-interwork
227 This option specifies that the output generated by the assembler should
228 be marked as supporting interworking.
230 @cindex @code{-mimplicit-it} command line option, ARM
231 @item -mimplicit-it=never
232 @itemx -mimplicit-it=always
233 @itemx -mimplicit-it=arm
234 @itemx -mimplicit-it=thumb
235 The @code{-mimplicit-it} option controls the behavior of the assembler when
236 conditional instructions are not enclosed in IT blocks.
237 There are four possible behaviors.
238 If @code{never} is specified, such constructs cause a warning in ARM
239 code and an error in Thumb-2 code.
240 If @code{always} is specified, such constructs are accepted in both
241 ARM and Thumb-2 code, where the IT instruction is added implicitly.
242 If @code{arm} is specified, such constructs are accepted in ARM code
243 and cause an error in Thumb-2 code.
244 If @code{thumb} is specified, such constructs cause a warning in ARM
245 code and are accepted in Thumb-2 code. If you omit this option, the
246 behavior is equivalent to @code{-mimplicit-it=arm}.
248 @cindex @code{-mapcs} command line option, ARM
249 @item -mapcs @code{[26|32]}
250 This option specifies that the output generated by the assembler should
251 be marked as supporting the indicated version of the Arm Procedure.
254 @cindex @code{-matpcs} command line option, ARM
256 This option specifies that the output generated by the assembler should
257 be marked as supporting the Arm/Thumb Procedure Calling Standard. If
258 enabled this option will cause the assembler to create an empty
259 debugging section in the object file called .arm.atpcs. Debuggers can
260 use this to determine the ABI being used by.
262 @cindex @code{-mapcs-float} command line option, ARM
264 This indicates the floating point variant of the APCS should be
265 used. In this variant floating point arguments are passed in FP
266 registers rather than integer registers.
268 @cindex @code{-mapcs-reentrant} command line option, ARM
269 @item -mapcs-reentrant
270 This indicates that the reentrant variant of the APCS should be used.
271 This variant supports position independent code.
273 @cindex @code{-mfloat-abi=} command line option, ARM
274 @item -mfloat-abi=@var{abi}
275 This option specifies that the output generated by the assembler should be
276 marked as using specified floating point ABI.
277 The following values are recognized:
283 @cindex @code{-eabi=} command line option, ARM
284 @item -meabi=@var{ver}
285 This option specifies which EABI version the produced object files should
287 The following values are recognized:
293 @cindex @code{-EB} command line option, ARM
295 This option specifies that the output generated by the assembler should
296 be marked as being encoded for a big-endian processor.
298 @cindex @code{-EL} command line option, ARM
300 This option specifies that the output generated by the assembler should
301 be marked as being encoded for a little-endian processor.
303 @cindex @code{-k} command line option, ARM
304 @cindex PIC code generation for ARM
306 This option specifies that the output of the assembler should be marked
307 as position-independent code (PIC).
309 @cindex @code{--fix-v4bx} command line option, ARM
311 Allow @code{BX} instructions in ARMv4 code. This is intended for use with
312 the linker option of the same name.
314 @cindex @code{-mwarn-deprecated} command line option, ARM
315 @item -mwarn-deprecated
316 @itemx -mno-warn-deprecated
317 Enable or disable warnings about using deprecated options or
318 features. The default is to warn.
326 * ARM-Instruction-Set:: Instruction Set
327 * ARM-Chars:: Special Characters
328 * ARM-Regs:: Register Names
329 * ARM-Relocations:: Relocations
332 @node ARM-Instruction-Set
333 @subsection Instruction Set Syntax
334 Two slightly different syntaxes are support for ARM and THUMB
335 instructions. The default, @code{divided}, uses the old style where
336 ARM and THUMB instructions had their own, separate syntaxes. The new,
337 @code{unified} syntax, which can be selected via the @code{.syntax}
338 directive, and has the following main features:
342 Immediate operands do not require a @code{#} prefix.
345 The @code{IT} instruction may appear, and if it does it is validated
346 against subsequent conditional affixes. In ARM mode it does not
347 generate machine code, in THUMB mode it does.
350 For ARM instructions the conditional affixes always appear at the end
351 of the instruction. For THUMB instructions conditional affixes can be
352 used, but only inside the scope of an @code{IT} instruction.
355 All of the instructions new to the V6T2 architecture (and later) are
356 available. (Only a few such instructions can be written in the
357 @code{divided} syntax).
360 The @code{.N} and @code{.W} suffixes are recognized and honored.
363 All instructions set the flags if and only if they have an @code{s}
368 @subsection Special Characters
370 @cindex line comment character, ARM
371 @cindex ARM line comment character
372 The presence of a @samp{@@} on a line indicates the start of a comment
373 that extends to the end of the current line. If a @samp{#} appears as
374 the first character of a line, the whole line is treated as a comment.
376 @cindex line separator, ARM
377 @cindex statement separator, ARM
378 @cindex ARM line separator
379 The @samp{;} character can be used instead of a newline to separate
382 @cindex immediate character, ARM
383 @cindex ARM immediate character
384 Either @samp{#} or @samp{$} can be used to indicate immediate operands.
386 @cindex identifiers, ARM
387 @cindex ARM identifiers
388 *TODO* Explain about /data modifier on symbols.
391 @subsection Register Names
393 @cindex ARM register names
394 @cindex register names, ARM
395 *TODO* Explain about ARM register naming, and the predefined names.
397 @node ARM Floating Point
398 @section Floating Point
400 @cindex floating point, ARM (@sc{ieee})
401 @cindex ARM floating point (@sc{ieee})
402 The ARM family uses @sc{ieee} floating-point numbers.
404 @node ARM-Relocations
405 @subsection ARM relocation generation
407 @cindex data relocations, ARM
408 @cindex ARM data relocations
409 Specific data relocations can be generated by putting the relocation name
410 in parentheses after the symbol name. For example:
416 This will generate an @samp{R_ARM_TARGET1} relocation against the symbol
418 The following relocations are supported:
431 For compatibility with older toolchains the assembler also accepts
432 @code{(PLT)} after branch targets. This will generate the deprecated
433 @samp{R_ARM_PLT32} relocation.
435 @cindex MOVW and MOVT relocations, ARM
436 Relocations for @samp{MOVW} and @samp{MOVT} instructions can be generated
437 by prefixing the value with @samp{#:lower16:} and @samp{#:upper16}
438 respectively. For example to load the 32-bit address of foo into r0:
441 MOVW r0, #:lower16:foo
442 MOVT r0, #:upper16:foo
446 @section ARM Machine Directives
448 @cindex machine directives, ARM
449 @cindex ARM machine directives
452 @c AAAAAAAAAAAAAAAAAAAAAAAAA
454 @cindex @code{.2byte} directive, ARM
455 @cindex @code{.4byte} directive, ARM
456 @cindex @code{.8byte} directive, ARM
457 @item .2byte @var{expression} [, @var{expression}]*
458 @itemx .4byte @var{expression} [, @var{expression}]*
459 @itemx .8byte @var{expression} [, @var{expression}]*
460 These directives write 2, 4 or 8 byte values to the output section.
462 @cindex @code{.align} directive, ARM
463 @item .align @var{expression} [, @var{expression}]
464 This is the generic @var{.align} directive. For the ARM however if the
465 first argument is zero (ie no alignment is needed) the assembler will
466 behave as if the argument had been 2 (ie pad to the next four byte
467 boundary). This is for compatibility with ARM's own assembler.
469 @cindex @code{.arch} directive, ARM
470 @item .arch @var{name}
471 Select the target architecture. Valid values for @var{name} are the same as
472 for the @option{-march} commandline option.
474 @cindex @code{.arm} directive, ARM
476 This performs the same action as @var{.code 32}.
479 @cindex @code{.pad} directive, ARM
480 @item .pad #@var{count}
481 Generate unwinder annotations for a stack adjustment of @var{count} bytes.
482 A positive value indicates the function prologue allocated stack space by
483 decrementing the stack pointer.
485 @c BBBBBBBBBBBBBBBBBBBBBBBBBB
487 @cindex @code{.bss} directive, ARM
489 This directive switches to the @code{.bss} section.
491 @c CCCCCCCCCCCCCCCCCCCCCCCCCC
493 @cindex @code{.cantunwind} directive, ARM
495 Prevents unwinding through the current function. No personality routine
496 or exception table data is required or permitted.
498 @cindex @code{.code} directive, ARM
499 @item .code @code{[16|32]}
500 This directive selects the instruction set being generated. The value 16
501 selects Thumb, with the value 32 selecting ARM.
503 @cindex @code{.cpu} directive, ARM
504 @item .cpu @var{name}
505 Select the target processor. Valid values for @var{name} are the same as
506 for the @option{-mcpu} commandline option.
508 @c DDDDDDDDDDDDDDDDDDDDDDDDDD
510 @cindex @code{.dn} and @code{.qn} directives, ARM
511 @item @var{name} .dn @var{register name} [@var{.type}] [[@var{index}]]
512 @item @var{name} .qn @var{register name} [@var{.type}] [[@var{index}]]
514 The @code{dn} and @code{qn} directives are used to create typed
515 and/or indexed register aliases for use in Advanced SIMD Extension
516 (Neon) instructions. The former should be used to create aliases
517 of double-precision registers, and the latter to create aliases of
518 quad-precision registers.
520 If these directives are used to create typed aliases, those aliases can
521 be used in Neon instructions instead of writing types after the mnemonic
522 or after each operand. For example:
531 This is equivalent to writing the following:
537 Aliases created using @code{dn} or @code{qn} can be destroyed using
540 @c EEEEEEEEEEEEEEEEEEEEEEEEEE
542 @cindex @code{.eabi_attribute} directive, ARM
543 @item .eabi_attribute @var{tag}, @var{value}
544 Set the EABI object attribute @var{tag} to @var{value}.
546 The @var{tag} is either an attribute number, or one of the following:
547 @code{Tag_CPU_raw_name}, @code{Tag_CPU_name}, @code{Tag_CPU_arch},
548 @code{Tag_CPU_arch_profile}, @code{Tag_ARM_ISA_use},
549 @code{Tag_THUMB_ISA_use}, @code{Tag_VFP_arch}, @code{Tag_WMMX_arch},
550 @code{Tag_Advanced_SIMD_arch}, @code{Tag_PCS_config},
551 @code{Tag_ABI_PCS_R9_use}, @code{Tag_ABI_PCS_RW_data},
552 @code{Tag_ABI_PCS_RO_data}, @code{Tag_ABI_PCS_GOT_use},
553 @code{Tag_ABI_PCS_wchar_t}, @code{Tag_ABI_FP_rounding},
554 @code{Tag_ABI_FP_denormal}, @code{Tag_ABI_FP_exceptions},
555 @code{Tag_ABI_FP_user_exceptions}, @code{Tag_ABI_FP_number_model},
556 @code{Tag_ABI_align8_needed}, @code{Tag_ABI_align8_preserved},
557 @code{Tag_ABI_enum_size}, @code{Tag_ABI_HardFP_use},
558 @code{Tag_ABI_VFP_args}, @code{Tag_ABI_WMMX_args},
559 @code{Tag_ABI_optimization_goals}, @code{Tag_ABI_FP_optimization_goals},
560 @code{Tag_compatibility}, @code{Tag_CPU_unaligned_access},
561 @code{Tag_VFP_HP_extension}, @code{Tag_ABI_FP_16bit_format},
562 @code{Tag_nodefaults}, @code{Tag_also_compatible_with},
563 @code{Tag_conformance}, @code{Tag_T2EE_use},
564 @code{Tag_Virtualization_use}, @code{Tag_MPextension_use}
566 The @var{value} is either a @code{number}, @code{"string"}, or
567 @code{number, "string"} depending on the tag.
569 @cindex @code{.even} directive, ARM
571 This directive aligns to an even-numbered address.
573 @cindex @code{.extend} directive, ARM
574 @cindex @code{.ldouble} directive, ARM
575 @item .extend @var{expression} [, @var{expression}]*
576 @itemx .ldouble @var{expression} [, @var{expression}]*
577 These directives write 12byte long double floating-point values to the
578 output section. These are not compatible with current ARM processors
581 @c FFFFFFFFFFFFFFFFFFFFFFFFFF
584 @cindex @code{.fnend} directive, ARM
586 Marks the end of a function with an unwind table entry. The unwind index
587 table entry is created when this directive is processed.
589 If no personality routine has been specified then standard personality
590 routine 0 or 1 will be used, depending on the number of unwind opcodes
594 @cindex @code{.fnstart} directive, ARM
596 Marks the start of a function with an unwind table entry.
598 @cindex @code{.force_thumb} directive, ARM
600 This directive forces the selection of Thumb instructions, even if the
601 target processor does not support those instructions
603 @cindex @code{.fpu} directive, ARM
604 @item .fpu @var{name}
605 Select the floating-point unit to assemble for. Valid values for @var{name}
606 are the same as for the @option{-mfpu} commandline option.
608 @c GGGGGGGGGGGGGGGGGGGGGGGGGG
609 @c HHHHHHHHHHHHHHHHHHHHHHHHHH
611 @cindex @code{.handlerdata} directive, ARM
613 Marks the end of the current function, and the start of the exception table
614 entry for that function. Anything between this directive and the
615 @code{.fnend} directive will be added to the exception table entry.
617 Must be preceded by a @code{.personality} or @code{.personalityindex}
620 @c IIIIIIIIIIIIIIIIIIIIIIIIII
622 @cindex @code{.inst} directive, ARM
623 @item .inst @var{opcode} [ , @dots{} ]
624 @item .inst.n @var{opcode} [ , @dots{} ]
625 @item .inst.w @var{opcode} [ , @dots{} ]
626 Generates the instruction corresponding to the numerical value @var{opcode}.
627 @code{.inst.n} and @code{.inst.w} allow the Thumb instruction size to be
628 specified explicitly, overriding the normal encoding rules.
630 @c JJJJJJJJJJJJJJJJJJJJJJJJJJ
631 @c KKKKKKKKKKKKKKKKKKKKKKKKKK
632 @c LLLLLLLLLLLLLLLLLLLLLLLLLL
634 @item .ldouble @var{expression} [, @var{expression}]*
637 @cindex @code{.ltorg} directive, ARM
639 This directive causes the current contents of the literal pool to be
640 dumped into the current section (which is assumed to be the .text
641 section) at the current location (aligned to a word boundary).
642 @code{GAS} maintains a separate literal pool for each section and each
643 sub-section. The @code{.ltorg} directive will only affect the literal
644 pool of the current section and sub-section. At the end of assembly
645 all remaining, un-empty literal pools will automatically be dumped.
647 Note - older versions of @code{GAS} would dump the current literal
648 pool any time a section change occurred. This is no longer done, since
649 it prevents accurate control of the placement of literal pools.
651 @c MMMMMMMMMMMMMMMMMMMMMMMMMM
653 @cindex @code{.movsp} directive, ARM
654 @item .movsp @var{reg} [, #@var{offset}]
655 Tell the unwinder that @var{reg} contains an offset from the current
656 stack pointer. If @var{offset} is not specified then it is assumed to be
659 @c NNNNNNNNNNNNNNNNNNNNNNNNNN
660 @c OOOOOOOOOOOOOOOOOOOOOOOOOO
662 @cindex @code{.object_arch} directive, ARM
663 @item .object_arch @var{name}
664 Override the architecture recorded in the EABI object attribute section.
665 Valid values for @var{name} are the same as for the @code{.arch} directive.
666 Typically this is useful when code uses runtime detection of CPU features.
668 @c PPPPPPPPPPPPPPPPPPPPPPPPPP
670 @cindex @code{.packed} directive, ARM
671 @item .packed @var{expression} [, @var{expression}]*
672 This directive writes 12-byte packed floating-point values to the
673 output section. These are not compatible with current ARM processors
676 @cindex @code{.pad} directive, ARM
677 @item .pad #@var{count}
678 Generate unwinder annotations for a stack adjustment of @var{count} bytes.
679 A positive value indicates the function prologue allocated stack space by
680 decrementing the stack pointer.
682 @cindex @code{.personality} directive, ARM
683 @item .personality @var{name}
684 Sets the personality routine for the current function to @var{name}.
686 @cindex @code{.personalityindex} directive, ARM
687 @item .personalityindex @var{index}
688 Sets the personality routine for the current function to the EABI standard
689 routine number @var{index}
691 @cindex @code{.pool} directive, ARM
693 This is a synonym for .ltorg.
695 @c QQQQQQQQQQQQQQQQQQQQQQQQQQ
696 @c RRRRRRRRRRRRRRRRRRRRRRRRRR
698 @cindex @code{.req} directive, ARM
699 @item @var{name} .req @var{register name}
700 This creates an alias for @var{register name} called @var{name}. For
707 @c SSSSSSSSSSSSSSSSSSSSSSSSSS
710 @cindex @code{.save} directive, ARM
711 @item .save @var{reglist}
712 Generate unwinder annotations to restore the registers in @var{reglist}.
713 The format of @var{reglist} is the same as the corresponding store-multiple
717 @exdent @emph{core registers}
718 .save @{r4, r5, r6, lr@}
719 stmfd sp!, @{r4, r5, r6, lr@}
720 @exdent @emph{FPA registers}
723 @exdent @emph{VFP registers}
724 .save @{d8, d9, d10@}
725 fstmdx sp!, @{d8, d9, d10@}
726 @exdent @emph{iWMMXt registers}
728 wstrd wr11, [sp, #-8]!
729 wstrd wr10, [sp, #-8]!
732 wstrd wr11, [sp, #-8]!
734 wstrd wr10, [sp, #-8]!
738 @cindex @code{.setfp} directive, ARM
739 @item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}]
740 Make all unwinder annotations relative to a frame pointer. Without this
741 the unwinder will use offsets from the stack pointer.
743 The syntax of this directive is the same as the @code{sub} or @code{mov}
744 instruction used to set the frame pointer. @var{spreg} must be either
745 @code{sp} or mentioned in a previous @code{.movsp} directive.
755 @cindex @code{.secrel32} directive, ARM
756 @item .secrel32 @var{expression} [, @var{expression}]*
757 This directive emits relocations that evaluate to the section-relative
758 offset of each expression's symbol. This directive is only supported
761 @cindex @code{.syntax} directive, ARM
762 @item .syntax [@code{unified} | @code{divided}]
763 This directive sets the Instruction Set Syntax as described in the
764 @ref{ARM-Instruction-Set} section.
766 @c TTTTTTTTTTTTTTTTTTTTTTTTTT
768 @cindex @code{.thumb} directive, ARM
770 This performs the same action as @var{.code 16}.
772 @cindex @code{.thumb_func} directive, ARM
774 This directive specifies that the following symbol is the name of a
775 Thumb encoded function. This information is necessary in order to allow
776 the assembler and linker to generate correct code for interworking
777 between Arm and Thumb instructions and should be used even if
778 interworking is not going to be performed. The presence of this
779 directive also implies @code{.thumb}
781 This directive is not neccessary when generating EABI objects. On these
782 targets the encoding is implicit when generating Thumb code.
784 @cindex @code{.thumb_set} directive, ARM
786 This performs the equivalent of a @code{.set} directive in that it
787 creates a symbol which is an alias for another symbol (possibly not yet
788 defined). This directive also has the added property in that it marks
789 the aliased symbol as being a thumb function entry point, in the same
790 way that the @code{.thumb_func} directive does.
792 @c UUUUUUUUUUUUUUUUUUUUUUUUUU
794 @cindex @code{.unreq} directive, ARM
795 @item .unreq @var{alias-name}
796 This undefines a register alias which was previously defined using the
797 @code{req}, @code{dn} or @code{qn} directives. For example:
804 An error occurs if the name is undefined. Note - this pseudo op can
805 be used to delete builtin in register name aliases (eg 'r0'). This
806 should only be done if it is really necessary.
808 @cindex @code{.unwind_raw} directive, ARM
809 @item .unwind_raw @var{offset}, @var{byte1}, @dots{}
810 Insert one of more arbitary unwind opcode bytes, which are known to adjust
811 the stack pointer by @var{offset} bytes.
813 For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to
816 @c VVVVVVVVVVVVVVVVVVVVVVVVVV
818 @cindex @code{.vsave} directive, ARM
819 @item .vsave @var{vfp-reglist}
820 Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist}
821 using FLDMD. Also works for VFPv3 registers
822 that are to be restored using VLDM.
823 The format of @var{vfp-reglist} is the same as the corresponding store-multiple
827 @exdent @emph{VFP registers}
828 .vsave @{d8, d9, d10@}
829 fstmdd sp!, @{d8, d9, d10@}
830 @exdent @emph{VFPv3 registers}
831 .vsave @{d15, d16, d17@}
832 vstm sp!, @{d15, d16, d17@}
835 Since FLDMX and FSTMX are now deprecated, this directive should be
836 used in favour of @code{.save} for saving VFP registers for ARMv6 and above.
838 @c WWWWWWWWWWWWWWWWWWWWWWWWWW
839 @c XXXXXXXXXXXXXXXXXXXXXXXXXX
840 @c YYYYYYYYYYYYYYYYYYYYYYYYYY
841 @c ZZZZZZZZZZZZZZZZZZZZZZZZZZ
849 @cindex opcodes for ARM
850 @code{@value{AS}} implements all the standard ARM opcodes. It also
851 implements several pseudo opcodes, including several synthetic load
856 @cindex @code{NOP} pseudo op, ARM
862 This pseudo op will always evaluate to a legal ARM instruction that does
863 nothing. Currently it will evaluate to MOV r0, r0.
865 @cindex @code{LDR reg,=<label>} pseudo op, ARM
868 ldr <register> , = <expression>
871 If expression evaluates to a numeric constant then a MOV or MVN
872 instruction will be used in place of the LDR instruction, if the
873 constant can be generated by either of these instructions. Otherwise
874 the constant will be placed into the nearest literal pool (if it not
875 already there) and a PC relative LDR instruction will be generated.
877 @cindex @code{ADR reg,<label>} pseudo op, ARM
880 adr <register> <label>
883 This instruction will load the address of @var{label} into the indicated
884 register. The instruction will evaluate to a PC relative ADD or SUB
885 instruction depending upon where the label is located. If the label is
886 out of range, or if it is not defined in the same file (and section) as
887 the ADR instruction, then an error will be generated. This instruction
888 will not make use of the literal pool.
890 @cindex @code{ADRL reg,<label>} pseudo op, ARM
893 adrl <register> <label>
896 This instruction will load the address of @var{label} into the indicated
897 register. The instruction will evaluate to one or two PC relative ADD
898 or SUB instructions depending upon where the label is located. If a
899 second instruction is not needed a NOP instruction will be generated in
900 its place, so that this instruction is always 8 bytes long.
902 If the label is out of range, or if it is not defined in the same file
903 (and section) as the ADRL instruction, then an error will be generated.
904 This instruction will not make use of the literal pool.
908 For information on the ARM or Thumb instruction sets, see @cite{ARM
909 Software Development Toolkit Reference Manual}, Advanced RISC Machines
912 @node ARM Mapping Symbols
913 @section Mapping Symbols
915 The ARM ELF specification requires that special symbols be inserted
916 into object files to mark certain features:
922 At the start of a region of code containing ARM instructions.
926 At the start of a region of code containing THUMB instructions.
930 At the start of a region of data.
934 The assembler will automatically insert these symbols for you - there
935 is no need to code them yourself. Support for tagging symbols ($b,
936 $f, $p and $m) which is also mentioned in the current ARM ELF
937 specification is not implemented. This is because they have been
938 dropped from the new EABI and so tools cannot rely upon their
941 @node ARM Unwinding Tutorial
944 The ABI for the ARM Architecture specifies a standard format for
945 exception unwind information. This information is used when an
946 exception is thrown to determine where control should be transferred.
947 In particular, the unwind information is used to determine which
948 function called the function that threw the exception, and which
949 function called that one, and so forth. This information is also used
950 to restore the values of callee-saved registers in the function
951 catching the exception.
953 If you are writing functions in assembly code, and those functions
954 call other functions that throw exceptions, you must use assembly
955 pseudo ops to ensure that appropriate exception unwind information is
956 generated. Otherwise, if one of the functions called by your assembly
957 code throws an exception, the run-time library will be unable to
958 unwind the stack through your assembly code and your program will not
961 To illustrate the use of these pseudo ops, we will examine the code
962 that G++ generates for the following C++ input:
976 This example does not show how to throw or catch an exception from
977 assembly code. That is a much more complex operation and should
978 always be done in a high-level language, such as C++, that directly
981 The code generated by one particular version of G++ when compiling the
988 @ Function supports interworking.
989 @ args = 0, pretend = 0, frame = 8
990 @ frame_needed = 1, uses_anonymous_args = 0
1012 Of course, the sequence of instructions varies based on the options
1013 you pass to GCC and on the version of GCC in use. The exact
1014 instructions are not important since we are focusing on the pseudo ops
1015 that are used to generate unwind information.
1017 An important assumption made by the unwinder is that the stack frame
1018 does not change during the body of the function. In particular, since
1019 we assume that the assembly code does not itself throw an exception,
1020 the only point where an exception can be thrown is from a call, such
1021 as the @code{bl} instruction above. At each call site, the same saved
1022 registers (including @code{lr}, which indicates the return address)
1023 must be located in the same locations relative to the frame pointer.
1025 The @code{.fnstart} (@pxref{arm_fnstart,,.fnstart pseudo op}) pseudo
1026 op appears immediately before the first instruction of the function
1027 while the @code{.fnend} (@pxref{arm_fnend,,.fnend pseudo op}) pseudo
1028 op appears immediately after the last instruction of the function.
1029 These pseudo ops specify the range of the function.
1031 Only the order of the other pseudos ops (e.g., @code{.setfp} or
1032 @code{.pad}) matters; their exact locations are irrelevant. In the
1033 example above, the compiler emits the pseudo ops with particular
1034 instructions. That makes it easier to understand the code, but it is
1035 not required for correctness. It would work just as well to emit all
1036 of the pseudo ops other than @code{.fnend} in the same order, but
1037 immediately after @code{.fnstart}.
1039 The @code{.save} (@pxref{arm_save,,.save pseudo op}) pseudo op
1040 indicates registers that have been saved to the stack so that they can
1041 be restored before the function returns. The argument to the
1042 @code{.save} pseudo op is a list of registers to save. If a register
1043 is ``callee-saved'' (as specified by the ABI) and is modified by the
1044 function you are writing, then your code must save the value before it
1045 is modified and restore the original value before the function
1046 returns. If an exception is thrown, the run-time library restores the
1047 values of these registers from their locations on the stack before
1048 returning control to the exception handler. (Of course, if an
1049 exception is not thrown, the function that contains the @code{.save}
1050 pseudo op restores these registers in the function epilogue, as is
1051 done with the @code{ldmfd} instruction above.)
1053 You do not have to save callee-saved registers at the very beginning
1054 of the function and you do not need to use the @code{.save} pseudo op
1055 immediately following the point at which the registers are saved.
1056 However, if you modify a callee-saved register, you must save it on
1057 the stack before modifying it and before calling any functions which
1058 might throw an exception. And, you must use the @code{.save} pseudo
1059 op to indicate that you have done so.
1061 The @code{.pad} (@pxref{arm_pad,,.pad}) pseudo op indicates a
1062 modification of the stack pointer that does not save any registers.
1063 The argument is the number of bytes (in decimal) that are subtracted
1064 from the stack pointer. (On ARM CPUs, the stack grows downwards, so
1065 subtracting from the stack pointer increases the size of the stack.)
1067 The @code{.setfp} (@pxref{arm_setfp,,.setfp pseudo op}) pseudo op
1068 indicates the register that contains the frame pointer. The first
1069 argument is the register that is set, which is typically @code{fp}.
1070 The second argument indicates the register from which the frame
1071 pointer takes its value. The third argument, if present, is the value
1072 (in decimal) added to the register specified by the second argument to
1073 compute the value of the frame pointer. You should not modify the
1074 frame pointer in the body of the function.
1076 If you do not use a frame pointer, then you should not use the
1077 @code{.setfp} pseudo op. If you do not use a frame pointer, then you
1078 should avoid modifying the stack pointer outside of the function
1079 prologue. Otherwise, the run-time library will be unable to find
1080 saved registers when it is unwinding the stack.
1082 The pseudo ops described above are sufficient for writing assembly
1083 code that calls functions which may throw exceptions. If you need to
1084 know more about the object-file format used to represent unwind
1085 information, you may consult the @cite{Exception Handling ABI for the
1086 ARM Architecture} available from @uref{http://infocenter.arm.com}.