[linux-2.6-block.git] / Documentation / arm64 / elf_hwcaps.rst

================
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.rst.

    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.rst.

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

HWCAP2_FRINT

    Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.


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