1 Using XSTATE features in user space applicatio
2 ==============================================
3
4 The x86 architecture supports floating-point e
5 enumerated via CPUID. Applications consult CPU
6 evaluate which features have been enabled by t
7
8 Up to AVX-512 and PKRU states, these features
9 the kernel if available. Features like AMX TIL
10 are enabled by XCR0 as well, but the first use
11 trapped by the kernel because by default the r
12 are not allocated automatically.
13
14 The purpose for dynamic features
15 --------------------------------
16
17 Legacy userspace libraries often have hard-cod
18 alternate signal stacks, often using MINSIGSTK
19 That stack must be able to store at *least* th
20 kernel sets up before jumping into the signal
21 must include an XSAVE buffer defined by the CP
22
23 However, that means that the size of signal st
24 because different CPUs have differently-sized
25 size of 2KB with existing applications is too
26 like AMX. Instead of universally requiring lar
27 enabling, the kernel can enforce userspace app
28 properly-sized altstacks.
29
30 Using dynamically enabled XSTATE features in u
31 ----------------------------------------------
32
33 The kernel provides an arch_prctl(2) based mec
34 request the usage of such features. The arch_p
35 this are:
36
37 -ARCH_GET_XCOMP_SUPP
38
39 arch_prctl(ARCH_GET_XCOMP_SUPP, &features);
40
41 ARCH_GET_XCOMP_SUPP stores the supported feat
42 type uint64_t. The second argument is a point
43
44 -ARCH_GET_XCOMP_PERM
45
46 arch_prctl(ARCH_GET_XCOMP_PERM, &features);
47
48 ARCH_GET_XCOMP_PERM stores the features for w
49 has permission in userspace storage of type u
50 is a pointer to that storage.
51
52 -ARCH_REQ_XCOMP_PERM
53
54 arch_prctl(ARCH_REQ_XCOMP_PERM, feature_nr);
55
56 ARCH_REQ_XCOMP_PERM allows to request permiss
57 feature or a feature set. A feature set can b
58 AMX, and can require one or more XSTATE compo
59
60 The feature argument is the number of the hig
61 is required for a facility to work.
62
63 When requesting permission for a feature, the
64 availability. The kernel ensures that sigaltst
65 are large enough to accommodate the resulting
66 enforces this both during ARCH_REQ_XCOMP_SUPP
67 sigaltstack(2) calls. If an installed sigaltst
68 resulting sigframe size, ARCH_REQ_XCOMP_SUPP r
69 sigaltstack(2) results in -ENOMEM if the reque
70 for the permitted features.
71
72 Permission, when granted, is valid per process
73 on fork(2) and cleared on exec(3).
74
75 The first use of an instruction related to a d
76 trapped by the kernel. The trap handler checks
77 permission to use the feature. If the process
78 kernel sends SIGILL to the application. If the
79 the handler allocates a larger xstate buffer f
80 state can be context switched. In the unlikely
81 fails, the kernel sends SIGSEGV.
82
83 AMX TILE_DATA enabling example
84 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
85
86 Below is the example of how userspace applicat
87 TILE_DATA dynamically:
88
89 1. The application first needs to query the
90 support::
91
92 #include <asm/prctl.h>
93 #include <sys/syscall.h>
94 #include <stdio.h>
95 #include <unistd.h>
96
97 #ifndef ARCH_GET_XCOMP_SUPP
98 #define ARCH_GET_XCOMP_SUPP 0x1021
99 #endif
100
101 #ifndef ARCH_XCOMP_TILECFG
102 #define ARCH_XCOMP_TILECFG 17
103 #endif
104
105 #ifndef ARCH_XCOMP_TILEDATA
106 #define ARCH_XCOMP_TILEDATA 18
107 #endif
108
109 #define MASK_XCOMP_TILE ((1 << AR
110 (1 << AR
111
112 unsigned long features;
113 long rc;
114
115 ...
116
117 rc = syscall(SYS_arch_prctl, ARCH_GET_
118
119 if (!rc && (features & MASK_XCOMP_TILE
120 printf("AMX is available.\n");
121
122 2. After that, determining support for AMX,
123 explicitly ask permission to use it::
124
125 #ifndef ARCH_REQ_XCOMP_PERM
126 #define ARCH_REQ_XCOMP_PERM 0x1023
127 #endif
128
129 ...
130
131 rc = syscall(SYS_arch_prctl, ARCH_REQ_
132
133 if (!rc)
134 printf("AMX is ready for use.\n");
135
136 Note this example does not include the sigalts
137
138 Dynamic features in signal frames
139 ---------------------------------
140
141 Dynamically enabled features are not written t
142 entry if the feature is in its initial configu
143 non-dynamic features which are always written
144 configuration. Signal handlers can examine th
145 field to determine if a features was written.
146
147 Dynamic features for virtual machines
148 -------------------------------------
149
150 The permission for the guest state component n
151 from the host, as they are exclusive to each o
152 are extended to control the guest permission:
153
154 -ARCH_GET_XCOMP_GUEST_PERM
155
156 arch_prctl(ARCH_GET_XCOMP_GUEST_PERM, &featur
157
158 ARCH_GET_XCOMP_GUEST_PERM is a variant of ARC
159 provides the same semantics and functionality
160 components.
161
162 -ARCH_REQ_XCOMP_GUEST_PERM
163
164 arch_prctl(ARCH_REQ_XCOMP_GUEST_PERM, feature
165
166 ARCH_REQ_XCOMP_GUEST_PERM is a variant of ARC
167 same semantics for the guest permission. Whil
168 functionality, this comes with a constraint.
169 first VCPU is created. Any attempt to change
170 is going to be rejected. So, the permission h
171 first VCPU creation.
172
173 Note that some VMMs may have already establish
174 components. These options are not presumed to
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.