From patchwork Tue Sep 10 06:37:22 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 11138773 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id AF17614DB for ; Tue, 10 Sep 2019 06:44:48 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 809FE20872 for ; Tue, 10 Sep 2019 06:44:48 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 809FE20872 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Received: from localhost ([::1]:34264 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i7ZtP-0004IR-AT for patchwork-qemu-devel@patchwork.kernel.org; Tue, 10 Sep 2019 02:44:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:38609) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i7ZmP-0004kM-Ba for qemu-devel@nongnu.org; Tue, 10 Sep 2019 02:37:35 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i7ZmN-0007ij-BE for qemu-devel@nongnu.org; Tue, 10 Sep 2019 02:37:33 -0400 Received: from mx1.redhat.com ([209.132.183.28]:52390) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1i7ZmM-0007hj-TS for qemu-devel@nongnu.org; Tue, 10 Sep 2019 02:37:31 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 316BB10C0935; Tue, 10 Sep 2019 06:37:30 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-117-142.ams2.redhat.com [10.36.117.142]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C68835D6B2; Tue, 10 Sep 2019 06:37:29 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 4F2D11165605; Tue, 10 Sep 2019 08:37:24 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Date: Tue, 10 Sep 2019 08:37:22 +0200 Message-Id: <20190910063724.28470-15-armbru@redhat.com> In-Reply-To: <20190910063724.28470-1-armbru@redhat.com> References: <20190910063724.28470-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.6.2 (mx1.redhat.com [10.5.110.66]); Tue, 10 Sep 2019 06:37:30 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: marcandre.lureau@redhat.com, mdroth@linux.vnet.ibm.com Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" The introduction to the QAPI schema is somewhat rambling. Rewrite for clarity. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake --- docs/devel/qapi-code-gen.txt | 106 ++++++++++++++++------------------- 1 file changed, 47 insertions(+), 59 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index d09232009e..54a324cc69 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -16,65 +16,53 @@ 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 ASCII. All control characters must be + escaped, even DEL. + +* Numbers are not supported. + +A QAPI schema consists of a series of top-level expressions (JSON +objects). Their order does 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