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

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'.

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'.