104a4722eSAndy Chiu.. SPDX-License-Identifier: GPL-2.0 204a4722eSAndy Chiu 304a4722eSAndy Chiu========================================= 404a4722eSAndy ChiuVector Extension Support for RISC-V Linux 504a4722eSAndy Chiu========================================= 604a4722eSAndy Chiu 704a4722eSAndy ChiuThis document briefly outlines the interface provided to userspace by Linux in 804a4722eSAndy Chiuorder to support the use of the RISC-V Vector Extension. 904a4722eSAndy Chiu 1004a4722eSAndy Chiu1. prctl() Interface 1104a4722eSAndy Chiu--------------------- 1204a4722eSAndy Chiu 1304a4722eSAndy ChiuTwo new prctl() calls are added to allow programs to manage the enablement 1404a4722eSAndy Chiustatus for the use of Vector in userspace. The intended usage guideline for 1504a4722eSAndy Chiuthese interfaces is to give init systems a way to modify the availability of V 16*d56b699dSBjorn Helgaasfor processes running under its domain. Calling these interfaces is not 1704a4722eSAndy Chiurecommended in libraries routines because libraries should not override policies 1804a4722eSAndy Chiuconfigured from the parant process. Also, users must noted that these interfaces 1904a4722eSAndy Chiuare not portable to non-Linux, nor non-RISC-V environments, so it is discourage 2004a4722eSAndy Chiuto use in a portable code. To get the availability of V in an ELF program, 2104a4722eSAndy Chiuplease read :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the 2204a4722eSAndy Chiuauxiliary vector. 2304a4722eSAndy Chiu 2404a4722eSAndy Chiu* prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg) 2504a4722eSAndy Chiu 2604a4722eSAndy Chiu Sets the Vector enablement status of the calling thread, where the control 2704a4722eSAndy Chiu argument consists of two 2-bit enablement statuses and a bit for inheritance 2804a4722eSAndy Chiu mode. Other threads of the calling process are unaffected. 2904a4722eSAndy Chiu 3004a4722eSAndy Chiu Enablement status is a tri-state value each occupying 2-bit of space in 3104a4722eSAndy Chiu the control argument: 3204a4722eSAndy Chiu 3304a4722eSAndy Chiu * :c:macro:`PR_RISCV_V_VSTATE_CTRL_DEFAULT`: Use the system-wide default 3404a4722eSAndy Chiu enablement status on execve(). The system-wide default setting can be 3504a4722eSAndy Chiu controlled via sysctl interface (see sysctl section below). 3604a4722eSAndy Chiu 3704a4722eSAndy Chiu * :c:macro:`PR_RISCV_V_VSTATE_CTRL_ON`: Allow Vector to be run for the 3804a4722eSAndy Chiu thread. 3904a4722eSAndy Chiu 4004a4722eSAndy Chiu * :c:macro:`PR_RISCV_V_VSTATE_CTRL_OFF`: Disallow Vector. Executing Vector 4104a4722eSAndy Chiu instructions under such condition will trap and casuse the termination of the thread. 4204a4722eSAndy Chiu 4304a4722eSAndy Chiu arg: The control argument is a 5-bit value consisting of 3 parts, and 4404a4722eSAndy Chiu accessed by 3 masks respectively. 4504a4722eSAndy Chiu 4604a4722eSAndy Chiu The 3 masks, PR_RISCV_V_VSTATE_CTRL_CUR_MASK, 4704a4722eSAndy Chiu PR_RISCV_V_VSTATE_CTRL_NEXT_MASK, and PR_RISCV_V_VSTATE_CTRL_INHERIT 4804a4722eSAndy Chiu represents bit[1:0], bit[3:2], and bit[4]. bit[1:0] accounts for the 4904a4722eSAndy Chiu enablement status of current thread, and the setting at bit[3:2] takes place 5004a4722eSAndy Chiu at next execve(). bit[4] defines the inheritance mode of the setting in 5104a4722eSAndy Chiu bit[3:2]. 5204a4722eSAndy Chiu 5304a4722eSAndy Chiu * :c:macro:`PR_RISCV_V_VSTATE_CTRL_CUR_MASK`: bit[1:0]: Account for the 5404a4722eSAndy Chiu Vector enablement status for the calling thread. The calling thread is 5504a4722eSAndy Chiu not able to turn off Vector once it has been enabled. The prctl() call 5604a4722eSAndy Chiu fails with EPERM if the value in this mask is PR_RISCV_V_VSTATE_CTRL_OFF 5704a4722eSAndy Chiu but the current enablement status is not off. Setting 5804a4722eSAndy Chiu PR_RISCV_V_VSTATE_CTRL_DEFAULT here takes no effect but to set back 5904a4722eSAndy Chiu the original enablement status. 6004a4722eSAndy Chiu 6104a4722eSAndy Chiu * :c:macro:`PR_RISCV_V_VSTATE_CTRL_NEXT_MASK`: bit[3:2]: Account for the 6204a4722eSAndy Chiu Vector enablement setting for the calling thread at the next execve() 6304a4722eSAndy Chiu system call. If PR_RISCV_V_VSTATE_CTRL_DEFAULT is used in this mask, 6404a4722eSAndy Chiu then the enablement status will be decided by the system-wide 6504a4722eSAndy Chiu enablement status when execve() happen. 6604a4722eSAndy Chiu 6704a4722eSAndy Chiu * :c:macro:`PR_RISCV_V_VSTATE_CTRL_INHERIT`: bit[4]: the inheritance 6804a4722eSAndy Chiu mode for the setting at PR_RISCV_V_VSTATE_CTRL_NEXT_MASK. If the bit 6904a4722eSAndy Chiu is set then the following execve() will not clear the setting in both 7004a4722eSAndy Chiu PR_RISCV_V_VSTATE_CTRL_NEXT_MASK and PR_RISCV_V_VSTATE_CTRL_INHERIT. 7104a4722eSAndy Chiu This setting persists across changes in the system-wide default value. 7204a4722eSAndy Chiu 7304a4722eSAndy Chiu Return value: 7404a4722eSAndy Chiu * 0 on success; 7504a4722eSAndy Chiu * EINVAL: Vector not supported, invalid enablement status for current or 7604a4722eSAndy Chiu next mask; 7704a4722eSAndy Chiu * EPERM: Turning off Vector in PR_RISCV_V_VSTATE_CTRL_CUR_MASK if Vector 7804a4722eSAndy Chiu was enabled for the calling thread. 7904a4722eSAndy Chiu 8004a4722eSAndy Chiu On success: 8104a4722eSAndy Chiu * A valid setting for PR_RISCV_V_VSTATE_CTRL_CUR_MASK takes place 8204a4722eSAndy Chiu immediately. The enablement status specified in 8304a4722eSAndy Chiu PR_RISCV_V_VSTATE_CTRL_NEXT_MASK happens at the next execve() call, or 8404a4722eSAndy Chiu all following execve() calls if PR_RISCV_V_VSTATE_CTRL_INHERIT bit is 8504a4722eSAndy Chiu set. 8604a4722eSAndy Chiu * Every successful call overwrites a previous setting for the calling 8704a4722eSAndy Chiu thread. 8804a4722eSAndy Chiu 8904a4722eSAndy Chiu* prctl(PR_RISCV_V_GET_CONTROL) 9004a4722eSAndy Chiu 9104a4722eSAndy Chiu Gets the same Vector enablement status for the calling thread. Setting for 9204a4722eSAndy Chiu next execve() call and the inheritance bit are all OR-ed together. 9304a4722eSAndy Chiu 9404a4722eSAndy Chiu Note that ELF programs are able to get the availability of V for itself by 9504a4722eSAndy Chiu reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the 9604a4722eSAndy Chiu auxiliary vector. 9704a4722eSAndy Chiu 9804a4722eSAndy Chiu Return value: 9904a4722eSAndy Chiu * a nonnegative value on success; 10004a4722eSAndy Chiu * EINVAL: Vector not supported. 10104a4722eSAndy Chiu 10204a4722eSAndy Chiu2. System runtime configuration (sysctl) 10304a4722eSAndy Chiu----------------------------------------- 10404a4722eSAndy Chiu 10504a4722eSAndy ChiuTo mitigate the ABI impact of expansion of the signal stack, a 10604a4722eSAndy Chiupolicy mechanism is provided to the administrators, distro maintainers, and 10704a4722eSAndy Chiudevelopers to control the default Vector enablement status for userspace 10804a4722eSAndy Chiuprocesses in form of sysctl knob: 10904a4722eSAndy Chiu 11004a4722eSAndy Chiu* /proc/sys/abi/riscv_v_default_allow 11104a4722eSAndy Chiu 11204a4722eSAndy Chiu Writing the text representation of 0 or 1 to this file sets the default 11304a4722eSAndy Chiu system enablement status for new starting userspace programs. Valid values 11404a4722eSAndy Chiu are: 11504a4722eSAndy Chiu 11604a4722eSAndy Chiu * 0: Do not allow Vector code to be executed as the default for new processes. 11704a4722eSAndy Chiu * 1: Allow Vector code to be executed as the default for new processes. 11804a4722eSAndy Chiu 11904a4722eSAndy Chiu Reading this file returns the current system default enablement status. 12004a4722eSAndy Chiu 12104a4722eSAndy Chiu At every execve() call, a new enablement status of the new process is set to 12204a4722eSAndy Chiu the system default, unless: 12304a4722eSAndy Chiu 12404a4722eSAndy Chiu * PR_RISCV_V_VSTATE_CTRL_INHERIT is set for the calling process, and the 12504a4722eSAndy Chiu setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not 12604a4722eSAndy Chiu PR_RISCV_V_VSTATE_CTRL_DEFAULT. Or, 12704a4722eSAndy Chiu 12804a4722eSAndy Chiu * The setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not 12904a4722eSAndy Chiu PR_RISCV_V_VSTATE_CTRL_DEFAULT. 13004a4722eSAndy Chiu 13104a4722eSAndy Chiu Modifying the system default enablement status does not affect the enablement 13204a4722eSAndy Chiu status of any existing process of thread that do not make an execve() call. 133bcc87900SPalmer Dabbelt 134bcc87900SPalmer Dabbelt3. Vector Register State Across System Calls 135bcc87900SPalmer Dabbelt--------------------------------------------- 136bcc87900SPalmer Dabbelt 137bcc87900SPalmer DabbeltAs indicated by version 1.0 of the V extension [1], vector registers are 138bcc87900SPalmer Dabbeltclobbered by system calls. 139bcc87900SPalmer Dabbelt 140bcc87900SPalmer Dabbelt1: https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc 141