[linux-block.git] / Documentation / arm64 / elf_hwcaps.txt

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_AA64ISAR0_EL1.AES == 0b0001.

HWCAP_PMULL

    Functionality implied by ID_AA64ISAR0_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.

HWCAP_DCPOP

    Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.

HWCAP_SHA3

    Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.

HWCAP_SM3

    Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.

HWCAP_SM4

    Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.

HWCAP_ASIMDDP

    Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.

HWCAP_SHA512

    Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.

HWCAP_SVE

    Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.

HWCAP_ASIMDFHM

   Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.

HWCAP_DIT

    Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.

HWCAP_USCAT

    Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.

HWCAP_ILRCPC

    Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.

HWCAP_FLAGM

    Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
Commit	Line	Data
611a7bc7 MR	1	ARM64 ELF hwcaps
	2	================
	3
	4	This document describes the usage and semantics of the arm64 ELF hwcaps.
	5
	6
	7	1. Introduction
	8	---------------
	9
	10	Some hardware or software features are only available on some CPU
	11	implementations, and/or with certain kernel configurations, but have no
	12	architected discovery mechanism available to userspace code at EL0. The
	13	kernel exposes the presence of these features to userspace through a set
	14	of flags called hwcaps, exposed in the auxilliary vector.
	15
	16	Userspace software can test for features by acquiring the AT_HWCAP entry
	17	of the auxilliary vector, and testing whether the relevant flags are
	18	set, e.g.
	19
	20	bool floating_point_is_present(void)
	21	{
	22	unsigned long hwcaps = getauxval(AT_HWCAP);
	23	if (hwcaps & HWCAP_FP)
	24	return true;
	25
	26	return false;
	27	}
	28
	29	Where software relies on a feature described by a hwcap, it should check
	30	the relevant hwcap flag to verify that the feature is present before
	31	attempting to make use of the feature.
	32
	33	Features cannot be probed reliably through other means. When a feature
	34	is not available, attempting to use it may result in unpredictable
	35	behaviour, and is not guaranteed to result in any reliable indication
	36	that the feature is unavailable, such as a SIGILL.
	37
	38
	39	2. Interpretation of hwcaps
	40	---------------------------
	41
	42	The majority of hwcaps are intended to indicate the presence of features
	43	which are described by architected ID registers inaccessible to
	44	userspace code at EL0. These hwcaps are defined in terms of ID register
	45	fields, and should be interpreted with reference to the definition of
	46	these fields in the ARM Architecture Reference Manual (ARM ARM).
	47
	48	Such hwcaps are described below in the form:
	49
	50	Functionality implied by idreg.field == val.
	51
	52	Such hwcaps indicate the availability of functionality that the ARM ARM
	53	defines as being present when idreg.field has value val, but do not
	54	indicate that idreg.field is precisely equal to val, nor do they
	55	indicate the absence of functionality implied by other values of
	56	idreg.field.
	57
	58	Other hwcaps may indicate the presence of features which cannot be
	59	described by ID registers alone. These may be described without
	60	reference to ID registers, and may refer to other documentation.
	61
	62
	63	3. The hwcaps exposed in AT_HWCAP
	64	---------------------------------
65
66	HWCAP_FP
67
68	Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000.
69
70	HWCAP_ASIMD
71
72	Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000.
73
74	HWCAP_EVTSTRM
75
76	The generic timer is configured to generate events at a frequency of
77	approximately 100KHz.
78
79	HWCAP_AES
80
4bfbe5ee	81	Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0001.
611a7bc7 MR	82
	83	HWCAP_PMULL
	84
4bfbe5ee	85	Functionality implied by ID_AA64ISAR0_EL1.AES == 0b0010.
611a7bc7 MR	86
	87	HWCAP_SHA1
	88
	89	Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001.
	90
	91	HWCAP_SHA2
	92
	93	Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001.
	94
	95	HWCAP_CRC32
	96
	97	Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001.
	98
	99	HWCAP_ATOMICS
	100
	101	Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010.
	102
	103	HWCAP_FPHP
	104
	105	Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001.
	106
	107	HWCAP_ASIMDHP
	108
	109	Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001.
	110
	111	HWCAP_CPUID
	112
	113	EL0 access to certain ID registers is available, to the extent
	114	described by Documentation/arm64/cpu-feature-registers.txt.
	115
	116	These ID registers may imply the availability of features.
	117
	118	HWCAP_ASIMDRDM
	119
	120	Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001.
	121
	122	HWCAP_JSCVT
	123
	124	Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001.
	125
	126	HWCAP_FCMA
	127
	128	Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001.
	129
	130	HWCAP_LRCPC
	131
	132	Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001.
	133
	134	HWCAP_DCPOP
	135
	136	Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001.
	137
	138	HWCAP_SHA3
	139
	140	Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
	141
	142	HWCAP_SM3
	143
	144	Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
	145
	146	HWCAP_SM4
	147
	148	Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
	149
150	HWCAP_ASIMDDP
151
152	Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
153
154	HWCAP_SHA512
155
4bfbe5ee	156	Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
43994d82 DM	157
	158	HWCAP_SVE
	159
	160	Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
3b3b6810 DG	161
	162	HWCAP_ASIMDFHM
	163
	164	Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
7206dc93 SP	165
	166	HWCAP_DIT
	167
	168	Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
	169
	170	HWCAP_USCAT
	171
	172	Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
	173
	174	HWCAP_ILRCPC
	175
4bfbe5ee	176	Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
7206dc93 SP	177
	178	HWCAP_FLAGM
	179
	180	Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.