From nobody Tue Nov 4 19:05:32 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 1530549422658229.68529888247895; Mon, 2 Jul 2018 09:37:02 -0700 (PDT) Received: from localhost ([::1]:34165 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fa1ox-0006iP-Fa for importer@patchew.org; Mon, 02 Jul 2018 12:36:59 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42529) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fa1at-0004RQ-5P for qemu-devel@nongnu.org; Mon, 02 Jul 2018 12:22:31 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fa1ap-0006c8-NL for qemu-devel@nongnu.org; Mon, 02 Jul 2018 12:22:27 -0400 Received: from mx3-rdu2.redhat.com ([66.187.233.73]:47584 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 1fa1ap-0006bo-IB for qemu-devel@nongnu.org; Mon, 02 Jul 2018 12:22:23 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 2F9427CBBA for ; Mon, 2 Jul 2018 16:22:23 +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 8E3781C5A7; Mon, 2 Jul 2018 16:22:19 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6CD481132DA0; Mon, 2 Jul 2018 18:22:18 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Date: Mon, 2 Jul 2018 18:21:49 +0200 Message-Id: <20180702162218.13678-4-armbru@redhat.com> In-Reply-To: <20180702162218.13678-1-armbru@redhat.com> References: <20180702162218.13678-1-armbru@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.11.54.5 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.2]); Mon, 02 Jul 2018 16:22:23 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.11.55.2]); Mon, 02 Jul 2018 16:22:23 +0000 (UTC) for IP:'10.11.54.5' DOMAIN:'int-mx05.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 03/32] docs/interop/qmp: Improve OOB documentation 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" OOB documentation is spread over qmp-spec.txt sections 2.2.1 Capabilities and 2.3 Issuing Commands. The amount of detail is a bit distracting there. Move the meat of the matter to new section 2.3.1 Out of band execution. Throw in a few other improvements while there: * 2.2 Server Greetung: Drop advice to search entire capabilities array; should be obvious. * 3. QMP Examples - 3.1 Server Greeting: Update greeting to current one. Now shows capability "oob". Update qmp-intro.txt likewise. - 3.2 Capabilities negotiation: Show client accepting capability "oob". - 3.7 Out-of-band execution: New. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake --- docs/interop/qmp-intro.txt | 13 +++---- docs/interop/qmp-spec.txt | 74 +++++++++++++++++++++++++------------- 2 files changed, 56 insertions(+), 31 deletions(-) diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt index 900d69d612..3dafa35ea6 100644 --- a/docs/interop/qmp-intro.txt +++ b/docs/interop/qmp-intro.txt @@ -52,13 +52,14 @@ Escape character is '^]'. "QMP": { "version": { "qemu": { - "micro": 50,=20 - "minor": 6,=20 - "major": 1 - },=20 - "package": "" - },=20 + "micro": 50, + "minor": 12, + "major": 2 + }, + "package": "v2.12.0-1763-g4e022f5ccd" + }, "capabilities": [ + "oob" ] } } diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.txt index 2bb492d1ea..e5f8116c54 100644 --- a/docs/interop/qmp-spec.txt +++ b/docs/interop/qmp-spec.txt @@ -77,8 +77,7 @@ The greeting message format is: is the same of the query-version command) - The "capabilities" member specify the availability of features beyond the baseline specification; the order of elements in this array has no - particular significance, so a client must search the entire array - when looking for a particular capability + particular significance. =20 2.2.1 Capabilities ------------------ @@ -86,16 +85,7 @@ The greeting message format is: Currently supported capabilities are: =20 - "oob": the QMP server supports "out-of-band" (OOB) command - execution. For more details, please see the "run-oob" parameter in - the "Issuing Commands" section below. Not all commands allow this - "oob" execution. The "query-qmp-schema" command can be used to - inspect which commands support "oob" execution. - -QMP clients can get a list of supported QMP capabilities of the QMP -server in the greeting message mentioned above. By default, all the -capabilities are off. To enable any QMP capabilities, the QMP client -needs to send the "qmp_capabilities" command with an extra parameter -for the requested capabilities. + execution, as described in section "2.3.1 Out-of-band execution". =20 2.3 Issuing Commands -------------------- @@ -115,14 +105,38 @@ The format for command execution is: - The "id" member is a transaction identification associated with the command execution. It is required for all commands if the OOB - capability was enabled at startup, and optional otherwise. The same - "id" field will be part of the response if provided. The "id" member - can be any json-value, although most clients merely use a - json-number incremented for each successive command -- The "control" member is optional, and currently only used for - out-of-band execution. The handling or response of an "oob" command - can overtake prior in-band commands. To enable "oob" handling of a - particular command, just provide a control field with: { "control": - { "run-oob": true } } + "id" field will be part of the response if provided. The "id" + member can be any json-value. A json-number incremented for each + successive command works fine. +- The optional "control" member further specifies how the command is + to be executed. Currently, its only member is optional "run-oob". + See section "2.3.1 Out-of-band execution" for details. + + +2.3.1 Out-of-band execution +--------------------------- + +The server normally reads, executes and responds to one command after +the other. The client therefore receives command respones in issue +order. + +With out-of-band execution enabled via capability negotiation (section +4.), the server reads and queues commands as they arrive. It executes +commands from the queue one after the other. Commands executed +out-of-band jump the queue: they command get executed right away, +possibly overtaking prior in-band commands. The client may therefore +receive such a command's response before responses from prior in-band +commands. + +To execute a command out-of-band, the client puts "run-oob": true into +execute's member "control". + +If the client sends in-band commands faster than the server can +execute them, the server will eventually drop commands to limit the +queue length. The sever sends event COMMAND_DROPPED then. + +Only a few commands support out-of-band execution. The ones that do +have "allow-oob": true in output of query-qmp-schema. =20 2.4 Commands Responses ---------------------- @@ -223,12 +237,13 @@ This section provides some examples of real QMP usage= , in all of them 3.1 Server greeting ------------------- =20 -S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 }, - "package": ""}, "capabilities": []}} +S: { "QMP": {"version": {"qemu": {"micro": 50, "minor": 12, "major": 2}, + "package": "v2.12.0-1763-g4e022f5ccd"}, "capabilities": ["oob"] } } =20 -3.2 Client QMP negotiation --------------------------- -C: { "execute": "qmp_capabilities" } +3.2 Capabilities negotiation +---------------------------- + +C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } } S: { "return": {}} =20 3.3 Simple 'stop' execution @@ -255,6 +270,15 @@ S: { "error": { "class": "GenericError", "desc": "Inva= lid JSON syntax" } } S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 }, "event": "POWERDOWN" } =20 +3.7 Out-of-band execution +------------------------- + +C: { "execute": "migrate-pause", "id": 42, "control": { "run-oob": true } } +S: { "id": 42, + "error": { "class": "GenericError", + "desc": "migrate-pause is currently only supported during postcopy-a= ctive state" } } + + 4. Capabilities Negotiation =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 --=20 2.17.1