1.. SPDX-License-Identifier: GPL-2.0
2
3=========================================
4Vector Extension Support for RISC-V Linux
5=========================================
6
7This document briefly outlines the interface provided to userspace by Linux in
8order to support the use of the RISC-V Vector Extension.
9
101.  prctl() Interface
11---------------------
12
13Two new prctl() calls are added to allow programs to manage the enablement
14status for the use of Vector in userspace. The intended usage guideline for
15these interfaces is to give init systems a way to modify the availability of V
16for processes running under its domain. Calling thess interfaces is not
17recommended in libraries routines because libraries should not override policies
18configured from the parant process. Also, users must noted that these interfaces
19are not portable to non-Linux, nor non-RISC-V environments, so it is discourage
20to 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 the
22auxiliary 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 control
27    argument consists of two 2-bit enablement statuses and a bit for inheritance
28    mode. Other threads of the calling process are unaffected.
29
30    Enablement status is a tri-state value each occupying 2-bit of space in
31    the control argument:
32
33    * :c:macro:`PR_RISCV_V_VSTATE_CTRL_DEFAULT`: Use the system-wide default
34      enablement status on execve(). The system-wide default setting can be
35      controlled via sysctl interface (see sysctl section below).
36
37    * :c:macro:`PR_RISCV_V_VSTATE_CTRL_ON`: Allow Vector to be run for the
38      thread.
39
40    * :c:macro:`PR_RISCV_V_VSTATE_CTRL_OFF`: Disallow Vector. Executing Vector
41      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, and
44    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_INHERIT
48    represents bit[1:0], bit[3:2], and bit[4]. bit[1:0] accounts for the
49    enablement status of current thread, and the setting at bit[3:2] takes place
50    at next execve(). bit[4] defines the inheritance mode of the setting in
51    bit[3:2].
52
53        * :c:macro:`PR_RISCV_V_VSTATE_CTRL_CUR_MASK`: bit[1:0]: Account for the
54          Vector enablement status for the calling thread. The calling thread is
55          not able to turn off Vector once it has been enabled. The prctl() call
56          fails with EPERM if the value in this mask is PR_RISCV_V_VSTATE_CTRL_OFF
57          but the current enablement status is not off. Setting
58          PR_RISCV_V_VSTATE_CTRL_DEFAULT here takes no effect but to set back
59          the original enablement status.
60
61        * :c:macro:`PR_RISCV_V_VSTATE_CTRL_NEXT_MASK`: bit[3:2]: Account for the
62          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-wide
65          enablement status when execve() happen.
66
67        * :c:macro:`PR_RISCV_V_VSTATE_CTRL_INHERIT`: bit[4]: the inheritance
68          mode for the setting at PR_RISCV_V_VSTATE_CTRL_NEXT_MASK. If the bit
69          is set then the following execve() will not clear the setting in both
70          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 or
76          next mask;
77        * EPERM: Turning off Vector in PR_RISCV_V_VSTATE_CTRL_CUR_MASK if Vector
78          was enabled for the calling thread.
79
80    On success:
81        * A valid setting for PR_RISCV_V_VSTATE_CTRL_CUR_MASK takes place
82          immediately. The enablement status specified in
83          PR_RISCV_V_VSTATE_CTRL_NEXT_MASK happens at the next execve() call, or
84          all following execve() calls if PR_RISCV_V_VSTATE_CTRL_INHERIT bit is
85          set.
86        * Every successful call overwrites a previous setting for the calling
87          thread.
88
89* prctl(PR_RISCV_V_GET_CONTROL)
90
91    Gets the same Vector enablement status for the calling thread. Setting for
92    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 by
95    reading :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
96    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, a
106policy mechanism is provided to the administrators, distro maintainers, and
107developers to control the default Vector enablement status for userspace
108processes in form of sysctl knob:
109
110* /proc/sys/abi/riscv_v_default_allow
111
112    Writing the text representation of 0 or 1 to this file sets the default
113    system enablement status for new starting userspace programs. Valid values
114    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 to
122    the system default, unless:
123
124      * PR_RISCV_V_VSTATE_CTRL_INHERIT is set for the calling process, and the
125        setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
126        PR_RISCV_V_VSTATE_CTRL_DEFAULT. Or,
127
128      * The setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
129        PR_RISCV_V_VSTATE_CTRL_DEFAULT.
130
131    Modifying the system default enablement status does not affect the enablement
132    status of any existing process of thread that do not make an execve() call.
133
1343.  Vector Register State Across System Calls
135---------------------------------------------
136
137As indicated by version 1.0 of the V extension [1], vector registers are
138clobbered by system calls.
139
1401: https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc
141