1 ==============================================
2 Scalable Matrix Extension support for AArch64
3 ==============================================
4
5 This document outlines briefly the interface p
6 order to support use of the ARM Scalable Matri
7
8 This is an outline of the most important featu
9 intended to be exhaustive. It should be read
10 documentation in sve.rst which provides detail
11 included in SME.
12
13 This document does not aim to describe the SME
14 model. To aid understanding, a minimal descri
15 model features for SME is included in Appendix
16
17
18 1. General
19 -----------
20
21 * PSTATE.SM, PSTATE.ZA, the streaming mode vec
22 present) ZTn register state and TPIDR2_EL0 a
23
24 * The presence of SME is reported to userspace
25 AT_HWCAP2 entry. Presence of this flag impl
26 instructions and registers, and the Linux-sp
27 described in this document. SME is reported
28
29 * The presence of SME2 is reported to userspac
30 aux vector AT_HWCAP2 entry. Presence of thi
31 the SME2 instructions and ZT0, and the Linux
32 described in this document. SME2 is reporte
33
34 * Support for the execution of SME instruction
35 detected by reading the CPU ID register ID_A
36 instruction, and checking that the value of
37
38 It does not guarantee the presence of the sy
39 following sections: software that needs to v
40 present must check for HWCAP2_SME instead.
41
42 * There are a number of optional SME features,
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 S
55
56 These extensions are also reported via the C
57 which userspace can read using an MRS instru
58 cpu-feature-registers.txt for details.
59
60 * Debuggers should restrict themselves to inte
61 NT_ARM_SVE, NT_ARM_SSVE, NT_ARM_ZA and NT_AR
62 way of detecting support for these regsets i
63 first and then attempt a
64
65 ptrace(PTRACE_GETREGSET, pid, NT_ARM_<
66
67 * Whenever ZA register values are exchanged in
68 the kernel, the register value is encoded in
69 vectors from 0 to VL/8-1 stored in the same
70 used for SVE vectors.
71
72 * On thread creation TPIDR2_EL0 is preserved u
73 in which case it is set to 0.
74
75 2. Vector lengths
76 ------------------
77
78 SME defines a second vector length similar to
79 controls the size of the streaming mode SVE ve
80 The ZA matrix is square with each side having
81 mode SVE vector.
82
83
84 3. Sharing of streaming and non-streaming mod
85 ----------------------------------------------
86
87 It is implementation defined which if any part
88 between streaming and non-streaming modes. Wh
89 via software interfaces such as ptrace if no r
90 part of switching no state will be assumed to
91 be zeroed.
92
93
94 4. System call behaviour
95 -------------------------
96
97 * On syscall PSTATE.ZA is preserved, if PSTATE
98 ZA matrix and ZTn (if present) are preserved
99
100 * On syscall PSTATE.SM will be cleared and the
101 as per the standard SVE ABI.
102
103 * None of the SVE registers, ZA or ZTn are use
104 or receive results from any syscall.
105
106 * On process creation (eg, clone()) the newly
107 PSTATE.SM cleared.
108
109 * All other SME state of a thread, including t
110 length, the state of the PR_SME_VL_INHERIT f
111 length (if any), is preserved across all sys
112 exceptions for execve() described in section
113
114
115 5. Signal handling
116 -------------------
117
118 * Signal handlers are invoked with streaming m
119
120 * A new signal frame record TPIDR2_MAGIC is ad
121 tpidr2_context to allow access to TPIDR2_EL0
122
123 * A new signal frame record za_context encodes
124 signal delivery. [1]
125
126 * The signal frame record for ZA always contai
127 the thread's vector length (in za_context.vl
128
129 * The ZA matrix may or may not be included in
130 the value of PSTATE.ZA. The registers are p
131 za_context.head.size >= ZA_SIG_CONTEXT_SIZE(
132 in which case PSTATE.ZA == 1.
133
134 * If matrix data is present, the remainder of
135 size and layout. Macros ZA_SIG_* are define
136 them.
137
138 * The matrix is stored as a series of horizont
139 is used for SVE vectors.
140
141 * If the ZA context is too big to fit in sigco
142 space is allocated on the stack, an extra_co
143 __reserved[] referencing this space. za_con
144 extra space. Refer to [1] for further detai
145
146 * If ZTn is supported and PSTATE.ZA==1 then a
147 be generated.
148
149 * The signal record for ZTn has magic ZT_MAGIC
150 standard signal frame header followed by a s
151 the number of ZTn registers supported by the
152 blocks of 64 bytes of data per register.
153
154
155 5. Signal return
156 -----------------
157
158 When returning from a signal handler:
159
160 * If there is no za_context record in the sign
161 present but contains no register data as des
162 then ZA is disabled.
163
164 * If za_context is present in the signal frame
165 PSTATE.ZA is set to 1 and ZA is populated wi
166
167 * The vector length cannot be changed via sign
168 the signal frame does not match the current
169 attempt is treated as illegal, resulting in
170
171 * If ZTn is not supported or PSTATE.ZA==0 then
172 signal frame record for ZTn, resulting in a
173
174
175 6. prctl extensions
176 --------------------
177
178 Some new prctl() calls are added to allow prog
179 length:
180
181 prctl(PR_SME_SET_VL, unsigned long arg)
182
183 Sets the vector length of the calling thre
184 arg == vl | flags. Other threads of the c
185
186 vl is the desired vector length, where sve
187
188 flags:
189
190 PR_SME_VL_INHERIT
191
192 Inherit the current vector length
193 vector length is reset to the syst
194 Section 9.)
195
196 PR_SME_SET_VL_ONEXEC
197
198 Defer the requested vector length
199 performed by this thread.
200
201 The effect is equivalent to implic
202 call immediately after the next ex
203
204 prctl(PR_SME_SET_VL, arg & ~PR
205
206 This allows launching of a new pro
207 length, while avoiding runtime sid
208
209 Without PR_SME_SET_VL_ONEXEC, the
210 immediately.
211
212
213 Return value: a nonnegative on success, or
214 EINVAL: SME not supported, invalid vec
215 invalid flags.
216
217
218 On success:
219
220 * Either the calling thread's vector lengt
221 to be applied at the next execve() by th
222 PR_SME_SET_VL_ONEXEC is present in arg),
223 supported by the system that is less tha
224 SVE_VL_MAX, the value set will be the la
225 system.
226
227 * Any previously outstanding deferred vect
228 thread is cancelled.
229
230 * The returned value describes the resulti
231 PR_SME_GET_VL. The vector length report
232 current vector length for this thread if
233 present in arg; otherwise, the reported
234 vector length that will be applied at th
235 thread.
236
237 * Changing the vector length causes all of
238 bits of Z0..Z31 except for Z0 bits [127:
239 unspecified, including both streaming an
240 Calling PR_SME_SET_VL with vl equal to t
241 length, or calling PR_SME_SET_VL with th
242 does not constitute a change to the vect
243
244 * Changing the vector length causes PSTATE
245 Calling PR_SME_SET_VL with vl equal to t
246 length, or calling PR_SME_SET_VL with th
247 does not constitute a change to the vect
248
249
250 prctl(PR_SME_GET_VL)
251
252 Gets the vector length of the calling thre
253
254 The following flag may be OR-ed into the r
255
256 PR_SME_VL_INHERIT
257
258 Vector length will be inherited ac
259
260 There is no way to determine whether there
261 vector length change (which would only nor
262 fork() or vfork() and the corresponding ex
263
264 To extract the vector length from the resu
265 PR_SME_VL_LEN_MASK.
266
267 Return value: a nonnegative value on succe
268 EINVAL: SME not supported.
269
270
271 7. ptrace extensions
272 ---------------------
273
274 * A new regset NT_ARM_SSVE is defined for acce
275 state via PTRACE_GETREGSET and PTRACE_SETRE
276 sve.rst.
277
278 * A new regset NT_ARM_ZA is defined for ZA sta
279 PTRACE_GETREGSET and PTRACE_SETREGSET.
280
281 Refer to [2] for definitions.
282
283 The regset data starts with struct user_za_hea
284
285 size
286
287 Size of the complete regset, in bytes.
288 This depends on vl and possibly on oth
289
290 If a call to PTRACE_GETREGSET requests
291 size, the caller can allocate a larger
292 read the complete regset.
293
294 max_size
295
296 Maximum size in bytes that the regset
297 thread. The regset won't grow bigger
298 thread changes its vector length etc.
299
300 vl
301
302 Target thread's current streaming vect
303
304 max_vl
305
306 Maximum possible streaming vector leng
307
308 flags
309
310 Zero or more of the following flags, w
311 meaning and behaviour as the correspon
312
313 SME_PT_VL_INHERIT
314
315 SME_PT_VL_ONEXEC (SETREGSET only).
316
317 * The effects of changing the vector length an
318 those documented for PR_SME_SET_VL.
319
320 The caller must make a further GETREGSET cal
321 actually set by SETREGSET, unless is it know
322 VL is supported.
323
324 * The size and layout of the payload depends o
325 ZA_PT_ZA*() macros are provided to facilitat
326
327 * In either case, for SETREGSET it is permissi
328 case the vector length and flags are changed
329 (along with any consequences of those change
330 then PSTATE.ZA will be set to 1.
331
332 * For SETREGSET, if the requested VL is not su
333 same as if the payload were omitted, except
334 No attempt is made to translate the payload
335 for the vector length actually set. It is u
336 payload layout for the actual VL and retry.
337
338 * The effect of writing a partial, incomplete
339
340 * A new regset NT_ARM_ZT is defined for access
341 PTRACE_GETREGSET and PTRACE_SETREGSET.
342
343 * The NT_ARM_ZT regset consists of a single 51
344
345 * When PSTATE.ZA==0 reads of NT_ARM_ZT will re
346
347 * Writes to NT_ARM_ZT will set PSTATE.ZA to 1.
348
349
350 8. ELF coredump extensions
351 ---------------------------
352
353 * NT_ARM_SSVE notes will be added to each core
354 each thread of the dumped process. The cont
355 data that would have been read if a PTRACE_G
356 type were executed for each thread when the
357
358 * A NT_ARM_ZA note will be added to each cored
359 dumped process. The contents will be equiva
360 been read if a PTRACE_GETREGSET of NT_ARM_ZA
361 when the coredump was generated.
362
363 * A NT_ARM_ZT note will be added to each cored
364 dumped process. The contents will be equiva
365 been read if a PTRACE_GETREGSET of NT_ARM_ZT
366 when the coredump was generated.
367
368 * The NT_ARM_TLS note will be extended to two
369 will contain TPIDR2_EL0 on systems that supp
370 zero with writes ignored otherwise.
371
372 9. System runtime configuration
373 --------------------------------
374
375 * To mitigate the ABI impact of expansion of t
376 mechanism is provided for administrators, di
377 to set the default vector length for userspa
378
379 /proc/sys/abi/sme_default_vector_length
380
381 Writing the text representation of an inte
382 default vector length to the specified val
383 using the same rules as for setting vector
384
385 The result can be determined by reopening
386 contents.
387
388 At boot, the default vector length is init
389 supported vector length, whichever is smal
390 determines the initial vector length of th
391
392 Reading this file returns the current syst
393
394 * At every execve() call, the new vector lengt
395 the system default vector length, unless
396
397 * PR_SME_VL_INHERIT (or equivalently SME_P
398 calling thread, or
399
400 * a deferred vector length change is pendi
401 PR_SME_SET_VL_ONEXEC flag (or SME_PT_VL_
402
403 * Modifying the system default vector length d
404 of any existing process or thread that does
405
406
407 Appendix A. SME programmer's model (informati
408 ==============================================
409
410 This section provides a minimal description of
411 ARMv8-A programmer's model that are relevant t
412
413 Note: This section is for information only and
414 to replace any architectural specification.
415
416 A.1. Registers
417 ---------------
418
419 In A64 state, SME adds the following:
420
421 * A new mode, streaming mode, in which a subse
422 features are available. When supported EL0
423 streaming mode at any time.
424
425 For best system performance it is strongly e
426 streaming mode only when it is actively bein
427
428 * A new vector length controlling the size of
429 streaming mode, separately to the vector len
430 streaming mode. There is no requirement tha
431 vector length or the set of vector lengths s
432 a given system have any relationship. The s
433 is referred to as SVL.
434
435 * A new ZA matrix register. This is a square
436 operations on ZA require that streaming mode
437 enabled without streaming mode in order to l
438
439 For best system performance it is strongly e
440 ZA only when it is actively being used.
441
442 * A new ZT0 register is introduced when SME2 i
443 register which is accessible when PSTATE.ZA
444
445 * Two new 1 bit fields in PSTATE which may be
446 SMSTOP instructions or by access to the SVCR
447
448 * PSTATE.ZA, if this is 1 then the ZA matrix
449 data while if it is 0 then ZA can not be a
450 changed from 0 to 1 all bits in ZA are cle
451
452 * PSTATE.SM, if this is 1 then the PE is in
453 of PSTATE.SM is changed then it is impleme
454 of the floating point register bits valid
455 Any other bits will be cleared.
456
457
458 References
459 ==========
460
461 [1] arch/arm64/include/uapi/asm/sigcontext.h
462 AArch64 Linux signal ABI definitions
463
464 [2] arch/arm64/include/uapi/asm/ptrace.h
465 AArch64 Linux ptrace ABI definitions
466
467 [3] Documentation/arch/arm64/cpu-feature-regis
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.