linux-kernel - [PATCH 07/14] KVM: arm64: Document behavior of pgtable visitor callback

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-Id: <20220830194132.962932-8-oliver.upton@linux.dev>
Date:   Tue, 30 Aug 2022 19:41:25 +0000
From:   Oliver Upton <oliver.upton@...ux.dev>
To:     Marc Zyngier <maz@...nel.org>, James Morse <james.morse@....com>,
        Alexandru Elisei <alexandru.elisei@....com>,
        Suzuki K Poulose <suzuki.poulose@....com>,
        Catalin Marinas <catalin.marinas@....com>,
        Will Deacon <will@...nel.org>,
        Quentin Perret <qperret@...gle.com>,
        Ricardo Koller <ricarkol@...gle.com>,
        Reiji Watanabe <reijiw@...gle.com>,
        David Matlack <dmatlack@...gle.com>,
        Ben Gardon <bgardon@...gle.com>,
        Paolo Bonzini <pbonzini@...hat.com>,
        Gavin Shan <gshan@...hat.com>, Peter Xu <peterx@...hat.com>,
        Sean Christopherson <seanjc@...gle.com>,
        Oliver Upton <oliver.upton@...ux.dev>
Cc:     linux-arm-kernel@...ts.infradead.org, kvmarm@...ts.cs.columbia.edu,
        kvm@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: [PATCH 07/14] KVM: arm64: Document behavior of pgtable visitor callback

The argument list to kvm_pgtable_visitor_fn_t has gotten rather long.
Additionally, @old serves as both an input and output parameter, which
isn't easily discerned from the declaration alone.

Document the meaning of the visitor callback arguments and the
conditions under which @old was written to.

Signed-off-by: Oliver Upton <oliver.upton@...ux.dev>
---
 arch/arm64/include/asm/kvm_pgtable.h | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/arch/arm64/include/asm/kvm_pgtable.h b/arch/arm64/include/asm/kvm_pgtable.h
index 47920ae3f7e7..78fbb7be1af6 100644
--- a/arch/arm64/include/asm/kvm_pgtable.h
+++ b/arch/arm64/include/asm/kvm_pgtable.h
@@ -194,6 +194,22 @@ enum kvm_pgtable_walk_flags {
 	KVM_PGTABLE_WALK_TABLE_POST		= BIT(2),
 };
 
+/**
+ * kvm_pgtable_visitor_fn_t - Page table traversal callback for visiting a PTE.
+ * @addr:	Input address (IA) mapped by the PTE.
+ * @end:	IA corresponding to the end of the page table traversal range.
+ * @ptep:	Pointer to the PTE.
+ * @old:	Value of the PTE observed by the visitor. Also used as an output
+ *		parameter for returning the new PTE value.
+ * @flag:	Flag identifying the entry type visited.
+ * @arg:	Argument passed to the callback function.
+ *
+ * Callback function signature invoked during page table traversal. Optionally
+ * returns the new value of the PTE via @old if the new value requires further
+ * traversal (i.e. installing a new table).
+ *
+ * Return: 0 on success, negative error code on failure.
+ */
 typedef int (*kvm_pgtable_visitor_fn_t)(u64 addr, u64 end, u32 level,
 					kvm_pte_t *ptep, kvm_pte_t *old,
 					enum kvm_pgtable_walk_flags flag,
-- 
2.37.2.672.g94769d06f0-goog