From 5747dff5f76398c6d9cd10c0db1e8e6f13cae2ad Mon Sep 17 00:00:00 2001 From: Peter Krempa Date: Mon, 21 Mar 2022 12:02:53 +0100 Subject: [PATCH] docs: drvqemu: Document overriding of device properties 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 Reviewed-by: Michal Privoznik --- 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 ```` tag allows to override +specific properties of devices instantiated by libvirt. + +The ```` sub-element groups overrides for a device identified via +the ``alias`` attribute. The alias corresponds to the ```` +property of a device. It's strongly recommended to use user-specified aliases +for devices with overriden properties. + +Sub element ```` 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 ```` 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: + +:: + + + testvm + + [...] + + + + + + + + + + + + + + Example domain XML config -------------------------