[AArch64][doc] Clarify -msve-vector-bits=128 behaviour

We've received reports about the -msve-vector-bits=128 bits being somewhat ambiguous.
It isn't clear whether -msve-vector-bits=128 forces vector-length-agnostic code or whether
-msve-vector-bits=scalable forces 128-bit vector-lengh-specific code.
The latter is a, perhaps unintuitive, reading that we want to exclude.

This patch makes it more explicit that -msve-vector-bits=128 is special and produces
vector-length *agnostic* code. In the end, I've rewritten the whole option documentation.

Checked make pdf that the output looks reasonable.

    * doc/invoke.texi (-msve-vector-bits): Clarify -msve-vector-bits=128
    behavior.

From-SVN: r267081

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 0e1cd58fcf9b0b66d700e28eaae31232752fb636..ba32d6d53c17e854a3bd0ee17f8789ed293c27d5 100644 (file)
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+2018-12-13  Kyrylo Tkachov  <kyrylo.tkachov@arm.com>
+
+       * doc/invoke.texi (-msve-vector-bits): Clarify -msve-vector-bits=128
+       behavior.
+
 2018-12-13  Wei Xiao  <wei3.xiao@intel.com>
 
        * common/config/i386/i386-common.c (processor_names): Add cascadelake.

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 1bdeac3c45a2d02657b86582b08bfa046abd0a43..44e1069de3b4c6904e9f494745cf8aaa0d29cd27 100644 (file)
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -15675,16 +15675,19 @@ an effect when SVE is enabled.
 
 GCC supports two forms of SVE code generation: ``vector-length
 agnostic'' output that works with any size of vector register and
-``vector-length specific'' output that only works when the vector
-registers are a particular size.  Replacing @var{bits} with
-@samp{scalable} selects vector-length agnostic output while
-replacing it with a number selects vector-length specific output.
-The possible lengths in the latter case are: 128, 256, 512, 1024
-and 2048.  @samp{scalable} is the default.
-
-At present, @samp{-msve-vector-bits=128} produces the same output
-as @samp{-msve-vector-bits=scalable}.
-
+``vector-length specific'' output that allows GCC to make assumptions
+about the vector length when it is useful for optimization reasons.
+The possible values of @samp{bits} are: @samp{scalable}, @samp{128},
+@samp{256}, @samp{512}, @samp{1024} and @samp{2048}.
+Specifying @samp{scalable} selects vector-length agnostic
+output.  At present @samp{-msve-vector-bits=128} also generates vector-length
+agnostic output.  All other values generate vector-length specific code.
+The behavior of these values may change in future releases and no value except
+@samp{scalable} should be relied on for producing code that is portable across
+different hardware SVE vector lengths.
+
+The default is @samp{-msve-vector-bits=scalable}, which produces
+vector-length agnostic code.
 @end table
 
 @subsubsection @option{-march} and @option{-mcpu} Feature Modifiers