1 .. SPDX-License-Identifier: GPL-2.0
2
3 =========================================
4 Vector Extension Support for RISC-V Linux
5 =========================================
6
7 This document briefly outlines the interface p
8 order to support the use of the RISC-V Vector
9
10 1. prctl() Interface
11 ---------------------
12
13 Two new prctl() calls are added to allow progr
14 status for the use of Vector in userspace. The
15 these interfaces is to give init systems a way
16 for processes running under its domain. Callin
17 recommended in libraries routines because libr
18 configured from the parent process. Also, user
19 are not portable to non-Linux, nor non-RISC-V
20 to use in a portable code. To get the availabi
21 please read :c:macro:`COMPAT_HWCAP_ISA_V` bit
22 auxiliary vector.
23
24 * prctl(PR_RISCV_V_SET_CONTROL, unsigned long
25
26 Sets the Vector enablement status of the c
27 argument consists of two 2-bit enablement
28 mode. Other threads of the calling process
29
30 Enablement status is a tri-state value eac
31 the control argument:
32
33 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_DEFAULT
34 enablement status on execve(). The syste
35 controlled via sysctl interface (see sys
36
37 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_ON`: Al
38 thread.
39
40 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_OFF`: D
41 instructions under such condition will t
42
43 arg: The control argument is a 5-bit value
44 accessed by 3 masks respectively.
45
46 The 3 masks, PR_RISCV_V_VSTATE_CTRL_CUR_MA
47 PR_RISCV_V_VSTATE_CTRL_NEXT_MASK, and PR_R
48 represents bit[1:0], bit[3:2], and bit[4].
49 enablement status of current thread, and t
50 at next execve(). bit[4] defines the inher
51 bit[3:2].
52
53 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_CUR
54 Vector enablement status for the cal
55 not able to turn off Vector once it
56 fails with EPERM if the value in thi
57 but the current enablement status is
58 PR_RISCV_V_VSTATE_CTRL_DEFAULT here
59 the original enablement status.
60
61 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_NEX
62 Vector enablement setting for the ca
63 system call. If PR_RISCV_V_VSTATE_CT
64 then the enablement status will be d
65 enablement status when execve() happ
66
67 * :c:macro:`PR_RISCV_V_VSTATE_CTRL_INH
68 mode for the setting at PR_RISCV_V_V
69 is set then the following execve() w
70 PR_RISCV_V_VSTATE_CTRL_NEXT_MASK and
71 This setting persists across changes
72
73 Return value:
74 * 0 on success;
75 * EINVAL: Vector not supported, invali
76 next mask;
77 * EPERM: Turning off Vector in PR_RISC
78 was enabled for the calling thread.
79
80 On success:
81 * A valid setting for PR_RISCV_V_VSTAT
82 immediately. The enablement status s
83 PR_RISCV_V_VSTATE_CTRL_NEXT_MASK hap
84 all following execve() calls if PR_R
85 set.
86 * Every successful call overwrites a p
87 thread.
88
89 * prctl(PR_RISCV_V_GET_CONTROL)
90
91 Gets the same Vector enablement status for
92 next execve() call and the inheritance bit
93
94 Note that ELF programs are able to get the
95 reading :c:macro:`COMPAT_HWCAP_ISA_V` bit
96 auxiliary vector.
97
98 Return value:
99 * a nonnegative value on success;
100 * EINVAL: Vector not supported.
101
102 2. System runtime configuration (sysctl)
103 -----------------------------------------
104
105 To mitigate the ABI impact of expansion of the
106 policy mechanism is provided to the administra
107 developers to control the default Vector enabl
108 processes in form of sysctl knob:
109
110 * /proc/sys/abi/riscv_v_default_allow
111
112 Writing the text representation of 0 or 1
113 system enablement status for new starting
114 are:
115
116 * 0: Do not allow Vector code to be execut
117 * 1: Allow Vector code to be executed as t
118
119 Reading this file returns the current syst
120
121 At every execve() call, a new enablement s
122 the system default, unless:
123
124 * PR_RISCV_V_VSTATE_CTRL_INHERIT is set
125 setting in PR_RISCV_V_VSTATE_CTRL_NEXT
126 PR_RISCV_V_VSTATE_CTRL_DEFAULT. Or,
127
128 * The setting in PR_RISCV_V_VSTATE_CTRL_
129 PR_RISCV_V_VSTATE_CTRL_DEFAULT.
130
131 Modifying the system default enablement st
132 status of any existing process of thread t
133
134 3. Vector Register State Across System Calls
135 ---------------------------------------------
136
137 As indicated by version 1.0 of the V extension
138 clobbered by system calls.
139
140 1: https://github.com/riscv/riscv-v-spec/blob/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.