[PATCH 00/12] Documentation: tdx: documentation fixes

[PATCH 00/12] Documentation: tdx: documentation fixes

[Bagas Sanjaya]

Here is the documentation fixes for KVM TDX feature tree ([1]). There
are 58 new warnings reported when making htmldocs, which are fixed.

[1]: https://github.com/intel/tdx/tree/kvm-upstream

Bagas Sanjaya (12):
  Documentation: kvm: Pad bullet lists with blank line
  Documentation: kvm: tdx: Use appropriate subbullet marker
  Documentation: kvm: tdx: Add footnote markers
  Documentation: kvm: tdx: Use bullet list for public kvm trees
  Documentation: kvm: tdx: title typofix
  Documentation: kvm: tdx-tdp-mmu: Add blank line padding for lists
  Documentation: kvm: tdx-tdp-mmu: Use literal code block for EPT
    violation diagrams
  Documentation: kvm: tdx-tdp-mmu: Properly format nested list for EPT
    state machine
  Documentation: kvm: tdx-tdp-mmu: Add blank line padding to lists in
    concurrent sections
  Documentation: x86: Enclose TDX initialization code inside code block
  Documentation: x86: Use literal code block for TDX dmesg output
  Documentation: kvm: Add TDX documentation to KVM table of contents

 Documentation/virt/kvm/index.rst       |   4 +
 Documentation/virt/kvm/intel-tdx.rst   | 114 ++++++++++----
 Documentation/virt/kvm/tdx-tdp-mmu.rst | 198 ++++++++++++++++---------
 Documentation/x86/tdx.rst              |  32 ++--
 4 files changed, 229 insertions(+), 119 deletions(-)


base-commit: 7af4efe32638544aecb58ed7365d0ef2ea6f85ea
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 01/12] Documentation: kvm: Pad bullet lists with blank line

[Bagas Sanjaya]

There are many "unexpected indentation" warnings due to missing blank line
padding surrounding bullet lists.

One of these are reported by kernel test robot:

Documentation/virt/kvm/intel-tdx.rst:181: WARNING: Enumerated list ends without a blank line; unexpected unindent.

Add the paddings. While at it, align TDX control flow list.

Link: https://lore.kernel.org/linux-doc/202207050428.5xG5lJOv-lkp@intel.com/
Fixes: 9e54fa1ac03df3 ("Documentation/virtual/kvm: Document on Trust Domain Extensions(TDX)")
Reported-by: kernel test robot <lkp@intel.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/intel-tdx.rst | 75 ++++++++++++++++++++++------
 1 file changed, 61 insertions(+), 14 deletions(-)

diff --git a/Documentation/virt/kvm/intel-tdx.rst b/Documentation/virt/kvm/intel-tdx.rst
index 3fae2cf9e5341d..46ad32f3248e40 100644
--- a/Documentation/virt/kvm/intel-tdx.rst
+++ b/Documentation/virt/kvm/intel-tdx.rst
@@ -178,26 +178,30 @@ In addition to KVM normal flow, new TDX ioctls need to be called.  The control f
 looks like as follows.
 
 #. system wide capability check
-  * KVM_CAP_VM_TYPES: check if VM type is supported and if TDX_VM_TYPE is
-    supported.
+
+   * KVM_CAP_VM_TYPES: check if VM type is supported and if TDX_VM_TYPE is
+     supported.
 
 #. creating VM
-  * KVM_CREATE_VM
-  * KVM_TDX_CAPABILITIES: query if TDX is supported on the platform.
-  * KVM_TDX_INIT_VM: pass TDX specific VM parameters.
+
+   * KVM_CREATE_VM
+   * KVM_TDX_CAPABILITIES: query if TDX is supported on the platform.
+   * KVM_TDX_INIT_VM: pass TDX specific VM parameters.
 
 #. creating VCPU
-  * KVM_CREATE_VCPU
-  * KVM_TDX_INIT_VCPU: pass TDX specific VCPU parameters.
+
+   * KVM_CREATE_VCPU
+   * KVM_TDX_INIT_VCPU: pass TDX specific VCPU parameters.
 
 #. initializing guest memory
-  * allocate guest memory and initialize page same to normal KVM case
-    In TDX case, parse and load TDVF into guest memory in addition.
-  * KVM_TDX_INIT_MEM_REGION to add and measure guest pages.
-    If the pages has contents above, those pages need to be added.
-    Otherwise the contents will be lost and guest sees zero pages.
-  * KVM_TDX_FINALIAZE_VM: Finalize VM and measurement
-    This must be after KVM_TDX_INIT_MEM_REGION.
+
+   * allocate guest memory and initialize page same to normal KVM case
+     In TDX case, parse and load TDVF into guest memory in addition.
+   * KVM_TDX_INIT_MEM_REGION to add and measure guest pages.
+     If the pages has contents above, those pages need to be added.
+     Otherwise the contents will be lost and guest sees zero pages.
+   * KVM_TDX_FINALIAZE_VM: Finalize VM and measurement
+     This must be after KVM_TDX_INIT_MEM_REGION.
 
 #. run vcpu
 
@@ -225,41 +229,58 @@ Several points to be considered.
     a centralized file is acceptable.
 
 - Wrapping kvm x86_ops: The current choice
+
   Introduce dedicated file for arch/x86/kvm/vmx/main.c (the name,
   main.c, is just chosen to show main entry points for callbacks.) and
   wrapper functions around all the callbacks with
   "if (is-tdx) tdx-callback() else vmx-callback()".
 
   Pros:
+
   - No major change in common x86 KVM code. The change is (mostly)
     contained under arch/x86/kvm/vmx/.
   - When TDX is disabled(CONFIG_INTEL_TDX_HOST=n), the overhead is
     optimized out.
   - Micro optimization by avoiding function pointer.
+
   Cons:
+
   - Many boiler plates in arch/x86/kvm/vmx/main.c.
 
 Alternative:
+
 - Introduce another callback layer under arch/x86/kvm/vmx.
+
   Pros:
+
   - No major change in common x86 KVM code. The change is (mostly)
     contained under arch/x86/kvm/vmx/.
   - clear separation on callbacks.
+
   Cons:
+
   - overhead in VMX even when TDX is disabled(CONFIG_INTEL_TDX_HOST=n).
 
 - Allow per-VM kvm_x86_ops callbacks instead of global kvm_x86_ops
+
   Pros:
+
   - clear separation on callbacks.
+
   Cons:
+
   - Big change in common x86 code.
   - overhead in common code even when TDX is
     disabled(CONFIG_INTEL_TDX_HOST=n).
 
 - Introduce new directory arch/x86/kvm/tdx
+
   Pros:
+
   - It clarifies that TDX is different from VMX.
+
   Cons:
+
   - Given the level of code sharing, it complicates code sharing.
 
 KVM MMU Changes
@@ -291,26 +312,38 @@ with host(if set to 1) or private to TD(if cleared to 0).
     = 51 or 47 bit set for TDX case.
 
   Pros:
+
   - Large code reuse with minimal new hooks.
   - Execution path is same.
+
   Cons:
+
   - Complicates the existing code.
   - Repurpose kvm_mmu_page as shadow of Secure-EPT can be confusing.
 
 Alternative:
+
 - Replace direct read/write on EPT entry with TDX-SEAM call by
   introducing callbacks on EPT entry.
+
   Pros:
+
   - Straightforward.
+
   Cons:
+
   - Too many touching point.
   - Too slow due to TDX-SEAM call.
   - Overhead even when TDX is disabled(CONFIG_INTEL_TDX_HOST=n).
 
 - Sprinkle "if (is-tdx)" for TDX special case
+
   Pros:
+
   - Straightforward.
+
   Cons:
+
   - The result is non-generic and ugly.
   - Put TDX specific logic into common KVM MMU code.
 
@@ -320,20 +353,30 @@ Additional KVM API are needed to control TD VMs. The operations on TD
 VMs are specific to TDX.
 
 - Piggyback and repurpose KVM_MEMORY_ENCRYPT_OP
+
   Although not all operation isn't memory encryption, repupose to get
   TDX specific ioctls.
+
   Pros:
+
   - No major change in common x86 KVM code.
+
   Cons:
+
   - The operations aren't actually memory encryption, but operations
     on TD VMs.
 
 Alternative:
+
 - Introduce new ioctl for guest protection like
   KVM_GUEST_PROTECTION_OP and introduce subcommand for TDX.
+
   Pros:
+
   - Clean name.
+
   Cons:
+
   - One more new ioctl for guest protection.
   - Confusion with KVM_MEMORY_ENCRYPT_OP with KVM_GUEST_PROTECTION_OP.
 
@@ -341,9 +384,13 @@ Alternative:
   KVM_MEMORY_ENCRYPT_OP as same value for user API for compatibility.
   "#define KVM_MEMORY_ENCRYPT_OP KVM_GUEST_PROTECTION_OP" for uapi
   compatibility.
+
   Pros:
+
   - No new ioctl with more suitable name.
+
   Cons:
+
   - May cause confusion to the existing user program.
 
 
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 02/12] Documentation: kvm: tdx: Use appropriate subbullet marker

[Bagas Sanjaya]

Sphinx only supports dash (-) and asterisk (*) as bullet marker. Use
them instead of dot (.) and equal (=).

Fixes: 9e54fa1ac03df3 ("Documentation/virtual/kvm: Document on Trust Domain Extensions(TDX)")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/intel-tdx.rst | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/virt/kvm/intel-tdx.rst b/Documentation/virt/kvm/intel-tdx.rst
index 46ad32f3248e40..7a7c17da3a045f 100644
--- a/Documentation/virt/kvm/intel-tdx.rst
+++ b/Documentation/virt/kvm/intel-tdx.rst
@@ -216,15 +216,16 @@ The main issue for it is that the logic of kvm_x86_ops callbacks for
 TDX is different from VMX. On the other hand, the variable,
 kvm_x86_ops, is global single variable. Not per-VM, not per-vcpu.
 
-Several points to be considered.
-  . No or minimal overhead when TDX is disabled(CONFIG_INTEL_TDX_HOST=n).
-  . Avoid overhead of indirect call via function pointers.
-  . Contain the changes under arch/x86/kvm/vmx directory and share logic
+Several points to be considered:
+
+  * No or minimal overhead when TDX is disabled(CONFIG_INTEL_TDX_HOST=n).
+  * Avoid overhead of indirect call via function pointers.
+  * Contain the changes under arch/x86/kvm/vmx directory and share logic
     with VMX for maintenance.
     Even though the ways to operation on VM (VMX instruction vs TDX
     SEAM call) is different, the basic idea remains same. So, many
     logic can be shared.
-  . Future maintenance
+  * Future maintenance
     The huge change of kvm_x86_ops in (near) future isn't expected.
     a centralized file is acceptable.
 
@@ -295,21 +296,23 @@ One bit of GPA (51 or 47 bit) is repurposed so that it means shared
 with host(if set to 1) or private to TD(if cleared to 0).
 
 - The current implementation
-  . Reuse the existing MMU code with minimal update.  Because the
+
+  * Reuse the existing MMU code with minimal update.  Because the
     execution flow is mostly same. But additional operation, TDX call
     for S-EPT, is needed. So add hooks for it to kvm_x86_ops.
-  . For performance, minimize TDX SEAM call to operate on S-EPT. When
+  * For performance, minimize TDX SEAM call to operate on S-EPT. When
     getting corresponding S-EPT pages/entry from faulting GPA, don't
     use TDX SEAM call to read S-EPT entry. Instead create shadow copy
     in host memory.
     Repurpose the existing kvm_mmu_page as shadow copy of S-EPT and
     associate S-EPT to it.
-  . Treats share bit as attributes. mask/unmask the bit where
+  * Treats share bit as attributes. mask/unmask the bit where
     necessary to keep the existing traversing code works.
     Introduce kvm.arch.gfn_shared_mask and use "if (gfn_share_mask)"
     for special case.
-    = 0 : for non-TDX case
-    = 51 or 47 bit set for TDX case.
+
+    * 0 : for non-TDX case
+    * 51 or 47 bit set for TDX case.
 
   Pros:
 
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 03/12] Documentation: kvm: tdx: Add footnote markers

[Bagas Sanjaya]

Sphinx reported unreferenced footnotes warnings:

Documentation/virt/kvm/intel-tdx.rst:353: WARNING: Footnote [1] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:355: WARNING: Footnote [2] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:357: WARNING: Footnote [3] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:359: WARNING: Footnote [4] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:361: WARNING: Footnote [5] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:363: WARNING: Footnote [6] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:365: WARNING: Footnote [7] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:367: WARNING: Footnote [8] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:370: WARNING: Footnote [9] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:372: WARNING: Footnote [10] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:375: WARNING: Footnote [11] is not referenced.
Documentation/virt/kvm/intel-tdx.rst:380: WARNING: Footnote [12] is not referenced.

Add missing reference markers to fix the warnings. While at it, reword
"Overview" section paragraph.

Fixes: 9e54fa1ac03df3 ("Documentation/virtual/kvm: Document on Trust Domain Extensions(TDX)")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/intel-tdx.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/virt/kvm/intel-tdx.rst b/Documentation/virt/kvm/intel-tdx.rst
index 7a7c17da3a045f..7371e152021621 100644
--- a/Documentation/virt/kvm/intel-tdx.rst
+++ b/Documentation/virt/kvm/intel-tdx.rst
@@ -8,9 +8,11 @@ Overview
 ========
 TDX stands for Trust Domain Extensions which isolates VMs from
 the virtual-machine manager (VMM)/hypervisor and any other software on
-the platform. [1]
-For details, the specifications, [2], [3], [4], [5], [6], [7], are
-available.
+the platform. For details, see the specifications [1]_, whitepaper [2]_,
+architectural extensions specification [3]_, module documentation [4]_,
+loader interface specification [5]_, guest-hypervisor communication
+interface [6]_, virtual firmware design guide [7]_, and other resources
+([8]_, [9]_, [10]_, [11]_, and [12]_).
 
 
 API description
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 04/12] Documentation: kvm: tdx: Use bullet list for public kvm trees

[Bagas Sanjaya]

The 8th external reference (public trees), doesn't have bullet list for
listing, so the reference is rendered as continous paragraph instead.

Use bullet list for the reference.

Fixes: 9e54fa1ac03df3 ("Documentation/virtual/kvm: Document on Trust Domain Extensions(TDX)")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/intel-tdx.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/virt/kvm/intel-tdx.rst b/Documentation/virt/kvm/intel-tdx.rst
index 7371e152021621..1e3ad0ca2925bf 100644
--- a/Documentation/virt/kvm/intel-tdx.rst
+++ b/Documentation/virt/kvm/intel-tdx.rst
@@ -417,8 +417,10 @@ References
 .. [7] Intel TDX Virtual Firmware Design Guide
    https://software.intel.com/content/dam/develop/external/us/en/documents/tdx-virtual-firmware-design-guide-rev-1.
 .. [8] intel public github
-   kvm TDX branch: https://github.com/intel/tdx/tree/kvm
-   TDX guest branch: https://github.com/intel/tdx/tree/guest
+
+   * kvm TDX branch: https://github.com/intel/tdx/tree/kvm
+   * TDX guest branch: https://github.com/intel/tdx/tree/guest
+
 .. [9] tdvf
     https://github.com/tianocore/edk2-staging/tree/TDVF
 .. [10] KVM forum 2020: Intel Virtualization Technology Extensions to
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 05/12] Documentation: kvm: tdx: title typofix

[Bagas Sanjaya]

The page title contains misspelled "Dodmain" instead of "Domain" and
missing space before abbreviation parentheses. Fix both mistakes.

Fixes: 9e54fa1ac03df3 ("Documentation/virtual/kvm: Document on Trust Domain Extensions(TDX)")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/intel-tdx.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/virt/kvm/intel-tdx.rst b/Documentation/virt/kvm/intel-tdx.rst
index 1e3ad0ca2925bf..5288631c80122d 100644
--- a/Documentation/virt/kvm/intel-tdx.rst
+++ b/Documentation/virt/kvm/intel-tdx.rst
@@ -1,7 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
 ===================================
-Intel Trust Dodmain Extensions(TDX)
+Intel Trust Domain Extensions (TDX)
 ===================================
 
 Overview
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 06/12] Documentation: kvm: tdx-tdp-mmu: Add blank line padding for lists

[Bagas Sanjaya]

There are many "unexpected indentations"-"block quote"-"bullet list"
warnings that are caused by missing blank line padding on
bullet lists at tdx-tdp-mmu.rst.

Add the padding to fix the warnings.

Fixes: 7af4efe3263854 ("KVM: x86: design documentation on TDX support of x86 KVM TDP MMU")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/tdx-tdp-mmu.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/Documentation/virt/kvm/tdx-tdp-mmu.rst b/Documentation/virt/kvm/tdx-tdp-mmu.rst
index 6d63bb75f785ab..c9d5fc43a6ca7a 100644
--- a/Documentation/virt/kvm/tdx-tdp-mmu.rst
+++ b/Documentation/virt/kvm/tdx-tdp-mmu.rst
@@ -63,32 +63,39 @@ Instead, TDX SEAMCALL API is used.  Several SEAMCALLs correspond to operation on
 the EPT entry.
 
 * TDH.MEM.SEPT.ADD():
+
   Add a secure EPT page from the secure EPT tree.  This corresponds to updating
   the non-leaf EPT entry with present bit set
 
 * TDH.MEM.SEPT.REMOVE():
+
   Remove the secure page from the secure EPT tree.  There is no corresponding
   to the EPT operation.
 
 * TDH.MEM.SEPT.RD():
+
   Read the secure EPT entry.  This corresponds to reading the EPT entry as
   memory.  Please note that this is much slower than direct memory reading.
 
 * TDH.MEM.PAGE.ADD() and TDH.MEM.PAGE.AUG():
+
   Add a private page to the secure EPT tree.  This corresponds to updating the
   leaf EPT entry with present bit set.
 
 * THD.MEM.PAGE.REMOVE():
+
   Remove a private page from the secure EPT tree.  There is no corresponding
   to the EPT operation.
 
 * TDH.MEM.RANGE.BLOCK():
+
   This (mostly) corresponds to clearing the present bit of the leaf EPT entry.
   Note that the private page is still linked in the secure EPT.  To remove it
   from the secure EPT, TDH.MEM.SEPT.REMOVE() and TDH.MEM.PAGE.REMOVE() needs to
   be called.
 
 * TDH.MEM.TRACK():
+
   Increment the TLB epoch counter. This (mostly) corresponds to EPT TLB flush.
   Note that the private page is still linked in the secure EPT.  To remove it
   from the secure EPT, tdh_mem_page_remove() needs to be called.
@@ -110,25 +117,34 @@ Dropping private page and TLB shootdown
 The procedure of dropping the private page looks as follows.
 
 1. TDH.MEM.RANGE.BLOCK(4K level)
+
    This mostly corresponds to clear the present bit in the EPT entry.  This
    prevents (or blocks) TLB entry from creating in the future.  Note that the
    private page is still linked in the secure EPT tree and the existing cache
    entry in the TLB isn't flushed.
+
 2. TDH.MEM.TRACK(range) and TLB shootdown
+
    This mostly corresponds to the EPT TLB shootdown.  Because all vcpus share
    the same Secure EPT, all vcpus need to flush TLB.
+
    * TDH.MEM.TRACK(range) by one vcpu.  It increments the global internal TLB
      epoch counter.
    * send IPI to remote vcpus
    * Other vcpu exits to VMM from guest TD and then re-enter. TDH.VP.ENTER().
    * TDH.VP.ENTER() checks the TLB epoch counter and If its TLB is old, flush
      TLB.
+
    Note that only single vcpu issues tdh_mem_track().
+
    Note that the private page is still linked in the secure EPT tree, unlike the
    conventional EPT.
+
 3. TDH.MEM.PAGE.PROMOTE, TDH.MEM.PAGEDEMOTE(), TDH.MEM.PAGE.RELOCATE(), or
    TDH.MEM.PAGE.REMOVE()
+
    There is no corresponding operation to the conventional EPT.
+
    * When changing page size (e.g. 4K <-> 2M) TDH.MEM.PAGE.PROMOTE() or
      TDH.MEM.PAGE.DEMOTE() is used.  During those operation, the guest page is
      kept referenced in the Secure EPT.
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 07/12] Documentation: kvm: tdx-tdp-mmu: Use literal code block for EPT violation diagrams

[Bagas Sanjaya]

EPT violation diagrams aren't inside literal code block, which trigger
"line block ends without a blank line" warning. Since these diagrams
aren't meant line blocks, use literal code block instead.

Fixes: 7af4efe3263854 ("KVM: x86: design documentation on TDX support of x86 KVM TDP MMU")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/tdx-tdp-mmu.rst | 39 +++++++++++++++++---------
 1 file changed, 25 insertions(+), 14 deletions(-)

diff --git a/Documentation/virt/kvm/tdx-tdp-mmu.rst b/Documentation/virt/kvm/tdx-tdp-mmu.rst
index c9d5fc43a6ca7a..f43ebb08f5cdad 100644
--- a/Documentation/virt/kvm/tdx-tdp-mmu.rst
+++ b/Documentation/virt/kvm/tdx-tdp-mmu.rst
@@ -169,30 +169,41 @@ hooks to KVM MMU to reuse the existing code.
 EPT violation on shared GPA
 ---------------------------
 (1) EPT violation on shared GPA or zapping shared GPA
-    walk down shared EPT tree (the existing code)
-        |
-        |
-        V
-shared EPT tree (CPU refers.)
+    ::
+
+       walk down shared EPT tree (the existing code)
+           |
+           |
+           V
+       shared EPT tree (CPU refers.)
+
 (2) update the EPT entry. (the existing code)
+
     TLB shootdown in the case of zapping.
 
 
 EPT violation on private GPA
 ----------------------------
 (1) EPT violation on private GPA or zapping private GPA
-    walk down the mirror of secure EPT tree (mostly same as the existing code)
-        |
-        |
-        V
-mirror of secure EPT tree (KVM MMU software only. reuse of the existing code)
+    ::
+
+       walk down the mirror of secure EPT tree (mostly same as the existing code)
+           |
+           |
+           V
+       mirror of secure EPT tree (KVM MMU software only. reuse of the existing code)
+
 (2) update the (mirrored) EPT entry. (mostly same as the existing code)
+
 (3) call the hooks with what EPT entry is changed
-        |
+    ::
+
+           |
         NEW: hooks in KVM MMU
-        |
-        V
-secure EPT root(CPU refers)
+           |
+           V
+        secure EPT root(CPU refers)
+
 (4) the TDX backend calls necessary TDX SEAMCALLs to update real secure EPT.
 
 The major modification is to add hooks for the TDX backend for additional
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 08/12] Documentation: kvm: tdx-tdp-mmu: Properly format nested list for EPT state machine

[Bagas Sanjaya]

The state machine list for EPT entry state machine basically use nested
bullet lists to describe all possible results. However, the list is
badly formatted, hence triggers many indentation warnings.

Fix the nested list formatting.

Fixes: 7af4efe3263854 ("KVM: x86: design documentation on TDX support of x86 KVM TDP MMU")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/tdx-tdp-mmu.rst | 134 ++++++++++++++-----------
 1 file changed, 76 insertions(+), 58 deletions(-)

diff --git a/Documentation/virt/kvm/tdx-tdp-mmu.rst b/Documentation/virt/kvm/tdx-tdp-mmu.rst
index f43ebb08f5cdad..c403e14fb223aa 100644
--- a/Documentation/virt/kvm/tdx-tdp-mmu.rst
+++ b/Documentation/virt/kvm/tdx-tdp-mmu.rst
@@ -306,76 +306,94 @@ for EPT violation path by penalizing MapGPA hypercall.
 
 The state machine of EPT entry
 ------------------------------
-(private EPT entry, shared EPT entry) =
-        (non-present, non-present):             private mapping is allowed
-        (present, non-present):                 private mapping is mapped
-        (non-present | SPTE_SHARED_MASK, non-present | SPTE_SHARED_MASK):
-                                                shared mapping is allowed
-        (non-present | SPTE_SHARED_MASK, present | SPTE_SHARED_MASK):
-                                                shared mapping is mapped
-        (present | SPTE_SHARED_MASK, any)       invalid combination
+* (private EPT entry, shared EPT entry)
 
-* map_gpa(private GPA): Mark the region that private GPA is allowed(NEW)
-        private EPT entry: clear SPTE_SHARED_MASK
-          present: nop
-          non-present: nop
-          non-present | SPTE_SHARED_MASK -> non-present (clear SPTE_SHARED_MASK)
+  * (non-present, non-present):
+       private mapping is allowed
+  * (present, non-present):
+       private mapping is mapped
+  * (non-present | SPTE_SHARED_MASK, non-present | SPTE_SHARED_MASK):
+       shared mapping is allowed
+  * (non-present | SPTE_SHARED_MASK, present | SPTE_SHARED_MASK):
+       shared mapping is mapped
+  * (present | SPTE_SHARED_MASK, any):
+       invalid combination
 
-        shared EPT entry: zap the entry, clear SPTE_SHARED_MASK
-          present: invalid
-          non-present -> non-present: nop
-          present | SPTE_SHARED_MASK -> non-present
-          non-present | SPTE_SHARED_MASK -> non-present
+* map_gpa (private GPA): Mark the region that private GPA is allowed(NEW)
 
-* map_gpa(shared GPA): Mark the region that shared GPA is allowed(NEW)
-        private EPT entry: zap and set SPTE_SHARED_MASK
-          present     -> non-present | SPTE_SHARED_MASK
-          non-present -> non-present | SPTE_SHARED_MASK
-          non-present | SPTE_SHARED_MASK: nop
+  * private EPT entry: clear SPTE_SHARED_MASK
 
-        shared EPT entry: set SPTE_SHARED_MASK
-          present: invalid
-          non-present -> non-present | SPTE_SHARED_MASK
-          present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK: nop
-          non-present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK: nop
+    * present: nop
+    * non-present: nop
+    * non-present | SPTE_SHARED_MASK -> non-present (clear SPTE_SHARED_MASK)
 
-* map(private GPA)
-        private EPT entry
-          present: nop
-          non-present -> present
-          non-present | SPTE_SHARED_MASK: nop. looping on EPT violation(NEW)
+  * shared EPT entry: zap the entry, clear SPTE_SHARED_MASK
 
-        shared EPT entry: nop
+    * present: invalid
+    * non-present -> non-present: nop
+    * present | SPTE_SHARED_MASK -> non-present
+    * non-present | SPTE_SHARED_MASK -> non-present
 
-* map(shared GPA)
-        private EPT entry: nop
+* map_gpa (shared GPA): Mark the region that shared GPA is allowed(NEW)
 
-        shared EPT entry
-          present: invalid
-          present | SPTE_SHARED_MASK: nop
-          non-present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK
-          non-present: nop. looping on EPT violation(NEW)
+  * private EPT entry: zap and set SPTE_SHARED_MASK
 
-* zap(private GPA)
-        private EPT entry: zap the entry with keeping SPTE_SHARED_MASK
-          present -> non-present
-          present | SPTE_SHARED_MASK: invalid
-          non-present: nop as is_shadow_present_pte() is checked
-          non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
-                                          checked
+    * present     -> non-present | SPTE_SHARED_MASK
+    * non-present -> non-present | SPTE_SHARED_MASK
+    * non-present | SPTE_SHARED_MASK: nop
 
-        shared EPT entry: nop
+  * shared EPT entry: set SPTE_SHARED_MASK
 
-* zap(shared GPA)
-        private EPT entry: nop
+    * present: invalid
+    * non-present -> non-present | SPTE_SHARED_MASK
+    * present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK: nop
+    * non-present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK: nop
 
-        shared EPT entry: zap
-          any -> non-present
-          present: invalid
-          present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK
-          non-present: nop as is_shadow_present_pte() is checked
-          non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
-                                          checked
+* map (private GPA)
+
+  * private EPT entry
+
+    * present: nop
+    * non-present -> present
+    * non-present | SPTE_SHARED_MASK: nop. looping on EPT violation(NEW)
+
+  * shared EPT entry: nop
+
+* map (shared GPA)
+
+  * private EPT entry: nop
+
+  * shared EPT entry:
+
+    * present: invalid
+    * present | SPTE_SHARED_MASK: nop
+    * non-present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK
+    * non-present: nop. looping on EPT violation(NEW)
+
+* zap (private GPA)
+
+  * private EPT entry: zap the entry with keeping SPTE_SHARED_MASK
+
+    * present -> non-present
+    * present | SPTE_SHARED_MASK: invalid
+    * non-present: nop as is_shadow_present_pte() is checked
+    * non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
+      checked
+
+  * shared EPT entry: nop
+
+* zap (shared GPA)
+
+  * private EPT entry: nop
+
+  * shared EPT entry: zap
+
+    * any -> non-present
+    * present: invalid
+    * present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK
+    * non-present: nop as is_shadow_present_pte() is checked
+    * non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
+      checked
 
 
 The original TDP MMU and race condition
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 08/12] Documentation: kvm: tdx-tdp-mmu: Properly format nested list for EPT state machine

[Bagas Sanjaya]

On Sat, Jul 09, 2022 at 11:20:34AM +0700, Bagas Sanjaya wrote:
>  The state machine of EPT entry
>  ------------------------------
> -(private EPT entry, shared EPT entry) =
> -        (non-present, non-present):             private mapping is allowed
> -        (present, non-present):                 private mapping is mapped
> -        (non-present | SPTE_SHARED_MASK, non-present | SPTE_SHARED_MASK):
> -                                                shared mapping is allowed
> -        (non-present | SPTE_SHARED_MASK, present | SPTE_SHARED_MASK):
> -                                                shared mapping is mapped
> -        (present | SPTE_SHARED_MASK, any)       invalid combination
> +* (private EPT entry, shared EPT entry)
>  
> -* map_gpa(private GPA): Mark the region that private GPA is allowed(NEW)
> -        private EPT entry: clear SPTE_SHARED_MASK
> -          present: nop
> -          non-present: nop
> -          non-present | SPTE_SHARED_MASK -> non-present (clear SPTE_SHARED_MASK)
> +  * (non-present, non-present):
> +       private mapping is allowed
> +  * (present, non-present):
> +       private mapping is mapped
> +  * (non-present | SPTE_SHARED_MASK, non-present | SPTE_SHARED_MASK):
> +       shared mapping is allowed
> +  * (non-present | SPTE_SHARED_MASK, present | SPTE_SHARED_MASK):
> +       shared mapping is mapped
> +  * (present | SPTE_SHARED_MASK, any):
> +       invalid combination
>  
> -        shared EPT entry: zap the entry, clear SPTE_SHARED_MASK
> -          present: invalid
> -          non-present -> non-present: nop
> -          present | SPTE_SHARED_MASK -> non-present
> -          non-present | SPTE_SHARED_MASK -> non-present
> +* map_gpa (private GPA): Mark the region that private GPA is allowed(NEW)
>  
> -* map_gpa(shared GPA): Mark the region that shared GPA is allowed(NEW)
> -        private EPT entry: zap and set SPTE_SHARED_MASK
> -          present     -> non-present | SPTE_SHARED_MASK
> -          non-present -> non-present | SPTE_SHARED_MASK
> -          non-present | SPTE_SHARED_MASK: nop
> +  * private EPT entry: clear SPTE_SHARED_MASK
>  
> -        shared EPT entry: set SPTE_SHARED_MASK
> -          present: invalid
> -          non-present -> non-present | SPTE_SHARED_MASK
> -          present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK: nop
> -          non-present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK: nop
> +    * present: nop
> +    * non-present: nop
> +    * non-present | SPTE_SHARED_MASK -> non-present (clear SPTE_SHARED_MASK)
>  
> -* map(private GPA)
> -        private EPT entry
> -          present: nop
> -          non-present -> present
> -          non-present | SPTE_SHARED_MASK: nop. looping on EPT violation(NEW)
> +  * shared EPT entry: zap the entry, clear SPTE_SHARED_MASK
>  
> -        shared EPT entry: nop
> +    * present: invalid
> +    * non-present -> non-present: nop
> +    * present | SPTE_SHARED_MASK -> non-present
> +    * non-present | SPTE_SHARED_MASK -> non-present
>  
> -* map(shared GPA)
> -        private EPT entry: nop
> +* map_gpa (shared GPA): Mark the region that shared GPA is allowed(NEW)
>  
> -        shared EPT entry
> -          present: invalid
> -          present | SPTE_SHARED_MASK: nop
> -          non-present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK
> -          non-present: nop. looping on EPT violation(NEW)
> +  * private EPT entry: zap and set SPTE_SHARED_MASK
>  
> -* zap(private GPA)
> -        private EPT entry: zap the entry with keeping SPTE_SHARED_MASK
> -          present -> non-present
> -          present | SPTE_SHARED_MASK: invalid
> -          non-present: nop as is_shadow_present_pte() is checked
> -          non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> -                                          checked
> +    * present     -> non-present | SPTE_SHARED_MASK
> +    * non-present -> non-present | SPTE_SHARED_MASK
> +    * non-present | SPTE_SHARED_MASK: nop
>  
> -        shared EPT entry: nop
> +  * shared EPT entry: set SPTE_SHARED_MASK
>  
> -* zap(shared GPA)
> -        private EPT entry: nop
> +    * present: invalid
> +    * non-present -> non-present | SPTE_SHARED_MASK
> +    * present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK: nop
> +    * non-present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK: nop
>  
> -        shared EPT entry: zap
> -          any -> non-present
> -          present: invalid
> -          present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK
> -          non-present: nop as is_shadow_present_pte() is checked
> -          non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> -                                          checked
> +* map (private GPA)
> +
> +  * private EPT entry
> +
> +    * present: nop
> +    * non-present -> present
> +    * non-present | SPTE_SHARED_MASK: nop. looping on EPT violation(NEW)
> +
> +  * shared EPT entry: nop
> +
> +* map (shared GPA)
> +
> +  * private EPT entry: nop
> +
> +  * shared EPT entry:
> +
> +    * present: invalid
> +    * present | SPTE_SHARED_MASK: nop
> +    * non-present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK
> +    * non-present: nop. looping on EPT violation(NEW)
> +
> +* zap (private GPA)
> +
> +  * private EPT entry: zap the entry with keeping SPTE_SHARED_MASK
> +
> +    * present -> non-present
> +    * present | SPTE_SHARED_MASK: invalid
> +    * non-present: nop as is_shadow_present_pte() is checked
> +    * non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> +      checked
> +
> +  * shared EPT entry: nop
> +
> +* zap (shared GPA)
> +
> +  * private EPT entry: nop
> +
> +  * shared EPT entry: zap
> +
> +    * any -> non-present
> +    * present: invalid
> +    * present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK
> +    * non-present: nop as is_shadow_present_pte() is checked
> +    * non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> +      checked

IMO, the state machine lists above should have used tables instead.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 08/12] Documentation: kvm: tdx-tdp-mmu: Properly format nested list for EPT state machine

[Isaku Yamahata]

On Sat, Jul 09, 2022 at 11:26:26AM +0700,
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> On Sat, Jul 09, 2022 at 11:20:34AM +0700, Bagas Sanjaya wrote:
> >  The state machine of EPT entry
> >  ------------------------------
> > -(private EPT entry, shared EPT entry) =
> > -        (non-present, non-present):             private mapping is allowed
> > -        (present, non-present):                 private mapping is mapped
> > -        (non-present | SPTE_SHARED_MASK, non-present | SPTE_SHARED_MASK):
> > -                                                shared mapping is allowed
> > -        (non-present | SPTE_SHARED_MASK, present | SPTE_SHARED_MASK):
> > -                                                shared mapping is mapped
> > -        (present | SPTE_SHARED_MASK, any)       invalid combination
> > +* (private EPT entry, shared EPT entry)
> >  
> > -* map_gpa(private GPA): Mark the region that private GPA is allowed(NEW)
> > -        private EPT entry: clear SPTE_SHARED_MASK
> > -          present: nop
> > -          non-present: nop
> > -          non-present | SPTE_SHARED_MASK -> non-present (clear SPTE_SHARED_MASK)
> > +  * (non-present, non-present):
> > +       private mapping is allowed
> > +  * (present, non-present):
> > +       private mapping is mapped
> > +  * (non-present | SPTE_SHARED_MASK, non-present | SPTE_SHARED_MASK):
> > +       shared mapping is allowed
> > +  * (non-present | SPTE_SHARED_MASK, present | SPTE_SHARED_MASK):
> > +       shared mapping is mapped
> > +  * (present | SPTE_SHARED_MASK, any):
> > +       invalid combination
> >  
> > -        shared EPT entry: zap the entry, clear SPTE_SHARED_MASK
> > -          present: invalid
> > -          non-present -> non-present: nop
> > -          present | SPTE_SHARED_MASK -> non-present
> > -          non-present | SPTE_SHARED_MASK -> non-present
> > +* map_gpa (private GPA): Mark the region that private GPA is allowed(NEW)
> >  
> > -* map_gpa(shared GPA): Mark the region that shared GPA is allowed(NEW)
> > -        private EPT entry: zap and set SPTE_SHARED_MASK
> > -          present     -> non-present | SPTE_SHARED_MASK
> > -          non-present -> non-present | SPTE_SHARED_MASK
> > -          non-present | SPTE_SHARED_MASK: nop
> > +  * private EPT entry: clear SPTE_SHARED_MASK
> >  
> > -        shared EPT entry: set SPTE_SHARED_MASK
> > -          present: invalid
> > -          non-present -> non-present | SPTE_SHARED_MASK
> > -          present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK: nop
> > -          non-present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK: nop
> > +    * present: nop
> > +    * non-present: nop
> > +    * non-present | SPTE_SHARED_MASK -> non-present (clear SPTE_SHARED_MASK)
> >  
> > -* map(private GPA)
> > -        private EPT entry
> > -          present: nop
> > -          non-present -> present
> > -          non-present | SPTE_SHARED_MASK: nop. looping on EPT violation(NEW)
> > +  * shared EPT entry: zap the entry, clear SPTE_SHARED_MASK
> >  
> > -        shared EPT entry: nop
> > +    * present: invalid
> > +    * non-present -> non-present: nop
> > +    * present | SPTE_SHARED_MASK -> non-present
> > +    * non-present | SPTE_SHARED_MASK -> non-present
> >  
> > -* map(shared GPA)
> > -        private EPT entry: nop
> > +* map_gpa (shared GPA): Mark the region that shared GPA is allowed(NEW)
> >  
> > -        shared EPT entry
> > -          present: invalid
> > -          present | SPTE_SHARED_MASK: nop
> > -          non-present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK
> > -          non-present: nop. looping on EPT violation(NEW)
> > +  * private EPT entry: zap and set SPTE_SHARED_MASK
> >  
> > -* zap(private GPA)
> > -        private EPT entry: zap the entry with keeping SPTE_SHARED_MASK
> > -          present -> non-present
> > -          present | SPTE_SHARED_MASK: invalid
> > -          non-present: nop as is_shadow_present_pte() is checked
> > -          non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> > -                                          checked
> > +    * present     -> non-present | SPTE_SHARED_MASK
> > +    * non-present -> non-present | SPTE_SHARED_MASK
> > +    * non-present | SPTE_SHARED_MASK: nop
> >  
> > -        shared EPT entry: nop
> > +  * shared EPT entry: set SPTE_SHARED_MASK
> >  
> > -* zap(shared GPA)
> > -        private EPT entry: nop
> > +    * present: invalid
> > +    * non-present -> non-present | SPTE_SHARED_MASK
> > +    * present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK: nop
> > +    * non-present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK: nop
> >  
> > -        shared EPT entry: zap
> > -          any -> non-present
> > -          present: invalid
> > -          present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK
> > -          non-present: nop as is_shadow_present_pte() is checked
> > -          non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> > -                                          checked
> > +* map (private GPA)
> > +
> > +  * private EPT entry
> > +
> > +    * present: nop
> > +    * non-present -> present
> > +    * non-present | SPTE_SHARED_MASK: nop. looping on EPT violation(NEW)
> > +
> > +  * shared EPT entry: nop
> > +
> > +* map (shared GPA)
> > +
> > +  * private EPT entry: nop
> > +
> > +  * shared EPT entry:
> > +
> > +    * present: invalid
> > +    * present | SPTE_SHARED_MASK: nop
> > +    * non-present | SPTE_SHARED_MASK -> present | SPTE_SHARED_MASK
> > +    * non-present: nop. looping on EPT violation(NEW)
> > +
> > +* zap (private GPA)
> > +
> > +  * private EPT entry: zap the entry with keeping SPTE_SHARED_MASK
> > +
> > +    * present -> non-present
> > +    * present | SPTE_SHARED_MASK: invalid
> > +    * non-present: nop as is_shadow_present_pte() is checked
> > +    * non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> > +      checked
> > +
> > +  * shared EPT entry: nop
> > +
> > +* zap (shared GPA)
> > +
> > +  * private EPT entry: nop
> > +
> > +  * shared EPT entry: zap
> > +
> > +    * any -> non-present
> > +    * present: invalid
> > +    * present | SPTE_SHARED_MASK -> non-present | SPTE_SHARED_MASK
> > +    * non-present: nop as is_shadow_present_pte() is checked
> > +    * non-present | SPTE_SHARED_MASK: nop as is_shadow_present_pte() is
> > +      checked
> 
> IMO, the state machine lists above should have used tables instead.

Makes sense. I'll convert those into tables.
-- 
Isaku Yamahata <isaku.yamahata@gmail.com>

[PATCH 09/12] Documentation: kvm: tdx-tdp-mmu: Add blank line padding to lists in concurrent sections

[Bagas Sanjaya]

The last warnings on tdx-tdp-mmu.rst are caused by missing blank line
padding at lists on "concurrent" sections. Add the padding.

Fixes: 7af4efe3263854 ("KVM: x86: design documentation on TDX support of x86 KVM TDP MMU")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/tdx-tdp-mmu.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/virt/kvm/tdx-tdp-mmu.rst b/Documentation/virt/kvm/tdx-tdp-mmu.rst
index c403e14fb223aa..f2170c154e18c3 100644
--- a/Documentation/virt/kvm/tdx-tdp-mmu.rst
+++ b/Documentation/virt/kvm/tdx-tdp-mmu.rst
@@ -418,8 +418,10 @@ Concurrent zapping
 2. freeze the EPT entry (atomically set the value to REMOVED_SPTE)
    If other vcpu froze the entry, restart page fault.
 3. TLB shootdown
+
    * send IPI to remote vcpus
    * TLB flush (local and remote)
+
    For each entry update, TLB shootdown is needed because of the
    concurrency.
 4. atomically set the EPT entry to the final value
@@ -429,6 +431,7 @@ Concurrent populating
 ---------------------
 In the case of populating the non-present EPT entry, atomically update the EPT
 entry.
+
 1. read lock
 2. atomically update the EPT entry
    If other vcpu frozen the entry or updated the entry, restart page fault.
@@ -436,6 +439,7 @@ entry.
 
 In the case of updating the present EPT entry (e.g. page migration), the
 operation is split into two.  Zapping the entry and populating the entry.
+
 1. read lock
 2. zap the EPT entry.  follow the concurrent zapping case.
 3. populate the non-present EPT entry.
@@ -451,7 +455,6 @@ In this case, the TLB shootdown is batched into one.
 3. TLB shootdown
 4. write unlock
 
-
 For Secure EPT, TDX SEAMCALLs are needed in addition to updating the mirrored
 EPT entry.
 
@@ -462,9 +465,11 @@ Add a hook for TDX SEAMCALLs at the step of the TLB shootdown.
 1. read lock
 2. freeze the EPT entry(set the value to REMOVED_SPTE)
 3. TLB shootdown via a hook
+
    * TLB.MEM.RANGE.BLOCK()
    * TLB.MEM.TRACK()
    * send IPI to remote vcpus
+
 4. set the EPT entry to the final value
 5. read unlock
 
@@ -477,7 +482,9 @@ condition.  A hook can be added.
 1. read lock
 2. freeze the EPT entry
 3. hook
+
    * TDH_MEM_SEPT_ADD() for non-leaf or TDH_MEM_PAGE_AUG() for leaf.
+
 4. set the EPT entry to the final value
 5. read unlock
 
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 10/12] Documentation: x86: Enclose TDX initialization code inside code block

[Bagas Sanjaya]

kernel test robot reported htmldocs warning on Documentation/x86/tdx.rst:

Documentation/x86/tdx.rst:69: WARNING: Unexpected indentation.
Documentation/x86/tdx.rst:70: WARNING: Block quote ends without a blank line; unexpected unindent.

These warnings above are due to missing code block marker before TDX
initialization code, which confuses Sphinx as normal block quote instead.

Add literal code block marker to fix the warnings.

Link: https://lore.kernel.org/linux-doc/202207042107.YqVvxdJz-lkp@intel.com/
Fixes: f05f595045dfc7 ("Documentation/x86: Add documentation for TDX host support")
Reported-by: kernel test robot <lkp@intel.com>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/x86/tdx.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
index 6c6b09ca6ba407..4430912a2e4f05 100644
--- a/Documentation/x86/tdx.rst
+++ b/Documentation/x86/tdx.rst
@@ -62,7 +62,7 @@ use it as 'metadata' for the TDX memory.  It also takes additional CPU
 time to initialize those metadata along with the TDX module itself.  Both
 are not trivial.  Current kernel doesn't choose to always initialize the
 TDX module during kernel boot, but provides a function tdx_init() to
-allow the caller to initialize TDX when it truly wants to use TDX:
+allow the caller to initialize TDX when it truly wants to use TDX::
 
         ret = tdx_init();
         if (ret)
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 10/12] Documentation: x86: Enclose TDX initialization code inside code block

[Kai Huang]

On Sat, 2022-07-09 at 11:20 +0700, Bagas Sanjaya wrote:
> kernel test robot reported htmldocs warning on Documentation/x86/tdx.rst:
> 
> Documentation/x86/tdx.rst:69: WARNING: Unexpected indentation.
> Documentation/x86/tdx.rst:70: WARNING: Block quote ends without a blank line; unexpected unindent.
> 
> These warnings above are due to missing code block marker before TDX
> initialization code, which confuses Sphinx as normal block quote instead.
> 
> Add literal code block marker to fix the warnings.

Thank you! will fix.

> 
> Link: https://lore.kernel.org/linux-doc/202207042107.YqVvxdJz-lkp@intel.com/
> Fixes: f05f595045dfc7 ("Documentation/x86: Add documentation for TDX host support")
> Reported-by: kernel test robot <lkp@intel.com>
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/x86/tdx.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
> index 6c6b09ca6ba407..4430912a2e4f05 100644
> --- a/Documentation/x86/tdx.rst
> +++ b/Documentation/x86/tdx.rst
> @@ -62,7 +62,7 @@ use it as 'metadata' for the TDX memory.  It also takes additional CPU
>  time to initialize those metadata along with the TDX module itself.  Both
>  are not trivial.  Current kernel doesn't choose to always initialize the
>  TDX module during kernel boot, but provides a function tdx_init() to
> -allow the caller to initialize TDX when it truly wants to use TDX:
> +allow the caller to initialize TDX when it truly wants to use TDX::
>  
>          ret = tdx_init();
>          if (ret)

[PATCH 11/12] Documentation: x86: Use literal code block for TDX dmesg output

[Bagas Sanjaya]

The dmesg output blocks are using line blocks, which is incorrect, since
this will render the blocks as normal paragraph with preserved line
breaks instead of code blocks.

Use literal code blocks instead for the output.

Fixes: f05f595045dfc7 ("Documentation/x86: Add documentation for TDX host support")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/x86/tdx.rst | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
index 4430912a2e4f05..f5bd22b89159ec 100644
--- a/Documentation/x86/tdx.rst
+++ b/Documentation/x86/tdx.rst
@@ -41,11 +41,11 @@ TDX boot-time detection
 -----------------------
 
 Kernel detects TDX and the TDX private KeyIDs during kernel boot.  User
-can see below dmesg if TDX is enabled by BIOS:
+can see below dmesg if TDX is enabled by BIOS::
 
-|  [..] tdx: SEAMRR enabled.
-|  [..] tdx: TDX private KeyID range: [16, 64).
-|  [..] tdx: TDX enabled by BIOS.
+   [..] tdx: SEAMRR enabled.
+   [..] tdx: TDX private KeyID range: [16, 64).
+   [..] tdx: TDX enabled by BIOS.
 
 TDX module detection and initialization
 ---------------------------------------
@@ -79,20 +79,20 @@ caller.
 User can consult dmesg to see the presence of the TDX module, and whether
 it has been initialized.
 
-If the TDX module is not loaded, dmesg shows below:
+If the TDX module is not loaded, dmesg shows below::
 
-|  [..] tdx: TDX module is not loaded.
+   [..] tdx: TDX module is not loaded.
 
 If the TDX module is initialized successfully, dmesg shows something
-like below:
+like below::
 
-|  [..] tdx: TDX module: vendor_id 0x8086, major_version 1, minor_version 0, build_date 20211209, build_num 160
-|  [..] tdx: 65667 pages allocated for PAMT.
-|  [..] tdx: TDX module initialized.
+   [..] tdx: TDX module: vendor_id 0x8086, major_version 1, minor_version 0, build_date 20211209, build_num 160
+   [..] tdx: 65667 pages allocated for PAMT.
+   [..] tdx: TDX module initialized.
 
-If the TDX module failed to initialize, dmesg shows below:
+If the TDX module failed to initialize, dmesg shows below::
 
-|  [..] tdx: Failed to initialize TDX module.  Shut it down.
+   [..] tdx: Failed to initialize TDX module.  Shut it down.
 
 TDX Interaction to Other Kernel Components
 ------------------------------------------
@@ -143,10 +143,10 @@ There are basically two memory hot-add cases that need to be prevented:
 ACPI memory hot-add and driver managed memory hot-add.  The kernel
 rejectes the driver managed memory hot-add too when TDX is enabled by
 BIOS.  For instance, dmesg shows below error when using kmem driver to
-add a legacy PMEM as system RAM:
+add a legacy PMEM as system RAM::
 
-|  [..] tdx: Unable to add memory [0x580000000, 0x600000000) on TDX enabled platform.
-|  [..] kmem dax0.0: mapping0: 0x580000000-0x5ffffffff memory add failed
+   [..] tdx: Unable to add memory [0x580000000, 0x600000000) on TDX enabled platform.
+   [..] kmem dax0.0: mapping0: 0x580000000-0x5ffffffff memory add failed
 
 However, adding new memory to ZONE_DEVICE should not be prevented as
 those pages are not managed by the page allocator.  Therefore,
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 11/12] Documentation: x86: Use literal code block for TDX dmesg output

[Kai Huang]

On Sat, 2022-07-09 at 11:20 +0700, Bagas Sanjaya wrote:
> The dmesg output blocks are using line blocks, which is incorrect, since
> this will render the blocks as normal paragraph with preserved line
> breaks instead of code blocks.
> 
> Use literal code blocks instead for the output.

Thank you very much!

Obviously I am not familiar with .rst.   I'll fix.

> 
> Fixes: f05f595045dfc7 ("Documentation/x86: Add documentation for TDX host support")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/x86/tdx.rst | 30 +++++++++++++++---------------
>  1 file changed, 15 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/x86/tdx.rst b/Documentation/x86/tdx.rst
> index 4430912a2e4f05..f5bd22b89159ec 100644
> --- a/Documentation/x86/tdx.rst
> +++ b/Documentation/x86/tdx.rst
> @@ -41,11 +41,11 @@ TDX boot-time detection
>  -----------------------
>  
>  Kernel detects TDX and the TDX private KeyIDs during kernel boot.  User
> -can see below dmesg if TDX is enabled by BIOS:
> +can see below dmesg if TDX is enabled by BIOS::
>  
> -|  [..] tdx: SEAMRR enabled.
> -|  [..] tdx: TDX private KeyID range: [16, 64).
> -|  [..] tdx: TDX enabled by BIOS.
> +   [..] tdx: SEAMRR enabled.
> +   [..] tdx: TDX private KeyID range: [16, 64).
> +   [..] tdx: TDX enabled by BIOS.
>  
>  TDX module detection and initialization
>  ---------------------------------------
> @@ -79,20 +79,20 @@ caller.
>  User can consult dmesg to see the presence of the TDX module, and whether
>  it has been initialized.
>  
> -If the TDX module is not loaded, dmesg shows below:
> +If the TDX module is not loaded, dmesg shows below::
>  
> -|  [..] tdx: TDX module is not loaded.
> +   [..] tdx: TDX module is not loaded.
>  
>  If the TDX module is initialized successfully, dmesg shows something
> -like below:
> +like below::
>  
> -|  [..] tdx: TDX module: vendor_id 0x8086, major_version 1, minor_version 0, build_date 20211209, build_num 160
> -|  [..] tdx: 65667 pages allocated for PAMT.
> -|  [..] tdx: TDX module initialized.
> +   [..] tdx: TDX module: vendor_id 0x8086, major_version 1, minor_version 0, build_date 20211209, build_num 160
> +   [..] tdx: 65667 pages allocated for PAMT.
> +   [..] tdx: TDX module initialized.
>  
> -If the TDX module failed to initialize, dmesg shows below:
> +If the TDX module failed to initialize, dmesg shows below::
>  
> -|  [..] tdx: Failed to initialize TDX module.  Shut it down.
> +   [..] tdx: Failed to initialize TDX module.  Shut it down.
>  
>  TDX Interaction to Other Kernel Components
>  ------------------------------------------
> @@ -143,10 +143,10 @@ There are basically two memory hot-add cases that need to be prevented:
>  ACPI memory hot-add and driver managed memory hot-add.  The kernel
>  rejectes the driver managed memory hot-add too when TDX is enabled by
>  BIOS.  For instance, dmesg shows below error when using kmem driver to
> -add a legacy PMEM as system RAM:
> +add a legacy PMEM as system RAM::
>  
> -|  [..] tdx: Unable to add memory [0x580000000, 0x600000000) on TDX enabled platform.
> -|  [..] kmem dax0.0: mapping0: 0x580000000-0x5ffffffff memory add failed
> +   [..] tdx: Unable to add memory [0x580000000, 0x600000000) on TDX enabled platform.
> +   [..] kmem dax0.0: mapping0: 0x580000000-0x5ffffffff memory add failed
>  
>  However, adding new memory to ZONE_DEVICE should not be prevented as
>  those pages are not managed by the page allocator.  Therefore,

[PATCH 12/12] Documentation: kvm: Add TDX documentation to KVM table of contents

[Bagas Sanjaya]

TDX documentation files under Documentation/virt/kvm/ are missing from
the table of contents index. Add the missing entries.

Fixes: 471b5bf12a3728 ("[MARKER] The start of TDX KVM patch series: TDX architectural definitions")
Fixes: 9e54fa1ac03df3 ("Documentation/virtual/kvm: Document on Trust Domain Extensions(TDX)")
Fixes: 7af4efe3263854 ("KVM: x86: design documentation on TDX support of x86 KVM TDP MMU")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/virt/kvm/index.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst
index e0a2c74e1043a0..f368a4625aa902 100644
--- a/Documentation/virt/kvm/index.rst
+++ b/Documentation/virt/kvm/index.rst
@@ -18,3 +18,7 @@ KVM
    locking
    vcpu-requests
    review-checklist
+
+   intel-tdx
+   intel-tdx-layer-status
+   tdx-tdp-mmu
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 00/12] Documentation: tdx: documentation fixes

[Isaku Yamahata]

On Sat, Jul 09, 2022 at 11:20:26AM +0700,
Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> Here is the documentation fixes for KVM TDX feature tree ([1]). There
> are 58 new warnings reported when making htmldocs, which are fixed.
> 
> [1]: https://github.com/intel/tdx/tree/kvm-upstream

Thank you for those fixes. I'll update the branch and include them for the next
respin.
-- 
Isaku Yamahata <isaku.yamahata@gmail.com>