| Message ID | 20231207130623.360473-1-alex.bennee@linaro.org |
|---|---|
| State | Accepted |
| Commit | 06ecb6ac197d8e87f91579d803194647dc24cd65 |
| Headers | show |
| Series | [for,8.2] docs: clean-up the xenpvh documentation | expand |
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 > >
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 >> >>
Applied, thanks. Please update the changelog at https://wiki.qemu.org/ChangeLog/8.2 for any user-visible changes.
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.
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(-)