From nobody Mon Feb 9 05:52:59 2026 Received: from mail-ot1-f66.google.com (mail-ot1-f66.google.com [209.85.210.66]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D9D0029B799 for ; Sat, 17 Jan 2026 23:32:43 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.66 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768692766; cv=none; b=Qdn1pLhaODrfmmuu0Rd5cM56sz1AIgOPM0N2uGxXKOKhHhQPg/iyA8Geq/1KwnnVNQjTU6SVtRAE74V/Cf1SBAVwuq55g0DX4P1nD8yfv/hzJBTxDhWXHwx6lYhWPIxB/PbGUCe0klG3kPhm2IjClmgxWcaZt3uYwSrPnRUnr94= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1768692766; c=relaxed/simple; bh=nuzfFbZEU3k5cU+MiiBqYrDg+WADiuf533wpQ8DfhBs=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References: MIME-Version; b=FSj3MfYARABIT33E553L54Cj4NkF7PWcN6d9dWP48YvSGMKq3fhRmJYMyBIu8Ktw6WXdQ9n56cvdpEt7Qd/pGZ2IP7LKB+BQ5xlGj9pCDVmBaUYtZx0D874FufMWBjdUY9qJGMYrsKksZwUcMxVq2K4aJ0ERgDrSBGxgknqqhlY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=nZxCBuN8; arc=none smtp.client-ip=209.85.210.66 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="nZxCBuN8" Received: by mail-ot1-f66.google.com with SMTP id 46e09a7af769-7cfd819ae5eso1687704a34.1 for ; Sat, 17 Jan 2026 15:32:43 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1768692763; x=1769297563; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=9QCMS+eF83vmFIaisSFMfMqnhtdmha//28PB8xvwFi8=; b=nZxCBuN8UwkhDPndteZg/N9ZaSMdr89r9Npua+41qVpMPfbs4a7ssfXQTPIRueV2Ad VKu1Q+BTiWcyWtEvCrkGfOvoN3PQgcuibIYaVAj+TFNWF4AvAcYLFeEAkch7VC4WxlMc L9Ocv8KxguJvqzfY7LISHjig5dNSgNvdI0aMbrfPYw6TlGomUzWnpUkfQftwNVMmYNvS 9qvuIwsQT2mGLs82JdqIzhvp/W+dPCnYj4XdBZG2xaWuMrM8+6mhMXIksgL9e+stRFwN bdmYy4tV0gLeTmroUCZSfNM5MLT3fPQSjQC54iNQA69xdaqXID0pgCme+hkOAsNs3efR dLmg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1768692763; x=1769297563; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=9QCMS+eF83vmFIaisSFMfMqnhtdmha//28PB8xvwFi8=; b=e0oHCRo+M2UyhtWw5YrzFhbBhydz/5t/YcjZXV8zRcwB1Ska/pBE3+u2cXGae91mBa w6ftqpszgSXoHkVSBJcFbtZuaxYC6bUOYuafsf1mv1wVP+cMzwk232D4Zy8HZdcBd0FQ 8jxLrXZGYSZzC6WiwBCDzM7MnC5KCyCj6aKQaRBUQBpSzo9ztUsq2rEN2E/ClgUMnV6w eMjXbxGaAi2PfMVDeqcresmm7kM63YC+e65sXcA0+VtT6tBuxJywH6jEoczsFh22NIca w8j4KGCx2CxliahKyrUfr+2W0mcQ8ekPenvp9hqTChdUvAn8lLv+JVfy0iI7/KpA2DL/ UlOw== X-Forwarded-Encrypted: i=1; AJvYcCW6TLx1riI0MJNYFKIIjASV1eftEZddwqR7YnyM3MWjdP7A5jrbbJgua4nN6rbSPSwFrlxv5hfSZ8AtdIs=@vger.kernel.org X-Gm-Message-State: AOJu0YyLoYoS1JdsJW2TQKHNR9OBF7dyOLsbcvU6RZiHB0uRLzb4Tyex 1bpLqIEG38WL7ilKfv8XlZR60eJjA/IxXe8x1seR9UyqfhoaAvut9yau X-Gm-Gg: AY/fxX6Rp+IDwJgqAHuDAuFCM7T1hkHeNrfHcqJV/MiNvIcALl/EHkz9ymX7M6ziHdn Ly2YQfEm8s6jWhXySXv07tL1CUTuvOkzwuV7wPeWFy4MuTwHTZ3Y8sHwjzK+HiDDETUaGwBx1Sx iEbUijenrdgzhR5K7QoQna15GRc52PnhW4AKgljbkrOCm9MTQ6/pAm+3XsDvMKU6iXccDlmZ3uI g7jAcxfsOnIm5l9itz79R+8mUAn97LCWpBluqOiCI/lNV4iwYz5UWpfzZF4lGuTQbZywRVhFn1d TQe29bD8kpbqpXEGXHdXeJUPXZgwUn0YNj5M4Ok0twn4v+UTJxHB8RQL/ppZMXECNJb9N88Yhdm 1WTlIL8YZ7t5xzlHzEUdiHAqlqVDYsmL7IBgmQ7dx4iaNqn2/R2yToHtn/ryWO5vZNzu7/G+He2 OQR1qLNjiK3DefKA1V/kLdPapx4Q4dzH7ChXRkN/rM X-Received: by 2002:a05:6808:30a2:b0:455:dfc8:46a6 with SMTP id 5614622812f47-45c9c018560mr3951786b6e.28.1768692761657; Sat, 17 Jan 2026 15:32:41 -0800 (PST) Received: from localhost.localdomain ([50.24.139.5]) by smtp.gmail.com with ESMTPSA id 5614622812f47-45c9e0086a4sm3424232b6e.12.2026.01.17.15.32.38 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Sat, 17 Jan 2026 15:32:40 -0800 (PST) From: Andy Chiu To: linux-riscv@lists.infradead.org, linux-doc@vger.kernel.org, pjw@kernel.org Cc: Andy Chiu , Zihong Yao , linux-kernel@vger.kernel.org, Alexandre Ghiti , paul.walmsley@sifive.com, greentime.hu@sifive.com, nick.hu@sifive.com, nylon.chen@sifive.com, eric.lin@sifive.com, vincent.chen@sifive.com, zong.li@sifive.com, yongxuan.wang@sifive.com, samuel.holland@sifive.com Subject: [PATCH v2 1/1] Documentation: riscv: update Vector discovery for userspace Date: Sat, 17 Jan 2026 17:32:27 -0600 Message-Id: <20260117233228.36088-2-andybnac@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-145) In-Reply-To: <20260117233228.36088-1-andybnac@gmail.com> References: <20260117233228.36088-1-andybnac@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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=3D220795 Suggested-by: Zihong Yao Signed-off-by: Andy Chiu --- 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 po= licies -configured from the parent process. Also, users must note that these inter= faces -are not portable to non-Linux, nor non-RISC-V environments, so it is disco= urage -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 t= he -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 pr= ocess. +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 res= ult 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. =20 * prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg) =20 @@ -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. =20 - Note that ELF programs are able to get the availability of V for itsel= f by - reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in t= he - auxiliary vector. + Note that ELF programs are able to get the availability of the standar= d V + extension for itself by reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of + :c:macro:`ELF_HWCAP` in the auxiliary vector. =20 Return value: * a nonnegative value on success; @@ -138,3 +139,33 @@ As indicated by version 1.0 of the V extension [1], ve= ctor registers are clobbered by system calls. =20 1: https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.ad= oc + +4. Vector Extensions Discovery +------------------------------- + +Existing kernel supports running user-mode Vector code on hardware impleme= nting +various sets of Vector-related extensions. Zve32x is the minimal subextens= ion +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 th= e kernel +recognizes and supports an extension on a hardware implementation, the ker= nel +indicates its existence on ``/proc/cpuinfo``, and the corresponding bits o= btained +from ``riscv_hwprobe(2)`` is also set. + +The existence of an extension does not necessary guarantee its availibilit= y to +any given process. The user process is responsible for checking if an exte= nsion is +available before using it. Traditionally, :c:macro:`ELF_HWCAP` is designed= for such +availibility check. This remains useful for checking the availabilty for t= he full +set of v1.0 Vector extension, defined by the isa string "v", by referencin= g the +:c:macro:`COMPAT_HWCAP_ISA_V` bit. + +However, even though the kernel provides compatibility for flexible hardwa= re +configurations, the kernel does not report the availability of "v" subexte= nsions, +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 s= ee 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 c= hek. +Then, ``prctl(PR_RISCV_V_GET_CONTROL)`` serves as the availibility check t= o see if +executing any Vector instructions is allowed by the runtime environment. --=20 2.39.3 (Apple Git-145)