From nobody Sat Feb 7 15:40:37 2026 Received: from mail-oo1-f67.google.com (mail-oo1-f67.google.com [209.85.161.67]) (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 46F2E10F2 for ; Wed, 7 Jan 2026 00:06:15 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.161.67 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767744376; cv=none; b=Mfe+KJIpLqXHTD2xtN7tWWklTn/TivC1K6+z+b0Ulw707wtzUECJfE43JUIYqos/PhqKV+A3jVjH2MpapXKzEkEDQbChQju6PH6no/57w/xXwSAqqmX0PvBYGKOim5py+xrhYf+D/DcgH/MPM+qm8bPxSe4LFC23Rf8oczUr6h0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1767744376; c=relaxed/simple; bh=L3zGK0vOWDwJ6EPx+wY8qWZHxhitG5NkRkBh/MFlPGA=; h=From:To:Cc:Subject:Date:Message-Id:MIME-Version; b=hq9HKh3p5ATmqEF7phpC9mP7aU2xQw92QpOFSFUKhI/McaA8DIz0DYUVs8ZQIbeXT+bxOK44/HN74UcGLNwrH+RL8vfZO+aRNrXJYQOtbCsdsllyPUZyJOLUTIeVSjG+y+gBeUYBmVnFluKa6gY5LvvABSHUZ/ow/1LDpPPxdnc= 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=geinxmEC; arc=none smtp.client-ip=209.85.161.67 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="geinxmEC" Received: by mail-oo1-f67.google.com with SMTP id 006d021491bc7-65d132240acso903201eaf.1 for ; Tue, 06 Jan 2026 16:06:15 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1767744374; x=1768349174; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=tgq7GZjchn1EcjfHQ/Ha9eC2PJUmykLGV5Ks1aM6jX8=; b=geinxmECRXk6QF98OZxRxy8waoIQXAxCXFQJLaXL1iKOlYqyqA58LeJswEPKAerVBz DZdy+mcm5qQjkvnx+u7rd4seoLt4TMUYuEc42NoVKl7NmVwZepn/lpjObVjtAQn9mgM4 CgVGmuSniPqOQrvomwWriVbyWVeV/28gejCIIQ2U9M3uhh1cFrvxJOrT7/4zDraGpCj8 iue8BniEuXaRkyJ2y1NZfbUdwj1t96TR0o/7Eu8Hs6hSCyuKEmO4PdLAACcPs0FQNn3q K4Urv1kq4v/E2c2Kq/JUupFzYGXYHTGk38pi8VDNoKSFBCtS5Z335YeOx6Q51CPE1zwq EDWw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1767744374; x=1768349174; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=tgq7GZjchn1EcjfHQ/Ha9eC2PJUmykLGV5Ks1aM6jX8=; b=W1ZG7pPFx4msUDPIsf3Clt3HiFs4W28625HZpevl9tYyrkUBJjp9PgQMQU+t+osscn lel+9iUMRXF+iIcHd6IvCreV96zjuB0KbIhA0kgnWYNNSInx0zNVjeXBFk/5G9fTzofx LBqYNkst+c/D1GGo7hjPq7PVs7GDJzVeoR2TCa2M4H2H5Bm7GZ9TWXSKwMJedp/pnQ5D SEvexbxrQwgBJ77S4hYNLnW/naHyqELiec/e7ffiq4pMzl3EUvhxNjp96UmljvHQzbCT PryBGNQgLqxyJE9L+CDph3D9CSPDq5zGvNRLrmsuCUJ02aGwemQ3Jcxed+hFwTKIDsvQ TzRA== X-Forwarded-Encrypted: i=1; AJvYcCUvGRynpIrJIEmcb83kz2V5hT33MQtIlNKdt8MTD3TbKv0uaNlOprl0hAsZYfZe7hBOgVlEbpqva9nnJOg=@vger.kernel.org X-Gm-Message-State: AOJu0YwbCLZCgGqD8hXGFOlgZNeG/5AUA8zAlb4ObUgvXtdpl99s5eJo VJp6vJn8HT/IZH2ituIAs/Vtynh8nQNj0fwkdM0/86uMXNqAlSZKDJs8 X-Gm-Gg: AY/fxX4xHzDkeI0mZSLxWRjVqjfofVl5imLB2nktg7uxSYt8D2VgqDmm/Mzwhm0Jsst dCXvuvIpHB9mOJA7fSIgp0y068wlldXGkRDpBsTtfjiqGq8QwX1tP9YPpq4lHLSZ46S2bJ/YO71 0YV2C8gDwEj2gV/uoedaHCMBJf5NKuqyuU0tEX/W47gLNQcKGszu10qnfSKRDUw8/trvBoBRptR AkKaNz3+wUSdjApYeJ7eGFZo0la+NMBewSRdafLSF+WHD/NHh+XsC2f/p74QAUgnPcH2+Q1oclt HpcSxwxo26D6XfCTND6inx/AdNpsaY23k+LHJDpd9+kTZ1Pok9aexR0vewm7gRYXVE6HTfftlyj O6oajjJBnsDEVzxOuCVGo/x1zLMLlz+6CcY2rCwFR7dHvPOQ7fR/FeQuz8eoCGYptr3/wpF9dhV kzX1Rrk0KH6engabTfA+x1gHUCCbq3 X-Google-Smtp-Source: AGHT+IHZk6/5mjRHyYCN1+0jYjV5yZCr12a2Qvfp3DAWPnZ9X8yCdldjy8vhbzKeSmmfI2HWux74cA== X-Received: by 2002:a05:6820:7511:b0:659:9a49:904d with SMTP id 006d021491bc7-65f54eda43bmr210960eaf.24.1767744374064; Tue, 06 Jan 2026 16:06:14 -0800 (PST) Received: from localhost.localdomain ([50.24.139.5]) by smtp.gmail.com with ESMTPSA id 586e51a60fabf-3ffbe3a6d8esm609612fac.15.2026.01.06.16.06.11 (version=TLS1_3 cipher=TLS_CHACHA20_POLY1305_SHA256 bits=256/256); Tue, 06 Jan 2026 16:06:12 -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 v1] Documentation: riscv: update Vector discovery for userspace Date: Tue, 6 Jan 2026 18:06:09 -0600 Message-Id: <20260107000609.63892-1-andybnac@gmail.com> X-Mailer: git-send-email 2.39.3 (Apple Git-145) 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 --- Documentation/arch/riscv/vector.rst | 49 +++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 10 deletions(-) diff --git a/Documentation/arch/riscv/vector.rst b/Documentation/arch/riscv= /vector.rst index 3987f5f76a9d..1fde56ffe85b 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,31 @@ 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 Vector code in the user space on hardware +that only implements zve32x subextension, or 0.7 version of the spec when +compiled with c:macro:`RISCV_ISA_V && RISCV_ISA_XTHEADVECTOR`. When the ke= rnel +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 availibilit= y to +any given process. Traditionally, :c:macro:`ELF_HWCAP` is used for such +availibility check. This remains useful for checking the availabilty for s= tandard +Vector extension, by referencing the :c:macro:`COMPAT_HWCAP_ISA_V` bit. + +However, though the kernel provides compatibility for flexible hardware +configurations, the kernel does not report the availability of subextensio= n, nor +pre-standarized Vector in :c:macro:`ELF_HWCAP` to prevent exagerating the +limited bit space. + +c:macro:`HWCAP` is designed to serve as a quick check to see if the standa= rd +Vector is both *pressence* and *available* to the process. For any non-sta= ndard +Vector extensions, the ABI guaranteed way to identify their existence is by +going through the hwprobe(2) interface. Then, the +:c:macro:`prctl(PR_RISCV_V_GET_CONTROL)` serves as the availibility +check to see if executing any Vector instructions is allowed by the runtime +environment. --=20 2.39.3 (Apple Git-145)