summaryrefslogtreecommitdiffstats
path: root/tests/qapi-schema
diff options
context:
space:
mode:
authorMarkus Armbruster2021-10-28 12:25:12 +0200
committerMarkus Armbruster2021-10-29 15:55:52 +0200
commita3c45b3e62962f99338716b1347cfb0d427cea44 (patch)
tree8193ab9d951f8eb6ef315e0db78117e8e7a354fb /tests/qapi-schema
parentMerge remote-tracking branch 'remotes/cschoenebeck/tags/pull-9p-20211027' int... (diff)
downloadqemu-a3c45b3e62962f99338716b1347cfb0d427cea44.tar.gz
qemu-a3c45b3e62962f99338716b1347cfb0d427cea44.tar.xz
qemu-a3c45b3e62962f99338716b1347cfb0d427cea44.zip
qapi: New special feature flag "unstable"
By convention, names starting with "x-" are experimental. The parts of external interfaces so named may be withdrawn or changed incompatibly in future releases. The naming convention makes unstable interfaces easy to recognize. Promoting something from experimental to stable involves a name change. Client code needs to be updated. Occasionally bothersome. Worse, the convention is not universally observed: * QOM type "input-barrier" has properties "x-origin", "y-origin". Looks accidental, but it's ABI since 4.2. * QOM types "memory-backend-file", "memory-backend-memfd", "memory-backend-ram", and "memory-backend-epc" have a property "x-use-canonical-path-for-ramblock-id" that is documented to be stable despite its name. We could document these exceptions, but documentation helps only humans. We want to recognize "unstable" in code, like "deprecated". So support recognizing it the same way: introduce new special feature flag "unstable". It will be treated specially by the QAPI generator, like the existing feature flag "deprecated", and unlike regular feature flags. This commit updates documentation and prepares tests. The next commit updates the QAPI schema. The remaining patches update the QAPI generator and wire up -compat policy checking. Management applications can then use query-qmp-schema and -compat to manage or guard against use of unstable interfaces the same way as for deprecated interfaces. docs/devel/qapi-code-gen.txt no longer mandates the naming convention. Using it anyway might help writers of programs that aren't full-fledged management applications. Not using it can save us bothersome renames. We'll see how that shakes out. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Message-Id: <20211028102520.747396-2-armbru@redhat.com>
Diffstat (limited to 'tests/qapi-schema')
-rw-r--r--tests/qapi-schema/qapi-schema-test.json7
-rw-r--r--tests/qapi-schema/qapi-schema-test.out5
2 files changed, 10 insertions, 2 deletions
diff --git a/tests/qapi-schema/qapi-schema-test.json b/tests/qapi-schema/qapi-schema-test.json
index b677ab861d..43b8697002 100644
--- a/tests/qapi-schema/qapi-schema-test.json
+++ b/tests/qapi-schema/qapi-schema-test.json
@@ -273,7 +273,7 @@
'data': { 'foo': { 'type': 'int', 'features': [ 'deprecated' ] } },
'features': [ 'feature1' ] }
{ 'struct': 'FeatureStruct2',
- 'data': { 'foo': 'int' },
+ 'data': { 'foo': { 'type': 'int', 'features': [ 'unstable' ] } },
'features': [ { 'name': 'feature1' } ] }
{ 'struct': 'FeatureStruct3',
'data': { 'foo': 'int' },
@@ -331,7 +331,7 @@
{ 'command': 'test-command-features1',
'features': [ 'deprecated' ] }
{ 'command': 'test-command-features3',
- 'features': [ 'feature1', 'feature2' ] }
+ 'features': [ 'unstable', 'feature1', 'feature2' ] }
{ 'command': 'test-command-cond-features1',
'features': [ { 'name': 'feature1', 'if': 'TEST_IF_FEATURE_1'} ] }
@@ -348,3 +348,6 @@
{ 'event': 'TEST_EVENT_FEATURES1',
'features': [ 'deprecated' ] }
+
+{ 'event': 'TEST_EVENT_FEATURES2',
+ 'features': [ 'unstable' ] }
diff --git a/tests/qapi-schema/qapi-schema-test.out b/tests/qapi-schema/qapi-schema-test.out
index 16846dbeb8..1f9585fa9b 100644
--- a/tests/qapi-schema/qapi-schema-test.out
+++ b/tests/qapi-schema/qapi-schema-test.out
@@ -308,6 +308,7 @@ object FeatureStruct1
feature feature1
object FeatureStruct2
member foo: int optional=False
+ feature unstable
feature feature1
object FeatureStruct3
member foo: int optional=False
@@ -373,6 +374,7 @@ command test-command-features1 None -> None
feature deprecated
command test-command-features3 None -> None
gen=True success_response=True boxed=False oob=False preconfig=False
+ feature unstable
feature feature1
feature feature2
command test-command-cond-features1 None -> None
@@ -394,6 +396,9 @@ event TEST_EVENT_FEATURES0 FeatureStruct1
event TEST_EVENT_FEATURES1 None
boxed=False
feature deprecated
+event TEST_EVENT_FEATURES2 None
+ boxed=False
+ feature unstable
module include/sub-module.json
include sub-sub-module.json
object SecondArrayRef