[01/11] arm64: docs: describe ELF hwcaps

Commit Message

Mark Rutland July 19, 2017, 4:01 p.m. UTC

We don't document our ELF hwcaps, leaving developers to interpret them
according to hearsay, guesswork, or (in exceptional cases) inspection of
the current kernel code.

This is less than optimal, and it would be far better if we had some
definitive description of each of the ELF hwcaps that developers could
refer to.

This patch adds a document describing the (native) arm64 ELF hwcaps.

Signed-off-by: Mark Rutland <[e-mail]>
Cc: Catalin Marinas <[e-mail]>
Cc: Dave Martin <[e-mail]>
Cc: Suzuki K Poulose <[e-mail]>
Cc: Will Deacon <[e-mail]>
---
 Documentation/arm64/elf_hwcaps.txt | 133 +++++++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 Documentation/arm64/elf_hwcaps.txt

Comments

Dave Martin July 21, 2017, 5:05 p.m. UTC | #1

On Wed, Jul 19, 2017 at 05:01:22PM +0100, Mark Rutland wrote:
> We don't document our ELF hwcaps, leaving developers to interpret them
> according to hearsay, guesswork, or (in exceptional cases) inspection of
> the current kernel code.
> 
> This is less than optimal, and it would be far better if we had some
> definitive description of each of the ELF hwcaps that developers could
> refer to.
> 
> This patch adds a document describing the (native) arm64 ELF hwcaps.

Minor nit: what do the hwcaps have to do with ELF really?  Can we just
call them "hwcaps"?

I'm not sure of the history here.

> Signed-off-by: Mark Rutland <[e-mail]>
> Cc: Catalin Marinas <[e-mail]>
> Cc: Dave Martin <[e-mail]>
> Cc: Suzuki K Poulose <[e-mail]>
> Cc: Will Deacon <[e-mail]>
> ---
>  Documentation/arm64/elf_hwcaps.txt | 133 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 133 insertions(+)
>  create mode 100644 Documentation/arm64/elf_hwcaps.txt
> 
> diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt
> new file mode 100644
> index 0000000..7bc2921
> --- /dev/null
> +++ b/Documentation/arm64/elf_hwcaps.txt
> @@ -0,0 +1,133 @@
> +ARM64 ELF hwcaps
> +================
> +
> +This document describes the usage and semantics of the arm64 ELF hwcaps.
> +
> +
> +1. Introduction
> +---------------
> +
> +Some hardware or software features are only available on some CPU
> +implementations, and/or with certain kernel configurations, but have no
> +architected discovery mechanism available to userspace code at EL0. The
> +kernel exposes the presence of these features to userspace through a set
> +of flags called hwcaps, exposed in the auxilliary vector.
> +
> +Userspace software can test for features by acquiring the AT_HWCAP entry
> +of the auxilliary vector, and testing whether the relevant flags are
> +set, e.g.
> +
> +bool floating_point_is_present(void)
> +{
> +	unsigned long hwcaps = getauxval(AT_HWCAP);
> +	if (hwcaps & HWCAP_FP)
> +		return true;
> +
> +	return false;
> +}
> +
> +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 cannot be probed reliably through other means. When a feature
> +is not available, attempting to use it may result in unpredictable

This says that features cannot be probed reliably via the (emulated) ID
registers available with HWCAP_CPUID.

So, what use is the ID register emulation?

For each of hwcaps and cpuid, a particular feature may be reported as
present (y), absent (n), or not described at all (x):

hwcap>    x n y
cpuid:
   x      N N Y
   n      N N
   y      Y   Y

I've filled in the straightforward cases, where software may (Y) or must
not (N) use the feature.

In the cases left blank, hwcap and cpuid disagree.

Are we confident that should never be observed -- i.e., it's a kernel
bug if seen?  If so, we can fill Ys in there.  But we need to be clear
about cases where the hwcap doesn't mean exactly the same as the
corresponding CPUID feature.  The hwcap may tell software it can assume
that certain kernel ABI extensions related to that CPU feature are
available for example.

This also affects how HWCAP_CPUID is described below.

[...]

Cheers
---Dave

Suzuki K Poulose July 24, 2017, 10:47 a.m. UTC | #2

On 21/07/17 18:05, Dave Martin wrote:
> On Wed, Jul 19, 2017 at 05:01:22PM +0100, Mark Rutland wrote:
>> We don't document our ELF hwcaps, leaving developers to interpret them
>> according to hearsay, guesswork, or (in exceptional cases) inspection of
>> the current kernel code.
>>
>> This is less than optimal, and it would be far better if we had some
>> definitive description of each of the ELF hwcaps that developers could
>> refer to.
>>
>> This patch adds a document describing the (native) arm64 ELF hwcaps.
>
> Minor nit: what do the hwcaps have to do with ELF really?  Can we just
> call them "hwcaps"?
>
> I'm not sure of the history here.

Dave,

This is something that I requested to avoid confusing it with the CPU hwcaps,
(stored in the variable named hwcaps), we maintain in the kernel for capabilities.
Though, what we describe in this document is not specific to ELF format as
you have mentioned, it is easy to get confused with the former.

>
>> Signed-off-by: Mark Rutland <[e-mail]>
>> Cc: Catalin Marinas <[e-mail]>
>> Cc: Dave Martin <[e-mail]>
>> Cc: Suzuki K Poulose <[e-mail]>
>> Cc: Will Deacon <[e-mail]>
>> ---
>>  Documentation/arm64/elf_hwcaps.txt | 133 +++++++++++++++++++++++++++++++++++++
>>  1 file changed, 133 insertions(+)
>>  create mode 100644 Documentation/arm64/elf_hwcaps.txt
>>
>> diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt
>> new file mode 100644
>> index 0000000..7bc2921
>> --- /dev/null
>> +++ b/Documentation/arm64/elf_hwcaps.txt
>> @@ -0,0 +1,133 @@
>> +ARM64 ELF hwcaps
>> +================
>> +
>> +This document describes the usage and semantics of the arm64 ELF hwcaps.
>> +
>> +
>> +1. Introduction
>> +---------------
>> +
>> +Some hardware or software features are only available on some CPU
>> +implementations, and/or with certain kernel configurations, but have no
>> +architected discovery mechanism available to userspace code at EL0. The
>> +kernel exposes the presence of these features to userspace through a set
>> +of flags called hwcaps, exposed in the auxilliary vector.
>> +
>> +Userspace software can test for features by acquiring the AT_HWCAP entry
>> +of the auxilliary vector, and testing whether the relevant flags are
>> +set, e.g.
>> +
>> +bool floating_point_is_present(void)
>> +{
>> +	unsigned long hwcaps = getauxval(AT_HWCAP);
>> +	if (hwcaps & HWCAP_FP)
>> +		return true;
>> +
>> +	return false;
>> +}
>> +
>> +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 cannot be probed reliably through other means. When a feature
>> +is not available, attempting to use it may result in unpredictable
>
> This says that features cannot be probed reliably via the (emulated) ID
> registers available with HWCAP_CPUID.
>
> So, what use is the ID register emulation?
>
> For each of hwcaps and cpuid, a particular feature may be reported as
> present (y), absent (n), or not described at all (x):
>
> hwcap>    x n y
> cpuid:
>    x      N N Y
>    n      N N
>    y      Y   Y
>
> I've filled in the straightforward cases, where software may (Y) or must
> not (N) use the feature.
>
> In the cases left blank, hwcap and cpuid disagree.
>
> Are we confident that should never be observed -- i.e., it's a kernel
> bug if seen?  If so, we can fill Ys in there.  But we need to be clear

CPUID=> n and HWCAP=> Y is Kernel bug, indeed, as both HWCAP and CPUID uses the
same underlying data for the decision. However, the other case is a bit complicated,
depending on whether we decide to continue adding (we do add at the moment) "new HWCAP"
bits for the newer features.
If we do add the new HWCAPs, that could possible create conflicts on older kernels
which doesn't know about the feature, while the CPUID could expose the feature.
If we don't add the HWCAP, there is no reliable way for the userspace to decide if
the kernel supports the feature or not.

So, in either case, we need to cap the value exposed by CPUID to the "kernel supported
feature level" to avoid problems like this.

Thoughts ?

Suzuki



> about cases where the hwcap doesn't mean exactly the same as the
> corresponding CPUID feature.  The hwcap may tell software it can assume
> that certain kernel ABI extensions related to that CPU feature are
> available for example.
>
> This also affects how HWCAP_CPUID is described below.
>
> [...]
>
> Cheers
> ---Dave
>

Catalin Marinas Aug. 3, 2017, 2:49 p.m. UTC | #3

On Wed, Jul 19, 2017 at 05:01:22PM +0100, Mark Rutland wrote:
> +3. The hwcaps exposed in AT_HWCAP
> +---------------------------------
> +
> +HWCAP_FP
> +
> +    Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.

Aren't these too restrictive? Linux would still present HWCAP_FP even
when ID_AA64PFR0_EL1.FP == 1. I think we should replace the strict
equal with greater than or equal, also mentioning that the field is
signed (or refer to the cpuid where the sign of the fields is
described).

Kees Cook Aug. 3, 2017, 5:57 p.m. UTC | #4

On Wed, Jul 19, 2017 at 9:01 AM, Mark Rutland <[e-mail]> wrote:
> We don't document our ELF hwcaps, leaving developers to interpret them
> according to hearsay, guesswork, or (in exceptional cases) inspection of
> the current kernel code.
>
> This is less than optimal, and it would be far better if we had some
> definitive description of each of the ELF hwcaps that developers could
> refer to.
>
> This patch adds a document describing the (native) arm64 ELF hwcaps.
>
> Signed-off-by: Mark Rutland <[e-mail]>
> Cc: Catalin Marinas <[e-mail]>
> Cc: Dave Martin <[e-mail]>
> Cc: Suzuki K Poulose <[e-mail]>
> Cc: Will Deacon <[e-mail]>
> ---
>  Documentation/arm64/elf_hwcaps.txt | 133 +++++++++++++++++++++++++++++++++++++

With the kernel docs moving to ReST markup[1], perhaps reformat this
to a .rst file and link to it from somewhere sensible in the ReST
tree, perhaps the userspace API section in
Documentation/userspace-api/index.rst?

-Kees

[1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html

Patch

diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt
new file mode 100644
index 0000000..7bc2921
--- /dev/null
+++ b/Documentation/arm64/elf_hwcaps.txt
@@ -0,0 +1,133 @@ 
+ARM64 ELF hwcaps
+================
+
+This document describes the usage and semantics of the arm64 ELF hwcaps.
+
+
+1. Introduction
+---------------
+
+Some hardware or software features are only available on some CPU
+implementations, and/or with certain kernel configurations, but have no
+architected discovery mechanism available to userspace code at EL0. The
+kernel exposes the presence of these features to userspace through a set
+of flags called hwcaps, exposed in the auxilliary vector.
+
+Userspace software can test for features by acquiring the AT_HWCAP entry
+of the auxilliary vector, and testing whether the relevant flags are
+set, e.g.
+
+bool floating_point_is_present(void)
+{
+	unsigned long hwcaps = getauxval(AT_HWCAP);
+	if (hwcaps & HWCAP_FP)
+		return true;
+
+	return false;
+}
+
+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 cannot be probed reliably through other means. When a feature
+is not available, attempting to use it may result in unpredictable
+behaviour, and is not guaranteed to result in any reliable indication
+that the feature is unavailable, such as a SIGILL.
+
+
+2. Interpretation of hwcaps
+---------------------------
+
+The majority of hwcaps are intended to indicate the presence of features
+which are described by architected ID registers inaccessible to
+userspace code at EL0. These hwcaps are defined in terms of ID register
+fields, and should be interpreted with reference to the definition of
+these fields in the ARM Architecture Reference Manual (ARM ARM).
+
+Such hwcaps are described below in the form:
+
+    Functionality implied by idreg.field == val.
+
+Such hwcaps indicate the availability of functionality that the ARM ARM
+defines as being present when idreg.field has value val, but do not
+indicate that idreg.field is precisely equal to val, nor do they
+indicate the absence of functionality implied by other values of
+idreg.field.
+
+Other hwcaps may indicate the presence of features which cannot be
+described by ID registers alone. These may be described without
+reference to ID registers, and may refer to other documentation.
+
+
+3. The hwcaps exposed in AT_HWCAP
+---------------------------------
+
+HWCAP_FP
+
+    Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
+
+HWCAP_ASIMD
+
+    Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
+
+HWCAP_EVTSTRM
+
+    The generic timer is configured to generate events at a frequency of
+    approximately 100KHz.
+
+HWCAP_AES
+
+    Functionality implied by ID_AA64ISAR1_EL1.AES == 0b0001.
+
+HWCAP_PMULL
+
+    Functionality implied by ID_AA64ISAR1_EL1.AES == 0b0010.
+
+HWCAP_SHA1
+
+    Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
+
+HWCAP_SHA2
+
+    Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
+
+HWCAP_CRC32
+
+    Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
+
+HWCAP_ATOMICS
+
+    Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
+
+HWCAP_FPHP
+
+    Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
+
+HWCAP_ASIMDHP
+
+    Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
+
+HWCAP_CPUID
+
+    EL0 access to certain ID registers is available, to the extent
+    described by Documentation/arm64/cpu-feature-registers.txt.
+
+    These ID registers may imply the availability of features.
+
+HWCAP_ASIMDRDM
+
+    Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
+
+HWCAP_JSCVT
+
+    Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
+
+HWCAP_FCMA
+
+    Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
+
+HWCAP_LRCPC
+
+    Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
+