[PATCH v2 1/6] docs: drvqemu: Document overriding of device properties

[Peter Krempa]

Upcoming patches will add possibility to override configuration of a
device with custom properties as a more versatile replacement to using
QEMU's '-set' parameter, which doesn't work when we use JSON to
instantiate devices.

Describe the XML used for the override as well as expectations of
upstream support in case something breaks.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/drvqemu.rst | 57 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst
index 9d7dd2656b..afc499ad50 100644
--- a/docs/drvqemu.rst
+++ b/docs/drvqemu.rst
@@ -580,6 +580,63 @@ reconfigure libvirtd.

 *DO NOT* use in production.

+Overriding properties of QEMU devices
+-------------------------------------
+
+For development or testing the ``<qemu:override>`` tag allows to override
+specific properties of devices instantiated by libvirt.
+
+The ``<qemu:device>`` sub-element groups overrides for a device identified via
+the ``alias`` attribute. The alias corresponds to the ``<alias name=''>``
+property of a device. It's strongly recommended to use user-specified aliases
+for devices with overriden properties.
+
+Sub element ``<qemu:frontend>`` encapsulates all overrides of properties for the
+device frontend and overrides what libvirt formats via ``-device``.
+:since:`Since 8.2.0`.
+
+The individual properties are overriden 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.
+
+The overrides are applied only to initial device configuration passed to QEMU
+via the commandline. Later hotplug operations will not apply any modifications.
+
+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 overriden properties. The domain is tainted when
+such configuration is used.
+
+Example:
+
+::
+
+   <domain type='kvm' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
+     <name>testvm</name>
+
+      [...]
+
+     <qemu:override>
+       <qemu:device alias='ua-devalias'>
+         <qemu:frontend>
+           <qemu:property name='propname1' type='string' value='test'/>
+           <qemu:property name='propname2' type='unsigned' value='123'/>
+           <qemu:property name='propname2' type='signed' value='-123'/>
+           <qemu:property name='propname3' type='bool' value='false'/>
+           <qemu:property name='propname4' type='remove'/>
+         </qemu:frontend>
+       </qemu:device>
+     </qemu:override>
+   </domain>
+
 Example domain XML config
 -------------------------

-- 
2.35.1