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
clarity.

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
+allowed.
+
+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).
+Differences:
+
+* 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
-- 
2.21.0



  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:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* 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 \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* 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:
	nntp://nntp.lore.kernel.org/org.nongnu.qemu-devel


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