]>
Commit | Line | Data |
---|---|---|
ce699081 DM |
1 | Scalable Vector Extension support for AArch64 Linux |
2 | =================================================== | |
3 | ||
4 | Author: Dave Martin <Dave.Martin@arm.com> | |
5 | Date: 4 August 2017 | |
6 | ||
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). | |
9 | ||
10 | This is an outline of the most important features and issues only and not | |
11 | intended to be exhaustive. | |
12 | ||
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. | |
16 | ||
17 | ||
18 | 1. General | |
19 | ----------- | |
20 | ||
21 | * SVE registers Z0..Z31, P0..P15 and FFR and the current vector length VL, are | |
22 | tracked per-thread. | |
23 | ||
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". | |
28 | ||
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] | |
32 | ||
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. | |
36 | ||
06a916fe DM |
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: | |
40 | ||
41 | HWCAP2_SVE2 | |
42 | HWCAP2_SVEAES | |
43 | HWCAP2_SVEPMULL | |
44 | HWCAP2_SVEBITPERM | |
45 | HWCAP2_SVESHA3 | |
46 | HWCAP2_SVESM4 | |
47 | ||
48 | This list may be extended over time as the SVE architecture evolves. | |
49 | ||
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. | |
53 | ||
ce699081 DM |
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). | |
58 | ||
41040cf7 DM |
59 | * Whenever SVE scalable register values (Zn, Pn, FFR) are exchanged in memory |
60 | between userspace and the kernel, the register value is encoded in memory in | |
61 | an endianness-invariant layout, with bits [(8 * i + 7) : (8 * i)] encoded at | |
62 | byte offset i from the start of the memory representation. This affects for | |
63 | example the signal frame (struct sve_context) and ptrace interface | |
64 | (struct user_sve_header) and associated data. | |
65 | ||
66 | Beware that on big-endian systems this results in a different byte order than | |
67 | for the FPSIMD V-registers, which are stored as single host-endian 128-bit | |
68 | values, with bits [(127 - 8 * i) : (120 - 8 * i)] of the register encoded at | |
69 | byte offset i. (struct fpsimd_context, struct user_fpsimd_state). | |
70 | ||
ce699081 DM |
71 | |
72 | 2. Vector length terminology | |
73 | ----------------------------- | |
74 | ||
75 | The size of an SVE vector (Z) register is referred to as the "vector length". | |
76 | ||
77 | To avoid confusion about the units used to express vector length, the kernel | |
78 | adopts the following conventions: | |
79 | ||
80 | * Vector length (VL) = size of a Z-register in bytes | |
81 | ||
82 | * Vector quadwords (VQ) = size of a Z-register in units of 128 bits | |
83 | ||
84 | (So, VL = 16 * VQ.) | |
85 | ||
86 | The VQ convention is used where the underlying granularity is important, such | |
87 | as in data structure definitions. In most other situations, the VL convention | |
88 | is used. This is consistent with the meaning of the "VL" pseudo-register in | |
89 | the SVE instruction set architecture. | |
90 | ||
91 | ||
92 | 3. System call behaviour | |
93 | ------------------------- | |
94 | ||
95 | * On syscall, V0..V31 are preserved (as without SVE). Thus, bits [127:0] of | |
96 | Z0..Z31 are preserved. All other bits of Z0..Z31, and all of P0..P15 and FFR | |
97 | become unspecified on return from a syscall. | |
98 | ||
99 | * The SVE registers are not used to pass arguments to or receive results from | |
100 | any syscall. | |
101 | ||
102 | * In practice the affected registers/bits will be preserved or will be replaced | |
103 | with zeros on return from a syscall, but userspace should not make | |
104 | assumptions about this. The kernel behaviour may vary on a case-by-case | |
105 | basis. | |
106 | ||
107 | * All other SVE state of a thread, including the currently configured vector | |
108 | length, the state of the PR_SVE_VL_INHERIT flag, and the deferred vector | |
109 | length (if any), is preserved across all syscalls, subject to the specific | |
110 | exceptions for execve() described in section 6. | |
111 | ||
112 | In particular, on return from a fork() or clone(), the parent and new child | |
113 | process or thread share identical SVE configuration, matching that of the | |
114 | parent before the call. | |
115 | ||
116 | ||
117 | 4. Signal handling | |
118 | ------------------- | |
119 | ||
120 | * A new signal frame record sve_context encodes the SVE registers on signal | |
121 | delivery. [1] | |
122 | ||
123 | * This record is supplementary to fpsimd_context. The FPSR and FPCR registers | |
124 | are only present in fpsimd_context. For convenience, the content of V0..V31 | |
125 | is duplicated between sve_context and fpsimd_context. | |
126 | ||
127 | * The signal frame record for SVE always contains basic metadata, in particular | |
128 | the thread's vector length (in sve_context.vl). | |
129 | ||
130 | * The SVE registers may or may not be included in the record, depending on | |
131 | whether the registers are live for the thread. The registers are present if | |
132 | and only if: | |
133 | sve_context.head.size >= SVE_SIG_CONTEXT_SIZE(sve_vq_from_vl(sve_context.vl)). | |
134 | ||
135 | * If the registers are present, the remainder of the record has a vl-dependent | |
136 | size and layout. Macros SVE_SIG_* are defined [1] to facilitate access to | |
137 | the members. | |
138 | ||
41040cf7 DM |
139 | * Each scalable register (Zn, Pn, FFR) is stored in an endianness-invariant |
140 | layout, with bits [(8 * i + 7) : (8 * i)] stored at byte offset i from the | |
141 | start of the register's representation in memory. | |
142 | ||
ce699081 DM |
143 | * If the SVE context is too big to fit in sigcontext.__reserved[], then extra |
144 | space is allocated on the stack, an extra_context record is written in | |
145 | __reserved[] referencing this space. sve_context is then written in the | |
146 | extra space. Refer to [1] for further details about this mechanism. | |
147 | ||
148 | ||
149 | 5. Signal return | |
150 | ----------------- | |
151 | ||
152 | When returning from a signal handler: | |
153 | ||
154 | * If there is no sve_context record in the signal frame, or if the record is | |
155 | present but contains no register data as desribed in the previous section, | |
156 | then the SVE registers/bits become non-live and take unspecified values. | |
157 | ||
158 | * If sve_context is present in the signal frame and contains full register | |
159 | data, the SVE registers become live and are populated with the specified | |
160 | data. However, for backward compatibility reasons, bits [127:0] of Z0..Z31 | |
161 | are always restored from the corresponding members of fpsimd_context.vregs[] | |
162 | and not from sve_context. The remaining bits are restored from sve_context. | |
163 | ||
164 | * Inclusion of fpsimd_context in the signal frame remains mandatory, | |
165 | irrespective of whether sve_context is present or not. | |
166 | ||
167 | * The vector length cannot be changed via signal return. If sve_context.vl in | |
168 | the signal frame does not match the current vector length, the signal return | |
169 | attempt is treated as illegal, resulting in a forced SIGSEGV. | |
170 | ||
171 | ||
172 | 6. prctl extensions | |
173 | -------------------- | |
174 | ||
175 | Some new prctl() calls are added to allow programs to manage the SVE vector | |
176 | length: | |
177 | ||
178 | prctl(PR_SVE_SET_VL, unsigned long arg) | |
179 | ||
180 | Sets the vector length of the calling thread and related flags, where | |
181 | arg == vl | flags. Other threads of the calling process are unaffected. | |
182 | ||
183 | vl is the desired vector length, where sve_vl_valid(vl) must be true. | |
184 | ||
185 | flags: | |
186 | ||
187 | PR_SVE_SET_VL_INHERIT | |
188 | ||
189 | Inherit the current vector length across execve(). Otherwise, the | |
190 | vector length is reset to the system default at execve(). (See | |
191 | Section 9.) | |
192 | ||
193 | PR_SVE_SET_VL_ONEXEC | |
194 | ||
195 | Defer the requested vector length change until the next execve() | |
196 | performed by this thread. | |
197 | ||
198 | The effect is equivalent to implicit exceution of the following | |
199 | call immediately after the next execve() (if any) by the thread: | |
200 | ||
201 | prctl(PR_SVE_SET_VL, arg & ~PR_SVE_SET_VL_ONEXEC) | |
202 | ||
203 | This allows launching of a new program with a different vector | |
204 | length, while avoiding runtime side effects in the caller. | |
205 | ||
206 | ||
207 | Without PR_SVE_SET_VL_ONEXEC, the requested change takes effect | |
208 | immediately. | |
209 | ||
210 | ||
211 | Return value: a nonnegative on success, or a negative value on error: | |
212 | EINVAL: SVE not supported, invalid vector length requested, or | |
213 | invalid flags. | |
214 | ||
215 | ||
216 | On success: | |
217 | ||
218 | * Either the calling thread's vector length or the deferred vector length | |
219 | to be applied at the next execve() by the thread (dependent on whether | |
220 | PR_SVE_SET_VL_ONEXEC is present in arg), is set to the largest value | |
221 | supported by the system that is less than or equal to vl. If vl == | |
222 | SVE_VL_MAX, the value set will be the largest value supported by the | |
223 | system. | |
224 | ||
225 | * Any previously outstanding deferred vector length change in the calling | |
226 | thread is cancelled. | |
227 | ||
228 | * The returned value describes the resulting configuration, encoded as for | |
229 | PR_SVE_GET_VL. The vector length reported in this value is the new | |
230 | current vector length for this thread if PR_SVE_SET_VL_ONEXEC was not | |
231 | present in arg; otherwise, the reported vector length is the deferred | |
232 | vector length that will be applied at the next execve() by the calling | |
233 | thread. | |
234 | ||
235 | * Changing the vector length causes all of P0..P15, FFR and all bits of | |
afce0cc9 | 236 | Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become |
ce699081 DM |
237 | unspecified. Calling PR_SVE_SET_VL with vl equal to the thread's current |
238 | vector length, or calling PR_SVE_SET_VL with the PR_SVE_SET_VL_ONEXEC | |
239 | flag, does not constitute a change to the vector length for this purpose. | |
240 | ||
241 | ||
242 | prctl(PR_SVE_GET_VL) | |
243 | ||
244 | Gets the vector length of the calling thread. | |
245 | ||
246 | The following flag may be OR-ed into the result: | |
247 | ||
248 | PR_SVE_SET_VL_INHERIT | |
249 | ||
250 | Vector length will be inherited across execve(). | |
251 | ||
252 | There is no way to determine whether there is an outstanding deferred | |
253 | vector length change (which would only normally be the case between a | |
254 | fork() or vfork() and the corresponding execve() in typical use). | |
255 | ||
256 | To extract the vector length from the result, and it with | |
257 | PR_SVE_VL_LEN_MASK. | |
258 | ||
259 | Return value: a nonnegative value on success, or a negative value on error: | |
260 | EINVAL: SVE not supported. | |
261 | ||
262 | ||
263 | 7. ptrace extensions | |
264 | --------------------- | |
265 | ||
266 | * A new regset NT_ARM_SVE is defined for use with PTRACE_GETREGSET and | |
267 | PTRACE_SETREGSET. | |
268 | ||
269 | Refer to [2] for definitions. | |
270 | ||
271 | The regset data starts with struct user_sve_header, containing: | |
272 | ||
273 | size | |
274 | ||
275 | Size of the complete regset, in bytes. | |
276 | This depends on vl and possibly on other things in the future. | |
277 | ||
278 | If a call to PTRACE_GETREGSET requests less data than the value of | |
279 | size, the caller can allocate a larger buffer and retry in order to | |
280 | read the complete regset. | |
281 | ||
282 | max_size | |
283 | ||
284 | Maximum size in bytes that the regset can grow to for the target | |
285 | thread. The regset won't grow bigger than this even if the target | |
286 | thread changes its vector length etc. | |
287 | ||
288 | vl | |
289 | ||
290 | Target thread's current vector length, in bytes. | |
291 | ||
292 | max_vl | |
293 | ||
294 | Maximum possible vector length for the target thread. | |
295 | ||
296 | flags | |
297 | ||
298 | either | |
299 | ||
300 | SVE_PT_REGS_FPSIMD | |
301 | ||
302 | SVE registers are not live (GETREGSET) or are to be made | |
303 | non-live (SETREGSET). | |
304 | ||
305 | The payload is of type struct user_fpsimd_state, with the same | |
306 | meaning as for NT_PRFPREG, starting at offset | |
307 | SVE_PT_FPSIMD_OFFSET from the start of user_sve_header. | |
308 | ||
309 | Extra data might be appended in the future: the size of the | |
310 | payload should be obtained using SVE_PT_FPSIMD_SIZE(vq, flags). | |
311 | ||
312 | vq should be obtained using sve_vq_from_vl(vl). | |
313 | ||
314 | or | |
315 | ||
316 | SVE_PT_REGS_SVE | |
317 | ||
318 | SVE registers are live (GETREGSET) or are to be made live | |
319 | (SETREGSET). | |
320 | ||
321 | The payload contains the SVE register data, starting at offset | |
322 | SVE_PT_SVE_OFFSET from the start of user_sve_header, and with | |
323 | size SVE_PT_SVE_SIZE(vq, flags); | |
324 | ||
325 | ... OR-ed with zero or more of the following flags, which have the same | |
326 | meaning and behaviour as the corresponding PR_SET_VL_* flags: | |
327 | ||
328 | SVE_PT_VL_INHERIT | |
329 | ||
330 | SVE_PT_VL_ONEXEC (SETREGSET only). | |
331 | ||
332 | * The effects of changing the vector length and/or flags are equivalent to | |
333 | those documented for PR_SVE_SET_VL. | |
334 | ||
335 | The caller must make a further GETREGSET call if it needs to know what VL is | |
336 | actually set by SETREGSET, unless is it known in advance that the requested | |
337 | VL is supported. | |
338 | ||
339 | * In the SVE_PT_REGS_SVE case, the size and layout of the payload depends on | |
340 | the header fields. The SVE_PT_SVE_*() macros are provided to facilitate | |
341 | access to the members. | |
342 | ||
343 | * In either case, for SETREGSET it is permissible to omit the payload, in which | |
344 | case only the vector length and flags are changed (along with any | |
345 | consequences of those changes). | |
346 | ||
347 | * For SETREGSET, if an SVE_PT_REGS_SVE payload is present and the | |
348 | requested VL is not supported, the effect will be the same as if the | |
349 | payload were omitted, except that an EIO error is reported. No | |
350 | attempt is made to translate the payload data to the correct layout | |
351 | for the vector length actually set. The thread's FPSIMD state is | |
352 | preserved, but the remaining bits of the SVE registers become | |
353 | unspecified. It is up to the caller to translate the payload layout | |
354 | for the actual VL and retry. | |
355 | ||
356 | * The effect of writing a partial, incomplete payload is unspecified. | |
357 | ||
358 | ||
359 | 8. ELF coredump extensions | |
360 | --------------------------- | |
361 | ||
362 | * A NT_ARM_SVE note will be added to each coredump for each thread of the | |
363 | dumped process. The contents will be equivalent to the data that would have | |
364 | been read if a PTRACE_GETREGSET of NT_ARM_SVE were executed for each thread | |
365 | when the coredump was generated. | |
366 | ||
367 | ||
368 | 9. System runtime configuration | |
369 | -------------------------------- | |
370 | ||
371 | * To mitigate the ABI impact of expansion of the signal frame, a policy | |
372 | mechanism is provided for administrators, distro maintainers and developers | |
373 | to set the default vector length for userspace processes: | |
374 | ||
375 | /proc/sys/abi/sve_default_vector_length | |
376 | ||
377 | Writing the text representation of an integer to this file sets the system | |
378 | default vector length to the specified value, unless the value is greater | |
379 | than the maximum vector length supported by the system in which case the | |
380 | default vector length is set to that maximum. | |
381 | ||
382 | The result can be determined by reopening the file and reading its | |
383 | contents. | |
384 | ||
385 | At boot, the default vector length is initially set to 64 or the maximum | |
386 | supported vector length, whichever is smaller. This determines the initial | |
387 | vector length of the init process (PID 1). | |
388 | ||
389 | Reading this file returns the current system default vector length. | |
390 | ||
391 | * At every execve() call, the new vector length of the new process is set to | |
392 | the system default vector length, unless | |
393 | ||
394 | * PR_SVE_SET_VL_INHERIT (or equivalently SVE_PT_VL_INHERIT) is set for the | |
395 | calling thread, or | |
396 | ||
397 | * a deferred vector length change is pending, established via the | |
398 | PR_SVE_SET_VL_ONEXEC flag (or SVE_PT_VL_ONEXEC). | |
399 | ||
400 | * Modifying the system default vector length does not affect the vector length | |
401 | of any existing process or thread that does not make an execve() call. | |
402 | ||
403 | ||
404 | Appendix A. SVE programmer's model (informative) | |
405 | ================================================= | |
406 | ||
407 | This section provides a minimal description of the additions made by SVE to the | |
408 | ARMv8-A programmer's model that are relevant to this document. | |
409 | ||
410 | Note: This section is for information only and not intended to be complete or | |
411 | to replace any architectural specification. | |
412 | ||
413 | A.1. Registers | |
414 | --------------- | |
415 | ||
416 | In A64 state, SVE adds the following: | |
417 | ||
418 | * 32 8VL-bit vector registers Z0..Z31 | |
419 | For each Zn, Zn bits [127:0] alias the ARMv8-A vector register Vn. | |
420 | ||
421 | A register write using a Vn register name zeros all bits of the corresponding | |
422 | Zn except for bits [127:0]. | |
423 | ||
424 | * 16 VL-bit predicate registers P0..P15 | |
425 | ||
426 | * 1 VL-bit special-purpose predicate register FFR (the "first-fault register") | |
427 | ||
428 | * a VL "pseudo-register" that determines the size of each vector register | |
429 | ||
430 | The SVE instruction set architecture provides no way to write VL directly. | |
431 | Instead, it can be modified only by EL1 and above, by writing appropriate | |
432 | system registers. | |
433 | ||
434 | * The value of VL can be configured at runtime by EL1 and above: | |
435 | 16 <= VL <= VLmax, where VL must be a multiple of 16. | |
436 | ||
437 | * The maximum vector length is determined by the hardware: | |
438 | 16 <= VLmax <= 256. | |
439 | ||
440 | (The SVE architecture specifies 256, but permits future architecture | |
441 | revisions to raise this limit.) | |
442 | ||
443 | * FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point | |
444 | operations in a similar way to the way in which they interact with ARMv8 | |
445 | floating-point operations. | |
446 | ||
447 | 8VL-1 128 0 bit index | |
448 | +---- //// -----------------+ | |
449 | Z0 | : V0 | | |
450 | : : | |
451 | Z7 | : V7 | | |
452 | Z8 | : * V8 | | |
453 | : : : | |
454 | Z15 | : *V15 | | |
455 | Z16 | : V16 | | |
456 | : : | |
457 | Z31 | : V31 | | |
458 | +---- //// -----------------+ | |
459 | 31 0 | |
460 | VL-1 0 +-------+ | |
461 | +---- //// --+ FPSR | | | |
462 | P0 | | +-------+ | |
463 | : | | *FPCR | | | |
464 | P15 | | +-------+ | |
465 | +---- //// --+ | |
466 | FFR | | +-----+ | |
467 | +---- //// --+ VL | | | |
468 | +-----+ | |
469 | ||
470 | (*) callee-save: | |
471 | This only applies to bits [63:0] of Z-/V-registers. | |
472 | FPCR contains callee-save and caller-save bits. See [4] for details. | |
473 | ||
474 | ||
475 | A.2. Procedure call standard | |
476 | ----------------------------- | |
477 | ||
478 | The ARMv8-A base procedure call standard is extended as follows with respect to | |
479 | the additional SVE register state: | |
480 | ||
481 | * All SVE register bits that are not shared with FP/SIMD are caller-save. | |
482 | ||
483 | * Z8 bits [63:0] .. Z15 bits [63:0] are callee-save. | |
484 | ||
485 | This follows from the way these bits are mapped to V8..V15, which are caller- | |
486 | save in the base procedure call standard. | |
487 | ||
488 | ||
489 | Appendix B. ARMv8-A FP/SIMD programmer's model | |
490 | =============================================== | |
491 | ||
492 | Note: This section is for information only and not intended to be complete or | |
493 | to replace any architectural specification. | |
494 | ||
495 | Refer to [4] for for more information. | |
496 | ||
497 | ARMv8-A defines the following floating-point / SIMD register state: | |
498 | ||
499 | * 32 128-bit vector registers V0..V31 | |
500 | * 2 32-bit status/control registers FPSR, FPCR | |
501 | ||
502 | 127 0 bit index | |
503 | +---------------+ | |
504 | V0 | | | |
505 | : : : | |
506 | V7 | | | |
507 | * V8 | | | |
508 | : : : : | |
509 | *V15 | | | |
510 | V16 | | | |
511 | : : : | |
512 | V31 | | | |
513 | +---------------+ | |
514 | ||
515 | 31 0 | |
516 | +-------+ | |
517 | FPSR | | | |
518 | +-------+ | |
519 | *FPCR | | | |
520 | +-------+ | |
521 | ||
522 | (*) callee-save: | |
523 | This only applies to bits [63:0] of V-registers. | |
524 | FPCR contains a mixture of callee-save and caller-save bits. | |
525 | ||
526 | ||
527 | References | |
528 | ========== | |
529 | ||
530 | [1] arch/arm64/include/uapi/asm/sigcontext.h | |
531 | AArch64 Linux signal ABI definitions | |
532 | ||
533 | [2] arch/arm64/include/uapi/asm/ptrace.h | |
534 | AArch64 Linux ptrace ABI definitions | |
535 | ||
afce0cc9 | 536 | [3] Documentation/arm64/cpu-feature-registers.txt |
ce699081 DM |
537 | |
538 | [4] ARM IHI0055C | |
539 | http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055c/IHI0055C_beta_aapcs64.pdf | |
540 | http://infocenter.arm.com/help/topic/com.arm.doc.subset.swdev.abi/index.html | |
541 | Procedure Call Standard for the ARM 64-bit Architecture (AArch64) |