xstate.rst (3290B)
1Using XSTATE features in user space applications 2================================================ 3 4The x86 architecture supports floating-point extensions which are 5enumerated via CPUID. Applications consult CPUID and use XGETBV to 6evaluate which features have been enabled by the kernel XCR0. 7 8Up to AVX-512 and PKRU states, these features are automatically enabled by 9the kernel if available. Features like AMX TILE_DATA (XSTATE component 18) 10are enabled by XCR0 as well, but the first use of related instruction is 11trapped by the kernel because by default the required large XSTATE buffers 12are not allocated automatically. 13 14Using dynamically enabled XSTATE features in user space applications 15-------------------------------------------------------------------- 16 17The kernel provides an arch_prctl(2) based mechanism for applications to 18request the usage of such features. The arch_prctl(2) options related to 19this are: 20 21-ARCH_GET_XCOMP_SUPP 22 23 arch_prctl(ARCH_GET_XCOMP_SUPP, &features); 24 25 ARCH_GET_XCOMP_SUPP stores the supported features in userspace storage of 26 type uint64_t. The second argument is a pointer to that storage. 27 28-ARCH_GET_XCOMP_PERM 29 30 arch_prctl(ARCH_GET_XCOMP_PERM, &features); 31 32 ARCH_GET_XCOMP_PERM stores the features for which the userspace process 33 has permission in userspace storage of type uint64_t. The second argument 34 is a pointer to that storage. 35 36-ARCH_REQ_XCOMP_PERM 37 38 arch_prctl(ARCH_REQ_XCOMP_PERM, feature_nr); 39 40 ARCH_REQ_XCOMP_PERM allows to request permission for a dynamically enabled 41 feature or a feature set. A feature set can be mapped to a facility, e.g. 42 AMX, and can require one or more XSTATE components to be enabled. 43 44 The feature argument is the number of the highest XSTATE component which 45 is required for a facility to work. 46 47When requesting permission for a feature, the kernel checks the 48availability. The kernel ensures that sigaltstacks in the process's tasks 49are large enough to accommodate the resulting large signal frame. It 50enforces this both during ARCH_REQ_XCOMP_SUPP and during any subsequent 51sigaltstack(2) calls. If an installed sigaltstack is smaller than the 52resulting sigframe size, ARCH_REQ_XCOMP_SUPP results in -ENOSUPP. Also, 53sigaltstack(2) results in -ENOMEM if the requested altstack is too small 54for the permitted features. 55 56Permission, when granted, is valid per process. Permissions are inherited 57on fork(2) and cleared on exec(3). 58 59The first use of an instruction related to a dynamically enabled feature is 60trapped by the kernel. The trap handler checks whether the process has 61permission to use the feature. If the process has no permission then the 62kernel sends SIGILL to the application. If the process has permission then 63the handler allocates a larger xstate buffer for the task so the large 64state can be context switched. In the unlikely cases that the allocation 65fails, the kernel sends SIGSEGV. 66 67Dynamic features in signal frames 68--------------------------------- 69 70Dynamcally enabled features are not written to the signal frame upon signal 71entry if the feature is in its initial configuration. This differs from 72non-dynamic features which are always written regardless of their 73configuration. Signal handlers can examine the XSAVE buffer's XSTATE_BV 74field to determine if a features was written.