[PATCH v3 0/6] Update document description for kvm_mmu_page and kvm_mmu_page_role

[PATCH v3 0/6] Update document description for kvm_mmu_page and kvm_mmu_page_role

[Mingwei Zhang]

This is the 3rd version and I made some changes according to feedback:

v2 -> v3:
 - update the description of shadowed_translation [sean,randy].
 - update the description of ptep for tdp mmu [sean].
 - update tdp_mmu_root_count into root_count and update the description
   [sean].
 - update mmu_valid_gen with more details suggested by [sean]
 - add extra description for tdp_mmu_page [sean]

Mingwei Zhang (6):
  KVM: Documentation: Add the missing description for guest_mode in
    kvm_mmu_page_role
  KVM: Documentation: Update the field name gfns and its description in
    kvm_mmu_page
  KVM: Documentation: Add the missing description for ptep in
    kvm_mmu_page
  KVM: Documentation: Add the missing description for tdp_mmu_root_count
    into kvm_mmu_page
  KVM: Documentation: Add the missing description for mmu_valid_gen into
    kvm_mmu_page
  KVM: Documentation: Add the missing description for tdp_mmu_page into
    kvm_mmu_page

 Documentation/virt/kvm/x86/mmu.rst | 44 ++++++++++++++++++++++++------
 1 file changed, 35 insertions(+), 9 deletions(-)


base-commit: 0b210faf337314e4bc88e796218bc70c72a51209
-- 
2.41.0.585.gd2178a4bd4-goog

[PATCH v3 1/6] KVM: Documentation: Add the missing description for guest_mode in kvm_mmu_page_role

[Mingwei Zhang]

Add the missing description for guest_mode in kvm_mmu_page_role
description.  guest_mode tells KVM whether a shadow page is used for the L1
or an L2. Update the missing field in documentation.

Signed-off-by: Mingwei Zhang <mizhang@google.com>
Reviewed-by: Kai Huang <kai.huang@intel.com>
---
 Documentation/virt/kvm/x86/mmu.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
index 8364afa228ec..561efa8ec7d7 100644
--- a/Documentation/virt/kvm/x86/mmu.rst
+++ b/Documentation/virt/kvm/x86/mmu.rst
@@ -202,6 +202,8 @@ Shadow pages contain the following information:
     Is 1 if the MMU instance cannot use A/D bits.  EPT did not have A/D
     bits before Haswell; shadow EPT page tables also cannot use A/D bits
     if the L1 hypervisor does not enable them.
+  role.guest_mode:
+    Indicates the shadow page is created for a nested guest.
   role.passthrough:
     The page is not backed by a guest page table, but its first entry
     points to one.  This is set if NPT uses 5-level page tables (host
-- 
2.41.0.585.gd2178a4bd4-goog

[PATCH v3 2/6] KVM: Documentation: Update the field name gfns and its description in kvm_mmu_page

[Mingwei Zhang]

Update the field 'gfns' in kvm_mmu_page to 'shadowed_translation' to be
consistent with the code. Also update the corresponding 'gfns' in the
comments. The more detailed description of 'shadowed_translation' is
already inlined in the data structure definition, so no need to duplicate
the text but simply just update the names.

Signed-off-by: Mingwei Zhang <mizhang@google.com>
Reviewed-by: Kai Huang <kai.huang@intel.com>
---
 Documentation/virt/kvm/x86/mmu.rst | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
index 561efa8ec7d7..35e642303962 100644
--- a/Documentation/virt/kvm/x86/mmu.rst
+++ b/Documentation/virt/kvm/x86/mmu.rst
@@ -221,11 +221,14 @@ Shadow pages contain the following information:
     at __pa(sp2->spt).  sp2 will point back at sp1 through parent_pte.
     The spt array forms a DAG structure with the shadow page as a node, and
     guest pages as leaves.
-  gfns:
-    An array of 512 guest frame numbers, one for each present pte.  Used to
-    perform a reverse map from a pte to a gfn. When role.direct is set, any
-    element of this array can be calculated from the gfn field when used, in
-    this case, the array of gfns is not allocated. See role.direct and gfn.
+  shadowed_translation:
+    An array of 512 shadow translation entries, one for each present pte. Used
+    to perform a reverse map from a pte to a gfn as well as its access
+    permission. When role.direct is set, the shadow_translation array is not
+    allocated. This is because the gfn contained in any element of this array
+    can be calculated from the gfn field when used.  In addition, when
+    role.direct is set, KVM does not track access permission for each of the
+    gfn. See role.direct and gfn.
   root_count:
     A counter keeping track of how many hardware registers (guest cr3 or
     pdptrs) are now pointing at the page.  While this counter is nonzero, the
-- 
2.41.0.585.gd2178a4bd4-goog

[PATCH v3 3/6] KVM: Documentation: Add the missing description for ptep in kvm_mmu_page

[Mingwei Zhang]

Add the missing description for ptep in kvm_mmu_page description. ptep is
used when TDP MMU is enabled and it shares the storage with parent_ptes.
Update the doc to help readers to get up-to-date info.

Signed-off-by: Mingwei Zhang <mizhang@google.com>
Reviewed-by: Kai Huang <kai.huang@intel.com>
---
 Documentation/virt/kvm/x86/mmu.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
index 35e642303962..17d90974204e 100644
--- a/Documentation/virt/kvm/x86/mmu.rst
+++ b/Documentation/virt/kvm/x86/mmu.rst
@@ -239,6 +239,9 @@ Shadow pages contain the following information:
     parent_ptes points at this single spte, otherwise, there exists multiple
     sptes pointing at this page and (parent_ptes & ~0x1) points at a data
     structure with a list of parent sptes.
+  ptep:
+    The kernel virtual address of the SPTE that points at this shadow page.
+    Used exclusively by the TDP MMU, this field is a union with parent_ptes.
   unsync:
     If true, then the translations in this page may not match the guest's
     translation.  This is equivalent to the state of the tlb when a pte is
-- 
2.41.0.585.gd2178a4bd4-goog

[PATCH v3 4/6] KVM: Documentation: Add the missing description for tdp_mmu_root_count into kvm_mmu_page

[Mingwei Zhang]

Add the description of tdp_mmu_root_count into kvm_mmu_page description and
combine it with the description of root_count. tdp_mmu_root_count is an
atomic counter used only in TDP MMU. Update the doc.

Signed-off-by: Mingwei Zhang <mizhang@google.com>
Reviewed-by: Kai Huang <kai.huang@intel.com>
---
 Documentation/virt/kvm/x86/mmu.rst | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
index 17d90974204e..40daf8beb9b1 100644
--- a/Documentation/virt/kvm/x86/mmu.rst
+++ b/Documentation/virt/kvm/x86/mmu.rst
@@ -229,10 +229,14 @@ Shadow pages contain the following information:
     can be calculated from the gfn field when used.  In addition, when
     role.direct is set, KVM does not track access permission for each of the
     gfn. See role.direct and gfn.
-  root_count:
-    A counter keeping track of how many hardware registers (guest cr3 or
-    pdptrs) are now pointing at the page.  While this counter is nonzero, the
-    page cannot be destroyed.  See role.invalid.
+  root_count / tdp_mmu_root_count:
+     root_count is a reference counter for root shadow pages in Shadow MMU.
+     vCPUs elevate the refcount when getting a shadow page that will be used as
+     a root page, i.e. page that will be loaded into hardware directly (CR3,
+     PDPTRs, nCR3 EPTP). Root pages cannot be destroyed while their refcount is
+     non-zero. See role.invalid. tdp_mmu_root_count is similar but exclusively
+     used in TDP MMU as an atomic refcount. When the value is non-zero, it
+     allows vCPUs acquire references while holding mmu_lock for read.
   parent_ptes:
     The reverse mapping for the pte/ptes pointing at this page's spt. If
     parent_ptes bit 0 is zero, only one spte points at this page and
-- 
2.41.0.585.gd2178a4bd4-goog

Re: [PATCH v3 4/6] KVM: Documentation: Add the missing description for tdp_mmu_root_count into kvm_mmu_page

[Sean Christopherson]

On Tue, Aug 01, 2023, Mingwei Zhang wrote:
> Add the description of tdp_mmu_root_count into kvm_mmu_page description and
> combine it with the description of root_count. tdp_mmu_root_count is an
> atomic counter used only in TDP MMU. Update the doc.
> 
> Signed-off-by: Mingwei Zhang <mizhang@google.com>
> Reviewed-by: Kai Huang <kai.huang@intel.com>
> ---
>  Documentation/virt/kvm/x86/mmu.rst | 12 ++++++++----
>  1 file changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
> index 17d90974204e..40daf8beb9b1 100644
> --- a/Documentation/virt/kvm/x86/mmu.rst
> +++ b/Documentation/virt/kvm/x86/mmu.rst
> @@ -229,10 +229,14 @@ Shadow pages contain the following information:
>      can be calculated from the gfn field when used.  In addition, when
>      role.direct is set, KVM does not track access permission for each of the
>      gfn. See role.direct and gfn.
> -  root_count:
> -    A counter keeping track of how many hardware registers (guest cr3 or
> -    pdptrs) are now pointing at the page.  While this counter is nonzero, the
> -    page cannot be destroyed.  See role.invalid.
> +  root_count / tdp_mmu_root_count:
> +     root_count is a reference counter for root shadow pages in Shadow MMU.
> +     vCPUs elevate the refcount when getting a shadow page that will be used as
> +     a root page, i.e. page that will be loaded into hardware directly (CR3,
> +     PDPTRs, nCR3 EPTP). Root pages cannot be destroyed while their refcount is
> +     non-zero. See role.invalid. tdp_mmu_root_count is similar but exclusively
> +     used in TDP MMU as an atomic refcount. When the value is non-zero, it
> +     allows vCPUs acquire references while holding mmu_lock for read.

That last sentence is wrong.  *vCPUs* can't acquire references while holding
mmu_lock for read.  And actually, they don't ever put references while holding
for read either.  vCPUs *must* hold mmu_lock for write to obtain a new root,
Not putting references while holding mmu_lock for read is mostly an implementation
quirk.

Maybe replace it with this?

    tdp_mmu_root_count is similar but exclusively used in the TDP MMU as an
    atomic refcount (select TDP MMU flows walk all roots while holding mmu_lock
    for read, e.g. when clearing dirty bits).

Re: [PATCH v3 4/6] KVM: Documentation: Add the missing description for tdp_mmu_root_count into kvm_mmu_page

[Mingwei Zhang]

On Wed, Aug 16, 2023, Sean Christopherson wrote:
> On Tue, Aug 01, 2023, Mingwei Zhang wrote:
> > Add the description of tdp_mmu_root_count into kvm_mmu_page description and
> > combine it with the description of root_count. tdp_mmu_root_count is an
> > atomic counter used only in TDP MMU. Update the doc.
> > 
> > Signed-off-by: Mingwei Zhang <mizhang@google.com>
> > Reviewed-by: Kai Huang <kai.huang@intel.com>
> > ---
> >  Documentation/virt/kvm/x86/mmu.rst | 12 ++++++++----
> >  1 file changed, 8 insertions(+), 4 deletions(-)
> > 
> > diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
> > index 17d90974204e..40daf8beb9b1 100644
> > --- a/Documentation/virt/kvm/x86/mmu.rst
> > +++ b/Documentation/virt/kvm/x86/mmu.rst
> > @@ -229,10 +229,14 @@ Shadow pages contain the following information:
> >      can be calculated from the gfn field when used.  In addition, when
> >      role.direct is set, KVM does not track access permission for each of the
> >      gfn. See role.direct and gfn.
> > -  root_count:
> > -    A counter keeping track of how many hardware registers (guest cr3 or
> > -    pdptrs) are now pointing at the page.  While this counter is nonzero, the
> > -    page cannot be destroyed.  See role.invalid.
> > +  root_count / tdp_mmu_root_count:
> > +     root_count is a reference counter for root shadow pages in Shadow MMU.
> > +     vCPUs elevate the refcount when getting a shadow page that will be used as
> > +     a root page, i.e. page that will be loaded into hardware directly (CR3,
> > +     PDPTRs, nCR3 EPTP). Root pages cannot be destroyed while their refcount is
> > +     non-zero. See role.invalid. tdp_mmu_root_count is similar but exclusively
> > +     used in TDP MMU as an atomic refcount. When the value is non-zero, it
> > +     allows vCPUs acquire references while holding mmu_lock for read.
> 
> That last sentence is wrong.  *vCPUs* can't acquire references while holding
> mmu_lock for read.  And actually, they don't ever put references while holding
> for read either.  vCPUs *must* hold mmu_lock for write to obtain a new root,
> Not putting references while holding mmu_lock for read is mostly an implementation
> quirk.
> 
> Maybe replace it with this?
> 
>     tdp_mmu_root_count is similar but exclusively used in the TDP MMU as an
>     atomic refcount (select TDP MMU flows walk all roots while holding mmu_lock
>     for read, e.g. when clearing dirty bits).

hmm, I think all the content within the bracket is details and we should
not mention them at all. In fact, when I see the implementation, the
last refcount of tdp_mmu_root_count is treated differently. Those
details should be instead mentioned in code or comments instead of
documentation as they may evolve much faster.

So, I will remove the last sentence.

[PATCH v3 5/6] KVM: Documentation: Add the missing description for mmu_valid_gen into kvm_mmu_page

[Mingwei Zhang]

Add the description for mmu_valid_gen into kvm_mmu_page description.
mmu_valid_gen is used in shadow MMU for fast zapping. Update the doc to
reflect that.

Signed-off-by: Mingwei Zhang <mizhang@google.com>
Reviewed-by: Kai Huang <kai.huang@intel.com>
---
 Documentation/virt/kvm/x86/mmu.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
index 40daf8beb9b1..581e53fa00a2 100644
--- a/Documentation/virt/kvm/x86/mmu.rst
+++ b/Documentation/virt/kvm/x86/mmu.rst
@@ -208,6 +208,16 @@ Shadow pages contain the following information:
     The page is not backed by a guest page table, but its first entry
     points to one.  This is set if NPT uses 5-level page tables (host
     CR4.LA57=1) and is shadowing L1's 4-level NPT (L1 CR4.LA57=1).
+  mmu_valid_gen:
+    The MMU generation of this page, used to fast zap of all MMU pages within a
+    VM without blocking vCPUs. Specifically, KVM updates the per-VM valid MMU
+    generation which causes the mismatch of mmu_valid_gen for each mmu page.
+    This makes all existing MMU pages obsolete. Obsolete pages can't be used.
+    Therefore, vCPUs must load a new, valid root before re-entering the guest.
+    The MMU generation is only ever '0' or '1'.  Note, the TDP MMU doesn't use
+    this field as non-root TDP MMU pages are reachable only from their owning
+    root.  Thus it suffices for TDP MMU to use role.invalid in root pages to
+    invalidate all MMU pages.
   gfn:
     Either the guest page table containing the translations shadowed by this
     page, or the base page frame for linear translations.  See role.direct.
-- 
2.41.0.585.gd2178a4bd4-goog

Re: [PATCH v3 5/6] KVM: Documentation: Add the missing description for mmu_valid_gen into kvm_mmu_page

[Sean Christopherson]

On Tue, Aug 01, 2023, Mingwei Zhang wrote:
> Add the description for mmu_valid_gen into kvm_mmu_page description.
> mmu_valid_gen is used in shadow MMU for fast zapping. Update the doc to
> reflect that.
> 
> Signed-off-by: Mingwei Zhang <mizhang@google.com>
> Reviewed-by: Kai Huang <kai.huang@intel.com>
> ---
>  Documentation/virt/kvm/x86/mmu.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
> index 40daf8beb9b1..581e53fa00a2 100644
> --- a/Documentation/virt/kvm/x86/mmu.rst
> +++ b/Documentation/virt/kvm/x86/mmu.rst
> @@ -208,6 +208,16 @@ Shadow pages contain the following information:
>      The page is not backed by a guest page table, but its first entry
>      points to one.  This is set if NPT uses 5-level page tables (host
>      CR4.LA57=1) and is shadowing L1's 4-level NPT (L1 CR4.LA57=1).
> +  mmu_valid_gen:
> +    The MMU generation of this page, used to fast zap of all MMU pages within a
> +    VM without blocking vCPUs.

KVM still blocks vCPUs, just for far less time.  How about this?

     The MMU generation of this page, used to determine whether or not a shadow
     page is obsolete, i.e. belongs to a previous MMU generation.  KVM changes
     the MMU generation when all shadow pages need to be invalidated, e.g. if a
     memslot is deleted, and so effectively marks all shadow pages as obsolete
     without having to touch each page.  Marking shadow pages obsolete allows
     KVM to zap them in the background, i.e. so that vCPUs can run while the
     zap is ongoing (using a root from the new generation).  The MMU generation
     is only ever '0' or '1' (slots_lock must be held until all pages from the
     previous generation are zapped).

     Note, the TDP MMU...

> Specifically, KVM updates the per-VM valid MMU
> +    generation which causes the mismatch of mmu_valid_gen for each mmu page.
> +    This makes all existing MMU pages obsolete. Obsolete pages can't be used.
> +    Therefore, vCPUs must load a new, valid root before re-entering the guest.
> +    The MMU generation is only ever '0' or '1'.  

Re: [PATCH v3 5/6] KVM: Documentation: Add the missing description for mmu_valid_gen into kvm_mmu_page

[Mingwei Zhang]

On Wed, Aug 16, 2023, Sean Christopherson wrote:
> On Tue, Aug 01, 2023, Mingwei Zhang wrote:
> > Add the description for mmu_valid_gen into kvm_mmu_page description.
> > mmu_valid_gen is used in shadow MMU for fast zapping. Update the doc to
> > reflect that.
> > 
> > Signed-off-by: Mingwei Zhang <mizhang@google.com>
> > Reviewed-by: Kai Huang <kai.huang@intel.com>
> > ---
> >  Documentation/virt/kvm/x86/mmu.rst | 10 ++++++++++
> >  1 file changed, 10 insertions(+)
> > 
> > diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
> > index 40daf8beb9b1..581e53fa00a2 100644
> > --- a/Documentation/virt/kvm/x86/mmu.rst
> > +++ b/Documentation/virt/kvm/x86/mmu.rst
> > @@ -208,6 +208,16 @@ Shadow pages contain the following information:
> >      The page is not backed by a guest page table, but its first entry
> >      points to one.  This is set if NPT uses 5-level page tables (host
> >      CR4.LA57=1) and is shadowing L1's 4-level NPT (L1 CR4.LA57=1).
> > +  mmu_valid_gen:
> > +    The MMU generation of this page, used to fast zap of all MMU pages within a
> > +    VM without blocking vCPUs.
> 
> KVM still blocks vCPUs, just for far less time.  How about this?
> 
>      The MMU generation of this page, used to determine whether or not a shadow
>      page is obsolete, i.e. belongs to a previous MMU generation.  KVM changes
>      the MMU generation when all shadow pages need to be invalidated, e.g. if a
>      memslot is deleted, and so effectively marks all shadow pages as obsolete
>      without having to touch each page.  Marking shadow pages obsolete allows
>      KVM to zap them in the background, i.e. so that vCPUs can run while the
>      zap is ongoing (using a root from the new generation).  The MMU generation
>      is only ever '0' or '1' (slots_lock must be held until all pages from the
>      previous generation are zapped).
> 
>      Note, the TDP MMU...
> 

Got you. I think instead of elaborating this, I would simply put this
way: "... without blocking vCPUs for too long". The subsequent description
basically tells how it works and naturally explains how it does not
blocks vCPUs for too long.

> > Specifically, KVM updates the per-VM valid MMU
> > +    generation which causes the mismatch of mmu_valid_gen for each mmu page.
> > +    This makes all existing MMU pages obsolete. Obsolete pages can't be used.
> > +    Therefore, vCPUs must load a new, valid root before re-entering the guest.
> > +    The MMU generation is only ever '0' or '1'.  

[PATCH v3 6/6] KVM: Documentation: Add the missing description for tdp_mmu_page into kvm_mmu_page

[Mingwei Zhang]

Add the description for tdp_mmu_page into kvm_mmu_page description.
tdp_mmu_page is a field to differentiate shadow pages from TDP MMU and
non-TDP MMU.

Signed-off-by: Mingwei Zhang <mizhang@google.com>
Reviewed-by: Kai Huang <kai.huang@intel.com>
---
 Documentation/virt/kvm/x86/mmu.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
index 581e53fa00a2..3be646a6daf5 100644
--- a/Documentation/virt/kvm/x86/mmu.rst
+++ b/Documentation/virt/kvm/x86/mmu.rst
@@ -283,6 +283,10 @@ Shadow pages contain the following information:
     since the last time the page table was actually used; if emulation
     is triggered too frequently on this page, KVM will unmap the page
     to avoid emulation in the future.
+  tdp_mmu_page:
+    Is 1 if the shadow page is a TDP MMU page. This variable is used to
+    bifurcate the control flows for KVM when walking any data structure that may
+    contain pages from both TDP MMU and shadow MMU.
 
 Reverse map
 ===========
-- 
2.41.0.585.gd2178a4bd4-goog