diff mbox series

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

Message ID 20220709042037.21903-9-bagasdotme@gmail.com (mailing list archive)
State New, archived
Headers show
Series Documentation: tdx: documentation fixes | expand

Commit Message

Bagas Sanjaya July 9, 2022, 4:20 a.m. UTC 
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(-)

Comments

Bagas Sanjaya July 9, 2022, 4:26 a.m. UTC | #1 
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.
Isaku Yamahata July 12, 2022, 7:34 p.m. UTC | #2 
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.
diff mbox series

Patch

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