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

[Mingwei Zhang <mizhang@google.com>]

On Tue, Jun 27, 2023, Sean Christopherson wrote:
> On Mon, Jun 26, 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 | 4 ++++
> >  1 file changed, 4 insertions(+)
> > 
> > diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst
> > index 97d695207e11..cc4bd190c93d 100644
> > --- a/Documentation/virt/kvm/x86/mmu.rst
> > +++ b/Documentation/virt/kvm/x86/mmu.rst
> > @@ -208,6 +208,10 @@ 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:
> > +    Used by comparing against kvm->arch.mmu_valid_gen to check whether the
> 
> This needs to explain what the generation is, and where it comes from.
> 
>   The MMU generation of this page, used to effect a "fast" zap of all MMU pages
>   across all roots.  To zap all pages in all roots without blocking vCPUs, e.g.
>   when deleting a memslot, KVM updates the per-VM valid MMU generation to mark
>   all existing pages and roots invalid/obsolete.  Obsolete pages can't be used,
>   e.g. vCPUs must load a new, valid root before re-entering the guest.
> 
>   The MMU generation is only ever '0' or '1', as slots_lock must be held until
>   all obsolete pages are zapped and freed, i.e. there is exactly one valid
>   generation and (at most) one invalid generation.
> 
>   Note, the TDP MMU doesn't use mmu_gen as non-root TDP MMU pages are reachable
>   only from their owning root, whereas all pages for shadow MMUs are reachable
>   via the hash map.  The TDP MMU uses role.invalid to track obsolete roots.

Sean, thanks for the detailed explanation. I will pick the most of the
content and get into the next version.
> 
> And then big bonus points if you add
> 
>   Page Role
>   =========
> 
> to explain the purpose of the role, and how/when it's used in the shadow MMU versus
> the TDP MMU.  The shadow MMU's use of a hash map is a fundemental aspect that really
> should be documented here.
> 
> > +    shadow page is obsolete thus a convenient variable for fast zapping.
> > +    Note that TDP MMU does not use mmu_valid_gen.
> >    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.162.gfafddb0af9-goog
> >