Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Bagas Sanjaya <bagasdotme@gmail.com>
To:     linux-doc@vger.kernel.org
Cc:     Paolo Bonzini <pbonzini@redhat.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Thomas Gleixner <tglx@linutronix.de>,
        Ingo Molnar <mingo@redhat.com>, Borislav Petkov <bp@alien8.de>,
        Dave Hansen <dave.hansen@linux.intel.com>,
        "H. Peter Anvin" <hpa@zytor.com>,
        Isaku Yamahata <isaku.yamahata@intel.com>,
        Kai Huang <kai.huang@intel.com>, x86@kernel.org,
        kvm@vger.kernel.org, linux-kernel@vger.kernel.org,
        Bagas Sanjaya <bagasdotme@gmail.com>,
        kernel test robot <lkp@intel.com>
Subject: [PATCH 01/12] Documentation: kvm: Pad bullet lists with blank line
Date:   Sat,  9 Jul 2022 11:20:27 +0700
Message-Id: <20220709042037.21903-2-bagasdotme@gmail.com>
In-Reply-To: <20220709042037.21903-1-bagasdotme@gmail.com>
References: <20220709042037.21903-1-bagasdotme@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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