Documentation/x86/xstate.rst

   1 Using XSTATE features in user space applications
   2 ================================================
   3
   4 The x86 architecture supports floating-point extensions which are
   5 enumerated via CPUID. Applications consult CPUID and use XGETBV to
   6 evaluate which features have been enabled by the kernel XCR0.
   7
   8 Up to AVX-512 and PKRU states, these features are automatically enabled by
   9 the kernel if available. Features like AMX TILE_DATA (XSTATE component 18)
  10 are enabled by XCR0 as well, but the first use of related instruction is
  11 trapped by the kernel because by default the required large XSTATE buffers
  12 are not allocated automatically.
  13
  14 Using dynamically enabled XSTATE features in user space applications
  15 --------------------------------------------------------------------
  16
  17 The kernel provides an arch_prctl(2) based mechanism for applications to
  18 request the usage of such features. The arch_prctl(2) options related to
  19 this 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
  47 When requesting permission for a feature, the kernel checks the
  48 availability. The kernel ensures that sigaltstacks in the process's tasks
  49 are large enough to accommodate the resulting large signal frame. It
  50 enforces this both during ARCH_REQ_XCOMP_SUPP and during any subsequent
  51 sigaltstack(2) calls. If an installed sigaltstack is smaller than the
  52 resulting sigframe size, ARCH_REQ_XCOMP_SUPP results in -ENOSUPP. Also,
  53 sigaltstack(2) results in -ENOMEM if the requested altstack is too small
  54 for the permitted features.
  55
  56 Permission, when granted, is valid per process. Permissions are inherited
  57 on fork(2) and cleared on exec(3).
  58
  59 The first use of an instruction related to a dynamically enabled feature is
  60 trapped by the kernel. The trap handler checks whether the process has
  61 permission to use the feature. If the process has no permission then the
  62 kernel sends SIGILL to the application. If the process has permission then
  63 the handler allocates a larger xstate buffer for the task so the large
  64 state can be context switched. In the unlikely cases that the allocation
  65 fails, the kernel sends SIGSEGV.
  66
  67 Dynamic features in signal frames
  68 ---------------------------------
  69
  70 Dynamcally enabled features are not written to the signal frame upon signal
  71 entry if the feature is in its initial configuration.  This differs from
  72 non-dynamic features which are always written regardless of their
  73 configuration.  Signal handlers can examine the XSAVE buffer's XSTATE_BV
  74 field to determine if a features was written.