Debian Codegraph @

upstream/debian-unstable/man2/PR_SVE_SET_VL.2const

raw
1 .\" Copyright 2020, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH PR_SVE_SET_VL 2const 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 PR_SVE_SET_VL
9 \-
10 set the thread's SVE vector length
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */"
17 .B #include <sys/prctl.h>
18 .P
19 .BI "int prctl(PR_SVE_SET_VL, unsigned long " val );
20 .fi
21 .SH DESCRIPTION
22 Configure the thread's SVE vector length,
23 as specified by
24 .IR val .
25 .P
26 The bits of
27 .I val
28 corresponding to
29 .B PR_SVE_VL_LEN_MASK
30 must be set to the desired vector length in bytes.
31 This is interpreted as an upper bound:
32 the kernel will select the greatest available vector length
33 that does not exceed the value specified.
34 In particular, specifying
35 .B SVE_VL_MAX
36 (defined in
37 .I <asm/sigcontext.h>)
38 for the
39 .B PR_SVE_VL_LEN_MASK
40 bits requests the maximum supported vector length.
41 .P
42 In addition, the other bits of
43 .I val
44 must be set to one of the following combinations of flags:
45 .TP
46 .B 0L
47 Perform the change immediately.
48 At the next
49 .BR execve (2)
50 in the thread,
51 the vector length will be reset to the value configured in
52 .IR /proc/\:sys/\:abi/\:sve_default_vector_length .
53 .TP
54 .B PR_SVE_VL_INHERIT
55 Perform the change immediately.
56 Subsequent
57 .BR execve (2)
58 calls will preserve the new vector length.
59 .TP
60 .B PR_SVE_SET_VL_ONEXEC
61 Defer the change, so that it is performed at the next
62 .BR execve (2)
63 in the thread.
64 Further
65 .BR execve (2)
66 calls will reset the vector length to the value configured in
67 .IR /proc/\:sys/\:abi/\:sve_default_vector_length .
68 .TP
69 .B PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT
70 Defer the change, so that it is performed at the next
71 .BR execve (2)
72 in the thread.
73 Further
74 .BR execve (2)
75 calls will preserve the new vector length.
76 .P
77 In all cases,
78 any previously pending deferred change is canceled.
79 .P
80 On success,
81 a nonnegative value is returned that describes the
82 .I selected
83 configuration.
84 If
85 .B PR_SVE_SET_VL_ONEXEC
86 was included in
87 .IR val ,
88 then the configuration described by the return value
89 will take effect at the next
90 .BR execve (2).
91 Otherwise, the configuration is already in effect when the
92 .B PR_SVE_SET_VL
93 call returns.
94 In either case, the value is encoded in the same way as the return value of
95 .BR PR_SVE_GET_VL .
96 Note that there is no explicit flag in the return value
97 corresponding to
98 .BR PR_SVE_SET_VL_ONEXEC .
99 .P
100 The configuration (including any pending deferred change)
101 is inherited across
102 .BR fork (2)
103 and
104 .BR clone (2).
105 .SH RETURN VALUE
106 On success,
107 .B PR_SVE_SET_VL
108 returns the nonnegative value described above.
109 On error, \-1 is returned, and
110 .I errno
111 is set to indicate the error.
112 .SH ERRORS
113 .TP
114 .B EINVAL
115 SVE is not available on this platform.
116 .TP
117 .B EINVAL
118 The value in the bits of
119 .I val
120 corresponding to
121 .B PR_SVE_VL_LEN_MASK
122 is outside the range
123 .RB [ SVE_VL_MIN ,
124 .BR SVE_VL_MAX ]
125 or is not a multiple of 16.
126 .TP
127 .B EINVAL
128 The other bits of
129 .I val
130 are invalid or unsupported.
131 .SH FILES
132 .TP
133 .I /proc/\:sys/\:abi/\:sve_default_vector_length
134 .SH STANDARDS
135 Linux.
136 arm64 only.
137 .SH HISTORY
138 .\" commit 2d2123bc7c7f843aa9db87720de159a049839862
139 .\" linux-5.6/Documentation/arm64/sve.rst
140 Linux 4.15 (arm64).
141 .SH CAVEATS
142 Because the compiler or run-time environment
143 may be using SVE, using this call without the
144 .B PR_SVE_SET_VL_ONEXEC
145 flag may crash the calling process.
146 The conditions for using it safely are complex and system-dependent.
147 Don't use it unless you really know what you are doing.
148 .SH SEE ALSO
149 .BR prctl (2),
150 .BR PR_SVE_GET_VL (2const)
151 .P
152 For more information, see the kernel source file
153 .IR Documentation/arch/arm64/sve.rst .