[PATCH for 8.2] docs: clean-up the xenpvh documentation

[PATCH for 8.2] docs: clean-up the xenpvh documentation

[Alex Bennée]

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>
---
 docs/specs/tpm.rst         |  2 ++
 docs/system/arm/xenpvh.rst | 39 +++++++++++++++++++++-----------------
 2 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/docs/specs/tpm.rst b/docs/specs/tpm.rst
index efe124a148..c96776a369 100644
--- 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 e1655c7ab8..430ac2c02e 100644
--- 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.
-- 
2.39.2

Re: [PATCH for 8.2] docs: clean-up the xenpvh documentation

[Stefan Hajnoczi]

On Thu, 7 Dec 2023 at 08:07, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> 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>
> ---
>  docs/specs/tpm.rst         |  2 ++
>  docs/system/arm/xenpvh.rst | 39 +++++++++++++++++++++-----------------
>  2 files changed, 24 insertions(+), 17 deletions(-)

QEMU 8.2.0-rc3 has already been tagged. At this stage only critical
bugs (crashes during startup, security issues, serious memory leaks,
etc).

This patch looks like a nice documentation fix but it has a limited
scope and I don't think it warrants rolling an -rc4 tag next week.

Do you agree with deferring this patch until after the 8.2 release?

Stefan

>
> diff --git a/docs/specs/tpm.rst b/docs/specs/tpm.rst
> index efe124a148..c96776a369 100644
> --- 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 e1655c7ab8..430ac2c02e 100644
> --- 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.
> --
> 2.39.2
>
>

Re: [PATCH for 8.2] docs: clean-up the xenpvh documentation

[Alex Bennée]

Stefan Hajnoczi <stefanha@gmail.com> writes:

> On Thu, 7 Dec 2023 at 08:07, Alex Bennée <alex.bennee@linaro.org> wrote:
>>
>> 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>
>> ---
>>  docs/specs/tpm.rst         |  2 ++
>>  docs/system/arm/xenpvh.rst | 39 +++++++++++++++++++++-----------------
>>  2 files changed, 24 insertions(+), 17 deletions(-)
>
> QEMU 8.2.0-rc3 has already been tagged. At this stage only critical
> bugs (crashes during startup, security issues, serious memory leaks,
> etc).
>
> This patch looks like a nice documentation fix but it has a limited
> scope and I don't think it warrants rolling an -rc4 tag next week.
>
> Do you agree with deferring this patch until after the 8.2 release?

Sure - but if you do end up rolling an rc4 it would be a low risk fix.

>
> Stefan
>
>>
>> diff --git a/docs/specs/tpm.rst b/docs/specs/tpm.rst
>> index efe124a148..c96776a369 100644
>> --- 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 e1655c7ab8..430ac2c02e 100644
>> --- 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.
>> --
>> 2.39.2
>>
>>

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [PATCH for 8.2] docs: clean-up the xenpvh documentation

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 115 bytes --]

Applied, thanks.

Please update the changelog at https://wiki.qemu.org/ChangeLog/8.2 for any user-visible changes.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]