0001 Using XSTATE features in user space applications
0002 ================================================
0003
0004 The x86 architecture supports floating-point extensions which are
0005 enumerated via CPUID. Applications consult CPUID and use XGETBV to
0006 evaluate which features have been enabled by the kernel XCR0.
0007
0008 Up to AVX-512 and PKRU states, these features are automatically enabled by
0009 the kernel if available. Features like AMX TILE_DATA (XSTATE component 18)
0010 are enabled by XCR0 as well, but the first use of related instruction is
0011 trapped by the kernel because by default the required large XSTATE buffers
0012 are not allocated automatically.
0013
0014 Using dynamically enabled XSTATE features in user space applications
0015 --------------------------------------------------------------------
0016
0017 The kernel provides an arch_prctl(2) based mechanism for applications to
0018 request the usage of such features. The arch_prctl(2) options related to
0019 this are:
0020
0021 -ARCH_GET_XCOMP_SUPP
0022
0023 arch_prctl(ARCH_GET_XCOMP_SUPP, &features);
0024
0025 ARCH_GET_XCOMP_SUPP stores the supported features in userspace storage of
0026 type uint64_t. The second argument is a pointer to that storage.
0027
0028 -ARCH_GET_XCOMP_PERM
0029
0030 arch_prctl(ARCH_GET_XCOMP_PERM, &features);
0031
0032 ARCH_GET_XCOMP_PERM stores the features for which the userspace process
0033 has permission in userspace storage of type uint64_t. The second argument
0034 is a pointer to that storage.
0035
0036 -ARCH_REQ_XCOMP_PERM
0037
0038 arch_prctl(ARCH_REQ_XCOMP_PERM, feature_nr);
0039
0040 ARCH_REQ_XCOMP_PERM allows to request permission for a dynamically enabled
0041 feature or a feature set. A feature set can be mapped to a facility, e.g.
0042 AMX, and can require one or more XSTATE components to be enabled.
0043
0044 The feature argument is the number of the highest XSTATE component which
0045 is required for a facility to work.
0046
0047 When requesting permission for a feature, the kernel checks the
0048 availability. The kernel ensures that sigaltstacks in the process's tasks
0049 are large enough to accommodate the resulting large signal frame. It
0050 enforces this both during ARCH_REQ_XCOMP_SUPP and during any subsequent
0051 sigaltstack(2) calls. If an installed sigaltstack is smaller than the
0052 resulting sigframe size, ARCH_REQ_XCOMP_SUPP results in -ENOSUPP. Also,
0053 sigaltstack(2) results in -ENOMEM if the requested altstack is too small
0054 for the permitted features.
0055
0056 Permission, when granted, is valid per process. Permissions are inherited
0057 on fork(2) and cleared on exec(3).
0058
0059 The first use of an instruction related to a dynamically enabled feature is
0060 trapped by the kernel. The trap handler checks whether the process has
0061 permission to use the feature. If the process has no permission then the
0062 kernel sends SIGILL to the application. If the process has permission then
0063 the handler allocates a larger xstate buffer for the task so the large
0064 state can be context switched. In the unlikely cases that the allocation
0065 fails, the kernel sends SIGSEGV.
0066
0067 Dynamic features in signal frames
0068 ---------------------------------
0069
0070 Dynamcally enabled features are not written to the signal frame upon signal
0071 entry if the feature is in its initial configuration. This differs from
0072 non-dynamic features which are always written regardless of their
0073 configuration. Signal handlers can examine the XSAVE buffer's XSTATE_BV
0074 field to determine if a features was written.
