[PATCH v2 0/1] update riscv prctl for discovering V extension

[PATCH v2 0/1] update riscv prctl for discovering V extension

[Andy Chiu]

This version of the patch fixes an htmldocs build fail and some formatting
issues, and it has some sentences rewritten for an easier read. The
patch is based on current riscv fixes and the hash is included at the
bottom.

Link to v1: https://lore.kernel.org/all/20260107000609.63892-1-andybnac@gmail.com/

Andy Chiu (1):
  Documentation: riscv: update Vector discovery for userspace

 Documentation/arch/riscv/vector.rst | 51 +++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 10 deletions(-)


base-commit: b0d7f5f0c9f05f1b6d4ee7110f15bef9c11f9df0
-- 
2.39.3 (Apple Git-145)

[PATCH v2 1/1] Documentation: riscv: update Vector discovery for userspace

[Andy Chiu]

Make it explicit that users may use both HWCAP and
PR_RISCV_V_GET_CONTROL for checking the availability of Vector
extensions. This addresses the ABI usage concern[1] arised from the user
space community in supporting Vector sub-exts and multiversioning.

[1]: https://bugzilla.kernel.org/show_bug.cgi?id=220795

Suggested-by: Zihong Yao <zihong.plct@isrc.iscas.ac.cn>
Signed-off-by: Andy Chiu <andybnac@gmail.com>
---
Changelog v2:
 - fix a document build failed reported by kernel test robot
 - rephrase some sentences and make it easier to read
---
 Documentation/arch/riscv/vector.rst | 51 +++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 10 deletions(-)

diff --git a/Documentation/arch/riscv/vector.rst b/Documentation/arch/riscv/vector.rst
index 3987f5f76a9d..47513edfa879 100644
--- a/Documentation/arch/riscv/vector.rst
+++ b/Documentation/arch/riscv/vector.rst
@@ -13,13 +13,14 @@ order to support the use of the RISC-V Vector Extension.
 Two new prctl() calls are added to allow programs to manage the enablement
 status for the use of Vector in userspace. The intended usage guideline for
 these interfaces is to give init systems a way to modify the availability of V
-for processes running under its domain. Calling these interfaces is not
-recommended in libraries routines because libraries should not override policies
-configured from the parent process. Also, users must note that these interfaces
-are not portable to non-Linux, nor non-RISC-V environments, so it is discourage
-to use in a portable code. To get the availability of V in an ELF program,
-please read :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
-auxiliary vector.
+for processes running under its domain. Changing Vector policy by calling
+:c:macro:`PR_RISCV_V_SET_CONTROL` is not recommended in library routines
+because libraries should not override policies configured by the parent process.
+Also, users must note that these interfaces are not portable to non-Linux,
+nor non-RISC-V environments, so their use is discouraged in portable code.
+To get the availability of V in an ELF program, user code may read the result of
+:c:macro:`PR_RISCV_V_GET_CONTROL`, or the :c:macro:`COMPAT_HWCAP_ISA_V` bit
+of :c:macro:`ELF_HWCAP` in the auxiliary vector.
 
 * prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
 
@@ -91,9 +92,9 @@ auxiliary vector.
     Gets the same Vector enablement status for the calling thread. Setting for
     next execve() call and the inheritance bit are all OR-ed together.
 
-    Note that ELF programs are able to get the availability of V for itself by
-    reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
-    auxiliary vector.
+    Note that ELF programs are able to get the availability of the standard V
+    extension for itself by reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of
+    :c:macro:`ELF_HWCAP` in the auxiliary vector.
 
     Return value:
         * a nonnegative value on success;
@@ -138,3 +139,33 @@ As indicated by version 1.0 of the V extension [1], vector registers are
 clobbered by system calls.
 
 1: https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc
+
+4.  Vector Extensions Discovery
+-------------------------------
+
+Existing kernel supports running user-mode Vector code on hardware implementing
+various sets of Vector-related extensions. Zve32x is the minimal subextension
+required for hardware that implements 1.0 version of the spec. Or, full v0.7 if the
+kernel is compiled with ``RISCV_ISA_V && RISCV_ISA_XTHEADVECTOR``. When the kernel
+recognizes and supports an extension on a hardware implementation, the kernel
+indicates its existence on ``/proc/cpuinfo``, and the corresponding bits obtained
+from ``riscv_hwprobe(2)`` is also set.
+
+The existence of an extension does not necessary guarantee its availibility to
+any given process. The user process is responsible for checking if an extension is
+available before using it. Traditionally, :c:macro:`ELF_HWCAP` is designed for such
+availibility check. This remains useful for checking the availabilty for the full
+set of v1.0 Vector extension, defined by the isa string "v", by referencing the
+:c:macro:`COMPAT_HWCAP_ISA_V` bit.
+
+However, even though the kernel provides compatibility for flexible hardware
+configurations, the kernel does not report the availability of "v" subextensions,
+nor pre-rectified Vector in :c:macro:`ELF_HWCAP` to prevent exagerating the
+limited bit space.
+
+The bit in :c:macro:`ELF_HWCAP` is designed to serve as a quick check to see iff
+the standard "v" extension is both **pressence** and **available** to the process.
+For any non-standard Vector extensions, the ABI guaranteed way to identify their
+existence is by going through the hwprobe(2) interface for the existency chek.
+Then, ``prctl(PR_RISCV_V_GET_CONTROL)`` serves as the availibility check to see if
+executing any Vector instructions is allowed by the runtime environment.
-- 
2.39.3 (Apple Git-145)

Re: [PATCH v2 0/1] update riscv prctl for discovering V extension

[Yao Zihong]

Hi all,

It has been a while since the last activity on this thread,
so I would like to gently ping for comments.

Thanks,
Zihong

Re: [PATCH v2 0/1] update riscv prctl for discovering V extension

[Samuel Holland]

Hi,

On 2026-03-13 4:19 AM, Yao Zihong wrote:
> It has been a while since the last activity on this thread,
> so I would like to gently ping for comments.

There was some off-list discussion about this around this time (anyone involved
please correct me, it has been several weeks), and my understanding of the
sentiment was that:

1) These sysctl and prctl() interfaces were introduced because adding vector
state to the signal frame was technically an ABI break, due to increasing the
minimum signal stack size. The prctl() provided an escape hatch for users to run
existing software that used a smaller signal stack size. Notably, this existing
software necessarily did not use RVV, because any C runtime that supported RVV
would have enforced a larger minimum signal stack size.

2) Using these interfaces for another reason is unsupported, and anyone doing so
gets to keep both pieces. Software that was aware of RVV at compile time is not
expected to ever run with the sysctl/prctl() disabled at runtime.

3) Therefore, hwprobe() is sufficient for detecting the presence of the various
vector extensions. The case where hwprobe() says RVV is available, but its usage
traps, is considered a configuration error.

Regards,
Samuel