Documentation/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 cpu_count, 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). For value-like keys (eg. vendor/arch/impl), the returned value will
  24 be only be valid if all CPUs in the given set have the same value. Otherwise -1
  25 will be returned. For boolean-like keys, the value returned will be a logical
  26 AND of the values for the specified CPUs. Usermode can supply NULL for cpus and
  27 0 for cpu_count as a shortcut for all online CPUs. There are currently no flags,
  28 this value must be zero for future compatibility.
  29
  30 On success 0 is returned, on failure a negative error code is returned.
  31
  32 The following keys are defined:
  33
  34 * :c:macro:`RISCV_HWPROBE_KEY_MVENDORID`: Contains the value of ``mvendorid``,
  35   as defined by the RISC-V privileged architecture specification.
  36
  37 * :c:macro:`RISCV_HWPROBE_KEY_MARCHID`: Contains the value of ``marchid``, as
  38   defined by the RISC-V privileged architecture specification.
  39
  40 * :c:macro:`RISCV_HWPROBE_KEY_MIMPLID`: Contains the value of ``mimplid``, as
  41   defined by the RISC-V privileged architecture specification.
  42
  43 * :c:macro:`RISCV_HWPROBE_KEY_BASE_BEHAVIOR`: A bitmask containing the base
  44   user-visible behavior that this kernel supports.  The following base user ABIs
  45   are defined:
  46
  47   * :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`: Support for rv32ima or
  48     rv64ima, as defined by version 2.2 of the user ISA and version 1.10 of the
  49     privileged ISA, with the following known exceptions (more exceptions may be
  50     added, but only if it can be demonstrated that the user ABI is not broken):
  51
  52     * The ``fence.i`` instruction cannot be directly executed by userspace
  53       programs (it may still be executed in userspace via a
  54       kernel-controlled mechanism such as the vDSO).
  55
  56 * :c:macro:`RISCV_HWPROBE_KEY_IMA_EXT_0`: A bitmask containing the extensions
  57   that are compatible with the :c:macro:`RISCV_HWPROBE_BASE_BEHAVIOR_IMA`:
  58   base system behavior.
  59
  60   * :c:macro:`RISCV_HWPROBE_IMA_FD`: The F and D extensions are supported, as
  61     defined by commit cd20cee ("FMIN/FMAX now implement
  62     minimumNumber/maximumNumber, not minNum/maxNum") of the RISC-V ISA manual.
  63
  64   * :c:macro:`RISCV_HWPROBE_IMA_C`: The C extension is supported, as defined
  65     by version 2.2 of the RISC-V ISA manual.
  66
  67   * :c:macro:`RISCV_HWPROBE_IMA_V`: The V extension is supported, as defined by
  68     version 1.0 of the RISC-V Vector extension manual.
  69
  70   * :c:macro:`RISCV_HWPROBE_EXT_ZBA`: The Zba address generation extension is
  71        supported, as defined in version 1.0 of the Bit-Manipulation ISA
  72        extensions.
  73
  74   * :c:macro:`RISCV_HWPROBE_EXT_ZBB`: The Zbb extension is supported, as defined
  75        in version 1.0 of the Bit-Manipulation ISA extensions.
  76
  77   * :c:macro:`RISCV_HWPROBE_EXT_ZBS`: The Zbs extension is supported, as defined
  78        in version 1.0 of the Bit-Manipulation ISA extensions.
  79
  80 * :c:macro:`RISCV_HWPROBE_KEY_CPUPERF_0`: A bitmask that contains performance
  81   information about the selected set of processors.
  82
  83   * :c:macro:`RISCV_HWPROBE_MISALIGNED_UNKNOWN`: The performance of misaligned
  84     accesses is unknown.
  85
  86   * :c:macro:`RISCV_HWPROBE_MISALIGNED_EMULATED`: Misaligned accesses are
  87     emulated via software, either in or below the kernel.  These accesses are
  88     always extremely slow.
  89
  90   * :c:macro:`RISCV_HWPROBE_MISALIGNED_SLOW`: Misaligned accesses are supported
  91     in hardware, but are slower than the cooresponding aligned accesses
  92     sequences.
  93
  94   * :c:macro:`RISCV_HWPROBE_MISALIGNED_FAST`: Misaligned accesses are supported
  95     in hardware and are faster than the cooresponding aligned accesses
  96     sequences.
  97
  98   * :c:macro:`RISCV_HWPROBE_MISALIGNED_UNSUPPORTED`: Misaligned accesses are
  99     not supported at all and will generate a misaligned address fault.