[PATCH Linux] powerpc: add documentation for HWCAPs

[Nicholas Piggin]

Finally got some details about the icache snoop question so just coming 
back to this now, sorry for the delay... (POWER10 does support the 
coherent icache flush sequence as expected, there was some updates to
the UM wording but that will be fixed).

Excerpts from Segher Boessenkool's message of May 25, 2022 3:38 am:
> Hi!
> 
> On Tue, May 24, 2022 at 07:38:28PM +1000, Nicholas Piggin wrote:
>> Thanks for all the comments and corrections. It should be nearing the
>> point where it is useful now. Yes I do think it would be useful to align
>> this more with OpenPOWER docs (and possibly eventually move it into the
>> ABI, given that's the allocator of these numbers) but that's not
>> done yet.
> 
> The auxiliary vector is a Linux/glibc thing, it should not be described
> in more generic ABI documents.  It is fine where you have it now afaics.

It is already in the ABI document. In fact that (not the kernel) had
been the allocator of the feature numbers, at least in the past I think.

> 
>> +Where software relies on a feature described by a HWCAP, it should check the
>> +relevant HWCAP flag to verify that the feature is present before attempting to
>> +make use of the feature.
>> +
>> +Features should not be probed through other means. When a feature is not
>> +available, attempting to use it may result in unpredictable behaviour, and
>> +may not be guaranteed to result in any reliable indication that the feature
>> +is unavailable.
> 

> Traditionally VMX was tested for by simply executing an instruction and
> catching SIGILL.  This is portable even.  This has worked fine for over
> two decades, it's a bit weird to declare this a forbidden practice
> now :-)

The statement does not override architectural specification, so
if an encoding does not exist then it should cause a trap and SIGILL.
I suppose in theory we could work around performance or correctness
issues in an implementation by clearing HWCAP even if the hardware does 
execute the instruction, so I would still say testing HWCAP is
preferred.

> 
> It certainly isn't recommended for more complex and/or newer things.
> 
>> +verstions.
> 
> (typo.  spellcheck maybe?)

Thanks,
Nick