[RFC Linux patch] powerpc: add documentation for HWCAPs

[Nicholas Piggin]

Excerpts from Paul E Murphy's message of May 21, 2022 12:21 am:
> 
> 
> On 5/20/22 12:15 AM, Nicholas Piggin via Gcc wrote:
>> This takes the arm64 file and adjusts it for powerpc. Feature
>> descriptions are vaguely handwaved by me.
>> ---
>> 
>> Anybody care to expand on or correct the meaning of these entries or
>> bikeshed the wording of the intro? Many of them are no longer used
>> anywhere by upstream kernels and even where they are it's not always
>> quite clear what the exact intent was, a lot of them are old history
>> and I don't know what or where they are used.
>> 
>> I may try to get these descriptions pushed into the ABI doc after a
>> time, but for now they can live in the kernel tree.
>> 
>> Thanks,
>> Nick
> 
> Thanks, this is really helpful.  I've been caught off-guard by some of 
> the subtleties in the meanings of these bits at times.  I think it would 
> be helpful to share what is implied by the usage of the word "facility" 
> below.  It would resolve some of my questions below.

Yeah that's probably a good point. In the introduction we can explain
that the facility is a class of instructions, registers, and behaviour,
but that the specifics depend on the ISA version.

> 
> 
> 
>> +PPC_FEATURE_HAS_ALTIVEC
>> +    Vector (aka Altivec, VSX) facility is available.
> 
> I think "(aka Altivec, VSX)" might be more accurately stated as "(aka 
> Altivec)"?

Yes VSX is a thinkso, should be VMX as pointed out.

>> +PPC_FEATURE_HAS_DFP
>> +    DFP facility is available.
> 
> Maybe something like "Decimal floating point instructions are available 
> to userspace.  Individual instruction availability is dependent on the
> reported architecture version."?

Yep, we can cover all these with a note in the intro.

>> +PPC_FEATURE_HAS_VSX
>> +    VSX facility is available.
> A small reminder the features are also dependent on architecture version 
> too might be helpful here too.
> 
> 
>> +PPC_FEATURE2_TAR
>> +    VSX facility is available.
> 
> Was manipulating the tar spr was once a privileged instruction, is this 
> a hint userspace can use the related instructions?

It can be disabled with facility control, and I guess there was
some consideration for how it might be used, e.g., "system software"
could use it for its own purpose then clear the bit for the application.

In practice I don't really know what makes use of this or whether
anything sanely can, it's marked reserved in the ABI. Would be 
interesting to know whether there is much benefit to use it in the
compiler. The kernel could actually use it for something nifty if we
were able to prevent userspace from accessing it entirely...

>> +
>> +PPC_FEATURE2_HAS_IEEE128
>> +    IEEE 128 is available? What instructions/data?
> 
> Maybe something like "IEEE 128 binary floating point instructions are 
> supported.  Individual instruction availability is dependent on the
> reported architecture version."?

Right, I just didn't know what architectural class of instructions
those are. Is it just VSX in general or are there some specific
things we can name?

>> +PPC_FEATURE2_SCV
>> +    scv instruction is available.
> 
> I think it might be clearer to say "This kernel supports syscalls using 
> the scv instruction".

Yeah good point.

>> +PPC_FEATURE2_MMA
>> +    MMA facility is available.
> 
> Maybe another note that specific instruction availability may depend on 
> the reported architecture version?

Thanks,
Nick