Skip to contentSkip to conversation

Documentation fixes for kvm-upstream-workaround

PATCH In review Bagas Sanjaya 2 participants 5 messages Aug 17, 2022 – Aug 23, 2022

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

v2 cover Documentation fixes for kvm-upstream-workaround

Here is documentation fixes for kvm-upstream-workaround branch of TDX tree [1]. The fixes below should be self-explanatory.

Changes since v1 [2]:
- Wrap description of "shutdown" status to fit the table
- Add Reported-by from kernel test robot

[1]: https://github.com/intel/tdx.git
[2]: https://lore.kernel.org/linux-doc/[email protected]/

Bagas Sanjaya (3):
Documentation: ABI: tdx: fix formatting in ABI documentation
Documentation: ABI: tdx: grammar improv
Documentation: kvm: enclose the final closing brace in code block

 Documentation/ABI/testing/sysfs-firmware-tdx | 62 ++++++++++----------
 Documentation/virt/kvm/api.rst               |  2 +-
 2 files changed, 33 insertions(+), 31 deletions(-)

base-commit: 85c097fdd1667a842a9e75d8f658fc16bd72981a

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH v2 1/3 Documentation: ABI: tdx: fix formatting in ABI documentation

Sphinx reported many warnings on ABI testing symbols doc entry:

Documentation/ABI/testing/sysfs-firmware-tdx:2: WARNING: Unexpected indentation. Documentation/ABI/testing/sysfs-firmware-tdx:2: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/ABI/testing/sysfs-firmware-tdx:2: WARNING: Malformed table.
Bottom/header table border does not match top border.

=============== ================================================
<snipped>
================== ============================================ Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Blank line required after table. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Unexpected indentation. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Unexpected indentation. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Unexpected indentation. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Block quote ends without a blank line; unexpected unindent. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/ABI/testing/sysfs-firmware-tdx:22: WARNING: Malformed table.
No bottom table border found.

================== ============================================ <snipped>

Fix the table and lists formatting.

Fixes 12cafff9983dad ("x86/virt/tdx: Export TDX keyid number and status of TDX module via sysfs")
---
 Documentation/ABI/testing/sysfs-firmware-tdx | 32 ++++++++++++--------
 1 file changed, 19 insertions(+), 13 deletions(-)
Documentation/ABI/testing/sysfs-firmware-tdx +19 -13
index eba50870ba0e95..bd743d758d7d49 100644
@@ -2,6 +2,7 @@ What:           /sys/firmware/tdx/
 Date:           March 2022
 KernelVersion:  5.17
 Contact:        Isaku Yamahata <[email protected]>, [email protected]
+Users:          libvirt
 Description:
                 Intel's Trust Domain Extensions (TDX) protect guest VMs from
                 malicious hosts and some physical attacks.  This directory
@@ -12,16 +13,17 @@ Description:
                 the first phase firmware loader (a.k.a NP-SEAMLDR) that loads
                 the next loader and the second phase firmware loader(a.k.a
                 P-SEAMLDR) that loads the TDX firmware(a.k.a the "TDX module").
+
                 =============== ================================================
                 keyid_num       the number of SEAM keyid as an hexadecimal
                                 number with the "0x" prefix.
                 =============== ================================================
-Users:          libvirt
 
 What:           /sys/firmware/tdx/tdx_module/
 Date:           March 2022
 KernelVersion:  5.17
 Contact:        Isaku Yamahata <[email protected]>, [email protected]
+Users:          libvirt
 Description:
                 The TDX requires a firmware as known as the TDX module.  It comes
                 with its attributes, vendor_id, build_data, build_num,
@@ -36,19 +38,23 @@ Description:
 
                 ================== ============================================
                 status             string of the TDX module status.
-                                   "unknown"
-                                   "none": the TDX module is not loaded
-                                   "loaded": The TDX module is loaded, but not
-                                             initialized
-                                   "initialized": the TDX module is fully
-                                                  initialized
-                                   "shutdown": the TDX module is shutdown due to
-                                               error during initialization.
+
+                                   * "unknown", "none": the TDX module is not
+                                     loaded
+                                   * "loaded": The TDX module is loaded, but
+                                     not initialized
+                                   * "initialized": the TDX module is fully
+                                     initialized
+                                   * "shutdown": the TDX module is shutdown due
+                                     to error during initialization.
+
                 attributes         32bit flags of the TDX module attributes as
                                    a hexadecimal number with the "0x" prefix.
-                                   Bits 31 - a production module(0) or
-                                             a debug module(1).
-                                   Bits 30:0 Reserved - set to 0.
+
+                                   * Bits 31 - a production module(0) or
+                                     a debug module(1).
+                                   * Bits 30:0 Reserved - set to 0.
+
                 vendor_id          vendor ID as a hexadecimal number with the
                                    "0x" prefix.
                 build_date         build date in yyyymmdd BCD format.
@@ -59,4 +65,4 @@ Description:
                 major_version      major versionas a hexadecimal number with
                                    the "0x" prefix.
                 ================== ============================================
-Users:          libvirt
\ No newline at end of file
+
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#2 lore raw

PATCH v2 2/3 Documentation: ABI: tdx: grammar improv

In reply to Bagas Sanjaya

Improve the grammar used in TDX ABI documentation.

Fixes 12cafff9983dad ("x86/virt/tdx: Export TDX keyid number and status of TDX module via sysfs")
Fixes 5318e72c20e45a ("x86/virt/tdx: Export information about the TDX

module via sysfs")

---
 Documentation/ABI/testing/sysfs-firmware-tdx | 32 +++++++++-----------
 1 file changed, 14 insertions(+), 18 deletions(-)
Documentation/ABI/testing/sysfs-firmware-tdx +14 -18
index bd743d758d7d49..0f2feff311f047 100644
@@ -8,11 +8,11 @@ Description:
                 malicious hosts and some physical attacks.  This directory
                 represents the entry point directory for the TDX.
 
-                the TDX requires the TDX firmware to load into an isolated
-                memory region.  It requires a two-step loading process.  It uses
-                the first phase firmware loader (a.k.a NP-SEAMLDR) that loads
-                the next loader and the second phase firmware loader(a.k.a
-                P-SEAMLDR) that loads the TDX firmware(a.k.a the "TDX module").
+                This feature requires the TDX firmware to load into an isolated
+                memory region.  It uses two-step loading process; the first
+                phase is NP-SEAMLDR loader that loads the next one and the
+                second phase is P-SEAMLDR loader that loads the TDX firmware
+                (a.k.a the "TDX module").
 
                 =============== ================================================
                 keyid_num       the number of SEAM keyid as an hexadecimal
@@ -25,16 +25,12 @@ KernelVersion:  5.17
 Contact:        Isaku Yamahata <[email protected]>, [email protected]
 Users:          libvirt
 Description:
-                The TDX requires a firmware as known as the TDX module.  It comes
-                with its attributes, vendor_id, build_data, build_num,
-                minor_version, major_version, etc.
-
-                Provides the information about the TDX module loaded on the
-                platform.  It contains the following read-only files.  The
-                information corresponds to the data structure, TDSYSINFO_STRUCT.
-                The admins or VMM management software like libvirt can refer to
-                that information, determine if TDX is supported, and identify
-                the loaded the TDX module.
+                The TDX feature requires a firmware that is known as the TDX
+                module. The module exposes its information in the following
+                read-only files. The information corresponds to the data
+                structure named TDSYSINFO_STRUCT. Administrators or VMM
+                managers like libvirt can refer to it to determine if TDX is
+                supported and identify the loaded module.
 
                 ================== ============================================
                 status             string of the TDX module status.
@@ -48,12 +44,12 @@ Description:
                                    * "shutdown": the TDX module is shutdown due
                                      to error during initialization.
 
-                attributes         32bit flags of the TDX module attributes as
+                attributes         32-bit flags of the TDX module attributes as
                                    a hexadecimal number with the "0x" prefix.
 
                                    * Bits 31 - a production module(0) or
                                      a debug module(1).
-                                   * Bits 30:0 Reserved - set to 0.
+                                   * Bits 0-30 - Reserved - set to 0.
 
                 vendor_id          vendor ID as a hexadecimal number with the
                                    "0x" prefix.
@@ -62,7 +58,7 @@ Description:
                                    the "0x" prefix.
                 minor_version      minor version as a hexadecimal number with
                                    the "0x" prefix.
-                major_version      major versionas a hexadecimal number with
+                major_version      major version as a hexadecimal number with
                                    the "0x" prefix.
                 ================== ============================================
 
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw

PATCH v2 3/3 Documentation: kvm: enclose the final closing brace in code block

In reply to Bagas Sanjaya

Sphinx reported literal block warning:

Documentation/virt/kvm/api.rst:1362: WARNING: Literal block ends without a blank line; unexpected unindent.

The warning is caused by the final closing brace in KVM_SET_USER_MEMORY_REGION struct definition is not indented as literal code block.

Indent the closing brace to fix the warning.

Fixes bb90daae9d7551 ("KVM: Extend the memslot to support fd-based private memory")
---
 Documentation/virt/kvm/api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/virt/kvm/api.rst +1 -1
index d9d43078080030..4acf4d1c95c099 100644
@@ -1359,7 +1359,7 @@ yet and must be cleared on entry.
 	__u32 private_fd;
 	__u32 pad1;
 	__u64 pad2[14];
-};
+  };
 
   /\* for kvm_memory_region::flags \*/
   #define KVM_MEM_LOG_DIRTY_PAGES	(1UL << 0)
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#4 lore raw
In reply to Bagas Sanjaya
Quoted 2 lines · Bagas Sanjaya

Here is documentation fixes for kvm-upstream-workaround branch of TDX tree [1]. The fixes below should be self-explanatory.

Thanks for patches. I'll merge it into the repo.

Signature · 1 line
Isaku Yamahata <[email protected]>