141 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=========================================4Vector Extension Support for RISC-V Linux5=========================================6 7This document briefly outlines the interface provided to userspace by Linux in8order to support the use of the RISC-V Vector Extension.9 101. prctl() Interface11---------------------12 13Two new prctl() calls are added to allow programs to manage the enablement14status for the use of Vector in userspace. The intended usage guideline for15these interfaces is to give init systems a way to modify the availability of V16for processes running under its domain. Calling these interfaces is not17recommended in libraries routines because libraries should not override policies18configured from the parent process. Also, users must note that these interfaces19are not portable to non-Linux, nor non-RISC-V environments, so it is discourage20to use in a portable code. To get the availability of V in an ELF program,21please read :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the22auxiliary vector.23 24* prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)25 26 Sets the Vector enablement status of the calling thread, where the control27 argument consists of two 2-bit enablement statuses and a bit for inheritance28 mode. Other threads of the calling process are unaffected.29 30 Enablement status is a tri-state value each occupying 2-bit of space in31 the control argument:32 33 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_DEFAULT`: Use the system-wide default34 enablement status on execve(). The system-wide default setting can be35 controlled via sysctl interface (see sysctl section below).36 37 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_ON`: Allow Vector to be run for the38 thread.39 40 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_OFF`: Disallow Vector. Executing Vector41 instructions under such condition will trap and casuse the termination of the thread.42 43 arg: The control argument is a 5-bit value consisting of 3 parts, and44 accessed by 3 masks respectively.45 46 The 3 masks, PR_RISCV_V_VSTATE_CTRL_CUR_MASK,47 PR_RISCV_V_VSTATE_CTRL_NEXT_MASK, and PR_RISCV_V_VSTATE_CTRL_INHERIT48 represents bit[1:0], bit[3:2], and bit[4]. bit[1:0] accounts for the49 enablement status of current thread, and the setting at bit[3:2] takes place50 at next execve(). bit[4] defines the inheritance mode of the setting in51 bit[3:2].52 53 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_CUR_MASK`: bit[1:0]: Account for the54 Vector enablement status for the calling thread. The calling thread is55 not able to turn off Vector once it has been enabled. The prctl() call56 fails with EPERM if the value in this mask is PR_RISCV_V_VSTATE_CTRL_OFF57 but the current enablement status is not off. Setting58 PR_RISCV_V_VSTATE_CTRL_DEFAULT here takes no effect but to set back59 the original enablement status.60 61 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_NEXT_MASK`: bit[3:2]: Account for the62 Vector enablement setting for the calling thread at the next execve()63 system call. If PR_RISCV_V_VSTATE_CTRL_DEFAULT is used in this mask,64 then the enablement status will be decided by the system-wide65 enablement status when execve() happen.66 67 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_INHERIT`: bit[4]: the inheritance68 mode for the setting at PR_RISCV_V_VSTATE_CTRL_NEXT_MASK. If the bit69 is set then the following execve() will not clear the setting in both70 PR_RISCV_V_VSTATE_CTRL_NEXT_MASK and PR_RISCV_V_VSTATE_CTRL_INHERIT.71 This setting persists across changes in the system-wide default value.72 73 Return value:74 * 0 on success;75 * EINVAL: Vector not supported, invalid enablement status for current or76 next mask;77 * EPERM: Turning off Vector in PR_RISCV_V_VSTATE_CTRL_CUR_MASK if Vector78 was enabled for the calling thread.79 80 On success:81 * A valid setting for PR_RISCV_V_VSTATE_CTRL_CUR_MASK takes place82 immediately. The enablement status specified in83 PR_RISCV_V_VSTATE_CTRL_NEXT_MASK happens at the next execve() call, or84 all following execve() calls if PR_RISCV_V_VSTATE_CTRL_INHERIT bit is85 set.86 * Every successful call overwrites a previous setting for the calling87 thread.88 89* prctl(PR_RISCV_V_GET_CONTROL)90 91 Gets the same Vector enablement status for the calling thread. Setting for92 next execve() call and the inheritance bit are all OR-ed together.93 94 Note that ELF programs are able to get the availability of V for itself by95 reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the96 auxiliary vector.97 98 Return value:99 * a nonnegative value on success;100 * EINVAL: Vector not supported.101 1022. System runtime configuration (sysctl)103-----------------------------------------104 105To mitigate the ABI impact of expansion of the signal stack, a106policy mechanism is provided to the administrators, distro maintainers, and107developers to control the default Vector enablement status for userspace108processes in form of sysctl knob:109 110* /proc/sys/abi/riscv_v_default_allow111 112 Writing the text representation of 0 or 1 to this file sets the default113 system enablement status for new starting userspace programs. Valid values114 are:115 116 * 0: Do not allow Vector code to be executed as the default for new processes.117 * 1: Allow Vector code to be executed as the default for new processes.118 119 Reading this file returns the current system default enablement status.120 121 At every execve() call, a new enablement status of the new process is set to122 the system default, unless:123 124 * PR_RISCV_V_VSTATE_CTRL_INHERIT is set for the calling process, and the125 setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not126 PR_RISCV_V_VSTATE_CTRL_DEFAULT. Or,127 128 * The setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not129 PR_RISCV_V_VSTATE_CTRL_DEFAULT.130 131 Modifying the system default enablement status does not affect the enablement132 status of any existing process of thread that do not make an execve() call.133 1343. Vector Register State Across System Calls135---------------------------------------------136 137As indicated by version 1.0 of the V extension [1], vector registers are138clobbered by system calls.139 1401: https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc141