[PATCH 0/5] docs: reorganize target-i386 to make room for SGX

[PATCH 0/5] docs: reorganize target-i386 to make room for SGX

[Paolo Bonzini]

The docs/ directory includes the documentation for many x86 features,
but target-i386.rst does not really have a structure that lends itself
to incorporating those documents.  One problem in particular is the
CPU model documentation, which is currently structured to be included
in both target-i386.rst and a man page.  This series changes that
documentation to be included from a subpage of target-i386.rst.

The first three patches use overline headings in standardized places
(book titles, docs/*/index.rst, man pages) to make include directives
easier to use from both manuals and man pages.

Based on this preparation, the fourth patch reorganizes target-i386.rst
so that it can be a place for many features currently documented in
docs/.  The new structure is inspired by the s390 documentation.
The final one converts the .txt file for SGX documentation to
reStructuredText and gives it a new home in docs/system/i386.

Paolo Bonzini (5):
  docs: standardize book titles to === with overline
  docs: standardize directory index to --- with overline
  docs/system: standardize man page section to --- with overline
  docs/system: move x86 CPU configuration to a separate document
  docs/system: move SGX documentation within the system docs

 docs/about/index.rst                        |  3 +-
 docs/devel/index.rst                        |  3 +-
 docs/index.rst                              |  1 +
 docs/interop/index.rst                      |  3 +-
 docs/specs/index.rst                        |  3 +-
 docs/system/cpu-models-x86.rst.inc          |  4 +-
 docs/system/i386/cpu.rst                    |  1 +
 docs/{intel-sgx.txt => system/i386/sgx.rst} | 70 ++++++++++-----------
 docs/system/index.rst                       |  3 +-
 docs/system/qemu-block-drivers.rst          |  4 ++
 docs/system/qemu-cpu-models.rst             | 10 ++-
 docs/system/qemu-manpage.rst                | 10 ++-
 docs/system/target-i386.rst                 |  9 ++-
 docs/tools/index.rst                        |  3 +-
 docs/tools/qemu-img.rst                     |  1 +
 docs/tools/qemu-nbd.rst                     |  1 +
 docs/tools/qemu-pr-helper.rst               |  1 +
 docs/tools/qemu-storage-daemon.rst          |  1 +
 docs/tools/qemu-trace-stap.rst              |  1 +
 docs/user/index.rst                         |  3 +-
 20 files changed, 84 insertions(+), 51 deletions(-)
 create mode 100644 docs/system/i386/cpu.rst
 rename docs/{intel-sgx.txt => system/i386/sgx.rst} (83%)

-- 
2.31.1

[PATCH 1/5] docs: standardize book titles to === with overline

[Paolo Bonzini]

Documents within a Sphinx manual are separate files and therefore can use
different conventions for headings.  However, keeping some consistency is
useful so that included files are easy to get right.

This patch uses a standard heading format for book titles, so that it is
obvious when a file sits at the top level toctree of a book or man page.
The heading is irrelevant for man pages, but keep it consistent as well.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/index.rst                     | 1 +
 docs/system/qemu-block-drivers.rst | 1 +
 docs/system/qemu-cpu-models.rst    | 1 +
 docs/system/qemu-manpage.rst       | 5 +++--
 docs/tools/qemu-img.rst            | 1 +
 docs/tools/qemu-nbd.rst            | 1 +
 docs/tools/qemu-pr-helper.rst      | 1 +
 docs/tools/qemu-storage-daemon.rst | 1 +
 docs/tools/qemu-trace-stap.rst     | 1 +
 9 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 5f7eaaa632..0b9ee9901d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,6 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+================================
 Welcome to QEMU's documentation!
 ================================
 
diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-drivers.rst
index bd99d4fa8e..eb276481d6 100644
--- a/docs/system/qemu-block-drivers.rst
+++ b/docs/system/qemu-block-drivers.rst
@@ -1,5 +1,6 @@
 :orphan:
 
+============================
 QEMU block drivers reference
 ============================
 
diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.rst
index 53d7538c47..8c51e2bf49 100644
--- a/docs/system/qemu-cpu-models.rst
+++ b/docs/system/qemu-cpu-models.rst
@@ -1,5 +1,6 @@
 :orphan:
 
+==================================
 QEMU / KVM CPU model configuration
 ==================================
 
diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst
index e9a25d0680..d6f44e265b 100644
--- a/docs/system/qemu-manpage.rst
+++ b/docs/system/qemu-manpage.rst
@@ -6,8 +6,9 @@
    parts of the documentation that go in the manpage as well as the
    HTML manual.
 
-Title
-=====
+=======================
+QEMU User Documentation
+=======================
 
 Synopsis
 --------
diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst
index b7d602a288..fe6c30d509 100644
--- a/docs/tools/qemu-img.rst
+++ b/docs/tools/qemu-img.rst
@@ -1,3 +1,4 @@
+=======================
 QEMU disk image utility
 =======================
 
diff --git a/docs/tools/qemu-nbd.rst b/docs/tools/qemu-nbd.rst
index ee862fa0bc..e39a9f4b1a 100644
--- a/docs/tools/qemu-nbd.rst
+++ b/docs/tools/qemu-nbd.rst
@@ -1,3 +1,4 @@
+=====================================
 QEMU Disk Network Block Device Server
 =====================================
 
diff --git a/docs/tools/qemu-pr-helper.rst b/docs/tools/qemu-pr-helper.rst
index ac036180ac..eaebe40da0 100644
--- a/docs/tools/qemu-pr-helper.rst
+++ b/docs/tools/qemu-pr-helper.rst
@@ -1,3 +1,4 @@
+==================================
 QEMU persistent reservation helper
 ==================================
 
diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
index 3ec4bdd914..b8ef4486f1 100644
--- a/docs/tools/qemu-storage-daemon.rst
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -1,3 +1,4 @@
+===================
 QEMU Storage Daemon
 ===================
 
diff --git a/docs/tools/qemu-trace-stap.rst b/docs/tools/qemu-trace-stap.rst
index fb70445c75..d53073b52b 100644
--- a/docs/tools/qemu-trace-stap.rst
+++ b/docs/tools/qemu-trace-stap.rst
@@ -1,3 +1,4 @@
+=========================
 QEMU SystemTap trace tool
 =========================
 
-- 
2.31.1

[PATCH 2/5] docs: standardize directory index to --- with overline

[Paolo Bonzini]

Use a standard heading format for the index.rst file in a directory.
Using overlines makes it clear that individual documents can use e.g.
=== for chapter titles and --- for section titles, as suggested in the
Linux kernel guidelines[1].  They could do it anyway, because documents
included in a toctree are parsed separately and therefore are not tied
to the same conventions for headings.  However, keeping some consistency is
useful since sometimes files are included from multiple places.

[1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/about/index.rst   | 3 ++-
 docs/devel/index.rst   | 3 ++-
 docs/interop/index.rst | 3 ++-
 docs/specs/index.rst   | 3 ++-
 docs/system/index.rst  | 3 ++-
 docs/tools/index.rst   | 3 ++-
 docs/user/index.rst    | 3 ++-
 7 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/docs/about/index.rst b/docs/about/index.rst
index beb762aa0a..5bea653c07 100644
--- a/docs/about/index.rst
+++ b/docs/about/index.rst
@@ -1,5 +1,6 @@
+----------
 About QEMU
-==========
+----------
 
 QEMU is a generic and open source machine emulator and virtualizer.
 
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 5522db7241..f95df10b3e 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -1,5 +1,6 @@
+---------------------
 Developer Information
-=====================
+---------------------
 
 This section of the manual documents various parts of the internals of QEMU.
 You only need to read it if you are interested in reading or
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index f9801a9c20..47b9ed82bb 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -1,5 +1,6 @@
+------------------------------------------------
 System Emulation Management and Interoperability
-================================================
+------------------------------------------------
 
 This section of the manual contains documents and specifications that
 are useful for making QEMU interoperate with other software.
diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index 65e9663916..ecc43896bb 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -1,5 +1,6 @@
+----------------------------------------------
 System Emulation Guest Hardware Specifications
-==============================================
+----------------------------------------------
 
 This section of the manual contains specifications of
 guest hardware that is specific to QEMU.
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 7b9276c05f..73bbedbc22 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -1,5 +1,6 @@
+----------------
 System Emulation
-================
+----------------
 
 This section of the manual is the overall guide for users using QEMU
 for full system emulation (as opposed to user-mode emulation).
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index ef6041a490..1edd5a8054 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -1,5 +1,6 @@
+-----
 Tools
-=====
+-----
 
 This section of the manual documents QEMU's "tools": its
 command line utilities and other standalone programs.
diff --git a/docs/user/index.rst b/docs/user/index.rst
index 9faa4badd7..2c4e29f3db 100644
--- a/docs/user/index.rst
+++ b/docs/user/index.rst
@@ -1,5 +1,6 @@
+-------------------
 User Mode Emulation
-===================
+-------------------
 
 This section of the manual is the overall guide for users using QEMU
 for user-mode emulation.  In this mode, QEMU can launch
-- 
2.31.1

[PATCH 3/5] docs/system: standardize docs/system man page sections to --- with overline

[Paolo Bonzini]

Man pages in docs/system use file inclusion heavily.  Use headings with
overlines in the main files, so that the same included file work well
from both manuals and man pages.

This style of heading is a bit more heavy-weight, so it is not used by
the other man pages in interop/ and tools/.  If in the future they
are changed to use include files, for example to avoid having sections
named "synopsis" or "description", they can switch to --- with overline
as well.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/system/qemu-block-drivers.rst | 3 +++
 docs/system/qemu-cpu-models.rst    | 9 ++++++---
 docs/system/qemu-manpage.rst       | 5 +++++
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/docs/system/qemu-block-drivers.rst b/docs/system/qemu-block-drivers.rst
index eb276481d6..c2c0114cec 100644
--- a/docs/system/qemu-block-drivers.rst
+++ b/docs/system/qemu-block-drivers.rst
@@ -4,16 +4,19 @@
 QEMU block drivers reference
 ============================
 
+--------
 Synopsis
 --------
 
 QEMU block driver reference manual
 
+-----------
 Description
 -----------
 
 .. include:: qemu-block-drivers.rst.inc
 
+--------
 See also
 --------
 
diff --git a/docs/system/qemu-cpu-models.rst b/docs/system/qemu-cpu-models.rst
index 8c51e2bf49..5cf6e46f8a 100644
--- a/docs/system/qemu-cpu-models.rst
+++ b/docs/system/qemu-cpu-models.rst
@@ -4,18 +4,21 @@
 QEMU / KVM CPU model configuration
 ==================================
 
+--------
 Synopsis
-''''''''
+--------
 
 QEMU CPU Modelling Infrastructure manual
 
+-----------
 Description
-'''''''''''
+-----------
 
 .. include:: cpu-models-x86.rst.inc
 .. include:: cpu-models-mips.rst.inc
 
+--------
 See also
-''''''''
+--------
 
 The HTML documentation of QEMU for more precise information and Linux user mode emulator invocation.
diff --git a/docs/system/qemu-manpage.rst b/docs/system/qemu-manpage.rst
index d6f44e265b..c47a412758 100644
--- a/docs/system/qemu-manpage.rst
+++ b/docs/system/qemu-manpage.rst
@@ -10,6 +10,7 @@
 QEMU User Documentation
 =======================
 
+--------
 Synopsis
 --------
 
@@ -17,11 +18,13 @@ Synopsis
 
    |qemu_system| [options] [disk_image]
 
+-----------
 Description
 -----------
 
 .. include:: target-i386-desc.rst.inc
 
+-------
 Options
 -------
 
@@ -34,11 +37,13 @@ not need a disk image.
 
 .. include:: mux-chardev.rst.inc
 
+-----
 Notes
 -----
 
 .. include:: device-url-syntax.rst.inc
 
+--------
 See also
 --------
 
-- 
2.31.1

[PATCH 4/5] docs/system: move x86 CPU configuration to a separate document

[Paolo Bonzini]

Currently, cpu-models-x86.rst.inc is included in target-i386.rst directly.
To make the toctree more homogeneous when adding more documentation,
include it through a first-class .rst file.

Together with the previous changes to the man page skeletons, this also
frees "===" for the headings, so that cpu-models-x86.rst.inc need not
assume anything about the headings used by target-i386.rst.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/system/cpu-models-x86.rst.inc | 4 ++--
 docs/system/i386/cpu.rst           | 1 +
 docs/system/target-i386.rst        | 8 +++++++-
 3 files changed, 10 insertions(+), 3 deletions(-)
 create mode 100644 docs/system/i386/cpu.rst

diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x86.rst.inc
index 9119f5dff5..6e8be7d79b 100644
--- a/docs/system/cpu-models-x86.rst.inc
+++ b/docs/system/cpu-models-x86.rst.inc
@@ -1,5 +1,5 @@
 Recommendations for KVM CPU model configuration on x86 hosts
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================================================
 
 The information that follows provides recommendations for configuring
 CPU models on x86 hosts. The goals are to maximise performance, while
@@ -368,7 +368,7 @@ featureset, which prevents guests having optimal performance.
 
 
 Syntax for configuring CPU models
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================================
 
 The examples below illustrate the approach to configuring the various
 CPU models / features in QEMU and libvirt.
diff --git a/docs/system/i386/cpu.rst b/docs/system/i386/cpu.rst
new file mode 100644
index 0000000000..738719da9a
--- /dev/null
+++ b/docs/system/i386/cpu.rst
@@ -0,0 +1 @@
+.. include:: ../cpu-models-x86.rst.inc
diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst
index 22ba5ce2c0..c9720a8cd1 100644
--- a/docs/system/target-i386.rst
+++ b/docs/system/target-i386.rst
@@ -19,7 +19,13 @@ Board-specific documentation
    i386/microvm
    i386/pc
 
-.. include:: cpu-models-x86.rst.inc
+Architectural features
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   i386/cpu
 
 .. _pcsys_005freq:
 
-- 
2.31.1

[PATCH 5/5] docs/system: move SGX documentation within the system docs

[Paolo Bonzini]

Convert to reStructuredText, and adopt the standard === --- ~~~ headings
suggested for example by Linux.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/{intel-sgx.txt => system/i386/sgx.rst} | 70 ++++++++++-----------
 docs/system/target-i386.rst                 |  1 +
 2 files changed, 35 insertions(+), 36 deletions(-)
 rename docs/{intel-sgx.txt => system/i386/sgx.rst} (83%)

diff --git a/docs/intel-sgx.txt b/docs/system/i386/sgx.rst
similarity index 83%
rename from docs/intel-sgx.txt
rename to docs/system/i386/sgx.rst
index f934d92f37..f103ae2a2f 100644
--- a/docs/intel-sgx.txt
+++ b/docs/system/i386/sgx.rst
@@ -1,9 +1,8 @@
-===============================
 Software Guard eXtensions (SGX)
 ===============================
 
 Overview
-========
+--------
 
 Intel Software Guard eXtensions (SGX) is a set of instructions and mechanisms
 for memory accesses in order to provide security accesses for sensitive
@@ -14,7 +13,7 @@ enclave memory area from any software not resident in the enclave are prevented,
 including those from privileged software.
 
 Virtual SGX
-===========
+-----------
 
 SGX feature is exposed to guest via SGX CPUID. Looking at SGX CPUID, we can
 report the same CPUID info to guest as on host for most of SGX CPUID. With
@@ -25,7 +24,7 @@ The guest's EPC base and size are determined by Qemu, and KVM needs Qemu to
 notify such info to it before it can initialize SGX for guest.
 
 Virtual EPC
------------
+~~~~~~~~~~~
 
 By default, Qemu does not assign EPC to a VM, i.e. fully enabling SGX in a VM
 requires explicit allocation of EPC to the VM. Similar to other specialized
@@ -42,7 +41,7 @@ that some kernels may not recognize all EPC sections, e.g. the Linux SGX driver
 is hardwired to support only 8 EPC sections.
 
 The following Qemu snippet creates two EPC sections, with 64M pre-allocated
-to the VM and an additional 28M mapped but not allocated:
+to the VM and an additional 28M mapped but not allocated::
 
  -object memory-backend-epc,id=mem1,size=64M,prealloc=on \
  -object memory-backend-epc,id=mem2,size=28M \
@@ -61,7 +60,7 @@ To simplify the implementation, EPC is always located above 4g in the guest
 physical address space.
 
 Migration
----------
+~~~~~~~~~
 
 Qemu/KVM doesn't prevent live migrating SGX VMs, although from hardware's
 perspective, SGX doesn't support live migration, since both EPC and the SGX
@@ -74,7 +73,7 @@ and when enclave fails to unseal sensitive information from outside, it can
 detect such error and sensitive information can be provisioned to it again.
 
 CPUID
------
+~~~~~
 
 Due to its myriad dependencies, SGX is currently not listed as supported
 in any of Qemu's built-in CPU configuration. To expose SGX (and SGX Launch
@@ -86,9 +85,9 @@ All SGX sub-features enumerated through CPUID, e.g. SGX2, MISCSELECT,
 ATTRIBUTES, etc... can be restricted via CPUID flags. Be aware that enforcing
 restriction of MISCSELECT, ATTRIBUTES and XFRM requires intercepting ECREATE,
 i.e. may marginally reduce SGX performance in the guest. All SGX sub-features
-controlled via -cpu are prefixed with "sgx", e.g.:
+controlled via -cpu are prefixed with "sgx", e.g.::
 
-$ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx
+  $ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx
   sgx
   sgx-debug
   sgx-encls-c
@@ -102,18 +101,16 @@ $ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx
   sgx2
   sgxlc
 
-The following Qemu snippet passes through the host CPU (and host physical
-address width) but restricts access to the provision and EINIT token keys:
+The following Qemu snippet passes through the host CPU but restricts access to
+the provision and EINIT token keys::
 
- -cpu host,host-phys-bits,-sgx-provisionkey,-sgx-tokenkey
-
-Note:
+ -cpu host,-sgx-provisionkey,-sgx-tokenkey
 
 SGX sub-features cannot be emulated, i.e. sub-features that are not present
 in hardware cannot be forced on via '-cpu'.
 
 Virtualize SGX Launch Control
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Qemu SGX support for Launch Control (LC) is passive, in the sense that it
 does not actively change the LC configuration.  Qemu SGX provides the user
@@ -127,41 +124,42 @@ for SGX guest by our design. If host is in locked mode, we can still allow
 creating VM with SGX.
 
 Feature Control
----------------
+~~~~~~~~~~~~~~~
 
 Qemu SGX updates the `etc/msr_feature_control` fw_cfg entry to set the SGX
 (bit 18) and SGX LC (bit 17) flags based on their respective CPUID support,
 i.e. existing guest firmware will automatically set SGX and SGX LC accordingly,
 assuming said firmware supports fw_cfg.msr_feature_control.
 
-Launch a guest
-==============
+Launching a guest
+-----------------
 
-To launch a SGX guest
-${QEMU} \
-   -cpu host,+sgx-provisionkey \
-   -object memory-backend-epc,id=mem1,size=64M,prealloc=on \
-   -object memory-backend-epc,id=mem2,size=28M \
+To launch a SGX guest:
+
+.. parsed-literal::
+
+  |qemu_system_x86| \\
+   -cpu host,+sgx-provisionkey \\
+   -object memory-backend-epc,id=mem1,size=64M,prealloc=on \\
+   -object memory-backend-epc,id=mem2,size=28M \\
    -M sgx-epc.0.memdev=mem1,sgx-epc.1.memdev=mem2
 
 Utilizing SGX in the guest requires a kernel/OS with SGX support.
+The support can be determined in guest by::
 
-The support can be determined in guest by:
-$ grep sgx /proc/cpuinfo
+  $ grep sgx /proc/cpuinfo
 
-Check the SGX epc info in the Guest:
-$ dmesg | grep sgx
-[    1.242142] sgx: EPC section 0x180000000-0x181bfffff
-[    1.242319] sgx: EPC section 0x181c00000-0x1837fffff
+and SGX epc info by::
+
+  $ dmesg | grep sgx
+  [    1.242142] sgx: EPC section 0x180000000-0x181bfffff
+  [    1.242319] sgx: EPC section 0x181c00000-0x1837fffff
 
 References
-==========
+----------
 
-SGX Homepage:
-https://software.intel.com/sgx
+- `SGX Homepage <https://software.intel.com/sgx>`__
 
-SGX SDK:
-https://github.com/intel/linux-sgx.git
+- `SGX SDK <https://github.com/intel/linux-sgx.git>`__
 
-SGX SPEC:
-Intel SDM Volume 3
+- SGX specification: Intel SDM Volume 3
diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst
index c9720a8cd1..6a86d63863 100644
--- a/docs/system/target-i386.rst
+++ b/docs/system/target-i386.rst
@@ -26,6 +26,7 @@ Architectural features
    :maxdepth: 1
 
    i386/cpu
+   i386/sgx
 
 .. _pcsys_005freq:
 
-- 
2.31.1

Re: [PATCH 1/5] docs: standardize book titles to === with overline

[Peter Maydell]

On Tue, 7 Sept 2021 at 16:56, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> Documents within a Sphinx manual are separate files and therefore can use
> different conventions for headings.  However, keeping some consistency is
> useful so that included files are easy to get right.
>
> This patch uses a standard heading format for book titles, so that it is
> obvious when a file sits at the top level toctree of a book or man page.
> The heading is irrelevant for man pages, but keep it consistent as well.
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

> --- a/docs/system/qemu-manpage.rst
> +++ b/docs/system/qemu-manpage.rst
> @@ -6,8 +6,9 @@
>     parts of the documentation that go in the manpage as well as the
>     HTML manual.
>
> -Title
> -=====
> +=======================
> +QEMU User Documentation
> +=======================

NB that this text is never rendered anywhere (unless you deliberately
edit URLs to go and look at
https://qemu-project.gitlab.io/qemu/system/qemu-manpage.html
which is only generated because AFAIK there is no way to tell
Sphinx "only render this file for this output builder type").

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH 2/5] docs: standardize directory index to --- with overline

[Peter Maydell]

On Tue, 7 Sept 2021 at 16:56, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> Use a standard heading format for the index.rst file in a directory.
> Using overlines makes it clear that individual documents can use e.g.
> === for chapter titles and --- for section titles, as suggested in the
> Linux kernel guidelines[1].  They could do it anyway, because documents
> included in a toctree are parsed separately and therefore are not tied
> to the same conventions for headings.  However, keeping some consistency is
> useful since sometimes files are included from multiple places.
>
> [1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH 3/5] docs/system: standardize docs/system man page sections to --- with overline

[Peter Maydell]

On Tue, 7 Sept 2021 at 16:56, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> Man pages in docs/system use file inclusion heavily.  Use headings with
> overlines in the main files, so that the same included file work well
> from both manuals and man pages.
>
> This style of heading is a bit more heavy-weight, so it is not used by
> the other man pages in interop/ and tools/.  If in the future they
> are changed to use include files, for example to avoid having sections
> named "synopsis" or "description", they can switch to --- with overline
> as well.

I did have a go a little while back at using include files consistently
for all our manpages (my motivation at the time was trying to add a
standard footer in the manpages mentioning the license). This runs aground
on a Sphinx issue -- Sphinx always builds all files, so if you have
 thingy-manpage.rst
 thingy-html-page.rst
 thingy-contents.rst.inc included from both the above
and thingy-contents defines a label, then Sphinx will complain about
"duplicate labels" in thingy-manpage and thingy-html-page, even though
no output ever wants to have both rst files. There's no way to tell
Sphinx "only build this for this builder" :-(

We get away with our current handling of qemu-manpage.rst only
because none of the files it includes happen to define labels, I think.

Anyway,
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH 4/5] docs/system: move x86 CPU configuration to a separate document

[Peter Maydell]

On Tue, 7 Sept 2021 at 16:56, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> Currently, cpu-models-x86.rst.inc is included in target-i386.rst directly.
> To make the toctree more homogeneous when adding more documentation,
> include it through a first-class .rst file.
>
> Together with the previous changes to the man page skeletons, this also
> frees "===" for the headings, so that cpu-models-x86.rst.inc need not
> assume anything about the headings used by target-i386.rst.
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  docs/system/cpu-models-x86.rst.inc | 4 ++--
>  docs/system/i386/cpu.rst           | 1 +
>  docs/system/target-i386.rst        | 8 +++++++-
>  3 files changed, 10 insertions(+), 3 deletions(-)
>  create mode 100644 docs/system/i386/cpu.rst
>
> diff --git a/docs/system/cpu-models-x86.rst.inc b/docs/system/cpu-models-x86.rst.inc
> index 9119f5dff5..6e8be7d79b 100644
> --- a/docs/system/cpu-models-x86.rst.inc
> +++ b/docs/system/cpu-models-x86.rst.inc
> @@ -1,5 +1,5 @@
>  Recommendations for KVM CPU model configuration on x86 hosts
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +============================================================
>
>  The information that follows provides recommendations for configuring
>  CPU models on x86 hosts. The goals are to maximise performance, while
> @@ -368,7 +368,7 @@ featureset, which prevents guests having optimal performance.
>
>
>  Syntax for configuring CPU models
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +=================================
>
>  The examples below illustrate the approach to configuring the various
>  CPU models / features in QEMU and libvirt.
> diff --git a/docs/system/i386/cpu.rst b/docs/system/i386/cpu.rst
> new file mode 100644
> index 0000000000..738719da9a
> --- /dev/null
> +++ b/docs/system/i386/cpu.rst
> @@ -0,0 +1 @@
> +.. include:: ../cpu-models-x86.rst.inc
> diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst
> index 22ba5ce2c0..c9720a8cd1 100644
> --- a/docs/system/target-i386.rst
> +++ b/docs/system/target-i386.rst
> @@ -19,7 +19,13 @@ Board-specific documentation
>     i386/microvm
>     i386/pc
>
> -.. include:: cpu-models-x86.rst.inc
> +Architectural features
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   i386/cpu

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

>  .. _pcsys_005freq:

This reminds me that we probably ought to clean up these weirdly
named labels that we inherited from the texinfo-to-rst conversion
unless we're actually using them.

thanks
-- PMM

Re: [PATCH 5/5] docs/system: move SGX documentation within the system docs

[Peter Maydell]

On Tue, 7 Sept 2021 at 16:56, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> Convert to reStructuredText, and adopt the standard === --- ~~~ headings
> suggested for example by Linux.
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  docs/{intel-sgx.txt => system/i386/sgx.rst} | 70 ++++++++++-----------
>  docs/system/target-i386.rst                 |  1 +
>  2 files changed, 35 insertions(+), 36 deletions(-)
>  rename docs/{intel-sgx.txt => system/i386/sgx.rst} (83%)

>  Due to its myriad dependencies, SGX is currently not listed as supported
>  in any of Qemu's built-in CPU configuration. To expose SGX (and SGX Launch
> @@ -86,9 +85,9 @@ All SGX sub-features enumerated through CPUID, e.g. SGX2, MISCSELECT,
>  ATTRIBUTES, etc... can be restricted via CPUID flags. Be aware that enforcing
>  restriction of MISCSELECT, ATTRIBUTES and XFRM requires intercepting ECREATE,
>  i.e. may marginally reduce SGX performance in the guest. All SGX sub-features
> -controlled via -cpu are prefixed with "sgx", e.g.:
> +controlled via -cpu are prefixed with "sgx", e.g.::
>
> -$ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx
> +  $ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx
>    sgx
>    sgx-debug
>    sgx-encls-c

This should probably use a ".. parsed-literal::" block so it can
use the "|qemu_system_x86|" macro.


> -The following Qemu snippet passes through the host CPU (and host physical

Not a conversion issue, but "QEMU" should be capitalized.

> -address width) but restricts access to the provision and EINIT token keys:
> +The following Qemu snippet passes through the host CPU but restricts access to
> +the provision and EINIT token keys::
>
> - -cpu host,host-phys-bits,-sgx-provisionkey,-sgx-tokenkey
> -
> -Note:
> + -cpu host,-sgx-provisionkey,-sgx-tokenkey
>
>  SGX sub-features cannot be emulated, i.e. sub-features that are not present
>  in hardware cannot be forced on via '-cpu'.

'something' isn't valid rST (or at least it's not rST that does anything
sensible for us); if you want monospace that's ''something''.
You should probably check for other uses of single-ticks in the file.

>
>  Virtualize SGX Launch Control
> ------------------------------
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
>  Qemu SGX support for Launch Control (LC) is passive, in the sense that it
>  does not actively change the LC configuration.  Qemu SGX provides the user
> @@ -127,41 +124,42 @@ for SGX guest by our design. If host is in locked mode, we can still allow
>  creating VM with SGX.
>
>  Feature Control
> ----------------
> +~~~~~~~~~~~~~~~
>
>  Qemu SGX updates the `etc/msr_feature_control` fw_cfg entry to set the SGX

Backticks? Should probably be '' ... '' .

>  (bit 18) and SGX LC (bit 17) flags based on their respective CPUID support,
>  i.e. existing guest firmware will automatically set SGX and SGX LC accordingly,
>  assuming said firmware supports fw_cfg.msr_feature_control.

Otherwise looks OK.

-- PMM