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