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
