[RFC PATCH 01/56] Documentation/admin-guide: Add documentation

[David Kaplan <david.kaplan@amd.com>]

Add new documentation for the dynamic mitigation feature.

Signed-off-by: David Kaplan <david.kaplan@amd.com>
---
 .../hw-vuln/dynamic_mitigations.rst           | 75 +++++++++++++++++++
 Documentation/admin-guide/hw-vuln/index.rst   |  1 +
 2 files changed, 76 insertions(+)
 create mode 100644 Documentation/admin-guide/hw-vuln/dynamic_mitigations.rst

diff --git a/Documentation/admin-guide/hw-vuln/dynamic_mitigations.rst b/Documentation/admin-guide/hw-vuln/dynamic_mitigations.rst
new file mode 100644
index 000000000000..9904e6ec9be5
--- /dev/null
+++ b/Documentation/admin-guide/hw-vuln/dynamic_mitigations.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Dynamic Mitigations
+-------------------
+
+Dynamic mitigation support enables the re-configuration of CPU vulnerability
+mitigations through sysfs.  The file /sys/devices/system/cpu/mitigations
+contains the current set of mitigation-related options.  The file can be written
+to in order to make the kernel re-select and re-apply mitigations without a
+reboot or kexec.
+
+The data written to the file should be command line options related to
+mitigation controls (e.g., "mitigations=auto spectre_v2=retpoline mds=off").
+When the file is written, all previous selections related to mitigation controls
+are discarded and the new options are evaluated.  Any non-mitigation related
+options are ignored.
+
+Dynamic mitigations are available if the CONFIG_DYNAMIC_MITIGATIONS option is
+selected.
+
+Purpose
+-------
+
+Dynamic mitigations serve two primary purposes:
+
+Move Policy To Userspace
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Mitigation choices are related to the security policy and posture of the system.
+Most mitigations are only necessary on shared, multi-user systems if untrusted
+code may be run on the system, such as through untrusted userspace or untrusted
+virtual machines.  The kernel may not know how the system will be used on boot,
+and therefore must adopt a strong security posture for safety.
+
+With dynamic mitigations, userspace can re-select mitigations once the needs of
+the system can be determined and more policy information is available.
+
+Mitigation Testing
+^^^^^^^^^^^^^^^^^^
+
+Dynamic mitigation support makes it easy to toggle individual mitigations or
+choose between different mitigation options without the expense of a reboot or
+kexec.  This may be useful when evaluating the performance of various
+mitigation options.  It can also be useful for performing bug fixes without a
+reboot, in case a particular mitigation is undesired or buggy.
+
+Caveats
+-------
+
+There are a few limitations to dynamic mitigation support:
+
+Runtime Limitations
+^^^^^^^^^^^^^^^^^^^
+
+There are a few mitigations that cannot be toggled at runtime due to the way
+they are structured.  Specifically, kernel PTI (page table isolation) cannot be
+toggled because of the complexity of this mitigation.  Additionally, SMT cannot
+be disabled at runtime.  Therefore, if a bug mitigation requires disabling SMT,
+a warning message will be printed.
+
+BPF JIT
+^^^^^^^
+
+There is currently no way to recompile already JIT'd BPF programs.  This can
+present a security problem if moving from a less secure security posture to a
+more secure one.  It is recommended to either unload BPF programs prior to
+re-configuring mitigations, ensure that security settings only become less
+restrictive over time, or disable use of the BPF JIT.
+
+Performance
+-----------
+
+Re-configuring mitigations is done under the biggest of hammers.  All tasks are
+frozen, all cores are stopped, interrupts are masked, etc.  This may affect
+system responsiveness if lots of patching must be done.
diff --git a/Documentation/admin-guide/hw-vuln/index.rst b/Documentation/admin-guide/hw-vuln/index.rst
index 55d747511f83..44418bad5895 100644
--- a/Documentation/admin-guide/hw-vuln/index.rst
+++ b/Documentation/admin-guide/hw-vuln/index.rst
@@ -27,3 +27,4 @@ are configurable at compile, boot or run time.
    old_microcode
    indirect-target-selection
    vmscape
+   dynamic_mitigations
-- 
2.34.1