1 Scalable Vector Extension support for AArch64 Linux
2 ===================================================
4 Author: Dave Martin <Dave.Martin@arm.com>
7 This document outlines briefly the interface provided to userspace by Linux in
8 order to support use of the ARM Scalable Vector Extension (SVE).
10 This is an outline of the most important features and issues only and not
11 intended to be exhaustive.
13 This document does not aim to describe the SVE architecture or programmer's
14 model. To aid understanding, a minimal description of relevant programmer's
15 model features for SVE is included in Appendix A.
21 * SVE registers Z0..Z31, P0..P15 and FFR and the current vector length VL, are
24 * The presence of SVE is reported to userspace via HWCAP_SVE in the aux vector
25 AT_HWCAP entry. Presence of this flag implies the presence of the SVE
26 instructions and registers, and the Linux-specific system interfaces
27 described in this document. SVE is reported in /proc/cpuinfo as "sve".
29 * Support for the execution of SVE instructions in userspace can also be
30 detected by reading the CPU ID register ID_AA64PFR0_EL1 using an MRS
31 instruction, and checking that the value of the SVE field is nonzero. [3]
33 It does not guarantee the presence of the system interfaces described in the
34 following sections: software that needs to verify that those interfaces are
35 present must check for HWCAP_SVE instead.
37 * On hardware that supports the SVE2 extensions, HWCAP2_SVE2 will also
38 be reported in the AT_HWCAP2 aux vector entry. In addition to this,
39 optional extensions to SVE2 may be reported by the presence of:
48 This list may be extended over time as the SVE architecture evolves.
50 These extensions are also reported via the CPU ID register ID_AA64ZFR0_EL1,
51 which userspace can read using an MRS instruction. See elf_hwcaps.txt and
52 cpu-feature-registers.txt for details.
54 * Debuggers should restrict themselves to interacting with the target via the
55 NT_ARM_SVE regset. The recommended way of detecting support for this regset
56 is to connect to a target process first and then attempt a
57 ptrace(PTRACE_GETREGSET, pid, NT_ARM_SVE, &iov).
60 2. Vector length terminology
61 -----------------------------
63 The size of an SVE vector (Z) register is referred to as the "vector length".
65 To avoid confusion about the units used to express vector length, the kernel
66 adopts the following conventions:
68 * Vector length (VL) = size of a Z-register in bytes
70 * Vector quadwords (VQ) = size of a Z-register in units of 128 bits
74 The VQ convention is used where the underlying granularity is important, such
75 as in data structure definitions. In most other situations, the VL convention
76 is used. This is consistent with the meaning of the "VL" pseudo-register in
77 the SVE instruction set architecture.
80 3. System call behaviour
81 -------------------------
83 * On syscall, V0..V31 are preserved (as without SVE). Thus, bits [127:0] of
84 Z0..Z31 are preserved. All other bits of Z0..Z31, and all of P0..P15 and FFR
85 become unspecified on return from a syscall.
87 * The SVE registers are not used to pass arguments to or receive results from
90 * In practice the affected registers/bits will be preserved or will be replaced
91 with zeros on return from a syscall, but userspace should not make
92 assumptions about this. The kernel behaviour may vary on a case-by-case
95 * All other SVE state of a thread, including the currently configured vector
96 length, the state of the PR_SVE_VL_INHERIT flag, and the deferred vector
97 length (if any), is preserved across all syscalls, subject to the specific
98 exceptions for execve() described in section 6.
100 In particular, on return from a fork() or clone(), the parent and new child
101 process or thread share identical SVE configuration, matching that of the
102 parent before the call.
108 * A new signal frame record sve_context encodes the SVE registers on signal
111 * This record is supplementary to fpsimd_context. The FPSR and FPCR registers
112 are only present in fpsimd_context. For convenience, the content of V0..V31
113 is duplicated between sve_context and fpsimd_context.
115 * The signal frame record for SVE always contains basic metadata, in particular
116 the thread's vector length (in sve_context.vl).
118 * The SVE registers may or may not be included in the record, depending on
119 whether the registers are live for the thread. The registers are present if
121 sve_context.head.size >= SVE_SIG_CONTEXT_SIZE(sve_vq_from_vl(sve_context.vl)).
123 * If the registers are present, the remainder of the record has a vl-dependent
124 size and layout. Macros SVE_SIG_* are defined [1] to facilitate access to
127 * If the SVE context is too big to fit in sigcontext.__reserved[], then extra
128 space is allocated on the stack, an extra_context record is written in
129 __reserved[] referencing this space. sve_context is then written in the
130 extra space. Refer to [1] for further details about this mechanism.
136 When returning from a signal handler:
138 * If there is no sve_context record in the signal frame, or if the record is
139 present but contains no register data as desribed in the previous section,
140 then the SVE registers/bits become non-live and take unspecified values.
142 * If sve_context is present in the signal frame and contains full register
143 data, the SVE registers become live and are populated with the specified
144 data. However, for backward compatibility reasons, bits [127:0] of Z0..Z31
145 are always restored from the corresponding members of fpsimd_context.vregs[]
146 and not from sve_context. The remaining bits are restored from sve_context.
148 * Inclusion of fpsimd_context in the signal frame remains mandatory,
149 irrespective of whether sve_context is present or not.
151 * The vector length cannot be changed via signal return. If sve_context.vl in
152 the signal frame does not match the current vector length, the signal return
153 attempt is treated as illegal, resulting in a forced SIGSEGV.
159 Some new prctl() calls are added to allow programs to manage the SVE vector
162 prctl(PR_SVE_SET_VL, unsigned long arg)
164 Sets the vector length of the calling thread and related flags, where
165 arg == vl | flags. Other threads of the calling process are unaffected.
167 vl is the desired vector length, where sve_vl_valid(vl) must be true.
171 PR_SVE_SET_VL_INHERIT
173 Inherit the current vector length across execve(). Otherwise, the
174 vector length is reset to the system default at execve(). (See
179 Defer the requested vector length change until the next execve()
180 performed by this thread.
182 The effect is equivalent to implicit exceution of the following
183 call immediately after the next execve() (if any) by the thread:
185 prctl(PR_SVE_SET_VL, arg & ~PR_SVE_SET_VL_ONEXEC)
187 This allows launching of a new program with a different vector
188 length, while avoiding runtime side effects in the caller.
191 Without PR_SVE_SET_VL_ONEXEC, the requested change takes effect
195 Return value: a nonnegative on success, or a negative value on error:
196 EINVAL: SVE not supported, invalid vector length requested, or
202 * Either the calling thread's vector length or the deferred vector length
203 to be applied at the next execve() by the thread (dependent on whether
204 PR_SVE_SET_VL_ONEXEC is present in arg), is set to the largest value
205 supported by the system that is less than or equal to vl. If vl ==
206 SVE_VL_MAX, the value set will be the largest value supported by the
209 * Any previously outstanding deferred vector length change in the calling
212 * The returned value describes the resulting configuration, encoded as for
213 PR_SVE_GET_VL. The vector length reported in this value is the new
214 current vector length for this thread if PR_SVE_SET_VL_ONEXEC was not
215 present in arg; otherwise, the reported vector length is the deferred
216 vector length that will be applied at the next execve() by the calling
219 * Changing the vector length causes all of P0..P15, FFR and all bits of
220 Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become
221 unspecified. Calling PR_SVE_SET_VL with vl equal to the thread's current
222 vector length, or calling PR_SVE_SET_VL with the PR_SVE_SET_VL_ONEXEC
223 flag, does not constitute a change to the vector length for this purpose.
228 Gets the vector length of the calling thread.
230 The following flag may be OR-ed into the result:
232 PR_SVE_SET_VL_INHERIT
234 Vector length will be inherited across execve().
236 There is no way to determine whether there is an outstanding deferred
237 vector length change (which would only normally be the case between a
238 fork() or vfork() and the corresponding execve() in typical use).
240 To extract the vector length from the result, and it with
243 Return value: a nonnegative value on success, or a negative value on error:
244 EINVAL: SVE not supported.
248 ---------------------
250 * A new regset NT_ARM_SVE is defined for use with PTRACE_GETREGSET and
253 Refer to [2] for definitions.
255 The regset data starts with struct user_sve_header, containing:
259 Size of the complete regset, in bytes.
260 This depends on vl and possibly on other things in the future.
262 If a call to PTRACE_GETREGSET requests less data than the value of
263 size, the caller can allocate a larger buffer and retry in order to
264 read the complete regset.
268 Maximum size in bytes that the regset can grow to for the target
269 thread. The regset won't grow bigger than this even if the target
270 thread changes its vector length etc.
274 Target thread's current vector length, in bytes.
278 Maximum possible vector length for the target thread.
286 SVE registers are not live (GETREGSET) or are to be made
287 non-live (SETREGSET).
289 The payload is of type struct user_fpsimd_state, with the same
290 meaning as for NT_PRFPREG, starting at offset
291 SVE_PT_FPSIMD_OFFSET from the start of user_sve_header.
293 Extra data might be appended in the future: the size of the
294 payload should be obtained using SVE_PT_FPSIMD_SIZE(vq, flags).
296 vq should be obtained using sve_vq_from_vl(vl).
302 SVE registers are live (GETREGSET) or are to be made live
305 The payload contains the SVE register data, starting at offset
306 SVE_PT_SVE_OFFSET from the start of user_sve_header, and with
307 size SVE_PT_SVE_SIZE(vq, flags);
309 ... OR-ed with zero or more of the following flags, which have the same
310 meaning and behaviour as the corresponding PR_SET_VL_* flags:
314 SVE_PT_VL_ONEXEC (SETREGSET only).
316 * The effects of changing the vector length and/or flags are equivalent to
317 those documented for PR_SVE_SET_VL.
319 The caller must make a further GETREGSET call if it needs to know what VL is
320 actually set by SETREGSET, unless is it known in advance that the requested
323 * In the SVE_PT_REGS_SVE case, the size and layout of the payload depends on
324 the header fields. The SVE_PT_SVE_*() macros are provided to facilitate
325 access to the members.
327 * In either case, for SETREGSET it is permissible to omit the payload, in which
328 case only the vector length and flags are changed (along with any
329 consequences of those changes).
331 * For SETREGSET, if an SVE_PT_REGS_SVE payload is present and the
332 requested VL is not supported, the effect will be the same as if the
333 payload were omitted, except that an EIO error is reported. No
334 attempt is made to translate the payload data to the correct layout
335 for the vector length actually set. The thread's FPSIMD state is
336 preserved, but the remaining bits of the SVE registers become
337 unspecified. It is up to the caller to translate the payload layout
338 for the actual VL and retry.
340 * The effect of writing a partial, incomplete payload is unspecified.
343 8. ELF coredump extensions
344 ---------------------------
346 * A NT_ARM_SVE note will be added to each coredump for each thread of the
347 dumped process. The contents will be equivalent to the data that would have
348 been read if a PTRACE_GETREGSET of NT_ARM_SVE were executed for each thread
349 when the coredump was generated.
352 9. System runtime configuration
353 --------------------------------
355 * To mitigate the ABI impact of expansion of the signal frame, a policy
356 mechanism is provided for administrators, distro maintainers and developers
357 to set the default vector length for userspace processes:
359 /proc/sys/abi/sve_default_vector_length
361 Writing the text representation of an integer to this file sets the system
362 default vector length to the specified value, unless the value is greater
363 than the maximum vector length supported by the system in which case the
364 default vector length is set to that maximum.
366 The result can be determined by reopening the file and reading its
369 At boot, the default vector length is initially set to 64 or the maximum
370 supported vector length, whichever is smaller. This determines the initial
371 vector length of the init process (PID 1).
373 Reading this file returns the current system default vector length.
375 * At every execve() call, the new vector length of the new process is set to
376 the system default vector length, unless
378 * PR_SVE_SET_VL_INHERIT (or equivalently SVE_PT_VL_INHERIT) is set for the
381 * a deferred vector length change is pending, established via the
382 PR_SVE_SET_VL_ONEXEC flag (or SVE_PT_VL_ONEXEC).
384 * Modifying the system default vector length does not affect the vector length
385 of any existing process or thread that does not make an execve() call.
388 Appendix A. SVE programmer's model (informative)
389 =================================================
391 This section provides a minimal description of the additions made by SVE to the
392 ARMv8-A programmer's model that are relevant to this document.
394 Note: This section is for information only and not intended to be complete or
395 to replace any architectural specification.
400 In A64 state, SVE adds the following:
402 * 32 8VL-bit vector registers Z0..Z31
403 For each Zn, Zn bits [127:0] alias the ARMv8-A vector register Vn.
405 A register write using a Vn register name zeros all bits of the corresponding
406 Zn except for bits [127:0].
408 * 16 VL-bit predicate registers P0..P15
410 * 1 VL-bit special-purpose predicate register FFR (the "first-fault register")
412 * a VL "pseudo-register" that determines the size of each vector register
414 The SVE instruction set architecture provides no way to write VL directly.
415 Instead, it can be modified only by EL1 and above, by writing appropriate
418 * The value of VL can be configured at runtime by EL1 and above:
419 16 <= VL <= VLmax, where VL must be a multiple of 16.
421 * The maximum vector length is determined by the hardware:
424 (The SVE architecture specifies 256, but permits future architecture
425 revisions to raise this limit.)
427 * FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point
428 operations in a similar way to the way in which they interact with ARMv8
429 floating-point operations.
431 8VL-1 128 0 bit index
432 +---- //// -----------------+
442 +---- //// -----------------+
445 +---- //// --+ FPSR | |
451 +---- //// --+ VL | |
455 This only applies to bits [63:0] of Z-/V-registers.
456 FPCR contains callee-save and caller-save bits. See [4] for details.
459 A.2. Procedure call standard
460 -----------------------------
462 The ARMv8-A base procedure call standard is extended as follows with respect to
463 the additional SVE register state:
465 * All SVE register bits that are not shared with FP/SIMD are caller-save.
467 * Z8 bits [63:0] .. Z15 bits [63:0] are callee-save.
469 This follows from the way these bits are mapped to V8..V15, which are caller-
470 save in the base procedure call standard.
473 Appendix B. ARMv8-A FP/SIMD programmer's model
474 ===============================================
476 Note: This section is for information only and not intended to be complete or
477 to replace any architectural specification.
479 Refer to [4] for for more information.
481 ARMv8-A defines the following floating-point / SIMD register state:
483 * 32 128-bit vector registers V0..V31
484 * 2 32-bit status/control registers FPSR, FPCR
507 This only applies to bits [63:0] of V-registers.
508 FPCR contains a mixture of callee-save and caller-save bits.
514 [1] arch/arm64/include/uapi/asm/sigcontext.h
515 AArch64 Linux signal ABI definitions
517 [2] arch/arm64/include/uapi/asm/ptrace.h
518 AArch64 Linux ptrace ABI definitions
520 [3] Documentation/arm64/cpu-feature-registers.txt
523 http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf
524 http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html
525 Procedure Call Standard for the ARM 64-bit Architecture (AArch64)