From 1a9a507b2e3e90aa719c96b4c092e7fad7215f21 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 16 Sep 2015 13:06:29 +0200 Subject: qapi-introspect: Hide type names To eliminate the temptation for clients to look up types by name (which are not ABI), replace all type names by meaningless strings. Reduces output of query-schema by 13 out of 85KiB. As a debugging aid, provide option -u to suppress the hiding. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <1442401589-24189-27-git-send-email-armbru@redhat.com> --- docs/qapi-code-gen.txt | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index f321d4b949..b1c8361d22 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -530,13 +530,16 @@ additional variant members depending on the value of meta-type. Each SchemaInfo object describes a wire ABI entity of a certain meta-type: a command, event or one of several kinds of type. -SchemaInfo for entities defined in the QAPI schema have the same name -as in the schema. This is the case for all commands and events, and -most types. +SchemaInfo for commands and events have the same name as in the QAPI +schema. Command and event names are part of the wire ABI, but type names are -not. Therefore, looking up a type by its name in the QAPI schema is -wrong. Look up the command or event, then follow references by name. +not. Therefore, the SchemaInfo for types have auto-generated +meaningless names. For readability, the examples in this section use +meaningful type names instead. + +To examine a type, start with a command or event using it, then follow +references by name. QAPI schema definitions not reachable that way are omitted. @@ -567,8 +570,7 @@ object type without members. The event may not have a data member on the wire then. Each command or event defined with dictionary-valued 'data' in the -QAPI schema implicitly defines an object type called ":obj-NAME-arg", -where NAME is the command or event's name. +QAPI schema implicitly defines an object type. Example: the SchemaInfo for EVENT_C from section Events @@ -623,12 +625,9 @@ Note that base types are "flattened": its members are included in the A simple union implicitly defines an enumeration type for its implicit discriminator (called "type" on the wire, see section Union types). -Such a type's name is made by appending "Kind" to the simple union's -name. A simple union implicitly defines an object type for each of its -variants. The type's name is ":obj-NAME-wrapper", where NAME is the -name of the name of the variant's type. +variants. Example: the SchemaInfo for simple union BlockdevOptions from section Union types @@ -659,8 +658,7 @@ Example: the SchemaInfo for BlockRef from section Alternate types The SchemaInfo for an array type has meta-type "array", and variant member "element-type", which names the array's element type. Array -types are implicitly defined. An array type's name is made by -appending "List" to its element type's name. +types are implicitly defined. Example: the SchemaInfo for ['str'] @@ -1067,13 +1065,13 @@ Example: [Uninteresting stuff omitted...] const char example_qmp_schema_json[] = "[" - "{\"arg-type\": \":empty\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, " + "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, " + "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, " + "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, " + "{\"members\": [{\"name\": \"arg1\", \"type\": \"2\"}], \"meta-type\": \"object\", \"name\": \"1\"}, " + "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, " "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, " - "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}, " - "{\"members\": [], \"meta-type\": \"object\", \"name\": \":empty\"}, " - "{\"members\": [{\"name\": \"arg1\", \"type\": \"UserDefOne\"}], \"meta-type\": \"object\", \"name\": \":obj-my-command-arg\"}, " - "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"UserDefOne\"}, " - "{\"arg-type\": \":obj-my-command-arg\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"UserDefOne\"}]"; + "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]"; $ cat qapi-generated/example-qmp-introspect.h [Uninteresting stuff omitted...] -- cgit v1.2.1