Markus Armbruster <arm...@redhat.com> writes:
> Fabiano Rosas <faro...@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 <faro...@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)
