From patchwork Mon Feb 26 10:49:38 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571942 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 7861AC48BF6 for ; Mon, 26 Feb 2024 10:52:29 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZB-0002ih-Le; Mon, 26 Feb 2024 05:50:37 -0500 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 1reYYe-0002bU-EW for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:11 -0500 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 1reYYa-0003j7-9J for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:03 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944599; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=17y74wMY6sd/vutpX5ZtIbIwKMPi0TNnU7HU+eQC1L0=; b=cwqjVHfe7xDjfU2UljI1DnDsXThafmBjVZ3CO++GrqBXzQSm0PlK76MA7tmltuddeD4gnz b0V6huuk6w+ZO42ujA6013UMt1+jdG5RvYtsMJbioBmb5IQih+FzW7q00UroMtwqCi+J3x NSqiO8t5wauyEoFdEWF1b8fEGQuSr3w= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-643-LxDx6wmvO2G1y8_vlz4KTw-1; Mon, 26 Feb 2024 05:49:56 -0500 X-MC-Unique: LxDx6wmvO2G1y8_vlz4KTw-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id ABF583814E8C; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7F60310800; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 86E1221E66FB; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, Het Gala , Peter Xu , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 01/17] qapi: Misc cleanups to migrate QAPIs Date: Mon, 26 Feb 2024 11:49:38 +0100 Message-ID: <20240226104954.3781985-2-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.5 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org From: Het Gala Signed-off-by: Het Gala Message-ID: <20240216195659.189091-1-het.gala@nutanix.com> Reviewed-by: Peter Xu Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/migration.json | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 5a565d9b8d..5756e650b0 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1728,6 +1728,7 @@ # # -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } # <- { "return": {} } +# # -> { "execute": "migrate", # "arguments": { # "channels": [ { "channel-type": "main", @@ -1796,19 +1797,19 @@ # # 3. The uri format is the same as for -incoming # -# 5. For now, number of migration streams is restricted to one, +# 4. For now, number of migration streams is restricted to one, # i.e number of items in 'channels' list is just 1. # -# 4. The 'uri' and 'channels' arguments are mutually exclusive; +# 5. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # # Example: # # -> { "execute": "migrate-incoming", -# "arguments": { "uri": "tcp::4446" } } +# "arguments": { "uri": "tcp:0:4446" } } # <- { "return": {} } # -# -> { "execute": "migrate", +# -> { "execute": "migrate-incoming", # "arguments": { # "channels": [ { "channel-type": "main", # "addr": { "transport": "socket", @@ -1817,7 +1818,7 @@ # "port": "1050" } } ] } } # <- { "return": {} } # -# -> { "execute": "migrate", +# -> { "execute": "migrate-incoming", # "arguments": { # "channels": [ { "channel-type": "main", # "addr": { "transport": "exec", @@ -1825,7 +1826,7 @@ # "/some/sock" ] } } ] } } # <- { "return": {} } # -# -> { "execute": "migrate", +# -> { "execute": "migrate-incoming", # "arguments": { # "channels": [ { "channel-type": "main", # "addr": { "transport": "rdma", From patchwork Mon Feb 26 10:49:39 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571939 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 1DF06C48BF6 for ; Mon, 26 Feb 2024 10:52:19 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZE-0002lf-Sz; Mon, 26 Feb 2024 05:50:40 -0500 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 1reYYh-0002bi-4P for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:13 -0500 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 1reYYa-0003jR-JR for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944600; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3GWUHtjiTVTcyXYDkXaYPS+RGx2VTtD2GOtHpGZPuXw=; b=UrFscSb8Cpshshmol92OYeGl0AoFmM6gkZBDATl+7cbms9Mhk60vANXuONPLgrPjFbt6dn QL+0tKQ9MZKnIn0w4Rfh4MFsRLRsI1i1hqEVNKBZHZcRYaDTtOllQGdoeKdmRfOLSjJSZX D4ECxFSZsFjUkXEwnDVwrolhe2CBHw4= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-398-5EscpoW4Owy1Kn189Ql_uw-1; Mon, 26 Feb 2024 05:49:56 -0500 X-MC-Unique: 5EscpoW4Owy1Kn189Ql_uw-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id A957C3C00085; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7FD491C06714; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 89B8121E6682; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 02/17] tests/qapi-schema: Fix test 'QAPI rST doc' Date: Mon, 26 Feb 2024 11:49:39 +0100 Message-ID: <20240226104954.3781985-3-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.7 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org The test compares Sphinx plain-text output against a golden reference. To work on Windows hosts, it filters out carriage returns in both files. Unfortunately, the filter doesn't work: it creates an empty file. Comparing empty files always succeeds. Fix the filter, and update the golden reference to current Sphinx output. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-2-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-good.txt | 21 +++++++++------------ tests/qapi-schema/meson.build | 10 ++++++---- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index b3b76bd43f..879f6ff50a 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -44,7 +44,7 @@ Values ~~~~~~ "one" (**If: **"IFONE") - The _one_ {and only} + The _one_ {and only}, description on the same line "two" Not documented @@ -76,7 +76,7 @@ Members ~~~~~~~ "base1": "Enum" - the first member + description starts on a new line, minimally indented If @@ -90,7 +90,9 @@ If A paragraph -Another paragraph (but no "var": line) +Another paragraph + +"var1" is undocumented Members @@ -141,7 +143,8 @@ Members ~~~~~~~ "i": "int" - an integer "b" is undocumented + description starts on the same line remainder indented the same "b" + is undocumented "b": "boolean" Not documented @@ -172,10 +175,10 @@ Arguments ~~~~~~~~~ "arg1": "int" - the first argument + description starts on a new line, indented "arg2": "string" (optional) - the second argument + description starts on the same line remainder indented differently "arg3": "boolean" Not documented @@ -203,12 +206,6 @@ Returns "Object" -TODO -~~~~ - -frobnicate - - Notes ~~~~~ diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index af085f745d..44a9385563 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -273,15 +273,17 @@ if build_docs output: ['doc-good.txt.nocr'], input: qapi_doc_out[0], build_by_default: true, - command: [remove_cr, '@INPUT@'], - capture: true) + command: [remove_cr], + capture: true, + feed: true) qapi_doc_ref_nocr = custom_target('QAPI rST doc reference newline-sanitized', output: ['doc-good.ref.nocr'], input: files('doc-good.txt'), build_by_default: true, - command: [remove_cr, '@INPUT@'], - capture: true) + command: [remove_cr], + capture: true, + feed: true) test('QAPI rST doc', diff, args: ['-u', qapi_doc_ref_nocr[0], qapi_doc_out_nocr[0]], suite: ['qapi-schema', 'qapi-doc']) From patchwork Mon Feb 26 10:49:40 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571967 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 C99A0C48BF6 for ; Mon, 26 Feb 2024 10:54:51 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZE-0002lE-Mn; Mon, 26 Feb 2024 05:50:40 -0500 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 1reYYe-0002bY-RP for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:11 -0500 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 1reYYa-0003jB-9l for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:04 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944599; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=h2yzBnFOprxDw+Csx+aeQsNAM+XVPX1VtXlsW4CMXlo=; b=NRQ9p/EDMza1u6M+psuJvSawdOAV3WlihHxt/H0O50ND45Lczfq8KTnCcKOpQIG1f42yY+ AdFdifUMBfQr1b+xqIehC068BOxINsecyjXdy9zw7iZTaGgXOw0atD9dxchUXgibwvZwIf Nh3PpkdorD5OA3vxJTyJ0iE9A0fgVW8= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-554--AbrU9UnP4GBZ8YUv5avjQ-1; Mon, 26 Feb 2024 05:49:55 -0500 X-MC-Unique: -AbrU9UnP4GBZ8YUv5avjQ-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id AB5B3882087; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 88D2424D; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8CB6621E6691; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 03/17] tests/qapi-schema: Cover duplicate 'Features:' line Date: Mon, 26 Feb 2024 11:49:40 +0100 Message-ID: <20240226104954.3781985-4-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org We don't actually recognize the second 'Features:' line. Instead, we treat it as an untagged section. If it was followed by feature description, we'd reject that like "description of '@feat2:' follows a section". Less than clear. To be improved shortly. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-duplicate-features.err | 0 tests/qapi-schema/doc-duplicate-features.json | 11 ++++++++++ tests/qapi-schema/doc-duplicate-features.out | 22 +++++++++++++++++++ tests/qapi-schema/meson.build | 1 + 4 files changed, 34 insertions(+) create mode 100644 tests/qapi-schema/doc-duplicate-features.err create mode 100644 tests/qapi-schema/doc-duplicate-features.json create mode 100644 tests/qapi-schema/doc-duplicate-features.out diff --git a/tests/qapi-schema/doc-duplicate-features.err b/tests/qapi-schema/doc-duplicate-features.err new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/doc-duplicate-features.json b/tests/qapi-schema/doc-duplicate-features.json new file mode 100644 index 0000000000..a4d559e740 --- /dev/null +++ b/tests/qapi-schema/doc-duplicate-features.json @@ -0,0 +1,11 @@ +# Duplicate 'Features:' line + +## +# @foo: +# +# Features: +# @feat: mumble +# +# Features: +## +{ 'command': 'foo', 'features': ['feat'] } diff --git a/tests/qapi-schema/doc-duplicate-features.out b/tests/qapi-schema/doc-duplicate-features.out new file mode 100644 index 0000000000..43bfe1034b --- /dev/null +++ b/tests/qapi-schema/doc-duplicate-features.out @@ -0,0 +1,22 @@ +module ./builtin +object q_empty +enum QType + prefix QTYPE + member none + member qnull + member qnum + member qstring + member qdict + member qlist + member qbool +module doc-duplicate-features.json +command foo None -> None + gen=True success_response=True boxed=False oob=False preconfig=False + feature feat +doc symbol=foo + body= + + feature=feat +mumble + section=None +Features: diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 44a9385563..4c714c792f 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -66,6 +66,7 @@ schemas = [ 'doc-bad-union-member.json', 'doc-before-include.json', 'doc-before-pragma.json', + 'doc-duplicate-features.json', 'doc-duplicated-arg.json', 'doc-duplicated-return.json', 'doc-duplicated-since.json', From patchwork Mon Feb 26 10:49:41 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571937 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 D2404C54E4A for ; Mon, 26 Feb 2024 10:51:55 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZ0-0002gv-OC; Mon, 26 Feb 2024 05:50:28 -0500 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 1reYYd-0002b9-EC for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:03 -0500 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 1reYYZ-0003ie-6n for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:03 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944597; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=dQVYjud/iikXvNXQY29C36T+8gUjVDp21/TZqAtAHLE=; b=SYQiFSdauaOzhb7fVybWWBeuAry+0aGSLqlxBEKwWvMeKgTspM3b6k/8DjT2Rpv4L0ugQI TDqUvVejmq4LfChPjxQooVzGjIpyS7c4vlMPl1VQVV5WqIP0TapkxBhrIKV7ebP0JVijGE IWT6peV4x8OipAmCEMpVGB1IxehcgSw= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-215-TSmN0kQsOlGzpmX2cytH2A-1; Mon, 26 Feb 2024 05:49:56 -0500 X-MC-Unique: TSmN0kQsOlGzpmX2cytH2A-1 Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id B33001C382A5; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 90F21492BC7; Mon, 26 Feb 2024 10:49:55 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8F8EC21E66A3; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 04/17] tests/qapi-schema: Cover 'Features:' not followed by descriptions Date: Mon, 26 Feb 2024 11:49:41 +0100 Message-ID: <20240226104954.3781985-5-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.9 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org A 'Features:' line without any features is useless, but not an error now. However, a later commit will make it one, because that makes rejecting duplicate 'Features:' easier. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-4-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- tests/qapi-schema/doc-empty-features.err | 0 tests/qapi-schema/doc-empty-features.json | 10 ++++++++++ tests/qapi-schema/doc-empty-features.out | 19 +++++++++++++++++++ tests/qapi-schema/meson.build | 1 + 4 files changed, 30 insertions(+) create mode 100644 tests/qapi-schema/doc-empty-features.err create mode 100644 tests/qapi-schema/doc-empty-features.json create mode 100644 tests/qapi-schema/doc-empty-features.out diff --git a/tests/qapi-schema/doc-empty-features.err b/tests/qapi-schema/doc-empty-features.err new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/doc-empty-features.json b/tests/qapi-schema/doc-empty-features.json new file mode 100644 index 0000000000..06f814e45d --- /dev/null +++ b/tests/qapi-schema/doc-empty-features.json @@ -0,0 +1,10 @@ +# 'Features:' line not followed by feature descriptions + +## +# @foo: +# +# Features: +# +# not a description +## +{ 'command': 'foo' } diff --git a/tests/qapi-schema/doc-empty-features.out b/tests/qapi-schema/doc-empty-features.out new file mode 100644 index 0000000000..0f85623dde --- /dev/null +++ b/tests/qapi-schema/doc-empty-features.out @@ -0,0 +1,19 @@ +module ./builtin +object q_empty +enum QType + prefix QTYPE + member none + member qnull + member qnum + member qstring + member qdict + member qlist + member qbool +module doc-empty-features.json +command foo None -> None + gen=True success_response=True boxed=False oob=False preconfig=False +doc symbol=foo + body= + + section=None +not a description diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 4c714c792f..4b8329d070 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -71,6 +71,7 @@ schemas = [ 'doc-duplicated-return.json', 'doc-duplicated-since.json', 'doc-empty-arg.json', + 'doc-empty-features.json', 'doc-empty-section.json', 'doc-empty-symbol.json', 'doc-good.json', From patchwork Mon Feb 26 10:49:42 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571938 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 3492FC54E4A for ; Mon, 26 Feb 2024 10:52:15 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZA-0002iD-Tt; Mon, 26 Feb 2024 05:50:36 -0500 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 1reYYg-0002bd-E9 for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:11 -0500 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 1reYYa-0003jI-EF for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:05 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944599; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=GsgsOUSA5kYAMJI0r5yNAd03d7uI00midcMtl+CB+rU=; b=izOjFivmv1tmHrHHnZFd7lsLrp61iLH/pMDTBggHbggO+wXJrPhFWZ7VCaGD4vbdrZEPFp V9Vz3b9xXrBNbpWmMqY1gs4yXIrLkODper/ctHX6lePM+274/S0+PDv0sCfjp/SmduW+BW 4hFOW6bMwb6lOBwF7HTIZrjBLOZayMI= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-558-X50WwBmZONCldio5c-z9ag-1; Mon, 26 Feb 2024 05:49:58 -0500 X-MC-Unique: X50WwBmZONCldio5c-z9ag-1 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id E000C882082; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BDB73492BE2; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 925F921E660C; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 05/17] sphinx/qapidoc: Drop code to generate doc for simple union branch Date: Mon, 26 Feb 2024 11:49:42 +0100 Message-ID: <20240226104954.3781985-6-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.10 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Commit 4e99f4b12c0 (qapi: Drop simple unions) eliminated implicitly defined union branch types, except for the empty object type 'q_empty'. QAPISchemaGenRSTVisitor._nodes_for_members() still has code to generate documentation for implicitly defined union branch types. It does nothing for 'q_empty'. Simplify. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-5-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- docs/sphinx/qapidoc.py | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 05b809af27..488de23d72 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -180,17 +180,13 @@ def _nodes_for_members(self, doc, what, base=None, variants=None): if variants: for v in variants.variants: - if v.type.is_implicit(): - assert not v.type.base and not v.type.variants - for m in v.type.local_members: - term = self._nodes_for_one_member(m) - term.extend(self._nodes_for_variant_when(variants, v)) - dlnode += self._make_dlitem(term, None) - else: - term = [nodes.Text('The members of '), - nodes.literal('', v.type.doc_type())] - term.extend(self._nodes_for_variant_when(variants, v)) - dlnode += self._make_dlitem(term, None) + if v.type.name == 'q_empty': + continue + assert not v.type.is_implicit() + term = [nodes.Text('The members of '), + nodes.literal('', v.type.doc_type())] + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode += self._make_dlitem(term, None) if not dlnode.children: return [] From patchwork Mon Feb 26 10:49:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571968 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 A238BC48BF6 for ; Mon, 26 Feb 2024 10:55:10 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZH-0002o9-GK; Mon, 26 Feb 2024 05:50:43 -0500 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 1reYYi-0002bv-LV for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:14 -0500 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 1reYYc-0003jl-1V for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:08 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944600; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=NasNtuTWkk84bQqZrMVBAZ4AmcnDthULAoF1YQuHW10=; b=A4JknY5KzeuQLX8FbI4nCn241ES6w2AMPiYHSSzSfxXgJpwsyGS/T49WDVam+xI3b9uPcl t6yG7ZsAEJq6d+QA+ulP7FPSRcQn6HgrAPfYeYcubFXdQFfdAv87cOd0pneBRaBzQPI0PN qAUPtm8ooWR/RWt9gg5CokVcsXqZ/Ec= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-353-1wFyqJDbMpWmOpUziqdT3Q-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: 1wFyqJDbMpWmOpUziqdT3Q-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 082B2185A787; Mon, 26 Feb 2024 10:49:57 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BD6F44024857; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9537C21E60F3; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 06/17] qapi: Improve error position for bogus argument descriptions Date: Mon, 26 Feb 2024 11:49:43 +0100 Message-ID: <20240226104954.3781985-7-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org When documented arguments don't exist, the error message points to the beginning of the definition comment. Point to the first bogus argument description instead. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-6-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- scripts/qapi/parser.py | 4 +++- tests/qapi-schema/doc-bad-alternate-member.err | 2 +- tests/qapi-schema/doc-bad-boxed-command-arg.err | 2 +- tests/qapi-schema/doc-bad-command-arg.err | 2 +- tests/qapi-schema/doc-bad-enum-member.err | 2 +- tests/qapi-schema/doc-bad-event-arg.err | 2 +- tests/qapi-schema/doc-bad-feature.err | 2 +- tests/qapi-schema/doc-bad-union-member.err | 2 +- 8 files changed, 10 insertions(+), 8 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 88221b3c64..82db595dcf 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -472,6 +472,8 @@ class Section: # pylint: disable=too-few-public-methods def __init__(self, parser: QAPISchemaParser, name: Optional[str] = None): + # section source info, i.e. where it begins + self.info = parser.info # parser, for error messages about indentation self._parser = parser # optional section name (argument/member or section name) @@ -770,7 +772,7 @@ def check_args_section( if not section.member] if bogus: raise QAPISemError( - self.info, + args[bogus[0]].info, "documented %s%s '%s' %s not exist" % ( what, "s" if len(bogus) > 1 else "", diff --git a/tests/qapi-schema/doc-bad-alternate-member.err b/tests/qapi-schema/doc-bad-alternate-member.err index d7286bb57c..1f6b7d2fe4 100644 --- a/tests/qapi-schema/doc-bad-alternate-member.err +++ b/tests/qapi-schema/doc-bad-alternate-member.err @@ -1 +1 @@ -doc-bad-alternate-member.json:3: documented members 'aa', 'bb' do not exist +doc-bad-alternate-member.json:7: documented members 'aa', 'bb' do not exist diff --git a/tests/qapi-schema/doc-bad-boxed-command-arg.err b/tests/qapi-schema/doc-bad-boxed-command-arg.err index 7137af3ec9..d6793e7fd8 100644 --- a/tests/qapi-schema/doc-bad-boxed-command-arg.err +++ b/tests/qapi-schema/doc-bad-boxed-command-arg.err @@ -1 +1 @@ -doc-bad-boxed-command-arg.json:9: documented member 'a' does not exist +doc-bad-boxed-command-arg.json:11: documented member 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-command-arg.err b/tests/qapi-schema/doc-bad-command-arg.err index 18ed076cef..b76167ec60 100644 --- a/tests/qapi-schema/doc-bad-command-arg.err +++ b/tests/qapi-schema/doc-bad-command-arg.err @@ -1 +1 @@ -doc-bad-command-arg.json:3: documented member 'b' does not exist +doc-bad-command-arg.json:6: documented member 'b' does not exist diff --git a/tests/qapi-schema/doc-bad-enum-member.err b/tests/qapi-schema/doc-bad-enum-member.err index 7efeb47363..0aa8d8e8e2 100644 --- a/tests/qapi-schema/doc-bad-enum-member.err +++ b/tests/qapi-schema/doc-bad-enum-member.err @@ -1 +1 @@ -doc-bad-enum-member.json:3: documented member 'a' does not exist +doc-bad-enum-member.json:5: documented member 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-event-arg.err b/tests/qapi-schema/doc-bad-event-arg.err index d13cacf21f..90527d5f82 100644 --- a/tests/qapi-schema/doc-bad-event-arg.err +++ b/tests/qapi-schema/doc-bad-event-arg.err @@ -1 +1 @@ -doc-bad-event-arg.json:3: documented member 'a' does not exist +doc-bad-event-arg.json:5: documented member 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-feature.err b/tests/qapi-schema/doc-bad-feature.err index 49d1746c3d..3166c6a305 100644 --- a/tests/qapi-schema/doc-bad-feature.err +++ b/tests/qapi-schema/doc-bad-feature.err @@ -1 +1 @@ -doc-bad-feature.json:3: documented feature 'a' does not exist +doc-bad-feature.json:7: documented feature 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-union-member.err b/tests/qapi-schema/doc-bad-union-member.err index 6dd2726a65..cdf1225cab 100644 --- a/tests/qapi-schema/doc-bad-union-member.err +++ b/tests/qapi-schema/doc-bad-union-member.err @@ -1 +1 @@ -doc-bad-union-member.json:3: documented members 'a', 'b' do not exist +doc-bad-union-member.json:5: documented members 'a', 'b' do not exist From patchwork Mon Feb 26 10:49:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571936 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 DAC94C54E51 for ; Mon, 26 Feb 2024 10:51:55 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZG-0002ne-Nv; Mon, 26 Feb 2024 05:50:42 -0500 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 1reYYg-0002ba-FK for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:12 -0500 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 1reYYa-0003iy-8p for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:05 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944599; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ZFRSAdSZWmsUT3rCIgBsqGoAo8qw2YkRWizVDHUWmx0=; b=WGiRguGB7Mh+rlqyBRxPIcO4SOKJe9F5oIIkN/UNQI5b1aP97FrJpHK5mqPnU791fqaDLt jr3aL3TCtdUW/hT85NyuLckPiDTxjE6yVmfKaM7PJPJLTzgyfCmbhMa2rbFV4RP3FWv9OA D/i+DNPsu7hiqiC+ZYDczBuxElMVEno= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-482-oqheQmOkMYCHZQM3YvHQbA-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: oqheQmOkMYCHZQM3YvHQbA-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id E14E83C000B2; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BE0F5112132A; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 97F2121E60F4; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 07/17] qapi: Improve error position for bogus invalid "Returns" section Date: Mon, 26 Feb 2024 11:49:44 +0100 Message-ID: <20240226104954.3781985-8-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.3 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_TEMPERROR=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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org When something other than a command has a "Returns" section, the error message points to the beginning of the definition comment. Point to the "Returns" section instead. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- scripts/qapi/parser.py | 10 +++++++--- tests/qapi-schema/doc-invalid-return.err | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 82db595dcf..a771013959 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -759,9 +759,13 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: self.features[feature.name].connect(feature) def check_expr(self, expr: QAPIExpression) -> None: - if self.has_section('Returns') and 'command' not in expr: - raise QAPISemError(self.info, - "'Returns:' is only valid for commands") + if 'command' not in expr: + sec = next((sec for sec in self.sections + if sec.name == 'Returns'), + None) + if sec: + raise QAPISemError(sec.info, + "'Returns:' is only valid for commands") def check(self) -> None: diff --git a/tests/qapi-schema/doc-invalid-return.err b/tests/qapi-schema/doc-invalid-return.err index 2ad89c5941..bc5826de20 100644 --- a/tests/qapi-schema/doc-invalid-return.err +++ b/tests/qapi-schema/doc-invalid-return.err @@ -1 +1 @@ -doc-invalid-return.json:3: 'Returns:' is only valid for commands +doc-invalid-return.json:5: 'Returns:' is only valid for commands From patchwork Mon Feb 26 10:49:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571964 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 701B2C54E49 for ; Mon, 26 Feb 2024 10:54:20 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZD-0002km-I1; Mon, 26 Feb 2024 05:50:39 -0500 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 1reYYg-0002bb-DJ for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:12 -0500 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 1reYYZ-0003iu-Uj for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:05 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944599; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=xyTe3JJVicR2YT26xqzTwUPaKmO95AOFbOEBCZXay6s=; b=SmL2/1JnuwGDj1ahGDxI1mvDFS5RTugVYWWCpnoUWAvbz/21nRVWAKlxSdIzezxlADbL7P 1jmW2TupEgwVBrNO4Yoj8+SlPIs6B5aARXKQ0HK/s5I0qd6eBrINPk0dq3q8lF6AO6E2jX WOOCzDXgQhucfTbdXIEOWaD+FPVQoIw= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-482-Uk8jxVzeNcKiPai55bkwBA-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: Uk8jxVzeNcKiPai55bkwBA-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 08EDF85A599; Mon, 26 Feb 2024 10:49:57 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BDB931C060B1; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9AE4D21E60F5; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 08/17] qapi: Improve error message for empty doc sections Date: Mon, 26 Feb 2024 11:49:45 +0100 Message-ID: <20240226104954.3781985-9-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.7 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_HELO_TEMPERROR=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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Improve the message for an empty tagged section from empty doc section 'Note' to text required after 'Note:' and the message for an empty argument or feature description from empty doc section 'foo' to text required after '@foo:' Improve the error position to refer to the beginning of the empty section instead of its end. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-8-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- docs/sphinx/qapidoc.py | 4 ++-- scripts/qapi/parser.py | 14 +++++++------- tests/qapi-schema/doc-empty-section.err | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 488de23d72..1e8b4a70a1 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -239,8 +239,8 @@ def _nodes_for_features(self, doc): seen_item = False dlnode = nodes.definition_list() for section in doc.features.values(): - dlnode += self._make_dlitem([nodes.literal('', section.name)], - section.text) + dlnode += self._make_dlitem( + [nodes.literal('', section.member.name)], section.text) seen_item = True if not seen_item: diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index a771013959..43daf55860 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -476,9 +476,9 @@ def __init__(self, parser: QAPISchemaParser, self.info = parser.info # parser, for error messages about indentation self._parser = parser - # optional section name (argument/member or section name) + # section tag, if any ('Returns', '@name', ...) self.name = name - # section text without section name + # section text without tag self.text = '' # indentation to strip (None means indeterminate) self._indent = None if self.name else 0 @@ -700,7 +700,7 @@ def _start_symbol_section( raise QAPIParseError(self._parser, "'%s' parameter name duplicated" % name) assert not self.sections - new_section = QAPIDoc.ArgSection(self._parser, name) + new_section = QAPIDoc.ArgSection(self._parser, '@' + name) self._switch_section(new_section) symbols_dict[name] = new_section @@ -727,9 +727,9 @@ def _switch_section(self, new_section: 'QAPIDoc.Section') -> None: # We do not create anonymous sections unless there is # something to put in them; this is a parser bug. assert self._section.name - raise QAPIParseError( - self._parser, - "empty doc section '%s'" % self._section.name) + raise QAPISemError( + self._section.info, + "text required after '%s:'" % self._section.name) self._section = new_section @@ -748,7 +748,7 @@ def connect_member(self, member: 'QAPISchemaMember') -> None: "%s '%s' lacks documentation" % (member.role, member.name)) self.args[member.name] = QAPIDoc.ArgSection(self._parser, - member.name) + '@' + member.name) self.args[member.name].connect(member) def connect_feature(self, feature: 'QAPISchemaFeature') -> None: diff --git a/tests/qapi-schema/doc-empty-section.err b/tests/qapi-schema/doc-empty-section.err index ba7ba70125..5f03a6d733 100644 --- a/tests/qapi-schema/doc-empty-section.err +++ b/tests/qapi-schema/doc-empty-section.err @@ -1 +1 @@ -doc-empty-section.json:7:1: empty doc section 'Note' +doc-empty-section.json:6: text required after 'Note:' From patchwork Mon Feb 26 10:49:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571941 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 535F7C54E49 for ; Mon, 26 Feb 2024 10:52:29 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZ5-0002ha-Dg; Mon, 26 Feb 2024 05:50:32 -0500 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 1reYYc-0002b0-92 for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:03 -0500 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 1reYYZ-0003in-I6 for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:02 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944598; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=RbsmI2YIBgzD3a9xKSNh3LiAi39vXM047TKLXUMTa/0=; b=LmBk2G9liSSSlf+54QTW6am8X9kU5QZeHaQ5SMc2Krtkkw/l49AQM/ajI5Gecd3uVrmBWD XQkspHXwXRX0JPfLKWkRJ8LxqwPhkelg7aM0zL9e+v365/BZQtkfLeVb9zYWYY0grtmtI6 BF+gjsWItj4cZlJBn7aHJ2sUqEnOm/o= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-101-sngwXIwYNhK51eZDfusxww-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: sngwXIwYNhK51eZDfusxww-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 0D9FA2812FE3; Mon, 26 Feb 2024 10:49:57 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BE8231812; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9DE9721E5A40; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 09/17] qapi: Rename QAPIDoc.Section.name to .tag Date: Mon, 26 Feb 2024 11:49:46 +0100 Message-ID: <20240226104954.3781985-10-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Since the previous commit, QAPIDoc.Section.name is either None (untagged section) or the section's tag string ('Returns', '@name', ...). Rename it to .tag. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-9-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- docs/sphinx/qapidoc.py | 6 +++--- scripts/qapi/parser.py | 30 +++++++++++++++--------------- tests/qapi-schema/test-qapi.py | 2 +- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 1e8b4a70a1..8d428c64b0 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -258,11 +258,11 @@ def _nodes_for_sections(self, doc): """Return list of doctree nodes for additional sections""" nodelist = [] for section in doc.sections: - if section.name and section.name == 'TODO': + if section.tag and section.tag == 'TODO': # Hide TODO: sections continue - snode = self._make_section(section.name) - if section.name and section.name.startswith('Example'): + snode = self._make_section(section.tag) + if section.tag and section.tag.startswith('Example'): snode += self._nodes_for_example(section.text) else: self._parse_text_into_node(section.text, snode) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 43daf55860..cc69f4f770 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -471,17 +471,17 @@ class QAPIDoc: class Section: # pylint: disable=too-few-public-methods def __init__(self, parser: QAPISchemaParser, - name: Optional[str] = None): + tag: Optional[str] = None): # section source info, i.e. where it begins self.info = parser.info # parser, for error messages about indentation self._parser = parser # section tag, if any ('Returns', '@name', ...) - self.name = name + self.tag = tag # section text without tag self.text = '' # indentation to strip (None means indeterminate) - self._indent = None if self.name else 0 + self._indent = None if self.tag else 0 def append(self, line: str) -> None: line = line.rstrip() @@ -504,8 +504,8 @@ def append(self, line: str) -> None: class ArgSection(Section): def __init__(self, parser: QAPISchemaParser, - name: str): - super().__init__(parser, name) + tag: str): + super().__init__(parser, tag) self.member: Optional['QAPISchemaMember'] = None def connect(self, member: 'QAPISchemaMember') -> None: @@ -536,10 +536,10 @@ def __init__(self, parser: QAPISchemaParser, info: QAPISourceInfo): self._section = self.body self._append_line = self._append_body_line - def has_section(self, name: str) -> bool: - """Return True if we have a section with this name.""" + def has_section(self, tag: str) -> bool: + """Return True if we have a section with this tag.""" for i in self.sections: - if i.name == name: + if i.tag == tag: return True return False @@ -710,11 +710,11 @@ def _start_args_section(self, name: str) -> None: def _start_features_section(self, name: str) -> None: self._start_symbol_section(self.features, name) - def _start_section(self, name: Optional[str] = None) -> None: - if name in ('Returns', 'Since') and self.has_section(name): + def _start_section(self, tag: Optional[str] = None) -> None: + if tag in ('Returns', 'Since') and self.has_section(tag): raise QAPIParseError(self._parser, - "duplicated '%s' section" % name) - new_section = QAPIDoc.Section(self._parser, name) + "duplicated '%s' section" % tag) + new_section = QAPIDoc.Section(self._parser, tag) self._switch_section(new_section) self.sections.append(new_section) @@ -726,10 +726,10 @@ def _switch_section(self, new_section: 'QAPIDoc.Section') -> None: if self._section != self.body and not text: # We do not create anonymous sections unless there is # something to put in them; this is a parser bug. - assert self._section.name + assert self._section.tag raise QAPISemError( self._section.info, - "text required after '%s:'" % self._section.name) + "text required after '%s:'" % self._section.tag) self._section = new_section @@ -761,7 +761,7 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: def check_expr(self, expr: QAPIExpression) -> None: if 'command' not in expr: sec = next((sec for sec in self.sections - if sec.name == 'Returns'), + if sec.tag == 'Returns'), None) if sec: raise QAPISemError(sec.info, diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index 14f7b62a44..40095431ae 100755 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -130,7 +130,7 @@ def test_frontend(fname): for feat, section in doc.features.items(): print(' feature=%s\n%s' % (feat, section.text)) for section in doc.sections: - print(' section=%s\n%s' % (section.name, section.text)) + print(' section=%s\n%s' % (section.tag, section.text)) def open_test_result(dir_name, file_name, update): From patchwork Mon Feb 26 10:49:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571969 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 BC4B1C48BF6 for ; Mon, 26 Feb 2024 10:55:13 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZI-0002pD-2m; Mon, 26 Feb 2024 05:50:44 -0500 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 1reYYi-0002bu-Lj for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:14 -0500 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 1reYYc-0003jf-1f for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:08 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944600; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=fGjWcbnRDrafVL+gPn1YGVCIw7yG/XxNC4mi7ogESDA=; b=Kv1+VrgU5pIi39Dzj61TAFjXXso7dXgw1zjgzhdlEk0GMIbpnyUZrHqeQi1i39TbxNypuP w+sCBdi5JR6ixV9Usl5yU9XimkrXV3T+GPTFoNYl5/qB09BxOAea9nw3t43Shr0r5PczU3 EWbDWiCuD3q0XoHyWC/MNUf5130RLsQ= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-101-2V1JKz0oPTiXkDofIwR8HQ-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: 2V1JKz0oPTiXkDofIwR8HQ-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id E4F53882086; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C0C1E40C94A8; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id A0E2F21E5A41; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 10/17] qapi: Reject section heading in the middle of a doc comment Date: Mon, 26 Feb 2024 11:49:47 +0100 Message-ID: <20240226104954.3781985-11-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org docs/devel/qapi-code-gen.txt claims "A heading line must be the first line of the documentation comment block" since commit 55ec69f8b16 (docs/devel/qapi-code-gen.txt: Update to new rST backend conventions). Not true, we have code to make it work anywhere in a free-form doc comment: commit dcdc07a97cb (qapi: Make section headings start a new doc comment block). Make it true, for simplicity's sake. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-10-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- scripts/qapi/parser.py | 6 +++--- tests/qapi-schema/doc-good.json | 4 +++- tests/qapi-schema/doc-non-first-section.err | 1 + tests/qapi-schema/doc-non-first-section.json | 6 ++++++ tests/qapi-schema/doc-non-first-section.out | 0 5 files changed, 13 insertions(+), 4 deletions(-) create mode 100644 tests/qapi-schema/doc-non-first-section.err create mode 100644 tests/qapi-schema/doc-non-first-section.json create mode 100644 tests/qapi-schema/doc-non-first-section.out diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index cc69f4f770..3aefec1c2b 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -440,9 +440,9 @@ def get_doc(self, info: QAPISourceInfo) -> List['QAPIDoc']: self, "unexpected '=' markup in definition documentation") if cur_doc.body.text: - cur_doc.end_comment() - docs.append(cur_doc) - cur_doc = QAPIDoc(self, info) + raise QAPIParseError( + self, + "'=' heading must come first in a comment block") cur_doc.append(self.val) self.accept(False) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 24a84fe6d7..0479d16a01 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -9,7 +9,9 @@ ## # = Section -# +## + +## # == Subsection # # *with emphasis* diff --git a/tests/qapi-schema/doc-non-first-section.err b/tests/qapi-schema/doc-non-first-section.err new file mode 100644 index 0000000000..eeced2bca7 --- /dev/null +++ b/tests/qapi-schema/doc-non-first-section.err @@ -0,0 +1 @@ +doc-non-first-section.json:5:1: '=' heading must come first in a comment block diff --git a/tests/qapi-schema/doc-non-first-section.json b/tests/qapi-schema/doc-non-first-section.json new file mode 100644 index 0000000000..1590876061 --- /dev/null +++ b/tests/qapi-schema/doc-non-first-section.json @@ -0,0 +1,6 @@ +# = section must be first line + +## +# +# = Not first +## diff --git a/tests/qapi-schema/doc-non-first-section.out b/tests/qapi-schema/doc-non-first-section.out new file mode 100644 index 0000000000..e69de29bb2 From patchwork Mon Feb 26 10:49:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571940 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 CA699C54E49 for ; Mon, 26 Feb 2024 10:52:14 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZC-0002jI-AD; Mon, 26 Feb 2024 05:50:38 -0500 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 1reYYl-0002c4-SI for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:16 -0500 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 1reYYb-0003ji-8r for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:09 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944600; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=CXXewQuhqcc3dLgqmHKJHGoB1OoLgBUyB8OCWYriZ5g=; b=K4meG0jb6TRap2Zirs3+RnHaXndVe5L8HbuolYFPkitdAiHYcnL7/tWIx0Shc8HZHQg9jS EDmcauqN6xmc+F5Nxh9bMsGwj/53l8NeD7GkPGIpcCDjEYWMN35pnLHn39vEt6knOaTusW Q6GhIPstDYDZFV4wm2RrhT/7yg1hcq0= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-373-aZ8g3uJYOk2RNk0zVYQPMA-1; Mon, 26 Feb 2024 05:49:58 -0500 X-MC-Unique: aZ8g3uJYOk2RNk0zVYQPMA-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id C9635800074; Mon, 26 Feb 2024 10:49:57 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BE30110F57; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id A6BF021E5A47; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 11/17] qapi: Require descriptions and tagged sections to be indented Date: Mon, 26 Feb 2024 11:49:48 +0100 Message-ID: <20240226104954.3781985-12-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.5 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org By convention, we indent the second and subsequent lines of descriptions and tagged sections, except for examples. Turn this into a hard rule, and apply it to examples, too. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-11-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé [Straightforward conflicts in qapi/migration.json resolved] --- docs/devel/qapi-code-gen.rst | 15 +- qapi/acpi.json | 20 +- qapi/block-core.json | 868 ++++++++++++++++---------------- qapi/block.json | 274 +++++----- qapi/char.json | 172 +++---- qapi/control.json | 54 +- qapi/dump.json | 26 +- qapi/machine-target.json | 6 +- qapi/machine.json | 302 +++++------ qapi/migration.json | 690 ++++++++++++------------- qapi/misc-target.json | 110 ++-- qapi/misc.json | 172 +++---- qapi/net.json | 118 ++--- qapi/pci.json | 252 +++++----- qapi/qdev.json | 38 +- qapi/qom.json | 54 +- qapi/rdma.json | 14 +- qapi/replay.json | 16 +- qapi/rocker.json | 66 +-- qapi/run-state.json | 84 ++-- qapi/tpm.json | 36 +- qapi/trace.json | 12 +- qapi/transaction.json | 36 +- qapi/ui.json | 324 ++++++------ qapi/virtio.json | 778 ++++++++++++++-------------- qapi/yank.json | 24 +- scripts/qapi/parser.py | 3 + tests/qapi-schema/doc-good.json | 12 +- 28 files changed, 2289 insertions(+), 2287 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 756adc187e..77a40f3bdc 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -973,7 +973,7 @@ commands and events), member (for structs and unions), branch (for alternates), or value (for enums), a description of each feature (if any), and finally optional tagged sections. -Descriptions start with '\@name:'. The description text should be +Descriptions start with '\@name:'. The description text must be indented like this:: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed @@ -997,8 +997,8 @@ A tagged section starts with one of the following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:", "TODO:". The section ends with the start of a new section. -The second and subsequent lines of sections other than -"Example"/"Examples" should be indented like this:: +The second and subsequent lines of tagged sections must be indented +like this:: # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco # laboris nisi ut aliquip ex ea commodo consequat. @@ -1049,11 +1049,10 @@ For example:: # # Example: # - # -> { "execute": "query-blockstats" } - # <- { - # ... lots of output ... - # } - # + # -> { "execute": "query-blockstats" } + # <- { + # ... lots of output ... + # } ## { 'command': 'query-blockstats', 'data': { '*query-nodes': 'bool' }, diff --git a/qapi/acpi.json b/qapi/acpi.json index e0739bd6ae..aa4dbe5794 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -113,12 +113,12 @@ # # Example: # -# -> { "execute": "query-acpi-ospm-status" } -# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, -# { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, -# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, -# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} -# ]} +# -> { "execute": "query-acpi-ospm-status" } +# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, +# { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, +# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, +# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} +# ]} ## { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } @@ -133,10 +133,10 @@ # # Example: # -# <- { "event": "ACPI_DEVICE_OST", -# "data": { "info": { "device": "d1", "slot": "0", -# "slot-type": "DIMM", "source": 1, "status": 0 } }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "ACPI_DEVICE_OST", +# "data": { "info": { "device": "d1", "slot": "0", +# "slot-type": "DIMM", "source": 1, "status": 0 } }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'ACPI_DEVICE_OST', 'data': { 'info': 'ACPIOSTInfo' } } diff --git a/qapi/block-core.json b/qapi/block-core.json index ab5a93a966..22b8634422 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -766,87 +766,87 @@ # # Example: # -# -> { "execute": "query-block" } -# <- { -# "return":[ -# { -# "io-status": "ok", -# "device":"ide0-hd0", -# "locked":false, -# "removable":false, -# "inserted":{ -# "ro":false, -# "drv":"qcow2", -# "encrypted":false, -# "file":"disks/test.qcow2", -# "backing_file_depth":1, -# "bps":1000000, -# "bps_rd":0, -# "bps_wr":0, -# "iops":1000000, -# "iops_rd":0, -# "iops_wr":0, -# "bps_max": 8000000, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "iops_size": 0, -# "detect_zeroes": "on", -# "write_threshold": 0, -# "image":{ -# "filename":"disks/test.qcow2", -# "format":"qcow2", -# "virtual-size":2048000, -# "backing_file":"base.qcow2", -# "full-backing-filename":"disks/base.qcow2", -# "backing-filename-format":"qcow2", -# "snapshots":[ -# { -# "id": "1", -# "name": "snapshot1", -# "vm-state-size": 0, -# "date-sec": 10000200, -# "date-nsec": 12, -# "vm-clock-sec": 206, -# "vm-clock-nsec": 30 -# } -# ], -# "backing-image":{ -# "filename":"disks/base.qcow2", +# -> { "execute": "query-block" } +# <- { +# "return":[ +# { +# "io-status": "ok", +# "device":"ide0-hd0", +# "locked":false, +# "removable":false, +# "inserted":{ +# "ro":false, +# "drv":"qcow2", +# "encrypted":false, +# "file":"disks/test.qcow2", +# "backing_file_depth":1, +# "bps":1000000, +# "bps_rd":0, +# "bps_wr":0, +# "iops":1000000, +# "iops_rd":0, +# "iops_wr":0, +# "bps_max": 8000000, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "iops_size": 0, +# "detect_zeroes": "on", +# "write_threshold": 0, +# "image":{ +# "filename":"disks/test.qcow2", # "format":"qcow2", -# "virtual-size":2048000 -# } -# } -# }, -# "qdev": "ide_disk", -# "type":"unknown" -# }, -# { -# "io-status": "ok", -# "device":"ide1-cd0", -# "locked":false, -# "removable":true, -# "qdev": "/machine/unattached/device[23]", -# "tray_open": false, -# "type":"unknown" -# }, -# { -# "device":"floppy0", -# "locked":false, -# "removable":true, -# "qdev": "/machine/unattached/device[20]", -# "type":"unknown" -# }, -# { -# "device":"sd0", -# "locked":false, -# "removable":true, -# "type":"unknown" -# } -# ] -# } +# "virtual-size":2048000, +# "backing_file":"base.qcow2", +# "full-backing-filename":"disks/base.qcow2", +# "backing-filename-format":"qcow2", +# "snapshots":[ +# { +# "id": "1", +# "name": "snapshot1", +# "vm-state-size": 0, +# "date-sec": 10000200, +# "date-nsec": 12, +# "vm-clock-sec": 206, +# "vm-clock-nsec": 30 +# } +# ], +# "backing-image":{ +# "filename":"disks/base.qcow2", +# "format":"qcow2", +# "virtual-size":2048000 +# } +# } +# }, +# "qdev": "ide_disk", +# "type":"unknown" +# }, +# { +# "io-status": "ok", +# "device":"ide1-cd0", +# "locked":false, +# "removable":true, +# "qdev": "/machine/unattached/device[23]", +# "tray_open": false, +# "type":"unknown" +# }, +# { +# "device":"floppy0", +# "locked":false, +# "removable":true, +# "qdev": "/machine/unattached/device[20]", +# "type":"unknown" +# }, +# { +# "device":"sd0", +# "locked":false, +# "removable":true, +# "type":"unknown" +# } +# ] +# } ## { 'command': 'query-block', 'returns': ['BlockInfo'], 'allow-preconfig': true } @@ -1170,105 +1170,105 @@ # # Example: # -# -> { "execute": "query-blockstats" } -# <- { -# "return":[ -# { -# "device":"ide0-hd0", -# "parent":{ -# "stats":{ -# "wr_highest_offset":3686448128, -# "wr_bytes":9786368, -# "wr_operations":751, -# "rd_bytes":122567168, -# "rd_operations":36772 -# "wr_total_times_ns":313253456 -# "rd_total_times_ns":3465673657 -# "flush_total_times_ns":49653 -# "flush_operations":61, -# "rd_merged":0, -# "wr_merged":0, -# "idle_time_ns":2953431879, -# "account_invalid":true, -# "account_failed":false -# } -# }, -# "stats":{ -# "wr_highest_offset":2821110784, -# "wr_bytes":9786368, -# "wr_operations":692, -# "rd_bytes":122739200, -# "rd_operations":36604 -# "flush_operations":51, -# "wr_total_times_ns":313253456 -# "rd_total_times_ns":3465673657 -# "flush_total_times_ns":49653, -# "rd_merged":0, -# "wr_merged":0, -# "idle_time_ns":2953431879, -# "account_invalid":true, -# "account_failed":false -# }, -# "qdev": "/machine/unattached/device[23]" -# }, -# { -# "device":"ide1-cd0", -# "stats":{ -# "wr_highest_offset":0, -# "wr_bytes":0, -# "wr_operations":0, -# "rd_bytes":0, -# "rd_operations":0 -# "flush_operations":0, -# "wr_total_times_ns":0 -# "rd_total_times_ns":0 -# "flush_total_times_ns":0, -# "rd_merged":0, -# "wr_merged":0, -# "account_invalid":false, -# "account_failed":false -# }, -# "qdev": "/machine/unattached/device[24]" -# }, -# { -# "device":"floppy0", -# "stats":{ -# "wr_highest_offset":0, -# "wr_bytes":0, -# "wr_operations":0, -# "rd_bytes":0, -# "rd_operations":0 -# "flush_operations":0, -# "wr_total_times_ns":0 -# "rd_total_times_ns":0 -# "flush_total_times_ns":0, -# "rd_merged":0, -# "wr_merged":0, -# "account_invalid":false, -# "account_failed":false -# }, -# "qdev": "/machine/unattached/device[16]" -# }, -# { -# "device":"sd0", -# "stats":{ -# "wr_highest_offset":0, -# "wr_bytes":0, -# "wr_operations":0, -# "rd_bytes":0, -# "rd_operations":0 -# "flush_operations":0, -# "wr_total_times_ns":0 -# "rd_total_times_ns":0 -# "flush_total_times_ns":0, -# "rd_merged":0, -# "wr_merged":0, -# "account_invalid":false, -# "account_failed":false -# } -# } -# ] -# } +# -> { "execute": "query-blockstats" } +# <- { +# "return":[ +# { +# "device":"ide0-hd0", +# "parent":{ +# "stats":{ +# "wr_highest_offset":3686448128, +# "wr_bytes":9786368, +# "wr_operations":751, +# "rd_bytes":122567168, +# "rd_operations":36772 +# "wr_total_times_ns":313253456 +# "rd_total_times_ns":3465673657 +# "flush_total_times_ns":49653 +# "flush_operations":61, +# "rd_merged":0, +# "wr_merged":0, +# "idle_time_ns":2953431879, +# "account_invalid":true, +# "account_failed":false +# } +# }, +# "stats":{ +# "wr_highest_offset":2821110784, +# "wr_bytes":9786368, +# "wr_operations":692, +# "rd_bytes":122739200, +# "rd_operations":36604 +# "flush_operations":51, +# "wr_total_times_ns":313253456 +# "rd_total_times_ns":3465673657 +# "flush_total_times_ns":49653, +# "rd_merged":0, +# "wr_merged":0, +# "idle_time_ns":2953431879, +# "account_invalid":true, +# "account_failed":false +# }, +# "qdev": "/machine/unattached/device[23]" +# }, +# { +# "device":"ide1-cd0", +# "stats":{ +# "wr_highest_offset":0, +# "wr_bytes":0, +# "wr_operations":0, +# "rd_bytes":0, +# "rd_operations":0 +# "flush_operations":0, +# "wr_total_times_ns":0 +# "rd_total_times_ns":0 +# "flush_total_times_ns":0, +# "rd_merged":0, +# "wr_merged":0, +# "account_invalid":false, +# "account_failed":false +# }, +# "qdev": "/machine/unattached/device[24]" +# }, +# { +# "device":"floppy0", +# "stats":{ +# "wr_highest_offset":0, +# "wr_bytes":0, +# "wr_operations":0, +# "rd_bytes":0, +# "rd_operations":0 +# "flush_operations":0, +# "wr_total_times_ns":0 +# "rd_total_times_ns":0 +# "flush_total_times_ns":0, +# "rd_merged":0, +# "wr_merged":0, +# "account_invalid":false, +# "account_failed":false +# }, +# "qdev": "/machine/unattached/device[16]" +# }, +# { +# "device":"sd0", +# "stats":{ +# "wr_highest_offset":0, +# "wr_bytes":0, +# "wr_operations":0, +# "rd_bytes":0, +# "rd_operations":0 +# "flush_operations":0, +# "wr_total_times_ns":0 +# "rd_total_times_ns":0 +# "flush_total_times_ns":0, +# "rd_merged":0, +# "wr_merged":0, +# "account_invalid":false, +# "account_failed":false +# } +# } +# ] +# } ## { 'command': 'query-blockstats', 'data': { '*query-nodes': 'bool' }, @@ -1464,9 +1464,9 @@ # # Example: # -# -> { "execute": "block_resize", -# "arguments": { "device": "scratch", "size": 1073741824 } } -# <- { "return": {} } +# -> { "execute": "block_resize", +# "arguments": { "device": "scratch", "size": 1073741824 } } +# <- { "return": {} } ## { 'command': 'block_resize', 'data': { '*device': 'str', @@ -1682,12 +1682,12 @@ # # Example: # -# -> { "execute": "blockdev-snapshot-sync", -# "arguments": { "device": "ide-hd0", -# "snapshot-file": -# "/some/place/my-image", -# "format": "qcow2" } } -# <- { "return": {} } +# -> { "execute": "blockdev-snapshot-sync", +# "arguments": { "device": "ide-hd0", +# "snapshot-file": +# "/some/place/my-image", +# "format": "qcow2" } } +# <- { "return": {} } ## { 'command': 'blockdev-snapshot-sync', 'data': 'BlockdevSnapshotSync', @@ -1715,19 +1715,19 @@ # # Example: # -# -> { "execute": "blockdev-add", -# "arguments": { "driver": "qcow2", -# "node-name": "node1534", -# "file": { "driver": "file", -# "filename": "hd1.qcow2" }, -# "backing": null } } +# -> { "execute": "blockdev-add", +# "arguments": { "driver": "qcow2", +# "node-name": "node1534", +# "file": { "driver": "file", +# "filename": "hd1.qcow2" }, +# "backing": null } } # -# <- { "return": {} } +# <- { "return": {} } # -# -> { "execute": "blockdev-snapshot", -# "arguments": { "node": "ide-hd0", -# "overlay": "node1534" } } -# <- { "return": {} } +# -> { "execute": "blockdev-snapshot", +# "arguments": { "node": "ide-hd0", +# "overlay": "node1534" } } +# <- { "return": {} } ## { 'command': 'blockdev-snapshot', 'data': 'BlockdevSnapshot', @@ -1863,10 +1863,10 @@ # # Example: # -# -> { "execute": "block-commit", -# "arguments": { "device": "virtio0", -# "top": "/tmp/snap1.qcow2" } } -# <- { "return": {} } +# -> { "execute": "block-commit", +# "arguments": { "device": "virtio0", +# "top": "/tmp/snap1.qcow2" } } +# <- { "return": {} } ## { 'command': 'block-commit', 'data': { '*job-id': 'str', 'device': 'str', '*base-node': 'str', @@ -1902,11 +1902,11 @@ # # Example: # -# -> { "execute": "drive-backup", -# "arguments": { "device": "drive0", -# "sync": "full", -# "target": "backup.img" } } -# <- { "return": {} } +# -> { "execute": "drive-backup", +# "arguments": { "device": "drive0", +# "sync": "full", +# "target": "backup.img" } } +# <- { "return": {} } ## { 'command': 'drive-backup', 'boxed': true, 'data': 'DriveBackup', 'features': ['deprecated'], @@ -1929,11 +1929,11 @@ # # Example: # -# -> { "execute": "blockdev-backup", -# "arguments": { "device": "src-id", -# "sync": "full", -# "target": "tgt-id" } } -# <- { "return": {} } +# -> { "execute": "blockdev-backup", +# "arguments": { "device": "src-id", +# "sync": "full", +# "target": "tgt-id" } } +# <- { "return": {} } ## { 'command': 'blockdev-backup', 'boxed': true, 'data': 'BlockdevBackup', @@ -1953,52 +1953,52 @@ # # Example: # -# -> { "execute": "query-named-block-nodes" } -# <- { "return": [ { "ro":false, -# "drv":"qcow2", -# "encrypted":false, -# "file":"disks/test.qcow2", -# "node-name": "my-node", -# "backing_file_depth":1, -# "detect_zeroes":"off", -# "bps":1000000, -# "bps_rd":0, -# "bps_wr":0, -# "iops":1000000, -# "iops_rd":0, -# "iops_wr":0, -# "bps_max": 8000000, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "iops_size": 0, -# "write_threshold": 0, -# "image":{ -# "filename":"disks/test.qcow2", -# "format":"qcow2", -# "virtual-size":2048000, -# "backing_file":"base.qcow2", -# "full-backing-filename":"disks/base.qcow2", -# "backing-filename-format":"qcow2", -# "snapshots":[ -# { -# "id": "1", -# "name": "snapshot1", -# "vm-state-size": 0, -# "date-sec": 10000200, -# "date-nsec": 12, -# "vm-clock-sec": 206, -# "vm-clock-nsec": 30 -# } -# ], -# "backing-image":{ -# "filename":"disks/base.qcow2", +# -> { "execute": "query-named-block-nodes" } +# <- { "return": [ { "ro":false, +# "drv":"qcow2", +# "encrypted":false, +# "file":"disks/test.qcow2", +# "node-name": "my-node", +# "backing_file_depth":1, +# "detect_zeroes":"off", +# "bps":1000000, +# "bps_rd":0, +# "bps_wr":0, +# "iops":1000000, +# "iops_rd":0, +# "iops_wr":0, +# "bps_max": 8000000, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "iops_size": 0, +# "write_threshold": 0, +# "image":{ +# "filename":"disks/test.qcow2", # "format":"qcow2", -# "virtual-size":2048000 -# } -# } } ] } +# "virtual-size":2048000, +# "backing_file":"base.qcow2", +# "full-backing-filename":"disks/base.qcow2", +# "backing-filename-format":"qcow2", +# "snapshots":[ +# { +# "id": "1", +# "name": "snapshot1", +# "vm-state-size": 0, +# "date-sec": 10000200, +# "date-nsec": 12, +# "vm-clock-sec": 206, +# "vm-clock-nsec": 30 +# } +# ], +# "backing-image":{ +# "filename":"disks/base.qcow2", +# "format":"qcow2", +# "virtual-size":2048000 +# } +# } } ] } ## { 'command': 'query-named-block-nodes', 'returns': [ 'BlockDeviceInfo' ], @@ -2135,12 +2135,12 @@ # # Example: # -# -> { "execute": "drive-mirror", -# "arguments": { "device": "ide-hd0", -# "target": "/some/place/my-image", -# "sync": "full", -# "format": "qcow2" } } -# <- { "return": {} } +# -> { "execute": "drive-mirror", +# "arguments": { "device": "ide-hd0", +# "target": "/some/place/my-image", +# "sync": "full", +# "format": "qcow2" } } +# <- { "return": {} } ## { 'command': 'drive-mirror', 'boxed': true, 'data': 'DriveMirror', @@ -2313,9 +2313,9 @@ # # Example: # -# -> { "execute": "block-dirty-bitmap-add", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } +# -> { "execute": "block-dirty-bitmap-add", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-add', 'data': 'BlockDirtyBitmapAdd', @@ -2338,9 +2338,9 @@ # # Example: # -# -> { "execute": "block-dirty-bitmap-remove", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } +# -> { "execute": "block-dirty-bitmap-remove", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-remove', 'data': 'BlockDirtyBitmap', @@ -2362,9 +2362,9 @@ # # Example: # -# -> { "execute": "block-dirty-bitmap-clear", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } +# -> { "execute": "block-dirty-bitmap-clear", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-clear', 'data': 'BlockDirtyBitmap', @@ -2384,9 +2384,9 @@ # # Example: # -# -> { "execute": "block-dirty-bitmap-enable", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } +# -> { "execute": "block-dirty-bitmap-enable", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-enable', 'data': 'BlockDirtyBitmap', @@ -2406,9 +2406,9 @@ # # Example: # -# -> { "execute": "block-dirty-bitmap-disable", -# "arguments": { "node": "drive0", "name": "bitmap0" } } -# <- { "return": {} } +# -> { "execute": "block-dirty-bitmap-disable", +# "arguments": { "node": "drive0", "name": "bitmap0" } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-disable', 'data': 'BlockDirtyBitmap', @@ -2439,10 +2439,10 @@ # # Example: # -# -> { "execute": "block-dirty-bitmap-merge", -# "arguments": { "node": "drive0", "target": "bitmap0", -# "bitmaps": ["bitmap1"] } } -# <- { "return": {} } +# -> { "execute": "block-dirty-bitmap-merge", +# "arguments": { "node": "drive0", "target": "bitmap0", +# "bitmaps": ["bitmap1"] } } +# <- { "return": {} } ## { 'command': 'block-dirty-bitmap-merge', 'data': 'BlockDirtyBitmapMerge', @@ -2548,11 +2548,11 @@ # # Example: # -# -> { "execute": "blockdev-mirror", -# "arguments": { "device": "ide-hd0", -# "target": "target0", -# "sync": "full" } } -# <- { "return": {} } +# -> { "execute": "blockdev-mirror", +# "arguments": { "device": "ide-hd0", +# "target": "target0", +# "sync": "full" } } +# <- { "return": {} } ## { 'command': 'blockdev-mirror', 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', @@ -2874,10 +2874,10 @@ # # Example: # -# -> { "execute": "block-stream", -# "arguments": { "device": "virtio0", -# "base": "/tmp/master.qcow2" } } -# <- { "return": {} } +# -> { "execute": "block-stream", +# "arguments": { "device": "virtio0", +# "base": "/tmp/master.qcow2" } } +# <- { "return": {} } ## { 'command': 'block-stream', 'data': { '*job-id': 'str', 'device': 'str', '*base': 'str', @@ -4805,41 +4805,41 @@ # # Examples: # -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "qcow2", -# "node-name": "test1", -# "file": { -# "driver": "file", -# "filename": "test.qcow2" -# } -# } -# } -# <- { "return": {} } -# -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "qcow2", -# "node-name": "node0", -# "discard": "unmap", -# "cache": { -# "direct": true -# }, -# "file": { -# "driver": "file", -# "filename": "/tmp/test.qcow2" -# }, -# "backing": { -# "driver": "raw", +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "qcow2", +# "node-name": "test1", # "file": { +# "driver": "file", +# "filename": "test.qcow2" +# } +# } +# } +# <- { "return": {} } +# +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "qcow2", +# "node-name": "node0", +# "discard": "unmap", +# "cache": { +# "direct": true +# }, +# "file": { # "driver": "file", -# "filename": "/dev/fdset/4" +# "filename": "/tmp/test.qcow2" +# }, +# "backing": { +# "driver": "raw", +# "file": { +# "driver": "file", +# "filename": "/dev/fdset/4" +# } # } # } -# } -# } +# } # -# <- { "return": {} } +# <- { "return": {} } ## { 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true, 'allow-preconfig': true } @@ -4903,22 +4903,22 @@ # # Example: # -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "qcow2", -# "node-name": "node0", -# "file": { -# "driver": "file", -# "filename": "test.qcow2" -# } -# } -# } -# <- { "return": {} } +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "qcow2", +# "node-name": "node0", +# "file": { +# "driver": "file", +# "filename": "test.qcow2" +# } +# } +# } +# <- { "return": {} } # -# -> { "execute": "blockdev-del", -# "arguments": { "node-name": "node0" } -# } -# <- { "return": {} } +# -> { "execute": "blockdev-del", +# "arguments": { "node-name": "node0" } +# } +# <- { "return": {} } ## { 'command': 'blockdev-del', 'data': { 'node-name': 'str' }, 'allow-preconfig': true } @@ -5552,10 +5552,10 @@ # # Example: # -# <- { "event": "BLOCK_IMAGE_CORRUPTED", -# "data": { "device": "", "node-name": "drive", "fatal": false, -# "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" }, -# "timestamp": { "seconds": 1648243240, "microseconds": 906060 } } +# <- { "event": "BLOCK_IMAGE_CORRUPTED", +# "data": { "device": "", "node-name": "drive", "fatal": false, +# "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" }, +# "timestamp": { "seconds": 1648243240, "microseconds": 906060 } } # # Since: 1.7 ## @@ -5601,13 +5601,13 @@ # # Example: # -# <- { "event": "BLOCK_IO_ERROR", -# "data": { "device": "ide0-hd1", -# "node-name": "#block212", -# "operation": "write", -# "action": "stop", -# "reason": "No space left on device" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "BLOCK_IO_ERROR", +# "data": { "device": "ide0-hd1", +# "node-name": "#block212", +# "operation": "write", +# "action": "stop", +# "reason": "No space left on device" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_IO_ERROR', 'data': { 'device': 'str', '*node-name': 'str', @@ -5641,11 +5641,11 @@ # # Example: # -# <- { "event": "BLOCK_JOB_COMPLETED", -# "data": { "type": "stream", "device": "virtio-disk0", -# "len": 10737418240, "offset": 10737418240, -# "speed": 0 }, -# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } +# <- { "event": "BLOCK_JOB_COMPLETED", +# "data": { "type": "stream", "device": "virtio-disk0", +# "len": 10737418240, "offset": 10737418240, +# "speed": 0 }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'BLOCK_JOB_COMPLETED', 'data': { 'type' : 'JobType', @@ -5676,11 +5676,11 @@ # # Example: # -# <- { "event": "BLOCK_JOB_CANCELLED", -# "data": { "type": "stream", "device": "virtio-disk0", -# "len": 10737418240, "offset": 134217728, -# "speed": 0 }, -# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } +# <- { "event": "BLOCK_JOB_CANCELLED", +# "data": { "type": "stream", "device": "virtio-disk0", +# "len": 10737418240, "offset": 134217728, +# "speed": 0 }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'BLOCK_JOB_CANCELLED', 'data': { 'type' : 'JobType', @@ -5705,11 +5705,11 @@ # # Example: # -# <- { "event": "BLOCK_JOB_ERROR", -# "data": { "device": "ide0-hd1", -# "operation": "write", -# "action": "stop" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "BLOCK_JOB_ERROR", +# "data": { "device": "ide0-hd1", +# "operation": "write", +# "action": "stop" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_JOB_ERROR', 'data': { 'device' : 'str', @@ -5740,10 +5740,10 @@ # # Example: # -# <- { "event": "BLOCK_JOB_READY", -# "data": { "device": "drive0", "type": "mirror", "speed": 0, -# "len": 2097152, "offset": 2097152 }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "BLOCK_JOB_READY", +# "data": { "device": "drive0", "type": "mirror", "speed": 0, +# "len": 2097152, "offset": 2097152 }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_JOB_READY', 'data': { 'type' : 'JobType', @@ -5768,9 +5768,9 @@ # # Example: # -# <- { "event": "BLOCK_JOB_PENDING", -# "data": { "type": "mirror", "id": "backup_1" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "BLOCK_JOB_PENDING", +# "data": { "type": "mirror", "id": "backup_1" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'BLOCK_JOB_PENDING', 'data': { 'type' : 'JobType', @@ -5842,10 +5842,10 @@ # # Example: # -# -> { "execute": "block-set-write-threshold", -# "arguments": { "node-name": "mydev", -# "write-threshold": 17179869184 } } -# <- { "return": {} } +# -> { "execute": "block-set-write-threshold", +# "arguments": { "node-name": "mydev", +# "write-threshold": 17179869184 } } +# <- { "return": {} } ## { 'command': 'block-set-write-threshold', 'data': { 'node-name': 'str', 'write-threshold': 'uint64' }, @@ -5887,26 +5887,26 @@ # # Examples: # -# 1. Add a new node to a quorum +# 1. Add a new node to a quorum # -# -> { "execute": "blockdev-add", -# "arguments": { -# "driver": "raw", -# "node-name": "new_node", -# "file": { "driver": "file", -# "filename": "test.raw" } } } -# <- { "return": {} } -# -> { "execute": "x-blockdev-change", -# "arguments": { "parent": "disk1", -# "node": "new_node" } } -# <- { "return": {} } +# -> { "execute": "blockdev-add", +# "arguments": { +# "driver": "raw", +# "node-name": "new_node", +# "file": { "driver": "file", +# "filename": "test.raw" } } } +# <- { "return": {} } +# -> { "execute": "x-blockdev-change", +# "arguments": { "parent": "disk1", +# "node": "new_node" } } +# <- { "return": {} } # -# 2. Delete a quorum's node +# 2. Delete a quorum's node # -# -> { "execute": "x-blockdev-change", -# "arguments": { "parent": "disk1", -# "child": "children.1" } } -# <- { "return": {} } +# -> { "execute": "x-blockdev-change", +# "arguments": { "parent": "disk1", +# "child": "children.1" } } +# <- { "return": {} } ## { 'command': 'x-blockdev-change', 'data' : { 'parent': 'str', @@ -5939,19 +5939,19 @@ # # Examples: # -# 1. Move a node into an IOThread +# 1. Move a node into an IOThread # -# -> { "execute": "x-blockdev-set-iothread", -# "arguments": { "node-name": "disk1", -# "iothread": "iothread0" } } -# <- { "return": {} } +# -> { "execute": "x-blockdev-set-iothread", +# "arguments": { "node-name": "disk1", +# "iothread": "iothread0" } } +# <- { "return": {} } # -# 2. Move a node into the main loop +# 2. Move a node into the main loop # -# -> { "execute": "x-blockdev-set-iothread", -# "arguments": { "node-name": "disk1", -# "iothread": null } } -# <- { "return": {} } +# -> { "execute": "x-blockdev-set-iothread", +# "arguments": { "node-name": "disk1", +# "iothread": null } } +# <- { "return": {} } ## { 'command': 'x-blockdev-set-iothread', 'data' : { 'node-name': 'str', @@ -5993,9 +5993,9 @@ # # Example: # -# <- { "event": "QUORUM_FAILURE", -# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, -# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } +# <- { "event": "QUORUM_FAILURE", +# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, +# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } ## { 'event': 'QUORUM_FAILURE', 'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } } @@ -6024,19 +6024,19 @@ # # Examples: # -# 1. Read operation +# 1. Read operation # -# <- { "event": "QUORUM_REPORT_BAD", -# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, -# "type": "read" }, -# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } +# <- { "event": "QUORUM_REPORT_BAD", +# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, +# "type": "read" }, +# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # -# 2. Flush operation +# 2. Flush operation # -# <- { "event": "QUORUM_REPORT_BAD", -# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, -# "type": "flush", "error": "Broken pipe" }, -# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } +# <- { "event": "QUORUM_REPORT_BAD", +# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, +# "type": "flush", "error": "Broken pipe" }, +# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } ## { 'event': 'QUORUM_REPORT_BAD', 'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str', @@ -6082,11 +6082,11 @@ # # Example: # -# -> { "execute": "blockdev-snapshot-internal-sync", -# "arguments": { "device": "ide-hd0", -# "name": "snapshot0" } -# } -# <- { "return": {} } +# -> { "execute": "blockdev-snapshot-internal-sync", +# "arguments": { "device": "ide-hd0", +# "name": "snapshot0" } +# } +# <- { "return": {} } ## { 'command': 'blockdev-snapshot-internal-sync', 'data': 'BlockdevSnapshotInternal', @@ -6119,21 +6119,21 @@ # # Example: # -# -> { "execute": "blockdev-snapshot-delete-internal-sync", -# "arguments": { "device": "ide-hd0", -# "name": "snapshot0" } -# } -# <- { "return": { -# "id": "1", -# "name": "snapshot0", -# "vm-state-size": 0, -# "date-sec": 1000012, -# "date-nsec": 10, -# "vm-clock-sec": 100, -# "vm-clock-nsec": 20, -# "icount": 220414 -# } -# } +# -> { "execute": "blockdev-snapshot-delete-internal-sync", +# "arguments": { "device": "ide-hd0", +# "name": "snapshot0" } +# } +# <- { "return": { +# "id": "1", +# "name": "snapshot0", +# "vm-state-size": 0, +# "date-sec": 1000012, +# "date-nsec": 10, +# "vm-clock-sec": 100, +# "vm-clock-nsec": 20, +# "icount": 220414 +# } +# } ## { 'command': 'blockdev-snapshot-delete-internal-sync', 'data': { 'device': 'str', '*id': 'str', '*name': 'str'}, diff --git a/qapi/block.json b/qapi/block.json index 998008cfa8..79a0bcc208 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -120,8 +120,8 @@ # # Example: # -# -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } -# <- { "return": {} } +# -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } +# <- { "return": {} } ## { 'command': 'eject', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, @@ -164,17 +164,17 @@ # # Example: # -# -> { "execute": "blockdev-open-tray", -# "arguments": { "id": "ide0-1-0" } } +# -> { "execute": "blockdev-open-tray", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "timestamp": { "seconds": 1418751016, -# "microseconds": 716996 }, -# "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "ide0-1-0", -# "tray-open": true } } +# <- { "timestamp": { "seconds": 1418751016, +# "microseconds": 716996 }, +# "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "ide0-1-0", +# "tray-open": true } } # -# <- { "return": {} } +# <- { "return": {} } ## { 'command': 'blockdev-open-tray', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, @@ -202,17 +202,17 @@ # # Example: # -# -> { "execute": "blockdev-close-tray", -# "arguments": { "id": "ide0-1-0" } } +# -> { "execute": "blockdev-close-tray", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "timestamp": { "seconds": 1418751345, -# "microseconds": 272147 }, -# "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "ide0-1-0", -# "tray-open": false } } +# <- { "timestamp": { "seconds": 1418751345, +# "microseconds": 272147 }, +# "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "ide0-1-0", +# "tray-open": false } } # -# <- { "return": {} } +# <- { "return": {} } ## { 'command': 'blockdev-close-tray', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, @@ -234,28 +234,28 @@ # # Example: # -# -> { "execute": "blockdev-remove-medium", -# "arguments": { "id": "ide0-1-0" } } +# -> { "execute": "blockdev-remove-medium", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "error": { "class": "GenericError", -# "desc": "Tray of device 'ide0-1-0' is not open" } } +# <- { "error": { "class": "GenericError", +# "desc": "Tray of device 'ide0-1-0' is not open" } } # -# -> { "execute": "blockdev-open-tray", -# "arguments": { "id": "ide0-1-0" } } +# -> { "execute": "blockdev-open-tray", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "timestamp": { "seconds": 1418751627, -# "microseconds": 549958 }, -# "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "ide0-1-0", -# "tray-open": true } } +# <- { "timestamp": { "seconds": 1418751627, +# "microseconds": 549958 }, +# "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "ide0-1-0", +# "tray-open": true } } # -# <- { "return": {} } +# <- { "return": {} } # -# -> { "execute": "blockdev-remove-medium", -# "arguments": { "id": "ide0-1-0" } } +# -> { "execute": "blockdev-remove-medium", +# "arguments": { "id": "ide0-1-0" } } # -# <- { "return": {} } +# <- { "return": {} } ## { 'command': 'blockdev-remove-medium', 'data': { 'id': 'str' } } @@ -275,19 +275,19 @@ # # Example: # -# -> { "execute": "blockdev-add", -# "arguments": { -# "node-name": "node0", -# "driver": "raw", -# "file": { "driver": "file", -# "filename": "fedora.iso" } } } -# <- { "return": {} } +# -> { "execute": "blockdev-add", +# "arguments": { +# "node-name": "node0", +# "driver": "raw", +# "file": { "driver": "file", +# "filename": "fedora.iso" } } } +# <- { "return": {} } # -# -> { "execute": "blockdev-insert-medium", -# "arguments": { "id": "ide0-1-0", -# "node-name": "node0" } } +# -> { "execute": "blockdev-insert-medium", +# "arguments": { "id": "ide0-1-0", +# "node-name": "node0" } } # -# <- { "return": {} } +# <- { "return": {} } ## { 'command': 'blockdev-insert-medium', 'data': { 'id': 'str', @@ -345,33 +345,33 @@ # # Examples: # -# 1. Change a removable medium +# 1. Change a removable medium # -# -> { "execute": "blockdev-change-medium", -# "arguments": { "id": "ide0-1-0", -# "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", -# "format": "raw" } } -# <- { "return": {} } +# -> { "execute": "blockdev-change-medium", +# "arguments": { "id": "ide0-1-0", +# "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", +# "format": "raw" } } +# <- { "return": {} } # -# 2. Load a read-only medium into a writable drive +# 2. Load a read-only medium into a writable drive # -# -> { "execute": "blockdev-change-medium", -# "arguments": { "id": "floppyA", -# "filename": "/srv/images/ro.img", -# "format": "raw", -# "read-only-mode": "retain" } } +# -> { "execute": "blockdev-change-medium", +# "arguments": { "id": "floppyA", +# "filename": "/srv/images/ro.img", +# "format": "raw", +# "read-only-mode": "retain" } } # -# <- { "error": -# { "class": "GenericError", -# "desc": "Could not open '/srv/images/ro.img': Permission denied" } } +# <- { "error": +# { "class": "GenericError", +# "desc": "Could not open '/srv/images/ro.img': Permission denied" } } # -# -> { "execute": "blockdev-change-medium", -# "arguments": { "id": "floppyA", -# "filename": "/srv/images/ro.img", -# "format": "raw", -# "read-only-mode": "read-only" } } +# -> { "execute": "blockdev-change-medium", +# "arguments": { "id": "floppyA", +# "filename": "/srv/images/ro.img", +# "format": "raw", +# "read-only-mode": "read-only" } } # -# <- { "return": {} } +# <- { "return": {} } ## { 'command': 'blockdev-change-medium', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] }, @@ -400,12 +400,12 @@ # # Example: # -# <- { "event": "DEVICE_TRAY_MOVED", -# "data": { "device": "ide1-cd0", -# "id": "/machine/unattached/device[22]", -# "tray-open": true -# }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "DEVICE_TRAY_MOVED", +# "data": { "device": "ide1-cd0", +# "id": "/machine/unattached/device[22]", +# "tray-open": true +# }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'DEVICE_TRAY_MOVED', 'data': { 'device': 'str', 'id': 'str', 'tray-open': 'bool' } } @@ -424,11 +424,11 @@ # # Example: # -# <- { "event": "PR_MANAGER_STATUS_CHANGED", -# "data": { "id": "pr-helper0", -# "connected": true -# }, -# "timestamp": { "seconds": 1519840375, "microseconds": 450486 } } +# <- { "event": "PR_MANAGER_STATUS_CHANGED", +# "data": { "id": "pr-helper0", +# "connected": true +# }, +# "timestamp": { "seconds": 1519840375, "microseconds": 450486 } } ## { 'event': 'PR_MANAGER_STATUS_CHANGED', 'data': { 'id': 'str', 'connected': 'bool' } } @@ -467,41 +467,41 @@ # # Examples: # -# -> { "execute": "block_set_io_throttle", -# "arguments": { "id": "virtio-blk-pci0/virtio-backend", -# "bps": 0, -# "bps_rd": 0, -# "bps_wr": 0, -# "iops": 512, -# "iops_rd": 0, -# "iops_wr": 0, -# "bps_max": 0, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "bps_max_length": 0, -# "iops_size": 0 } } -# <- { "return": {} } +# -> { "execute": "block_set_io_throttle", +# "arguments": { "id": "virtio-blk-pci0/virtio-backend", +# "bps": 0, +# "bps_rd": 0, +# "bps_wr": 0, +# "iops": 512, +# "iops_rd": 0, +# "iops_wr": 0, +# "bps_max": 0, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "bps_max_length": 0, +# "iops_size": 0 } } +# <- { "return": {} } # -# -> { "execute": "block_set_io_throttle", -# "arguments": { "id": "ide0-1-0", -# "bps": 1000000, -# "bps_rd": 0, -# "bps_wr": 0, -# "iops": 0, -# "iops_rd": 0, -# "iops_wr": 0, -# "bps_max": 8000000, -# "bps_rd_max": 0, -# "bps_wr_max": 0, -# "iops_max": 0, -# "iops_rd_max": 0, -# "iops_wr_max": 0, -# "bps_max_length": 60, -# "iops_size": 0 } } -# <- { "return": {} } +# -> { "execute": "block_set_io_throttle", +# "arguments": { "id": "ide0-1-0", +# "bps": 1000000, +# "bps_rd": 0, +# "bps_wr": 0, +# "iops": 0, +# "iops_rd": 0, +# "iops_wr": 0, +# "bps_max": 8000000, +# "bps_rd_max": 0, +# "bps_wr_max": 0, +# "iops_max": 0, +# "iops_rd_max": 0, +# "iops_wr_max": 0, +# "bps_max_length": 60, +# "iops_size": 0 } } +# <- { "return": {} } ## { 'command': 'block_set_io_throttle', 'boxed': true, 'data': 'BlockIOThrottle', @@ -547,43 +547,43 @@ # # Example: # -# Set new histograms for all io types with intervals [0, 10), [10, -# 50), [50, 100), [100, +inf): +# Set new histograms for all io types with intervals [0, 10), [10, +# 50), [50, 100), [100, +inf): # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0", -# "boundaries": [10, 50, 100] } } -# <- { "return": {} } +# -> { "execute": "block-latency-histogram-set", +# "arguments": { "id": "drive0", +# "boundaries": [10, 50, 100] } } +# <- { "return": {} } # # Example: # -# Set new histogram only for write, other histograms will remain not -# changed (or not created): +# Set new histogram only for write, other histograms will remain not +# changed (or not created): # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0", -# "boundaries-write": [10, 50, 100] } } -# <- { "return": {} } +# -> { "execute": "block-latency-histogram-set", +# "arguments": { "id": "drive0", +# "boundaries-write": [10, 50, 100] } } +# <- { "return": {} } # # Example: # -# Set new histograms with the following intervals: read, flush: [0, -# 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000, -# 5000), [5000, +inf) +# Set new histograms with the following intervals: read, flush: [0, +# 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000, +# 5000), [5000, +inf) # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0", -# "boundaries": [10, 50, 100], -# "boundaries-write": [1000, 5000] } } -# <- { "return": {} } +# -> { "execute": "block-latency-histogram-set", +# "arguments": { "id": "drive0", +# "boundaries": [10, 50, 100], +# "boundaries-write": [1000, 5000] } } +# <- { "return": {} } # # Example: # -# Remove all latency histograms: +# Remove all latency histograms: # -# -> { "execute": "block-latency-histogram-set", -# "arguments": { "id": "drive0" } } -# <- { "return": {} } +# -> { "execute": "block-latency-histogram-set", +# "arguments": { "id": "drive0" } } +# <- { "return": {} } ## { 'command': 'block-latency-histogram-set', 'data': {'id': 'str', diff --git a/qapi/char.json b/qapi/char.json index 2b786104f8..4873bc635a 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -42,26 +42,26 @@ # # Example: # -# -> { "execute": "query-chardev" } -# <- { -# "return": [ -# { -# "label": "charchannel0", -# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on", -# "frontend-open": false -# }, -# { -# "label": "charmonitor", -# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on", -# "frontend-open": true -# }, -# { -# "label": "charserial0", -# "filename": "pty:/dev/pts/2", -# "frontend-open": true -# } -# ] -# } +# -> { "execute": "query-chardev" } +# <- { +# "return": [ +# { +# "label": "charchannel0", +# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on", +# "frontend-open": false +# }, +# { +# "label": "charmonitor", +# "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on", +# "frontend-open": true +# }, +# { +# "label": "charserial0", +# "filename": "pty:/dev/pts/2", +# "frontend-open": true +# } +# ] +# } ## { 'command': 'query-chardev', 'returns': ['ChardevInfo'], 'allow-preconfig': true } @@ -88,23 +88,23 @@ # # Example: # -# -> { "execute": "query-chardev-backends" } -# <- { -# "return":[ -# { -# "name":"udp" -# }, -# { -# "name":"tcp" -# }, -# { -# "name":"unix" -# }, -# { -# "name":"spiceport" -# } -# ] -# } +# -> { "execute": "query-chardev-backends" } +# <- { +# "return":[ +# { +# "name":"udp" +# }, +# { +# "name":"tcp" +# }, +# { +# "name":"unix" +# }, +# { +# "name":"spiceport" +# } +# ] +# } ## { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] } @@ -145,11 +145,11 @@ # # Example: # -# -> { "execute": "ringbuf-write", -# "arguments": { "device": "foo", -# "data": "abcdefgh", -# "format": "utf8" } } -# <- { "return": {} } +# -> { "execute": "ringbuf-write", +# "arguments": { "device": "foo", +# "data": "abcdefgh", +# "format": "utf8" } } +# <- { "return": {} } ## { 'command': 'ringbuf-write', 'data': { 'device': 'str', @@ -181,11 +181,11 @@ # # Example: # -# -> { "execute": "ringbuf-read", -# "arguments": { "device": "foo", -# "size": 1000, -# "format": "utf8" } } -# <- { "return": "abcdefgh" } +# -> { "execute": "ringbuf-read", +# "arguments": { "device": "foo", +# "size": 1000, +# "format": "utf8" } } +# <- { "return": "abcdefgh" } ## { 'command': 'ringbuf-read', 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'}, @@ -703,21 +703,21 @@ # # Examples: # -# -> { "execute" : "chardev-add", -# "arguments" : { "id" : "foo", -# "backend" : { "type" : "null", "data" : {} } } } -# <- { "return": {} } +# -> { "execute" : "chardev-add", +# "arguments" : { "id" : "foo", +# "backend" : { "type" : "null", "data" : {} } } } +# <- { "return": {} } # -# -> { "execute" : "chardev-add", -# "arguments" : { "id" : "bar", -# "backend" : { "type" : "file", -# "data" : { "out" : "/tmp/bar.log" } } } } -# <- { "return": {} } +# -> { "execute" : "chardev-add", +# "arguments" : { "id" : "bar", +# "backend" : { "type" : "file", +# "data" : { "out" : "/tmp/bar.log" } } } } +# <- { "return": {} } # -# -> { "execute" : "chardev-add", -# "arguments" : { "id" : "baz", -# "backend" : { "type" : "pty", "data" : {} } } } -# <- { "return": { "pty" : "/dev/pty/42" } } +# -> { "execute" : "chardev-add", +# "arguments" : { "id" : "baz", +# "backend" : { "type" : "pty", "data" : {} } } } +# <- { "return": { "pty" : "/dev/pty/42" } } ## { 'command': 'chardev-add', 'data': { 'id': 'str', @@ -739,26 +739,26 @@ # # Examples: # -# -> { "execute" : "chardev-change", -# "arguments" : { "id" : "baz", -# "backend" : { "type" : "pty", "data" : {} } } } -# <- { "return": { "pty" : "/dev/pty/42" } } +# -> { "execute" : "chardev-change", +# "arguments" : { "id" : "baz", +# "backend" : { "type" : "pty", "data" : {} } } } +# <- { "return": { "pty" : "/dev/pty/42" } } # -# -> {"execute" : "chardev-change", -# "arguments" : { -# "id" : "charchannel2", -# "backend" : { -# "type" : "socket", -# "data" : { -# "addr" : { -# "type" : "unix" , -# "data" : { -# "path" : "/tmp/charchannel2.socket" -# } -# }, -# "server" : true, -# "wait" : false }}}} -# <- {"return": {}} +# -> {"execute" : "chardev-change", +# "arguments" : { +# "id" : "charchannel2", +# "backend" : { +# "type" : "socket", +# "data" : { +# "addr" : { +# "type" : "unix" , +# "data" : { +# "path" : "/tmp/charchannel2.socket" +# } +# }, +# "server" : true, +# "wait" : false }}}} +# <- {"return": {}} ## { 'command': 'chardev-change', 'data': { 'id': 'str', @@ -778,8 +778,8 @@ # # Example: # -# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } -# <- { "return": {} } +# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } +# <- { "return": {} } ## { 'command': 'chardev-remove', 'data': { 'id': 'str' } } @@ -797,8 +797,8 @@ # # Example: # -# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } -# <- { "return": {} } +# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } +# <- { "return": {} } ## { 'command': 'chardev-send-break', 'data': { 'id': 'str' } } @@ -818,9 +818,9 @@ # # Example: # -# <- { "event": "VSERPORT_CHANGE", -# "data": { "id": "channel0", "open": true }, -# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +# <- { "event": "VSERPORT_CHANGE", +# "data": { "id": "channel0", "open": true }, +# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } ## { 'event': 'VSERPORT_CHANGE', 'data': { 'id': 'str', diff --git a/qapi/control.json b/qapi/control.json index a91fa33407..f404daef60 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -20,9 +20,9 @@ # # Example: # -# -> { "execute": "qmp_capabilities", -# "arguments": { "enable": [ "oob" ] } } -# <- { "return": {} } +# -> { "execute": "qmp_capabilities", +# "arguments": { "enable": [ "oob" ] } } +# <- { "return": {} } # # Notes: This command is valid exactly when first connecting: it must # be issued before any other command will be accepted, and will @@ -102,17 +102,17 @@ # # Example: # -# -> { "execute": "query-version" } -# <- { -# "return":{ -# "qemu":{ -# "major":0, -# "minor":11, -# "micro":5 -# }, -# "package":"" -# } -# } +# -> { "execute": "query-version" } +# <- { +# "return":{ +# "qemu":{ +# "major":0, +# "minor":11, +# "micro":5 +# }, +# "package":"" +# } +# } ## { 'command': 'query-version', 'returns': 'VersionInfo', 'allow-preconfig': true } @@ -139,17 +139,17 @@ # # Example: # -# -> { "execute": "query-commands" } -# <- { -# "return":[ -# { -# "name":"query-balloon" -# }, -# { -# "name":"system_powerdown" -# } -# ] -# } +# -> { "execute": "query-commands" } +# <- { +# "return":[ +# { +# "name":"query-balloon" +# }, +# { +# "name":"system_powerdown" +# } +# ] +# } # # Note: This example has been shortened as the real response is too # long. @@ -169,8 +169,8 @@ # # Example: # -# -> { "execute": "quit" } -# <- { "return": {} } +# -> { "execute": "quit" } +# <- { "return": {} } ## { 'command': 'quit', 'allow-preconfig': true } diff --git a/qapi/dump.json b/qapi/dump.json index 1997c1d1d4..f82dd6a1af 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -98,9 +98,9 @@ # # Example: # -# -> { "execute": "dump-guest-memory", -# "arguments": { "paging": false, "protocol": "fd:dump" } } -# <- { "return": {} } +# -> { "execute": "dump-guest-memory", +# "arguments": { "paging": false, "protocol": "fd:dump" } } +# <- { "return": {} } ## { 'command': 'dump-guest-memory', 'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool', @@ -154,9 +154,9 @@ # # Example: # -# -> { "execute": "query-dump" } -# <- { "return": { "status": "active", "completed": 1024000, -# "total": 2048000 } } +# -> { "execute": "query-dump" } +# <- { "return": { "status": "active", "completed": 1024000, +# "total": 2048000 } } ## { 'command': 'query-dump', 'returns': 'DumpQueryResult' } @@ -175,10 +175,10 @@ # # Example: # -# <- { "event": "DUMP_COMPLETED", -# "data": { "result": { "total": 1090650112, "status": "completed", -# "completed": 1090650112 } }, -# "timestamp": { "seconds": 1648244171, "microseconds": 950316 } } +# <- { "event": "DUMP_COMPLETED", +# "data": { "result": { "total": 1090650112, "status": "completed", +# "completed": 1090650112 } }, +# "timestamp": { "seconds": 1648244171, "microseconds": 950316 } } ## { 'event': 'DUMP_COMPLETED' , 'data': { 'result': 'DumpQueryResult', '*error': 'str' } } @@ -206,9 +206,9 @@ # # Example: # -# -> { "execute": "query-dump-guest-memory-capability" } -# <- { "return": { "formats": -# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } +# -> { "execute": "query-dump-guest-memory-capability" } +# <- { "return": { "formats": +# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } ## { 'command': 'query-dump-guest-memory-capability', 'returns': 'DumpGuestMemoryCapability' } diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 7b7149f81c..2c5dda735e 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -447,9 +447,9 @@ # # Example: # -# <- { "event": "CPU_POLARIZATION_CHANGE", -# "data": { "polarization": "horizontal" }, -# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +# <- { "event": "CPU_POLARIZATION_CHANGE", +# "data": { "polarization": "horizontal" }, +# "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } ## { 'event': 'CPU_POLARIZATION_CHANGE', 'data': { 'polarization': 'CpuS390Polarization' }, diff --git a/qapi/machine.json b/qapi/machine.json index d816c5c02e..93b4677286 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -106,32 +106,32 @@ # # Example: # -# -> { "execute": "query-cpus-fast" } -# <- { "return": [ -# { -# "thread-id": 25627, -# "props": { -# "core-id": 0, -# "thread-id": 0, -# "socket-id": 0 +# -> { "execute": "query-cpus-fast" } +# <- { "return": [ +# { +# "thread-id": 25627, +# "props": { +# "core-id": 0, +# "thread-id": 0, +# "socket-id": 0 +# }, +# "qom-path": "/machine/unattached/device[0]", +# "target":"x86_64", +# "cpu-index": 0 # }, -# "qom-path": "/machine/unattached/device[0]", -# "target":"x86_64", -# "cpu-index": 0 -# }, -# { -# "thread-id": 25628, -# "props": { -# "core-id": 0, -# "thread-id": 0, -# "socket-id": 1 -# }, -# "qom-path": "/machine/unattached/device[2]", -# "target":"x86_64", -# "cpu-index": 1 -# } -# ] -# } +# { +# "thread-id": 25628, +# "props": { +# "core-id": 0, +# "thread-id": 0, +# "socket-id": 1 +# }, +# "qom-path": "/machine/unattached/device[2]", +# "target":"x86_64", +# "cpu-index": 1 +# } +# ] +# } ## { 'command': 'query-cpus-fast', 'returns': [ 'CpuInfoFast' ] } @@ -258,8 +258,8 @@ # # Example: # -# -> { "execute": "query-uuid" } -# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } +# -> { "execute": "query-uuid" } +# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } ## { 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true } @@ -292,8 +292,8 @@ # # Example: # -# -> { "execute": "system_reset" } -# <- { "return": {} } +# -> { "execute": "system_reset" } +# <- { "return": {} } ## { 'command': 'system_reset' } @@ -311,8 +311,8 @@ # # Example: # -# -> { "execute": "system_powerdown" } -# <- { "return": {} } +# -> { "execute": "system_powerdown" } +# <- { "return": {} } ## { 'command': 'system_powerdown' } @@ -333,8 +333,8 @@ # # Example: # -# -> { "execute": "system_wakeup" } -# <- { "return": {} } +# -> { "execute": "system_wakeup" } +# <- { "return": {} } ## { 'command': 'system_wakeup' } @@ -386,8 +386,8 @@ # # Example: # -# -> { "execute": "inject-nmi" } -# <- { "return": {} } +# -> { "execute": "inject-nmi" } +# <- { "return": {} } ## { 'command': 'inject-nmi' } @@ -415,8 +415,8 @@ # # Example: # -# -> { "execute": "query-kvm" } -# <- { "return": { "enabled": true, "present": true } } +# -> { "execute": "query-kvm" } +# <- { "return": { "enabled": true, "present": true } } ## { 'command': 'query-kvm', 'returns': 'KvmInfo' } @@ -786,11 +786,11 @@ # # Example: # -# -> { "execute": "memsave", -# "arguments": { "val": 10, -# "size": 100, -# "filename": "/tmp/virtual-mem-dump" } } -# <- { "return": {} } +# -> { "execute": "memsave", +# "arguments": { "val": 10, +# "size": 100, +# "filename": "/tmp/virtual-mem-dump" } } +# <- { "return": {} } ## { 'command': 'memsave', 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} } @@ -814,11 +814,11 @@ # # Example: # -# -> { "execute": "pmemsave", -# "arguments": { "val": 10, -# "size": 100, -# "filename": "/tmp/physical-mem-dump" } } -# <- { "return": {} } +# -> { "execute": "pmemsave", +# "arguments": { "val": 10, +# "size": 100, +# "filename": "/tmp/physical-mem-dump" } } +# <- { "return": {} } ## { 'command': 'pmemsave', 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} } @@ -875,29 +875,29 @@ # # Example: # -# -> { "execute": "query-memdev" } -# <- { "return": [ -# { -# "id": "mem1", -# "size": 536870912, -# "merge": false, -# "dump": true, -# "prealloc": false, -# "share": false, -# "host-nodes": [0, 1], -# "policy": "bind" -# }, -# { -# "size": 536870912, -# "merge": false, -# "dump": true, -# "prealloc": true, -# "share": false, -# "host-nodes": [2, 3], -# "policy": "preferred" +# -> { "execute": "query-memdev" } +# <- { "return": [ +# { +# "id": "mem1", +# "size": 536870912, +# "merge": false, +# "dump": true, +# "prealloc": false, +# "share": false, +# "host-nodes": [0, 1], +# "policy": "bind" +# }, +# { +# "size": 536870912, +# "merge": false, +# "dump": true, +# "prealloc": true, +# "share": false, +# "host-nodes": [2, 3], +# "policy": "preferred" +# } +# ] # } -# ] -# } ## { 'command': 'query-memdev', 'returns': ['Memdev'], 'allow-preconfig': true } @@ -990,47 +990,47 @@ # # Examples: # -# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu -# POWER8: +# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu +# POWER8: # -# -> { "execute": "query-hotpluggable-cpus" } -# <- {"return": [ -# { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core", -# "vcpus-count": 1 }, -# { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", -# "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} -# ]}' +# -> { "execute": "query-hotpluggable-cpus" } +# <- {"return": [ +# { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core", +# "vcpus-count": 1 }, +# { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", +# "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} +# ]}' # -# For pc machine type started with -smp 1,maxcpus=2: +# For pc machine type started with -smp 1,maxcpus=2: # -# -> { "execute": "query-hotpluggable-cpus" } -# <- {"return": [ -# { -# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, -# "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} -# }, -# { -# "qom-path": "/machine/unattached/device[0]", -# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, -# "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} -# } -# ]} +# -> { "execute": "query-hotpluggable-cpus" } +# <- {"return": [ +# { +# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, +# "props": {"core-id": 0, "socket-id": 1, "thread-id": 0} +# }, +# { +# "qom-path": "/machine/unattached/device[0]", +# "type": "qemu64-x86_64-cpu", "vcpus-count": 1, +# "props": {"core-id": 0, "socket-id": 0, "thread-id": 0} +# } +# ]} # -# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu -# qemu (Since: 2.11): +# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu +# qemu (Since: 2.11): # -# -> { "execute": "query-hotpluggable-cpus" } -# <- {"return": [ -# { -# "type": "qemu-s390x-cpu", "vcpus-count": 1, -# "props": { "core-id": 1 } -# }, -# { -# "qom-path": "/machine/unattached/device[0]", -# "type": "qemu-s390x-cpu", "vcpus-count": 1, -# "props": { "core-id": 0 } -# } -# ]} +# -> { "execute": "query-hotpluggable-cpus" } +# <- {"return": [ +# { +# "type": "qemu-s390x-cpu", "vcpus-count": 1, +# "props": { "core-id": 1 } +# }, +# { +# "qom-path": "/machine/unattached/device[0]", +# "type": "qemu-s390x-cpu", "vcpus-count": 1, +# "props": { "core-id": 0 } +# } +# ]} ## { 'command': 'query-hotpluggable-cpus', 'returns': ['HotpluggableCPU'], 'allow-preconfig': true } @@ -1074,10 +1074,10 @@ # # Example: # -# -> { "execute": "balloon", "arguments": { "value": 536870912 } } -# <- { "return": {} } +# -> { "execute": "balloon", "arguments": { "value": 536870912 } } +# <- { "return": {} } # -# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# With a 2.5GiB guest this command inflated the ballon to 3GiB. ## { 'command': 'balloon', 'data': {'value': 'int'} } @@ -1108,11 +1108,11 @@ # # Example: # -# -> { "execute": "query-balloon" } -# <- { "return": { -# "actual": 1073741824 -# } -# } +# -> { "execute": "query-balloon" } +# <- { "return": { +# "actual": 1073741824 +# } +# } ## { 'command': 'query-balloon', 'returns': 'BalloonInfo' } @@ -1132,9 +1132,9 @@ # # Example: # -# <- { "event": "BALLOON_CHANGE", -# "data": { "actual": 944766976 }, -# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } +# <- { "event": "BALLOON_CHANGE", +# "data": { "actual": 944766976 }, +# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } ## { 'event': 'BALLOON_CHANGE', 'data': { 'actual': 'int' } } @@ -1172,12 +1172,12 @@ # # Example: # -# -> { "execute": "query-hv-balloon-status-report" } -# <- { "return": { -# "committed": 816640000, -# "available": 3333054464 -# } -# } +# -> { "execute": "query-hv-balloon-status-report" } +# <- { "return": { +# "committed": 816640000, +# "available": 3333054464 +# } +# } ## { 'command': 'query-hv-balloon-status-report', 'returns': 'HvBalloonInfo' } @@ -1193,9 +1193,9 @@ # # Example: # -# <- { "event": "HV_BALLOON_STATUS_REPORT", -# "data": { "committed": 816640000, "available": 3333054464 }, -# "timestamp": { "seconds": 1600295492, "microseconds": 661044 } } +# <- { "event": "HV_BALLOON_STATUS_REPORT", +# "data": { "committed": 816640000, "available": 3333054464 }, +# "timestamp": { "seconds": 1600295492, "microseconds": 661044 } } # ## { 'event': 'HV_BALLOON_STATUS_REPORT', @@ -1226,8 +1226,8 @@ # # Example: # -# -> { "execute": "query-memory-size-summary" } -# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } +# -> { "execute": "query-memory-size-summary" } +# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } # # Since: 2.11 ## @@ -1505,18 +1505,18 @@ # # Example: # -# -> { "execute": "query-memory-devices" } -# <- { "return": [ { "data": -# { "addr": 5368709120, -# "hotpluggable": true, -# "hotplugged": true, -# "id": "d1", -# "memdev": "/objects/memX", -# "node": 0, -# "size": 1073741824, -# "slot": 0}, -# "type": "dimm" -# } ] } +# -> { "execute": "query-memory-devices" } +# <- { "return": [ { "data": +# { "addr": 5368709120, +# "hotpluggable": true, +# "hotplugged": true, +# "id": "d1", +# "memdev": "/objects/memX", +# "node": 0, +# "size": 1073741824, +# "slot": 0}, +# "type": "dimm" +# } ] } ## { 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } @@ -1539,10 +1539,10 @@ # # Example: # -# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", -# "data": { "id": "vm0", "size": 1073741824, -# "qom-path": "/machine/unattached/device[2]" }, -# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } +# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", +# "data": { "id": "vm0", "size": 1073741824, +# "qom-path": "/machine/unattached/device[2]" }, +# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } ## { 'event': 'MEMORY_DEVICE_SIZE_CHANGE', 'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} } @@ -1565,11 +1565,11 @@ # # Example: # -# <- { "event": "MEM_UNPLUG_ERROR", -# "data": { "device": "dimm1", -# "msg": "acpi: device unplug for unsupported device" -# }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "MEM_UNPLUG_ERROR", +# "data": { "device": "dimm1", +# "msg": "acpi: device unplug for unsupported device" +# }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'MEM_UNPLUG_ERROR', 'data': { 'device': 'str', 'msg': 'str' }, @@ -1836,9 +1836,9 @@ # # Example: # -# -> { "execute": "dumpdtb" } -# "arguments": { "filename": "fdt.dtb" } } -# <- { "return": {} } +# -> { "execute": "dumpdtb" } +# "arguments": { "filename": "fdt.dtb" } } +# <- { "return": {} } ## { 'command': 'dumpdtb', 'data': { 'filename': 'str' }, diff --git a/qapi/migration.json b/qapi/migration.json index 5756e650b0..7303e57e8e 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -312,112 +312,112 @@ # # Examples: # -# 1. Before the first migration +# 1. Before the first migration # -# -> { "execute": "query-migrate" } -# <- { "return": {} } +# -> { "execute": "query-migrate" } +# <- { "return": {} } # -# 2. Migration is done and has succeeded +# 2. Migration is done and has succeeded # -# -> { "execute": "query-migrate" } -# <- { "return": { -# "status": "completed", -# "total-time":12345, -# "setup-time":12345, -# "downtime":12345, -# "ram":{ -# "transferred":123, -# "remaining":123, -# "total":246, -# "duplicate":123, -# "normal":123, -# "normal-bytes":123456, -# "dirty-sync-count":15 -# } -# } -# } -# -# 3. Migration is done and has failed -# -# -> { "execute": "query-migrate" } -# <- { "return": { "status": "failed" } } -# -# 4. Migration is being performed and is not a block migration: -# -# -> { "execute": "query-migrate" } -# <- { -# "return":{ -# "status":"active", -# "total-time":12345, -# "setup-time":12345, -# "expected-downtime":12345, -# "ram":{ -# "transferred":123, -# "remaining":123, -# "total":246, -# "duplicate":123, -# "normal":123, -# "normal-bytes":123456, -# "dirty-sync-count":15 +# -> { "execute": "query-migrate" } +# <- { "return": { +# "status": "completed", +# "total-time":12345, +# "setup-time":12345, +# "downtime":12345, +# "ram":{ +# "transferred":123, +# "remaining":123, +# "total":246, +# "duplicate":123, +# "normal":123, +# "normal-bytes":123456, +# "dirty-sync-count":15 +# } # } -# } -# } +# } # -# 5. Migration is being performed and is a block migration: +# 3. Migration is done and has failed # -# -> { "execute": "query-migrate" } -# <- { -# "return":{ -# "status":"active", -# "total-time":12345, -# "setup-time":12345, -# "expected-downtime":12345, -# "ram":{ -# "total":1057024, -# "remaining":1053304, -# "transferred":3720, -# "duplicate":123, -# "normal":123, -# "normal-bytes":123456, -# "dirty-sync-count":15 -# }, -# "disk":{ -# "total":20971520, -# "remaining":20880384, -# "transferred":91136 -# } -# } -# } +# -> { "execute": "query-migrate" } +# <- { "return": { "status": "failed" } } # -# 6. Migration is being performed and XBZRLE is active: +# 4. Migration is being performed and is not a block migration: # -# -> { "execute": "query-migrate" } -# <- { -# "return":{ -# "status":"active", -# "total-time":12345, -# "setup-time":12345, -# "expected-downtime":12345, -# "ram":{ -# "total":1057024, -# "remaining":1053304, -# "transferred":3720, -# "duplicate":10, -# "normal":3333, -# "normal-bytes":3412992, -# "dirty-sync-count":15 -# }, -# "xbzrle-cache":{ -# "cache-size":67108864, -# "bytes":20971520, -# "pages":2444343, -# "cache-miss":2244, -# "cache-miss-rate":0.123, -# "encoding-rate":80.1, -# "overflow":34434 -# } -# } -# } +# -> { "execute": "query-migrate" } +# <- { +# "return":{ +# "status":"active", +# "total-time":12345, +# "setup-time":12345, +# "expected-downtime":12345, +# "ram":{ +# "transferred":123, +# "remaining":123, +# "total":246, +# "duplicate":123, +# "normal":123, +# "normal-bytes":123456, +# "dirty-sync-count":15 +# } +# } +# } +# +# 5. Migration is being performed and is a block migration: +# +# -> { "execute": "query-migrate" } +# <- { +# "return":{ +# "status":"active", +# "total-time":12345, +# "setup-time":12345, +# "expected-downtime":12345, +# "ram":{ +# "total":1057024, +# "remaining":1053304, +# "transferred":3720, +# "duplicate":123, +# "normal":123, +# "normal-bytes":123456, +# "dirty-sync-count":15 +# }, +# "disk":{ +# "total":20971520, +# "remaining":20880384, +# "transferred":91136 +# } +# } +# } +# +# 6. Migration is being performed and XBZRLE is active: +# +# -> { "execute": "query-migrate" } +# <- { +# "return":{ +# "status":"active", +# "total-time":12345, +# "setup-time":12345, +# "expected-downtime":12345, +# "ram":{ +# "total":1057024, +# "remaining":1053304, +# "transferred":3720, +# "duplicate":10, +# "normal":3333, +# "normal-bytes":3412992, +# "dirty-sync-count":15 +# }, +# "xbzrle-cache":{ +# "cache-size":67108864, +# "bytes":20971520, +# "pages":2444343, +# "cache-miss":2244, +# "cache-miss-rate":0.123, +# "encoding-rate":80.1, +# "overflow":34434 +# } +# } +# } ## { 'command': 'query-migrate', 'returns': 'MigrationInfo' } @@ -582,9 +582,9 @@ # # Example: # -# -> { "execute": "migrate-set-capabilities" , "arguments": -# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } -# <- { "return": {} } +# -> { "execute": "migrate-set-capabilities" , "arguments": +# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } +# <- { "return": {} } ## { 'command': 'migrate-set-capabilities', 'data': { 'capabilities': ['MigrationCapabilityStatus'] } } @@ -600,17 +600,17 @@ # # Example: # -# -> { "execute": "query-migrate-capabilities" } -# <- { "return": [ -# {"state": false, "capability": "xbzrle"}, -# {"state": false, "capability": "rdma-pin-all"}, -# {"state": false, "capability": "auto-converge"}, -# {"state": false, "capability": "zero-blocks"}, -# {"state": false, "capability": "compress"}, -# {"state": true, "capability": "events"}, -# {"state": false, "capability": "postcopy-ram"}, -# {"state": false, "capability": "x-colo"} -# ]} +# -> { "execute": "query-migrate-capabilities" } +# <- { "return": [ +# {"state": false, "capability": "xbzrle"}, +# {"state": false, "capability": "rdma-pin-all"}, +# {"state": false, "capability": "auto-converge"}, +# {"state": false, "capability": "zero-blocks"}, +# {"state": false, "capability": "compress"}, +# {"state": true, "capability": "events"}, +# {"state": false, "capability": "postcopy-ram"}, +# {"state": false, "capability": "x-colo"} +# ]} ## { 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']} @@ -1130,9 +1130,9 @@ # # Example: # -# -> { "execute": "migrate-set-parameters" , -# "arguments": { "multifd-channels": 5 } } -# <- { "return": {} } +# -> { "execute": "migrate-set-parameters" , +# "arguments": { "multifd-channels": 5 } } +# <- { "return": {} } ## { 'command': 'migrate-set-parameters', 'boxed': true, 'data': 'MigrateSetParameters' } @@ -1357,15 +1357,15 @@ # # Example: # -# -> { "execute": "query-migrate-parameters" } -# <- { "return": { -# "multifd-channels": 2, -# "cpu-throttle-increment": 10, -# "cpu-throttle-initial": 20, -# "max-bandwidth": 33554432, -# "downtime-limit": 300 -# } -# } +# -> { "execute": "query-migrate-parameters" } +# <- { "return": { +# "multifd-channels": 2, +# "cpu-throttle-increment": 10, +# "cpu-throttle-initial": 20, +# "max-bandwidth": 33554432, +# "downtime-limit": 300 +# } +# } ## { 'command': 'query-migrate-parameters', 'returns': 'MigrationParameters' } @@ -1381,8 +1381,8 @@ # # Example: # -# -> { "execute": "migrate-start-postcopy" } -# <- { "return": {} } +# -> { "execute": "migrate-start-postcopy" } +# <- { "return": {} } ## { 'command': 'migrate-start-postcopy' } @@ -1397,9 +1397,9 @@ # # Example: # -# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, -# "event": "MIGRATION", -# "data": {"status": "completed"} } +# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, +# "event": "MIGRATION", +# "data": {"status": "completed"} } ## { 'event': 'MIGRATION', 'data': {'status': 'MigrationStatus'}} @@ -1416,8 +1416,8 @@ # # Example: # -# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, -# "event": "MIGRATION_PASS", "data": {"pass": 2} } +# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, +# "event": "MIGRATION_PASS", "data": {"pass": 2} } ## { 'event': 'MIGRATION_PASS', 'data': { 'pass': 'int' } } @@ -1500,8 +1500,8 @@ # # Example: # -# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, -# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } +# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, +# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } } ## { 'event': 'COLO_EXIT', 'data': {'mode': 'COLOMode', 'reason': 'COLOExitReason' } } @@ -1543,8 +1543,8 @@ # # Example: # -# -> { "execute": "x-colo-lost-heartbeat" } -# <- { "return": {} } +# -> { "execute": "x-colo-lost-heartbeat" } +# <- { "return": {} } ## { 'command': 'x-colo-lost-heartbeat', 'features': [ 'unstable' ], @@ -1564,8 +1564,8 @@ # # Example: # -# -> { "execute": "migrate_cancel" } -# <- { "return": {} } +# -> { "execute": "migrate_cancel" } +# <- { "return": {} } ## { 'command': 'migrate_cancel' } @@ -1582,9 +1582,9 @@ # # Example: # -# -> { "execute": "migrate-continue" , "arguments": -# { "state": "pre-switchover" } } -# <- { "return": {} } +# -> { "execute": "migrate-continue" , "arguments": +# { "state": "pre-switchover" } } +# <- { "return": {} } ## { 'command': 'migrate-continue', 'data': {'state': 'MigrationStatus'} } @@ -1726,41 +1726,41 @@ # # Example: # -# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } -# <- { "return": {} } +# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } +# <- { "return": {} } # -# -> { "execute": "migrate", -# "arguments": { -# "channels": [ { "channel-type": "main", -# "addr": { "transport": "socket", -# "type": "inet", -# "host": "10.12.34.9", -# "port": "1050" } } ] } } -# <- { "return": {} } +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "socket", +# "type": "inet", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } # -# -> { "execute": "migrate", -# "arguments": { -# "channels": [ { "channel-type": "main", -# "addr": { "transport": "exec", -# "args": [ "/bin/nc", "-p", "6000", -# "/some/sock" ] } } ] } } -# <- { "return": {} } +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "exec", +# "args": [ "/bin/nc", "-p", "6000", +# "/some/sock" ] } } ] } } +# <- { "return": {} } # -# -> { "execute": "migrate", -# "arguments": { -# "channels": [ { "channel-type": "main", -# "addr": { "transport": "rdma", -# "host": "10.12.34.9", -# "port": "1050" } } ] } } -# <- { "return": {} } +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "rdma", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } # -# -> { "execute": "migrate", -# "arguments": { -# "channels": [ { "channel-type": "main", -# "addr": { "transport": "file", -# "filename": "/tmp/migfile", -# "offset": "0x1000" } } ] } } -# <- { "return": {} } +# -> { "execute": "migrate", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "file", +# "filename": "/tmp/migfile", +# "offset": "0x1000" } } ] } } +# <- { "return": {} } # ## { 'command': 'migrate', @@ -1805,34 +1805,34 @@ # # Example: # -# -> { "execute": "migrate-incoming", -# "arguments": { "uri": "tcp:0:4446" } } -# <- { "return": {} } +# -> { "execute": "migrate-incoming", +# "arguments": { "uri": "tcp:0:4446" } } +# <- { "return": {} } # -# -> { "execute": "migrate-incoming", -# "arguments": { -# "channels": [ { "channel-type": "main", -# "addr": { "transport": "socket", -# "type": "inet", -# "host": "10.12.34.9", -# "port": "1050" } } ] } } -# <- { "return": {} } +# -> { "execute": "migrate-incoming", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "socket", +# "type": "inet", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } # -# -> { "execute": "migrate-incoming", -# "arguments": { -# "channels": [ { "channel-type": "main", -# "addr": { "transport": "exec", -# "args": [ "/bin/nc", "-p", "6000", -# "/some/sock" ] } } ] } } -# <- { "return": {} } +# -> { "execute": "migrate-incoming", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "exec", +# "args": [ "/bin/nc", "-p", "6000", +# "/some/sock" ] } } ] } } +# <- { "return": {} } # -# -> { "execute": "migrate-incoming", -# "arguments": { -# "channels": [ { "channel-type": "main", -# "addr": { "transport": "rdma", -# "host": "10.12.34.9", -# "port": "1050" } } ] } } -# <- { "return": {} } +# -> { "execute": "migrate-incoming", +# "arguments": { +# "channels": [ { "channel-type": "main", +# "addr": { "transport": "rdma", +# "host": "10.12.34.9", +# "port": "1050" } } ] } } +# <- { "return": {} } ## { 'command': 'migrate-incoming', 'data': {'*uri': 'str', @@ -1857,9 +1857,9 @@ # # Example: # -# -> { "execute": "xen-save-devices-state", -# "arguments": { "filename": "/tmp/save" } } -# <- { "return": {} } +# -> { "execute": "xen-save-devices-state", +# "arguments": { "filename": "/tmp/save" } } +# <- { "return": {} } ## { 'command': 'xen-save-devices-state', 'data': {'filename': 'str', '*live':'bool' } } @@ -1877,9 +1877,9 @@ # # Example: # -# -> { "execute": "xen-set-global-dirty-log", -# "arguments": { "enable": true } } -# <- { "return": {} } +# -> { "execute": "xen-set-global-dirty-log", +# "arguments": { "enable": true } } +# <- { "return": {} } ## { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } @@ -1897,9 +1897,9 @@ # # Example: # -# -> { "execute": "xen-load-devices-state", -# "arguments": { "filename": "/tmp/resume" } } -# <- { "return": {} } +# -> { "execute": "xen-load-devices-state", +# "arguments": { "filename": "/tmp/resume" } } +# <- { "return": {} } ## { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } @@ -1919,9 +1919,9 @@ # # Example: # -# -> { "execute": "xen-set-replication", -# "arguments": {"enable": true, "primary": false} } -# <- { "return": {} } +# -> { "execute": "xen-set-replication", +# "arguments": {"enable": true, "primary": false} } +# <- { "return": {} } # # Since: 2.9 ## @@ -1954,8 +1954,8 @@ # # Example: # -# -> { "execute": "query-xen-replication-status" } -# <- { "return": { "error": false } } +# -> { "execute": "query-xen-replication-status" } +# <- { "return": { "error": false } } # # Since: 2.9 ## @@ -1972,8 +1972,8 @@ # # Example: # -# -> { "execute": "xen-colo-do-checkpoint" } -# <- { "return": {} } +# -> { "execute": "xen-colo-do-checkpoint" } +# <- { "return": {} } # # Since: 2.9 ## @@ -2010,8 +2010,8 @@ # # Example: # -# -> { "execute": "query-colo-status" } -# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } +# -> { "execute": "query-colo-status" } +# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } } # # Since: 3.1 ## @@ -2030,9 +2030,9 @@ # # Example: # -# -> { "execute": "migrate-recover", -# "arguments": { "uri": "tcp:192.168.1.200:12345" } } -# <- { "return": {} } +# -> { "execute": "migrate-recover", +# "arguments": { "uri": "tcp:192.168.1.200:12345" } } +# <- { "return": {} } # # Since: 3.0 ## @@ -2049,8 +2049,8 @@ # # Example: # -# -> { "execute": "migrate-pause" } -# <- { "return": {} } +# -> { "execute": "migrate-pause" } +# <- { "return": {} } # # Since: 3.0 ## @@ -2070,9 +2070,9 @@ # # Example: # -# <- { "event": "UNPLUG_PRIMARY", -# "data": { "device-id": "hostdev0" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "UNPLUG_PRIMARY", +# "data": { "device-id": "hostdev0" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'UNPLUG_PRIMARY', 'data': { 'device-id': 'str' } } @@ -2231,16 +2231,16 @@ # # Example: # -# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, -# 'sample-pages': 512} } -# <- { "return": {} } +# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, +# 'sample-pages': 512} } +# <- { "return": {} } # -# Measure dirty rate using dirty bitmap for 500 milliseconds: +# Measure dirty rate using dirty bitmap for 500 milliseconds: # -# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, -# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } +# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, +# "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } # -# <- { "return": {} } +# <- { "return": {} } ## { 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', '*calc-time-unit': 'TimeUnit', @@ -2259,17 +2259,17 @@ # # Examples: # -# 1. Measurement is in progress: +# 1. Measurement is in progress: # -# <- {"status": "measuring", "sample-pages": 512, -# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, -# "calc-time-unit": "second"} +# <- {"status": "measuring", "sample-pages": 512, +# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, +# "calc-time-unit": "second"} # -# 2. Measurement has been completed: +# 2. Measurement has been completed: # -# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, -# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, -# "calc-time-unit": "second"} +# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, +# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10, +# "calc-time-unit": "second"} ## { 'command': 'query-dirty-rate', 'data': {'*calc-time-unit': 'TimeUnit' }, 'returns': 'DirtyRateInfo' } @@ -2310,10 +2310,10 @@ # # Example: # -# -> {"execute": "set-vcpu-dirty-limit"} -# "arguments": { "dirty-rate": 200, -# "cpu-index": 1 } } -# <- { "return": {} } +# -> {"execute": "set-vcpu-dirty-limit"} +# "arguments": { "dirty-rate": 200, +# "cpu-index": 1 } } +# <- { "return": {} } ## { 'command': 'set-vcpu-dirty-limit', 'data': { '*cpu-index': 'int', @@ -2334,9 +2334,9 @@ # # Example: # -# -> {"execute": "cancel-vcpu-dirty-limit"}, -# "arguments": { "cpu-index": 1 } } -# <- { "return": {} } +# -> {"execute": "cancel-vcpu-dirty-limit"}, +# "arguments": { "cpu-index": 1 } } +# <- { "return": {} } ## { 'command': 'cancel-vcpu-dirty-limit', 'data': { '*cpu-index': 'int'} } @@ -2351,10 +2351,10 @@ # # Example: # -# -> {"execute": "query-vcpu-dirty-limit"} -# <- {"return": [ -# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, -# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} +# -> {"execute": "query-vcpu-dirty-limit"} +# <- {"return": [ +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} ## { 'command': 'query-vcpu-dirty-limit', 'returns': [ 'DirtyLimitInfo' ] } @@ -2419,40 +2419,40 @@ # # Example: # -# -> { "execute": "snapshot-save", -# "arguments": { -# "job-id": "snapsave0", -# "tag": "my-snap", -# "vmstate": "disk0", -# "devices": ["disk0", "disk1"] -# } -# } -# <- { "return": { } } -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, -# "data": {"status": "created", "id": "snapsave0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, -# "data": {"status": "running", "id": "snapsave0"}} -# <- {"event": "STOP", -# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } -# <- {"event": "RESUME", -# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, -# "data": {"status": "waiting", "id": "snapsave0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, -# "data": {"status": "pending", "id": "snapsave0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, -# "data": {"status": "concluded", "id": "snapsave0"}} -# -> {"execute": "query-jobs"} -# <- {"return": [{"current-progress": 1, -# "status": "concluded", -# "total-progress": 1, -# "type": "snapshot-save", -# "id": "snapsave0"}]} +# -> { "execute": "snapshot-save", +# "arguments": { +# "job-id": "snapsave0", +# "tag": "my-snap", +# "vmstate": "disk0", +# "devices": ["disk0", "disk1"] +# } +# } +# <- { "return": { } } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432121972, "microseconds": 744001}, +# "data": {"status": "created", "id": "snapsave0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432122172, "microseconds": 744001}, +# "data": {"status": "running", "id": "snapsave0"}} +# <- {"event": "STOP", +# "timestamp": {"seconds": 1432122372, "microseconds": 744001} } +# <- {"event": "RESUME", +# "timestamp": {"seconds": 1432122572, "microseconds": 744001} } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432122772, "microseconds": 744001}, +# "data": {"status": "waiting", "id": "snapsave0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432122972, "microseconds": 744001}, +# "data": {"status": "pending", "id": "snapsave0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1432123172, "microseconds": 744001}, +# "data": {"status": "concluded", "id": "snapsave0"}} +# -> {"execute": "query-jobs"} +# <- {"return": [{"current-progress": 1, +# "status": "concluded", +# "total-progress": 1, +# "type": "snapshot-save", +# "id": "snapsave0"}]} # # Since: 6.0 ## @@ -2491,40 +2491,40 @@ # # Example: # -# -> { "execute": "snapshot-load", -# "arguments": { -# "job-id": "snapload0", -# "tag": "my-snap", -# "vmstate": "disk0", -# "devices": ["disk0", "disk1"] -# } -# } -# <- { "return": { } } -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, -# "data": {"status": "created", "id": "snapload0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, -# "data": {"status": "running", "id": "snapload0"}} -# <- {"event": "STOP", -# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } -# <- {"event": "RESUME", -# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, -# "data": {"status": "waiting", "id": "snapload0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, -# "data": {"status": "pending", "id": "snapload0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, -# "data": {"status": "concluded", "id": "snapload0"}} -# -> {"execute": "query-jobs"} -# <- {"return": [{"current-progress": 1, -# "status": "concluded", -# "total-progress": 1, -# "type": "snapshot-load", -# "id": "snapload0"}]} +# -> { "execute": "snapshot-load", +# "arguments": { +# "job-id": "snapload0", +# "tag": "my-snap", +# "vmstate": "disk0", +# "devices": ["disk0", "disk1"] +# } +# } +# <- { "return": { } } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472124172, "microseconds": 744001}, +# "data": {"status": "created", "id": "snapload0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472125172, "microseconds": 744001}, +# "data": {"status": "running", "id": "snapload0"}} +# <- {"event": "STOP", +# "timestamp": {"seconds": 1472125472, "microseconds": 744001} } +# <- {"event": "RESUME", +# "timestamp": {"seconds": 1472125872, "microseconds": 744001} } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472126172, "microseconds": 744001}, +# "data": {"status": "waiting", "id": "snapload0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472127172, "microseconds": 744001}, +# "data": {"status": "pending", "id": "snapload0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1472128172, "microseconds": 744001}, +# "data": {"status": "concluded", "id": "snapload0"}} +# -> {"execute": "query-jobs"} +# <- {"return": [{"current-progress": 1, +# "status": "concluded", +# "total-progress": 1, +# "type": "snapshot-load", +# "id": "snapload0"}]} # # Since: 6.0 ## @@ -2554,35 +2554,35 @@ # # Example: # -# -> { "execute": "snapshot-delete", -# "arguments": { -# "job-id": "snapdelete0", -# "tag": "my-snap", -# "devices": ["disk0", "disk1"] -# } -# } -# <- { "return": { } } -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, -# "data": {"status": "created", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, -# "data": {"status": "running", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, -# "data": {"status": "waiting", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, -# "data": {"status": "pending", "id": "snapdelete0"}} -# <- {"event": "JOB_STATUS_CHANGE", -# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, -# "data": {"status": "concluded", "id": "snapdelete0"}} -# -> {"execute": "query-jobs"} -# <- {"return": [{"current-progress": 1, -# "status": "concluded", -# "total-progress": 1, -# "type": "snapshot-delete", -# "id": "snapdelete0"}]} +# -> { "execute": "snapshot-delete", +# "arguments": { +# "job-id": "snapdelete0", +# "tag": "my-snap", +# "devices": ["disk0", "disk1"] +# } +# } +# <- { "return": { } } +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442124172, "microseconds": 744001}, +# "data": {"status": "created", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442125172, "microseconds": 744001}, +# "data": {"status": "running", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442126172, "microseconds": 744001}, +# "data": {"status": "waiting", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442127172, "microseconds": 744001}, +# "data": {"status": "pending", "id": "snapdelete0"}} +# <- {"event": "JOB_STATUS_CHANGE", +# "timestamp": {"seconds": 1442128172, "microseconds": 744001}, +# "data": {"status": "concluded", "id": "snapdelete0"}} +# -> {"execute": "query-jobs"} +# <- {"return": [{"current-progress": 1, +# "status": "concluded", +# "total-progress": 1, +# "type": "snapshot-delete", +# "id": "snapdelete0"}]} # # Since: 6.0 ## diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 03e83c053f..542a3e42f2 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -13,8 +13,8 @@ # # Example: # -# -> { "execute": "rtc-reset-reinjection" } -# <- { "return": {} } +# -> { "execute": "rtc-reset-reinjection" } +# <- { "return": {} } ## { 'command': 'rtc-reset-reinjection', 'if': 'TARGET_I386' } @@ -91,10 +91,10 @@ # # Example: # -# -> { "execute": "query-sev" } -# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, -# "build-id" : 0, "policy" : 0, "state" : "running", -# "handle" : 1 } } +# -> { "execute": "query-sev" } +# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, +# "build-id" : 0, "policy" : 0, "state" : "running", +# "handle" : 1 } } ## { 'command': 'query-sev', 'returns': 'SevInfo', 'if': 'TARGET_I386' } @@ -122,8 +122,8 @@ # # Example: # -# -> { "execute": "query-sev-launch-measure" } -# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } +# -> { "execute": "query-sev-launch-measure" } +# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } ## { 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo', 'if': 'TARGET_I386' } @@ -167,10 +167,10 @@ # # Example: # -# -> { "execute": "query-sev-capabilities" } -# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", -# "cpu0-id": "2lvmGwo+...61iEinw==", -# "cbitpos": 47, "reduced-phys-bits": 1}} +# -> { "execute": "query-sev-capabilities" } +# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", +# "cpu0-id": "2lvmGwo+...61iEinw==", +# "cbitpos": 47, "reduced-phys-bits": 1}} ## { 'command': 'query-sev-capabilities', 'returns': 'SevCapability', 'if': 'TARGET_I386' } @@ -221,9 +221,9 @@ # # Example: # -# -> { "execute" : "query-sev-attestation-report", -# "arguments": { "mnonce": "aaaaaaa" } } -# <- { "return" : { "data": "aaaaaaaabbbddddd"} } +# -> { "execute" : "query-sev-attestation-report", +# "arguments": { "mnonce": "aaaaaaa" } } +# <- { "return" : { "data": "aaaaaaaabbbddddd"} } ## { 'command': 'query-sev-attestation-report', 'data': { 'mnonce': 'str' }, @@ -241,9 +241,9 @@ # # Example: # -# -> { "execute": "dump-skeys", -# "arguments": { "filename": "/tmp/skeys" } } -# <- { "return": {} } +# -> { "execute": "dump-skeys", +# "arguments": { "filename": "/tmp/skeys" } } +# <- { "return": {} } ## { 'command': 'dump-skeys', 'data': { 'filename': 'str' }, @@ -286,9 +286,9 @@ # # Example: # -# -> { "execute": "query-gic-capabilities" } -# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, -# { "version": 3, "emulated": false, "kernel": true } ] } +# -> { "execute": "query-gic-capabilities" } +# <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, +# { "version": 3, "emulated": false, "kernel": true } ] } ## { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'], 'if': 'TARGET_ARM' } @@ -344,11 +344,11 @@ # # Example: # -# -> { "execute": "query-sgx" } -# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, -# "flc": true, -# "sections": [{"node": 0, "size": 67108864}, -# {"node": 1, "size": 29360128}]} } +# -> { "execute": "query-sgx" } +# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, +# "flc": true, +# "sections": [{"node": 0, "size": 67108864}, +# {"node": 1, "size": 29360128}]} } ## { 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } @@ -363,11 +363,11 @@ # # Example: # -# -> { "execute": "query-sgx-capabilities" } -# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, -# "flc": true, -# "section" : [{"node": 0, "size": 67108864}, -# {"node": 1, "size": 29360128}]} } +# -> { "execute": "query-sgx-capabilities" } +# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, +# "flc": true, +# "section" : [{"node": 0, "size": 67108864}, +# {"node": 1, "size": 29360128}]} } ## { 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' } @@ -438,28 +438,28 @@ # # Example: # -# -> { "execute": "xen-event-list" } -# <- { "return": [ -# { -# "pending": false, -# "port": 1, -# "vcpu": 1, -# "remote-domain": "qemu", -# "masked": false, -# "type": "interdomain", -# "target": 1 -# }, -# { -# "pending": false, -# "port": 2, -# "vcpu": 0, -# "remote-domain": "", -# "masked": false, -# "type": "virq", -# "target": 0 -# } -# ] -# } +# -> { "execute": "xen-event-list" } +# <- { "return": [ +# { +# "pending": false, +# "port": 1, +# "vcpu": 1, +# "remote-domain": "qemu", +# "masked": false, +# "type": "interdomain", +# "target": 1 +# }, +# { +# "pending": false, +# "port": 2, +# "vcpu": 0, +# "remote-domain": "", +# "masked": false, +# "type": "virq", +# "target": 0 +# } +# ] +# } ## { 'command': 'xen-event-list', 'returns': ['EvtchnInfo'], @@ -479,8 +479,8 @@ # # Example: # -# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } -# <- { "return": { } } +# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } +# <- { "return": { } } ## { 'command': 'xen-event-inject', 'data': { 'port': 'uint32' }, diff --git a/qapi/misc.json b/qapi/misc.json index 4108a0c951..11c55c2b6c 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -34,9 +34,9 @@ # # Example: # -# -> { "execute": "add_client", "arguments": { "protocol": "vnc", -# "fdname": "myclient" } } -# <- { "return": {} } +# -> { "execute": "add_client", "arguments": { "protocol": "vnc", +# "fdname": "myclient" } } +# <- { "return": {} } ## { 'command': 'add_client', 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool', @@ -64,8 +64,8 @@ # # Example: # -# -> { "execute": "query-name" } -# <- { "return": { "name": "qemu-name" } } +# -> { "execute": "query-name" } +# <- { "return": { "name": "qemu-name" } } ## { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true } @@ -115,18 +115,18 @@ # # Example: # -# -> { "execute": "query-iothreads" } -# <- { "return": [ -# { -# "id":"iothread0", -# "thread-id":3134 -# }, -# { -# "id":"iothread1", -# "thread-id":3135 -# } -# ] -# } +# -> { "execute": "query-iothreads" } +# <- { "return": [ +# { +# "id":"iothread0", +# "thread-id":3134 +# }, +# { +# "id":"iothread1", +# "thread-id":3135 +# } +# ] +# } ## { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'], 'allow-preconfig': true } @@ -148,8 +148,8 @@ # # Example: # -# -> { "execute": "stop" } -# <- { "return": {} } +# -> { "execute": "stop" } +# <- { "return": {} } ## { 'command': 'stop' } @@ -174,8 +174,8 @@ # # Example: # -# -> { "execute": "cont" } -# <- { "return": {} } +# -> { "execute": "cont" } +# <- { "return": {} } ## { 'command': 'cont' } @@ -200,8 +200,8 @@ # # Example: # -# -> { "execute": "x-exit-preconfig" } -# <- { "return": {} } +# -> { "execute": "x-exit-preconfig" } +# <- { "return": {} } ## { 'command': 'x-exit-preconfig', 'allow-preconfig': true, 'features': [ 'unstable' ] } @@ -240,9 +240,9 @@ # # Example: # -# -> { "execute": "human-monitor-command", -# "arguments": { "command-line": "info kvm" } } -# <- { "return": "kvm support: enabled\r\n" } +# -> { "execute": "human-monitor-command", +# "arguments": { "command-line": "info kvm" } } +# <- { "return": "kvm support: enabled\r\n" } ## { 'command': 'human-monitor-command', 'data': {'command-line': 'str', '*cpu-index': 'int'}, @@ -268,8 +268,8 @@ # # Example: # -# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } -# <- { "return": {} } +# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } +# <- { "return": {} } ## { 'command': 'getfd', 'data': {'fdname': 'str'}, 'if': 'CONFIG_POSIX' } @@ -297,8 +297,8 @@ # # Example: # -# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } } -# <- { "return": {} } +# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } } +# <- { "return": {} } ## { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' } @@ -315,8 +315,8 @@ # # Example: # -# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } -# <- { "return": {} } +# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } +# <- { "return": {} } ## { 'command': 'closefd', 'data': {'fdname': 'str'} } @@ -357,8 +357,8 @@ # # Example: # -# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } -# <- { "return": { "fdset-id": 1, "fd": 3 } } +# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } +# <- { "return": { "fdset-id": 1, "fd": 3 } } ## { 'command': 'add-fd', 'data': { '*fdset-id': 'int', @@ -388,8 +388,8 @@ # # Example: # -# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } -# <- { "return": {} } +# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } +# <- { "return": {} } ## { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} } @@ -434,34 +434,34 @@ # # Example: # -# -> { "execute": "query-fdsets" } -# <- { "return": [ -# { -# "fds": [ +# -> { "execute": "query-fdsets" } +# <- { "return": [ # { -# "fd": 30, -# "opaque": "rdonly:/path/to/file" +# "fds": [ +# { +# "fd": 30, +# "opaque": "rdonly:/path/to/file" +# }, +# { +# "fd": 24, +# "opaque": "rdwr:/path/to/file" +# } +# ], +# "fdset-id": 1 # }, # { -# "fd": 24, -# "opaque": "rdwr:/path/to/file" +# "fds": [ +# { +# "fd": 28 +# }, +# { +# "fd": 29 +# } +# ], +# "fdset-id": 0 # } -# ], -# "fdset-id": 1 -# }, -# { -# "fds": [ -# { -# "fd": 28 -# }, -# { -# "fd": 29 -# } -# ], -# "fdset-id": 0 +# ] # } -# ] -# } ## { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] } @@ -535,24 +535,24 @@ # # Example: # -# -> { "execute": "query-command-line-options", -# "arguments": { "option": "option-rom" } } -# <- { "return": [ -# { -# "parameters": [ -# { -# "name": "romfile", -# "type": "string" -# }, -# { -# "name": "bootindex", -# "type": "number" -# } -# ], -# "option": "option-rom" -# } -# ] -# } +# -> { "execute": "query-command-line-options", +# "arguments": { "option": "option-rom" } } +# <- { "return": [ +# { +# "parameters": [ +# { +# "name": "romfile", +# "type": "string" +# }, +# { +# "name": "bootindex", +# "type": "number" +# } +# ], +# "option": "option-rom" +# } +# ] +# } ## {'command': 'query-command-line-options', 'data': {'*option': 'str'}, @@ -577,9 +577,9 @@ # # Example: # -# <- { "event": "RTC_CHANGE", -# "data": { "offset": 78 }, -# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } +# <- { "event": "RTC_CHANGE", +# "data": { "offset": 78 }, +# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } ## { 'event': 'RTC_CHANGE', 'data': { 'offset': 'int', 'qom-path': 'str' } } @@ -604,12 +604,12 @@ # # Example: # -# <- { "event": "VFU_CLIENT_HANGUP", -# "data": { "vfu-id": "vfu1", -# "vfu-qom-path": "/objects/vfu1", -# "dev-id": "sas1", -# "dev-qom-path": "/machine/peripheral/sas1" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "VFU_CLIENT_HANGUP", +# "data": { "vfu-id": "vfu1", +# "vfu-qom-path": "/objects/vfu1", +# "dev-id": "sas1", +# "dev-qom-path": "/machine/peripheral/sas1" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'VFU_CLIENT_HANGUP', 'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str', diff --git a/qapi/net.json b/qapi/net.json index 0a993e1a3d..1374caac64 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -29,9 +29,9 @@ # # Example: # -# -> { "execute": "set_link", -# "arguments": { "name": "e1000.0", "up": false } } -# <- { "return": {} } +# -> { "execute": "set_link", +# "arguments": { "name": "e1000.0", "up": false } } +# <- { "return": {} } ## { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} } @@ -50,10 +50,10 @@ # # Example: # -# -> { "execute": "netdev_add", -# "arguments": { "type": "user", "id": "netdev1", -# "dnssearch": [ { "str": "example.org" } ] } } -# <- { "return": {} } +# -> { "execute": "netdev_add", +# "arguments": { "type": "user", "id": "netdev1", +# "dnssearch": [ { "str": "example.org" } ] } } +# <- { "return": {} } ## { 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true, 'allow-preconfig': true } @@ -73,8 +73,8 @@ # # Example: # -# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } -# <- { "return": {} } +# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } +# <- { "return": {} } ## { 'command': 'netdev_del', 'data': {'id': 'str'}, 'allow-preconfig': true } @@ -836,32 +836,32 @@ # # Example: # -# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } -# <- { "return": [ -# { -# "promiscuous": true, -# "name": "vnet0", -# "main-mac": "52:54:00:12:34:56", -# "unicast": "normal", -# "vlan": "normal", -# "vlan-table": [ -# 4, -# 0 -# ], -# "unicast-table": [ -# ], -# "multicast": "normal", -# "multicast-overflow": false, -# "unicast-overflow": false, -# "multicast-table": [ -# "01:00:5e:00:00:01", -# "33:33:00:00:00:01", -# "33:33:ff:12:34:56" -# ], -# "broadcast-allowed": false -# } -# ] -# } +# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } +# <- { "return": [ +# { +# "promiscuous": true, +# "name": "vnet0", +# "main-mac": "52:54:00:12:34:56", +# "unicast": "normal", +# "vlan": "normal", +# "vlan-table": [ +# 4, +# 0 +# ], +# "unicast-table": [ +# ], +# "multicast": "normal", +# "multicast-overflow": false, +# "unicast-overflow": false, +# "multicast-table": [ +# "01:00:5e:00:00:01", +# "33:33:00:00:00:01", +# "33:33:ff:12:34:56" +# ], +# "broadcast-allowed": false +# } +# ] +# } ## { 'command': 'query-rx-filter', 'data': { '*name': 'str' }, @@ -881,10 +881,10 @@ # # Example: # -# <- { "event": "NIC_RX_FILTER_CHANGED", -# "data": { "name": "vnet0", -# "path": "/machine/peripheral/vnet0/virtio-backend" }, -# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } +# <- { "event": "NIC_RX_FILTER_CHANGED", +# "data": { "name": "vnet0", +# "path": "/machine/peripheral/vnet0/virtio-backend" }, +# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } ## { 'event': 'NIC_RX_FILTER_CHANGED', 'data': { '*name': 'str', 'path': 'str' } } @@ -930,11 +930,11 @@ # # Example: # -# -> { "execute": "announce-self", -# "arguments": { -# "initial": 50, "max": 550, "rounds": 10, "step": 50, -# "interfaces": ["vn2", "vn3"], "id": "bob" } } -# <- { "return": {} } +# -> { "execute": "announce-self", +# "arguments": { +# "initial": 50, "max": 550, "rounds": 10, "step": 50, +# "interfaces": ["vn2", "vn3"], "id": "bob" } } +# <- { "return": {} } # # Since: 4.0 ## @@ -955,9 +955,9 @@ # # Example: # -# <- { "event": "FAILOVER_NEGOTIATED", -# "data": { "device-id": "net1" }, -# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } +# <- { "event": "FAILOVER_NEGOTIATED", +# "data": { "device-id": "net1" }, +# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } ## { 'event': 'FAILOVER_NEGOTIATED', 'data': {'device-id': 'str'} } @@ -975,16 +975,16 @@ # # Examples: # -# <- { "event": "NETDEV_STREAM_CONNECTED", -# "data": { "netdev-id": "netdev0", -# "addr": { "port": "47666", "ipv6": true, -# "host": "::1", "type": "inet" } }, -# "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } +# <- { "event": "NETDEV_STREAM_CONNECTED", +# "data": { "netdev-id": "netdev0", +# "addr": { "port": "47666", "ipv6": true, +# "host": "::1", "type": "inet" } }, +# "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } # -# <- { "event": "NETDEV_STREAM_CONNECTED", -# "data": { "netdev-id": "netdev0", -# "addr": { "path": "/tmp/qemu0", "type": "unix" } }, -# "timestamp": { "seconds": 1666269706, "microseconds": 413651 } } +# <- { "event": "NETDEV_STREAM_CONNECTED", +# "data": { "netdev-id": "netdev0", +# "addr": { "path": "/tmp/qemu0", "type": "unix" } }, +# "timestamp": { "seconds": 1666269706, "microseconds": 413651 } } ## { 'event': 'NETDEV_STREAM_CONNECTED', 'data': { 'netdev-id': 'str', @@ -1001,9 +1001,9 @@ # # Example: # -# <- { 'event': 'NETDEV_STREAM_DISCONNECTED', -# 'data': {'netdev-id': 'netdev0'}, -# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} } +# <- { 'event': 'NETDEV_STREAM_DISCONNECTED', +# 'data': {'netdev-id': 'netdev0'}, +# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} } ## { 'event': 'NETDEV_STREAM_DISCONNECTED', 'data': { 'netdev-id': 'str' } } diff --git a/qapi/pci.json b/qapi/pci.json index 086c773052..08bf695863 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -184,132 +184,132 @@ # # Example: # -# -> { "execute": "query-pci" } -# <- { "return": [ -# { -# "bus": 0, -# "devices": [ -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 0, -# "class_info": { -# "class": 1536, -# "desc": "Host bridge" -# }, -# "id": { -# "device": 32902, -# "vendor": 4663 -# }, -# "function": 0, -# "regions": [ -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 1, -# "class_info": { -# "class": 1537, -# "desc": "ISA bridge" -# }, -# "id": { -# "device": 32902, -# "vendor": 28672 -# }, -# "function": 0, -# "regions": [ -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 1, -# "class_info": { -# "class": 257, -# "desc": "IDE controller" -# }, -# "id": { -# "device": 32902, -# "vendor": 28688 -# }, -# "function": 1, -# "regions": [ -# { -# "bar": 4, -# "size": 16, -# "address": 49152, -# "type": "io" -# } -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 2, -# "class_info": { -# "class": 768, -# "desc": "VGA controller" -# }, -# "id": { -# "device": 4115, -# "vendor": 184 -# }, -# "function": 0, -# "regions": [ -# { -# "prefetch": true, -# "mem_type_64": false, -# "bar": 0, -# "size": 33554432, -# "address": 4026531840, -# "type": "memory" -# }, -# { -# "prefetch": false, -# "mem_type_64": false, -# "bar": 1, -# "size": 4096, -# "address": 4060086272, -# "type": "memory" -# }, -# { -# "prefetch": false, -# "mem_type_64": false, -# "bar": 6, -# "size": 65536, -# "address": -1, -# "type": "memory" -# } -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "irq": 11, -# "slot": 4, -# "class_info": { -# "class": 1280, -# "desc": "RAM controller" -# }, -# "id": { -# "device": 6900, -# "vendor": 4098 -# }, -# "function": 0, -# "regions": [ -# { -# "bar": 0, -# "size": 32, -# "address": 49280, -# "type": "io" -# } -# ] -# } -# ] -# } -# ] -# } +# -> { "execute": "query-pci" } +# <- { "return": [ +# { +# "bus": 0, +# "devices": [ +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 0, +# "class_info": { +# "class": 1536, +# "desc": "Host bridge" +# }, +# "id": { +# "device": 32902, +# "vendor": 4663 +# }, +# "function": 0, +# "regions": [ +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 1, +# "class_info": { +# "class": 1537, +# "desc": "ISA bridge" +# }, +# "id": { +# "device": 32902, +# "vendor": 28672 +# }, +# "function": 0, +# "regions": [ +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 1, +# "class_info": { +# "class": 257, +# "desc": "IDE controller" +# }, +# "id": { +# "device": 32902, +# "vendor": 28688 +# }, +# "function": 1, +# "regions": [ +# { +# "bar": 4, +# "size": 16, +# "address": 49152, +# "type": "io" +# } +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 2, +# "class_info": { +# "class": 768, +# "desc": "VGA controller" +# }, +# "id": { +# "device": 4115, +# "vendor": 184 +# }, +# "function": 0, +# "regions": [ +# { +# "prefetch": true, +# "mem_type_64": false, +# "bar": 0, +# "size": 33554432, +# "address": 4026531840, +# "type": "memory" +# }, +# { +# "prefetch": false, +# "mem_type_64": false, +# "bar": 1, +# "size": 4096, +# "address": 4060086272, +# "type": "memory" +# }, +# { +# "prefetch": false, +# "mem_type_64": false, +# "bar": 6, +# "size": 65536, +# "address": -1, +# "type": "memory" +# } +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "irq": 11, +# "slot": 4, +# "class_info": { +# "class": 1280, +# "desc": "RAM controller" +# }, +# "id": { +# "device": 6900, +# "vendor": 4098 +# }, +# "function": 0, +# "regions": [ +# { +# "bar": 0, +# "size": 32, +# "address": 49280, +# "type": "io" +# } +# ] +# } +# ] +# } +# ] +# } # # Note: This example has been shortened as the real response is too # long. diff --git a/qapi/qdev.json b/qapi/qdev.json index 3b3ccfa413..32ffaee644 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -64,11 +64,11 @@ # # Example: # -# -> { "execute": "device_add", -# "arguments": { "driver": "e1000", "id": "net1", -# "bus": "pci.0", -# "mac": "52:54:00:12:34:56" } } -# <- { "return": {} } +# -> { "execute": "device_add", +# "arguments": { "driver": "e1000", "id": "net1", +# "bus": "pci.0", +# "mac": "52:54:00:12:34:56" } } +# <- { "return": {} } # # TODO: This command effectively bypasses QAPI completely due to its # "additional arguments" business. It shouldn't have been added @@ -107,13 +107,13 @@ # # Examples: # -# -> { "execute": "device_del", -# "arguments": { "id": "net1" } } -# <- { "return": {} } +# -> { "execute": "device_del", +# "arguments": { "id": "net1" } } +# <- { "return": {} } # -# -> { "execute": "device_del", -# "arguments": { "id": "/machine/peripheral-anon/device[0]" } } -# <- { "return": {} } +# -> { "execute": "device_del", +# "arguments": { "id": "/machine/peripheral-anon/device[0]" } } +# <- { "return": {} } ## { 'command': 'device_del', 'data': {'id': 'str'} } @@ -133,10 +133,10 @@ # # Example: # -# <- { "event": "DEVICE_DELETED", -# "data": { "device": "virtio-net-pci-0", -# "path": "/machine/peripheral/virtio-net-pci-0" }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# <- { "event": "DEVICE_DELETED", +# "data": { "device": "virtio-net-pci-0", +# "path": "/machine/peripheral/virtio-net-pci-0" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } ## { 'event': 'DEVICE_DELETED', 'data': { '*device': 'str', 'path': 'str' } } @@ -155,10 +155,10 @@ # # Example: # -# <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", -# "data": { "device": "core1", -# "path": "/machine/peripheral/core1" }, -# "timestamp": { "seconds": 1615570772, "microseconds": 202844 } } +# <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", +# "data": { "device": "core1", +# "path": "/machine/peripheral/core1" }, +# "timestamp": { "seconds": 1615570772, "microseconds": 202844 } } ## { 'event': 'DEVICE_UNPLUG_GUEST_ERROR', 'data': { '*device': 'str', 'path': 'str' } } diff --git a/qapi/qom.json b/qapi/qom.json index 84af23fe24..2a6e49365a 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -61,12 +61,12 @@ # # Example: # -# -> { "execute": "qom-list", -# "arguments": { "path": "/chardevs" } } -# <- { "return": [ { "name": "type", "type": "string" }, -# { "name": "parallel0", "type": "child" }, -# { "name": "serial0", "type": "child" }, -# { "name": "mon0", "type": "child" } ] } +# -> { "execute": "qom-list", +# "arguments": { "path": "/chardevs" } } +# <- { "return": [ { "name": "type", "type": "string" }, +# { "name": "parallel0", "type": "child" }, +# { "name": "serial0", "type": "child" }, +# { "name": "mon0", "type": "child" } ] } ## { 'command': 'qom-list', 'data': { 'path': 'str' }, @@ -106,19 +106,19 @@ # # Examples: # -# 1. Use absolute path +# 1. Use absolute path # -# -> { "execute": "qom-get", -# "arguments": { "path": "/machine/unattached/device[0]", -# "property": "hotplugged" } } -# <- { "return": false } +# -> { "execute": "qom-get", +# "arguments": { "path": "/machine/unattached/device[0]", +# "property": "hotplugged" } } +# <- { "return": false } # -# 2. Use partial path +# 2. Use partial path # -# -> { "execute": "qom-get", -# "arguments": { "path": "unattached/sysbus", -# "property": "type" } } -# <- { "return": "System" } +# -> { "execute": "qom-get", +# "arguments": { "path": "unattached/sysbus", +# "property": "type" } } +# <- { "return": "System" } ## { 'command': 'qom-get', 'data': { 'path': 'str', 'property': 'str' }, @@ -141,11 +141,11 @@ # # Example: # -# -> { "execute": "qom-set", -# "arguments": { "path": "/machine", -# "property": "graphics", -# "value": false } } -# <- { "return": {} } +# -> { "execute": "qom-set", +# "arguments": { "path": "/machine", +# "property": "graphics", +# "value": false } } +# <- { "return": {} } ## { 'command': 'qom-set', 'data': { 'path': 'str', 'property': 'str', 'value': 'any' }, @@ -1064,10 +1064,10 @@ # # Example: # -# -> { "execute": "object-add", -# "arguments": { "qom-type": "rng-random", "id": "rng1", -# "filename": "/dev/hwrng" } } -# <- { "return": {} } +# -> { "execute": "object-add", +# "arguments": { "qom-type": "rng-random", "id": "rng1", +# "filename": "/dev/hwrng" } } +# <- { "return": {} } ## { 'command': 'object-add', 'data': 'ObjectOptions', 'boxed': true, 'allow-preconfig': true } @@ -1087,8 +1087,8 @@ # # Example: # -# -> { "execute": "object-del", "arguments": { "id": "rng1" } } -# <- { "return": {} } +# -> { "execute": "object-del", "arguments": { "id": "rng1" } } +# <- { "return": {} } ## { 'command': 'object-del', 'data': {'id': 'str'}, 'allow-preconfig': true } diff --git a/qapi/rdma.json b/qapi/rdma.json index 23ebcf7885..195c001850 100644 --- a/qapi/rdma.json +++ b/qapi/rdma.json @@ -23,13 +23,13 @@ # # Example: # -# <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760}, -# "event": "RDMA_GID_STATUS_CHANGED", -# "data": -# {"netdev": "bridge0", -# "interface-id": 15880512517475447892, -# "gid-status": true, -# "subnet-prefix": 33022}} +# <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760}, +# "event": "RDMA_GID_STATUS_CHANGED", +# "data": +# {"netdev": "bridge0", +# "interface-id": 15880512517475447892, +# "gid-status": true, +# "subnet-prefix": 33022}} ## { 'event': 'RDMA_GID_STATUS_CHANGED', 'data': { 'netdev' : 'str', diff --git a/qapi/replay.json b/qapi/replay.json index 289b2d3658..8626fb58f4 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -56,8 +56,8 @@ # # Example: # -# -> { "execute": "query-replay" } -# <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } } +# -> { "execute": "query-replay" } +# <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } } ## { 'command': 'query-replay', 'returns': 'ReplayInfo' } @@ -78,8 +78,8 @@ # # Example: # -# -> { "execute": "replay-break", "arguments": { "icount": 220414 } } -# <- { "return": {} } +# -> { "execute": "replay-break", "arguments": { "icount": 220414 } } +# <- { "return": {} } ## { 'command': 'replay-break', 'data': { 'icount': 'int' } } @@ -93,8 +93,8 @@ # # Example: # -# -> { "execute": "replay-delete-break" } -# <- { "return": {} } +# -> { "execute": "replay-delete-break" } +# <- { "return": {} } ## { 'command': 'replay-delete-break' } @@ -114,7 +114,7 @@ # # Example: # -# -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } -# <- { "return": {} } +# -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } +# <- { "return": {} } ## { 'command': 'replay-seek', 'data': { 'icount': 'int' } } diff --git a/qapi/rocker.json b/qapi/rocker.json index 31ce0b36f6..5635cf174f 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -32,8 +32,8 @@ # # Example: # -# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } -# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} +# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } +# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} ## { 'command': 'query-rocker', 'data': { 'name': 'str' }, @@ -100,12 +100,12 @@ # # Example: # -# -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } -# <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", -# "autoneg": "off", "link-up": true, "speed": 10000}, -# {"duplex": "full", "enabled": true, "name": "sw1.2", -# "autoneg": "off", "link-up": true, "speed": 10000} -# ]} +# -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } +# <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", +# "autoneg": "off", "link-up": true, "speed": 10000}, +# {"duplex": "full", "enabled": true, "name": "sw1.2", +# "autoneg": "off", "link-up": true, "speed": 10000} +# ]} ## { 'command': 'query-rocker-ports', 'data': { 'name': 'str' }, @@ -242,16 +242,16 @@ # # Example: # -# -> { "execute": "query-rocker-of-dpa-flows", -# "arguments": { "name": "sw1" } } -# <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0}, -# "hits": 138, -# "cookie": 0, -# "action": {"goto-tbl": 10}, -# "mask": {"in-pport": 4294901760} -# }, -# {...more...}, -# ]} +# -> { "execute": "query-rocker-of-dpa-flows", +# "arguments": { "name": "sw1" } } +# <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0}, +# "hits": 138, +# "cookie": 0, +# "action": {"goto-tbl": 10}, +# "mask": {"in-pport": 4294901760} +# }, +# {...more...}, +# ]} ## { 'command': 'query-rocker-of-dpa-flows', 'data': { 'name': 'str', '*tbl-id': 'uint32' }, @@ -317,21 +317,21 @@ # # Example: # -# -> { "execute": "query-rocker-of-dpa-groups", -# "arguments": { "name": "sw1" } } -# <- { "return": [ {"type": 0, "out-pport": 2, -# "pport": 2, "vlan-id": 3841, -# "pop-vlan": 1, "id": 251723778}, -# {"type": 0, "out-pport": 0, -# "pport": 0, "vlan-id": 3841, -# "pop-vlan": 1, "id": 251723776}, -# {"type": 0, "out-pport": 1, -# "pport": 1, "vlan-id": 3840, -# "pop-vlan": 1, "id": 251658241}, -# {"type": 0, "out-pport": 0, -# "pport": 0, "vlan-id": 3840, -# "pop-vlan": 1, "id": 251658240} -# ]} +# -> { "execute": "query-rocker-of-dpa-groups", +# "arguments": { "name": "sw1" } } +# <- { "return": [ {"type": 0, "out-pport": 2, +# "pport": 2, "vlan-id": 3841, +# "pop-vlan": 1, "id": 251723778}, +# {"type": 0, "out-pport": 0, +# "pport": 0, "vlan-id": 3841, +# "pop-vlan": 1, "id": 251723776}, +# {"type": 0, "out-pport": 1, +# "pport": 1, "vlan-id": 3840, +# "pop-vlan": 1, "id": 251658241}, +# {"type": 0, "out-pport": 0, +# "pport": 0, "vlan-id": 3840, +# "pop-vlan": 1, "id": 251658240} +# ]} ## { 'command': 'query-rocker-of-dpa-groups', 'data': { 'name': 'str', '*type': 'uint8' }, diff --git a/qapi/run-state.json b/qapi/run-state.json index 08bc99cb85..d19d23a0fd 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -128,9 +128,9 @@ # # Example: # -# -> { "execute": "query-status" } -# <- { "return": { "running": true, -# "status": "running" } } +# -> { "execute": "query-status" } +# <- { "return": { "running": true, +# "status": "running" } } ## { 'command': 'query-status', 'returns': 'StatusInfo', 'allow-preconfig': true } @@ -157,9 +157,9 @@ # # Example: # -# <- { "event": "SHUTDOWN", -# "data": { "guest": true, "reason": "guest-shutdown" }, -# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } +# <- { "event": "SHUTDOWN", +# "data": { "guest": true, "reason": "guest-shutdown" }, +# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } ## { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } @@ -173,8 +173,8 @@ # # Example: # -# <- { "event": "POWERDOWN", -# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } +# <- { "event": "POWERDOWN", +# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } ## { 'event': 'POWERDOWN' } @@ -194,9 +194,9 @@ # # Example: # -# <- { "event": "RESET", -# "data": { "guest": false, "reason": "guest-reset" }, -# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } +# <- { "event": "RESET", +# "data": { "guest": false, "reason": "guest-reset" }, +# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } ## { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } @@ -209,8 +209,8 @@ # # Example: # -# <- { "event": "STOP", -# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } +# <- { "event": "STOP", +# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } ## { 'event': 'STOP' } @@ -223,8 +223,8 @@ # # Example: # -# <- { "event": "RESUME", -# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } +# <- { "event": "RESUME", +# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } ## { 'event': 'RESUME' } @@ -238,8 +238,8 @@ # # Example: # -# <- { "event": "SUSPEND", -# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } +# <- { "event": "SUSPEND", +# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } ## { 'event': 'SUSPEND' } @@ -257,8 +257,8 @@ # # Example: # -# <- { "event": "SUSPEND_DISK", -# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } +# <- { "event": "SUSPEND_DISK", +# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } ## { 'event': 'SUSPEND_DISK' } @@ -272,8 +272,8 @@ # # Example: # -# <- { "event": "WAKEUP", -# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } +# <- { "event": "WAKEUP", +# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } ## { 'event': 'WAKEUP' } @@ -294,9 +294,9 @@ # # Example: # -# <- { "event": "WATCHDOG", -# "data": { "action": "reset" }, -# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } +# <- { "event": "WATCHDOG", +# "data": { "action": "reset" }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'WATCHDOG', 'data': { 'action': 'WatchdogAction' } } @@ -406,12 +406,12 @@ # # Example: # -# -> { "execute": "set-action", -# "arguments": { "reboot": "shutdown", -# "shutdown" : "pause", -# "panic": "pause", -# "watchdog": "inject-nmi" } } -# <- { "return": {} } +# -> { "execute": "set-action", +# "arguments": { "reboot": "shutdown", +# "shutdown" : "pause", +# "panic": "pause", +# "watchdog": "inject-nmi" } } +# <- { "return": {} } ## { 'command': 'set-action', 'data': { '*reboot': 'RebootAction', @@ -433,9 +433,9 @@ # # Example: # -# <- { "event": "GUEST_PANICKED", -# "data": { "action": "pause" }, -# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } } +# <- { "event": "GUEST_PANICKED", +# "data": { "action": "pause" }, +# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } } ## { 'event': 'GUEST_PANICKED', 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } @@ -453,9 +453,9 @@ # # Example: # -# <- { "event": "GUEST_CRASHLOADED", -# "data": { "action": "run" }, -# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } } +# <- { "event": "GUEST_CRASHLOADED", +# "data": { "action": "run" }, +# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } } ## { 'event': 'GUEST_CRASHLOADED', 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } @@ -583,12 +583,12 @@ # # Example: # -# <- { "event": "MEMORY_FAILURE", -# "data": { "recipient": "hypervisor", -# "action": "fatal", -# "flags": { "action-required": false, -# "recursive": false } }, -# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } +# <- { "event": "MEMORY_FAILURE", +# "data": { "recipient": "hypervisor", +# "action": "fatal", +# "flags": { "action-required": false, +# "recursive": false } }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } ## { 'event': 'MEMORY_FAILURE', 'data': { 'recipient': 'MemoryFailureRecipient', diff --git a/qapi/tpm.json b/qapi/tpm.json index f9c1e866e7..07a73e5f2b 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -33,8 +33,8 @@ # # Example: # -# -> { "execute": "query-tpm-models" } -# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } +# -> { "execute": "query-tpm-models" } +# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } ## { 'command': 'query-tpm-models', 'returns': ['TpmModel'], 'if': 'CONFIG_TPM' } @@ -64,8 +64,8 @@ # # Example: # -# -> { "execute": "query-tpm-types" } -# <- { "return": [ "passthrough", "emulator" ] } +# -> { "execute": "query-tpm-types" } +# <- { "return": [ "passthrough", "emulator" ] } ## { 'command': 'query-tpm-types', 'returns': ['TpmType'], 'if': 'CONFIG_TPM' } @@ -172,21 +172,21 @@ # # Example: # -# -> { "execute": "query-tpm" } -# <- { "return": -# [ -# { "model": "tpm-tis", -# "options": -# { "type": "passthrough", -# "data": -# { "cancel-path": "/sys/class/misc/tpm0/device/cancel", -# "path": "/dev/tpm0" -# } -# }, -# "id": "tpm0" +# -> { "execute": "query-tpm" } +# <- { "return": +# [ +# { "model": "tpm-tis", +# "options": +# { "type": "passthrough", +# "data": +# { "cancel-path": "/sys/class/misc/tpm0/device/cancel", +# "path": "/dev/tpm0" +# } +# }, +# "id": "tpm0" +# } +# ] # } -# ] -# } ## { 'command': 'query-tpm', 'returns': ['TPMInfo'], 'if': 'CONFIG_TPM' } diff --git a/qapi/trace.json b/qapi/trace.json index 2077d7e117..043d12f83e 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -66,9 +66,9 @@ # # Example: # -# -> { "execute": "trace-event-get-state", -# "arguments": { "name": "qemu_memalign" } } -# <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] } +# -> { "execute": "trace-event-get-state", +# "arguments": { "name": "qemu_memalign" } } +# <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] } ## { 'command': 'trace-event-get-state', 'data': {'name': 'str', @@ -96,9 +96,9 @@ # # Example: # -# -> { "execute": "trace-event-set-state", -# "arguments": { "name": "qemu_memalign", "enable": true } } -# <- { "return": {} } +# -> { "execute": "trace-event-set-state", +# "arguments": { "name": "qemu_memalign", "enable": true } } +# <- { "return": {} } ## { 'command': 'trace-event-set-state', 'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool', diff --git a/qapi/transaction.json b/qapi/transaction.json index 7a95c081e9..45233ddd2a 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -247,24 +247,24 @@ # # Example: # -# -> { "execute": "transaction", -# "arguments": { "actions": [ -# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", -# "snapshot-file": "/some/place/my-image", -# "format": "qcow2" } }, -# { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", -# "snapshot-file": "/some/place/my-image2", -# "snapshot-node-name": "node3432", -# "mode": "existing", -# "format": "qcow2" } }, -# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", -# "snapshot-file": "/some/place/my-image2", -# "mode": "existing", -# "format": "qcow2" } }, -# { "type": "blockdev-snapshot-internal-sync", "data" : { -# "device": "ide-hd2", -# "name": "snapshot0" } } ] } } -# <- { "return": {} } +# -> { "execute": "transaction", +# "arguments": { "actions": [ +# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", +# "snapshot-file": "/some/place/my-image", +# "format": "qcow2" } }, +# { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", +# "snapshot-file": "/some/place/my-image2", +# "snapshot-node-name": "node3432", +# "mode": "existing", +# "format": "qcow2" } }, +# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", +# "snapshot-file": "/some/place/my-image2", +# "mode": "existing", +# "format": "qcow2" } }, +# { "type": "blockdev-snapshot-internal-sync", "data" : { +# "device": "ide-hd2", +# "name": "snapshot0" } } ] } } +# <- { "return": {} } ## { 'command': 'transaction', 'data': { 'actions': [ 'TransactionAction' ], diff --git a/qapi/ui.json b/qapi/ui.json index 1448eaca73..e3999b7c07 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -86,9 +86,9 @@ # # Example: # -# -> { "execute": "set_password", "arguments": { "protocol": "vnc", -# "password": "secret" } } -# <- { "return": {} } +# -> { "execute": "set_password", "arguments": { "protocol": "vnc", +# "password": "secret" } } +# <- { "return": {} } ## { 'command': 'set_password', 'boxed': true, 'data': 'SetPasswordOptions' } @@ -149,9 +149,9 @@ # # Example: # -# -> { "execute": "expire_password", "arguments": { "protocol": "vnc", -# "time": "+60" } } -# <- { "return": {} } +# -> { "execute": "expire_password", "arguments": { "protocol": "vnc", +# "time": "+60" } } +# <- { "return": {} } ## { 'command': 'expire_password', 'boxed': true, 'data': 'ExpirePasswordOptions' } @@ -193,9 +193,9 @@ # # Example: # -# -> { "execute": "screendump", -# "arguments": { "filename": "/tmp/image" } } -# <- { "return": {} } +# -> { "execute": "screendump", +# "arguments": { "filename": "/tmp/image" } } +# <- { "return": {} } ## { 'command': 'screendump', 'data': {'filename': 'str', '*device': 'str', '*head': 'int', @@ -337,38 +337,38 @@ # # Example: # -# -> { "execute": "query-spice" } -# <- { "return": { -# "enabled": true, -# "auth": "spice", -# "port": 5920, -# "migrated":false, -# "tls-port": 5921, -# "host": "0.0.0.0", -# "mouse-mode":"client", -# "channels": [ -# { -# "port": "54924", -# "family": "ipv4", -# "channel-type": 1, -# "connection-id": 1804289383, -# "host": "127.0.0.1", -# "channel-id": 0, -# "tls": true -# }, -# { -# "port": "36710", -# "family": "ipv4", -# "channel-type": 4, -# "connection-id": 1804289383, -# "host": "127.0.0.1", -# "channel-id": 0, -# "tls": false -# }, -# [ ... more channels follow ... ] -# ] -# } -# } +# -> { "execute": "query-spice" } +# <- { "return": { +# "enabled": true, +# "auth": "spice", +# "port": 5920, +# "migrated":false, +# "tls-port": 5921, +# "host": "0.0.0.0", +# "mouse-mode":"client", +# "channels": [ +# { +# "port": "54924", +# "family": "ipv4", +# "channel-type": 1, +# "connection-id": 1804289383, +# "host": "127.0.0.1", +# "channel-id": 0, +# "tls": true +# }, +# { +# "port": "36710", +# "family": "ipv4", +# "channel-type": 4, +# "connection-id": 1804289383, +# "host": "127.0.0.1", +# "channel-id": 0, +# "tls": false +# }, +# [ ... more channels follow ... ] +# ] +# } +# } ## { 'command': 'query-spice', 'returns': 'SpiceInfo', 'if': 'CONFIG_SPICE' } @@ -386,12 +386,12 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, -# "event": "SPICE_CONNECTED", -# "data": { -# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, -# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} -# }} +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, +# "event": "SPICE_CONNECTED", +# "data": { +# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, +# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} +# }} ## { 'event': 'SPICE_CONNECTED', 'data': { 'server': 'SpiceBasicInfo', @@ -412,14 +412,14 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, -# "event": "SPICE_INITIALIZED", -# "data": {"server": {"auth": "spice", "port": "5921", -# "family": "ipv4", "host": "127.0.0.1"}, -# "client": {"port": "49004", "family": "ipv4", "channel-type": 3, -# "connection-id": 1804289383, "host": "127.0.0.1", -# "channel-id": 0, "tls": true} -# }} +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, +# "event": "SPICE_INITIALIZED", +# "data": {"server": {"auth": "spice", "port": "5921", +# "family": "ipv4", "host": "127.0.0.1"}, +# "client": {"port": "49004", "family": "ipv4", "channel-type": 3, +# "connection-id": 1804289383, "host": "127.0.0.1", +# "channel-id": 0, "tls": true} +# }} ## { 'event': 'SPICE_INITIALIZED', 'data': { 'server': 'SpiceServerInfo', @@ -439,12 +439,12 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, -# "event": "SPICE_DISCONNECTED", -# "data": { -# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, -# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} -# }} +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, +# "event": "SPICE_DISCONNECTED", +# "data": { +# "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"}, +# "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"} +# }} ## { 'event': 'SPICE_DISCONNECTED', 'data': { 'server': 'SpiceBasicInfo', @@ -460,8 +460,8 @@ # # Example: # -# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, -# "event": "SPICE_MIGRATE_COMPLETED" } +# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, +# "event": "SPICE_MIGRATE_COMPLETED" } ## { 'event': 'SPICE_MIGRATE_COMPLETED', 'if': 'CONFIG_SPICE' } @@ -668,23 +668,23 @@ # # Example: # -# -> { "execute": "query-vnc" } -# <- { "return": { -# "enabled":true, -# "host":"0.0.0.0", -# "service":"50402", -# "auth":"vnc", -# "family":"ipv4", -# "clients":[ -# { -# "host":"127.0.0.1", -# "service":"50401", -# "family":"ipv4", -# "websocket":false -# } -# ] -# } -# } +# -> { "execute": "query-vnc" } +# <- { "return": { +# "enabled":true, +# "host":"0.0.0.0", +# "service":"50402", +# "auth":"vnc", +# "family":"ipv4", +# "clients":[ +# { +# "host":"127.0.0.1", +# "service":"50401", +# "family":"ipv4", +# "websocket":false +# } +# ] +# } +# } ## { 'command': 'query-vnc', 'returns': 'VncInfo', 'if': 'CONFIG_VNC' } @@ -733,13 +733,13 @@ # # Example: # -# <- { "event": "VNC_CONNECTED", -# "data": { -# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, -# "service": "5901", "host": "0.0.0.0" }, -# "client": { "family": "ipv4", "service": "58425", -# "host": "127.0.0.1", "websocket": false } }, -# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } +# <- { "event": "VNC_CONNECTED", +# "data": { +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, +# "service": "5901", "host": "0.0.0.0" }, +# "client": { "family": "ipv4", "service": "58425", +# "host": "127.0.0.1", "websocket": false } }, +# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } ## { 'event': 'VNC_CONNECTED', 'data': { 'server': 'VncServerInfo', @@ -760,13 +760,13 @@ # # Example: # -# <- { "event": "VNC_INITIALIZED", -# "data": { -# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, -# "service": "5901", "host": "0.0.0.0"}, -# "client": { "family": "ipv4", "service": "46089", "websocket": false, -# "host": "127.0.0.1", "sasl_username": "luiz" } }, -# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } +# <- { "event": "VNC_INITIALIZED", +# "data": { +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, +# "service": "5901", "host": "0.0.0.0"}, +# "client": { "family": "ipv4", "service": "46089", "websocket": false, +# "host": "127.0.0.1", "sasl_username": "luiz" } }, +# "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } ## { 'event': 'VNC_INITIALIZED', 'data': { 'server': 'VncServerInfo', @@ -786,13 +786,13 @@ # # Example: # -# <- { "event": "VNC_DISCONNECTED", -# "data": { -# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, -# "service": "5901", "host": "0.0.0.0" }, -# "client": { "family": "ipv4", "service": "58425", "websocket": false, -# "host": "127.0.0.1", "sasl_username": "luiz" } }, -# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } +# <- { "event": "VNC_DISCONNECTED", +# "data": { +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, +# "service": "5901", "host": "0.0.0.0" }, +# "client": { "family": "ipv4", "service": "58425", "websocket": false, +# "host": "127.0.0.1", "sasl_username": "luiz" } }, +# "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } ## { 'event': 'VNC_DISCONNECTED', 'data': { 'server': 'VncServerInfo', @@ -834,22 +834,22 @@ # # Example: # -# -> { "execute": "query-mice" } -# <- { "return": [ -# { -# "name":"QEMU Microsoft Mouse", -# "index":0, -# "current":false, -# "absolute":false -# }, -# { -# "name":"QEMU PS/2 Mouse", -# "index":1, -# "current":true, -# "absolute":true -# } -# ] -# } +# -> { "execute": "query-mice" } +# <- { "return": [ +# { +# "name":"QEMU Microsoft Mouse", +# "index":0, +# "current":false, +# "absolute":false +# }, +# { +# "name":"QEMU PS/2 Mouse", +# "index":1, +# "current":true, +# "absolute":true +# } +# ] +# } ## { 'command': 'query-mice', 'returns': ['MouseInfo'] } @@ -1044,11 +1044,11 @@ # # Example: # -# -> { "execute": "send-key", -# "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, -# { "type": "qcode", "data": "alt" }, -# { "type": "qcode", "data": "delete" } ] } } -# <- { "return": {} } +# -> { "execute": "send-key", +# "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, +# { "type": "qcode", "data": "alt" }, +# { "type": "qcode", "data": "delete" } ] } } +# <- { "return": {} } ## { 'command': 'send-key', 'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } } @@ -1270,39 +1270,39 @@ # # Examples: # -# 1. Press left mouse button. +# 1. Press left mouse button. # -# -> { "execute": "input-send-event", -# "arguments": { "device": "video0", -# "events": [ { "type": "btn", -# "data" : { "down": true, "button": "left" } } ] } } -# <- { "return": {} } +# -> { "execute": "input-send-event", +# "arguments": { "device": "video0", +# "events": [ { "type": "btn", +# "data" : { "down": true, "button": "left" } } ] } } +# <- { "return": {} } # -# -> { "execute": "input-send-event", -# "arguments": { "device": "video0", -# "events": [ { "type": "btn", -# "data" : { "down": false, "button": "left" } } ] } } -# <- { "return": {} } +# -> { "execute": "input-send-event", +# "arguments": { "device": "video0", +# "events": [ { "type": "btn", +# "data" : { "down": false, "button": "left" } } ] } } +# <- { "return": {} } # -# 2. Press ctrl-alt-del. +# 2. Press ctrl-alt-del. # -# -> { "execute": "input-send-event", -# "arguments": { "events": [ -# { "type": "key", "data" : { "down": true, -# "key": {"type": "qcode", "data": "ctrl" } } }, -# { "type": "key", "data" : { "down": true, -# "key": {"type": "qcode", "data": "alt" } } }, -# { "type": "key", "data" : { "down": true, -# "key": {"type": "qcode", "data": "delete" } } } ] } } -# <- { "return": {} } +# -> { "execute": "input-send-event", +# "arguments": { "events": [ +# { "type": "key", "data" : { "down": true, +# "key": {"type": "qcode", "data": "ctrl" } } }, +# { "type": "key", "data" : { "down": true, +# "key": {"type": "qcode", "data": "alt" } } }, +# { "type": "key", "data" : { "down": true, +# "key": {"type": "qcode", "data": "delete" } } } ] } } +# <- { "return": {} } # -# 3. Move mouse pointer to absolute coordinates (20000, 400). +# 3. Move mouse pointer to absolute coordinates (20000, 400). # -# -> { "execute": "input-send-event" , -# "arguments": { "events": [ -# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, -# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } -# <- { "return": {} } +# -> { "execute": "input-send-event" , +# "arguments": { "events": [ +# { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, +# { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } +# <- { "return": {} } ## { 'command': 'input-send-event', 'data': { '*device': 'str', @@ -1611,9 +1611,9 @@ # # Example: # -# -> { "execute": "display-reload", -# "arguments": { "type": "vnc", "tls-certs": true } } -# <- { "return": {} } +# -> { "execute": "display-reload", +# "arguments": { "type": "vnc", "tls-certs": true } } +# <- { "return": {} } ## { 'command': 'display-reload', 'data': 'DisplayReloadOptions', @@ -1670,11 +1670,11 @@ # # Example: # -# -> { "execute": "display-update", -# "arguments": { "type": "vnc", "addresses": -# [ { "type": "inet", "host": "0.0.0.0", -# "port": "5901" } ] } } -# <- { "return": {} } +# -> { "execute": "display-update", +# "arguments": { "type": "vnc", "addresses": +# [ { "type": "inet", "host": "0.0.0.0", +# "port": "5901" } ] } } +# <- { "return": {} } ## { 'command': 'display-update', 'data': 'DisplayUpdateOptions', @@ -1701,11 +1701,11 @@ # # Example: # -# -> { "execute": "client_migrate_info", -# "arguments": { "protocol": "spice", -# "hostname": "virt42.lab.kraxel.org", -# "port": 1234 } } -# <- { "return": {} } +# -> { "execute": "client_migrate_info", +# "arguments": { "protocol": "spice", +# "hostname": "virt42.lab.kraxel.org", +# "port": 1234 } } +# <- { "return": {} } ## { 'command': 'client_migrate_info', 'data': { 'protocol': 'str', 'hostname': 'str', '*port': 'int', diff --git a/qapi/virtio.json b/qapi/virtio.json index 19c7c36e36..a79013fe89 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -36,30 +36,30 @@ # # Example: # -# -> { "execute": "x-query-virtio" } -# <- { "return": [ -# { -# "name": "virtio-input", -# "path": "/machine/peripheral-anon/device[4]/virtio-backend" -# }, -# { -# "name": "virtio-crypto", -# "path": "/machine/peripheral/crypto0/virtio-backend" -# }, -# { -# "name": "virtio-scsi", -# "path": "/machine/peripheral-anon/device[2]/virtio-backend" -# }, -# { -# "name": "virtio-net", -# "path": "/machine/peripheral-anon/device[1]/virtio-backend" -# }, -# { -# "name": "virtio-serial", -# "path": "/machine/peripheral-anon/device[0]/virtio-backend" -# } -# ] -# } +# -> { "execute": "x-query-virtio" } +# <- { "return": [ +# { +# "name": "virtio-input", +# "path": "/machine/peripheral-anon/device[4]/virtio-backend" +# }, +# { +# "name": "virtio-crypto", +# "path": "/machine/peripheral/crypto0/virtio-backend" +# }, +# { +# "name": "virtio-scsi", +# "path": "/machine/peripheral-anon/device[2]/virtio-backend" +# }, +# { +# "name": "virtio-net", +# "path": "/machine/peripheral-anon/device[1]/virtio-backend" +# }, +# { +# "name": "virtio-serial", +# "path": "/machine/peripheral-anon/device[0]/virtio-backend" +# } +# ] +# } ## { 'command': 'x-query-virtio', 'returns': [ 'VirtioInfo' ], @@ -205,229 +205,229 @@ # # Examples: # -# 1. Poll for the status of virtio-crypto (no vhost-crypto active) +# 1. Poll for the status of virtio-crypto (no vhost-crypto active) # -# -> { "execute": "x-query-virtio-status", -# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" } -# } -# <- { "return": { -# "device-endian": "little", -# "bus-name": "", -# "disable-legacy-check": false, -# "name": "virtio-crypto", -# "started": true, -# "device-id": 20, -# "backend-features": { -# "transports": [], -# "dev-features": [] -# }, -# "start-on-kick": false, -# "isr": 1, -# "broken": false, -# "status": { -# "statuses": [ -# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found", -# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device", -# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete", -# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready" -# ] -# }, -# "num-vqs": 2, -# "guest-features": { -# "dev-features": [], -# "transports": [ -# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", -# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", -# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" -# ] -# }, -# "host-features": { -# "unknown-dev-features": 1073741824, -# "dev-features": [], -# "transports": [ -# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", -# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", -# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", -# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", -# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" -# ] -# }, -# "use-guest-notifier-mask": true, -# "vm-running": true, -# "queue-sel": 1, -# "disabled": false, -# "vhost-started": false, -# "use-started": true -# } -# } -# -# 2. Poll for the status of virtio-net (vhost-net is active) -# -# -> { "execute": "x-query-virtio-status", -# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" } -# } -# <- { "return": { -# "device-endian": "little", -# "bus-name": "", -# "disabled-legacy-check": false, -# "name": "virtio-net", -# "started": true, -# "device-id": 1, -# "vhost-dev": { -# "n-tmp-sections": 4, -# "n-mem-sections": 4, -# "max-queues": 1, -# "backend-cap": 2, -# "log-size": 0, +# -> { "execute": "x-query-virtio-status", +# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" } +# } +# <- { "return": { +# "device-endian": "little", +# "bus-name": "", +# "disable-legacy-check": false, +# "name": "virtio-crypto", +# "started": true, +# "device-id": 20, # "backend-features": { +# "transports": [], +# "dev-features": [] +# }, +# "start-on-kick": false, +# "isr": 1, +# "broken": false, +# "status": { +# "statuses": [ +# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found", +# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device", +# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete", +# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready" +# ] +# }, +# "num-vqs": 2, +# "guest-features": { # "dev-features": [], -# "transports": [] -# }, -# "nvqs": 2, -# "protocol-features": { -# "protocols": [] -# }, -# "vq-index": 0, -# "log-enabled": false, -# "acked-features": { -# "dev-features": [ -# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers" -# ], # "transports": [ # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" # ] # }, -# "features": { -# "dev-features": [ -# "VHOST_F_LOG_ALL: Logging write descriptors supported", -# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers" -# ], +# "host-features": { +# "unknown-dev-features": 1073741824, +# "dev-features": [], # "transports": [ # "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", # "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", -# "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform", # "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", # "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", # "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" # ] -# } -# }, -# "backend-features": { -# "dev-features": [ -# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported", -# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported", -# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", -# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", -# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported", -# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", -# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", -# "VIRTIO_NET_F_CTRL_VQ: Control channel available", -# "VIRTIO_NET_F_STATUS: Configuration status field available", -# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", -# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", -# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", -# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", -# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", -# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", -# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", -# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", -# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", -# "VIRTIO_NET_F_MAC: Device has given MAC address", -# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", -# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", -# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" -# ], -# "transports": [ -# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", -# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", -# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", -# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", -# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" -# ] -# }, -# "start-on-kick": false, -# "isr": 1, -# "broken": false, -# "status": { -# "statuses": [ -# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found", -# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device", -# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete", -# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready" -# ] -# }, -# "num-vqs": 3, -# "guest-features": { -# "dev-features": [ -# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", -# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", -# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", -# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", -# "VIRTIO_NET_F_CTRL_VQ: Control channel available", -# "VIRTIO_NET_F_STATUS: Configuration status field available", -# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", -# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", -# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", -# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", -# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", -# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", -# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", -# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", -# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", -# "VIRTIO_NET_F_MAC: Device has given MAC address", -# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", -# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", -# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" -# ], -# "transports": [ -# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", -# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", -# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" -# ] -# }, -# "host-features": { -# "dev-features": [ -# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported", -# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported", -# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", -# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", -# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported", -# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", -# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", -# "VIRTIO_NET_F_CTRL_VQ: Control channel available", -# "VIRTIO_NET_F_STATUS: Configuration status field available", -# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", -# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", -# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", -# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", -# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", -# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", -# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", -# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", -# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", -# "VIRTIO_NET_F_MAC: Device has given MAC address", -# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", -# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", -# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" -# ], -# "transports": [ -# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", -# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", -# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", -# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", -# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" -# ] -# }, -# "use-guest-notifier-mask": true, -# "vm-running": true, -# "queue-sel": 2, -# "disabled": false, -# "vhost-started": true, -# "use-started": true -# } -# } +# }, +# "use-guest-notifier-mask": true, +# "vm-running": true, +# "queue-sel": 1, +# "disabled": false, +# "vhost-started": false, +# "use-started": true +# } +# } +# +# 2. Poll for the status of virtio-net (vhost-net is active) +# +# -> { "execute": "x-query-virtio-status", +# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" } +# } +# <- { "return": { +# "device-endian": "little", +# "bus-name": "", +# "disabled-legacy-check": false, +# "name": "virtio-net", +# "started": true, +# "device-id": 1, +# "vhost-dev": { +# "n-tmp-sections": 4, +# "n-mem-sections": 4, +# "max-queues": 1, +# "backend-cap": 2, +# "log-size": 0, +# "backend-features": { +# "dev-features": [], +# "transports": [] +# }, +# "nvqs": 2, +# "protocol-features": { +# "protocols": [] +# }, +# "vq-index": 0, +# "log-enabled": false, +# "acked-features": { +# "dev-features": [ +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" +# ] +# }, +# "features": { +# "dev-features": [ +# "VHOST_F_LOG_ALL: Logging write descriptors supported", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_IOMMU_PLATFORM: Device can be used on IOMMU platform", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", +# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", +# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" +# ] +# } +# }, +# "backend-features": { +# "dev-features": [ +# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported", +# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported", +# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", +# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", +# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported", +# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", +# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", +# "VIRTIO_NET_F_CTRL_VQ: Control channel available", +# "VIRTIO_NET_F_STATUS: Configuration status field available", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", +# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", +# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", +# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", +# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", +# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", +# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", +# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", +# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", +# "VIRTIO_NET_F_MAC: Device has given MAC address", +# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", +# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", +# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", +# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", +# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" +# ] +# }, +# "start-on-kick": false, +# "isr": 1, +# "broken": false, +# "status": { +# "statuses": [ +# "VIRTIO_CONFIG_S_ACKNOWLEDGE: Valid virtio device found", +# "VIRTIO_CONFIG_S_DRIVER: Guest OS compatible with device", +# "VIRTIO_CONFIG_S_FEATURES_OK: Feature negotiation complete", +# "VIRTIO_CONFIG_S_DRIVER_OK: Driver setup and ready" +# ] +# }, +# "num-vqs": 3, +# "guest-features": { +# "dev-features": [ +# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", +# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", +# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", +# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", +# "VIRTIO_NET_F_CTRL_VQ: Control channel available", +# "VIRTIO_NET_F_STATUS: Configuration status field available", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", +# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", +# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", +# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", +# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", +# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", +# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", +# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", +# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", +# "VIRTIO_NET_F_MAC: Device has given MAC address", +# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", +# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", +# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)" +# ] +# }, +# "host-features": { +# "dev-features": [ +# "VHOST_USER_F_PROTOCOL_FEATURES: Vhost-user protocol features negotiation supported", +# "VIRTIO_NET_F_GSO: Handling GSO-type packets supported", +# "VIRTIO_NET_F_CTRL_MAC_ADDR: MAC address set through control channel", +# "VIRTIO_NET_F_GUEST_ANNOUNCE: Driver sending gratuitous packets supported", +# "VIRTIO_NET_F_CTRL_RX_EXTRA: Extra RX mode control supported", +# "VIRTIO_NET_F_CTRL_VLAN: Control channel VLAN filtering supported", +# "VIRTIO_NET_F_CTRL_RX: Control channel RX mode supported", +# "VIRTIO_NET_F_CTRL_VQ: Control channel available", +# "VIRTIO_NET_F_STATUS: Configuration status field available", +# "VIRTIO_NET_F_MRG_RXBUF: Driver can merge receive buffers", +# "VIRTIO_NET_F_HOST_UFO: Device can receive UFO", +# "VIRTIO_NET_F_HOST_ECN: Device can receive TSO with ECN", +# "VIRTIO_NET_F_HOST_TSO6: Device can receive TSOv6", +# "VIRTIO_NET_F_HOST_TSO4: Device can receive TSOv4", +# "VIRTIO_NET_F_GUEST_UFO: Driver can receive UFO", +# "VIRTIO_NET_F_GUEST_ECN: Driver can receive TSO with ECN", +# "VIRTIO_NET_F_GUEST_TSO6: Driver can receive TSOv6", +# "VIRTIO_NET_F_GUEST_TSO4: Driver can receive TSOv4", +# "VIRTIO_NET_F_MAC: Device has given MAC address", +# "VIRTIO_NET_F_CTRL_GUEST_OFFLOADS: Control channel offloading reconfig. supported", +# "VIRTIO_NET_F_GUEST_CSUM: Driver handling packets with partial checksum supported", +# "VIRTIO_NET_F_CSUM: Device handling packets with partial checksum supported" +# ], +# "transports": [ +# "VIRTIO_RING_F_EVENT_IDX: Used & avail. event fields enabled", +# "VIRTIO_RING_F_INDIRECT_DESC: Indirect descriptors supported", +# "VIRTIO_F_VERSION_1: Device compliant for v1 spec (legacy)", +# "VIRTIO_F_ANY_LAYOUT: Device accepts arbitrary desc. layouts", +# "VIRTIO_F_NOTIFY_ON_EMPTY: Notify when device runs out of avail. descs. on VQ" +# ] +# }, +# "use-guest-notifier-mask": true, +# "vm-running": true, +# "queue-sel": 2, +# "disabled": false, +# "vhost-started": true, +# "use-started": true +# } +# } ## { 'command': 'x-query-virtio-status', 'data': { 'path': 'str' }, @@ -570,52 +570,52 @@ # # Examples: # -# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running) # -# -> { "execute": "x-query-virtio-queue-status", -# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", -# "queue": 1 } -# } -# <- { "return": { -# "signalled-used": 0, -# "inuse": 0, -# "name": "vhost-vsock", -# "vring-align": 4096, -# "vring-desc": 5217370112, -# "signalled-used-valid": false, -# "vring-num-default": 128, -# "vring-avail": 5217372160, -# "queue-index": 1, -# "last-avail-idx": 0, -# "vring-used": 5217372480, -# "used-idx": 0, -# "vring-num": 128 -# } -# } +# -> { "execute": "x-query-virtio-queue-status", +# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", +# "queue": 1 } +# } +# <- { "return": { +# "signalled-used": 0, +# "inuse": 0, +# "name": "vhost-vsock", +# "vring-align": 4096, +# "vring-desc": 5217370112, +# "signalled-used-valid": false, +# "vring-num-default": 128, +# "vring-avail": 5217372160, +# "queue-index": 1, +# "last-avail-idx": 0, +# "vring-used": 5217372480, +# "used-idx": 0, +# "vring-num": 128 +# } +# } # -# 2. Get VirtQueueStatus for virtio-serial (no vhost) +# 2. Get VirtQueueStatus for virtio-serial (no vhost) # -# -> { "execute": "x-query-virtio-queue-status", -# "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend", -# "queue": 20 } -# } -# <- { "return": { -# "signalled-used": 0, -# "inuse": 0, -# "name": "virtio-serial", -# "vring-align": 4096, -# "vring-desc": 5182074880, -# "signalled-used-valid": false, -# "vring-num-default": 128, -# "vring-avail": 5182076928, -# "queue-index": 20, -# "last-avail-idx": 0, -# "vring-used": 5182077248, -# "used-idx": 0, -# "shadow-avail-idx": 0, -# "vring-num": 128 -# } -# } +# -> { "execute": "x-query-virtio-queue-status", +# "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend", +# "queue": 20 } +# } +# <- { "return": { +# "signalled-used": 0, +# "inuse": 0, +# "name": "virtio-serial", +# "vring-align": 4096, +# "vring-desc": 5182074880, +# "signalled-used-valid": false, +# "vring-num-default": 128, +# "vring-avail": 5182076928, +# "queue-index": 20, +# "last-avail-idx": 0, +# "vring-used": 5182077248, +# "used-idx": 0, +# "shadow-avail-idx": 0, +# "vring-num": 128 +# } +# } ## { 'command': 'x-query-virtio-queue-status', 'data': { 'path': 'str', 'queue': 'uint16' }, @@ -690,51 +690,51 @@ # # Examples: # -# 1. Get vhost_virtqueue status for vhost-crypto +# 1. Get vhost_virtqueue status for vhost-crypto # -# -> { "execute": "x-query-virtio-vhost-queue-status", -# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", -# "queue": 0 } -# } -# <- { "return": { -# "avail-phys": 5216124928, -# "name": "virtio-crypto", -# "used-phys": 5216127040, -# "avail-size": 2054, -# "desc-size": 16384, -# "used-size": 8198, -# "desc": 140141447430144, -# "num": 1024, -# "call": 0, -# "avail": 140141447446528, -# "desc-phys": 5216108544, -# "used": 140141447448640, -# "kick": 0 -# } -# } +# -> { "execute": "x-query-virtio-vhost-queue-status", +# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", +# "queue": 0 } +# } +# <- { "return": { +# "avail-phys": 5216124928, +# "name": "virtio-crypto", +# "used-phys": 5216127040, +# "avail-size": 2054, +# "desc-size": 16384, +# "used-size": 8198, +# "desc": 140141447430144, +# "num": 1024, +# "call": 0, +# "avail": 140141447446528, +# "desc-phys": 5216108544, +# "used": 140141447448640, +# "kick": 0 +# } +# } # -# 2. Get vhost_virtqueue status for vhost-vsock +# 2. Get vhost_virtqueue status for vhost-vsock # -# -> { "execute": "x-query-virtio-vhost-queue-status", -# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", -# "queue": 0 } -# } -# <- { "return": { -# "avail-phys": 5182261248, -# "name": "vhost-vsock", -# "used-phys": 5182261568, -# "avail-size": 262, -# "desc-size": 2048, -# "used-size": 1030, -# "desc": 140141413580800, -# "num": 128, -# "call": 0, -# "avail": 140141413582848, -# "desc-phys": 5182259200, -# "used": 140141413583168, -# "kick": 0 -# } -# } +# -> { "execute": "x-query-virtio-vhost-queue-status", +# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend", +# "queue": 0 } +# } +# <- { "return": { +# "avail-phys": 5182261248, +# "name": "vhost-vsock", +# "used-phys": 5182261568, +# "avail-size": 262, +# "desc-size": 2048, +# "used-size": 1030, +# "desc": 140141413580800, +# "num": 128, +# "call": 0, +# "avail": 140141413582848, +# "desc-phys": 5182259200, +# "used": 140141413583168, +# "kick": 0 +# } +# } ## { 'command': 'x-query-virtio-vhost-queue-status', 'data': { 'path': 'str', 'queue': 'uint16' }, @@ -839,90 +839,90 @@ # # Examples: # -# 1. Introspect on virtio-net's VirtQueue 0 at index 5 +# 1. Introspect on virtio-net's VirtQueue 0 at index 5 # -# -> { "execute": "x-query-virtio-queue-element", -# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend", -# "queue": 0, -# "index": 5 } -# } -# <- { "return": { -# "index": 5, -# "name": "virtio-net", -# "descs": [ -# { -# "flags": ["write"], -# "len": 1536, -# "addr": 5257305600 +# -> { "execute": "x-query-virtio-queue-element", +# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend", +# "queue": 0, +# "index": 5 } +# } +# <- { "return": { +# "index": 5, +# "name": "virtio-net", +# "descs": [ +# { +# "flags": ["write"], +# "len": 1536, +# "addr": 5257305600 +# } +# ], +# "avail": { +# "idx": 256, +# "flags": 0, +# "ring": 5 +# }, +# "used": { +# "idx": 13, +# "flags": 0 # } -# ], -# "avail": { -# "idx": 256, -# "flags": 0, -# "ring": 5 -# }, -# "used": { -# "idx": 13, -# "flags": 0 # } -# } -# } +# } # -# 2. Introspect on virtio-crypto's VirtQueue 1 at head +# 2. Introspect on virtio-crypto's VirtQueue 1 at head # -# -> { "execute": "x-query-virtio-queue-element", -# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", -# "queue": 1 } -# } -# <- { "return": { -# "index": 0, -# "name": "virtio-crypto", -# "descs": [ -# { -# "flags": [], -# "len": 0, -# "addr": 8080268923184214134 +# -> { "execute": "x-query-virtio-queue-element", +# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend", +# "queue": 1 } +# } +# <- { "return": { +# "index": 0, +# "name": "virtio-crypto", +# "descs": [ +# { +# "flags": [], +# "len": 0, +# "addr": 8080268923184214134 +# } +# ], +# "avail": { +# "idx": 280, +# "flags": 0, +# "ring": 0 +# }, +# "used": { +# "idx": 280, +# "flags": 0 # } -# ], -# "avail": { -# "idx": 280, -# "flags": 0, -# "ring": 0 -# }, -# "used": { -# "idx": 280, -# "flags": 0 # } -# } -# } +# } # -# 3. Introspect on virtio-scsi's VirtQueue 2 at head +# 3. Introspect on virtio-scsi's VirtQueue 2 at head # -# -> { "execute": "x-query-virtio-queue-element", -# "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend", -# "queue": 2 } -# } -# <- { "return": { -# "index": 19, -# "name": "virtio-scsi", -# "descs": [ -# { -# "flags": ["used", "indirect", "write"], -# "len": 4099327944, -# "addr": 12055409292258155293 +# -> { "execute": "x-query-virtio-queue-element", +# "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend", +# "queue": 2 } +# } +# <- { "return": { +# "index": 19, +# "name": "virtio-scsi", +# "descs": [ +# { +# "flags": ["used", "indirect", "write"], +# "len": 4099327944, +# "addr": 12055409292258155293 +# } +# ], +# "avail": { +# "idx": 1147, +# "flags": 0, +# "ring": 19 +# }, +# "used": { +# "idx": 280, +# "flags": 0 # } -# ], -# "avail": { -# "idx": 1147, -# "flags": 0, -# "ring": 19 -# }, -# "used": { -# "idx": 280, -# "flags": 0 # } -# } -# } +# } ## { 'command': 'x-query-virtio-queue-element', 'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' }, diff --git a/qapi/yank.json b/qapi/yank.json index ee038a11a1..b7aeb9ceef 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -84,13 +84,13 @@ # # Example: # -# -> { "execute": "yank", -# "arguments": { -# "instances": [ -# { "type": "block-node", -# "node-name": "nbd0" } -# ] } } -# <- { "return": {} } +# -> { "execute": "yank", +# "arguments": { +# "instances": [ +# { "type": "block-node", +# "node-name": "nbd0" } +# ] } } +# <- { "return": {} } # # Since: 6.0 ## @@ -107,11 +107,11 @@ # # Example: # -# -> { "execute": "query-yank" } -# <- { "return": [ -# { "type": "block-node", -# "node-name": "nbd0" } -# ] } +# -> { "execute": "query-yank" } +# <- { "return": [ +# { "type": "block-node", +# "node-name": "nbd0" } +# ] } # # Since: 6.0 ## diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 3aefec1c2b..f8da315332 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -492,6 +492,9 @@ def append(self, line: str) -> None: # indeterminate indentation if self.text != '': # non-blank, non-first line determines indentation + if indent == 0: + raise QAPIParseError( + self._parser, "line needs to be indented") self._indent = indent elif indent < self._indent: raise QAPIParseError( diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 0479d16a01..977bb38b6e 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -165,11 +165,11 @@ # Duis aute irure dolor # Example: # -# -> in -# <- out +# -> in +# <- out # Examples: -# - *verbatim* -# - {braces} +# - *verbatim* +# - {braces} # Since: 2.10 ## { 'command': 'cmd', @@ -185,9 +185,9 @@ # @cmd-feat2: another feature # Example: # -# -> in +# -> in # -# <- out +# <- out ## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object', From patchwork Mon Feb 26 10:49:49 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571946 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 B2FC0C48BF6 for ; Mon, 26 Feb 2024 10:53:49 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZD-0002kX-1x; Mon, 26 Feb 2024 05:50:39 -0500 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 1reYYg-0002bc-Dr for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:12 -0500 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 1reYYZ-0003io-Fv for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:05 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944598; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=HlwZfUu7aZshrJvo0RyUUeAZQEM9eADcDp82hTJ3OqU=; b=CgJE7mOYKh/XJIBrU23JgwJBqaMJU7zdZEpfLeNFoxrOLwi/a090y3vAhjJIEgiM4cqo6Y 6+RphIZZspQ9CexkQ/ne4QHUGw2P3RKBpTGfWVskaZi73ixtLcoPsQBP1nwACuViaRz09C lZt9PGODM34UWls+zoYYtuzTBVGN1A0= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-101-yOqwrroTP7Wl6bQ3kPuaxg-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: yOqwrroTP7Wl6bQ3kPuaxg-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 0BFDE845E60; Mon, 26 Feb 2024 10:49:57 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BE84C2026D0A; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id A9B6721E5A58; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 12/17] qapi: Recognize section tags and 'Features:' only after blank line Date: Mon, 26 Feb 2024 11:49:49 +0100 Message-ID: <20240226104954.3781985-13-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.4 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_HELO_TEMPERROR=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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Putting a blank line before section tags and 'Features:' is good, existing practice. Enforce it. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-12-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- docs/devel/qapi-code-gen.rst | 15 +++++++++------ scripts/qapi/parser.py | 11 ++++++++--- tests/qapi-schema/doc-duplicated-return.err | 2 +- tests/qapi-schema/doc-duplicated-return.json | 1 + tests/qapi-schema/doc-duplicated-since.err | 2 +- tests/qapi-schema/doc-duplicated-since.json | 1 + tests/qapi-schema/doc-good.json | 9 +++++++++ tests/qapi-schema/doc-invalid-return.err | 2 +- tests/qapi-schema/doc-invalid-return.json | 1 + 9 files changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 77a40f3bdc..6804a4b596 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -986,16 +986,17 @@ indented like this:: Extensions added after the definition was first released carry a "(since x.y.z)" comment. -The feature descriptions must be preceded by a line "Features:", like -this:: +The feature descriptions must be preceded by a blank line and then a +line "Features:", like this:: + # # Features: # # @feature: Description text -A tagged section starts with one of the following words: -"Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:", -"TODO:". The section ends with the start of a new section. +A tagged section begins with a paragraph that starts with one of the +following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:", +"Returns:", "TODO:". It ends with the start of a new section. The second and subsequent lines of tagged sections must be indented like this:: @@ -1086,8 +1087,10 @@ need to line up with each other, like this:: # or cache associativity unknown) # (since 5.0) -Section tags are case-sensitive and end with a colon. Good example:: +Section tags are case-sensitive and end with a colon. They are only +recognized after a blank line. Good example:: + # # Since: 7.1 Bad examples (all ordinary paragraphs):: diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index f8da315332..de2ce3ec2c 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -538,6 +538,7 @@ def __init__(self, parser: QAPISchemaParser, info: QAPISourceInfo): # the current section self._section = self.body self._append_line = self._append_body_line + self._first_line_in_paragraph = False def has_section(self, tag: str) -> bool: """Return True if we have a section with this tag.""" @@ -560,12 +561,14 @@ def append(self, line: str) -> None: line = line[1:] if not line: self._append_freeform(line) + self._first_line_in_paragraph = True return if line[0] != ' ': raise QAPIParseError(self._parser, "missing space after #") line = line[1:] self._append_line(line) + self._first_line_in_paragraph = False def end_comment(self) -> None: self._switch_section(QAPIDoc.NullSection(self._parser)) @@ -574,9 +577,11 @@ def end_comment(self) -> None: def _match_at_name_colon(string: str) -> Optional[Match[str]]: return re.match(r'@([^:]*): *', string) - @staticmethod - def _match_section_tag(string: str) -> Optional[Match[str]]: - return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string) + def _match_section_tag(self, string: str) -> Optional[Match[str]]: + if not self._first_line_in_paragraph: + return None + return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', + string) def _append_body_line(self, line: str) -> None: """ diff --git a/tests/qapi-schema/doc-duplicated-return.err b/tests/qapi-schema/doc-duplicated-return.err index fe97e3db8d..f19a2b8ec4 100644 --- a/tests/qapi-schema/doc-duplicated-return.err +++ b/tests/qapi-schema/doc-duplicated-return.err @@ -1 +1 @@ -doc-duplicated-return.json:7:1: duplicated 'Returns' section +doc-duplicated-return.json:8:1: duplicated 'Returns' section diff --git a/tests/qapi-schema/doc-duplicated-return.json b/tests/qapi-schema/doc-duplicated-return.json index b44b5ae979..4e1ec2ef42 100644 --- a/tests/qapi-schema/doc-duplicated-return.json +++ b/tests/qapi-schema/doc-duplicated-return.json @@ -4,5 +4,6 @@ # @foo: # # Returns: 0 +# # Returns: 1 ## diff --git a/tests/qapi-schema/doc-duplicated-since.err b/tests/qapi-schema/doc-duplicated-since.err index abca141a2c..565b753b6a 100644 --- a/tests/qapi-schema/doc-duplicated-since.err +++ b/tests/qapi-schema/doc-duplicated-since.err @@ -1 +1 @@ -doc-duplicated-since.json:7:1: duplicated 'Since' section +doc-duplicated-since.json:8:1: duplicated 'Since' section diff --git a/tests/qapi-schema/doc-duplicated-since.json b/tests/qapi-schema/doc-duplicated-since.json index 343cd872cb..2755f95719 100644 --- a/tests/qapi-schema/doc-duplicated-since.json +++ b/tests/qapi-schema/doc-duplicated-since.json @@ -4,5 +4,6 @@ # @foo: # # Since: 0 +# # Since: 1 ## diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 977bb38b6e..5bb2b69071 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -154,22 +154,29 @@ # Features: # @cmd-feat1: a feature # @cmd-feat2: another feature +# # Note: @arg3 is undocumented +# # Returns: @Object +# # TODO: frobnicate +# # Notes: # # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam # # Duis aute irure dolor +# # Example: # # -> in # <- out +# # Examples: # - *verbatim* # - {braces} +# # Since: 2.10 ## { 'command': 'cmd', @@ -180,9 +187,11 @@ ## # @cmd-boxed: # If you're bored enough to read this, go see a video of boxed cats +# # Features: # @cmd-feat1: a feature # @cmd-feat2: another feature +# # Example: # # -> in diff --git a/tests/qapi-schema/doc-invalid-return.err b/tests/qapi-schema/doc-invalid-return.err index bc5826de20..3d9e71c2b3 100644 --- a/tests/qapi-schema/doc-invalid-return.err +++ b/tests/qapi-schema/doc-invalid-return.err @@ -1 +1 @@ -doc-invalid-return.json:5: 'Returns:' is only valid for commands +doc-invalid-return.json:6: 'Returns:' is only valid for commands diff --git a/tests/qapi-schema/doc-invalid-return.json b/tests/qapi-schema/doc-invalid-return.json index 95e7583930..1aabef3482 100644 --- a/tests/qapi-schema/doc-invalid-return.json +++ b/tests/qapi-schema/doc-invalid-return.json @@ -2,6 +2,7 @@ ## # @FOO: +# # Returns: blah ## { 'event': 'FOO' } From patchwork Mon Feb 26 10:49:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571965 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 EE503C54E4A for ; Mon, 26 Feb 2024 10:54:23 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZD-0002ko-VZ; Mon, 26 Feb 2024 05:50:39 -0500 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 1reYYe-0002bW-PB for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:12 -0500 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 1reYYa-0003iv-E8 for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:04 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944599; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=8w12yVQTUHu71nwpu/QeSRSCKr3NQUj/iWWCHnk5SRs=; b=TsXMkLL+9MeP4qWdDI+ZjBVY//BRotI6rUySAPKvfaqxyZygy54zr0evN2MIuHtPFq7kBN rI2dKYsW2von4HQLgHuVJ70uSTrb403uUV7eiykLxbXPxvallXDysvXXNIsyjM8IFMNqw7 WzIHD6cmMy1d6VLT1sMERf5BzAJXCJI= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-482-lXPPQQXcM2CyEiDA9LYXDw-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: lXPPQQXcM2CyEiDA9LYXDw-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id E57721C382A7; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C33D840C1430; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id AC8A221E5A5A; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 13/17] qapi: Call QAPIDoc.check() always Date: Mon, 26 Feb 2024 11:49:50 +0100 Message-ID: <20240226104954.3781985-14-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org We currently call QAPIDoc.check() only for definition documentation. Calling it for free-form documentation as well is simpler. No change, because it doesn't actually do anything there. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-13-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- scripts/qapi/schema.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index 6a836950a9..8ba5665bc6 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -95,10 +95,6 @@ def connect_doc(self, doc=None): for f in self.features: doc.connect_feature(f) - def check_doc(self): - if self.doc: - self.doc.check() - def _set_module(self, schema, info): assert self._checked fname = info.fname if info else QAPISchemaModule.BUILTIN_MODULE_NAME @@ -1223,9 +1219,10 @@ def check(self): for ent in self._entity_list: ent.check(self) ent.connect_doc() - ent.check_doc() for ent in self._entity_list: ent.set_module(self) + for doc in self.docs: + doc.check() def visit(self, visitor): visitor.visit_begin(self) From patchwork Mon Feb 26 10:49:51 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571947 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 59C0EC54E49 for ; Mon, 26 Feb 2024 10:54:14 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZB-0002iY-49; Mon, 26 Feb 2024 05:50:37 -0500 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 1reYYh-0002bh-3t for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:13 -0500 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 1reYYa-0003im-JV for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944598; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=zTkxPSK2MHkGo5DezQTXlE1R/e6VnhXGyFV2gjrdJFg=; b=IU6NBEDOooXFXZWMwroKjucfB0Ilgae0Ul28MwMw01MeVRVGqlRxCgvbxZagqyE1KvQGcq OKyWgTvgkAwyJhCMhXU6z2Xh9bBxF1tFWifMKKTpU1k4kQk64ntXNhDweCGjUT2UyZcBNh HSWeiCuFV3FE2Q3ajJkD6bEmxQXYzgA= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-556-GepmOfSUPLico_xTwGY9Nw-1; Mon, 26 Feb 2024 05:49:57 -0500 X-MC-Unique: GepmOfSUPLico_xTwGY9Nw-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id E8B123C1E9C2; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C5A2E40C122C; Mon, 26 Feb 2024 10:49:56 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id AF59521E5A5B; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 14/17] qapi: Merge adjacent untagged sections Date: Mon, 26 Feb 2024 11:49:51 +0100 Message-ID: <20240226104954.3781985-15-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org The parser mostly doesn't create adjacent untagged sections, and merging the ones it does create is hardly worth the bother. I'm doing it to avoid behavioral change in the next commit. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-14-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- scripts/qapi/parser.py | 3 +++ tests/qapi-schema/doc-empty-features.out | 2 -- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index de2ce3ec2c..48cc9a6367 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -719,6 +719,9 @@ def _start_features_section(self, name: str) -> None: self._start_symbol_section(self.features, name) def _start_section(self, tag: Optional[str] = None) -> None: + if not tag and not self._section.tag: + # extend current section + return if tag in ('Returns', 'Since') and self.has_section(tag): raise QAPIParseError(self._parser, "duplicated '%s' section" % tag) diff --git a/tests/qapi-schema/doc-empty-features.out b/tests/qapi-schema/doc-empty-features.out index 0f85623dde..473f59552d 100644 --- a/tests/qapi-schema/doc-empty-features.out +++ b/tests/qapi-schema/doc-empty-features.out @@ -14,6 +14,4 @@ command foo None -> None gen=True success_response=True boxed=False oob=False preconfig=False doc symbol=foo body= - - section=None not a description From patchwork Mon Feb 26 10:49:52 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571966 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 3259FC54E51 for ; Mon, 26 Feb 2024 10:54:23 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZE-0002kq-7b; Mon, 26 Feb 2024 05:50:40 -0500 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 1reYYm-0002cD-Gi for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:16 -0500 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 1reYYb-0003jp-NO for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:08 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944601; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=zpbPMw0AV3eYRGJICWVf22yH/4UM4eiSrRuRqrdP+o0=; b=Z152aEWOT5JH8+zcFY++9+2TADP97kIakyhgn2ZSNLANh2fXqCR3GVJbQ+Fw5FMhEgrixB KiBuotMSn6bjbN7EY7Eo4HYx4nXtHH323hPyS7MbwkeD0wv8VI34sRQdqEC98DDEIzkf6x ZuBQFXnWsMngX/flRFuSIs3Cy/FPf6g= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-224-b8p_-VwmNa2CC4oVx-nEOQ-1; Mon, 26 Feb 2024 05:49:59 -0500 X-MC-Unique: b8p_-VwmNa2CC4oVx-nEOQ-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id B5C9A2812FE5; Mon, 26 Feb 2024 10:49:58 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 380AB40166A5; Mon, 26 Feb 2024 10:49:58 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B277E21E5A5C; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 15/17] qapi: Rewrite doc comment parser Date: Mon, 26 Feb 2024 11:49:52 +0100 Message-ID: <20240226104954.3781985-16-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org QAPISchemaParser is a conventional recursive descent parser. Except QAPISchemaParser.get_doc() delegates most of the doc comment parsing work to a state machine in QAPIDoc. The state machine doesn't get tokens like a recursive descent parser, it is fed tokens. I find this state machine rather opaque and hard to maintain. Replace it by a conventional parser, all in QAPISchemaParser. Less code, and (at least in my opinion) easier to understand. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-15-armbru@redhat.com> Tested-by: Daniel P. Berrangé --- scripts/qapi/parser.py | 478 ++++++++++++++++++----------------------- 1 file changed, 210 insertions(+), 268 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 48cc9a6367..73ff150430 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -134,8 +134,8 @@ def _parse(self) -> None: info = self.info if self.tok == '#': self.reject_expr_doc(cur_doc) - for cur_doc in self.get_doc(info): - self.docs.append(cur_doc) + cur_doc = self.get_doc() + self.docs.append(cur_doc) continue expr = self.get_expr() @@ -414,39 +414,171 @@ def get_expr(self) -> _ExprValue: self, "expected '{', '[', string, or boolean") return expr - def get_doc(self, info: QAPISourceInfo) -> List['QAPIDoc']: + def get_doc_line(self) -> Optional[str]: + if self.tok != '#': + raise QAPIParseError( + self, "documentation comment must end with '##'") + assert isinstance(self.val, str) + if self.val.startswith('##'): + # End of doc comment + if self.val != '##': + raise QAPIParseError( + self, "junk after '##' at end of documentation comment") + return None + if self.val == '#': + return '' + if self.val[1] != ' ': + raise QAPIParseError(self, "missing space after #") + return self.val[2:].rstrip() + + @staticmethod + def _match_at_name_colon(string: str) -> Optional[Match[str]]: + return re.match(r'@([^:]*): *', string) + + def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[str]: + self.accept(False) + line = self.get_doc_line() + while line == '': + doc.append_line(line) + self.accept(False) + line = self.get_doc_line() + if line is None: + return line + indent = must_match(r'\s*', line).end() + if not indent: + return line + doc.append_line(line[indent:]) + prev_line_blank = False + while True: + self.accept(False) + line = self.get_doc_line() + if line is None: + return line + if self._match_at_name_colon(line): + return line + cur_indent = must_match(r'\s*', line).end() + if line != '' and cur_indent < indent: + if prev_line_blank: + return line + raise QAPIParseError( + self, + "unexpected de-indent (expected at least %d spaces)" % + indent) + doc.append_line(line[indent:]) + prev_line_blank = True + + def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]: + while True: + self.accept(False) + line = self.get_doc_line() + if line is None: + return line + if line == '': + return line + doc.append_line(line) + + def get_doc(self) -> 'QAPIDoc': if self.val != '##': raise QAPIParseError( self, "junk after '##' at start of documentation comment") - - docs = [] - cur_doc = QAPIDoc(self, info) + info = self.info self.accept(False) - while self.tok == '#': - assert isinstance(self.val, str) - if self.val.startswith('##'): - # End of doc comment - if self.val != '##': - raise QAPIParseError( - self, - "junk after '##' at end of documentation comment") - cur_doc.end_comment() - docs.append(cur_doc) - self.accept() - return docs - if self.val.startswith('# ='): - if cur_doc.symbol: + line = self.get_doc_line() + if line is not None and line.startswith('@'): + # Definition documentation + if not line.endswith(':'): + raise QAPIParseError(self, "line should end with ':'") + # Invalid names are not checked here, but the name + # provided *must* match the following definition, + # which *is* validated in expr.py. + symbol = line[1:-1] + if not symbol: + raise QAPIParseError(self, "name required after '@'") + doc = QAPIDoc(self, info, symbol) + self.accept(False) + line = self.get_doc_line() + no_more_args = False + + while line is not None: + # Blank lines + while line == '': + self.accept(False) + line = self.get_doc_line() + if line is None: + break + # Non-blank line, first of a section + if line == 'Features:' and not doc.features: + self.accept(False) + line = self.get_doc_line() + while line == '': + self.accept(False) + line = self.get_doc_line() + while (line is not None + and (match := self._match_at_name_colon(line))): + doc.new_feature(match.group(1)) + text = line[match.end():] + if text: + doc.append_line(text) + line = self.get_doc_indented(doc) + no_more_args = True + elif match := self._match_at_name_colon(line): + # description + if no_more_args: + raise QAPIParseError( + self, + "description of '@%s:' follows a section" + % match.group(1)) + while (line is not None + and (match := self._match_at_name_colon(line))): + doc.new_argument(match.group(1)) + text = line[match.end():] + if text: + doc.append_line(text) + line = self.get_doc_indented(doc) + no_more_args = True + elif match := re.match( + r'(Returns|Since|Notes?|Examples?|TODO): *', + line): + # tagged section + doc.new_tagged_section(match.group(1)) + text = line[match.end():] + if text: + doc.append_line(text) + line = self.get_doc_indented(doc) + no_more_args = True + elif line.startswith('='): raise QAPIParseError( self, "unexpected '=' markup in definition documentation") - if cur_doc.body.text: + else: + # tag-less paragraph + doc.ensure_untagged_section() + doc.append_line(line) + line = self.get_doc_paragraph(doc) + else: + # Free-form documentation + doc = QAPIDoc(self, info) + doc.ensure_untagged_section() + first = True + while line is not None: + if match := self._match_at_name_colon(line): raise QAPIParseError( self, - "'=' heading must come first in a comment block") - cur_doc.append(self.val) - self.accept(False) + "'@%s:' not allowed in free-form documentation" + % match.group(1)) + if line.startswith('='): + if not first: + raise QAPIParseError( + self, + "'=' heading must come first in a comment block") + doc.append_line(line) + self.accept(False) + line = self.get_doc_line() + first = False - raise QAPIParseError(self, "documentation comment must end with '##'") + self.accept(False) + doc.end() + return doc class QAPIDoc: @@ -469,7 +601,6 @@ class QAPIDoc: """ class Section: - # pylint: disable=too-few-public-methods def __init__(self, parser: QAPISchemaParser, tag: Optional[str] = None): # section source info, i.e. where it begins @@ -480,29 +611,8 @@ def __init__(self, parser: QAPISchemaParser, self.tag = tag # section text without tag self.text = '' - # indentation to strip (None means indeterminate) - self._indent = None if self.tag else 0 - - def append(self, line: str) -> None: - line = line.rstrip() - - if line: - indent = must_match(r'\s*', line).end() - if self._indent is None: - # indeterminate indentation - if self.text != '': - # non-blank, non-first line determines indentation - if indent == 0: - raise QAPIParseError( - self._parser, "line needs to be indented") - self._indent = indent - elif indent < self._indent: - raise QAPIParseError( - self._parser, - "unexpected de-indent (expected at least %d spaces)" % - self._indent) - line = line[self._indent:] + def append_line(self, line: str) -> None: self.text += line + '\n' class ArgSection(Section): @@ -514,243 +624,75 @@ def __init__(self, parser: QAPISchemaParser, def connect(self, member: 'QAPISchemaMember') -> None: self.member = member - class NullSection(Section): - """ - Immutable dummy section for use at the end of a doc block. - """ - # pylint: disable=too-few-public-methods - def append(self, line: str) -> None: - assert False, "Text appended after end_comment() called." - - def __init__(self, parser: QAPISchemaParser, info: QAPISourceInfo): + def __init__(self, parser: QAPISchemaParser, info: QAPISourceInfo, + symbol: Optional[str] = None): # self._parser is used to report errors with QAPIParseError. The # resulting error position depends on the state of the parser. # It happens to be the beginning of the comment. More or less # servicable, but action at a distance. self._parser = parser + # info points to the doc comment block's first line self.info = info - self.symbol: Optional[str] = None - self.body = QAPIDoc.Section(parser) - # dicts mapping parameter/feature names to their ArgSection - self.args: Dict[str, QAPIDoc.ArgSection] = OrderedDict() - self.features: Dict[str, QAPIDoc.ArgSection] = OrderedDict() + # definition doc's symbol, None for free-form doc + self.symbol: Optional[str] = symbol + # the sections in textual order + self.all_sections: List[QAPIDoc.Section] = [QAPIDoc.Section(parser)] + # the body section + self.body: Optional[QAPIDoc.Section] = self.all_sections[0] + # dicts mapping parameter/feature names to their description + self.args: Dict[str, QAPIDoc.ArgSection] = {} + self.features: Dict[str, QAPIDoc.ArgSection] = {} + # sections other than .body, .args, .features self.sections: List[QAPIDoc.Section] = [] - # the current section - self._section = self.body - self._append_line = self._append_body_line - self._first_line_in_paragraph = False - def has_section(self, tag: str) -> bool: - """Return True if we have a section with this tag.""" - for i in self.sections: - if i.tag == tag: - return True - return False + def end(self) -> None: + for section in self.all_sections: + section.text = section.text.strip('\n') + if section.tag is not None and section.text == '': + raise QAPISemError( + section.info, "text required after '%s:'" % section.tag) - def append(self, line: str) -> None: - """ - Parse a comment line and add it to the documentation. - - The way that the line is dealt with depends on which part of - the documentation we're parsing right now: - * The body section: ._append_line is ._append_body_line - * An argument section: ._append_line is ._append_args_line - * A features section: ._append_line is ._append_features_line - * An additional section: ._append_line is ._append_various_line - """ - line = line[1:] - if not line: - self._append_freeform(line) - self._first_line_in_paragraph = True + def ensure_untagged_section(self) -> None: + if self.all_sections and not self.all_sections[-1].tag: + # extend current section + self.all_sections[-1].text += '\n' return + # start new section + section = self.Section(self._parser) + self.sections.append(section) + self.all_sections.append(section) - if line[0] != ' ': - raise QAPIParseError(self._parser, "missing space after #") - line = line[1:] - self._append_line(line) - self._first_line_in_paragraph = False + def new_tagged_section(self, tag: str) -> None: + if tag in ('Returns', 'Since'): + for section in self.all_sections: + if isinstance(section, self.ArgSection): + continue + if section.tag == tag: + raise QAPIParseError( + self._parser, "duplicated '%s' section" % tag) + section = self.Section(self._parser, tag) + self.sections.append(section) + self.all_sections.append(section) - def end_comment(self) -> None: - self._switch_section(QAPIDoc.NullSection(self._parser)) - - @staticmethod - def _match_at_name_colon(string: str) -> Optional[Match[str]]: - return re.match(r'@([^:]*): *', string) - - def _match_section_tag(self, string: str) -> Optional[Match[str]]: - if not self._first_line_in_paragraph: - return None - return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', - string) - - def _append_body_line(self, line: str) -> None: - """ - Process a line of documentation text in the body section. - - If this a symbol line and it is the section's first line, this - is a definition documentation block for that symbol. - - If it's a definition documentation block, another symbol line - begins the argument section for the argument named by it, and - a section tag begins an additional section. Start that - section and append the line to it. - - Else, append the line to the current section. - """ - # FIXME not nice: things like '# @foo:' and '# @foo: ' aren't - # recognized, and get silently treated as ordinary text - if not self.symbol and not self.body.text and line.startswith('@'): - if not line.endswith(':'): - raise QAPIParseError(self._parser, "line should end with ':'") - self.symbol = line[1:-1] - # Invalid names are not checked here, but the name provided MUST - # match the following definition, which *is* validated in expr.py. - if not self.symbol: - raise QAPIParseError( - self._parser, "name required after '@'") - elif self.symbol: - # This is a definition documentation block - if self._match_at_name_colon(line): - self._append_line = self._append_args_line - self._append_args_line(line) - elif line == 'Features:': - self._append_line = self._append_features_line - elif self._match_section_tag(line): - self._append_line = self._append_various_line - self._append_various_line(line) - else: - self._append_freeform(line) - else: - # This is a free-form documentation block - self._append_freeform(line) - - def _append_args_line(self, line: str) -> None: - """ - Process a line of documentation text in an argument section. - - A symbol line begins the next argument section, a section tag - section or a non-indented line after a blank line begins an - additional section. Start that section and append the line to - it. - - Else, append the line to the current section. - - """ - match = self._match_at_name_colon(line) - if match: - line = line[match.end():] - self._start_args_section(match.group(1)) - elif self._match_section_tag(line): - self._append_line = self._append_various_line - self._append_various_line(line) - return - elif (self._section.text.endswith('\n\n') - and line and not line[0].isspace()): - if line == 'Features:': - self._append_line = self._append_features_line - else: - self._start_section() - self._append_line = self._append_various_line - self._append_various_line(line) - return - - self._append_freeform(line) - - def _append_features_line(self, line: str) -> None: - match = self._match_at_name_colon(line) - if match: - line = line[match.end():] - self._start_features_section(match.group(1)) - elif self._match_section_tag(line): - self._append_line = self._append_various_line - self._append_various_line(line) - return - elif (self._section.text.endswith('\n\n') - and line and not line[0].isspace()): - self._start_section() - self._append_line = self._append_various_line - self._append_various_line(line) - return - - self._append_freeform(line) - - def _append_various_line(self, line: str) -> None: - """ - Process a line of documentation text in an additional section. - - A symbol line is an error. - - A section tag begins an additional section. Start that - section and append the line to it. - - Else, append the line to the current section. - """ - match = self._match_at_name_colon(line) - if match: - raise QAPIParseError(self._parser, - "description of '@%s:' follows a section" - % match.group(1)) - match = self._match_section_tag(line) - if match: - line = line[match.end():] - self._start_section(match.group(1)) - - self._append_freeform(line) - - def _start_symbol_section( - self, - symbols_dict: Dict[str, 'QAPIDoc.ArgSection'], - name: str) -> None: - # FIXME invalid names other than the empty string aren't flagged + def _new_description(self, name: str, + desc: Dict[str, ArgSection]) -> None: if not name: raise QAPIParseError(self._parser, "invalid parameter name") - if name in symbols_dict: + if name in desc: raise QAPIParseError(self._parser, "'%s' parameter name duplicated" % name) - assert not self.sections - new_section = QAPIDoc.ArgSection(self._parser, '@' + name) - self._switch_section(new_section) - symbols_dict[name] = new_section + section = self.ArgSection(self._parser, '@' + name) + self.all_sections.append(section) + desc[name] = section - def _start_args_section(self, name: str) -> None: - self._start_symbol_section(self.args, name) + def new_argument(self, name: str) -> None: + self._new_description(name, self.args) - def _start_features_section(self, name: str) -> None: - self._start_symbol_section(self.features, name) + def new_feature(self, name: str) -> None: + self._new_description(name, self.features) - def _start_section(self, tag: Optional[str] = None) -> None: - if not tag and not self._section.tag: - # extend current section - return - if tag in ('Returns', 'Since') and self.has_section(tag): - raise QAPIParseError(self._parser, - "duplicated '%s' section" % tag) - new_section = QAPIDoc.Section(self._parser, tag) - self._switch_section(new_section) - self.sections.append(new_section) - - def _switch_section(self, new_section: 'QAPIDoc.Section') -> None: - text = self._section.text = self._section.text.strip('\n') - - # Only the 'body' section is allowed to have an empty body. - # All other sections, including anonymous ones, must have text. - if self._section != self.body and not text: - # We do not create anonymous sections unless there is - # something to put in them; this is a parser bug. - assert self._section.tag - raise QAPISemError( - self._section.info, - "text required after '%s:'" % self._section.tag) - - self._section = new_section - - def _append_freeform(self, line: str) -> None: - match = re.match(r'(@\S+:)', line) - if match: - raise QAPIParseError(self._parser, - "'%s' not allowed in free-form documentation" - % match.group(1)) - self._section.append(line) + def append_line(self, line: str) -> None: + self.all_sections[-1].append_line(line) def connect_member(self, member: 'QAPISchemaMember') -> None: if member.name not in self.args: @@ -758,8 +700,8 @@ def connect_member(self, member: 'QAPISchemaMember') -> None: raise QAPISemError(member.info, "%s '%s' lacks documentation" % (member.role, member.name)) - self.args[member.name] = QAPIDoc.ArgSection(self._parser, - '@' + member.name) + self.args[member.name] = QAPIDoc.ArgSection( + self._parser, '@' + member.name) self.args[member.name].connect(member) def connect_feature(self, feature: 'QAPISchemaFeature') -> None: From patchwork Mon Feb 26 10:49:53 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571943 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 8BB0AC54E49 for ; Mon, 26 Feb 2024 10:52:44 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZ5-0002hJ-AK; Mon, 26 Feb 2024 05:50:31 -0500 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 1reYYi-0002bt-Kn for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:14 -0500 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 1reYYb-0003jn-Js for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:07 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944601; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=0OpC8VJdKlXR+vl6ysj+HO/1NUcTsIx8fThTL+bzAhw=; b=UuQNgj3DZtyCCVbV/25Ey0SuKD5xHYfcqzzs8o9ALU0TlufJ6gwiPJLO1gy+2c5sNmB6aB +DpRyMVhlPP+yt3aScdhS0mB8NDfVULSnzMq8j53ivx5U6raoNDTsKa+CuQ0PSsHg2VkEs MgMqaQUZZsFdly6LjFFViBiK+fxOo0w= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-387-YdJgNVdaNMiACQDP97Cr_w-1; Mon, 26 Feb 2024 05:49:58 -0500 X-MC-Unique: YdJgNVdaNMiACQDP97Cr_w-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 32A6B85CE41; Mon, 26 Feb 2024 10:49:58 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E556C8CE8; Mon, 26 Feb 2024 10:49:57 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B557721E5A0D; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 16/17] qapi: Reject multiple and empty feature descriptions Date: Mon, 26 Feb 2024 11:49:53 +0100 Message-ID: <20240226104954.3781985-17-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.5 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org The parser recognizes only the first "Features:" line. Any subsequent ones are treated as ordinary text, as visible in test case doc-duplicate-features. Recognize "Features:" lines anywhere. A second one is an error. A 'Features:' line without any features is useless, but not an error. Make it an error. This makes detecting a second "Features:" line easier. qapi/run-state.json actually has an instance of this since commit fe17522d854 (qapi: Remove deprecated 'singlestep' member of StatusInfo). Clean it up. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-16-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- qapi/run-state.json | 2 -- scripts/qapi/parser.py | 8 ++++++- tests/qapi-schema/doc-duplicate-features.err | 1 + tests/qapi-schema/doc-duplicate-features.out | 22 -------------------- tests/qapi-schema/doc-empty-features.err | 1 + tests/qapi-schema/doc-empty-features.out | 17 --------------- 6 files changed, 9 insertions(+), 42 deletions(-) diff --git a/qapi/run-state.json b/qapi/run-state.json index d19d23a0fd..dd0770b379 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -108,8 +108,6 @@ # # @status: the virtual machine @RunState # -# Features: -# # Since: 0.14 # ## diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 73ff150430..3d8c62b412 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -507,7 +507,10 @@ def get_doc(self) -> 'QAPIDoc': if line is None: break # Non-blank line, first of a section - if line == 'Features:' and not doc.features: + if line == 'Features:': + if doc.features: + raise QAPIParseError( + self, "duplicated 'Features:' line") self.accept(False) line = self.get_doc_line() while line == '': @@ -520,6 +523,9 @@ def get_doc(self) -> 'QAPIDoc': if text: doc.append_line(text) line = self.get_doc_indented(doc) + if not doc.features: + raise QAPIParseError( + self, 'feature descriptions expected') no_more_args = True elif match := self._match_at_name_colon(line): # description diff --git a/tests/qapi-schema/doc-duplicate-features.err b/tests/qapi-schema/doc-duplicate-features.err index e69de29bb2..cadb2957a6 100644 --- a/tests/qapi-schema/doc-duplicate-features.err +++ b/tests/qapi-schema/doc-duplicate-features.err @@ -0,0 +1 @@ +doc-duplicate-features.json:9:1: duplicated 'Features:' line diff --git a/tests/qapi-schema/doc-duplicate-features.out b/tests/qapi-schema/doc-duplicate-features.out index 43bfe1034b..e69de29bb2 100644 --- a/tests/qapi-schema/doc-duplicate-features.out +++ b/tests/qapi-schema/doc-duplicate-features.out @@ -1,22 +0,0 @@ -module ./builtin -object q_empty -enum QType - prefix QTYPE - member none - member qnull - member qnum - member qstring - member qdict - member qlist - member qbool -module doc-duplicate-features.json -command foo None -> None - gen=True success_response=True boxed=False oob=False preconfig=False - feature feat -doc symbol=foo - body= - - feature=feat -mumble - section=None -Features: diff --git a/tests/qapi-schema/doc-empty-features.err b/tests/qapi-schema/doc-empty-features.err index e69de29bb2..2709a18d8f 100644 --- a/tests/qapi-schema/doc-empty-features.err +++ b/tests/qapi-schema/doc-empty-features.err @@ -0,0 +1 @@ +doc-empty-features.json:8:1: feature descriptions expected diff --git a/tests/qapi-schema/doc-empty-features.out b/tests/qapi-schema/doc-empty-features.out index 473f59552d..e69de29bb2 100644 --- a/tests/qapi-schema/doc-empty-features.out +++ b/tests/qapi-schema/doc-empty-features.out @@ -1,17 +0,0 @@ -module ./builtin -object q_empty -enum QType - prefix QTYPE - member none - member qnull - member qnum - member qstring - member qdict - member qlist - member qbool -module doc-empty-features.json -command foo None -> None - gen=True success_response=True boxed=False oob=False preconfig=False -doc symbol=foo - body= -not a description From patchwork Mon Feb 26 10:49:54 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13571944 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 9C5ADC48BF6 for ; Mon, 26 Feb 2024 10:52:58 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1reYZB-0002il-Q7; Mon, 26 Feb 2024 05:50:37 -0500 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 1reYYm-0002cE-Gl for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:16 -0500 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 1reYYc-0003kP-Oz for qemu-devel@nongnu.org; Mon, 26 Feb 2024 05:50:09 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1708944601; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=OekHLpN6vzZJTV5G+d2k3Xx25V6a7wHSDzsezDC1Z9E=; b=GeTeVYIGgPUP5qDe12uw1tzylhiCRBYOiknVAwmrlQpesntYkIyHlggb1imh5Ka+QDZzMu Lcwd0hnGwxt9AQpANbKPkz6S6TgyVw54VNcL1PMiI+mTqR+b7A6DCWSoyTxvz8cy1MUIvS QqQjCW54c6AjX00N1I6kD8R1/PJxNhA= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-619-wONSnZ6dOJWov4ZLwqkg_A-1; Mon, 26 Feb 2024 05:49:58 -0500 X-MC-Unique: wONSnZ6dOJWov4ZLwqkg_A-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 33B6D85A588; Mon, 26 Feb 2024 10:49:58 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E60C524D; Mon, 26 Feb 2024 10:49:57 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B833E21E5A0E; Mon, 26 Feb 2024 11:49:54 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= Subject: [PULL 17/17] qapi: Divorce QAPIDoc from QAPIParseError Date: Mon, 26 Feb 2024 11:49:54 +0100 Message-ID: <20240226104954.3781985-18-armbru@redhat.com> In-Reply-To: <20240226104954.3781985-1-armbru@redhat.com> References: <20240226104954.3781985-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.097, 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_H2=-0.001, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org QAPIDoc stores a reference to QAPIParser just to pass it to QAPIParseError. The resulting error position depends on the state of the parser. It happens to be the current comment line. Servicable, but action at a distance. The commit before previous moved most uses of QAPIParseError from QAPIDoc to QAPIParser. There are just three left. Convert them to QAPISemError. This involves passing info to a few methods. Then drop the reference to QAPIParser. The three errors lose the column number. Not really interesting here: it's the comment line's indentation. Signed-off-by: Markus Armbruster Message-ID: <20240216145841.2099240-17-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- scripts/qapi/parser.py | 66 +++++++++------------ tests/qapi-schema/doc-duplicated-arg.err | 2 +- tests/qapi-schema/doc-duplicated-return.err | 2 +- tests/qapi-schema/doc-duplicated-since.err | 2 +- tests/qapi-schema/doc-empty-arg.err | 2 +- 5 files changed, 32 insertions(+), 42 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 3d8c62b412..11707418fb 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -494,7 +494,7 @@ def get_doc(self) -> 'QAPIDoc': symbol = line[1:-1] if not symbol: raise QAPIParseError(self, "name required after '@'") - doc = QAPIDoc(self, info, symbol) + doc = QAPIDoc(info, symbol) self.accept(False) line = self.get_doc_line() no_more_args = False @@ -518,7 +518,7 @@ def get_doc(self) -> 'QAPIDoc': line = self.get_doc_line() while (line is not None and (match := self._match_at_name_colon(line))): - doc.new_feature(match.group(1)) + doc.new_feature(self.info, match.group(1)) text = line[match.end():] if text: doc.append_line(text) @@ -536,7 +536,7 @@ def get_doc(self) -> 'QAPIDoc': % match.group(1)) while (line is not None and (match := self._match_at_name_colon(line))): - doc.new_argument(match.group(1)) + doc.new_argument(self.info, match.group(1)) text = line[match.end():] if text: doc.append_line(text) @@ -546,7 +546,7 @@ def get_doc(self) -> 'QAPIDoc': r'(Returns|Since|Notes?|Examples?|TODO): *', line): # tagged section - doc.new_tagged_section(match.group(1)) + doc.new_tagged_section(self.info, match.group(1)) text = line[match.end():] if text: doc.append_line(text) @@ -558,13 +558,13 @@ def get_doc(self) -> 'QAPIDoc': "unexpected '=' markup in definition documentation") else: # tag-less paragraph - doc.ensure_untagged_section() + doc.ensure_untagged_section(self.info) doc.append_line(line) line = self.get_doc_paragraph(doc) else: # Free-form documentation - doc = QAPIDoc(self, info) - doc.ensure_untagged_section() + doc = QAPIDoc(info) + doc.ensure_untagged_section(self.info) first = True while line is not None: if match := self._match_at_name_colon(line): @@ -607,12 +607,10 @@ class QAPIDoc: """ class Section: - def __init__(self, parser: QAPISchemaParser, + def __init__(self, info: QAPISourceInfo, tag: Optional[str] = None): # section source info, i.e. where it begins - self.info = parser.info - # parser, for error messages about indentation - self._parser = parser + self.info = info # section tag, if any ('Returns', '@name', ...) self.tag = tag # section text without tag @@ -622,27 +620,20 @@ def append_line(self, line: str) -> None: self.text += line + '\n' class ArgSection(Section): - def __init__(self, parser: QAPISchemaParser, - tag: str): - super().__init__(parser, tag) + def __init__(self, info: QAPISourceInfo, tag: str): + super().__init__(info, tag) self.member: Optional['QAPISchemaMember'] = None def connect(self, member: 'QAPISchemaMember') -> None: self.member = member - def __init__(self, parser: QAPISchemaParser, info: QAPISourceInfo, - symbol: Optional[str] = None): - # self._parser is used to report errors with QAPIParseError. The - # resulting error position depends on the state of the parser. - # It happens to be the beginning of the comment. More or less - # servicable, but action at a distance. - self._parser = parser + def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None): # info points to the doc comment block's first line self.info = info # definition doc's symbol, None for free-form doc self.symbol: Optional[str] = symbol # the sections in textual order - self.all_sections: List[QAPIDoc.Section] = [QAPIDoc.Section(parser)] + self.all_sections: List[QAPIDoc.Section] = [QAPIDoc.Section(info)] # the body section self.body: Optional[QAPIDoc.Section] = self.all_sections[0] # dicts mapping parameter/feature names to their description @@ -658,44 +649,43 @@ def end(self) -> None: raise QAPISemError( section.info, "text required after '%s:'" % section.tag) - def ensure_untagged_section(self) -> None: + def ensure_untagged_section(self, info: QAPISourceInfo) -> None: if self.all_sections and not self.all_sections[-1].tag: # extend current section self.all_sections[-1].text += '\n' return # start new section - section = self.Section(self._parser) + section = self.Section(info) self.sections.append(section) self.all_sections.append(section) - def new_tagged_section(self, tag: str) -> None: + def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None: if tag in ('Returns', 'Since'): for section in self.all_sections: if isinstance(section, self.ArgSection): continue if section.tag == tag: - raise QAPIParseError( - self._parser, "duplicated '%s' section" % tag) - section = self.Section(self._parser, tag) + raise QAPISemError( + info, "duplicated '%s' section" % tag) + section = self.Section(info, tag) self.sections.append(section) self.all_sections.append(section) - def _new_description(self, name: str, + def _new_description(self, info: QAPISourceInfo, name: str, desc: Dict[str, ArgSection]) -> None: if not name: - raise QAPIParseError(self._parser, "invalid parameter name") + raise QAPISemError(info, "invalid parameter name") if name in desc: - raise QAPIParseError(self._parser, - "'%s' parameter name duplicated" % name) - section = self.ArgSection(self._parser, '@' + name) + raise QAPISemError(info, "'%s' parameter name duplicated" % name) + section = self.ArgSection(info, '@' + name) self.all_sections.append(section) desc[name] = section - def new_argument(self, name: str) -> None: - self._new_description(name, self.args) + def new_argument(self, info: QAPISourceInfo, name: str) -> None: + self._new_description(info, name, self.args) - def new_feature(self, name: str) -> None: - self._new_description(name, self.features) + def new_feature(self, info: QAPISourceInfo, name: str) -> None: + self._new_description(info, name, self.features) def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) @@ -707,7 +697,7 @@ def connect_member(self, member: 'QAPISchemaMember') -> None: "%s '%s' lacks documentation" % (member.role, member.name)) self.args[member.name] = QAPIDoc.ArgSection( - self._parser, '@' + member.name) + self.info, '@' + member.name) self.args[member.name].connect(member) def connect_feature(self, feature: 'QAPISchemaFeature') -> None: diff --git a/tests/qapi-schema/doc-duplicated-arg.err b/tests/qapi-schema/doc-duplicated-arg.err index 0d0d777a1f..d876312734 100644 --- a/tests/qapi-schema/doc-duplicated-arg.err +++ b/tests/qapi-schema/doc-duplicated-arg.err @@ -1 +1 @@ -doc-duplicated-arg.json:6:1: 'a' parameter name duplicated +doc-duplicated-arg.json:6: 'a' parameter name duplicated diff --git a/tests/qapi-schema/doc-duplicated-return.err b/tests/qapi-schema/doc-duplicated-return.err index f19a2b8ec4..503b916b25 100644 --- a/tests/qapi-schema/doc-duplicated-return.err +++ b/tests/qapi-schema/doc-duplicated-return.err @@ -1 +1 @@ -doc-duplicated-return.json:8:1: duplicated 'Returns' section +doc-duplicated-return.json:8: duplicated 'Returns' section diff --git a/tests/qapi-schema/doc-duplicated-since.err b/tests/qapi-schema/doc-duplicated-since.err index 565b753b6a..a9b60c0c3d 100644 --- a/tests/qapi-schema/doc-duplicated-since.err +++ b/tests/qapi-schema/doc-duplicated-since.err @@ -1 +1 @@ -doc-duplicated-since.json:8:1: duplicated 'Since' section +doc-duplicated-since.json:8: duplicated 'Since' section diff --git a/tests/qapi-schema/doc-empty-arg.err b/tests/qapi-schema/doc-empty-arg.err index 2d0f35f310..83f4fc66d5 100644 --- a/tests/qapi-schema/doc-empty-arg.err +++ b/tests/qapi-schema/doc-empty-arg.err @@ -1 +1 @@ -doc-empty-arg.json:5:1: invalid parameter name +doc-empty-arg.json:5: invalid parameter name