From patchwork Tue Aug 30 19:41:25 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Oliver Upton X-Patchwork-Id: 12959801 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 27816ECAAA1 for ; Tue, 30 Aug 2022 19:45:31 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:Cc:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=C6v4qDGnrVW+sDfIatyy564KEW1VgAQmH8tOU4wXJaA=; b=yVcKwoVClRURqq CsfNUJRcHjR7+0iuMIIyg1b+T5Mo7fgxcHgMkTuJWHxygk7lkt9D/KSgh1ayBoEUQ2YIvV9Otaklq l/4CuUkVdaOQ/+5yAYre8aJ9gLEF2fqohqtROmRVpy9sj45l+jdYMDZgmZNEXQqHAZuq/NJkpV/Q0 sRbBhnyh8Asoh6QsYnwGLp/GIu9g8K9nQjc8F+kZQssAvlbd2xwroChwtZVdQNdjkwjH+97xqDcgO Gh8ul7HGL21ohirVdvnYs8rrfDTLXF5Xi4jLViif+yfzO0vQEkrOh/EcGUpD76op32cUpsD/2kYy4 3SJffuj7E95yfHmwHSaQ==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.94.2 #2 (Red Hat Linux)) id 1oT79s-001W4L-3p; Tue, 30 Aug 2022 19:44:24 +0000 Received: from out1.migadu.com ([2001:41d0:2:863f::]) by bombadil.infradead.org with esmtps (Exim 4.94.2 #2 (Red Hat Linux)) id 1oT77r-001VAv-9b for linux-arm-kernel@lists.infradead.org; Tue, 30 Aug 2022 19:42:21 +0000 X-Report-Abuse: Please report any abuse attempt to abuse@migadu.com and include these headers. DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linux.dev; s=key1; t=1661888538; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=fQeI6zpamXufaG6UtIBPMTAxGRkDzaVjmSqbL7fqmA4=; b=D9h9JwBXgp4fk3oXEgNrHS+gL2418x+oOQGDIhu15jN7Y5D9JRtyE3eEsyuBeRj9CrBaD2 A90lb39Q6XzojxcGyb2Go/11MI9HEgqpfAGScUJOzE/yMG2o6XrcZg782/2VeGVGKzCubS V8ZWLLP9SU9I0vP7yG914m7jhzl30+0= From: Oliver Upton To: Marc Zyngier , James Morse , Alexandru Elisei , Suzuki K Poulose , Catalin Marinas , Will Deacon , Quentin Perret , Ricardo Koller , Reiji Watanabe , David Matlack , Ben Gardon , Paolo Bonzini , Gavin Shan , Peter Xu , Sean Christopherson , Oliver Upton Cc: linux-arm-kernel@lists.infradead.org, kvmarm@lists.cs.columbia.edu, kvm@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 07/14] KVM: arm64: Document behavior of pgtable visitor callback Date: Tue, 30 Aug 2022 19:41:25 +0000 Message-Id: <20220830194132.962932-8-oliver.upton@linux.dev> In-Reply-To: <20220830194132.962932-1-oliver.upton@linux.dev> References: <20220830194132.962932-1-oliver.upton@linux.dev> MIME-Version: 1.0 X-Migadu-Flow: FLOW_OUT X-Migadu-Auth-User: linux.dev X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20220830_124219_541782_D1E38F1B X-CRM114-Status: GOOD ( 10.45 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org 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 --- 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,