1.. _elf_hwcaps_powerpc:
2
3==================
4POWERPC ELF HWCAPs
5==================
6
7This document describes the usage and semantics of the powerpc ELF HWCAPs.
8
9
101. Introduction
11---------------
12
13Some hardware or software features are only available on some CPU
14implementations, and/or with certain kernel configurations, but have no other
15discovery mechanism available to userspace code. The kernel exposes the
16presence of these features to userspace through a set of flags called HWCAPs,
17exposed in the auxiliary vector.
18
19Userspace software can test for features by acquiring the AT_HWCAP or
20AT_HWCAP2 entry of the auxiliary vector, and testing whether the relevant
21flags are set, e.g.::
22
23	bool floating_point_is_present(void)
24	{
25		unsigned long HWCAPs = getauxval(AT_HWCAP);
26		if (HWCAPs & PPC_FEATURE_HAS_FPU)
27			return true;
28
29		return false;
30	}
31
32Where software relies on a feature described by a HWCAP, it should check the
33relevant HWCAP flag to verify that the feature is present before attempting to
34make use of the feature.
35
36HWCAP is the preferred method to test for the presence of a feature rather
37than probing through other means, which may not be reliable or may cause
38unpredictable behaviour.
39
40Software that targets a particular platform does not necessarily have to
41test for required or implied features. For example if the program requires
42FPU, VMX, VSX, it is not necessary to test those HWCAPs, and it may be
43impossible to do so if the compiler generates code requiring those features.
44
452. Facilities
46-------------
47
48The Power ISA uses the term "facility" to describe a class of instructions,
49registers, interrupts, etc. The presence or absence of a facility indicates
50whether this class is available to be used, but the specifics depend on the
51ISA version. For example, if the VSX facility is available, the VSX
52instructions that can be used differ between the v3.0B and v3.1B ISA
53versions.
54
553. Categories
56-------------
57
58The Power ISA before v3.0 uses the term "category" to describe certain
59classes of instructions and operating modes which may be optional or
60mutually exclusive, the exact meaning of the HWCAP flag may depend on
61context, e.g., the presence of the BOOKE feature implies that the server
62category is not implemented.
63
644. HWCAP allocation
65-------------------
66
67HWCAPs are allocated as described in Power Architecture 64-Bit ELF V2 ABI
68Specification (which will be reflected in the kernel's uapi headers).
69
705. The HWCAPs exposed in AT_HWCAP
71---------------------------------
72
73PPC_FEATURE_32
74    32-bit CPU
75
76PPC_FEATURE_64
77    64-bit CPU (userspace may be running in 32-bit mode).
78
79PPC_FEATURE_601_INSTR
80    The processor is PowerPC 601.
81    Unused in the kernel since f0ed73f3fa2c ("powerpc: Remove PowerPC 601")
82
83PPC_FEATURE_HAS_ALTIVEC
84    Vector (aka Altivec, VMX) facility is available.
85
86PPC_FEATURE_HAS_FPU
87    Floating point facility is available.
88
89PPC_FEATURE_HAS_MMU
90    Memory management unit is present and enabled.
91
92PPC_FEATURE_HAS_4xxMAC
93    The processor is 40x or 44x family.
94
95PPC_FEATURE_UNIFIED_CACHE
96    The processor has a unified L1 cache for instructions and data, as
97    found in NXP e200.
98    Unused in the kernel since 39c8bf2b3cc1 ("powerpc: Retire e200 core (mpc555x processor)")
99
100PPC_FEATURE_HAS_SPE
101    Signal Processing Engine facility is available.
102
103PPC_FEATURE_HAS_EFP_SINGLE
104    Embedded Floating Point single precision operations are available.
105
106PPC_FEATURE_HAS_EFP_DOUBLE
107    Embedded Floating Point double precision operations are available.
108
109PPC_FEATURE_NO_TB
110    The timebase facility (mftb instruction) is not available.
111    This is a 601 specific HWCAP, so if it is known that the processor
112    running is not a 601, via other HWCAPs or other means, it is not
113    required to test this bit before using the timebase.
114    Unused in the kernel since f0ed73f3fa2c ("powerpc: Remove PowerPC 601")
115
116PPC_FEATURE_POWER4
117    The processor is POWER4 or PPC970/FX/MP.
118    POWER4 support dropped from the kernel since 471d7ff8b51b ("powerpc/64s: Remove POWER4 support")
119
120PPC_FEATURE_POWER5
121    The processor is POWER5.
122
123PPC_FEATURE_POWER5_PLUS
124    The processor is POWER5+.
125
126PPC_FEATURE_CELL
127    The processor is Cell.
128
129PPC_FEATURE_BOOKE
130    The processor implements the embedded category ("BookE") architecture.
131
132PPC_FEATURE_SMT
133    The processor implements SMT.
134
135PPC_FEATURE_ICACHE_SNOOP
136    The processor icache is coherent with the dcache, and instruction storage
137    can be made consistent with data storage for the purpose of executing
138    instructions with the sequence (as described in, e.g., POWER9 Processor
139    User's Manual, 4.6.2.2 Instruction Cache Block Invalidate (icbi))::
140
141        sync
142        icbi (to any address)
143        isync
144
145PPC_FEATURE_ARCH_2_05
146    The processor supports the v2.05 userlevel architecture. Processors
147    supporting later architectures DO NOT set this feature.
148
149PPC_FEATURE_PA6T
150    The processor is PA6T.
151
152PPC_FEATURE_HAS_DFP
153    DFP facility is available.
154
155PPC_FEATURE_POWER6_EXT
156    The processor is POWER6.
157
158PPC_FEATURE_ARCH_2_06
159    The processor supports the v2.06 userlevel architecture. Processors
160    supporting later architectures also set this feature.
161
162PPC_FEATURE_HAS_VSX
163    VSX facility is available.
164
165PPC_FEATURE_PSERIES_PERFMON_COMPAT
166    The processor supports architected PMU events in the range 0xE0-0xFF.
167
168PPC_FEATURE_TRUE_LE
169    The processor supports true little-endian mode.
170
171PPC_FEATURE_PPC_LE
172    The processor supports "PowerPC Little-Endian", that uses address
173    munging to make storage access appear to be little-endian, but the
174    data is stored in a different format that is unsuitable to be
175    accessed by other agents not running in this mode.
176
1776. The HWCAPs exposed in AT_HWCAP2
178----------------------------------
179
180PPC_FEATURE2_ARCH_2_07
181    The processor supports the v2.07 userlevel architecture. Processors
182    supporting later architectures also set this feature.
183
184PPC_FEATURE2_HTM
185    Transactional Memory feature is available.
186
187PPC_FEATURE2_DSCR
188    DSCR facility is available.
189
190PPC_FEATURE2_EBB
191    EBB facility is available.
192
193PPC_FEATURE2_ISEL
194    isel instruction is available. This is superseded by ARCH_2_07 and
195    later.
196
197PPC_FEATURE2_TAR
198    TAR facility is available.
199
200PPC_FEATURE2_VEC_CRYPTO
201    v2.07 crypto instructions are available.
202
203PPC_FEATURE2_HTM_NOSC
204    System calls fail if called in a transactional state, see
205    Documentation/powerpc/syscall64-abi.rst
206
207PPC_FEATURE2_ARCH_3_00
208    The processor supports the v3.0B / v3.0C userlevel architecture. Processors
209    supporting later architectures also set this feature.
210
211PPC_FEATURE2_HAS_IEEE128
212    IEEE 128-bit binary floating point is supported with VSX
213    quad-precision instructions and data types.
214
215PPC_FEATURE2_DARN
216    darn instruction is available.
217
218PPC_FEATURE2_SCV
219    The scv 0 instruction may be used for system calls, see
220    Documentation/powerpc/syscall64-abi.rst.
221
222PPC_FEATURE2_HTM_NO_SUSPEND
223    A limited Transactional Memory facility that does not support suspend is
224    available, see Documentation/powerpc/transactional_memory.rst.
225
226PPC_FEATURE2_ARCH_3_1
227    The processor supports the v3.1 userlevel architecture. Processors
228    supporting later architectures also set this feature.
229
230PPC_FEATURE2_MMA
231    MMA facility is available.
232