From nobody Tue Feb 10 03:37:15 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1628173256; cv=none; d=zohomail.com; s=zohoarc; b=PTV00JtIFZteKbZ1PwrK9R9zoEZ5lDj87fZKFVv6umfdHwMX9T219BjGuWQVvUwTzUBD2ImzwsXEsX1BDsDSMhxh7+ZzgZW0+2/zVLyZq/Ac667pFmMfTf5yzV9VLr26z3mnbl2Ym/dQ9lN4dbvTy/ZibzrsRsBySU0AfXgD05k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1628173256; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=qr+5glCU8GfKFnGWHfI0YLXbaxu50IRNw6H96SLd2og=; b=Zf+EtQ1T4dqKZBEGNvLLZW5fzyQw5pkYxQdQviKpqzYozF86Jpc1YdAtjpXZIFjOZ60OBgzrmsCVSIuiwXGbdBkiXc6dUggbWPl+0XBMC9QYj5QFQqMaFsh2ovBo2+t3/6gpoJHxxO8P89osBUMIDXPQPW23Y7U2Uj9p2ngk95M= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1628173256120950.8436723192194; Thu, 5 Aug 2021 07:20:56 -0700 (PDT) Received: from localhost ([::1]:38132 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mBeEw-0000zB-Ot for importer@patchew.org; Thu, 05 Aug 2021 10:20:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50422) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mBe3g-0000Lh-AT for qemu-devel@nongnu.org; Thu, 05 Aug 2021 10:09:16 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:57815) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mBe3a-0007tm-6a for qemu-devel@nongnu.org; Thu, 05 Aug 2021 10:09:16 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-407-qjxz_G6GOTWKZHRAVqk5Sw-1; Thu, 05 Aug 2021 10:09:05 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 502CE87D545; Thu, 5 Aug 2021 14:09:04 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-12.ams2.redhat.com [10.36.112.12]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 8675B10016F5; Thu, 5 Aug 2021 14:09:03 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 246D711380A2; Thu, 5 Aug 2021 16:09:02 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1628172549; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=qr+5glCU8GfKFnGWHfI0YLXbaxu50IRNw6H96SLd2og=; b=bz09AzyZjyGEKgORpnVfNicaY+i4zuWwj/2l8vMUKx0teI4DYzKa0WLRem27Kukm22kgkd Esg4qvAg5xau8mVfdnxWZwGbNjlDD6NVrvGRhDvi+Oh7zBZmlG3UrhGZoiD9B68d7C9FrY VOkvl2PkfnXTWKNVYjpp/62At1SELKE= X-MC-Unique: qjxz_G6GOTWKZHRAVqk5Sw-1 From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 2/5] docs: convert qapi-code-gen.txt to ReST Date: Thu, 5 Aug 2021 16:08:59 +0200 Message-Id: <20210805140902.2110546-3-armbru@redhat.com> In-Reply-To: <20210805140902.2110546-1-armbru@redhat.com> References: <20210805140902.2110546-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.699, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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: peter.maydell@linaro.org, John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1628173258257100001 Content-Type: text/plain; charset="utf-8" From: John Snow This is a very rudimentary conversion from .txt to .rst changing as little as possible, but getting it to render somewhat nicely; without using any Sphinx directives. (It is 'native' ReST.) Further patches will add cross-references and Sphinx-specific extensions to make it sparkle. Signed-off-by: John Snow Message-Id: <20210720235619.2048797-2-jsnow@redhat.com> Reviewed-by: Peter Maydell Signed-off-by: Markus Armbruster --- docs/devel/index.rst | 1 + .../{qapi-code-gen.txt =3D> qapi-code-gen.rst} | 559 ++++++++++-------- 2 files changed, 312 insertions(+), 248 deletions(-) rename docs/devel/{qapi-code-gen.txt =3D> qapi-code-gen.rst} (86%) diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 153979caf4..bfba3a8daa 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -42,3 +42,4 @@ modifying QEMU's source code. multi-process ebpf_rss vfio-migration + qapi-code-gen diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.rst similarity index 86% rename from docs/devel/qapi-code-gen.txt rename to docs/devel/qapi-code-gen.rst index 233022184b..9155dba262 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.rst @@ -1,12 +1,17 @@ -=3D How to use the QAPI code generator =3D +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +How to use the QAPI code generator +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -Copyright IBM Corp. 2011 -Copyright (C) 2012-2016 Red Hat, Inc. +.. + Copyright IBM Corp. 2011 + Copyright (C) 2012-2016 Red Hat, Inc. =20 -This work is licensed under the terms of the GNU GPL, version 2 or -later. See the COPYING file in the top-level directory. + This work is licensed under the terms of the GNU GPL, version 2 or + later. See the COPYING file in the top-level directory. =20 -=3D=3D Introduction =3D=3D + +Introduction +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 QAPI is a native C API within QEMU which provides management-level functionality to internal and external users. For external @@ -23,7 +28,8 @@ Protocol and to C. It additionally provides guidance on = maintaining Client JSON Protocol compatibility. =20 =20 -=3D=3D The QAPI schema language =3D=3D +The QAPI schema language +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The QAPI schema defines the Client JSON Protocol's commands and events, as well as types used by them. Forward references are @@ -39,9 +45,10 @@ complex types (structs and two flavors of unions), and a= lternate types (a choice between other types). =20 =20 -=3D=3D=3D Schema syntax =3D=3D=3D +Schema syntax +------------- =20 -Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt). +Syntax is loosely based on `JSON `_. Differences: =20 * Comments: start with a hash character (#) that is not part of a @@ -79,7 +86,7 @@ syntax in an EBNF-like notation: The order of members within JSON objects does not matter unless explicitly noted. =20 -A QAPI schema consists of a series of top-level expressions: +A QAPI schema consists of a series of top-level expressions:: =20 SCHEMA =3D TOP-LEVEL-EXPR... =20 @@ -87,11 +94,11 @@ The top-level expressions are all JSON objects. Code a= nd documentation is generated in schema definition order. Code order should not matter. =20 -A top-level expressions is either a directive or a definition: +A top-level expressions is either a directive or a definition:: =20 TOP-LEVEL-EXPR =3D DIRECTIVE | DEFINITION =20 -There are two kinds of directives and six kinds of definitions: +There are two kinds of directives and six kinds of definitions:: =20 DIRECTIVE =3D INCLUDE | PRAGMA DEFINITION =3D ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT @@ -99,9 +106,10 @@ There are two kinds of directives and six kinds of defi= nitions: These are discussed in detail below. =20 =20 -=3D=3D=3D Built-in Types =3D=3D=3D +Built-in Types +-------------- =20 -The following types are predefined, and map to C as follows: +The following types are predefined, and map to C as follows:: =20 Schema C JSON str char * any JSON string, UTF-8 @@ -124,12 +132,14 @@ The following types are predefined, and map to C as f= ollows: QType QType JSON string matching enum QType values =20 =20 -=3D=3D=3D Include directives =3D=3D=3D +Include directives +------------------ + +Syntax:: =20 -Syntax: INCLUDE =3D { 'include': STRING } =20 -The QAPI schema definitions can be modularized using the 'include' directi= ve: +The QAPI schema definitions can be modularized using the 'include' directi= ve:: =20 { 'include': 'path/to/file.json' } =20 @@ -144,9 +154,11 @@ an outer file. The parser may be made stricter in the= future to prevent incomplete include files. =20 =20 -=3D=3D=3D Pragma directives =3D=3D=3D +Pragma directives +----------------- + +Syntax:: =20 -Syntax: PRAGMA =3D { 'pragma': { '*doc-required': BOOL, '*command-name-exceptions': [ STRING, ... ], @@ -172,9 +184,11 @@ names may contain uppercase letters, and '_' instead o= f '-'. Default is none. =20 =20 -=3D=3D=3D Enumeration types =3D=3D=3D +Enumeration types +----------------- + +Syntax:: =20 -Syntax: ENUM =3D { 'enum': STRING, 'data': [ ENUM-VALUE, ... ], '*prefix': STRING, @@ -189,7 +203,7 @@ Each member of the 'data' array defines a value of the = enumeration type. The form STRING is shorthand for { 'name': STRING }. The 'name' values must be be distinct. =20 -Example: +Example:: =20 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } =20 @@ -218,9 +232,11 @@ The optional 'features' member specifies features. Se= e "Features" below for more on this. =20 =20 -=3D=3D=3D Type references and array types =3D=3D=3D +Type references and array types +------------------------------- + +Syntax:: =20 -Syntax: TYPE-REF =3D STRING | ARRAY-TYPE ARRAY-TYPE =3D [ STRING ] =20 @@ -230,9 +246,11 @@ A one-element array containing a string denotes an arr= ay of the type named by the string. Example: ['int'] denotes an array of 'int'. =20 =20 -=3D=3D=3D Struct types =3D=3D=3D +Struct types +------------ + +Syntax:: =20 -Syntax: STRUCT =3D { 'struct': STRING, 'data': MEMBERS, '*base': STRING, @@ -254,7 +272,7 @@ struct member name. If '*' is present, the member is o= ptional. The MEMBER's value defines its properties, in particular its type. The form TYPE-REF is shorthand for { 'type': TYPE-REF }. =20 -Example: +Example:: =20 { 'struct': 'MyType', 'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } } @@ -265,7 +283,7 @@ The C struct's members are generated in QAPI schema ord= er. The optional 'base' member names a struct type whose members are to be included in this type. They go first in the C struct. =20 -Example: +Example:: =20 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } @@ -274,7 +292,7 @@ Example: 'data': { '*backing': 'str' } } =20 An example BlockdevOptionsGenericCOWFormat object on the wire could use -both members like this: +both members like this:: =20 { "file": "/some/place/my-image", "backing": "/some/place/my-backing-file" } @@ -286,9 +304,11 @@ The optional 'features' member specifies features. Se= e "Features" below for more on this. =20 =20 -=3D=3D=3D Union types =3D=3D=3D +Union types +----------- + +Syntax:: =20 -Syntax: UNION =3D { 'union': STRING, 'data': BRANCHES, '*if': COND, @@ -317,7 +337,7 @@ The BRANCH's value defines the branch's properties, in = particular its type. The form TYPE-REF is shorthand for { 'type': TYPE-REF }. =20 A simple union type defines a mapping from automatic discriminator -values to data types like in this example: +values to data types like in this example:: =20 { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } } { 'struct': 'BlockdevOptionsQcow2', @@ -330,7 +350,7 @@ values to data types like in this example: In the Client JSON Protocol, a simple union is represented by an object that contains the 'type' member as a discriminator, and a 'data' member that is of the specified data type corresponding to the -discriminator value, as in these examples: +discriminator value, as in these examples:: =20 { "type": "file", "data": { "filename": "/some/place/my-image" } } { "type": "qcow2", "data": { "backing": "/some/place/my-image", @@ -361,7 +381,7 @@ struct. The following example enhances the above simple union example by adding an optional common member 'read-only', renaming the discriminator to something more applicable than the simple union's -default of 'type', and reducing the number of {} required on the wire: +default of 'type', and reducing the number of {} required on the wire:: =20 { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] } { 'union': 'BlockdevOptions', @@ -370,7 +390,7 @@ default of 'type', and reducing the number of {} requir= ed on the wire: 'data': { 'file': 'BlockdevOptionsFile', 'qcow2': 'BlockdevOptionsQcow2' } } =20 -Resulting in these JSON objects: +Resulting in these JSON objects:: =20 { "driver": "file", "read-only": true, "filename": "/some/place/my-image" } @@ -390,11 +410,11 @@ struct. =20 A simple union can always be re-written as a flat union where the base class has a single member named 'type', and where each branch of the -union has a struct with a single member named 'data'. That is, +union has a struct with a single member named 'data'. That is, :: =20 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } } =20 -is identical on the wire to: +is identical on the wire to:: =20 { 'enum': 'Enum', 'data': ['one', 'two'] } { 'struct': 'Branch1', 'data': { 'data': 'str' } } @@ -409,9 +429,11 @@ The optional 'features' member specifies features. Se= e "Features" below for more on this. =20 =20 -=3D=3D=3D Alternate types =3D=3D=3D +Alternate types +--------------- + +Syntax:: =20 -Syntax: ALTERNATE =3D { 'alternate': STRING, 'data': ALTERNATIVES, '*if': COND, @@ -430,7 +452,7 @@ The ALTERNATIVE's STRING name is the branch name. The ALTERNATIVE's value defines the branch's properties, in particular its type. The form STRING is shorthand for { 'type': STRING }. =20 -Example: +Example:: =20 { 'alternate': 'BlockdevRef', 'data': { 'definition': 'BlockdevOptions', @@ -449,7 +471,7 @@ as the 'null' built-in, it accepts JSON null; and if it= is typed as a complex type (struct or union), it accepts a JSON object. =20 The example alternate declaration above allows using both of the -following example objects: +following example objects:: =20 { "file": "my_existing_block_device_id" } { "file": { "driver": "file", @@ -463,9 +485,11 @@ The optional 'features' member specifies features. Se= e "Features" below for more on this. =20 =20 -=3D=3D=3D Commands =3D=3D=3D +Commands +-------- + +Syntax:: =20 -Syntax: COMMAND =3D { 'command': STRING, ( '*data': ( MEMBERS | STRING ), @@ -508,7 +532,7 @@ member is the command name. The value of the "argument= s" member then has to conform to the arguments, and the value of the success response's "return" member will conform to the return type. =20 -Some example commands: +Some example commands:: =20 { 'command': 'my-first-command', 'data': { 'arg1': 'str', '*arg2': 'str' } } @@ -516,7 +540,7 @@ Some example commands: { 'command': 'my-second-command', 'returns': [ 'MyType' ] } =20 -which would validate this Client JSON Protocol transaction: +which would validate this Client JSON Protocol transaction:: =20 =3D> { "execute": "my-first-command", "arguments": { "arg1": "hello" } } @@ -543,7 +567,7 @@ In rare cases, QAPI cannot express a type-safe represen= tation of a corresponding Client JSON Protocol command. You then have to suppress generation of a marshalling function by including a member 'gen' with boolean value false, and instead write your own function. For -example: +example:: =20 { 'command': 'netdev_add', 'data': {'type': 'str', 'id': 'str'}, @@ -561,7 +585,7 @@ the command definition includes the optional member 'su= ccess-response' with boolean value false. So far, only QGA makes use of this member. =20 Member 'allow-oob' declares whether the command supports out-of-band -(OOB) execution. It defaults to false. For example: +(OOB) execution. It defaults to false. For example:: =20 { 'command': 'migrate_recover', 'data': { 'uri': 'str' }, 'allow-oob': true } @@ -594,7 +618,7 @@ other "slow" lock. When in doubt, do not implement OOB execution support. =20 Member 'allow-preconfig' declares whether the command is available -before the machine is built. It defaults to false. For example: +before the machine is built. It defaults to false. For example:: =20 { 'enum': 'QMPCapability', 'data': [ 'oob' ] } @@ -640,9 +664,11 @@ The optional 'features' member specifies features. Se= e "Features" below for more on this. =20 =20 -=3D=3D=3D Events =3D=3D=3D +Events +------ + +Syntax:: =20 -Syntax: EVENT =3D { 'event': STRING, ( '*data': ( MEMBERS | STRING ), @@ -665,16 +691,16 @@ data just like a struct type's 'data' defines struct = type members. If 'data' is a STRING, then STRING names a complex type whose members are the event-specific data. A union type requires 'boxed': true. =20 -An example event is: +An example event is:: =20 -{ 'event': 'EVENT_C', - 'data': { '*a': 'int', 'b': 'str' } } + { 'event': 'EVENT_C', + 'data': { '*a': 'int', 'b': 'str' } } =20 -Resulting in this JSON object: +Resulting in this JSON object:: =20 -{ "event": "EVENT_C", - "data": { "b": "test string" }, - "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } + { "event": "EVENT_C", + "data": { "b": "test string" }, + "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } =20 The generator emits a function to send the event. When member 'boxed' is absent, it takes event-specific data one by one, in QAPI schema @@ -688,9 +714,11 @@ The optional 'features' member specifies features. Se= e "Features" below for more on this. =20 =20 -=3D=3D=3D Features =3D=3D=3D +Features +-------- + +Syntax:: =20 -Syntax: FEATURES =3D [ FEATURE, ... ] FEATURE =3D STRING | { 'name': STRING, '*if': COND } @@ -701,17 +729,17 @@ that previously resulted in an error). QMP clients m= ay still need to know whether the extension is available. =20 For this purpose, a list of features can be specified for a command or -struct type. Each list member can either be { 'name': STRING, '*if': -COND }, or STRING, which is shorthand for { 'name': STRING }. +struct type. Each list member can either be ``{ 'name': STRING, '*if': +COND }``, or STRING, which is shorthand for ``{ 'name': STRING }``. =20 The optional 'if' member specifies a conditional. See "Configuring the schema" below for more on this. =20 -Example: +Example:: =20 -{ 'struct': 'TestType', - 'data': { 'number': 'int' }, - 'features': [ 'allow-negative-numbers' ] } + { 'struct': 'TestType', + 'data': { 'number': 'int' }, + 'features': [ 'allow-negative-numbers' ] } =20 The feature strings are exposed to clients in introspection, as explained in section "Client JSON Protocol introspection". @@ -720,20 +748,22 @@ Intended use is to have each feature string signal th= at this build of QEMU shows a certain behaviour. =20 =20 -=3D=3D=3D=3D Special features =3D=3D=3D=3D +Special features +~~~~~~~~~~~~~~~~ =20 Feature "deprecated" marks a command, event, or struct member as deprecated. It is not supported elsewhere so far. =20 =20 -=3D=3D=3D Naming rules and reserved names =3D=3D=3D +Naming rules and reserved names +------------------------------- =20 All names must begin with a letter, and contain only ASCII letters, digits, hyphen, and underscore. There are two exceptions: enum values may start with a digit, and names that are downstream extensions (see section Downstream extensions) start with underscore. =20 -Names beginning with 'q_' are reserved for the generator, which uses +Names beginning with 'q\_' are reserved for the generator, which uses them for munging QMP names that resemble C keywords or other problematic strings. For example, a member named "default" in qapi becomes "q_default" in the generated C code. @@ -753,7 +783,7 @@ consistency is preferred over blindly avoiding undersco= re. =20 Event names should be ALL_CAPS with words separated by underscore. =20 -Member name 'u' and names starting with 'has-' or 'has_' are reserved +Member name 'u' and names starting with 'has-' or 'has\_' are reserved for the generator, which uses them for unions and for tracking optional members. =20 @@ -765,7 +795,8 @@ Pragmas 'command-name-exceptions' and 'member-name-exce= ptions' let you violate naming rules. Use for new code is strongly discouraged. =20 =20 -=3D=3D=3D Downstream extensions =3D=3D=3D +Downstream extensions +--------------------- =20 QAPI schema names that are externally visible, say in the Client JSON Protocol, need to be managed with care. Names starting with a @@ -777,9 +808,11 @@ Example: Red Hat, Inc. controls redhat.com, and may th= erefore add a downstream command __com.redhat_drive-mirror. =20 =20 -=3D=3D=3D Configuring the schema =3D=3D=3D +Configuring the schema +---------------------- + +Syntax:: =20 -Syntax: COND =3D STRING | [ STRING, ... ] =20 @@ -788,12 +821,12 @@ string or a list of strings. A string is shorthand f= or a list containing just that string. The code generated for the definition will then be guarded by #if STRING for each STRING in the COND list. =20 -Example: a conditional struct +Example: a conditional struct :: =20 { 'struct': 'IfStruct', 'data': { 'foo': 'int' }, 'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] } =20 -gets its generated code guarded like this: +gets its generated code guarded like this:: =20 #if defined(CONFIG_FOO) #if defined(HAVE_BAR) @@ -806,11 +839,11 @@ event-specific data can also be made conditional. Th= is requires the longhand form of MEMBER. =20 Example: a struct type with unconditional member 'foo' and conditional -member 'bar' +member 'bar' :: =20 -{ 'struct': 'IfStruct', 'data': - { 'foo': 'int', - 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } } + { 'struct': 'IfStruct', 'data': + { 'foo': 'int', + 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } } =20 A union's discriminator may not be conditional. =20 @@ -818,21 +851,21 @@ Likewise, individual enumeration values be conditiona= l. This requires the longhand form of ENUM-VALUE. =20 Example: an enum type with unconditional value 'foo' and conditional -value 'bar' +value 'bar' :: =20 -{ 'enum': 'IfEnum', 'data': - [ 'foo', - { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] } + { 'enum': 'IfEnum', 'data': + [ 'foo', + { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] } =20 Likewise, features can be conditional. This requires the longhand form of FEATURE. =20 -Example: a struct with conditional feature 'allow-negative-numbers' +Example: a struct with conditional feature 'allow-negative-numbers' :: =20 -{ 'struct': 'TestType', - 'data': { 'number': 'int' }, - 'features': [ { 'name': 'allow-negative-numbers', - 'if': 'defined(IFCOND)' } ] } + { 'struct': 'TestType', + 'data': { 'number': 'int' }, + 'features': [ { 'name': 'allow-negative-numbers', + 'if': 'defined(IFCOND)' } ] } =20 Please note that you are responsible to ensure that the C code will compile with an arbitrary combination of conditions, since the @@ -843,12 +876,13 @@ shows a conditional entity only when the condition is= satisfied in this particular build. =20 =20 -=3D=3D=3D Documentation comments =3D=3D=3D +Documentation comments +---------------------- =20 A multi-line comment that starts and ends with a '##' line is a documentation comment. =20 -If the documentation comment starts like +If the documentation comment starts like :: =20 ## # @SYMBOL: @@ -861,10 +895,12 @@ See below for more on definition documentation. Free-form documentation may be used to provide additional text and structuring content. =20 -=3D=3D=3D=3D Headings and subheadings =3D=3D=3D=3D + +Headings and subheadings +~~~~~~~~~~~~~~~~~~~~~~~~ =20 A free-form documentation comment containing a line which starts with -some '=3D' symbols and then a space defines a section heading: +some '=3D' symbols and then a space defines a section heading:: =20 ## # =3D This is a top level heading @@ -883,17 +919,19 @@ comment block. Section headings must always be correctly nested, so you can only define a third-level heading inside a second-level heading, and so on. =20 -=3D=3D=3D=3D Documentation markup =3D=3D=3D=3D + +Documentation markup +~~~~~~~~~~~~~~~~~~~~ =20 Documentation comments can use most rST markup. In particular, -a '::' literal block can be used for examples: +a '::' literal block can be used for examples:: =20 # :: # # Text of the example, may span # multiple lines =20 -'*' starts an itemized list: +'*' starts an itemized list:: =20 # * First item, may span # multiple lines @@ -901,7 +939,7 @@ a '::' literal block can be used for examples: =20 You can also use '-' instead of '*'. =20 -A decimal number followed by '.' starts a numbered list: +A decimal number followed by '.' starts a numbered list:: =20 # 1. First item, may span # multiple lines @@ -920,24 +958,25 @@ backslash-escape it. As an extension beyond the usua= l rST syntax, you can also use '@foo' to reference a name in the schema; this is rendered the same way as '``foo``'. =20 -Example: +Example:: =20 -## -# Some text foo with **bold** and *emphasis* -# 1. with a list -# 2. like that -# -# And some code: -# -# :: -# -# $ echo foo -# -> do this -# <- get that -## + ## + # Some text foo with **bold** and *emphasis* + # 1. with a list + # 2. like that + # + # And some code: + # + # :: + # + # $ echo foo + # -> do this + # <- get that + ## =20 =20 -=3D=3D=3D=3D Definition documentation =3D=3D=3D=3D +Definition documentation +~~~~~~~~~~~~~~~~~~~~~~~~ =20 Definition documentation, if present, must immediately precede the definition it documents. @@ -956,14 +995,14 @@ text can start on the line following the '@argname:',= in which case it must not be indented at all. It can also start on the same line as the '@argname:'. In this case if it spans multiple lines then second and subsequent lines must be indented to line up with the first -character of the first line of the description: +character of the first line of the description:: =20 -# @argone: -# This is a two line description -# in the first style. -# -# @argtwo: This is a two line description -# in the second style. + # @argone: + # This is a two line description + # in the first style. + # + # @argtwo: This is a two line description + # in the second style. =20 The number of spaces between the ':' and the text is not significant. =20 @@ -997,52 +1036,53 @@ An 'Example' or 'Examples' section is automatically = rendered entirely as literal fixed-width text. In other sections, the text is formatted, and rST markup can be used. =20 -For example: +For example:: =20 -## -# @BlockStats: -# -# Statistics of a virtual block device or a block backing device. -# -# @device: If the stats are for a virtual block device, the name -# corresponding to the virtual block device. -# -# @node-name: The node name of the device. (since 2.3) -# -# ... more members ... -# -# Since: 0.14.0 -## -{ 'struct': 'BlockStats', - 'data': {'*device': 'str', '*node-name': 'str', - ... more members ... } } + ## + # @BlockStats: + # + # Statistics of a virtual block device or a block backing device. + # + # @device: If the stats are for a virtual block device, the name + # corresponding to the virtual block device. + # + # @node-name: The node name of the device. (since 2.3) + # + # ... more members ... + # + # Since: 0.14.0 + ## + { 'struct': 'BlockStats', + 'data': {'*device': 'str', '*node-name': 'str', + ... more members ... } } =20 -## -# @query-blockstats: -# -# Query the @BlockStats for all virtual block devices. -# -# @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. -# -# Since: 0.14.0 -# -# Example: -# -# -> { "execute": "query-blockstats" } -# <- { -# ... lots of output ... -# } -# -## -{ 'command': 'query-blockstats', - 'data': { '*query-nodes': 'bool' }, - 'returns': ['BlockStats'] } + ## + # @query-blockstats: + # + # Query the @BlockStats for all virtual block devices. + # + # @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. + # + # Since: 0.14.0 + # + # Example: + # + # -> { "execute": "query-blockstats" } + # <- { + # ... lots of output ... + # } + # + ## + { 'command': 'query-blockstats', + 'data': { '*query-nodes': 'bool' }, + 'returns': ['BlockStats'] } =20 =20 -=3D=3D Client JSON Protocol introspection =3D=3D +Client JSON Protocol introspection +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Clients of a Client JSON Protocol commonly need to figure out what exactly the server (QEMU) supports. @@ -1114,13 +1154,13 @@ If the command takes no arguments, "arg-type" names= an object type without members. Likewise, if the command returns nothing, "ret-type" names an object type without members. =20 -Example: the SchemaInfo for command query-qmp-schema +Example: the SchemaInfo for command query-qmp-schema :: =20 - { "name": "query-qmp-schema", "meta-type": "command", - "arg-type": "q_empty", "ret-type": "SchemaInfoList" } + { "name": "query-qmp-schema", "meta-type": "command", + "arg-type": "q_empty", "ret-type": "SchemaInfoList" } =20 - Type "q_empty" is an automatic object type without members, and type - "SchemaInfoList" is the array of SchemaInfo type. + Type "q_empty" is an automatic object type without members, and type + "SchemaInfoList" is the array of SchemaInfo type. =20 The SchemaInfo for an event has meta-type "event", and variant member "arg-type". On the wire, a "data" member that the server passes in an @@ -1133,7 +1173,7 @@ the wire then. Each command or event defined with 'data' as MEMBERS object in the QAPI schema implicitly defines an object type. =20 -Example: the SchemaInfo for EVENT_C from section Events +Example: the SchemaInfo for EVENT_C from section Events :: =20 { "name": "EVENT_C", "meta-type": "event", "arg-type": "q_obj-EVENT_C-arg" } @@ -1157,7 +1197,7 @@ extensions. The "members" array is in no particular = order; clients must search the entire object when learning whether a particular member is supported. =20 -Example: the SchemaInfo for MyType from section Struct types +Example: the SchemaInfo for MyType from section Struct types :: =20 { "name": "MyType", "meta-type": "object", "members": [ @@ -1168,7 +1208,7 @@ Example: the SchemaInfo for MyType from section Struc= t types "features" exposes the command's feature strings as a JSON array of strings. =20 -Example: the SchemaInfo for TestType from section Features: +Example: the SchemaInfo for TestType from section Features:: =20 { "name": "TestType", "meta-type": "object", "members": [ @@ -1184,7 +1224,7 @@ that provides the variant members for this type tag v= alue). The list cases in the same order as the corresponding "tag" enum type. =20 Example: the SchemaInfo for flat union BlockdevOptions from section -Union types +Union types :: =20 { "name": "BlockdevOptions", "meta-type": "object", "members": [ @@ -1205,7 +1245,7 @@ A simple union implicitly defines an object type for = each of its variants. =20 Example: the SchemaInfo for simple union BlockdevOptionsSimple from section -Union types +Union types :: =20 { "name": "BlockdevOptionsSimple", "meta-type": "object", "members": [ @@ -1225,7 +1265,7 @@ a JSON object with member "type", which names a type.= Values of the alternate type conform to exactly one of its member types. There is no guarantee on the order in which "members" will be listed. =20 -Example: the SchemaInfo for BlockdevRef from section Alternate types +Example: the SchemaInfo for BlockdevRef from section Alternate types :: =20 { "name": "BlockdevRef", "meta-type": "alternate", "members": [ @@ -1239,7 +1279,7 @@ resemble the element type; however, clients should ex= amine member "element-type" instead of making assumptions based on parsing member "name". =20 -Example: the SchemaInfo for ['str'] +Example: the SchemaInfo for ['str'] :: =20 { "name": "[str]", "meta-type": "array", "element-type": "str" } @@ -1249,7 +1289,7 @@ variant member "values". The values are listed in no= particular order; clients must search the entire enum when learning whether a particular value is supported. =20 -Example: the SchemaInfo for MyEnum from section Enumeration types +Example: the SchemaInfo for MyEnum from section Enumeration types :: =20 { "name": "MyEnum", "meta-type": "enum", "values": [ "value1", "value2", "value3" ] } @@ -1259,7 +1299,7 @@ the QAPI schema (see section Built-in Types), with on= e exception detailed below. It has variant member "json-type" that shows how values of this type are encoded on the wire. =20 -Example: the SchemaInfo for str +Example: the SchemaInfo for str :: =20 { "name": "str", "meta-type": "builtin", "json-type": "string" } =20 @@ -1273,7 +1313,8 @@ the names of built-in types. Clients should examine = member "json-type" instead of hard-coding names of built-in types. =20 =20 -=3D=3D Compatibility considerations =3D=3D +Compatibility considerations +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 Maintaining backward compatibility at the Client JSON Protocol level while evolving the schema requires some care. This section is about @@ -1333,7 +1374,8 @@ may be freely renamed. Even certain refactorings are= invisible, such as splitting members from one type into a common base type. =20 =20 -=3D=3D Code generation =3D=3D +Code generation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The QAPI code generator qapi-gen.py generates code and documentation from the schema. Together with the core QAPI libraries, this code @@ -1347,7 +1389,7 @@ As an example, we'll use the following schema, which = describes a single complex user-defined type, along with command which takes a list of that type as a parameter, and returns a single element of that type. The user is responsible for writing the implementation of -qmp_my_command(); everything else is produced by the generator. +qmp_my_command(); everything else is produced by the generator. :: =20 $ cat example-schema.json { 'struct': 'UserDefOne', @@ -1359,7 +1401,7 @@ qmp_my_command(); everything else is produced by the = generator. =20 { 'event': 'MY_EVENT' } =20 -We run qapi-gen.py like this: +We run qapi-gen.py like this:: =20 $ python scripts/qapi-gen.py --output-dir=3D"qapi-generated" \ --prefix=3D"example-" example-schema.json @@ -1369,24 +1411,27 @@ tests/qapi-schema/qapi-schema-tests.json that cover= s more examples of what the generator will accept, and compiles the resulting C code as part of 'make check-unit'. =20 -=3D=3D=3D Code generated for QAPI types =3D=3D=3D + +Code generated for QAPI types +----------------------------- =20 The following files are created: =20 -$(prefix)qapi-types.h - C types corresponding to types defined in - the schema + ``$(prefix)qapi-types.h`` + C types corresponding to types defined in the schema =20 -$(prefix)qapi-types.c - Cleanup functions for the above C types + ``$(prefix)qapi-types.c`` + Cleanup functions for the above C types =20 The $(prefix) is an optional parameter used as a namespace to keep the generated code from one schema/code-generation separated from others so co= de can be generated/used from multiple schemas without clobbering previously created code. =20 -Example: +Example:: =20 $ cat qapi-generated/example-qapi-types.h -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 #ifndef EXAMPLE_QAPI_TYPES_H #define EXAMPLE_QAPI_TYPES_H @@ -1422,7 +1467,7 @@ Example: =20 #endif /* EXAMPLE_QAPI_TYPES_H */ $ cat qapi-generated/example-qapi-types.c -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 void qapi_free_UserDefOne(UserDefOne *obj) { @@ -1450,22 +1495,26 @@ Example: visit_free(v); } =20 -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 For a modular QAPI schema (see section Include directives), code for -each sub-module SUBDIR/SUBMODULE.json is actually generated into +each sub-module SUBDIR/SUBMODULE.json is actually generated into :: =20 -SUBDIR/$(prefix)qapi-types-SUBMODULE.h -SUBDIR/$(prefix)qapi-types-SUBMODULE.c + SUBDIR/$(prefix)qapi-types-SUBMODULE.h + SUBDIR/$(prefix)qapi-types-SUBMODULE.c =20 If qapi-gen.py is run with option --builtins, additional files are created: =20 -qapi-builtin-types.h - C types corresponding to built-in types + ``qapi-builtin-types.h`` + C types corresponding to built-in types =20 -qapi-builtin-types.c - Cleanup functions for the above C types + ``qapi-builtin-types.c`` + Cleanup functions for the above C types =20 -=3D=3D=3D Code generated for visiting QAPI types =3D=3D=3D + +Code generated for visiting QAPI types +-------------------------------------- =20 These are the visitor functions used to walk through and convert between a native QAPI C data structure and some other format (such as @@ -1474,19 +1523,18 @@ visit_type_FOO_members(). =20 The following files are generated: =20 -$(prefix)qapi-visit.c: Visitor function for a particular C type, used - to automagically convert QObjects into the - corresponding C type and vice-versa, as well - as for deallocating memory for an existing C - type + ``$(prefix)qapi-visit.c`` + Visitor function for a particular C type, used to automagically + convert QObjects into the corresponding C type and vice-versa, as + well as for deallocating memory for an existing C type =20 -$(prefix)qapi-visit.h: Declarations for previously mentioned visitor - functions + ``$(prefix)qapi-visit.h`` + Declarations for previously mentioned visitor functions =20 -Example: +Example:: =20 $ cat qapi-generated/example-qapi-visit.h -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 #ifndef EXAMPLE_QAPI_VISIT_H #define EXAMPLE_QAPI_VISIT_H @@ -1507,7 +1555,7 @@ Example: =20 #endif /* EXAMPLE_QAPI_VISIT_H */ $ cat qapi-generated/example-qapi-visit.c -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error = **errp) { @@ -1585,22 +1633,26 @@ Example: return true; } =20 -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 For a modular QAPI schema (see section Include directives), code for -each sub-module SUBDIR/SUBMODULE.json is actually generated into +each sub-module SUBDIR/SUBMODULE.json is actually generated into :: =20 -SUBDIR/$(prefix)qapi-visit-SUBMODULE.h -SUBDIR/$(prefix)qapi-visit-SUBMODULE.c + SUBDIR/$(prefix)qapi-visit-SUBMODULE.h + SUBDIR/$(prefix)qapi-visit-SUBMODULE.c =20 If qapi-gen.py is run with option --builtins, additional files are created: =20 -qapi-builtin-visit.h - Visitor functions for built-in types + ``qapi-builtin-visit.h`` + Visitor functions for built-in types =20 -qapi-builtin-visit.c - Declarations for these visitor functions + ``qapi-builtin-visit.c`` + Declarations for these visitor functions =20 -=3D=3D=3D Code generated for commands =3D=3D=3D + +Code generated for commands +--------------------------- =20 These are the marshaling/dispatch functions for the commands defined in the schema. The generated code provides qmp_marshal_COMMAND(), and @@ -1608,20 +1660,23 @@ declares qmp_COMMAND() that the user must implement. =20 The following files are generated: =20 -$(prefix)qapi-commands.c: Command marshal/dispatch functions for each - QMP command defined in the schema + ``$(prefix)qapi-commands.c`` + Command marshal/dispatch functions for each QMP command defined in + the schema =20 -$(prefix)qapi-commands.h: Function prototypes for the QMP commands - specified in the schema + ``$(prefix)qapi-commands.h`` + Function prototypes for the QMP commands specified in the schema =20 -$(prefix)qapi-init-commands.h - Command initialization prototype + ``$(prefix)qapi-init-commands.h`` + Command initialization prototype =20 -$(prefix)qapi-init-commands.c - Command initialization code + ``$(prefix)qapi-init-commands.c`` + Command initialization code =20 -Example: +Example:: =20 $ cat qapi-generated/example-qapi-commands.h -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 #ifndef EXAMPLE_QAPI_COMMANDS_H #define EXAMPLE_QAPI_COMMANDS_H @@ -1633,7 +1688,7 @@ Example: =20 #endif /* EXAMPLE_QAPI_COMMANDS_H */ $ cat qapi-generated/example-qapi-commands.c -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 =20 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, @@ -1688,9 +1743,9 @@ Example: visit_free(v); } =20 -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] $ cat qapi-generated/example-qapi-init-commands.h -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H #define EXAMPLE_QAPI_INIT_COMMANDS_H =20 @@ -1700,7 +1755,7 @@ Example: =20 #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */ $ cat qapi-generated/example-qapi-init-commands.c -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] void example_qmp_init_marshal(QmpCommandList *cmds) { QTAILQ_INIT(cmds); @@ -1708,34 +1763,39 @@ Example: qmp_register_command(cmds, "my-command", qmp_marshal_my_command, QCO_NO_OPTIONS); } -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 For a modular QAPI schema (see section Include directives), code for -each sub-module SUBDIR/SUBMODULE.json is actually generated into +each sub-module SUBDIR/SUBMODULE.json is actually generated into:: =20 -SUBDIR/$(prefix)qapi-commands-SUBMODULE.h -SUBDIR/$(prefix)qapi-commands-SUBMODULE.c + SUBDIR/$(prefix)qapi-commands-SUBMODULE.h + SUBDIR/$(prefix)qapi-commands-SUBMODULE.c =20 -=3D=3D=3D Code generated for events =3D=3D=3D + +Code generated for events +------------------------- =20 This is the code related to events defined in the schema, providing qapi_event_send_EVENT(). =20 The following files are created: =20 -$(prefix)qapi-events.h - Function prototypes for each event type + ``$(prefix)qapi-events.h`` + Function prototypes for each event type =20 -$(prefix)qapi-events.c - Implementation of functions to send an event + ``$(prefix)qapi-events.c`` + Implementation of functions to send an event =20 -$(prefix)qapi-emit-events.h - Enumeration of all event names, and - common event code declarations + ``$(prefix)qapi-emit-events.h`` + Enumeration of all event names, and common event code declarations =20 -$(prefix)qapi-emit-events.c - Common event code definitions + ``$(prefix)qapi-emit-events.c`` + Common event code definitions =20 -Example: +Example:: =20 $ cat qapi-generated/example-qapi-events.h -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 #ifndef EXAMPLE_QAPI_EVENTS_H #define EXAMPLE_QAPI_EVENTS_H @@ -1747,7 +1807,7 @@ Example: =20 #endif /* EXAMPLE_QAPI_EVENTS_H */ $ cat qapi-generated/example-qapi-events.c -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 void qapi_event_send_my_event(void) { @@ -1760,9 +1820,9 @@ Example: qobject_unref(qmp); } =20 -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] $ cat qapi-generated/example-qapi-emit-events.h -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H #define EXAMPLE_QAPI_EMIT_EVENTS_H @@ -1783,7 +1843,7 @@ Example: =20 #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */ $ cat qapi-generated/example-qapi-emit-events.c -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 const QEnumLookup example_QAPIEvent_lookup =3D { .array =3D (const char *const[]) { @@ -1792,27 +1852,30 @@ Example: .size =3D EXAMPLE_QAPI_EVENT__MAX }; =20 -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 For a modular QAPI schema (see section Include directives), code for -each sub-module SUBDIR/SUBMODULE.json is actually generated into +each sub-module SUBDIR/SUBMODULE.json is actually generated into :: =20 -SUBDIR/$(prefix)qapi-events-SUBMODULE.h -SUBDIR/$(prefix)qapi-events-SUBMODULE.c + SUBDIR/$(prefix)qapi-events-SUBMODULE.h + SUBDIR/$(prefix)qapi-events-SUBMODULE.c =20 -=3D=3D=3D Code generated for introspection =3D=3D=3D + +Code generated for introspection +-------------------------------- =20 The following files are created: =20 -$(prefix)qapi-introspect.c - Defines a string holding a JSON - description of the schema + ``$(prefix)qapi-introspect.c`` + Defines a string holding a JSON description of the schema =20 -$(prefix)qapi-introspect.h - Declares the above string + ``$(prefix)qapi-introspect.h`` + Declares the above string =20 -Example: +Example:: =20 $ cat qapi-generated/example-qapi-introspect.h -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 #ifndef EXAMPLE_QAPI_INTROSPECT_H #define EXAMPLE_QAPI_INTROSPECT_H @@ -1823,7 +1886,7 @@ Example: =20 #endif /* EXAMPLE_QAPI_INTROSPECT_H */ $ cat qapi-generated/example-qapi-introspect.c -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] =20 const QLitObject example_qmp_schema_qlit =3D QLIT_QLIST(((QLitObject[]= ) { QLIT_QDICT(((QLitDictEntry[]) { @@ -1903,4 +1966,4 @@ Example: {} })); =20 -[Uninteresting stuff omitted...] + [Uninteresting stuff omitted...] --=20 2.31.1