← Documents Documentation/arch/riscv/vector.rst GitHub 원문 ↗

Linux 6.18.37 · Architecture

Vector Extension Support for RISC-V Linux

Thread별 Vector enablement prctl, execve inheritance, system default sysctl과 register ABI입니다.

Source pathDocumentation/arch/riscv/vector.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

vector.rst:1-140

5-bit `PR_RISCV_V_SET_CONTROL`은 current, next-exec, inheritance state를 분리합니다. `/proc/sys/abi/riscv_v_default_allow`는 새 process default만 바꾸며 system call은 vector register를 clobber합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
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 provided to userspace by Linux in
8 order to support the use of the RISC-V Vector Extension.
9
10 1. prctl() Interface
11 ---------------------
12
13 Two new prctl() calls are added to allow programs to manage the enablement
14 status for the use of Vector in userspace. The intended usage guideline for
15 these interfaces is to give init systems a way to modify the availability of V
16 for processes running under its domain. Calling these interfaces is not
17 recommended in libraries routines because libraries should not override policies
18 configured from the parent process. Also, users must note that these interfaces
19 are not portable to non-Linux, nor non-RISC-V environments, so it is discourage
20 to use in a portable code. To get the availability of V in an ELF program,
21 please read :c:macro:`COMPAT_HWCAP_ISA_V` bit of :c:macro:`ELF_HWCAP` in the
22 auxiliary 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
102 2. System runtime configuration (sysctl)
103 -----------------------------------------
104
105 To mitigate the ABI impact of expansion of the signal stack, a
106 policy mechanism is provided to the administrators, distro maintainers, and
107 developers to control the default Vector enablement status for userspace
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 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
134 3. Vector Register State Across System Calls
135 ---------------------------------------------
136
137 As indicated by version 1.0 of the V extension [1], vector registers are
138 clobbered by system calls.
139
140 1: https://github.com/riscv/riscv-v-spec/blob/master/calling-convention.adoc
141

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

RISC-V Vector userspace support

1-9

이 문서는 RISC-V Vector Extension을 userspace에서 사용하도록 Linux가 제공하는 interface를 간략히 설명합니다.

prctl() interface의 용도

10-23

두 `prctl()` call은 userspace Vector 사용의 enablement status를 관리합니다. Init system이 자신의 domain 아래 process에 V availability policy를 설정하는 용도입니다.

Library가 parent process의 policy를 덮어쓰면 안 되므로 library routine에서 호출하는 것은 권장하지 않습니다. Linux/RISC-V 전용이어서 portable code에도 권장하지 않습니다.

ELF program은 auxiliary vector의 `ELF_HWCAP`에서 `COMPAT_HWCAP_ISA_V` bit를 읽어 V availability를 확인할 수 있습니다.

PR_RISCV_V_SET_CONTROL

24-42

`prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)`는 calling thread의 Vector enablement status를 설정하며 같은 process의 다른 thread에는 영향을 주지 않습니다. Control argument에는 2-bit status 두 개와 inheritance bit 하나가 있습니다.

Status macro의미
`PR_RISCV_V_VSTATE_CTRL_DEFAULT``execve()` 때 system-wide default 사용
`PR_RISCV_V_VSTATE_CTRL_ON`Thread의 Vector 실행 허용
`PR_RISCV_V_VSTATE_CTRL_OFF`Vector 실행 금지. 실행하면 trap과 thread termination

5-bit control argument

43-72

`arg`는 세 mask로 접근하는 5-bit 값입니다. `PR_RISCV_V_VSTATE_CTRL_CUR_MASK`는 bit[1:0], `PR_RISCV_V_VSTATE_CTRL_NEXT_MASK`는 bit[3:2], `PR_RISCV_V_VSTATE_CTRL_INHERIT`는 bit[4]입니다.

MaskBits동작
`PR_RISCV_V_VSTATE_CTRL_CUR_MASK`[1:0]Calling thread의 현재 status. 한번 enable된 Vector는 끌 수 없으며 OFF 요청은 EPERM. DEFAULT는 원래 status로 복원
`PR_RISCV_V_VSTATE_CTRL_NEXT_MASK`[3:2]다음 `execve()`의 status. DEFAULT면 당시 system-wide status 사용
`PR_RISCV_V_VSTATE_CTRL_INHERIT`[4]NEXT와 INHERIT를 이후 `execve()`에서도 유지하며 system-wide default 변경에도 지속
Vector enablement control lifecycle
CUR_MASKCalling thread에 즉시 적용
NEXT_MASK다음 `execve()`에 적용
INHERIT이후 모든 `execve()`에 NEXT 유지

현재 thread 설정과 다음 `execve()` 설정의 적용 시점입니다.

SET_CONTROL return과 성공 효과

73-88
Result조건
0성공
EINVALVector 미지원 또는 current/next mask의 invalid status
EPERMCalling thread에서 이미 enable된 Vector를 CUR_MASK로 끄려 함

성공하면 유효한 CUR_MASK setting은 즉시 적용되고 NEXT_MASK는 다음 `execve()`에 적용됩니다. INHERIT가 설정되면 이후 모든 `execve()`에도 적용됩니다. 성공한 call은 calling thread의 이전 setting을 덮어씁니다.

PR_RISCV_V_GET_CONTROL

89-101

`prctl(PR_RISCV_V_GET_CONTROL)`은 calling thread의 같은 Vector enablement status를 가져오며 next-exec setting과 inheritance bit를 OR한 값을 반환합니다. ELF program은 `ELF_HWCAP`의 `COMPAT_HWCAP_ISA_V`로 자체 V availability를 확인할 수도 있습니다.

Result의미
Nonnegative value성공한 control value
EINVALVector 미지원

System runtime configuration

102-133

Signal stack 확장이 ABI에 미치는 영향을 줄이기 위해 administrator, distribution maintainer, developer가 userspace process의 default Vector status를 제어하는 sysctl을 제공합니다.

Path는 `/proc/sys/abi/riscv_v_default_allow`입니다.

Value새 process의 default
0Vector code 실행을 허용하지 않음
1Vector code 실행을 허용

File을 읽으면 현재 system default status를 반환합니다. 각 `execve()`에서 새 process status는 system default가 되지만, NEXT_MASK가 DEFAULT가 아니거나 INHERIT와 non-default NEXT_MASK가 설정돼 있으면 해당 setting을 사용합니다.

System default를 바꿔도 `execve()`를 호출하지 않는 기존 process나 thread의 enablement status에는 영향을 주지 않습니다.

System call 이후 vector register state

134-140

V extension version 1.0의 calling convention에 따라 vector register는 system call 뒤 `clobbered` 상태가 됩니다.