mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
026644cf5f
qemu/tests/qapi-schema/qapi-schema-test.out
Markus Armbruster a3c45b3e62 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>
2021-10-29 15:55:52 +02:00

412 lines
13 KiB
Plaintext
Raw Blame History

module ./builtin
object q_empty
enum QType
prefix QTYPE
member none
member qnull
member qnum
member qstring
member qdict
member qlist
member qbool
module qapi-schema-test.json
object TestStruct
member integer: int optional=False
member boolean: bool optional=False
member string: str optional=False
object NestedEnumsOne
member enum1: EnumOne optional=False
member enum2: EnumOne optional=True
member enum3: EnumOne optional=False
member enum4: EnumOne optional=True
enum MyEnum
object Empty1
object Empty2
base Empty1
object q_obj_Union-base
member type: EnumOne optional=False
object Union
base q_obj_Union-base
tag type
case value1: q_empty
case value2: q_empty
case value3: q_empty
case value4: q_empty
command user-def-cmd0 Empty2 -> Empty2
gen=True success_response=True boxed=False oob=False preconfig=False
enum QEnumTwo
prefix QENUM_TWO
member value1
member value2
object UserDefOne
base UserDefZero
member string: str optional=False
member enum1: EnumOne optional=True
enum EnumOne
member value1
member value2
member value3
member value4
object UserDefZero
member integer: int optional=False
object UserDefTwoDictDict
member userdef: UserDefOne optional=False
member string: str optional=False
object UserDefTwoDict
member string1: str optional=False
member dict2: UserDefTwoDictDict optional=False
member dict3: UserDefTwoDictDict optional=True
object UserDefTwo
member string0: str optional=False
member dict1: UserDefTwoDict optional=False
object UserDefThree
member string0: str optional=False
array UserDefOneList UserDefOne
array UserDefTwoList UserDefTwo
array TestStructList TestStruct
object ForceArrays
member unused1: UserDefOneList optional=False
member unused2: UserDefTwoList optional=False
member unused3: TestStructList optional=False
object UserDefA
member boolean: bool optional=False
member a_b: int optional=True
object UserDefB
member intb: int optional=False
member a-b: bool optional=True
object UserDefFlatUnion
base UserDefUnionBase
tag enum1
case value1: UserDefA
case value2: UserDefB
case value3: UserDefB
case value4: q_empty
object UserDefUnionBase
base UserDefZero
member string: str optional=False
member enum1: EnumOne optional=False
object q_obj_UserDefFlatUnion2-base
member integer: int optional=True
member string: str optional=False
member enum1: QEnumTwo optional=False
object UserDefFlatUnion2
base q_obj_UserDefFlatUnion2-base
tag enum1
case value1: UserDefC
case value2: UserDefB
object WrapAlternate
member alt: UserDefAlternate optional=False
alternate UserDefAlternate
tag type
case udfu: UserDefFlatUnion
case e: EnumOne
case i: int
case n: null
object UserDefC
member string1: str optional=False
member string2: str optional=False
alternate AltEnumBool
tag type
case e: EnumOne
case b: bool
alternate AltEnumNum
tag type
case e: EnumOne
case n: number
alternate AltNumEnum
tag type
case n: number
case e: EnumOne
alternate AltEnumInt
tag type
case e: EnumOne
case i: int
alternate AltStrObj
tag type
case s: str
case o: TestStruct
object ArrayStruct
member integer: intList optional=False
member s8: int8List optional=False
member s16: int16List optional=False
member s32: int32List optional=False
member s64: int64List optional=False
member u8: uint8List optional=False
member u16: uint16List optional=False
member u32: uint32List optional=False
member u64: uint64List optional=False
member number: numberList optional=False
member boolean: boolList optional=False
member string: strList optional=False
member sz: sizeList optional=True
member any: anyList optional=True
member user: StatusList optional=True
include include/sub-module.json
command user-def-cmd None -> None
gen=True success_response=True boxed=False oob=False preconfig=False
object q_obj_user-def-cmd1-arg
member ud1a: UserDefOne optional=False
command user-def-cmd1 q_obj_user-def-cmd1-arg -> None
gen=True success_response=True boxed=False oob=False preconfig=False
object q_obj_user-def-cmd2-arg
member ud1a: UserDefOne optional=False
member ud1b: UserDefOne optional=True
command user-def-cmd2 q_obj_user-def-cmd2-arg -> UserDefTwo
gen=True success_response=True boxed=False oob=False preconfig=False
command cmd-success-response None -> None
gen=True success_response=False boxed=False oob=False preconfig=False
command coroutine-cmd None -> None
gen=True success_response=True boxed=False oob=False preconfig=False coroutine=True
object q_obj_guest-get-time-arg
member a: int optional=False
member b: int optional=True
command guest-get-time q_obj_guest-get-time-arg -> int
gen=True success_response=True boxed=False oob=False preconfig=False
object q_obj_guest-sync-arg
member arg: any optional=False
command guest-sync q_obj_guest-sync-arg -> any
gen=True success_response=True boxed=False oob=False preconfig=False
command boxed-struct UserDefZero -> None
gen=True success_response=True boxed=True oob=False preconfig=False
command boxed-union UserDefFlatUnion -> None
gen=True success_response=True boxed=True oob=False preconfig=False
command boxed-empty Empty1 -> None
gen=True success_response=True boxed=True oob=False preconfig=False
command test-flags-command None -> None
gen=True success_response=True boxed=False oob=True preconfig=True
object UserDefOptions
member i64: intList optional=True
member u64: uint64List optional=True
member u16: uint16List optional=True
member i64x: int optional=True
member u64x: uint64 optional=True
object EventStructOne
member struct1: UserDefOne optional=False
member string: str optional=False
member enum2: EnumOne optional=True
event EVENT_A None
boxed=False
event EVENT_B None
boxed=False
object q_obj_EVENT_C-arg
member a: int optional=True
member b: UserDefOne optional=True
member c: str optional=False
event EVENT_C q_obj_EVENT_C-arg
boxed=False
object q_obj_EVENT_D-arg
member a: EventStructOne optional=False
member b: str optional=False
member c: str optional=True
member enum3: EnumOne optional=True
event EVENT_D q_obj_EVENT_D-arg
boxed=False
event EVENT_E UserDefZero
boxed=True
event EVENT_F UserDefFlatUnion
boxed=True
event EVENT_G Empty1
boxed=True
enum __org.qemu_x-Enum
member __org.qemu_x-value
object __org.qemu_x-Base
member __org.qemu_x-member1: __org.qemu_x-Enum optional=False
object __org.qemu_x-Struct
base __org.qemu_x-Base
member __org.qemu_x-member2: str optional=False
member wchar-t: int optional=True
alternate __org.qemu_x-Alt1
tag type
case __org.qemu_x-branch: str
array __org.qemu_x-UnionList __org.qemu_x-Union
object __org.qemu_x-Struct2
member array: __org.qemu_x-UnionList optional=False
object __org.qemu_x-Union
base __org.qemu_x-Base
tag __org.qemu_x-member1
case __org.qemu_x-value: __org.qemu_x-Struct2
alternate __org.qemu_x-Alt
tag type
case __org.qemu_x-branch: __org.qemu_x-Base
event __ORG.QEMU_X-EVENT __org.qemu_x-Struct
boxed=False
array __org.qemu_x-EnumList __org.qemu_x-Enum
array __org.qemu_x-StructList __org.qemu_x-Struct
object q_obj___org.qemu_x-command-arg
member a: __org.qemu_x-EnumList optional=False
member b: __org.qemu_x-StructList optional=False
member c: __org.qemu_x-Union optional=False
member d: __org.qemu_x-Alt optional=False
command __org.qemu_x-command q_obj___org.qemu_x-command-arg -> None
gen=True success_response=True boxed=False oob=False preconfig=False
object TestIfStruct
member foo: int optional=False
member bar: int optional=False
if TEST_IF_STRUCT_BAR
if TEST_IF_STRUCT
enum TestIfEnum
member foo
member bar
if TEST_IF_ENUM_BAR
if TEST_IF_ENUM
object q_obj_TestIfUnion-base
member type: TestIfEnum optional=False
if {'all': ['TEST_IF_UNION', 'TEST_IF_STRUCT']}
object TestIfUnion
base q_obj_TestIfUnion-base
tag type
case foo: TestStruct
case bar: UserDefZero
if TEST_IF_ENUM_BAR
if {'all': ['TEST_IF_UNION', 'TEST_IF_STRUCT']}
object q_obj_test-if-union-cmd-arg
member union-cmd-arg: TestIfUnion optional=False
if {'all': ['TEST_IF_UNION', 'TEST_IF_STRUCT']}
command test-if-union-cmd q_obj_test-if-union-cmd-arg -> None
gen=True success_response=True boxed=False oob=False preconfig=False
if {'all': ['TEST_IF_UNION', 'TEST_IF_STRUCT']}
alternate TestIfAlternate
tag type
case foo: int
case bar: TestStruct
if TEST_IF_ALT_BAR
if {'all': ['TEST_IF_ALT', 'TEST_IF_STRUCT']}
object q_obj_test-if-alternate-cmd-arg
member alt-cmd-arg: TestIfAlternate optional=False
if {'all': ['TEST_IF_ALT', 'TEST_IF_STRUCT']}
command test-if-alternate-cmd q_obj_test-if-alternate-cmd-arg -> None
gen=True success_response=True boxed=False oob=False preconfig=False
if {'all': ['TEST_IF_ALT', 'TEST_IF_STRUCT']}
object q_obj_test-if-cmd-arg
member foo: TestIfStruct optional=False
member bar: TestIfEnum optional=False
if TEST_IF_CMD_BAR
if {'all': ['TEST_IF_CMD', 'TEST_IF_STRUCT']}
command test-if-cmd q_obj_test-if-cmd-arg -> UserDefThree
gen=True success_response=True boxed=False oob=False preconfig=False
if {'all': ['TEST_IF_CMD', 'TEST_IF_STRUCT']}
command test-cmd-return-def-three None -> UserDefThree
gen=True success_response=True boxed=False oob=False preconfig=False
array TestIfEnumList TestIfEnum
if TEST_IF_ENUM
object q_obj_TEST_IF_EVENT-arg
member foo: TestIfStruct optional=False
member bar: TestIfEnumList optional=False
if TEST_IF_EVT_BAR
if {'all': ['TEST_IF_EVT', 'TEST_IF_STRUCT']}
event TEST_IF_EVENT q_obj_TEST_IF_EVENT-arg
boxed=False
if {'all': ['TEST_IF_EVT', 'TEST_IF_STRUCT']}
event TEST_IF_EVENT2 None
boxed=False
if {'not': {'any': [{'not': 'TEST_IF_EVT'}, {'not': 'TEST_IF_STRUCT'}]}}
object FeatureStruct0
member foo: int optional=False
object FeatureStruct1
member foo: int optional=False
feature deprecated
feature feature1
object FeatureStruct2
member foo: int optional=False
feature unstable
feature feature1
object FeatureStruct3
member foo: int optional=False
feature feature1
feature feature2
object FeatureStruct4
member namespace-test: int optional=False
feature namespace-test
feature int
feature name
feature if
object CondFeatureStruct1
member foo: int optional=False
feature feature1
if TEST_IF_FEATURE_1
object CondFeatureStruct2
member foo: int optional=False
feature feature1
if TEST_IF_FEATURE_1
feature feature2
if TEST_IF_FEATURE_2
object CondFeatureStruct3
member foo: int optional=False
feature feature1
if {'all': ['TEST_IF_COND_1', 'TEST_IF_COND_2']}
object CondFeatureStruct4
member foo: int optional=False
feature feature1
if {'any': ['TEST_IF_COND_1', 'TEST_IF_COND_2']}
enum FeatureEnum1
member eins
member zwei
member drei
feature deprecated
feature feature1
object q_obj_FeatureUnion1-base
member tag: FeatureEnum1 optional=False
object FeatureUnion1
base q_obj_FeatureUnion1-base
tag tag
case eins: FeatureStruct1
case zwei: q_empty
case drei: q_empty
feature feature1
alternate FeatureAlternate1
tag type
case eins: FeatureStruct1
feature feature1
object q_obj_test-features0-arg
member fs0: FeatureStruct0 optional=True
member fs1: FeatureStruct1 optional=True
member fs2: FeatureStruct2 optional=True
member fs3: FeatureStruct3 optional=True
member fs4: FeatureStruct4 optional=True
member cfs1: CondFeatureStruct1 optional=True
member cfs2: CondFeatureStruct2 optional=True
member cfs3: CondFeatureStruct3 optional=True
member cfs4: CondFeatureStruct4 optional=True
command test-features0 q_obj_test-features0-arg -> FeatureStruct1
gen=True success_response=True boxed=False oob=False preconfig=False
command test-command-features1 None -> None
gen=True success_response=True boxed=False oob=False preconfig=False
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
gen=True success_response=True boxed=False oob=False preconfig=False
feature feature1
if TEST_IF_FEATURE_1
command test-command-cond-features2 None -> None
gen=True success_response=True boxed=False oob=False preconfig=False
feature feature1
if TEST_IF_FEATURE_1
feature feature2
if TEST_IF_FEATURE_2
command test-command-cond-features3 None -> None
gen=True success_response=True boxed=False oob=False preconfig=False
feature feature1
if {'all': ['TEST_IF_COND_1', 'TEST_IF_COND_2']}
event TEST_EVENT_FEATURES0 FeatureStruct1
boxed=False
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
member s: StatusList optional=False
module sub-sub-module.json
array StatusList Status
enum Status
member good
member bad
member ugly
Reference in New Issue View Git Blame Copy Permalink