[PATCH 0/2] docs: improve isa-debugcon example

The feature from libvirt 8.1 that the OVMF debug log can be captured with native domain XML elements is super useful, but the example snippet in the documentation is more difficult to use than necessary. Improve it. Cc: "Daniel P. Berrangé" <berrange@redhat.com> Cc: Andrea Bolognani <abologna@redhat.com> Thanks! Laszlo Laszlo Ersek (2): docs: fix typo in isa-debugcon example docs: make isa-debugcon example more useful / directly applicable docs/formatdomain.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) base-commit: 5ee27c37e6d0d081714d1e1d25a0a4e472665120

The <serial> opening tag is paired with the </console> closing tag; that's a mismatch. The question is then whether to modify the former to <console>, or the latter to </serial>. Per section "Relationship between serial ports and consoles", <serial> is used for emulated (not paravirt) consoles, and it's the type that's suitable for early debug output (such as from firmware). Thus, change </console> to </serial>. Cc: "Daniel P. Berrangé" <berrange@redhat.com> Cc: Andrea Bolognani <abologna@redhat.com> Fixes: 654968381df0256c047d2ecd4542ccc90dc57ad0 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- docs/formatdomain.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 1f52f58d37e1..6b8b60804e62 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -6634,7 +6634,7 @@ Serial port <serial type='pty'> <target type='isa-debug'/> <address type='isa' iobase='0x402'/> - </console> + </serial> </devices> ...

On Thu, May 18, 2023 at 02:59:38PM +0200, Laszlo Ersek wrote:
The <serial> opening tag is paired with the </console> closing tag; that's a mismatch. The question is then whether to modify the former to <console>, or the latter to </serial>.
Per section "Relationship between serial ports and consoles", <serial> is used for emulated (not paravirt) consoles, and it's the type that's suitable for early debug output (such as from firmware). Thus, change </console> to </serial>.
Cc: "Daniel P. Berrangé" <berrange@redhat.com> Cc: Andrea Bolognani <abologna@redhat.com> Fixes: 654968381df0256c047d2ecd4542ccc90dc57ad0 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- docs/formatdomain.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Oops O:-) Reviewed-by: Andrea Bolognani <abologna@redhat.com> -- Andrea Bolognani / Red Hat / Virtualization

The type='pty' attribute in the <serial> element causes a Pseudo TTY to be allocated on the host side via "/dev/ptmx", which is meant to be interacted with via "virsh console" or similar. That's not how a firmware log is typically viewed or saved. Replace type='pty' with type='file', and also provide an example <source> element (with the pathname of the logfile), similarly to how the <serial> example just above provides a <source> element too. Cc: "Daniel P. Berrangé" <berrange@redhat.com> Cc: Andrea Bolognani <abologna@redhat.com> Updates: 654968381df0256c047d2ecd4542ccc90dc57ad0 Signed-off-by: Laszlo Ersek <lersek@redhat.com> --- Notes: context:-U6 docs/formatdomain.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 6b8b60804e62..b46eefb0f675 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -6628,15 +6628,16 @@ Serial port <!-- Serial port --> <serial type='pty'> <source path='/dev/pts/3'/> <target port='0'/> </serial> <!-- Debug port for SeaBIOS / EDK II --> - <serial type='pty'> + <serial type='file'> <target type='isa-debug'/> <address type='isa' iobase='0x402'/> + <source path='/tmp/DOMAIN-ovmf.log'/> </serial> </devices> ... ::

On Thu, May 18, 2023 at 02:59:39PM +0200, Laszlo Ersek wrote:
The type='pty' attribute in the <serial> element causes a Pseudo TTY to be allocated on the host side via "/dev/ptmx", which is meant to be interacted with via "virsh console" or similar.
That's not how a firmware log is typically viewed or saved. Replace type='pty' with type='file', and also provide an example <source> element (with the pathname of the logfile), similarly to how the <serial> example just above provides a <source> element too.
Cc: "Daniel P. Berrangé" <berrange@redhat.com> Cc: Andrea Bolognani <abologna@redhat.com> Updates: 654968381df0256c047d2ecd4542ccc90dc57ad0 Signed-off-by: Laszlo Ersek <lersek@redhat.com> ---
Notes: context:-U6
docs/formatdomain.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
I see you've already pushed the patches but, just for completeness' sake: Reviewed-by: Andrea Bolognani <abologna@redhat.com> -- Andrea Bolognani / Red Hat / Virtualization

On 5/18/23 16:34, Andrea Bolognani wrote:
On Thu, May 18, 2023 at 02:59:39PM +0200, Laszlo Ersek wrote:
The type='pty' attribute in the <serial> element causes a Pseudo TTY to be allocated on the host side via "/dev/ptmx", which is meant to be interacted with via "virsh console" or similar.
That's not how a firmware log is typically viewed or saved. Replace type='pty' with type='file', and also provide an example <source> element (with the pathname of the logfile), similarly to how the <serial> example just above provides a <source> element too.
Cc: "Daniel P. Berrangé" <berrange@redhat.com> Cc: Andrea Bolognani <abologna@redhat.com> Updates: 654968381df0256c047d2ecd4542ccc90dc57ad0 Signed-off-by: Laszlo Ersek <lersek@redhat.com> ---
Notes: context:-U6
docs/formatdomain.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
I see you've already pushed the patches
I for sure have not, I don't have the right (that I know of)! Hm... we have Jano to blame ^W^W to thank to, for the push :)
but, just for completeness' sake:
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Thank you both! Laszlo

On a Thursday in 2023, Laszlo Ersek wrote:
The feature from libvirt 8.1 that the OVMF debug log can be captured with native domain XML elements is super useful, but the example snippet in the documentation is more difficult to use than necessary. Improve it.
Cc: "Daniel P. Berrangé" <berrange@redhat.com> Cc: Andrea Bolognani <abologna@redhat.com>
Thanks! Laszlo
Laszlo Ersek (2): docs: fix typo in isa-debugcon example docs: make isa-debugcon example more useful / directly applicable
docs/formatdomain.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (3)
-
Andrea Bolognani
-
Ján Tomko
-
Laszlo Ersek