From bec399e5a05a517430abb10c3286279a7a31cb9f Mon Sep 17 00:00:00 2001 From: Tsukasa OI Date: Fri, 15 Aug 2025 02:34:17 +0000 Subject: [PATCH] std_detect: RISC-V platform guide documentation This is practically a revert of a revert, making the commit e907456b2e10622ccd854a3bba8d02ce170b5dbb on `stdarch` come around again with minor fixes, enhancements and adjustments. An excerpt from the original commit message follows: Since there's no architectural feature detection on RISC-V (unlike `CPUID` on x86 architectures and some system registers on Arm/AArch64), runtime feature detection entirely depends on the platform-specific facility. As a result, availability of each feature heavily depends on the platform and its version. To help users make a decision for feature checking on a RISC-V system, this commit adds a platform guide with minimum supported platform versions. --- library/std_detect/src/detect/arch/riscv.rs | 197 +++++++++++--------- 1 file changed, 114 insertions(+), 83 deletions(-) diff --git a/library/std_detect/src/detect/arch/riscv.rs b/library/std_detect/src/detect/arch/riscv.rs index 1d21b1d485589..1e57d09edb143 100644 --- a/library/std_detect/src/detect/arch/riscv.rs +++ b/library/std_detect/src/detect/arch/riscv.rs @@ -37,90 +37,121 @@ features! { /// /// # Unprivileged Specification /// - /// The supported ratified RISC-V instruction sets are as follows: + /// The supported ratified RISC-V instruction sets are as follows (OS + /// columns denote runtime feature detection support with or without the + /// minimum supported version): /// - /// * RV32E: `"rv32e"` - /// * RV32I: `"rv32i"` - /// * RV64I: `"rv64i"` - /// * A: `"a"` - /// * Zaamo: `"zaamo"` - /// * Zalrsc: `"zalrsc"` - /// * B: `"b"` - /// * Zba: `"zba"` - /// * Zbb: `"zbb"` - /// * Zbs: `"zbs"` - /// * C: `"c"` - /// * Zca: `"zca"` - /// * Zcd: `"zcd"` (if D is enabled) - /// * Zcf: `"zcf"` (if F is enabled on RV32) - /// * D: `"d"` - /// * F: `"f"` - /// * M: `"m"` - /// * Q: `"q"` - /// * V: `"v"` - /// * Zve32x: `"zve32x"` - /// * Zve32f: `"zve32f"` - /// * Zve64x: `"zve64x"` - /// * Zve64f: `"zve64f"` - /// * Zve64d: `"zve64d"` - /// * Zicbom: `"zicbom"` - /// * Zicboz: `"zicboz"` - /// * Zicntr: `"zicntr"` - /// * Zicond: `"zicond"` - /// * Zicsr: `"zicsr"` - /// * Zifencei: `"zifencei"` - /// * Zihintntl: `"zihintntl"` - /// * Zihintpause: `"zihintpause"` - /// * Zihpm: `"zihpm"` - /// * Zimop: `"zimop"` - /// * Zabha: `"zabha"` - /// * Zacas: `"zacas"` - /// * Zawrs: `"zawrs"` - /// * Zfa: `"zfa"` - /// * Zfbfmin: `"zfbfmin"` - /// * Zfh: `"zfh"` - /// * Zfhmin: `"zfhmin"` - /// * Zfinx: `"zfinx"` - /// * Zdinx: `"zdinx"` - /// * Zhinx: `"zhinx"` - /// * Zhinxmin: `"zhinxmin"` - /// * Zcb: `"zcb"` - /// * Zcmop: `"zcmop"` - /// * Zbc: `"zbc"` - /// * Zbkb: `"zbkb"` - /// * Zbkc: `"zbkc"` - /// * Zbkx: `"zbkx"` - /// * Zk: `"zk"` - /// * Zkn: `"zkn"` - /// * Zknd: `"zknd"` - /// * Zkne: `"zkne"` - /// * Zknh: `"zknh"` - /// * Zkr: `"zkr"` - /// * Zks: `"zks"` - /// * Zksed: `"zksed"` - /// * Zksh: `"zksh"` - /// * Zkt: `"zkt"` - /// * Zvbb: `"zvbb"` - /// * Zvbc: `"zvbc"` - /// * Zvfbfmin: `"zvfbfmin"` - /// * Zvfbfwma: `"zvfbfwma"` - /// * Zvfh: `"zvfh"` - /// * Zvfhmin: `"zvfhmin"` - /// * Zvkb: `"zvkb"` - /// * Zvkg: `"zvkg"` - /// * Zvkn: `"zvkn"` - /// * Zvkned: `"zvkned"` - /// * Zvknha: `"zvknha"` - /// * Zvknhb: `"zvknhb"` - /// * Zvknc: `"zvknc"` - /// * Zvkng: `"zvkng"` - /// * Zvks: `"zvks"` - /// * Zvksed: `"zvksed"` - /// * Zvksh: `"zvksh"` - /// * Zvksc: `"zvksc"` - /// * Zvksg: `"zvksg"` - /// * Zvkt: `"zvkt"` - /// * Ztso: `"ztso"` + /// | Literal | Base | Linux | + /// |:---------- |:------- |:---------- | + /// | `"rv32e"` | RV32E | No | + /// | `"rv32i"` | RV32I | Yes [^ima] | + /// | `"rv64i"` | RV64I | Yes [^ima] | + /// + /// | Literal | Extension | Linux | + /// |:--------------- |:----------- |:------------------- | + /// | `"a"` | A | Yes [^ima] | + /// | `"b"` | B | 6.5 | + /// | `"c"` | C | Yes | + /// | `"d"` | D | Yes | + /// | `"f"` | F | Yes | + /// | `"m"` | M | Yes [^ima] | + /// | `"q"` | Q | No | + /// | `"v"` | V | 6.5 | + /// | `"zaamo"` | Zaamo | 6.15 [^ima] [^dep] | + /// | `"zabha"` | Zabha | 6.16 | + /// | `"zacas"` | Zacas | 6.8 | + /// | `"zalrsc"` | Zalrsc | 6.15 [^ima] [^dep] | + /// | `"zawrs"` | Zawrs | 6.11 | + /// | `"zba"` | Zba | 6.5 | + /// | `"zbb"` | Zbb | 6.5 | + /// | `"zbc"` | Zbc | 6.8 | + /// | `"zbkb"` | Zbkb | 6.8 | + /// | `"zbkc"` | Zbkc | 6.8 | + /// | `"zbkx"` | Zbkx | 6.8 | + /// | `"zbs"` | Zbs | 6.5 | + /// | `"zca"` | Zca | 6.11 [^dep] | + /// | `"zcb"` | Zcb | 6.11 | + /// | `"zcd"` | Zcd | 6.11 [^dep] | + /// | `"zcf"` | Zcf | 6.11 [^dep] | + /// | `"zcmop"` | Zcmop | 6.11 | + /// | `"zdinx"` | Zdinx | No | + /// | `"zfa"` | Zfa | 6.8 | + /// | `"zfbfmin"` | Zfbfmin | 6.15 | + /// | `"zfh"` | Zfh | 6.8 | + /// | `"zfhmin"` | Zfhmin | 6.8 | + /// | `"zfinx"` | Zfinx | No | + /// | `"zhinx"` | Zhinx | No | + /// | `"zhinxmin"` | Zhinxmin | No | + /// | `"zicbom"` | Zicbom | 6.15 | + /// | `"zicboz"` | Zicboz | 6.7 | + /// | `"zicntr"` | Zicntr | 6.15 [^ima] [^cntr] | + /// | `"zicond"` | Zicond | 6.8 | + /// | `"zicsr"` | Zicsr | No [^ima] [^dep] | + /// | `"zifencei"` | Zifencei | No [^ima] | + /// | `"zihintntl"` | Zihintntl | 6.8 | + /// | `"zihintpause"` | Zihintpause | 6.10 | + /// | `"zihpm"` | Zihpm | 6.15 [^cntr] | + /// | `"zimop"` | Zimop | 6.11 | + /// | `"zk"` | Zk | No [^zkr] | + /// | `"zkn"` | Zkn | 6.8 | + /// | `"zknd"` | Zknd | 6.8 | + /// | `"zkne"` | Zkne | 6.8 | + /// | `"zknh"` | Zknh | 6.8 | + /// | `"zkr"` | Zkr | No [^zkr] | + /// | `"zks"` | Zks | 6.8 | + /// | `"zksed"` | Zksed | 6.8 | + /// | `"zksh"` | Zksh | 6.8 | + /// | `"zkt"` | Zkt | 6.8 | + /// | `"ztso"` | Ztso | 6.8 | + /// | `"zvbb"` | Zvbb | 6.8 | + /// | `"zvbc"` | Zvbc | 6.8 | + /// | `"zve32f"` | Zve32f | 6.11 [^dep] | + /// | `"zve32x"` | Zve32x | 6.11 [^dep] | + /// | `"zve64d"` | Zve64d | 6.11 [^dep] | + /// | `"zve64f"` | Zve64f | 6.11 [^dep] | + /// | `"zve64x"` | Zve64x | 6.11 [^dep] | + /// | `"zvfbfmin"` | Zvfbfmin | 6.15 | + /// | `"zvfbfwma"` | Zvfbfwma | 6.15 | + /// | `"zvfh"` | Zvfh | 6.8 | + /// | `"zvfhmin"` | Zvfhmin | 6.8 | + /// | `"zvkb"` | Zvkb | 6.8 | + /// | `"zvkg"` | Zvkg | 6.8 | + /// | `"zvkn"` | Zvkn | 6.8 | + /// | `"zvknc"` | Zvknc | 6.8 | + /// | `"zvkned"` | Zvkned | 6.8 | + /// | `"zvkng"` | Zvkng | 6.8 | + /// | `"zvknha"` | Zvknha | 6.8 | + /// | `"zvknhb"` | Zvknhb | 6.8 | + /// | `"zvks"` | Zvks | 6.8 | + /// | `"zvksc"` | Zvksc | 6.8 | + /// | `"zvksed"` | Zvksed | 6.8 | + /// | `"zvksg"` | Zvksg | 6.8 | + /// | `"zvksh"` | Zvksh | 6.8 | + /// | `"zvkt"` | Zvkt | 6.8 | + /// + /// [^ima]: Or enabled when the IMA base behavior is detected on the Linux + /// kernel version 6.4 or later (for bases, the only matching one -- either + /// `"rv32i"` or `"rv64i"` -- is enabled). + /// + /// [^cntr]: Even if this extension is available, it does not necessarily + /// mean all performance counters are accessible. + /// For example, accesses to all performance counters except `time` + /// (wall-clock) are blocked by default on the Linux kernel + /// version 6.6 or later. + /// Also beware that, even if performance counters like `cycle` and + /// `instret` are accessible, their value can be unreliable (e.g. returning + /// the constant value) under certain circumstances. + /// + /// [^dep]: Or enabled as a dependency of another extension (a superset) + /// even if runtime detection of this feature itself is not supported (as + /// long as the runtime detection of the superset is supported). + /// + /// [^zkr]: Linux does not report existence of this extension even if + /// supported by the hardware mainly because the `seed` CSR on the Zkr + /// extension (which provides hardware-based randomness) is normally + /// inaccessible from the user mode. + /// For the Zk extension features except this CSR, check existence of both + /// `"zkn"` and `"zkt"` features instead. /// /// There's also bases and extensions marked as standard instruction set, /// but they are in frozen or draft state. These instruction sets are also