1 .. SPDX-License-Identifier: GPL-2.0
2
3 RISC-V Hardware Probing Interface
4 ---------------------------------
5
6 The RISC-V hardware probing interface is based around a single syscall, which
7 is defined in <asm/hwprobe.h>::
8
9 struct riscv_hwprobe {
10 __s64 key;
11 __u64 value;
12 };
13
14 long sys_riscv_hwprobe(struct riscv_hwprobe *pairs, size_t pair_count,
15 size_t cpusetsize, cpu_set_t *cpus,
16 unsigned int flags);
17
18 The arguments are split into three groups: an array of key-value pairs, a CPU
19 set, and some flags. The key-value pairs are supplied with a count. Userspace
20 must prepopulate the key field for each element, and the kernel will fill in the
21 value if the key is recognized. If a key is unknown to the kernel, its key field
22 will be cleared to -1, and its value set to 0. The CPU set is defined by
23 CPU_SET(3) with size ``cpusetsize`` bytes. For value-like keys (eg. vendor,
24 arch, impl), the returned value will only be valid if all CPUs in the given set
25 have the same value. Otherwise -1 will be returned. For boolean-like keys, the
26 value returned will be a logical AND of the values for the specified CPUs.
27 Usermode can supply NULL for ``cpus`` and 0 for ``cpusetsize`` as a shortcut for
28 all online CPUs. The currently supported flags are:
29
30 * :c:macro:`RISCV_HWPROBE_WHICH_CPUS`: This flag basically reverses the behavior
31 of sys_riscv_hwprobe(). Instead of populating the values of keys for a given
32 set of CPUs, the values of each key are given and the set of CPUs is reduced
33 by sys_riscv_hwprobe() to only those which match each of the key-value pairs.
34 How matching is done depends on the key type. For value-like keys, matching
35 means to be the exact same as the value. For boolean-like keys, matching
36 means the result of a logical AND of the pair's value with the CPU's value is
37 exactly the same as the pair's value. Additionally, when ``cpus`` is an empty
38 set, then it is initialized to all online CPUs which fit within it, i.e. the
39 CPU set returned is the reduction of all the online CPUs which can be
40 represented with a CPU set of size ``cpusetsize``.
41
42 All other flags are reserved for future compatibility and must be zero.
43
44 On success 0 is returned, on failure a negative error code is returned.
45
46 The following keys are defined:
47
48 * :c:macro:`RISCV_HWPROBE_KEY_MVENDORID`: Contains the value of ``mvendorid``,
49 as defined by the RISC-V privileged architecture specification.
50
51 * :c:macro:`RISCV_HWPROBE_KEY_MARCHID`: Contains the value of ``marchid``, as
52 defined by the RISC-V privileged architecture specification.
53
54 * :c:macro:`RISCV_HWPROBE_KEY_MIMPLID`: Contains the value of ``mimplid``, as
55 defined by the RISC-V privileged architecture specification.
56
57 * :c:macro:`RISCV_HWPROBE_KEY_BASE_BEHAVIOR`: A bitmask containing the base
58 user-visible behavior that this kernel supports. The following base user ABIs
59 are defined:
60
61 * :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`: Support for rv32ima or
62 rv64ima, as defined by version 2.2 of the user ISA and version 1.10 of the
63 privileged ISA, with the following known exceptions (more exceptions may be
64 added, but only if it can be demonstrated that the user ABI is not broken):
65
66 * The ``fence.i`` instruction cannot be directly executed by userspace
67 programs (it may still be executed in userspace via a
68 kernel-controlled mechanism such as the vDSO).
69
70 * :c:macro:`RISCV_HWPROBE_KEY_IMA_EXT_0`: A bitmask containing the extensions
71 that are compatible with the :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`:
72 base system behavior.
73
74 * :c:macro:`RISCV_HWPROBE_IMA_FD`: The F and D extensions are supported, as
75 defined by commit cd20cee ("FMIN/FMAX now implement
76 minimumNumber/maximumNumber, not minNum/maxNum") of the RISC-V ISA manual.
77
78 * :c:macro:`RISCV_HWPROBE_IMA_C`: The C extension is supported, as defined
79 by version 2.2 of the RISC-V ISA manual.
80
81 * :c:macro:`RISCV_HWPROBE_IMA_V`: The V extension is supported, as defined by
82 version 1.0 of the RISC-V Vector extension manual.
83
84 * :c:macro:`RISCV_HWPROBE_EXT_ZBA`: The Zba address generation extension is
85 supported, as defined in version 1.0 of the Bit-Manipulation ISA
86 extensions.
87
88 * :c:macro:`RISCV_HWPROBE_EXT_ZBB`: The Zbb extension is supported, as defined
89 in version 1.0 of the Bit-Manipulation ISA extensions.
90
91 * :c:macro:`RISCV_HWPROBE_EXT_ZBS`: The Zbs extension is supported, as defined
92 in version 1.0 of the Bit-Manipulation ISA extensions.
93
94 * :c:macro:`RISCV_HWPROBE_EXT_ZICBOZ`: The Zicboz extension is supported, as
95 ratified in commit 3dd606f ("Create cmobase-v1.0.pdf") of riscv-CMOs.
96
97 * :c:macro:`RISCV_HWPROBE_EXT_ZBC` The Zbc extension is supported, as defined
98 in version 1.0 of the Bit-Manipulation ISA extensions.
99
100 * :c:macro:`RISCV_HWPROBE_EXT_ZBKB` The Zbkb extension is supported, as
101 defined in version 1.0 of the Scalar Crypto ISA extensions.
102
103 * :c:macro:`RISCV_HWPROBE_EXT_ZBKC` The Zbkc extension is supported, as
104 defined in version 1.0 of the Scalar Crypto ISA extensions.
105
106 * :c:macro:`RISCV_HWPROBE_EXT_ZBKX` The Zbkx extension is supported, as
107 defined in version 1.0 of the Scalar Crypto ISA extensions.
108
109 * :c:macro:`RISCV_HWPROBE_EXT_ZKND` The Zknd extension is supported, as
110 defined in version 1.0 of the Scalar Crypto ISA extensions.
111
112 * :c:macro:`RISCV_HWPROBE_EXT_ZKNE` The Zkne extension is supported, as
113 defined in version 1.0 of the Scalar Crypto ISA extensions.
114
115 * :c:macro:`RISCV_HWPROBE_EXT_ZKNH` The Zknh extension is supported, as
116 defined in version 1.0 of the Scalar Crypto ISA extensions.
117
118 * :c:macro:`RISCV_HWPROBE_EXT_ZKSED` The Zksed extension is supported, as
119 defined in version 1.0 of the Scalar Crypto ISA extensions.
120
121 * :c:macro:`RISCV_HWPROBE_EXT_ZKSH` The Zksh extension is supported, as
122 defined in version 1.0 of the Scalar Crypto ISA extensions.
123
124 * :c:macro:`RISCV_HWPROBE_EXT_ZKT` The Zkt extension is supported, as defined
125 in version 1.0 of the Scalar Crypto ISA extensions.
126
127 * :c:macro:`RISCV_HWPROBE_EXT_ZVBB`: The Zvbb extension is supported as
128 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
129
130 * :c:macro:`RISCV_HWPROBE_EXT_ZVBC`: The Zvbc extension is supported as
131 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
132
133 * :c:macro:`RISCV_HWPROBE_EXT_ZVKB`: The Zvkb extension is supported as
134 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
135
136 * :c:macro:`RISCV_HWPROBE_EXT_ZVKG`: The Zvkg extension is supported as
137 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
138
139 * :c:macro:`RISCV_HWPROBE_EXT_ZVKNED`: The Zvkned extension is supported as
140 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
141
142 * :c:macro:`RISCV_HWPROBE_EXT_ZVKNHA`: The Zvknha extension is supported as
143 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
144
145 * :c:macro:`RISCV_HWPROBE_EXT_ZVKNHB`: The Zvknhb extension is supported as
146 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
147
148 * :c:macro:`RISCV_HWPROBE_EXT_ZVKSED`: The Zvksed extension is supported as
149 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
150
151 * :c:macro:`RISCV_HWPROBE_EXT_ZVKSH`: The Zvksh extension is supported as
152 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
153
154 * :c:macro:`RISCV_HWPROBE_EXT_ZVKT`: The Zvkt extension is supported as
155 defined in version 1.0 of the RISC-V Cryptography Extensions Volume II.
156
157 * :c:macro:`RISCV_HWPROBE_EXT_ZFH`: The Zfh extension version 1.0 is supported
158 as defined in the RISC-V ISA manual.
159
160 * :c:macro:`RISCV_HWPROBE_EXT_ZFHMIN`: The Zfhmin extension version 1.0 is
161 supported as defined in the RISC-V ISA manual.
162
163 * :c:macro:`RISCV_HWPROBE_EXT_ZIHINTNTL`: The Zihintntl extension version 1.0
164 is supported as defined in the RISC-V ISA manual.
165
166 * :c:macro:`RISCV_HWPROBE_EXT_ZVFH`: The Zvfh extension is supported as
167 defined in the RISC-V Vector manual starting from commit e2ccd0548d6c
168 ("Remove draft warnings from Zvfh[min]").
169
170 * :c:macro:`RISCV_HWPROBE_EXT_ZVFHMIN`: The Zvfhmin extension is supported as
171 defined in the RISC-V Vector manual starting from commit e2ccd0548d6c
172 ("Remove draft warnings from Zvfh[min]").
173
174 * :c:macro:`RISCV_HWPROBE_EXT_ZFA`: The Zfa extension is supported as
175 defined in the RISC-V ISA manual starting from commit 056b6ff467c7
176 ("Zfa is ratified").
177
178 * :c:macro:`RISCV_HWPROBE_EXT_ZTSO`: The Ztso extension is supported as
179 defined in the RISC-V ISA manual starting from commit 5618fb5a216b
180 ("Ztso is now ratified.")
181
182 * :c:macro:`RISCV_HWPROBE_EXT_ZACAS`: The Zacas extension is supported as
183 defined in the Atomic Compare-and-Swap (CAS) instructions manual starting
184 from commit 5059e0ca641c ("update to ratified").
185
186 * :c:macro:`RISCV_HWPROBE_EXT_ZICOND`: The Zicond extension is supported as
187 defined in the RISC-V Integer Conditional (Zicond) operations extension
188 manual starting from commit 95cf1f9 ("Add changes requested by Ved
189 during signoff")
190
191 * :c:macro:`RISCV_HWPROBE_EXT_ZIHINTPAUSE`: The Zihintpause extension is
192 supported as defined in the RISC-V ISA manual starting from commit
193 d8ab5c78c207 ("Zihintpause is ratified").
194
195 * :c:macro:`RISCV_HWPROBE_EXT_ZVE32X`: The Vector sub-extension Zve32x is
196 supported, as defined by version 1.0 of the RISC-V Vector extension manual.
197
198 * :c:macro:`RISCV_HWPROBE_EXT_ZVE32F`: The Vector sub-extension Zve32f is
199 supported, as defined by version 1.0 of the RISC-V Vector extension manual.
200
201 * :c:macro:`RISCV_HWPROBE_EXT_ZVE64X`: The Vector sub-extension Zve64x is
202 supported, as defined by version 1.0 of the RISC-V Vector extension manual.
203
204 * :c:macro:`RISCV_HWPROBE_EXT_ZVE64F`: The Vector sub-extension Zve64f is
205 supported, as defined by version 1.0 of the RISC-V Vector extension manual.
206
207 * :c:macro:`RISCV_HWPROBE_EXT_ZVE64D`: The Vector sub-extension Zve64d is
208 supported, as defined by version 1.0 of the RISC-V Vector extension manual.
209
210 * :c:macro:`RISCV_HWPROBE_EXT_ZIMOP`: The Zimop May-Be-Operations extension is
211 supported as defined in the RISC-V ISA manual starting from commit
212 58220614a5f ("Zimop is ratified/1.0").
213
214 * :c:macro:`RISCV_HWPROBE_EXT_ZCA`: The Zca extension part of Zc* standard
215 extensions for code size reduction, as ratified in commit 8be3419c1c0
216 ("Zcf doesn't exist on RV64 as it contains no instructions") of
217 riscv-code-size-reduction.
218
219 * :c:macro:`RISCV_HWPROBE_EXT_ZCB`: The Zcb extension part of Zc* standard
220 extensions for code size reduction, as ratified in commit 8be3419c1c0
221 ("Zcf doesn't exist on RV64 as it contains no instructions") of
222 riscv-code-size-reduction.
223
224 * :c:macro:`RISCV_HWPROBE_EXT_ZCD`: The Zcd extension part of Zc* standard
225 extensions for code size reduction, as ratified in commit 8be3419c1c0
226 ("Zcf doesn't exist on RV64 as it contains no instructions") of
227 riscv-code-size-reduction.
228
229 * :c:macro:`RISCV_HWPROBE_EXT_ZCF`: The Zcf extension part of Zc* standard
230 extensions for code size reduction, as ratified in commit 8be3419c1c0
231 ("Zcf doesn't exist on RV64 as it contains no instructions") of
232 riscv-code-size-reduction.
233
234 * :c:macro:`RISCV_HWPROBE_EXT_ZCMOP`: The Zcmop May-Be-Operations extension is
235 supported as defined in the RISC-V ISA manual starting from commit
236 c732a4f39a4 ("Zcmop is ratified/1.0").
237
238 * :c:macro:`RISCV_HWPROBE_EXT_ZAWRS`: The Zawrs extension is supported as
239 ratified in commit 98918c844281 ("Merge pull request #1217 from
240 riscv/zawrs") of riscv-isa-manual.
241
242 * :c:macro:`RISCV_HWPROBE_KEY_CPUPERF_0`: Deprecated. Returns similar values to
243 :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`, but the key was
244 mistakenly classified as a bitmask rather than a value.
245
246 * :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`: An enum value describing
247 the performance of misaligned scalar native word accesses on the selected set
248 of processors.
249
250 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNKNOWN`: The performance of
251 misaligned scalar accesses is unknown.
252
253 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_EMULATED`: Misaligned scalar
254 accesses are emulated via software, either in or below the kernel. These
255 accesses are always extremely slow.
256
257 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_SLOW`: Misaligned scalar native
258 word sized accesses are slower than the equivalent quantity of byte
259 accesses. Misaligned accesses may be supported directly in hardware, or
260 trapped and emulated by software.
261
262 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_FAST`: Misaligned scalar native
263 word sized accesses are faster than the equivalent quantity of byte
264 accesses.
265
266 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNSUPPORTED`: Misaligned scalar
267 accesses are not supported at all and will generate a misaligned address
268 fault.
269
270 * :c:macro:`RISCV_HWPROBE_KEY_ZICBOZ_BLOCK_SIZE`: An unsigned int which
271 represents the size of the Zicboz block in bytes.
272
273 * :c:macro:`RISCV_HWPROBE_KEY_HIGHEST_VIRT_ADDRESS`: An unsigned long which
274 represent the highest userspace virtual address usable.
275
276 * :c:macro:`RISCV_HWPROBE_KEY_TIME_CSR_FREQ`: Frequency (in Hz) of `time CSR`.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.