xref: /openbmc/linux/Documentation/arch/arm64/sme.rst (revision c3651fef)
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 TPIDR2_EL0 is preserved unless CLONE_SETTLS is specified,
73  in which case it is set to 0.
74
752.  Vector lengths
76------------------
77
78SME defines a second vector length similar to the SVE vector length which is
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.  Sharing of streaming and non-streaming mode SVE state
85---------------------------------------------------------
86
87It is implementation defined which if any parts of the SVE state are shared
88between streaming and non-streaming modes.  When switching between modes
89via software interfaces such as ptrace if no register content is provided as
90part of switching no state will be assumed to be shared and everything will
91be zeroed.
92
93
944.  System call behaviour
95-------------------------
96
97* On syscall PSTATE.ZA is preserved, if PSTATE.ZA==1 then the contents of the
98  ZA matrix and ZTn (if present) are preserved.
99
100* On syscall PSTATE.SM will be cleared and the SVE registers will be handled
101  as per the standard SVE ABI.
102
103* None of the SVE registers, ZA or ZTn are used to pass arguments to
104  or receive results from any syscall.
105
106* On process creation (eg, clone()) the newly created process will have
107  PSTATE.SM cleared.
108
109* All other SME state of a thread, including the currently configured vector
110  length, the state of the PR_SME_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
1155.  Signal handling
116-------------------
117
118* Signal handlers are invoked with streaming mode and ZA disabled.
119
120* A new signal frame record TPIDR2_MAGIC is added formatted as a struct
121  tpidr2_context to allow access to TPIDR2_EL0 from signal handlers.
122
123* A new signal frame record za_context encodes the ZA register contents on
124  signal delivery. [1]
125
126* The signal frame record for ZA always contains basic metadata, in particular
127  the thread's vector length (in za_context.vl).
128
129* The ZA matrix may or may not be included in the record, depending on
130  the value of PSTATE.ZA.  The registers are present if and only if:
131  za_context.head.size >= ZA_SIG_CONTEXT_SIZE(sve_vq_from_vl(za_context.vl))
132  in which case PSTATE.ZA == 1.
133
134* If matrix data is present, the remainder of the record has a vl-dependent
135  size and layout.  Macros ZA_SIG_* are defined [1] to facilitate access to
136  them.
137
138* The matrix is stored as a series of horizontal vectors in the same format as
139  is used for SVE vectors.
140
141* If the ZA context is too big to fit in sigcontext.__reserved[], then extra
142  space is allocated on the stack, an extra_context record is written in
143  __reserved[] referencing this space.  za_context is then written in the
144  extra space.  Refer to [1] for further details about this mechanism.
145
146* If ZTn is supported and PSTATE.ZA==1 then a signal frame record for ZTn will
147  be generated.
148
149* The signal record for ZTn has magic ZT_MAGIC (0x5a544e01) and consists of a
150  standard signal frame header followed by a struct zt_context specifying
151  the number of ZTn registers supported by the system, then zt_context.nregs
152  blocks of 64 bytes of data per register.
153
154
1555.  Signal return
156-----------------
157
158When returning from a signal handler:
159
160* If there is no za_context record in the signal frame, or if the record is
161  present but contains no register data as described in the previous section,
162  then ZA is disabled.
163
164* If za_context is present in the signal frame and contains matrix data then
165  PSTATE.ZA is set to 1 and ZA is populated with the specified data.
166
167* The vector length cannot be changed via signal return.  If za_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* If ZTn is not supported or PSTATE.ZA==0 then it is illegal to have a
172  signal frame record for ZTn, resulting in a forced SIGSEGV.
173
174
1756.  prctl extensions
176--------------------
177
178Some new prctl() calls are added to allow programs to manage the SME vector
179length:
180
181prctl(PR_SME_SET_VL, unsigned long arg)
182
183    Sets the vector length of the calling thread and related flags, where
184    arg == vl | flags.  Other threads of the calling process are unaffected.
185
186    vl is the desired vector length, where sve_vl_valid(vl) must be true.
187
188    flags:
189
190	PR_SME_VL_INHERIT
191
192	    Inherit the current vector length across execve().  Otherwise, the
193	    vector length is reset to the system default at execve().  (See
194	    Section 9.)
195
196	PR_SME_SET_VL_ONEXEC
197
198	    Defer the requested vector length change until the next execve()
199	    performed by this thread.
200
201	    The effect is equivalent to implicit execution of the following
202	    call immediately after the next execve() (if any) by the thread:
203
204		prctl(PR_SME_SET_VL, arg & ~PR_SME_SET_VL_ONEXEC)
205
206	    This allows launching of a new program with a different vector
207	    length, while avoiding runtime side effects in the caller.
208
209	    Without PR_SME_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: SME 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_SME_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_SME_GET_VL.  The vector length reported in this value is the new
232      current vector length for this thread if PR_SME_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 ZA, ZTn, P0..P15, FFR and all
238      bits of Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become
239      unspecified, including both streaming and non-streaming SVE state.
240      Calling PR_SME_SET_VL with vl equal to the thread's current vector
241      length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag,
242      does not constitute a change to the vector length for this purpose.
243
244    * Changing the vector length causes PSTATE.ZA and PSTATE.SM to be cleared.
245      Calling PR_SME_SET_VL with vl equal to the thread's current vector
246      length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag,
247      does not constitute a change to the vector length for this purpose.
248
249
250prctl(PR_SME_GET_VL)
251
252    Gets the vector length of the calling thread.
253
254    The following flag may be OR-ed into the result:
255
256	PR_SME_VL_INHERIT
257
258	    Vector length will be inherited across execve().
259
260    There is no way to determine whether there is an outstanding deferred
261    vector length change (which would only normally be the case between a
262    fork() or vfork() and the corresponding execve() in typical use).
263
264    To extract the vector length from the result, bitwise and it with
265    PR_SME_VL_LEN_MASK.
266
267    Return value: a nonnegative value on success, or a negative value on error:
268	EINVAL: SME not supported.
269
270
2717.  ptrace extensions
272---------------------
273
274* A new regset NT_ARM_SSVE is defined for access to streaming mode SVE
275  state via PTRACE_GETREGSET and  PTRACE_SETREGSET, this is documented in
276  sve.rst.
277
278* A new regset NT_ARM_ZA is defined for ZA state for access to ZA state via
279  PTRACE_GETREGSET and PTRACE_SETREGSET.
280
281  Refer to [2] for definitions.
282
283The regset data starts with struct user_za_header, containing:
284
285    size
286
287	Size of the complete regset, in bytes.
288	This depends on vl and possibly on other things in the future.
289
290	If a call to PTRACE_GETREGSET requests less data than the value of
291	size, the caller can allocate a larger buffer and retry in order to
292	read the complete regset.
293
294    max_size
295
296	Maximum size in bytes that the regset can grow to for the target
297	thread.  The regset won't grow bigger than this even if the target
298	thread changes its vector length etc.
299
300    vl
301
302	Target thread's current streaming vector length, in bytes.
303
304    max_vl
305
306	Maximum possible streaming vector length for the target thread.
307
308    flags
309
310	Zero or more of the following flags, which have the same
311	meaning and behaviour as the corresponding PR_SET_VL_* flags:
312
313	    SME_PT_VL_INHERIT
314
315	    SME_PT_VL_ONEXEC (SETREGSET only).
316
317* The effects of changing the vector length and/or flags are equivalent to
318  those documented for PR_SME_SET_VL.
319
320  The caller must make a further GETREGSET call if it needs to know what VL is
321  actually set by SETREGSET, unless is it known in advance that the requested
322  VL is supported.
323
324* The size and layout of the payload depends on the header fields.  The
325  ZA_PT_ZA*() macros are provided to facilitate access to the data.
326
327* In either case, for SETREGSET it is permissible to omit the payload, in which
328  case the vector length and flags are changed and PSTATE.ZA is set to 0
329  (along with any consequences of those changes).  If a payload is provided
330  then PSTATE.ZA will be set to 1.
331
332* For SETREGSET, if the requested VL is not supported, the effect will be the
333  same as if the payload were omitted, except that an EIO error is reported.
334  No attempt is made to translate the payload data to the correct layout
335  for the vector length actually set.  It is up to the caller to translate the
336  payload layout for the actual VL and retry.
337
338* The effect of writing a partial, incomplete payload is unspecified.
339
340* A new regset NT_ARM_ZT is defined for access to ZTn state via
341  PTRACE_GETREGSET and PTRACE_SETREGSET.
342
343* The NT_ARM_ZT regset consists of a single 512 bit register.
344
345* When PSTATE.ZA==0 reads of NT_ARM_ZT will report all bits of ZTn as 0.
346
347* Writes to NT_ARM_ZT will set PSTATE.ZA to 1.
348
349
3508.  ELF coredump extensions
351---------------------------
352
353* NT_ARM_SSVE notes will be added to each coredump for
354  each thread of the dumped process.  The contents will be equivalent to the
355  data that would have been read if a PTRACE_GETREGSET of the corresponding
356  type were executed for each thread when the coredump was generated.
357
358* A NT_ARM_ZA note will be added to each coredump for each thread of the
359  dumped process.  The contents will be equivalent to the data that would have
360  been read if a PTRACE_GETREGSET of NT_ARM_ZA were executed for each thread
361  when the coredump was generated.
362
363* A NT_ARM_ZT note will be added to each coredump for each thread of the
364  dumped process.  The contents will be equivalent to the data that would have
365  been read if a PTRACE_GETREGSET of NT_ARM_ZT were executed for each thread
366  when the coredump was generated.
367
368* The NT_ARM_TLS note will be extended to two registers, the second register
369  will contain TPIDR2_EL0 on systems that support SME and will be read as
370  zero with writes ignored otherwise.
371
3729.  System runtime configuration
373--------------------------------
374
375* To mitigate the ABI impact of expansion of the signal frame, a policy
376  mechanism is provided for administrators, distro maintainers and developers
377  to set the default vector length for userspace processes:
378
379/proc/sys/abi/sme_default_vector_length
380
381    Writing the text representation of an integer to this file sets the system
382    default vector length to the specified value, unless the value is greater
383    than the maximum vector length supported by the system in which case the
384    default vector length is set to that maximum.
385
386    The result can be determined by reopening the file and reading its
387    contents.
388
389    At boot, the default vector length is initially set to 32 or the maximum
390    supported vector length, whichever is smaller and supported.  This
391    determines the initial vector length of the init process (PID 1).
392
393    Reading this file returns the current system default vector length.
394
395* At every execve() call, the new vector length of the new process is set to
396  the system default vector length, unless
397
398    * PR_SME_VL_INHERIT (or equivalently SME_PT_VL_INHERIT) is set for the
399      calling thread, or
400
401    * a deferred vector length change is pending, established via the
402      PR_SME_SET_VL_ONEXEC flag (or SME_PT_VL_ONEXEC).
403
404* Modifying the system default vector length does not affect the vector length
405  of any existing process or thread that does not make an execve() call.
406
407
408Appendix A.  SME programmer's model (informative)
409=================================================
410
411This section provides a minimal description of the additions made by SME to the
412ARMv8-A programmer's model that are relevant to this document.
413
414Note: This section is for information only and not intended to be complete or
415to replace any architectural specification.
416
417A.1.  Registers
418---------------
419
420In A64 state, SME adds the following:
421
422* A new mode, streaming mode, in which a subset of the normal FPSIMD and SVE
423  features are available.  When supported EL0 software may enter and leave
424  streaming mode at any time.
425
426  For best system performance it is strongly encouraged for software to enable
427  streaming mode only when it is actively being used.
428
429* A new vector length controlling the size of ZA and the Z registers when in
430  streaming mode, separately to the vector length used for SVE when not in
431  streaming mode.  There is no requirement that either the currently selected
432  vector length or the set of vector lengths supported for the two modes in
433  a given system have any relationship.  The streaming mode vector length
434  is referred to as SVL.
435
436* A new ZA matrix register.  This is a square matrix of SVLxSVL bits.  Most
437  operations on ZA require that streaming mode be enabled but ZA can be
438  enabled without streaming mode in order to load, save and retain data.
439
440  For best system performance it is strongly encouraged for software to enable
441  ZA only when it is actively being used.
442
443* A new ZT0 register is introduced when SME2 is present. This is a 512 bit
444  register which is accessible when PSTATE.ZA is set, as ZA itself is.
445
446* Two new 1 bit fields in PSTATE which may be controlled via the SMSTART and
447  SMSTOP instructions or by access to the SVCR system register:
448
449  * PSTATE.ZA, if this is 1 then the ZA matrix is accessible and has valid
450    data while if it is 0 then ZA can not be accessed.  When PSTATE.ZA is
451    changed from 0 to 1 all bits in ZA are cleared.
452
453  * PSTATE.SM, if this is 1 then the PE is in streaming mode.  When the value
454    of PSTATE.SM is changed then it is implementation defined if the subset
455    of the floating point register bits valid in both modes may be retained.
456    Any other bits will be cleared.
457
458
459References
460==========
461
462[1] arch/arm64/include/uapi/asm/sigcontext.h
463    AArch64 Linux signal ABI definitions
464
465[2] arch/arm64/include/uapi/asm/ptrace.h
466    AArch64 Linux ptrace ABI definitions
467
468[3] Documentation/arch/arm64/cpu-feature-registers.rst
469