diff options
Diffstat (limited to 'binutils-2.24/gas/doc/c-arm.texi')
| -rw-r--r-- | binutils-2.24/gas/doc/c-arm.texi | 1189 |
1 files changed, 0 insertions, 1189 deletions
diff --git a/binutils-2.24/gas/doc/c-arm.texi b/binutils-2.24/gas/doc/c-arm.texi deleted file mode 100644 index b4b2d953..00000000 --- a/binutils-2.24/gas/doc/c-arm.texi +++ /dev/null @@ -1,1189 +0,0 @@ -@c Copyright 1996-2013 Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. - -@ifset GENERIC -@page -@node ARM-Dependent -@chapter ARM Dependent Features -@end ifset - -@ifclear GENERIC -@node Machine Dependencies -@chapter ARM Dependent Features -@end ifclear - -@cindex ARM support -@cindex Thumb support -@menu -* ARM Options:: Options -* ARM Syntax:: Syntax -* ARM Floating Point:: Floating Point -* ARM Directives:: ARM Machine Directives -* ARM Opcodes:: Opcodes -* ARM Mapping Symbols:: Mapping Symbols -* ARM Unwinding Tutorial:: Unwinding -@end menu - -@node ARM Options -@section Options -@cindex ARM options (none) -@cindex options for ARM (none) - -@table @code - -@cindex @code{-mcpu=} command line option, ARM -@item -mcpu=@var{processor}[+@var{extension}@dots{}] -This option specifies the target processor. The assembler will issue an -error message if an attempt is made to assemble an instruction which -will not execute on the target processor. The following processor names are -recognized: -@code{arm1}, -@code{arm2}, -@code{arm250}, -@code{arm3}, -@code{arm6}, -@code{arm60}, -@code{arm600}, -@code{arm610}, -@code{arm620}, -@code{arm7}, -@code{arm7m}, -@code{arm7d}, -@code{arm7dm}, -@code{arm7di}, -@code{arm7dmi}, -@code{arm70}, -@code{arm700}, -@code{arm700i}, -@code{arm710}, -@code{arm710t}, -@code{arm720}, -@code{arm720t}, -@code{arm740t}, -@code{arm710c}, -@code{arm7100}, -@code{arm7500}, -@code{arm7500fe}, -@code{arm7t}, -@code{arm7tdmi}, -@code{arm7tdmi-s}, -@code{arm8}, -@code{arm810}, -@code{strongarm}, -@code{strongarm1}, -@code{strongarm110}, -@code{strongarm1100}, -@code{strongarm1110}, -@code{arm9}, -@code{arm920}, -@code{arm920t}, -@code{arm922t}, -@code{arm940t}, -@code{arm9tdmi}, -@code{fa526} (Faraday FA526 processor), -@code{fa626} (Faraday FA626 processor), -@code{arm9e}, -@code{arm926e}, -@code{arm926ej-s}, -@code{arm946e-r0}, -@code{arm946e}, -@code{arm946e-s}, -@code{arm966e-r0}, -@code{arm966e}, -@code{arm966e-s}, -@code{arm968e-s}, -@code{arm10t}, -@code{arm10tdmi}, -@code{arm10e}, -@code{arm1020}, -@code{arm1020t}, -@code{arm1020e}, -@code{arm1022e}, -@code{arm1026ej-s}, -@code{fa606te} (Faraday FA606TE processor), -@code{fa616te} (Faraday FA616TE processor), -@code{fa626te} (Faraday FA626TE processor), -@code{fmp626} (Faraday FMP626 processor), -@code{fa726te} (Faraday FA726TE processor), -@code{arm1136j-s}, -@code{arm1136jf-s}, -@code{arm1156t2-s}, -@code{arm1156t2f-s}, -@code{arm1176jz-s}, -@code{arm1176jzf-s}, -@code{mpcore}, -@code{mpcorenovfp}, -@code{cortex-a5}, -@code{cortex-a7}, -@code{cortex-a8}, -@code{cortex-a9}, -@code{cortex-a15}, -@code{cortex-r4}, -@code{cortex-r4f}, -@code{cortex-r5}, -@code{cortex-r7}, -@code{cortex-m4}, -@code{cortex-m3}, -@code{cortex-m1}, -@code{cortex-m0}, -@code{cortex-m0plus}, -@code{ep9312} (ARM920 with Cirrus Maverick coprocessor), -@code{i80200} (Intel XScale processor) -@code{iwmmxt} (Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) -and -@code{xscale}. -The special name @code{all} may be used to allow the -assembler to accept instructions valid for any ARM processor. - -In addition to the basic instruction set, the assembler can be told to -accept various extension mnemonics that extend the processor using the -co-processor instruction space. For example, @code{-mcpu=arm920+maverick} -is equivalent to specifying @code{-mcpu=ep9312}. - -Multiple extensions may be specified, separated by a @code{+}. The -extensions should be specified in ascending alphabetical order. - -Some extensions may be restricted to particular architectures; this is -documented in the list of extensions below. - -Extension mnemonics may also be removed from those the assembler accepts. -This is done be prepending @code{no} to the option that adds the extension. -Extensions that are removed should be listed after all extensions which have -been added, again in ascending alphabetical order. For example, -@code{-mcpu=ep9312+nomaverick} is equivalent to specifying @code{-mcpu=arm920}. - - -The following extensions are currently supported: -@code{crypto} (Cryptography Extensions for v8-A architecture, implies @code{fp+simd}), -@code{fp} (Floating Point Extensions for v8-A architecture), -@code{idiv} (Integer Divide Extensions for v7-A and v7-R architectures), -@code{iwmmxt}, -@code{iwmmxt2}, -@code{maverick}, -@code{mp} (Multiprocessing Extensions for v7-A and v7-R architectures), -@code{os} (Operating System for v6M architecture), -@code{sec} (Security Extensions for v6K and v7-A architectures), -@code{simd} (Advanced SIMD Extensions for v8-A architecture, implies @code{fp}), -@code{virt} (Virtualization Extensions for v7-A architecture, implies -@code{idiv}), -and -@code{xscale}. - -@cindex @code{-march=} command line option, ARM -@item -march=@var{architecture}[+@var{extension}@dots{}] -This option specifies the target architecture. The assembler will issue -an error message if an attempt is made to assemble an instruction which -will not execute on the target architecture. The following architecture -names are recognized: -@code{armv1}, -@code{armv2}, -@code{armv2a}, -@code{armv2s}, -@code{armv3}, -@code{armv3m}, -@code{armv4}, -@code{armv4xm}, -@code{armv4t}, -@code{armv4txm}, -@code{armv5}, -@code{armv5t}, -@code{armv5txm}, -@code{armv5te}, -@code{armv5texp}, -@code{armv6}, -@code{armv6j}, -@code{armv6k}, -@code{armv6z}, -@code{armv6zk}, -@code{armv6-m}, -@code{armv6s-m}, -@code{armv7}, -@code{armv7-a}, -@code{armv7ve}, -@code{armv7-r}, -@code{armv7-m}, -@code{armv7e-m}, -@code{armv8-a}, -@code{iwmmxt} -and -@code{xscale}. -If both @code{-mcpu} and -@code{-march} are specified, the assembler will use -the setting for @code{-mcpu}. - -The architecture option can be extended with the same instruction set -extension options as the @code{-mcpu} option. - -@cindex @code{-mfpu=} command line option, ARM -@item -mfpu=@var{floating-point-format} - -This option specifies the floating point format to assemble for. The -assembler will issue an error message if an attempt is made to assemble -an instruction which will not execute on the target floating point unit. -The following format options are recognized: -@code{softfpa}, -@code{fpe}, -@code{fpe2}, -@code{fpe3}, -@code{fpa}, -@code{fpa10}, -@code{fpa11}, -@code{arm7500fe}, -@code{softvfp}, -@code{softvfp+vfp}, -@code{vfp}, -@code{vfp10}, -@code{vfp10-r0}, -@code{vfp9}, -@code{vfpxd}, -@code{vfpv2}, -@code{vfpv3}, -@code{vfpv3-fp16}, -@code{vfpv3-d16}, -@code{vfpv3-d16-fp16}, -@code{vfpv3xd}, -@code{vfpv3xd-d16}, -@code{vfpv4}, -@code{vfpv4-d16}, -@code{fpv4-sp-d16}, -@code{fp-armv8}, -@code{arm1020t}, -@code{arm1020e}, -@code{arm1136jf-s}, -@code{maverick}, -@code{neon}, -@code{neon-vfpv4}, -@code{neon-fp-armv8}, -and -@code{crypto-neon-fp-armv8}. - -In addition to determining which instructions are assembled, this option -also affects the way in which the @code{.double} assembler directive behaves -when assembling little-endian code. - -The default is dependent on the processor selected. For Architecture 5 or -later, the default is to assembler for VFP instructions; for earlier -architectures the default is to assemble for FPA instructions. - -@cindex @code{-mthumb} command line option, ARM -@item -mthumb -This option specifies that the assembler should start assembling Thumb -instructions; that is, it should behave as though the file starts with a -@code{.code 16} directive. - -@cindex @code{-mthumb-interwork} command line option, ARM -@item -mthumb-interwork -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-26} command line option, ARM -@cindex @code{-mapcs-32} command line option, ARM -@item -mapcs-26 -@itemx -mapcs-32 -These options specify that the output generated by the assembler should -be marked as supporting the indicated version of the Arm Procedure. -Calling Standard. - -@cindex @code{-matpcs} command line option, ARM -@item -matpcs -This option specifies that the output generated by the assembler should -be marked as supporting the Arm/Thumb Procedure Calling Standard. If -enabled this option will cause the assembler to create an empty -debugging section in the object file called .arm.atpcs. Debuggers can -use this to determine the ABI being used by. - -@cindex @code{-mapcs-float} command line option, ARM -@item -mapcs-float -This indicates the floating point variant of the APCS should be -used. In this variant floating point arguments are passed in FP -registers rather than integer registers. - -@cindex @code{-mapcs-reentrant} command line option, ARM -@item -mapcs-reentrant -This indicates that the reentrant variant of the APCS should be used. -This variant supports position independent code. - -@cindex @code{-mfloat-abi=} command line option, ARM -@item -mfloat-abi=@var{abi} -This option specifies that the output generated by the assembler should be -marked as using specified floating point ABI. -The following values are recognized: -@code{soft}, -@code{softfp} -and -@code{hard}. - -@cindex @code{-eabi=} command line option, ARM -@item -meabi=@var{ver} -This option specifies which EABI version the produced object files should -conform to. -The following values are recognized: -@code{gnu}, -@code{4} -and -@code{5}. - -@cindex @code{-EB} command line option, ARM -@item -EB -This option specifies that the output generated by the assembler should -be marked as being encoded for a big-endian processor. - -@cindex @code{-EL} command line option, ARM -@item -EL -This option specifies that the output generated by the assembler should -be marked as being encoded for a little-endian processor. - -@cindex @code{-k} command line option, ARM -@cindex PIC code generation for ARM -@item -k -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 -* ARM-Neon-Alignment:: NEON Alignment Specifiers -@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: - -@itemize @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 itemize - -@node ARM-Chars -@subsection Special Characters - -@cindex line comment character, ARM -@cindex ARM line comment character -The presence of a @samp{@@} anywhere on a line indicates the start of -a comment that extends to the end of that line. - -If a @samp{#} appears as the first character of a line then the whole -line is treated as a comment, but in this case the line could also be -a logical line number directive (@pxref{Comments}) or a preprocessor -control command (@pxref{Preprocessing}). - -@cindex line separator, ARM -@cindex statement separator, ARM -@cindex ARM line separator -The @samp{;} character can be used instead of a newline to separate -statements. - -@cindex immediate character, ARM -@cindex ARM immediate character -Either @samp{#} or @samp{$} can be used to indicate immediate operands. - -@cindex identifiers, ARM -@cindex ARM identifiers -*TODO* Explain about /data modifier on symbols. - -@node ARM-Regs -@subsection Register Names - -@cindex ARM register names -@cindex register names, ARM -*TODO* Explain about ARM register naming, and the predefined names. - -@node ARM-Relocations -@subsection ARM relocation generation - -@cindex data relocations, ARM -@cindex ARM data relocations -Specific data relocations can be generated by putting the relocation name -in parentheses after the symbol name. For example: - -@smallexample - .word foo(TARGET1) -@end smallexample - -This will generate an @samp{R_ARM_TARGET1} relocation against the symbol -@var{foo}. -The following relocations are supported: -@code{GOT}, -@code{GOTOFF}, -@code{TARGET1}, -@code{TARGET2}, -@code{SBREL}, -@code{TLSGD}, -@code{TLSLDM}, -@code{TLSLDO}, -@code{TLSDESC}, -@code{TLSCALL}, -@code{GOTTPOFF}, -@code{GOT_PREL} -and -@code{TPOFF}. - -For compatibility with older toolchains the assembler also accepts -@code{(PLT)} after branch targets. On legacy targets this will -generate the deprecated @samp{R_ARM_PLT32} relocation. On EABI -targets it will encode either the @samp{R_ARM_CALL} or -@samp{R_ARM_JUMP24} relocation, as appropriate. - -@cindex MOVW and MOVT relocations, ARM -Relocations for @samp{MOVW} and @samp{MOVT} instructions can be generated -by prefixing the value with @samp{#:lower16:} and @samp{#:upper16} -respectively. For example to load the 32-bit address of foo into r0: - -@smallexample - MOVW r0, #:lower16:foo - MOVT r0, #:upper16:foo -@end smallexample - -@node ARM-Neon-Alignment -@subsection NEON Alignment Specifiers - -@cindex alignment for NEON instructions -Some NEON load/store instructions allow an optional address -alignment qualifier. -The ARM documentation specifies that this is indicated by -@samp{@@ @var{align}}. However GAS already interprets -the @samp{@@} character as a "line comment" start, -so @samp{: @var{align}} is used instead. For example: - -@smallexample - vld1.8 @{q0@}, [r0, :128] -@end smallexample - -@node ARM Floating Point -@section Floating Point - -@cindex floating point, ARM (@sc{ieee}) -@cindex ARM floating point (@sc{ieee}) -The ARM family uses @sc{ieee} floating-point numbers. - -@node ARM Directives -@section ARM Machine Directives - -@cindex machine directives, ARM -@cindex ARM machine directives -@table @code - -@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{.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. - -Specifying @code{.arch} clears any previously selected architecture -extensions. - -@cindex @code{.arch_extension} directive, ARM -@item .arch_extension @var{name} -Add or remove an architecture extension to the target architecture. Valid -values for @var{name} are the same as those accepted as architectural -extensions by the @option{-mcpu} commandline option. - -@code{.arch_extension} may be used multiple times to add or remove extensions -incrementally to the architecture being compiled for. - -@cindex @code{.arm} directive, ARM -@item .arm -This performs the same action as @var{.code 32}. - -@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. - -@c BBBBBBBBBBBBBBBBBBBBBBBBBB - -@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. - -Specifying @code{.cpu} clears any previously selected architecture -extensions. - -@c DDDDDDDDDDDDDDDDDDDDDDDDDD - -@cindex @code{.dn} and @code{.qn} directives, ARM -@item @var{name} .dn @var{register name} [@var{.type}] [[@var{index}]] -@itemx @var{name} .qn @var{register name} [@var{.type}] [[@var{index}]] - -The @code{dn} and @code{qn} directives are used to create typed -and/or indexed register aliases for use in Advanced SIMD Extension -(Neon) instructions. The former should be used to create aliases -of double-precision registers, and the latter to create aliases of -quad-precision registers. - -If these directives are used to create typed aliases, those aliases can -be used in Neon instructions instead of writing types after the mnemonic -or after each operand. For example: - -@smallexample - x .dn d2.f32 - y .dn d3.f32 - z .dn d4.f32[1] - vmul x,y,z -@end smallexample - -This is equivalent to writing the following: - -@smallexample - vmul.f32 d2,d3,d4[1] -@end smallexample - -Aliases created using @code{dn} or @code{qn} can be destroyed using -@code{unreq}. - -@c EEEEEEEEEEEEEEEEEEEEEEEEEE - -@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_FP_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_align_needed}, @code{Tag_ABI_align_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_FP_HP_extension}, @code{Tag_ABI_FP_16bit_format}, -@code{Tag_MPextension_use}, @code{Tag_DIV_use}, -@code{Tag_nodefaults}, @code{Tag_also_compatible_with}, -@code{Tag_conformance}, @code{Tag_T2EE_use}, -@code{Tag_Virtualization_use} - -The @var{value} is either a @code{number}, @code{"string"}, or -@code{number, "string"} depending on the tag. - -Note - the following legacy values are also accepted by @var{tag}: -@code{Tag_VFP_arch}, @code{Tag_ABI_align8_needed}, -@code{Tag_ABI_align8_preserved}, @code{Tag_VFP_HP_extension}, - -@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. - -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 -@item .force_thumb -This directive forces the selection of Thumb instructions, even if the -target processor does not support those instructions - -@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. - -@c GGGGGGGGGGGGGGGGGGGGGGGGGG -@c HHHHHHHHHHHHHHHHHHHHHHHHHH - -@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{} ] -@itemx .inst.n @var{opcode} [ , @dots{} ] -@itemx .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 -This directive causes the current contents of the literal pool to be -dumped into the current section (which is assumed to be the .text -section) at the current location (aligned to a word boundary). -@code{GAS} maintains a separate literal pool for each section and each -sub-section. The @code{.ltorg} directive will only affect the literal -pool of the current section and sub-section. At the end of assembly -all remaining, un-empty literal pools will automatically be dumped. - -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. - -@c MMMMMMMMMMMMMMMMMMMMMMMMMM - -@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. - -@c NNNNNNNNNNNNNNNNNNNNNNNNNN -@c OOOOOOOOOOOOOOOOOOOOOOOOOO - -@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. - -@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 @var{name}. - -@cindex @code{.personalityindex} directive, ARM -@item .personalityindex @var{index} -Sets the personality routine for the current function to the EABI standard -routine number @var{index} - -@cindex @code{.pool} directive, ARM -@item .pool -This is a synonym for .ltorg. - -@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}. -The format of @var{reglist} is the same as the corresponding store-multiple -instruction. - -@smallexample -@exdent @emph{core registers} - .save @{r4, r5, r6, lr@} - stmfd sp!, @{r4, r5, r6, lr@} -@exdent @emph{FPA registers} - .save f4, 2 - sfmfd f4, 2, [sp]! -@exdent @emph{VFP registers} - .save @{d8, d9, d10@} - fstmdx sp!, @{d8, d9, d10@} -@exdent @emph{iWMMXt registers} - .save @{wr10, wr11@} - wstrd wr11, [sp, #-8]! - wstrd wr10, [sp, #-8]! -or - .save wr11 - wstrd wr11, [sp, #-8]! - .save wr10 - wstrd wr10, [sp, #-8]! -@end smallexample - -@anchor{arm_setfp} -@cindex @code{.setfp} directive, ARM -@item .setfp @var{fpreg}, @var{spreg} [, #@var{offset}] -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{add} or @code{mov} -instruction used to set the frame pointer. @var{spreg} must be either -@code{sp} or mentioned in a previous @code{.movsp} directive. - -@smallexample -.movsp ip -mov ip, sp -@dots{} -.setfp fp, ip, #4 -add 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. - -@cindex @code{.tlsdescseq} directive, ARM -@item .tlsdescseq @var{tls-variable} -This directive is used to annotate parts of an inlined TLS descriptor -trampoline. Normally the trampoline is provided by the linker, and -this directive is not needed. - -@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 .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@}} - -@c VVVVVVVVVVVVVVVVVVVVVVVVVV - -@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. - -@c WWWWWWWWWWWWWWWWWWWWWWWWWW -@c XXXXXXXXXXXXXXXXXXXXXXXXXX -@c YYYYYYYYYYYYYYYYYYYYYYYYYY -@c ZZZZZZZZZZZZZZZZZZZZZZZZZZ - -@end table - -@node ARM Opcodes -@section Opcodes - -@cindex ARM opcodes -@cindex opcodes for ARM -@code{@value{AS}} implements all the standard ARM opcodes. It also -implements several pseudo opcodes, including several synthetic load -instructions. - -@table @code - -@cindex @code{NOP} pseudo op, ARM -@item NOP -@smallexample - nop -@end smallexample - -This pseudo op will always evaluate to a legal ARM instruction that does -nothing. Currently it will evaluate to MOV r0, r0. - -@cindex @code{LDR reg,=<label>} pseudo op, ARM -@item LDR -@smallexample - ldr <register> , = <expression> -@end smallexample - -If expression evaluates to a numeric constant then a MOV or MVN -instruction will be used in place of the LDR instruction, if the -constant can be generated by either of these instructions. Otherwise -the constant will be placed into the nearest literal pool (if it not -already there) and a PC relative LDR instruction will be generated. - -@cindex @code{ADR reg,<label>} pseudo op, ARM -@item ADR -@smallexample - adr <register> <label> -@end smallexample - -This instruction will load the address of @var{label} into the indicated -register. The instruction will evaluate to a PC relative ADD or SUB -instruction depending upon where the label is located. If the label is -out of range, or if it is not defined in the same file (and section) as -the ADR instruction, then an error will be generated. This instruction -will not make use of the literal pool. - -@cindex @code{ADRL reg,<label>} pseudo op, ARM -@item ADRL -@smallexample - adrl <register> <label> -@end smallexample - -This instruction will load the address of @var{label} into the indicated -register. The instruction will evaluate to one or two PC relative ADD -or SUB instructions depending upon where the label is located. If a -second instruction is not needed a NOP instruction will be generated in -its place, so that this instruction is always 8 bytes long. - -If the label is out of range, or if it is not defined in the same file -(and section) as the ADRL instruction, then an error will be generated. -This instruction will not make use of the literal pool. - -@end table - -For information on the ARM or Thumb instruction sets, see @cite{ARM -Software Development Toolkit Reference Manual}, Advanced RISC Machines -Ltd. - -@node ARM Mapping Symbols -@section Mapping Symbols - -The ARM ELF specification requires that special symbols be inserted -into object files to mark certain features: - -@table @code - -@cindex @code{$a} -@item $a -At the start of a region of code containing ARM instructions. - -@cindex @code{$t} -@item $t -At the start of a region of code containing THUMB instructions. - -@cindex @code{$d} -@item $d -At the start of a region of data. - -@end table - -The assembler will automatically insert these symbols for you - there -is no need to code them yourself. Support for tagging symbols ($b, -$f, $p and $m) which is also mentioned in the current ARM ELF -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}. |