Re: [PATCH 1/2, AArch64] gas docs missing for -mcpu/-march option

[Richard Earnshaw <rearnsha at arm dot com>]

On 13/03/14 12:09, Jiong Wang wrote:
> Currently, there are no -mcpu/-march documentations for AArch64.
> 
> This patch add the docs for them.
> 
> Please review.
> 

Thanks.

I've reworded some of this and committed the attached, which also
includes some other minor cleanups.

2014-03-13  Richard Earnshaw  <rearnsha@arm.com>
	    Jiong Wang  <Jiong.Wang@arm.com>

	* doc/c-aarch64.texi: Clean up some formatting issues.
	(AArch64 Options): Document -mcpu and -march.
	(AArch64 Extensions): New node.

> Thanks.
> Jiong
> 
> gas/
> 
>    * doc/c-aarch64.texi (AArch64 Options): Document -mcpu and -march.
> 
> 
> gas-doc.patch
> 
> 
> diff --git a/gas/doc/c-aarch64.texi b/gas/doc/c-aarch64.texi
> index 6019006..544d5ab 100644
> --- a/gas/doc/c-aarch64.texi
> +++ b/gas/doc/c-aarch64.texi
> @@ -50,6 +50,46 @@ Specify which ABI the source code uses.  The recognized arguments
>  are: @code{ilp32} and @code{lp64}, which decides the generated object
>  file in ELF32 and ELF64 format respectively.  The default is @code{lp64}.
>  
> +@cindex @code{-mcpu=} command line option, AArch64
> +@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{cortex-a53},
> +@code{cortex-a57},
> +and
> +@code{xgene-1}.
> +The special name @code{all} may be used to allow the assembler to accept
> +instructions valid for any ARMv8 processor.
> +
> +In addition to the basic instruction set, the assembler can be told to accept
> +various extension mnemonics that extend the processor.
> +
> +Multiple extensions may be specified, separated by a @code{+}.  Extension
> +mnemonics may also be removed from those the assembler accepts. This is done by
> +prepending @code{no} to the option that adds the extension.  Extensions that are
> +removed should be listed after all extensions which have been added.
> +
> +The following extensions are currently supported:
> +@code{crc} (Enable CRC instructions.),
> +@code{crypto} (Enable cryptographic extension.  This implies @code{fp} and @code{simd}.),
> +@code{fp} (Enable floating-point extension.),
> +and
> +@code{simd} (Enable Advanced SIMD extension, This implies @code{fp}.).
> +
> +@cindex @code{-march=} command line option, AArch64
> +@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 only value for @var{arch} is
> +@code{armv8-a}.
> +
> +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.
> +
>  @end table
>  @c man end
>  
> 

diff --git a/gas/doc/c-aarch64.texi b/gas/doc/c-aarch64.texi
index 51de642..65d465c 100644
--- a/gas/doc/c-aarch64.texi
+++ b/gas/doc/c-aarch64.texi
@@ -16,9 +16,9 @@
 @end ifclear
 
 @cindex AArch64 support
-@cindex Thumb support
 @menu
 * AArch64 Options::              Options
+* AArch64 Extensions::		 Extensions
 * AArch64 Syntax::               Syntax
 * AArch64 Floating Point::       Floating Point
 * AArch64 Directives::           AArch64 Machine Directives
@@ -34,25 +34,94 @@
 @c man begin OPTIONS
 @table @gcctabopt
 
-@cindex @code{-EB} command line option, AArch64
+@cindex @option{-EB} command line option, AArch64
 @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, AArch64
+@cindex @option{-EL} command line option, AArch64
 @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{-mabi=} command line option, AArch64
+@cindex @option{-mabi=} command line option, AArch64
 @item -mabi=@var{abi}
 Specify which ABI the source code uses.  The recognized arguments
 are: @code{ilp32} and @code{lp64}, which decides the generated object
 file in ELF32 and ELF64 format respectively.  The default is @code{lp64}.
 
+@cindex @option{-mcpu=} command line option, AArch64
+@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{cortex-a53},
+@code{cortex-a57},
+and
+@code{xgene-1}.
+The special name @code{all} may be used to allow the assembler to accept
+instructions valid for any supported processor, including all optional 
+extensions.
+
+In addition to the basic instruction set, the assembler can be told to
+accept, or restrict, various extension mnemonics that extend the
+processor.  @xref{AArch64 Extensions}.
+
+If some implementations of a particular processor can have an
+extension, then then those extensions are automatically enabled.
+Consequently, you will not normally have to specify any additional
+extensions.
+
+@cindex @option{-march=} command line option, AArch64
+@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
+only value for @var{architecture} is @code{armv8-a}.
+
+If both @option{-mcpu} and @option{-march} are specified, the
+assembler will use the setting for @option{-mcpu}.  If neither are
+specified, the assembler will default to @option{-mcpu=all}.
+
+The architecture option can be extended with the same instruction set
+extension options as the @option{-mcpu} option.  Unlike
+@option{-mcpu}, extensions are not always enabled by default,
+@xref{AArch64 Extensions}.
+
 @end table
 @c man end
 
+@node AArch64 Extensions
+@section Architecture Extensions
+
+The table below lists the permitted architecture extensions that are
+supported by the assembler and the conditions under which they are
+automatically enabled.  
+
+Multiple extensions may be specified, separated by a @code{+}.
+Extension mnemonics may also be removed from those the assembler
+accepts.  This is done by prepending @code{no} to the option that adds
+the extension.  Extensions that are removed must be listed after all
+extensions that have been added.  
+
+Enabling an extension that requires other extensions will
+automatically cause those extensions to be enabled.  Similarly,
+disabling an extension that is required by other extensions will
+automatically cause those extensions to be disabled.
+
+@multitable @columnfractions .12 .17 .17 .54
+@headitem Extension @tab Minimum Architecture @tab Enabled by default
+ @tab Description
+@item @code{crc} @tab ARMv8-A @tab No
+ @tab Enable CRC instructions.
+@item @code{crypto} @tab ARMv8-A @tab No
+ @tab Enable cryptographic extensions.  This implies @code{fp} and @code{simd}.
+@item @code{fp} @tab ARMv8-A @tab ARMv8-A or later
+ @tab Enable floating-point extensions.
+@item @code{simd} @tab ARMv8-A @tab ARMv8-A or later
+ @tab Enable Advanced SIMD extensions.  This implies @code{fp}.
+@end multitable
+
 @node AArch64 Syntax
 @section Syntax
 @menu
@@ -174,12 +243,12 @@ This directive switches to the @code{.bss} section.
 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
+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
+Note - older versions of 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.
 
@@ -240,7 +309,7 @@ should only be done if it is really necessary.
 
 @cindex AArch64 opcodes
 @cindex opcodes for AArch64
-@code{@value{AS}} implements all the standard AArch64 opcodes.  It also
+GAS implements all the standard AArch64 opcodes.  It also
 implements several pseudo opcodes, including several synthetic load
 instructions.