Commit 3c2758c2 authored by Peter Maydell's avatar Peter Maydell
Browse files

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: default avatarPeter Maydell <peter.maydell@linaro.org>
parents 3716fba3 012b126d

.gitignore

+5 −5
Original line number Diff line number Diff line
@@ -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/qemu-qmp-ref.info*

/qemu-ga-qapi.texi

/qemu-qapi.texi

/version.texi

/docs/version.texi

*.tps

.stgit-*

cscope.*

Makefile

+15 −12
Original line number Diff line number Diff line
@@ -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

	$(call quiet-command,texi2pdf $(TEXIFLAG) -I $(SRC_PATH) -I . $< -o $@,"GEN","$@")

%.pdf: %.texi

	$(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

+50 −30
Original line number Diff line number Diff line
@@ -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',

often with their default value; and extensions added after the

expression was first released are also given a '(since x.y.z)'

comment.

Extensions added after the expression was first released carry 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:

'include', 'command', 'struct', 'enum', 'union', 'alternate', and

'event'.  There are several groups of types: simple types (a number of

built-in types, such as 'int' and 'str'; as well as enumerations),

complex types (structs and two flavors of unions), and alternate types

(a choice between other types).  The 'command' and 'event' expressions

can refer to existing types by name, or list an anonymous type as a

dictionary. Listing a type name inside an array refers to a

single-dimension array of that type; multi-dimension arrays are not

directly supported (although an array of a complex struct that

contains an array member is possible).

There are eight top-level expressions recognized by the parser:

'include', 'pragma', 'command', 'struct', 'enum', 'union',

'alternate', and 'event'.  There are several groups of types: simple

types (a number of built-in types, such as 'int' and 'str'; as well as

enumerations), complex types (structs and two flavors of unions), and

alternate types (a choice between other types).  The 'command' and

'event' expressions can refer to existing types by name, or list an

anonymous type as a dictionary. Listing a type name inside an array

refers to a single-dimension array of that type; multi-dimension

arrays are not directly supported (although an array of a complex

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

one exception noted below when 'gen' is used.

anonymous type with the same semantics as a 'struct' expression.



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,

with one exception noted below when 'gen' is used.  Although it is

permitted to have the 'returns' member name a built-in type or an

array of built-in types, any command that does this cannot be extended

to return additional information in the future; thus, new commands

should strongly consider returning a dictionary-based type or an array

of dictionaries, even if the dictionary only contains one member at the

present.

one-element array containing the name of a complex or built-in type.

To return anything else, you have to list the command in pragma

'returns-whitelist'.  If you do this, the command cannot be extended

to return additional information in the future.  Use of

'returns-whitelist' for new commands is strongly discouraged.



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

+1 −1
Original line number Diff line number Diff line
@@ -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

+2 −2
Original line number Diff line number Diff line
@@ -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

##