Documentation: Add L1D flushing Documentation

Add documentation of l1d flushing, explain the need for the feature and how it can be used.

Balbir Singh committed 5 years ago

Commit b7fe54f1 parent e893bb14 files · +95 −0Browse files

Unified · Split

4 files

Documentation/admin-guide/hw-vuln/index.rst +1 −0
Documentation/admin-guide/hw-vuln/l1d_flush.rst +69 −0
Documentation/admin-guide/kernel-parameters.txt +17 −0
Documentation/userspace-api/spec_ctrl.rst +8 −0

Documentation/admin-guide/hw-vuln/index.rst+1−0

@@ -16,3 +16,4 @@ are configurable at compile, boot or run time. · 15 unmodified lines
16	multihit.rst	16	multihit.rst
17	special-register-buffer-data-sampling.rst	17	special-register-buffer-data-sampling.rst
18	core-scheduling.rst	18	core-scheduling.rst
		19	l1d_flush.rst

Documentation/admin-guide/hw-vuln/l1d_flush.rst+69−0

@@ -0,0 +1,69 @@
	1	L1D Flushing
	2	============
	3
	4	With an increasing number of vulnerabilities being reported around data
	5	leaks from the Level 1 Data cache (L1D) the kernel provides an opt-in
	6	mechanism to flush the L1D cache on context switch.
	7
	8	This mechanism can be used to address e.g. CVE-2020-0550. For applications
	9	the mechanism keeps them safe from vulnerabilities, related to leaks
	10	(snooping of) from the L1D cache.
	11
	12
	13	Related CVEs
	14	------------
	15	The following CVEs can be addressed by this
	16	mechanism
	17
	18	============= ======================== ==================
	19	CVE-2020-0550 Improper Data Forwarding OS related aspects
	20	============= ======================== ==================
	21
	22	Usage Guidelines
	23	----------------
	24
	25	Please see document: :ref:`Documentation/userspace-api/spec_ctrl.rst
	26	<set_spec_ctrl>` for details.
	27
	28	NOTE: The feature is disabled by default, applications need to
	29	specifically opt into the feature to enable it.
	30
	31	Mitigation
	32	----------
	33
	34	When PR_SET_L1D_FLUSH is enabled for a task a flush of the L1D cache is
	35	performed when the task is scheduled out and the incoming task belongs to a
	36	different process and therefore to a different address space.
	37
	38	If the underlying CPU supports L1D flushing in hardware, the hardware
	39	mechanism is used, software fallback for the mitigation, is not supported.
	40
	41	Mitigation control on the kernel command line
	42	---------------------------------------------
	43
	44	The kernel command line allows to control the L1D flush mitigations at boot
	45	time with the option "l1d_flush=". The valid arguments for this option are:
	46
	47	============ =============================================================
	48	on Enables the prctl interface, applications trying to use
	49	the prctl() will fail with an error if l1d_flush is not
	50	enabled
	51	============ =============================================================
	52
	53	By default the mechanism is disabled.
	54
	55	Limitations
	56	-----------
	57
	58	The mechanism does not mitigate L1D data leaks between tasks belonging to
	59	different processes which are concurrently executing on sibling threads of
	60	a physical CPU core when SMT is enabled on the system.
	61
	62	This can be addressed by controlled placement of processes on physical CPU
	63	cores or by disabling SMT. See the relevant chapter in the L1TF mitigation
	64	document: :ref:`Documentation/admin-guide/hw-vuln/l1tf.rst <smt_control>`.
	65
	66	NOTE : The opt-in of a task for L1D flushing works only when the task's
	67	affinity is limited to cores running in non-SMT mode. If a task which
	68	requested L1D flushing is scheduled on a SMT-enabled core the kernel sends
	69	a SIGBUS to the task.

Documentation/admin-guide/kernel-parameters.txt+17−0

@@ -2421,6 +2421,23 @@ · 2420 unmodified lines
2421	feature (tagged TLBs) on capable Intel chips.	2421	feature (tagged TLBs) on capable Intel chips.
2422	Default is 1 (enabled)	2422	Default is 1 (enabled)
2423		2423
		2424	l1d_flush= [X86,INTEL]
		2425	Control mitigation for L1D based snooping vulnerability.
		2426
		2427	Certain CPUs are vulnerable to an exploit against CPU
		2428	internal buffers which can forward information to a
		2429	disclosure gadget under certain conditions.
		2430
		2431	In vulnerable processors, the speculatively
		2432	forwarded data can be used in a cache side channel
		2433	attack, to access data to which the attacker does
		2434	not have direct access.
		2435
		2436	This parameter controls the mitigation. The
		2437	options are:
		2438
		2439	on - enable the interface for the mitigation
		2440
2424	l1tf= [X86] Control mitigation of the L1TF vulnerability on	2441	l1tf= [X86] Control mitigation of the L1TF vulnerability on
2425	affected CPUs	2442	affected CPUs
2426		2443

Documentation/userspace-api/spec_ctrl.rst+8−0

@@ -106,3 +106,11 @@ Speculation misfeature controls · 105 unmodified lines
106	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_ENABLE, 0, 0);	106	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_ENABLE, 0, 0);
107	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_DISABLE, 0, 0);	107	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_DISABLE, 0, 0);
108	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_FORCE_DISABLE, 0, 0);	108	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_FORCE_DISABLE, 0, 0);
		109
		110	- PR_SPEC_L1D_FLUSH: Flush L1D Cache on context switch out of the task
		111	(works only when tasks run on non SMT cores)
		112
		113	Invocations:
		114	* prctl(PR_GET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, 0, 0, 0);
		115	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, PR_SPEC_ENABLE, 0, 0);
		116	* prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_L1D_FLUSH, PR_SPEC_DISABLE, 0, 0);