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_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`.
277