* [PATCH v2] Documentation: Use grid table over list table
@ 2024-09-06 10:49 Takahiro Itazuri
2024-09-06 13:26 ` Jani Nikula
0 siblings, 1 reply; 5+ messages in thread
From: Takahiro Itazuri @ 2024-09-06 10:49 UTC (permalink / raw)
To: linux-doc, linux-kernel, corbet
Cc: bp, itazur, zulinx86, jpoimboe, pawan.kumar.gupta, peterz, tglx
Using a simple table, a line break in the first column would be
recognized as two rows. To avoid that, list table was used but it
is unreadable for plain text readers. Uses grid table instead.
Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
---
Changes in v2:
- Use grid table over list table (applying to not only GDS but also
other vulnerabilities)
- Link to v1: https://lore.kernel.org/all/20240903132533.26458-1-itazur@amazon.com/
---
.../hw-vuln/gather_data_sampling.rst | 40 +++++++------
Documentation/admin-guide/hw-vuln/mds.rst | 50 ++++++++--------
.../admin-guide/hw-vuln/multihit.rst | 27 +++++----
.../hw-vuln/processor_mmio_stale_data.rst | 57 ++++++++++---------
.../hw-vuln/reg-file-data-sampling.rst | 23 ++++----
Documentation/admin-guide/hw-vuln/spectre.rst | 55 +++++++++---------
.../admin-guide/hw-vuln/tsx_async_abort.rst | 57 +++++++++++--------
7 files changed, 170 insertions(+), 139 deletions(-)
diff --git a/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
index 264bfa937f7d..15d124fe979a 100644
--- a/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
+++ b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
@@ -85,23 +85,29 @@ GDS this can be accessed by the following sysfs file:
The possible values contained in this file are:
- ============================== =============================================
- Not affected Processor not vulnerable.
- Vulnerable Processor vulnerable and mitigation disabled.
- Vulnerable: No microcode Processor vulnerable and microcode is missing
- mitigation.
- Mitigation: AVX disabled,
- no microcode Processor is vulnerable and microcode is missing
- mitigation. AVX disabled as mitigation.
- Mitigation: Microcode Processor is vulnerable and mitigation is in
- effect.
- Mitigation: Microcode (locked) Processor is vulnerable and mitigation is in
- effect and cannot be disabled.
- Unknown: Dependent on
- hypervisor status Running on a virtual guest processor that is
- affected but with no way to know if host
- processor is mitigated or vulnerable.
- ============================== =============================================
+ +----------------------------+----------------------------------------------+
+ | 'Not affected' | Processor is not vulnerable. |
+ +----------------------------+----------------------------------------------+
+ | 'Vulnerable' | Processor is vulnerable and mitigation |
+ | | disabled. |
+ +----------------------------+----------------------------------------------+
+ | 'Vulnerable: No microcode' | Processor is vulnerable and microcode is |
+ | | missing mitigation. |
+ +----------------------------+----------------------------------------------+
+ | 'Mitigation: AVX disabled, | Processor is vulnerable and microcode is |
+ | no microcode' | missing mitigation. AVX disabled as |
+ | | mitigation. |
+ +----------------------------+----------------------------------------------+
+ | 'Mitigation: Microcode' | Processor is vulnerable and mitigation is in |
+ | | effect. |
+ +----------------------------+----------------------------------------------+
+ | 'Mitigation: Microcode | Processor is vulnerable and mitigation is in |
+ | (locked)' | effect and cannot be disabled. |
+ +----------------------------+----------------------------------------------+
+ | 'Unknown: Dependent on | Running on a virtual guest processor that is |
+ | hypervisor status' | affected but with no way to know if host |
+ | | processor is mitigated or vulnerable. |
+ +----------------------------+----------------------------------------------+
GDS Default mitigation
----------------------
diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst
index 48c7b0b72aed..a57f50233d42 100644
--- a/Documentation/admin-guide/hw-vuln/mds.rst
+++ b/Documentation/admin-guide/hw-vuln/mds.rst
@@ -95,29 +95,33 @@ mitigations are active. The relevant sysfs file is:
The possible values in this file are:
- .. list-table::
-
- * - 'Not affected'
- - The processor is not vulnerable
- * - 'Vulnerable'
- - The processor is vulnerable, but no mitigation enabled
- * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
- - The processor is vulnerable but microcode is not updated. The
- mitigation is enabled on a best effort basis.
-
- If the processor is vulnerable but the availability of the microcode
- based mitigation mechanism is not advertised via CPUID, the kernel
- selects a best effort mitigation mode. This mode invokes the mitigation
- instructions without a guarantee that they clear the CPU buffers.
-
- This is done to address virtualization scenarios where the host has the
- microcode update applied, but the hypervisor is not yet updated to
- expose the CPUID to the guest. If the host has updated microcode the
- protection takes effect; otherwise a few CPU cycles are wasted
- pointlessly.
- * - 'Mitigation: Clear CPU buffers'
- - The processor is vulnerable and the CPU buffer clearing mitigation is
- enabled.
+ +------------------------+---------------------------------------------------+
+ | 'Not affected' | The processor is not vulnerable. |
+ +------------------------+---------------------------------------------------+
+ | 'Vulnerable' | The processor is vulnerable, but no mitigation |
+ | | enabled. |
+ +------------------------+---------------------------------------------------+
+ | 'Vulnerable: Clear CPU | The processor is vulnerable but microcode is not |
+ | buffers attempted, no | updated. The mitigation is enabled on a best |
+ | microcode' | effort basis. |
+ | | |
+ | | If the processor is vulnerable but the |
+ | | availability of the microcode based mitigation |
+ | | mechanism is not advertised via CPUID, the kernel |
+ | | selects a best effort mitigation mode. This mode |
+ | | invokes the mitigation instructions without a |
+ | | guarantee that they clear the CPU buffers. |
+ | | |
+ | | This is done to address virtualization scenarios |
+ | | where the host has the microcode update applied, |
+ | | but the hypervisor is not yet updated to expose |
+ | | the CPUID to the guest. If the host has updated |
+ | | microcode the protection takes effect; otherwise |
+ | | a few CPU cycles are wasted pointlessly. |
+ +------------------------+---------------------------------------------------+
+ | 'Mitigation: Clear CPU | The processor is vulnerable and the CPU buffer |
+ | buffers' | clearning mitigation is enabled. |
+ +------------------------+---------------------------------------------------+
If the processor is vulnerable then the following information is appended
to the above information:
diff --git a/Documentation/admin-guide/hw-vuln/multihit.rst b/Documentation/admin-guide/hw-vuln/multihit.rst
index 140e4cec38c3..4870afa5b40a 100644
--- a/Documentation/admin-guide/hw-vuln/multihit.rst
+++ b/Documentation/admin-guide/hw-vuln/multihit.rst
@@ -74,18 +74,21 @@ mitigations are active. The relevant sysfs file is:
The possible values in this file are:
-.. list-table::
-
- * - Not affected
- - The processor is not vulnerable.
- * - KVM: Mitigation: Split huge pages
- - Software changes mitigate this issue.
- * - KVM: Mitigation: VMX unsupported
- - KVM is not vulnerable because Virtual Machine Extensions (VMX) is not supported.
- * - KVM: Mitigation: VMX disabled
- - KVM is not vulnerable because Virtual Machine Extensions (VMX) is disabled.
- * - KVM: Vulnerable
- - The processor is vulnerable, but no mitigation enabled
+ +-------------------+-------------------------------------------------+
+ | 'Not affected' | The processor is not vulnerable. |
+ +-------------------+-------------------------------------------------+
+ | 'KVM mitigation: | Software changes mitigate this issue. |
+ | Split huge pages' | |
+ +-------------------+-------------------------------------------------+
+ | 'KVM mitigation: | KVM is not vulnerable because Virtual Machine |
+ | VMX unsupported' | Extensions (VMX) is not supported. |
+ +-------------------+-------------------------------------------------+
+ | 'KVM mitigation: | KVM is not vulnerable because Virtual Machine |
+ | VMX disabled' | Extensions (VMX) is disabled. |
+ +-------------------+-------------------------------------------------+
+ | 'KVM: Vulnerable' | The processor is vulnerable, but no mitigation |
+ | | enabled. |
+ +-------------------+-------------------------------------------------+
Enumeration of the erratum
diff --git a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
index 1302fd1b55e8..7f9a5d8de10a 100644
--- a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
+++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
@@ -218,32 +218,37 @@ which mitigations are active. The relevant sysfs file is:
The possible values in this file are:
- .. list-table::
-
- * - 'Not affected'
- - The processor is not vulnerable
- * - 'Vulnerable'
- - The processor is vulnerable, but no mitigation enabled
- * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
- - The processor is vulnerable but microcode is not updated. The
- mitigation is enabled on a best effort basis.
-
- If the processor is vulnerable but the availability of the microcode
- based mitigation mechanism is not advertised via CPUID, the kernel
- selects a best effort mitigation mode. This mode invokes the mitigation
- instructions without a guarantee that they clear the CPU buffers.
-
- This is done to address virtualization scenarios where the host has the
- microcode update applied, but the hypervisor is not yet updated to
- expose the CPUID to the guest. If the host has updated microcode the
- protection takes effect; otherwise a few CPU cycles are wasted
- pointlessly.
- * - 'Mitigation: Clear CPU buffers'
- - The processor is vulnerable and the CPU buffer clearing mitigation is
- enabled.
- * - 'Unknown: No mitigations'
- - The processor vulnerability status is unknown because it is
- out of Servicing period. Mitigation is not attempted.
+ +------------------------+--------------------------------------------------+
+ | 'Not affected' | The processor is not vulnerable. |
+ +------------------------+--------------------------------------------------+
+ | 'Vulnerable' | The processor is vulnerable, but no mitigation |
+ | | enabled. |
+ +------------------------+--------------------------------------------------+
+ | 'Vulnerable: Clear CPU | The processor is vulnerable but microcode is not |
+ | buffers attempted, no | updated. The mitigation is enabled on a best |
+ | microcode' | effort basis. |
+ | | |
+ | | The processor is vulnerable but the availability |
+ | | of the microcode based mitigation mechanism is |
+ | | not advertised via CPUID, the kernel selects a |
+ | | best effort mitigation mode. This mode invokes |
+ | | the mitigation instructions without a guarantee |
+ | | that they clear the CPU buffers. |
+ | | |
+ | | This is done to address virtualization scenarios |
+ | | where the host has the microcode update applied, |
+ | | but the hypervisor is not yet updated to expose |
+ | | the CPUID to the guest. If the host has updated |
+ | | microcode the protection takes effect; otherwise |
+ | | a few CPU cycles are wasted pointlessly. |
+ +------------------------+--------------------------------------------------+
+ | 'Mitigation: Clear CPU | The processor is vulnerable and the CPU buffer |
+ | buffers' | clearing mitigation is enabled. |
+ +------------------------+--------------------------------------------------+
+ | 'Unknown: No | The processor vulnerability status is unknown |
+ | mitigations' | because it is out of Servicing period. |
+ | | Mitigation is not attempted. |
+ +------------------------+--------------------------------------------------+
Definitions:
------------
diff --git a/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst b/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
index 0585d02b9a6c..e5f324206bed 100644
--- a/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
+++ b/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
@@ -86,17 +86,18 @@ which mitigations are active. The relevant sysfs file is:
The possible values in this file are:
- .. list-table::
-
- * - 'Not affected'
- - The processor is not vulnerable
- * - 'Vulnerable'
- - The processor is vulnerable, but no mitigation enabled
- * - 'Vulnerable: No microcode'
- - The processor is vulnerable but microcode is not updated.
- * - 'Mitigation: Clear Register File'
- - The processor is vulnerable and the CPU buffer clearing mitigation is
- enabled.
+ +--------------------+---------------------------------------------------+
+ | 'Not affected' | The processor is not vulnerable. |
+ +--------------------+---------------------------------------------------+
+ | 'Vulnerable' | The processor is vulnerable, but no mitigation |
+ | | enabled. |
+ +--------------------+---------------------------------------------------+
+ | 'Vulnerable: No | The processor is vulnerable but microcode is not |
+ | microcode' | updated. |
+ +--------------------+---------------------------------------------------+
+ | 'Mitigation: Clear | The processor is vulnerable and the CPU buffer |
+ | Register File' | clearing mitigation is enabled. |
+ +--------------------+---------------------------------------------------+
References
----------
diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst
index 132e0bc6007e..114139f86d1a 100644
--- a/Documentation/admin-guide/hw-vuln/spectre.rst
+++ b/Documentation/admin-guide/hw-vuln/spectre.rst
@@ -336,18 +336,20 @@ The sysfs file showing Spectre variant 1 mitigation status is:
The possible values in this file are:
- .. list-table::
-
- * - 'Not affected'
- - The processor is not vulnerable.
- * - 'Vulnerable: __user pointer sanitization and usercopy barriers only; no swapgs barriers'
- - The swapgs protections are disabled; otherwise it has
- protection in the kernel on a case by case base with explicit
- pointer sanitation and usercopy LFENCE barriers.
- * - 'Mitigation: usercopy/swapgs barriers and __user pointer sanitization'
- - Protection in the kernel on a case by case base with explicit
- pointer sanitation, usercopy LFENCE barriers, and swapgs LFENCE
- barriers.
+ +------------------------------+--------------------------------------------+
+ | 'Not affected' | The processor is not vulnerable. |
+ +------------------------------+--------------------------------------------+
+ | 'Vulnerable: __user pointer | The swapgs protections are disabled; |
+ | sanitization and usercopy | otherwise it has protection in the kernel |
+ | barriers only; no swapgs | on a case by case basis with explicit |
+ | barriers' | pointer sanitization and usercopy LFENCE |
+ | | barriers. |
+ +------------------------------+--------------------------------------------+
+ | 'Mitigation: usercopy/swapgs | Protection in the kernel on a case by case |
+ | barriers and __user pointer | basis with explicit pointer sanitization, |
+ | sanitization' | usercopy LFENCE barriers, and swapgs |
+ | | LFENCE barriers. |
+ +------------------------------+--------------------------------------------+
However, the protections are put in place on a case by case basis,
and there is no guarantee that all possible attack vectors for Spectre
@@ -431,20 +433,21 @@ The possible values in this file are:
- Branch History Injection (BHI) protection status:
-.. list-table::
-
- * - BHI: Not affected
- - System is not affected
- * - BHI: Retpoline
- - System is protected by retpoline
- * - BHI: BHI_DIS_S
- - System is protected by BHI_DIS_S
- * - BHI: SW loop, KVM SW loop
- - System is protected by software clearing sequence
- * - BHI: Vulnerable
- - System is vulnerable to BHI
- * - BHI: Vulnerable, KVM: SW loop
- - System is vulnerable; KVM is protected by software clearing sequence
+ +---------------------+----------------------------------------------------+
+ | 'BHI: Not affected' | System is not affected. |
+ +---------------------+----------------------------------------------------+
+ | 'BHI: Retpoline' | System is protected by retpoline. |
+ +---------------------+----------------------------------------------------+
+ | 'BHI: BHI_DIS_S' | System is protected by BHI_DIS_S. |
+ +---------------------+----------------------------------------------------+
+ | 'BHI: SW loop, KVM | System is protected by software clearing sequence. |
+ | SW loop' | |
+ +---------------------+----------------------------------------------------+
+ | 'BHI: Vulnerable' | System is vulnerable to BHI. |
+ +---------------------+----------------------------------------------------+
+ | 'BHI: Vulnerable, | System is vulnerable; KVM is protected by software |
+ | KVM: SW loop' | clearing sequence. |
+ +---------------------+----------------------------------------------------+
Full mitigation might require a microcode update from the CPU
vendor. When the necessary microcode is not available, the kernel will
diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
index 444f84e22a91..24811752d9a9 100644
--- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
+++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
@@ -93,30 +93,39 @@ of mitigated systems. The relevant sysfs file is:
The possible values in this file are:
-.. list-table::
-
- * - 'Vulnerable'
- - The CPU is affected by this vulnerability and the microcode and kernel mitigation are not applied.
- * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
- - The processor is vulnerable but microcode is not updated. The
- mitigation is enabled on a best effort basis.
-
- If the processor is vulnerable but the availability of the microcode
- based mitigation mechanism is not advertised via CPUID, the kernel
- selects a best effort mitigation mode. This mode invokes the mitigation
- instructions without a guarantee that they clear the CPU buffers.
-
- This is done to address virtualization scenarios where the host has the
- microcode update applied, but the hypervisor is not yet updated to
- expose the CPUID to the guest. If the host has updated microcode the
- protection takes effect; otherwise a few CPU cycles are wasted
- pointlessly.
- * - 'Mitigation: Clear CPU buffers'
- - The microcode has been updated to clear the buffers. TSX is still enabled.
- * - 'Mitigation: TSX disabled'
- - TSX is disabled.
- * - 'Not affected'
- - The CPU is not affected by this issue.
+ +------------------------+--------------------------------------------------+
+ | 'Not affected' | The processor is not affected by this |
+ | | vulnerability. |
+ +------------------------+--------------------------------------------------+
+ | 'Vulnerable' | The processor is affected by this vulnerability |
+ | | and the microcode and kernel mitigation are not |
+ | | applied. |
+ +------------------------+--------------------------------------------------+
+ | 'Vulnerable: Clear CPU | The processor is vulnerable but microcode is not |
+ | buffers attempted, no | updated. The mitigation is enabled on a best |
+ | microcode' | effort basis. |
+ | | |
+ | | If the processor is vulnerable but the |
+ | | availability of the microcode based mitigation |
+ | | mechanism is not advertised via CPUID, the |
+ | | kernel selects a best effort mitigation mode. |
+ | | This mode invokes the mitigation instructions |
+ | | without a guarantee that they clear the CPU |
+ | | buffers. |
+ | | |
+ | | This is done to address virtualization scenarios |
+ | | where the host has the microcode update applied, |
+ | | but the hypervisor is not yet updated to expose |
+ | | the CPUID to the guest. If the host has updated |
+ | | microcode the protection takes effect; otherwise |
+ | | a few CPU cycles are wasted pointlessly. |
+ +------------------------+--------------------------------------------------+
+ | 'Mitigation: Clear CPU | The microcode has been updated to clear the |
+ | buffers' | buffers. TSX is still enabled. |
+ +------------------------+--------------------------------------------------+
+ | 'Mitigation: TSX | TSX is disabled. |
+ | disabled' | |
+ +------------------------+--------------------------------------------------+
Mitigation mechanism
--------------------
--
2.40.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v2] Documentation: Use grid table over list table
2024-09-06 10:49 [PATCH v2] Documentation: Use grid table over list table Takahiro Itazuri
@ 2024-09-06 13:26 ` Jani Nikula
2024-09-06 13:45 ` Jonathan Corbet
2024-09-06 17:23 ` Pawan Gupta
0 siblings, 2 replies; 5+ messages in thread
From: Jani Nikula @ 2024-09-06 13:26 UTC (permalink / raw)
To: Takahiro Itazuri, linux-doc, linux-kernel, corbet
Cc: bp, itazur, zulinx86, jpoimboe, pawan.kumar.gupta, peterz, tglx
On Fri, 06 Sep 2024, Takahiro Itazuri <itazur@amazon.com> wrote:
> Using a simple table, a line break in the first column would be
> recognized as two rows. To avoid that, list table was used but it
> is unreadable for plain text readers. Uses grid table instead.
>
> Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
> ---
> Changes in v2:
> - Use grid table over list table (applying to not only GDS but also
> other vulnerabilities)
> - Link to v1: https://lore.kernel.org/all/20240903132533.26458-1-itazur@amazon.com/
I see that Jon asked you to use a grid table.
But when I look at what's being changed, I can't help but think a
definition list [1] might provide the best compromise between readable
(and easily editable!) source rst and generated html. I don't think it
has to be a *table* in either.
Up to Jon, of course.
BR,
Jani.
[1] https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists
>
> ---
> .../hw-vuln/gather_data_sampling.rst | 40 +++++++------
> Documentation/admin-guide/hw-vuln/mds.rst | 50 ++++++++--------
> .../admin-guide/hw-vuln/multihit.rst | 27 +++++----
> .../hw-vuln/processor_mmio_stale_data.rst | 57 ++++++++++---------
> .../hw-vuln/reg-file-data-sampling.rst | 23 ++++----
> Documentation/admin-guide/hw-vuln/spectre.rst | 55 +++++++++---------
> .../admin-guide/hw-vuln/tsx_async_abort.rst | 57 +++++++++++--------
> 7 files changed, 170 insertions(+), 139 deletions(-)
>
> diff --git a/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
> index 264bfa937f7d..15d124fe979a 100644
> --- a/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
> +++ b/Documentation/admin-guide/hw-vuln/gather_data_sampling.rst
> @@ -85,23 +85,29 @@ GDS this can be accessed by the following sysfs file:
>
> The possible values contained in this file are:
>
> - ============================== =============================================
> - Not affected Processor not vulnerable.
> - Vulnerable Processor vulnerable and mitigation disabled.
> - Vulnerable: No microcode Processor vulnerable and microcode is missing
> - mitigation.
> - Mitigation: AVX disabled,
> - no microcode Processor is vulnerable and microcode is missing
> - mitigation. AVX disabled as mitigation.
> - Mitigation: Microcode Processor is vulnerable and mitigation is in
> - effect.
> - Mitigation: Microcode (locked) Processor is vulnerable and mitigation is in
> - effect and cannot be disabled.
> - Unknown: Dependent on
> - hypervisor status Running on a virtual guest processor that is
> - affected but with no way to know if host
> - processor is mitigated or vulnerable.
> - ============================== =============================================
> + +----------------------------+----------------------------------------------+
> + | 'Not affected' | Processor is not vulnerable. |
> + +----------------------------+----------------------------------------------+
> + | 'Vulnerable' | Processor is vulnerable and mitigation |
> + | | disabled. |
> + +----------------------------+----------------------------------------------+
> + | 'Vulnerable: No microcode' | Processor is vulnerable and microcode is |
> + | | missing mitigation. |
> + +----------------------------+----------------------------------------------+
> + | 'Mitigation: AVX disabled, | Processor is vulnerable and microcode is |
> + | no microcode' | missing mitigation. AVX disabled as |
> + | | mitigation. |
> + +----------------------------+----------------------------------------------+
> + | 'Mitigation: Microcode' | Processor is vulnerable and mitigation is in |
> + | | effect. |
> + +----------------------------+----------------------------------------------+
> + | 'Mitigation: Microcode | Processor is vulnerable and mitigation is in |
> + | (locked)' | effect and cannot be disabled. |
> + +----------------------------+----------------------------------------------+
> + | 'Unknown: Dependent on | Running on a virtual guest processor that is |
> + | hypervisor status' | affected but with no way to know if host |
> + | | processor is mitigated or vulnerable. |
> + +----------------------------+----------------------------------------------+
>
> GDS Default mitigation
> ----------------------
> diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst
> index 48c7b0b72aed..a57f50233d42 100644
> --- a/Documentation/admin-guide/hw-vuln/mds.rst
> +++ b/Documentation/admin-guide/hw-vuln/mds.rst
> @@ -95,29 +95,33 @@ mitigations are active. The relevant sysfs file is:
>
> The possible values in this file are:
>
> - .. list-table::
> -
> - * - 'Not affected'
> - - The processor is not vulnerable
> - * - 'Vulnerable'
> - - The processor is vulnerable, but no mitigation enabled
> - * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
> - - The processor is vulnerable but microcode is not updated. The
> - mitigation is enabled on a best effort basis.
> -
> - If the processor is vulnerable but the availability of the microcode
> - based mitigation mechanism is not advertised via CPUID, the kernel
> - selects a best effort mitigation mode. This mode invokes the mitigation
> - instructions without a guarantee that they clear the CPU buffers.
> -
> - This is done to address virtualization scenarios where the host has the
> - microcode update applied, but the hypervisor is not yet updated to
> - expose the CPUID to the guest. If the host has updated microcode the
> - protection takes effect; otherwise a few CPU cycles are wasted
> - pointlessly.
> - * - 'Mitigation: Clear CPU buffers'
> - - The processor is vulnerable and the CPU buffer clearing mitigation is
> - enabled.
> + +------------------------+---------------------------------------------------+
> + | 'Not affected' | The processor is not vulnerable. |
> + +------------------------+---------------------------------------------------+
> + | 'Vulnerable' | The processor is vulnerable, but no mitigation |
> + | | enabled. |
> + +------------------------+---------------------------------------------------+
> + | 'Vulnerable: Clear CPU | The processor is vulnerable but microcode is not |
> + | buffers attempted, no | updated. The mitigation is enabled on a best |
> + | microcode' | effort basis. |
> + | | |
> + | | If the processor is vulnerable but the |
> + | | availability of the microcode based mitigation |
> + | | mechanism is not advertised via CPUID, the kernel |
> + | | selects a best effort mitigation mode. This mode |
> + | | invokes the mitigation instructions without a |
> + | | guarantee that they clear the CPU buffers. |
> + | | |
> + | | This is done to address virtualization scenarios |
> + | | where the host has the microcode update applied, |
> + | | but the hypervisor is not yet updated to expose |
> + | | the CPUID to the guest. If the host has updated |
> + | | microcode the protection takes effect; otherwise |
> + | | a few CPU cycles are wasted pointlessly. |
> + +------------------------+---------------------------------------------------+
> + | 'Mitigation: Clear CPU | The processor is vulnerable and the CPU buffer |
> + | buffers' | clearning mitigation is enabled. |
> + +------------------------+---------------------------------------------------+
>
> If the processor is vulnerable then the following information is appended
> to the above information:
> diff --git a/Documentation/admin-guide/hw-vuln/multihit.rst b/Documentation/admin-guide/hw-vuln/multihit.rst
> index 140e4cec38c3..4870afa5b40a 100644
> --- a/Documentation/admin-guide/hw-vuln/multihit.rst
> +++ b/Documentation/admin-guide/hw-vuln/multihit.rst
> @@ -74,18 +74,21 @@ mitigations are active. The relevant sysfs file is:
>
> The possible values in this file are:
>
> -.. list-table::
> -
> - * - Not affected
> - - The processor is not vulnerable.
> - * - KVM: Mitigation: Split huge pages
> - - Software changes mitigate this issue.
> - * - KVM: Mitigation: VMX unsupported
> - - KVM is not vulnerable because Virtual Machine Extensions (VMX) is not supported.
> - * - KVM: Mitigation: VMX disabled
> - - KVM is not vulnerable because Virtual Machine Extensions (VMX) is disabled.
> - * - KVM: Vulnerable
> - - The processor is vulnerable, but no mitigation enabled
> + +-------------------+-------------------------------------------------+
> + | 'Not affected' | The processor is not vulnerable. |
> + +-------------------+-------------------------------------------------+
> + | 'KVM mitigation: | Software changes mitigate this issue. |
> + | Split huge pages' | |
> + +-------------------+-------------------------------------------------+
> + | 'KVM mitigation: | KVM is not vulnerable because Virtual Machine |
> + | VMX unsupported' | Extensions (VMX) is not supported. |
> + +-------------------+-------------------------------------------------+
> + | 'KVM mitigation: | KVM is not vulnerable because Virtual Machine |
> + | VMX disabled' | Extensions (VMX) is disabled. |
> + +-------------------+-------------------------------------------------+
> + | 'KVM: Vulnerable' | The processor is vulnerable, but no mitigation |
> + | | enabled. |
> + +-------------------+-------------------------------------------------+
>
>
> Enumeration of the erratum
> diff --git a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
> index 1302fd1b55e8..7f9a5d8de10a 100644
> --- a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
> +++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
> @@ -218,32 +218,37 @@ which mitigations are active. The relevant sysfs file is:
>
> The possible values in this file are:
>
> - .. list-table::
> -
> - * - 'Not affected'
> - - The processor is not vulnerable
> - * - 'Vulnerable'
> - - The processor is vulnerable, but no mitigation enabled
> - * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
> - - The processor is vulnerable but microcode is not updated. The
> - mitigation is enabled on a best effort basis.
> -
> - If the processor is vulnerable but the availability of the microcode
> - based mitigation mechanism is not advertised via CPUID, the kernel
> - selects a best effort mitigation mode. This mode invokes the mitigation
> - instructions without a guarantee that they clear the CPU buffers.
> -
> - This is done to address virtualization scenarios where the host has the
> - microcode update applied, but the hypervisor is not yet updated to
> - expose the CPUID to the guest. If the host has updated microcode the
> - protection takes effect; otherwise a few CPU cycles are wasted
> - pointlessly.
> - * - 'Mitigation: Clear CPU buffers'
> - - The processor is vulnerable and the CPU buffer clearing mitigation is
> - enabled.
> - * - 'Unknown: No mitigations'
> - - The processor vulnerability status is unknown because it is
> - out of Servicing period. Mitigation is not attempted.
> + +------------------------+--------------------------------------------------+
> + | 'Not affected' | The processor is not vulnerable. |
> + +------------------------+--------------------------------------------------+
> + | 'Vulnerable' | The processor is vulnerable, but no mitigation |
> + | | enabled. |
> + +------------------------+--------------------------------------------------+
> + | 'Vulnerable: Clear CPU | The processor is vulnerable but microcode is not |
> + | buffers attempted, no | updated. The mitigation is enabled on a best |
> + | microcode' | effort basis. |
> + | | |
> + | | The processor is vulnerable but the availability |
> + | | of the microcode based mitigation mechanism is |
> + | | not advertised via CPUID, the kernel selects a |
> + | | best effort mitigation mode. This mode invokes |
> + | | the mitigation instructions without a guarantee |
> + | | that they clear the CPU buffers. |
> + | | |
> + | | This is done to address virtualization scenarios |
> + | | where the host has the microcode update applied, |
> + | | but the hypervisor is not yet updated to expose |
> + | | the CPUID to the guest. If the host has updated |
> + | | microcode the protection takes effect; otherwise |
> + | | a few CPU cycles are wasted pointlessly. |
> + +------------------------+--------------------------------------------------+
> + | 'Mitigation: Clear CPU | The processor is vulnerable and the CPU buffer |
> + | buffers' | clearing mitigation is enabled. |
> + +------------------------+--------------------------------------------------+
> + | 'Unknown: No | The processor vulnerability status is unknown |
> + | mitigations' | because it is out of Servicing period. |
> + | | Mitigation is not attempted. |
> + +------------------------+--------------------------------------------------+
>
> Definitions:
> ------------
> diff --git a/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst b/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
> index 0585d02b9a6c..e5f324206bed 100644
> --- a/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
> +++ b/Documentation/admin-guide/hw-vuln/reg-file-data-sampling.rst
> @@ -86,17 +86,18 @@ which mitigations are active. The relevant sysfs file is:
>
> The possible values in this file are:
>
> - .. list-table::
> -
> - * - 'Not affected'
> - - The processor is not vulnerable
> - * - 'Vulnerable'
> - - The processor is vulnerable, but no mitigation enabled
> - * - 'Vulnerable: No microcode'
> - - The processor is vulnerable but microcode is not updated.
> - * - 'Mitigation: Clear Register File'
> - - The processor is vulnerable and the CPU buffer clearing mitigation is
> - enabled.
> + +--------------------+---------------------------------------------------+
> + | 'Not affected' | The processor is not vulnerable. |
> + +--------------------+---------------------------------------------------+
> + | 'Vulnerable' | The processor is vulnerable, but no mitigation |
> + | | enabled. |
> + +--------------------+---------------------------------------------------+
> + | 'Vulnerable: No | The processor is vulnerable but microcode is not |
> + | microcode' | updated. |
> + +--------------------+---------------------------------------------------+
> + | 'Mitigation: Clear | The processor is vulnerable and the CPU buffer |
> + | Register File' | clearing mitigation is enabled. |
> + +--------------------+---------------------------------------------------+
>
> References
> ----------
> diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst
> index 132e0bc6007e..114139f86d1a 100644
> --- a/Documentation/admin-guide/hw-vuln/spectre.rst
> +++ b/Documentation/admin-guide/hw-vuln/spectre.rst
> @@ -336,18 +336,20 @@ The sysfs file showing Spectre variant 1 mitigation status is:
>
> The possible values in this file are:
>
> - .. list-table::
> -
> - * - 'Not affected'
> - - The processor is not vulnerable.
> - * - 'Vulnerable: __user pointer sanitization and usercopy barriers only; no swapgs barriers'
> - - The swapgs protections are disabled; otherwise it has
> - protection in the kernel on a case by case base with explicit
> - pointer sanitation and usercopy LFENCE barriers.
> - * - 'Mitigation: usercopy/swapgs barriers and __user pointer sanitization'
> - - Protection in the kernel on a case by case base with explicit
> - pointer sanitation, usercopy LFENCE barriers, and swapgs LFENCE
> - barriers.
> + +------------------------------+--------------------------------------------+
> + | 'Not affected' | The processor is not vulnerable. |
> + +------------------------------+--------------------------------------------+
> + | 'Vulnerable: __user pointer | The swapgs protections are disabled; |
> + | sanitization and usercopy | otherwise it has protection in the kernel |
> + | barriers only; no swapgs | on a case by case basis with explicit |
> + | barriers' | pointer sanitization and usercopy LFENCE |
> + | | barriers. |
> + +------------------------------+--------------------------------------------+
> + | 'Mitigation: usercopy/swapgs | Protection in the kernel on a case by case |
> + | barriers and __user pointer | basis with explicit pointer sanitization, |
> + | sanitization' | usercopy LFENCE barriers, and swapgs |
> + | | LFENCE barriers. |
> + +------------------------------+--------------------------------------------+
>
> However, the protections are put in place on a case by case basis,
> and there is no guarantee that all possible attack vectors for Spectre
> @@ -431,20 +433,21 @@ The possible values in this file are:
>
> - Branch History Injection (BHI) protection status:
>
> -.. list-table::
> -
> - * - BHI: Not affected
> - - System is not affected
> - * - BHI: Retpoline
> - - System is protected by retpoline
> - * - BHI: BHI_DIS_S
> - - System is protected by BHI_DIS_S
> - * - BHI: SW loop, KVM SW loop
> - - System is protected by software clearing sequence
> - * - BHI: Vulnerable
> - - System is vulnerable to BHI
> - * - BHI: Vulnerable, KVM: SW loop
> - - System is vulnerable; KVM is protected by software clearing sequence
> + +---------------------+----------------------------------------------------+
> + | 'BHI: Not affected' | System is not affected. |
> + +---------------------+----------------------------------------------------+
> + | 'BHI: Retpoline' | System is protected by retpoline. |
> + +---------------------+----------------------------------------------------+
> + | 'BHI: BHI_DIS_S' | System is protected by BHI_DIS_S. |
> + +---------------------+----------------------------------------------------+
> + | 'BHI: SW loop, KVM | System is protected by software clearing sequence. |
> + | SW loop' | |
> + +---------------------+----------------------------------------------------+
> + | 'BHI: Vulnerable' | System is vulnerable to BHI. |
> + +---------------------+----------------------------------------------------+
> + | 'BHI: Vulnerable, | System is vulnerable; KVM is protected by software |
> + | KVM: SW loop' | clearing sequence. |
> + +---------------------+----------------------------------------------------+
>
> Full mitigation might require a microcode update from the CPU
> vendor. When the necessary microcode is not available, the kernel will
> diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
> index 444f84e22a91..24811752d9a9 100644
> --- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
> +++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
> @@ -93,30 +93,39 @@ of mitigated systems. The relevant sysfs file is:
>
> The possible values in this file are:
>
> -.. list-table::
> -
> - * - 'Vulnerable'
> - - The CPU is affected by this vulnerability and the microcode and kernel mitigation are not applied.
> - * - 'Vulnerable: Clear CPU buffers attempted, no microcode'
> - - The processor is vulnerable but microcode is not updated. The
> - mitigation is enabled on a best effort basis.
> -
> - If the processor is vulnerable but the availability of the microcode
> - based mitigation mechanism is not advertised via CPUID, the kernel
> - selects a best effort mitigation mode. This mode invokes the mitigation
> - instructions without a guarantee that they clear the CPU buffers.
> -
> - This is done to address virtualization scenarios where the host has the
> - microcode update applied, but the hypervisor is not yet updated to
> - expose the CPUID to the guest. If the host has updated microcode the
> - protection takes effect; otherwise a few CPU cycles are wasted
> - pointlessly.
> - * - 'Mitigation: Clear CPU buffers'
> - - The microcode has been updated to clear the buffers. TSX is still enabled.
> - * - 'Mitigation: TSX disabled'
> - - TSX is disabled.
> - * - 'Not affected'
> - - The CPU is not affected by this issue.
> + +------------------------+--------------------------------------------------+
> + | 'Not affected' | The processor is not affected by this |
> + | | vulnerability. |
> + +------------------------+--------------------------------------------------+
> + | 'Vulnerable' | The processor is affected by this vulnerability |
> + | | and the microcode and kernel mitigation are not |
> + | | applied. |
> + +------------------------+--------------------------------------------------+
> + | 'Vulnerable: Clear CPU | The processor is vulnerable but microcode is not |
> + | buffers attempted, no | updated. The mitigation is enabled on a best |
> + | microcode' | effort basis. |
> + | | |
> + | | If the processor is vulnerable but the |
> + | | availability of the microcode based mitigation |
> + | | mechanism is not advertised via CPUID, the |
> + | | kernel selects a best effort mitigation mode. |
> + | | This mode invokes the mitigation instructions |
> + | | without a guarantee that they clear the CPU |
> + | | buffers. |
> + | | |
> + | | This is done to address virtualization scenarios |
> + | | where the host has the microcode update applied, |
> + | | but the hypervisor is not yet updated to expose |
> + | | the CPUID to the guest. If the host has updated |
> + | | microcode the protection takes effect; otherwise |
> + | | a few CPU cycles are wasted pointlessly. |
> + +------------------------+--------------------------------------------------+
> + | 'Mitigation: Clear CPU | The microcode has been updated to clear the |
> + | buffers' | buffers. TSX is still enabled. |
> + +------------------------+--------------------------------------------------+
> + | 'Mitigation: TSX | TSX is disabled. |
> + | disabled' | |
> + +------------------------+--------------------------------------------------+
>
> Mitigation mechanism
> --------------------
--
Jani Nikula, Intel
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] Documentation: Use grid table over list table
2024-09-06 13:26 ` Jani Nikula
@ 2024-09-06 13:45 ` Jonathan Corbet
2024-09-06 17:23 ` Pawan Gupta
1 sibling, 0 replies; 5+ messages in thread
From: Jonathan Corbet @ 2024-09-06 13:45 UTC (permalink / raw)
To: Jani Nikula, Takahiro Itazuri, linux-doc, linux-kernel
Cc: bp, itazur, zulinx86, jpoimboe, pawan.kumar.gupta, peterz, tglx
Jani Nikula <jani.nikula@linux.intel.com> writes:
> On Fri, 06 Sep 2024, Takahiro Itazuri <itazur@amazon.com> wrote:
>> Using a simple table, a line break in the first column would be
>> recognized as two rows. To avoid that, list table was used but it
>> is unreadable for plain text readers. Uses grid table instead.
>>
>> Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
>> ---
>> Changes in v2:
>> - Use grid table over list table (applying to not only GDS but also
>> other vulnerabilities)
>> - Link to v1: https://lore.kernel.org/all/20240903132533.26458-1-itazur@amazon.com/
>
> I see that Jon asked you to use a grid table.
>
> But when I look at what's being changed, I can't help but think a
> definition list [1] might provide the best compromise between readable
> (and easily editable!) source rst and generated html. I don't think it
> has to be a *table* in either.
>
> Up to Jon, of course.
I think it's up to the people who write and use the documentation in the
end; I don't want to dictate minor choices like that. Anything that
makes it more readable works well for me.
Thanks,
jon
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v2] Documentation: Use grid table over list table
2024-09-06 13:26 ` Jani Nikula
2024-09-06 13:45 ` Jonathan Corbet
@ 2024-09-06 17:23 ` Pawan Gupta
2024-09-08 15:50 ` Takahiro Itazuri
1 sibling, 1 reply; 5+ messages in thread
From: Pawan Gupta @ 2024-09-06 17:23 UTC (permalink / raw)
To: Jani Nikula
Cc: Takahiro Itazuri, linux-doc, linux-kernel, corbet, bp, zulinx86,
jpoimboe, peterz, tglx
On Fri, Sep 06, 2024 at 04:26:49PM +0300, Jani Nikula wrote:
> On Fri, 06 Sep 2024, Takahiro Itazuri <itazur@amazon.com> wrote:
> > Using a simple table, a line break in the first column would be
> > recognized as two rows. To avoid that, list table was used but it
> > is unreadable for plain text readers. Uses grid table instead.
> >
> > Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
> > ---
> > Changes in v2:
> > - Use grid table over list table (applying to not only GDS but also
> > other vulnerabilities)
> > - Link to v1: https://lore.kernel.org/all/20240903132533.26458-1-itazur@amazon.com/
>
> I see that Jon asked you to use a grid table.
>
> But when I look at what's being changed, I can't help but think a
> definition list [1] might provide the best compromise between readable
> (and easily editable!) source rst and generated html. I don't think it
> has to be a *table* in either.
I second that, definition list looks to be a good balance between ease and
readability.
Roughly this is what it boils down to:
**Not affected**
Processor is not vulnerable.
**Vulnerable**
Processor is vulnerable and mitigation disabled.
**Vulnerable: No microcode**
Processor is vulnerable and microcode is missing mitigation.
**Mitigation: AVX disabled, no microcode**
Processor is vulnerable and microcode is missing mitigation. AVX
disabled as mitigation.
**Mitigation: Microcode**
Processor is vulnerable and mitigation is in effect.
**Mitigation: Microcode (locked)**
Processor is vulnerable and mitigation is in effect and cannot be
disabled.
**Unknown: Dependent on hypervisor status**
Running on a virtual guest processor that is affected but with no way
to know if host processor is mitigated or vulnerable.
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH v2] Documentation: Use grid table over list table
2024-09-06 17:23 ` Pawan Gupta
@ 2024-09-08 15:50 ` Takahiro Itazuri
0 siblings, 0 replies; 5+ messages in thread
From: Takahiro Itazuri @ 2024-09-08 15:50 UTC (permalink / raw)
To: pawan.kumar.gupta, corbet, jani.nikula
Cc: bp, jpoimboe, linux-doc, linux-kernel, peterz, tglx, zulinx86
On Fri, 6 Sep 2024, Pawan Gupta <pawan.kumar.gupta@linux.intel.com> wrote:
> On Fri, Sep 06, 2024 at 04:26:49PM +0300, Jani Nikula wrote:
> > On Fri, 06 Sep 2024, Takahiro Itazuri <itazur@amazon.com> wrote:
> > > Using a simple table, a line break in the first column would be
> > > recognized as two rows. To avoid that, list table was used but it
> > > is unreadable for plain text readers. Uses grid table instead.
> > >
> > > Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
> > > ---
> > > Changes in v2:
> > > - Use grid table over list table (applying to not only GDS but also
> > > other vulnerabilities)
> > > - Link to v1: https://lore.kernel.org/all/20240903132533.26458-1-itazur@amazon.com/
> >
> > I see that Jon asked you to use a grid table.
> >
> > But when I look at what's being changed, I can't help but think a
> > definition list [1] might provide the best compromise between readable
> > (and easily editable!) source rst and generated html. I don't think it
> > has to be a *table* in either.
Thank you for your feedback!
Then, I'd prefer list table again because it doesn't change the existing HTML
appearance and it doesn't look much different from the definition list in plain
text format.
For readability/editability in plain text format, a line break can be inserted
between items as follows:
.. list-table::
* - 'Not affected'
- Processor not vulnerable.
* - 'Vulnerable'
- Processor vulnerable and mitigation disabled.
* - 'Vulnerable: No microcode'
- Processor vulnerable and microcode is missing migitation.
* - 'Mitigation: AVX disabled, no microcode'
- Processor is vulnerable and microcode is missing mitigation. AVX disbaled as
mitigation.
* - 'Mitigation: Microcode'
- Processor is vulnerable and mitigation is in effect.
* - 'Mitigation: Microcode (locked)'
- Processor is vulnerable and mitigation is in effect and cannot be disabled.
* - 'Unknown: Dependent on hypervisor status'
- Running on a virtual guest processor that is affected but with no way to
know if host processor is mitigated or vulnerable.
Thanks,
Taka
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2024-09-08 15:50 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-09-06 10:49 [PATCH v2] Documentation: Use grid table over list table Takahiro Itazuri
2024-09-06 13:26 ` Jani Nikula
2024-09-06 13:45 ` Jonathan Corbet
2024-09-06 17:23 ` Pawan Gupta
2024-09-08 15:50 ` Takahiro Itazuri
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).