[PATCH v2] docs: Update desc of best effort mode

[PATCH v2] docs: Update desc of best effort mode

[Takahiro Itazuri]

Moves the description of the best effort mitigation mode to the table of
the possible values in the mds and tsx_async_abort docs, and adds the
same one to the mmio_stale_data doc.

Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
---

v1 -> v2: https://lore.kernel.org/all/20230830144426.80258-1-itazur@amazon.com/
- Puts the desc into the table of the possible values.

---
 Documentation/admin-guide/hw-vuln/mds.rst     | 33 ++++++++-----------
 .../hw-vuln/processor_mmio_stale_data.rst     | 13 +++++++-
 .../admin-guide/hw-vuln/tsx_async_abort.rst   | 32 ++++++++----------
 3 files changed, 38 insertions(+), 40 deletions(-)

diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst
index 48ca0bd85..0fe98151a 100644
--- a/Documentation/admin-guide/hw-vuln/mds.rst
+++ b/Documentation/admin-guide/hw-vuln/mds.rst
@@ -102,9 +102,19 @@ The possible values in this file are:
      * - '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. See :ref:`vmwerv`
+       - 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.
@@ -119,23 +129,6 @@ to the above information:
     'SMT Host state unknown'  Kernel runs in a VM, Host SMT state unknown
     ========================  ============================================
 
-.. _vmwerv:
-
-Best effort mitigation mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-  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.
-
-  The state in the mds sysfs file reflects this situation accordingly.
-
 
 Mitigation mechanism
 -------------------------
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 c98fd1190..1302fd1b5 100644
--- a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
+++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
@@ -225,8 +225,19 @@ The possible values in this file are:
      * - '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
+       - 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.
diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
index 014167ef8..c6400fe6b 100644
--- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
+++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
@@ -98,7 +98,19 @@ The possible values in this file are:
    * - '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 system tries to clear the buffers but the microcode might not support the operation.
+     - 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'
@@ -106,24 +118,6 @@ The possible values in this file are:
    * - 'Not affected'
      - The CPU is not affected by this issue.
 
-.. _ucode_needed:
-
-Best effort mitigation mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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.
-
-The state in the tsx_async_abort sysfs file reflects this situation
-accordingly.
-
 
 Mitigation mechanism
 --------------------
-- 
2.40.1

Re: [PATCH v2] docs: Update desc of best effort mode

[Pawan Gupta]

On Thu, Aug 31, 2023 at 12:18:47PM +0100, Takahiro Itazuri wrote:
> Moves the description of the best effort mitigation mode to the table of
> the possible values in the mds and tsx_async_abort docs, and adds the
> same one to the mmio_stale_data doc.

I would suggest to change the subject prefix to:

docs/hw-vuln: Update desc of best effort mode

or

Documentation/hw-vuln: Update desc of best effort mode

> Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
> ---
> 
> v1 -> v2: https://lore.kernel.org/all/20230830144426.80258-1-itazur@amazon.com/
> - Puts the desc into the table of the possible values.
> 
> ---
>  Documentation/admin-guide/hw-vuln/mds.rst     | 33 ++++++++-----------
>  .../hw-vuln/processor_mmio_stale_data.rst     | 13 +++++++-
>  .../admin-guide/hw-vuln/tsx_async_abort.rst   | 32 ++++++++----------
>  3 files changed, 38 insertions(+), 40 deletions(-)
> 
> diff --git a/Documentation/admin-guide/hw-vuln/mds.rst b/Documentation/admin-guide/hw-vuln/mds.rst
> index 48ca0bd85..0fe98151a 100644
> --- a/Documentation/admin-guide/hw-vuln/mds.rst
> +++ b/Documentation/admin-guide/hw-vuln/mds.rst
> @@ -102,9 +102,19 @@ The possible values in this file are:
>       * - '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. See :ref:`vmwerv`
> +       - 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.
> @@ -119,23 +129,6 @@ to the above information:
>      'SMT Host state unknown'  Kernel runs in a VM, Host SMT state unknown
>      ========================  ============================================
>  
> -.. _vmwerv:
> -
> -Best effort mitigation mode
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -  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.
> -
> -  The state in the mds sysfs file reflects this situation accordingly.
> -

This deletion leaves an extra newline. Same for TAA.

>  Mitigation mechanism
>  -------------------------
> 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 c98fd1190..1302fd1b5 100644
> --- a/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
> +++ b/Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst
> @@ -225,8 +225,19 @@ The possible values in this file are:
>       * - '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
> +       - 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.
> diff --git a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
> index 014167ef8..c6400fe6b 100644
> --- a/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
> +++ b/Documentation/admin-guide/hw-vuln/tsx_async_abort.rst
> @@ -98,7 +98,19 @@ The possible values in this file are:
>     * - '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 system tries to clear the buffers but the microcode might not support the operation.
> +     - 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'
> @@ -106,24 +118,6 @@ The possible values in this file are:
>     * - 'Not affected'
>       - The CPU is not affected by this issue.
>  
> -.. _ucode_needed:
> -
> -Best effort mitigation mode
> -^^^^^^^^^^^^^^^^^^^^^^^^^^^
> -
> -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.
> -
> -The state in the tsx_async_abort sysfs file reflects this situation
> -accordingly.
> -

Reviewed-by: Pawan Gupta <pawan.kumar.gupta@linux.intel.com>