Debian Codegraph @

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

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