Documentation/arch/riscv/hwprobe.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 RISC-V Hardware Probing Interface
   4 ---------------------------------
   5
   6 The RISC-V hardware probing interface is based around a single syscall, which
   7 is 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
  18 The arguments are split into three groups: an array of key-value pairs, a CPU
  19 set, and some flags. The key-value pairs are supplied with a count. Userspace
  20 must prepopulate the key field for each element, and the kernel will fill in the
  21 value if the key is recognized. If a key is unknown to the kernel, its key field
  22 will be cleared to -1, and its value set to 0. The CPU set is defined by
  23 CPU_SET(3) with size ``cpusetsize`` bytes. For value-like keys (eg. vendor,
  24 arch, impl), the returned value will only be valid if all CPUs in the given set
  25 have the same value. Otherwise -1 will be returned. For boolean-like keys, the
  26 value returned will be a logical AND of the values for the specified CPUs.
  27 Usermode can supply NULL for ``cpus`` and 0 for ``cpusetsize`` as a shortcut for
  28 all 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
  42 All other flags are reserved for future compatibility and must be zero.
  43
  44 On success 0 is returned, on failure a negative error code is returned.
  45
  46 The 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_EXT_SUPM`: The Supm extension is supported as
 243        defined in version 1.0 of the RISC-V Pointer Masking extensions.
 244
 245 * :c:macro:`RISCV_HWPROBE_KEY_CPUPERF_0`: Deprecated.  Returns similar values to
 246      :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`, but the key was
 247      mistakenly classified as a bitmask rather than a value.
 248
 249 * :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_SCALAR_PERF`: An enum value describing
 250   the performance of misaligned scalar native word accesses on the selected set
 251   of processors.
 252
 253   * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNKNOWN`: The performance of
 254     misaligned scalar accesses is unknown.
 255
 256   * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_EMULATED`: Misaligned scalar
 257     accesses are emulated via software, either in or below the kernel.  These
 258     accesses are always extremely slow.
 259
 260   * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_SLOW`: Misaligned scalar native
 261     word sized accesses are slower than the equivalent quantity of byte
 262     accesses. Misaligned accesses may be supported directly in hardware, or
 263     trapped and emulated by software.
 264
 265   * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_FAST`: Misaligned scalar native
 266     word sized accesses are faster than the equivalent quantity of byte
 267     accesses.
 268
 269   * :c:macro:`RISCV_HWPROBE_MISALIGNED_SCALAR_UNSUPPORTED`: Misaligned scalar
 270     accesses are not supported at all and will generate a misaligned address
 271     fault.
 272
 273 * :c:macro:`RISCV_HWPROBE_KEY_ZICBOZ_BLOCK_SIZE`: An unsigned int which
 274   represents the size of the Zicboz block in bytes.
 275
 276 * :c:macro:`RISCV_HWPROBE_KEY_HIGHEST_VIRT_ADDRESS`: An unsigned long which
 277   represent the highest userspace virtual address usable.
 278
 279 * :c:macro:`RISCV_HWPROBE_KEY_TIME_CSR_FREQ`: Frequency (in Hz) of `time CSR`.
 280
 281 * :c:macro:`RISCV_HWPROBE_KEY_MISALIGNED_VECTOR_PERF`: An enum value describing the
 282      performance of misaligned vector accesses on the selected set of processors.
 283
 284   * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_UNKNOWN`: The performance of misaligned
 285     vector accesses is unknown.
 286
 287   * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_SLOW`: 32-bit misaligned accesses using vector
 288     registers are slower than the equivalent quantity of byte accesses via vector registers.
 289     Misaligned accesses may be supported directly in hardware, or trapped and emulated by software.
 290
 291   * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_FAST`: 32-bit misaligned accesses using vector
 292     registers are faster than the equivalent quantity of byte accesses via vector registers.
 293
 294   * :c:macro:`RISCV_HWPROBE_MISALIGNED_VECTOR_UNSUPPORTED`: Misaligned vector accesses are
 295     not supported at all and will generate a misaligned address fault.