[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 or
AT_HWCAP2 entry of the auxiliary 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.

HWCAP2_DCPODP

    Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.

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.

HWCAP2_SVE2

    Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.

HWCAP2_SVEAES

    Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.

HWCAP2_SVEPMULL

    Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.

HWCAP2_SVEBITPERM

    Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.

HWCAP2_SVESHA3

    Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.

HWCAP2_SVESM4

    Functionality implied by ID_AA64ZFR0_EL1.SM4 == 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.

HWCAP2_FLAGM2

    Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.

HWCAP_SSBS

    Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.

HWCAP_PACA

    Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
    ID_AA64ISAR1_EL1.API == 0b0001, as described by
    Documentation/arm64/pointer-authentication.txt.

HWCAP_PACG

    Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
    ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
    Documentation/arm64/pointer-authentication.txt.


4. Unused AT_HWCAP bits
-----------------------

For interoperation with userspace, the kernel guarantees that bits 62
and 63 of AT_HWCAP will always be returned as 0.
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
aaba098f AM	16	Userspace software can test for features by acquiring the AT_HWCAP or
	17	AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
	18	flags are set, e.g.
611a7bc7 MR	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
671db581 AM	138	HWCAP2_DCPODP
	139
	140	Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
	141
611a7bc7 MR	142	HWCAP_SHA3
	143
	144	Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001.
	145
	146	HWCAP_SM3
	147
	148	Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001.
	149
	150	HWCAP_SM4
	151
	152	Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001.
	153
	154	HWCAP_ASIMDDP
	155
	156	Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001.
	157
	158	HWCAP_SHA512
	159
4bfbe5ee	160	Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0010.
43994d82 DM	161
	162	HWCAP_SVE
	163
	164	Functionality implied by ID_AA64PFR0_EL1.SVE == 0b0001.
3b3b6810	165
06a916fe DM	166	HWCAP2_SVE2
	167
	168	Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
	169
	170	HWCAP2_SVEAES
	171
	172	Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
	173
	174	HWCAP2_SVEPMULL
	175
	176	Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
	177
	178	HWCAP2_SVEBITPERM
	179
	180	Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
	181
	182	HWCAP2_SVESHA3
	183
	184	Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
	185
	186	HWCAP2_SVESM4
	187
	188	Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
	189
3b3b6810 DG	190	HWCAP_ASIMDFHM
	191
	192	Functionality implied by ID_AA64ISAR0_EL1.FHM == 0b0001.
7206dc93 SP	193
	194	HWCAP_DIT
	195
	196	Functionality implied by ID_AA64PFR0_EL1.DIT == 0b0001.
	197
	198	HWCAP_USCAT
	199
	200	Functionality implied by ID_AA64MMFR2_EL1.AT == 0b0001.
	201
	202	HWCAP_ILRCPC
	203
4bfbe5ee	204	Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0010.
7206dc93 SP	205
	206	HWCAP_FLAGM
	207
	208	Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0001.
ee911761	209
12019374 MB	210	HWCAP2_FLAGM2
	211
	212	Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
	213
ee911761 WD	214	HWCAP_SSBS
	215
	216	Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010.
fbedc599 MR	217
	218	HWCAP_PACA
	219
	220	Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or
	221	ID_AA64ISAR1_EL1.API == 0b0001, as described by
	222	Documentation/arm64/pointer-authentication.txt.
	223
	224	HWCAP_PACG
	225
	226	Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or
	227	ID_AA64ISAR1_EL1.GPI == 0b0001, as described by
	228	Documentation/arm64/pointer-authentication.txt.
aaba098f AM	229
	230
	231	4. Unused AT_HWCAP bits
	232	-----------------------
	233
	234	For interoperation with userspace, the kernel guarantees that bits 62
	235	and 63 of AT_HWCAP will always be returned as 0.