= Speculation Control (Spectre variant 2) =

== How to detect if the CPU supports Speculation Control ==

When the first CPU boots or after a microcode update, if the CPU has
speculation control capabilities these lines are printed:

	FEATURE SPEC_CTRL Present
	FEATURE IBPB_SUPPORT Present

If speculation control is missing these lines are printed:

	FEATURE SPEC_CTRL Not Present
	FEATURE IBPB_SUPPORT Not Present

Some CPUs only have IBPB_SUPPORT in which case this will be printed:

	FEATURE SPEC_CTRL Not Present
	FEATURE IBPB_SUPPORT Present

Some CPUs can only disable IBP but have no IBRS/IBPB support in which case
these lines are printed and a special use_ibp_disable mode is
used.

	FEATURE SPEC_CTRL Present (Implicit)
	FEATURE IBPB_SUPPORT Present (Implicit)

== How to tune Speculation Control ==

The current spectre_v2 mitigation status can be determined by reading
the following file:

  /sys/devices/system/cpu/vulnerabilities/spectre_v2

That file provides a basic status -- "Vulnerable" or "Mitigation" --
along with a short description of the mitigation in use (or lack
thereof).

Speculation control may be tuned from the kernel command line with the
spectre_v2= parameter.  For the available options, see
Documentation/kernel-parameters.txt.

It may also be tuned from debugfs.  There is one control knob:

  /sys/kernel/debug/x86/ibrs_enabled

There are also two read-only informational debugfs entries:

  /sys/kernel/debug/x86/ibpb_enabled (read-only)
  /sys/kernel/debug/x86/retp_enabled (read-only)

If both of the above microcode features aren't present, ibrs_enabled and
ibpb_enabled are both set to 0, and ibrs_enabled cannot be changed.

If both of the above features are present, the ibrs_enabled and
ibpb_enabled show the current kernel usage of the respective feature.

If, on an AMD processor, IBPB_SUPPORT is present, but SPEC_CTRL is not
present, ibrs_enabled will be read-only at 0, and ibpb_enabled will be
either 0 or 1, dependent on whether retpolines are enabled.

When IBRS is enabled, it means IBP (Indirect Branch Prediction)
restricted speculation and it slows down the CPU significantly,
particularly on pre-Skylake CPUs.  This is why pre-Skylake CPUs default
to using retpolines instead of IBRS.

On all CPUs except for Intel Skylake+ and AMD 10h/12h, retpolines
are the default.  This mitigation doesn't directly depend on any
microcode features.  However, it's only considered a partial solution
without the IBPB_SUPPORT microcode feature which adds user-to-user
and guest-to-guest protection across context switches.

ibrs_enabled 0: Disabled

ibrs_enabled 1: IBRS enabled in kernel mode.

		Kernel is protected from userland and guest
                mode. Userland is not protected from guest mode. User
                mode isn't protected from other user mode running in a
                sibling hyperthread.

		This is the default mode on Skylake and newer CPUs.  It
		cannot be used with retp_enabled 1.

		requires SPEC_CTRL present

ibrs_enabled 2: IBRS enabled in user mode and kernel mode. Only guest
	        can disable IBRS.

		Kernel and usermode are both protected. This protects
		userland from hyperthreading effects and from guest
		mode too.

		This is the default mode on AMD 10h and AMD 12h
		families, which have the ability to completely disable
		the indirect branch predictor.  They don't actually have
		IBRS, but the effect is the same.

		requires SPEC_CTRL present

ibrs_enabled 3: IBRS enabled in user mode.

		Userland is protected from guest mode and from
		hyperthreading effects.  This option can *only* be used
		when retpolines are enabled at boot time. Retpolines
		protects the kernel, and IBRS protects userland.

		requires SPEC_CTRL present

ibpb_enabled 0: Disabled

ibpb_enabled 1: IBPB IBP barrier is used to flush the IBP across mm
                switches (if next task has not enough credentials to
                read the memory of the prev task by other means) and
                across guest mode switches. This protects user and
                guest mode against user and guest mode.

		This doesn't protect against hyperthreading and
                simultaneous multithreading effects.

		This option is read-only.  It is automatically selected
		when ibrs_enabled is 1 or 2, or retpolines are enabled.

		requires IBPB_SUPPORT present

retp_enabled 0: Retpolines are disabled in the kernel.

retp_enabled 1: Retpolines are enabled in the kernel, which replace all
		indirect jumps and indirect calls with a special
		instruction sequence which avoids the use of IBP.

		The state of retpolines can only be changed by
		rebooting the system with a different spectre_v2=
		command line option.
===================
Speculation Control
===================

Quite some CPUs have speculation related misfeatures which are in fact
vulnerabilites causing data leaks in various forms even accross privilege
domains.

The kernel provides mitigation for such vulnerabilities in various
forms. Some of these mitigations are compile time configurable and some on
the kernel command line.

There is also a class of mitigations which are very expensive, but they can
be restricted to a certain set of processes or tasks in controlled
environments. The mechanism to control these mitigations is via prctl(2).

There are two prctl options which are related to this:

 * PR_GET_SPECULATION_CTRL

 * PR_SET_SPECULATION_CTRL

PR_GET_SPECULATION_CTRL
-----------------------

PR_GET_SPECULATION_CTRL returns the state of the speculation misfeature
which is selected with arg2 of prctl(2). The return value uses bits 0-2 with
the following meaning:

==== ================ ===================================================
Bit  Define           Description
==== ================ ===================================================
0    PR_SPEC_PRCTL    Mitigation can be controlled per task by
                      PR_SET_SPECULATION_CTRL
1    PR_SPEC_ENABLE   The speculation feature is enabled, mitigation is
                      disabled
2    PR_SPEC_DISABLE  The speculation feature is disabled, mitigation is
                      enabled
==== ================ ===================================================

If all bits are 0 the CPU is not affected by the speculation misfeature.

If PR_SPEC_PRCTL is set, then the per task control of the mitigation is
available. If not set, prctl(PR_SET_SPECULATION_CTRL) for the speculation
misfeature will fail.

PR_SET_SPECULATION_CTRL
-----------------------
PR_SET_SPECULATION_CTRL allows to control the speculation misfeature, which
is selected by arg2 of prctl(2) per task. arg3 is used to hand in the control
value, i.e. either PR_SPEC_ENABLE or PR_SPEC_DISABLE.

Common error codes
------------------
======= =================================================================
Value   Meaning
======= =================================================================
EINVAL  The prctl is not implemented by the architecture or unused
        prctl(2) arguments are not 0

ENODEV  arg2 is selecting a not supported speculation misfeature
======= =================================================================

PR_SET_SPECULATION_CTRL error codes
-----------------------------------
======= =================================================================
Value   Meaning
======= =================================================================
0       Success

ERANGE  arg3 is incorrect, i.e. it's neither PR_SPEC_ENABLE nor
        PR_SPEC_DISABLE

ENXIO   Control of the selected speculation misfeature is not possible.
        See PR_GET_SPECULATION_CTRL.
======= =================================================================

Speculation misfeature controls
-------------------------------
- PR_SPEC_STORE_BYPASS: Speculative Store Bypass

  Invocations:
   * prctl(PR_GET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, 0, 0, 0);
   * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_ENABLE, 0, 0);
   * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_DISABLE, 0, 0);
