KVM: x86/mmu: Clean up function comments for dirty logging APIs
Sean Christopherson
maintainerPATCH v2 1/1 KVM: x86/mmu: Clean up function comments for dirty logging APIs
Rework the function comment for kvm_arch_mmu_enable_log_dirty_pt_masked() into the body of the function, as it has gotten a bit stale, is harder to read without the code context, and is the last source of warnings for W=1 builds in KVM x86 due to using a kernel-doc comment without documenting all parameters.
Opportunistically subsume the functions comments for kvm_mmu_write_protect_pt_masked() and kvm_mmu_clear_dirty_pt_masked(), as there is no value in regurgitating similar information at a higher level, and capturing the differences between write-protection and PML-based dirty logging is best done in a common location.
No functional change intended.
---
v2: Put the comments in the function body. [David]
v1: https://lore.kernel.org/all/[email protected]
arch/x86/kvm/mmu/mmu.c | 48 +++++++++++++----------------------------- 1 file changed, 15 insertions(+), 33 deletions(-)
arch/x86/kvm/mmu/mmu.c +15 -33
@@ -1307,15 +1307,6 @@ static bool __rmap_clear_dirty(struct kvm *kvm, struct kvm_rmap_head *rmap_head,return flush; } -/** -* kvm_mmu_write_protect_pt_masked - write protect selected PT level pages -* @kvm: kvm instance -* @slot: slot to protect -* @gfn_offset: start of the BITS_PER_LONG pages we care about -* @mask: indicates which pages we should protect -* -* Used when we do not need to care about huge page mappings. -*/ static void kvm_mmu_write_protect_pt_masked (struct kvm *kvm,struct kvm_memory_slot *slot,gfn_t gfn_offset,unsigned long mask)
@@ -1339,16 +1330,6 @@ static void kvm_mmu_write_protect_pt_masked(struct kvm *kvm, } } -/** -* kvm_mmu_clear_dirty_pt_masked - clear MMU D-bit for PT level pages, or write -* protect the page if the D-bit isn't supported. -* @kvm: kvm instance -* @slot: slot to clear D-bit -* @gfn_offset: start of the BITS_PER_LONG pages we care about -* @mask: indicates which pages we should clear D-bit -* -* Used for PML to re-log the dirty GPAs after userspace querying dirty_bitmap. -*/ static void kvm_mmu_clear_dirty_pt_masked (struct kvm *kvm,struct kvm_memory_slot *slot,gfn_t gfn_offset,unsigned long mask)
@@ -1372,24 +1353,16 @@ static void kvm_mmu_clear_dirty_pt_masked(struct kvm *kvm, } } -/** -* kvm_arch_mmu_enable_log_dirty_pt_masked - enable dirty logging for selected -* PT level pages. -* -* It calls kvm_mmu_write_protect_pt_masked to write protect selected pages to -* enable dirty logging for them. -* -* We need to care about huge page mappings: e.g. during dirty logging we may -* have such mappings. -*/ void kvm_arch_mmu_enable_log_dirty_pt_masked (struct kvm *kvm,struct kvm_memory_slot *slot,gfn_t gfn_offset,unsigned long mask) {/* -* Huge pages are NOT write protected when we start dirty logging in -* initially-all-set mode; must write protect them here so that they -* are split to 4K on the first write. +* If the slot was assumed to be "initially all dirty", write-protect +* huge pages to ensure they are split to 4KiB on the first write (KVM +* dirty logs at 4KiB granularity). If eager page splitting is enabled, +* immediately try to split huge pages, e.g. so that vCPUs don't get +* saddled with the cost of splitting. * * The gfn_offset is guaranteed to be aligned to 64, but the base_gfn * of memslot has no such restriction, so the range can cross two large
@@ -1411,7 +1384,16 @@ void kvm_arch_mmu_enable_log_dirty_pt_masked(struct kvm *kvm, PG_LEVEL_2M); } -/* Now handle 4K PTEs. */ +/* +* (Re)Enable dirty logging for all 4KiB SPTEs that map the GFNs in +* mask. If PML is enabled and the and the GFN doesn't need to be +* write-protected for other reasons, e.g. shadow paging, clear the +* Dirty bit. Otherwise clear the Writable bit. +* +* Note that kvm_mmu_clear_dirty_pt_masked() is called whenever PML is +* enabled but it chooses between clearing the Dirty bit and Writeable +* bit based on the context. +*/ if (kvm_x86_ops.cpu_dirty_log_size)kvm_mmu_clear_dirty_pt_masked (kvm, slot, gfn_offset, mask);else
base-commit: 332d2c1d713e232e163386c35a3ba0c1b90df83f
Signature · 1 line
2.46.0.rc2.264.g509ed76dc8-goog
Quoted 12 lines · Sean Christopherson
Rework the function comment for
kvm_arch_mmu_enable_log_dirty_pt_masked()into the body of the function, as it has gotten a bit stale, is harder to read without the code context, and is the last source of warnings for W=1 builds in KVM x86 due to using a kernel-doc comment without documenting all parameters.Opportunistically subsume the functions comments for
kvm_mmu_write_protect_pt_masked()andkvm_mmu_clear_dirty_pt_masked(), as there is no value in regurgitating similar information at a higher level, and capturing the differences between write-protection and PML-based dirty logging is best done in a common location.
Quoted 5 lines
No functional change intended.
Cc David Matlack <[email protected]>Signed-off-by Sean Christopherson <[email protected]>
[...]
arch/x86/kvm/mmu/mmu.c void kvm_arch_mmu_enable_log_dirty_pt_masked(struct kvm *kvm, · line 1389
Quoted 5 lines
arch/x86/kvm/mmu/mmu.c +3
-1-/* Now handle 4K PTEs. */ +/* +* (Re)Enable dirty logging for all 4KiB SPTEs that map the GFNs in +* mask. If PML is enabled and the and the GFN doesn't need to be
^ double "and the"
Quoted 100 lines
Rework the function comment for
kvm_arch_mmu_enable_log_dirty_pt_masked()into the body of the function, as it has gotten a bit stale, is harder to read without the code context, and is the last source of warnings for W=1 builds in KVM x86 due to using a kernel-doc comment without documenting all parameters.Opportunistically subsume the functions comments for
kvm_mmu_write_protect_pt_masked()andkvm_mmu_clear_dirty_pt_masked(), as there is no value in regurgitating similar information at a higher level, and capturing the differences between write-protection and PML-based dirty logging is best done in a common location.No functional change intended.
Cc David Matlack <[email protected]>Signed-off-by Sean Christopherson <[email protected]>---
v2: Put the comments in the function body. [David]
v1: https://lore.kernel.org/all/[email protected]
arch/x86/kvm/mmu/mmu.c | 48 +++++++++++++----------------------------- 1 file changed, 15 insertions(+), 33 deletions(-)arch/x86/kvm/mmu/mmu.c +8
-33@@ -1307,15 +1307,6 @@ static bool __rmap_clear_dirty(struct kvm *kvm, struct kvm_rmap_head *rmap_head,return flush; } -/** -* kvm_mmu_write_protect_pt_masked - write protect selected PT level pages -* @kvm: kvm instance -* @slot: slot to protect -* @gfn_offset: start of the BITS_PER_LONG pages we care about -* @mask: indicates which pages we should protect -* -* Used when we do not need to care about huge page mappings. -*/ static void kvm_mmu_write_protect_pt_masked (struct kvm *kvm,struct kvm_memory_slot *slot,gfn_t gfn_offset,unsigned long mask)@@ -1339,16 +1330,6 @@ static void kvm_mmu_write_protect_pt_masked(struct kvm *kvm, } } -/** -* kvm_mmu_clear_dirty_pt_masked - clear MMU D-bit for PT level pages, or write -* protect the page if the D-bit isn't supported. -* @kvm: kvm instance -* @slot: slot to clear D-bit -* @gfn_offset: start of the BITS_PER_LONG pages we care about -* @mask: indicates which pages we should clear D-bit -* -* Used for PML to re-log the dirty GPAs after userspace querying dirty_bitmap. -*/ static void kvm_mmu_clear_dirty_pt_masked (struct kvm *kvm,struct kvm_memory_slot *slot,gfn_t gfn_offset,unsigned long mask)@@ -1372,24 +1353,16 @@ static void kvm_mmu_clear_dirty_pt_masked(struct kvm *kvm, } } -/** -* kvm_arch_mmu_enable_log_dirty_pt_masked - enable dirty logging for selected -* PT level pages. -* -* It calls kvm_mmu_write_protect_pt_masked to write protect selected pages to -* enable dirty logging for them. -* -* We need to care about huge page mappings: e.g. during dirty logging we may -* have such mappings. -*/ void kvm_arch_mmu_enable_log_dirty_pt_masked (struct kvm *kvm,struct kvm_memory_slot *slot,gfn_t gfn_offset,unsigned long mask) {/* -* Huge pages are NOT write protected when we start dirty logging in -* initially-all-set mode; must write protect them here so that they -* are split to 4K on the first write. +* If the slot was assumed to be "initially all dirty", write-protect +* huge pages to ensure they are split to 4KiB on the first write (KVM +* dirty logs at 4KiB granularity). If eager page splitting is enabled, +* immediately try to split huge pages, e.g. so that vCPUs don't get +* saddled with the cost of splitting. * * The gfn_offset is guaranteed to be aligned to 64, but the base_gfn * of memslot has no such restriction, so the range can cross two large @@ -1411,7 +1384,16 @@ void kvm_arch_mmu_enable_log_dirty_pt_masked(struct kvm *kvm, PG_LEVEL_2M); } -/* Now handle 4K PTEs. */ +/* +* (Re)Enable dirty logging for all 4KiB SPTEs that map the GFNs in +* mask. If PML is enabled and the and the GFN doesn't need to be
arch/x86/kvm/mmu/mmu.c void kvm_arch_mmu_enable_log_dirty_pt_masked(struct kvm *kvm, · line 1399
Quoted 10 lines
arch/x86/kvm/mmu/mmu.c +7
-0+* write-protected for other reasons, e.g. shadow paging, clear the +* Dirty bit. Otherwise clear the Writable bit. +* +* Note that kvm_mmu_clear_dirty_pt_masked() is called whenever PML is +* enabled but it chooses between clearing the Dirty bit and Writeable +* bit based on the context. +*/ if (kvm_x86_ops.cpu_dirty_log_size)kvm_mmu_clear_dirty_pt_masked (kvm, slot, gfn_offset, mask);else
Thanks for fixing this comment. Indeed it required to look a bit in code if the condition means, PML is enabled, I faced this as well.
Quoted 2 lines
base-commit:
332d2c1d713e232e163386c35a3ba0c1b90df83f
Quoted 6 lines · Sean Christopherson
Rework the function comment for
kvm_arch_mmu_enable_log_dirty_pt_masked()into the body of the function, as it has gotten a bit stale, is harder to read without the code context, and is the last source of warnings for W=1 builds in KVM x86 due to using a kernel-doc comment without documenting all parameters.
Quoted 7 lines
Opportunistically subsume the functions comments for
kvm_mmu_write_protect_pt_masked()andkvm_mmu_clear_dirty_pt_masked(), as there is no value in regurgitating similar information at a higher level, and capturing the differences between write-protection and PML-based dirty logging is best done in a common location.[...]
Applied to kvm-x86 mmu, thanks!
[1/1] KVM: x86/mmu: Clean up function comments for dirty logging APIs
https://github.com/kvm-x86/linux/commit/acf2923271ef