QEMU-Devel Archive on lore.kernel.org
 help / color / Atom feed
From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: marcandre.lureau@redhat.com, mdroth@linux.vnet.ibm.com
Subject: [Qemu-devel] [PATCH v3 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema
Date: Fri, 13 Sep 2019 22:13:47 +0200
Message-ID: <20190913201349.24332-15-armbru@redhat.com> (raw)
In-Reply-To: <20190913201349.24332-1-armbru@redhat.com>

The introduction to the QAPI schema is somewhat rambling.  Rewrite for

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
 docs/devel/qapi-code-gen.txt | 107 ++++++++++++++++-------------------
 1 file changed, 48 insertions(+), 59 deletions(-)

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 2406e1bdbc..e75d680f6e 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -16,65 +16,54 @@ well as the QEMU Guest Agent (QGA) for communicating with the guest.
 The remainder of this document uses "Client JSON Protocol" when
 referring to the wire contents of a QMP or QGA connection.
-To map Client JSON Protocol interfaces to the native C QAPI
-implementations, a JSON-based schema is used to define types and
-function signatures, and a set of scripts is used to generate types,
-signatures, and marshaling/dispatch code. This document will describe
-how the schemas, scripts, and resulting code are used.
-== QMP/Guest agent schema ==
-A QAPI schema file is designed to be loosely based on JSON
-(http://www.ietf.org/rfc/rfc8259.txt) with changes for quoting style
-and the use of comments; a QAPI schema file is then parsed by a python
-code generation program.  A valid QAPI schema consists of a series of
-top-level expressions, with no commas between them.  Where
-dictionaries (JSON objects) are used, they are parsed as python
-OrderedDicts so that ordering is preserved (for predictable layout of
-generated C structs and parameter lists).  Ordering doesn't matter
-between top-level expressions or the keys within an expression, but
-does matter within dictionary values for 'data' and 'returns' members
-of a single expression.  QAPI schema input is written using 'single
-quotes' instead of JSON's "double quotes" (in contrast, Client JSON
-Protocol uses no comments, and while input accepts 'single quotes' as
-an extension, output is strict JSON using only "double quotes").  As
-in JSON, trailing commas are not permitted in arrays or dictionaries.
-Input must be ASCII (although QMP supports full Unicode strings, the
-QAPI parser does not).  At present, there is no place where a QAPI
-schema requires the use of JSON numbers or null.
-=== Comments ===
-Comments are allowed; anything between an unquoted # and the following
-newline is ignored.
-=== Schema overview ===
-The schema sets up a series of types, as well as commands and events
-that will use those types.  Forward references are allowed: the parser
-scans in two passes, where the first pass learns all type names, and
-the second validates the schema and generates the code.  This allows
-the definition of complex structs that can have mutually recursive
-types, and allows for indefinite nesting of Client JSON Protocol that
-satisfies the schema.  A type name should not be defined more than
-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 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).
+To map between Client JSON Protocol interfaces and the native C API,
+we generate C code from a QAPI schema.  This document describes the
+QAPI schema language, and how it gets mapped to the Client JSON
+Protocol and to C.  It additionally provides guidance on maintaining
+Client JSON Protocol compatibility.
+== The QAPI schema language ==
+The QAPI schema defines the Client JSON Protocol's commands and
+events, as well as types used by them.  Forward references are
+It is permissible for the schema to contain additional types not used
+by any commands or events, for the side effect of generated C code
+used internally.
+There are several kinds of types: simple types (a number of built-in
+types, such as 'int' and 'str'; as well as enumerations), arrays,
+complex types (structs and two flavors of unions), and alternate types
+(a choice between other types).
+=== Schema syntax ===
+Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt).
+* Comments: start with a hash character (#) that is not part of a
+  string, and extend to the end of the line.
+* Strings are enclosed in 'single quotes', not "double quotes".
+* Strings are restricted to printable ASCII, and escape sequences to
+  just '\\'.
+* Numbers are not supported.
+A QAPI schema consists of a series of top-level expressions (JSON
+objects).  Code and documentation is generated in schema definition
+order.  Code order should not matter.
+The order of keys within JSON objects does not matter unless
+explicitly noted.
+There are eight kinds of top-level expressions: 'include', 'pragma',
+'command', 'struct', 'enum', 'union', 'alternate', and 'event'.  These
+are discussed in detail below.
 In the rest of this document, usage lines are given for each
 expression type, with literal strings written in lower case and

  parent reply index

Thread overview: 25+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-13 20:13 [Qemu-devel] [PATCH v3 00/16] qapi: Schema language cleanups & doc improvements Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 01/16] scripts/git.orderfile: Match QAPI schema more precisely Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 02/16] qapi: Drop check_type()'s redundant parameter @allow_optional Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 03/16] qapi: Drop support for boxed alternate arguments Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 04/16] docs/devel/qapi-code-gen: Minor specification fixes Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 05/16] tests/qapi-schema: Demonstrate bad reporting of funny characters Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 06/16] qapi: Restrict strings to printable ASCII Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 07/16] qapi: Drop support for escape sequences other than \\ Markus Armbruster
2019-09-17 16:18   ` Eric Blake
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 08/16] qapi: Permit 'boxed' with empty type Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 09/16] qapi: Permit alternates with just one branch Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 10/16] qapi: Permit omitting all flat union branches Markus Armbruster
2019-09-17 16:20   ` Eric Blake
2019-09-23 11:46     ` Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 11/16] qapi: Adjust frontend errors to say enum value, not member Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 12/16] docs/devel/qapi-code-gen: Reorder sections for readability Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations Markus Armbruster
2019-09-17 16:22   ` Eric Blake
2019-09-13 20:13 ` Markus Armbruster [this message]
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 15/16] docs/devel/qapi-code-gen: Improve QAPI schema language doc Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 16/16] qapi: Tweak code to match docs/devel/qapi-code-gen.txt Markus Armbruster
2019-09-14  2:49 ` [Qemu-devel] [PATCH v3 00/16] qapi: Schema language cleanups & doc improvements no-reply
2019-09-17 16:31 ` Eric Blake
2019-09-23 11:49   ` Markus Armbruster
2019-09-23 18:29 ` Markus Armbruster

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190913201349.24332-15-armbru@redhat.com \
    --to=armbru@redhat.com \
    --cc=marcandre.lureau@redhat.com \
    --cc=mdroth@linux.vnet.ibm.com \
    --cc=qemu-devel@nongnu.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

QEMU-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/qemu-devel/0 qemu-devel/git/0.git
	git clone --mirror https://lore.kernel.org/qemu-devel/1 qemu-devel/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 qemu-devel qemu-devel/ https://lore.kernel.org/qemu-devel \
		qemu-devel@nongnu.org qemu-devel@archiver.kernel.org
	public-inbox-index qemu-devel

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone https://public-inbox.org/ public-inbox