X-Git-Url: https://oss.titaniummirror.com/gitweb?p=msp430-binutils.git;a=blobdiff_plain;f=gas%2Fdoc%2Fc-arm.texi;fp=gas%2Fdoc%2Fc-arm.texi;h=b6ac8b1c22c98c0cb35f03c3cb2fd3c322241949;hp=404c8ef1b26d985f1cf0b135ba1a2ad4ecd905a0;hb=d5da4f291af551c0b8b79e1d4a9b173d60e5c10e;hpb=7b5ea4fcdf2819e070665ab5610f8b48e3867c10 diff --git a/gas/doc/c-arm.texi b/gas/doc/c-arm.texi index 404c8ef..b6ac8b1 100644 --- a/gas/doc/c-arm.texi +++ b/gas/doc/c-arm.texi @@ -1,5 +1,5 @@ -@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. @@ -23,6 +23,7 @@ * ARM Directives:: ARM Machine Directives * ARM Opcodes:: Opcodes * ARM Mapping Symbols:: Mapping Symbols +* ARM Unwinding Tutorial:: Unwinding @end menu @node ARM Options @@ -81,6 +82,8 @@ recognized: @code{arm922t}, @code{arm940t}, @code{arm9tdmi}, +@code{fa526} (Faraday FA526 processor), +@code{fa626} (Faraday FA626 processor), @code{arm9e}, @code{arm926e}, @code{arm926ej-s}, @@ -99,6 +102,8 @@ recognized: @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}, @@ -108,8 +113,11 @@ recognized: @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) @@ -190,11 +198,15 @@ The following format options are recognized: @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 @@ -215,6 +227,24 @@ instructions; that is, it should behave as though the file starts with a 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 @@ -276,17 +306,64 @@ be marked as being encoded for a little-endian processor. 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 @@ -372,37 +449,65 @@ respectively. For example to load the 32-bit address of foo into r0: @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}]] @@ -432,43 +537,102 @@ This is equivalent to writing the following: 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 @@ -484,27 +648,36 @@ Note - older versions of @code{GAS} would dump the current literal 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} @@ -515,15 +688,25 @@ Sets the personality routine for the current function to @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}. @@ -551,41 +734,10 @@ or 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} @@ -600,40 +752,93 @@ mov ip, sp 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 @@ -733,3 +938,149 @@ specification is not implemented. This is because they have been 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}.