Re: [PATCH 02/21] migration: Remove MigrateSetParameters

[Fabiano Rosas <farosas@suse.de>]

Markus Armbruster <armbru@redhat.com> writes:

> Fabiano Rosas <farosas@suse.de> writes:
>
>> Now that the TLS options have been made the same between
>> migrate-set-parameters and query-migrate-parameters, a single type can
>> be used. Remove MigrateSetParameters.
>>
>> The TLS options documentation from MigrationParameters were replaced
>> with the ones from MigrateSetParameters which was more complete.
>>
>> I'm choosing to somewhat ignore any ambiguity between "query" and
>> "set" because other options' docs are already ambiguous in that
>> regard.
>>
>> Signed-off-by: Fabiano Rosas <farosas@suse.de>
>> ---
>>  migration/migration-hmp-cmds.c |   4 +-
>>  migration/options.c            |   6 +-
>>  qapi/migration.json            | 221 +++------------------------------
>>  3 files changed, 20 insertions(+), 211 deletions(-)
>>
>> diff --git a/migration/migration-hmp-cmds.c b/migration/migration-hmp-cmds.c
>> index bc8179c582..aacffdc532 100644
>> --- a/migration/migration-hmp-cmds.c
>> +++ b/migration/migration-hmp-cmds.c
>> @@ -490,7 +490,7 @@ void hmp_migrate_set_parameter(Monitor *mon, const QDict *qdict)
>>      const char *param = qdict_get_str(qdict, "parameter");
>>      const char *valuestr = qdict_get_str(qdict, "value");
>>      Visitor *v = string_input_visitor_new(valuestr);
>> -    MigrateSetParameters *p = g_new0(MigrateSetParameters, 1);
>> +    MigrationParameters *p = g_new0(MigrationParameters, 1);
>>      uint64_t valuebw = 0;
>>      uint64_t cache_size;
>>      Error *err = NULL;
>> @@ -656,7 +656,7 @@ void hmp_migrate_set_parameter(Monitor *mon, const QDict *qdict)
>>      qmp_migrate_set_parameters(p, &err);
>>  
>>   cleanup:
>> -    qapi_free_MigrateSetParameters(p);
>> +    qapi_free_MigrationParameters(p);
>>      visit_free(v);
>>      hmp_handle_error(mon, err);
>>  }
>> diff --git a/migration/options.c b/migration/options.c
>> index 45a95dc6da..e49d584a99 100644
>> --- a/migration/options.c
>> +++ b/migration/options.c
>> @@ -1227,7 +1227,7 @@ bool migrate_params_check(MigrationParameters *params, Error **errp)
>>      return true;
>>  }
>>  
>> -static void migrate_params_test_apply(MigrateSetParameters *params,
>> +static void migrate_params_test_apply(MigrationParameters *params,
>>                                        MigrationParameters *dest)
>>  {
>>      *dest = migrate_get_current()->parameters;
>> @@ -1350,7 +1350,7 @@ static void migrate_params_test_apply(MigrateSetParameters *params,
>>      }
>>  }
>>  
>> -static void migrate_params_apply(MigrateSetParameters *params, Error **errp)
>> +static void migrate_params_apply(MigrationParameters *params, Error **errp)
>>  {
>>      MigrationState *s = migrate_get_current();
>>  
>> @@ -1479,7 +1479,7 @@ static void migrate_params_apply(MigrateSetParameters *params, Error **errp)
>>      }
>>  }
>>  
>> -void qmp_migrate_set_parameters(MigrateSetParameters *params, Error **errp)
>> +void qmp_migrate_set_parameters(MigrationParameters *params, Error **errp)
>>  {
>>      MigrationParameters tmp;
>>  
>> diff --git a/qapi/migration.json b/qapi/migration.json
>> index fa42d94810..080968993a 100644
>> --- a/qapi/migration.json
>> +++ b/qapi/migration.json
>> @@ -914,202 +914,6 @@
>>             'zero-page-detection',
>>             'direct-io'] }
>>  
>> -##
>> -# @MigrateSetParameters:
>
> Only use is argument type of migrate-set-parameters.  You're replacing
> it by MigrationParameters there.  Let's compare the deleted docs to
> their replacement.  I'll quote replacement docs exactly where they
> differ.
>
>    # @MigrationParameters:
>    #
>    # Migration parameters. Optional members are optional when used with
>    # an input command, otherwise mandatory.
>
> Figuring out which commands are input commands is left to the reader.
> Why not simply "optional with migrate-set-parameters"?
>

Future patches include migrate and migrate-incoming. I can enumerate
them if that's better.

> However, it doesn't end there.  The paragraph creates a problem with
> John Snow's "inliner", which I hope to merge later this year.  Let me
> explain.
>
> Generated command documentation normally looks like this:
>
>     Command migrate-set-capabilities (Since: 1.2)
>
>        Enable/Disable the following migration capabilities (like xbzrle)
>
>        Arguments:
>           * **capabilities** ("[""MigrationCapabilityStatus""]") -- json
>             array of capability modifications to make
>
> Except when we happen to use a named type for the arguments.  This
> should be an implementation detail, and it is, except for generated
> documentation, which looks like
>
>     Command migrate-set-parameters (Since: 2.4)
>
>        Set various migration parameters.
>
>        Arguments:
>           * The members of "MigrationParameters".
>
> The arguments are hidden behind a link.  The "inliner" will show the
> them normally *always*, for better usability.  It will not, however,
> inline the introductory paragraph above.  I can explain why if
> necessary.
>
> To compensate for the loss of that paragraph, we'll have to add suitable
> text to migrate-set-parameters's doc comment.
>
> I think we could just as well do that *now*: scratch the paragraph here,
> add a suitable paragraph there.
>

Ok, no worries.

>> -#
>> -# @announce-initial: Initial delay (in milliseconds) before sending
>> -#     the first announce (Since 4.0)
>> -#
>> -# @announce-max: Maximum delay (in milliseconds) between packets in
>> -#     the announcement (Since 4.0)
>> -#
>> -# @announce-rounds: Number of self-announce packets sent after
>> -#     migration (Since 4.0)
>> -#
>> -# @announce-step: Increase in delay (in milliseconds) between
>> -#     subsequent packets in the announcement (Since 4.0)
>> -#
>> -# @throttle-trigger-threshold: The ratio of bytes_dirty_period and
>> -#     bytes_xfer_period to trigger throttling.  It is expressed as
>> -#     percentage.  The default value is 50.  (Since 5.0)
>> -#
>> -# @cpu-throttle-initial: Initial percentage of time guest cpus are
>> -#     throttled when migration auto-converge is activated.  The
>> -#     default value is 20.  (Since 2.7)
>> -#
>
>    # @cpu-throttle-initial: Initial percentage of time guest cpus are
>    #     throttled when migration auto-converge is activated.  (Since
>    #     2.7)
>
> We no longer document the default value.
>

Rebase blunder, I believe the defaults were added recently.

>> -# @cpu-throttle-increment: throttle percentage increase each time
>> -#     auto-converge detects that migration is not making progress.
>> -#     The default value is 10.  (Since 2.7)
>
>    # @cpu-throttle-increment: throttle percentage increase each time
>    #     auto-converge detects that migration is not making progress.
>    #     (Since 2.7)
>
> Likewise.
>

Here as well.

>> -#
>> -# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
>> -#     the tail stage of throttling, the Guest is very sensitive to CPU
>> -#     percentage while the @cpu-throttle -increment is excessive
>> -#     usually at tail stage.  If this parameter is true, we will
>> -#     compute the ideal CPU percentage used by the Guest, which may
>> -#     exactly make the dirty rate match the dirty rate threshold.
>> -#     Then we will choose a smaller throttle increment between the one
>> -#     specified by @cpu-throttle-increment and the one generated by
>> -#     ideal CPU percentage.  Therefore, it is compatible to
>> -#     traditional throttling, meanwhile the throttle increment won't
>> -#     be excessive at tail stage.  The default value is false.  (Since
>> -#     5.1)
>> -#
>> -# @tls-creds: ID of the 'tls-creds' object that provides credentials
>> -#     for establishing a TLS connection over the migration data
>> -#     channel.  On the outgoing side of the migration, the credentials
>> -#     must be for a 'client' endpoint, while for the incoming side the
>> -#     credentials must be for a 'server' endpoint.  Setting this to a
>> -#     non-empty string enables TLS for all migrations.  An empty
>> -#     string means that QEMU will use plain text mode for migration,
>> -#     rather than TLS.  This is the default.  (Since 2.7)
>> -#
>> -# @tls-hostname: migration target's hostname for validating the
>> -#     server's x509 certificate identity.  If empty, QEMU will use the
>> -#     hostname from the migration URI, if any.  A non-empty value is
>> -#     required when using x509 based TLS credentials and the migration
>> -#     URI does not include a hostname, such as fd: or exec: based
>> -#     migration.  (Since 2.7)
>> -#
>> -#     Note: empty value works only since 2.9.
>> -#
>> -# @tls-authz: ID of the 'authz' object subclass that provides access
>> -#     control checking of the TLS x509 certificate distinguished name.
>> -#     This object is only resolved at time of use, so can be deleted
>> -#     and recreated on the fly while the migration server is active.
>> -#     If missing, it will default to denying access (Since 4.0)
>> -#
>> -# @max-bandwidth: maximum speed for migration, in bytes per second.
>> -#     (Since 2.8)
>> -#
>> -# @avail-switchover-bandwidth: to set the available bandwidth that
>> -#     migration can use during switchover phase.  NOTE!  This does not
>> -#     limit the bandwidth during switchover, but only for calculations
>> -#     when making decisions to switchover.  By default, this value is
>> -#     zero, which means QEMU will estimate the bandwidth
>> -#     automatically.  This can be set when the estimated value is not
>> -#     accurate, while the user is able to guarantee such bandwidth is
>> -#     available when switching over.  When specified correctly, this
>> -#     can make the switchover decision much more accurate.
>> -#     (Since 8.2)
>> -#
>> -# @downtime-limit: set maximum tolerated downtime for migration.
>> -#     maximum downtime in milliseconds (Since 2.8)
>> -#
>> -# @x-checkpoint-delay: The delay time (in ms) between two COLO
>> -#     checkpoints in periodic mode.  (Since 2.8)
>
>    # @x-checkpoint-delay: the delay time between two COLO checkpoints.
>    #     (Since 2.8)
>
> We no longer mention periodic mode.
>

I'll fix it.

>> -#
>> -# @multifd-channels: Number of channels used to migrate data in
>> -#     parallel.  This is the same number that the number of sockets
>> -#     used for migration.  The default value is 2 (since 4.0)
>> -#
>> -# @xbzrle-cache-size: cache size to be used by XBZRLE migration.  It
>> -#     needs to be a multiple of the target page size and a power of 2
>> -#     (Since 2.11)
>> -#
>> -# @max-postcopy-bandwidth: Background transfer bandwidth during
>> -#     postcopy.  Defaults to 0 (unlimited).  In bytes per second.
>> -#     (Since 3.0)
>> -#
>> -# @max-cpu-throttle: maximum cpu throttle percentage.  Defaults to 99.
>> -#     (Since 3.1)
>> -#
>> -# @multifd-compression: Which compression method to use.  Defaults to
>> -#     none.  (Since 5.0)
>> -#
>> -# @multifd-zlib-level: Set the compression level to be used in live
>> -#     migration, the compression level is an integer between 0 and 9,
>> -#     where 0 means no compression, 1 means the best compression
>> -#     speed, and 9 means best compression ratio which will consume
>> -#     more CPU.  Defaults to 1.  (Since 5.0)
>> -#
>> -# @multifd-qatzip-level: Set the compression level to be used in live
>> -#     migration. The level is an integer between 1 and 9, where 1 means
>> -#     the best compression speed, and 9 means the best compression
>> -#     ratio which will consume more CPU. Defaults to 1.  (Since 9.2)
>> -#
>> -# @multifd-zstd-level: Set the compression level to be used in live
>> -#     migration, the compression level is an integer between 0 and 20,
>> -#     where 0 means no compression, 1 means the best compression
>> -#     speed, and 20 means best compression ratio which will consume
>> -#     more CPU.  Defaults to 1.  (Since 5.0)
>> -#
>> -# @block-bitmap-mapping: Maps block nodes and bitmaps on them to
>> -#     aliases for the purpose of dirty bitmap migration.  Such aliases
>> -#     may for example be the corresponding names on the opposite site.
>> -#     The mapping must be one-to-one, but not necessarily complete: On
>> -#     the source, unmapped bitmaps and all bitmaps on unmapped nodes
>> -#     will be ignored.  On the destination, encountering an unmapped
>> -#     alias in the incoming migration stream will result in a report,
>> -#     and all further bitmap migration data will then be discarded.
>> -#     Note that the destination does not know about bitmaps it does
>> -#     not receive, so there is no limitation or requirement regarding
>> -#     the number of bitmaps received, or how they are named, or on
>> -#     which nodes they are placed.  By default (when this parameter
>> -#     has never been set), bitmap names are mapped to themselves.
>> -#     Nodes are mapped to their block device name if there is one, and
>> -#     to their node name otherwise.  (Since 5.2)
>> -#
>> -# @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty
>> -#     limit during live migration.  Should be in the range 1 to
>> -#     1000ms.  Defaults to 1000ms.  (Since 8.1)
>> -#
>> -# @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
>> -#     Defaults to 1.  (Since 8.1)
>> -#
>> -# @mode: Migration mode.  See description in @MigMode.  Default is
>> -#     'normal'.  (Since 8.2)
>> -#
>> -# @zero-page-detection: Whether and how to detect zero pages.
>> -#     See description in @ZeroPageDetection.  Default is 'multifd'.
>> -#     (since 9.0)
>> -#
>> -# @direct-io: Open migration files with O_DIRECT when possible.  This
>> -#     only has effect if the @mapped-ram capability is enabled.
>> -#     (Since 9.1)
>> -#
>> -# Features:
>> -#
>> -# @unstable: Members @x-checkpoint-delay and
>> -#     @x-vcpu-dirty-limit-period are experimental.
>> -#
>> -# TODO: either fuse back into MigrationParameters, or make
>> -#     MigrationParameters members mandatory
>
> The TODO is gone.  Makes sense.
>
>> -#
>> -# Since: 2.4
>> -##
>> -{ 'struct': 'MigrateSetParameters',
>> -  'data': { '*announce-initial': 'size',
>> -            '*announce-max': 'size',
>> -            '*announce-rounds': 'size',
>> -            '*announce-step': 'size',
>> -            '*throttle-trigger-threshold': 'uint8',
>> -            '*cpu-throttle-initial': 'uint8',
>> -            '*cpu-throttle-increment': 'uint8',
>> -            '*cpu-throttle-tailslow': 'bool',
>> -            '*tls-creds': 'StrOrNull',
>> -            '*tls-hostname': 'StrOrNull',
>> -            '*tls-authz': 'StrOrNull',
>> -            '*max-bandwidth': 'size',
>> -            '*avail-switchover-bandwidth': 'size',
>> -            '*downtime-limit': 'uint64',
>> -            '*x-checkpoint-delay': { 'type': 'uint32',
>> -                                     'features': [ 'unstable' ] },
>> -            '*multifd-channels': 'uint8',
>> -            '*xbzrle-cache-size': 'size',
>> -            '*max-postcopy-bandwidth': 'size',
>> -            '*max-cpu-throttle': 'uint8',
>> -            '*multifd-compression': 'MultiFDCompression',
>> -            '*multifd-zlib-level': 'uint8',
>> -            '*multifd-qatzip-level': 'uint8',
>> -            '*multifd-zstd-level': 'uint8',
>> -            '*block-bitmap-mapping': [ 'BitmapMigrationNodeAlias' ],
>> -            '*x-vcpu-dirty-limit-period': { 'type': 'uint64',
>> -                                            'features': [ 'unstable' ] },
>> -            '*vcpu-dirty-limit': 'uint64',
>> -            '*mode': 'MigMode',
>> -            '*zero-page-detection': 'ZeroPageDetection',
>> -            '*direct-io': 'bool' } }
>> -
>>  ##
>>  # @migrate-set-parameters:
>>  #
>> @@ -1124,12 +928,13 @@
>>  #     <- { "return": {} }
>>  ##
>>  { 'command': 'migrate-set-parameters', 'boxed': true,
>> -  'data': 'MigrateSetParameters' }
>> +  'data': 'MigrationParameters' }
>>  
>>  ##
>>  # @MigrationParameters:
>>  #
>> -# The optional members aren't actually optional.
>> +# Migration parameters. Optional members are optional when used with
>> +# an input command, otherwise mandatory.
>>  #
>>  # @announce-initial: Initial delay (in milliseconds) before sending
>>  #     the first announce (Since 4.0)
>> @@ -1172,21 +977,25 @@
>>  #     for establishing a TLS connection over the migration data
>>  #     channel.  On the outgoing side of the migration, the credentials
>>  #     must be for a 'client' endpoint, while for the incoming side the
>> -#     credentials must be for a 'server' endpoint.  An empty string
>> -#     means that QEMU will use plain text mode for migration, rather
>> -#     than TLS.  (Since 2.7)
>> -#
>> -#     Note: 2.8 omits empty @tls-creds instead.
>> +#     credentials must be for a 'server' endpoint.  Setting this to a
>> +#     non-empty string enables TLS for all migrations.  An empty
>> +#     string means that QEMU will use plain text mode for migration,
>> +#     rather than TLS.  This is the default.  (Since 2.7)
>>  #
>>  # @tls-hostname: migration target's hostname for validating the
>>  #     server's x509 certificate identity.  If empty, QEMU will use the
>> -#     hostname from the migration URI, if any.  (Since 2.7)
>> +#     hostname from the migration URI, if any.  A non-empty value is
>> +#     required when using x509 based TLS credentials and the migration
>> +#     URI does not include a hostname, such as fd: or exec: based
>> +#     migration.  (Since 2.7)
>>  #
>> -#     Note: 2.8 omits empty @tls-hostname instead.
>> +#     Note: empty value works only since 2.9.
>>  #
>>  # @tls-authz: ID of the 'authz' object subclass that provides access
>>  #     control checking of the TLS x509 certificate distinguished name.
>> -#     (Since 4.0)
>> +#     This object is only resolved at time of use, so can be deleted
>> +#     and recreated on the fly while the migration server is active.
>> +#     If missing, it will default to denying access (Since 4.0)
>>  #
>>  # @max-bandwidth: maximum speed for migration, in bytes per second.
>>  #     (Since 2.8)