Documentation/userspace-api/spec_ctrl.rst

   1 ===================
   2 Speculation Control
   3 ===================
   4
   5 Quite some CPUs have speculation related misfeatures which are in fact
   6 vulnerabilites causing data leaks in various forms even accross privilege
   7 domains.
   8
   9 The kernel provides mitigation for such vulnerabilities in various
  10 forms. Some of these mitigations are compile time configurable and some on
  11 the kernel command line.
  12
  13 There is also a class of mitigations which are very expensive, but they can
  14 be restricted to a certain set of processes or tasks in controlled
  15 environments. The mechanism to control these mitigations is via
  16 :manpage:`prctl(2)`.
  17
  18 There are two prctl options which are related to this:
  19
  20  * PR_GET_SPECULATION_CTRL
  21
  22  * PR_SET_SPECULATION_CTRL
  23
  24 PR_GET_SPECULATION_CTRL
  25 -----------------------
  26
  27 PR_GET_SPECULATION_CTRL returns the state of the speculation misfeature
  28 which is selected with arg2 of prctl(2). The return value uses bits 0-2 with
  29 the following meaning:
  30
  31 ==== ================ ===================================================
  32 Bit  Define           Description
  33 ==== ================ ===================================================
  34 0    PR_SPEC_PRCTL    Mitigation can be controlled per task by
  35                       PR_SET_SPECULATION_CTRL
  36 1    PR_SPEC_ENABLE   The speculation feature is enabled, mitigation is
  37                       disabled
  38 2    PR_SPEC_DISABLE  The speculation feature is disabled, mitigation is
  39                       enabled
  40 ==== ================ ===================================================
  41
  42 If all bits are 0 the CPU is not affected by the speculation misfeature.
  43
  44 If PR_SPEC_PRCTL is set, then the per task control of the mitigation is
  45 available. If not set, prctl(PR_SET_SPECULATION_CTRL) for the speculation
  46 misfeature will fail.
  47
  48 PR_SET_SPECULATION_CTRL
  49 -----------------------
  50 PR_SET_SPECULATION_CTRL allows to control the speculation misfeature, which
  51 is selected by arg2 of :manpage:`prctl(2)` per task. arg3 is used to hand
  52 in the control value, i.e. either PR_SPEC_ENABLE or PR_SPEC_DISABLE.
  53
  54 Common error codes
  55 ------------------
  56 ======= =================================================================
  57 Value   Meaning
  58 ======= =================================================================
  59 EINVAL  The prctl is not implemented by the architecture or unused
  60         prctl(2) arguments are not 0
  61
  62 ENODEV  arg2 is selecting a not supported speculation misfeature
  63 ======= =================================================================
  64
  65 PR_SET_SPECULATION_CTRL error codes
  66 -----------------------------------
  67 ======= =================================================================
  68 Value   Meaning
  69 ======= =================================================================
  70 0       Success
  71
  72 ERANGE  arg3 is incorrect, i.e. it's neither PR_SPEC_ENABLE nor
  73         PR_SPEC_DISABLE
  74
  75 ENXIO   Control of the selected speculation misfeature is not possible.
  76         See PR_GET_SPECULATION_CTRL.
  77 ======= =================================================================
  78
  79 Speculation misfeature controls
  80 -------------------------------
  81 - PR_SPEC_STORE_BYPASS: Speculative Store Bypass
  82
  83   Invocations:
  84    * prctl(PR_GET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, 0, 0, 0);
  85    * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_ENABLE, 0, 0);
  86    * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_DISABLE, 0, 0);