[libvirt] [PATCH 0/5] docs: drvqemu: Clean up documentation regarding XML<->native conversion
This is a follow up to the series for dropping qemu command line parsing. This fixes the qemu driver documentation. Note that the patches removing the outdated examples can be skipped if we wish to keep them around. I did not see a point in doing so though. Peter Krempa (5): docs: drvqemu: Clarify caveats of domxml-to-native docs: drvqemu: Remove outdated example of virsh domxml-from-native docs: css: Add style for <span class='deprecated'> ... docs: drvqemu: Add note about deprecation of domxml-from-native docs: drvqemu: Drop old example for domxml-to-native docs/drvqemu.html.in | 77 +++++--------------------------------------- docs/libvirt.css | 6 ++++ 2 files changed, 14 insertions(+), 69 deletions(-) -- 2.21.0
Explicitly state that the conversion nowadays produces results which aren't really usable manually as it requires all the stuff which is usually prepared by libvirtd. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.html.in | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in index 0218b5a7a9..65712cfb47 100644 --- a/docs/drvqemu.html.in +++ b/docs/drvqemu.html.in @@ -478,7 +478,10 @@ $ virsh domxml-from-native qemu-argv demo.args <p> The <code>virsh domxml-to-native</code> provides a way to convert a guest description using libvirt Domain XML, into a set of QEMU args - that can be run manually. + that can be run manually. Note that currently the command line formatted + by libvirt is no longer suited for manually running qemu as the + configuration expects various resources and open file descriptors passed + to the process which are usually prepared by libvirtd. </p> <pre>$ cat > demo.xml <<EOF -- 2.21.0
The current version will definitely not provide such a neat commandline. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.html.in | 34 ---------------------------------- 1 file changed, 34 deletions(-) diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in index 65712cfb47..cf3af03126 100644 --- a/docs/drvqemu.html.in +++ b/docs/drvqemu.html.in @@ -484,40 +484,6 @@ $ virsh domxml-from-native qemu-argv demo.args to the process which are usually prepared by libvirtd. </p> - <pre>$ cat > demo.xml <<EOF -<domain type='qemu'> - <name>QEMUGuest1</name> - <uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid> - <memory>219200</memory> - <currentMemory>219200</currentMemory> - <vcpu>1</vcpu> - <os> - <type arch='i686' machine='pc'>hvm</type> - <boot dev='hd'/> - </os> - <clock offset='utc'/> - <on_poweroff>destroy</on_poweroff> - <on_reboot>restart</on_reboot> - <on_crash>destroy</on_crash> - <devices> - <emulator>/usr/bin/qemu</emulator> - <disk type='block' device='disk'> - <source dev='/dev/HostVG/QEMUGuest1'/> - <target dev='hda' bus='ide'/> - </disk> - </devices> -</domain> -EOF - -$ virsh domxml-to-native qemu-argv demo.xml - LC_ALL=C PATH=/usr/bin:/bin HOME=/home/test \ - USER=test LOGNAME=test /usr/bin/qemu -S -M pc \ - -no-kqemu -m 214 -smp 1 -name QEMUGuest1 -nographic \ - -monitor pty -no-acpi -boot c -drive \ - file=/dev/HostVG/QEMUGuest1,if=ide,index=0 -net none \ - -serial none -parallel none -usb -</pre> - <h2><a id="qemucommand">Pass-through of arbitrary qemu commands</a></h2> -- 2.21.0
Allow marking of the deprecation of features similarly how we mark introduction of features. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/libvirt.css | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/libvirt.css b/docs/libvirt.css index 8238f0275c..4c7afc4042 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -274,6 +274,12 @@ span.since { font-weight: bold; } +span.deprecated { + color: darkred; + font-style: italic; + font-weight: bold; +} + img.diagram { background: rgb(230,230,230); border: 2px dotted rgb(178,178,178); -- 2.21.0
Add a warning that the operation will no longer work. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.html.in | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in index cf3af03126..601f918091 100644 --- a/docs/drvqemu.html.in +++ b/docs/drvqemu.html.in @@ -426,6 +426,10 @@ mount -t cgroup none /dev/cgroup -o devices <h3><a id="xmlimport">Converting from QEMU args to domain XML</a></h3> + <p> + <b>Note:</b> this operation is <span class="deprecated"> deprecated as of + 5.5.0</span> and will return an error. + </p> <p> The <code>virsh domxml-from-native</code> provides a way to convert an existing set of QEMU args into a guest description -- 2.21.0
The example is very outdated and we dropped the support for it anyways. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.html.in | 34 ---------------------------------- 1 file changed, 34 deletions(-) diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in index 601f918091..cf36f6cc7b 100644 --- a/docs/drvqemu.html.in +++ b/docs/drvqemu.html.in @@ -443,40 +443,6 @@ mount -t cgroup none /dev/cgroup -o devices examples) or by manually crafting XML to pass to virsh. </p> - <pre>$ cat > demo.args <<EOF -LC_ALL=C PATH=/bin HOME=/home/test USER=test \ -LOGNAME=test /usr/bin/qemu -S -M pc -m 214 -smp 1 \ --nographic -monitor pty -no-acpi -boot c -hda \ -/dev/HostVG/QEMUGuest1 -net none -serial none \ --parallel none -usb -EOF - -$ virsh domxml-from-native qemu-argv demo.args -<domain type='qemu'> - <uuid>00000000-0000-0000-0000-000000000000</uuid> - <memory>219136</memory> - <currentMemory>219136</currentMemory> - <vcpu>1</vcpu> - <os> - <type arch='i686' machine='pc'>hvm</type> - <boot dev='hd'/> - </os> - <clock offset='utc'/> - <on_poweroff>destroy</on_poweroff> - <on_reboot>restart</on_reboot> - <on_crash>destroy</on_crash> - <devices> - <emulator>/usr/bin/qemu</emulator> - <disk type='block' device='disk'> - <source dev='/dev/HostVG/QEMUGuest1'/> - <target dev='hda' bus='ide'/> - </disk> - </devices> -</domain> -</pre> - - <p>NB, don't include the literal \ in the args, put everything on one line</p> - <h3><a id="xmlexport">Converting from domain XML to QEMU args</a></h3> <p> -- 2.21.0
On Tue, Jun 18, 2019 at 01:38:05PM +0200, Peter Krempa wrote:
This is a follow up to the series for dropping qemu command line parsing.
This fixes the qemu driver documentation.
Note that the patches removing the outdated examples can be skipped if we wish to keep them around. I did not see a point in doing so though.
Peter Krempa (5): docs: drvqemu: Clarify caveats of domxml-to-native docs: drvqemu: Remove outdated example of virsh domxml-from-native docs: css: Add style for <span class='deprecated'> ... docs: drvqemu: Add note about deprecation of domxml-from-native docs: drvqemu: Drop old example for domxml-to-native
docs/drvqemu.html.in | 77 +++++--------------------------------------- docs/libvirt.css | 6 ++++ 2 files changed, 14 insertions(+), 69 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Maybe someone will suggest a better wording for 1/5 in the meantime Jano
participants (2)
-
Ján Tomko -
Peter Krempa