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

Bagas Sanjaya
2022-07-09T04:21:34Z

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.