X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gas%2Fdoc%2Fc-arm.texi;h=5e518c69fed6d9750ad13462e89ef2ca34614fc7;hb=dec41383fff7116c9f66cdeca3105e968047a4e6;hp=b6ac8b1c22c98c0cb35f03c3cb2fd3c322241949;hpb=aa820537ead0135a7c38c619039dce8a6fc74ed1;p=deliverable%2Fbinutils-gdb.git diff --git a/gas/doc/c-arm.texi b/gas/doc/c-arm.texi index b6ac8b1c22..5e518c69fe 100644 --- a/gas/doc/c-arm.texi +++ b/gas/doc/c-arm.texi @@ -1,5 +1,4 @@ -@c Copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, -@c 2006, 2007, 2008, 2009 Free Software Foundation, Inc. +@c Copyright (C) 1996-2017 Free Software Foundation, Inc. @c This is part of the GAS manual. @c For copying conditions, see the file as.texinfo. @@ -38,7 +37,7 @@ 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: +recognized: @code{arm1}, @code{arm2}, @code{arm250}, @@ -102,7 +101,10 @@ recognized: @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}, @@ -112,36 +114,96 @@ recognized: @code{arm1176jzf-s}, @code{mpcore}, @code{mpcorenovfp}, +@code{cortex-a5}, +@code{cortex-a7}, @code{cortex-a8}, @code{cortex-a9}, +@code{cortex-a15}, +@code{cortex-a17}, +@code{cortex-a32}, +@code{cortex-a35}, +@code{cortex-a53}, +@code{cortex-a55}, +@code{cortex-a57}, +@code{cortex-a72}, +@code{cortex-a73}, +@code{cortex-a75}, @code{cortex-r4}, +@code{cortex-r4f}, +@code{cortex-r5}, +@code{cortex-r7}, +@code{cortex-r8}, +@code{cortex-r52}, +@code{cortex-m33}, +@code{cortex-m23}, +@code{cortex-m7}, +@code{cortex-m4}, @code{cortex-m3}, @code{cortex-m1}, @code{cortex-m0}, +@code{cortex-m0plus}, +@code{exynos-m1}, +@code{marvell-pj4}, +@code{marvell-whitney}, +@code{xgene1}, +@code{xgene2}, @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}. +@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 +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}. The following extensions -are currently supported: -@code{+maverick} -@code{+iwmmxt} +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{crc} +@code{crypto} (Cryptography Extensions for v8-A architecture, implies @code{fp+simd}), +@code{dotprod} (Dot Product Extensions for v8.2-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{xscale}, +@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}), +@code{pan} (Privileged Access Never Extensions for v8-A architecture), +@code{ras} (Reliability, Availability and Serviceability extensions +for v8-A architecture), +@code{rdma} (ARMv8.1 Advanced SIMD extensions for v8-A architecture, implies +@code{simd}) and -@code{+xscale}. +@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: +will not execute on the target architecture. The following architecture +names are recognized: @code{armv1}, @code{armv2}, @code{armv2a}, @@ -161,12 +223,23 @@ names are recognized: @code{armv6j}, @code{armv6k}, @code{armv6z}, -@code{armv6zk}, +@code{armv6kz}, +@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{armv8.1-a}, +@code{armv8.2-a}, +@code{armv8.3-a}, +@code{armv8-r}, +@code{armv8.4-a}, @code{iwmmxt} +@code{iwmmxt2} and @code{xscale}. If both @code{-mcpu} and @@ -181,7 +254,7 @@ extension options as the @code{-mcpu} option. 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. +an instruction which will not execute on the target floating point unit. The following format options are recognized: @code{softfpa}, @code{fpe}, @@ -198,28 +271,45 @@ The following format options are recognized: @code{vfp10-r0}, @code{vfp9}, @code{vfpxd}, -@code{vfpv2} -@code{vfpv3} -@code{vfpv3-d16} +@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{fpv5-sp-d16}, +@code{fpv5-d16}, +@code{fp-armv8}, @code{arm1020t}, @code{arm1020e}, @code{arm1136jf-s}, -@code{maverick} +@code{maverick}, +@code{neon}, +@code{neon-vfpv3}, +@code{neon-fp16}, +@code{neon-vfpv4}, +@code{neon-fp-armv8}, +@code{crypto-neon-fp-armv8}, +@code{neon-fp-armv8.1} and -@code{neon}. +@code{crypto-neon-fp-armv8.1}. 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 +The default is dependent on the processor selected. For Architecture 5 or +later, the default is to assemble 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 +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 @@ -245,15 +335,17 @@ 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 +@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 +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 @@ -295,6 +387,12 @@ and This option specifies that the output generated by the assembler should be marked as being encoded for a big-endian processor. +Note: If a program is being built for a system with big-endian data +and little-endian instructions then it should be assembled with the +@option{-EB} option, (all of it, code and data) and then linked with +the @option{--be8} option. This will reverse the endianness of the +instructions back to little-endian, but leave the data as big-endian. + @cindex @code{-EL} command line option, ARM @item -EL This option specifies that the output generated by the assembler should @@ -317,6 +415,16 @@ the linker option of the same name. Enable or disable warnings about using deprecated options or features. The default is to warn. +@cindex @code{-mccs} command line option, ARM +@item -mccs +Turns on CodeComposer Studio assembly syntax compatibility mode. + +@cindex @code{-mwarn-syms} command line option, ARM +@item -mwarn-syms +@itemx -mno-warn-syms +Enable or disable warnings about symbols that match the names of ARM +instructions. The default is to warn. + @end table @@ -327,6 +435,7 @@ features. The default is to warn. * ARM-Chars:: Special Characters * ARM-Regs:: Register Names * ARM-Relocations:: Relocations +* ARM-Neon-Alignment:: NEON Alignment Specifiers @end menu @node ARM-Instruction-Set @@ -337,7 +446,7 @@ 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 +@itemize @bullet @item Immediate operands do not require a @code{#} prefix. @@ -362,16 +471,20 @@ 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 +@end itemize @node ARM-Chars @subsection Special Characters @cindex line comment character, ARM @cindex ARM line comment character -The presence of a @samp{@@} on a line indicates the start of a comment -that extends to the end of the current line. If a @samp{#} appears as -the first character of a line, the whole line is treated as a comment. +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 @@ -394,13 +507,6 @@ Either @samp{#} or @samp{$} can be used to indicate immediate operands. @cindex register names, ARM *TODO* Explain about ARM register naming, and the predefined names. -@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-Relocations @subsection ARM relocation generation @@ -424,13 +530,18 @@ The following relocations are supported: @code{TLSGD}, @code{TLSLDM}, @code{TLSLDO}, -@code{GOTTPOFF} +@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. This will generate the deprecated -@samp{R_ARM_PLT32} relocation. +@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 @@ -442,6 +553,44 @@ respectively. For example to load the 32-bit address of foo into r0: MOVT r0, #:upper16:foo @end smallexample +Relocations @samp{R_ARM_THM_ALU_ABS_G0_NC}, @samp{R_ARM_THM_ALU_ABS_G1_NC}, +@samp{R_ARM_THM_ALU_ABS_G2_NC} and @samp{R_ARM_THM_ALU_ABS_G3_NC} can be +generated by prefixing the value with @samp{#:lower0_7:#}, +@samp{#:lower8_15:#}, @samp{#:upper0_7:#} and @samp{#:upper8_15:#} +respectively. For example to load the 32-bit address of foo into r0: + +@smallexample + MOVS r0, #:upper8_15:#foo + LSLS r0, r0, #8 + ADDS r0, #:upper0_7:#foo + LSLS r0, r0, #8 + ADDS r0, #:lower8_15:#foo + LSLS r0, r0, #8 + ADDS r0, #:lower0_7:#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 @@ -451,6 +600,7 @@ respectively. For example to load the 32-bit address of foo into r0: @c AAAAAAAAAAAAAAAAAAAAAAAAA +@ifclear ELF @cindex @code{.2byte} directive, ARM @cindex @code{.4byte} directive, ARM @cindex @code{.8byte} directive, ARM @@ -458,6 +608,7 @@ respectively. For example to load the 32-bit address of foo into r0: @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. +@end ifclear @cindex @code{.align} directive, ARM @item .align @var{expression} [, @var{expression}] @@ -471,17 +622,22 @@ boundary). This is for compatibility with ARM's own assembler. 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 @@ -505,11 +661,14 @@ selects Thumb, with the value 32 selecting ARM. 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}]] -@item @var{name} .qn @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 @@ -546,26 +705,31 @@ 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_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_align8_needed}, @code{Tag_ABI_align8_preserved}, +@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_VFP_HP_extension}, @code{Tag_ABI_FP_16bit_format}, +@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}, @code{Tag_MPextension_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. @@ -621,8 +785,8 @@ directive. @cindex @code{.inst} directive, ARM @item .inst @var{opcode} [ , @dots{} ] -@item .inst.n @var{opcode} [ , @dots{} ] -@item .inst.w @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. @@ -673,6 +837,7 @@ This directive writes 12-byte packed floating-point values to the output section. These are not compatible with current ARM processors or ABIs. +@anchor{arm_pad} @cindex @code{.pad} directive, ARM @item .pad #@var{count} Generate unwinder annotations for a stack adjustment of @var{count} bytes. @@ -740,7 +905,7 @@ or 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} +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. @@ -749,7 +914,7 @@ instruction used to set the frame pointer. @var{spreg} must be either mov ip, sp @dots{} .setfp fp, ip, #4 -sub fp, ip, #4 +add fp, ip, #4 @end smallexample @cindex @code{.secrel32} directive, ARM @@ -778,7 +943,7 @@ 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 +This directive is not necessary when generating EABI objects. On these targets the encoding is implicit when generating Thumb code. @cindex @code{.thumb_set} directive, ARM @@ -789,6 +954,12 @@ 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 @@ -807,7 +978,7 @@ 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 +Insert one of more arbitrary 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 @@ -849,7 +1020,7 @@ used in favour of @code{.save} for saving VFP registers for ARMv6 and above. @cindex opcodes for ARM @code{@value{AS}} implements all the standard ARM opcodes. It also implements several pseudo opcodes, including several synthetic load -instructions. +instructions. @table @code @@ -863,7 +1034,7 @@ 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,=