Re: [ARM Documentation] Clarify -mcpu, -mtune, -march

[James Greenhalgh <james dot greenhalgh at arm dot com>]

*ping*

Thanks,
James

On Mon, Jan 27, 2014 at 10:01:51AM +0000, James Greenhalgh wrote:
> 
> Hi,
> 
> I've tripped myself over with these three options too many times,
> actually, their behaviour is very simple.
> 
> This patch clarifies the language used to describe the options, and
> puts them in a logical order. I'm happy to reword again if this
> is still not clear.
> 
> OK?
> 
> Thanks,
> James
> 
> ---
> gcc/
> 
> 2014-01-27  James Greenhalgh  <james.greenhalgh@arm.com>
> 
> 	PR target/59718
> 	* doc/invoke.texi (-march=): Clarify documentation for ARM.
> 	(-mtune=): Likewise.
> 	(-mcpu=): Likewise.
> 

> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 8c620a5..38a55a0 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -12221,11 +12221,35 @@ option should only be used if you require compatibility with code for
>  big-endian ARM processors generated by versions of the compiler prior to
>  2.8.  This option is now deprecated.
>  
> -@item -mcpu=@var{name}
> -@opindex mcpu
> -This specifies the name of the target ARM processor.  GCC uses this name
> -to determine what kind of instructions it can emit when generating
> -assembly code.  Permissible names are: @samp{arm2}, @samp{arm250},
> +@item -march=@var{name}
> +@opindex march
> +This specifies the name of the target ARM architecture.  GCC uses this
> +name to determine what kind of instructions it can emit when generating
> +assembly code.  This option can be used in conjunction with or instead
> +of the @option{-mcpu=} option.  Permissible names are: @samp{armv2},
> +@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
> +@samp{armv5}, @samp{armv5t}, @samp{armv5e}, @samp{armv5te},
> +@samp{armv6}, @samp{armv6j},
> +@samp{armv6t2}, @samp{armv6z}, @samp{armv6zk}, @samp{armv6-m},
> +@samp{armv7}, @samp{armv7-a}, @samp{armv7-r}, @samp{armv7-m},
> +@samp{armv8-a}, @samp{armv8-a+crc},
> +@samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}.
> +
> +@option{-march=armv8-a+crc} enables code generation for the ARMv8-A
> +architecture together with the optional CRC32 extensions.
> +
> +@option{-march=native} causes the compiler to auto-detect the architecture
> +of the build computer.  At present, this feature is only supported on
> +Linux, and not all architectures are recognized.  If the auto-detect is
> +unsuccessful the option has no effect.
> +
> +@item -mtune=@var{name}
> +@opindex mtune
> +This option specifies the name of the target ARM processor for
> +which GCC should tune the performance of the code.
> +For some ARM implementations better performance can be obtained by using
> +this option.
> +Permissible names are: @samp{arm2}, @samp{arm250},
>  @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
>  @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
>  @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
> @@ -12259,26 +12283,6 @@ Additionally, this option can specify that GCC should tune the performance
>  of the code for a big.LITTLE system.  Permissible names are:
>  @samp{cortex-a15.cortex-a7}, @samp{cortex-a57.cortex-a53}.
>  
> -@option{-mcpu=generic-@var{arch}} is also permissible, and is
> -equivalent to @option{-march=@var{arch} -mtune=generic-@var{arch}}.
> -See @option{-mtune} for more information.
> -
> -@option{-mcpu=native} causes the compiler to auto-detect the CPU
> -of the build computer.  At present, this feature is only supported on
> -Linux, and not all architectures are recognized.  If the auto-detect is
> -unsuccessful the option has no effect.
> -
> -@item -mtune=@var{name}
> -@opindex mtune
> -This option is very similar to the @option{-mcpu=} option, except that
> -instead of specifying the actual target processor type, and hence
> -restricting which instructions can be used, it specifies that GCC should
> -tune the performance of the code as if the target were of the type
> -specified in this option, but still choosing the instructions it
> -generates based on the CPU specified by a @option{-mcpu=} option.
> -For some ARM implementations better performance can be obtained by using
> -this option.
> -
>  @option{-mtune=generic-@var{arch}} specifies that GCC should tune the
>  performance for a blend of processors within architecture @var{arch}.
>  The aim is to generate code that run well on the current most popular
> @@ -12291,24 +12295,21 @@ of the build computer.  At present, this feature is only supported on
>  Linux, and not all architectures are recognized.  If the auto-detect is
>  unsuccessful the option has no effect.
>  
> -@item -march=@var{name}
> -@opindex march
> -This specifies the name of the target ARM architecture.  GCC uses this
> -name to determine what kind of instructions it can emit when generating
> -assembly code.  This option can be used in conjunction with or instead
> -of the @option{-mcpu=} option.  Permissible names are: @samp{armv2},
> -@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
> -@samp{armv5}, @samp{armv5t}, @samp{armv5e}, @samp{armv5te},
> -@samp{armv6}, @samp{armv6j},
> -@samp{armv6t2}, @samp{armv6z}, @samp{armv6zk}, @samp{armv6-m},
> -@samp{armv7}, @samp{armv7-a}, @samp{armv7-r}, @samp{armv7-m},
> -@samp{armv8-a}, @samp{armv8-a+crc},
> -@samp{iwmmxt}, @samp{iwmmxt2}, @samp{ep9312}.
> +@item -mcpu=@var{name}
> +@opindex mcpu
> +This specifies the name of the target ARM processor.  GCC uses this name
> +to derive the name of the target ARM architecture (as if specified
> +by @option{-march}) and the ARM processor type for which to tune for
> +performance (as if specified by @option{-mtune}).  Where this option
> +is used in conjunction with @option{-march} or @option{-mtune}, those
> +options override this option.  Permissible names for this option
> +are the same as those for @option{-mtune}.
>  
> -@option{-march=armv8-a+crc} enables code generation for the ARMv8-A
> -architecture together with the optional CRC32 extensions.
> +@option{-mcpu=generic-@var{arch}} is also permissible, and is
> +equivalent to @option{-march=@var{arch} -mtune=generic-@var{arch}}.
> +See @option{-mtune} for more information.
>  
> -@option{-march=native} causes the compiler to auto-detect the architecture
> +@option{-mcpu=native} causes the compiler to auto-detect the CPU
>  of the build computer.  At present, this feature is only supported on
>  Linux, and not all architectures are recognized.  If the auto-detect is
>  unsuccessful the option has no effect.