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

Hi all,

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.

Ok for trunk and GCC 8?

Thanks,
Kyrill

2018-12-13  Kyrylo Tkachov  <kyrylo.tkachov@arm.com>

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

Thanks for doing this.

"Kyrill Tkachov" <kyrylo.tkachov@foss.arm.com> writes:
> @@ -15716,16 +15716,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.

Think we should have a comma before "which" in the last sentence.
OK with that change.

Richard

On Thu, Dec 13, 2018 at 10:15 AM Richard Sandiford
<richard.sandiford@arm.com> wrote:
>
> Thanks for doing this.
>
> "Kyrill Tkachov" <kyrylo.tkachov@foss.arm.com> writes:
> > @@ -15716,16 +15716,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.
>
> Think we should have a comma before "which" in the last sentence.
> OK with that change.

And backport to GCC-8 ?

ramana

>
> Richard

Ramana Radhakrishnan <ramana.gcc@googlemail.com> writes:
> On Thu, Dec 13, 2018 at 10:15 AM Richard Sandiford
> <richard.sandiford@arm.com> wrote:
>>
>> Thanks for doing this.
>>
>> "Kyrill Tkachov" <kyrylo.tkachov@foss.arm.com> writes:
>> > @@ -15716,16 +15716,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.
>>
>> Think we should have a comma before "which" in the last sentence.
>> OK with that change.
>
> And backport to GCC-8 ?

Yeah, OK for the backport too.