[PATCH 0/4] API docs fixes
Peter Krempa (4): libvirt-domain: Use consistent flag names for APIs declaring use of 'virDomainDeviceModifyFlags' libvirt-qemu: Add reference to QMP protocol documentation libvirt-qemu: Document that 'virDomainQemuAttach' no longer works libvirt-qemu: Add reference to QEMU agent protocol syntax src/libvirt-domain.c | 24 ++++++++++++------------ src/libvirt-qemu.c | 17 ++++++++++++++++- 2 files changed, 28 insertions(+), 13 deletions(-) -- 2.55.0
From: Peter Krempa <pkrempa@redhat.com> APIs which declared that they use 'virDomainDeviceModifyFlags' enum as flags used 'virDomainModificationImpact' flag names instead. Fix the flag names so that it's consistent. Closes: https://gitlab.com/libvirt/libvirt/-/work_items/897 Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain.c | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 4cf1d996b8..60d84b24a1 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -8989,11 +8989,11 @@ virDomainAttachDevice(virDomainPtr domain, const char *xml) * @flags: bitwise-OR of virDomainDeviceModifyFlags * * Attach a virtual device to a domain, using the flags parameter - * to control how the device is attached. VIR_DOMAIN_AFFECT_CURRENT + * to control how the device is attached. VIR_DOMAIN_DEVICE_MODIFY_CURRENT * specifies that the device allocation is made based on current domain - * state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be + * state. VIR_DOMAIN_DEVICE_MODIFY_LIVE specifies that the device shall be * allocated to the active domain instance only and is not added to the - * persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG + * persisted domain configuration. VIR_DOMAIN_DEVICE_MODIFY_CONFIG * specifies that the device shall be allocated to the persisted domain * configuration only. Note that the target hypervisor must return an * error if unable to satisfy flags. E.g. the hypervisor driver will @@ -9050,7 +9050,7 @@ virDomainAttachDeviceFlags(virDomainPtr domain, * @xml: pointer to XML description of one device * * This is an equivalent of virDomainDetachDeviceFlags() when called with - * @flags parameter set to VIR_DOMAIN_AFFECT_LIVE. + * @flags parameter set to VIR_DOMAIN_DEVICE_MODIFY_LIVE. * * See virDomainDetachDeviceFlags() for more details. * @@ -9096,11 +9096,11 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml) * @flags: bitwise-OR of virDomainDeviceModifyFlags * * Detach a virtual device from a domain, using the flags parameter - * to control how the device is detached. VIR_DOMAIN_AFFECT_CURRENT + * to control how the device is detached. VIR_DOMAIN_DEVICE_MODIFY_CURRENT * specifies that the device allocation is removed based on current domain - * state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be + * state. VIR_DOMAIN_DEVICE_MODIFY_LIVE specifies that the device shall be * deallocated from the active domain instance only and is not from the - * persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG + * persisted domain configuration. VIR_DOMAIN_DEVICE_MODIFY_CONFIG * specifies that the device shall be deallocated from the persisted domain * configuration only. Note that the target hypervisor must return an * error if unable to satisfy flags. E.g. the hypervisor driver will @@ -9181,11 +9181,11 @@ virDomainDetachDeviceFlags(virDomainPtr domain, * @flags: bitwise-OR of virDomainDeviceModifyFlags * * Change a virtual device on a domain, using the flags parameter - * to control how the device is changed. VIR_DOMAIN_AFFECT_CURRENT + * to control how the device is changed. VIR_DOMAIN_DEVICE_MODIFY_CURRENT * specifies that the device change is made based on current domain - * state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be + * state. VIR_DOMAIN_DEVICE_MODIFY_LIVE specifies that the device shall be * changed on the active domain instance only and is not added to the - * persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG + * persisted domain configuration. VIR_DOMAIN_DEVICE_MODIFY_CONFIG * specifies that the device shall be changed on the persisted domain * configuration only. Note that the target hypervisor must return an * error if unable to satisfy flags. E.g. the hypervisor driver will @@ -9248,8 +9248,8 @@ virDomainUpdateDeviceFlags(virDomainPtr domain, * * Detach a virtual device from a domain, using the alias to * specify the device. The value of @flags should be either - * VIR_DOMAIN_AFFECT_CURRENT, or a bitwise-or of values from - * VIR_DOMAIN_AFFECT_LIVE and VIR_DOMAIN_AFFECT_CURRENT, although + * VIR_DOMAIN_DEVICE_MODIFY_CURRENT, or a bitwise-or of values from + * VIR_DOMAIN_DEVICE_MODIFY_LIVE and VIR_DOMAIN_DEVICE_MODIFY_CONFIG, although * hypervisors vary in which flags are supported. * * In contrast to virDomainDetachDeviceFlags() this API is -- 2.55.0
From: Peter Krempa <pkrempa@redhat.com> Add link to the qemu QMP protocol reference. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-qemu.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c index 2898b71983..d6c68083f2 100644 --- a/src/libvirt-qemu.c +++ b/src/libvirt-qemu.c @@ -51,6 +51,9 @@ VIR_LOG_INIT("libvirt-qemu"); * libvirt is possible as a means to test new QEMU features before * they have support in libvirt, but no guarantees are made to safety * + * QEMU expects the command @cmd to be in the QMP format which is documented at + * https://www.qemu.org/docs/master/interop/qmp-spec.html + * * If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is * considered to be a human monitor command and libvirt will automatically * convert it into QMP if needed. In that case the @result will also @@ -123,6 +126,9 @@ virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd, * libvirt is possible as a means to test new QEMU features before * they have support in libvirt, but no guarantees are made to safety * + * QEMU expects the command @cmd to be in the QMP format which is documented at + * https://www.qemu.org/docs/master/interop/qmp-spec.html + * * If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is * considered to be a human monitor command and libvirt will automatically * convert it into QMP if needed. In that case the @result will also -- 2.55.0
From: Peter Krempa <pkrempa@redhat.com> The qemu driver support was removed in libvirt 5.5.0 but the top level documentation for the API didn't mention that yet. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-qemu.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c index d6c68083f2..c4cbc49ef7 100644 --- a/src/libvirt-qemu.c +++ b/src/libvirt-qemu.c @@ -202,6 +202,9 @@ virDomainQemuMonitorCommandWithFiles(virDomainPtr domain, * @pid_value: the UNIX process ID of the external QEMU process * @flags: optional flags, currently unused * + * This API is not functional since libvirt 5.5.0 as support in the QEMU driver + * was removed. + * * This API is QEMU specific, so it will only work with hypervisor * connections to the QEMU driver. * -- 2.55.0
From: Peter Krempa <pkrempa@redhat.com> Add a reference to the expected format of commands used with 'virDomainQemuAgentCommand'. Closes: https://gitlab.com/libvirt/libvirt/-/work_items/891 Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-qemu.c | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c index c4cbc49ef7..3df33609e9 100644 --- a/src/libvirt-qemu.c +++ b/src/libvirt-qemu.c @@ -278,6 +278,11 @@ virDomainQemuAttach(virConnectPtr conn, * Execute an arbitrary Guest Agent command. * * Issue @cmd to the guest agent running in @domain. + * + * The QEMU guest agent expects the command @cmd to be in the QEMU Guest Agent + * Protocol format documented at: + * https://www.qemu.org/docs/master/interop/qemu-ga-ref.html + * * @timeout must be -2, -1, 0 or positive. * VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK(-2): meaning to block forever waiting for * a result. @@ -285,7 +290,8 @@ virDomainQemuAttach(virConnectPtr conn, * VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT(0): does not wait. * positive value: wait for @timeout seconds * - * Returns strings if success, NULL in failure. + * Returns string containing the verbatim reply from the guest agent on + * success, NULL on failure. * * Since: 0.10.0 */ -- 2.55.0
On a Tuesday in 2026, Peter Krempa via Devel wrote:
Peter Krempa (4): libvirt-domain: Use consistent flag names for APIs declaring use of 'virDomainDeviceModifyFlags' libvirt-qemu: Add reference to QMP protocol documentation libvirt-qemu: Document that 'virDomainQemuAttach' no longer works libvirt-qemu: Add reference to QEMU agent protocol syntax
src/libvirt-domain.c | 24 ++++++++++++------------ src/libvirt-qemu.c | 17 ++++++++++++++++- 2 files changed, 28 insertions(+), 13 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (2)
-
Ján Tomko -
Peter Krempa