[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