[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v3 4/4] migration/qapi: Drop @MigrationParameter enum
|
From: |
Peter Xu |
|
Subject: |
Re: [PATCH v3 4/4] migration/qapi: Drop @MigrationParameter enum |
|
Date: |
Mon, 16 Oct 2023 12:16:58 -0400 |
On Mon, Oct 16, 2023 at 08:29:58AM +0200, Markus Armbruster wrote:
> Better, because even stupider: drop the feature flags. They have no
> effect on internal use, and there is no external use.
>
> ##
> # @MigrationParameter:
> #
> # TODO: elide from generated documentation (type is used only
> # internally, and not visible in QMP)
> #
> # Since: 2.4
> ##
> { 'enum': 'MigrationParameter',
> 'data': ['announce-initial', 'announce-max',
> 'announce-rounds', 'announce-step',
> 'compress-level', 'compress-threads', 'decompress-threads',
> 'compress-wait-thread', 'throttle-trigger-threshold',
> 'cpu-throttle-initial', 'cpu-throttle-increment',
> 'cpu-throttle-tailslow',
> 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth',
> 'downtime-limit',
> 'x-checkpoint-delay',
> 'block-incremental',
> 'multifd-channels',
> 'xbzrle-cache-size', 'max-postcopy-bandwidth',
> 'max-cpu-throttle', 'multifd-compression',
> 'multifd-zlib-level', 'multifd-zstd-level',
> 'block-bitmap-mapping',
> 'x-vcpu-dirty-limit-period',
> 'vcpu-dirty-limit'] }
Didn't work either, unfortunately.. Compile is fine, but I still see the
lines generated in qemu-qmp-ref.7.
MigrationParameter (Enum)
Values
announce-initial
Not documented
announce-max
Not documented
announce-rounds
Not documented
announce-step
Not documented
compress-level
Not documented
[...]
Patch attached.
Thanks,
===8<===
>From 6e9355f2b5e1ad21de1e13114055390077f34ca0 Mon Sep 17 00:00:00 2001
From: Peter Xu <peterx@redhat.com>
Date: Mon, 16 Oct 2023 12:00:44 -0400
Subject: [PATCH] migration/qapi: Drop documentation for MigrationParameter
@MigrationParameter shouldn't be exposed in QAPI schema. It should only be
used in QEMU internally. Documentation is not required for this object.
Keeping it under qapi/ still makes sense, so as to benefit QEMU from
auto-generated helpers around the object to reduce hand written codes.
After all, the documentation duplicates with @MigrationSetParameters and
@MigrationParameters which are real exported QAPI objects. It's more
challenging to deduplicate all three into one, but drop the easy one first
by leveraging a loophole in QAPI generator.
When at it, redo the newlines so one parameter per line.
Suggested-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
---
qapi/migration.json | 203 ++++++--------------------------------------
1 file changed, 27 insertions(+), 176 deletions(-)
diff --git a/qapi/migration.json b/qapi/migration.json
index db3df12d6c..7b9054433a 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -673,190 +673,41 @@
##
# @MigrationParameter:
#
-# Migration parameters enumeration
-#
-# @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)
-#
-# @compress-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.
-#
-# @compress-threads: Set compression thread count to be used in live
-# migration, the compression thread count is an integer between 1
-# and 255.
-#
-# @compress-wait-thread: Controls behavior when all compression
-# threads are currently busy. If true (default), wait for a free
-# compression thread to become available; otherwise, send the page
-# uncompressed. (Since 3.1)
-#
-# @decompress-threads: Set decompression thread count to be used in
-# live migration, the decompression thread count is an integer
-# between 1 and 255. Usually, decompression is at least 4 times as
-# fast as compression, so set the decompress-threads to the number
-# about 1/4 of compress-threads is adequate.
-#
-# @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-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-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 will
-# enable TLS for all migrations. The default is unset, resulting
-# in unsecured migration at the QEMU level. (Since 2.7)
-#
-# @tls-hostname: hostname of the target host for the migration. This
-# is required when using x509 based TLS credentials and the
-# migration URI does not already include a hostname. For example
-# if using fd: or exec: based migration, the hostname must be
-# provided so that the server's x509 certificate identity can be
-# validated. (Since 2.7)
-#
-# @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: to set maximum speed for migration. maximum speed
-# 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)
-#
-# @block-incremental: Affects how much storage is migrated when the
-# block migration capability is enabled. When false, the entire
-# storage backing chain is migrated into a flattened image at the
-# destination; when true, only the active qcow2 layer is migrated
-# and the destination must already have access to the same backing
-# chain as was used on the source. (since 2.10)
-#
-# @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-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)
-#
-# Features:
-#
-# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
-# are experimental.
+# TODO: elide from generated documentation (type is used only
+# internally, and not visible in QMP)
#
# Since: 2.4
##
{ 'enum': 'MigrationParameter',
- 'data': ['announce-initial', 'announce-max',
- 'announce-rounds', 'announce-step',
- 'compress-level', 'compress-threads', 'decompress-threads',
- 'compress-wait-thread', 'throttle-trigger-threshold',
- 'cpu-throttle-initial', 'cpu-throttle-increment',
+ 'data': ['announce-initial',
+ 'announce-max',
+ 'announce-rounds',
+ 'announce-step',
+ 'compress-level',
+ 'compress-threads',
+ 'decompress-threads',
+ 'compress-wait-thread',
+ 'throttle-trigger-threshold',
+ 'cpu-throttle-initial',
+ 'cpu-throttle-increment',
'cpu-throttle-tailslow',
- 'tls-creds', 'tls-hostname', 'tls-authz', 'max-bandwidth',
- 'avail-switchover-bandwidth', 'downtime-limit',
- { 'name': 'x-checkpoint-delay', 'features': [ 'unstable' ] },
+ 'tls-creds',
+ 'tls-hostname',
+ 'tls-authz',
+ 'max-bandwidth',
+ 'avail-switchover-bandwidth',
+ 'downtime-limit',
+ 'x-checkpoint-delay',
'block-incremental',
'multifd-channels',
- 'xbzrle-cache-size', 'max-postcopy-bandwidth',
- 'max-cpu-throttle', 'multifd-compression',
- 'multifd-zlib-level', 'multifd-zstd-level',
+ 'xbzrle-cache-size',
+ 'max-postcopy-bandwidth',
+ 'max-cpu-throttle',
+ 'multifd-compression',
+ 'multifd-zlib-level',
+ 'multifd-zstd-level',
'block-bitmap-mapping',
- { 'name': 'x-vcpu-dirty-limit-period', 'features': ['unstable'] },
+ 'x-vcpu-dirty-limit-period',
'vcpu-dirty-limit'] }
##
--
2.41.0
--
Peter Xu