[v2,2/6] KVM: Documentation: Update the field name gfns and its description in kvm_mmu_page
Message ID | 20230626182016.4127366-3-mizhang@google.com |
---|---|
State | New |
Headers |
Return-Path: <linux-kernel-owner@vger.kernel.org> Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:994d:0:b0:3d9:f83d:47d9 with SMTP id k13csp7702420vqr; Mon, 26 Jun 2023 12:20:08 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ5sKA0u7pG8EIQ616CAhrcgcfWdsuHzJcBvm8yWy3vCQJf7mr2V+jeGYaWChFLHmxuk0xDQ X-Received: by 2002:aa7:d790:0:b0:51d:91c2:679f with SMTP id s16-20020aa7d790000000b0051d91c2679fmr5450642edq.16.1687807207980; Mon, 26 Jun 2023 12:20:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1687807207; cv=none; d=google.com; s=arc-20160816; b=Uf3yR8RU5hiFESmJnUGOjktSJkDfJUg4QTBqIt3TUPe7phIOYdPY5+2YaWYaC/KMD6 T60qjcj4ahrygbwQsFXpVfWvdOLOV/34pHD8NPb4//O5hprmJM6KbcTMPrkq3NdujNu5 Nj2dS/Ra4xwMv+5d+S2rE6uKKzCipDE6roCHhWHMESlQ54/zqkJcJKxYwfGAH1XinWIT fNZrRWkjzKsYNew+pM6LpX4jKXhKn5Fi+iloE7rO+QioOgrzBgjZDFFStLyFX9xe4+JW dMdrXOk6zOm9tZ2xcSTZIoMhz1T9eGWWwn+/XISyJWunq3+Ml6NhbBge8DATI24+rpWu BWWg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:from:subject:message-id:references :mime-version:in-reply-to:date:reply-to:dkim-signature; bh=qTMxx/LJnmIWvUmH+gdz70kQEF0zmvOjZ2b4ibjV0JA=; fh=4e3puReJ7DjwMG6rJqHJp2nX/a/7QqKKhs1FjQcufg4=; b=d4Gt/HgXZJdOGKYjQ8c7hzJOYcMh32LmeJwBVMK4p84YHD+3n3fo/0h/iAQQ2bFdx2 3LBUwzWajzRo3wSs7v4HQsf+rigsBd+CfZ3B/tuWlifH1ePfx05cdy0TSNb06YYQJVnr K3MdiyaA5Zgb0IET66YcEJKxhjM+ivGM51rE6AtyS7AToTUpXo5eUAmw7bZOcZSC9MGc /6oTwVetx7AbOvsEiRIyqgkLtVojnqCo8uOJpfW2bH0CepopcBQA6Y0qZyxS+UMyJikP b9uH46surQGGyMDcZTw0FuC1pfq9vmmJEcz0jjeLl2CiONTNBUC77j4rrRXYbM5/+tAQ ZFUw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20221208 header.b=S4eXFyS5; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id b19-20020a05640202d300b0051bebe13248si2934186edx.63.2023.06.26.12.19.43; Mon, 26 Jun 2023 12:20:07 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@google.com header.s=20221208 header.b=S4eXFyS5; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231830AbjFZSU7 (ORCPT <rfc822;filip.gregor98@gmail.com> + 99 others); Mon, 26 Jun 2023 14:20:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:35062 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231681AbjFZSUe (ORCPT <rfc822;linux-kernel@vger.kernel.org>); Mon, 26 Jun 2023 14:20:34 -0400 Received: from mail-pl1-x649.google.com (mail-pl1-x649.google.com [IPv6:2607:f8b0:4864:20::649]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A4CDFE74 for <linux-kernel@vger.kernel.org>; Mon, 26 Jun 2023 11:20:24 -0700 (PDT) Received: by mail-pl1-x649.google.com with SMTP id d9443c01a7336-1b5465a79edso14555495ad.3 for <linux-kernel@vger.kernel.org>; Mon, 26 Jun 2023 11:20:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20221208; t=1687803624; x=1690395624; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:reply-to:from:to:cc:subject:date:message-id:reply-to; bh=qTMxx/LJnmIWvUmH+gdz70kQEF0zmvOjZ2b4ibjV0JA=; b=S4eXFyS5rCCSmx6iv7PwkGg0BQvm/qIBJWemgkd6QqmzpVRLetRiUZjak1W1mQyzZr mMKoaj7RIcwyjjYeEciNW4ODHuDXAB0C13yWbXWuat885LfNkeAe1aW17ajmWdoYdpXC lk8VuAdGvlhi04z5vwImriXcHwbtXGq5yiwmyAeXX64MSqe0tt/49ZE3I4ee91HgxP3c zZI/w6Nc73N8LQ4zawaNdpS2epI7IexAi7Wb/yi0aenclZFLqPugb8wyTg5JeBEyxrHx Xt5PuAKkhVJcUdmnZRtHtS5GOOJqKuDtYqs0xkgs9jrVWM7sdTirDlmdiNS+WWD/3Ss3 DLzw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1687803624; x=1690395624; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:reply-to:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=qTMxx/LJnmIWvUmH+gdz70kQEF0zmvOjZ2b4ibjV0JA=; b=f7YQiyJAwi1qI0V1MG1CZ1tISz/XsTs+cSN5JvUQoz079tz0sAyWauAJYA/l+PJg4p eP5CyUlR1XWs68qaT0XptDPIr1EXau38sc/LUle19QIzHb400HsZe4zC9fLavXHcv23/ pg8Ma7yi3EkmjCf0WkN3zXWfgaRzpr5AgvTYaP+KcOQVTBXyVthB7ixXQtKlJBWzuIXe B9SGL1Zu5s2+45C1y8rCLnUi2R/WVk3Cjm19S7cq5h4gk06jqVFQGZLqraTzGXuTDBXP ujlRXXSKltcdFG59su/x7hT/1ViF4x+g2eOMcMd510duyfV5PgHLnnVsRr9cTiRynJXd f42w== X-Gm-Message-State: AC+VfDz+AhiM2lvZMVWT4nJc1krppUtrJUQN63cLI5/J7I/7+453AWvz UyF2lJc6U40hKXpZWOxD237xWQOSS347 X-Received: from mizhang-super.c.googlers.com ([35.247.89.60]) (user=mizhang job=sendgmr) by 2002:a17:902:b608:b0:1b5:bd8:5aaa with SMTP id b8-20020a170902b60800b001b50bd85aaamr1078296pls.1.1687803624119; Mon, 26 Jun 2023 11:20:24 -0700 (PDT) Reply-To: Mingwei Zhang <mizhang@google.com> Date: Mon, 26 Jun 2023 18:20:12 +0000 In-Reply-To: <20230626182016.4127366-1-mizhang@google.com> Mime-Version: 1.0 References: <20230626182016.4127366-1-mizhang@google.com> X-Mailer: git-send-email 2.41.0.162.gfafddb0af9-goog Message-ID: <20230626182016.4127366-3-mizhang@google.com> Subject: [PATCH v2 2/6] KVM: Documentation: Update the field name gfns and its description in kvm_mmu_page From: Mingwei Zhang <mizhang@google.com> To: Sean Christopherson <seanjc@google.com>, Paolo Bonzini <pbonzini@redhat.com> Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Mingwei Zhang <mizhang@google.com>, Kai Huang <kai.huang@intel.com>, Jim Mattson <jmattson@google.com>, David Matlack <dmatlack@google.com>, Ben Gardon <bgardon@google.com>, Xu Yilun <yilun.xu@intel.com>, Zhi Wang <zhi.wang.linux@gmail.com> Content-Type: text/plain; charset="UTF-8" X-Spam-Status: No, score=-9.6 required=5.0 tests=BAYES_00,DKIMWL_WL_MED, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE,USER_IN_DEF_DKIM_WL autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: <linux-kernel.vger.kernel.org> X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1769794131364819339?= X-GMAIL-MSGID: =?utf-8?q?1769794131364819339?= |
Series |
Update document description for kvm_mmu_page and kvm_mmu_page_role
|
|
Commit Message
Mingwei Zhang
June 26, 2023, 6:20 p.m. UTC
Update the field 'gfns' in kvm_mmu_page to 'shadowed_translation' to be consistent with the code. Also update the corresponding 'gfns' in the comments. The more detailed description of 'shadowed_translation' is already inlined in the data structure definition, so no need to duplicate the text but simply just update the names. Signed-off-by: Mingwei Zhang <mizhang@google.com> Reviewed-by: Kai Huang <kai.huang@intel.com> --- Documentation/virt/kvm/x86/mmu.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-)
Comments
Hi-- On 6/26/23 11:20, Mingwei Zhang wrote: > Update the field 'gfns' in kvm_mmu_page to 'shadowed_translation' to be > consistent with the code. Also update the corresponding 'gfns' in the > comments. The more detailed description of 'shadowed_translation' is > already inlined in the data structure definition, so no need to duplicate > the text but simply just update the names. > > Signed-off-by: Mingwei Zhang <mizhang@google.com> > Reviewed-by: Kai Huang <kai.huang@intel.com> > --- > Documentation/virt/kvm/x86/mmu.rst | 9 +++++---- > 1 file changed, 5 insertions(+), 4 deletions(-) > > diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst > index 561efa8ec7d7..4c9044b4dc6c 100644 > --- a/Documentation/virt/kvm/x86/mmu.rst > +++ b/Documentation/virt/kvm/x86/mmu.rst > @@ -221,11 +221,12 @@ Shadow pages contain the following information: > at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. > The spt array forms a DAG structure with the shadow page as a node, and > guest pages as leaves. > - gfns: > - An array of 512 guest frame numbers, one for each present pte. Used to > - perform a reverse map from a pte to a gfn. When role.direct is set, any > + shadowed_translation: > + An array of 512 shadow translation entries, one for each present pte. Used > + to perform a reverse map from a pte to a gfn. When role.direct is set, any > element of this array can be calculated from the gfn field when used, in > - this case, the array of gfns is not allocated. See role.direct and gfn. > + this case, the array of shadowed_translation is not allocated. See I cannot parse the before version nor the after version of this sentence (new version): When role.direct is set, any element of this array can be calculated from the gfn field when used, in this case, the array of shadowed_translation is not allocated. > + role.direct and gfn. > root_count: > A counter keeping track of how many hardware registers (guest cr3 or > pdptrs) are now pointing at the page. While this counter is nonzero, the
On Mon, Jun 26, 2023, Randy Dunlap wrote: > Hi-- > > On 6/26/23 11:20, Mingwei Zhang wrote: > > Update the field 'gfns' in kvm_mmu_page to 'shadowed_translation' to be > > consistent with the code. Also update the corresponding 'gfns' in the > > comments. The more detailed description of 'shadowed_translation' is > > already inlined in the data structure definition, so no need to duplicate > > the text but simply just update the names. > > > > Signed-off-by: Mingwei Zhang <mizhang@google.com> > > Reviewed-by: Kai Huang <kai.huang@intel.com> > > --- > > Documentation/virt/kvm/x86/mmu.rst | 9 +++++---- > > 1 file changed, 5 insertions(+), 4 deletions(-) > > > > diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst > > index 561efa8ec7d7..4c9044b4dc6c 100644 > > --- a/Documentation/virt/kvm/x86/mmu.rst > > +++ b/Documentation/virt/kvm/x86/mmu.rst > > @@ -221,11 +221,12 @@ Shadow pages contain the following information: > > at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. > > The spt array forms a DAG structure with the shadow page as a node, and > > guest pages as leaves. > > - gfns: > > - An array of 512 guest frame numbers, one for each present pte. Used to > > - perform a reverse map from a pte to a gfn. When role.direct is set, any > > + shadowed_translation: > > + An array of 512 shadow translation entries, one for each present pte. Used > > + to perform a reverse map from a pte to a gfn. When role.direct is set, any > > element of this array can be calculated from the gfn field when used, in > > - this case, the array of gfns is not allocated. See role.direct and gfn. > > + this case, the array of shadowed_translation is not allocated. See > > I cannot parse the before version nor the after version of this sentence (new version): > > When role.direct is set, any > element of this array can be calculated from the gfn field when used, in > this case, the array of shadowed_translation is not allocated. > > Sorry for the late reply. Why is it not parsed? It just means that when role.direct is set, do not use gfns. The gfn can be calculated from the base address + offset. The base address here is the 'gfn' field in kvm_mmu_page. > > + role.direct and gfn. > > root_count: > > A counter keeping track of how many hardware registers (guest cr3 or > > pdptrs) are now pointing at the page. While this counter is nonzero, the > > -- > ~Randy
On Mon, Jul 31, 2023, Mingwei Zhang wrote: > On Mon, Jun 26, 2023, Randy Dunlap wrote: > > Hi-- > > > > On 6/26/23 11:20, Mingwei Zhang wrote: > > > Update the field 'gfns' in kvm_mmu_page to 'shadowed_translation' to be > > > consistent with the code. Also update the corresponding 'gfns' in the > > > comments. The more detailed description of 'shadowed_translation' is > > > already inlined in the data structure definition, so no need to duplicate > > > the text but simply just update the names. > > > > > > Signed-off-by: Mingwei Zhang <mizhang@google.com> > > > Reviewed-by: Kai Huang <kai.huang@intel.com> > > > --- > > > Documentation/virt/kvm/x86/mmu.rst | 9 +++++---- > > > 1 file changed, 5 insertions(+), 4 deletions(-) > > > > > > diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst > > > index 561efa8ec7d7..4c9044b4dc6c 100644 > > > --- a/Documentation/virt/kvm/x86/mmu.rst > > > +++ b/Documentation/virt/kvm/x86/mmu.rst > > > @@ -221,11 +221,12 @@ Shadow pages contain the following information: > > > at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. > > > The spt array forms a DAG structure with the shadow page as a node, and > > > guest pages as leaves. > > > - gfns: > > > - An array of 512 guest frame numbers, one for each present pte. Used to > > > - perform a reverse map from a pte to a gfn. When role.direct is set, any > > > + shadowed_translation: > > > + An array of 512 shadow translation entries, one for each present pte. Used > > > + to perform a reverse map from a pte to a gfn. When role.direct is set, any > > > element of this array can be calculated from the gfn field when used, in > > > - this case, the array of gfns is not allocated. See role.direct and gfn. > > > + this case, the array of shadowed_translation is not allocated. See > > > > I cannot parse the before version nor the after version of this sentence (new version): > > > > When role.direct is set, any > > element of this array can be calculated from the gfn field when used, in > > this case, the array of shadowed_translation is not allocated. > > > > > > Sorry for the late reply. Why is it not parsed? It just means that when > role.direct is set, do not use gfns. The gfn can be calculated from the > base address + offset. The base address here is the 'gfn' field in > kvm_mmu_page. It's a bit of a run-on sentence with confusing pronoun usage. How about this? When role.direct is set, the shadow_translation array is not allocated as the per-SPTE gfn is simply an offset from the base gfn, and KVM doesn't track access permissions for direct shadow pages.
On Mon, Jul 31, 2023, Sean Christopherson wrote: > On Mon, Jul 31, 2023, Mingwei Zhang wrote: > > On Mon, Jun 26, 2023, Randy Dunlap wrote: > > > Hi-- > > > > > > On 6/26/23 11:20, Mingwei Zhang wrote: > > > > Update the field 'gfns' in kvm_mmu_page to 'shadowed_translation' to be > > > > consistent with the code. Also update the corresponding 'gfns' in the > > > > comments. The more detailed description of 'shadowed_translation' is > > > > already inlined in the data structure definition, so no need to duplicate > > > > the text but simply just update the names. > > > > > > > > Signed-off-by: Mingwei Zhang <mizhang@google.com> > > > > Reviewed-by: Kai Huang <kai.huang@intel.com> > > > > --- > > > > Documentation/virt/kvm/x86/mmu.rst | 9 +++++---- > > > > 1 file changed, 5 insertions(+), 4 deletions(-) > > > > > > > > diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst > > > > index 561efa8ec7d7..4c9044b4dc6c 100644 > > > > --- a/Documentation/virt/kvm/x86/mmu.rst > > > > +++ b/Documentation/virt/kvm/x86/mmu.rst > > > > @@ -221,11 +221,12 @@ Shadow pages contain the following information: > > > > at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. > > > > The spt array forms a DAG structure with the shadow page as a node, and > > > > guest pages as leaves. > > > > - gfns: > > > > - An array of 512 guest frame numbers, one for each present pte. Used to > > > > - perform a reverse map from a pte to a gfn. When role.direct is set, any > > > > + shadowed_translation: > > > > + An array of 512 shadow translation entries, one for each present pte. Used > > > > + to perform a reverse map from a pte to a gfn. When role.direct is set, any > > > > element of this array can be calculated from the gfn field when used, in > > > > - this case, the array of gfns is not allocated. See role.direct and gfn. > > > > + this case, the array of shadowed_translation is not allocated. See > > > > > > I cannot parse the before version nor the after version of this sentence (new version): > > > > > > When role.direct is set, any > > > element of this array can be calculated from the gfn field when used, in > > > this case, the array of shadowed_translation is not allocated. > > > > > > > > > > Sorry for the late reply. Why is it not parsed? It just means that when > > role.direct is set, do not use gfns. The gfn can be calculated from the > > base address + offset. The base address here is the 'gfn' field in > > kvm_mmu_page. > > It's a bit of a run-on sentence with confusing pronoun usage. How about this? > > When role.direct is set, the shadow_translation array is not allocated as the > per-SPTE gfn is simply an offset from the base gfn, and KVM doesn't track > access permissions for direct shadow pages. I think the problem might be that the sentence is slightly long. To be accurate, we have to mention access permission which the original text did not. Also, I split the sentences and try only using short ones. The overall description will be longer. How about this? shadowed_translation: An array of 512 shadow translation entries, one for each present pte. Used to perform a reverse map from a pte to a gfn as well as its access permission. When role.direct is set, the shadow_translation array is not allocated. This is because the gfn contained in any element of this array can be calculated from the gfn field when used. In addition, when role.direct is set, KVM does not track access permission for each of the gfn. See role.direct and gfn.
diff --git a/Documentation/virt/kvm/x86/mmu.rst b/Documentation/virt/kvm/x86/mmu.rst index 561efa8ec7d7..4c9044b4dc6c 100644 --- a/Documentation/virt/kvm/x86/mmu.rst +++ b/Documentation/virt/kvm/x86/mmu.rst @@ -221,11 +221,12 @@ Shadow pages contain the following information: at __pa(sp2->spt). sp2 will point back at sp1 through parent_pte. The spt array forms a DAG structure with the shadow page as a node, and guest pages as leaves. - gfns: - An array of 512 guest frame numbers, one for each present pte. Used to - perform a reverse map from a pte to a gfn. When role.direct is set, any + shadowed_translation: + An array of 512 shadow translation entries, one for each present pte. Used + to perform a reverse map from a pte to a gfn. When role.direct is set, any element of this array can be calculated from the gfn field when used, in - this case, the array of gfns is not allocated. See role.direct and gfn. + this case, the array of shadowed_translation is not allocated. See + role.direct and gfn. root_count: A counter keeping track of how many hardware registers (guest cr3 or pdptrs) are now pointing at the page. While this counter is nonzero, the