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_KEY_CPUPERF_0`: A bitmask that contains performance 192 information about the selected set of processors. 193 194 * :c:macro:`RISCV_HWPROBE_MISALIGNED_UNKNOWN`: The performance of misaligned 195 accesses is unknown. 196 197 * :c:macro:`RISCV_HWPROBE_MISALIGNED_EMULATED`: Misaligned accesses are 198 emulated via software, either in or below the kernel. These accesses are 199 always extremely slow. 200 201 * :c:macro:`RISCV_HWPROBE_MISALIGNED_SLOW`: Misaligned accesses are slower 202 than equivalent byte accesses. Misaligned accesses may be supported 203 directly in hardware, or trapped and emulated by software. 204 205 * :c:macro:`RISCV_HWPROBE_MISALIGNED_FAST`: Misaligned accesses are faster 206 than equivalent byte accesses. 207 208 * :c:macro:`RISCV_HWPROBE_MISALIGNED_UNSUPPORTED`: Misaligned accesses are 209 not supported at all and will generate a misaligned address fault. 210 211* :c:macro:`RISCV_HWPROBE_KEY_ZICBOZ_BLOCK_SIZE`: An unsigned int which 212 represents the size of the Zicboz block in bytes. 213