1.. SPDX-License-Identifier: GPL-2.0
2
3RISC-V Hardware Probing Interface
4---------------------------------
5
6The RISC-V hardware probing interface is based around a single syscall, which
7is 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
18The arguments are split into three groups: an array of key-value pairs, a CPU
19set, and some flags. The key-value pairs are supplied with a count. Userspace
20must prepopulate the key field for each element, and the kernel will fill in the
21value if the key is recognized. If a key is unknown to the kernel, its key field
22will be cleared to -1, and its value set to 0. The CPU set is defined by
23CPU_SET(3) with size ``cpusetsize`` bytes. For value-like keys (eg. vendor,
24arch, impl), the returned value will only be valid if all CPUs in the given set
25have the same value. Otherwise -1 will be returned. For boolean-like keys, the
26value returned will be a logical AND of the values for the specified CPUs.
27Usermode can supply NULL for ``cpus`` and 0 for ``cpusetsize`` as a shortcut for
28all 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
42All other flags are reserved for future compatibility and must be zero.
43
44On success 0 is returned, on failure a negative error code is returned.
45
46The 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_MIMPID`: Contains the value of ``mimpid``, 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_ZICNTR`: The Zicntr extension version 2.0
187       is supported as defined in the RISC-V ISA manual.
188
189  * :c:macro:`RISCV_HWPROBE_EXT_ZICOND`: The Zicond extension is supported as
190       defined in the RISC-V Integer Conditional (Zicond) operations extension
191       manual starting from commit 95cf1f9 ("Add changes requested by Ved
192       during signoff")
193
194  * :c:macro:`RISCV_HWPROBE_EXT_ZIHINTPAUSE`: The Zihintpause extension is
195       supported as defined in the RISC-V ISA manual starting from commit
196       d8ab5c78c207 ("Zihintpause is ratified").
197
198  * :c:macro:`RISCV_HWPROBE_EXT_ZIHPM`: The Zihpm extension version 2.0
199       is supported as defined in the RISC-V ISA manual.
200
201  * :c:macro:`RISCV_HWPROBE_EXT_ZVE32X`: The Vector sub-extension Zve32x is
202    supported, as defined by version 1.0 of the RISC-V Vector extension manual.
203
204  * :c:macro:`RISCV_HWPROBE_EXT_ZVE32F`: The Vector sub-extension Zve32f is
205    supported, as defined by version 1.0 of the RISC-V Vector extension manual.
206
207  * :c:macro:`RISCV_HWPROBE_EXT_ZVE64X`: The Vector sub-extension Zve64x is
208    supported, as defined by version 1.0 of the RISC-V Vector extension manual.
209
210  * :c:macro:`RISCV_HWPROBE_EXT_ZVE64F`: The Vector sub-extension Zve64f is
211    supported, as defined by version 1.0 of the RISC-V Vector extension manual.
212
213  * :c:macro:`RISCV_HWPROBE_EXT_ZVE64D`: The Vector sub-extension Zve64d is
214    supported, as defined by version 1.0 of the RISC-V Vector extension manual.
215
216  * :c:macro:`RISCV_HWPROBE_EXT_ZIMOP`: The Zimop May-Be-Operations extension is
217       supported as defined in the RISC-V ISA manual starting from commit
218       58220614a5f ("Zimop is ratified/1.0").
219
220  * :c:macro:`RISCV_HWPROBE_EXT_ZCA`: The Zca extension part of Zc* standard
221       extensions for code size reduction, as ratified in commit 8be3419c1c0
222       ("Zcf doesn't exist on RV64 as it contains no instructions") of
223       riscv-code-size-reduction.
224
225  * :c:macro:`RISCV_HWPROBE_EXT_ZCB`: The Zcb extension part of Zc* standard
226       extensions for code size reduction, as ratified in commit 8be3419c1c0
227       ("Zcf doesn't exist on RV64 as it contains no instructions") of
228       riscv-code-size-reduction.
229
230  * :c:macro:`RISCV_HWPROBE_EXT_ZCD`: The Zcd extension part of Zc* standard
231       extensions for code size reduction, as ratified in commit 8be3419c1c0
232       ("Zcf doesn't exist on RV64 as it contains no instructions") of
233       riscv-code-size-reduction.
234
235  * :c:macro:`RISCV_HWPROBE_EXT_ZCF`: The Zcf extension part of Zc* standard
236       extensions for code size reduction, as ratified in commit 8be3419c1c0
237       ("Zcf doesn't exist on RV64 as it contains no instructions") of
238       riscv-code-size-reduction.
239
240  * :c:macro:`RISCV_HWPROBE_EXT_ZCMOP`: The Zcmop May-Be-Operations extension is
241       supported as defined in the RISC-V ISA manual starting from commit
242       c732a4f39a4 ("Zcmop is ratified/1.0").
243
244  * :c:macro:`RISCV_HWPROBE_EXT_ZAWRS`: The Zawrs extension is supported as
245       ratified in commit 98918c844281 ("Merge pull request #1217 from
246       riscv/zawrs") of riscv-isa-manual.
247
248  * :c:macro:`RISCV_HWPROBE_EXT_ZAAMO`: The Zaamo extension is supported as
249       defined in the in the RISC-V ISA manual starting from commit e87412e621f1
250       ("integrate Zaamo and Zalrsc text (#1304)").
251
252  * :c:macro:`RISCV_HWPROBE_EXT_ZALRSC`: The Zalrsc extension is supported as
253       defined in the in the RISC-V ISA manual starting from commit e87412e621f1
254       ("integrate Zaamo and Zalrsc text (#1304)").
255
256  * :c:macro:`RISCV_HWPROBE_EXT_SUPM`: The Supm extension is supported as
257       defined in version 1.0 of the RISC-V Pointer Masking extensions.
258
259  * :c:macro:`RISCV_HWPROBE_EXT_ZFBFMIN`: The Zfbfmin extension is supported as
260       defined in the RISC-V ISA manual starting from commit 4dc23d6229de
261       ("Added Chapter title to BF16").
262
263  * :c:macro:`RISCV_HWPROBE_EXT_ZVFBFMIN`: The Zvfbfmin extension is supported as
264       defined in the RISC-V ISA manual starting from commit 4dc23d6229de
265       ("Added Chapter title to BF16").
266
267  * :c:macro:`RISCV_HWPROBE_EXT_ZVFBFWMA`: The Zvfbfwma extension is supported as
268       defined in the RISC-V ISA manual starting from commit 4dc23d6229de
269       ("Added Chapter title to BF16").
270
271  * :c:macro:`RISCV_HWPROBE_EXT_ZICBOM`: The Zicbom extension is supported, as
272       ratified in commit 3dd606f ("Create cmobase-v1.0.pdf") of riscv-CMOs.
273
274* :c:macro:`RISCV_HWPROBE_KEY_CPUPERF_0`: Deprecated.  Returns similar values to
275     :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`, but the key was
276     mistakenly classified as a bitmask rather than a value.
277
278* :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`: An enum value describing
279  the performance of misaligned scalar native word accesses on the selected set
280  of processors.
281
282  * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNKNOWN`: The performance of
283    misaligned scalar accesses is unknown.
284
285  * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_EMULATED`: Misaligned scalar
286    accesses are emulated via software, either in or below the kernel.  These
287    accesses are always extremely slow.
288
289  * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_SLOW`: Misaligned scalar native
290    word sized accesses are slower than the equivalent quantity of byte
291    accesses. Misaligned accesses may be supported directly in hardware, or
292    trapped and emulated by software.
293
294  * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_FAST`: Misaligned scalar native
295    word sized accesses are faster than the equivalent quantity of byte
296    accesses.
297
298  * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNSUPPORTED`: Misaligned scalar
299    accesses are not supported at all and will generate a misaligned address
300    fault.
301
302* :c:macro:`RISCV_HWPROBE_KEY_ZICBOZ_BLOCK_SIZE`: An unsigned int which
303  represents the size of the Zicboz block in bytes.
304
305* :c:macro:`RISCV_HWPROBE_KEY_HIGHEST_VIRT_ADDRESS`: An unsigned long which
306  represent the highest userspace virtual address usable.
307
308* :c:macro:`RISCV_HWPROBE_KEY_TIME_CSR_FREQ`: Frequency (in Hz) of `time CSR`.
309
310* :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_VECTOR_PERF`: An enum value describing the
311     performance of misaligned vector accesses on the selected set of processors.
312
313  * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_UNKNOWN`: The performance of misaligned
314    vector accesses is unknown.
315
316  * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_SLOW`: 32-bit misaligned accesses using vector
317    registers are slower than the equivalent quantity of byte accesses via vector registers.
318    Misaligned accesses may be supported directly in hardware, or trapped and emulated by software.
319
320  * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_FAST`: 32-bit misaligned accesses using vector
321    registers are faster than the equivalent quantity of byte accesses via vector registers.
322
323  * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_UNSUPPORTED`: Misaligned vector accesses are
324    not supported at all and will generate a misaligned address fault.
325
326* :c:macro:`RISCV_HWPROBE_KEY_VENDOR_EXT_THEAD_0`: A bitmask containing the
327  thead vendor extensions that are compatible with the
328  :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`: base system behavior.
329
330  * T-HEAD
331
332    * :c:macro:`RISCV_HWPROBE_VENDOR_EXT_XTHEADVECTOR`: The xtheadvector vendor
333        extension is supported in the T-Head ISA extensions spec starting from
334	commit a18c801634 ("Add T-Head VECTOR vendor extension. ").
335
336* :c:macro:`RISCV_HWPROBE_KEY_ZICBOM_BLOCK_SIZE`: An unsigned int which
337  represents the size of the Zicbom block in bytes.
338