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