1=================================================== 2Scalable Matrix Extension support for AArch64 Linux 3=================================================== 4 5This document outlines briefly the interface provided to userspace by Linux in 6order to support use of the ARM Scalable Matrix Extension (SME). 7 8This is an outline of the most important features and issues only and not 9intended to be exhaustive. It should be read in conjunction with the SVE 10documentation in sve.rst which provides details on the Streaming SVE mode 11included in SME. 12 13This document does not aim to describe the SME architecture or programmer's 14model. To aid understanding, a minimal description of relevant programmer's 15model features for SME is included in Appendix A. 16 17 181. General 19----------- 20 21* PSTATE.SM, PSTATE.ZA, the streaming mode vector length, the ZA and (when 22 present) ZTn register state and TPIDR2_EL0 are tracked per thread. 23 24* The presence of SME is reported to userspace via HWCAP2_SME in the aux vector 25 AT_HWCAP2 entry. Presence of this flag implies the presence of the SME 26 instructions and registers, and the Linux-specific system interfaces 27 described in this document. SME is reported in /proc/cpuinfo as "sme". 28 29* The presence of SME2 is reported to userspace via HWCAP2_SME2 in the 30 aux vector AT_HWCAP2 entry. Presence of this flag implies the presence of 31 the SME2 instructions and ZT0, and the Linux-specific system interfaces 32 described in this document. SME2 is reported in /proc/cpuinfo as "sme2". 33 34* Support for the execution of SME instructions in userspace can also be 35 detected by reading the CPU ID register ID_AA64PFR1_EL1 using an MRS 36 instruction, and checking that the value of the SME field is nonzero. [3] 37 38 It does not guarantee the presence of the system interfaces described in the 39 following sections: software that needs to verify that those interfaces are 40 present must check for HWCAP2_SME instead. 41 42* There are a number of optional SME features, presence of these is reported 43 through AT_HWCAP2 through: 44 45 HWCAP2_SME_I16I64 46 HWCAP2_SME_F64F64 47 HWCAP2_SME_I8I32 48 HWCAP2_SME_F16F32 49 HWCAP2_SME_B16F32 50 HWCAP2_SME_F32F32 51 HWCAP2_SME_FA64 52 HWCAP2_SME2 53 54 This list may be extended over time as the SME architecture evolves. 55 56 These extensions are also reported via the CPU ID register ID_AA64SMFR0_EL1, 57 which userspace can read using an MRS instruction. See elf_hwcaps.txt and 58 cpu-feature-registers.txt for details. 59 60* Debuggers should restrict themselves to interacting with the target via the 61 NT_ARM_SVE, NT_ARM_SSVE, NT_ARM_ZA and NT_ARM_ZT regsets. The recommended 62 way of detecting support for these regsets is to connect to a target process 63 first and then attempt a 64 65 ptrace(PTRACE_GETREGSET, pid, NT_ARM_<regset>, &iov). 66 67* Whenever ZA register values are exchanged in memory between userspace and 68 the kernel, the register value is encoded in memory as a series of horizontal 69 vectors from 0 to VL/8-1 stored in the same endianness invariant format as is 70 used for SVE vectors. 71 72* On thread creation PSTATE.ZA and TPIDR2_EL0 are preserved unless CLONE_VM 73 is specified, in which case PSTATE.ZA is set to 0 and TPIDR2_EL0 is set to 0. 74 752. Vector lengths 76------------------ 77 78SME defines a second vector length similar to the SVE vector length which 79controls the size of the streaming mode SVE vectors and the ZA matrix array. 80The ZA matrix is square with each side having as many bytes as a streaming 81mode SVE vector. 82 83 843. System call behaviour 85------------------------- 86 87* On syscall PSTATE.ZA is preserved, if PSTATE.ZA==1 then the contents of the 88 ZA matrix and ZTn (if present) are preserved. 89 90* On syscall PSTATE.SM will be cleared and the SVE registers will be handled 91 as per the standard SVE ABI. 92 93* None of the SVE registers, ZA or ZTn are used to pass arguments to 94 or receive results from any syscall. 95 96* On process creation (eg, clone()) the newly created process will have 97 PSTATE.SM cleared. 98 99* All other SME state of a thread, including the currently configured vector 100 length, the state of the PR_SME_VL_INHERIT flag, and the deferred vector 101 length (if any), is preserved across all syscalls, subject to the specific 102 exceptions for execve() described in section 6. 103 104 1054. Signal handling 106------------------- 107 108* Signal handlers are invoked with PSTATE.SM=0, PSTATE.ZA=0, and TPIDR2_EL0=0. 109 110* A new signal frame record TPIDR2_MAGIC is added formatted as a struct 111 tpidr2_context to allow access to TPIDR2_EL0 from signal handlers. 112 113* A new signal frame record za_context encodes the ZA register contents on 114 signal delivery. [1] 115 116* The signal frame record for ZA always contains basic metadata, in particular 117 the thread's vector length (in za_context.vl). 118 119* The ZA matrix may or may not be included in the record, depending on 120 the value of PSTATE.ZA. The registers are present if and only if: 121 za_context.head.size >= ZA_SIG_CONTEXT_SIZE(sve_vq_from_vl(za_context.vl)) 122 in which case PSTATE.ZA == 1. 123 124* If matrix data is present, the remainder of the record has a vl-dependent 125 size and layout. Macros ZA_SIG_* are defined [1] to facilitate access to 126 them. 127 128* The matrix is stored as a series of horizontal vectors in the same format as 129 is used for SVE vectors. 130 131* If the ZA context is too big to fit in sigcontext.__reserved[], then extra 132 space is allocated on the stack, an extra_context record is written in 133 __reserved[] referencing this space. za_context is then written in the 134 extra space. Refer to [1] for further details about this mechanism. 135 136* If ZTn is supported and PSTATE.ZA==1 then a signal frame record for ZTn will 137 be generated. 138 139* The signal record for ZTn has magic ZT_MAGIC (0x5a544e01) and consists of a 140 standard signal frame header followed by a struct zt_context specifying 141 the number of ZTn registers supported by the system, then zt_context.nregs 142 blocks of 64 bytes of data per register. 143 144 1455. Signal return 146----------------- 147 148When returning from a signal handler: 149 150* If there is no za_context record in the signal frame, or if the record is 151 present but contains no register data as described in the previous section, 152 then ZA is disabled. 153 154* If za_context is present in the signal frame and contains matrix data then 155 PSTATE.ZA is set to 1 and ZA is populated with the specified data. 156 157* The vector length cannot be changed via signal return. If za_context.vl in 158 the signal frame does not match the current vector length, the signal return 159 attempt is treated as illegal, resulting in a forced SIGSEGV. 160 161* If ZTn is not supported or PSTATE.ZA==0 then it is illegal to have a 162 signal frame record for ZTn, resulting in a forced SIGSEGV. 163 164 1656. prctl extensions 166-------------------- 167 168Some new prctl() calls are added to allow programs to manage the SME vector 169length: 170 171prctl(PR_SME_SET_VL, unsigned long arg) 172 173 Sets the vector length of the calling thread and related flags, where 174 arg == vl | flags. Other threads of the calling process are unaffected. 175 176 vl is the desired vector length, where sve_vl_valid(vl) must be true. 177 178 flags: 179 180 PR_SME_VL_INHERIT 181 182 Inherit the current vector length across execve(). Otherwise, the 183 vector length is reset to the system default at execve(). (See 184 Section 9.) 185 186 PR_SME_SET_VL_ONEXEC 187 188 Defer the requested vector length change until the next execve() 189 performed by this thread. 190 191 The effect is equivalent to implicit execution of the following 192 call immediately after the next execve() (if any) by the thread: 193 194 prctl(PR_SME_SET_VL, arg & ~PR_SME_SET_VL_ONEXEC) 195 196 This allows launching of a new program with a different vector 197 length, while avoiding runtime side effects in the caller. 198 199 Without PR_SME_SET_VL_ONEXEC, the requested change takes effect 200 immediately. 201 202 203 Return value: a nonnegative on success, or a negative value on error: 204 EINVAL: SME not supported, invalid vector length requested, or 205 invalid flags. 206 207 208 On success: 209 210 * Either the calling thread's vector length or the deferred vector length 211 to be applied at the next execve() by the thread (dependent on whether 212 PR_SME_SET_VL_ONEXEC is present in arg), is set to the largest value 213 supported by the system that is less than or equal to vl. If vl == 214 SVE_VL_MAX, the value set will be the largest value supported by the 215 system. 216 217 * Any previously outstanding deferred vector length change in the calling 218 thread is cancelled. 219 220 * The returned value describes the resulting configuration, encoded as for 221 PR_SME_GET_VL. The vector length reported in this value is the new 222 current vector length for this thread if PR_SME_SET_VL_ONEXEC was not 223 present in arg; otherwise, the reported vector length is the deferred 224 vector length that will be applied at the next execve() by the calling 225 thread. 226 227 * Changing the vector length causes all of ZA, ZTn, P0..P15, FFR and all 228 bits of Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become 229 unspecified, including both streaming and non-streaming SVE state. 230 Calling PR_SME_SET_VL with vl equal to the thread's current vector 231 length, or calling PR_SME_SET_VL with the PR_SME_SET_VL_ONEXEC flag, 232 does not constitute a change to the vector length for this purpose. 233 234 * Changing the vector length causes PSTATE.ZA to be cleared. 235 Calling PR_SME_SET_VL with vl equal to the thread's current vector 236 length, or calling PR_SME_SET_VL with the PR_SME_SET_VL_ONEXEC flag, 237 does not constitute a change to the vector length for this purpose. 238 239 240prctl(PR_SME_GET_VL) 241 242 Gets the vector length of the calling thread. 243 244 The following flag may be OR-ed into the result: 245 246 PR_SME_VL_INHERIT 247 248 Vector length will be inherited across execve(). 249 250 There is no way to determine whether there is an outstanding deferred 251 vector length change (which would only normally be the case between a 252 fork() or vfork() and the corresponding execve() in typical use). 253 254 To extract the vector length from the result, bitwise and it with 255 PR_SME_VL_LEN_MASK. 256 257 Return value: a nonnegative value on success, or a negative value on error: 258 EINVAL: SME not supported. 259 260 2617. ptrace extensions 262--------------------- 263 264* A new regset NT_ARM_SSVE is defined for access to streaming mode SVE 265 state via PTRACE_GETREGSET and PTRACE_SETREGSET, this is documented in 266 sve.rst. 267 268* A new regset NT_ARM_ZA is defined for ZA state for access to ZA state via 269 PTRACE_GETREGSET and PTRACE_SETREGSET. 270 271 Refer to [2] for definitions. 272 273The regset data starts with struct user_za_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 streaming vector length, in bytes. 293 294 max_vl 295 296 Maximum possible streaming vector length for the target thread. 297 298 flags 299 300 Zero or more of the following flags, which have the same 301 meaning and behaviour as the corresponding PR_SET_VL_* flags: 302 303 SME_PT_VL_INHERIT 304 305 SME_PT_VL_ONEXEC (SETREGSET only). 306 307* The effects of changing the vector length and/or flags are equivalent to 308 those documented for PR_SME_SET_VL. 309 310 The caller must make a further GETREGSET call if it needs to know what VL is 311 actually set by SETREGSET, unless is it known in advance that the requested 312 VL is supported. 313 314* The size and layout of the payload depends on the header fields. The 315 ZA_PT_ZA*() macros are provided to facilitate access to the data. 316 317* In either case, for SETREGSET it is permissible to omit the payload, in which 318 case the vector length and flags are changed and PSTATE.ZA is set to 0 319 (along with any consequences of those changes). If a payload is provided 320 then PSTATE.ZA will be set to 1. 321 322* For SETREGSET, if the requested VL is not supported, the effect will be the 323 same as if the payload were omitted, except that an EIO error is reported. 324 No attempt is made to translate the payload data to the correct layout 325 for the vector length actually set. It is up to the caller to translate the 326 payload layout for the actual VL and retry. 327 328* The effect of writing a partial, incomplete payload is unspecified. 329 330* A new regset NT_ARM_ZT is defined for access to ZTn state via 331 PTRACE_GETREGSET and PTRACE_SETREGSET. 332 333* The NT_ARM_ZT regset consists of a single 512 bit register. 334 335* When PSTATE.ZA==0 reads of NT_ARM_ZT will report all bits of ZTn as 0. 336 337* Writes to NT_ARM_ZT will set PSTATE.ZA to 1. 338 339* If any register data is provided along with SME_PT_VL_ONEXEC then the 340 registers data will be interpreted with the current vector length, not 341 the vector length configured for use on exec. 342 343 3448. ELF coredump extensions 345--------------------------- 346 347* NT_ARM_SSVE notes will be added to each coredump for 348 each thread of the dumped process. The contents will be equivalent to the 349 data that would have been read if a PTRACE_GETREGSET of the corresponding 350 type were executed for each thread when the coredump was generated. 351 352* A NT_ARM_ZA note will be added to each coredump for each thread of the 353 dumped process. The contents will be equivalent to the data that would have 354 been read if a PTRACE_GETREGSET of NT_ARM_ZA were executed for each thread 355 when the coredump was generated. 356 357* A NT_ARM_ZT note will be added to each coredump for each thread of the 358 dumped process. The contents will be equivalent to the data that would have 359 been read if a PTRACE_GETREGSET of NT_ARM_ZT were executed for each thread 360 when the coredump was generated. 361 362* The NT_ARM_TLS note will be extended to two registers, the second register 363 will contain TPIDR2_EL0 on systems that support SME and will be read as 364 zero with writes ignored otherwise. 365 3669. System runtime configuration 367-------------------------------- 368 369* To mitigate the ABI impact of expansion of the signal frame, a policy 370 mechanism is provided for administrators, distro maintainers and developers 371 to set the default vector length for userspace processes: 372 373/proc/sys/abi/sme_default_vector_length 374 375 Writing the text representation of an integer to this file sets the system 376 default vector length to the specified value rounded to a supported value 377 using the same rules as for setting vector length via PR_SME_SET_VL. 378 379 The result can be determined by reopening the file and reading its 380 contents. 381 382 At boot, the default vector length is initially set to 32 or the maximum 383 supported vector length, whichever is smaller and supported. This 384 determines the initial vector length of the init process (PID 1). 385 386 Reading this file returns the current system default vector length. 387 388* At every execve() call, the new vector length of the new process is set to 389 the system default vector length, unless 390 391 * PR_SME_VL_INHERIT (or equivalently SME_PT_VL_INHERIT) is set for the 392 calling thread, or 393 394 * a deferred vector length change is pending, established via the 395 PR_SME_SET_VL_ONEXEC flag (or SME_PT_VL_ONEXEC). 396 397* Modifying the system default vector length does not affect the vector length 398 of any existing process or thread that does not make an execve() call. 399 400 401Appendix A. SME programmer's model (informative) 402================================================= 403 404This section provides a minimal description of the additions made by SME to the 405ARMv8-A programmer's model that are relevant to this document. 406 407Note: This section is for information only and not intended to be complete or 408to replace any architectural specification. 409 410A.1. Registers 411--------------- 412 413In A64 state, SME adds the following: 414 415* A new mode, streaming mode, in which a subset of the normal FPSIMD and SVE 416 features are available. When supported EL0 software may enter and leave 417 streaming mode at any time. 418 419 For best system performance it is strongly encouraged for software to enable 420 streaming mode only when it is actively being used. 421 422* A new vector length controlling the size of ZA and the Z registers when in 423 streaming mode, separately to the vector length used for SVE when not in 424 streaming mode. There is no requirement that either the currently selected 425 vector length or the set of vector lengths supported for the two modes in 426 a given system have any relationship. The streaming mode vector length 427 is referred to as SVL. 428 429* A new ZA matrix register. This is a square matrix of SVLxSVL bits. Most 430 operations on ZA require that streaming mode be enabled but ZA can be 431 enabled without streaming mode in order to load, save and retain data. 432 433 For best system performance it is strongly encouraged for software to enable 434 ZA only when it is actively being used. 435 436* A new ZT0 register is introduced when SME2 is present. This is a 512 bit 437 register which is accessible when PSTATE.ZA is set, as ZA itself is. 438 439* Two new 1 bit fields in PSTATE which may be controlled via the SMSTART and 440 SMSTOP instructions or by access to the SVCR system register: 441 442 * PSTATE.ZA, if this is 1 then the ZA matrix is accessible and has valid 443 data while if it is 0 then ZA can not be accessed. When PSTATE.ZA is 444 changed from 0 to 1 all bits in ZA are cleared. 445 446 * PSTATE.SM, if this is 1 then the PE is in streaming mode. When the value 447 of PSTATE.SM is changed then it is implementation defined if the subset 448 of the floating point register bits valid in both modes may be retained. 449 Any other bits will be cleared. 450 451 452References 453========== 454 455[1] arch/arm64/include/uapi/asm/sigcontext.h 456 AArch64 Linux signal ABI definitions 457 458[2] arch/arm64/include/uapi/asm/ptrace.h 459 AArch64 Linux ptrace ABI definitions 460 461[3] Documentation/arch/arm64/cpu-feature-registers.rst 462