The concept of capabilities is being merged into the concept of
parameters. From now on, the commands that handle capabilities are
deprecated in favor of the commands that handle parameters.

Affected commands:

- migrate-set-capabilities
- query-migrate-capabilities

Signed-off-by: Fabiano Rosas <farosas@suse.de>
---
 docs/about/deprecated.rst      | 12 ++++++++++++
 migration/migration-hmp-cmds.c |  6 ++++++
 qapi/migration.json            | 16 ++++++++++++++--
 3 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
index 42037131de..15474833ea 100644
--- a/docs/about/deprecated.rst
+++ b/docs/about/deprecated.rst
@@ -605,3 +605,15 @@ command documentation for details on the ``fdset`` usage.
 
 The ``zero-blocks`` capability was part of the block migration which
 doesn't exist anymore since it was removed in QEMU v9.1.
+
+``migrate-set-capabilities`` command (since 10.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''
+
+This command was deprecated. Use ``migrate-set-parameters`` instead
+which now supports setting capabilities.
+
+``query-migrate-capabilities`` command (since 10.1)
+'''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This command was deprecated. Use ``query-migrate-parameters`` instead
+which now supports querying capabilities.
diff --git a/migration/migration-hmp-cmds.c b/migration/migration-hmp-cmds.c
index 8615340a6b..7f234d5aa8 100644
--- a/migration/migration-hmp-cmds.c
+++ b/migration/migration-hmp-cmds.c
@@ -229,6 +229,9 @@ void hmp_info_migrate_capabilities(Monitor *mon, const QDict *qdict)
 {
     MigrationCapabilityStatusList *caps, *cap;
 
+    warn_report("info migrate_capabilities is deprecated;"
+                " use info migrate_parameters instead");
+
     caps = qmp_query_migrate_capabilities(NULL);
 
     if (caps) {
@@ -616,6 +619,9 @@ void hmp_migrate_set_capability(Monitor *mon, const QDict *qdict)
     MigrationCapabilityStatus *value;
     int val;
 
+    warn_report("migrate_set_capability is deprecated;"
+                " use migrate_set_parameter instead");
+
     val = qapi_enum_parse(&MigrationCapability_lookup, cap, -1, &err);
     if (val < 0) {
         goto end;
diff --git a/qapi/migration.json b/qapi/migration.json
index 3d3f5624c5..c5e6ea1a2d 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -521,6 +521,11 @@
 #
 # @capabilities: json array of capability modifications to make
 #
+# Features:
+#
+# @deprecated: This command is deprecated in favor of
+# migrate-set-parameters.
+#
 # Since: 1.2
 #
 # .. qmp-example::
@@ -530,7 +535,8 @@
 #     <- { "return": {} }
 ##
 { 'command': 'migrate-set-capabilities',
-  'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
+  'data': { 'capabilities': ['MigrationCapabilityStatus'] },
+  'features': ['deprecated'] }
 
 ##
 # @query-migrate-capabilities:
@@ -539,6 +545,11 @@
 #
 # Returns: @MigrationCapabilityStatus
 #
+# Features:
+#
+# @deprecated: This command is deprecated in favor of
+# query-migrate-parameters.
+#
 # Since: 1.2
 #
 # .. qmp-example::
@@ -554,7 +565,8 @@
 #           {"state": false, "capability": "x-colo"}
 #        ]}
 ##
-{ 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus']}
+{ 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus'],
+  'features': ['deprecated'] }
 
 ##
 # @MultiFDCompression:
-- 
2.35.3

On Mon, Jun 30, 2025 at 04:59:07PM -0300, Fabiano Rosas wrote:
> The concept of capabilities is being merged into the concept of
> parameters. From now on, the commands that handle capabilities are
> deprecated in favor of the commands that handle parameters.
> 
> Affected commands:
> 
> - migrate-set-capabilities
> - query-migrate-capabilities
> 
> Signed-off-by: Fabiano Rosas <farosas@suse.de>
> ---
>  docs/about/deprecated.rst      | 12 ++++++++++++
>  migration/migration-hmp-cmds.c |  6 ++++++
>  qapi/migration.json            | 16 ++++++++++++++--
>  3 files changed, 32 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
> index 42037131de..15474833ea 100644
> --- a/docs/about/deprecated.rst
> +++ b/docs/about/deprecated.rst
> @@ -605,3 +605,15 @@ command documentation for details on the ``fdset`` usage.
>  
>  The ``zero-blocks`` capability was part of the block migration which
>  doesn't exist anymore since it was removed in QEMU v9.1.
> +
> +``migrate-set-capabilities`` command (since 10.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +This command was deprecated. Use ``migrate-set-parameters`` instead
> +which now supports setting capabilities.
> +
> +``query-migrate-capabilities`` command (since 10.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''

Don't forget to update the versions.

Reviewed-by: Peter Xu <peterx@redhat.com>

-- 
Peter Xu

On Mon, Jun 30, 2025 at 16:59:07 -0300, Fabiano Rosas wrote:
> The concept of capabilities is being merged into the concept of
> parameters. From now on, the commands that handle capabilities are
> deprecated in favor of the commands that handle parameters.
> 
> Affected commands:
> 
> - migrate-set-capabilities
> - query-migrate-capabilities
> 
> Signed-off-by: Fabiano Rosas <farosas@suse.de>
> ---
>  docs/about/deprecated.rst      | 12 ++++++++++++
>  migration/migration-hmp-cmds.c |  6 ++++++
>  qapi/migration.json            | 16 ++++++++++++++--
>  3 files changed, 32 insertions(+), 2 deletions(-)

We'll need to adapt libvirt as both commands are actively used now. Is
there a way of detecting where the relevant commands for
setting/querying parameters support capabilities? I guess QAPI schema
should work, right?

Jirka

On Tue, Jul 01, 2025 at 10:38:44AM +0200, Jiri Denemark wrote:
> On Mon, Jun 30, 2025 at 16:59:07 -0300, Fabiano Rosas wrote:
> > The concept of capabilities is being merged into the concept of
> > parameters. From now on, the commands that handle capabilities are
> > deprecated in favor of the commands that handle parameters.
> > 
> > Affected commands:
> > 
> > - migrate-set-capabilities
> > - query-migrate-capabilities
> > 
> > Signed-off-by: Fabiano Rosas <farosas@suse.de>
> > ---
> >  docs/about/deprecated.rst      | 12 ++++++++++++
> >  migration/migration-hmp-cmds.c |  6 ++++++
> >  qapi/migration.json            | 16 ++++++++++++++--
> >  3 files changed, 32 insertions(+), 2 deletions(-)
> 
> We'll need to adapt libvirt as both commands are actively used now. Is
> there a way of detecting where the relevant commands for
> setting/querying parameters support capabilities? I guess QAPI schema
> should work, right?

Query the 'migrate' command schema which gains a new 'config' parameter
in patch 20 in this series.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Tue, Jul 01, 2025 at 10:38:44 +0200, Jiri Denemark via Devel wrote:
> On Mon, Jun 30, 2025 at 16:59:07 -0300, Fabiano Rosas wrote:
> > The concept of capabilities is being merged into the concept of
> > parameters. From now on, the commands that handle capabilities are
> > deprecated in favor of the commands that handle parameters.
> > 
> > Affected commands:
> > 
> > - migrate-set-capabilities
> > - query-migrate-capabilities
> > 
> > Signed-off-by: Fabiano Rosas <farosas@suse.de>
> > ---
> >  docs/about/deprecated.rst      | 12 ++++++++++++
> >  migration/migration-hmp-cmds.c |  6 ++++++
> >  qapi/migration.json            | 16 ++++++++++++++--
> >  3 files changed, 32 insertions(+), 2 deletions(-)
> 
> We'll need to adapt libvirt as both commands are actively used now. Is
> there a way of detecting where the relevant commands for
> setting/querying parameters support capabilities? I guess QAPI schema
> should work, right?

The parameters command gains the fields from "migrate-set-capabilities"
which is easy to query. Alternatively we can query the "deprecated"
feature as well.

Fabiano Rosas <farosas@suse.de> writes:

> The concept of capabilities is being merged into the concept of
> parameters. From now on, the commands that handle capabilities are
> deprecated in favor of the commands that handle parameters.
>
> Affected commands:
>
> - migrate-set-capabilities
> - query-migrate-capabilities
>
> Signed-off-by: Fabiano Rosas <farosas@suse.de>
> ---
>  docs/about/deprecated.rst      | 12 ++++++++++++
>  migration/migration-hmp-cmds.c |  6 ++++++
>  qapi/migration.json            | 16 ++++++++++++++--
>  3 files changed, 32 insertions(+), 2 deletions(-)
>
> diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
> index 42037131de..15474833ea 100644
> --- a/docs/about/deprecated.rst
> +++ b/docs/about/deprecated.rst
> @@ -605,3 +605,15 @@ command documentation for details on the ``fdset`` usage.
>  
>  The ``zero-blocks`` capability was part of the block migration which
>  doesn't exist anymore since it was removed in QEMU v9.1.
> +
> +``migrate-set-capabilities`` command (since 10.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +This command was deprecated. Use ``migrate-set-parameters`` instead
> +which now supports setting capabilities.
> +
> +``query-migrate-capabilities`` command (since 10.1)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +This command was deprecated. Use ``query-migrate-parameters`` instead
> +which now supports querying capabilities.

Scratch "This command was deprecated."

Could also scratch "which now supports..."  Up to you.

> diff --git a/migration/migration-hmp-cmds.c b/migration/migration-hmp-cmds.c
> index 8615340a6b..7f234d5aa8 100644
> --- a/migration/migration-hmp-cmds.c
> +++ b/migration/migration-hmp-cmds.c
> @@ -229,6 +229,9 @@ void hmp_info_migrate_capabilities(Monitor *mon, const QDict *qdict)
>  {
>      MigrationCapabilityStatusList *caps, *cap;
>  
> +    warn_report("info migrate_capabilities is deprecated;"
> +                " use info migrate_parameters instead");
> +
>      caps = qmp_query_migrate_capabilities(NULL);
>  
>      if (caps) {
> @@ -616,6 +619,9 @@ void hmp_migrate_set_capability(Monitor *mon, const QDict *qdict)
>      MigrationCapabilityStatus *value;
>      int val;
>  
> +    warn_report("migrate_set_capability is deprecated;"
> +                " use migrate_set_parameter instead");
> +
>      val = qapi_enum_parse(&MigrationCapability_lookup, cap, -1, &err);
>      if (val < 0) {
>          goto end;
> diff --git a/qapi/migration.json b/qapi/migration.json
> index 3d3f5624c5..c5e6ea1a2d 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -521,6 +521,11 @@
>  #
>  # @capabilities: json array of capability modifications to make
>  #
> +# Features:
> +#
> +# @deprecated: This command is deprecated in favor of
> +# migrate-set-parameters.

For consistency with existing deprecation notes:

   # @deprecated: This command is deprecated.  Use migrate-set-parameters
   # instead.

> +#
>  # Since: 1.2
>  #
>  # .. qmp-example::
> @@ -530,7 +535,8 @@
>  #     <- { "return": {} }
>  ##
>  { 'command': 'migrate-set-capabilities',
> -  'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
> +  'data': { 'capabilities': ['MigrationCapabilityStatus'] },
> +  'features': ['deprecated'] }
>  
>  ##
>  # @query-migrate-capabilities:
> @@ -539,6 +545,11 @@
>  #
>  # Returns: @MigrationCapabilityStatus
>  #
> +# Features:
> +#
> +# @deprecated: This command is deprecated in favor of
> +# query-migrate-parameters.

Likewise.

> +#
>  # Since: 1.2
>  #
>  # .. qmp-example::
> @@ -554,7 +565,8 @@
>  #           {"state": false, "capability": "x-colo"}
>  #        ]}
>  ##
> -{ 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus']}
> +{ 'command': 'query-migrate-capabilities', 'returns':   ['MigrationCapabilityStatus'],
> +  'features': ['deprecated'] }
>  
>  ##
>  # @MultiFDCompression:

With that:

Reviewed-by: Markus Armbruster <armbru@redhat.com>