[PATCH 0/3] docs: drvqemu: Fixes for device property overriding docs
Peter Krempa (3): docs: drvqemu: Fix and improve docs about device override types docs: drvqemu: Give example how to query device properties for overriding docs: drvqemu: Remove inaccuate limitations statement docs/drvqemu.rst | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) -- 2.37.3
The 'number' override type didn't exist in the final version so change it to the corresponding 'signed' and 'unsigned'. Additionally clarify which override type is used for a corresponding qemu type and also that we use base 10 numbers so users will need to convert the numbers if needed. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.rst | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst index 7ee11e9deb..7bfb28ea9c 100644 --- a/docs/drvqemu.rst +++ b/docs/drvqemu.rst @@ -688,10 +688,36 @@ The individual properties are overridden by a ``<qemu:property>`` element. The ``name`` specifies the name of the property to override. In case when libvirt doesn't configure the property a property with the name is added to the commandline. The ``type`` attribute specifies a type of the argument used. The -type must correspond with the type that is expected by QEMU. Supported values -for the type attribute are: ``string``, ``number``, ``bool`` (allowed values for -``bool`` are ``true`` and ``false``) and ``remove``. The ``remove`` type is -special and instructs libvirt to remove the property without replacement. +type must correspond semantically (e.g use a numeric type when qemu expects a +number) with the type that is expected by QEMU. Supported values for the ``type`` +attribute are: + + ``string`` + Used to override ``qemu`` properties of ``str`` type as well as any + enumeration type (e.g. ``OnOffAuto`` in which case the value can be one of + ``on``, ``off``, or ``auto``). + + ``unsigned`` + Used to override numeric properties with an non-negative value. Note that + this can be used to also override signed values in qemu. + + Used for any numeric type of a ``qemu`` property such as ``uint32``, + ``int32``, ``size``, etc. + + The value is interpreted as a base 10 number, make sure to convert numbers + if needed. + + ``signed`` + Same semantics as ``unsigned`` above but used when a negative value is + needed. + + ``bool`` + Used to override ``qemu`` properties of ``bool`` type. Allowed values for + are ``true`` and ``false``. + + ``remove``. + The ``remove`` type is special and instructs libvirt to remove the property + without replacement. The overrides are applied only to initial device configuration passed to QEMU via the commandline. Later hotplug operations will not apply any modifications. -- 2.37.3
On a Monday in 2022, Peter Krempa wrote:
The 'number' override type didn't exist in the final version so change it to the corresponding 'signed' and 'unsigned'.
Additionally clarify which override type is used for a corresponding qemu type and also that we use base 10 numbers so users will need to
Every base is base 10. Jano
convert the numbers if needed.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.rst | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-)
Add an example of invoking qemu with '-device TYPE,?' to query properties of a given type. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst index 7bfb28ea9c..b31b1785db 100644 --- a/docs/drvqemu.rst +++ b/docs/drvqemu.rst @@ -722,6 +722,11 @@ attribute are: The overrides are applied only to initial device configuration passed to QEMU via the commandline. Later hotplug operations will not apply any modifications. +The properties of a device can be queried directly in qemu (e.g. for the +``virtio-blk-pci`` device) via :: + + # qemu-system-x86_64 -device virtio-blk-pci,? + Configuring override for a device alias which is not used or attempting to remove a device property which is not formatted by libvirt will cause failure to startup the VM. -- 2.37.3
We don't refuse override definitions for device which doesn't exist and the same way don't care about 'remove' being used on a property which is not actually formatted by libvirt. Drop the paragraph claiming the contrary. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drvqemu.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst index b31b1785db..bbd51066a1 100644 --- a/docs/drvqemu.rst +++ b/docs/drvqemu.rst @@ -727,10 +727,6 @@ The properties of a device can be queried directly in qemu (e.g. for the # qemu-system-x86_64 -device virtio-blk-pci,? -Configuring override for a device alias which is not used or attempting to -remove a device property which is not formatted by libvirt will cause failure -to startup the VM. - *Note:* The libvirt project doesn't guarantee any form of compatibility and stability of devices with overridden properties. The domain is tainted when such configuration is used. -- 2.37.3
On a Monday in 2022, Peter Krempa wrote:
Peter Krempa (3): docs: drvqemu: Fix and improve docs about device override types docs: drvqemu: Give example how to query device properties for overriding docs: drvqemu: Remove inaccuate limitations statement
docs/drvqemu.rst | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (2)
-
Ján Tomko -
Peter Krempa