Re: [PATCH v2] Documentation: Use grid table over list table

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Fri, 06 Sep 2024, Takahiro Itazuri <itazur@xxxxxxxxxx> 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@xxxxxxxxxx>
> ---
> 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@xxxxxxxxxx/

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




[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux