-@c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004
-@c Free Software Foundation, Inc.
+@c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+@c 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c This is part of the GAS manual.
@c For copying conditions, see the file as.texinfo.
* ARM Directives:: ARM Machine Directives
* ARM Opcodes:: Opcodes
* ARM Mapping Symbols:: Mapping Symbols
+* ARM Unwinding Tutorial:: Unwinding
@end menu
@node ARM Options
@code{arm922t},
@code{arm940t},
@code{arm9tdmi},
+@code{fa526} (Faraday FA526 processor),
+@code{fa626} (Faraday FA626 processor),
@code{arm9e},
@code{arm926e},
@code{arm926ej-s},
@code{arm1020e},
@code{arm1022e},
@code{arm1026ej-s},
+@code{fa626te} (Faraday FA626TE processor),
+@code{fa726te} (Faraday FA726TE processor),
@code{arm1136j-s},
@code{arm1136jf-s},
@code{arm1156t2-s},
@code{mpcore},
@code{mpcorenovfp},
@code{cortex-a8},
+@code{cortex-a9},
@code{cortex-r4},
@code{cortex-m3},
+@code{cortex-m1},
+@code{cortex-m0},
@code{ep9312} (ARM920 with Cirrus Maverick coprocessor),
@code{i80200} (Intel XScale processor)
@code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor)
@code{vfp10-r0},
@code{vfp9},
@code{vfpxd},
+@code{vfpv2}
+@code{vfpv3}
+@code{vfpv3-d16}
@code{arm1020t},
@code{arm1020e},
-@code{arm1136jf-s}
+@code{arm1136jf-s},
+@code{maverick}
and
-@code{maverick}.
+@code{neon}.
In addition to determining which instructions are assembled, this option
also affects the way in which the @code{.double} assembler directive behaves
This option specifies that the output generated by the assembler should
be marked as supporting interworking.
+@cindex @code{-mimplicit-it} command line option, ARM
+@item -mimplicit-it=never
+@itemx -mimplicit-it=always
+@itemx -mimplicit-it=arm
+@itemx -mimplicit-it=thumb
+The @code{-mimplicit-it} option controls the behavior of the assembler when
+conditional instructions are not enclosed in IT blocks.
+There are four possible behaviors.
+If @code{never} is specified, such constructs cause a warning in ARM
+code and an error in Thumb-2 code.
+If @code{always} is specified, such constructs are accepted in both
+ARM and Thumb-2 code, where the IT instruction is added implicitly.
+If @code{arm} is specified, such constructs are accepted in ARM code
+and cause an error in Thumb-2 code.
+If @code{thumb} is specified, such constructs cause a warning in ARM
+code and are accepted in Thumb-2 code. If you omit this option, the
+behavior is equivalent to @code{-mimplicit-it=arm}.
+
@cindex @code{-mapcs} command line option, ARM
@item -mapcs @code{[26|32]}
This option specifies that the output generated by the assembler should
This option specifies that the output of the assembler should be marked
as position-independent code (PIC).
+@cindex @code{--fix-v4bx} command line option, ARM
+@item --fix-v4bx
+Allow @code{BX} instructions in ARMv4 code. This is intended for use with
+the linker option of the same name.
+
+@cindex @code{-mwarn-deprecated} command line option, ARM
+@item -mwarn-deprecated
+@itemx -mno-warn-deprecated
+Enable or disable warnings about using deprecated options or
+features. The default is to warn.
+
@end table
@node ARM Syntax
@section Syntax
@menu
+* ARM-Instruction-Set:: Instruction Set
* ARM-Chars:: Special Characters
* ARM-Regs:: Register Names
* ARM-Relocations:: Relocations
@end menu
+@node ARM-Instruction-Set
+@subsection Instruction Set Syntax
+Two slightly different syntaxes are support for ARM and THUMB
+instructions. The default, @code{divided}, uses the old style where
+ARM and THUMB instructions had their own, separate syntaxes. The new,
+@code{unified} syntax, which can be selected via the @code{.syntax}
+directive, and has the following main features:
+
+@table @bullet
+@item
+Immediate operands do not require a @code{#} prefix.
+
+@item
+The @code{IT} instruction may appear, and if it does it is validated
+against subsequent conditional affixes. In ARM mode it does not
+generate machine code, in THUMB mode it does.
+
+@item
+For ARM instructions the conditional affixes always appear at the end
+of the instruction. For THUMB instructions conditional affixes can be
+used, but only inside the scope of an @code{IT} instruction.
+
+@item
+All of the instructions new to the V6T2 architecture (and later) are
+available. (Only a few such instructions can be written in the
+@code{divided} syntax).
+
+@item
+The @code{.N} and @code{.W} suffixes are recognized and honored.
+
+@item
+All instructions set the flags if and only if they have an @code{s}
+affix.
+@end table
+
@node ARM-Chars
@subsection Special Characters
@cindex ARM machine directives
@table @code
-@cindex @code{align} directive, ARM
+@c AAAAAAAAAAAAAAAAAAAAAAAAA
+
+@cindex @code{.2byte} directive, ARM
+@cindex @code{.4byte} directive, ARM
+@cindex @code{.8byte} directive, ARM
+@item .2byte @var{expression} [, @var{expression}]*
+@itemx .4byte @var{expression} [, @var{expression}]*
+@itemx .8byte @var{expression} [, @var{expression}]*
+These directives write 2, 4 or 8 byte values to the output section.
+
+@cindex @code{.align} directive, ARM
@item .align @var{expression} [, @var{expression}]
This is the generic @var{.align} directive. For the ARM however if the
first argument is zero (ie no alignment is needed) the assembler will
behave as if the argument had been 2 (ie pad to the next four byte
boundary). This is for compatibility with ARM's own assembler.
-@cindex @code{req} directive, ARM
-@item @var{name} .req @var{register name}
-This creates an alias for @var{register name} called @var{name}. For
-example:
+@cindex @code{.arch} directive, ARM
+@item .arch @var{name}
+Select the target architecture. Valid values for @var{name} are the same as
+for the @option{-march} commandline option.
-@smallexample
- foo .req r0
-@end smallexample
+@cindex @code{.arm} directive, ARM
+@item .arm
+This performs the same action as @var{.code 32}.
-@cindex @code{unreq} directive, ARM
-@item .unreq @var{alias-name}
-This undefines a register alias which was previously defined using the
-@code{req}, @code{dn} or @code{qn} directives. For example:
+@anchor{arm_pad}
+@cindex @code{.pad} directive, ARM
+@item .pad #@var{count}
+Generate unwinder annotations for a stack adjustment of @var{count} bytes.
+A positive value indicates the function prologue allocated stack space by
+decrementing the stack pointer.
-@smallexample
- foo .req r0
- .unreq foo
-@end smallexample
+@c BBBBBBBBBBBBBBBBBBBBBBBBBB
-An error occurs if the name is undefined. Note - this pseudo op can
-be used to delete builtin in register name aliases (eg 'r0'). This
-should only be done if it is really necessary.
+@cindex @code{.bss} directive, ARM
+@item .bss
+This directive switches to the @code{.bss} section.
+
+@c CCCCCCCCCCCCCCCCCCCCCCCCCC
+
+@cindex @code{.cantunwind} directive, ARM
+@item .cantunwind
+Prevents unwinding through the current function. No personality routine
+or exception table data is required or permitted.
+
+@cindex @code{.code} directive, ARM
+@item .code @code{[16|32]}
+This directive selects the instruction set being generated. The value 16
+selects Thumb, with the value 32 selecting ARM.
+
+@cindex @code{.cpu} directive, ARM
+@item .cpu @var{name}
+Select the target processor. Valid values for @var{name} are the same as
+for the @option{-mcpu} commandline option.
-@cindex @code{dn} and @code{qn} directives, ARM
+@c DDDDDDDDDDDDDDDDDDDDDDDDDD
+
+@cindex @code{.dn} and @code{.qn} directives, ARM
@item @var{name} .dn @var{register name} [@var{.type}] [[@var{index}]]
@item @var{name} .qn @var{register name} [@var{.type}] [[@var{index}]]
Aliases created using @code{dn} or @code{qn} can be destroyed using
@code{unreq}.
-@cindex @code{code} directive, ARM
-@item .code @code{[16|32]}
-This directive selects the instruction set being generated. The value 16
-selects Thumb, with the value 32 selecting ARM.
+@c EEEEEEEEEEEEEEEEEEEEEEEEEE
-@cindex @code{thumb} directive, ARM
-@item .thumb
-This performs the same action as @var{.code 16}.
+@cindex @code{.eabi_attribute} directive, ARM
+@item .eabi_attribute @var{tag}, @var{value}
+Set the EABI object attribute @var{tag} to @var{value}.
+
+The @var{tag} is either an attribute number, or one of the following:
+@code{Tag_CPU_raw_name}, @code{Tag_CPU_name}, @code{Tag_CPU_arch},
+@code{Tag_CPU_arch_profile}, @code{Tag_ARM_ISA_use},
+@code{Tag_THUMB_ISA_use}, @code{Tag_VFP_arch}, @code{Tag_WMMX_arch},
+@code{Tag_Advanced_SIMD_arch}, @code{Tag_PCS_config},
+@code{Tag_ABI_PCS_R9_use}, @code{Tag_ABI_PCS_RW_data},
+@code{Tag_ABI_PCS_RO_data}, @code{Tag_ABI_PCS_GOT_use},
+@code{Tag_ABI_PCS_wchar_t}, @code{Tag_ABI_FP_rounding},
+@code{Tag_ABI_FP_denormal}, @code{Tag_ABI_FP_exceptions},
+@code{Tag_ABI_FP_user_exceptions}, @code{Tag_ABI_FP_number_model},
+@code{Tag_ABI_align8_needed}, @code{Tag_ABI_align8_preserved},
+@code{Tag_ABI_enum_size}, @code{Tag_ABI_HardFP_use},
+@code{Tag_ABI_VFP_args}, @code{Tag_ABI_WMMX_args},
+@code{Tag_ABI_optimization_goals}, @code{Tag_ABI_FP_optimization_goals},
+@code{Tag_compatibility}, @code{Tag_CPU_unaligned_access},
+@code{Tag_VFP_HP_extension}, @code{Tag_ABI_FP_16bit_format},
+@code{Tag_nodefaults}, @code{Tag_also_compatible_with},
+@code{Tag_conformance}, @code{Tag_T2EE_use},
+@code{Tag_Virtualization_use}, @code{Tag_MPextension_use}
+
+The @var{value} is either a @code{number}, @code{"string"}, or
+@code{number, "string"} depending on the tag.
+
+@cindex @code{.even} directive, ARM
+@item .even
+This directive aligns to an even-numbered address.
+
+@cindex @code{.extend} directive, ARM
+@cindex @code{.ldouble} directive, ARM
+@item .extend @var{expression} [, @var{expression}]*
+@itemx .ldouble @var{expression} [, @var{expression}]*
+These directives write 12byte long double floating-point values to the
+output section. These are not compatible with current ARM processors
+or ABIs.
+
+@c FFFFFFFFFFFFFFFFFFFFFFFFFF
+
+@anchor{arm_fnend}
+@cindex @code{.fnend} directive, ARM
+@item .fnend
+Marks the end of a function with an unwind table entry. The unwind index
+table entry is created when this directive is processed.
-@cindex @code{arm} directive, ARM
-@item .arm
-This performs the same action as @var{.code 32}.
+If no personality routine has been specified then standard personality
+routine 0 or 1 will be used, depending on the number of unwind opcodes
+required.
+
+@anchor{arm_fnstart}
+@cindex @code{.fnstart} directive, ARM
+@item .fnstart
+Marks the start of a function with an unwind table entry.
-@cindex @code{force_thumb} directive, ARM
+@cindex @code{.force_thumb} directive, ARM
@item .force_thumb
This directive forces the selection of Thumb instructions, even if the
target processor does not support those instructions
-@cindex @code{thumb_func} directive, ARM
-@item .thumb_func
-This directive specifies that the following symbol is the name of a
-Thumb encoded function. This information is necessary in order to allow
-the assembler and linker to generate correct code for interworking
-between Arm and Thumb instructions and should be used even if
-interworking is not going to be performed. The presence of this
-directive also implies @code{.thumb}
+@cindex @code{.fpu} directive, ARM
+@item .fpu @var{name}
+Select the floating-point unit to assemble for. Valid values for @var{name}
+are the same as for the @option{-mfpu} commandline option.
-This directive is not neccessary when generating EABI objects. On these
-targets the encoding is implicit when generating Thumb code.
+@c GGGGGGGGGGGGGGGGGGGGGGGGGG
+@c HHHHHHHHHHHHHHHHHHHHHHHHHH
-@cindex @code{thumb_set} directive, ARM
-@item .thumb_set
-This performs the equivalent of a @code{.set} directive in that it
-creates a symbol which is an alias for another symbol (possibly not yet
-defined). This directive also has the added property in that it marks
-the aliased symbol as being a thumb function entry point, in the same
-way that the @code{.thumb_func} directive does.
+@cindex @code{.handlerdata} directive, ARM
+@item .handlerdata
+Marks the end of the current function, and the start of the exception table
+entry for that function. Anything between this directive and the
+@code{.fnend} directive will be added to the exception table entry.
+
+Must be preceded by a @code{.personality} or @code{.personalityindex}
+directive.
+
+@c IIIIIIIIIIIIIIIIIIIIIIIIII
+
+@cindex @code{.inst} directive, ARM
+@item .inst @var{opcode} [ , @dots{} ]
+@item .inst.n @var{opcode} [ , @dots{} ]
+@item .inst.w @var{opcode} [ , @dots{} ]
+Generates the instruction corresponding to the numerical value @var{opcode}.
+@code{.inst.n} and @code{.inst.w} allow the Thumb instruction size to be
+specified explicitly, overriding the normal encoding rules.
+
+@c JJJJJJJJJJJJJJJJJJJJJJJJJJ
+@c KKKKKKKKKKKKKKKKKKKKKKKKKK
+@c LLLLLLLLLLLLLLLLLLLLLLLLLL
+
+@item .ldouble @var{expression} [, @var{expression}]*
+See @code{.extend}.
@cindex @code{.ltorg} directive, ARM
@item .ltorg
pool any time a section change occurred. This is no longer done, since
it prevents accurate control of the placement of literal pools.
-@cindex @code{.pool} directive, ARM
-@item .pool
-This is a synonym for .ltorg.
+@c MMMMMMMMMMMMMMMMMMMMMMMMMM
-@cindex @code{.fnstart} directive, ARM
-@item .unwind_fnstart
-Marks the start of a function with an unwind table entry.
+@cindex @code{.movsp} directive, ARM
+@item .movsp @var{reg} [, #@var{offset}]
+Tell the unwinder that @var{reg} contains an offset from the current
+stack pointer. If @var{offset} is not specified then it is assumed to be
+zero.
-@cindex @code{.fnend} directive, ARM
-@item .unwind_fnend
-Marks the end of a function with an unwind table entry. The unwind index
-table entry is created when this directive is processed.
+@c NNNNNNNNNNNNNNNNNNNNNNNNNN
+@c OOOOOOOOOOOOOOOOOOOOOOOOOO
-If no personality routine has been specified then standard personality
-routine 0 or 1 will be used, depending on the number of unwind opcodes
-required.
+@cindex @code{.object_arch} directive, ARM
+@item .object_arch @var{name}
+Override the architecture recorded in the EABI object attribute section.
+Valid values for @var{name} are the same as for the @code{.arch} directive.
+Typically this is useful when code uses runtime detection of CPU features.
-@cindex @code{.cantunwind} directive, ARM
-@item .cantunwind
-Prevents unwinding through the current function. No personality routine
-or exception table data is required or permitted.
+@c PPPPPPPPPPPPPPPPPPPPPPPPPP
+
+@cindex @code{.packed} directive, ARM
+@item .packed @var{expression} [, @var{expression}]*
+This directive writes 12-byte packed floating-point values to the
+output section. These are not compatible with current ARM processors
+or ABIs.
+
+@cindex @code{.pad} directive, ARM
+@item .pad #@var{count}
+Generate unwinder annotations for a stack adjustment of @var{count} bytes.
+A positive value indicates the function prologue allocated stack space by
+decrementing the stack pointer.
@cindex @code{.personality} directive, ARM
@item .personality @var{name}
Sets the personality routine for the current function to the EABI standard
routine number @var{index}
-@cindex @code{.handlerdata} directive, ARM
-@item .handlerdata
-Marks the end of the current function, and the start of the exception table
-entry for that function. Anything between this directive and the
-@code{.fnend} directive will be added to the exception table entry.
+@cindex @code{.pool} directive, ARM
+@item .pool
+This is a synonym for .ltorg.
-Must be preceded by a @code{.personality} or @code{.personalityindex}
-directive.
+@c QQQQQQQQQQQQQQQQQQQQQQQQQQ
+@c RRRRRRRRRRRRRRRRRRRRRRRRRR
+
+@cindex @code{.req} directive, ARM
+@item @var{name} .req @var{register name}
+This creates an alias for @var{register name} called @var{name}. For
+example:
+
+@smallexample
+ foo .req r0
+@end smallexample
+
+@c SSSSSSSSSSSSSSSSSSSSSSSSSS
+@anchor{arm_save}
@cindex @code{.save} directive, ARM
@item .save @var{reglist}
Generate unwinder annotations to restore the registers in @var{reglist}.
wstrd wr10, [sp, #-8]!
@end smallexample
-@cindex @code{.vsave} directive, ARM
-@item .vsave @var{vfp-reglist}
-Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist}
-using FLDMD. Also works for VFPv3 registers
-that are to be restored using VLDM.
-The format of @var{vfp-reglist} is the same as the corresponding store-multiple
-instruction.
-
-@smallexample
-@exdent @emph{VFP registers}
- .vsave @{d8, d9, d10@}
- fstmdd sp!, @{d8, d9, d10@}
-@exdent @emph{VFPv3 registers}
- .vsave @{d15, d16, d17@}
- vstm sp!, @{d15, d16, d17@}
-@end smallexample
-
-Since FLDMX and FSTMX are now deprecated, this directive should be
-used in favour of @code{.save} for saving VFP registers for ARMv6 and above.
-
-@cindex @code{.pad} directive, ARM
-@item .pad #@var{count}
-Generate unwinder annotations for a stack adjustment of @var{count} bytes.
-A positive value indicates the function prologue allocated stack space by
-decrementing the stack pointer.
-
-@cindex @code{.movsp} directive, ARM
-@item .movsp @var{reg} [, #@var{offset}]
-Tell the unwinder that @var{reg} contains an offset from the current
-stack pointer. If @var{offset} is not specified then it is assumed to be
-zero.
-
+@anchor{arm_setfp}
@cindex @code{.setfp} directive, ARM
@item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}]
-Make all unwinder annotations relaive to a frame pointer. Without this
+Make all unwinder annotations relative to a frame pointer. Without this
the unwinder will use offsets from the stack pointer.
The syntax of this directive is the same as the @code{sub} or @code{mov}
sub fp, ip, #4
@end smallexample
+@cindex @code{.secrel32} directive, ARM
+@item .secrel32 @var{expression} [, @var{expression}]*
+This directive emits relocations that evaluate to the section-relative
+offset of each expression's symbol. This directive is only supported
+for PE targets.
+
+@cindex @code{.syntax} directive, ARM
+@item .syntax [@code{unified} | @code{divided}]
+This directive sets the Instruction Set Syntax as described in the
+@ref{ARM-Instruction-Set} section.
+
+@c TTTTTTTTTTTTTTTTTTTTTTTTTT
+
+@cindex @code{.thumb} directive, ARM
+@item .thumb
+This performs the same action as @var{.code 16}.
+
+@cindex @code{.thumb_func} directive, ARM
+@item .thumb_func
+This directive specifies that the following symbol is the name of a
+Thumb encoded function. This information is necessary in order to allow
+the assembler and linker to generate correct code for interworking
+between Arm and Thumb instructions and should be used even if
+interworking is not going to be performed. The presence of this
+directive also implies @code{.thumb}
+
+This directive is not neccessary when generating EABI objects. On these
+targets the encoding is implicit when generating Thumb code.
+
+@cindex @code{.thumb_set} directive, ARM
+@item .thumb_set
+This performs the equivalent of a @code{.set} directive in that it
+creates a symbol which is an alias for another symbol (possibly not yet
+defined). This directive also has the added property in that it marks
+the aliased symbol as being a thumb function entry point, in the same
+way that the @code{.thumb_func} directive does.
+
+@c UUUUUUUUUUUUUUUUUUUUUUUUUU
+
+@cindex @code{.unreq} directive, ARM
+@item .unreq @var{alias-name}
+This undefines a register alias which was previously defined using the
+@code{req}, @code{dn} or @code{qn} directives. For example:
+
+@smallexample
+ foo .req r0
+ .unreq foo
+@end smallexample
+
+An error occurs if the name is undefined. Note - this pseudo op can
+be used to delete builtin in register name aliases (eg 'r0'). This
+should only be done if it is really necessary.
+
@cindex @code{.unwind_raw} directive, ARM
-@item .raw @var{offset}, @var{byte1}, @dots{}
+@item .unwind_raw @var{offset}, @var{byte1}, @dots{}
Insert one of more arbitary unwind opcode bytes, which are known to adjust
the stack pointer by @var{offset} bytes.
For example @code{.unwind_raw 4, 0xb1, 0x01} is equivalent to
@code{.save @{r0@}}
-@cindex @code{.cpu} directive, ARM
-@item .cpu @var{name}
-Select the target processor. Valid values for @var{name} are the same as
-for the @option{-mcpu} commandline option.
+@c VVVVVVVVVVVVVVVVVVVVVVVVVV
-@cindex @code{.arch} directive, ARM
-@item .arch @var{name}
-Select the target architecture. Valid values for @var{name} are the same as
-for the @option{-march} commandline option.
+@cindex @code{.vsave} directive, ARM
+@item .vsave @var{vfp-reglist}
+Generate unwinder annotations to restore the VFP registers in @var{vfp-reglist}
+using FLDMD. Also works for VFPv3 registers
+that are to be restored using VLDM.
+The format of @var{vfp-reglist} is the same as the corresponding store-multiple
+instruction.
-@cindex @code{.object_arch} directive, ARM
-@item .object_arch @var{name}
-Override the architecture recorded in the EABI object attribute section.
-Valid values for @var{name} are the same as for the @code{.arch} directive.
-Typically this is useful when code uses runtime detection of CPU features.
+@smallexample
+@exdent @emph{VFP registers}
+ .vsave @{d8, d9, d10@}
+ fstmdd sp!, @{d8, d9, d10@}
+@exdent @emph{VFPv3 registers}
+ .vsave @{d15, d16, d17@}
+ vstm sp!, @{d15, d16, d17@}
+@end smallexample
-@cindex @code{.fpu} directive, ARM
-@item .fpu @var{name}
-Select the floating point unit to assemble for. Valid values for @var{name}
-are the same as for the @option{-mfpu} commandline option.
+Since FLDMX and FSTMX are now deprecated, this directive should be
+used in favour of @code{.save} for saving VFP registers for ARMv6 and above.
-@cindex @code{.eabi_attribute} directive, ARM
-@item .eabi_attribute @var{tag}, @var{value}
-Set the EABI object attribute number @var{tag} to @var{value}. The value
-is either a @code{number}, @code{"string"}, or @code{number, "string"}
-depending on the tag.
+@c WWWWWWWWWWWWWWWWWWWWWWWWWW
+@c XXXXXXXXXXXXXXXXXXXXXXXXXX
+@c YYYYYYYYYYYYYYYYYYYYYYYYYY
+@c ZZZZZZZZZZZZZZZZZZZZZZZZZZ
@end table
dropped from the new EABI and so tools cannot rely upon their
presence.
+@node ARM Unwinding Tutorial
+@section Unwinding
+
+The ABI for the ARM Architecture specifies a standard format for
+exception unwind information. This information is used when an
+exception is thrown to determine where control should be transferred.
+In particular, the unwind information is used to determine which
+function called the function that threw the exception, and which
+function called that one, and so forth. This information is also used
+to restore the values of callee-saved registers in the function
+catching the exception.
+
+If you are writing functions in assembly code, and those functions
+call other functions that throw exceptions, you must use assembly
+pseudo ops to ensure that appropriate exception unwind information is
+generated. Otherwise, if one of the functions called by your assembly
+code throws an exception, the run-time library will be unable to
+unwind the stack through your assembly code and your program will not
+behave correctly.
+
+To illustrate the use of these pseudo ops, we will examine the code
+that G++ generates for the following C++ input:
+
+@verbatim
+void callee (int *);
+
+int
+caller ()
+{
+ int i;
+ callee (&i);
+ return i;
+}
+@end verbatim
+
+This example does not show how to throw or catch an exception from
+assembly code. That is a much more complex operation and should
+always be done in a high-level language, such as C++, that directly
+supports exceptions.
+
+The code generated by one particular version of G++ when compiling the
+example above is:
+
+@verbatim
+_Z6callerv:
+ .fnstart
+.LFB2:
+ @ Function supports interworking.
+ @ args = 0, pretend = 0, frame = 8
+ @ frame_needed = 1, uses_anonymous_args = 0
+ stmfd sp!, {fp, lr}
+ .save {fp, lr}
+.LCFI0:
+ .setfp fp, sp, #4
+ add fp, sp, #4
+.LCFI1:
+ .pad #8
+ sub sp, sp, #8
+.LCFI2:
+ sub r3, fp, #8
+ mov r0, r3
+ bl _Z6calleePi
+ ldr r3, [fp, #-8]
+ mov r0, r3
+ sub sp, fp, #4
+ ldmfd sp!, {fp, lr}
+ bx lr
+.LFE2:
+ .fnend
+@end verbatim
+
+Of course, the sequence of instructions varies based on the options
+you pass to GCC and on the version of GCC in use. The exact
+instructions are not important since we are focusing on the pseudo ops
+that are used to generate unwind information.
+
+An important assumption made by the unwinder is that the stack frame
+does not change during the body of the function. In particular, since
+we assume that the assembly code does not itself throw an exception,
+the only point where an exception can be thrown is from a call, such
+as the @code{bl} instruction above. At each call site, the same saved
+registers (including @code{lr}, which indicates the return address)
+must be located in the same locations relative to the frame pointer.
+
+The @code{.fnstart} (@pxref{arm_fnstart,,.fnstart pseudo op}) pseudo
+op appears immediately before the first instruction of the function
+while the @code{.fnend} (@pxref{arm_fnend,,.fnend pseudo op}) pseudo
+op appears immediately after the last instruction of the function.
+These pseudo ops specify the range of the function.
+
+Only the order of the other pseudos ops (e.g., @code{.setfp} or
+@code{.pad}) matters; their exact locations are irrelevant. In the
+example above, the compiler emits the pseudo ops with particular
+instructions. That makes it easier to understand the code, but it is
+not required for correctness. It would work just as well to emit all
+of the pseudo ops other than @code{.fnend} in the same order, but
+immediately after @code{.fnstart}.
+
+The @code{.save} (@pxref{arm_save,,.save pseudo op}) pseudo op
+indicates registers that have been saved to the stack so that they can
+be restored before the function returns. The argument to the
+@code{.save} pseudo op is a list of registers to save. If a register
+is ``callee-saved'' (as specified by the ABI) and is modified by the
+function you are writing, then your code must save the value before it
+is modified and restore the original value before the function
+returns. If an exception is thrown, the run-time library restores the
+values of these registers from their locations on the stack before
+returning control to the exception handler. (Of course, if an
+exception is not thrown, the function that contains the @code{.save}
+pseudo op restores these registers in the function epilogue, as is
+done with the @code{ldmfd} instruction above.)
+
+You do not have to save callee-saved registers at the very beginning
+of the function and you do not need to use the @code{.save} pseudo op
+immediately following the point at which the registers are saved.
+However, if you modify a callee-saved register, you must save it on
+the stack before modifying it and before calling any functions which
+might throw an exception. And, you must use the @code{.save} pseudo
+op to indicate that you have done so.
+
+The @code{.pad} (@pxref{arm_pad,,.pad}) pseudo op indicates a
+modification of the stack pointer that does not save any registers.
+The argument is the number of bytes (in decimal) that are subtracted
+from the stack pointer. (On ARM CPUs, the stack grows downwards, so
+subtracting from the stack pointer increases the size of the stack.)
+
+The @code{.setfp} (@pxref{arm_setfp,,.setfp pseudo op}) pseudo op
+indicates the register that contains the frame pointer. The first
+argument is the register that is set, which is typically @code{fp}.
+The second argument indicates the register from which the frame
+pointer takes its value. The third argument, if present, is the value
+(in decimal) added to the register specified by the second argument to
+compute the value of the frame pointer. You should not modify the
+frame pointer in the body of the function.
+
+If you do not use a frame pointer, then you should not use the
+@code{.setfp} pseudo op. If you do not use a frame pointer, then you
+should avoid modifying the stack pointer outside of the function
+prologue. Otherwise, the run-time library will be unable to find
+saved registers when it is unwinding the stack.
+
+The pseudo ops described above are sufficient for writing assembly
+code that calls functions which may throw exceptions. If you need to
+know more about the object-file format used to represent unwind
+information, you may consult the @cite{Exception Handling ABI for the
+ARM Architecture} available from @uref{http://infocenter.arm.com}.
projects / msp430-binutils.git / blobdiff