From patchwork Fri Apr 4 12:14:03 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038389 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id BCE59C36010 for ; Fri, 4 Apr 2025 12:15:54 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwM-0005rk-Oa; Fri, 04 Apr 2025 08:14:30 -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 1u0fwJ-0005qL-Kz for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:28 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwG-0005qE-GF for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:27 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768863; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=8BaBm7vzXaXVZ/BBtmGC2zL7uZD73yk8BYfS9G6HbH8=; b=L2kL8tT2PSVDpleNxtYrxQfJXxI3QkAhF75NPRUoOZ5Mqa4CfGHunwuCgJAW5vTclQD9uD M1MguJ03gL0nv8+5fKH/r1KvxhHQ0Bh/ZntIe3OrEr5evAax35ogoSdzynVEh0QvCCz+8I NPFgIJtKcmrR++jtFLcOE4eLnDyUEiA= Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-63-NyanbwtJPIi3YyjEOpz8yg-1; Fri, 04 Apr 2025 08:14:20 -0400 X-MC-Unique: NyanbwtJPIi3YyjEOpz8yg-1 X-Mimecast-MFC-AGG-ID: NyanbwtJPIi3YyjEOpz8yg_1743768859 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id BD68518004A9; Fri, 4 Apr 2025 12:14:18 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8A6161828AA4; Fri, 4 Apr 2025 12:14:16 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 64D8221E66E3; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 01/11] docs/devel/qapi-code-gen: Tidy up whitespace Date: Fri, 4 Apr 2025 14:14:03 +0200 Message-ID: <20250404121413.1743790-2-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Consistently use two spaces to separate sentences. Put "::" on a line of its own when it's preceded by whitespace. Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index f9cfe8721f..ad517349fc 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -763,8 +763,8 @@ Names beginning with ``x-`` used to signify "experimental". This convention has been replaced by special feature "unstable". Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let -you violate naming rules. Use for new code is strongly discouraged. See -`Pragma directives`_ for details. +you violate naming rules. Use for new code is strongly discouraged. +See `Pragma directives`_ for details. Downstream extensions @@ -1013,7 +1013,7 @@ like this:: document the success and the error response, respectively. "Errors" sections should be formatted as an rST list, each entry -detailing a relevant error condition. For example:: +detailing a relevant error condition. For example:: # Errors: # - If @device does not exist, DeviceNotFound @@ -1026,13 +1026,13 @@ definition. QMP). In other sections, the text is formatted, and rST markup can be used. -QMP Examples can be added by using the ``.. qmp-example::`` -directive. In its simplest form, this can be used to contain a single -QMP code block which accepts standard JSON syntax with additional server +QMP Examples can be added by using the ``.. qmp-example::`` directive. +In its simplest form, this can be used to contain a single QMP code +block which accepts standard JSON syntax with additional server directionality indicators (``->`` and ``<-``), and elisions (``...``). Optionally, a plaintext title may be provided by using the ``:title:`` -directive option. If the title is omitted, the example title will +directive option. If the title is omitted, the example title will default to "Example:". A simple QMP example:: @@ -1043,10 +1043,10 @@ A simple QMP example:: # -> { "execute": "query-block" } # <- { ... } -More complex or multi-step examples where exposition is needed before or -between QMP code blocks can be created by using the ``:annotated:`` -directive option. When using this option, nested QMP code blocks must be -entered explicitly with rST's ``::`` syntax. +More complex or multi-step examples where exposition is needed before +or between QMP code blocks can be created by using the ``:annotated:`` +directive option. When using this option, nested QMP code blocks must +be entered explicitly with rST's ``::`` syntax. Highlighting in non-QMP languages can be accomplished by using the ``.. code-block:: lang`` directive, and non-highlighted text can be @@ -1466,7 +1466,9 @@ 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. + +:: $ cat example-schema.json { 'struct': 'UserDefOne', From patchwork Fri Apr 4 12:14:04 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038420 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id CC263C3601E for ; Fri, 4 Apr 2025 12:16:49 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwj-000620-Gu; Fri, 04 Apr 2025 08:14:53 -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 1u0fwK-0005qm-Sa for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:28 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwH-0005qg-Ib for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:28 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768865; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=iNjWoivzUTHy9W+FeBB1QQ6/pfeYGmq23CdVrIdqrY4=; b=W4rdk3cCJXygS9ITtH7JVwbxGm9Nnnzp4stLj6GL/ChrFR4oO2/x7arHBRsneousBXEEaF /0vSC4GWu0zQV5W0cJMaXYl/q3YN8Fce1kspycCam1X6bVTv1TDpawZ1n8KG4/zX2ChbCD cPbhRS8ykOcUL9UdWH+3Zgdn+K1bSEM= Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-688-z5X0B3EhOLSmGwvk6heRvw-1; Fri, 04 Apr 2025 08:14:19 -0400 X-MC-Unique: z5X0B3EhOLSmGwvk6heRvw-1 X-Mimecast-MFC-AGG-ID: z5X0B3EhOLSmGwvk6heRvw_1743768858 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A8DFA19560BB; Fri, 4 Apr 2025 12:14:17 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id BAF07191F254; Fri, 4 Apr 2025 12:14:16 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6922B21E66E4; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 02/11] qapi/rocker: Tidy up query-rocker-of-dpa-flows example Date: Fri, 4 Apr 2025 14:14:04 +0200 Message-ID: <20250404121413.1743790-3-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org The command can return any number of RockerOfDpaFlow objects. The example shows it returning exactly two, with the second objecy's members elided. Tweak it so it elides elements after the first instead. Signed-off-by: Markus Armbruster --- qapi/rocker.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/rocker.json b/qapi/rocker.json index 51aa5b4930..0c7ef1f77c 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -254,7 +254,7 @@ # "action": {"goto-tbl": 10}, # "mask": {"in-pport": 4294901760} # }, -# {...}, +# ... # ]} ## { 'command': 'query-rocker-of-dpa-flows', From patchwork Fri Apr 4 12:14:05 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038388 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 66318C3601E for ; Fri, 4 Apr 2025 12:15:43 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwM-0005rq-OZ; Fri, 04 Apr 2025 08:14:30 -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 1u0fwJ-0005px-4V for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:27 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwG-0005q3-GA for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:26 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768863; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=IfohWAx7MrWs8vUk2D18jK5Clogpg7UJOIXFcAIoBFs=; b=Pms6F58t2Xpku2Lkdsnb3CZIdrtgeol2JypCXFou4UMTx8cma7abgKJL4edR/LsADKzY46 nazisWppaDC3wg+QhmswHRJ8AQyCO/fRHEhQrJSiig8VERpg3nTYbBQtNIjcXNnXftJrxS K1sF+NEN8rLNZnndsuCJbX1CUbWl4KI= Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-279-nSzNkYH9MGWkLn7UVN_JbA-1; Fri, 04 Apr 2025 08:14:18 -0400 X-MC-Unique: nSzNkYH9MGWkLn7UVN_JbA-1 X-Mimecast-MFC-AGG-ID: nSzNkYH9MGWkLn7UVN_JbA_1743768857 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 706761954B32; Fri, 4 Apr 2025 12:14:17 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 847E81828A9F; Fri, 4 Apr 2025 12:14:16 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6D50D21E66E5; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 03/11] docs/interop: Delete "QEMU Guest Agent Protocol Reference" TOC Date: Fri, 4 Apr 2025 14:14:05 +0200 Message-ID: <20250404121413.1743790-4-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org The "QEMU Guest Agent Protocol Reference" starts with the following table of contents: Contents * QEMU Guest Agent Protocol Reference * QEMU guest agent protocol commands and structs This is useless. Delete the entire TOC. Signed-off-by: Markus Armbruster --- docs/interop/qemu-ga-ref.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 19b5c7a549..25f6e24b03 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -1,9 +1,6 @@ QEMU Guest Agent Protocol Reference =================================== -.. contents:: - :depth: 3 - .. qapi-doc:: qga/qapi-schema.json :transmogrify: :namespace: QGA From patchwork Fri Apr 4 12:14:06 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038424 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id F2081C36010 for ; Fri, 4 Apr 2025 12:17:07 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwi-0005yl-Dw; Fri, 04 Apr 2025 08:14:52 -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 1u0fwK-0005qh-Fj for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:28 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwG-0005qT-Vk for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:28 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768864; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=OGz2Trd3J3eebcx0QBdUVwvGNT0slZ7erjafWGrzzwU=; b=fxZFFdpM59VcYxgTjuwsVW/glIAfRngLCdP1yP7VuyRL0PVO49poX1+/tLiGhte8YxgThn ff8qo83bzOiyF4742Rq90045byRJtU2UGP9gMk+JZ8ExBqpeoBtOpHyvubZ18bFYiq0UXV 6/inPpB1LHP3CLX310uLtQLXIBwIIzE= Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-182-95h9bhbdMm-f3E912L8plA-1; Fri, 04 Apr 2025 08:14:20 -0400 X-MC-Unique: 95h9bhbdMm-f3E912L8plA-1 X-Mimecast-MFC-AGG-ID: 95h9bhbdMm-f3E912L8plA_1743768859 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0F3FD19560B8; Fri, 4 Apr 2025 12:14:19 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id AE17319560AD; Fri, 4 Apr 2025 12:14:16 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7186321E66E9; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 04/11] docs/interop: Sanitize QMP reference manuals TOC Date: Fri, 4 Apr 2025 14:14:06 +0200 Message-ID: <20250404121413.1743790-5-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org The "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual" start with a table of contents that looks like this: Contents * Title of the manual * Title of first first-level section * Title of its first second-level section * Title of its second second-level section ... * Title of second first-level section ... The first level is useless. Drop it. While there, delete the option that limits the TOC to depth 3. Its actual depth was 3 before the patch, and is now 2. Signed-off-by: Markus Armbruster --- docs/interop/qemu-qmp-ref.rst | 2 +- docs/interop/qemu-storage-daemon-qmp-ref.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst index ef8792b53f..3bc1ca12b1 100644 --- a/docs/interop/qemu-qmp-ref.rst +++ b/docs/interop/qemu-qmp-ref.rst @@ -4,7 +4,7 @@ QEMU QMP Reference Manual ========================= .. contents:: - :depth: 3 + :local: .. qapi-doc:: qapi/qapi-schema.json :transmogrify: diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst index d0228d63b8..dc7bde262a 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -2,7 +2,7 @@ QEMU Storage Daemon QMP Reference Manual ======================================== .. contents:: - :depth: 3 + :local: .. qapi-doc:: storage-daemon/qapi/qapi-schema.json :transmogrify: From patchwork Fri Apr 4 12:14:07 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038390 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 4B165C3601E for ; Fri, 4 Apr 2025 12:15:58 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwU-0005uw-U2; Fri, 04 Apr 2025 08:14:40 -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 1u0fwL-0005rg-PE for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:30 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwI-0005qn-2U for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:29 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768865; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=JXFnKJMNYKMSFA9doJlGysHAAmio8OIcedRbeus1bfw=; b=aYnTONlgj2AXtgk6/kdsy9uJbMCD88vec7lxK5v7+tN5BbFmRi5jZW30YyfScxSvvvKwuE QPARnf4gBRw6ZtWplgmW95pbtleQStXZRxVl6omAfUstrkgfs/5yL9e3rwRhTf+RZQ873Z sjmUVGDO3QKkbfOTXqmu0MMQJARCtYI= Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-651-jYdV9sLpNyCI6hhEdmlqUQ-1; Fri, 04 Apr 2025 08:14:22 -0400 X-MC-Unique: jYdV9sLpNyCI6hhEdmlqUQ-1 X-Mimecast-MFC-AGG-ID: jYdV9sLpNyCI6hhEdmlqUQ_1743768861 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1EEA2180AF56; Fri, 4 Apr 2025 12:14:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7E1241809B6C; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7589D21E66EF; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 05/11] docs/devel/qapi-code-gen: Improve the part on qmp-example directive Date: Fri, 4 Apr 2025 14:14:07 +0200 Message-ID: <20250404121413.1743790-6-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ad517349fc..25a46fafb6 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1038,20 +1038,15 @@ default to "Example:". A simple QMP example:: # .. qmp-example:: - # :title: Using query-block # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-name" } + # <- { "return": { "name": "Fred" } } More complex or multi-step examples where exposition is needed before or between QMP code blocks can be created by using the ``:annotated:`` directive option. When using this option, nested QMP code blocks must be entered explicitly with rST's ``::`` syntax. -Highlighting in non-QMP languages can be accomplished by using the -``.. code-block:: lang`` directive, and non-highlighted text can be -achieved by omitting the language argument. - For example:: # .. qmp-example:: @@ -1061,11 +1056,21 @@ For example:: # This is a more complex example that can use # ``arbitrary rST syntax`` in its exposition:: # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-block" } + # <- { "return": [ + # { + # "device": "ide0-hd0", + # ... + # } + # ... + # ] } # # Above, lengthy output has been omitted for brevity. +Highlighting in non-QMP languages can be accomplished by using the +``.. code-block:: lang`` directive, and non-highlighted text can be +achieved by omitting the language argument. + Examples of complete definition documentation:: From patchwork Fri Apr 4 12:14:08 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038392 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 17D7CC36010 for ; Fri, 4 Apr 2025 12:16:16 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwi-00060w-Qy; Fri, 04 Apr 2025 08:14:52 -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 1u0fwL-0005rh-V6 for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:30 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwI-0005qv-95 for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:29 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768865; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=IRaQ20QHLxcMP2T+LCjH5Xz4ptiQxKPNqwa+AUFd49s=; b=KrBfiAHHIfjgHQ+lI1hrVRAEVO3LEfgbSIA2vuyfycj5z9WxR2gGSvG0kRkcIKs16sNZV3 bV1JLUb5GVW4zztfepkFS5q9yuLntauQxQzfT8AL6g0Tl3Q11L4fGVZHqseSUy/cw8FnBB ablib9LDKvUIiemtw3tOQJDLJ/bI+YA= Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-434-BB4XPyBOOTOryJGfT-7kUQ-1; Fri, 04 Apr 2025 08:14:21 -0400 X-MC-Unique: BB4XPyBOOTOryJGfT-7kUQ-1 X-Mimecast-MFC-AGG-ID: BB4XPyBOOTOryJGfT-7kUQ_1743768860 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8888A1800361; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 39D59180B488; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 79E1A21E6698; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax Date: Fri, 4 Apr 2025 14:14:08 +0200 Message-ID: <20250404121413.1743790-7-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Accept "... lorem ipsum ..." in addition to "...". Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 6 ++++-- docs/sphinx/qmp_lexer.py | 2 +- tests/qapi-schema/doc-good.json | 2 +- tests/qapi-schema/doc-good.out | 2 +- tests/qapi-schema/doc-good.txt | 2 +- 5 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 25a46fafb6..231cc0fecf 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1029,7 +1029,9 @@ used. QMP Examples can be added by using the ``.. qmp-example::`` directive. In its simplest form, this can be used to contain a single QMP code block which accepts standard JSON syntax with additional server -directionality indicators (``->`` and ``<-``), and elisions (``...``). +directionality indicators (``->`` and ``<-``), and elisions. An +elision is commonly ``...``, but it can also be or a pair of ``...`` +with text in between. Optionally, a plaintext title may be provided by using the ``:title:`` directive option. If the title is omitted, the example title will @@ -1062,7 +1064,7 @@ For example:: # "device": "ide0-hd0", # ... # } - # ... + # ... more ... # ] } # # Above, lengthy output has been omitted for brevity. diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py index a59de8a079..1bd1b81b70 100644 --- a/docs/sphinx/qmp_lexer.py +++ b/docs/sphinx/qmp_lexer.py @@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer): 'root': [ (r'-> ', token.Generic.Prompt), (r'<- ', token.Generic.Prompt), - (r' ?\.{3} ?', token.Generic.Prompt), + (r'\.{3}( .* \.{3})?', token.Generic.Prompt), ] } diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 0a4f139f83..14b808f909 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -212,7 +212,7 @@ # # -> "this example" # -# <- "has no title" +# <- ... has no title ... ## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object', diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 5773f1dd6d..dc8352eed4 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -217,7 +217,7 @@ another feature -> "this example" - <- "has no title" + <- ... has no title ... doc symbol=EVT_BOXED body= diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index cb37db606a..17a1d56ef1 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -264,7 +264,7 @@ Example:: -> "this example" - <- "has no title" + <- ... has no title ... "EVT_BOXED" (Event) From patchwork Fri Apr 4 12:14:09 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038421 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id C5486C36010 for ; Fri, 4 Apr 2025 12:16:49 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwl-00064a-4S; Fri, 04 Apr 2025 08:14:55 -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 1u0fwN-0005sc-3y for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:33 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwI-0005rD-J7 for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:30 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768865; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=znKfdpbF3/2StJjAWxS9fb6UEGm1rqVF6y0KVAFSMhQ=; b=NbCsKNRu7ZirZA/E6mFa614pj12blWGUyLlzLKpWcJKSKNkEfj40icl3JZCJy3rPsB41dv rclPhqTBnd4LCoz0N7jjl6X+4Os657rFyEEOMh6ARuYDtdixHUehzaH0Rl1AHAdO4NYSy9 7/nQco1xsrmRt452xeVfwB+/v7LDewQ= Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-343-Ab1QeL7oPaugxbqFVZqlYg-1; Fri, 04 Apr 2025 08:14:22 -0400 X-MC-Unique: Ab1QeL7oPaugxbqFVZqlYg-1 X-Mimecast-MFC-AGG-ID: Ab1QeL7oPaugxbqFVZqlYg_1743768861 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 57EE119560B3; Fri, 4 Apr 2025 12:14:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id BA994180B488; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7E03421E65D0; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 07/11] docs/sphinx/qmp_lexer: Highlight elisions like comments, not prompts Date: Fri, 4 Apr 2025 14:14:09 +0200 Message-ID: <20250404121413.1743790-8-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Signed-off-by: Markus Armbruster --- docs/sphinx/qmp_lexer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py index 1bd1b81b70..7b3b808d12 100644 --- a/docs/sphinx/qmp_lexer.py +++ b/docs/sphinx/qmp_lexer.py @@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer): 'root': [ (r'-> ', token.Generic.Prompt), (r'<- ', token.Generic.Prompt), - (r'\.{3}( .* \.{3})?', token.Generic.Prompt), + (r'\.{3}( .* \.{3})?', token.Comment.Multiline), ] } From patchwork Fri Apr 4 12:14:10 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038387 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 6FD46C369A1 for ; Fri, 4 Apr 2025 12:15:38 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwY-0005vO-MV; Fri, 04 Apr 2025 08:14:44 -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 1u0fwJ-0005qJ-EM for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:27 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwG-0005qO-Qi for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:27 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768864; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=10y11os0F0bwAH1rHrRBxrJEpoKummWpa4TbtalAzm4=; b=CIyAWYLqprz68VzzfbHLQVqWizt8nON7rFHm+1DLj67hSIYJZjapOlLcrRoWm82oXmeIxK ZgQNwhq/Qx7bhjSJWP3G5GRu1xJJZyiP5MBlSoco2QUSc/CW/JAPz5JxchJ3qqh8YJ1Fj8 XcuVjP5ZiJA9TdxPmdfTqseYBr5WIQU= Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-581-ZPVxiV1CN2iyH9lzqYFONA-1; Fri, 04 Apr 2025 08:14:22 -0400 X-MC-Unique: ZPVxiV1CN2iyH9lzqYFONA-1 X-Mimecast-MFC-AGG-ID: ZPVxiV1CN2iyH9lzqYFONA_1743768861 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D02BC180035C; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7E0FB1809B6A; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 822B021E65DA; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 08/11] qapi/qapi-schema: Update introduction for example notation Date: Fri, 4 Apr 2025 14:14:10 +0200 Message-ID: <20250404121413.1743790-9-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org The introduction explains example notation. The series merged in merge commit e6485190f77e (in 9.1) improved how they look in generated docs, but neglected to update the introduction accordingly. Do that now. Signed-off-by: Markus Armbruster --- qapi/qapi-schema.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index c41c01eb2a..0d027d5017 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -26,10 +26,10 @@ # # Example: # -# :: +# .. qmp-example:: # -# -> data issued by the Client -# <- Server data response +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... # # Please refer to the # :doc:`QEMU Machine Protocol Specification ` From patchwork Fri Apr 4 12:14:11 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038422 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 63BF0C36010 for ; Fri, 4 Apr 2025 12:16:55 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwg-0005xr-BZ; Fri, 04 Apr 2025 08:14:52 -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 1u0fwM-0005rl-4N for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:30 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwI-0005r6-DP for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:29 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768865; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=EkOx9DvyW+UIqO3JgCkIGQT82yofg2cjLuOSgtkw5CQ=; b=iX3dKQ3AFAho2l2OiE0j7g38KHigMJR9Oqg6VB7YPC+17t4XwHBpArTvPJWy8AH4SMGUYG cMy0htg8HstWySdrdp5f51VA1dQwGZ5raGR3lAD3MXqXOF6a4zKJtxxBZm2qGWd7n9VgYO sDWnlDflx3bd3MmTerYJd14w3QaoGlA= Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-266-_LBKEJaUOAeKjJIU82CScw-1; Fri, 04 Apr 2025 08:14:22 -0400 X-MC-Unique: _LBKEJaUOAeKjJIU82CScw-1 X-Mimecast-MFC-AGG-ID: _LBKEJaUOAeKjJIU82CScw_1743768861 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 762C61800258; Fri, 4 Apr 2025 12:14:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id EB68B1955BC2; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8651B21E65DC; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 09/11] qapi/qapi-schema: Address the introduction's bit rot Date: Fri, 4 Apr 2025 14:14:11 +0200 Message-ID: <20250404121413.1743790-10-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Cut the crap that stopped making sense years ago. Adjust the remainder. Signed-off-by: Markus Armbruster --- qapi/qapi-schema.json | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 0d027d5017..7bc600bb76 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -3,37 +3,24 @@ ## # = Introduction # -# This document describes all commands currently supported by QMP. +# This manual describes the commands and events supported by the QEMU +# Monitor Protocol (QMP). # # For locating a particular item, please see the `qapi-qmp-index`. # -# Most of the time their usage is exactly the same as in the user -# Monitor, this means that any other document which also describe -# commands (the manpage, QEMU's manual, etc) can and should be -# consulted. -# -# QMP has two types of commands: regular and query commands. Regular -# commands usually change the Virtual Machine's state someway, while -# query commands just return information. The sections below are -# divided accordingly. -# -# It's important to observe that all communication examples are -# formatted in a reader-friendly way, so that they're easier to -# understand. However, in real protocol usage, they're emitted as a -# single line. -# -# Also, the following notation is used to denote data flow: -# -# Example: +# The following notation is used in examples: # # .. qmp-example:: # # -> ... text sent by client (commands) ... # <- ... text sent by server (command responses and events) ... # +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# # Please refer to the # :doc:`QEMU Machine Protocol Specification ` -# for detailed information on the Server command and response formats. +# for the general format of commands, responses, and events. ## { 'include': 'pragma.json' } From patchwork Fri Apr 4 12:14:12 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038423 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id D31EBC3601E for ; Fri, 4 Apr 2025 12:16:55 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwk-00064C-Qt; Fri, 04 Apr 2025 08:14:54 -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 1u0fwN-0005sx-AM for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:33 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwI-0005rH-KE for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:31 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768865; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=d+Q4R+bot80f3nmL5oEcuMAs8/G4H/L4mRCskw2AAm4=; b=VI5XBEjbhrq4uQXUdTVDHF4regyuLzW8RrYj9J/LDobGSmz/CXya2Vz1gVaShezNbllBHH CioTNYowDwJcrp6lG3IXhyTXDmDIajSGL3+wlHxh5rkyrElYTD/DuV9bKddtTSnFV1T+U+ 7b2MQf1HhsZIank7LR49s9mDIR5bwAU= Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-651-pV2DxJMFMNWzzoEnHClOfA-1; Fri, 04 Apr 2025 08:14:22 -0400 X-MC-Unique: pV2DxJMFMNWzzoEnHClOfA-1 X-Mimecast-MFC-AGG-ID: pV2DxJMFMNWzzoEnHClOfA_1743768861 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 51170180035E; Fri, 4 Apr 2025 12:14:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id DE8291809B71; Fri, 4 Apr 2025 12:14:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8A61121E65DF; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 10/11] storage-daemon/qapi/qapi-schema: Add a proper introduction Date: Fri, 4 Apr 2025 14:14:12 +0200 Message-ID: <20250404121413.1743790-11-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Contents adapted from qapi/qapi-schema.json. Signed-off-by: Markus Armbruster --- storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json index 2a562ee32e..0427594c98 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -14,10 +14,26 @@ # storage daemon. ## -# = QEMU storage daemon protocol commands and structs +# = Introduction # -# For a concise listing of all commands, events, and types in the QEMU -# storage daemon, please consult the `qapi-qsd-index`. +# This manual describes the commands and events supported by the QEMU +# storage daemon QMP. +# +# For locating a particular item, please see the `qapi-qsd-index`. +# +# The following notation is used in examples: +# +# .. qmp-example:: +# +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... +# +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# +# Please refer to the +# :doc:`QEMU Machine Protocol Specification ` +# for the general format of commands, responses, and events. ## From patchwork Fri Apr 4 12:14:13 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 14038425 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 6C5F4C369A1 for ; Fri, 4 Apr 2025 12:17:09 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1u0fwj-000622-GW; Fri, 04 Apr 2025 08:14:53 -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 1u0fwN-0005sz-CS for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:33 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1u0fwI-0005rV-UT for qemu-devel@nongnu.org; Fri, 04 Apr 2025 08:14:31 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1743768866; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=qvKFkQYuyviiDeQyZBdwL+sGeoIrEhB6ebL4ypSh9sI=; b=EoRmm6WT/ktXyLZaW4uk13latFwhdboPIqNE4vSae6kU3eSPBe2Ko39GZg8fk81fDJr9da AwtdY6uEniwX+FDhHln/hnL5x7MWdsylsaI871K2+4n9UJs3JJ8pdeXc8MR8qhqgxKioqY pwITnXgACImqDs+B1aofsQzPFDU/FU0= Received: from mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-421-8A1wnMFSMSOjoH-XYKicZA-1; Fri, 04 Apr 2025 08:14:22 -0400 X-MC-Unique: 8A1wnMFSMSOjoH-XYKicZA-1 X-Mimecast-MFC-AGG-ID: 8A1wnMFSMSOjoH-XYKicZA_1743768861 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D19A719560BB; Fri, 4 Apr 2025 12:14:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.7]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 702C61809B63; Fri, 4 Apr 2025 12:14:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8E33621E65EC; Fri, 04 Apr 2025 14:14:13 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, kkostiuk@redhat.com, kwolf@redhat.com, jsnow@redhat.com, peter.maydell@linaro.org, eblake@redhat.com, jiri@resnulli.us, qemu-block@nongnu.org Subject: [PATCH 11/11] qga/qapi-schema: Add a proper introduction Date: Fri, 4 Apr 2025 14:14:13 +0200 Message-ID: <20250404121413.1743790-12-armbru@redhat.com> In-Reply-To: <20250404121413.1743790-1-armbru@redhat.com> References: <20250404121413.1743790-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.028, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Contents adapted from qapi/qapi-schema.json. Signed-off-by: Markus Armbruster --- qga/qapi-schema.json | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 35ec0e7db3..5316bfacbf 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -2,10 +2,24 @@ # vim: filetype=python ## -# = QEMU guest agent protocol commands and structs +# This manual describes the commands supported by the QEMU Guest +# Agent Protocol. # -# For a concise listing of all commands, events, and types in the QEMU -# guest agent, please consult the `qapi-qga-index`. +# For locating a particular item, please see the `qapi-qga-index`. +# +# The following notation is used in examples: +# +# .. qmp-example:: +# +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... +# +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# +# Please refer to the +# :doc:`QEMU Machine Protocol Specification ` +# for the general format of commands, responses, and events. ## { 'pragma': { 'doc-required': true } }