On Mon, Jul 08, 2019 at 02:00:22PM -0600, Jonathan Corbet wrote:

On Sat,  6 Jul 2019 14:38:14 -0700
Luke Nowakowski-Krijger [off-list ref] wrote:

quoted

From: Luke Nowakowski-Krijger <redacted>

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. 

Signed-off-by: Luke Nowakowski-Krijger <redacted>
---
 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

diff --git a/Documentation/virtual/kvm/cpuid.rst b/Documentation/virtual/kvm/cpuid.rst
new file mode 100644
index 000000000000..1a03336a500e
--- /dev/null
+++ b/Documentation/virtual/kvm/cpuid.rst

@@ -0,0 +1,99 @@
+.. SPDX-License-Identifier: GPL-2.0

Do you know that this is the appropriate license for this file?  If so, you
should say how you know that.  I appreciate that you thought to add the
SPDX line, but we have to be sure that it actually matches the intent of
the creator of this file.

I do not know what the authors intent was. You are right. This is not my
work after all. Ill remove it in the next version.

quoted

+==============
+KVM CPUID bits
+==============
+
+:Author: Glauber Costa [off-list ref], Red Hat Inc, 2010

I rather suspect that email address doesn't work these days.

No I guess it wont :). We would still keep this correct? 

quoted

+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)**

I wouldn't add the **markup** here, it doesn't really help.

My intent was to make the "function" part more readable immediately
because otherwise it sort of looks like a wall of text. I might have
gotten a little too fancy here though. 

quoted

+
+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                   |

You might consider using the

    ======= ===== ======
    simpler table format
    ======= ===== ======

here, it might be a bit easier to read and maintain.

Understood. 

Thanks,

jon

Thanks for the review, 
- Luke