docs: clean-up the xenpvh documentation

I noticed the code blocks where not rendering properly so thought I'd
better fix things up. So:

  - Use better title for the machine type
  - Explain why Xen is a little different
  - Add a proper anchor to the tpm-device link
  - add newline so code block properly renders
  - add some indentation to make continuation clearer

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-ID: <20231207130623.360473-1-alex.bennee@linaro.org>

diff --git a/docs/specs/tpm.rst b/docs/specs/tpm.rst
index efe124a14867444607cc94b08819cb7a04138aa6..c96776a369d225666a774c2785324ca289af58f4 100644 (file)
--- a/docs/specs/tpm.rst
+++ b/docs/specs/tpm.rst
@@ -1,3 +1,5 @@
+.. _tpm-device:
+
 ===============
 QEMU TPM Device
 ===============

diff --git a/docs/system/arm/xenpvh.rst b/docs/system/arm/xenpvh.rst
index e1655c7ab87b896711b99565ce2b2cbfc60a0377..430ac2c02e7c07c8203d2f0eda739835163a8d49 100644 (file)
--- a/docs/system/arm/xenpvh.rst
+++ b/docs/system/arm/xenpvh.rst
@@ -1,34 +1,39 @@
-XENPVH (``xenpvh``)
+Xen Device Emulation Backend (``xenpvh``)
 =========================================
-This machine creates a IOREQ server to register/connect with Xen Hypervisor.
 
-When TPM is enabled, this machine also creates a tpm-tis-device at a user input
-tpm base address, adds a TPM emulator and connects to a swtpm application
-running on host machine via chardev socket. This enables xenpvh to support TPM
-functionalities for a guest domain.
+This machine is a little unusual compared to others as QEMU just acts
+as an IOREQ server to register/connect with Xen Hypervisor. Control of
+the VMs themselves is left to the Xen tooling.
 
-More information about TPM use and installing swtpm linux application can be
-found at: docs/specs/tpm.rst.
+When TPM is enabled, this machine also creates a tpm-tis-device at a
+user input tpm base address, adds a TPM emulator and connects to a
+swtpm application running on host machine via chardev socket. This
+enables xenpvh to support TPM functionalities for a guest domain.
+
+More information about TPM use and installing swtpm linux application
+can be found in the :ref:`tpm-device` section.
 
 Example for starting swtpm on host machine:
+
 .. code-block:: console
 
     mkdir /tmp/vtpm2
     swtpm socket --tpmstate dir=/tmp/vtpm2 \
-    --ctrl type=unixio,path=/tmp/vtpm2/swtpm-sock &
+      --ctrl type=unixio,path=/tmp/vtpm2/swtpm-sock &
 
 Sample QEMU xenpvh commands for running and connecting with Xen:
+
 .. code-block:: console
 
     qemu-system-aarch64 -xen-domid 1 \
-    -chardev socket,id=libxl-cmd,path=qmp-libxl-1,server=on,wait=off \
-    -mon chardev=libxl-cmd,mode=control \
-    -chardev socket,id=libxenstat-cmd,path=qmp-libxenstat-1,server=on,wait=off \
-    -mon chardev=libxenstat-cmd,mode=control \
-    -xen-attach -name guest0 -vnc none -display none -nographic \
-    -machine xenpvh -m 1301 \
-    -chardev socket,id=chrtpm,path=tmp/vtpm2/swtpm-sock \
-    -tpmdev emulator,id=tpm0,chardev=chrtpm -machine tpm-base-addr=0x0C000000
+      -chardev socket,id=libxl-cmd,path=qmp-libxl-1,server=on,wait=off \
+      -mon chardev=libxl-cmd,mode=control \
+      -chardev socket,id=libxenstat-cmd,path=qmp-libxenstat-1,server=on,wait=off \
+      -mon chardev=libxenstat-cmd,mode=control \
+      -xen-attach -name guest0 -vnc none -display none -nographic \
+      -machine xenpvh -m 1301 \
+      -chardev socket,id=chrtpm,path=tmp/vtpm2/swtpm-sock \
+      -tpmdev emulator,id=tpm0,chardev=chrtpm -machine tpm-base-addr=0x0C000000
 
 In above QEMU command, last two lines are for connecting xenpvh QEMU to swtpm
 via chardev socket.