[Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

This series adds machine type deprecation information to the
output of the `query-machines` QMP command.  With this, libvirt
and management software will be able to show this information to
users and/or suggest changes to VM configuration to avoid
deprecated machine types.

Eduardo Habkost (3):
  qapi: SupportStatusInfo struct
  machine: Use SupportStatusInfo for deprecation info
  qmp: Add deprecation information to query-machines

 qapi/common.json                   | 24 ++++++++++++++++++++++++
 qapi/misc.json                     |  5 ++++-
 include/hw/boards.h                |  7 ++++---
 hw/i386/pc_piix.c                  |  4 +++-
 hw/ppc/prep.c                      |  4 +++-
 vl.c                               | 19 +++++++++++++++----
 tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
 7 files changed, 80 insertions(+), 10 deletions(-)
 create mode 100644 tests/acceptance/query_machines.py

-- 
2.18.0.rc1.1.g3f1ff2140

[Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

This series adds machine type deprecation information to the
output of the `query-machines` QMP command.  With this, libvirt
and management software will be able to show this information to
users and/or suggest changes to VM configuration to avoid
deprecated machine types.

Eduardo Habkost (3):
  qapi: SupportStatusInfo struct
  machine: Use SupportStatusInfo for deprecation info
  qmp: Add deprecation information to query-machines

 qapi/common.json                   | 24 ++++++++++++++++++++++++
 qapi/misc.json                     |  5 ++++-
 include/hw/boards.h                |  7 ++++---
 hw/i386/pc_piix.c                  |  4 +++-
 hw/ppc/prep.c                      |  4 +++-
 vl.c                               | 19 +++++++++++++++----
 tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
 7 files changed, 80 insertions(+), 10 deletions(-)
 create mode 100644 tests/acceptance/query_machines.py

-- 
2.18.0.rc1.1.g3f1ff2140

[Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

This struct will be used to represent support and deprecation
status of QEMU features.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 qapi/common.json | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/qapi/common.json b/qapi/common.json
index 99d313ef3b..b59d0dc66b 100644
--- a/qapi/common.json
+++ b/qapi/common.json
@@ -193,3 +193,27 @@
              'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
              'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
              'x86_64', 'xtensa', 'xtensaeb' ] }
+
+##
+# @SupportStatusInfo:
+#
+# Information on support status of a given feature
+# (e.g. machine type)
+#
+# @deprecated: if true, the given feature is deprecated and may be removed
+#              in future versions of QEMU according to the QEMU deprecation
+#              policy.
+#
+# @status-message: Human readable message describing support status
+#                  of the feature.
+#
+# @suggested-alternative: Optional.  Suggested alternative for a deprecated
+#                         feature.  For machine types, this should be the name
+#                         of an available machine-type.
+#
+# Since: 4.1
+##
+{ 'struct': 'SupportStatusInfo',
+  'data': { 'deprecated': 'bool',
+            '*status-message': 'str',
+            '*suggested-alternative': 'str' } }
-- 
2.18.0.rc1.1.g3f1ff2140

[Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

This struct will be used to represent support and deprecation
status of QEMU features.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 qapi/common.json | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/qapi/common.json b/qapi/common.json
index 99d313ef3b..b59d0dc66b 100644
--- a/qapi/common.json
+++ b/qapi/common.json
@@ -193,3 +193,27 @@
              'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
              'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
              'x86_64', 'xtensa', 'xtensaeb' ] }
+
+##
+# @SupportStatusInfo:
+#
+# Information on support status of a given feature
+# (e.g. machine type)
+#
+# @deprecated: if true, the given feature is deprecated and may be removed
+#              in future versions of QEMU according to the QEMU deprecation
+#              policy.
+#
+# @status-message: Human readable message describing support status
+#                  of the feature.
+#
+# @suggested-alternative: Optional.  Suggested alternative for a deprecated
+#                         feature.  For machine types, this should be the name
+#                         of an available machine-type.
+#
+# Since: 4.1
+##
+{ 'struct': 'SupportStatusInfo',
+  'data': { 'deprecated': 'bool',
+            '*status-message': 'str',
+            '*suggested-alternative': 'str' } }
-- 
2.18.0.rc1.1.g3f1ff2140

[Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Eduardo Habkost]

Use SupportStatusInfo to represent deprecation information of
machine types.

Instead of using a generic "use XXX instead" message for humans,
encode the suggested alternative in a machine-friendly way at the
'suggested_alternatives' field.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 include/hw/boards.h |  7 ++++---
 hw/i386/pc_piix.c   |  4 +++-
 hw/ppc/prep.c       |  4 +++-
 vl.c                | 13 +++++++++----
 4 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/include/hw/boards.h b/include/hw/boards.h
index e231860666..243bf3c7ce 100644
--- a/include/hw/boards.h
+++ b/include/hw/boards.h
@@ -8,6 +8,8 @@
 #include "hw/qdev.h"
 #include "qom/object.h"
 #include "qom/cpu.h"
+#include "qapi/qapi-types-common.h"
+
 
 /**
  * memory_region_allocate_system_memory - Allocate a board's main memory
@@ -105,8 +107,7 @@ typedef struct {
 
 /**
  * MachineClass:
- * @deprecation_reason: If set, the machine is marked as deprecated. The
- *    string should provide some clear information about what to use instead.
+ * @support_status: Support and deprecation status of machine type.
  * @max_cpus: maximum number of CPUs supported. Default: 1
  * @min_cpus: minimum number of CPUs supported. Default: 1
  * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
@@ -169,7 +170,7 @@ struct MachineClass {
     char *name;
     const char *alias;
     const char *desc;
-    const char *deprecation_reason;
+    SupportStatusInfo support_status;
 
     void (*init)(MachineState *state);
     void (*reset)(void);
diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
index 8ad8e885c6..97bd401618 100644
--- a/hw/i386/pc_piix.c
+++ b/hw/i386/pc_piix.c
@@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
 
     pc_i440fx_1_0_machine_options(m);
     m->hw_version = "0.15";
-    m->deprecation_reason = "use a newer machine type instead";
+    m->support_status.deprecated = true;
+    m->support_status.has_suggested_alternative = true;
+    m->support_status.suggested_alternative = g_strdup("pc");
     compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
 }
 
diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
index 847d320465..9a02b0eec4 100644
--- a/hw/ppc/prep.c
+++ b/hw/ppc/prep.c
@@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
 
 static void prep_machine_init(MachineClass *mc)
 {
-    mc->deprecation_reason = "use 40p machine type instead";
+    mc->support_status.deprecated = true;
+    mc->support_status.has_suggested_alternative = true;
+    mc->support_status.suggested_alternative = g_strdup("40p");
     mc->desc = "PowerPC PREP platform";
     mc->init = ppc_prep_init;
     mc->block_default_type = IF_IDE;
diff --git a/vl.c b/vl.c
index c696ad2a13..99b857ed2a 100644
--- a/vl.c
+++ b/vl.c
@@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
             }
             printf("%-20s %s%s%s\n", mc->name, mc->desc,
                    mc->is_default ? " (default)" : "",
-                   mc->deprecation_reason ? " (deprecated)" : "");
+                   mc->support_status.deprecated ? " (deprecated)" : "");
         }
     }
 
@@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
      * called from configure_accelerator().
      */
 
-    if (!qtest_enabled() && machine_class->deprecation_reason) {
-        error_report("Machine type '%s' is deprecated: %s",
-                     machine_class->name, machine_class->deprecation_reason);
+    if (!qtest_enabled() && machine_class->support_status.deprecated) {
+        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
+                     machine_class->support_status.status_message ? ": " : "",
+                     machine_class->support_status.status_message ?: "");
+        if (machine_class->support_status.suggested_alternative) {
+            error_report("Suggested solution: use '%s' machine type instead",
+                         machine_class->support_status.suggested_alternative);
+        }
     }
 
     /*
-- 
2.18.0.rc1.1.g3f1ff2140

[Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Eduardo Habkost]

Use SupportStatusInfo to represent deprecation information of
machine types.

Instead of using a generic "use XXX instead" message for humans,
encode the suggested alternative in a machine-friendly way at the
'suggested_alternatives' field.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 include/hw/boards.h |  7 ++++---
 hw/i386/pc_piix.c   |  4 +++-
 hw/ppc/prep.c       |  4 +++-
 vl.c                | 13 +++++++++----
 4 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/include/hw/boards.h b/include/hw/boards.h
index e231860666..243bf3c7ce 100644
--- a/include/hw/boards.h
+++ b/include/hw/boards.h
@@ -8,6 +8,8 @@
 #include "hw/qdev.h"
 #include "qom/object.h"
 #include "qom/cpu.h"
+#include "qapi/qapi-types-common.h"
+
 
 /**
  * memory_region_allocate_system_memory - Allocate a board's main memory
@@ -105,8 +107,7 @@ typedef struct {
 
 /**
  * MachineClass:
- * @deprecation_reason: If set, the machine is marked as deprecated. The
- *    string should provide some clear information about what to use instead.
+ * @support_status: Support and deprecation status of machine type.
  * @max_cpus: maximum number of CPUs supported. Default: 1
  * @min_cpus: minimum number of CPUs supported. Default: 1
  * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
@@ -169,7 +170,7 @@ struct MachineClass {
     char *name;
     const char *alias;
     const char *desc;
-    const char *deprecation_reason;
+    SupportStatusInfo support_status;
 
     void (*init)(MachineState *state);
     void (*reset)(void);
diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
index 8ad8e885c6..97bd401618 100644
--- a/hw/i386/pc_piix.c
+++ b/hw/i386/pc_piix.c
@@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
 
     pc_i440fx_1_0_machine_options(m);
     m->hw_version = "0.15";
-    m->deprecation_reason = "use a newer machine type instead";
+    m->support_status.deprecated = true;
+    m->support_status.has_suggested_alternative = true;
+    m->support_status.suggested_alternative = g_strdup("pc");
     compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
 }
 
diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
index 847d320465..9a02b0eec4 100644
--- a/hw/ppc/prep.c
+++ b/hw/ppc/prep.c
@@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
 
 static void prep_machine_init(MachineClass *mc)
 {
-    mc->deprecation_reason = "use 40p machine type instead";
+    mc->support_status.deprecated = true;
+    mc->support_status.has_suggested_alternative = true;
+    mc->support_status.suggested_alternative = g_strdup("40p");
     mc->desc = "PowerPC PREP platform";
     mc->init = ppc_prep_init;
     mc->block_default_type = IF_IDE;
diff --git a/vl.c b/vl.c
index c696ad2a13..99b857ed2a 100644
--- a/vl.c
+++ b/vl.c
@@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
             }
             printf("%-20s %s%s%s\n", mc->name, mc->desc,
                    mc->is_default ? " (default)" : "",
-                   mc->deprecation_reason ? " (deprecated)" : "");
+                   mc->support_status.deprecated ? " (deprecated)" : "");
         }
     }
 
@@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
      * called from configure_accelerator().
      */
 
-    if (!qtest_enabled() && machine_class->deprecation_reason) {
-        error_report("Machine type '%s' is deprecated: %s",
-                     machine_class->name, machine_class->deprecation_reason);
+    if (!qtest_enabled() && machine_class->support_status.deprecated) {
+        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
+                     machine_class->support_status.status_message ? ": " : "",
+                     machine_class->support_status.status_message ?: "");
+        if (machine_class->support_status.suggested_alternative) {
+            error_report("Suggested solution: use '%s' machine type instead",
+                         machine_class->support_status.suggested_alternative);
+        }
     }
 
     /*
-- 
2.18.0.rc1.1.g3f1ff2140

[Qemu-devel] [PATCH 3/3] qmp: Add deprecation information to query-machines

[Eduardo Habkost]

Export machine type deprecation information through the
query-machines QMP command.  With this, libvirt and management
software will be able to show this information to users and/or
suggest changes to VM configuration to avoid deprecated machines.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 qapi/misc.json                     |  5 ++++-
 vl.c                               |  6 ++++++
 tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 tests/acceptance/query_machines.py

diff --git a/qapi/misc.json b/qapi/misc.json
index 8b3ca4fdd3..941d251d17 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -2018,12 +2018,15 @@
 #
 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
 #
+# @support-status: Support/deprecation status information (since 4.1.0)
+#
 # Since: 1.2.0
 ##
 { 'struct': 'MachineInfo',
   'data': { 'name': 'str', '*alias': 'str',
             '*is-default': 'bool', 'cpu-max': 'int',
-            'hotpluggable-cpus': 'bool'} }
+            'hotpluggable-cpus': 'bool',
+            'support-status': 'SupportStatusInfo' } }
 
 ##
 # @query-machines:
diff --git a/vl.c b/vl.c
index 99b857ed2a..ca23d2a404 100644
--- a/vl.c
+++ b/vl.c
@@ -1530,6 +1530,12 @@ MachineInfoList *qmp_query_machines(Error **errp)
         info->name = g_strdup(mc->name);
         info->cpu_max = !mc->max_cpus ? 1 : mc->max_cpus;
         info->hotpluggable_cpus = mc->has_hotpluggable_cpus;
+        assert(!mc->support_status.status_message ||
+               mc->support_status.has_status_message);
+        assert(!mc->support_status.suggested_alternative ||
+               mc->support_status.has_suggested_alternative);
+        info->support_status =
+            QAPI_CLONE(SupportStatusInfo, &mc->support_status);
 
         entry = g_malloc0(sizeof(*entry));
         entry->value = info;
diff --git a/tests/acceptance/query_machines.py b/tests/acceptance/query_machines.py
new file mode 100644
index 0000000000..23a56ea617
--- /dev/null
+++ b/tests/acceptance/query_machines.py
@@ -0,0 +1,27 @@
+# Sanity check query-machines QMP command results
+#
+# Copyright (c) 2019 Red Hat, Inc.
+#
+# Author:
+#  Eduardo Habkost <ehabkost@redhat.com>
+#
+# This work is licensed under the terms of the GNU GPL, version 2 or
+# later.  See the COPYING file in the top-level directory.
+
+from avocado_qemu import Test
+
+class QueryMachines(Test):
+    def test(self):
+        self.vm.launch()
+        machines = self.vm.command('query-machines')
+        machinesdict = dict((m['name'], m) for m in machines)
+        machinesdict.update((m['alias'], m) for m in machines if 'alias' in m)
+        for machine in machines:
+            status = machine['support-status']
+            if status['deprecated']:
+                self.assertTrue(status.get('status-message') or \
+                                status.get('suggested-alternative'),
+                                "Deprecated machine (%s) must have status-message or suggested-alternative" % (machine['name']))
+            if 'suggested-alternative' in status:
+                self.assertTrue(status['suggested-alternative'] in machinesdict,
+                                "suggested-alternative of %s must point to a valid machine type" % (machine['name']))
-- 
2.18.0.rc1.1.g3f1ff2140

[Qemu-devel] [PATCH 3/3] qmp: Add deprecation information to query-machines

[Eduardo Habkost]

Export machine type deprecation information through the
query-machines QMP command.  With this, libvirt and management
software will be able to show this information to users and/or
suggest changes to VM configuration to avoid deprecated machines.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 qapi/misc.json                     |  5 ++++-
 vl.c                               |  6 ++++++
 tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
 3 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 tests/acceptance/query_machines.py

diff --git a/qapi/misc.json b/qapi/misc.json
index 8b3ca4fdd3..941d251d17 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -2018,12 +2018,15 @@
 #
 # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
 #
+# @support-status: Support/deprecation status information (since 4.1.0)
+#
 # Since: 1.2.0
 ##
 { 'struct': 'MachineInfo',
   'data': { 'name': 'str', '*alias': 'str',
             '*is-default': 'bool', 'cpu-max': 'int',
-            'hotpluggable-cpus': 'bool'} }
+            'hotpluggable-cpus': 'bool',
+            'support-status': 'SupportStatusInfo' } }
 
 ##
 # @query-machines:
diff --git a/vl.c b/vl.c
index 99b857ed2a..ca23d2a404 100644
--- a/vl.c
+++ b/vl.c
@@ -1530,6 +1530,12 @@ MachineInfoList *qmp_query_machines(Error **errp)
         info->name = g_strdup(mc->name);
         info->cpu_max = !mc->max_cpus ? 1 : mc->max_cpus;
         info->hotpluggable_cpus = mc->has_hotpluggable_cpus;
+        assert(!mc->support_status.status_message ||
+               mc->support_status.has_status_message);
+        assert(!mc->support_status.suggested_alternative ||
+               mc->support_status.has_suggested_alternative);
+        info->support_status =
+            QAPI_CLONE(SupportStatusInfo, &mc->support_status);
 
         entry = g_malloc0(sizeof(*entry));
         entry->value = info;
diff --git a/tests/acceptance/query_machines.py b/tests/acceptance/query_machines.py
new file mode 100644
index 0000000000..23a56ea617
--- /dev/null
+++ b/tests/acceptance/query_machines.py
@@ -0,0 +1,27 @@
+# Sanity check query-machines QMP command results
+#
+# Copyright (c) 2019 Red Hat, Inc.
+#
+# Author:
+#  Eduardo Habkost <ehabkost@redhat.com>
+#
+# This work is licensed under the terms of the GNU GPL, version 2 or
+# later.  See the COPYING file in the top-level directory.
+
+from avocado_qemu import Test
+
+class QueryMachines(Test):
+    def test(self):
+        self.vm.launch()
+        machines = self.vm.command('query-machines')
+        machinesdict = dict((m['name'], m) for m in machines)
+        machinesdict.update((m['alias'], m) for m in machines if 'alias' in m)
+        for machine in machines:
+            status = machine['support-status']
+            if status['deprecated']:
+                self.assertTrue(status.get('status-message') or \
+                                status.get('suggested-alternative'),
+                                "Deprecated machine (%s) must have status-message or suggested-alternative" % (machine['name']))
+            if 'suggested-alternative' in status:
+                self.assertTrue(status['suggested-alternative'] in machinesdict,
+                                "suggested-alternative of %s must point to a valid machine type" % (machine['name']))
-- 
2.18.0.rc1.1.g3f1ff2140

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190423212246.3542-1-ehabkost@redhat.com/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Type: series
Message-id: 20190423212246.3542-1-ehabkost@redhat.com
Subject: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190416125744.27770-1-peter.maydell@linaro.org -> patchew/20190416125744.27770-1-peter.maydell@linaro.org
 t [tag update]            patchew/20190418113110.160664-1-borntraeger@de.ibm.com -> patchew/20190418113110.160664-1-borntraeger@de.ibm.com
 t [tag update]            patchew/20190420073442.7488-1-richard.henderson@linaro.org -> patchew/20190420073442.7488-1-richard.henderson@linaro.org
 t [tag update]            patchew/20190422195020.1494-1-philmd@redhat.com -> patchew/20190422195020.1494-1-philmd@redhat.com
 t [tag update]            patchew/20190422221714.7630-1-jsnow@redhat.com -> patchew/20190422221714.7630-1-jsnow@redhat.com
 t [tag update]            patchew/20190423160608.7519-1-thuth@redhat.com -> patchew/20190423160608.7519-1-thuth@redhat.com
 * [new tag]               patchew/20190423212246.3542-1-ehabkost@redhat.com -> patchew/20190423212246.3542-1-ehabkost@redhat.com
Switched to a new branch 'test'
29e2716a80 qmp: Add deprecation information to query-machines
34cb9a3b70 machine: Use SupportStatusInfo for deprecation info
b44b7a4718 qapi: SupportStatusInfo struct

=== OUTPUT BEGIN ===
1/3 Checking commit b44b7a47188e (qapi: SupportStatusInfo struct)
2/3 Checking commit 34cb9a3b7083 (machine: Use SupportStatusInfo for deprecation info)
3/3 Checking commit 29e2716a80c8 (qmp: Add deprecation information to query-machines)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#37: 
new file mode 100644

ERROR: line over 90 characters
#65: FILE: tests/acceptance/query_machines.py:24:
+                                "Deprecated machine (%s) must have status-message or suggested-alternative" % (machine['name']))

ERROR: line over 90 characters
#68: FILE: tests/acceptance/query_machines.py:27:
+                                "suggested-alternative of %s must point to a valid machine type" % (machine['name']))

total: 2 errors, 1 warnings, 55 lines checked

Patch 3/3 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.

=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190423212246.3542-1-ehabkost@redhat.com/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[no-reply]

Patchew URL: https://patchew.org/QEMU/20190423212246.3542-1-ehabkost@redhat.com/



Hi,

This series seems to have some coding style problems. See output below for
more information:

Type: series
Message-id: 20190423212246.3542-1-ehabkost@redhat.com
Subject: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===

Updating 3c8cf5a9c21ff8782164d1def7f44bd888713384
From https://github.com/patchew-project/qemu
 t [tag update]            patchew/20190416125744.27770-1-peter.maydell@linaro.org -> patchew/20190416125744.27770-1-peter.maydell@linaro.org
 t [tag update]            patchew/20190418113110.160664-1-borntraeger@de.ibm.com -> patchew/20190418113110.160664-1-borntraeger@de.ibm.com
 t [tag update]            patchew/20190420073442.7488-1-richard.henderson@linaro.org -> patchew/20190420073442.7488-1-richard.henderson@linaro.org
 t [tag update]            patchew/20190422195020.1494-1-philmd@redhat.com -> patchew/20190422195020.1494-1-philmd@redhat.com
 t [tag update]            patchew/20190422221714.7630-1-jsnow@redhat.com -> patchew/20190422221714.7630-1-jsnow@redhat.com
 t [tag update]            patchew/20190423160608.7519-1-thuth@redhat.com -> patchew/20190423160608.7519-1-thuth@redhat.com
 * [new tag]               patchew/20190423212246.3542-1-ehabkost@redhat.com -> patchew/20190423212246.3542-1-ehabkost@redhat.com
Switched to a new branch 'test'
29e2716a80 qmp: Add deprecation information to query-machines
34cb9a3b70 machine: Use SupportStatusInfo for deprecation info
b44b7a4718 qapi: SupportStatusInfo struct

=== OUTPUT BEGIN ===
1/3 Checking commit b44b7a47188e (qapi: SupportStatusInfo struct)
2/3 Checking commit 34cb9a3b7083 (machine: Use SupportStatusInfo for deprecation info)
3/3 Checking commit 29e2716a80c8 (qmp: Add deprecation information to query-machines)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#37: 
new file mode 100644

ERROR: line over 90 characters
#65: FILE: tests/acceptance/query_machines.py:24:
+                                "Deprecated machine (%s) must have status-message or suggested-alternative" % (machine['name']))

ERROR: line over 90 characters
#68: FILE: tests/acceptance/query_machines.py:27:
+                                "suggested-alternative of %s must point to a valid machine type" % (machine['name']))

total: 2 errors, 1 warnings, 55 lines checked

Patch 3/3 has style problems, please review.  If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.

=== OUTPUT END ===

Test command exited with code: 1


The full log is available at
http://patchew.org/logs/20190423212246.3542-1-ehabkost@redhat.com/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Philippe Mathieu-Daudé]

Hi Eduardo,

On 4/23/19 11:22 PM, Eduardo Habkost wrote:
> This struct will be used to represent support and deprecation
> status of QEMU features.

Excellent idea!

> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  qapi/common.json | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
> 
> diff --git a/qapi/common.json b/qapi/common.json
> index 99d313ef3b..b59d0dc66b 100644
> --- a/qapi/common.json
> +++ b/qapi/common.json
> @@ -193,3 +193,27 @@
>               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
>               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
>               'x86_64', 'xtensa', 'xtensaeb' ] }
> +
> +##
> +# @SupportStatusInfo:
> +#
> +# Information on support status of a given feature
> +# (e.g. machine type)

Hopefully it is generic, we can use it for devices too.

> +#
> +# @deprecated: if true, the given feature is deprecated and may be removed
> +#              in future versions of QEMU according to the QEMU deprecation
> +#              policy.
> +#
> +# @status-message: Human readable message describing support status
> +#                  of the feature.
> +#
> +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> +#                         feature.  For machine types, this should be the name
> +#                         of an available machine-type.
> +#
> +# Since: 4.1
> +##
> +{ 'struct': 'SupportStatusInfo',
> +  'data': { 'deprecated': 'bool',
> +            '*status-message': 'str',

This one shouldn't be optional IMHO, we should enforce developpers to
give a reason for their deprecation.

With this argument not optional:

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

> +            '*suggested-alternative': 'str' } }
> 

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Philippe Mathieu-Daudé]

On 4/23/19 11:22 PM, Eduardo Habkost wrote:
> Use SupportStatusInfo to represent deprecation information of
> machine types.
> 
> Instead of using a generic "use XXX instead" message for humans,
> encode the suggested alternative in a machine-friendly way at the
> 'suggested_alternatives' field.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  include/hw/boards.h |  7 ++++---
>  hw/i386/pc_piix.c   |  4 +++-
>  hw/ppc/prep.c       |  4 +++-
>  vl.c                | 13 +++++++++----
>  4 files changed, 19 insertions(+), 9 deletions(-)
> 
> diff --git a/include/hw/boards.h b/include/hw/boards.h
> index e231860666..243bf3c7ce 100644
> --- a/include/hw/boards.h
> +++ b/include/hw/boards.h
> @@ -8,6 +8,8 @@
>  #include "hw/qdev.h"
>  #include "qom/object.h"
>  #include "qom/cpu.h"
> +#include "qapi/qapi-types-common.h"
> +
>  
>  /**
>   * memory_region_allocate_system_memory - Allocate a board's main memory
> @@ -105,8 +107,7 @@ typedef struct {
>  
>  /**
>   * MachineClass:
> - * @deprecation_reason: If set, the machine is marked as deprecated. The
> - *    string should provide some clear information about what to use instead.
> + * @support_status: Support and deprecation status of machine type.
>   * @max_cpus: maximum number of CPUs supported. Default: 1
>   * @min_cpus: minimum number of CPUs supported. Default: 1
>   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> @@ -169,7 +170,7 @@ struct MachineClass {
>      char *name;
>      const char *alias;
>      const char *desc;
> -    const char *deprecation_reason;
> +    SupportStatusInfo support_status;
>  
>      void (*init)(MachineState *state);
>      void (*reset)(void);
> diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> index 8ad8e885c6..97bd401618 100644
> --- a/hw/i386/pc_piix.c
> +++ b/hw/i386/pc_piix.c
> @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
>  
>      pc_i440fx_1_0_machine_options(m);
>      m->hw_version = "0.15";
> -    m->deprecation_reason = "use a newer machine type instead";
> +    m->support_status.deprecated = true;
> +    m->support_status.has_suggested_alternative = true;
> +    m->support_status.suggested_alternative = g_strdup("pc");
>      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
>  }
>  
> diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> index 847d320465..9a02b0eec4 100644
> --- a/hw/ppc/prep.c
> +++ b/hw/ppc/prep.c
> @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
>  
>  static void prep_machine_init(MachineClass *mc)
>  {
> -    mc->deprecation_reason = "use 40p machine type instead";
> +    mc->support_status.deprecated = true;
> +    mc->support_status.has_suggested_alternative = true;
> +    mc->support_status.suggested_alternative = g_strdup("40p");
>      mc->desc = "PowerPC PREP platform";
>      mc->init = ppc_prep_init;
>      mc->block_default_type = IF_IDE;
> diff --git a/vl.c b/vl.c
> index c696ad2a13..99b857ed2a 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
>              }
>              printf("%-20s %s%s%s\n", mc->name, mc->desc,
>                     mc->is_default ? " (default)" : "",
> -                   mc->deprecation_reason ? " (deprecated)" : "");
> +                   mc->support_status.deprecated ? " (deprecated)" : "");
>          }
>      }
>  
> @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
>       * called from configure_accelerator().
>       */
>  
> -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> -        error_report("Machine type '%s' is deprecated: %s",
> -                     machine_class->name, machine_class->deprecation_reason);
> +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> +                     machine_class->support_status.status_message ? ": " : "",
> +                     machine_class->support_status.status_message ?: "");
> +        if (machine_class->support_status.suggested_alternative) {
> +            error_report("Suggested solution: use '%s' machine type instead",

Maybe "Recommended alternative:"?
(Also consider renaming the SupportStatusInfo.suggested_alternative field).

> +                         machine_class->support_status.suggested_alternative);
> +        }
>      }
>  
>      /*
> 

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Philippe Mathieu-Daudé]

On 4/23/19 11:22 PM, Eduardo Habkost wrote:
> Use SupportStatusInfo to represent deprecation information of
> machine types.
> 
> Instead of using a generic "use XXX instead" message for humans,
> encode the suggested alternative in a machine-friendly way at the
> 'suggested_alternatives' field.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  include/hw/boards.h |  7 ++++---
>  hw/i386/pc_piix.c   |  4 +++-
>  hw/ppc/prep.c       |  4 +++-
>  vl.c                | 13 +++++++++----
>  4 files changed, 19 insertions(+), 9 deletions(-)
> 
> diff --git a/include/hw/boards.h b/include/hw/boards.h
> index e231860666..243bf3c7ce 100644
> --- a/include/hw/boards.h
> +++ b/include/hw/boards.h
> @@ -8,6 +8,8 @@
>  #include "hw/qdev.h"
>  #include "qom/object.h"
>  #include "qom/cpu.h"
> +#include "qapi/qapi-types-common.h"
> +
>  
>  /**
>   * memory_region_allocate_system_memory - Allocate a board's main memory
> @@ -105,8 +107,7 @@ typedef struct {
>  
>  /**
>   * MachineClass:
> - * @deprecation_reason: If set, the machine is marked as deprecated. The
> - *    string should provide some clear information about what to use instead.
> + * @support_status: Support and deprecation status of machine type.
>   * @max_cpus: maximum number of CPUs supported. Default: 1
>   * @min_cpus: minimum number of CPUs supported. Default: 1
>   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> @@ -169,7 +170,7 @@ struct MachineClass {
>      char *name;
>      const char *alias;
>      const char *desc;
> -    const char *deprecation_reason;
> +    SupportStatusInfo support_status;
>  
>      void (*init)(MachineState *state);
>      void (*reset)(void);
> diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> index 8ad8e885c6..97bd401618 100644
> --- a/hw/i386/pc_piix.c
> +++ b/hw/i386/pc_piix.c
> @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
>  
>      pc_i440fx_1_0_machine_options(m);
>      m->hw_version = "0.15";
> -    m->deprecation_reason = "use a newer machine type instead";
> +    m->support_status.deprecated = true;
> +    m->support_status.has_suggested_alternative = true;
> +    m->support_status.suggested_alternative = g_strdup("pc");
>      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
>  }
>  
> diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> index 847d320465..9a02b0eec4 100644
> --- a/hw/ppc/prep.c
> +++ b/hw/ppc/prep.c
> @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
>  
>  static void prep_machine_init(MachineClass *mc)
>  {
> -    mc->deprecation_reason = "use 40p machine type instead";
> +    mc->support_status.deprecated = true;
> +    mc->support_status.has_suggested_alternative = true;
> +    mc->support_status.suggested_alternative = g_strdup("40p");
>      mc->desc = "PowerPC PREP platform";
>      mc->init = ppc_prep_init;
>      mc->block_default_type = IF_IDE;
> diff --git a/vl.c b/vl.c
> index c696ad2a13..99b857ed2a 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
>              }
>              printf("%-20s %s%s%s\n", mc->name, mc->desc,
>                     mc->is_default ? " (default)" : "",
> -                   mc->deprecation_reason ? " (deprecated)" : "");
> +                   mc->support_status.deprecated ? " (deprecated)" : "");
>          }
>      }
>  
> @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
>       * called from configure_accelerator().
>       */
>  
> -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> -        error_report("Machine type '%s' is deprecated: %s",
> -                     machine_class->name, machine_class->deprecation_reason);
> +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> +                     machine_class->support_status.status_message ? ": " : "",
> +                     machine_class->support_status.status_message ?: "");
> +        if (machine_class->support_status.suggested_alternative) {
> +            error_report("Suggested solution: use '%s' machine type instead",

Maybe "Recommended alternative:"?
(Also consider renaming the SupportStatusInfo.suggested_alternative field).

> +                         machine_class->support_status.suggested_alternative);
> +        }
>      }
>  
>      /*
> 

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[David Gibson]

[-- Attachment #1: Type: text/plain, Size: 4750 bytes --]

On Tue, Apr 23, 2019 at 06:22:45PM -0300, Eduardo Habkost wrote:
> Use SupportStatusInfo to represent deprecation information of
> machine types.
> 
> Instead of using a generic "use XXX instead" message for humans,
> encode the suggested alternative in a machine-friendly way at the
> 'suggested_alternatives' field.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>

ppc parts

Acked-by: David Gibson <david@gibson.dropbear.id.au>

> ---
>  include/hw/boards.h |  7 ++++---
>  hw/i386/pc_piix.c   |  4 +++-
>  hw/ppc/prep.c       |  4 +++-
>  vl.c                | 13 +++++++++----
>  4 files changed, 19 insertions(+), 9 deletions(-)
> 
> diff --git a/include/hw/boards.h b/include/hw/boards.h
> index e231860666..243bf3c7ce 100644
> --- a/include/hw/boards.h
> +++ b/include/hw/boards.h
> @@ -8,6 +8,8 @@
>  #include "hw/qdev.h"
>  #include "qom/object.h"
>  #include "qom/cpu.h"
> +#include "qapi/qapi-types-common.h"
> +
>  
>  /**
>   * memory_region_allocate_system_memory - Allocate a board's main memory
> @@ -105,8 +107,7 @@ typedef struct {
>  
>  /**
>   * MachineClass:
> - * @deprecation_reason: If set, the machine is marked as deprecated. The
> - *    string should provide some clear information about what to use instead.
> + * @support_status: Support and deprecation status of machine type.
>   * @max_cpus: maximum number of CPUs supported. Default: 1
>   * @min_cpus: minimum number of CPUs supported. Default: 1
>   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> @@ -169,7 +170,7 @@ struct MachineClass {
>      char *name;
>      const char *alias;
>      const char *desc;
> -    const char *deprecation_reason;
> +    SupportStatusInfo support_status;
>  
>      void (*init)(MachineState *state);
>      void (*reset)(void);
> diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> index 8ad8e885c6..97bd401618 100644
> --- a/hw/i386/pc_piix.c
> +++ b/hw/i386/pc_piix.c
> @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
>  
>      pc_i440fx_1_0_machine_options(m);
>      m->hw_version = "0.15";
> -    m->deprecation_reason = "use a newer machine type instead";
> +    m->support_status.deprecated = true;
> +    m->support_status.has_suggested_alternative = true;
> +    m->support_status.suggested_alternative = g_strdup("pc");
>      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
>  }
>  
> diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> index 847d320465..9a02b0eec4 100644
> --- a/hw/ppc/prep.c
> +++ b/hw/ppc/prep.c
> @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
>  
>  static void prep_machine_init(MachineClass *mc)
>  {
> -    mc->deprecation_reason = "use 40p machine type instead";
> +    mc->support_status.deprecated = true;
> +    mc->support_status.has_suggested_alternative = true;
> +    mc->support_status.suggested_alternative = g_strdup("40p");
>      mc->desc = "PowerPC PREP platform";
>      mc->init = ppc_prep_init;
>      mc->block_default_type = IF_IDE;
> diff --git a/vl.c b/vl.c
> index c696ad2a13..99b857ed2a 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
>              }
>              printf("%-20s %s%s%s\n", mc->name, mc->desc,
>                     mc->is_default ? " (default)" : "",
> -                   mc->deprecation_reason ? " (deprecated)" : "");
> +                   mc->support_status.deprecated ? " (deprecated)" : "");
>          }
>      }
>  
> @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
>       * called from configure_accelerator().
>       */
>  
> -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> -        error_report("Machine type '%s' is deprecated: %s",
> -                     machine_class->name, machine_class->deprecation_reason);
> +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> +                     machine_class->support_status.status_message ? ": " : "",
> +                     machine_class->support_status.status_message ?: "");
> +        if (machine_class->support_status.suggested_alternative) {
> +            error_report("Suggested solution: use '%s' machine type instead",
> +                         machine_class->support_status.suggested_alternative);
> +        }
>      }
>  
>      /*

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[David Gibson]

[-- Attachment #1: Type: text/plain, Size: 4750 bytes --]

On Tue, Apr 23, 2019 at 06:22:45PM -0300, Eduardo Habkost wrote:
> Use SupportStatusInfo to represent deprecation information of
> machine types.
> 
> Instead of using a generic "use XXX instead" message for humans,
> encode the suggested alternative in a machine-friendly way at the
> 'suggested_alternatives' field.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>

ppc parts

Acked-by: David Gibson <david@gibson.dropbear.id.au>

> ---
>  include/hw/boards.h |  7 ++++---
>  hw/i386/pc_piix.c   |  4 +++-
>  hw/ppc/prep.c       |  4 +++-
>  vl.c                | 13 +++++++++----
>  4 files changed, 19 insertions(+), 9 deletions(-)
> 
> diff --git a/include/hw/boards.h b/include/hw/boards.h
> index e231860666..243bf3c7ce 100644
> --- a/include/hw/boards.h
> +++ b/include/hw/boards.h
> @@ -8,6 +8,8 @@
>  #include "hw/qdev.h"
>  #include "qom/object.h"
>  #include "qom/cpu.h"
> +#include "qapi/qapi-types-common.h"
> +
>  
>  /**
>   * memory_region_allocate_system_memory - Allocate a board's main memory
> @@ -105,8 +107,7 @@ typedef struct {
>  
>  /**
>   * MachineClass:
> - * @deprecation_reason: If set, the machine is marked as deprecated. The
> - *    string should provide some clear information about what to use instead.
> + * @support_status: Support and deprecation status of machine type.
>   * @max_cpus: maximum number of CPUs supported. Default: 1
>   * @min_cpus: minimum number of CPUs supported. Default: 1
>   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> @@ -169,7 +170,7 @@ struct MachineClass {
>      char *name;
>      const char *alias;
>      const char *desc;
> -    const char *deprecation_reason;
> +    SupportStatusInfo support_status;
>  
>      void (*init)(MachineState *state);
>      void (*reset)(void);
> diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> index 8ad8e885c6..97bd401618 100644
> --- a/hw/i386/pc_piix.c
> +++ b/hw/i386/pc_piix.c
> @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
>  
>      pc_i440fx_1_0_machine_options(m);
>      m->hw_version = "0.15";
> -    m->deprecation_reason = "use a newer machine type instead";
> +    m->support_status.deprecated = true;
> +    m->support_status.has_suggested_alternative = true;
> +    m->support_status.suggested_alternative = g_strdup("pc");
>      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
>  }
>  
> diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> index 847d320465..9a02b0eec4 100644
> --- a/hw/ppc/prep.c
> +++ b/hw/ppc/prep.c
> @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
>  
>  static void prep_machine_init(MachineClass *mc)
>  {
> -    mc->deprecation_reason = "use 40p machine type instead";
> +    mc->support_status.deprecated = true;
> +    mc->support_status.has_suggested_alternative = true;
> +    mc->support_status.suggested_alternative = g_strdup("40p");
>      mc->desc = "PowerPC PREP platform";
>      mc->init = ppc_prep_init;
>      mc->block_default_type = IF_IDE;
> diff --git a/vl.c b/vl.c
> index c696ad2a13..99b857ed2a 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
>              }
>              printf("%-20s %s%s%s\n", mc->name, mc->desc,
>                     mc->is_default ? " (default)" : "",
> -                   mc->deprecation_reason ? " (deprecated)" : "");
> +                   mc->support_status.deprecated ? " (deprecated)" : "");
>          }
>      }
>  
> @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
>       * called from configure_accelerator().
>       */
>  
> -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> -        error_report("Machine type '%s' is deprecated: %s",
> -                     machine_class->name, machine_class->deprecation_reason);
> +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> +                     machine_class->support_status.status_message ? ": " : "",
> +                     machine_class->support_status.status_message ?: "");
> +        if (machine_class->support_status.suggested_alternative) {
> +            error_report("Suggested solution: use '%s' machine type instead",
> +                         machine_class->support_status.suggested_alternative);
> +        }
>      }
>  
>      /*

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Thomas Huth]

On 23/04/2019 23.22, Eduardo Habkost wrote:
> This series adds machine type deprecation information to the
> output of the `query-machines` QMP command.  With this, libvirt
> and management software will be able to show this information to
> users and/or suggest changes to VM configuration to avoid
> deprecated machine types.
> 
> Eduardo Habkost (3):
>   qapi: SupportStatusInfo struct
>   machine: Use SupportStatusInfo for deprecation info
>   qmp: Add deprecation information to query-machines
> 
>  qapi/common.json                   | 24 ++++++++++++++++++++++++
>  qapi/misc.json                     |  5 ++++-
>  include/hw/boards.h                |  7 ++++---
>  hw/i386/pc_piix.c                  |  4 +++-
>  hw/ppc/prep.c                      |  4 +++-
>  vl.c                               | 19 +++++++++++++++----
>  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>  7 files changed, 80 insertions(+), 10 deletions(-)
>  create mode 100644 tests/acceptance/query_machines.py

Good idea, but some questions come to my mind:

- What about devices? IIRC Gerd wrote a patch series last year that does
  something similar for devices... It would be good to synchronize the
  work, so that we do not have two completely interfaces between devices
  and machines here in the end...

- Is deprecation as a status enough, or do we want to carry more
  information here? E.g. is the machine maintained or orphan? Is it
  stable or rather experimental? And didn't Gerd have also some
  patches for this last year? ... yes, I think it was this series here:
  http://lists.gnu.org/archive/html/qemu-ppc/2018-11/msg00039.html
  ... actually, I like that idea with QemuSupportState... maybe you
  could base your work on that series instead?

 Thomas

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Michal Privoznik]

On 4/23/19 11:22 PM, Eduardo Habkost wrote:
> This series adds machine type deprecation information to the
> output of the `query-machines` QMP command.  With this, libvirt
> and management software will be able to show this information to
> users and/or suggest changes to VM configuration to avoid
> deprecated machine types.
> 
> Eduardo Habkost (3):
>    qapi: SupportStatusInfo struct
>    machine: Use SupportStatusInfo for deprecation info
>    qmp: Add deprecation information to query-machines
> 
>   qapi/common.json                   | 24 ++++++++++++++++++++++++
>   qapi/misc.json                     |  5 ++++-
>   include/hw/boards.h                |  7 ++++---
>   hw/i386/pc_piix.c                  |  4 +++-
>   hw/ppc/prep.c                      |  4 +++-
>   vl.c                               | 19 +++++++++++++++----
>   tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>   7 files changed, 80 insertions(+), 10 deletions(-)
>   create mode 100644 tests/acceptance/query_machines.py
> 

ACK.

Now we need to think how to deal with this in libvirt. Whether it's 
sufficient to expose this in capabilities XML or libvirt needs to do 
something more.

Michal

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Michal Privoznik]

On 4/23/19 11:22 PM, Eduardo Habkost wrote:
> This series adds machine type deprecation information to the
> output of the `query-machines` QMP command.  With this, libvirt
> and management software will be able to show this information to
> users and/or suggest changes to VM configuration to avoid
> deprecated machine types.
> 
> Eduardo Habkost (3):
>    qapi: SupportStatusInfo struct
>    machine: Use SupportStatusInfo for deprecation info
>    qmp: Add deprecation information to query-machines
> 
>   qapi/common.json                   | 24 ++++++++++++++++++++++++
>   qapi/misc.json                     |  5 ++++-
>   include/hw/boards.h                |  7 ++++---
>   hw/i386/pc_piix.c                  |  4 +++-
>   hw/ppc/prep.c                      |  4 +++-
>   vl.c                               | 19 +++++++++++++++----
>   tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>   7 files changed, 80 insertions(+), 10 deletions(-)
>   create mode 100644 tests/acceptance/query_machines.py
> 

ACK.

Now we need to think how to deal with this in libvirt. Whether it's 
sufficient to expose this in capabilities XML or libvirt needs to do 
something more.

Michal

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Daniel P. Berrangé]

On Tue, Apr 23, 2019 at 06:22:45PM -0300, Eduardo Habkost wrote:
> Use SupportStatusInfo to represent deprecation information of
> machine types.
> 
> Instead of using a generic "use XXX instead" message for humans,
> encode the suggested alternative in a machine-friendly way at the
> 'suggested_alternatives' field.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  include/hw/boards.h |  7 ++++---
>  hw/i386/pc_piix.c   |  4 +++-
>  hw/ppc/prep.c       |  4 +++-
>  vl.c                | 13 +++++++++----
>  4 files changed, 19 insertions(+), 9 deletions(-)
> 
> diff --git a/include/hw/boards.h b/include/hw/boards.h
> index e231860666..243bf3c7ce 100644
> --- a/include/hw/boards.h
> +++ b/include/hw/boards.h
> @@ -8,6 +8,8 @@
>  #include "hw/qdev.h"
>  #include "qom/object.h"
>  #include "qom/cpu.h"
> +#include "qapi/qapi-types-common.h"
> +
>  
>  /**
>   * memory_region_allocate_system_memory - Allocate a board's main memory
> @@ -105,8 +107,7 @@ typedef struct {
>  
>  /**
>   * MachineClass:
> - * @deprecation_reason: If set, the machine is marked as deprecated. The
> - *    string should provide some clear information about what to use instead.
> + * @support_status: Support and deprecation status of machine type.
>   * @max_cpus: maximum number of CPUs supported. Default: 1
>   * @min_cpus: minimum number of CPUs supported. Default: 1
>   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> @@ -169,7 +170,7 @@ struct MachineClass {
>      char *name;
>      const char *alias;
>      const char *desc;
> -    const char *deprecation_reason;
> +    SupportStatusInfo support_status;
>  
>      void (*init)(MachineState *state);
>      void (*reset)(void);
> diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> index 8ad8e885c6..97bd401618 100644
> --- a/hw/i386/pc_piix.c
> +++ b/hw/i386/pc_piix.c
> @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
>  
>      pc_i440fx_1_0_machine_options(m);
>      m->hw_version = "0.15";
> -    m->deprecation_reason = "use a newer machine type instead";
> +    m->support_status.deprecated = true;
> +    m->support_status.has_suggested_alternative = true;
> +    m->support_status.suggested_alternative = g_strdup("pc");
>      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
>  }
>  
> diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> index 847d320465..9a02b0eec4 100644
> --- a/hw/ppc/prep.c
> +++ b/hw/ppc/prep.c
> @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
>  
>  static void prep_machine_init(MachineClass *mc)
>  {
> -    mc->deprecation_reason = "use 40p machine type instead";
> +    mc->support_status.deprecated = true;
> +    mc->support_status.has_suggested_alternative = true;
> +    mc->support_status.suggested_alternative = g_strdup("40p");
>      mc->desc = "PowerPC PREP platform";
>      mc->init = ppc_prep_init;
>      mc->block_default_type = IF_IDE;
> diff --git a/vl.c b/vl.c
> index c696ad2a13..99b857ed2a 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
>              }
>              printf("%-20s %s%s%s\n", mc->name, mc->desc,
>                     mc->is_default ? " (default)" : "",
> -                   mc->deprecation_reason ? " (deprecated)" : "");
> +                   mc->support_status.deprecated ? " (deprecated)" : "");
>          }
>      }
>  
> @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
>       * called from configure_accelerator().
>       */
>  
> -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> -        error_report("Machine type '%s' is deprecated: %s",
> -                     machine_class->name, machine_class->deprecation_reason);
> +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> +                     machine_class->support_status.status_message ? ": " : "",
> +                     machine_class->support_status.status_message ?: "");
> +        if (machine_class->support_status.suggested_alternative) {
> +            error_report("Suggested solution: use '%s' machine type instead",
> +                         machine_class->support_status.suggested_alternative);

I'd just drop the word "Suggested solution: " as I think it is fine to just
say "Use foobar machine type instead".


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 :|

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Daniel P. Berrangé]

On Tue, Apr 23, 2019 at 06:22:45PM -0300, Eduardo Habkost wrote:
> Use SupportStatusInfo to represent deprecation information of
> machine types.
> 
> Instead of using a generic "use XXX instead" message for humans,
> encode the suggested alternative in a machine-friendly way at the
> 'suggested_alternatives' field.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  include/hw/boards.h |  7 ++++---
>  hw/i386/pc_piix.c   |  4 +++-
>  hw/ppc/prep.c       |  4 +++-
>  vl.c                | 13 +++++++++----
>  4 files changed, 19 insertions(+), 9 deletions(-)
> 
> diff --git a/include/hw/boards.h b/include/hw/boards.h
> index e231860666..243bf3c7ce 100644
> --- a/include/hw/boards.h
> +++ b/include/hw/boards.h
> @@ -8,6 +8,8 @@
>  #include "hw/qdev.h"
>  #include "qom/object.h"
>  #include "qom/cpu.h"
> +#include "qapi/qapi-types-common.h"
> +
>  
>  /**
>   * memory_region_allocate_system_memory - Allocate a board's main memory
> @@ -105,8 +107,7 @@ typedef struct {
>  
>  /**
>   * MachineClass:
> - * @deprecation_reason: If set, the machine is marked as deprecated. The
> - *    string should provide some clear information about what to use instead.
> + * @support_status: Support and deprecation status of machine type.
>   * @max_cpus: maximum number of CPUs supported. Default: 1
>   * @min_cpus: minimum number of CPUs supported. Default: 1
>   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> @@ -169,7 +170,7 @@ struct MachineClass {
>      char *name;
>      const char *alias;
>      const char *desc;
> -    const char *deprecation_reason;
> +    SupportStatusInfo support_status;
>  
>      void (*init)(MachineState *state);
>      void (*reset)(void);
> diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> index 8ad8e885c6..97bd401618 100644
> --- a/hw/i386/pc_piix.c
> +++ b/hw/i386/pc_piix.c
> @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
>  
>      pc_i440fx_1_0_machine_options(m);
>      m->hw_version = "0.15";
> -    m->deprecation_reason = "use a newer machine type instead";
> +    m->support_status.deprecated = true;
> +    m->support_status.has_suggested_alternative = true;
> +    m->support_status.suggested_alternative = g_strdup("pc");
>      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
>  }
>  
> diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> index 847d320465..9a02b0eec4 100644
> --- a/hw/ppc/prep.c
> +++ b/hw/ppc/prep.c
> @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
>  
>  static void prep_machine_init(MachineClass *mc)
>  {
> -    mc->deprecation_reason = "use 40p machine type instead";
> +    mc->support_status.deprecated = true;
> +    mc->support_status.has_suggested_alternative = true;
> +    mc->support_status.suggested_alternative = g_strdup("40p");
>      mc->desc = "PowerPC PREP platform";
>      mc->init = ppc_prep_init;
>      mc->block_default_type = IF_IDE;
> diff --git a/vl.c b/vl.c
> index c696ad2a13..99b857ed2a 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
>              }
>              printf("%-20s %s%s%s\n", mc->name, mc->desc,
>                     mc->is_default ? " (default)" : "",
> -                   mc->deprecation_reason ? " (deprecated)" : "");
> +                   mc->support_status.deprecated ? " (deprecated)" : "");
>          }
>      }
>  
> @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
>       * called from configure_accelerator().
>       */
>  
> -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> -        error_report("Machine type '%s' is deprecated: %s",
> -                     machine_class->name, machine_class->deprecation_reason);
> +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> +                     machine_class->support_status.status_message ? ": " : "",
> +                     machine_class->support_status.status_message ?: "");
> +        if (machine_class->support_status.suggested_alternative) {
> +            error_report("Suggested solution: use '%s' machine type instead",
> +                         machine_class->support_status.suggested_alternative);

I'd just drop the word "Suggested solution: " as I think it is fine to just
say "Use foobar machine type instead".


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 :|

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> This struct will be used to represent support and deprecation
> status of QEMU features.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  qapi/common.json | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
> 
> diff --git a/qapi/common.json b/qapi/common.json
> index 99d313ef3b..b59d0dc66b 100644
> --- a/qapi/common.json
> +++ b/qapi/common.json
> @@ -193,3 +193,27 @@
>               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
>               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
>               'x86_64', 'xtensa', 'xtensaeb' ] }
> +
> +##
> +# @SupportStatusInfo:
> +#
> +# Information on support status of a given feature
> +# (e.g. machine type)
> +#
> +# @deprecated: if true, the given feature is deprecated and may be removed
> +#              in future versions of QEMU according to the QEMU deprecation
> +#              policy.
> +#
> +# @status-message: Human readable message describing support status
> +#                  of the feature.
> +#
> +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> +#                         feature.  For machine types, this should be the name
> +#                         of an available machine-type.
> +#
> +# Since: 4.1
> +##
> +{ 'struct': 'SupportStatusInfo',
> +  'data': { 'deprecated': 'bool',
> +            '*status-message': 'str',
> +            '*suggested-alternative': 'str' } }

I see status-message has to be optional, since you're embedding the
struct into another struct and want deprecated==false by default.

I'd be inclined to change it to embed a pointer to the struct and
drop the deprecated field, and make both status-message and
suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
the pointer to which is NULL if not deprecated.

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 :|

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> This struct will be used to represent support and deprecation
> status of QEMU features.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  qapi/common.json | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
> 
> diff --git a/qapi/common.json b/qapi/common.json
> index 99d313ef3b..b59d0dc66b 100644
> --- a/qapi/common.json
> +++ b/qapi/common.json
> @@ -193,3 +193,27 @@
>               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
>               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
>               'x86_64', 'xtensa', 'xtensaeb' ] }
> +
> +##
> +# @SupportStatusInfo:
> +#
> +# Information on support status of a given feature
> +# (e.g. machine type)
> +#
> +# @deprecated: if true, the given feature is deprecated and may be removed
> +#              in future versions of QEMU according to the QEMU deprecation
> +#              policy.
> +#
> +# @status-message: Human readable message describing support status
> +#                  of the feature.
> +#
> +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> +#                         feature.  For machine types, this should be the name
> +#                         of an available machine-type.
> +#
> +# Since: 4.1
> +##
> +{ 'struct': 'SupportStatusInfo',
> +  'data': { 'deprecated': 'bool',
> +            '*status-message': 'str',
> +            '*suggested-alternative': 'str' } }

I see status-message has to be optional, since you're embedding the
struct into another struct and want deprecated==false by default.

I'd be inclined to change it to embed a pointer to the struct and
drop the deprecated field, and make both status-message and
suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
the pointer to which is NULL if not deprecated.

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 :|

Re: [Qemu-devel] [PATCH 3/3] qmp: Add deprecation information to query-machines

[Daniel P. Berrangé]

On Tue, Apr 23, 2019 at 06:22:46PM -0300, Eduardo Habkost wrote:
> Export machine type deprecation information through the
> query-machines QMP command.  With this, libvirt and management
> software will be able to show this information to users and/or
> suggest changes to VM configuration to avoid deprecated machines.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  qapi/misc.json                     |  5 ++++-
>  vl.c                               |  6 ++++++
>  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>  3 files changed, 37 insertions(+), 1 deletion(-)
>  create mode 100644 tests/acceptance/query_machines.py
> 
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 8b3ca4fdd3..941d251d17 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -2018,12 +2018,15 @@
>  #
>  # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
>  #
> +# @support-status: Support/deprecation status information (since 4.1.0)
> +#
>  # Since: 1.2.0
>  ##
>  { 'struct': 'MachineInfo',
>    'data': { 'name': 'str', '*alias': 'str',
>              '*is-default': 'bool', 'cpu-max': 'int',
> -            'hotpluggable-cpus': 'bool'} }
> +            'hotpluggable-cpus': 'bool',
> +            'support-status': 'SupportStatusInfo' } }

With my comment on the first patch this would become

    "deprecation-info": "*DeprecationInfo"

> diff --git a/vl.c b/vl.c
> index 99b857ed2a..ca23d2a404 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -1530,6 +1530,12 @@ MachineInfoList *qmp_query_machines(Error **errp)
>          info->name = g_strdup(mc->name);
>          info->cpu_max = !mc->max_cpus ? 1 : mc->max_cpus;
>          info->hotpluggable_cpus = mc->has_hotpluggable_cpus;
> +        assert(!mc->support_status.status_message ||
> +               mc->support_status.has_status_message);
> +        assert(!mc->support_status.suggested_alternative ||
> +               mc->support_status.has_suggested_alternative);
> +        info->support_status =
> +            QAPI_CLONE(SupportStatusInfo, &mc->support_status);
>  
>          entry = g_malloc0(sizeof(*entry));
>          entry->value = info;
> diff --git a/tests/acceptance/query_machines.py b/tests/acceptance/query_machines.py
> new file mode 100644
> index 0000000000..23a56ea617
> --- /dev/null
> +++ b/tests/acceptance/query_machines.py
> @@ -0,0 +1,27 @@
> +# Sanity check query-machines QMP command results
> +#
> +# Copyright (c) 2019 Red Hat, Inc.
> +#
> +# Author:
> +#  Eduardo Habkost <ehabkost@redhat.com>
> +#
> +# This work is licensed under the terms of the GNU GPL, version 2 or
> +# later.  See the COPYING file in the top-level directory.
> +
> +from avocado_qemu import Test
> +
> +class QueryMachines(Test):
> +    def test(self):
> +        self.vm.launch()
> +        machines = self.vm.command('query-machines')
> +        machinesdict = dict((m['name'], m) for m in machines)
> +        machinesdict.update((m['alias'], m) for m in machines if 'alias' in m)
> +        for machine in machines:
> +            status = machine['support-status']
> +            if status['deprecated']:
> +                self.assertTrue(status.get('status-message') or \
> +                                status.get('suggested-alternative'),
> +                                "Deprecated machine (%s) must have status-message or suggested-alternative" % (machine['name']))
> +            if 'suggested-alternative' in status:
> +                self.assertTrue(status['suggested-alternative'] in machinesdict,
> +                                "suggested-alternative of %s must point to a valid machine type" % (machine['name']))
> -- 
> 2.18.0.rc1.1.g3f1ff2140
> 
> 

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 :|

Re: [Qemu-devel] [PATCH 3/3] qmp: Add deprecation information to query-machines

[Daniel P. Berrangé]

On Tue, Apr 23, 2019 at 06:22:46PM -0300, Eduardo Habkost wrote:
> Export machine type deprecation information through the
> query-machines QMP command.  With this, libvirt and management
> software will be able to show this information to users and/or
> suggest changes to VM configuration to avoid deprecated machines.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  qapi/misc.json                     |  5 ++++-
>  vl.c                               |  6 ++++++
>  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>  3 files changed, 37 insertions(+), 1 deletion(-)
>  create mode 100644 tests/acceptance/query_machines.py
> 
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 8b3ca4fdd3..941d251d17 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -2018,12 +2018,15 @@
>  #
>  # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
>  #
> +# @support-status: Support/deprecation status information (since 4.1.0)
> +#
>  # Since: 1.2.0
>  ##
>  { 'struct': 'MachineInfo',
>    'data': { 'name': 'str', '*alias': 'str',
>              '*is-default': 'bool', 'cpu-max': 'int',
> -            'hotpluggable-cpus': 'bool'} }
> +            'hotpluggable-cpus': 'bool',
> +            'support-status': 'SupportStatusInfo' } }

With my comment on the first patch this would become

    "deprecation-info": "*DeprecationInfo"

> diff --git a/vl.c b/vl.c
> index 99b857ed2a..ca23d2a404 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -1530,6 +1530,12 @@ MachineInfoList *qmp_query_machines(Error **errp)
>          info->name = g_strdup(mc->name);
>          info->cpu_max = !mc->max_cpus ? 1 : mc->max_cpus;
>          info->hotpluggable_cpus = mc->has_hotpluggable_cpus;
> +        assert(!mc->support_status.status_message ||
> +               mc->support_status.has_status_message);
> +        assert(!mc->support_status.suggested_alternative ||
> +               mc->support_status.has_suggested_alternative);
> +        info->support_status =
> +            QAPI_CLONE(SupportStatusInfo, &mc->support_status);
>  
>          entry = g_malloc0(sizeof(*entry));
>          entry->value = info;
> diff --git a/tests/acceptance/query_machines.py b/tests/acceptance/query_machines.py
> new file mode 100644
> index 0000000000..23a56ea617
> --- /dev/null
> +++ b/tests/acceptance/query_machines.py
> @@ -0,0 +1,27 @@
> +# Sanity check query-machines QMP command results
> +#
> +# Copyright (c) 2019 Red Hat, Inc.
> +#
> +# Author:
> +#  Eduardo Habkost <ehabkost@redhat.com>
> +#
> +# This work is licensed under the terms of the GNU GPL, version 2 or
> +# later.  See the COPYING file in the top-level directory.
> +
> +from avocado_qemu import Test
> +
> +class QueryMachines(Test):
> +    def test(self):
> +        self.vm.launch()
> +        machines = self.vm.command('query-machines')
> +        machinesdict = dict((m['name'], m) for m in machines)
> +        machinesdict.update((m['alias'], m) for m in machines if 'alias' in m)
> +        for machine in machines:
> +            status = machine['support-status']
> +            if status['deprecated']:
> +                self.assertTrue(status.get('status-message') or \
> +                                status.get('suggested-alternative'),
> +                                "Deprecated machine (%s) must have status-message or suggested-alternative" % (machine['name']))
> +            if 'suggested-alternative' in status:
> +                self.assertTrue(status['suggested-alternative'] in machinesdict,
> +                                "suggested-alternative of %s must point to a valid machine type" % (machine['name']))
> -- 
> 2.18.0.rc1.1.g3f1ff2140
> 
> 

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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Daniel P. Berrangé]

On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> On 23/04/2019 23.22, Eduardo Habkost wrote:
> > This series adds machine type deprecation information to the
> > output of the `query-machines` QMP command.  With this, libvirt
> > and management software will be able to show this information to
> > users and/or suggest changes to VM configuration to avoid
> > deprecated machine types.
> > 
> > Eduardo Habkost (3):
> >   qapi: SupportStatusInfo struct
> >   machine: Use SupportStatusInfo for deprecation info
> >   qmp: Add deprecation information to query-machines
> > 
> >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> >  qapi/misc.json                     |  5 ++++-
> >  include/hw/boards.h                |  7 ++++---
> >  hw/i386/pc_piix.c                  |  4 +++-
> >  hw/ppc/prep.c                      |  4 +++-
> >  vl.c                               | 19 +++++++++++++++----
> >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> >  7 files changed, 80 insertions(+), 10 deletions(-)
> >  create mode 100644 tests/acceptance/query_machines.py
> 
> Good idea, but some questions come to my mind:
> 
> - What about devices? IIRC Gerd wrote a patch series last year that does
>   something similar for devices... It would be good to synchronize the
>   work, so that we do not have two completely interfaces between devices
>   and machines here in the end...

Might as well add  CPU models to that too as there's plenty of awful
CPUs no one should use with KVM. The tricky thing is they are fine
/ sensible with TCG still.

> 
> - Is deprecation as a status enough, or do we want to carry more
>   information here? E.g. is the machine maintained or orphan? Is it
>   stable or rather experimental? And didn't Gerd have also some
>   patches for this last year? ... yes, I think it was this series here:
>   http://lists.gnu.org/archive/html/qemu-ppc/2018-11/msg00039.html
>   ... actually, I like that idea with QemuSupportState... maybe you
>   could base your work on that series instead?


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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Daniel P. Berrangé]

On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> On 23/04/2019 23.22, Eduardo Habkost wrote:
> > This series adds machine type deprecation information to the
> > output of the `query-machines` QMP command.  With this, libvirt
> > and management software will be able to show this information to
> > users and/or suggest changes to VM configuration to avoid
> > deprecated machine types.
> > 
> > Eduardo Habkost (3):
> >   qapi: SupportStatusInfo struct
> >   machine: Use SupportStatusInfo for deprecation info
> >   qmp: Add deprecation information to query-machines
> > 
> >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> >  qapi/misc.json                     |  5 ++++-
> >  include/hw/boards.h                |  7 ++++---
> >  hw/i386/pc_piix.c                  |  4 +++-
> >  hw/ppc/prep.c                      |  4 +++-
> >  vl.c                               | 19 +++++++++++++++----
> >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> >  7 files changed, 80 insertions(+), 10 deletions(-)
> >  create mode 100644 tests/acceptance/query_machines.py
> 
> Good idea, but some questions come to my mind:
> 
> - What about devices? IIRC Gerd wrote a patch series last year that does
>   something similar for devices... It would be good to synchronize the
>   work, so that we do not have two completely interfaces between devices
>   and machines here in the end...

Might as well add  CPU models to that too as there's plenty of awful
CPUs no one should use with KVM. The tricky thing is they are fine
/ sensible with TCG still.

> 
> - Is deprecation as a status enough, or do we want to carry more
>   information here? E.g. is the machine maintained or orphan? Is it
>   stable or rather experimental? And didn't Gerd have also some
>   patches for this last year? ... yes, I think it was this series here:
>   http://lists.gnu.org/archive/html/qemu-ppc/2018-11/msg00039.html
>   ... actually, I like that idea with QemuSupportState... maybe you
>   could base your work on that series instead?


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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> On 23/04/2019 23.22, Eduardo Habkost wrote:
> > This series adds machine type deprecation information to the
> > output of the `query-machines` QMP command.  With this, libvirt
> > and management software will be able to show this information to
> > users and/or suggest changes to VM configuration to avoid
> > deprecated machine types.
> > 
> > Eduardo Habkost (3):
> >   qapi: SupportStatusInfo struct
> >   machine: Use SupportStatusInfo for deprecation info
> >   qmp: Add deprecation information to query-machines
> > 
> >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> >  qapi/misc.json                     |  5 ++++-
> >  include/hw/boards.h                |  7 ++++---
> >  hw/i386/pc_piix.c                  |  4 +++-
> >  hw/ppc/prep.c                      |  4 +++-
> >  vl.c                               | 19 +++++++++++++++----
> >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> >  7 files changed, 80 insertions(+), 10 deletions(-)
> >  create mode 100644 tests/acceptance/query_machines.py
> 
> Good idea, but some questions come to my mind:
> 
> - What about devices? IIRC Gerd wrote a patch series last year that does
>   something similar for devices... It would be good to synchronize the
>   work, so that we do not have two completely interfaces between devices
>   and machines here in the end...

My plan is to support this on devices, too.  I even had a version
where documentation of SupportStatusInfo mentioned device types,
but I decided to leave that out until we actually implement a
device deprecation info API.

> 
> - Is deprecation as a status enough, or do we want to carry more
>   information here? E.g. is the machine maintained or orphan? Is it
>   stable or rather experimental? And didn't Gerd have also some
>   patches for this last year? ... yes, I think it was this series here:
>   http://lists.gnu.org/archive/html/qemu-ppc/2018-11/msg00039.html
>   ... actually, I like that idea with QemuSupportState... maybe you
>   could base your work on that series instead?

We might want to carry more information eventually.  The
possibility of extending the data later is the main reason I
called the struct SupportStatusInfo and not just DeprecationInfo.

But I'd really like us to export the existing information first,
before extending the data.  Having important data available
through stderr and not QMP is a bug.  Tracking additional data
may be desirable, but it would be an additional feature.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> On 23/04/2019 23.22, Eduardo Habkost wrote:
> > This series adds machine type deprecation information to the
> > output of the `query-machines` QMP command.  With this, libvirt
> > and management software will be able to show this information to
> > users and/or suggest changes to VM configuration to avoid
> > deprecated machine types.
> > 
> > Eduardo Habkost (3):
> >   qapi: SupportStatusInfo struct
> >   machine: Use SupportStatusInfo for deprecation info
> >   qmp: Add deprecation information to query-machines
> > 
> >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> >  qapi/misc.json                     |  5 ++++-
> >  include/hw/boards.h                |  7 ++++---
> >  hw/i386/pc_piix.c                  |  4 +++-
> >  hw/ppc/prep.c                      |  4 +++-
> >  vl.c                               | 19 +++++++++++++++----
> >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> >  7 files changed, 80 insertions(+), 10 deletions(-)
> >  create mode 100644 tests/acceptance/query_machines.py
> 
> Good idea, but some questions come to my mind:
> 
> - What about devices? IIRC Gerd wrote a patch series last year that does
>   something similar for devices... It would be good to synchronize the
>   work, so that we do not have two completely interfaces between devices
>   and machines here in the end...

My plan is to support this on devices, too.  I even had a version
where documentation of SupportStatusInfo mentioned device types,
but I decided to leave that out until we actually implement a
device deprecation info API.

> 
> - Is deprecation as a status enough, or do we want to carry more
>   information here? E.g. is the machine maintained or orphan? Is it
>   stable or rather experimental? And didn't Gerd have also some
>   patches for this last year? ... yes, I think it was this series here:
>   http://lists.gnu.org/archive/html/qemu-ppc/2018-11/msg00039.html
>   ... actually, I like that idea with QemuSupportState... maybe you
>   could base your work on that series instead?

We might want to carry more information eventually.  The
possibility of extending the data later is the main reason I
called the struct SupportStatusInfo and not just DeprecationInfo.

But I'd really like us to export the existing information first,
before extending the data.  Having important data available
through stderr and not QMP is a bug.  Tracking additional data
may be desirable, but it would be an additional feature.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Wed, Apr 24, 2019 at 09:31:13AM +0100, Daniel P. Berrangé wrote:
> On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> > On 23/04/2019 23.22, Eduardo Habkost wrote:
> > > This series adds machine type deprecation information to the
> > > output of the `query-machines` QMP command.  With this, libvirt
> > > and management software will be able to show this information to
> > > users and/or suggest changes to VM configuration to avoid
> > > deprecated machine types.
> > > 
> > > Eduardo Habkost (3):
> > >   qapi: SupportStatusInfo struct
> > >   machine: Use SupportStatusInfo for deprecation info
> > >   qmp: Add deprecation information to query-machines
> > > 
> > >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> > >  qapi/misc.json                     |  5 ++++-
> > >  include/hw/boards.h                |  7 ++++---
> > >  hw/i386/pc_piix.c                  |  4 +++-
> > >  hw/ppc/prep.c                      |  4 +++-
> > >  vl.c                               | 19 +++++++++++++++----
> > >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> > >  7 files changed, 80 insertions(+), 10 deletions(-)
> > >  create mode 100644 tests/acceptance/query_machines.py
> > 
> > Good idea, but some questions come to my mind:
> > 
> > - What about devices? IIRC Gerd wrote a patch series last year that does
> >   something similar for devices... It would be good to synchronize the
> >   work, so that we do not have two completely interfaces between devices
> >   and machines here in the end...
> 
> Might as well add  CPU models to that too as there's plenty of awful
> CPUs no one should use with KVM. The tricky thing is they are fine
> / sensible with TCG still.

Right.  We also have devices that are supported in some machines
but not in others.  We will probably need a separate API that
takes a (device type, machine type, accelerator) tuple as input.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="UTF-8", Size: 1976 bytes --]

On Wed, Apr 24, 2019 at 09:31:13AM +0100, Daniel P. Berrangé wrote:
> On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> > On 23/04/2019 23.22, Eduardo Habkost wrote:
> > > This series adds machine type deprecation information to the
> > > output of the `query-machines` QMP command.  With this, libvirt
> > > and management software will be able to show this information to
> > > users and/or suggest changes to VM configuration to avoid
> > > deprecated machine types.
> > > 
> > > Eduardo Habkost (3):
> > >   qapi: SupportStatusInfo struct
> > >   machine: Use SupportStatusInfo for deprecation info
> > >   qmp: Add deprecation information to query-machines
> > > 
> > >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> > >  qapi/misc.json                     |  5 ++++-
> > >  include/hw/boards.h                |  7 ++++---
> > >  hw/i386/pc_piix.c                  |  4 +++-
> > >  hw/ppc/prep.c                      |  4 +++-
> > >  vl.c                               | 19 +++++++++++++++----
> > >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> > >  7 files changed, 80 insertions(+), 10 deletions(-)
> > >  create mode 100644 tests/acceptance/query_machines.py
> > 
> > Good idea, but some questions come to my mind:
> > 
> > - What about devices? IIRC Gerd wrote a patch series last year that does
> >   something similar for devices... It would be good to synchronize the
> >   work, so that we do not have two completely interfaces between devices
> >   and machines here in the end...
> 
> Might as well add  CPU models to that too as there's plenty of awful
> CPUs no one should use with KVM. The tricky thing is they are fine
> / sensible with TCG still.

Right.  We also have devices that are supported in some machines
but not in others.  We will probably need a separate API that
takes a (device type, machine type, accelerator) tuple as input.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > This struct will be used to represent support and deprecation
> > status of QEMU features.
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  qapi/common.json | 24 ++++++++++++++++++++++++
> >  1 file changed, 24 insertions(+)
> > 
> > diff --git a/qapi/common.json b/qapi/common.json
> > index 99d313ef3b..b59d0dc66b 100644
> > --- a/qapi/common.json
> > +++ b/qapi/common.json
> > @@ -193,3 +193,27 @@
> >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > +
> > +##
> > +# @SupportStatusInfo:
> > +#
> > +# Information on support status of a given feature
> > +# (e.g. machine type)
> > +#
> > +# @deprecated: if true, the given feature is deprecated and may be removed
> > +#              in future versions of QEMU according to the QEMU deprecation
> > +#              policy.
> > +#
> > +# @status-message: Human readable message describing support status
> > +#                  of the feature.
> > +#
> > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > +#                         feature.  For machine types, this should be the name
> > +#                         of an available machine-type.
> > +#
> > +# Since: 4.1
> > +##
> > +{ 'struct': 'SupportStatusInfo',
> > +  'data': { 'deprecated': 'bool',
> > +            '*status-message': 'str',
> > +            '*suggested-alternative': 'str' } }
> 
> I see status-message has to be optional, since you're embedding the
> struct into another struct and want deprecated==false by default.
> 
> I'd be inclined to change it to embed a pointer to the struct and
> drop the deprecated field, and make both status-message and
> suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> the pointer to which is NULL if not deprecated.

That could be a simple solution if we were sure we would only
track deprecation info.  But I would like us to track additional
support status on that struct eventually.

Also, I'd like to explicitly differentiate "information is not
available because QEMU is old" from "information is available and
machine type is not deprecated".

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="UTF-8", Size: 2445 bytes --]

On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > This struct will be used to represent support and deprecation
> > status of QEMU features.
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  qapi/common.json | 24 ++++++++++++++++++++++++
> >  1 file changed, 24 insertions(+)
> > 
> > diff --git a/qapi/common.json b/qapi/common.json
> > index 99d313ef3b..b59d0dc66b 100644
> > --- a/qapi/common.json
> > +++ b/qapi/common.json
> > @@ -193,3 +193,27 @@
> >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > +
> > +##
> > +# @SupportStatusInfo:
> > +#
> > +# Information on support status of a given feature
> > +# (e.g. machine type)
> > +#
> > +# @deprecated: if true, the given feature is deprecated and may be removed
> > +#              in future versions of QEMU according to the QEMU deprecation
> > +#              policy.
> > +#
> > +# @status-message: Human readable message describing support status
> > +#                  of the feature.
> > +#
> > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > +#                         feature.  For machine types, this should be the name
> > +#                         of an available machine-type.
> > +#
> > +# Since: 4.1
> > +##
> > +{ 'struct': 'SupportStatusInfo',
> > +  'data': { 'deprecated': 'bool',
> > +            '*status-message': 'str',
> > +            '*suggested-alternative': 'str' } }
> 
> I see status-message has to be optional, since you're embedding the
> struct into another struct and want deprecated==false by default.
> 
> I'd be inclined to change it to embed a pointer to the struct and
> drop the deprecated field, and make both status-message and
> suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> the pointer to which is NULL if not deprecated.

That could be a simple solution if we were sure we would only
track deprecation info.  But I would like us to track additional
support status on that struct eventually.

Also, I'd like to explicitly differentiate "information is not
available because QEMU is old" from "information is available and
machine type is not deprecated".

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

On Wed, Apr 24, 2019 at 12:23:33AM +0200, Philippe Mathieu-Daudé wrote:
> Hi Eduardo,
> 
> On 4/23/19 11:22 PM, Eduardo Habkost wrote:
> > This struct will be used to represent support and deprecation
> > status of QEMU features.
> 
> Excellent idea!
> 
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  qapi/common.json | 24 ++++++++++++++++++++++++
> >  1 file changed, 24 insertions(+)
> > 
> > diff --git a/qapi/common.json b/qapi/common.json
> > index 99d313ef3b..b59d0dc66b 100644
> > --- a/qapi/common.json
> > +++ b/qapi/common.json
> > @@ -193,3 +193,27 @@
> >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > +
> > +##
> > +# @SupportStatusInfo:
> > +#
> > +# Information on support status of a given feature
> > +# (e.g. machine type)
> 
> Hopefully it is generic, we can use it for devices too.

Yes, I want to keep it generic.

> 
> > +#
> > +# @deprecated: if true, the given feature is deprecated and may be removed
> > +#              in future versions of QEMU according to the QEMU deprecation
> > +#              policy.
> > +#
> > +# @status-message: Human readable message describing support status
> > +#                  of the feature.
> > +#
> > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > +#                         feature.  For machine types, this should be the name
> > +#                         of an available machine-type.
> > +#
> > +# Since: 4.1
> > +##
> > +{ 'struct': 'SupportStatusInfo',
> > +  'data': { 'deprecated': 'bool',
> > +            '*status-message': 'str',
> 
> This one shouldn't be optional IMHO, we should enforce developpers to
> give a reason for their deprecation.
> 
> With this argument not optional:
> 
> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

I might agree with you if you show me what would be a good
"reason for deprecation" string for pc-0.15 and spapr.  :)

The only information contained in these machines today is "use
another machine instead", and this is already encoded in the
suggested-alternative field.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="UTF-8", Size: 2281 bytes --]

On Wed, Apr 24, 2019 at 12:23:33AM +0200, Philippe Mathieu-Daudé wrote:
> Hi Eduardo,
> 
> On 4/23/19 11:22 PM, Eduardo Habkost wrote:
> > This struct will be used to represent support and deprecation
> > status of QEMU features.
> 
> Excellent idea!
> 
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  qapi/common.json | 24 ++++++++++++++++++++++++
> >  1 file changed, 24 insertions(+)
> > 
> > diff --git a/qapi/common.json b/qapi/common.json
> > index 99d313ef3b..b59d0dc66b 100644
> > --- a/qapi/common.json
> > +++ b/qapi/common.json
> > @@ -193,3 +193,27 @@
> >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > +
> > +##
> > +# @SupportStatusInfo:
> > +#
> > +# Information on support status of a given feature
> > +# (e.g. machine type)
> 
> Hopefully it is generic, we can use it for devices too.

Yes, I want to keep it generic.

> 
> > +#
> > +# @deprecated: if true, the given feature is deprecated and may be removed
> > +#              in future versions of QEMU according to the QEMU deprecation
> > +#              policy.
> > +#
> > +# @status-message: Human readable message describing support status
> > +#                  of the feature.
> > +#
> > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > +#                         feature.  For machine types, this should be the name
> > +#                         of an available machine-type.
> > +#
> > +# Since: 4.1
> > +##
> > +{ 'struct': 'SupportStatusInfo',
> > +  'data': { 'deprecated': 'bool',
> > +            '*status-message': 'str',
> 
> This one shouldn't be optional IMHO, we should enforce developpers to
> give a reason for their deprecation.
> 
> With this argument not optional:
> 
> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

I might agree with you if you show me what would be a good
"reason for deprecation" string for pc-0.15 and spapr.  :)

The only information contained in these machines today is "use
another machine instead", and this is already encoded in the
suggested-alternative field.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Eduardo Habkost]

On Wed, Apr 24, 2019 at 09:23:09AM +0100, Daniel P. Berrangé wrote:
> On Tue, Apr 23, 2019 at 06:22:45PM -0300, Eduardo Habkost wrote:
> > Use SupportStatusInfo to represent deprecation information of
> > machine types.
> > 
> > Instead of using a generic "use XXX instead" message for humans,
> > encode the suggested alternative in a machine-friendly way at the
> > 'suggested_alternatives' field.
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  include/hw/boards.h |  7 ++++---
> >  hw/i386/pc_piix.c   |  4 +++-
> >  hw/ppc/prep.c       |  4 +++-
> >  vl.c                | 13 +++++++++----
> >  4 files changed, 19 insertions(+), 9 deletions(-)
> > 
> > diff --git a/include/hw/boards.h b/include/hw/boards.h
> > index e231860666..243bf3c7ce 100644
> > --- a/include/hw/boards.h
> > +++ b/include/hw/boards.h
> > @@ -8,6 +8,8 @@
> >  #include "hw/qdev.h"
> >  #include "qom/object.h"
> >  #include "qom/cpu.h"
> > +#include "qapi/qapi-types-common.h"
> > +
> >  
> >  /**
> >   * memory_region_allocate_system_memory - Allocate a board's main memory
> > @@ -105,8 +107,7 @@ typedef struct {
> >  
> >  /**
> >   * MachineClass:
> > - * @deprecation_reason: If set, the machine is marked as deprecated. The
> > - *    string should provide some clear information about what to use instead.
> > + * @support_status: Support and deprecation status of machine type.
> >   * @max_cpus: maximum number of CPUs supported. Default: 1
> >   * @min_cpus: minimum number of CPUs supported. Default: 1
> >   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> > @@ -169,7 +170,7 @@ struct MachineClass {
> >      char *name;
> >      const char *alias;
> >      const char *desc;
> > -    const char *deprecation_reason;
> > +    SupportStatusInfo support_status;
> >  
> >      void (*init)(MachineState *state);
> >      void (*reset)(void);
> > diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> > index 8ad8e885c6..97bd401618 100644
> > --- a/hw/i386/pc_piix.c
> > +++ b/hw/i386/pc_piix.c
> > @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
> >  
> >      pc_i440fx_1_0_machine_options(m);
> >      m->hw_version = "0.15";
> > -    m->deprecation_reason = "use a newer machine type instead";
> > +    m->support_status.deprecated = true;
> > +    m->support_status.has_suggested_alternative = true;
> > +    m->support_status.suggested_alternative = g_strdup("pc");
> >      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
> >  }
> >  
> > diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> > index 847d320465..9a02b0eec4 100644
> > --- a/hw/ppc/prep.c
> > +++ b/hw/ppc/prep.c
> > @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
> >  
> >  static void prep_machine_init(MachineClass *mc)
> >  {
> > -    mc->deprecation_reason = "use 40p machine type instead";
> > +    mc->support_status.deprecated = true;
> > +    mc->support_status.has_suggested_alternative = true;
> > +    mc->support_status.suggested_alternative = g_strdup("40p");
> >      mc->desc = "PowerPC PREP platform";
> >      mc->init = ppc_prep_init;
> >      mc->block_default_type = IF_IDE;
> > diff --git a/vl.c b/vl.c
> > index c696ad2a13..99b857ed2a 100644
> > --- a/vl.c
> > +++ b/vl.c
> > @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
> >              }
> >              printf("%-20s %s%s%s\n", mc->name, mc->desc,
> >                     mc->is_default ? " (default)" : "",
> > -                   mc->deprecation_reason ? " (deprecated)" : "");
> > +                   mc->support_status.deprecated ? " (deprecated)" : "");
> >          }
> >      }
> >  
> > @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
> >       * called from configure_accelerator().
> >       */
> >  
> > -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> > -        error_report("Machine type '%s' is deprecated: %s",
> > -                     machine_class->name, machine_class->deprecation_reason);
> > +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> > +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> > +                     machine_class->support_status.status_message ? ": " : "",
> > +                     machine_class->support_status.status_message ?: "");
> > +        if (machine_class->support_status.suggested_alternative) {
> > +            error_report("Suggested solution: use '%s' machine type instead",
> > +                         machine_class->support_status.suggested_alternative);
> 
> I'd just drop the word "Suggested solution: " as I think it is fine to just
> say "Use foobar machine type instead".

I'm not sure.  Can we reword this, but in a way that it still
sounds like a suggestion, not as a definitive solution?

Sometimes the provided alternative won't work for everybody.
e.g. if one day we deprecate pc-i440fx, we can't be sure that
everybody will be able to use q35 instead.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 2/3] machine: Use SupportStatusInfo for deprecation info

[Eduardo Habkost]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="UTF-8", Size: 5158 bytes --]

On Wed, Apr 24, 2019 at 09:23:09AM +0100, Daniel P. Berrangé wrote:
> On Tue, Apr 23, 2019 at 06:22:45PM -0300, Eduardo Habkost wrote:
> > Use SupportStatusInfo to represent deprecation information of
> > machine types.
> > 
> > Instead of using a generic "use XXX instead" message for humans,
> > encode the suggested alternative in a machine-friendly way at the
> > 'suggested_alternatives' field.
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  include/hw/boards.h |  7 ++++---
> >  hw/i386/pc_piix.c   |  4 +++-
> >  hw/ppc/prep.c       |  4 +++-
> >  vl.c                | 13 +++++++++----
> >  4 files changed, 19 insertions(+), 9 deletions(-)
> > 
> > diff --git a/include/hw/boards.h b/include/hw/boards.h
> > index e231860666..243bf3c7ce 100644
> > --- a/include/hw/boards.h
> > +++ b/include/hw/boards.h
> > @@ -8,6 +8,8 @@
> >  #include "hw/qdev.h"
> >  #include "qom/object.h"
> >  #include "qom/cpu.h"
> > +#include "qapi/qapi-types-common.h"
> > +
> >  
> >  /**
> >   * memory_region_allocate_system_memory - Allocate a board's main memory
> > @@ -105,8 +107,7 @@ typedef struct {
> >  
> >  /**
> >   * MachineClass:
> > - * @deprecation_reason: If set, the machine is marked as deprecated. The
> > - *    string should provide some clear information about what to use instead.
> > + * @support_status: Support and deprecation status of machine type.
> >   * @max_cpus: maximum number of CPUs supported. Default: 1
> >   * @min_cpus: minimum number of CPUs supported. Default: 1
> >   * @default_cpus: number of CPUs instantiated if none are specified. Default: 1
> > @@ -169,7 +170,7 @@ struct MachineClass {
> >      char *name;
> >      const char *alias;
> >      const char *desc;
> > -    const char *deprecation_reason;
> > +    SupportStatusInfo support_status;
> >  
> >      void (*init)(MachineState *state);
> >      void (*reset)(void);
> > diff --git a/hw/i386/pc_piix.c b/hw/i386/pc_piix.c
> > index 8ad8e885c6..97bd401618 100644
> > --- a/hw/i386/pc_piix.c
> > +++ b/hw/i386/pc_piix.c
> > @@ -781,7 +781,9 @@ static void pc_i440fx_0_15_machine_options(MachineClass *m)
> >  
> >      pc_i440fx_1_0_machine_options(m);
> >      m->hw_version = "0.15";
> > -    m->deprecation_reason = "use a newer machine type instead";
> > +    m->support_status.deprecated = true;
> > +    m->support_status.has_suggested_alternative = true;
> > +    m->support_status.suggested_alternative = g_strdup("pc");
> >      compat_props_add(m->compat_props, compat, G_N_ELEMENTS(compat));
> >  }
> >  
> > diff --git a/hw/ppc/prep.c b/hw/ppc/prep.c
> > index 847d320465..9a02b0eec4 100644
> > --- a/hw/ppc/prep.c
> > +++ b/hw/ppc/prep.c
> > @@ -587,7 +587,9 @@ static void ppc_prep_init(MachineState *machine)
> >  
> >  static void prep_machine_init(MachineClass *mc)
> >  {
> > -    mc->deprecation_reason = "use 40p machine type instead";
> > +    mc->support_status.deprecated = true;
> > +    mc->support_status.has_suggested_alternative = true;
> > +    mc->support_status.suggested_alternative = g_strdup("40p");
> >      mc->desc = "PowerPC PREP platform";
> >      mc->init = ppc_prep_init;
> >      mc->block_default_type = IF_IDE;
> > diff --git a/vl.c b/vl.c
> > index c696ad2a13..99b857ed2a 100644
> > --- a/vl.c
> > +++ b/vl.c
> > @@ -2610,7 +2610,7 @@ static gint machine_class_cmp(gconstpointer a, gconstpointer b)
> >              }
> >              printf("%-20s %s%s%s\n", mc->name, mc->desc,
> >                     mc->is_default ? " (default)" : "",
> > -                   mc->deprecation_reason ? " (deprecated)" : "");
> > +                   mc->support_status.deprecated ? " (deprecated)" : "");
> >          }
> >      }
> >  
> > @@ -4308,9 +4308,14 @@ int main(int argc, char **argv, char **envp)
> >       * called from configure_accelerator().
> >       */
> >  
> > -    if (!qtest_enabled() && machine_class->deprecation_reason) {
> > -        error_report("Machine type '%s' is deprecated: %s",
> > -                     machine_class->name, machine_class->deprecation_reason);
> > +    if (!qtest_enabled() && machine_class->support_status.deprecated) {
> > +        error_report("Machine type '%s' is deprecated%s%s", machine_class->name,
> > +                     machine_class->support_status.status_message ? ": " : "",
> > +                     machine_class->support_status.status_message ?: "");
> > +        if (machine_class->support_status.suggested_alternative) {
> > +            error_report("Suggested solution: use '%s' machine type instead",
> > +                         machine_class->support_status.suggested_alternative);
> 
> I'd just drop the word "Suggested solution: " as I think it is fine to just
> say "Use foobar machine type instead".

I'm not sure.  Can we reword this, but in a way that it still
sounds like a suggestion, not as a definitive solution?

Sometimes the provided alternative won't work for everybody.
e.g. if one day we deprecate pc-i440fx, we can't be sure that
everybody will be able to use q35 instead.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Thomas Huth]

On 24/04/2019 20.10, Eduardo Habkost wrote:
> On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
>> On 23/04/2019 23.22, Eduardo Habkost wrote:
>>> This series adds machine type deprecation information to the
>>> output of the `query-machines` QMP command.  With this, libvirt
>>> and management software will be able to show this information to
>>> users and/or suggest changes to VM configuration to avoid
>>> deprecated machine types.
>>>
>>> Eduardo Habkost (3):
>>>   qapi: SupportStatusInfo struct
>>>   machine: Use SupportStatusInfo for deprecation info
>>>   qmp: Add deprecation information to query-machines
>>>
>>>  qapi/common.json                   | 24 ++++++++++++++++++++++++
>>>  qapi/misc.json                     |  5 ++++-
>>>  include/hw/boards.h                |  7 ++++---
>>>  hw/i386/pc_piix.c                  |  4 +++-
>>>  hw/ppc/prep.c                      |  4 +++-
>>>  vl.c                               | 19 +++++++++++++++----
>>>  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>>>  7 files changed, 80 insertions(+), 10 deletions(-)
>>>  create mode 100644 tests/acceptance/query_machines.py
>>
>> Good idea, but some questions come to my mind:
>>
>> - What about devices? IIRC Gerd wrote a patch series last year that does
>>   something similar for devices... It would be good to synchronize the
>>   work, so that we do not have two completely interfaces between devices
>>   and machines here in the end...
> 
> My plan is to support this on devices, too.  I even had a version
> where documentation of SupportStatusInfo mentioned device types,
> but I decided to leave that out until we actually implement a
> device deprecation info API.
> 
>>
>> - Is deprecation as a status enough, or do we want to carry more
>>   information here? E.g. is the machine maintained or orphan? Is it
>>   stable or rather experimental? And didn't Gerd have also some
>>   patches for this last year? ... yes, I think it was this series here:
>>   http://lists.gnu.org/archive/html/qemu-ppc/2018-11/msg00039.html
>>   ... actually, I like that idea with QemuSupportState... maybe you
>>   could base your work on that series instead?
> 
> We might want to carry more information eventually.  The
> possibility of extending the data later is the main reason I
> called the struct SupportStatusInfo and not just DeprecationInfo.

Ok. I was just a little bit afraid that we define an interface here that
we have to change again completely once we want to carry more
information. For example whether "deprecated" should be a "bool" here,
or rather one of the "enum" entries like in Gerd's series. But after
reading through https://patchwork.kernel.org/patch/10660677/ again, I
think I agree that "deprecated" is orthogonal to the support state, e.g.
a device could still be supported (in the sense that there is a
maintainer for it), while it has been marked as "deprecated" already.
So no more objections from my side here.

 Thomas

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Thomas Huth]

On 24/04/2019 20.10, Eduardo Habkost wrote:
> On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
>> On 23/04/2019 23.22, Eduardo Habkost wrote:
>>> This series adds machine type deprecation information to the
>>> output of the `query-machines` QMP command.  With this, libvirt
>>> and management software will be able to show this information to
>>> users and/or suggest changes to VM configuration to avoid
>>> deprecated machine types.
>>>
>>> Eduardo Habkost (3):
>>>   qapi: SupportStatusInfo struct
>>>   machine: Use SupportStatusInfo for deprecation info
>>>   qmp: Add deprecation information to query-machines
>>>
>>>  qapi/common.json                   | 24 ++++++++++++++++++++++++
>>>  qapi/misc.json                     |  5 ++++-
>>>  include/hw/boards.h                |  7 ++++---
>>>  hw/i386/pc_piix.c                  |  4 +++-
>>>  hw/ppc/prep.c                      |  4 +++-
>>>  vl.c                               | 19 +++++++++++++++----
>>>  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>>>  7 files changed, 80 insertions(+), 10 deletions(-)
>>>  create mode 100644 tests/acceptance/query_machines.py
>>
>> Good idea, but some questions come to my mind:
>>
>> - What about devices? IIRC Gerd wrote a patch series last year that does
>>   something similar for devices... It would be good to synchronize the
>>   work, so that we do not have two completely interfaces between devices
>>   and machines here in the end...
> 
> My plan is to support this on devices, too.  I even had a version
> where documentation of SupportStatusInfo mentioned device types,
> but I decided to leave that out until we actually implement a
> device deprecation info API.
> 
>>
>> - Is deprecation as a status enough, or do we want to carry more
>>   information here? E.g. is the machine maintained or orphan? Is it
>>   stable or rather experimental? And didn't Gerd have also some
>>   patches for this last year? ... yes, I think it was this series here:
>>   http://lists.gnu.org/archive/html/qemu-ppc/2018-11/msg00039.html
>>   ... actually, I like that idea with QemuSupportState... maybe you
>>   could base your work on that series instead?
> 
> We might want to carry more information eventually.  The
> possibility of extending the data later is the main reason I
> called the struct SupportStatusInfo and not just DeprecationInfo.

Ok. I was just a little bit afraid that we define an interface here that
we have to change again completely once we want to carry more
information. For example whether "deprecated" should be a "bool" here,
or rather one of the "enum" entries like in Gerd's series. But after
reading through https://patchwork.kernel.org/patch/10660677/ again, I
think I agree that "deprecated" is orthogonal to the support state, e.g.
a device could still be supported (in the sense that there is a
maintainer for it), while it has been marked as "deprecated" already.
So no more objections from my side here.

 Thomas

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Wainer dos Santos Moschetta]

Hi Eduardo,


On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
> This struct will be used to represent support and deprecation
> status of QEMU features.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>   qapi/common.json | 24 ++++++++++++++++++++++++
>   1 file changed, 24 insertions(+)
>
> diff --git a/qapi/common.json b/qapi/common.json
> index 99d313ef3b..b59d0dc66b 100644
> --- a/qapi/common.json
> +++ b/qapi/common.json
> @@ -193,3 +193,27 @@
>                'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
>                'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
>                'x86_64', 'xtensa', 'xtensaeb' ] }
> +
> +##
> +# @SupportStatusInfo:
> +#
> +# Information on support status of a given feature
> +# (e.g. machine type)
> +#
> +# @deprecated: if true, the given feature is deprecated and may be removed
> +#              in future versions of QEMU according to the QEMU deprecation
> +#              policy.

Eventually management software will need the know the QEMU version the 
feature is planed for removal. So makes sense to include a field to 
capture that information as well or do you expect it to be added (as a 
good practice) in the 'status-message'?

- Wainer

> +#
> +# @status-message: Human readable message describing support status
> +#                  of the feature.
> +#
> +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> +#                         feature.  For machine types, this should be the name
> +#                         of an available machine-type.
> +#
> +# Since: 4.1
> +##
> +{ 'struct': 'SupportStatusInfo',
> +  'data': { 'deprecated': 'bool',
> +            '*status-message': 'str',
> +            '*suggested-alternative': 'str' } }

Re: [Qemu-devel] [PATCH 3/3] qmp: Add deprecation information to query-machines

[Wainer dos Santos Moschetta]

Hi Eduardo,

On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
> Export machine type deprecation information through the
> query-machines QMP command.  With this, libvirt and management
> software will be able to show this information to users and/or
> suggest changes to VM configuration to avoid deprecated machines.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>   qapi/misc.json                     |  5 ++++-
>   vl.c                               |  6 ++++++
>   tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
>   3 files changed, 37 insertions(+), 1 deletion(-)
>   create mode 100644 tests/acceptance/query_machines.py
>
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 8b3ca4fdd3..941d251d17 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -2018,12 +2018,15 @@
>   #
>   # @hotpluggable-cpus: cpu hotplug via -device is supported (since 2.7.0)
>   #
> +# @support-status: Support/deprecation status information (since 4.1.0)
> +#
>   # Since: 1.2.0
>   ##
>   { 'struct': 'MachineInfo',
>     'data': { 'name': 'str', '*alias': 'str',
>               '*is-default': 'bool', 'cpu-max': 'int',
> -            'hotpluggable-cpus': 'bool'} }
> +            'hotpluggable-cpus': 'bool',
> +            'support-status': 'SupportStatusInfo' } }
>   
>   ##
>   # @query-machines:
> diff --git a/vl.c b/vl.c
> index 99b857ed2a..ca23d2a404 100644
> --- a/vl.c
> +++ b/vl.c
> @@ -1530,6 +1530,12 @@ MachineInfoList *qmp_query_machines(Error **errp)
>           info->name = g_strdup(mc->name);
>           info->cpu_max = !mc->max_cpus ? 1 : mc->max_cpus;
>           info->hotpluggable_cpus = mc->has_hotpluggable_cpus;
> +        assert(!mc->support_status.status_message ||
> +               mc->support_status.has_status_message);
> +        assert(!mc->support_status.suggested_alternative ||
> +               mc->support_status.has_suggested_alternative);
> +        info->support_status =
> +            QAPI_CLONE(SupportStatusInfo, &mc->support_status);
>   
>           entry = g_malloc0(sizeof(*entry));
>           entry->value = info;
> diff --git a/tests/acceptance/query_machines.py b/tests/acceptance/query_machines.py
> new file mode 100644
> index 0000000000..23a56ea617
> --- /dev/null
> +++ b/tests/acceptance/query_machines.py
> @@ -0,0 +1,27 @@
> +# Sanity check query-machines QMP command results
> +#
> +# Copyright (c) 2019 Red Hat, Inc.
> +#
> +# Author:
> +#  Eduardo Habkost <ehabkost@redhat.com>
> +#
> +# This work is licensed under the terms of the GNU GPL, version 2 or
> +# later.  See the COPYING file in the top-level directory.
> +
> +from avocado_qemu import Test
> +
> +class QueryMachines(Test):
> +    def test(self):

I suggest to use a meaning test case name as it will be displayed with 
Avocado output. Something like 'test_status_information'.

> +        self.vm.launch()
> +        machines = self.vm.command('query-machines')

Also I suggest to assert you got at least on machine, so ensure 
'query-machines' returning nothing doesn't pass unnoticed.

- Wainer

> +        machinesdict = dict((m['name'], m) for m in machines)
> +        machinesdict.update((m['alias'], m) for m in machines if 'alias' in m)
> +        for machine in machines:
> +            status = machine['support-status']
> +            if status['deprecated']:
> +                self.assertTrue(status.get('status-message') or \
> +                                status.get('suggested-alternative'),
> +                                "Deprecated machine (%s) must have status-message or suggested-alternative" % (machine['name']))
> +            if 'suggested-alternative' in status:
> +                self.assertTrue(status['suggested-alternative'] in machinesdict,
> +                                "suggested-alternative of %s must point to a valid machine type" % (machine['name']))

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

On Thu, Apr 25, 2019 at 11:20:58AM -0300, Wainer dos Santos Moschetta wrote:
> Hi Eduardo,
> 
> 
> On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
> > This struct will be used to represent support and deprecation
> > status of QEMU features.
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >   qapi/common.json | 24 ++++++++++++++++++++++++
> >   1 file changed, 24 insertions(+)
> > 
> > diff --git a/qapi/common.json b/qapi/common.json
> > index 99d313ef3b..b59d0dc66b 100644
> > --- a/qapi/common.json
> > +++ b/qapi/common.json
> > @@ -193,3 +193,27 @@
> >                'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> >                'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> >                'x86_64', 'xtensa', 'xtensaeb' ] }
> > +
> > +##
> > +# @SupportStatusInfo:
> > +#
> > +# Information on support status of a given feature
> > +# (e.g. machine type)
> > +#
> > +# @deprecated: if true, the given feature is deprecated and may be removed
> > +#              in future versions of QEMU according to the QEMU deprecation
> > +#              policy.
> 
> Eventually management software will need the know the QEMU version the
> feature is planed for removal. So makes sense to include a field to capture
> that information as well or do you expect it to be added (as a good
> practice) in the 'status-message'?

If we really want to provide extra information like version
numbers, adding a separate field sounds better than using
status-message.

But I'm not sure we really want to include this amount of detail
in the API.  Mentioning explicit version numbers could make
things more complex for downstream distributions of QEMU that
include backports and/or have a different deprecation policy.

I'd like to hear opinions from others.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

On Thu, Apr 25, 2019 at 11:20:58AM -0300, Wainer dos Santos Moschetta wrote:
> Hi Eduardo,
> 
> 
> On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
> > This struct will be used to represent support and deprecation
> > status of QEMU features.
> > 
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >   qapi/common.json | 24 ++++++++++++++++++++++++
> >   1 file changed, 24 insertions(+)
> > 
> > diff --git a/qapi/common.json b/qapi/common.json
> > index 99d313ef3b..b59d0dc66b 100644
> > --- a/qapi/common.json
> > +++ b/qapi/common.json
> > @@ -193,3 +193,27 @@
> >                'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> >                'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> >                'x86_64', 'xtensa', 'xtensaeb' ] }
> > +
> > +##
> > +# @SupportStatusInfo:
> > +#
> > +# Information on support status of a given feature
> > +# (e.g. machine type)
> > +#
> > +# @deprecated: if true, the given feature is deprecated and may be removed
> > +#              in future versions of QEMU according to the QEMU deprecation
> > +#              policy.
> 
> Eventually management software will need the know the QEMU version the
> feature is planed for removal. So makes sense to include a field to capture
> that information as well or do you expect it to be added (as a good
> practice) in the 'status-message'?

If we really want to provide extra information like version
numbers, adding a separate field sounds better than using
status-message.

But I'm not sure we really want to include this amount of detail
in the API.  Mentioning explicit version numbers could make
things more complex for downstream distributions of QEMU that
include backports and/or have a different deprecation policy.

I'd like to hear opinions from others.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 3/3] qmp: Add deprecation information to query-machines

[Eduardo Habkost]

On Thu, Apr 25, 2019 at 11:54:34AM -0300, Wainer dos Santos Moschetta wrote:
> Hi Eduardo,
> 
> On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
[...]
> > +class QueryMachines(Test):
> > +    def test(self):
> 
> I suggest to use a meaning test case name as it will be displayed with
> Avocado output. Something like 'test_status_information'.

This is a generic test case for query-machines, and I don't
expect it to be specific for validating support-status.

> 
> > +        self.vm.launch()
> > +        machines = self.vm.command('query-machines')
> 
> Also I suggest to assert you got at least on machine, so ensure
> 'query-machines' returning nothing doesn't pass unnoticed.

Good idea.  I will send this in v2 or as a follow up patch.
Thanks!

-- 
Eduardo

Re: [Qemu-devel] [PATCH 3/3] qmp: Add deprecation information to query-machines

[Eduardo Habkost]

On Thu, Apr 25, 2019 at 11:54:34AM -0300, Wainer dos Santos Moschetta wrote:
> Hi Eduardo,
> 
> On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
[...]
> > +class QueryMachines(Test):
> > +    def test(self):
> 
> I suggest to use a meaning test case name as it will be displayed with
> Avocado output. Something like 'test_status_information'.

This is a generic test case for query-machines, and I don't
expect it to be specific for validating support-status.

> 
> > +        self.vm.launch()
> > +        machines = self.vm.command('query-machines')
> 
> Also I suggest to assert you got at least on machine, so ensure
> 'query-machines' returning nothing doesn't pass unnoticed.

Good idea.  I will send this in v2 or as a follow up patch.
Thanks!

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Thu, Apr 25, 2019 at 02:42:08PM -0300, Eduardo Habkost wrote:
> On Thu, Apr 25, 2019 at 11:20:58AM -0300, Wainer dos Santos Moschetta wrote:
> > Hi Eduardo,
> > 
> > 
> > On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
> > > This struct will be used to represent support and deprecation
> > > status of QEMU features.
> > > 
> > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > ---
> > >   qapi/common.json | 24 ++++++++++++++++++++++++
> > >   1 file changed, 24 insertions(+)
> > > 
> > > diff --git a/qapi/common.json b/qapi/common.json
> > > index 99d313ef3b..b59d0dc66b 100644
> > > --- a/qapi/common.json
> > > +++ b/qapi/common.json
> > > @@ -193,3 +193,27 @@
> > >                'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > >                'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > >                'x86_64', 'xtensa', 'xtensaeb' ] }
> > > +
> > > +##
> > > +# @SupportStatusInfo:
> > > +#
> > > +# Information on support status of a given feature
> > > +# (e.g. machine type)
> > > +#
> > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > +#              in future versions of QEMU according to the QEMU deprecation
> > > +#              policy.
> > 
> > Eventually management software will need the know the QEMU version the
> > feature is planed for removal. So makes sense to include a field to capture
> > that information as well or do you expect it to be added (as a good
> > practice) in the 'status-message'?
> 
> If we really want to provide extra information like version
> numbers, adding a separate field sounds better than using
> status-message.
> 
> But I'm not sure we really want to include this amount of detail
> in the API.  Mentioning explicit version numbers could make
> things more complex for downstream distributions of QEMU that
> include backports and/or have a different deprecation policy.
> 
> I'd like to hear opinions from others.

Yeah, I'm *not* in favour of mentioning any version number in this. Our
"2 cycle" deprecation rule is more of a guideline than a strict rule.
It can be extended if we find some blocking problem that makes removal
more painful than expected.

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 :|

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Thu, Apr 25, 2019 at 02:42:08PM -0300, Eduardo Habkost wrote:
> On Thu, Apr 25, 2019 at 11:20:58AM -0300, Wainer dos Santos Moschetta wrote:
> > Hi Eduardo,
> > 
> > 
> > On 04/23/2019 06:22 PM, Eduardo Habkost wrote:
> > > This struct will be used to represent support and deprecation
> > > status of QEMU features.
> > > 
> > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > ---
> > >   qapi/common.json | 24 ++++++++++++++++++++++++
> > >   1 file changed, 24 insertions(+)
> > > 
> > > diff --git a/qapi/common.json b/qapi/common.json
> > > index 99d313ef3b..b59d0dc66b 100644
> > > --- a/qapi/common.json
> > > +++ b/qapi/common.json
> > > @@ -193,3 +193,27 @@
> > >                'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > >                'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > >                'x86_64', 'xtensa', 'xtensaeb' ] }
> > > +
> > > +##
> > > +# @SupportStatusInfo:
> > > +#
> > > +# Information on support status of a given feature
> > > +# (e.g. machine type)
> > > +#
> > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > +#              in future versions of QEMU according to the QEMU deprecation
> > > +#              policy.
> > 
> > Eventually management software will need the know the QEMU version the
> > feature is planed for removal. So makes sense to include a field to capture
> > that information as well or do you expect it to be added (as a good
> > practice) in the 'status-message'?
> 
> If we really want to provide extra information like version
> numbers, adding a separate field sounds better than using
> status-message.
> 
> But I'm not sure we really want to include this amount of detail
> in the API.  Mentioning explicit version numbers could make
> things more complex for downstream distributions of QEMU that
> include backports and/or have a different deprecation policy.
> 
> I'd like to hear opinions from others.

Yeah, I'm *not* in favour of mentioning any version number in this. Our
"2 cycle" deprecation rule is more of a guideline than a strict rule.
It can be extended if we find some blocking problem that makes removal
more painful than expected.

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 :|

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Wed, Apr 24, 2019 at 03:20:36PM -0300, Eduardo Habkost wrote:
> On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> > On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > > This struct will be used to represent support and deprecation
> > > status of QEMU features.
> > > 
> > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > ---
> > >  qapi/common.json | 24 ++++++++++++++++++++++++
> > >  1 file changed, 24 insertions(+)
> > > 
> > > diff --git a/qapi/common.json b/qapi/common.json
> > > index 99d313ef3b..b59d0dc66b 100644
> > > --- a/qapi/common.json
> > > +++ b/qapi/common.json
> > > @@ -193,3 +193,27 @@
> > >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > > +
> > > +##
> > > +# @SupportStatusInfo:
> > > +#
> > > +# Information on support status of a given feature
> > > +# (e.g. machine type)
> > > +#
> > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > +#              in future versions of QEMU according to the QEMU deprecation
> > > +#              policy.
> > > +#
> > > +# @status-message: Human readable message describing support status
> > > +#                  of the feature.
> > > +#
> > > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > > +#                         feature.  For machine types, this should be the name
> > > +#                         of an available machine-type.
> > > +#
> > > +# Since: 4.1
> > > +##
> > > +{ 'struct': 'SupportStatusInfo',
> > > +  'data': { 'deprecated': 'bool',
> > > +            '*status-message': 'str',
> > > +            '*suggested-alternative': 'str' } }
> > 
> > I see status-message has to be optional, since you're embedding the
> > struct into another struct and want deprecated==false by default.
> > 
> > I'd be inclined to change it to embed a pointer to the struct and
> > drop the deprecated field, and make both status-message and
> > suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> > the pointer to which is NULL if not deprecated.
> 
> That could be a simple solution if we were sure we would only
> track deprecation info.  But I would like us to track additional
> support status on that struct eventually.

I've no objection to expanding it to capture other info - we'll
want to change the 'deprecated' field to an enum though. Also,
in some cases there won't be any real alternative so lets just
call it 'hint' instead. How about

    { 'enum':  "SupportStatus",
      'data': { 'production',  # Secure for use in hostile production env
                'development', # No security guarentee, friendly dev only
		'deprecated',  # To be removed in the future
    } }

    { 'struct': "SupportStatusInfo",
       'data': { 'status': 'SupportStatus',
                 '*info': 'str',
		 '*hint': 'str' } }

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 :|

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Wed, Apr 24, 2019 at 03:20:36PM -0300, Eduardo Habkost wrote:
> On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> > On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > > This struct will be used to represent support and deprecation
> > > status of QEMU features.
> > > 
> > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > ---
> > >  qapi/common.json | 24 ++++++++++++++++++++++++
> > >  1 file changed, 24 insertions(+)
> > > 
> > > diff --git a/qapi/common.json b/qapi/common.json
> > > index 99d313ef3b..b59d0dc66b 100644
> > > --- a/qapi/common.json
> > > +++ b/qapi/common.json
> > > @@ -193,3 +193,27 @@
> > >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > > +
> > > +##
> > > +# @SupportStatusInfo:
> > > +#
> > > +# Information on support status of a given feature
> > > +# (e.g. machine type)
> > > +#
> > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > +#              in future versions of QEMU according to the QEMU deprecation
> > > +#              policy.
> > > +#
> > > +# @status-message: Human readable message describing support status
> > > +#                  of the feature.
> > > +#
> > > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > > +#                         feature.  For machine types, this should be the name
> > > +#                         of an available machine-type.
> > > +#
> > > +# Since: 4.1
> > > +##
> > > +{ 'struct': 'SupportStatusInfo',
> > > +  'data': { 'deprecated': 'bool',
> > > +            '*status-message': 'str',
> > > +            '*suggested-alternative': 'str' } }
> > 
> > I see status-message has to be optional, since you're embedding the
> > struct into another struct and want deprecated==false by default.
> > 
> > I'd be inclined to change it to embed a pointer to the struct and
> > drop the deprecated field, and make both status-message and
> > suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> > the pointer to which is NULL if not deprecated.
> 
> That could be a simple solution if we were sure we would only
> track deprecation info.  But I would like us to track additional
> support status on that struct eventually.

I've no objection to expanding it to capture other info - we'll
want to change the 'deprecated' field to an enum though. Also,
in some cases there won't be any real alternative so lets just
call it 'hint' instead. How about

    { 'enum':  "SupportStatus",
      'data': { 'production',  # Secure for use in hostile production env
                'development', # No security guarentee, friendly dev only
		'deprecated',  # To be removed in the future
    } }

    { 'struct': "SupportStatusInfo",
       'data': { 'status': 'SupportStatus',
                 '*info': 'str',
		 '*hint': 'str' } }

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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Daniel P. Berrangé]

On Wed, Apr 24, 2019 at 03:10:49PM -0300, Eduardo Habkost wrote:
> On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> > On 23/04/2019 23.22, Eduardo Habkost wrote:
> > > This series adds machine type deprecation information to the
> > > output of the `query-machines` QMP command.  With this, libvirt
> > > and management software will be able to show this information to
> > > users and/or suggest changes to VM configuration to avoid
> > > deprecated machine types.
> > > 
> > > Eduardo Habkost (3):
> > >   qapi: SupportStatusInfo struct
> > >   machine: Use SupportStatusInfo for deprecation info
> > >   qmp: Add deprecation information to query-machines
> > > 
> > >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> > >  qapi/misc.json                     |  5 ++++-
> > >  include/hw/boards.h                |  7 ++++---
> > >  hw/i386/pc_piix.c                  |  4 +++-
> > >  hw/ppc/prep.c                      |  4 +++-
> > >  vl.c                               | 19 +++++++++++++++----
> > >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> > >  7 files changed, 80 insertions(+), 10 deletions(-)
> > >  create mode 100644 tests/acceptance/query_machines.py
> > 
> > Good idea, but some questions come to my mind:
> > 
> > - What about devices? IIRC Gerd wrote a patch series last year that does
> >   something similar for devices... It would be good to synchronize the
> >   work, so that we do not have two completely interfaces between devices
> >   and machines here in the end...
> 
> My plan is to support this on devices, too.  I even had a version
> where documentation of SupportStatusInfo mentioned device types,
> but I decided to leave that out until we actually implement a
> device deprecation info API.

We need it on CPU models, and on CPU features too potentially. Essentially
we should consider it applicable to anything we report in QMP.


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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Daniel P. Berrangé]

On Wed, Apr 24, 2019 at 03:10:49PM -0300, Eduardo Habkost wrote:
> On Wed, Apr 24, 2019 at 09:56:53AM +0200, Thomas Huth wrote:
> > On 23/04/2019 23.22, Eduardo Habkost wrote:
> > > This series adds machine type deprecation information to the
> > > output of the `query-machines` QMP command.  With this, libvirt
> > > and management software will be able to show this information to
> > > users and/or suggest changes to VM configuration to avoid
> > > deprecated machine types.
> > > 
> > > Eduardo Habkost (3):
> > >   qapi: SupportStatusInfo struct
> > >   machine: Use SupportStatusInfo for deprecation info
> > >   qmp: Add deprecation information to query-machines
> > > 
> > >  qapi/common.json                   | 24 ++++++++++++++++++++++++
> > >  qapi/misc.json                     |  5 ++++-
> > >  include/hw/boards.h                |  7 ++++---
> > >  hw/i386/pc_piix.c                  |  4 +++-
> > >  hw/ppc/prep.c                      |  4 +++-
> > >  vl.c                               | 19 +++++++++++++++----
> > >  tests/acceptance/query_machines.py | 27 +++++++++++++++++++++++++++
> > >  7 files changed, 80 insertions(+), 10 deletions(-)
> > >  create mode 100644 tests/acceptance/query_machines.py
> > 
> > Good idea, but some questions come to my mind:
> > 
> > - What about devices? IIRC Gerd wrote a patch series last year that does
> >   something similar for devices... It would be good to synchronize the
> >   work, so that we do not have two completely interfaces between devices
> >   and machines here in the end...
> 
> My plan is to support this on devices, too.  I even had a version
> where documentation of SupportStatusInfo mentioned device types,
> but I decided to leave that out until we actually implement a
> device deprecation info API.

We need it on CPU models, and on CPU features too potentially. Essentially
we should consider it applicable to anything we report in QMP.


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 :|

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

On Tue, Apr 30, 2019 at 11:10:06AM +0100, Daniel P. Berrangé wrote:
> On Wed, Apr 24, 2019 at 03:20:36PM -0300, Eduardo Habkost wrote:
> > On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> > > On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > > > This struct will be used to represent support and deprecation
> > > > status of QEMU features.
> > > > 
> > > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > > ---
> > > >  qapi/common.json | 24 ++++++++++++++++++++++++
> > > >  1 file changed, 24 insertions(+)
> > > > 
> > > > diff --git a/qapi/common.json b/qapi/common.json
> > > > index 99d313ef3b..b59d0dc66b 100644
> > > > --- a/qapi/common.json
> > > > +++ b/qapi/common.json
> > > > @@ -193,3 +193,27 @@
> > > >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > > >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > > >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > > > +
> > > > +##
> > > > +# @SupportStatusInfo:
> > > > +#
> > > > +# Information on support status of a given feature
> > > > +# (e.g. machine type)
> > > > +#
> > > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > > +#              in future versions of QEMU according to the QEMU deprecation
> > > > +#              policy.
> > > > +#
> > > > +# @status-message: Human readable message describing support status
> > > > +#                  of the feature.
> > > > +#
> > > > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > > > +#                         feature.  For machine types, this should be the name
> > > > +#                         of an available machine-type.
> > > > +#
> > > > +# Since: 4.1
> > > > +##
> > > > +{ 'struct': 'SupportStatusInfo',
> > > > +  'data': { 'deprecated': 'bool',
> > > > +            '*status-message': 'str',
> > > > +            '*suggested-alternative': 'str' } }
> > > 
> > > I see status-message has to be optional, since you're embedding the
> > > struct into another struct and want deprecated==false by default.
> > > 
> > > I'd be inclined to change it to embed a pointer to the struct and
> > > drop the deprecated field, and make both status-message and
> > > suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> > > the pointer to which is NULL if not deprecated.
> > 
> > That could be a simple solution if we were sure we would only
> > track deprecation info.  But I would like us to track additional
> > support status on that struct eventually.
> 
> I've no objection to expanding it to capture other info - we'll
> want to change the 'deprecated' field to an enum though. Also,
> in some cases there won't be any real alternative so lets just
> call it 'hint' instead. How about
> 
>     { 'enum':  "SupportStatus",
>       'data': { 'production',  # Secure for use in hostile production env
>                 'development', # No security guarentee, friendly dev only
> 		'deprecated',  # To be removed in the future
>     } }

"secure for production" and "deprecated" are independent
variables.  There are deprecated features that are still secure,
and deprecated features that were never supposed to be used in
production in the first place.

> 
>     { 'struct': "SupportStatusInfo",
>        'data': { 'status': 'SupportStatus',
>                  '*info': 'str',
> 		 '*hint': 'str' } }

"hint" seems nicer than "suggested" or "recommended".  I like it.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Eduardo Habkost]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="UTF-8", Size: 3570 bytes --]

On Tue, Apr 30, 2019 at 11:10:06AM +0100, Daniel P. Berrangé wrote:
> On Wed, Apr 24, 2019 at 03:20:36PM -0300, Eduardo Habkost wrote:
> > On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> > > On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > > > This struct will be used to represent support and deprecation
> > > > status of QEMU features.
> > > > 
> > > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > > ---
> > > >  qapi/common.json | 24 ++++++++++++++++++++++++
> > > >  1 file changed, 24 insertions(+)
> > > > 
> > > > diff --git a/qapi/common.json b/qapi/common.json
> > > > index 99d313ef3b..b59d0dc66b 100644
> > > > --- a/qapi/common.json
> > > > +++ b/qapi/common.json
> > > > @@ -193,3 +193,27 @@
> > > >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > > >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > > >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > > > +
> > > > +##
> > > > +# @SupportStatusInfo:
> > > > +#
> > > > +# Information on support status of a given feature
> > > > +# (e.g. machine type)
> > > > +#
> > > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > > +#              in future versions of QEMU according to the QEMU deprecation
> > > > +#              policy.
> > > > +#
> > > > +# @status-message: Human readable message describing support status
> > > > +#                  of the feature.
> > > > +#
> > > > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > > > +#                         feature.  For machine types, this should be the name
> > > > +#                         of an available machine-type.
> > > > +#
> > > > +# Since: 4.1
> > > > +##
> > > > +{ 'struct': 'SupportStatusInfo',
> > > > +  'data': { 'deprecated': 'bool',
> > > > +            '*status-message': 'str',
> > > > +            '*suggested-alternative': 'str' } }
> > > 
> > > I see status-message has to be optional, since you're embedding the
> > > struct into another struct and want deprecated==false by default.
> > > 
> > > I'd be inclined to change it to embed a pointer to the struct and
> > > drop the deprecated field, and make both status-message and
> > > suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> > > the pointer to which is NULL if not deprecated.
> > 
> > That could be a simple solution if we were sure we would only
> > track deprecation info.  But I would like us to track additional
> > support status on that struct eventually.
> 
> I've no objection to expanding it to capture other info - we'll
> want to change the 'deprecated' field to an enum though. Also,
> in some cases there won't be any real alternative so lets just
> call it 'hint' instead. How about
> 
>     { 'enum':  "SupportStatus",
>       'data': { 'production',  # Secure for use in hostile production env
>                 'development', # No security guarentee, friendly dev only
> 		'deprecated',  # To be removed in the future
>     } }

"secure for production" and "deprecated" are independent
variables.  There are deprecated features that are still secure,
and deprecated features that were never supposed to be used in
production in the first place.

> 
>     { 'struct': "SupportStatusInfo",
>        'data': { 'status': 'SupportStatus',
>                  '*info': 'str',
> 		 '*hint': 'str' } }

"hint" seems nicer than "suggested" or "recommended".  I like it.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Tue, Apr 30, 2019 at 09:42:36AM -0300, Eduardo Habkost wrote:
> On Tue, Apr 30, 2019 at 11:10:06AM +0100, Daniel P. Berrangé wrote:
> > On Wed, Apr 24, 2019 at 03:20:36PM -0300, Eduardo Habkost wrote:
> > > On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> > > > On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > > > > This struct will be used to represent support and deprecation
> > > > > status of QEMU features.
> > > > > 
> > > > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > > > ---
> > > > >  qapi/common.json | 24 ++++++++++++++++++++++++
> > > > >  1 file changed, 24 insertions(+)
> > > > > 
> > > > > diff --git a/qapi/common.json b/qapi/common.json
> > > > > index 99d313ef3b..b59d0dc66b 100644
> > > > > --- a/qapi/common.json
> > > > > +++ b/qapi/common.json
> > > > > @@ -193,3 +193,27 @@
> > > > >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > > > >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > > > >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > > > > +
> > > > > +##
> > > > > +# @SupportStatusInfo:
> > > > > +#
> > > > > +# Information on support status of a given feature
> > > > > +# (e.g. machine type)
> > > > > +#
> > > > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > > > +#              in future versions of QEMU according to the QEMU deprecation
> > > > > +#              policy.
> > > > > +#
> > > > > +# @status-message: Human readable message describing support status
> > > > > +#                  of the feature.
> > > > > +#
> > > > > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > > > > +#                         feature.  For machine types, this should be the name
> > > > > +#                         of an available machine-type.
> > > > > +#
> > > > > +# Since: 4.1
> > > > > +##
> > > > > +{ 'struct': 'SupportStatusInfo',
> > > > > +  'data': { 'deprecated': 'bool',
> > > > > +            '*status-message': 'str',
> > > > > +            '*suggested-alternative': 'str' } }
> > > > 
> > > > I see status-message has to be optional, since you're embedding the
> > > > struct into another struct and want deprecated==false by default.
> > > > 
> > > > I'd be inclined to change it to embed a pointer to the struct and
> > > > drop the deprecated field, and make both status-message and
> > > > suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> > > > the pointer to which is NULL if not deprecated.
> > > 
> > > That could be a simple solution if we were sure we would only
> > > track deprecation info.  But I would like us to track additional
> > > support status on that struct eventually.
> > 
> > I've no objection to expanding it to capture other info - we'll
> > want to change the 'deprecated' field to an enum though. Also,
> > in some cases there won't be any real alternative so lets just
> > call it 'hint' instead. How about
> > 
> >     { 'enum':  "SupportStatus",
> >       'data': { 'production',  # Secure for use in hostile production env
> >                 'development', # No security guarentee, friendly dev only
> > 		'deprecated',  # To be removed in the future
> >     } }
> 
> "secure for production" and "deprecated" are independent
> variables.  There are deprecated features that are still secure,
> and deprecated features that were never supposed to be used in
> production in the first place.

Good point - we should track  quality status separately. So still
need a boolean deprecation flag too i guess. 

> 
> > 
> >     { 'struct': "SupportStatusInfo",
> >        'data': { 'status': 'SupportStatus',
> >                  '*info': 'str',
> > 		 '*hint': 'str' } }
> 
> "hint" seems nicer than "suggested" or "recommended".  I like it.
> 
> -- 
> Eduardo

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 :|

Re: [Qemu-devel] [PATCH 1/3] qapi: SupportStatusInfo struct

[Daniel P. Berrangé]

On Tue, Apr 30, 2019 at 09:42:36AM -0300, Eduardo Habkost wrote:
> On Tue, Apr 30, 2019 at 11:10:06AM +0100, Daniel P. Berrangé wrote:
> > On Wed, Apr 24, 2019 at 03:20:36PM -0300, Eduardo Habkost wrote:
> > > On Wed, Apr 24, 2019 at 09:26:52AM +0100, Daniel P. Berrangé wrote:
> > > > On Tue, Apr 23, 2019 at 06:22:44PM -0300, Eduardo Habkost wrote:
> > > > > This struct will be used to represent support and deprecation
> > > > > status of QEMU features.
> > > > > 
> > > > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > > > ---
> > > > >  qapi/common.json | 24 ++++++++++++++++++++++++
> > > > >  1 file changed, 24 insertions(+)
> > > > > 
> > > > > diff --git a/qapi/common.json b/qapi/common.json
> > > > > index 99d313ef3b..b59d0dc66b 100644
> > > > > --- a/qapi/common.json
> > > > > +++ b/qapi/common.json
> > > > > @@ -193,3 +193,27 @@
> > > > >               'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4',
> > > > >               'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32',
> > > > >               'x86_64', 'xtensa', 'xtensaeb' ] }
> > > > > +
> > > > > +##
> > > > > +# @SupportStatusInfo:
> > > > > +#
> > > > > +# Information on support status of a given feature
> > > > > +# (e.g. machine type)
> > > > > +#
> > > > > +# @deprecated: if true, the given feature is deprecated and may be removed
> > > > > +#              in future versions of QEMU according to the QEMU deprecation
> > > > > +#              policy.
> > > > > +#
> > > > > +# @status-message: Human readable message describing support status
> > > > > +#                  of the feature.
> > > > > +#
> > > > > +# @suggested-alternative: Optional.  Suggested alternative for a deprecated
> > > > > +#                         feature.  For machine types, this should be the name
> > > > > +#                         of an available machine-type.
> > > > > +#
> > > > > +# Since: 4.1
> > > > > +##
> > > > > +{ 'struct': 'SupportStatusInfo',
> > > > > +  'data': { 'deprecated': 'bool',
> > > > > +            '*status-message': 'str',
> > > > > +            '*suggested-alternative': 'str' } }
> > > > 
> > > > I see status-message has to be optional, since you're embedding the
> > > > struct into another struct and want deprecated==false by default.
> > > > 
> > > > I'd be inclined to change it to embed a pointer to the struct and
> > > > drop the deprecated field, and make both status-message and
> > > > suggested-alternative be mandatory. ie a struct  "DeprecationInfo" 
> > > > the pointer to which is NULL if not deprecated.
> > > 
> > > That could be a simple solution if we were sure we would only
> > > track deprecation info.  But I would like us to track additional
> > > support status on that struct eventually.
> > 
> > I've no objection to expanding it to capture other info - we'll
> > want to change the 'deprecated' field to an enum though. Also,
> > in some cases there won't be any real alternative so lets just
> > call it 'hint' instead. How about
> > 
> >     { 'enum':  "SupportStatus",
> >       'data': { 'production',  # Secure for use in hostile production env
> >                 'development', # No security guarentee, friendly dev only
> > 		'deprecated',  # To be removed in the future
> >     } }
> 
> "secure for production" and "deprecated" are independent
> variables.  There are deprecated features that are still secure,
> and deprecated features that were never supposed to be used in
> production in the first place.

Good point - we should track  quality status separately. So still
need a boolean deprecation flag too i guess. 

> 
> > 
> >     { 'struct': "SupportStatusInfo",
> >        'data': { 'status': 'SupportStatus',
> >                  '*info': 'str',
> > 		 '*hint': 'str' } }
> 
> "hint" seems nicer than "suggested" or "recommended".  I like it.
> 
> -- 
> Eduardo

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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> This series adds machine type deprecation information to the
> output of the `query-machines` QMP command.  With this, libvirt
> and management software will be able to show this information to
> users and/or suggest changes to VM configuration to avoid
> deprecated machine types.

This overlaps with something I want to try, namely using Kevin's
proposed QAPI feature flags for deprecation markings.  Let's compare the
two.

To mark something as deprecated with your patches, you add a
@support-status member somewhere, where "somewhere" is related to
"something" by "provides information on".

Example: MachineInfo (returned by query-machines) provides information
on possible values of -machine parameter type.  If -machine was
QAPIfied, it would provide information on possible values of a QAPI
object type's member.  The type might be anonymous.  The member should
be an enum (we currently use 'str' in MachineInfo).

Example: say we want to deprecate block driver "vfat",
i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
multiple places; let's ignore all but BlockdevOptions.  We need to add
@support-status to something that provides information on
BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
providing information on either of the two, because QAPI/QMP
introspection has been sufficient.  What now?

Can we add deprecation information to (general) QAPI/QMP introspection
instead of ad hoc queries?

Kevin's proposed QAPI feature flags[*] extend the QAPI language so that
struct types can optionally have a list of feature flags, which are
strings.  Struct types suffice for his immediate needs.  I'd like to use
feature flags to mark deprecation by tacking a "deprecated" feature onto
whatever is deprecated.  This obviously needs feature support for
everything we want to be able to deprecate: commands, and events, as
well as members of enum and object types.

Example: to deprecate block driver "vfat", add feature "deprecated" to
BlockdevDriver member @vfat.

Unlike your patches, this does not require finding a "somewhere" that
provides information on "something".  You simply tack "deprecated" right
onto "something".

Your patches provide more information, however: human-readable messages.

Food for thought :)


[*] Hiding in
Subject: [PATCH 0/4] file-posix: Add dynamic-auto-read-only QAPI feature
Date: Mon,  8 Apr 2019 16:35:39 +0200
Message-Id: <20190408143543.3982-1-kwolf@redhat.com>

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
> Eduardo Habkost <ehabkost@redhat.com> writes:
> 
> > This series adds machine type deprecation information to the
> > output of the `query-machines` QMP command.  With this, libvirt
> > and management software will be able to show this information to
> > users and/or suggest changes to VM configuration to avoid
> > deprecated machine types.
> 
> This overlaps with something I want to try, namely using Kevin's
> proposed QAPI feature flags for deprecation markings.  Let's compare the
> two.
> 
> To mark something as deprecated with your patches, you add a
> @support-status member somewhere, where "somewhere" is related to
> "something" by "provides information on".
> 
> Example: MachineInfo (returned by query-machines) provides information
> on possible values of -machine parameter type.  If -machine was
> QAPIfied, it would provide information on possible values of a QAPI
> object type's member.  The type might be anonymous.  The member should
> be an enum (we currently use 'str' in MachineInfo).

QAPIfying -machine, -cpu, and -device would be wonderful.

> 
> Example: say we want to deprecate block driver "vfat",
> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
> multiple places; let's ignore all but BlockdevOptions.  We need to add
> @support-status to something that provides information on
> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
> providing information on either of the two, because QAPI/QMP
> introspection has been sufficient.  What now?
> 
> Can we add deprecation information to (general) QAPI/QMP introspection

Yes, we can.  I think it's a good idea.  But:

> instead of ad hoc queries?

I'm not sure about the "instead of" part.  I don't want perfect
to be the enemy of done, and I don't want QAPIfication of
-machine to be a requirement to start reporting machine type
deprecation information.

> 
> Kevin's proposed QAPI feature flags[*] extend the QAPI language so that
> struct types can optionally have a list of feature flags, which are
> strings.  Struct types suffice for his immediate needs.  I'd like to use
> feature flags to mark deprecation by tacking a "deprecated" feature onto
> whatever is deprecated.  This obviously needs feature support for
> everything we want to be able to deprecate: commands, and events, as
> well as members of enum and object types.
> 
> Example: to deprecate block driver "vfat", add feature "deprecated" to
> BlockdevDriver member @vfat.
> 
> Unlike your patches, this does not require finding a "somewhere" that
> provides information on "something".  You simply tack "deprecated" right
> onto "something".
> 
> Your patches provide more information, however: human-readable messages.

It also includes a machine-friendly suggested alternative (which
I think is even more important that the human-readable message).

We could extend QAPI introspection to return that if necessary,
right?


> 
> Food for thought :)
> 
> 
> [*] Hiding in
> Subject: [PATCH 0/4] file-posix: Add dynamic-auto-read-only QAPI feature
> Date: Mon,  8 Apr 2019 16:35:39 +0200
> Message-Id: <20190408143543.3982-1-kwolf@redhat.com>

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
>> Eduardo Habkost <ehabkost@redhat.com> writes:
>> 
>> > This series adds machine type deprecation information to the
>> > output of the `query-machines` QMP command.  With this, libvirt
>> > and management software will be able to show this information to
>> > users and/or suggest changes to VM configuration to avoid
>> > deprecated machine types.
>> 
>> This overlaps with something I want to try, namely using Kevin's
>> proposed QAPI feature flags for deprecation markings.  Let's compare the
>> two.
>> 
>> To mark something as deprecated with your patches, you add a
>> @support-status member somewhere, where "somewhere" is related to
>> "something" by "provides information on".
>> 
>> Example: MachineInfo (returned by query-machines) provides information
>> on possible values of -machine parameter type.  If -machine was
>> QAPIfied, it would provide information on possible values of a QAPI
>> object type's member.  The type might be anonymous.  The member should
>> be an enum (we currently use 'str' in MachineInfo).
>
> QAPIfying -machine, -cpu, and -device would be wonderful.
>
>> 
>> Example: say we want to deprecate block driver "vfat",
>> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
>> multiple places; let's ignore all but BlockdevOptions.  We need to add
>> @support-status to something that provides information on
>> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
>> providing information on either of the two, because QAPI/QMP
>> introspection has been sufficient.  What now?
>> 
>> Can we add deprecation information to (general) QAPI/QMP introspection
>
> Yes, we can.  I think it's a good idea.  But:
>
>> instead of ad hoc queries?
>
> I'm not sure about the "instead of" part.  I don't want perfect
> to be the enemy of done, and I don't want QAPIfication of
> -machine to be a requirement to start reporting machine type
> deprecation information.

Valid point.  Still, I believe we should at least try to predict how the
pieces we create now would fit with the pieces we plan to create later
on.

Note that full QAPIfication of -machine isn't necessary to make QAPI
feature "deprecated" work for machine types.  Turning MachineInfo member
@name into an enum, so we can tack "deprecated" onto its values, would
suffice.

Such a QAPIfication of machine types is still hard: QOM types are
defined at compile time just like the QAPI schema, but their definition
is distributed, and collected into one place only at run time.  I
discussed this on slide 39 of my "QEMU interface introspection: From
hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
just a special case of QOM.  Choices listed there:

* Collect drivers at compile time? Hard...
* Make QAPI schema dynamic? Hard...
* Forgo driver-specific arguments in schema?
  Defeats introspection...

I'd like to add to the last item:

  Provide QOM introspection on par with QAPI schema introspection

The QOM introspection we have (qom-list-types etc. is not on par.

Back to exposing machine type deprecation.

I'm doubtful your proposed solution can be applied widely.  It relies on
adding @support-status to something that provides information on
whatever is deprecated.  The initial use is with a something that is an
ad hoc query, namely query-machines.  To use it, the management
application needs to understand what query-machines' @support-status
applies to.  Certainly feasible.  But I fear every use will be a special
case.  Furthermore, a suitable ad hoc query need not exist.  What then?
Create suitable ad hoc queries just for communicating deprecation?

Instead, I'd like us to think about a more genral solution.  Or perhaps
two: one for properly QAPIfied stuff, and one for QOM.

>> Kevin's proposed QAPI feature flags[*] extend the QAPI language so that
>> struct types can optionally have a list of feature flags, which are
>> strings.  Struct types suffice for his immediate needs.  I'd like to use
>> feature flags to mark deprecation by tacking a "deprecated" feature onto
>> whatever is deprecated.  This obviously needs feature support for
>> everything we want to be able to deprecate: commands, and events, as
>> well as members of enum and object types.
>> 
>> Example: to deprecate block driver "vfat", add feature "deprecated" to
>> BlockdevDriver member @vfat.
>> 
>> Unlike your patches, this does not require finding a "somewhere" that
>> provides information on "something".  You simply tack "deprecated" right
>> onto "something".
>> 
>> Your patches provide more information, however: human-readable messages.
>
> It also includes a machine-friendly suggested alternative (which
> I think is even more important that the human-readable message).

I agree we should point to a preferred replacement whenever we deprecate
something.

We have to do it in documentation.  And we generally do, in
qemu-deprecated.texi.

How useful would doing it in QMP as well be?  Depends on what management
applications can do with the additional information.

> We could extend QAPI introspection to return that if necessary,
> right?

I'm confident we can come up with *something*.  It might kill the neat
and simple "use QAPI features to communicate deprecation" idea, though.

>> Food for thought :)
>> 
>> 
>> [*] Hiding in
>> Subject: [PATCH 0/4] file-posix: Add dynamic-auto-read-only QAPI feature
>> Date: Mon,  8 Apr 2019 16:35:39 +0200
>> Message-Id: <20190408143543.3982-1-kwolf@redhat.com>

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> Eduardo Habkost <ehabkost@redhat.com> writes:
> 
> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> >> 
> >> > This series adds machine type deprecation information to the
> >> > output of the `query-machines` QMP command.  With this, libvirt
> >> > and management software will be able to show this information to
> >> > users and/or suggest changes to VM configuration to avoid
> >> > deprecated machine types.
> >> 
> >> This overlaps with something I want to try, namely using Kevin's
> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
> >> two.
> >> 
> >> To mark something as deprecated with your patches, you add a
> >> @support-status member somewhere, where "somewhere" is related to
> >> "something" by "provides information on".
> >> 
> >> Example: MachineInfo (returned by query-machines) provides information
> >> on possible values of -machine parameter type.  If -machine was
> >> QAPIfied, it would provide information on possible values of a QAPI
> >> object type's member.  The type might be anonymous.  The member should
> >> be an enum (we currently use 'str' in MachineInfo).
> >
> > QAPIfying -machine, -cpu, and -device would be wonderful.
> >
> >> 
> >> Example: say we want to deprecate block driver "vfat",
> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
> >> @support-status to something that provides information on
> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
> >> providing information on either of the two, because QAPI/QMP
> >> introspection has been sufficient.  What now?
> >> 
> >> Can we add deprecation information to (general) QAPI/QMP introspection
> >
> > Yes, we can.  I think it's a good idea.  But:
> >
> >> instead of ad hoc queries?
> >
> > I'm not sure about the "instead of" part.  I don't want perfect
> > to be the enemy of done, and I don't want QAPIfication of
> > -machine to be a requirement to start reporting machine type
> > deprecation information.
> 
> Valid point.  Still, I believe we should at least try to predict how the
> pieces we create now would fit with the pieces we plan to create later
> on.

Sure.

> 
> Note that full QAPIfication of -machine isn't necessary to make QAPI
> feature "deprecated" work for machine types.  Turning MachineInfo member
> @name into an enum, so we can tack "deprecated" onto its values, would
> suffice.
> 
> Such a QAPIfication of machine types is still hard: QOM types are
> defined at compile time just like the QAPI schema, but their definition
> is distributed, and collected into one place only at run time.  I
> discussed this on slide 39 of my "QEMU interface introspection: From
> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
> just a special case of QOM.  Choices listed there:
> 
> * Collect drivers at compile time? Hard...
> * Make QAPI schema dynamic? Hard...
> * Forgo driver-specific arguments in schema?
>   Defeats introspection...
> 
> I'd like to add to the last item:
> 
>   Provide QOM introspection on par with QAPI schema introspection
> 
> The QOM introspection we have (qom-list-types etc. is not on par.

Agreed, but do we really want to do it?  We have been avoiding
exposing QOM internals to the outside on purpose.  I believe
there are at least two reasons for that:

1) Not every QOM type/property is supposed to be visible to the
   outside (and nobody really knows what's the full set of
   supported external QOM interfaces);
2) QAPI is our preferred interface interface specification/introspection
   mechanism.

> 
> Back to exposing machine type deprecation.
> 
> I'm doubtful your proposed solution can be applied widely.  It relies on
> adding @support-status to something that provides information on
> whatever is deprecated.  The initial use is with a something that is an
> ad hoc query, namely query-machines.  To use it, the management
> application needs to understand what query-machines' @support-status
> applies to.  Certainly feasible.  But I fear every use will be a special
> case.  Furthermore, a suitable ad hoc query need not exist.  What then?
> Create suitable ad hoc queries just for communicating deprecation?
> 
> Instead, I'd like us to think about a more genral solution.  Or perhaps
> two: one for properly QAPIfied stuff, and one for QOM.

Should we really spend our time designing a second solution, if
we could build this on top of QAPI abstractions?  Making the QAPI
schema dynamic might be hard, but reinventing QAPI and
maintaining the two systems in parallel seems harder.


> 
> >> Kevin's proposed QAPI feature flags[*] extend the QAPI language so that
> >> struct types can optionally have a list of feature flags, which are
> >> strings.  Struct types suffice for his immediate needs.  I'd like to use
> >> feature flags to mark deprecation by tacking a "deprecated" feature onto
> >> whatever is deprecated.  This obviously needs feature support for
> >> everything we want to be able to deprecate: commands, and events, as
> >> well as members of enum and object types.
> >> 
> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
> >> BlockdevDriver member @vfat.
> >> 
> >> Unlike your patches, this does not require finding a "somewhere" that
> >> provides information on "something".  You simply tack "deprecated" right
> >> onto "something".
> >> 
> >> Your patches provide more information, however: human-readable messages.
> >
> > It also includes a machine-friendly suggested alternative (which
> > I think is even more important that the human-readable message).
> 
> I agree we should point to a preferred replacement whenever we deprecate
> something.
> 
> We have to do it in documentation.  And we generally do, in
> qemu-deprecated.texi.
> 
> How useful would doing it in QMP as well be?  Depends on what management
> applications can do with the additional information.

I expect it to be useful for things that have obvious
replacements, like old machine type or CPU model versions.

> 
> > We could extend QAPI introspection to return that if necessary,
> > right?
> 
> I'm confident we can come up with *something*.  It might kill the neat
> and simple "use QAPI features to communicate deprecation" idea, though.
> 

If something is important enough to be communicated through
stderr, it's important enough to be communicated through QMP.
Is that enough reason to provide something more complex?

Do we need QAPI features to be just strings?  Can't they be a
more complex type, like a QAPI alternate?


> >> Food for thought :)
> >> 
> >> 
> >> [*] Hiding in
> >> Subject: [PATCH 0/4] file-posix: Add dynamic-auto-read-only QAPI feature
> >> Date: Mon,  8 Apr 2019 16:35:39 +0200
> >> Message-Id: <20190408143543.3982-1-kwolf@redhat.com>

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Markus Armbruster]

We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.

Eduardo Habkost <ehabkost@redhat.com> writes:

> On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
>> Eduardo Habkost <ehabkost@redhat.com> writes:
>> 
>> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
>> >> Eduardo Habkost <ehabkost@redhat.com> writes:
>> >> 
>> >> > This series adds machine type deprecation information to the
>> >> > output of the `query-machines` QMP command.  With this, libvirt
>> >> > and management software will be able to show this information to
>> >> > users and/or suggest changes to VM configuration to avoid
>> >> > deprecated machine types.
>> >> 
>> >> This overlaps with something I want to try, namely using Kevin's
>> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
>> >> two.
>> >> 
>> >> To mark something as deprecated with your patches, you add a
>> >> @support-status member somewhere, where "somewhere" is related to
>> >> "something" by "provides information on".
>> >> 
>> >> Example: MachineInfo (returned by query-machines) provides information
>> >> on possible values of -machine parameter type.  If -machine was
>> >> QAPIfied, it would provide information on possible values of a QAPI
>> >> object type's member.  The type might be anonymous.  The member should
>> >> be an enum (we currently use 'str' in MachineInfo).
>> >
>> > QAPIfying -machine, -cpu, and -device would be wonderful.
>> >
>> >> 
>> >> Example: say we want to deprecate block driver "vfat",
>> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
>> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
>> >> @support-status to something that provides information on
>> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
>> >> providing information on either of the two, because QAPI/QMP
>> >> introspection has been sufficient.  What now?
>> >> 
>> >> Can we add deprecation information to (general) QAPI/QMP introspection
>> >
>> > Yes, we can.  I think it's a good idea.  But:
>> >
>> >> instead of ad hoc queries?
>> >
>> > I'm not sure about the "instead of" part.  I don't want perfect
>> > to be the enemy of done, and I don't want QAPIfication of
>> > -machine to be a requirement to start reporting machine type
>> > deprecation information.
>> 
>> Valid point.  Still, I believe we should at least try to predict how the
>> pieces we create now would fit with the pieces we plan to create later
>> on.
>
> Sure.
>
>> 
>> Note that full QAPIfication of -machine isn't necessary to make QAPI
>> feature "deprecated" work for machine types.  Turning MachineInfo member
>> @name into an enum, so we can tack "deprecated" onto its values, would
>> suffice.
>> 
>> Such a QAPIfication of machine types is still hard: QOM types are
>> defined at compile time just like the QAPI schema, but their definition
>> is distributed, and collected into one place only at run time.  I
>> discussed this on slide 39 of my "QEMU interface introspection: From
>> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
>> just a special case of QOM.  Choices listed there:
>> 
>> * Collect drivers at compile time? Hard...
>> * Make QAPI schema dynamic? Hard...
>> * Forgo driver-specific arguments in schema?
>>   Defeats introspection...
>> 
>> I'd like to add to the last item:
>> 
>>   Provide QOM introspection on par with QAPI schema introspection
>> 
>> The QOM introspection we have (qom-list-types etc. is not on par.
>
> Agreed, but do we really want to do it?  We have been avoiding
> exposing QOM internals to the outside on purpose.  I believe
> there are at least two reasons for that:
>
> 1) Not every QOM type/property is supposed to be visible to the
>    outside

True.

However, the parts of QOM exposed via device_add and object-add are
definitely part of the stable external interface (unless explicitly
marked unstable).

>            (and nobody really knows what's the full set of
>    supported external QOM interfaces);

Also true.  And terrible.

> 2) QAPI is our preferred interface interface specification/introspection
>    mechanism.

When preferences and requirements collide, preferences tend to get run
over.

The QAPI schema is *declarative*: the schema declares QAPI objects and
properties.  We generate C from the schema, which we then compile and
link into QEMU.

QOM is by design *imperative*: we execute compiled C at QEMU run-time to
define QOM objects and properties.  Maximizes flexibility.  See also
Turing tarpit.

No matter how much we'd prefer to use QAPI to specify external
interfaces to QOM, we can't without making QAPI much more dynamic or QOM
much more static.  Either is hard.  Quite possibly infeasible.

We could try to extend QAPI/QMP introspection to somehow merge in
additional information at run-time[1].  Could be regarded as a limited
way to make QAPI more dynamic.  This is in the "vague idea, not sure
it's feasible" stage.

We could try to rearchitect QOM so that you can optionally specify QOM
stuff in the QAPI schema, then require that for QOM stuff that's part of
a stable external interface.  Same "vague idea" stage, feasibility even
more doubtful.

If I remember correctly, Paolo suggested to abandon the idea to have
query-qmp-schema cover device_add as infeasible.  Instead, cover it
separately.

I think this separate introspection mechanism should be as similar to
query-qmp-schema as practical.  It should cover not just device_add, but
also object-add, and whatever other external interface to QOM we deem
stable.

Should there be more stable external interfaces that can't be defined in
the QAPI schema, we might want to cover them in this second
introspection mechanism, too.

>> Back to exposing machine type deprecation.
>> 
>> I'm doubtful your proposed solution can be applied widely.  It relies on
>> adding @support-status to something that provides information on
>> whatever is deprecated.  The initial use is with a something that is an
>> ad hoc query, namely query-machines.  To use it, the management
>> application needs to understand what query-machines' @support-status
>> applies to.  Certainly feasible.  But I fear every use will be a special
>> case.  Furthermore, a suitable ad hoc query need not exist.  What then?
>> Create suitable ad hoc queries just for communicating deprecation?
>> 
>> Instead, I'd like us to think about a more genral solution.  Or perhaps
>> two: one for properly QAPIfied stuff, and one for QOM.
>
> Should we really spend our time designing a second solution, if
> we could build this on top of QAPI abstractions?  Making the QAPI
> schema dynamic might be hard, but reinventing QAPI and
> maintaining the two systems in parallel seems harder.

I'd love to see a practical way forward that keeps QAPI/QMP
introspection the only game in town.

>> >> Kevin's proposed QAPI feature flags[*] extend the QAPI language so that
>> >> struct types can optionally have a list of feature flags, which are
>> >> strings.  Struct types suffice for his immediate needs.  I'd like to use
>> >> feature flags to mark deprecation by tacking a "deprecated" feature onto
>> >> whatever is deprecated.  This obviously needs feature support for
>> >> everything we want to be able to deprecate: commands, and events, as
>> >> well as members of enum and object types.
>> >> 
>> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
>> >> BlockdevDriver member @vfat.
>> >> 
>> >> Unlike your patches, this does not require finding a "somewhere" that
>> >> provides information on "something".  You simply tack "deprecated" right
>> >> onto "something".
>> >> 
>> >> Your patches provide more information, however: human-readable messages.
>> >
>> > It also includes a machine-friendly suggested alternative (which
>> > I think is even more important that the human-readable message).
>> 
>> I agree we should point to a preferred replacement whenever we deprecate
>> something.
>> 
>> We have to do it in documentation.  And we generally do, in
>> qemu-deprecated.texi.
>> 
>> How useful would doing it in QMP as well be?  Depends on what management
>> applications can do with the additional information.
>
> I expect it to be useful for things that have obvious
> replacements, like old machine type or CPU model versions.

I doubt a management application should apply suggested replacements
automatically, and I doubt libvirt would.  Not even when QEMU developers
deem them "obvious".

>> > We could extend QAPI introspection to return that if necessary,
>> > right?
>> 
>> I'm confident we can come up with *something*.  It might kill the neat
>> and simple "use QAPI features to communicate deprecation" idea, though.
>
> If something is important enough to be communicated through
> stderr, it's important enough to be communicated through QMP.

Mostly.  Differences are due to the different consumers.

stderr is primarily for human users.  We print stuff useful to human
users.

QMP is primarily for machines, secondarily for the humans building these
machines.  We send stuff useful to the machines themselves, and stuff
the machines can use to be more useful for their users (which may be
machines or humans).  We can also send stuff to help the humans building
the machines.

In any case, the information we provide is limited by the cost to
provide it.

> Is that enough reason to provide something more complex?

We need to consider cost / benefit.

On benefit, I'd like to know what libvirt would do with the additional
information beyond logging it.

Is the additional information you propose to provide static or dynamic?

By "static", I mean each occurence of a feature in the QAPI schema is
tied to one fixed instance of "additional information".

> Do we need QAPI features to be just strings?  Can't they be a
> more complex type, like a QAPI alternate?

Adds complexity.

We currently imagine QAPI features enum-like, i.e. a list of strings,
optionally with conditions.  The conditions are evaluated at QAPI
generation time, and not visible in introspection.

This is probably the stupidest solution that could possibly work.  The
structure of features is trivial.

More expressive solutions include:

* List of 'any'.  Feels like a bad idea, because it's completely
  unstructured.

* List of some 'QapiFeatures' object type.  Lets us expose the variable
  structure of features in introspection.

* List of some 'QapiFeatures' alternate type.  Like the previous, but
  permits coding simple feature flags as strings.

All of the more expressive solutions I listed treat the additional
information as dynamic.  Overly general in case the information is
actually always static.

>> >> Food for thought :)
>> >> 
>> >> 
>> >> [*] Hiding in
>> >> Subject: [PATCH 0/4] file-posix: Add dynamic-auto-read-only QAPI feature
>> >> Date: Mon,  8 Apr 2019 16:35:39 +0200
>> >> Message-Id: <20190408143543.3982-1-kwolf@redhat.com>


[1] Special case of "merge additional information into QAPI/QMP
introspection at run-time, relegated to a footnote, because I think it's
of mostly historical interest now.

Qdev was designed to be declarative, but the declarations always got
collected only at run-time.  It has since been rebased onto imperative
QOM.  Since you can mix declarative qdev and imperative QOM, the
combination is effectively imperative.

We could collect the declarative parts of qdev at compile-time somehow,
and fold them into QAPI introspection.  That's the "Collect drives at
compile time" item from the slide I quoted.  I think this idea has
become pretty much worthless, since it would cover device_add only in
part, and object-add not at all.

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Daniel P. Berrangé]

On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
> We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
> 
> Eduardo Habkost <ehabkost@redhat.com> writes:
> 
> > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> >> 
> >> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
> >> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> >> >> 
> >> >> > This series adds machine type deprecation information to the
> >> >> > output of the `query-machines` QMP command.  With this, libvirt
> >> >> > and management software will be able to show this information to
> >> >> > users and/or suggest changes to VM configuration to avoid
> >> >> > deprecated machine types.
> >> >> 
> >> >> This overlaps with something I want to try, namely using Kevin's
> >> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
> >> >> two.
> >> >> 
> >> >> To mark something as deprecated with your patches, you add a
> >> >> @support-status member somewhere, where "somewhere" is related to
> >> >> "something" by "provides information on".
> >> >> 
> >> >> Example: MachineInfo (returned by query-machines) provides information
> >> >> on possible values of -machine parameter type.  If -machine was
> >> >> QAPIfied, it would provide information on possible values of a QAPI
> >> >> object type's member.  The type might be anonymous.  The member should
> >> >> be an enum (we currently use 'str' in MachineInfo).
> >> >
> >> > QAPIfying -machine, -cpu, and -device would be wonderful.
> >> >
> >> >> 
> >> >> Example: say we want to deprecate block driver "vfat",
> >> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
> >> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
> >> >> @support-status to something that provides information on
> >> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
> >> >> providing information on either of the two, because QAPI/QMP
> >> >> introspection has been sufficient.  What now?
> >> >> 
> >> >> Can we add deprecation information to (general) QAPI/QMP introspection
> >> >
> >> > Yes, we can.  I think it's a good idea.  But:
> >> >
> >> >> instead of ad hoc queries?
> >> >
> >> > I'm not sure about the "instead of" part.  I don't want perfect
> >> > to be the enemy of done, and I don't want QAPIfication of
> >> > -machine to be a requirement to start reporting machine type
> >> > deprecation information.
> >> 
> >> Valid point.  Still, I believe we should at least try to predict how the
> >> pieces we create now would fit with the pieces we plan to create later
> >> on.
> >
> > Sure.
> >
> >> 
> >> Note that full QAPIfication of -machine isn't necessary to make QAPI
> >> feature "deprecated" work for machine types.  Turning MachineInfo member
> >> @name into an enum, so we can tack "deprecated" onto its values, would
> >> suffice.
> >> 
> >> Such a QAPIfication of machine types is still hard: QOM types are
> >> defined at compile time just like the QAPI schema, but their definition
> >> is distributed, and collected into one place only at run time.  I
> >> discussed this on slide 39 of my "QEMU interface introspection: From
> >> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
> >> just a special case of QOM.  Choices listed there:
> >> 
> >> * Collect drivers at compile time? Hard...
> >> * Make QAPI schema dynamic? Hard...
> >> * Forgo driver-specific arguments in schema?
> >>   Defeats introspection...
> >> 
> >> I'd like to add to the last item:
> >> 
> >>   Provide QOM introspection on par with QAPI schema introspection
> >> 
> >> The QOM introspection we have (qom-list-types etc. is not on par.
> >
> > Agreed, but do we really want to do it?  We have been avoiding
> > exposing QOM internals to the outside on purpose.  I believe
> > there are at least two reasons for that:
> >
> > 1) Not every QOM type/property is supposed to be visible to the
> >    outside
> 
> True.
> 
> However, the parts of QOM exposed via device_add and object-add are
> definitely part of the stable external interface (unless explicitly
> marked unstable).
> 
> >            (and nobody really knows what's the full set of
> >    supported external QOM interfaces);
> 
> Also true.  And terrible.
> 
> > 2) QAPI is our preferred interface interface specification/introspection
> >    mechanism.
> 
> When preferences and requirements collide, preferences tend to get run
> over.
> 
> The QAPI schema is *declarative*: the schema declares QAPI objects and
> properties.  We generate C from the schema, which we then compile and
> link into QEMU.
> 
> QOM is by design *imperative*: we execute compiled C at QEMU run-time to
> define QOM objects and properties.  Maximizes flexibility.  See also
> Turing tarpit.
> 
> No matter how much we'd prefer to use QAPI to specify external
> interfaces to QOM, we can't without making QAPI much more dynamic or QOM
> much more static.  Either is hard.  Quite possibly infeasible.
> 
> We could try to extend QAPI/QMP introspection to somehow merge in
> additional information at run-time[1].  Could be regarded as a limited
> way to make QAPI more dynamic.  This is in the "vague idea, not sure
> it's feasible" stage.
> 
> We could try to rearchitect QOM so that you can optionally specify QOM
> stuff in the QAPI schema, then require that for QOM stuff that's part of
> a stable external interface.  Same "vague idea" stage, feasibility even
> more doubtful.

I think it is feasible to use QAPI to declare the QOM object type,
QOM parent type, list of QOM interfaces and QOM properties in a
declarative manner. From that generate all the tedious boilerplate
code. The dev then just has to provide the "interesting" code for
the object.

I'd really like to do a PoC of this but never have free time :-(
Perhaps an interesting task for someone who wants to delve into
some new work...


> >> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
> >> >> BlockdevDriver member @vfat.
> >> >> 
> >> >> Unlike your patches, this does not require finding a "somewhere" that
> >> >> provides information on "something".  You simply tack "deprecated" right
> >> >> onto "something".
> >> >> 
> >> >> Your patches provide more information, however: human-readable messages.
> >> >
> >> > It also includes a machine-friendly suggested alternative (which
> >> > I think is even more important that the human-readable message).
> >> 
> >> I agree we should point to a preferred replacement whenever we deprecate
> >> something.
> >> 
> >> We have to do it in documentation.  And we generally do, in
> >> qemu-deprecated.texi.
> >> 
> >> How useful would doing it in QMP as well be?  Depends on what management
> >> applications can do with the additional information.
> >
> > I expect it to be useful for things that have obvious
> > replacements, like old machine type or CPU model versions.
> 
> I doubt a management application should apply suggested replacements
> automatically, and I doubt libvirt would.  Not even when QEMU developers
> deem them "obvious".

We certainly won't apply the suggested replacement as in many cases
it is not going to be a functionally equivalent drop-in.

If QEMU logs it to stderr, it will end up in the per-VM log file
libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
doesn't log it to stderr, then libvirt would just write it to
that same log file itself.

If libvirt gains some API or event for notifying apps of deprecation
we might bubble it up to the mgmt app that way.

I still feel it is useful to have the suggested replacement in the
logs, rather  than only leaving it in qemu-deprecated.texi.  This
way the info is immediately visible to both app developers and any
support person dealing with bugs.

If the app dev see the suggested replacement upfront they're more
likely to make an immediate decision to update their code if the
suggestion is trivial. If they need to go find the QEMU docs to
lookup what action is required I feel they'll more likely just
put the item on their long todo list where it will languish.

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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Thu, May 09, 2019 at 10:14:52AM +0100, Daniel P. Berrangé wrote:
> On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
> > We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
> > 
> > Eduardo Habkost <ehabkost@redhat.com> writes:
> > 
> > > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> > >> Eduardo Habkost <ehabkost@redhat.com> writes:
> > >> 
> > >> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
> > >> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> > >> >> 
> > >> >> > This series adds machine type deprecation information to the
> > >> >> > output of the `query-machines` QMP command.  With this, libvirt
> > >> >> > and management software will be able to show this information to
> > >> >> > users and/or suggest changes to VM configuration to avoid
> > >> >> > deprecated machine types.
> > >> >> 
> > >> >> This overlaps with something I want to try, namely using Kevin's
> > >> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
> > >> >> two.
> > >> >> 
> > >> >> To mark something as deprecated with your patches, you add a
> > >> >> @support-status member somewhere, where "somewhere" is related to
> > >> >> "something" by "provides information on".
> > >> >> 
> > >> >> Example: MachineInfo (returned by query-machines) provides information
> > >> >> on possible values of -machine parameter type.  If -machine was
> > >> >> QAPIfied, it would provide information on possible values of a QAPI
> > >> >> object type's member.  The type might be anonymous.  The member should
> > >> >> be an enum (we currently use 'str' in MachineInfo).
> > >> >
> > >> > QAPIfying -machine, -cpu, and -device would be wonderful.
> > >> >
> > >> >> 
> > >> >> Example: say we want to deprecate block driver "vfat",
> > >> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
> > >> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
> > >> >> @support-status to something that provides information on
> > >> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
> > >> >> providing information on either of the two, because QAPI/QMP
> > >> >> introspection has been sufficient.  What now?
> > >> >> 
> > >> >> Can we add deprecation information to (general) QAPI/QMP introspection
> > >> >
> > >> > Yes, we can.  I think it's a good idea.  But:
> > >> >
> > >> >> instead of ad hoc queries?
> > >> >
> > >> > I'm not sure about the "instead of" part.  I don't want perfect
> > >> > to be the enemy of done, and I don't want QAPIfication of
> > >> > -machine to be a requirement to start reporting machine type
> > >> > deprecation information.
> > >> 
> > >> Valid point.  Still, I believe we should at least try to predict how the
> > >> pieces we create now would fit with the pieces we plan to create later
> > >> on.
> > >
> > > Sure.
> > >
> > >> 
> > >> Note that full QAPIfication of -machine isn't necessary to make QAPI
> > >> feature "deprecated" work for machine types.  Turning MachineInfo member
> > >> @name into an enum, so we can tack "deprecated" onto its values, would
> > >> suffice.
> > >> 
> > >> Such a QAPIfication of machine types is still hard: QOM types are
> > >> defined at compile time just like the QAPI schema, but their definition
> > >> is distributed, and collected into one place only at run time.  I
> > >> discussed this on slide 39 of my "QEMU interface introspection: From
> > >> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
> > >> just a special case of QOM.  Choices listed there:
> > >> 
> > >> * Collect drivers at compile time? Hard...
> > >> * Make QAPI schema dynamic? Hard...
> > >> * Forgo driver-specific arguments in schema?
> > >>   Defeats introspection...
> > >> 
> > >> I'd like to add to the last item:
> > >> 
> > >>   Provide QOM introspection on par with QAPI schema introspection
> > >> 
> > >> The QOM introspection we have (qom-list-types etc. is not on par.
> > >
> > > Agreed, but do we really want to do it?  We have been avoiding
> > > exposing QOM internals to the outside on purpose.  I believe
> > > there are at least two reasons for that:
> > >
> > > 1) Not every QOM type/property is supposed to be visible to the
> > >    outside
> > 
> > True.
> > 
> > However, the parts of QOM exposed via device_add and object-add are
> > definitely part of the stable external interface (unless explicitly
> > marked unstable).
> > 
> > >            (and nobody really knows what's the full set of
> > >    supported external QOM interfaces);
> > 
> > Also true.  And terrible.
> > 
> > > 2) QAPI is our preferred interface interface specification/introspection
> > >    mechanism.
> > 
> > When preferences and requirements collide, preferences tend to get run
> > over.
> > 
> > The QAPI schema is *declarative*: the schema declares QAPI objects and
> > properties.  We generate C from the schema, which we then compile and
> > link into QEMU.
> > 
> > QOM is by design *imperative*: we execute compiled C at QEMU run-time to
> > define QOM objects and properties.  Maximizes flexibility.  See also
> > Turing tarpit.
> > 
> > No matter how much we'd prefer to use QAPI to specify external
> > interfaces to QOM, we can't without making QAPI much more dynamic or QOM
> > much more static.  Either is hard.  Quite possibly infeasible.
> > 
> > We could try to extend QAPI/QMP introspection to somehow merge in
> > additional information at run-time[1].  Could be regarded as a limited
> > way to make QAPI more dynamic.  This is in the "vague idea, not sure
> > it's feasible" stage.
> > 
> > We could try to rearchitect QOM so that you can optionally specify QOM
> > stuff in the QAPI schema, then require that for QOM stuff that's part of
> > a stable external interface.  Same "vague idea" stage, feasibility even
> > more doubtful.
> 
> I think it is feasible to use QAPI to declare the QOM object type,
> QOM parent type, list of QOM interfaces and QOM properties in a
> declarative manner. From that generate all the tedious boilerplate
> code. The dev then just has to provide the "interesting" code for
> the object.
> 
> I'd really like to do a PoC of this but never have free time :-(
> Perhaps an interesting task for someone who wants to delve into
> some new work...
> 
> 
> > >> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
> > >> >> BlockdevDriver member @vfat.
> > >> >> 
> > >> >> Unlike your patches, this does not require finding a "somewhere" that
> > >> >> provides information on "something".  You simply tack "deprecated" right
> > >> >> onto "something".
> > >> >> 
> > >> >> Your patches provide more information, however: human-readable messages.
> > >> >
> > >> > It also includes a machine-friendly suggested alternative (which
> > >> > I think is even more important that the human-readable message).
> > >> 
> > >> I agree we should point to a preferred replacement whenever we deprecate
> > >> something.
> > >> 
> > >> We have to do it in documentation.  And we generally do, in
> > >> qemu-deprecated.texi.
> > >> 
> > >> How useful would doing it in QMP as well be?  Depends on what management
> > >> applications can do with the additional information.
> > >
> > > I expect it to be useful for things that have obvious
> > > replacements, like old machine type or CPU model versions.
> > 
> > I doubt a management application should apply suggested replacements
> > automatically, and I doubt libvirt would.  Not even when QEMU developers
> > deem them "obvious".
> 
> We certainly won't apply the suggested replacement as in many cases
> it is not going to be a functionally equivalent drop-in.

Who's "we"?

> 
> If QEMU logs it to stderr, it will end up in the per-VM log file
> libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
> doesn't log it to stderr, then libvirt would just write it to
> that same log file itself.
> 
> If libvirt gains some API or event for notifying apps of deprecation
> we might bubble it up to the mgmt app that way.
> 
> I still feel it is useful to have the suggested replacement in the
> logs, rather  than only leaving it in qemu-deprecated.texi.  This
> way the info is immediately visible to both app developers and any
> support person dealing with bugs.
> 
> If the app dev see the suggested replacement upfront they're more
> likely to make an immediate decision to update their code if the
> suggestion is trivial. If they need to go find the QEMU docs to
> lookup what action is required I feel they'll more likely just
> put the item on their long todo list where it will languish.

Agreed.  However, note that the audience for deprecation
information is not just developers and support people.  End users
need to know when they are relying on a deprecated feature, and
applications should make it as easy as possible for them to
update their configurations.

I'm not suggesting the alternative would be applied
automatically.  But having the alternative available in a
machine-friendly way may be the difference between a unhelpful UI
that just tells the user there's some problem but can't give a
solution, and one that can really assist the user to fix the
problem.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Daniel P. Berrangé]

On Thu, May 09, 2019 at 12:52:47PM -0300, Eduardo Habkost wrote:
> On Thu, May 09, 2019 at 10:14:52AM +0100, Daniel P. Berrangé wrote:
> > On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
> > > We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
> > > 
> > > Eduardo Habkost <ehabkost@redhat.com> writes:
> > > 
> > > > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> > > >> Eduardo Habkost <ehabkost@redhat.com> writes:
> > > >> 
> > > >> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
> > > >> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> > > >> >> 
> > > >> >> > This series adds machine type deprecation information to the
> > > >> >> > output of the `query-machines` QMP command.  With this, libvirt
> > > >> >> > and management software will be able to show this information to
> > > >> >> > users and/or suggest changes to VM configuration to avoid
> > > >> >> > deprecated machine types.
> > > >> >> 
> > > >> >> This overlaps with something I want to try, namely using Kevin's
> > > >> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
> > > >> >> two.
> > > >> >> 
> > > >> >> To mark something as deprecated with your patches, you add a
> > > >> >> @support-status member somewhere, where "somewhere" is related to
> > > >> >> "something" by "provides information on".
> > > >> >> 
> > > >> >> Example: MachineInfo (returned by query-machines) provides information
> > > >> >> on possible values of -machine parameter type.  If -machine was
> > > >> >> QAPIfied, it would provide information on possible values of a QAPI
> > > >> >> object type's member.  The type might be anonymous.  The member should
> > > >> >> be an enum (we currently use 'str' in MachineInfo).
> > > >> >
> > > >> > QAPIfying -machine, -cpu, and -device would be wonderful.
> > > >> >
> > > >> >> 
> > > >> >> Example: say we want to deprecate block driver "vfat",
> > > >> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
> > > >> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
> > > >> >> @support-status to something that provides information on
> > > >> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
> > > >> >> providing information on either of the two, because QAPI/QMP
> > > >> >> introspection has been sufficient.  What now?
> > > >> >> 
> > > >> >> Can we add deprecation information to (general) QAPI/QMP introspection
> > > >> >
> > > >> > Yes, we can.  I think it's a good idea.  But:
> > > >> >
> > > >> >> instead of ad hoc queries?
> > > >> >
> > > >> > I'm not sure about the "instead of" part.  I don't want perfect
> > > >> > to be the enemy of done, and I don't want QAPIfication of
> > > >> > -machine to be a requirement to start reporting machine type
> > > >> > deprecation information.
> > > >> 
> > > >> Valid point.  Still, I believe we should at least try to predict how the
> > > >> pieces we create now would fit with the pieces we plan to create later
> > > >> on.
> > > >
> > > > Sure.
> > > >
> > > >> 
> > > >> Note that full QAPIfication of -machine isn't necessary to make QAPI
> > > >> feature "deprecated" work for machine types.  Turning MachineInfo member
> > > >> @name into an enum, so we can tack "deprecated" onto its values, would
> > > >> suffice.
> > > >> 
> > > >> Such a QAPIfication of machine types is still hard: QOM types are
> > > >> defined at compile time just like the QAPI schema, but their definition
> > > >> is distributed, and collected into one place only at run time.  I
> > > >> discussed this on slide 39 of my "QEMU interface introspection: From
> > > >> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
> > > >> just a special case of QOM.  Choices listed there:
> > > >> 
> > > >> * Collect drivers at compile time? Hard...
> > > >> * Make QAPI schema dynamic? Hard...
> > > >> * Forgo driver-specific arguments in schema?
> > > >>   Defeats introspection...
> > > >> 
> > > >> I'd like to add to the last item:
> > > >> 
> > > >>   Provide QOM introspection on par with QAPI schema introspection
> > > >> 
> > > >> The QOM introspection we have (qom-list-types etc. is not on par.
> > > >
> > > > Agreed, but do we really want to do it?  We have been avoiding
> > > > exposing QOM internals to the outside on purpose.  I believe
> > > > there are at least two reasons for that:
> > > >
> > > > 1) Not every QOM type/property is supposed to be visible to the
> > > >    outside
> > > 
> > > True.
> > > 
> > > However, the parts of QOM exposed via device_add and object-add are
> > > definitely part of the stable external interface (unless explicitly
> > > marked unstable).
> > > 
> > > >            (and nobody really knows what's the full set of
> > > >    supported external QOM interfaces);
> > > 
> > > Also true.  And terrible.
> > > 
> > > > 2) QAPI is our preferred interface interface specification/introspection
> > > >    mechanism.
> > > 
> > > When preferences and requirements collide, preferences tend to get run
> > > over.
> > > 
> > > The QAPI schema is *declarative*: the schema declares QAPI objects and
> > > properties.  We generate C from the schema, which we then compile and
> > > link into QEMU.
> > > 
> > > QOM is by design *imperative*: we execute compiled C at QEMU run-time to
> > > define QOM objects and properties.  Maximizes flexibility.  See also
> > > Turing tarpit.
> > > 
> > > No matter how much we'd prefer to use QAPI to specify external
> > > interfaces to QOM, we can't without making QAPI much more dynamic or QOM
> > > much more static.  Either is hard.  Quite possibly infeasible.
> > > 
> > > We could try to extend QAPI/QMP introspection to somehow merge in
> > > additional information at run-time[1].  Could be regarded as a limited
> > > way to make QAPI more dynamic.  This is in the "vague idea, not sure
> > > it's feasible" stage.
> > > 
> > > We could try to rearchitect QOM so that you can optionally specify QOM
> > > stuff in the QAPI schema, then require that for QOM stuff that's part of
> > > a stable external interface.  Same "vague idea" stage, feasibility even
> > > more doubtful.
> > 
> > I think it is feasible to use QAPI to declare the QOM object type,
> > QOM parent type, list of QOM interfaces and QOM properties in a
> > declarative manner. From that generate all the tedious boilerplate
> > code. The dev then just has to provide the "interesting" code for
> > the object.
> > 
> > I'd really like to do a PoC of this but never have free time :-(
> > Perhaps an interesting task for someone who wants to delve into
> > some new work...
> > 
> > 
> > > >> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
> > > >> >> BlockdevDriver member @vfat.
> > > >> >> 
> > > >> >> Unlike your patches, this does not require finding a "somewhere" that
> > > >> >> provides information on "something".  You simply tack "deprecated" right
> > > >> >> onto "something".
> > > >> >> 
> > > >> >> Your patches provide more information, however: human-readable messages.
> > > >> >
> > > >> > It also includes a machine-friendly suggested alternative (which
> > > >> > I think is even more important that the human-readable message).
> > > >> 
> > > >> I agree we should point to a preferred replacement whenever we deprecate
> > > >> something.
> > > >> 
> > > >> We have to do it in documentation.  And we generally do, in
> > > >> qemu-deprecated.texi.
> > > >> 
> > > >> How useful would doing it in QMP as well be?  Depends on what management
> > > >> applications can do with the additional information.
> > > >
> > > > I expect it to be useful for things that have obvious
> > > > replacements, like old machine type or CPU model versions.
> > > 
> > > I doubt a management application should apply suggested replacements
> > > automatically, and I doubt libvirt would.  Not even when QEMU developers
> > > deem them "obvious".
> > 
> > We certainly won't apply the suggested replacement as in many cases
> > it is not going to be a functionally equivalent drop-in.
> 
> Who's "we"?

I was refering to libvirt here.

> > If QEMU logs it to stderr, it will end up in the per-VM log file
> > libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
> > doesn't log it to stderr, then libvirt would just write it to
> > that same log file itself.
> > 
> > If libvirt gains some API or event for notifying apps of deprecation
> > we might bubble it up to the mgmt app that way.
> > 
> > I still feel it is useful to have the suggested replacement in the
> > logs, rather  than only leaving it in qemu-deprecated.texi.  This
> > way the info is immediately visible to both app developers and any
> > support person dealing with bugs.
> > 
> > If the app dev see the suggested replacement upfront they're more
> > likely to make an immediate decision to update their code if the
> > suggestion is trivial. If they need to go find the QEMU docs to
> > lookup what action is required I feel they'll more likely just
> > put the item on their long todo list where it will languish.
> 
> Agreed.  However, note that the audience for deprecation
> information is not just developers and support people.  End users
> need to know when they are relying on a deprecated feature, and
> applications should make it as easy as possible for them to
> update their configurations.
> 
> I'm not suggesting the alternative would be applied
> automatically.  But having the alternative available in a
> machine-friendly way may be the difference between a unhelpful UI
> that just tells the user there's some problem but can't give a
> solution, and one that can really assist the user to fix the
> problem.

For some aspects of QEMU it might be possible, but considering the
broader set of things which can be deprecated, I don't think it is
possible to expose a machine consumable "suggestion".

Consider the deprecation of the ACL feature. We deprecated monitor
commands "acl_add", "acl_policy", "acl_reset", etc. The suggested
replacement is to use one of the many possible QAuthZ types combined
with the -object arg. Even if we invented some way to express this
in the schema, I don't think any app would usefully consume it.

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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Thu, May 09, 2019 at 05:08:11PM +0100, Daniel P. Berrangé wrote:
> On Thu, May 09, 2019 at 12:52:47PM -0300, Eduardo Habkost wrote:
> > On Thu, May 09, 2019 at 10:14:52AM +0100, Daniel P. Berrangé wrote:
> > > On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
> > > > We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
> > > > 
> > > > Eduardo Habkost <ehabkost@redhat.com> writes:
> > > > 
> > > > > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> > > > >> Eduardo Habkost <ehabkost@redhat.com> writes:
> > > > >> 
> > > > >> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
> > > > >> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> > > > >> >> 
> > > > >> >> > This series adds machine type deprecation information to the
> > > > >> >> > output of the `query-machines` QMP command.  With this, libvirt
> > > > >> >> > and management software will be able to show this information to
> > > > >> >> > users and/or suggest changes to VM configuration to avoid
> > > > >> >> > deprecated machine types.
> > > > >> >> 
> > > > >> >> This overlaps with something I want to try, namely using Kevin's
> > > > >> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
> > > > >> >> two.
> > > > >> >> 
> > > > >> >> To mark something as deprecated with your patches, you add a
> > > > >> >> @support-status member somewhere, where "somewhere" is related to
> > > > >> >> "something" by "provides information on".
> > > > >> >> 
> > > > >> >> Example: MachineInfo (returned by query-machines) provides information
> > > > >> >> on possible values of -machine parameter type.  If -machine was
> > > > >> >> QAPIfied, it would provide information on possible values of a QAPI
> > > > >> >> object type's member.  The type might be anonymous.  The member should
> > > > >> >> be an enum (we currently use 'str' in MachineInfo).
> > > > >> >
> > > > >> > QAPIfying -machine, -cpu, and -device would be wonderful.
> > > > >> >
> > > > >> >> 
> > > > >> >> Example: say we want to deprecate block driver "vfat",
> > > > >> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
> > > > >> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
> > > > >> >> @support-status to something that provides information on
> > > > >> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
> > > > >> >> providing information on either of the two, because QAPI/QMP
> > > > >> >> introspection has been sufficient.  What now?
> > > > >> >> 
> > > > >> >> Can we add deprecation information to (general) QAPI/QMP introspection
> > > > >> >
> > > > >> > Yes, we can.  I think it's a good idea.  But:
> > > > >> >
> > > > >> >> instead of ad hoc queries?
> > > > >> >
> > > > >> > I'm not sure about the "instead of" part.  I don't want perfect
> > > > >> > to be the enemy of done, and I don't want QAPIfication of
> > > > >> > -machine to be a requirement to start reporting machine type
> > > > >> > deprecation information.
> > > > >> 
> > > > >> Valid point.  Still, I believe we should at least try to predict how the
> > > > >> pieces we create now would fit with the pieces we plan to create later
> > > > >> on.
> > > > >
> > > > > Sure.
> > > > >
> > > > >> 
> > > > >> Note that full QAPIfication of -machine isn't necessary to make QAPI
> > > > >> feature "deprecated" work for machine types.  Turning MachineInfo member
> > > > >> @name into an enum, so we can tack "deprecated" onto its values, would
> > > > >> suffice.
> > > > >> 
> > > > >> Such a QAPIfication of machine types is still hard: QOM types are
> > > > >> defined at compile time just like the QAPI schema, but their definition
> > > > >> is distributed, and collected into one place only at run time.  I
> > > > >> discussed this on slide 39 of my "QEMU interface introspection: From
> > > > >> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
> > > > >> just a special case of QOM.  Choices listed there:
> > > > >> 
> > > > >> * Collect drivers at compile time? Hard...
> > > > >> * Make QAPI schema dynamic? Hard...
> > > > >> * Forgo driver-specific arguments in schema?
> > > > >>   Defeats introspection...
> > > > >> 
> > > > >> I'd like to add to the last item:
> > > > >> 
> > > > >>   Provide QOM introspection on par with QAPI schema introspection
> > > > >> 
> > > > >> The QOM introspection we have (qom-list-types etc. is not on par.
> > > > >
> > > > > Agreed, but do we really want to do it?  We have been avoiding
> > > > > exposing QOM internals to the outside on purpose.  I believe
> > > > > there are at least two reasons for that:
> > > > >
> > > > > 1) Not every QOM type/property is supposed to be visible to the
> > > > >    outside
> > > > 
> > > > True.
> > > > 
> > > > However, the parts of QOM exposed via device_add and object-add are
> > > > definitely part of the stable external interface (unless explicitly
> > > > marked unstable).
> > > > 
> > > > >            (and nobody really knows what's the full set of
> > > > >    supported external QOM interfaces);
> > > > 
> > > > Also true.  And terrible.
> > > > 
> > > > > 2) QAPI is our preferred interface interface specification/introspection
> > > > >    mechanism.
> > > > 
> > > > When preferences and requirements collide, preferences tend to get run
> > > > over.
> > > > 
> > > > The QAPI schema is *declarative*: the schema declares QAPI objects and
> > > > properties.  We generate C from the schema, which we then compile and
> > > > link into QEMU.
> > > > 
> > > > QOM is by design *imperative*: we execute compiled C at QEMU run-time to
> > > > define QOM objects and properties.  Maximizes flexibility.  See also
> > > > Turing tarpit.
> > > > 
> > > > No matter how much we'd prefer to use QAPI to specify external
> > > > interfaces to QOM, we can't without making QAPI much more dynamic or QOM
> > > > much more static.  Either is hard.  Quite possibly infeasible.
> > > > 
> > > > We could try to extend QAPI/QMP introspection to somehow merge in
> > > > additional information at run-time[1].  Could be regarded as a limited
> > > > way to make QAPI more dynamic.  This is in the "vague idea, not sure
> > > > it's feasible" stage.
> > > > 
> > > > We could try to rearchitect QOM so that you can optionally specify QOM
> > > > stuff in the QAPI schema, then require that for QOM stuff that's part of
> > > > a stable external interface.  Same "vague idea" stage, feasibility even
> > > > more doubtful.
> > > 
> > > I think it is feasible to use QAPI to declare the QOM object type,
> > > QOM parent type, list of QOM interfaces and QOM properties in a
> > > declarative manner. From that generate all the tedious boilerplate
> > > code. The dev then just has to provide the "interesting" code for
> > > the object.
> > > 
> > > I'd really like to do a PoC of this but never have free time :-(
> > > Perhaps an interesting task for someone who wants to delve into
> > > some new work...
> > > 
> > > 
> > > > >> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
> > > > >> >> BlockdevDriver member @vfat.
> > > > >> >> 
> > > > >> >> Unlike your patches, this does not require finding a "somewhere" that
> > > > >> >> provides information on "something".  You simply tack "deprecated" right
> > > > >> >> onto "something".
> > > > >> >> 
> > > > >> >> Your patches provide more information, however: human-readable messages.
> > > > >> >
> > > > >> > It also includes a machine-friendly suggested alternative (which
> > > > >> > I think is even more important that the human-readable message).
> > > > >> 
> > > > >> I agree we should point to a preferred replacement whenever we deprecate
> > > > >> something.
> > > > >> 
> > > > >> We have to do it in documentation.  And we generally do, in
> > > > >> qemu-deprecated.texi.
> > > > >> 
> > > > >> How useful would doing it in QMP as well be?  Depends on what management
> > > > >> applications can do with the additional information.
> > > > >
> > > > > I expect it to be useful for things that have obvious
> > > > > replacements, like old machine type or CPU model versions.
> > > > 
> > > > I doubt a management application should apply suggested replacements
> > > > automatically, and I doubt libvirt would.  Not even when QEMU developers
> > > > deem them "obvious".
> > > 
> > > We certainly won't apply the suggested replacement as in many cases
> > > it is not going to be a functionally equivalent drop-in.
> > 
> > Who's "we"?
> 
> I was refering to libvirt here.
> 
> > > If QEMU logs it to stderr, it will end up in the per-VM log file
> > > libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
> > > doesn't log it to stderr, then libvirt would just write it to
> > > that same log file itself.
> > > 
> > > If libvirt gains some API or event for notifying apps of deprecation
> > > we might bubble it up to the mgmt app that way.
> > > 
> > > I still feel it is useful to have the suggested replacement in the
> > > logs, rather  than only leaving it in qemu-deprecated.texi.  This
> > > way the info is immediately visible to both app developers and any
> > > support person dealing with bugs.
> > > 
> > > If the app dev see the suggested replacement upfront they're more
> > > likely to make an immediate decision to update their code if the
> > > suggestion is trivial. If they need to go find the QEMU docs to
> > > lookup what action is required I feel they'll more likely just
> > > put the item on their long todo list where it will languish.
> > 
> > Agreed.  However, note that the audience for deprecation
> > information is not just developers and support people.  End users
> > need to know when they are relying on a deprecated feature, and
> > applications should make it as easy as possible for them to
> > update their configurations.
> > 
> > I'm not suggesting the alternative would be applied
> > automatically.  But having the alternative available in a
> > machine-friendly way may be the difference between a unhelpful UI
> > that just tells the user there's some problem but can't give a
> > solution, and one that can really assist the user to fix the
> > problem.
> 
> For some aspects of QEMU it might be possible, but considering the
> broader set of things which can be deprecated, I don't think it is
> possible to expose a machine consumable "suggestion".
> 
> Consider the deprecation of the ACL feature. We deprecated monitor
> commands "acl_add", "acl_policy", "acl_reset", etc. The suggested
> replacement is to use one of the many possible QAuthZ types combined
> with the -object arg. Even if we invented some way to express this
> in the schema, I don't think any app would usefully consume it.

No problem, we don't need to suggest a machine consumable
alternative for everything.

I'm thinking about features that are visible to the end user and
require user action to fix their configuration, like machine type
versions or CPU model versions.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
> We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
> 
> Eduardo Habkost <ehabkost@redhat.com> writes:
> 
> > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> >> 
> >> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
> >> >> Eduardo Habkost <ehabkost@redhat.com> writes:
> >> >> 
> >> >> > This series adds machine type deprecation information to the
> >> >> > output of the `query-machines` QMP command.  With this, libvirt
> >> >> > and management software will be able to show this information to
> >> >> > users and/or suggest changes to VM configuration to avoid
> >> >> > deprecated machine types.
> >> >> 
> >> >> This overlaps with something I want to try, namely using Kevin's
> >> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
> >> >> two.
> >> >> 
> >> >> To mark something as deprecated with your patches, you add a
> >> >> @support-status member somewhere, where "somewhere" is related to
> >> >> "something" by "provides information on".
> >> >> 
> >> >> Example: MachineInfo (returned by query-machines) provides information
> >> >> on possible values of -machine parameter type.  If -machine was
> >> >> QAPIfied, it would provide information on possible values of a QAPI
> >> >> object type's member.  The type might be anonymous.  The member should
> >> >> be an enum (we currently use 'str' in MachineInfo).
> >> >
> >> > QAPIfying -machine, -cpu, and -device would be wonderful.
> >> >
> >> >> 
> >> >> Example: say we want to deprecate block driver "vfat",
> >> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
> >> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
> >> >> @support-status to something that provides information on
> >> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
> >> >> providing information on either of the two, because QAPI/QMP
> >> >> introspection has been sufficient.  What now?
> >> >> 
> >> >> Can we add deprecation information to (general) QAPI/QMP introspection
> >> >
> >> > Yes, we can.  I think it's a good idea.  But:
> >> >
> >> >> instead of ad hoc queries?
> >> >
> >> > I'm not sure about the "instead of" part.  I don't want perfect
> >> > to be the enemy of done, and I don't want QAPIfication of
> >> > -machine to be a requirement to start reporting machine type
> >> > deprecation information.
> >> 
> >> Valid point.  Still, I believe we should at least try to predict how the
> >> pieces we create now would fit with the pieces we plan to create later
> >> on.
> >
> > Sure.
> >
> >> 
> >> Note that full QAPIfication of -machine isn't necessary to make QAPI
> >> feature "deprecated" work for machine types.  Turning MachineInfo member
> >> @name into an enum, so we can tack "deprecated" onto its values, would
> >> suffice.
> >> 
> >> Such a QAPIfication of machine types is still hard: QOM types are
> >> defined at compile time just like the QAPI schema, but their definition
> >> is distributed, and collected into one place only at run time.  I
> >> discussed this on slide 39 of my "QEMU interface introspection: From
> >> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
> >> just a special case of QOM.  Choices listed there:
> >> 
> >> * Collect drivers at compile time? Hard...
> >> * Make QAPI schema dynamic? Hard...
> >> * Forgo driver-specific arguments in schema?
> >>   Defeats introspection...
> >> 
> >> I'd like to add to the last item:
> >> 
> >>   Provide QOM introspection on par with QAPI schema introspection
> >> 
> >> The QOM introspection we have (qom-list-types etc. is not on par.
> >
> > Agreed, but do we really want to do it?  We have been avoiding
> > exposing QOM internals to the outside on purpose.  I believe
> > there are at least two reasons for that:
> >
> > 1) Not every QOM type/property is supposed to be visible to the
> >    outside
> 
> True.
> 
> However, the parts of QOM exposed via device_add and object-add are
> definitely part of the stable external interface (unless explicitly
> marked unstable).
> 
> >            (and nobody really knows what's the full set of
> >    supported external QOM interfaces);
> 
> Also true.  And terrible.
> 
> > 2) QAPI is our preferred interface interface specification/introspection
> >    mechanism.
> 
> When preferences and requirements collide, preferences tend to get run
> over.
> 
> The QAPI schema is *declarative*: the schema declares QAPI objects and
> properties.  We generate C from the schema, which we then compile and
> link into QEMU.
> 
> QOM is by design *imperative*: we execute compiled C at QEMU run-time to
> define QOM objects and properties.  Maximizes flexibility.  See also
> Turing tarpit.
> 
> No matter how much we'd prefer to use QAPI to specify external
> interfaces to QOM, we can't without making QAPI much more dynamic or QOM
> much more static.  Either is hard.  Quite possibly infeasible.
> 
> We could try to extend QAPI/QMP introspection to somehow merge in
> additional information at run-time[1].  Could be regarded as a limited
> way to make QAPI more dynamic.  This is in the "vague idea, not sure
> it's feasible" stage.
> 
> We could try to rearchitect QOM so that you can optionally specify QOM
> stuff in the QAPI schema, then require that for QOM stuff that's part of
> a stable external interface.  Same "vague idea" stage, feasibility even
> more doubtful.
> 
> If I remember correctly, Paolo suggested to abandon the idea to have
> query-qmp-schema cover device_add as infeasible.  Instead, cover it
> separately.
> 
> I think this separate introspection mechanism should be as similar to
> query-qmp-schema as practical.  It should cover not just device_add, but
> also object-add, and whatever other external interface to QOM we deem
> stable.

I think we are in agreement here.  We don't need to make the new
introspection mechanism part of query-qmp-schema, but I think it
should use the same abstractions.

> 
> Should there be more stable external interfaces that can't be defined in
> the QAPI schema, we might want to cover them in this second
> introspection mechanism, too.

Agreed.

> 
> >> Back to exposing machine type deprecation.
> >> 
> >> I'm doubtful your proposed solution can be applied widely.  It relies on
> >> adding @support-status to something that provides information on
> >> whatever is deprecated.  The initial use is with a something that is an
> >> ad hoc query, namely query-machines.  To use it, the management
> >> application needs to understand what query-machines' @support-status
> >> applies to.  Certainly feasible.  But I fear every use will be a special
> >> case.  Furthermore, a suitable ad hoc query need not exist.  What then?
> >> Create suitable ad hoc queries just for communicating deprecation?
> >> 
> >> Instead, I'd like us to think about a more genral solution.  Or perhaps
> >> two: one for properly QAPIfied stuff, and one for QOM.
> >
> > Should we really spend our time designing a second solution, if
> > we could build this on top of QAPI abstractions?  Making the QAPI
> > schema dynamic might be hard, but reinventing QAPI and
> > maintaining the two systems in parallel seems harder.
> 
> I'd love to see a practical way forward that keeps QAPI/QMP
> introspection the only game in town.
> 
> >> >> Kevin's proposed QAPI feature flags[*] extend the QAPI language so that
> >> >> struct types can optionally have a list of feature flags, which are
> >> >> strings.  Struct types suffice for his immediate needs.  I'd like to use
> >> >> feature flags to mark deprecation by tacking a "deprecated" feature onto
> >> >> whatever is deprecated.  This obviously needs feature support for
> >> >> everything we want to be able to deprecate: commands, and events, as
> >> >> well as members of enum and object types.
> >> >> 
> >> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
> >> >> BlockdevDriver member @vfat.
> >> >> 
> >> >> Unlike your patches, this does not require finding a "somewhere" that
> >> >> provides information on "something".  You simply tack "deprecated" right
> >> >> onto "something".
> >> >> 
> >> >> Your patches provide more information, however: human-readable messages.
> >> >
> >> > It also includes a machine-friendly suggested alternative (which
> >> > I think is even more important that the human-readable message).
> >> 
> >> I agree we should point to a preferred replacement whenever we deprecate
> >> something.
> >> 
> >> We have to do it in documentation.  And we generally do, in
> >> qemu-deprecated.texi.
> >> 
> >> How useful would doing it in QMP as well be?  Depends on what management
> >> applications can do with the additional information.
> >
> > I expect it to be useful for things that have obvious
> > replacements, like old machine type or CPU model versions.
> 
> I doubt a management application should apply suggested replacements
> automatically, and I doubt libvirt would.  Not even when QEMU developers
> deem them "obvious".
> 
> >> > We could extend QAPI introspection to return that if necessary,
> >> > right?
> >> 
> >> I'm confident we can come up with *something*.  It might kill the neat
> >> and simple "use QAPI features to communicate deprecation" idea, though.
> >
> > If something is important enough to be communicated through
> > stderr, it's important enough to be communicated through QMP.
> 
> Mostly.  Differences are due to the different consumers.
> 
> stderr is primarily for human users.  We print stuff useful to human
> users.

We have users that don't have access to stderr.  They might have
access to log files, but log files are pretty bad user
interfaces.  If it's important for some set of human users, apps
using libvirt or QMP need access to that information so they can
show it to their human users too.

> 
> QMP is primarily for machines, secondarily for the humans building these
> machines.  We send stuff useful to the machines themselves, and stuff
> the machines can use to be more useful for their users (which may be
> machines or humans).  We can also send stuff to help the humans building
> the machines.
> 
> In any case, the information we provide is limited by the cost to
> provide it.

Absolutely.

> 
> > Is that enough reason to provide something more complex?
> 
> We need to consider cost / benefit.
> 
> On benefit, I'd like to know what libvirt would do with the additional
> information beyond logging it.

I'd say it should provide it to apps, otherwise this won't be
more useful than the existing log files.

> 
> Is the additional information you propose to provide static or dynamic?
> 
> By "static", I mean each occurence of a feature in the QAPI schema is
> tied to one fixed instance of "additional information".

I don't think I understand this description of "static".  I
expect the data to be fixed at build time, but I expect it to be
different in downstream distributions of QEMU.


> 
> > Do we need QAPI features to be just strings?  Can't they be a
> > more complex type, like a QAPI alternate?
> 
> Adds complexity.
> 
> We currently imagine QAPI features enum-like, i.e. a list of strings,
> optionally with conditions.  The conditions are evaluated at QAPI
> generation time, and not visible in introspection.
> 
> This is probably the stupidest solution that could possibly work.  The
> structure of features is trivial.
> 
> More expressive solutions include:
> 
> * List of 'any'.  Feels like a bad idea, because it's completely
>   unstructured.

Agreed.

> 
> * List of some 'QapiFeatures' object type.  Lets us expose the variable
>   structure of features in introspection.
> 
> * List of some 'QapiFeatures' alternate type.  Like the previous, but
>   permits coding simple feature flags as strings.
> 
> All of the more expressive solutions I listed treat the additional
> information as dynamic.  Overly general in case the information is
> actually always static.

The static vs. dynamic distinction is getting me confused.  Why
are the more expressive solutions more dynamic than "list of
strings"?  Can you give examples?

Also, why do we want to place all info inside the same "features"
attribute instead of just adding new fields to SchemaInfoObject?

i.e. why are these options:

  { "members" [ ... ],
    "features": [ "dynamic-read-only", "deprecated" ] }

  { "members" [ ... ],
    "features": [ "dynamic-read-only",
                  { "deprecated": true, "hint": "FOO" } ] }

better than these options:

  { "members" [ ... ],
    "features": [ "dynamic-read-only" ],
    "deprecated": true }

  { "members" [ ... ],
    "features": [ "dynamic-read-only" ],
    "deprecation-info": { "deprecated": true, "hint": "FOO" } }



> 
> >> >> Food for thought :)
> >> >> 
> >> >> 
> >> >> [*] Hiding in
> >> >> Subject: [PATCH 0/4] file-posix: Add dynamic-auto-read-only QAPI feature
> >> >> Date: Mon,  8 Apr 2019 16:35:39 +0200
> >> >> Message-Id: <20190408143543.3982-1-kwolf@redhat.com>
> 
> 
> [1] Special case of "merge additional information into QAPI/QMP
> introspection at run-time, relegated to a footnote, because I think it's
> of mostly historical interest now.
> 
> Qdev was designed to be declarative, but the declarations always got
> collected only at run-time.  It has since been rebased onto imperative
> QOM.  Since you can mix declarative qdev and imperative QOM, the
> combination is effectively imperative.
> 
> We could collect the declarative parts of qdev at compile-time somehow,
> and fold them into QAPI introspection.  That's the "Collect drives at
> compile time" item from the slide I quoted.  I think this idea has
> become pretty much worthless, since it would cover device_add only in
> part, and object-add not at all.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> On Thu, May 09, 2019 at 10:14:52AM +0100, Daniel P. Berrangé wrote:
>> On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
>> > We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
>> > 
>> > Eduardo Habkost <ehabkost@redhat.com> writes:
>> > 
>> > > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
[...]
>> > >> I agree we should point to a preferred replacement whenever we deprecate
>> > >> something.
>> > >> 
>> > >> We have to do it in documentation.  And we generally do, in
>> > >> qemu-deprecated.texi.
>> > >> 
>> > >> How useful would doing it in QMP as well be?  Depends on what management
>> > >> applications can do with the additional information.
>> > >
>> > > I expect it to be useful for things that have obvious
>> > > replacements, like old machine type or CPU model versions.
>> > 
>> > I doubt a management application should apply suggested replacements
>> > automatically, and I doubt libvirt would.  Not even when QEMU developers
>> > deem them "obvious".
>> 
>> We certainly won't apply the suggested replacement as in many cases
>> it is not going to be a functionally equivalent drop-in.
>
> Who's "we"?
>
>> 
>> If QEMU logs it to stderr, it will end up in the per-VM log file
>> libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
>> doesn't log it to stderr, then libvirt would just write it to
>> that same log file itself.
>> 
>> If libvirt gains some API or event for notifying apps of deprecation
>> we might bubble it up to the mgmt app that way.
>> 
>> I still feel it is useful to have the suggested replacement in the
>> logs, rather  than only leaving it in qemu-deprecated.texi.  This
>> way the info is immediately visible to both app developers and any
>> support person dealing with bugs.
>> 
>> If the app dev see the suggested replacement upfront they're more
>> likely to make an immediate decision to update their code if the
>> suggestion is trivial. If they need to go find the QEMU docs to
>> lookup what action is required I feel they'll more likely just
>> put the item on their long todo list where it will languish.
>
> Agreed.  However, note that the audience for deprecation
> information is not just developers and support people.  End users
> need to know when they are relying on a deprecated feature, and
> applications should make it as easy as possible for them to
> update their configurations.
>
> I'm not suggesting the alternative would be applied
> automatically.  But having the alternative available in a
> machine-friendly way may be the difference between a unhelpful UI
> that just tells the user there's some problem but can't give a
> solution, and one that can really assist the user to fix the
> problem.

I'm skeptical.

For the management application to assist its users, it has to translate
both the deprecated QEMU interface and its replacement into its own
interfaces (because those are the ones the users actually use).
Management applications routinely translate in the other direction.  I
doubt anyone would build reverse translation capabilities just for
helping users update deprecated configurations.  So unless such
capabilities get built for other purposes, machine-friendliness will
remain unused.

If the management application's user is another machine, another
translation is needed.  And so forth until we reach the guy who's
supposed to update configuration.

Such a game of telephone is unlikely to produce anything but confusion,
except for specific cases we test across the whole stack.

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> On Thu, May 09, 2019 at 05:08:11PM +0100, Daniel P. Berrangé wrote:
>> On Thu, May 09, 2019 at 12:52:47PM -0300, Eduardo Habkost wrote:
>> > On Thu, May 09, 2019 at 10:14:52AM +0100, Daniel P. Berrangé wrote:
>> > > On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
>> > > > We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
>> > > > 
>> > > > Eduardo Habkost <ehabkost@redhat.com> writes:
>> > > > 
>> > > > > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
[...]
>> > > > >> I agree we should point to a preferred replacement whenever we deprecate
>> > > > >> something.
>> > > > >> 
>> > > > >> We have to do it in documentation.  And we generally do, in
>> > > > >> qemu-deprecated.texi.
>> > > > >> 
>> > > > >> How useful would doing it in QMP as well be?  Depends on what management
>> > > > >> applications can do with the additional information.
>> > > > >
>> > > > > I expect it to be useful for things that have obvious
>> > > > > replacements, like old machine type or CPU model versions.
>> > > > 
>> > > > I doubt a management application should apply suggested replacements
>> > > > automatically, and I doubt libvirt would.  Not even when QEMU developers
>> > > > deem them "obvious".
>> > > 
>> > > We certainly won't apply the suggested replacement as in many cases
>> > > it is not going to be a functionally equivalent drop-in.
>> > 
>> > Who's "we"?
>> 
>> I was refering to libvirt here.
>> 
>> > > If QEMU logs it to stderr, it will end up in the per-VM log file
>> > > libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
>> > > doesn't log it to stderr, then libvirt would just write it to
>> > > that same log file itself.
>> > > 
>> > > If libvirt gains some API or event for notifying apps of deprecation
>> > > we might bubble it up to the mgmt app that way.
>> > > 
>> > > I still feel it is useful to have the suggested replacement in the
>> > > logs, rather  than only leaving it in qemu-deprecated.texi.  This
>> > > way the info is immediately visible to both app developers and any
>> > > support person dealing with bugs.
>> > > 
>> > > If the app dev see the suggested replacement upfront they're more
>> > > likely to make an immediate decision to update their code if the
>> > > suggestion is trivial. If they need to go find the QEMU docs to
>> > > lookup what action is required I feel they'll more likely just
>> > > put the item on their long todo list where it will languish.
>> > 
>> > Agreed.  However, note that the audience for deprecation
>> > information is not just developers and support people.  End users
>> > need to know when they are relying on a deprecated feature, and
>> > applications should make it as easy as possible for them to
>> > update their configurations.
>> > 
>> > I'm not suggesting the alternative would be applied
>> > automatically.  But having the alternative available in a
>> > machine-friendly way may be the difference between a unhelpful UI
>> > that just tells the user there's some problem but can't give a
>> > solution, and one that can really assist the user to fix the
>> > problem.
>> 
>> For some aspects of QEMU it might be possible, but considering the
>> broader set of things which can be deprecated, I don't think it is
>> possible to expose a machine consumable "suggestion".
>> 
>> Consider the deprecation of the ACL feature. We deprecated monitor
>> commands "acl_add", "acl_policy", "acl_reset", etc. The suggested
>> replacement is to use one of the many possible QAuthZ types combined
>> with the -object arg. Even if we invented some way to express this
>> in the schema, I don't think any app would usefully consume it.
>
> No problem, we don't need to suggest a machine consumable
> alternative for everything.

Sure, but we need to get enough value out of it to justify its cost.

> I'm thinking about features that are visible to the end user and
> require user action to fix their configuration, like machine type
> versions or CPU model versions.

Even those may need translation as we cross layers of the stack.

The fewer cases we have where the machinery for machine-readable
deprecation advice is actually useful, the worse its cost / benefit
ratio is going to be.

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
>> We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
>> 
>> Eduardo Habkost <ehabkost@redhat.com> writes:
>> 
>> > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
>> >> Eduardo Habkost <ehabkost@redhat.com> writes:
>> >> 
>> >> > On Tue, May 07, 2019 at 07:07:04AM +0200, Markus Armbruster wrote:
>> >> >> Eduardo Habkost <ehabkost@redhat.com> writes:
>> >> >> 
>> >> >> > This series adds machine type deprecation information to the
>> >> >> > output of the `query-machines` QMP command.  With this, libvirt
>> >> >> > and management software will be able to show this information to
>> >> >> > users and/or suggest changes to VM configuration to avoid
>> >> >> > deprecated machine types.
>> >> >> 
>> >> >> This overlaps with something I want to try, namely using Kevin's
>> >> >> proposed QAPI feature flags for deprecation markings.  Let's compare the
>> >> >> two.
>> >> >> 
>> >> >> To mark something as deprecated with your patches, you add a
>> >> >> @support-status member somewhere, where "somewhere" is related to
>> >> >> "something" by "provides information on".
>> >> >> 
>> >> >> Example: MachineInfo (returned by query-machines) provides information
>> >> >> on possible values of -machine parameter type.  If -machine was
>> >> >> QAPIfied, it would provide information on possible values of a QAPI
>> >> >> object type's member.  The type might be anonymous.  The member should
>> >> >> be an enum (we currently use 'str' in MachineInfo).
>> >> >
>> >> > QAPIfying -machine, -cpu, and -device would be wonderful.
>> >> >
>> >> >> 
>> >> >> Example: say we want to deprecate block driver "vfat",
>> >> >> i.e. BlockdevDriver member @vfat.  Type BlockdevDriver is used in
>> >> >> multiple places; let's ignore all but BlockdevOptions.  We need to add
>> >> >> @support-status to something that provides information on
>> >> >> BlockdevDriver, or maybe on BlockdevOptions.  There is no ad hoc query
>> >> >> providing information on either of the two, because QAPI/QMP
>> >> >> introspection has been sufficient.  What now?
>> >> >> 
>> >> >> Can we add deprecation information to (general) QAPI/QMP introspection
>> >> >
>> >> > Yes, we can.  I think it's a good idea.  But:
>> >> >
>> >> >> instead of ad hoc queries?
>> >> >
>> >> > I'm not sure about the "instead of" part.  I don't want perfect
>> >> > to be the enemy of done, and I don't want QAPIfication of
>> >> > -machine to be a requirement to start reporting machine type
>> >> > deprecation information.
>> >> 
>> >> Valid point.  Still, I believe we should at least try to predict how the
>> >> pieces we create now would fit with the pieces we plan to create later
>> >> on.
>> >
>> > Sure.
>> >
>> >> 
>> >> Note that full QAPIfication of -machine isn't necessary to make QAPI
>> >> feature "deprecated" work for machine types.  Turning MachineInfo member
>> >> @name into an enum, so we can tack "deprecated" onto its values, would
>> >> suffice.
>> >> 
>> >> Such a QAPIfication of machine types is still hard: QOM types are
>> >> defined at compile time just like the QAPI schema, but their definition
>> >> is distributed, and collected into one place only at run time.  I
>> >> discussed this on slide 39 of my "QEMU interface introspection: From
>> >> hacks to solutions" talk (KVM Form 2015).  Just for device_add, but it's
>> >> just a special case of QOM.  Choices listed there:
>> >> 
>> >> * Collect drivers at compile time? Hard...
>> >> * Make QAPI schema dynamic? Hard...
>> >> * Forgo driver-specific arguments in schema?
>> >>   Defeats introspection...
>> >> 
>> >> I'd like to add to the last item:
>> >> 
>> >>   Provide QOM introspection on par with QAPI schema introspection
>> >> 
>> >> The QOM introspection we have (qom-list-types etc. is not on par.
>> >
>> > Agreed, but do we really want to do it?  We have been avoiding
>> > exposing QOM internals to the outside on purpose.  I believe
>> > there are at least two reasons for that:
>> >
>> > 1) Not every QOM type/property is supposed to be visible to the
>> >    outside
>> 
>> True.
>> 
>> However, the parts of QOM exposed via device_add and object-add are
>> definitely part of the stable external interface (unless explicitly
>> marked unstable).
>> 
>> >            (and nobody really knows what's the full set of
>> >    supported external QOM interfaces);
>> 
>> Also true.  And terrible.
>> 
>> > 2) QAPI is our preferred interface interface specification/introspection
>> >    mechanism.
>> 
>> When preferences and requirements collide, preferences tend to get run
>> over.
>> 
>> The QAPI schema is *declarative*: the schema declares QAPI objects and
>> properties.  We generate C from the schema, which we then compile and
>> link into QEMU.
>> 
>> QOM is by design *imperative*: we execute compiled C at QEMU run-time to
>> define QOM objects and properties.  Maximizes flexibility.  See also
>> Turing tarpit.
>> 
>> No matter how much we'd prefer to use QAPI to specify external
>> interfaces to QOM, we can't without making QAPI much more dynamic or QOM
>> much more static.  Either is hard.  Quite possibly infeasible.
>> 
>> We could try to extend QAPI/QMP introspection to somehow merge in
>> additional information at run-time[1].  Could be regarded as a limited
>> way to make QAPI more dynamic.  This is in the "vague idea, not sure
>> it's feasible" stage.
>> 
>> We could try to rearchitect QOM so that you can optionally specify QOM
>> stuff in the QAPI schema, then require that for QOM stuff that's part of
>> a stable external interface.  Same "vague idea" stage, feasibility even
>> more doubtful.
>> 
>> If I remember correctly, Paolo suggested to abandon the idea to have
>> query-qmp-schema cover device_add as infeasible.  Instead, cover it
>> separately.
>> 
>> I think this separate introspection mechanism should be as similar to
>> query-qmp-schema as practical.  It should cover not just device_add, but
>> also object-add, and whatever other external interface to QOM we deem
>> stable.
>
> I think we are in agreement here.  We don't need to make the new
> introspection mechanism part of query-qmp-schema, but I think it
> should use the same abstractions.

I agree we're basically in agreement :)

Covering dynamically defined external interfaces (such as device_add and
object-add) in query-qmp-schema would certainly be nice, but it's not a
hard requirement.  If we can't, then having separate introspection
commands share abstractions as much as practical is desirable.

>> Should there be more stable external interfaces that can't be defined in
>> the QAPI schema, we might want to cover them in this second
>> introspection mechanism, too.
>
> Agreed.
>
>> 
>> >> Back to exposing machine type deprecation.
>> >> 
>> >> I'm doubtful your proposed solution can be applied widely.  It relies on
>> >> adding @support-status to something that provides information on
>> >> whatever is deprecated.  The initial use is with a something that is an
>> >> ad hoc query, namely query-machines.  To use it, the management
>> >> application needs to understand what query-machines' @support-status
>> >> applies to.  Certainly feasible.  But I fear every use will be a special
>> >> case.  Furthermore, a suitable ad hoc query need not exist.  What then?
>> >> Create suitable ad hoc queries just for communicating deprecation?
>> >> 
>> >> Instead, I'd like us to think about a more genral solution.  Or perhaps
>> >> two: one for properly QAPIfied stuff, and one for QOM.
>> >
>> > Should we really spend our time designing a second solution, if
>> > we could build this on top of QAPI abstractions?  Making the QAPI
>> > schema dynamic might be hard, but reinventing QAPI and
>> > maintaining the two systems in parallel seems harder.
>> 
>> I'd love to see a practical way forward that keeps QAPI/QMP
>> introspection the only game in town.
>> 
>> >> >> Kevin's proposed QAPI feature flags[*] extend the QAPI language so that
>> >> >> struct types can optionally have a list of feature flags, which are
>> >> >> strings.  Struct types suffice for his immediate needs.  I'd like to use
>> >> >> feature flags to mark deprecation by tacking a "deprecated" feature onto
>> >> >> whatever is deprecated.  This obviously needs feature support for
>> >> >> everything we want to be able to deprecate: commands, and events, as
>> >> >> well as members of enum and object types.
>> >> >> 
>> >> >> Example: to deprecate block driver "vfat", add feature "deprecated" to
>> >> >> BlockdevDriver member @vfat.
>> >> >> 
>> >> >> Unlike your patches, this does not require finding a "somewhere" that
>> >> >> provides information on "something".  You simply tack "deprecated" right
>> >> >> onto "something".
>> >> >> 
>> >> >> Your patches provide more information, however: human-readable messages.
>> >> >
>> >> > It also includes a machine-friendly suggested alternative (which
>> >> > I think is even more important that the human-readable message).
>> >> 
>> >> I agree we should point to a preferred replacement whenever we deprecate
>> >> something.
>> >> 
>> >> We have to do it in documentation.  And we generally do, in
>> >> qemu-deprecated.texi.
>> >> 
>> >> How useful would doing it in QMP as well be?  Depends on what management
>> >> applications can do with the additional information.
>> >
>> > I expect it to be useful for things that have obvious
>> > replacements, like old machine type or CPU model versions.
>> 
>> I doubt a management application should apply suggested replacements
>> automatically, and I doubt libvirt would.  Not even when QEMU developers
>> deem them "obvious".
>> 
>> >> > We could extend QAPI introspection to return that if necessary,
>> >> > right?
>> >> 
>> >> I'm confident we can come up with *something*.  It might kill the neat
>> >> and simple "use QAPI features to communicate deprecation" idea, though.
>> >
>> > If something is important enough to be communicated through
>> > stderr, it's important enough to be communicated through QMP.
>> 
>> Mostly.  Differences are due to the different consumers.
>> 
>> stderr is primarily for human users.  We print stuff useful to human
>> users.
>
> We have users that don't have access to stderr.  They might have
> access to log files, but log files are pretty bad user
> interfaces.  If it's important for some set of human users, apps
> using libvirt or QMP need access to that information so they can
> show it to their human users too.

Command line means stderr.

I'm afraid our command line is awkward both for machines and for humans,
albeit for different reasons.

For humans doing simple things, the command line is okay.  But beyond
that, it gets forbiddingly unwieldy[2].

Machines are fine with that kind of unwieldy, but would prefer something
with more structure, both on input (talking to QEMU) and even more so on
output (QEMU talking back).

Ideally, we'd support machines do their work in (structured) QMP,
resorting to the command line only to set up a QMP monitor.  We're not
anywhere close to this.

As long as management applications use the command line in not-trivial
ways, they have to deal with configuration errors reported via stderr.

>> QMP is primarily for machines, secondarily for the humans building these
>> machines.  We send stuff useful to the machines themselves, and stuff
>> the machines can use to be more useful for their users (which may be
>> machines or humans).  We can also send stuff to help the humans building
>> the machines.
>>
>> In any case, the information we provide is limited by the cost to
>> provide it.
>
> Absolutely.
>
>> 
>> > Is that enough reason to provide something more complex?
>> 
>> We need to consider cost / benefit.
>> 
>> On benefit, I'd like to know what libvirt would do with the additional
>> information beyond logging it.
>
> I'd say it should provide it to apps, otherwise this won't be
> more useful than the existing log files.

A management application simply showing its user whatever error QEMU
reports or hint it provides is bound to be confusing: since QEMU talks
in QEMU terms, its errors and hints generally need translation to make
sense at higher layers.  Translation involves recognizing specific
messages, which means it's limited to special cases (and painfully
brittle).

The farther you propagate QEMU's messages up the stack, the less sense
they'll likely make.

Management applications logging QEMU's messages is useful anyway, mainly
because it's better than nothing.

I doubt logging them some more further up the stack would be all that
useful, but I might be wrong.

Discussed further elsewhere in this thread.

>> Is the additional information you propose to provide static or dynamic?
>> 
>> By "static", I mean each occurence of a feature in the QAPI schema is
>> tied to one fixed instance of "additional information".
>
> I don't think I understand this description of "static".  I
> expect the data to be fixed at build time, but I expect it to be
> different in downstream distributions of QEMU.

Let me try differently.

QAPI features as currently envisaged convey one bit of information:
there / not there.  The information is fixed at build time.  It is tied
to a specific QAPI entity (command, object type, enumeration value,
...).

My question is about the difference between this and what you have in
mind.  Specifically, is the difference only the amount of information
(one bit vs. a pair of string literals), or is there more?

"More" includes string values that can vary at run time or between
different uses of the QAPI entity in the schema.

>> > Do we need QAPI features to be just strings?  Can't they be a
>> > more complex type, like a QAPI alternate?
>> 
>> Adds complexity.
>> 
>> We currently imagine QAPI features enum-like, i.e. a list of strings,
>> optionally with conditions.  The conditions are evaluated at QAPI
>> generation time, and not visible in introspection.
>> 
>> This is probably the stupidest solution that could possibly work.  The
>> structure of features is trivial.
>> 
>> More expressive solutions include:
>> 
>> * List of 'any'.  Feels like a bad idea, because it's completely
>>   unstructured.
>
> Agreed.
>
>> 
>> * List of some 'QapiFeatures' object type.  Lets us expose the variable
>>   structure of features in introspection.
>> 
>> * List of some 'QapiFeatures' alternate type.  Like the previous, but
>>   permits coding simple feature flags as strings.
>> 
>> All of the more expressive solutions I listed treat the additional
>> information as dynamic.  Overly general in case the information is
>> actually always static.
>
> The static vs. dynamic distinction is getting me confused.  Why
> are the more expressive solutions more dynamic than "list of
> strings"?  Can you give examples?

Insufficiently precise thinking leads to vague and confusing prose.  Let
me try again.

The scenario I had in mind is having only the (static) structure of the
additional information in query-qmp-schema, and the actual (possibly
dynamic) information elsewhere, say in query-machines, or a new member
of the QMP success response.

> Also, why do we want to place all info inside the same "features"
> attribute instead of just adding new fields to SchemaInfoObject?
>
> i.e. why are these options:
>
>   { "members" [ ... ],
>     "features": [ "dynamic-read-only", "deprecated" ] }
>
>   { "members" [ ... ],
>     "features": [ "dynamic-read-only",
>                   { "deprecated": true, "hint": "FOO" } ] }
>
> better than these options:
>
>   { "members" [ ... ],
>     "features": [ "dynamic-read-only" ],
>     "deprecated": true }
>
>   { "members" [ ... ],
>     "features": [ "dynamic-read-only" ],
>     "deprecation-info": { "deprecated": true, "hint": "FOO" } }

I wouldn't claim "better".  I merely observe it takes its own QAPI
language extension, unlike the 'neat and simple "use QAPI features to
communicate deprecation" idea'.

>> >> >> Food for thought :)
>> >> >> 
>> >> >> 
>> >> >> [*] Hiding in
>> >> >> Subject: [PATCH 0/4] file-posix: Add dynamic-auto-read-only QAPI feature
>> >> >> Date: Mon,  8 Apr 2019 16:35:39 +0200
>> >> >> Message-Id: <20190408143543.3982-1-kwolf@redhat.com>
>> 
>> 
>> [1] Special case of "merge additional information into QAPI/QMP
>> introspection at run-time, relegated to a footnote, because I think it's
>> of mostly historical interest now.
>> 
>> Qdev was designed to be declarative, but the declarations always got
>> collected only at run-time.  It has since been rebased onto imperative
>> QOM.  Since you can mix declarative qdev and imperative QOM, the
>> combination is effectively imperative.
>> 
>> We could collect the declarative parts of qdev at compile-time somehow,
>> and fold them into QAPI introspection.  That's the "Collect drives at
>> compile time" item from the slide I quoted.  I think this idea has
>> become pretty much worthless, since it would cover device_add only in
>> part, and object-add not at all.

[2] Example quoted from my "Towards a more expressive and introspectable
QEMU command line" talk at KVM Forum 2017 (predating -blockdev, which
spices up things even more):
/usr/bin/qemu-system-x86_64 -machine accel=kvm -name boxes-unknown -S -machine pc-i440fx-1.6,accel=kvm,usb=off -cpu Penryn -m 3115 -realtime mlock=off -smp 4,sockets=1,cores=4,threads=1 -uuid 8bd53789-adab-484f-8c53-a6df9d5f1dbf -no-user-config -nodefaults -chardev socket,id=charmonitor,path=/home/guillaume/.config/libvirt/qemu/lib/boxes-unknown.monitor,server,nowait -mon chardev=charmonitor,id=monitor,mode=control -rtc base=utc,driftfix=slew -global kvm-pit.lost_tick_policy=discard -no-shutdown -global PIIX4_PM.disable_s3=1 -global PIIX4_PM.disable_s4=1 -boot strict=on -device ich9-usb-ehci1,id=usb,bus=pci.0,addr=0x5.0x7 -device ich9-usb-uhci1,masterbus=usb.0,firstport=0,bus=pci.0,multifunction=on,addr=0x5 -device ich9-usb-uhci2,masterbus=usb.0,firstport=2,bus=pci.0,addr=0x5.0x1-device ich9-usb-uhci3,masterbus=usb.0,firstport=4,bus=pci.0,addr=0x5.0x2 -device virtio-serial-pci,id=virtio-serial0,bus=pci.0,addr=0x6 -device usb-ccid,id=ccid0 -drive file=/home/guillaume/.local/share/gnome-boxes/images/boxes-unknown,if=none,id=drive-ide0-0-0,format=qcow2,cache=none -device ide-hd,bus=ide.0,unit=0,drive=drive-ide0-0-0,id=ide0-0-0,bootindex=1 -drive if=none,id=drive-ide0-1-0,readonly=on,format=raw -device ide-cd,bus=ide.1,unit=0,drive=drive-ide0-1-0,id=ide0-1-0 -netdev tap,fd=23,id=hostnet0 -device rtl8139,netdev=hostnet0,id=net0,mac=52:54:00:db:56:54,bus=pci.0,addr=0x3 -chardev spicevmc,id=charsmartcard0,name=smartcard -device ccid-card-passthru,chardev=charsmartcard0,id=smartcard0,bus=ccid0.0 -chardev pty,id=charserial0 -device isa-serial,chardev=charserial0,id=serial0 -chardev spicevmc,id=charchannel0,name=vdagent -device virtserialport,bus=virtio-serial0.0,nr=1,chardev=charchannel0,id=channel0,name=com.redhat.spice.0 -device usb-tablet,id=input0 -spice port=5901,addr=127.0.0.1,disable-ticketing,image-compression=off,seamless-migration=on -device qxl-vga,id=video0,ram_size=67108864,vram_size=67108864,vgamem_mb=16,bus=pci.0,addr=0x2 -device AC97,id=sound0,bus=pci.0,addr=0x4 -chardev spicevmc,id=charredir0,name=usbredir -device usb-redir,chardev=charredir0,id=redir0 -chardev spicevmc,id=charredir1,name=usbredir -device usb-redir,chardev=charredir1,id=redir1 -chardev spicevmc,id=charredir2,name=usbredir -device usb-redir,chardev=charredir2,id=redir2 -chardev spicevmc,id=charredir3,name=usbredir -device usb-redir,chardev=charredir3,id=redir3 -incoming fd:20 -device virtio-balloon-pci,id=balloon0,bus=pci.0,addr=0x7 -msg timestamp=on

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Fri, May 10, 2019 at 08:19:52AM +0200, Markus Armbruster wrote:
> Eduardo Habkost <ehabkost@redhat.com> writes:
> 
> > On Thu, May 09, 2019 at 10:14:52AM +0100, Daniel P. Berrangé wrote:
> >> On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
> >> > We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
> >> > 
> >> > Eduardo Habkost <ehabkost@redhat.com> writes:
> >> > 
> >> > > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> [...]
> >> > >> I agree we should point to a preferred replacement whenever we deprecate
> >> > >> something.
> >> > >> 
> >> > >> We have to do it in documentation.  And we generally do, in
> >> > >> qemu-deprecated.texi.
> >> > >> 
> >> > >> How useful would doing it in QMP as well be?  Depends on what management
> >> > >> applications can do with the additional information.
> >> > >
> >> > > I expect it to be useful for things that have obvious
> >> > > replacements, like old machine type or CPU model versions.
> >> > 
> >> > I doubt a management application should apply suggested replacements
> >> > automatically, and I doubt libvirt would.  Not even when QEMU developers
> >> > deem them "obvious".
> >> 
> >> We certainly won't apply the suggested replacement as in many cases
> >> it is not going to be a functionally equivalent drop-in.
> >
> > Who's "we"?
> >
> >> 
> >> If QEMU logs it to stderr, it will end up in the per-VM log file
> >> libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
> >> doesn't log it to stderr, then libvirt would just write it to
> >> that same log file itself.
> >> 
> >> If libvirt gains some API or event for notifying apps of deprecation
> >> we might bubble it up to the mgmt app that way.
> >> 
> >> I still feel it is useful to have the suggested replacement in the
> >> logs, rather  than only leaving it in qemu-deprecated.texi.  This
> >> way the info is immediately visible to both app developers and any
> >> support person dealing with bugs.
> >> 
> >> If the app dev see the suggested replacement upfront they're more
> >> likely to make an immediate decision to update their code if the
> >> suggestion is trivial. If they need to go find the QEMU docs to
> >> lookup what action is required I feel they'll more likely just
> >> put the item on their long todo list where it will languish.
> >
> > Agreed.  However, note that the audience for deprecation
> > information is not just developers and support people.  End users
> > need to know when they are relying on a deprecated feature, and
> > applications should make it as easy as possible for them to
> > update their configurations.
> >
> > I'm not suggesting the alternative would be applied
> > automatically.  But having the alternative available in a
> > machine-friendly way may be the difference between a unhelpful UI
> > that just tells the user there's some problem but can't give a
> > solution, and one that can really assist the user to fix the
> > problem.
> 
> I'm skeptical.
> 
> For the management application to assist its users, it has to translate
> both the deprecated QEMU interface and its replacement into its own
> interfaces (because those are the ones the users actually use).
> Management applications routinely translate in the other direction.  I
> doubt anyone would build reverse translation capabilities just for
> helping users update deprecated configurations.  So unless such
> capabilities get built for other purposes, machine-friendliness will
> remain unused.
> 
> If the management application's user is another machine, another
> translation is needed.  And so forth until we reach the guy who's
> supposed to update configuration.
> 
> Such a game of telephone is unlikely to produce anything but confusion,
> except for specific cases we test across the whole stack.

I don't see how that applies to machine type and CPU model names.
Machine type and CPU model names are often exposed directly to
the end user.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Fri, May 10, 2019 at 08:28:04AM +0200, Markus Armbruster wrote:
> Eduardo Habkost <ehabkost@redhat.com> writes:
> 
> > On Thu, May 09, 2019 at 05:08:11PM +0100, Daniel P. Berrangé wrote:
> >> On Thu, May 09, 2019 at 12:52:47PM -0300, Eduardo Habkost wrote:
> >> > On Thu, May 09, 2019 at 10:14:52AM +0100, Daniel P. Berrangé wrote:
> >> > > On Thu, May 09, 2019 at 10:31:46AM +0200, Markus Armbruster wrote:
> >> > > > We've wandered into the QAPI vs. QOM swamp.  Cc: Paolo.
> >> > > > 
> >> > > > Eduardo Habkost <ehabkost@redhat.com> writes:
> >> > > > 
> >> > > > > On Wed, May 08, 2019 at 11:16:50AM +0200, Markus Armbruster wrote:
> [...]
> >> > > > >> I agree we should point to a preferred replacement whenever we deprecate
> >> > > > >> something.
> >> > > > >> 
> >> > > > >> We have to do it in documentation.  And we generally do, in
> >> > > > >> qemu-deprecated.texi.
> >> > > > >> 
> >> > > > >> How useful would doing it in QMP as well be?  Depends on what management
> >> > > > >> applications can do with the additional information.
> >> > > > >
> >> > > > > I expect it to be useful for things that have obvious
> >> > > > > replacements, like old machine type or CPU model versions.
> >> > > > 
> >> > > > I doubt a management application should apply suggested replacements
> >> > > > automatically, and I doubt libvirt would.  Not even when QEMU developers
> >> > > > deem them "obvious".
> >> > > 
> >> > > We certainly won't apply the suggested replacement as in many cases
> >> > > it is not going to be a functionally equivalent drop-in.
> >> > 
> >> > Who's "we"?
> >> 
> >> I was refering to libvirt here.
> >> 
> >> > > If QEMU logs it to stderr, it will end up in the per-VM log file
> >> > > libvirt has under /var/log/libvirt/qemu/$GUESTNAME.log.  If QEMU
> >> > > doesn't log it to stderr, then libvirt would just write it to
> >> > > that same log file itself.
> >> > > 
> >> > > If libvirt gains some API or event for notifying apps of deprecation
> >> > > we might bubble it up to the mgmt app that way.
> >> > > 
> >> > > I still feel it is useful to have the suggested replacement in the
> >> > > logs, rather  than only leaving it in qemu-deprecated.texi.  This
> >> > > way the info is immediately visible to both app developers and any
> >> > > support person dealing with bugs.
> >> > > 
> >> > > If the app dev see the suggested replacement upfront they're more
> >> > > likely to make an immediate decision to update their code if the
> >> > > suggestion is trivial. If they need to go find the QEMU docs to
> >> > > lookup what action is required I feel they'll more likely just
> >> > > put the item on their long todo list where it will languish.
> >> > 
> >> > Agreed.  However, note that the audience for deprecation
> >> > information is not just developers and support people.  End users
> >> > need to know when they are relying on a deprecated feature, and
> >> > applications should make it as easy as possible for them to
> >> > update their configurations.
> >> > 
> >> > I'm not suggesting the alternative would be applied
> >> > automatically.  But having the alternative available in a
> >> > machine-friendly way may be the difference between a unhelpful UI
> >> > that just tells the user there's some problem but can't give a
> >> > solution, and one that can really assist the user to fix the
> >> > problem.
> >> 
> >> For some aspects of QEMU it might be possible, but considering the
> >> broader set of things which can be deprecated, I don't think it is
> >> possible to expose a machine consumable "suggestion".
> >> 
> >> Consider the deprecation of the ACL feature. We deprecated monitor
> >> commands "acl_add", "acl_policy", "acl_reset", etc. The suggested
> >> replacement is to use one of the many possible QAuthZ types combined
> >> with the -object arg. Even if we invented some way to express this
> >> in the schema, I don't think any app would usefully consume it.
> >
> > No problem, we don't need to suggest a machine consumable
> > alternative for everything.
> 
> Sure, but we need to get enough value out of it to justify its cost.
> 
> > I'm thinking about features that are visible to the end user and
> > require user action to fix their configuration, like machine type
> > versions or CPU model versions.
> 
> Even those may need translation as we cross layers of the stack.
> 
> The fewer cases we have where the machinery for machine-readable
> deprecation advice is actually useful, the worse its cost / benefit
> ratio is going to be.

Are you arguing the cost is unreasonably large?  I still don't
see what the problem is, here.

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Eduardo Habkost]

On Fri, May 10, 2019 at 11:29:53AM +0200, Markus Armbruster wrote:
[...]
> >> >> > We could extend QAPI introspection to return that if necessary,
> >> >> > right?
> >> >> 
> >> >> I'm confident we can come up with *something*.  It might kill the neat
> >> >> and simple "use QAPI features to communicate deprecation" idea, though.
> >> >
> >> > If something is important enough to be communicated through
> >> > stderr, it's important enough to be communicated through QMP.
> >> 
> >> Mostly.  Differences are due to the different consumers.
> >> 
> >> stderr is primarily for human users.  We print stuff useful to human
> >> users.
> >
> > We have users that don't have access to stderr.  They might have
> > access to log files, but log files are pretty bad user
> > interfaces.  If it's important for some set of human users, apps
> > using libvirt or QMP need access to that information so they can
> > show it to their human users too.
> 
> Command line means stderr.

I disagree.

> 
> I'm afraid our command line is awkward both for machines and for humans,
> albeit for different reasons.
> 
> For humans doing simple things, the command line is okay.  But beyond
> that, it gets forbiddingly unwieldy[2].
> 
> Machines are fine with that kind of unwieldy, but would prefer something
> with more structure, both on input (talking to QEMU) and even more so on
> output (QEMU talking back).
> 
> Ideally, we'd support machines do their work in (structured) QMP,
> resorting to the command line only to set up a QMP monitor.  We're not
> anywhere close to this.
> 
> As long as management applications use the command line in not-trivial
> ways, they have to deal with configuration errors reported via stderr.

That's only true if we want to.

Command line is an interface usable by machines.  Not the ideal,
but it works.

Messages on stderr are not an interface for machines.  We must
provide something better, and I don't think "wait until we
convert everything to QMP" is a reasonable answer.


> 
> >> QMP is primarily for machines, secondarily for the humans building these
> >> machines.  We send stuff useful to the machines themselves, and stuff
> >> the machines can use to be more useful for their users (which may be
> >> machines or humans).  We can also send stuff to help the humans building
> >> the machines.
> >>
> >> In any case, the information we provide is limited by the cost to
> >> provide it.
> >
> > Absolutely.
> >
> >> 
> >> > Is that enough reason to provide something more complex?
> >> 
> >> We need to consider cost / benefit.
> >> 
> >> On benefit, I'd like to know what libvirt would do with the additional
> >> information beyond logging it.
> >
> > I'd say it should provide it to apps, otherwise this won't be
> > more useful than the existing log files.
> 
> A management application simply showing its user whatever error QEMU
> reports or hint it provides is bound to be confusing: since QEMU talks
> in QEMU terms, its errors and hints generally need translation to make
> sense at higher layers.  Translation involves recognizing specific
> messages, which means it's limited to special cases (and painfully
> brittle).
> 
> The farther you propagate QEMU's messages up the stack, the less sense
> they'll likely make.
> 
> Management applications logging QEMU's messages is useful anyway, mainly
> because it's better than nothing.
> 
> I doubt logging them some more further up the stack would be all that
> useful, but I might be wrong.
> 
> Discussed further elsewhere in this thread.
> 
> >> Is the additional information you propose to provide static or dynamic?
> >> 
> >> By "static", I mean each occurence of a feature in the QAPI schema is
> >> tied to one fixed instance of "additional information".
> >
> > I don't think I understand this description of "static".  I
> > expect the data to be fixed at build time, but I expect it to be
> > different in downstream distributions of QEMU.
> 
> Let me try differently.
> 
> QAPI features as currently envisaged convey one bit of information:
> there / not there.  The information is fixed at build time.  It is tied
> to a specific QAPI entity (command, object type, enumeration value,
> ...).
> 
> My question is about the difference between this and what you have in
> mind.  Specifically, is the difference only the amount of information
> (one bit vs. a pair of string literals), or is there more?

Right now, it's only in the amount of information.

> 
> "More" includes string values that can vary at run time or between
> different uses of the QAPI entity in the schema.

Right now, it includes string values that are fixed at build
time, but collected dynamically at run time (because we are
describing QOM types, which are collected dynamically).

> 
> >> > Do we need QAPI features to be just strings?  Can't they be a
> >> > more complex type, like a QAPI alternate?
> >> 
> >> Adds complexity.
> >> 
> >> We currently imagine QAPI features enum-like, i.e. a list of strings,
> >> optionally with conditions.  The conditions are evaluated at QAPI
> >> generation time, and not visible in introspection.
> >> 
> >> This is probably the stupidest solution that could possibly work.  The
> >> structure of features is trivial.
> >> 
> >> More expressive solutions include:
> >> 
> >> * List of 'any'.  Feels like a bad idea, because it's completely
> >>   unstructured.
> >
> > Agreed.
> >
> >> 
> >> * List of some 'QapiFeatures' object type.  Lets us expose the variable
> >>   structure of features in introspection.
> >> 
> >> * List of some 'QapiFeatures' alternate type.  Like the previous, but
> >>   permits coding simple feature flags as strings.
> >> 
> >> All of the more expressive solutions I listed treat the additional
> >> information as dynamic.  Overly general in case the information is
> >> actually always static.
> >
> > The static vs. dynamic distinction is getting me confused.  Why
> > are the more expressive solutions more dynamic than "list of
> > strings"?  Can you give examples?
> 
> Insufficiently precise thinking leads to vague and confusing prose.  Let
> me try again.
> 
> The scenario I had in mind is having only the (static) structure of the
> additional information in query-qmp-schema, and the actual (possibly
> dynamic) information elsewhere, say in query-machines, or a new member
> of the QMP success response.

The structure of the additional information can be part of the
schema, yes.  The actual information needs to be collected at
runtime so we won't be able to make it part of the QAPI schema.

> 
> > Also, why do we want to place all info inside the same "features"
> > attribute instead of just adding new fields to SchemaInfoObject?
> >
> > i.e. why are these options:
> >
> >   { "members" [ ... ],
> >     "features": [ "dynamic-read-only", "deprecated" ] }
> >
> >   { "members" [ ... ],
> >     "features": [ "dynamic-read-only",
> >                   { "deprecated": true, "hint": "FOO" } ] }
> >
> > better than these options:
> >
> >   { "members" [ ... ],
> >     "features": [ "dynamic-read-only" ],
> >     "deprecated": true }
> >
> >   { "members" [ ... ],
> >     "features": [ "dynamic-read-only" ],
> >     "deprecation-info": { "deprecated": true, "hint": "FOO" } }
> 
> I wouldn't claim "better".  I merely observe it takes its own QAPI
> language extension, unlike the 'neat and simple "use QAPI features to
> communicate deprecation" idea'.

I agree that "neat and simple" is a nice goal.  But it's not a
requirement, right?

> [...]

-- 
Eduardo

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Daniel P. Berrangé]

On Fri, May 10, 2019 at 02:17:11PM -0300, Eduardo Habkost wrote:
> On Fri, May 10, 2019 at 11:29:53AM +0200, Markus Armbruster wrote:
> [...]
> > I'm afraid our command line is awkward both for machines and for humans,
> > albeit for different reasons.
> > 
> > For humans doing simple things, the command line is okay.  But beyond
> > that, it gets forbiddingly unwieldy[2].
> > 
> > Machines are fine with that kind of unwieldy, but would prefer something
> > with more structure, both on input (talking to QEMU) and even more so on
> > output (QEMU talking back).
> > 
> > Ideally, we'd support machines do their work in (structured) QMP,
> > resorting to the command line only to set up a QMP monitor.  We're not
> > anywhere close to this.
> > 
> > As long as management applications use the command line in not-trivial
> > ways, they have to deal with configuration errors reported via stderr.
> 
> That's only true if we want to.
> 
> Command line is an interface usable by machines.  Not the ideal,
> but it works.
> 
> Messages on stderr are not an interface for machines.  We must
> provide something better, and I don't think "wait until we
> convert everything to QMP" is a reasonable answer.

If QEMU successfully starts then libvirt essentially ignores stderr
just letting it go to the logfile.

If we see any deprecated features used during startup the natural
thing would be to queue up a list of warnings, and then once the
client (libvirt) connects to QMP emit them as events.

QEMU still ought to emit them on stderr anyway so they do end up
in the logs regardless of whether anyone actually procsses the
deprecation QMP events.

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 :|

Re: [Qemu-devel] [PATCH 0/3] Export machine type deprecation info through QMP

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> On Fri, May 10, 2019 at 11:29:53AM +0200, Markus Armbruster wrote:
> [...]
>> >> >> > We could extend QAPI introspection to return that if necessary,
>> >> >> > right?
>> >> >> 
>> >> >> I'm confident we can come up with *something*.  It might kill the neat
>> >> >> and simple "use QAPI features to communicate deprecation" idea, though.
>> >> >
>> >> > If something is important enough to be communicated through
>> >> > stderr, it's important enough to be communicated through QMP.
>> >> 
>> >> Mostly.  Differences are due to the different consumers.
>> >> 
>> >> stderr is primarily for human users.  We print stuff useful to human
>> >> users.
>> >
>> > We have users that don't have access to stderr.  They might have
>> > access to log files, but log files are pretty bad user
>> > interfaces.  If it's important for some set of human users, apps
>> > using libvirt or QMP need access to that information so they can
>> > show it to their human users too.
>> 
>> Command line means stderr.
>
> I disagree.
>
>> I'm afraid our command line is awkward both for machines and for humans,
>> albeit for different reasons.
>> 
>> For humans doing simple things, the command line is okay.  But beyond
>> that, it gets forbiddingly unwieldy[2].
>> 
>> Machines are fine with that kind of unwieldy, but would prefer something
>> with more structure, both on input (talking to QEMU) and even more so on
>> output (QEMU talking back).
>> 
>> Ideally, we'd support machines do their work in (structured) QMP,
>> resorting to the command line only to set up a QMP monitor.  We're not
>> anywhere close to this.
>> 
>> As long as management applications use the command line in not-trivial
>> ways, they have to deal with configuration errors reported via stderr.
>
> That's only true if we want to.
>
> Command line is an interface usable by machines.  Not the ideal,
> but it works.
>
> Messages on stderr are not an interface for machines.  We must
> provide something better, and I don't think "wait until we
> convert everything to QMP" is a reasonable answer.

Where else do you propose to report command line errors?

In what format?

>> >> QMP is primarily for machines, secondarily for the humans building these
>> >> machines.  We send stuff useful to the machines themselves, and stuff
>> >> the machines can use to be more useful for their users (which may be
>> >> machines or humans).  We can also send stuff to help the humans building
>> >> the machines.
>> >>
>> >> In any case, the information we provide is limited by the cost to
>> >> provide it.
>> >
>> > Absolutely.
>> >
>> >> 
>> >> > Is that enough reason to provide something more complex?
>> >> 
>> >> We need to consider cost / benefit.
>> >> 
>> >> On benefit, I'd like to know what libvirt would do with the additional
>> >> information beyond logging it.
>> >
>> > I'd say it should provide it to apps, otherwise this won't be
>> > more useful than the existing log files.
>> 
>> A management application simply showing its user whatever error QEMU
>> reports or hint it provides is bound to be confusing: since QEMU talks
>> in QEMU terms, its errors and hints generally need translation to make
>> sense at higher layers.  Translation involves recognizing specific
>> messages, which means it's limited to special cases (and painfully
>> brittle).
>> 
>> The farther you propagate QEMU's messages up the stack, the less sense
>> they'll likely make.
>> 
>> Management applications logging QEMU's messages is useful anyway, mainly
>> because it's better than nothing.
>> 
>> I doubt logging them some more further up the stack would be all that
>> useful, but I might be wrong.
>> 
>> Discussed further elsewhere in this thread.
>> 
>> >> Is the additional information you propose to provide static or dynamic?
>> >> 
>> >> By "static", I mean each occurence of a feature in the QAPI schema is
>> >> tied to one fixed instance of "additional information".
>> >
>> > I don't think I understand this description of "static".  I
>> > expect the data to be fixed at build time, but I expect it to be
>> > different in downstream distributions of QEMU.
>> 
>> Let me try differently.
>> 
>> QAPI features as currently envisaged convey one bit of information:
>> there / not there.  The information is fixed at build time.  It is tied
>> to a specific QAPI entity (command, object type, enumeration value,
>> ...).
>> 
>> My question is about the difference between this and what you have in
>> mind.  Specifically, is the difference only the amount of information
>> (one bit vs. a pair of string literals), or is there more?
>
> Right now, it's only in the amount of information.
>
>> 
>> "More" includes string values that can vary at run time or between
>> different uses of the QAPI entity in the schema.
>
> Right now, it includes string values that are fixed at build
> time, but collected dynamically at run time (because we are
> describing QOM types, which are collected dynamically).

Thanks.

>> >> > Do we need QAPI features to be just strings?  Can't they be a
>> >> > more complex type, like a QAPI alternate?
>> >> 
>> >> Adds complexity.
>> >> 
>> >> We currently imagine QAPI features enum-like, i.e. a list of strings,
>> >> optionally with conditions.  The conditions are evaluated at QAPI
>> >> generation time, and not visible in introspection.
>> >> 
>> >> This is probably the stupidest solution that could possibly work.  The
>> >> structure of features is trivial.
>> >> 
>> >> More expressive solutions include:
>> >> 
>> >> * List of 'any'.  Feels like a bad idea, because it's completely
>> >>   unstructured.
>> >
>> > Agreed.
>> >
>> >> 
>> >> * List of some 'QapiFeatures' object type.  Lets us expose the variable
>> >>   structure of features in introspection.
>> >> 
>> >> * List of some 'QapiFeatures' alternate type.  Like the previous, but
>> >>   permits coding simple feature flags as strings.
>> >> 
>> >> All of the more expressive solutions I listed treat the additional
>> >> information as dynamic.  Overly general in case the information is
>> >> actually always static.
>> >
>> > The static vs. dynamic distinction is getting me confused.  Why
>> > are the more expressive solutions more dynamic than "list of
>> > strings"?  Can you give examples?
>> 
>> Insufficiently precise thinking leads to vague and confusing prose.  Let
>> me try again.
>> 
>> The scenario I had in mind is having only the (static) structure of the
>> additional information in query-qmp-schema, and the actual (possibly
>> dynamic) information elsewhere, say in query-machines, or a new member
>> of the QMP success response.
>
> The structure of the additional information can be part of the
> schema, yes.  The actual information needs to be collected at
> runtime so we won't be able to make it part of the QAPI schema.

This means query-qmp-schema in its current form cannot serve this
purpose.

But let me refine my question.  Could the actual deprecation information
for *schema-defined* entities always be part of the QAPI schema?

>> > Also, why do we want to place all info inside the same "features"
>> > attribute instead of just adding new fields to SchemaInfoObject?
>> >
>> > i.e. why are these options:
>> >
>> >   { "members" [ ... ],
>> >     "features": [ "dynamic-read-only", "deprecated" ] }
>> >
>> >   { "members" [ ... ],
>> >     "features": [ "dynamic-read-only",
>> >                   { "deprecated": true, "hint": "FOO" } ] }
>> >
>> > better than these options:
>> >
>> >   { "members" [ ... ],
>> >     "features": [ "dynamic-read-only" ],
>> >     "deprecated": true }
>> >
>> >   { "members" [ ... ],
>> >     "features": [ "dynamic-read-only" ],
>> >     "deprecation-info": { "deprecated": true, "hint": "FOO" } }
>> 
>> I wouldn't claim "better".  I merely observe it takes its own QAPI
>> language extension, unlike the 'neat and simple "use QAPI features to
>> communicate deprecation" idea'.
>
> I agree that "neat and simple" is a nice goal.  But it's not a
> requirement, right?

"Simple" can become a requirement when the alternative is infeasible or
too costly.

I think you're approaching the "expose deprecation" feature from the
special case of machine types (and possibly CPU types), aiming for a
solution that can be generalized.  That's legitimate.

I'm approaching it from the general QAPI/QMP introspection case.

We've arrived at completely different solutions.  Hardly surprising, as
machine and CPU type introspection are both special cases completely
separate from QAPI/QMP introspection.

Having multiple separate introspection interfaces is undesirable.
However, as long as QAPI/QMP introspection fails to cover QOM, some
separate introspection interfaces for QOM-based stuff are unavoidable.

The separate introspection interfaces we have share basically nothing
with QAPI/QMP introspection.  Also undesirable, but it's what we got.

We've discussed more general QOM introspection, either within a single
introspection interface covering both QAPI/QMP and QOM/QMP, or with a
separate interface designed to share as much as possible.  Desirable,
but we're still in the vague ideas stage there.

Back to the problem at hand: we have two proposals for exposing
deprecation, and I can't see how to reconcile them.

My solution leverages QAPI feature flags we need for other purposes
anyway.  In other words, it's basically free.

As is, your solution involves extending ad hoc query commands that
provide information on whatever is being deprecated.  Adapting this to
general QAPI/QMP introspection involves extending the introspection data
generated from the schema.  This means the additional data must go into
the schema, which takes a QAPI language extension.

I have no capacity for such a QAPI language extension now, and I don't
expect this to change soon enough to matter.

I already committed to QAPI feature flags (for other purposes,
remember).  This involves me merging Kevin's first step (not too bad),
and me implementing the rest (hopefully not bad, either).

Further QAPI needs to be addressed include command line QAPIfication and
general QOM introspection.

I feel all of these are more important than improving machine-readable
deprecation information from a single "deprecated" bit to a full object
type capable of conveying support status, suggested alternative, and
more.  Not least because I can't quite see how the layers above can put
the additional information to productive use.  Logging it doesn't count
for me, because we can do that in QEMU.

This isn't sufficient reason for me to NAK this series.  Your series
"only" takes ad hoc machine introspection further away from general
QAPI/QMP introspection, setting a precedent for other ad hoc
introspection queries.  It could conceivably also influence a more
general QOM introspection interface down the road, but we can hash out
how to expose deprecation there when we have a design to discuss.

It might be sufficient for you to reconsider, but that's up to you.

The one thing I ask for is to adjust documentation to capture some of
our discussion.  Specifically, your SupportStatusInfo's documentation
currently sounds like SupportStatusInfo was the accepted path forward
for exposing feature deprecation.  It isn't.  What about:

##
# @SupportStatusInfo:
#
# This can be used to convey the support status of some feature, such as
# a machine type.
#