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