From nobody Tue May 14 21:33:02 2024 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=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1684167838; cv=none; d=zohomail.com; s=zohoarc; b=Eme6goNF6A859y2XOV2kMKmglxpfqTA55g9x46+PB4HyKM0ReUKNzKXD7sGoQvTBIxslQx0535Ny6xcoH3uMuftbQ3qS3ZQAcMwe4rX/A8YIIOyxz2Je15oqipW5CnaWPfRiZpefoo37xKrA34vbiSF9QXRa282c97RiuR5PMP8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1684167838; h=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=OaJIr35f0SoNree+5+82PsKu8ep7DIZDi9Kkj/M+Vks=; b=jOAAZRDAI8zG0I1/6Lo2hsL7BRBOR5JbMMreWuE8O53afYoypycrsVSqTXngxqXVVQuCq6OG3qRm78EZnLJK/VXrrHdIlQNgjVktAiToL9Qf0dvaFCHh/OdYmVx+yDWvAp7SBE0a1RMpSm0iTFbyiwm9l5xDQYYFONah+ofKGRQ= 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 1684167838333234.4989259765008; Mon, 15 May 2023 09:23:58 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pyayZ-0001NR-P5; Mon, 15 May 2023 12:23:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pyayN-0001Gn-Qc for qemu-devel@nongnu.org; Mon, 15 May 2023 12:22:56 -0400 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pyayH-0005Mp-Fx for qemu-devel@nongnu.org; Mon, 15 May 2023 12:22:55 -0400 Received: by mail-wr1-x42e.google.com with SMTP id ffacd0b85a97d-306281edf15so12314239f8f.1 for ; Mon, 15 May 2023 09:22:49 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id h12-20020adffd4c000000b003063176ef09sm278203wrs.6.2023.05.15.09.22.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 15 May 2023 09:22:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1684167768; x=1686759768; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=OaJIr35f0SoNree+5+82PsKu8ep7DIZDi9Kkj/M+Vks=; b=XfbKLPgNMAfE6oH+A//A/B/93SiFFMrIxImwi8S5UmQkIRsGvaVcUUcaTXs3T+e+WB Tax/x0St8Qba6YtXYCLbMXZ4AlHk6cEHiev8lrMtwapEG9a5QJPA7NCep0FHmAldbNzP e1wNYgyiDmhKM9D8ZpAzp+i4hDYmV40spF7Nvf98JjKFboHXK9U/Afol3yVewmfCN0MB n7jvWH+xatasSwDXTgT4HsjOV3amw7j6nMRu0U+8LLOnTitBZ4ZwcAQqPC+ZVZFN2EGQ oYbkcA9EjGm3kZ5rnDwtfnPl7nFNwkHyqfogRFNTibMe2KCzGw95MamiSn+OGl8P2u57 Af8w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1684167768; x=1686759768; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=OaJIr35f0SoNree+5+82PsKu8ep7DIZDi9Kkj/M+Vks=; b=ZE+5YhVZvDsw9XkDMsqjScFiSelTQSgYA7u4lyokZkzFqBMCAoEnmF5jqwu/BKAxa6 d3VUA/LNZeyHdOTN9VIC36iuTTzgB9TUE0Z2w/OwvhKFw1zaQUYViHMwrJX7v7u5rQAq qESGY5XV2+NRw50YFl0VCQvYbmiA6yZKeBc+//1XMDLlvioLSrcVggy6grEzxS6gMQTd UkWhrq3db9AIvJ9v4Qeo2gfr35m3X2AwGC635XeECGzyxpas/vDB2+/q4AFcjE6iUWXQ nSxXcfuA0uT/k25H9392DiY7UyVWXuJDMsAYLZ7DOQhpJskOuYv3dGbUp3oOR/CDUv4j e/Lg== X-Gm-Message-State: AC+VfDxAxlgaPx5lZu1ZNBhYoxwxWWBI3p7dQYa56lclclq86GchNHB+ K8FuoSmXXOMxy80w44WNMPPSfZriyuzamlZjLCc= X-Google-Smtp-Source: ACHHUZ67joaQu/rODAOtfvZVEKNfmrHJ1ke56sXLLRmYPYij7F8826h1LOuIUquhLkQ9y2dWrGydgw== X-Received: by 2002:a05:6000:1148:b0:2fa:88f2:b04c with SMTP id d8-20020a056000114800b002fa88f2b04cmr23536182wrx.20.1684167767264; Mon, 15 May 2023 09:22:47 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Cc: Markus Armbruster , Eric Blake Subject: [PATCH v3 1/3] docs/interop: Convert qmp-spec.txt to rST Date: Mon, 15 May 2023 17:22:43 +0100 Message-Id: <20230515162245.3964307-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230515162245.3964307-1-peter.maydell@linaro.org> References: <20230515162245.3964307-1-peter.maydell@linaro.org> MIME-Version: 1.0 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=2a00:1450:4864:20::42e; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42e.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1684167840412100007 Content-Type: text/plain; charset="utf-8" Convert the qmp-spec.txt document to restructuredText. Notable points about the conversion: * numbers at the start of section headings are removed, to match the style of the rest of the manual * cross-references to other sections or documents are hyperlinked * various formatting tweaks (notably the examples, which need the -> and <- prefixed so the QMP code-block lexer will accept them) * English prose fixed in a few places Reviewed-by: Eric Blake Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster --- v1->v2: minor tweaks per Eric's review * consistently use '.' at end of sentences in Where: lists * s/the same of the/the same as for the/ v2->v3: fix up the references elsewhere in the codebase to qmp-spec.txt (this includes using section names rather than numbers) --- docs/devel/qapi-code-gen.rst | 3 +- docs/interop/index.rst | 1 + docs/interop/{qmp-spec.txt =3D> qmp-spec.rst} | 337 +++++++++++--------- qapi/control.json | 4 +- qapi/qapi-schema.json | 3 +- qobject/json-lexer.c | 2 +- python/qemu/qmp/models.py | 8 +- python/qemu/qmp/qmp_client.py | 4 +- 8 files changed, 199 insertions(+), 163 deletions(-) rename docs/interop/{qmp-spec.txt =3D> qmp-spec.rst} (55%) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 5618a80378e..7f78183cd48 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -545,7 +545,8 @@ Member 'allow-oob' declares whether the command support= s out-of-band { 'command': 'migrate_recover', 'data': { 'uri': 'str' }, 'allow-oob': true } =20 -See qmp-spec.txt for out-of-band execution syntax and semantics. +See the :doc:`/interop/qmp-spec` for out-of-band execution syntax +and semantics. =20 Commands supporting out-of-band execution can still be executed in-band. diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 6351ff9ba6e..ed65395bfb2 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -15,6 +15,7 @@ are useful for making QEMU interoperate with other softwa= re. dbus-display live-block-operations pr-helper + qmp-spec qemu-ga qemu-ga-ref qemu-qmp-ref diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.rst similarity index 55% rename from docs/interop/qmp-spec.txt rename to docs/interop/qmp-spec.rst index b0e8351d5b2..bfad570a160 100644 --- a/docs/interop/qmp-spec.txt +++ b/docs/interop/qmp-spec.rst @@ -1,24 +1,26 @@ - QEMU Machine Protocol Specification +.. + Copyright (C) 2009-2016 Red Hat, Inc. =20 -0. About This Document -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + 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 -Copyright (C) 2009-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. +=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 +QEMU Machine Protocol Specification +=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 =20 -1. Introduction -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -This document specifies the QEMU Machine Protocol (QMP), a JSON-based +The QEMU Machine Protocol (QMP) is a JSON-based protocol which is available for applications to operate QEMU at the machine-level. It is also in use by the QEMU Guest Agent (QGA), which is available for host applications to interact with the guest -operating system. +operating system. This page specifies the general format of +the protocol; details of the commands and data structures can +be found in the :doc:`qemu-qmp-ref` and the :doc:`qemu-ga-ref`. =20 -2. Protocol Specification -=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 +.. contents:: + +Protocol Specification +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 This section details the protocol format. For the purpose of this document, "Server" is either QEMU or the QEMU Guest Agent, and @@ -30,9 +32,7 @@ following format: json-DATA-STRUCTURE-NAME =20 Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined -by the JSON standard: - -http://www.ietf.org/rfc/rfc8259.txt +by the `JSON standard `_. =20 The server expects its input to be encoded in UTF-8, and sends its output encoded in ASCII. @@ -45,83 +45,89 @@ important unless specifically documented otherwise. Re= peating a key within a json-object gives unpredictable results. =20 Also for convenience, the server will accept an extension of -'single-quoted' strings in place of the usual "double-quoted" +``'single-quoted'`` strings in place of the usual ``"double-quoted"`` json-string, and both input forms of strings understand an additional -escape sequence of "\'" for a single quote. The server will only use +escape sequence of ``\'`` for a single quote. The server will only use double quoting on output. =20 -2.1 General Definitions ------------------------ - -2.1.1 All interactions transmitted by the Server are json-objects, always - terminating with CRLF - -2.1.2 All json-objects members are mandatory when not specified otherwise - -2.2 Server Greeting +General Definitions ------------------- =20 +All interactions transmitted by the Server are json-objects, always +terminating with CRLF. + +All json-objects members are mandatory when not specified otherwise. + +Server Greeting +--------------- + Right when connected the Server will issue a greeting message, which signa= ls that the connection has been successfully established and that the Server = is ready for capabilities negotiation (for more information refer to section -'4. Capabilities Negotiation'). +`Capabilities Negotiation`_). =20 The greeting message format is: =20 -{ "QMP": { "version": json-object, "capabilities": json-array } } +.. code-block:: =20 - Where, + { "QMP": { "version": json-object, "capabilities": json-array } } =20 -- The "version" member contains the Server's version information (the form= at - is the same of the query-version command) -- The "capabilities" member specify the availability of features beyond the +Where: + +- The ``version`` member contains the Server's version information (the fo= rmat + is the same as for the query-version command). +- The ``capabilities`` member specifies the availability of features beyon= d the baseline specification; the order of elements in this array has no particular significance. =20 -2.2.1 Capabilities ------------------- +Capabilities +------------ =20 Currently supported capabilities are: =20 -- "oob": the QMP server supports "out-of-band" (OOB) command - execution, as described in section "2.3.1 Out-of-band execution". +``oob`` + the QMP server supports "out-of-band" (OOB) command + execution, as described in section `Out-of-band execution`_. =20 -2.3 Issuing Commands --------------------- +Issuing Commands +---------------- =20 The format for command execution is: =20 -{ "execute": json-string, "arguments": json-object, "id": json-value } +.. code-block:: + + { "execute": json-string, "arguments": json-object, "id": json-value } =20 or =20 -{ "exec-oob": json-string, "arguments": json-object, "id": json-value } +.. code-block:: =20 - Where, + { "exec-oob": json-string, "arguments": json-object, "id": json-value } =20 -- The "execute" or "exec-oob" member identifies the command to be +Where: + +- The ``execute`` or ``exec-oob`` member identifies the command to be executed by the server. The latter requests out-of-band execution. -- The "arguments" member is used to pass any arguments required for the +- The ``arguments`` member is used to pass any arguments required for the execution of the command, it is optional when no arguments are required. Each command documents what contents will be considered - valid when handling the json-argument -- The "id" member is a transaction identification associated with the + valid when handling the json-argument. +- The ``id`` member is a transaction identification associated with the command execution, it is optional and will be part of the response - if provided. The "id" member can be any json-value. A json-number + if provided. The ``id`` member can be any json-value. A json-number incremented for each successive command works fine. =20 -The actual commands are documented in the QEMU QMP reference manual -docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}. +The actual commands are documented in the :doc:`qemu-qmp-ref`. =20 -2.3.1 Out-of-band execution ---------------------------- +Out-of-band execution +--------------------- =20 The server normally reads, executes and responds to one command after the other. The client therefore receives command responses in issue order. =20 -With out-of-band execution enabled via capability negotiation (section -4.), the server reads and queues commands as they arrive. It executes +With out-of-band execution enabled via `capabilities negotiation`_, +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: the command get executed right away, possibly overtaking prior in-band commands. The client may therefore @@ -129,8 +135,8 @@ receive such a command's response before responses from= prior in-band commands. =20 To be able to match responses back to their commands, the client needs -to pass "id" with out-of-band commands. Passing it with all commands -is recommended for clients that accept capability "oob". +to pass ``id`` with out-of-band commands. Passing it with all commands +is recommended for clients that accept capability ``oob``. =20 If the client sends in-band commands faster than the server can execute them, the server will stop reading requests until the request @@ -140,57 +146,61 @@ To ensure commands to be executed out-of-band get rea= d and executed, the client should have at most eight in-band commands in flight. =20 Only a few commands support out-of-band execution. The ones that do -have "allow-oob": true in output of query-qmp-schema. +have ``"allow-oob": true`` in the output of ``query-qmp-schema``. =20 -2.4 Commands Responses ----------------------- +Commands Responses +------------------ =20 There are two possible responses which the Server will issue as the result of a command execution: success or error. =20 -As long as the commands were issued with a proper "id" field, then the -same "id" field will be attached in the corresponding response message +As long as the commands were issued with a proper ``id`` field, then the +same ``id`` field will be attached in the corresponding response message so that requests and responses can match. Clients should drop all the -responses that have an unknown "id" field. +responses that have an unknown ``id`` field. =20 -2.4.1 success -------------- +Success +------- =20 The format of a success response is: =20 -{ "return": json-value, "id": json-value } +.. code-block:: =20 - Where, + { "return": json-value, "id": json-value } =20 -- The "return" member contains the data returned by the command, which +Where: + +- The ``return`` member contains the data returned by the command, which is defined on a per-command basis (usually a json-object or json-array of json-objects, but sometimes a json-number, json-string, or json-array of json-strings); it is an empty json-object if the - command does not return data -- The "id" member contains the transaction identification associated - with the command execution if issued by the Client + command does not return data. +- The ``id`` member contains the transaction identification associated + with the command execution if issued by the Client. =20 -2.4.2 error ------------ +Error +----- =20 The format of an error response is: =20 -{ "error": { "class": json-string, "desc": json-string }, "id": json-value= } +.. code-block:: =20 - Where, + { "error": { "class": json-string, "desc": json-string }, "id": json-val= ue } =20 -- The "class" member contains the error class name (eg. "GenericError") -- The "desc" member is a human-readable error message. Clients should +Where: + +- The ``class`` member contains the error class name (eg. ``"GenericError"= ``). +- The ``desc`` member is a human-readable error message. Clients should not attempt to parse this message. -- The "id" member contains the transaction identification associated with - the command execution if issued by the Client +- The ``id`` member contains the transaction identification associated with + the command execution if issued by the Client. =20 -NOTE: Some errors can occur before the Server is able to read the "id" mem= ber, -in these cases the "id" member will not be part of the error response, even +NOTE: Some errors can occur before the Server is able to read the ``id`` m= ember; +in these cases the ``id`` member will not be part of the error response, e= ven if provided by the client. =20 -2.5 Asynchronous events ------------------------ +Asynchronous events +------------------- =20 As a result of state changes, the Server may send messages unilaterally to the Client at any time, when not in the middle of any other @@ -198,44 +208,45 @@ response. They are called "asynchronous events". =20 The format of asynchronous events is: =20 -{ "event": json-string, "data": json-object, - "timestamp": { "seconds": json-number, "microseconds": json-number } } +.. code-block:: =20 - Where, + { "event": json-string, "data": json-object, + "timestamp": { "seconds": json-number, "microseconds": json-number } } =20 -- The "event" member contains the event's name -- The "data" member contains event specific data, which is defined in a - per-event basis, it is optional -- The "timestamp" member contains the exact time of when the event +Where: + +- The ``event`` member contains the event's name. +- The ``data`` member contains event specific data, which is defined in a + per-event basis. It is optional. +- The ``timestamp`` member contains the exact time of when the event occurred in the Server. It is a fixed json-object with time in seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if there is a failure to retrieve host time, both members of the timestamp will be set to -1. =20 -The actual asynchronous events are documented in the QEMU QMP -reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}. +The actual asynchronous events are documented in the :doc:`qemu-qmp-ref`. =20 Some events are rate-limited to at most one per second. If additional "similar" events arrive within one second, all but the last one are dropped, and the last one is delayed. "Similar" normally means same event type. =20 -2.6 Forcing the JSON parser into known-good state -------------------------------------------------- +Forcing the JSON parser into known-good state +--------------------------------------------- =20 Incomplete or invalid input can leave the server's JSON parser in a state where it can't parse additional commands. To get it back into known-good state, the client should provoke a lexical error. =20 The cleanest way to do that is sending an ASCII control character -other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new -line). +other than ``\t`` (horizontal tab), ``\r`` (carriage return), or +``\n`` (new line). =20 Sadly, older versions of QEMU can fail to flag this as an error. If a client needs to deal with them, it should send a 0xFF byte. =20 -2.7 QGA Synchronization ------------------------ +QGA Synchronization +------------------- =20 When a client connects to QGA over a transport lacking proper connection semantics such as virtio-serial, QGA may have read partial @@ -243,86 +254,106 @@ input from a previous client. The client needs to f= orce QGA's parser into known-good state using the previous section's technique. Moreover, the client may receive output a previous client didn't read. To help with skipping that output, QGA provides the -'guest-sync-delimited' command. Refer to its documentation for +``guest-sync-delimited`` command. Refer to its documentation for details. =20 =20 -3. QMP Examples -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +QMP Examples +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 This section provides some examples of real QMP usage, in all of them -"C" stands for "Client" and "S" stands for "Server". +``->`` marks text sent by the Client and ``<-`` marks replies by the Serve= r. =20 -3.1 Server greeting -------------------- +.. admonition:: Example =20 -S: { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3}, - "package": "v3.0.0"}, "capabilities": ["oob"] } } + Server greeting =20 -3.2 Capabilities negotiation ----------------------------- + .. code-block:: QMP =20 -C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } } -S: { "return": {}} + <- { "QMP": {"version": {"qemu": {"micro": 0, "minor": 0, "major": 3}, + "package": "v3.0.0"}, "capabilities": ["oob"] } } =20 -3.3 Simple 'stop' execution ---------------------------- +.. admonition:: Example =20 -C: { "execute": "stop" } -S: { "return": {} } + Capabilities negotiation =20 -3.4 KVM information -------------------- + .. code-block:: QMP =20 -C: { "execute": "query-kvm", "id": "example" } -S: { "return": { "enabled": true, "present": true }, "id": "example"} + -> { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] }= } + <- { "return": {}} =20 -3.5 Parsing error ------------------- +.. admonition:: Example =20 -C: { "execute": } -S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } } + Simple 'stop' execution =20 -3.6 Powerdown event -------------------- + .. code-block:: QMP =20 -S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 }, - "event": "POWERDOWN" } + -> { "execute": "stop" } + <- { "return": {} } =20 -3.7 Out-of-band execution -------------------------- +.. admonition:: Example =20 -C: { "exec-oob": "migrate-pause", "id": 42 } -S: { "id": 42, - "error": { "class": "GenericError", - "desc": "migrate-pause is currently only supported during postcopy-a= ctive state" } } + KVM information + + .. code-block:: QMP + + -> { "execute": "query-kvm", "id": "example" } + <- { "return": { "enabled": true, "present": true }, "id": "example"} + +.. admonition:: Example + + Parsing error + + .. code-block:: QMP + + -> { "execute": } + <- { "error": { "class": "GenericError", "desc": "Invalid JSON syntax"= } } + +.. admonition:: Example + + Powerdown event + + .. code-block:: QMP + + <- { "timestamp": { "seconds": 1258551470, "microseconds": 802384 }, + "event": "POWERDOWN" } + +.. admonition:: Example + + Out-of-band execution + + .. code-block:: QMP + + -> { "exec-oob": "migrate-pause", "id": 42 } + <- { "id": 42, + "error": { "class": "GenericError", + "desc": "migrate-pause is currently only supported during postco= py-active state" } } =20 =20 -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 +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 =20 When a Client successfully establishes a connection, the Server is in Capabilities Negotiation mode. =20 -In this mode only the qmp_capabilities command is allowed to run, all -other commands will return the CommandNotFound error. Asynchronous +In this mode only the ``qmp_capabilities`` command is allowed to run; all +other commands will return the ``CommandNotFound`` error. Asynchronous messages are not delivered either. =20 -Clients should use the qmp_capabilities command to enable capabilities -advertised in the Server's greeting (section '2.2 Server Greeting') they -support. +Clients should use the ``qmp_capabilities`` command to enable capabilities +advertised in the `Server Greeting`_ which they support. =20 -When the qmp_capabilities command is issued, and if it does not return an -error, the Server enters in Command mode where capabilities changes take -effect, all commands (except qmp_capabilities) are allowed and asynchronous +When the ``qmp_capabilities`` command is issued, and if it does not return= an +error, the Server enters Command mode where capabilities changes take +effect, all commands (except ``qmp_capabilities``) are allowed and asynchr= onous messages are delivered. =20 -5 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=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 All protocol changes or new features which modify the protocol format in an incompatible way are disabled by default and will be advertised by the -capabilities array (section '2.2 Server Greeting'). Thus, Clients can check +capabilities array (in the `Server Greeting`_). Thus, Clients can check that array and enable the capabilities they support. =20 The QMP Server performs a type check on the arguments to a command. It @@ -337,12 +368,12 @@ However, Clients must not assume any particular: =20 - Length of json-arrays - Size of json-objects; in particular, future versions of QEMU may add - new keys and Clients should be able to ignore them. + new keys and Clients should be able to ignore them - Order of json-object members or json-array elements - Amount of errors generated by a command, that is, new errors can be added to any existing command in newer versions of the Server =20 -Any command or member name beginning with "x-" is deemed experimental, +Any command or member name beginning with ``x-`` is deemed experimental, and may be withdrawn or changed in an incompatible manner in a future release. =20 @@ -350,8 +381,8 @@ Of course, the Server does guarantee to send valid JSON= . But apart from this, a Client should be "conservative in what they send, and liberal in what they accept". =20 -6. Downstream extension of QMP -=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 +Downstream extension of QMP +=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 We recommend that downstream consumers of QEMU do *not* modify QMP. Management tools should be able to support both upstream and downstream @@ -363,23 +394,25 @@ avoid modifying QMP. Both upstream and downstream ne= ed to take care to preserve long-term compatibility and interoperability. =20 To help with that, QMP reserves JSON object member names beginning with -'__' (double underscore) for downstream use ("downstream names"). This +``__`` (double underscore) for downstream use ("downstream names"). This means upstream will never use any downstream names for its commands, arguments, errors, asynchronous events, and so forth. =20 -Any new names downstream wishes to add must begin with '__'. To +Any new names downstream wishes to add must begin with ``__``. To ensure compatibility with other downstreams, it is strongly -recommended that you prefix your downstream names with '__RFQDN_' where +recommended that you prefix your downstream names with ``__RFQDN_`` where RFQDN is a valid, reverse fully qualified domain name which you control. For example, a qemu-kvm specific monitor command would be: =20 +.. code-block:: + (qemu) __org.linux-kvm_enable_irqchip =20 -Downstream must not change the server greeting (section 2.2) other than +Downstream must not change the `server greeting`_ other than to offer additional capabilities. But see below for why even that is discouraged. =20 -Section '5 Compatibility Considerations' applies to downstream as well +The section `Compatibility Considerations`_ applies to downstream as well as to upstream, obviously. It follows that downstream must behave exactly like upstream for any input not containing members with downstream names ("downstream members"), except it may add members diff --git a/qapi/control.json b/qapi/control.json index 6a7c5af882a..a91fa334079 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -27,7 +27,7 @@ # Notes: This command is valid exactly when first connecting: it must # be issued before any other command will be accepted, and will # fail once the monitor is accepting other commands. (see qemu -# docs/interop/qmp-spec.txt) +# docs/interop/qmp-spec.rst) # # The QMP client needs to explicitly enable QMP capabilities, # otherwise all the QMP capabilities will be turned off by @@ -46,7 +46,7 @@ # connection, used for agreeing on particular QMP extension behaviors. # # @oob: QMP ability to support out-of-band requests. (Please refer to -# qmp-spec.txt for more information on OOB) +# qmp-spec.rst for more information on OOB) # # Since: 2.12 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 31e0b364547..6594afba312 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -29,7 +29,8 @@ # -> data issued by the Client # <- Server data response # -# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) +# Please refer to the +# :doc:`QEMU Machine Protocol Specification ` # for detailed information on the Server command and response formats. ## =20 diff --git a/qobject/json-lexer.c b/qobject/json-lexer.c index 632320d72d5..51341d96e49 100644 --- a/qobject/json-lexer.c +++ b/qobject/json-lexer.c @@ -139,7 +139,7 @@ static const uint8_t json_lexer[][256] =3D { * bytes '\xFE', '\xFF'. Structural characters and line * endings are promising resynchronization points. Clients * may use the others to force the JSON parser into known-good - * state; see docs/interop/qmp-spec.txt. + * state; see docs/interop/qmp-spec.rst. */ [0 ... 0x1F] =3D IN_START | LOOKAHEAD, [0x20 ... 0xFD] =3D IN_RECOVERY, diff --git a/python/qemu/qmp/models.py b/python/qemu/qmp/models.py index de87f878047..da52848d5a7 100644 --- a/python/qemu/qmp/models.py +++ b/python/qemu/qmp/models.py @@ -54,7 +54,7 @@ def __repr__(self) -> str: =20 class Greeting(Model): """ - Defined in qmp-spec.txt, section 2.2, "Server Greeting". + Defined in qmp-spec.rst, section "Server Greeting". =20 :param raw: The raw Greeting object. :raise KeyError: If any required fields are absent. @@ -82,7 +82,7 @@ def _asdict(self) -> Dict[str, object]: =20 class QMPGreeting(Model): """ - Defined in qmp-spec.txt, section 2.2, "Server Greeting". + Defined in qmp-spec.rst, section "Server Greeting". =20 :param raw: The raw QMPGreeting object. :raise KeyError: If any required fields are absent. @@ -104,7 +104,7 @@ def __init__(self, raw: Mapping[str, Any]): =20 class ErrorResponse(Model): """ - Defined in qmp-spec.txt, section 2.4.2, "error". + Defined in qmp-spec.rst, section "Error". =20 :param raw: The raw ErrorResponse object. :raise KeyError: If any required fields are absent. @@ -126,7 +126,7 @@ def __init__(self, raw: Mapping[str, Any]): =20 class ErrorInfo(Model): """ - Defined in qmp-spec.txt, section 2.4.2, "error". + Defined in qmp-spec.rst, section "Error". =20 :param raw: The raw ErrorInfo object. :raise KeyError: If any required fields are absent. diff --git a/python/qemu/qmp/qmp_client.py b/python/qemu/qmp/qmp_client.py index 9d73ae6e7ad..2a817f9db33 100644 --- a/python/qemu/qmp/qmp_client.py +++ b/python/qemu/qmp/qmp_client.py @@ -369,7 +369,7 @@ async def _on_message(self, msg: Message) -> None: # This is very likely a server parsing error. # It doesn't inherently belong to any pending execution. # Instead of performing clever recovery, just terminate. - # See "NOTE" in qmp-spec.txt, section 2.4.2 + # See "NOTE" in qmp-spec.rst, section "Error". raise ServerParseError( ("Server sent an error response without an ID, " "but there are no ID-less executions pending. " @@ -377,7 +377,7 @@ async def _on_message(self, msg: Message) -> None: msg ) =20 - # qmp-spec.txt, section 2.4: + # qmp-spec.rst, section "Commands Responses": # 'Clients should drop all the responses # that have an unknown "id" field.' self.logger.log( --=20 2.34.1 From nobody Tue May 14 21:33:02 2024 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=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1684167800; cv=none; d=zohomail.com; s=zohoarc; b=Xv6wfV196BHN98bt7dWbKc8grQAiwo3RZ5jL6C/+23e4VkhxGmhCwQ1AKYzQHV3ICY8Yxy0fqmWI1OYpFUbelENdnwNu5ot76TEg5SAziSErRaXKVd+H86++R/YLYGKytFfOpyg8H+M8RU4AUhTX3mHvSs1uB2N8ww18YoNks0M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1684167800; h=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=guoQvu7q9W2yxt0cEFeDYnD/GAjXS0PXF9GI5TpOJx4=; b=D/Yc/9eNT5or60T+cymSgFBtuQpjE8GIOsWEBYxYuJpgsojn4YK0h0PtKNrIesYAzROXYKJfrGmNDhmISH4s8KZtxwo9LhSaYOmq0bQGHd6h8B0YDKcrFcTw/7RgWRhI/cOM5mG+pXpqHqzA/PPN8Dz9TK6XVZz5aXTSYLBaAjs= 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 1684167800433286.68535407420063; Mon, 15 May 2023 09:23:20 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pyayU-0001J4-1W; Mon, 15 May 2023 12:23:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pyayK-0001DV-Qo for qemu-devel@nongnu.org; Mon, 15 May 2023 12:22:54 -0400 Received: from mail-wm1-x32d.google.com ([2a00:1450:4864:20::32d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pyayH-0005Mr-E2 for qemu-devel@nongnu.org; Mon, 15 May 2023 12:22:52 -0400 Received: by mail-wm1-x32d.google.com with SMTP id 5b1f17b1804b1-3f423521b10so64331365e9.0 for ; Mon, 15 May 2023 09:22:49 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id h12-20020adffd4c000000b003063176ef09sm278203wrs.6.2023.05.15.09.22.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 15 May 2023 09:22:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1684167768; x=1686759768; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=guoQvu7q9W2yxt0cEFeDYnD/GAjXS0PXF9GI5TpOJx4=; b=xwMyOBKuCs5Web5eoA6nCFlKh4k6xnODg0C3EFRdb6ZkCPKlW/u4NigSozTWEdjv+p 7Wt61zYRoyj0w9/1H0U+L2d4+L6zuYn9D6LGCmWvPVcdk0dbe50kmaPF1g/lFNt+NBNs zMvK7TQzt8G69vcqxYxcZHqtS1jfNADeT/YVQWjpbanapAokph52DlBvytmnLG70Q3zf 1Hy+8CVfOrGfkbpZ4BqIKYrjSlxYFUzQuMSzN9cyAn/R3zxDa1GAsxZ9+iyPBh7Qdnnk WhrSBasVObWQBQ2uxLk3UArcySlVFL9waSzancpefryMonQ9JkG3wZ8nkAuX5bj93V70 OjIQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1684167768; x=1686759768; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=guoQvu7q9W2yxt0cEFeDYnD/GAjXS0PXF9GI5TpOJx4=; b=CSTjGF+mVWmEM2tpz8WekcHxXh5ahd7vdivrsfvNxOBW1creWPk9qPXhwlOkSLQ8ir luPjOwhlP5WCQFHnoZ2x07NEJYD7d24C+E4eAAxj/T0x0atwhYmYcDx1ZvgedaXDIfpY /P/4SAvX0MKSI1lFndHymTiNkrHLbd0htl8atfiUB4gDACHbFFetqJHeoFJ0xlURz30G llMxpLX1+xtvKi2t/73vQZizafL79UroCwlGWQHXOA2Lfj7bBrMwm8DKiwmi8cKuyHAE Fuq8SoVl1JPAQv6PPVINAagW9bbT2S1VOBrs7+jOn6BkUVTWXRmoQwNEnz6tF7kYdsKB 4xdA== X-Gm-Message-State: AC+VfDwwyR0Ghb9Pd8ew61Awg1L7gCr6W/xEkE2S5USuF8qgAP3qPUcQ lUoLrGfAJuZMsG5JlX7IaPvZEdurnkLmXNRfsw0= X-Google-Smtp-Source: ACHHUZ7LTyF4Gyq8szmT5zGQ/nOHIKZ2653C1xMHew7TkgMkuOv349c6OXNBtA48KtyznvieI6Jldg== X-Received: by 2002:a5d:69cc:0:b0:306:42bb:53be with SMTP id s12-20020a5d69cc000000b0030642bb53bemr24099081wrw.10.1684167767915; Mon, 15 May 2023 09:22:47 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Cc: Markus Armbruster , Eric Blake Subject: [PATCH v3 2/3] docs/interop/qmp-spec: Update error description for parsing errors Date: Mon, 15 May 2023 17:22:44 +0100 Message-Id: <20230515162245.3964307-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230515162245.3964307-1-peter.maydell@linaro.org> References: <20230515162245.3964307-1-peter.maydell@linaro.org> MIME-Version: 1.0 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=2a00:1450:4864:20::32d; envelope-from=peter.maydell@linaro.org; helo=mail-wm1-x32d.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1684167802368100007 Content-Type: text/plain; charset="utf-8" The description text for a parsing error has changed since the spec doc was first written; update the example in the docs. Suggested-by: Markus Armbruster Signed-off-by: Peter Maydell Reviewed-by: Eric Blake Reviewed-by: Markus Armbruster --- docs/interop/qmp-spec.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/interop/qmp-spec.rst b/docs/interop/qmp-spec.rst index bfad570a160..2609b3ff9b2 100644 --- a/docs/interop/qmp-spec.rst +++ b/docs/interop/qmp-spec.rst @@ -307,7 +307,7 @@ This section provides some examples of real QMP usage, = in all of them .. code-block:: QMP =20 -> { "execute": } - <- { "error": { "class": "GenericError", "desc": "Invalid JSON syntax"= } } + <- { "error": { "class": "GenericError", "desc": "JSON parse error, ex= pecting value" } } =20 .. admonition:: Example =20 --=20 2.34.1 From nobody Tue May 14 21:33:02 2024 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=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1684167836; cv=none; d=zohomail.com; s=zohoarc; b=fEUluvaLY2e5TB+i+tvsWFZNpAX5eWwwH5w3ppgaeo8mBSGFSMeFrgLqXjdWq+HbeUdc/P35UjKdi8ZOyHbZ0ZQDK+ZZrx76QHAAJJUkpqthhBFdBavIescATBaxabsGBMMxDwH+Zm7GrjCNGthhqd2mcluvXHQp/didDW0XrX4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1684167836; h=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=l10MjSHz1E+vOlw/u/G09LRDhrQUH8Om/xwnB3b6ut0=; b=b40bBFzsMGihbFc6c2V+elBsWCAow0gJqhM48kgk2z4pQO/O4jc59yQzdvw0Cy4iDRWC+N4Hu5yuR0aondqPRBtLAKOJeIRfE+QWhK2FYuH9etnRkOX+5+ew/jTLkhPTfb+fNIbou7YDqImwGllsW8tMI8Zuhry2O77yk2n81nI= 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 1684167836641454.5424815989236; Mon, 15 May 2023 09:23:56 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pyayY-0001MM-AU; Mon, 15 May 2023 12:23:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pyayM-0001Fn-99 for qemu-devel@nongnu.org; Mon, 15 May 2023 12:22:56 -0400 Received: from mail-wr1-x42b.google.com ([2a00:1450:4864:20::42b]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pyayK-0005Mz-30 for qemu-devel@nongnu.org; Mon, 15 May 2023 12:22:54 -0400 Received: by mail-wr1-x42b.google.com with SMTP id ffacd0b85a97d-3078cc99232so9720223f8f.3 for ; Mon, 15 May 2023 09:22:49 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [2001:8b0:1d0::2]) by smtp.gmail.com with ESMTPSA id h12-20020adffd4c000000b003063176ef09sm278203wrs.6.2023.05.15.09.22.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 15 May 2023 09:22:48 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1684167768; x=1686759768; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=l10MjSHz1E+vOlw/u/G09LRDhrQUH8Om/xwnB3b6ut0=; b=sYgSS/W1casWGu692hV8A8Neqtlcyua+c7lB8gvje7at0sMMkYbljJtt/2eENy6Gb0 +ChB2/EmQgirOLG05CBkudzuloxWxPFelDyxdds1Hch8l/buYuPXIyQb/jxnWQjPshx2 DegTq+E0jQjAR9URkr5W0gjW9AqW3J57Bsu8inAZwE41z4Bx2OF6FpUEmHyQ85Z6oMU2 VHfjCq5g5S1KWKt+jsQVGVZGXh7+dQos7ARPCsRkr0KVE4vGAItk5xtR3Bvqj5fSTrTN vObTvoXOZkMZLaj3qSnXUONfpWPnUzsckJHthG2j+Yx1Da3SRjhCJOxarfVDSIJdnsT4 H/fQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1684167768; x=1686759768; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=l10MjSHz1E+vOlw/u/G09LRDhrQUH8Om/xwnB3b6ut0=; b=g1Qmwrz32IZNSMSWDWH6e5PuUC71eO0USpGw+hghdOivD61Zv3EOk4jmWkAurK4PX8 ovDM7SqNLsvHngJrYcYE7Gs3EpacGd39mjGQNLAjr9KnQnVgaSNjDWC40oFCIgVyqzyf ezUcWRgYyhYMkj0L9G909qZFMpP2cvzUipyED1GVYOVpnGwMhU50ZhGVjJchCpL1V5mE r2EMFt42nd0YXXRVYgMflLC9UUmWSnwFio0+fCZJaEGxtpZX++GX+Cb2CH9SI13xljF5 oZr6SuGCwgZhGc+dvkSO+l4sexOzUHtVkOWr6pqYINQ3JsOa5oPLaNcXFvEhREFPuyBz oDmA== X-Gm-Message-State: AC+VfDy9aQTqitXD1YDGWI7tvEz2nhn+xyiSQa7Fd/a4sItcef5JwusN oLBSYNOUOs9bUFh+TTAfSmEX1Q6n+mwRswm4cXU= X-Google-Smtp-Source: ACHHUZ5rGFsrOirVjWyKCLrsUuGDtiXOthl/zt3oUAsratMfD2FuLygLWULf2Pp4KAr5h+DIXgGrRw== X-Received: by 2002:a5d:4685:0:b0:306:4063:1afe with SMTP id u5-20020a5d4685000000b0030640631afemr28940908wrq.71.1684167768442; Mon, 15 May 2023 09:22:48 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Cc: Markus Armbruster , Eric Blake Subject: [PATCH v3 3/3] docs/interop: Delete qmp-intro.txt Date: Mon, 15 May 2023 17:22:45 +0100 Message-Id: <20230515162245.3964307-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230515162245.3964307-1-peter.maydell@linaro.org> References: <20230515162245.3964307-1-peter.maydell@linaro.org> MIME-Version: 1.0 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=2a00:1450:4864:20::42b; envelope-from=peter.maydell@linaro.org; helo=mail-wr1-x42b.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @linaro.org) X-ZM-MESSAGEID: 1684167838440100003 Content-Type: text/plain; charset="utf-8" qmp-intro.txt is quite small and provides very little information that isn't already in the documentation elsewhere. Fold the example command lines into qemu-options.hx, and delete the now-unneeded plain text document. While we're touching the qemu-options.hx documentation text, wordsmith it a little bit and improve the rST formatting. Reviewed-by: Eric Blake Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell --- docs/interop/qmp-intro.txt | 88 -------------------------------------- qemu-options.hx | 28 +++++++++--- 2 files changed, 22 insertions(+), 94 deletions(-) delete mode 100644 docs/interop/qmp-intro.txt diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt deleted file mode 100644 index 1c745a7af04..00000000000 --- a/docs/interop/qmp-intro.txt +++ /dev/null @@ -1,88 +0,0 @@ - QEMU Machine Protocol - =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D - -Introduction ------------- - -The QEMU Machine Protocol (QMP) allows applications to operate a -QEMU instance. - -QMP is JSON[1] based and features the following: - -- Lightweight, text-based, easy to parse data format -- Asynchronous messages support (ie. events) -- Capabilities Negotiation - -For detailed information on QMP's usage, please, refer to the following fi= les: - -o qmp-spec.txt QEMU Machine Protocol current specification -o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at build-= time) - -[1] https://www.json.org - -Usage ------ - -You can use the -qmp option to enable QMP. For example, the following -makes QMP available on localhost port 4444: - -$ qemu [...] -qmp tcp:localhost:4444,server=3Don,wait=3Doff - -However, for more flexibility and to make use of more options, the -mon -command-line option should be used. For instance, the following example -creates one HMP instance (human monitor) on stdio and one QMP instance -on localhost port 4444: - -$ qemu [...] -chardev stdio,id=3Dmon0 -mon chardev=3Dmon0,mode=3Dreadline \ - -chardev socket,id=3Dmon1,host=3Dlocalhost,port=3D4444,server= =3Don,wait=3Doff \ - -mon chardev=3Dmon1,mode=3Dcontrol,pretty=3Don - -Please, refer to QEMU's manpage for more information. - -Simple Testing --------------- - -To manually test QMP one can connect with telnet and issue commands by han= d: - -$ telnet localhost 4444 -Trying 127.0.0.1... -Connected to localhost. -Escape character is '^]'. -{ - "QMP": { - "version": { - "qemu": { - "micro": 0, - "minor": 0, - "major": 3 - }, - "package": "v3.0.0" - }, - "capabilities": [ - "oob" - ] - } -} - -{ "execute": "qmp_capabilities" } -{ - "return": { - } -} - -{ "execute": "query-status" } -{ - "return": { - "status": "prelaunch",=20 - "singlestep": false,=20 - "running": false - } -} - -Please refer to docs/interop/qemu-qmp-ref.* for a complete command -reference, generated from qapi/qapi-schema.json. - -QMP wiki page -------------- - -https://wiki.qemu.org/QMP diff --git a/qemu-options.hx b/qemu-options.hx index 42b9094c10f..920f9640155 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -4170,26 +4170,42 @@ DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ QEMU_ARCH_ALL) SRST ``-qmp dev`` - Like -monitor but opens in 'control' mode. + Like ``-monitor`` but opens in 'control' mode. For example, to make + QMP available on localhost port 4444:: + + -qmp tcp:localhost:4444,server=3Don,wait=3Doff + + Not all options are configurable via this syntax; for maximum + flexibility use the ``-mon`` option and an accompanying ``-chardev``. + ERST DEF("qmp-pretty", HAS_ARG, QEMU_OPTION_qmp_pretty, \ "-qmp-pretty dev like -qmp but uses pretty JSON formatting\n", QEMU_ARCH_ALL) SRST ``-qmp-pretty dev`` - Like -qmp but uses pretty JSON formatting. + Like ``-qmp`` but uses pretty JSON formatting. ERST =20 DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ "-mon [chardev=3D]name[,mode=3Dreadline|control][,pretty[=3Don|off]]\n= ", QEMU_ARCH_ALL) SRST ``-mon [chardev=3D]name[,mode=3Dreadline|control][,pretty[=3Don|off]]`` - Setup monitor on chardev name. ``mode=3Dcontrol`` configures=20 - a QMP monitor (a JSON RPC-style protocol) and it is not the - same as HMP, the human monitor that has a "(qemu)" prompt. - ``pretty`` is only valid when ``mode=3Dcontrol``,=20 + Set up a monitor connected to the chardev ``name``. + QEMU supports two monitors: the Human Monitor Protocol + (HMP; for human interaction), and the QEMU Monitor Protocol + (QMP; a JSON RPC-style protocol). + The default is HMP; ``mode=3Dcontrol`` selects QMP instead. + ``pretty`` is only valid when ``mode=3Dcontrol``, turning on JSON pretty printing to ease human reading and debugging. + + For example:: + + -chardev socket,id=3Dmon1,host=3Dlocalhost,port=3D4444,server=3Don,w= ait=3Doff \ + -mon chardev=3Dmon1,mode=3Dcontrol,pretty=3Don + + enables the QMP monitor on localhost port 4444 with pretty-printing. ERST =20 DEF("debugcon", HAS_ARG, QEMU_OPTION_debugcon, \ --=20 2.34.1