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@xxxxxxxxxx>
>> ---
>> 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
