From nobody Tue Apr 7 07:05:55 2026 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 vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id EAE0FECAAA1 for ; Wed, 31 Aug 2022 00:17:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231528AbiHaAR0 (ORCPT ); Tue, 30 Aug 2022 20:17:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:54750 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231514AbiHaARR (ORCPT ); Tue, 30 Aug 2022 20:17:17 -0400 Received: from mail-pj1-x1049.google.com (mail-pj1-x1049.google.com [IPv6:2607:f8b0:4864:20::1049]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id DADFB9BB6E for ; Tue, 30 Aug 2022 17:17:14 -0700 (PDT) Received: by mail-pj1-x1049.google.com with SMTP id mq13-20020a17090b380d00b001fb60a596c8so1455489pjb.0 for ; Tue, 30 Aug 2022 17:17:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:reply-to:from:to:cc; bh=W7gWj5xWpB4Nm/5nHsnSYJ2NBkPvoSHoIvPmK8zyBD4=; b=apF5W0LbK7aSyoktgfKgInFInnrXWL9VjEodnG0XpZyi3607eiUgzGiRhJL5RM2TL9 YfsoSbs4PRLUnHxX1xqwhkkjQN4wIqR44jXWqimODSYzoZFu0cD2TrssVikUiQHSLtDD vKck8No7qEHWQJrxZuQvcILCXEEuQJbDyGZ4W8dSpeXPyfKn3OO5ijY38+n4upa8E0bb cLeZyxI1mHAPNPTzQxKsnIzUs5USDf5oDx33hxvTgZhJe7vYPmuWu4m195TNztfGp5xG TkEXQenDtXrRDdlBfCP2DjcomChN7F7dHoH4AMxgqwHR2PwWnd1EOHRs3PGD0VtuoWej sq6w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:reply-to:x-gm-message-state:from:to:cc; bh=W7gWj5xWpB4Nm/5nHsnSYJ2NBkPvoSHoIvPmK8zyBD4=; b=5Acad5uS6qD7bcjnGmwAenWD9cxtFgQtkZXeqMlDzODFnHnybxEyukXSlUUBsKkV5O hDK363QUyDq5gY0x4+yPlSQwqdnSziXr1SEEiDlgyYUIx7PVadpJAhvnM/SbMqRM2bl0 RwIyZbZSAmeuJeQ9RX8UV5vi7YJj5itfnbcRkN/PiRsISIl/VU8/Fnp4/ej2c5MdHp+6 SNo2tShrb7+PPjVT4+T81wcHdK2mTkaSjx8Kmyb9bPldpq1pl767/4T58uVpa3Y34MJp 4AYhgT62TVAqUq5pklfdrd8JCC1DLNVeCFo/8zo3aLvBNq/Xip8DRFpYz+ZwrwUJCIWX XMfQ== X-Gm-Message-State: ACgBeo2HTs+CDxZf06cHspoiqQPXiFDlZMrDy2hcRnCT+JJBKb3Yzzv9 FdEbQsNGc8sKfEyHEC9JUtoFIqnrLs0= X-Google-Smtp-Source: AA6agR4sgrM+8MSFb94eBPFvXUY852S6/HICOlkjKy3bOT/hEkeGasAZ2SS/kAPgwNIf3Ik/7zxZ9sxDuko= X-Received: from zagreus.c.googlers.com ([fda3:e722:ac3:cc00:7f:e700:c0a8:5c37]) (user=seanjc job=sendgmr) by 2002:a17:90a:249:b0:1e0:a8a3:3c6c with SMTP id t9-20020a17090a024900b001e0a8a33c6cmr22624pje.0.1661905033981; Tue, 30 Aug 2022 17:17:13 -0700 (PDT) Reply-To: Sean Christopherson Date: Wed, 31 Aug 2022 00:17:06 +0000 In-Reply-To: <20220831001706.4075399-1-seanjc@google.com> Mime-Version: 1.0 References: <20220831001706.4075399-1-seanjc@google.com> X-Mailer: git-send-email 2.37.2.672.g94769d06f0-goog Message-ID: <20220831001706.4075399-4-seanjc@google.com> Subject: [PATCH 3/3] KVM: x86: Clean up KVM_CAP_X86_USER_SPACE_MSR documentation From: Sean Christopherson To: Paolo Bonzini Cc: kvm@vger.kernel.org, linux-kernel@vger.kernel.org, Sean Christopherson , Aaron Lewis Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Clean up the KVM_CAP_X86_USER_SPACE_MSR documentation to eliminate misleading and/or inconsistent verbiage, and to actually document what accesses are intercepted by which flags. - s/will/may since not all #GPs are guaranteed to be intercepted - s/deflect/intercept to align with common KVM terminology - s/user space/userspace to align with the majority of KVM docs - Avoid using "trap" terminology, as KVM exits to userspace _before_ stepping, i.e. doesn't exhibit trap-like behavior - Actually document the flags Signed-off-by: Sean Christopherson --- Documentation/virt/kvm/api.rst | 40 ++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 406d3e7c5a59..32d8fc8dcbb5 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -6431,29 +6431,29 @@ if it decides to decode and emulate the instruction. =20 Used on x86 systems. When the VM capability KVM_CAP_X86_USER_SPACE_MSR is enabled, MSR accesses to registers that would invoke a #GP by KVM kernel c= ode -will instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_= WRMSR +may instead trigger a KVM_EXIT_X86_RDMSR exit for reads and KVM_EXIT_X86_W= RMSR exit for writes. =20 -The "reason" field specifies why the MSR trap occurred. User space will on= ly -receive MSR exit traps when a particular reason was requested during throu= gh +The "reason" field specifies why the MSR interception occurred. Userspace = will +only receive MSR exits when a particular reason was requested during throu= gh ENABLE_CAP. Currently valid exit reasons are: =20 KVM_MSR_EXIT_REASON_UNKNOWN - access to MSR that is unknown to KVM KVM_MSR_EXIT_REASON_INVAL - access to invalid MSRs or reserved bits KVM_MSR_EXIT_REASON_FILTER - access blocked by KVM_X86_SET_MSR_FILTER =20 -For KVM_EXIT_X86_RDMSR, the "index" field tells user space which MSR the g= uest -wants to read. To respond to this request with a successful read, user spa= ce +For KVM_EXIT_X86_RDMSR, the "index" field tells userspace which MSR the gu= est +wants to read. To respond to this request with a successful read, userspace writes the respective data into the "data" field and must continue guest execution to ensure the read data is transferred into guest register state. =20 -If the RDMSR request was unsuccessful, user space indicates that with a "1= " in +If the RDMSR request was unsuccessful, userspace indicates that with a "1"= in the "error" field. This will inject a #GP into the guest when the VCPU is executed again. =20 -For KVM_EXIT_X86_WRMSR, the "index" field tells user space which MSR the g= uest -wants to write. Once finished processing the event, user space must contin= ue -vCPU execution. If the MSR write was unsuccessful, user space also sets the +For KVM_EXIT_X86_WRMSR, the "index" field tells userspace which MSR the gu= est +wants to write. Once finished processing the event, userspace must continue +vCPU execution. If the MSR write was unsuccessful, userspace also sets the "error" field to "1". =20 See KVM_X86_SET_MSR_FILTER for details on the interaction with MSR filteri= ng. @@ -7223,19 +7223,27 @@ the module parameter for the target VM. :Parameters: args[0] contains the mask of KVM_MSR_EXIT_REASON_* events to = report :Returns: 0 on success; -1 on error =20 -This capability enables trapping of #GP invoking RDMSR and WRMSR instructi= ons -into user space. +This capability allows userspace to intercept RDMSR and WRMSR instructions= if +access to an MSR is denied. By default, KVM injects #GP on denied accesse= s. =20 When a guest requests to read or write an MSR, KVM may not implement all M= SRs that are relevant to a respective system. It also does not differentiate by CPU type. =20 -To allow more fine grained control over MSR handling, user space may enable +To allow more fine grained control over MSR handling, userspace may enable this capability. With it enabled, MSR accesses that match the mask specifi= ed in -args[0] and trigger a #GP event inside the guest by KVM will instead trigg= er -KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications which user sp= ace -can then handle to implement model specific MSR handling and/or user notif= ications -to inform a user that an MSR was not handled. +args[0] and would trigger a #GP inside the guest will instead trigger +KVM_EXIT_X86_RDMSR and KVM_EXIT_X86_WRMSR exit notifications. Userspace +can then implement model specific MSR handling and/or user notifications +to inform a user that an MSR was not emulated/virtualized by KVM. + +The valid mask flags are: + + KVM_MSR_EXIT_REASON_UNKNOWN - intercept accesses to unknown (to KVM) MSRs + KVM_MSR_EXIT_REASON_INVAL - intercept accesses that are architecturally + invalid according to the vCPU model and/or= mode + KVM_MSR_EXIT_REASON_FILTER - intercept accesses that are denied by users= pace + via KVM_X86_SET_MSR_FILTER =20 7.22 KVM_CAP_X86_BUS_LOCK_EXIT ------------------------------- --=20 2.37.2.672.g94769d06f0-goog