Documentation/arm64/sve.txt

   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
  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
  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
  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
  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
 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
 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
 236       Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become
 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
 536 [3] Documentation/arm64/cpu-feature-registers.txt
 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)