On 2/19/19 1:33 PM, John Ferlan wrote:
On 2/14/19 4:29 PM, Eric Blake wrote:
Commit 28f8dfdc (1.0.0) added a flag to virDomainGetXMLDesc, but failed to document its effects.
Signed-off-by: Eric Blake <eblake@redhat.com> --- src/libvirt-domain.c | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 54ca18f249..6158382d07 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -2559,7 +2559,13 @@ virDomainGetControlInfo(virDomainPtr domain, * currently running domain. If @flags contains * VIR_DOMAIN_XML_UPDATE_CPU, then the portion of the domain XML * describing CPU capabilities is modified to match actual - * capabilities of the host. + * capabilities of the host. If @flags contains VIR_DOMAIN_XML_MIGRATABLE, + * the XML is altered to trim redundant information that might interfere + * with migration to an older version of libvirt, as well as expose additional + * information internal to libvirt; this flag is rejected on read-only + * connections, and the resulting XML might not validate against the schema, + * but it can serve as a starting point for custom XML in calls such as + * virDomainMigrate2().
You could just use the same attribution from the referenced commit message, e.g. "virDomainMigrate{,ToURI}2 or virDomainSaveFlags."
I'm not insistent, just following back links. There could be other examples by now too I suppose.
After looking at this one more, I'm going to submit a v3 on this patch with wording more like: + * If @flags contains VIR_DOMAIN_XML_MIGRATABLE, the XML is altered to + * assist in migrations where the source and destination are running + * different libvirt versions, whether by trimming redundant or + * default information that might confuse an older recipient, or by + * exposing internal details that aid a newer recipient; this flag is + * rejected on read-only connections, and the resulting XML might not + * validate against the schema, so it is mainly for internal use. For the rest of the series, I've made the edits you suggested and pushed. Thanks for the review. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org