From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
Cc: linux-kernel-mentees@lists.linuxfoundation.org,
pbonzini@redhat.com, rkrcmar@redhat.com, corbet@lwn.net,
kvm@vger.kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 1/3] Documentation: kvm: Convert cpuid.txt to .rst
Date: Wed, 10 Jul 2019 10:07:10 -0300 [thread overview]
Message-ID: <20190710100710.58443e79@coco.lan> (raw)
In-Reply-To: <20190709200721.16991-2-lnowakow@neg.ucsd.edu>
Em Tue, 9 Jul 2019 13:07:19 -0700
Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu> escreveu:
> From: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
>
> Convert cpuid.txt to .rst format to be parsable by sphinx.
>
> Change format and spacing to make function definitions and return values
> much more clear. Also added a table that is parsable by sphinx and makes
> the information much more clean. Updated Author email to their new
> active email address. Added license identifier with the consent of the
> author.
>
> Signed-off-by: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
> ---
> Changes since v2:
> + added updated Author email address
> + changed table to simpler format
> - removed function bolding from v1
> Changes since v1:
> + Converted doc to .rst format
>
> Documentation/virtual/kvm/cpuid.rst | 99 +++++++++++++++++++++++++++++
> Documentation/virtual/kvm/cpuid.txt | 83 ------------------------
> 2 files changed, 99 insertions(+), 83 deletions(-)
> create mode 100644 Documentation/virtual/kvm/cpuid.rst
> delete mode 100644 Documentation/virtual/kvm/cpuid.txt
I strongly suggest to generate the diff with -M1, in order to show it
as a diff, instead of create/delete.
Btw, when applying on the top of linux-next, I got a merge conflict,
probably due to this patch:
commit 9824c83f92bc8351dfb5c387436cc2816616fb4a
Author: Paolo Bonzini <pbonzini@redhat.com>
Date: Tue Jul 2 18:57:29 2019 +0200
Documentation: kvm: document CPUID bit for MSR_KVM_POLL_CONTROL
which added a new flag (KVM_FEATURE_PV_POLL_CONTROL). There's also
another patch adding KVM_FEATURE_PV_SCHED_YIELD flag.
In order to check the results, I did already a rebase on the top a temp
branch on my experimental tree:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames_next_v3&id=90330aba498e6d9d5258322d0006b3968e9a65a9
(please notice that this is not the upstream docs branch, so you
need to re-submit the patch to the ML)
With the rebase, for this 3 patch series:
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> diff --git a/Documentation/virtual/kvm/cpuid.rst b/Documentation/virtual/kvm/cpuid.rst
> new file mode 100644
> index 000000000000..644c53687861
> --- /dev/null
> +++ b/Documentation/virtual/kvm/cpuid.rst
> @@ -0,0 +1,99 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +==============
> +KVM CPUID bits
> +==============
> +
> +:Author: Glauber Costa <glommer@gmail.com>
> +
> +A guest running on a kvm host, can check some of its features using
> +cpuid. This is not always guaranteed to work, since userspace can
> +mask-out some, or even all KVM-related cpuid features before launching
> +a guest.
> +
> +KVM cpuid functions are:
> +
> +function: KVM_CPUID_SIGNATURE (0x40000000)
> +
> +returns::
> +
> + eax = 0x40000001
> + ebx = 0x4b4d564b
> + ecx = 0x564b4d56
> + edx = 0x4d
> +
> +Note that this value in ebx, ecx and edx corresponds to the string "KVMKVMKVM".
> +The value in eax corresponds to the maximum cpuid function present in this leaf,
> +and will be updated if more functions are added in the future.
> +Note also that old hosts set eax value to 0x0. This should
> +be interpreted as if the value was 0x40000001.
> +This function queries the presence of KVM cpuid leafs.
> +
> +function: define KVM_CPUID_FEATURES (0x40000001)
> +
> +returns::
> +
> + ebx, ecx
> + eax = an OR'ed group of (1 << flag)
> +
> +where ``flag`` is defined as below:
> +
> +================================= =========== ================================
> +flag value meaning
> +================================= =========== ================================
> +KVM_FEATURE_CLOCKSOURCE 0 kvmclock available at msrs
> + 0x11 and 0x12
> +
> +KVM_FEATURE_NOP_IO_DELAY 1 not necessary to perform delays
> + on PIO operations
> +
> +KVM_FEATURE_MMU_OP 2 deprecated
> +
> +KVM_FEATURE_CLOCKSOURCE2 3 kvmclock available at msrs
> +
> + 0x4b564d00 and 0x4b564d01
> +KVM_FEATURE_ASYNC_PF 4 async pf can be enabled by
> + writing to msr 0x4b564d02
> +
> +KVM_FEATURE_STEAL_TIME 5 steal time can be enabled by
> + writing to msr 0x4b564d03
> +
> +KVM_FEATURE_PV_EOI 6 paravirtualized end of interrupt
> + handler can be enabled by
> + writing to msr 0x4b564d04
> +
> +KVM_FEATURE_PV_UNHAULT 7 guest checks this feature bit
> + before enabling paravirtualized
> + spinlock support
> +
> +KVM_FEATURE_PV_TLB_FLUSH 9 guest checks this feature bit
> + before enabling paravirtualized
> + tlb flush
> +
> +KVM_FEATURE_ASYNC_PF_VMEXIT 10 paravirtualized async PF VM EXIT
> + can be enabled by setting bit 2
> + when writing to msr 0x4b564d02
> +
> +KVM_FEATURE_PV_SEND_IPI 11 guest checks this feature bit
> + before enabling paravirtualized
> + sebd IPIs
> +
> +KVM_FEATURE_CLOCSOURCE_STABLE_BIT 24 host will warn if no guest-side
> + per-cpu warps are expeced in
> + kvmclock
> +================================= =========== ================================
> +
> +::
> +
> + edx = an OR'ed group of (1 << flag)
> +
> +Where ``flag`` here is defined as below:
> +
> +================== ============ =================================
> +flag value meaning
> +================== ============ =================================
> +KVM_HINTS_REALTIME 0 guest checks this feature bit to
> + determine that vCPUs are never
> + preempted for an unlimited time
> + allowing optimizations
> +================== ============ =================================
> diff --git a/Documentation/virtual/kvm/cpuid.txt b/Documentation/virtual/kvm/cpuid.txt
> deleted file mode 100644
> index 97ca1940a0dc..000000000000
> --- a/Documentation/virtual/kvm/cpuid.txt
> +++ /dev/null
> @@ -1,83 +0,0 @@
> -KVM CPUID bits
> -Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010
> -=====================================================
> -
> -A guest running on a kvm host, can check some of its features using
> -cpuid. This is not always guaranteed to work, since userspace can
> -mask-out some, or even all KVM-related cpuid features before launching
> -a guest.
> -
> -KVM cpuid functions are:
> -
> -function: KVM_CPUID_SIGNATURE (0x40000000)
> -returns : eax = 0x40000001,
> - ebx = 0x4b4d564b,
> - ecx = 0x564b4d56,
> - edx = 0x4d.
> -Note that this value in ebx, ecx and edx corresponds to the string "KVMKVMKVM".
> -The value in eax corresponds to the maximum cpuid function present in this leaf,
> -and will be updated if more functions are added in the future.
> -Note also that old hosts set eax value to 0x0. This should
> -be interpreted as if the value was 0x40000001.
> -This function queries the presence of KVM cpuid leafs.
> -
> -
> -function: define KVM_CPUID_FEATURES (0x40000001)
> -returns : ebx, ecx
> - eax = an OR'ed group of (1 << flag), where each flags is:
> -
> -
> -flag || value || meaning
> -=============================================================================
> -KVM_FEATURE_CLOCKSOURCE || 0 || kvmclock available at msrs
> - || || 0x11 and 0x12.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_NOP_IO_DELAY || 1 || not necessary to perform delays
> - || || on PIO operations.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_MMU_OP || 2 || deprecated.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_CLOCKSOURCE2 || 3 || kvmclock available at msrs
> - || || 0x4b564d00 and 0x4b564d01
> -------------------------------------------------------------------------------
> -KVM_FEATURE_ASYNC_PF || 4 || async pf can be enabled by
> - || || writing to msr 0x4b564d02
> -------------------------------------------------------------------------------
> -KVM_FEATURE_STEAL_TIME || 5 || steal time can be enabled by
> - || || writing to msr 0x4b564d03.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_PV_EOI || 6 || paravirtualized end of interrupt
> - || || handler can be enabled by writing
> - || || to msr 0x4b564d04.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_PV_UNHALT || 7 || guest checks this feature bit
> - || || before enabling paravirtualized
> - || || spinlock support.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_PV_TLB_FLUSH || 9 || guest checks this feature bit
> - || || before enabling paravirtualized
> - || || tlb flush.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_ASYNC_PF_VMEXIT || 10 || paravirtualized async PF VM exit
> - || || can be enabled by setting bit 2
> - || || when writing to msr 0x4b564d02
> -------------------------------------------------------------------------------
> -KVM_FEATURE_PV_SEND_IPI || 11 || guest checks this feature bit
> - || || before using paravirtualized
> - || || send IPIs.
> -------------------------------------------------------------------------------
> -KVM_FEATURE_CLOCKSOURCE_STABLE_BIT || 24 || host will warn if no guest-side
> - || || per-cpu warps are expected in
> - || || kvmclock.
> -------------------------------------------------------------------------------
> -
> - edx = an OR'ed group of (1 << flag), where each flags is:
> -
> -
> -flag || value || meaning
> -==================================================================================
> -KVM_HINTS_REALTIME || 0 || guest checks this feature bit to
> - || || determine that vCPUs are never
> - || || preempted for an unlimited time,
> - || || allowing optimizations
> -----------------------------------------------------------------------------------
Thanks,
Mauro
next prev parent reply other threads:[~2019-07-10 13:07 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-07-09 20:07 [PATCH v2 0/3] Documentation: virtual: convert .txt to .rst Luke Nowakowski-Krijger
2019-07-09 20:07 ` [PATCH v2 1/3] Documentation: kvm: Convert cpuid.txt " Luke Nowakowski-Krijger
2019-07-10 13:07 ` Mauro Carvalho Chehab [this message]
2019-07-09 20:07 ` [PATCH v2 2/3] Documentation: virtual: Convert paravirt_ops.txt " Luke Nowakowski-Krijger
2019-07-09 20:07 ` [PATCH v2 3/3] Documentation: virtual: Add toctree hooks Luke Nowakowski-Krijger
2019-07-10 5:41 ` [PATCH v2 0/3] Documentation: virtual: convert .txt to .rst Paolo Bonzini
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190710100710.58443e79@coco.lan \
--to=mchehab+samsung@kernel.org \
--cc=corbet@lwn.net \
--cc=kvm@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel-mentees@lists.linuxfoundation.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lnowakow@eng.ucsd.edu \
--cc=pbonzini@redhat.com \
--cc=rkrcmar@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).