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
  60 2.  Vector length terminology
  61 -----------------------------
  62
  63 The size of an SVE vector (Z) register is referred to as the "vector length".
  64
  65 To avoid confusion about the units used to express vector length, the kernel
  66 adopts the following conventions:
  67
  68 * Vector length (VL) = size of a Z-register in bytes
  69
  70 * Vector quadwords (VQ) = size of a Z-register in units of 128 bits
  71
  72 (So, VL = 16 * VQ.)
  73
  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.
  78
  79
  80 3.  System call behaviour
  81 -------------------------
  82
  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.
  86
  87 * The SVE registers are not used to pass arguments to or receive results from
  88   any syscall.
  89
  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
  93   basis.
  94
  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.
  99
 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.
 103
 104
 105 4.  Signal handling
 106 -------------------
 107
 108 * A new signal frame record sve_context encodes the SVE registers on signal
 109   delivery. [1]
 110
 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.
 114
 115 * The signal frame record for SVE always contains basic metadata, in particular
 116   the thread's vector length (in sve_context.vl).
 117
 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
 120   and only if:
 121   sve_context.head.size >= SVE_SIG_CONTEXT_SIZE(sve_vq_from_vl(sve_context.vl)).
 122
 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
 125   the members.
 126
 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.
 131
 132
 133 5.  Signal return
 134 -----------------
 135
 136 When returning from a signal handler:
 137
 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.
 141
 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.
 147
 148 * Inclusion of fpsimd_context in the signal frame remains mandatory,
 149   irrespective of whether sve_context is present or not.
 150
 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.
 154
 155
 156 6.  prctl extensions
 157 --------------------
 158
 159 Some new prctl() calls are added to allow programs to manage the SVE vector
 160 length:
 161
 162 prctl(PR_SVE_SET_VL, unsigned long arg)
 163
 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.
 166
 167     vl is the desired vector length, where sve_vl_valid(vl) must be true.
 168
 169     flags:
 170
 171         PR_SVE_SET_VL_INHERIT
 172
 173             Inherit the current vector length across execve().  Otherwise, the
 174             vector length is reset to the system default at execve().  (See
 175             Section 9.)
 176
 177         PR_SVE_SET_VL_ONEXEC
 178
 179             Defer the requested vector length change until the next execve()
 180             performed by this thread.
 181
 182             The effect is equivalent to implicit exceution of the following
 183             call immediately after the next execve() (if any) by the thread:
 184
 185                 prctl(PR_SVE_SET_VL, arg & ~PR_SVE_SET_VL_ONEXEC)
 186
 187             This allows launching of a new program with a different vector
 188             length, while avoiding runtime side effects in the caller.
 189
 190
 191             Without PR_SVE_SET_VL_ONEXEC, the requested change takes effect
 192             immediately.
 193
 194
 195     Return value: a nonnegative on success, or a negative value on error:
 196         EINVAL: SVE not supported, invalid vector length requested, or
 197             invalid flags.
 198
 199
 200     On success:
 201
 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
 207       system.
 208
 209     * Any previously outstanding deferred vector length change in the calling
 210       thread is cancelled.
 211
 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
 217       thread.
 218
 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.
 224
 225
 226 prctl(PR_SVE_GET_VL)
 227
 228     Gets the vector length of the calling thread.
 229
 230     The following flag may be OR-ed into the result:
 231
 232         PR_SVE_SET_VL_INHERIT
 233
 234             Vector length will be inherited across execve().
 235
 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).
 239
 240     To extract the vector length from the result, and it with
 241     PR_SVE_VL_LEN_MASK.
 242
 243     Return value: a nonnegative value on success, or a negative value on error:
 244         EINVAL: SVE not supported.
 245
 246
 247 7.  ptrace extensions
 248 ---------------------
 249
 250 * A new regset NT_ARM_SVE is defined for use with PTRACE_GETREGSET and
 251   PTRACE_SETREGSET.
 252
 253   Refer to [2] for definitions.
 254
 255 The regset data starts with struct user_sve_header, containing:
 256
 257     size
 258
 259         Size of the complete regset, in bytes.
 260         This depends on vl and possibly on other things in the future.
 261
 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.
 265
 266     max_size
 267
 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.
 271
 272     vl
 273
 274         Target thread's current vector length, in bytes.
 275
 276     max_vl
 277
 278         Maximum possible vector length for the target thread.
 279
 280     flags
 281
 282         either
 283
 284             SVE_PT_REGS_FPSIMD
 285
 286                 SVE registers are not live (GETREGSET) or are to be made
 287                 non-live (SETREGSET).
 288
 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.
 292
 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).
 295
 296                 vq should be obtained using sve_vq_from_vl(vl).
 297
 298                 or
 299
 300             SVE_PT_REGS_SVE
 301
 302                 SVE registers are live (GETREGSET) or are to be made live
 303                 (SETREGSET).
 304
 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);
 308
 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:
 311
 312             SVE_PT_VL_INHERIT
 313
 314             SVE_PT_VL_ONEXEC (SETREGSET only).
 315
 316 * The effects of changing the vector length and/or flags are equivalent to
 317   those documented for PR_SVE_SET_VL.
 318
 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
 321   VL is supported.
 322
 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.
 326
 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).
 330
 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.
 339
 340 * The effect of writing a partial, incomplete payload is unspecified.
 341
 342
 343 8.  ELF coredump extensions
 344 ---------------------------
 345
 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.
 350
 351
 352 9.  System runtime configuration
 353 --------------------------------
 354
 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:
 358
 359 /proc/sys/abi/sve_default_vector_length
 360
 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.
 365
 366     The result can be determined by reopening the file and reading its
 367     contents.
 368
 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).
 372
 373     Reading this file returns the current system default vector length.
 374
 375 * At every execve() call, the new vector length of the new process is set to
 376   the system default vector length, unless
 377
 378     * PR_SVE_SET_VL_INHERIT (or equivalently SVE_PT_VL_INHERIT) is set for the
 379       calling thread, or
 380
 381     * a deferred vector length change is pending, established via the
 382       PR_SVE_SET_VL_ONEXEC flag (or SVE_PT_VL_ONEXEC).
 383
 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.
 386
 387
 388 Appendix A.  SVE programmer's model (informative)
 389 =================================================
 390
 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.
 393
 394 Note: This section is for information only and not intended to be complete or
 395 to replace any architectural specification.
 396
 397 A.1.  Registers
 398 ---------------
 399
 400 In A64 state, SVE adds the following:
 401
 402 * 32 8VL-bit vector registers Z0..Z31
 403   For each Zn, Zn bits [127:0] alias the ARMv8-A vector register Vn.
 404
 405   A register write using a Vn register name zeros all bits of the corresponding
 406   Zn except for bits [127:0].
 407
 408 * 16 VL-bit predicate registers P0..P15
 409
 410 * 1 VL-bit special-purpose predicate register FFR (the "first-fault register")
 411
 412 * a VL "pseudo-register" that determines the size of each vector register
 413
 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
 416   system registers.
 417
 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.
 420
 421 * The maximum vector length is determined by the hardware:
 422   16 <= VLmax <= 256.
 423
 424   (The SVE architecture specifies 256, but permits future architecture
 425   revisions to raise this limit.)
 426
 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.
 430
 431          8VL-1                       128               0  bit index
 432         +----          ////            -----------------+
 433      Z0 |                               :       V0      |
 434       :                                          :
 435      Z7 |                               :       V7      |
 436      Z8 |                               :     * V8      |
 437       :                                       :  :
 438     Z15 |                               :     *V15      |
 439     Z16 |                               :      V16      |
 440       :                                          :
 441     Z31 |                               :      V31      |
 442         +----          ////            -----------------+
 443                                                  31    0
 444          VL-1                  0                +-------+
 445         +----       ////      --+          FPSR |       |
 446      P0 |                       |               +-------+
 447       : |                       |         *FPCR |       |
 448     P15 |                       |               +-------+
 449         +----       ////      --+
 450     FFR |                       |               +-----+
 451         +----       ////      --+            VL |     |
 452                                                 +-----+
 453
 454 (*) callee-save:
 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.
 457
 458
 459 A.2.  Procedure call standard
 460 -----------------------------
 461
 462 The ARMv8-A base procedure call standard is extended as follows with respect to
 463 the additional SVE register state:
 464
 465 * All SVE register bits that are not shared with FP/SIMD are caller-save.
 466
 467 * Z8 bits [63:0] .. Z15 bits [63:0] are callee-save.
 468
 469   This follows from the way these bits are mapped to V8..V15, which are caller-
 470   save in the base procedure call standard.
 471
 472
 473 Appendix B.  ARMv8-A FP/SIMD programmer's model
 474 ===============================================
 475
 476 Note: This section is for information only and not intended to be complete or
 477 to replace any architectural specification.
 478
 479 Refer to [4] for for more information.
 480
 481 ARMv8-A defines the following floating-point / SIMD register state:
 482
 483 * 32 128-bit vector registers V0..V31
 484 * 2 32-bit status/control registers FPSR, FPCR
 485
 486          127           0  bit index
 487         +---------------+
 488      V0 |               |
 489       : :               :
 490      V7 |               |
 491    * V8 |               |
 492    :  : :               :
 493    *V15 |               |
 494     V16 |               |
 495       : :               :
 496     V31 |               |
 497         +---------------+
 498
 499                  31    0
 500                 +-------+
 501            FPSR |       |
 502                 +-------+
 503           *FPCR |       |
 504                 +-------+
 505
 506 (*) callee-save:
 507     This only applies to bits [63:0] of V-registers.
 508     FPCR contains a mixture of callee-save and caller-save bits.
 509
 510
 511 References
 512 ==========
 513
 514 [1] arch/arm64/include/uapi/asm/sigcontext.h
 515     AArch64 Linux signal ABI definitions
 516
 517 [2] arch/arm64/include/uapi/asm/ptrace.h
 518     AArch64 Linux ptrace ABI definitions
 519
 520 [3] Documentation/arm64/cpu-feature-registers.txt
 521
 522 [4] ARM IHI0055C
 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)