[libvirt] [RFC PATCH 15/19] qapi: Mark deprecated QMP commands with feature 'deprecated'

Add feature 'deprecated' to the deprecated QMP commands, so their deprecation becomes visible in output of query-qmp-schema. Looks like this: {"name": "query-cpus", "ret-type": "[164]", "meta-type": "command", "arg-type": "0", ---> "features": ["deprecated"]} The deprecated commands are change, cpu-add, migrate-set-cache-size, migrate_set_downtime, migrate_set_speed, query-cpus, query-events, query-migrate-cache-size. Management applications can use -compat deprecated-input=... to set policy for these commands. So far, the only available policy is "accept", which doesn't change behavior. The next few commits will provide more interesting policies. Command deprecation becomes visible in introspection. Management applications could conceivably use this for static checking. Signed-off-by: Markus Armbruster <armbru(a)redhat.com&gt; --- qapi/machine.json | 24 ++++++++++++++---------- qapi/migration.json | 36 ++++++++++++++++++++++++------------ qapi/misc.json | 25 +++++++++++++++---------- 3 files changed, 53 insertions(+), 32 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index ca26779f1a..3913ef2138 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -189,6 +189,11 @@ # It is recommended to use @query-cpus-fast instead of this command to # avoid the vCPU interruption. # +# Features: +# @deprecated: This interface is deprecated (since 2.12.0), and it is +# strongly recommended that you avoid using it. Use +# @query-cpus-fast to obtain information about virtual CPUs. +# # Returns: a list of @CpuInfo for each virtual CPU # # Since: 0.14.0 @@ -218,12 +223,9 @@ # ] # } # -# Notes: This interface is deprecated (since 2.12.0), and it is strongly -# recommended that you avoid using it. Use @query-cpus-fast to -# obtain information about virtual CPUs. -# ## -{ 'command': 'query-cpus', 'returns': ['CpuInfo'] } +{ 'command': 'query-cpus', 'returns': ['CpuInfo'], + 'features': [ 'deprecated' ] } ## # @CpuInfoFast: @@ -309,21 +311,23 @@ # # @id: ID of CPU to be created, valid values [0..max_cpus) # +# Features: +# @deprecated: This command is deprecated. The `device_add` command +# should be used instead. See the `query-hotpluggable-cpus` +# command for details. +# # Returns: Nothing on success # # Since: 1.5 # -# Note: This command is deprecated. The `device_add` command should be -# used instead. See the `query-hotpluggable-cpus` command for -# details. -# # Example: # # -> { "execute": "cpu-add", "arguments": { "id": 2 } } # <- { "return": {} } # ## -{ 'command': 'cpu-add', 'data': {'id': 'int'} } +{ 'command': 'cpu-add', 'data': {'id': 'int'}, + 'features': [ 'deprecated' ] } ## # @MachineInfo: diff --git a/qapi/migration.json b/qapi/migration.json index 82feb5bd39..a110948bfe 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1119,9 +1119,11 @@ # # @value: maximum downtime in seconds # -# Returns: nothing on success +# Features: +# @deprecated: This command is deprecated in favor of +# 'migrate-set-parameters'. # -# Notes: This command is deprecated in favor of 'migrate-set-parameters' +# Returns: nothing on success # # Since: 0.14.0 # @@ -1131,7 +1133,8 @@ # <- { "return": {} } # ## -{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'} } +{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'}, + 'features': [ 'deprecated' ] } ## # @migrate_set_speed: @@ -1140,9 +1143,11 @@ # # @value: maximum speed in bytes per second. # -# Returns: nothing on success +# Features: +# @deprecated: This command is deprecated in favor of +# 'migrate-set-parameters'. # -# Notes: This command is deprecated in favor of 'migrate-set-parameters' +# Returns: nothing on success # # Since: 0.14.0 # @@ -1152,7 +1157,8 @@ # <- { "return": {} } # ## -{ 'command': 'migrate_set_speed', 'data': {'value': 'int'} } +{ 'command': 'migrate_set_speed', 'data': {'value': 'int'}, + 'features': [ 'deprecated' ] } ## # @migrate-set-cache-size: @@ -1161,13 +1167,15 @@ # # @value: cache size in bytes # +# Features: +# @deprecated: This command is deprecated in favor of +# 'migrate-set-parameters'. +# # The size will be rounded down to the nearest power of 2. # The cache size can be modified before and during ongoing migration # # Returns: nothing on success # -# Notes: This command is deprecated in favor of 'migrate-set-parameters' -# # Since: 1.2 # # Example: @@ -1177,17 +1185,20 @@ # <- { "return": {} } # ## -{ 'command': 'migrate-set-cache-size', 'data': {'value': 'int'} } +{ 'command': 'migrate-set-cache-size', 'data': {'value': 'int'}, + 'features': [ 'deprecated' ] } ## # @query-migrate-cache-size: # # Query migration XBZRLE cache size # +# Features: +# @deprecated: This command is deprecated in favor of +# 'query-migrate-parameters'. +# # Returns: XBZRLE cache size in bytes # -# Notes: This command is deprecated in favor of 'query-migrate-parameters' -# # Since: 1.2 # # Example: @@ -1196,7 +1207,8 @@ # <- { "return": 67108864 } # ## -{ 'command': 'query-migrate-cache-size', 'returns': 'int' } +{ 'command': 'query-migrate-cache-size', 'returns': 'int', + 'features': [ 'deprecated' ] } ## # @migrate: diff --git a/qapi/misc.json b/qapi/misc.json index 33b94e3589..abd2e5dc6e 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -316,13 +316,15 @@ # # Return information on QMP events. # +# Features: +# @deprecated: This command is deprecated, because its output doesn't +# reflect compile-time configuration. Use query-qmp-schema +# instead. +# # Returns: A list of @EventInfo. # # Since: 1.2.0 # -# Note: This command is deprecated, because its output doesn't reflect -# compile-time configuration. Use query-qmp-schema instead. -# # Example: # # -> { "execute": "query-events" } @@ -340,7 +342,8 @@ # Note: This example has been shortened as the real response is too long. # ## -{ 'command': 'query-events', 'returns': ['EventInfo'] } +{ 'command': 'query-events', 'returns': ['EventInfo'], + 'features': [ 'deprecated' ] } ## # @IOThreadInfo: @@ -1074,14 +1077,15 @@ # If @device is 'vnc' and @target is 'password', this is the new VNC # password to set. See change-vnc-password for additional notes. # +# Features: +# @deprecated: This command is deprecated, and it is strongly +# recommended that you avoid using it. For changing block +# devices, use blockdev-change-medium; for changing VNC +# parameters, use change-vnc-password. +# # Returns: Nothing on success. # If @device is not a valid block device, DeviceNotFound # -# Notes: This interface is deprecated, and it is strongly recommended that you -# avoid using it. For changing block devices, use -# blockdev-change-medium; for changing VNC parameters, use -# change-vnc-password. -# # Since: 0.14.0 # # Example: @@ -1102,7 +1106,8 @@ # ## { 'command': 'change', - 'data': {'device': 'str', 'target': 'str', '*arg': 'str'} } + 'data': {'device': 'str', 'target': 'str', '*arg': 'str'}, + 'features': [ 'deprecated' ] } ## # @xen-set-global-dirty-log: -- 2.21.0