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_ZALASR`: The Zalasr extension is supported as 253 frozen at commit 194f0094 ("Version 0.9 for freeze") of riscv-zalasr. 254 255 * :c:macro:`RISCV_HWPROBE_EXT_ZALRSC`: The Zalrsc extension is supported as 256 defined in the in the RISC-V ISA manual starting from commit e87412e621f1 257 ("integrate Zaamo and Zalrsc text (#1304)"). 258 259 * :c:macro:`RISCV_HWPROBE_EXT_SUPM`: The Supm extension is supported as 260 defined in version 1.0 of the RISC-V Pointer Masking extensions. 261 262 * :c:macro:`RISCV_HWPROBE_EXT_ZFBFMIN`: The Zfbfmin extension is supported as 263 defined in the RISC-V ISA manual starting from commit 4dc23d6229de 264 ("Added Chapter title to BF16"). 265 266 * :c:macro:`RISCV_HWPROBE_EXT_ZVFBFMIN`: The Zvfbfmin extension is supported as 267 defined in the RISC-V ISA manual starting from commit 4dc23d6229de 268 ("Added Chapter title to BF16"). 269 270 * :c:macro:`RISCV_HWPROBE_EXT_ZVFBFWMA`: The Zvfbfwma extension is supported as 271 defined in the RISC-V ISA manual starting from commit 4dc23d6229de 272 ("Added Chapter title to BF16"). 273 274 * :c:macro:`RISCV_HWPROBE_EXT_ZICBOM`: The Zicbom extension is supported, as 275 ratified in commit 3dd606f ("Create cmobase-v1.0.pdf") of riscv-CMOs. 276 277 * :c:macro:`RISCV_HWPROBE_EXT_ZABHA`: The Zabha extension is supported as 278 ratified in commit 49f49c842ff9 ("Update to Rafified state") of 279 riscv-zabha. 280 281 * :c:macro:`RISCV_HWPROBE_EXT_ZICBOP`: The Zicbop extension is supported, as 282 ratified in commit 3dd606f ("Create cmobase-v1.0.pdf") of riscv-CMOs. 283 284* :c:macro:`RISCV_HWPROBE_KEY_CPUPERF_0`: Deprecated. Returns similar values to 285 :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`, but the key was 286 mistakenly classified as a bitmask rather than a value. 287 288* :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`: An enum value describing 289 the performance of misaligned scalar native word accesses on the selected set 290 of processors. 291 292 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNKNOWN`: The performance of 293 misaligned scalar accesses is unknown. 294 295 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_EMULATED`: Misaligned scalar 296 accesses are emulated via software, either in or below the kernel. These 297 accesses are always extremely slow. 298 299 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_SLOW`: Misaligned scalar native 300 word sized accesses are slower than the equivalent quantity of byte 301 accesses. Misaligned accesses may be supported directly in hardware, or 302 trapped and emulated by software. 303 304 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_FAST`: Misaligned scalar native 305 word sized accesses are faster than the equivalent quantity of byte 306 accesses. 307 308 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNSUPPORTED`: Misaligned scalar 309 accesses are not supported at all and will generate a misaligned address 310 fault. 311 312* :c:macro:`RISCV_HWPROBE_KEY_ZICBOZ_BLOCK_SIZE`: An unsigned int which 313 represents the size of the Zicboz block in bytes. 314 315* :c:macro:`RISCV_HWPROBE_KEY_HIGHEST_VIRT_ADDRESS`: An unsigned long which 316 represent the highest userspace virtual address usable. 317 318* :c:macro:`RISCV_HWPROBE_KEY_TIME_CSR_FREQ`: Frequency (in Hz) of `time CSR`. 319 320* :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_VECTOR_PERF`: An enum value describing the 321 performance of misaligned vector accesses on the selected set of processors. 322 323 * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_UNKNOWN`: The performance of misaligned 324 vector accesses is unknown. 325 326 * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_SLOW`: 32-bit misaligned accesses using vector 327 registers are slower than the equivalent quantity of byte accesses via vector registers. 328 Misaligned accesses may be supported directly in hardware, or trapped and emulated by software. 329 330 * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_FAST`: 32-bit misaligned accesses using vector 331 registers are faster than the equivalent quantity of byte accesses via vector registers. 332 333 * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_UNSUPPORTED`: Misaligned vector accesses are 334 not supported at all and will generate a misaligned address fault. 335 336* :c:macro:`RISCV_HWPROBE_KEY_VENDOR_EXT_MIPS_0`: A bitmask containing the 337 mips vendor extensions that are compatible with the 338 :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`: base system behavior. 339 340 * MIPS 341 342 * :c:macro:`RISCV_HWPROBE_VENDOR_EXT_XMIPSEXECTL`: The xmipsexectl vendor 343 extension is supported in the MIPS ISA extensions spec. 344 345* :c:macro:`RISCV_HWPROBE_KEY_VENDOR_EXT_THEAD_0`: A bitmask containing the 346 thead vendor extensions that are compatible with the 347 :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`: base system behavior. 348 349 * T-HEAD 350 351 * :c:macro:`RISCV_HWPROBE_VENDOR_EXT_XTHEADVECTOR`: The xtheadvector vendor 352 extension is supported in the T-Head ISA extensions spec starting from 353 commit a18c801634 ("Add T-Head VECTOR vendor extension. "). 354 355* :c:macro:`RISCV_HWPROBE_KEY_ZICBOM_BLOCK_SIZE`: An unsigned int which 356 represents the size of the Zicbom block in bytes. 357 358* :c:macro:`RISCV_HWPROBE_KEY_VENDOR_EXT_SIFIVE_0`: A bitmask containing the 359 sifive vendor extensions that are compatible with the 360 :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`: base system behavior. 361 362 * SIFIVE 363 364 * :c:macro:`RISCV_HWPROBE_VENDOR_EXT_XSFVQMACCDOD`: The Xsfqmaccdod vendor 365 extension is supported in version 1.1 of SiFive Int8 Matrix Multiplication 366 Extensions Specification. 367 368 * :c:macro:`RISCV_HWPROBE_VENDOR_EXT_XSFVQMACCQOQ`: The Xsfqmaccqoq vendor 369 extension is supported in version 1.1 of SiFive Int8 Matrix Multiplication 370 Instruction Extensions Specification. 371 372 * :c:macro:`RISCV_HWPROBE_VENDOR_EXT_XSFVFNRCLIPXFQF`: The Xsfvfnrclipxfqf 373 vendor extension is supported in version 1.0 of SiFive FP32-to-int8 Ranged 374 Clip Instructions Extensions Specification. 375 376 * :c:macro:`RISCV_HWPROBE_VENDOR_EXT_XSFVFWMACCQQQ`: The Xsfvfwmaccqqq 377 vendor extension is supported in version 1.0 of Matrix Multiply Accumulate 378 Instruction Extensions Specification. 379 380* :c:macro:`RISCV_HWPROBE_KEY_ZICBOP_BLOCK_SIZE`: An unsigned int which 381 represents the size of the Zicbop block in bytes. 382