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