QAPI patches for 2017-03-16

-----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJYyi4+AAoJEDhwtADrkYZTvK4P/3S4ggOt/BKs13ayJUMXemeT
 snGc0lpDOQMobE6zjsjuPtO0oZYtqi2A+LW+PC5aPADTvjqna6mywLxoEUc/Q7tB
 +Tv27NerbpYKzmZxUJKkTrVCwTPaYmEfnKO0wTjYI/cme359nEiMPd4ZPYZSgAfh
 ZTdeMVp0mUoQTbNHkw8/y4KsWMtwgsJDNgIcYyq303BPAG9P1QOAWi4gj/11GZoo
 MnDMk5KmoE7S9eq1R/GCjmg9plEbkx/nwXqpddpwTBQiwicPORhRzEa/SmOOd5xY
 vIOIakukRUYBpqTZdvyvNX8HGvI32qyG87mG/2+sWH+nSM5bYG+uSxJKoJuy7PFS
 ABmEmfd8ghkOe2mGDy/jiCa0VGYImd+uCwNEUUOlko4ccxXHDnC9rlZepc4STeDW
 Un4KoBszBXKOL6oqtdSqNWgCd2IpULFBldi27qo2K7EZCBZ62daP8y7CONLbisj9
 bwuKgkp0124Ds/MV/dTJ5bFPgYdAyG85POnxQfktSqHKGwYunmyh/98Awj4zhy0h
 5gDuN5FjDeRsjzao9xkVYhQPMS97TuUVMvixz6pGTilKu3pMyrw0YfveIE7iif0d
 AZicrwGlUHoccZyhjM+wbutPjt4P2/pFKk7J0p1LX1PCa7ZU79ORRwVdAeNVywoF
 M+PtTo1TYvJ9TfdPkH2g
 =u+an
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-03-16' into staging

QAPI patches for 2017-03-16

# gpg: Signature made Thu 16 Mar 2017 06:18:38 GMT
# gpg:                using RSA key 0x3870B400EB918653
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>"
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>"
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2017-03-16: (49 commits)
  qapi: Fix a misleading parser error message
  qapi: Make pylint a bit happier
  qapi: Drop unused .check_clash() parameter schema
  qapi: union_types is a list used like a dict, make it one
  qapi: struct_types is a list used like a dict, make it one
  qapi: enum_types is a list used like a dict, make it one
  qapi: Factor add_name() calls out of the meta conditional
  qapi: Simplify what gets stored in enum_types
  qapi: Drop unused variable events
  qapi: Eliminate check_docs() and drop QAPIDoc.expr
  qapi: Fix detection of bogus member documentation
  tests/qapi-schema: Improve coverage of bogus member docs
  tests/qapi-schema: Rename doc-bad-args to doc-bad-command-arg
  qapi: Move empty doc section checking to doc parser
  qapi: Improve error message on @NAME: in free-form doc
  qapi: Move detection of doc / expression name mismatch
  qapi: Fix detection of doc / expression mismatch
  tests/qapi-schema: Improve doc / expression mismatch coverage
  qapi2texi: Use category "Object" for all object types
  qapi2texi: Generate descriptions for simple union tags
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

.gitignore

@@ -99,15 +99,15 @@
 /pc-bios/optionrom/kvmvapic.img
 /pc-bios/s390-ccw/s390-ccw.elf
 /pc-bios/s390-ccw/s390-ccw.img
+/docs/qemu-ga-qapi.texi
 /docs/qemu-ga-ref.html
+/docs/qemu-ga-ref.info*
 /docs/qemu-ga-ref.txt
+/docs/qemu-qmp-qapi.texi
 /docs/qemu-qmp-ref.html
+/docs/qemu-qmp-ref.info*
 /docs/qemu-qmp-ref.txt
-docs/qemu-ga-ref.info*
+/docs/version.texi
-docs/qemu-qmp-ref.info*
-/qemu-ga-qapi.texi
-/qemu-qapi.texi
-/version.texi
 *.tps
 .stgit-*
 cscope.*

Makefile

@@ -516,7 +516,7 @@ distclean: clean
 	rm -f qemu-doc.vr qemu-doc.txt
 	rm -f config.log
 	rm -f linux-headers/asm
-	rm -f qemu-ga-qapi.texi qemu-qapi.texi version.texi
+	rm -f docs/qemu-ga-qapi.texi docs/qemu-qmp-qapi.texi docs/version.texi
 	rm -f docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7
 	rm -f docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt
 	rm -f docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf
@@ -663,25 +663,28 @@ ui/console-gl.o: $(SRC_PATH)/ui/console-gl.c \
 
 # documentation
 MAKEINFO=makeinfo
-MAKEINFOFLAGS=--no-split --number-sections
+MAKEINFOFLAGS=--no-split --number-sections -I docs
 TEXIFLAG=$(if $(V),,--quiet)
 
-version.texi: $(SRC_PATH)/VERSION
+docs/version.texi: $(SRC_PATH)/VERSION
 	$(call quiet-command,echo "@set VERSION $(VERSION)" > $@,"GEN","$@")
 
-%.html: %.texi version.texi
+%.html: %.texi
 	$(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers \
 	--html $< -o $@,"GEN","$@")
 
-%.info: %.texi version.texi
+%.info: %.texi
 	$(call quiet-command,$(MAKEINFO) $(MAKEINFOFLAGS) $< -o $@,"GEN","$@")
 
-%.txt: %.texi version.texi
+%.txt: %.texi
 	$(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers \
 	--plaintext $< -o $@,"GEN","$@")
 
-%.pdf: %.texi version.texi
+%.pdf: %.texi
-	$(call quiet-command,texi2pdf $(TEXIFLAG) -I $(SRC_PATH) -I . $< -o $@,"GEN","$@")
+	$(call quiet-command,texi2pdf $(TEXIFLAG) -I $(SRC_PATH) -I docs $< -o $@,"GEN","$@")
+
+docs/qemu-ga-ref.html docs/qemu-ga-ref.info docs/qemu-ga-ref.txt docs/qemu-ga-ref.pdf docs/qemu-ga-ref.7.pod: docs/version.texi
+docs/qemu-qmp-ref.html docs/qemu-qmp-ref.info docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.pdf docs/qemu-qmp-ref.pod: docs/version.texi
 
 qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
@@ -695,10 +698,10 @@ qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxt
 qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
 
-qemu-qapi.texi: $(qapi-modules) $(qapi-py)
+docs/qemu-qmp-qapi.texi: $(qapi-modules) $(qapi-py)
 	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > $@,"GEN","$@")
 
-qemu-ga-qapi.texi: $(SRC_PATH)/qga/qapi-schema.json $(qapi-py)
+docs/qemu-ga-qapi.texi: $(SRC_PATH)/qga/qapi-schema.json $(qapi-py)
 	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > $@,"GEN","$@")
 
 qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
@@ -719,10 +722,10 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
 	qemu-monitor-info.texi
 
 docs/qemu-ga-ref.dvi docs/qemu-ga-ref.html docs/qemu-ga-ref.info docs/qemu-ga-ref.pdf docs/qemu-ga-ref.txt docs/qemu-ga-ref.7: \
-docs/qemu-ga-ref.texi qemu-ga-qapi.texi
+docs/qemu-ga-ref.texi docs/qemu-ga-qapi.texi
 
 docs/qemu-qmp-ref.dvi docs/qemu-qmp-ref.html docs/qemu-qmp-ref.info docs/qemu-qmp-ref.pdf docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.7: \
-docs/qemu-qmp-ref.texi qemu-qapi.texi
+docs/qemu-qmp-ref.texi docs/qemu-qmp-qapi.texi
 
 
 ifdef CONFIG_WIN32

docs/qapi-code-gen.txt

@@ -117,10 +117,13 @@ Example:
 
 ==== Expression documentation ====
 
-Each expression that isn't an include directive must be preceded by a
+Each expression that isn't an include directive may be preceded by a
 documentation block.  Such blocks are called expression documentation
 blocks.
 
+When documentation is required (see pragma 'doc-required'), expression
+documentation blocks are mandatory.
+
 The documentation block consists of a first line naming the
 expression, an optional overview, a description of each argument (for
 commands and events) or member (for structs, unions and alternates),
@@ -128,10 +131,8 @@ and optional tagged sections.
 
 FIXME: the parser accepts these things in almost any order.
 
-Optional arguments / members are tagged with the phrase '#optional',
+Extensions added after the expression was first released carry a
-often with their default value; and extensions added after the
+'(since x.y.z)' comment.
-expression was first released are also given a '(since x.y.z)'
-comment.
 
 A tagged section starts with one of the following words:
 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
@@ -147,10 +148,10 @@ For example:
 #
 # Statistics of a virtual block device or a block backing device.
 #
-# @device: #optional If the stats are for a virtual block device, the name
+# @device: If the stats are for a virtual block device, the name
 #          corresponding to the virtual block device.
 #
-# @node-name: #optional The node name of the device. (since 2.3)
+# @node-name: The node name of the device. (since 2.3)
 #
 # ... more members ...
 #
@@ -165,7 +166,7 @@ For example:
 #
 # Query the @BlockStats for all virtual block devices.
 #
-# @query-nodes: #optional If true, the command will query all the
+# @query-nodes: If true, the command will query all the
 #               block nodes ... explain, explain ...  (since 2.3)
 #
 # Returns: A list of @BlockStats for each virtual block devices.
@@ -204,17 +205,17 @@ once.  It is permissible for the schema to contain additional types
 not used by any commands or events in the Client JSON Protocol, for
 the side effect of generated C code used internally.
 
-There are seven top-level expressions recognized by the parser:
+There are eight top-level expressions recognized by the parser:
-'include', 'command', 'struct', 'enum', 'union', 'alternate', and
+'include', 'pragma', 'command', 'struct', 'enum', 'union',
-'event'.  There are several groups of types: simple types (a number of
+'alternate', and 'event'.  There are several groups of types: simple
-built-in types, such as 'int' and 'str'; as well as enumerations),
+types (a number of built-in types, such as 'int' and 'str'; as well as
-complex types (structs and two flavors of unions), and alternate types
+enumerations), complex types (structs and two flavors of unions), and
-(a choice between other types).  The 'command' and 'event' expressions
+alternate types (a choice between other types).  The 'command' and
-can refer to existing types by name, or list an anonymous type as a
+'event' expressions can refer to existing types by name, or list an
-dictionary. Listing a type name inside an array refers to a
+anonymous type as a dictionary. Listing a type name inside an array
-single-dimension array of that type; multi-dimension arrays are not
+refers to a single-dimension array of that type; multi-dimension
-directly supported (although an array of a complex struct that
+arrays are not directly supported (although an array of a complex
-contains an array member is possible).
+struct that contains an array member is possible).
 
 All names must begin with a letter, and contain only ASCII letters,
 digits, hyphen, and underscore.  There are two exceptions: enum values
@@ -249,6 +250,9 @@ Any name (command, event, type, member, or enum value) beginning with
 "x-" is marked experimental, and may be withdrawn or changed
 incompatibly in a future release.
 
+Pragma 'name-case-whitelist' lets you violate the rules on use of
+upper and lower case.  Use for new code is strongly discouraged.
+
 In the rest of this document, usage lines are given for each
 expression type, with literal strings written in lower case and
 placeholders written in capitals.  If a literal string includes a
@@ -282,7 +286,7 @@ The following types are predefined, and map to C as follows:
   QType     QType      JSON string matching enum QType values
 
 
-=== Includes ===
+=== Include directives ===
 
 Usage: { 'include': STRING }
 
@@ -302,6 +306,26 @@ an outer file.  The parser may be made stricter in the future to
 prevent incomplete include files.
 
 
+=== Pragma directives ===
+
+Usage: { 'pragma': DICT }
+
+The pragma directive lets you control optional generator behavior.
+The dictionary's entries are pragma names and values.
+
+Pragma's scope is currently the complete schema.  Setting the same
+pragma to different values in parts of the schema doesn't work.
+
+Pragma 'doc-required' takes a boolean value.  If true, documentation
+is required.  Default is false.
+
+Pragma 'returns-whitelist' takes a list of command names that may
+violate the rules on permitted return types.  Default is none.
+
+Pragma 'name-case-whitelist' takes a list of names that may violate
+rules on use of upper- vs. lower-case letters.  Default is none.
+
+
 === Struct types ===
 
 Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
@@ -541,22 +565,18 @@ The 'data' argument maps to the "arguments" dictionary passed in as
 part of a Client JSON Protocol command.  The 'data' member is optional
 and defaults to {} (an empty dictionary).  If present, it must be the
 string name of a complex type, or a dictionary that declares an
-anonymous type with the same semantics as a 'struct' expression, with
+anonymous type with the same semantics as a 'struct' expression.
-one exception noted below when 'gen' is used.
 
 The 'returns' member describes what will appear in the "return" member
 of a Client JSON Protocol reply on successful completion of a command.
 The member is optional from the command declaration; if absent, the
 "return" member will be an empty dictionary.  If 'returns' is present,
 it must be the string name of a complex or built-in type, a
-one-element array containing the name of a complex or built-in type,
+one-element array containing the name of a complex or built-in type.
-with one exception noted below when 'gen' is used.  Although it is
+To return anything else, you have to list the command in pragma
-permitted to have the 'returns' member name a built-in type or an
+'returns-whitelist'.  If you do this, the command cannot be extended
-array of built-in types, any command that does this cannot be extended
+to return additional information in the future.  Use of
-to return additional information in the future; thus, new commands
+'returns-whitelist' for new commands is strongly discouraged.
-should strongly consider returning a dictionary-based type or an array
-of dictionaries, even if the dictionary only contains one member at the
-present.
 
 All commands in Client JSON Protocol use a dictionary to report
 failure, with no way to specify that in QAPI.  Where the error return

docs/qemu-qmp-ref.texi

@@ -65,7 +65,7 @@ along with this manual.  If not, see http://www.gnu.org/licenses/.
 @c for texi2pod:
 @c man begin DESCRIPTION
 
-@include qemu-qapi.texi
+@include qemu-qmp-qapi.texi
 
 @c man end
 

docs/writing-qmp-commands.txt

@@ -252,7 +252,7 @@ here goes "hello-world"'s new entry for the qapi-schema.json file:
 #
 # Print a client provided string to the standard output stream.
 #
-# @message: #optional string to be printed
+# @message: string to be printed
 #
 # Returns: Nothing on success.
 #
@@ -358,7 +358,7 @@ The best way to return that data is to create a new QAPI type, as shown below:
 #
 # @clock-name: The alarm clock method's name.
 #
-# @next-deadline: #optional The time (in nanoseconds) the next alarm will fire.
+# @next-deadline: The time (in nanoseconds) the next alarm will fire.
 #
 # Since: 1.0
 ##

qapi/block.json

@@ -163,11 +163,11 @@
 #
 # Ejects a device from a removable drive.
 #
-# @device:  #optional Block device name (deprecated, use @id instead)
+# @device:  Block device name (deprecated, use @id instead)
 #
-# @id:      #optional The name or QOM path of the guest device (since: 2.8)
+# @id:      The name or QOM path of the guest device (since: 2.8)
 #
-# @force:   #optional If true, eject regardless of whether the drive is locked.
+# @force:   If true, eject regardless of whether the drive is locked.
 #           If not specified, the default value is false.
 #
 # Returns:  Nothing on success
@@ -215,7 +215,7 @@
 # @device: The device name or node name of the node to be exported
 #
 # @writable: Whether clients should be able to write to the device via the
-#     NBD connection (default false). #optional
+#     NBD connection (default false).
 #
 # Returns: error if the device is already marked for export.
 #

qapi/crypto.json

@@ -152,7 +152,7 @@
 #
 # The options that apply to QCow/QCow2 AES-CBC encryption format
 #
-# @key-secret: #optional the ID of a QCryptoSecret object providing the
+# @key-secret: the ID of a QCryptoSecret object providing the
 #              decryption key. Mandatory except when probing image for
 #              metadata only.
 #
@@ -166,7 +166,7 @@
 #
 # The options that apply to LUKS encryption format
 #
-# @key-secret: #optional the ID of a QCryptoSecret object providing the
+# @key-secret: the ID of a QCryptoSecret object providing the
 #              decryption key. Mandatory except when probing image for
 #              metadata only.
 # Since: 2.6
@@ -180,17 +180,17 @@
 #
 # The options that apply to LUKS encryption format initialization
 #
-# @cipher-alg: #optional the cipher algorithm for data encryption
+# @cipher-alg: the cipher algorithm for data encryption
 #              Currently defaults to 'aes'.
-# @cipher-mode: #optional the cipher mode for data encryption
+# @cipher-mode: the cipher mode for data encryption
 #               Currently defaults to 'cbc'
-# @ivgen-alg: #optional the initialization vector generator
+# @ivgen-alg: the initialization vector generator
 #             Currently defaults to 'essiv'
-# @ivgen-hash-alg: #optional the initialization vector generator hash
+# @ivgen-hash-alg: the initialization vector generator hash
 #                  Currently defaults to 'sha256'
-# @hash-alg: #optional the master key hash algorithm
+# @hash-alg: the master key hash algorithm
 #            Currently defaults to 'sha256'
-# @iter-time: #optional number of milliseconds to spend in
+# @iter-time: number of milliseconds to spend in
 #             PBKDF passphrase processing. Currently defaults
 #             to 2000. (since 2.8)
 # Since: 2.6
@@ -257,8 +257,8 @@
 #
 # @active: whether the key slot is currently in use
 # @key-offset: offset to the key material in bytes
-# @iters: #optional number of PBKDF2 iterations for key material
+# @iters: number of PBKDF2 iterations for key material
-# @stripes: #optional number of stripes for splitting key material
+# @stripes: number of stripes for splitting key material
 #
 # Since: 2.7
 ##
@@ -277,7 +277,7 @@
 # @cipher-alg: the cipher algorithm for data encryption
 # @cipher-mode: the cipher mode for data encryption
 # @ivgen-alg: the initialization vector generator
-# @ivgen-hash-alg: #optional the initialization vector generator hash
+# @ivgen-hash-alg: the initialization vector generator hash
 # @hash-alg: the master key hash algorithm
 # @payload-offset: offset to the payload data in bytes
 # @master-key-iters: number of PBKDF2 iterations for key material

qapi/event.json

@@ -186,7 +186,7 @@
 # At this point, it's safe to reuse the specified device ID. Device removal can
 # be initiated by the guest or by HMP/QMP commands.
 #
-# @device: #optional device name
+# @device: device name
 #
 # @path: device path
 #
@@ -209,7 +209,7 @@
 # Emitted once until the 'query-rx-filter' command is executed, the first event
 # will always be emitted
 #
-# @name: #optional net client name
+# @name: net client name
 #
 # @path: device path
 #
@@ -488,7 +488,7 @@
 #
 # @action: action that has been taken, currently always "pause"
 #
-# @info: #optional information about a panic (since 2.9)
+# @info: information about a panic (since 2.9)
 #
 # Since: 1.5
 #
@@ -533,7 +533,7 @@
 #
 # @type: quorum operation type (Since 2.6)
 #
-# @error: #optional error message. Only present on failure. This field
+# @error: error message. Only present on failure. This field
 #         contains a human-readable error message. There are no semantics other
 #         than that the block layer reported an error and clients should not
 #         try to interpret the error string.
@@ -620,7 +620,7 @@
 #
 # @result: DumpQueryResult type described in qapi-schema.json.
 #
-# @error: #optional human-readable error string that provides
+# @error: human-readable error string that provides
 #         hint on why dump failed. Only presents on failure. The
 #         user should not try to interpret the error string.
 #

qapi/introspect.json

@@ -163,10 +163,10 @@
 #
 # @members: the object type's (non-variant) members, in no particular order.
 #
-# @tag: #optional the name of the member serving as type tag.
+# @tag: the name of the member serving as type tag.
 #       An element of @members with this name must exist.
 #
-# @variants: #optional variant members, i.e. additional members that
+# @variants: variant members, i.e. additional members that
 #            depend on the type tag's value.  Present exactly when
 #            @tag is present.  The variants are in no particular order,
 #            and may even differ from the order of the values of the
@@ -190,7 +190,7 @@
 #
 # @type: the name of the member's type.
 #
-# @default: #optional default when used as command parameter.
+# @default: default when used as command parameter.
 #           If absent, the parameter is mandatory.
 #           If present, the value must be null.  The parameter is
 #           optional, and behavior when it's missing is not specified

qapi/rocker.json

@@ -1,3 +1,5 @@
+# -*- Mode: Python -*-
+
 ##
 # = Rocker switch device
 ##
@@ -119,26 +121,26 @@
 #
 # @tbl-id: flow table ID
 #
-# @in-pport: #optional physical input port
+# @in-pport: physical input port
 #
-# @tunnel-id: #optional tunnel ID
+# @tunnel-id: tunnel ID
 #
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
 #
-# @eth-type: #optional Ethernet header type
+# @eth-type: Ethernet header type
 #
-# @eth-src: #optional Ethernet header source MAC address
+# @eth-src: Ethernet header source MAC address
 #
-# @eth-dst: #optional Ethernet header destination MAC address
+# @eth-dst: Ethernet header destination MAC address
 #
-# @ip-proto: #optional IP Header protocol field
+# @ip-proto: IP Header protocol field
 #
-# @ip-tos: #optional IP header TOS field
+# @ip-tos: IP header TOS field
 #
-# @ip-dst: #optional IP header destination address
+# @ip-dst: IP header destination address
 #
-# Note: fields are marked #optional to indicate that they may or may not
+# Note: optional members may or may not appear in the flow key
-# appear in the flow key depending if they're relevant to the flow key.
+# depending if they're relevant to the flow key.
 #
 # Since: 2.4
 ##
@@ -153,22 +155,22 @@
 #
 # Rocker switch OF-DPA flow mask
 #
-# @in-pport: #optional physical input port
+# @in-pport: physical input port
 #
-# @tunnel-id: #optional tunnel ID
+# @tunnel-id: tunnel ID
 #
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
 #
-# @eth-src: #optional Ethernet header source MAC address
+# @eth-src: Ethernet header source MAC address
 #
-# @eth-dst: #optional Ethernet header destination MAC address
+# @eth-dst: Ethernet header destination MAC address
 #
-# @ip-proto: #optional IP Header protocol field
+# @ip-proto: IP Header protocol field
 #
-# @ip-tos: #optional IP header TOS field
+# @ip-tos: IP header TOS field
 #
-# Note: fields are marked #optional to indicate that they may or may not
+# Note: optional members may or may not appear in the flow mask
-# appear in the flow mask depending if they're relevant to the flow mask.
+# depending if they're relevant to the flow mask.
 #
 # Since: 2.4
 ##
@@ -182,20 +184,20 @@
 #
 # Rocker switch OF-DPA flow action
 #
-# @goto-tbl: #optional next table ID
+# @goto-tbl: next table ID
 #
-# @group-id: #optional group ID
+# @group-id: group ID
 #
-# @tunnel-lport: #optional tunnel logical port ID
+# @tunnel-lport: tunnel logical port ID
 #
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
 #
-# @new-vlan-id: #optional new VLAN ID
+# @new-vlan-id: new VLAN ID
 #
-# @out-pport: #optional physical output port
+# @out-pport: physical output port
 #
-# Note: fields are marked #optional to indicate that they may or may not
+# Note: optional members may or may not appear in the flow action
-# appear in the flow action depending if they're relevant to the flow action.
+# depending if they're relevant to the flow action.
 #
 # Since: 2.4
 ##
@@ -232,7 +234,7 @@
 #
 # @name: switch name
 #
-# @tbl-id: #optional flow table ID.  If tbl-id is not specified, returns
+# @tbl-id: flow table ID.  If tbl-id is not specified, returns
 # flow information for all tables.
 #
 # Returns: rocker OF-DPA flow information
@@ -266,30 +268,30 @@
 #
 # @type: group type
 #
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
 #
-# @pport: #optional physical port number
+# @pport: physical port number
 #
-# @index: #optional group index, unique with group type
+# @index: group index, unique with group type
 #
-# @out-pport: #optional output physical port number
+# @out-pport: output physical port number
 #
-# @group-id: #optional next group ID
+# @group-id: next group ID
 #
-# @set-vlan-id: #optional VLAN ID to set
+# @set-vlan-id: VLAN ID to set
 #
-# @pop-vlan: #optional pop VLAN headr from packet
+# @pop-vlan: pop VLAN headr from packet
 #
-# @group-ids: #optional list of next group IDs
+# @group-ids: list of next group IDs
 #
-# @set-eth-src: #optional set source MAC address in Ethernet header
+# @set-eth-src: set source MAC address in Ethernet header
 #
-# @set-eth-dst: #optional set destination MAC address in Ethernet header
+# @set-eth-dst: set destination MAC address in Ethernet header
 #
-# @ttl-check: #optional perform TTL check
+# @ttl-check: perform TTL check
 #
-# Note: fields are marked #optional to indicate that they may or may not
+# Note: optional members may or may not appear in the group depending
-# appear in the group depending if they're relevant to the group type.
+# if they're relevant to the group type.
 #
 # Since: 2.4
 ##
@@ -308,7 +310,7 @@
 #
 # @name: switch name
 #
-# @type: #optional group type.  If type is not specified, returns
+# @type: group type.  If type is not specified, returns
 # group information for all group types.
 #
 # Returns: rocker OF-DPA group information

qapi/trace.json

@@ -48,7 +48,7 @@
 # Query the state of events.
 #
 # @name: Event name pattern (case-sensitive glob).
-# @vcpu: #optional The vCPU to query (any by default; since 2.7).
+# @vcpu: The vCPU to query (any by default; since 2.7).
 #
 # Returns: a list of @TraceEventInfo for the matching events
 #
@@ -81,8 +81,8 @@
 #
 # @name: Event name pattern (case-sensitive glob).
 # @enable: Whether to enable tracing.
-# @ignore-unavailable: #optional Do not match unavailable events with @name.
+# @ignore-unavailable: Do not match unavailable events with @name.
-# @vcpu: #optional The vCPU to act upon (all by default; since 2.7).
+# @vcpu: The vCPU to act upon (all by default; since 2.7).
 #
 # An event's state is modified if:
 # - its name matches the @name pattern, and

qga/qapi-schema.json

@@ -11,6 +11,23 @@
 #
 ##
 
+{ 'pragma': { 'doc-required': true } }
+
+# Whitelists to permit QAPI rule violations; think twice before you
+# add to them!
+{ 'pragma': {
+    # Commands allowed to return a non-dictionary:
+    'returns-whitelist': [
+        'guest-file-open',
+        'guest-fsfreeze-freeze',
+        'guest-fsfreeze-freeze-list',
+        'guest-fsfreeze-status',
+        'guest-fsfreeze-thaw',
+        'guest-get-time',
+        'guest-set-vcpus',
+        'guest-sync',
+        'guest-sync-delimited' ] } }
+
 ##
 # @guest-sync-delimited:
 #
@@ -127,7 +144,7 @@
 # If that's the case users are advised to always pass a
 # value.
 #
-# @time: #optional time of nanoseconds, relative to the Epoch
+# @time: time of nanoseconds, relative to the Epoch
 #        of 1970-01-01 in UTC.
 #
 # Returns: Nothing on success.
@@ -186,7 +203,7 @@
 # Initiate guest-activated shutdown. Note: this is an asynchronous
 # shutdown request, with no guarantee of successful shutdown.
 #
-# @mode: #optional "halt", "powerdown" (default), or "reboot"
+# @mode: "halt", "powerdown" (default), or "reboot"
 #
 # This command does NOT return a response on success. Success condition
 # is indicated by the VM exiting with a zero exit status or, when
@@ -205,7 +222,7 @@
 #
 # @path: Full path to the file in the guest to open.
 #
-# @mode: #optional open mode, as per fopen(), "r" is the default.
+# @mode: open mode, as per fopen(), "r" is the default.
 #
 # Returns: Guest file handle on success.
 #
@@ -253,7 +270,7 @@
 #
 # @handle: filehandle returned by guest-file-open
 #
-# @count: #optional maximum number of bytes to read (default is 4KB)
+# @count: maximum number of bytes to read (default is 4KB)
 #
 # Returns: @GuestFileRead on success.
 #
@@ -287,7 +304,7 @@
 #
 # @buf-b64: base64-encoded string representing data to be written
 #
-# @count: #optional bytes to write (actual bytes, after base64-decode),
+# @count: bytes to write (actual bytes, after base64-decode),
 #         default is all content in buf-b64 buffer after base64 decoding
 #
 # Returns: @GuestFileWrite on success.
@@ -424,7 +441,7 @@
 #
 # Sync and freeze specified guest filesystems
 #
-# @mountpoints: #optional an array of mountpoints of filesystems to be frozen.
+# @mountpoints: an array of mountpoints of filesystems to be frozen.
 #               If omitted, every mounted filesystem is frozen.
 #
 # Returns: Number of file systems currently frozen. On error, all filesystems
@@ -653,7 +670,7 @@
 #
 # @online: Whether the VCPU is enabled.
 #
-# @can-offline: #optional Whether offlining the VCPU is possible. This member
+# @can-offline: Whether offlining the VCPU is possible. This member
 #               is always filled in by the guest agent when the structure is
 #               returned, and always ignored on input (hence it can be omitted
 #               then).
@@ -841,7 +858,7 @@
 #
 # @online: Whether the MEMORY BLOCK is enabled in guest.
 #
-# @can-offline: #optional Whether offlining the MEMORY BLOCK is possible.
+# @can-offline: Whether offlining the MEMORY BLOCK is possible.
 #               This member is always filled in by the guest agent when the
 #               structure is returned, and always ignored on input (hence it
 #               can be omitted then).
@@ -894,7 +911,7 @@
 #
 # @response: the result of memory block operation.
 #
-# @error-code: #optional the error number.
+# @error-code: the error number.
 #               When memory block operation fails, we assign the value of
 #               'errno' to this member, it indicates what goes wrong.
 #               When the operation succeeds, it will be omitted.
@@ -962,16 +979,16 @@
 # @GuestExecStatus:
 #
 # @exited: true if process has already terminated.
-# @exitcode: #optional process exit code if it was normally terminated.
+# @exitcode: process exit code if it was normally terminated.
-# @signal: #optional signal number (linux) or unhandled exception code
+# @signal: signal number (linux) or unhandled exception code
 #       (windows) if the process was abnormally terminated.
-# @out-data: #optional base64-encoded stdout of the process
+# @out-data: base64-encoded stdout of the process
-# @err-data: #optional base64-encoded stderr of the process
+# @err-data: base64-encoded stderr of the process
 #       Note: @out-data and @err-data are present only
 #       if 'capture-output' was specified for 'guest-exec'
-# @out-truncated: #optional true if stdout was not fully captured
+# @out-truncated: true if stdout was not fully captured
 #       due to size limitation.
-# @err-truncated: #optional true if stderr was not fully captured
+# @err-truncated: true if stderr was not fully captured
 #       due to size limitation.
 #
 # Since: 2.5
@@ -1011,10 +1028,10 @@
 # Execute a command in the guest
 #
 # @path: path or executable name to execute
-# @arg: #optional argument list to pass to executable
+# @arg: argument list to pass to executable
-# @env: #optional environment variables to pass to executable
+# @env: environment variables to pass to executable
-# @input-data: #optional data to be passed to process stdin (base64 encoded)
+# @input-data: data to be passed to process stdin (base64 encoded)
-# @capture-output: #optional bool flag to enable capture of
+# @capture-output: bool flag to enable capture of
 #                  stdout/stderr of running process. defaults to false.
 #
 # Returns: PID on success.

rules.mak

@@ -380,7 +380,7 @@ define unnest-vars
 endef
 
 TEXI2MAN = $(call quiet-command, \
-	perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< $@.pod && \
+	perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl -I docs $< $@.pod && \
 	$(POD2MAN) --section=$(subst .,,$(suffix $@)) --center=" " --release=" " $@.pod > $@, \
 	"GEN","$@")
 

scripts/qapi-commands.py

@@ -13,7 +13,6 @@
 # See the COPYING file in the top-level directory.
 
 from qapi import *
-import re
 
 
 def gen_command_decl(name, arg_type, boxed, ret_type):
@@ -84,7 +83,8 @@ static void qmp_marshal_output_%(c_name)s(%(c_type)s ret_in, QObject **ret_out,
 
 
 def gen_marshal_proto(name):
-    return 'void qmp_marshal_%s(QDict *args, QObject **ret, Error **errp)' % c_name(name)
+    return ('void qmp_marshal_%s(QDict *args, QObject **ret, Error **errp)'
+            % c_name(name))
 
 
 def gen_marshal_decl(name):
@@ -198,7 +198,7 @@ def gen_register_command(name, success_response):
         options = 'QCO_NO_SUCCESS_RESP'
 
     ret = mcgen('''
-    qmp_register_command(cmds, "%(name)s", 
+    qmp_register_command(cmds, "%(name)s",
                          qmp_marshal_%(c_name)s, %(opts)s);
 ''',
                 name=name, c_name=c_name(name),

scripts/qapi-event.py

@@ -223,7 +223,7 @@ fdecl.write(mcgen('''
 ''',
                   prefix=prefix))
 
-event_enum_name = c_name(prefix + "QAPIEvent", protect=False)
+event_enum_name = c_name(prefix + 'QAPIEvent', protect=False)
 
 schema = QAPISchema(input_file)
 gen = QAPISchemaGenEventVisitor()

scripts/qapi-introspect.py

@@ -170,10 +170,10 @@ const char %(c_name)s[] = %(c_string)s;
 opt_unmask = False
 
 (input_file, output_dir, do_c, do_h, prefix, opts) = \
-    parse_command_line("u", ["unmask-non-abi-names"])
+    parse_command_line('u', ['unmask-non-abi-names'])
 
 for o, a in opts:
-    if o in ("-u", "--unmask-non-abi-names"):
+    if o in ('-u', '--unmask-non-abi-names'):
         opt_unmask = True
 
 c_comment = '''

scripts/qapi-types.py

@@ -244,10 +244,10 @@ class QAPISchemaGenTypeVisitor(QAPISchemaVisitor):
 do_builtins = False
 
 (input_file, output_dir, do_c, do_h, prefix, opts) = \
-    parse_command_line("b", ["builtins"])
+    parse_command_line('b', ['builtins'])
 
 for o, a in opts:
-    if o in ("-b", "--builtins"):
+    if o in ('-b', '--builtins'):
         do_builtins = True
 
 c_comment = '''

scripts/qapi-visit.py

@@ -13,7 +13,6 @@
 # See the COPYING file in the top-level directory.
 
 from qapi import *
-import re
 
 
 def gen_visit_decl(name, scalar=False):
@@ -335,10 +334,10 @@ class QAPISchemaGenVisitVisitor(QAPISchemaVisitor):
 do_builtins = False
 
 (input_file, output_dir, do_c, do_h, prefix, opts) = \
-    parse_command_line("b", ["builtins"])
+    parse_command_line('b', ['builtins'])
 
 for o, a in opts:
-    if o in ("-b", "--builtins"):
+    if o in ('-b', '--builtins'):
         do_builtins = True
 
 c_comment = '''

scripts/qapi2texi.py

@@ -9,7 +9,7 @@ import sys
 
 import qapi
 
-COMMAND_FMT = """
+MSG_FMT = """
 @deftypefn {type} {{}} {name}
 
 {body}
@@ -18,16 +18,7 @@ COMMAND_FMT = """
 
 """.format
 
-ENUM_FMT = """
+TYPE_FMT = """
-@deftp Enum {name}
-
-{body}
-
-@end deftp
-
-""".format
-
-STRUCT_FMT = """
 @deftp {{{type}}} {name}
 
 {body}
@@ -59,7 +50,7 @@ def subst_vars(doc):
 
 def subst_braces(doc):
     """Replaces {} with @{ @}"""
-    return doc.replace("{", "@{").replace("}", "@}")
+    return doc.replace('{', '@{').replace('}', '@}')
 
 
 def texi_example(doc):
@@ -88,10 +79,10 @@ def texi_format(doc):
     doc = subst_vars(doc)
     doc = subst_emph(doc)
     doc = subst_strong(doc)
-    inlist = ""
+    inlist = ''
     lastempty = False
     for line in doc.split('\n'):
-        empty = line == ""
+        empty = line == ''
 
         # FIXME: Doing this in a single if / elif chain is
         # problematic.  For instance, a line without markup terminates
@@ -101,158 +92,194 @@ def texi_format(doc):
         #
         # Make sure to update section "Documentation markup" in
         # docs/qapi-code-gen.txt when fixing this.
-        if line.startswith("| "):
+        if line.startswith('| '):
             line = EXAMPLE_FMT(code=line[2:])
-        elif line.startswith("= "):
+        elif line.startswith('= '):
-            line = "@section " + line[2:]
+            line = '@section ' + line[2:]
-        elif line.startswith("== "):
+        elif line.startswith('== '):
-            line = "@subsection " + line[3:]
+            line = '@subsection ' + line[3:]
         elif re.match(r'^([0-9]*\.) ', line):
             if not inlist:
-                lines.append("@enumerate")
+                lines.append('@enumerate')
-                inlist = "enumerate"
+                inlist = 'enumerate'
-            line = line[line.find(" ")+1:]
+            line = line[line.find(' ')+1:]
-            lines.append("@item")
+            lines.append('@item')
         elif re.match(r'^[*-] ', line):
             if not inlist:
-                lines.append("@itemize %s" % {'*': "@bullet",
+                lines.append('@itemize %s' % {'*': '@bullet',
-                                              '-': "@minus"}[line[0]])
+                                              '-': '@minus'}[line[0]])
-                inlist = "itemize"
+                inlist = 'itemize'
-            lines.append("@item")
+            lines.append('@item')
             line = line[2:]
         elif lastempty and inlist:
-            lines.append("@end %s\n" % inlist)
+            lines.append('@end %s\n' % inlist)
-            inlist = ""
+            inlist = ''
 
         lastempty = empty
         lines.append(line)
 
     if inlist:
-        lines.append("@end %s\n" % inlist)
+        lines.append('@end %s\n' % inlist)
-    return "\n".join(lines)
+    return '\n'.join(lines)
 
 
 def texi_body(doc):
-    """
+    """Format the main documentation body"""
-    Format the body of a symbol documentation:
+    return texi_format(str(doc.body)) + '\n'
-    - main body
-    - table of arguments
-    - followed by "Returns/Notes/Since/Example" sections
-    """
-    body = texi_format(str(doc.body)) + "\n"
-    if doc.args:
-        body += "@table @asis\n"
-        for arg, section in doc.args.iteritems():
-            desc = str(section)
-            opt = ''
-            if "#optional" in desc:
-                desc = desc.replace("#optional", "")
-                opt = ' (optional)'
-            body += "@item @code{'%s'}%s\n%s\n" % (arg, opt,
-                                                   texi_format(desc))
-        body += "@end table\n"
 
+
+def texi_enum_value(value):
+    """Format a table of members item for an enumeration value"""
+    return '@item @code{%s}\n' % value.name
+
+
+def texi_member(member, suffix=''):
+    """Format a table of members item for an object type member"""
+    typ = member.type.doc_type()
+    return '@item @code{%s%s%s}%s%s\n' % (
+        member.name,
+        ': ' if typ else '',
+        typ if typ else '',
+        ' (optional)' if member.optional else '',
+        suffix)
+
+
+def texi_members(doc, what, base, variants, member_func):
+    """Format the table of members"""
+    items = ''
+    for section in doc.args.itervalues():
+        # TODO Drop fallbacks when undocumented members are outlawed
+        if section.content:
+            desc = texi_format(str(section))
+        elif (variants and variants.tag_member == section.member
+              and not section.member.type.doc_type()):
+            values = section.member.type.member_names()
+            desc = 'One of ' + ', '.join(['@t{"%s"}' % v for v in values])
+        else:
+            desc = 'Not documented'
+        items += member_func(section.member) + desc + '\n'
+    if base:
+        items += '@item The members of @code{%s}\n' % base.doc_type()
+    if variants:
+        for v in variants.variants:
+            when = ' when @code{%s} is @t{"%s"}' % (
+                variants.tag_member.name, v.name)
+            if v.type.is_implicit():
+                assert not v.type.base and not v.type.variants
+                for m in v.type.local_members:
+                    items += member_func(m, when)
+            else:
+                items += '@item The members of @code{%s}%s\n' % (
+                    v.type.doc_type(), when)
+    if not items:
+        return ''
+    return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items)
+
+
+def texi_sections(doc):
+    """Format additional sections following arguments"""
+    body = ''
     for section in doc.sections:
         name, doc = (section.name, str(section))
         func = texi_format
-        if name.startswith("Example"):
+        if name.startswith('Example'):
             func = texi_example
 
         if name:
             # prefer @b over @strong, so txt doesn't translate it to *Foo:*
-            body += "\n\n@b{%s:}\n" % name
+            body += '\n\n@b{%s:}\n' % name
 
         body += func(doc)
-
     return body
 
 
-def texi_alternate(expr, doc):
+def texi_entity(doc, what, base=None, variants=None,
-    """Format an alternate to texi"""
+                member_func=texi_member):
-    body = texi_body(doc)
+    return (texi_body(doc)
-    return STRUCT_FMT(type="Alternate",
+            + texi_members(doc, what, base, variants, member_func)
-                      name=doc.symbol,
+            + texi_sections(doc))
-                      body=body)
 
 
-def texi_union(expr, doc):
+class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
-    """Format a union to texi"""
+    def __init__(self):
-    discriminator = expr.get("discriminator")
+        self.out = None
-    if discriminator:
+        self.cur_doc = None
-        union = "Flat Union"
-    else:
-        union = "Simple Union"
 
-    body = texi_body(doc)
+    def visit_begin(self, schema):
-    return STRUCT_FMT(type=union,
+        self.out = ''
-                      name=doc.symbol,
+
-                      body=body)
+    def visit_enum_type(self, name, info, values, prefix):
+        doc = self.cur_doc
+        if self.out:
+            self.out += '\n'
+        self.out += TYPE_FMT(type='Enum',
+                             name=doc.symbol,
+                             body=texi_entity(doc, 'Values',
+                                              member_func=texi_enum_value))
+
+    def visit_object_type(self, name, info, base, members, variants):
+        doc = self.cur_doc
+        if base and base.is_implicit():
+            base = None
+        if self.out:
+            self.out += '\n'
+        self.out += TYPE_FMT(type='Object',
+                             name=doc.symbol,
+                             body=texi_entity(doc, 'Members', base, variants))
+
+    def visit_alternate_type(self, name, info, variants):
+        doc = self.cur_doc
+        if self.out:
+            self.out += '\n'
+        self.out += TYPE_FMT(type='Alternate',
+                             name=doc.symbol,
+                             body=texi_entity(doc, 'Members'))
+
+    def visit_command(self, name, info, arg_type, ret_type,
+                      gen, success_response, boxed):
+        doc = self.cur_doc
+        if self.out:
+            self.out += '\n'
+        if boxed:
+            body = texi_body(doc)
+            body += '\n@b{Arguments:} the members of @code{%s}' % arg_type.name
+            body += texi_sections(doc)
+        else:
+            body = texi_entity(doc, 'Arguments')
+        self.out += MSG_FMT(type='Command',
+                            name=doc.symbol,
+                            body=body)
+
+    def visit_event(self, name, info, arg_type, boxed):
+        doc = self.cur_doc
+        if self.out:
+            self.out += '\n'
+        self.out += MSG_FMT(type='Event',
+                            name=doc.symbol,
+                            body=texi_entity(doc, 'Arguments'))
+
+    def symbol(self, doc, entity):
+        self.cur_doc = doc
+        entity.visit(self)
+        self.cur_doc = None
+
+    def freeform(self, doc):
+        assert not doc.args
+        if self.out:
+            self.out += '\n'
+        self.out += texi_body(doc) + texi_sections(doc)
 
 
-def texi_enum(expr, doc):
+def texi_schema(schema):
-    """Format an enum to texi"""
+    """Convert QAPI schema documentation to Texinfo"""
-    for i in expr['data']:
+    gen = QAPISchemaGenDocVisitor()
-        if i not in doc.args:
+    gen.visit_begin(schema)
-            doc.args[i] = ''
+    for doc in schema.docs:
-    body = texi_body(doc)
+        if doc.symbol:
-    return ENUM_FMT(name=doc.symbol,
+            gen.symbol(doc, schema.lookup_entity(doc.symbol))
-                    body=body)
+        else:
-
+            gen.freeform(doc)
-
+    return gen.out
-def texi_struct(expr, doc):
-    """Format a struct to texi"""
-    body = texi_body(doc)
-    return STRUCT_FMT(type="Struct",
-                      name=doc.symbol,
-                      body=body)
-
-
-def texi_command(expr, doc):
-    """Format a command to texi"""
-    body = texi_body(doc)
-    return COMMAND_FMT(type="Command",
-                       name=doc.symbol,
-                       body=body)
-
-
-def texi_event(expr, doc):
-    """Format an event to texi"""
-    body = texi_body(doc)
-    return COMMAND_FMT(type="Event",
-                       name=doc.symbol,
-                       body=body)
-
-
-def texi_expr(expr, doc):
-    """Format an expr to texi"""
-    (kind, _) = expr.items()[0]
-
-    fmt = {"command": texi_command,
-           "struct": texi_struct,
-           "enum": texi_enum,
-           "union": texi_union,
-           "alternate": texi_alternate,
-           "event": texi_event}[kind]
-
-    return fmt(expr, doc)
-
-
-def texi(docs):
-    """Convert QAPI schema expressions to texi documentation"""
-    res = []
-    for doc in docs:
-        expr = doc.expr
-        if not expr:
-            res.append(texi_body(doc))
-            continue
-        try:
-            doc = texi_expr(expr, doc)
-            res.append(doc)
-        except:
-            print >>sys.stderr, "error at @%s" % doc.info
-            raise
-
-    return '\n'.join(res)
 
 
 def main(argv):
@@ -262,8 +289,11 @@ def main(argv):
         sys.exit(1)
 
     schema = qapi.QAPISchema(argv[1])
-    print texi(schema.docs)
+    if not qapi.doc_required:
+        print >>sys.stderr, ("%s: need pragma 'doc-required' "
+                             "to generate documentation" % argv[0])
+    print texi_schema(schema)
 
 
-if __name__ == "__main__":
+if __name__ == '__main__':
     main(sys.argv)

scripts/qmp/qmp-shell

@@ -166,8 +166,8 @@ class QMPShell(qmp.QEMUMonitorProtocol):
 
     def __cli_expr(self, tokens, parent):
         for arg in tokens:
-            (key, _, val) = arg.partition('=')
+            (key, sep, val) = arg.partition('=')
-            if not val:
+            if sep != '=':
                 raise QMPShellError("Expected a key=value pair, got '%s'" % arg)
 
             value = self.__parse_value(val)

tests/Makefile.include

@@ -367,8 +367,12 @@ qapi-schema += base-cycle-direct.json
 qapi-schema += base-cycle-indirect.json
 qapi-schema += command-int.json
 qapi-schema += comments.json
-qapi-schema += doc-bad-args.json
+qapi-schema += doc-bad-alternate-member.json
+qapi-schema += doc-bad-command-arg.json
 qapi-schema += doc-bad-symbol.json
+qapi-schema += doc-bad-union-member.json
+qapi-schema += doc-before-include.json
+qapi-schema += doc-before-pragma.json
 qapi-schema += doc-duplicated-arg.json
 qapi-schema += doc-duplicated-return.json
 qapi-schema += doc-duplicated-since.json
@@ -381,10 +385,11 @@ qapi-schema += doc-invalid-end2.json
 qapi-schema += doc-invalid-return.json
 qapi-schema += doc-invalid-section.json
 qapi-schema += doc-invalid-start.json
+qapi-schema += doc-missing.json
 qapi-schema += doc-missing-colon.json
 qapi-schema += doc-missing-expr.json
 qapi-schema += doc-missing-space.json
-qapi-schema += doc-optional.json
+qapi-schema += doc-no-symbol.json
 qapi-schema += double-data.json
 qapi-schema += double-type.json
 qapi-schema += duplicate-key.json
@@ -422,6 +427,7 @@ qapi-schema += funny-char.json
 qapi-schema += ident-with-escape.json
 qapi-schema += include-before-err.json
 qapi-schema += include-cycle.json
+qapi-schema += include-extra-junk.json
 qapi-schema += include-format-err.json
 qapi-schema += include-nested-err.json
 qapi-schema += include-no-file.json
@@ -439,6 +445,11 @@ qapi-schema += missing-comma-object.json
 qapi-schema += missing-type.json
 qapi-schema += nested-struct-data.json
 qapi-schema += non-objects.json
+qapi-schema += pragma-doc-required-crap.json
+qapi-schema += pragma-extra-junk.json
+qapi-schema += pragma-name-case-whitelist-crap.json
+qapi-schema += pragma-non-dict.json
+qapi-schema += pragma-returns-whitelist-crap.json
 qapi-schema += qapi-schema-test.json
 qapi-schema += quoted-structural-chars.json
 qapi-schema += redefined-builtin.json
@@ -469,6 +480,7 @@ qapi-schema += unclosed-list.json
 qapi-schema += unclosed-object.json
 qapi-schema += unclosed-string.json
 qapi-schema += unicode-str.json
+qapi-schema += union-base-empty.json
 qapi-schema += union-base-no-discriminator.json
 qapi-schema += union-branch-case.json
 qapi-schema += union-clash-branches.json

tests/qapi-schema/alternate-any.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-any.json:6: Alternate 'Alt' member 'one' cannot use type 'any'
+tests/qapi-schema/alternate-any.json:2: Alternate 'Alt' member 'one' cannot use type 'any'

tests/qapi-schema/alternate-any.json

@@ -1,8 +1,4 @@
 # we do not allow the 'any' type as an alternate branch
-
-##
-# @Alt:
-##
 { 'alternate': 'Alt',
   'data': { 'one': 'any',
             'two': 'int' } }

tests/qapi-schema/alternate-array.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-array.json:12: Member 'two' of alternate 'Alt' cannot be an array
+tests/qapi-schema/alternate-array.json:5: Member 'two' of alternate 'Alt' cannot be an array

tests/qapi-schema/alternate-array.json

@@ -1,14 +1,7 @@
 # we do not allow array branches in alternates
-
-##
-# @One:
-##
 # TODO: should we support this?
 { 'struct': 'One',
   'data': { 'name': 'str' } }
-##
-# @Alt:
-##
 { 'alternate': 'Alt',
   'data': { 'one': 'One',
             'two': [ 'int' ] } }

tests/qapi-schema/alternate-base.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-base.json:11: Unknown key 'base' in alternate 'Alt'
+tests/qapi-schema/alternate-base.json:4: Unknown key 'base' in alternate 'Alt'

tests/qapi-schema/alternate-base.json

@@ -1,13 +1,6 @@
 # we reject alternate with base type
-
-##
-# @Base:
-##
 { 'struct': 'Base',
   'data': { 'string': 'str' } }
-##
-# @Alt:
-##
 { 'alternate': 'Alt',
   'base': 'Base',
   'data': { 'number': 'int' } }

tests/qapi-schema/alternate-clash.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-clash.json:11: 'a_b' (branch of Alt1) collides with 'a-b' (branch of Alt1)
+tests/qapi-schema/alternate-clash.json:7: 'a_b' (branch of Alt1) collides with 'a-b' (branch of Alt1)

tests/qapi-schema/alternate-clash.json

@@ -4,9 +4,5 @@
 # TODO: In the future, if alternates are simplified to not generate
 # the implicit Alt1Kind enum, we would still have a collision with the
 # resulting C union trying to have two members named 'a_b'.
-
-##
-# @Alt1:
-##
 { 'alternate': 'Alt1',
   'data': { 'a-b': 'str', 'a_b': 'int' } }

tests/qapi-schema/alternate-conflict-dict.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-conflict-dict.json:16: Alternate 'Alt' member 'two' can't be distinguished from member 'one'
+tests/qapi-schema/alternate-conflict-dict.json:6: Alternate 'Alt' member 'two' can't be distinguished from member 'one'

tests/qapi-schema/alternate-conflict-dict.json

@@ -1,18 +1,8 @@
 # we reject alternates with multiple object branches
-
-##
-# @One:
-##
 { 'struct': 'One',
   'data': { 'name': 'str' } }
-##
-# @Two:
-##
 { 'struct': 'Two',
   'data': { 'value': 'int' } }
-##
-# @Alt:
-##
 { 'alternate': 'Alt',
   'data': { 'one': 'One',
             'two': 'Two' } }

tests/qapi-schema/alternate-conflict-string.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-conflict-string.json:11: Alternate 'Alt' member 'two' can't be distinguished from member 'one'
+tests/qapi-schema/alternate-conflict-string.json:4: Alternate 'Alt' member 'two' can't be distinguished from member 'one'

tests/qapi-schema/alternate-conflict-string.json

@@ -1,13 +1,6 @@
 # we reject alternates with multiple string-like branches
-
-##
-# @Enum:
-##
 { 'enum': 'Enum',
   'data': [ 'hello', 'world' ] }
-##
-# @Alt:
-##
 { 'alternate': 'Alt',
   'data': { 'one': 'str',
             'two': 'Enum' } }

tests/qapi-schema/alternate-empty.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-empty.json:6: Alternate 'Alt' should have at least two branches in 'data'
+tests/qapi-schema/alternate-empty.json:2: Alternate 'Alt' should have at least two branches in 'data'

tests/qapi-schema/alternate-empty.json

@@ -1,6 +1,2 @@
 # alternates must list at least two types to be useful
-
-##
-# @Alt:
-##
 { 'alternate': 'Alt', 'data': { 'i': 'int' } }

tests/qapi-schema/alternate-nested.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-nested.json:11: Member 'nested' of alternate 'Alt2' cannot use alternate type 'Alt1'
+tests/qapi-schema/alternate-nested.json:4: Member 'nested' of alternate 'Alt2' cannot use alternate type 'Alt1'

tests/qapi-schema/alternate-nested.json

@@ -1,12 +1,5 @@
 # we reject a nested alternate branch
-
-##
-# @Alt1:
-##
 { 'alternate': 'Alt1',
   'data': { 'name': 'str', 'value': 'int' } }
-##
-# @Alt2:
-##
 { 'alternate': 'Alt2',
   'data': { 'nested': 'Alt1', 'b': 'bool' } }

tests/qapi-schema/alternate-unknown.err

@@ -1 +1 @@
-tests/qapi-schema/alternate-unknown.json:6: Member 'unknown' of alternate 'Alt' uses unknown type 'MissingType'
+tests/qapi-schema/alternate-unknown.json:2: Member 'unknown' of alternate 'Alt' uses unknown type 'MissingType'

tests/qapi-schema/alternate-unknown.json

@@ -1,7 +1,3 @@
 # we reject an alternate with unknown type in branch
-
-##
-# @Alt:
-##
 { 'alternate': 'Alt',
   'data': { 'unknown': 'MissingType', 'i': 'int' } }

tests/qapi-schema/args-alternate.err

@@ -1 +1 @@
-tests/qapi-schema/args-alternate.json:11: 'data' for command 'oops' cannot use alternate type 'Alt'
+tests/qapi-schema/args-alternate.json:3: 'data' for command 'oops' cannot use alternate type 'Alt'

tests/qapi-schema/args-alternate.json

@@ -1,11 +1,3 @@
 # we do not allow alternate arguments
-
-##
-# @Alt:
-##
 { 'alternate': 'Alt', 'data': { 'case1': 'int', 'case2': 'str' } }
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': 'Alt' }

tests/qapi-schema/args-any.err

@@ -1 +1 @@
-tests/qapi-schema/args-any.json:6: 'data' for command 'oops' cannot use built-in type 'any'
+tests/qapi-schema/args-any.json:2: 'data' for command 'oops' cannot use built-in type 'any'

tests/qapi-schema/args-any.json

@@ -1,6 +1,2 @@
 # we do not allow an 'any' argument
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': 'any' }

tests/qapi-schema/args-array-empty.err

@@ -1 +1 @@
-tests/qapi-schema/args-array-empty.json:6: Member 'empty' of 'data' for command 'oops': array type must contain single type name
+tests/qapi-schema/args-array-empty.json:2: Member 'empty' of 'data' for command 'oops': array type must contain single type name

tests/qapi-schema/args-array-empty.json

@@ -1,6 +1,2 @@
 # we reject an array for data if it does not contain a known type
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': { 'empty': [ ] } }

tests/qapi-schema/args-array-unknown.err

@@ -1 +1 @@
-tests/qapi-schema/args-array-unknown.json:6: Member 'array' of 'data' for command 'oops' uses unknown type 'NoSuchType'
+tests/qapi-schema/args-array-unknown.json:2: Member 'array' of 'data' for command 'oops' uses unknown type 'NoSuchType'

tests/qapi-schema/args-array-unknown.json

@@ -1,6 +1,2 @@
 # we reject an array for data if it does not contain a known type
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': { 'array': [ 'NoSuchType' ] } }

tests/qapi-schema/args-bad-boxed.err

@@ -1 +1 @@
-tests/qapi-schema/args-bad-boxed.json:6: 'boxed' of command 'foo' should only use true value
+tests/qapi-schema/args-bad-boxed.json:2: 'boxed' of command 'foo' should only use true value

tests/qapi-schema/args-bad-boxed.json

@@ -1,6 +1,2 @@
 # 'boxed' should only appear with value true
-
-##
-# @foo:
-##
 { 'command': 'foo', 'boxed': false }

tests/qapi-schema/args-boxed-anon.err

@@ -1 +1 @@
-tests/qapi-schema/args-boxed-anon.json:6: 'data' for command 'foo' should be a type name
+tests/qapi-schema/args-boxed-anon.json:2: 'data' for command 'foo' should be a type name

tests/qapi-schema/args-boxed-anon.json

@@ -1,6 +1,2 @@
 # 'boxed' can only be used with named types
-
-##
-# @foo:
-##
 { 'command': 'foo', 'boxed': true, 'data': { 'string': 'str' } }

tests/qapi-schema/args-boxed-empty.err

@@ -1 +1 @@
-tests/qapi-schema/args-boxed-empty.json:11: Cannot use 'boxed' with empty type
+tests/qapi-schema/args-boxed-empty.json:3: Cannot use 'boxed' with empty type

tests/qapi-schema/args-boxed-empty.json

@@ -1,11 +1,3 @@
 # 'boxed' requires a non-empty type
-
-##
-# @Empty:
-##
 { 'struct': 'Empty', 'data': {} }
-
-##
-# @foo:
-##
 { 'command': 'foo', 'boxed': true, 'data': 'Empty' }

tests/qapi-schema/args-boxed-string.err

@@ -1 +1 @@
-tests/qapi-schema/args-boxed-string.json:6: 'data' for command 'foo' cannot use built-in type 'str'
+tests/qapi-schema/args-boxed-string.json:2: 'data' for command 'foo' cannot use built-in type 'str'

tests/qapi-schema/args-boxed-string.json

@@ -1,6 +1,2 @@
 # 'boxed' requires a complex (not built-in) type
-
-##
-# @foo:
-##
 { 'command': 'foo', 'boxed': true, 'data': 'str' }

tests/qapi-schema/args-int.err

@@ -1 +1 @@
-tests/qapi-schema/args-int.json:6: 'data' for command 'oops' cannot use built-in type 'int'
+tests/qapi-schema/args-int.json:2: 'data' for command 'oops' cannot use built-in type 'int'

tests/qapi-schema/args-int.json

@@ -1,6 +1,2 @@
 # we reject commands where data is not an array or complex type
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': 'int' }

tests/qapi-schema/args-invalid.err

@@ -1 +1 @@
-tests/qapi-schema/args-invalid.json:4: 'data' for command 'foo' should be a dictionary or type name
+tests/qapi-schema/args-invalid.json:1: 'data' for command 'foo' should be a dictionary or type name

tests/qapi-schema/args-invalid.json

@@ -1,5 +1,2 @@
-##
-# @foo:
-##
 { 'command': 'foo',
   'data': false }

tests/qapi-schema/args-member-array-bad.err

@@ -1 +1 @@
-tests/qapi-schema/args-member-array-bad.json:6: Member 'member' of 'data' for command 'oops': array type must contain single type name
+tests/qapi-schema/args-member-array-bad.json:2: Member 'member' of 'data' for command 'oops': array type must contain single type name

tests/qapi-schema/args-member-array-bad.json

@@ -1,6 +1,2 @@
 # we reject data if it does not contain a valid array type
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': { 'member': [ { 'nested': 'str' } ] } }

tests/qapi-schema/args-member-case.err

@@ -1 +1 @@
-tests/qapi-schema/args-member-case.json:6: 'Arg' (parameter of no-way-this-will-get-whitelisted) should not use uppercase
+tests/qapi-schema/args-member-case.json:2: 'Arg' (parameter of no-way-this-will-get-whitelisted) should not use uppercase

tests/qapi-schema/args-member-case.json

@@ -1,6 +1,2 @@
 # Member names should be 'lower-case' unless the struct/command is whitelisted
-
-##
-# @no-way-this-will-get-whitelisted:
-##
 { 'command': 'no-way-this-will-get-whitelisted', 'data': { 'Arg': 'int' } }

tests/qapi-schema/args-member-unknown.err

@@ -1 +1 @@
-tests/qapi-schema/args-member-unknown.json:6: Member 'member' of 'data' for command 'oops' uses unknown type 'NoSuchType'
+tests/qapi-schema/args-member-unknown.json:2: Member 'member' of 'data' for command 'oops' uses unknown type 'NoSuchType'

tests/qapi-schema/args-member-unknown.json

@@ -1,6 +1,2 @@
 # we reject data if it does not contain a known type
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': { 'member': 'NoSuchType' } }

tests/qapi-schema/args-name-clash.err

@@ -1 +1 @@
-tests/qapi-schema/args-name-clash.json:8: 'a_b' (parameter of oops) collides with 'a-b' (parameter of oops)
+tests/qapi-schema/args-name-clash.json:4: 'a_b' (parameter of oops) collides with 'a-b' (parameter of oops)

tests/qapi-schema/args-name-clash.json

@@ -1,8 +1,4 @@
 # C member name collision
 # Reject members that clash when mapped to C names (we would have two 'a_b'
 # members).
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': { 'a-b': 'str', 'a_b': 'str' } }

tests/qapi-schema/args-union.err

@@ -1 +1 @@
-tests/qapi-schema/args-union.json:10: 'data' for command 'oops' cannot use union type 'Uni'
+tests/qapi-schema/args-union.json:3: 'data' for command 'oops' cannot use union type 'Uni'

tests/qapi-schema/args-union.json

@@ -1,10 +1,3 @@
 # use of union arguments requires 'boxed':true
-
-##
-# @Uni:
-##
 { 'union': 'Uni', 'data': { 'case1': 'int', 'case2': 'str' } }
-##
-# oops:
-##
 { 'command': 'oops', 'data': 'Uni' }

tests/qapi-schema/args-unknown.err

@@ -1 +1 @@
-tests/qapi-schema/args-unknown.json:6: 'data' for command 'oops' uses unknown type 'NoSuchType'
+tests/qapi-schema/args-unknown.json:2: 'data' for command 'oops' uses unknown type 'NoSuchType'

tests/qapi-schema/args-unknown.json

@@ -1,6 +1,2 @@
 # we reject data if it does not contain a known type
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': 'NoSuchType' }

tests/qapi-schema/bad-base.err

@@ -1 +1 @@
-tests/qapi-schema/bad-base.json:10: 'base' for struct 'MyType' cannot use union type 'Union'
+tests/qapi-schema/bad-base.json:3: 'base' for struct 'MyType' cannot use union type 'Union'

tests/qapi-schema/bad-base.json

@@ -1,10 +1,3 @@
 # we reject a base that is not a struct
-
-##
-# @Union:
-##
 { 'union': 'Union', 'data': { 'a': 'int', 'b': 'str' } }
-##
-# @MyType:
-##
 { 'struct': 'MyType', 'base': 'Union', 'data': { 'c': 'int' } }

tests/qapi-schema/bad-data.err

@@ -1 +1 @@
-tests/qapi-schema/bad-data.json:6: 'data' for command 'oops' cannot be an array
+tests/qapi-schema/bad-data.json:2: 'data' for command 'oops' cannot be an array

tests/qapi-schema/bad-data.json

@@ -1,6 +1,2 @@
 # we ensure 'data' is a dictionary for all but enums
-
-##
-# @oops:
-##
 { 'command': 'oops', 'data': [ ] }

tests/qapi-schema/bad-ident.err

@@ -1 +1 @@
-tests/qapi-schema/bad-ident.json:6: 'struct' does not allow optional name '*oops'
+tests/qapi-schema/bad-ident.json:2: 'struct' does not allow optional name '*oops'

tests/qapi-schema/bad-ident.json

@@ -1,6 +1,2 @@
 # we reject creating a type name with bad name
-
-##
-# @*oops:
-##
 { 'struct': '*oops', 'data': { 'i': 'int' } }

tests/qapi-schema/bad-type-bool.err

@@ -1 +1 @@
-tests/qapi-schema/bad-type-bool.json:6: 'struct' key must have a string value
+tests/qapi-schema/bad-type-bool.json:2: 'struct' key must have a string value

tests/qapi-schema/bad-type-bool.json

@@ -1,6 +1,2 @@
 # we reject an expression with a metatype that is not a string
-
-##
-# @true:
-##
 { 'struct': true, 'data': { } }

tests/qapi-schema/bad-type-dict.err

@@ -1 +1 @@
-tests/qapi-schema/bad-type-dict.json:6: 'command' key must have a string value
+tests/qapi-schema/bad-type-dict.json:2: 'command' key must have a string value

tests/qapi-schema/bad-type-dict.json

@@ -1,6 +1,2 @@
 # we reject an expression with a metatype that is not a string
-
-##
-# @foo:
-##
 { 'command': { } }

tests/qapi-schema/base-cycle-direct.err

@@ -1 +1 @@
-tests/qapi-schema/base-cycle-direct.json:6: Object Loopy contains itself
+tests/qapi-schema/base-cycle-direct.json:2: Object Loopy contains itself

tests/qapi-schema/base-cycle-direct.json

@@ -1,6 +1,2 @@
 # we reject a loop in base classes
-
-##
-# @Loopy:
-##
 { 'struct': 'Loopy', 'base': 'Loopy', 'data': {} }

tests/qapi-schema/base-cycle-indirect.err

@@ -1 +1 @@
-tests/qapi-schema/base-cycle-indirect.json:6: Object Base1 contains itself
+tests/qapi-schema/base-cycle-indirect.json:2: Object Base1 contains itself

tests/qapi-schema/base-cycle-indirect.json

@@ -1,10 +1,3 @@
 # we reject a loop in base classes
-
-##
-# @Base1:
-##
 { 'struct': 'Base1', 'base': 'Base2', 'data': {} }
-##
-# @Base2:
-##
 { 'struct': 'Base2', 'base': 'Base1', 'data': {} }

tests/qapi-schema/command-int.err

@@ -1 +1 @@
-tests/qapi-schema/command-int.json:6: built-in 'int' is already defined
+tests/qapi-schema/command-int.json:2: built-in 'int' is already defined

tests/qapi-schema/command-int.json

@@ -1,6 +1,2 @@
 # we reject collisions between commands and types
-
-##
-# @int:
-##
 { 'command': 'int', 'data': { 'character': 'str' } }

tests/qapi-schema/comments.json

@@ -1,8 +1,4 @@
 # Unindented comment
-
-##
-# @Status:
-##
 { 'enum': 'Status',             # Comment to the right of code
   # Indented comment
   'data': [ 'good', 'bad', 'ugly' ] }

tests/qapi-schema/comments.out

@@ -2,4 +2,3 @@ enum QType ['none', 'qnull', 'qint', 'qstring', 'qdict', 'qlist', 'qfloat', 'qbo
     prefix QTYPE
 enum Status ['good', 'bad', 'ugly']
 object q_empty
-doc symbol=Status expr=('enum', 'Status')

tests/qapi-schema/doc-bad-alternate-member.err

@@ -0,0 +1 @@
+tests/qapi-schema/doc-bad-alternate-member.json:3: The following documented members are not in the declaration: aa, bb

tests/qapi-schema/doc-bad-alternate-member.json

@@ -0,0 +1,9 @@
+# Arguments listed in the doc comment must exist in the actual schema
+
+##
+# @AorB:
+# @aa: a
+# @bb: b
+##
+{ 'alternate': 'AorB',
+  'data': { 'a': 'str', 'b': 'int' } }

tests/qapi-schema/doc-bad-args.err

@@ -1 +0,0 @@
-tests/qapi-schema/doc-bad-args.json:3: The following documented members are not in the declaration: b

tests/qapi-schema/doc-bad-command-arg.err

@@ -0,0 +1 @@
+tests/qapi-schema/doc-bad-command-arg.json:3: The following documented members are not in the declaration: b