From nobody Tue Nov 4 18:51:46 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1530549781296385.70633343717986; Mon, 2 Jul 2018 09:43:01 -0700 (PDT) Received: from localhost ([::1]:34197 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fa1um-00030V-GC for importer@patchew.org; Mon, 02 Jul 2018 12:43:00 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42669) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fa1aw-0004UX-1g for qemu-devel@nongnu.org; Mon, 02 Jul 2018 12:22:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fa1as-0006gl-B0 for qemu-devel@nongnu.org; Mon, 02 Jul 2018 12:22:29 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:54944 helo=mx1.redhat.com) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fa1ar-0006fB-SA for qemu-devel@nongnu.org; Mon, 02 Jul 2018 12:22:26 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 4BC3840704BB for ; Mon, 2 Jul 2018 16:22:25 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-116-58.ams2.redhat.com [10.36.116.58]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0558021568A1; Mon, 2 Jul 2018 16:22:25 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 06B911132754; Mon, 2 Jul 2018 18:22:19 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Date: Mon, 2 Jul 2018 18:22:18 +0200 Message-Id: <20180702162218.13678-33-armbru@redhat.com> In-Reply-To: <20180702162218.13678-1-armbru@redhat.com> References: <20180702162218.13678-1-armbru@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.7]); Mon, 02 Jul 2018 16:22:25 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.7]); Mon, 02 Jul 2018 16:22:25 +0000 (UTC) for IP:'10.11.54.6' DOMAIN:'int-mx06.intmail.prod.int.rdu2.redhat.com' HELO:'smtp.corp.redhat.com' FROM:'armbru@redhat.com' RCPT:'' X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 66.187.233.73 Subject: [Qemu-devel] [PATCH 32/32] qapi: Polish command flags documentation in qapi-code-gen.txt X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: stefanha@redhat.com, peterx@redhat.com, dgilbert@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.txt | 61 +++++++++++++++--------------------- 1 file changed, 25 insertions(+), 36 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index f020f6bab2..8decd6f17d 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -624,60 +624,48 @@ its return value. In rare cases, QAPI cannot express a type-safe representation of a corresponding Client JSON Protocol command. You then have to suppress generation of a marshalling function by including a key 'gen' with -boolean value false, and instead write your own function. Please try -to avoid adding new commands that rely on this, and instead use -type-safe unions. For an example of this usage: +boolean value false, and instead write your own function. For +example: =20 { 'command': 'netdev_add', 'data': {'type': 'str', 'id': 'str'}, 'gen': false } =20 +Please try to avoid adding new commands that rely on this, and instead +use type-safe unions. + Normally, the QAPI schema is used to describe synchronous exchanges, where a response is expected. But in some cases, the action of a command is expected to change state in a way that a successful response is not possible (although the command will still return a normal dictionary error on failure). When a successful reply is not -possible, the command expression should include the optional key +possible, the command expression includes the optional key 'success-response' with boolean value false. So far, only QGA makes use of this member. =20 -A command can be declared to support out-of-band (OOB) execution. By -default, commands do not support OOB. To declare a command that -supports it, the schema includes an extra 'allow-oob' field. For -example: +Key 'allow-oob' declares whether the command supports out-of-band +(OOB) execution. It defaults to false. For example: =20 { 'command': 'migrate_recover', 'data': { 'uri': 'str' }, 'allow-oob': true } =20 -To execute a command with out-of-band priority, the client uses key -"exec-oob" instead of "execute". Example: +See qmp-spec.txt for out-of-band execution syntax and semantics. =20 - =3D> { "exec-oob": "migrate-recover", - "arguments": { "uri": "tcp:192.168.1.200:12345" } } - <=3D { "return": { } } +Commands supporting out-of-band execution can still be executed +in-band. =20 -Without it, even the commands that support out-of-band execution will -still be run in-band. +When a command is executed in-band, its handler runs in the main +thread with the BQL held. =20 -Under normal QMP command execution, the following apply to each -command: +When a command is executed out-of-band, its handler runs in a +dedicated monitor I/O thread with the BQL *not* held. =20 -- They are executed in order, -- They run only in main thread of QEMU, -- They run with the BQL held. +An OOB-capable command handler must satisfy the following conditions: =20 -When a command is executed with OOB, the following changes occur: - -- They can be completed before a pending in-band command, -- They run in a dedicated monitor thread, -- They run with the BQL not held. - -OOB command handlers must satisfy the following conditions: - -- It terminates quickly, -- It does not invoke system calls that may block, +- It terminates quickly. +- It does not invoke system calls that may block. - It does not access guest RAM that may block when userfaultfd is - enabled for postcopy live migration, + enabled for postcopy live migration. - It takes only "fast" locks, i.e. all critical sections protected by any lock it takes also satisfy the conditions for OOB command handler code. @@ -686,17 +674,18 @@ The restrictions on locking limit access to shared st= ate. Such access requires synchronization, but OOB commands can't take the BQL or any other "slow" lock. =20 -If in doubt, do not implement OOB execution support. +When in doubt, do not implement OOB execution support. =20 -A command may use the optional 'allow-preconfig' key to permit its executi= on -at early runtime configuration stage (preconfig runstate). -If not specified then a command defaults to 'allow-preconfig': false. +Key 'allow-preconfig' declares whether the command is available before +the machine is built. It defaults to false. For example: =20 -An example of declaring a command that is enabled during preconfig: { 'command': 'qmp_capabilities', 'data': { '*enable': [ 'QMPCapability' ] }, 'allow-preconfig': true } =20 +QMP is available before the machine is built only when QEMU was +started with --preconfig. + =3D=3D=3D Events =3D=3D=3D =20 Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, --=20 2.17.1