[PATCH 0/3] [PATCH 0/3] Documentation: virtual: convert files from .txt to

[PATCH 0/3] [PATCH 0/3] Documentation: virtual: convert files from .txt to

[Luke Nowakowski-Krijger]

From: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>

Converted a few documents in virtual and virtual/kvm to .rst format.
Also added toctree hooks wherever there were .rst files. Adding hooks to
the main doc tree should be in another patch series once there are more
files in the directory. 

After confirming with the appropriate lists that all the 
Documentation/virtual/* files are not obsolete I will continue
converting the rest of the .txt files to .rst. 

Luke Nowakowski-Krijger (3):
  Documentation: virtual: Add toctree hooks
  Documentation: kvm: Convert cpuid.txt to .rst
  Documentation: virtual: Convert paravirt_ops.txt to .rst

 Documentation/virtual/index.rst               | 18 ++++
 Documentation/virtual/kvm/cpuid.rst           | 99 +++++++++++++++++++
 Documentation/virtual/kvm/cpuid.txt           | 83 ----------------
 Documentation/virtual/kvm/index.rst           | 12 +++
 .../{paravirt_ops.txt => paravirt_ops.rst}    | 19 ++--
 5 files changed, 140 insertions(+), 91 deletions(-)
 create mode 100644 Documentation/virtual/index.rst
 create mode 100644 Documentation/virtual/kvm/cpuid.rst
 delete mode 100644 Documentation/virtual/kvm/cpuid.txt
 create mode 100644 Documentation/virtual/kvm/index.rst
 rename Documentation/virtual/{paravirt_ops.txt => paravirt_ops.rst} (65%)

-- 
2.20.1

[PATCH 1/3] Documentation: virtual: Add toctree hooks

[Luke Nowakowski-Krijger]

From: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>

Added toctree hooks for indexing. Hooks added only for newly added files
or already existing files. 

The hook for the top of the tree will be added in a later patch series
when a few more substantial changes have been added. 

Signed-off-by: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
---
 Documentation/virtual/index.rst     | 18 ++++++++++++++++++
 Documentation/virtual/kvm/index.rst | 12 ++++++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 Documentation/virtual/index.rst
 create mode 100644 Documentation/virtual/kvm/index.rst

diff --git a/Documentation/virtual/index.rst b/Documentation/virtual/index.rst
new file mode 100644
index 000000000000..19c9fa2266f4
--- /dev/null
+++ b/Documentation/virtual/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
+Linux Virtual Documentation
+===========================
+
+.. toctree::
+   :maxdepth: 2
+
+   kvm/index
+   paravirt_ops
+
+.. only:: html and subproject
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/virtual/kvm/index.rst b/Documentation/virtual/kvm/index.rst
new file mode 100644
index 000000000000..ada224a511fe
--- /dev/null
+++ b/Documentation/virtual/kvm/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===
+KVM
+===
+
+.. toctree::
+   :maxdepth: 2
+
+   amd-memory-encryption
+   cpuid
+   vcpu-requests
-- 
2.20.1

[PATCH 2/3] Documentation: kvm: Convert cpuid.txt to .rst

[Luke Nowakowski-Krijger]

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. 

Signed-off-by: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
---
 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
+
+==============
+KVM CPUID bits
+==============
+
+:Author: 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 ``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  | 24         | host will warn if no guest-side |
+| _BIT                           |            | 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
-----------------------------------------------------------------------------------
-- 
2.20.1

[PATCH 3/3] Documentation: virtual: Convert paravirt_ops.txt to .rst

[Luke Nowakowski-Krijger]

From: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>

Convert paravirt_opts.txt to .rst format to be able to be parsed by
sphinx. 

Made some minor spacing and formatting corrections to make defintions
much more clear and easy to read. 

Signed-off-by: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
---
 .../{paravirt_ops.txt => paravirt_ops.rst}    | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)
 rename Documentation/virtual/{paravirt_ops.txt => paravirt_ops.rst} (65%)

diff --git a/Documentation/virtual/paravirt_ops.txt b/Documentation/virtual/paravirt_ops.rst
similarity index 65%
rename from Documentation/virtual/paravirt_ops.txt
rename to Documentation/virtual/paravirt_ops.rst
index d4881c00e339..6b789d27cead 100644
--- a/Documentation/virtual/paravirt_ops.txt
+++ b/Documentation/virtual/paravirt_ops.rst
@@ -1,3 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
 Paravirt_ops
 ============
 
@@ -18,15 +21,15 @@ at boot time.
 pv_ops operations are classified into three categories:
 
 - simple indirect call
-  These operations correspond to high level functionality where it is
-  known that the overhead of indirect call isn't very important.
+   These operations correspond to high level functionality where it is
+   known that the overhead of indirect call isn't very important.
 
 - indirect call which allows optimization with binary patch
-  Usually these operations correspond to low level critical instructions. They
-  are called frequently and are performance critical. The overhead is
-  very important.
+   Usually these operations correspond to low level critical instructions. They
+   are called frequently and are performance critical. The overhead is
+   very important.
 
 - a set of macros for hand written assembly code
-  Hand written assembly codes (.S files) also need paravirtualization
-  because they include sensitive instructions or some of code paths in
-  them are very performance critical.
+   Hand written assembly codes (.S files) also need paravirtualization
+   because they include sensitive instructions or some of code paths in
+   them are very performance critical.
-- 
2.20.1

Re: [PATCH 1/3] Documentation: virtual: Add toctree hooks

[Jonathan Corbet]

On Sat,  6 Jul 2019 14:38:13 -0700
Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu> wrote:

> From: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
> 
> Added toctree hooks for indexing. Hooks added only for newly added files
> or already existing files. 
> 
> The hook for the top of the tree will be added in a later patch series
> when a few more substantial changes have been added. 
> 
> Signed-off-by: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
> ---
>  Documentation/virtual/index.rst     | 18 ++++++++++++++++++
>  Documentation/virtual/kvm/index.rst | 12 ++++++++++++
>  2 files changed, 30 insertions(+)
>  create mode 100644 Documentation/virtual/index.rst
>  create mode 100644 Documentation/virtual/kvm/index.rst
> 
> diff --git a/Documentation/virtual/index.rst b/Documentation/virtual/index.rst
> new file mode 100644
> index 000000000000..19c9fa2266f4
> --- /dev/null
> +++ b/Documentation/virtual/index.rst
> @@ -0,0 +1,18 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===========================
> +Linux Virtual Documentation
> +===========================
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   kvm/index
> +   paravirt_ops
> +
> +.. only:: html and subproject
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> diff --git a/Documentation/virtual/kvm/index.rst b/Documentation/virtual/kvm/index.rst
> new file mode 100644
> index 000000000000..ada224a511fe
> --- /dev/null
> +++ b/Documentation/virtual/kvm/index.rst
> @@ -0,0 +1,12 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===
> +KVM
> +===
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   amd-memory-encryption
> +   cpuid
> +   vcpu-requests

At this point in the patch series, the above-mentioned RST files don't
exist.  So if somebody tries to build the docs here, the build will fail.
I suspect that it's pretty rare for people to use bisection with docs
builds, but it's still proper practice to ensure that things work at every
step in your series.  So the above entries should be added in the patches
that convert the files.

Also, vcpu-requests.txt is never touched in this patch series, which
suggests that you didn't build the docs even at the end of it.

Thanks,

jon

Re: [PATCH 2/3] Documentation: kvm: Convert cpuid.txt to .rst

[Jonathan Corbet]

On Sat,  6 Jul 2019 14:38:14 -0700
Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu> wrote:

> 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. 
> 
> Signed-off-by: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
> ---
>  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.

> +==============
> +KVM CPUID bits
> +==============
> +
> +:Author: Glauber Costa <glommer@redhat.com>, Red Hat Inc, 2010

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

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

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

Thanks,

jon

Re: [PATCH 2/3] Documentation: kvm: Convert cpuid.txt to .rst

[Luke Nowakowski-Krijger]

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 <lnowakow@eng.ucsd.edu> wrote:
> 
> > 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. 
> > 
> > Signed-off-by: Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu>
> > ---
> >  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.

> > +==============
> > +KVM CPUID bits
> > +==============
> > +
> > +:Author: Glauber Costa <glommer@redhat.com>, 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? 

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

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

Re: [PATCH 2/3] Documentation: kvm: Convert cpuid.txt to .rst

[Jonathan Corbet]

On Mon, 8 Jul 2019 13:15:10 -0700
Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu> wrote:

> > > +:Author: Glauber Costa <glommer@redhat.com>, 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? 

There's nothing good that will come from keeping a broken email address
there.  You could either:

 - Just take the address out, or

 - Track Glauber down and get a newer address; you could ask him about the
   licensing while you're at it :)

Thanks,

jon

Re: [PATCH 1/3] Documentation: virtual: Add toctree hooks

[Luke Nowakowski-Krijger]

On Mon, Jul 08, 2019 at 01:54:04PM -0600, Jonathan Corbet wrote:
> On Sat,  6 Jul 2019 14:38:13 -0700
> Luke Nowakowski-Krijger <lnowakow@eng.ucsd.edu> wrote:
> 
 
> At this point in the patch series, the above-mentioned RST files don't
> exist.  So if somebody tries to build the docs here, the build will fail.
> I suspect that it's pretty rare for people to use bisection with docs
> builds, but it's still proper practice to ensure that things work at every
> step in your series.  So the above entries should be added in the patches
> that convert the files.
>

Yes, agreed. It should be at the end of the series. 

> Also, vcpu-requests.txt is never touched in this patch series, which
> suggests that you didn't build the docs even at the end of it.
> 

In the staging tree I was doing work out of I saw a vcpu-requests.rst
file so thought I could add it "while I'm here". 

You're right. I should only add the files I am converting. 

> Thanks,
> 
> jon

Thanks again, 
- Luke

Re: [PATCH 2/3] Documentation: kvm: Convert cpuid.txt to .rst

[Paolo Bonzini]

On 08/07/19 22:20, Jonathan Corbet wrote:
>>>> +:Author: Glauber Costa <glommer@redhat.com>, 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? 
> There's nothing good that will come from keeping a broken email address
> there.  You could either:
> 
>  - Just take the address out, or

I agree with this, there have been more authors since 2010.

Regarding the license, it was my understanding that if somebody wants
anything but GPL-2.0 they should put it in the file when they create it.
 That's because even if Glauber had a different idea of what license to
use, other contributors to the file couldn't know.

Paolo

>  - Track Glauber down and get a newer address; you could ask him about the
>    licensing while you're at it :)