From patchwork Mon Mar 4 06:32:19 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580099 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 08CF7C54E49 for ; Mon, 4 Mar 2024 06:33:37 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1sV-0005Xg-TM; Mon, 04 Mar 2024 01:32:48 -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 1rh1sS-0005XB-Lw for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:45 -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 1rh1sR-00007Y-0y for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:44 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533960; 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=TfE/bEdPvuajNPHkFQIHTUt/Ptrgpq+oPHT+0UHMa2c=; b=VlXy4rFsfgnwzZWySbf7ezHevzlq0httJHGMiAZEw5AMw1OzdZgPC2zNSj/wNeycIgmZZ6 UlizifEr9YeEwPmz+js7vpRGOfWPjeuEp0yK4/jxSqzCJ+h4lzQ+aN1MG0KD5bOAWBXFkj NzedPFD1ejjEzvuzhUgldylvZgSTI/A= 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-531-IzhuNUV7MKa4qORbYQW6_w-1; Mon, 04 Mar 2024 01:32:38 -0500 X-MC-Unique: IzhuNUV7MKa4qORbYQW6_w-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 D645C3C14943; Mon, 4 Mar 2024 06:32:37 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 943BB28D; Mon, 4 Mar 2024 06:32:37 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6DB8221E6A28; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 01/18] qapi: Memorize since & returns sections Date: Mon, 4 Mar 2024 07:32:19 +0100 Message-ID: <20240304063236.213955-2-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 This is chiefly to make code that looks up these sections easier to read. Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-2-armbru@redhat.com> --- scripts/qapi/parser.py | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 11707418fb..bfc47cf3cb 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -639,6 +639,10 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None): # dicts mapping parameter/feature names to their description self.args: Dict[str, QAPIDoc.ArgSection] = {} self.features: Dict[str, QAPIDoc.ArgSection] = {} + # a command's "Returns" section + self.returns: Optional[QAPIDoc.Section] = None + # "Since" section + self.since: Optional[QAPIDoc.Section] = None # sections other than .body, .args, .features self.sections: List[QAPIDoc.Section] = [] @@ -660,14 +664,17 @@ def ensure_untagged_section(self, info: QAPISourceInfo) -> None: self.all_sections.append(section) 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 QAPISemError( - info, "duplicated '%s' section" % tag) section = self.Section(info, tag) + if tag == 'Returns': + if self.returns: + raise QAPISemError( + info, "duplicated '%s' section" % tag) + self.returns = section + elif tag == 'Since': + if self.since: + raise QAPISemError( + info, "duplicated '%s' section" % tag) + self.since = section self.sections.append(section) self.all_sections.append(section) @@ -708,13 +715,9 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: self.features[feature.name].connect(feature) def check_expr(self, expr: QAPIExpression) -> None: - if 'command' not in expr: - sec = next((sec for sec in self.sections - if sec.tag == 'Returns'), - None) - if sec: - raise QAPISemError(sec.info, - "'Returns:' is only valid for commands") + if self.returns and 'command' not in expr: + raise QAPISemError(self.returns.info, + "'Returns:' is only valid for commands") def check(self) -> None: From patchwork Mon Mar 4 06:32:20 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580100 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 64277C54E4A for ; Mon, 4 Mar 2024 06:33:52 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1se-0005aP-GV; Mon, 04 Mar 2024 01:32:56 -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 1rh1sT-0005XA-Lg for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:45 -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 1rh1sQ-000079-Vw for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:44 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533959; 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=2nmkhQb09zV+qs/RWYjWNCxM3Ojz6v2JXLi69VMeL1w=; b=c6QDWEhA3AMFB68KDmcfSlvAdpGbVvhe08mxKG6uvexj/biyf4pWAe06vIiVMRJx+39OXk i26zqlqzPyWhsKvrxmmcyHCvf9OE18APmF7c7EpES3R6B7E0OyjU1wlMBQHEXL0w9yjaD0 RF0l+ZMTmKUIV1nl+aqCoHscu+2EtDc= 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-462-KdlBDffvOc23YQjQ9X47fg-1; Mon, 04 Mar 2024 01:32:38 -0500 X-MC-Unique: KdlBDffvOc23YQjQ9X47fg-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 D5584185A781; Mon, 4 Mar 2024 06:32:37 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 942CA1C060AF; Mon, 4 Mar 2024 06:32:37 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7057C21E691E; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 02/18] qapi: Slightly clearer error message for invalid "Returns" section Date: Mon, 4 Mar 2024 07:32:20 +0100 Message-ID: <20240304063236.213955-3-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Change "'Returns:' is only valid for commands" to "'Returns' section is only valid for commands". Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-3-armbru@redhat.com> --- scripts/qapi/parser.py | 5 +++-- tests/qapi-schema/doc-invalid-return.err | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index bfc47cf3cb..e4c2259e39 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -716,8 +716,9 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: def check_expr(self, expr: QAPIExpression) -> None: if self.returns and 'command' not in expr: - raise QAPISemError(self.returns.info, - "'Returns:' is only valid for commands") + raise QAPISemError( + self.returns.info, + "'Returns' section 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 3d9e71c2b3..aafd57b135 100644 --- a/tests/qapi-schema/doc-invalid-return.err +++ b/tests/qapi-schema/doc-invalid-return.err @@ -1 +1 @@ -doc-invalid-return.json:6: 'Returns:' is only valid for commands +doc-invalid-return.json:6: 'Returns' section is only valid for commands From patchwork Mon Mar 4 06:32:21 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580107 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 334CBC48BF6 for ; Mon, 4 Mar 2024 06:34:38 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1sh-0005bJ-2X; Mon, 04 Mar 2024 01:32:59 -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 1rh1sU-0005XV-Jm for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:47 -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 1rh1sR-00008X-An for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533962; 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=xoerteqzZBJWDn5qrScOg6SAib2ZuH5H4VV8uCSj2Xw=; b=ahWTYlHDyeOs9S0MgIkA5lKqKcc55A8lb38lTlsi990hRNSZ5soob+Xw3ffav3SBIceJ/5 QLmmjzU0zv+oB3q0PI6qqT/+3rAeazNufuhi3uPGGOEJbdCSeFwPvcqHQvC0KBIG4Y9lKu jKpsibO396yBs91pSTMfmMWVqZIXdKQ= 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-557-wQk1LFeXORir5QTyX4KVfw-1; Mon, 04 Mar 2024 01:32:38 -0500 X-MC-Unique: wQk1LFeXORir5QTyX4KVfw-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 001F63C14941; Mon, 4 Mar 2024 06:32:38 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 944ED1121306; Mon, 4 Mar 2024 06:32:37 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7321621E692E; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 03/18] qapi: New documentation section tag "Errors" Date: Mon, 4 Mar 2024 07:32:21 +0100 Message-ID: <20240304063236.213955-4-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.3 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 We use section "Returns" for documenting both success and error response of commands. I intend to generate better command success response documentation. Easier when "Returns" documents just he success response. Create new section tag "Errors". The next two commits will move error response documentation from "Returns" sections to "Errors" sections. Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-4-armbru@redhat.com> --- docs/devel/qapi-code-gen.rst | 6 +++++- scripts/qapi/parser.py | 23 +++++++++++++++++------ tests/qapi-schema/doc-good.json | 2 ++ tests/qapi-schema/doc-good.out | 2 ++ tests/qapi-schema/doc-good.txt | 6 ++++++ 5 files changed, 32 insertions(+), 7 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 6804a4b596..f453bd3546 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -996,7 +996,8 @@ line "Features:", like this:: 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. +"Returns:", "Errors:", "TODO:". It ends with the start of a new +section. The second and subsequent lines of tagged sections must be indented like this:: @@ -1007,6 +1008,9 @@ like this:: # Duis aute irure dolor in reprehenderit in voluptate velit esse # cillum dolore eu fugiat nulla pariatur. +"Returns" and "Errors" sections are only valid for commands. They +document the success and the error response, respectively. + A "Since: x.y.z" tagged section lists the release that introduced the definition. diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index e4c2259e39..a32b2c7e7f 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -543,7 +543,7 @@ def get_doc(self) -> 'QAPIDoc': line = self.get_doc_indented(doc) no_more_args = True elif match := re.match( - r'(Returns|Since|Notes?|Examples?|TODO): *', + r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', line): # tagged section doc.new_tagged_section(self.info, match.group(1)) @@ -639,8 +639,9 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None): # dicts mapping parameter/feature names to their description self.args: Dict[str, QAPIDoc.ArgSection] = {} self.features: Dict[str, QAPIDoc.ArgSection] = {} - # a command's "Returns" section + # a command's "Returns" and "Errors" section self.returns: Optional[QAPIDoc.Section] = None + self.errors: Optional[QAPIDoc.Section] = None # "Since" section self.since: Optional[QAPIDoc.Section] = None # sections other than .body, .args, .features @@ -670,6 +671,11 @@ def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None: raise QAPISemError( info, "duplicated '%s' section" % tag) self.returns = section + elif tag == 'Errors': + if self.errors: + raise QAPISemError( + info, "duplicated '%s' section" % tag) + self.errors = section elif tag == 'Since': if self.since: raise QAPISemError( @@ -715,10 +721,15 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: self.features[feature.name].connect(feature) def check_expr(self, expr: QAPIExpression) -> None: - if self.returns and 'command' not in expr: - raise QAPISemError( - self.returns.info, - "'Returns' section is only valid for commands") + if 'command' not in expr: + if self.returns: + raise QAPISemError( + self.returns.info, + "'Returns' section is only valid for commands") + if self.errors: + raise QAPISemError( + self.returns.info, + "'Errors' section is only valid for commands") def check(self) -> None: diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 5bb2b69071..de38a386e8 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -159,6 +159,8 @@ # # Returns: @Object # +# Errors: some +# # TODO: frobnicate # # Notes: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 34ee74af4b..716a9a4102 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -173,6 +173,8 @@ another feature @arg3 is undocumented section=Returns @Object + section=Errors +some section=TODO frobnicate section=Notes diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index 879f6ff50a..847db70412 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -206,6 +206,12 @@ Returns "Object" +Errors +~~~~~~ + +some + + Notes ~~~~~ From patchwork Mon Mar 4 06:32:22 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580101 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 559AAC54E49 for ; Mon, 4 Mar 2024 06:33:52 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1tE-00068E-Sv; Mon, 04 Mar 2024 01:33: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 1rh1sV-0005XW-1x for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:47 -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 1rh1sR-00008V-Ap for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533962; 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=L4GnWHNwD/AcGghOgj5tGaSvGA1f4PcDDOBdd8GirJ4=; b=R9UREJAY+basK+B8QFtwa8lOxjZL5/YcWaWtLTh9cAv62Ru3rHPqrFt0OvfiXsZXTGeISl hDmKmVIamTZFxVW8YAY3tn8NOhGRk/tK3WxSgIcRpAIbsc458Uw9U5wlSLmFxiOTvOfSI2 52uyr8BgY8qBCYNq8McIyISKF6MVTVA= 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-313-OECM3uLdMVefPvJg9pIG1A-1; Mon, 04 Mar 2024 01:32:38 -0500 X-MC-Unique: OECM3uLdMVefPvJg9pIG1A-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 1CA92835380; Mon, 4 Mar 2024 06:32:38 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 94588422A9; Mon, 4 Mar 2024 06:32:37 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7651021E6939; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 04/18] qapi: Move error documentation to new "Errors" sections Date: Mon, 4 Mar 2024 07:32:22 +0100 Message-ID: <20240304063236.213955-5-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-5-armbru@redhat.com> --- qapi/block-core.json | 44 ++++++++++++++++++++++++++++++++++++++++ qapi/block-export.json | 23 ++++++++++++--------- qapi/block.json | 8 ++++++-- qapi/machine-target.json | 35 ++++++++++++++++++++------------ qapi/machine.json | 6 ++++++ qapi/misc.json | 10 +++++++-- qapi/net.json | 14 ++++++++++--- qapi/qdev.json | 2 ++ qapi/qom.json | 4 ++++ qapi/transaction.json | 3 ++- qapi/ui.json | 6 ++++++ qapi/yank.json | 2 ++ 12 files changed, 126 insertions(+), 31 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 22b8634422..cea46b4668 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1458,6 +1458,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 0.14 @@ -1676,6 +1678,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 0.14 @@ -1756,6 +1760,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If "device" does not exist or cannot be determined, # DeviceNotFound # @@ -1856,6 +1862,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @device does not exist, DeviceNotFound # - Any other error returns a GenericError. # @@ -1896,6 +1904,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, GenericError # # Since: 1.6 @@ -1923,6 +1933,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 2.3 @@ -2129,6 +2141,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, GenericError # # Since: 1.3 @@ -2306,6 +2320,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is already taken, GenericError with an explanation # @@ -2330,6 +2346,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is not found, GenericError with an explanation # - if @name is frozen by an operation, GenericError @@ -2355,6 +2373,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation # @@ -2377,6 +2397,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation # @@ -2399,6 +2421,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation # @@ -2429,6 +2453,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If any bitmap in @bitmaps or @target is not found, # GenericError @@ -2471,6 +2497,8 @@ # # Returns: # - BlockDirtyBitmapSha256 on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found or if hashing has failed, GenericError # with an explanation @@ -2868,6 +2896,8 @@ # # Returns: # - Nothing on success. +# +# Errors: # - If @device does not exist, DeviceNotFound. # # Since: 1.1 @@ -2907,6 +2937,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -2952,6 +2984,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -2979,6 +3013,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -3004,6 +3040,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -3036,6 +3074,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -6072,6 +6112,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, GenericError # - If any snapshot matching @name exists, or @name is empty, # GenericError @@ -6109,6 +6151,8 @@ # # Returns: # - SnapshotInfo on success +# +# Errors: # - If @device is not a valid block device, GenericError # - If snapshot not found, GenericError # - If the format of the image used does not support it, diff --git a/qapi/block-export.json b/qapi/block-export.json index d9bd376b48..3919a2d5b9 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -65,7 +65,8 @@ # server from advertising multiple client support (since 5.2; # default: 0). # -# Returns: error if the server is already running. +# Errors: +# - if the server is already running # # Since: 1.3 ## @@ -247,8 +248,9 @@ # @deprecated: This command is deprecated. Use @block-export-add # instead. # -# Returns: error if the server is not running, or export with the same -# name already exists. +# Errors: +# - if the server is not running +# - if an export with the same name already exists # # Since: 1.3 ## @@ -294,11 +296,10 @@ # @deprecated: This command is deprecated. Use @block-export-del # instead. # -# Returns: error if -# -# - the server is not running -# - export is not found -# - mode is 'safe' and there are existing connections +# Errors: +# - if the server is not running +# - if export is not found +# - if mode is 'safe' and there are existing connections # # Since: 2.12 ## @@ -415,8 +416,10 @@ # @mode: Mode of command operation. See @BlockExportRemoveMode # description. Default is 'safe'. # -# Returns: Error if the export is not found or @mode is 'safe' and the -# export is still in use (e.g. by existing client connections) +# Errors: +# - if the export is not found +# - if @mode is 'safe' and the export is still in use (e.g. by +# existing client connections) # # Since: 5.2 ## diff --git a/qapi/block.json b/qapi/block.json index 79a0bcc208..dab616799a 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -112,6 +112,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Notes: Ejecting a device with no media results in success @@ -461,6 +463,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 1.1 @@ -540,8 +544,8 @@ # @boundaries-flush: list of interval boundary values for flush # latency histogram. # -# Returns: error if device is not found or any boundary arrays are -# invalid. +# Errors: +# - if device is not found or any boundary arrays are invalid. # # Since: 4.0 # diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 2c5dda735e..db6c0fae98 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -154,10 +154,13 @@ # Some architectures may not support comparing CPU models. s390x # supports comparing CPU models. # -# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU -# models is not supported, if a model cannot be used, if a model -# contains an unknown cpu definition name, unknown properties or -# properties with wrong types. +# Returns: a CpuModelBaselineInfo +# +# Errors: +# - if comparing CPU models is not supported +# - if a model cannot be used +# - if a model contains an unknown cpu definition name, unknown +# properties or properties with wrong types. # # Note: this command isn't specific to s390x, but is only implemented # on this architecture currently. @@ -201,10 +204,13 @@ # Some architectures may not support baselining CPU models. s390x # supports baselining CPU models. # -# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU -# models is not supported, if a model cannot be used, if a model -# contains an unknown cpu definition name, unknown properties or -# properties with wrong types. +# Returns: a CpuModelBaselineInfo +# +# Errors: +# - if baselining CPU models is not supported +# - if a model cannot be used +# - if a model contains an unknown cpu definition name, unknown +# properties or properties with wrong types. # # Note: this command isn't specific to s390x, but is only implemented # on this architecture currently. @@ -263,11 +269,14 @@ # Some architectures may not support all expansion types. s390x # supports "full" and "static". Arm only supports "full". # -# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU -# models is not supported, if the model cannot be expanded, if the -# model contains an unknown CPU definition name, unknown -# properties or properties with a wrong type. Also returns an -# error if an expansion type is not supported. +# Returns: a CpuModelExpansionInfo +# +# Errors: +# - if expanding CPU models is not supported +# - if the model cannot be expanded +# - if the model contains an unknown CPU definition name, unknown +# properties or properties with a wrong type +# - if an expansion type is not supported # # Since: 2.8 ## diff --git a/qapi/machine.json b/qapi/machine.json index 93b4677286..0985c61740 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1062,6 +1062,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive @@ -1100,6 +1102,8 @@ # # Returns: # - @BalloonInfo on success +# +# Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive @@ -1164,6 +1168,8 @@ # # Returns: # - @HvBalloonInfo on success +# +# Errors: # - If no hv-balloon device is present, guest memory status # reporting is not enabled or no guest memory status report # received yet, GenericError diff --git a/qapi/misc.json b/qapi/misc.json index 11c55c2b6c..578f574a68 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -345,6 +345,8 @@ # # Returns: # - @AddfdInfo on success +# +# Errors: # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError # @@ -376,6 +378,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @fdset-id or @fd is not found, GenericError # # Since: 1.2 @@ -528,8 +532,10 @@ # @option: option name # # Returns: list of @CommandLineOptionInfo for all options (or for the -# given @option). Returns an error if the given @option doesn't -# exist. +# given @option). +# +# Errors: +# - if the given @option doesn't exist # # Since: 1.5 # diff --git a/qapi/net.json b/qapi/net.json index 1374caac64..09e644a742 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -19,6 +19,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @name is not a valid network device, DeviceNotFound # # Since: 0.14 @@ -46,6 +48,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @type is not a valid network backend, DeviceNotFound # # Example: @@ -67,6 +71,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @id is not a valid network backend, DeviceNotFound # # Since: 0.14 @@ -828,9 +834,11 @@ # @name: net client name # # Returns: list of @RxFilterInfo for all NICs (or for the given NIC). -# Returns an error if the given @name doesn't exist, or given NIC -# doesn't support rx-filter querying, or given net client isn't a -# NIC. +# +# Errors: +# - if the given @name doesn't exist +# - if the given NIC doesn't support rx-filter querying +# - if the given net client isn't a NIC # # Since: 1.6 # diff --git a/qapi/qdev.json b/qapi/qdev.json index 32ffaee644..cc72c55a99 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -91,6 +91,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @id is not a valid device, DeviceNotFound # # Notes: When this command completes, the device may not be removed diff --git a/qapi/qom.json b/qapi/qom.json index 2a6e49365a..33aa30bb41 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -1058,6 +1058,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - Error if @qom-type is not a valid class name # # Since: 2.0 @@ -1081,6 +1083,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - Error if @id is not a valid id for a QOM object # # Since: 2.0 diff --git a/qapi/transaction.json b/qapi/transaction.json index 45233ddd2a..78cc21800d 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -236,7 +236,8 @@ # # Returns: nothing on success # -# Errors depend on the operations of the transaction +# Errors: +# Any errors from commands in the transaction # # Note: The transaction aborts on the first failure. Therefore, there # will be information on only one failed operation returned in an diff --git a/qapi/ui.json b/qapi/ui.json index e3999b7c07..199a412c5a 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -80,6 +80,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If Spice is not enabled, DeviceNotFound # # Since: 0.14 @@ -142,6 +144,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @protocol is 'spice' and Spice is not active, # DeviceNotFound # @@ -1038,6 +1042,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If key is unknown or redundant, GenericError # # Since: 1.3 diff --git a/qapi/yank.json b/qapi/yank.json index b7aeb9ceef..a457284b45 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -80,6 +80,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - @DeviceNotFound error, if any of the YankInstances doesn't exist # # Example: From patchwork Mon Mar 4 06:32:23 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580103 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 A38EEC54E49 for ; Mon, 4 Mar 2024 06:33:58 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1sg-0005b6-E1; Mon, 04 Mar 2024 01:32:58 -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 1rh1sW-0005YG-RO for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:49 -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 1rh1sR-000083-Bd for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:48 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533961; 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=4MgM1k7X1o4w5pqerdPU9z26qKfE16Q0If0WZAOUvIs=; b=BAy9lWJQJnQC+jastxAx6TAbpR2VdPZ3BpLtJireUaUR8DXoR/VVtGfXt/ZcFMBZPB38i+ 96prXqhwJj3ONBPS3xOXIgzOz79wJ18iXoPH/o39yjpQSVAJxdKtnYg6koiXTi/W5D2YeF a2Wrx8zG6W2Bhmh72YAPUcmi/fpicj0= 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-117-R_2ccEZAMJuhSFKNSgxLRg-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: R_2ccEZAMJuhSFKNSgxLRg-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (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 6CC5C846D5D; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0EE662166B36; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 797C121E6889; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 05/18] qapi: Delete useless "Returns" sections Date: Mon, 4 Mar 2024 07:32:23 +0100 Message-ID: <20240304063236.213955-6-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.6 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-6-armbru@redhat.com> --- qapi/block-core.json | 66 ---------------------------------------- qapi/block.json | 6 ---- qapi/char.json | 6 ---- qapi/dump.json | 2 -- qapi/machine-target.json | 2 -- qapi/machine.json | 11 ------- qapi/migration.json | 26 ---------------- qapi/misc-target.json | 3 -- qapi/misc.json | 15 --------- qapi/net.json | 9 ------ qapi/qdev.json | 3 -- qapi/qom.json | 6 ---- qapi/run-state.json | 5 +-- qapi/tpm.json | 2 -- qapi/transaction.json | 2 -- qapi/ui.json | 17 ----------- qapi/yank.json | 3 -- 17 files changed, 1 insertion(+), 183 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index cea46b4668..94b01deffc 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1456,9 +1456,6 @@ # # @size: new image size in bytes # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -1676,9 +1673,6 @@ # # For the arguments, see the documentation of BlockdevSnapshotSync. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -1758,9 +1752,6 @@ # is not validated, so care should be taken when specifying the # string or the image chain may not be able to be reopened again. # -# Returns: -# - Nothing on success -# # Errors: # - If "device" does not exist or cannot be determined, # DeviceNotFound @@ -1860,9 +1851,6 @@ # @deprecated: Members @base and @top are deprecated. Use @base-node # and @top-node instead. # -# Returns: -# - Nothing on success -# # Errors: # - If @device does not exist, DeviceNotFound # - Any other error returns a GenericError. @@ -1902,9 +1890,6 @@ # @deprecated: This command is deprecated. Use @blockdev-backup # instead. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, GenericError # @@ -1931,9 +1916,6 @@ # 'backup'. The operation can be stopped before it has completed using # the block-job-cancel command. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -2139,9 +2121,6 @@ # specifies the format of the mirror image, default is to probe if # mode='existing', else the format of the source. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, GenericError # @@ -2318,9 +2297,6 @@ # Create a dirty bitmap with a name on the node, and start tracking # the writes. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is already taken, GenericError with an explanation @@ -2344,9 +2320,6 @@ # with block-dirty-bitmap-add. If the bitmap is persistent, remove it # from its storage too. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2371,9 +2344,6 @@ # backup from this point in time forward will only backup clusters # modified after this clear operation. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2395,9 +2365,6 @@ # # Enables a dirty bitmap so that it will begin tracking disk changes. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2419,9 +2386,6 @@ # # Disables a dirty bitmap so that it will stop tracking disk changes. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2451,9 +2415,6 @@ # dirty in any of the source bitmaps. This can be used to achieve # backup checkpoints, or in simpler usages, to copy bitmaps. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If any bitmap in @bitmaps or @target is not found, @@ -2570,8 +2531,6 @@ # disappear from the query list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: nothing on success. -# # Since: 2.6 # # Example: @@ -2894,9 +2853,6 @@ # disappear from the query list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: -# - Nothing on success. -# # Errors: # - If @device does not exist, DeviceNotFound. # @@ -2935,9 +2891,6 @@ # @speed: the maximum speed, in bytes per second, or 0 for unlimited. # Defaults to 0. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -2982,9 +2935,6 @@ # paused) instead of waiting for the destination to complete its # final synchronization (since 1.3) # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3011,9 +2961,6 @@ # the name of the parameter), but since QEMU 2.7 it can have other # values. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3038,9 +2985,6 @@ # the name of the parameter), but since QEMU 2.7 it can have other # values. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3072,9 +3016,6 @@ # the name of the parameter), but since QEMU 2.7 it can have other # values. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3099,8 +3040,6 @@ # # @id: The job identifier. # -# Returns: Nothing on success -# # Since: 2.12 ## { 'command': 'block-job-dismiss', 'data': { 'id': 'str' }, @@ -3118,8 +3057,6 @@ # # @id: The job identifier. # -# Returns: Nothing on success -# # Since: 2.12 ## { 'command': 'block-job-finalize', 'data': { 'id': 'str' }, @@ -6110,9 +6047,6 @@ # For the arguments, see the documentation of # BlockdevSnapshotInternal. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, GenericError # - If any snapshot matching @name exists, or @name is empty, diff --git a/qapi/block.json b/qapi/block.json index dab616799a..65d9804bdf 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -110,9 +110,6 @@ # # @deprecated: Member @device is deprecated. Use @id instead. # -# Returns: -# - Nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -461,9 +458,6 @@ # the device will be removed from its group and the rest of its # members will not be affected. The 'group' parameter is ignored. # -# Returns: -# - Nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # diff --git a/qapi/char.json b/qapi/char.json index 4873bc635a..777dde55d9 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -139,8 +139,6 @@ # - data itself is always Unicode regardless of format, like any # other string. # -# Returns: Nothing on success -# # Since: 1.4 # # Example: @@ -772,8 +770,6 @@ # # @id: the chardev's ID, must exist and not be in use # -# Returns: Nothing on success -# # Since: 1.4 # # Example: @@ -791,8 +787,6 @@ # # @id: the chardev's ID, must exist # -# Returns: Nothing on success -# # Since: 2.10 # # Example: diff --git a/qapi/dump.json b/qapi/dump.json index f82dd6a1af..4c021dd53c 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -92,8 +92,6 @@ # # Note: All boolean arguments default to false # -# Returns: nothing on success -# # Since: 1.2 # # Example: diff --git a/qapi/machine-target.json b/qapi/machine-target.json index db6c0fae98..519adf3220 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -414,8 +414,6 @@ # # @unstable: This command is experimental. # -# Returns: Nothing on success. -# # Since: 8.2 ## { 'command': 'set-cpu-topology', diff --git a/qapi/machine.json b/qapi/machine.json index 0985c61740..7d3ca33683 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -326,8 +326,6 @@ # # Since: 1.1 # -# Returns: nothing. -# # Note: prior to 4.0, this command does nothing in case the guest # isn't suspended. # @@ -377,8 +375,6 @@ # all CPUs (ppc64). The command fails when the guest doesn't support # injecting. # -# Returns: If successful, nothing -# # Since: 0.14 # # Note: prior to 2.1, this command was only supported for x86 and s390 @@ -778,8 +774,6 @@ # @cpu-index: the index of the virtual CPU to use for translating the # virtual address (defaults to CPU 0) # -# Returns: Nothing on success -# # Since: 0.14 # # Notes: Errors were not reliably returned until 1.1 @@ -806,8 +800,6 @@ # # @filename: the file to save the memory to as binary data # -# Returns: Nothing on success -# # Since: 0.14 # # Notes: Errors were not reliably returned until 1.1 @@ -1060,9 +1052,6 @@ # # From it we have: balloon_size = vm_ram_size - @value # -# Returns: -# - Nothing on success -# # Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap diff --git a/qapi/migration.json b/qapi/migration.json index 0b33a71ab4..27a67e5012 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1566,8 +1566,6 @@ # # Cancel the current executing migration process. # -# Returns: nothing on success -# # Notes: This command succeeds even if there is no migration process # running. # @@ -1587,8 +1585,6 @@ # # @state: The state the migration is currently expected to be in # -# Returns: nothing on success -# # Since: 2.11 # # Example: @@ -1710,8 +1706,6 @@ # @deprecated: Members @inc and @blk are deprecated. Use # blockdev-mirror with NBD instead. # -# Returns: nothing on success -# # Since: 0.14 # # Notes: @@ -1793,8 +1787,6 @@ # @channels: list of migration stream channels with each stream in the # list connected to a destination interface endpoint. # -# Returns: nothing on success -# # Since: 2.3 # # Notes: @@ -1862,8 +1854,6 @@ # @live: Optional argument to ask QEMU to treat this command as part # of a live migration. Default to true. (since 2.11) # -# Returns: Nothing on success -# # Since: 1.1 # # Example: @@ -1882,8 +1872,6 @@ # # @enable: true to enable, false to disable. # -# Returns: nothing -# # Since: 1.3 # # Example: @@ -1926,8 +1914,6 @@ # @failover: true to do failover, false to stop. but cannot be # specified if 'enable' is true. default value is false. # -# Returns: nothing. -# # Example: # # -> { "execute": "xen-set-replication", @@ -1979,8 +1965,6 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # -# Returns: nothing. -# # Example: # # -> { "execute": "xen-colo-do-checkpoint" } @@ -2037,8 +2021,6 @@ # # @uri: the URI to be used for the recovery of migration stream. # -# Returns: nothing. -# # Example: # # -> { "execute": "migrate-recover", @@ -2056,8 +2038,6 @@ # # Pause a migration. Currently it only supports postcopy. # -# Returns: nothing. -# # Example: # # -> { "execute": "migrate-pause" } @@ -2426,8 +2406,6 @@ # # If @tag already exists, an error will be reported # -# Returns: nothing -# # Example: # # -> { "execute": "snapshot-save", @@ -2498,8 +2476,6 @@ # device nodes that can have changed since the original @snapshot-save # command execution. # -# Returns: nothing -# # Example: # # -> { "execute": "snapshot-load", @@ -2561,8 +2537,6 @@ # to determine completion and to fetch details of any errors that # arise. # -# Returns: nothing -# # Example: # # -> { "execute": "snapshot-delete", diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 542a3e42f2..4e0a6492a9 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -472,9 +472,6 @@ # # @port: The port number # -# Returns: -# - Nothing on success. -# # Since: 8.0 # # Example: diff --git a/qapi/misc.json b/qapi/misc.json index 578f574a68..015388aa3e 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -28,8 +28,6 @@ # # @tls: whether to perform TLS. Only applies to the "spice" protocol # -# Returns: nothing on success. -# # Since: 0.14 # # Example: @@ -160,8 +158,6 @@ # # Since: 0.14 # -# Returns: If successful, nothing -# # Notes: This command will succeed if the guest is currently running. # It will also succeed if the guest is in the "inmigrate" state; # in this case, the effect of the command is to make sure the @@ -196,8 +192,6 @@ # # Since: 3.0 # -# Returns: nothing -# # Example: # # -> { "execute": "x-exit-preconfig" } @@ -256,8 +250,6 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 0.14 # # Notes: If @fdname already exists, the file descriptor assigned to it @@ -285,8 +277,6 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 8.0 # # Notes: If @fdname already exists, the file descriptor assigned to it @@ -309,8 +299,6 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 0.14 # # Example: @@ -376,9 +364,6 @@ # # @fd: The file descriptor that is to be removed. # -# Returns: -# - Nothing on success -# # Errors: # - If @fdset-id or @fd is not found, GenericError # diff --git a/qapi/net.json b/qapi/net.json index 09e644a742..417b61a321 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -17,9 +17,6 @@ # # @up: true to set the link status to be up # -# Returns: -# - Nothing on success -# # Errors: # - If @name is not a valid network device, DeviceNotFound # @@ -46,9 +43,6 @@ # # Since: 0.14 # -# Returns: -# - Nothing on success -# # Errors: # - If @type is not a valid network backend, DeviceNotFound # @@ -69,9 +63,6 @@ # # @id: the name of the network backend to remove # -# Returns: -# - Nothing on success -# # Errors: # - If @id is not a valid network backend, DeviceNotFound # diff --git a/qapi/qdev.json b/qapi/qdev.json index cc72c55a99..facaa0bc6a 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -89,9 +89,6 @@ # # @id: the device's ID or QOM path # -# Returns: -# - Nothing on success -# # Errors: # - If @id is not a valid device, DeviceNotFound # diff --git a/qapi/qom.json b/qapi/qom.json index 33aa30bb41..032c6fa037 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -1056,9 +1056,6 @@ # # Create a QOM object. # -# Returns: -# - Nothing on success -# # Errors: # - Error if @qom-type is not a valid class name # @@ -1081,9 +1078,6 @@ # # @id: the name of the QOM object to remove # -# Returns: -# - Nothing on success -# # Errors: # - Error if @id is not a valid id for a QOM object # diff --git a/qapi/run-state.json b/qapi/run-state.json index dd0770b379..789fc34559 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -395,10 +395,7 @@ # # @panic: @PanicAction action taken on guest panic. # -# @watchdog: @WatchdogAction action taken when watchdog timer expires -# . -# -# Returns: Nothing on success. +# @watchdog: @WatchdogAction action taken when watchdog timer expires. # # Since: 6.0 # diff --git a/qapi/tpm.json b/qapi/tpm.json index 07a73e5f2b..1577b5c259 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -166,8 +166,6 @@ # # Return information about the TPM device # -# Returns: @TPMInfo on success -# # Since: 1.5 # # Example: diff --git a/qapi/transaction.json b/qapi/transaction.json index 78cc21800d..5749c133d4 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -234,8 +234,6 @@ # execution of the transaction. See @TransactionProperties for # additional detail. # -# Returns: nothing on success -# # Errors: # Any errors from commands in the transaction # diff --git a/qapi/ui.json b/qapi/ui.json index 199a412c5a..1726f15429 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -78,9 +78,6 @@ # # Set the password of a remote display server. # -# Returns: -# - Nothing on success -# # Errors: # - If Spice is not enabled, DeviceNotFound # @@ -142,9 +139,6 @@ # # Expire the password of a remote display server. # -# Returns: -# - Nothing on success -# # Errors: # - If @protocol is 'spice' and Spice is not active, # DeviceNotFound @@ -191,8 +185,6 @@ # # @format: image format for screendump. (default: ppm) (Since 7.1) # -# Returns: Nothing on success -# # Since: 0.14 # # Example: @@ -1040,9 +1032,6 @@ # @hold-time: time to delay key up events, milliseconds. Defaults to # 100 # -# Returns: -# - Nothing on success -# # Errors: # - If key is unknown or redundant, GenericError # @@ -1265,8 +1254,6 @@ # # @events: List of InputEvent union. # -# Returns: Nothing on success. -# # Since: 2.6 # # Note: The consoles are visible in the qom tree, under @@ -1611,8 +1598,6 @@ # # Reload display configuration. # -# Returns: Nothing on success. -# # Since: 6.0 # # Example: @@ -1670,8 +1655,6 @@ # # Update display configuration. # -# Returns: Nothing on success. -# # Since: 7.1 # # Example: diff --git a/qapi/yank.json b/qapi/yank.json index a457284b45..fffb39a397 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -78,9 +78,6 @@ # # @instances: the instances to be yanked # -# Returns: -# - Nothing on success -# # Errors: # - @DeviceNotFound error, if any of the YankInstances doesn't exist # From patchwork Mon Mar 4 06:32:24 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580105 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 3443EC48BF6 for ; Mon, 4 Mar 2024 06:34:17 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1tB-0005zu-QI; Mon, 04 Mar 2024 01:33:29 -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 1rh1sb-0005Yz-6B for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:54 -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 1rh1sU-0000B6-6E for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:52 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533965; 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=dK5qbWuvGQr8E/pGL1aCZeieC2IGKNRoYzQJak+xQpw=; b=gefMVFDKSJwHnQnoXrtBAeH1lVbI+8IjzsGs0kg/MLymjCIHqrwQacuvyIa+y58JJRg0cp cg1R5eQub89CIiwGwcEv4Ml5N3R8+9GpFxQ9jawvNHBFKcB9R1AT/LBqfdVXNBadeXfCpW wKk9wCKn9RI18d5vqoyotNscTKSZd4I= 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-372-o6GPx_8MP4uxZqXSmoJPCA-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: o6GPx_8MP4uxZqXSmoJPCA-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 32DED1064F7F; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0F17720229A4; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7C28A21E688F; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 06/18] qapi: Clean up "Returns" sections Date: Mon, 4 Mar 2024 07:32:24 +0100 Message-ID: <20240304063236.213955-7-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.4 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Drop list markup, since there's just one item left. Drop "on success" where it is redundant with "Returns:". Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-7-armbru@redhat.com> --- qapi/block-core.json | 4 ++-- qapi/machine.json | 4 ++-- qapi/misc.json | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 94b01deffc..1874f880a8 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -2457,7 +2457,7 @@ # @unstable: This command is meant for debugging. # # Returns: -# - BlockDirtyBitmapSha256 on success +# BlockDirtyBitmapSha256 # # Errors: # - If @node is not a valid block device, DeviceNotFound @@ -6084,7 +6084,7 @@ # @name: optional the snapshot's name to be deleted # # Returns: -# - SnapshotInfo on success +# SnapshotInfo # # Errors: # - If @device is not a valid block device, GenericError diff --git a/qapi/machine.json b/qapi/machine.json index 7d3ca33683..bb5a178909 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1090,7 +1090,7 @@ # Return information about the balloon device. # # Returns: -# - @BalloonInfo on success +# @BalloonInfo # # Errors: # - If the balloon driver is enabled but not functional because @@ -1156,7 +1156,7 @@ # message from the guest. # # Returns: -# - @HvBalloonInfo on success +# @HvBalloonInfo # # Errors: # - If no hv-balloon device is present, guest memory status diff --git a/qapi/misc.json b/qapi/misc.json index 015388aa3e..1b0c5dad88 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -332,7 +332,7 @@ # @opaque: A free-form string that can be used to describe the fd. # # Returns: -# - @AddfdInfo on success +# @AddfdInfo # # Errors: # - If file descriptor was not received, GenericError From patchwork Mon Mar 4 06:32:25 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580113 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 AC6F8C54E4A for ; Mon, 4 Mar 2024 06:36:40 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1tA-0005uN-O2; Mon, 04 Mar 2024 01:33: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 1rh1sY-0005YO-Iz for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:51 -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 1rh1sR-00009x-Li for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:50 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533963; 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=Ck0LmdFKk32Log5qrvwNFTXNJk8f7wC/oQFqmX5XaKA=; b=VA45GRS3KPktAtqaqj4Mv4g4L7w9T3GiL7nTUOrRNXCNZboYidZk+o69WmxKQlkZIKTe7J W74pIuWyhTdWMbvdyRSRvpka+JSrdFFJ4zxtkLdHqXNZA4ijqQq7JomlsROGxoH1Dyb30E /tNuzYb1ASSpI2kUbXlbQM9Pw0C19bA= 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-194-r5JDqiXMMBWYTHcTUuzcew-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: r5JDqiXMMBWYTHcTUuzcew-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 31B34846D56; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0F38B400D6C9; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7EE2721E6891; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 07/18] qapi/yank: Tweak @yank's error description for consistency Date: Mon, 4 Mar 2024 07:32:25 +0100 Message-ID: <20240304063236.213955-8-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Phrase it like "If , ", like we do elsewhere. Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-8-armbru@redhat.com> --- qapi/yank.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/yank.json b/qapi/yank.json index fffb39a397..89f2f4d199 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -79,7 +79,7 @@ # @instances: the instances to be yanked # # Errors: -# - @DeviceNotFound error, if any of the YankInstances doesn't exist +# - If any of the YankInstances doesn't exist, DeviceNotFound # # Example: # From patchwork Mon Mar 4 06:32:26 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580109 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 0F056C48BF6 for ; Mon, 4 Mar 2024 06:34:46 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1t7-0005ij-Ns; Mon, 04 Mar 2024 01:33:25 -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 1rh1sZ-0005YW-V5 for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:53 -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 1rh1sT-0000AE-DM for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:51 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533963; 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=brIXQLgcIaTCqH8Gr/w1n9NP7xEZZJ2uDmD+ytlTOcU=; b=RYc91HUoE3t8Hh0i71+sXqMSv84ilX9OncYfiUf9i+wbmFdTtj5fcjqd0BPQtEuCa/avhn CDXVIzOwRromqnhTEn4LhRop5TRRVSdNxhjLGXepx+X6drkMssK9p1WB6RgaNrt3XFfxM7 iNaRxxy3lkCNH1Z2iYJCirGQs4QMhuI= 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-117-k0Evv4_fO_aHIGgfmAVGqA-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: k0Evv4_fO_aHIGgfmAVGqA-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 339A81064F80; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0F6AE1C06532; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 81AD621E68B2; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 08/18] qga/qapi-schema: Move error documentation to new "Errors" sections Date: Mon, 4 Mar 2024 07:32:26 +0100 Message-ID: <20240304063236.213955-9-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.7 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-9-armbru@redhat.com> --- qga/qapi-schema.json | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index b8efe31897..c5f2ac8f59 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -561,9 +561,8 @@ # could also exit (or set its status to "shutdown") due to other # reasons. # -# The following errors may be returned: -# -# - If suspend to disk is not supported, Unsupported +# Errors: +# - If suspend to disk is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command # before sending commands when the guest resumes @@ -598,9 +597,8 @@ # 2. Issue the query-status QMP command to confirm the VM status is # "suspended" # -# The following errors may be returned: -# -# - If suspend to ram is not supported, Unsupported +# Errors: +# - If suspend to ram is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command # before sending commands when the guest resumes @@ -634,9 +632,8 @@ # 2. Issue the query-status QMP command to confirm the VM status is # "suspended" # -# The following errors may be returned: -# -# - If hybrid suspend is not supported, Unsupported +# Errors: +# - If hybrid suspend is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command # before sending commands when the guest resumes @@ -796,9 +793,6 @@ # - 0: # if the @vcpus list was empty on input. Guest state has not # been changed. Otherwise, -# - Error: -# processing the first node of @vcpus failed for the reason -# returned. Guest state has not been changed. Otherwise, # - < length(@vcpus): # more than zero initial nodes have been processed, but not the # entire @vcpus list. Guest state has changed accordingly. To @@ -808,6 +802,10 @@ # - length(@vcpus): # call successful. # +# Errors: +# - If the reconfiguration of the first node in @vcpus failed. +# Guest state has not been changed. +# # Since: 1.5 ## { 'command': 'guest-set-vcpus', From patchwork Mon Mar 4 06:32:27 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580115 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 3176FC54E4A for ; Mon, 4 Mar 2024 06:37:42 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1ss-0005bt-DG; Mon, 04 Mar 2024 01:33:19 -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 1rh1sW-0005Xv-61 for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:48 -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 1rh1sR-00008D-EE for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533961; 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=pOjnZidORcDEQ/A5DM1wItaLmYEEvB17BaywLPOi69Y=; b=H8wJ+FIAsKwx8OMlXM9SG7NTd/M6aYGrWkQBJ8vY8+lTAmF9XiiIYmNnvzI7Qv62phWgRn u8fISgQjoRtvnmumonQtuaQJqETFBZ7ujOWaaHCeQfg45BMffTRUzSgc5H8ZtUPwFgB1sX wF1yOb1R/0cyFBJIEBi6dMwQxCHnI9g= 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-563-aP4l2THTNtis9Xo6f4YYdQ-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: aP4l2THTNtis9Xo6f4YYdQ-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 32B5F85A589; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0F2521C060B1; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 844F621E68BD; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 09/18] qga/qapi-schema: Delete useless "Returns" sections Date: Mon, 4 Mar 2024 07:32:27 +0100 Message-ID: <20240304063236.213955-10-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.7 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-10-armbru@redhat.com> --- qga/qapi-schema.json | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index c5f2ac8f59..636c2c5697 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -153,8 +153,6 @@ # @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in # UTC. # -# Returns: Nothing on success. -# # Since: 1.5 ## { 'command': 'guest-set-time', @@ -245,8 +243,6 @@ # # @handle: filehandle returned by guest-file-open # -# Returns: Nothing on success. -# # Since: 0.15.0 ## { 'command': 'guest-file-close', @@ -399,8 +395,6 @@ # # @handle: filehandle returned by guest-file-open # -# Returns: Nothing on success. -# # Since: 0.15.0 ## { 'command': 'guest-file-flush', @@ -1077,8 +1071,6 @@ # transmission, even if already crypt()d, to ensure it is 8-bit safe # when passed as JSON. # -# Returns: Nothing on success. -# # Since: 2.3 ## { 'command': 'guest-set-user-password', @@ -1602,8 +1594,6 @@ # # @reset: ignore the existing content, set it with the given keys only # -# Returns: Nothing on success. -# # Since: 5.2 ## { 'command': 'guest-ssh-add-authorized-keys', @@ -1622,8 +1612,6 @@ # @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys # format) # -# Returns: Nothing on success. -# # Since: 5.2 ## { 'command': 'guest-ssh-remove-authorized-keys', From patchwork Mon Mar 4 06:32:28 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580112 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 65454C48BF6 for ; Mon, 4 Mar 2024 06:36:40 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1t6-0005fy-QG; Mon, 04 Mar 2024 01:33:24 -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 1rh1sV-0005XT-Fg for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:47 -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 1rh1sR-000081-8w for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533961; 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=8/FXbU9k4Xbe6CQGPTK1P/C/8UWcPJ+aHRUxwKj2KcM=; b=V/tfhmOgg+IkXDQuGRKW0lXn1ObXt8GDhy0DdqrZmH7TbwSTiAD6tA5STi36653gk06YOY S7+IL6YudpvNaajudqxlH6E0Rh/0VhlIOuSYEwecBMf2Yt4pMHhzh3MTs4lUc3kzxFQG5d D5Rhl7CN3OVMfC318iol53lh2+vJXcM= 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-537-DgFhCSR1PqOKoTJjkUnYdg-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: DgFhCSR1PqOKoTJjkUnYdg-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 3307884AE41; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0F1402022AAC; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 86E1B21E6828; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 10/18] qga/qapi-schema: Clean up "Returns" sections Date: Mon, 4 Mar 2024 07:32:28 +0100 Message-ID: <20240304063236.213955-11-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Drop "on success" where it is redundant with "Returns:". Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-11-armbru@redhat.com> --- qga/qapi-schema.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 636c2c5697..326d324901 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -228,7 +228,7 @@ # # @mode: open mode, as per fopen(), "r" is the default. # -# Returns: Guest file handle on success. +# Returns: Guest file handle # # Since: 0.15.0 ## @@ -277,7 +277,7 @@ # @count: maximum number of bytes to read (default is 4KB, maximum is # 48MB) # -# Returns: @GuestFileRead on success. +# Returns: @GuestFileRead # # Since: 0.15.0 ## @@ -312,7 +312,7 @@ # @count: bytes to write (actual bytes, after base64-decode), default # is all content in buf-b64 buffer after base64 decoding # -# Returns: @GuestFileWrite on success. +# Returns: @GuestFileWrite # # Since: 0.15.0 ## @@ -379,7 +379,7 @@ # # @whence: Symbolic or numeric code for interpreting offset # -# Returns: @GuestFileSeek on success. +# Returns: @GuestFileSeek # # Since: 0.15.0 ## @@ -723,7 +723,7 @@ # # Get list of guest IP addresses, MAC addresses and netmasks. # -# Returns: List of GuestNetworkInterface on success. +# Returns: List of GuestNetworkInterface # # Since: 1.1 ## @@ -1247,7 +1247,7 @@ # # @pid: pid returned from guest-exec # -# Returns: GuestExecStatus on success. +# Returns: GuestExecStatus # # Since: 2.5 ## @@ -1315,7 +1315,7 @@ # @capture-output: bool flag to enable capture of stdout/stderr of # running process. defaults to false. # -# Returns: PID on success. +# Returns: PID # # Since: 2.5 ## @@ -1344,7 +1344,7 @@ # or even present in DNS or some other name service at all. It need # not even be unique on your local network or site, but usually it is. # -# Returns: the host name of the machine on success +# Returns: the host name of the machine # # Since: 2.10 ## From patchwork Mon Mar 4 06:32:29 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580110 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 55F92C48BF6 for ; Mon, 4 Mar 2024 06:34:51 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1t8-0005ku-Fb; Mon, 04 Mar 2024 01:33:26 -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 1rh1sY-0005YM-6g for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:51 -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 1rh1sR-00008T-Js for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:49 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533962; 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=PodDuA9Z2AzM6J1ckpRmgJtCGOPIO57g00FZEAHTzbM=; b=An9/Fv5hIQnUNsRvwNDtBg5QuZfebSXqCavd9vnT+z1r30A0vDRKsOsM4TFGys0kubzacU sWPawHl7y2Tcx9L/uB7Z5Q5hkA9VQ4FADsSKpisehda+Ym3o7oMCTaJxRFJaWX9TvNvWuQ Q0lEGvjCV9uG2TD5fP1+xevOlzCSSn4= 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-194-PPTQw3LLOoGbYssaMvHg0w-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: PPTQw3LLOoGbYssaMvHg0w-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 31836811E79; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0EA5B492BE2; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8989C21E6829; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 11/18] qga/qapi-schema: Tweak documentation of fsfreeze commands Date: Mon, 4 Mar 2024 07:32:29 +0100 Message-ID: <20240304063236.213955-12-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 "Returns:" sections of guest-fsfreeze-freeze and guest-fsfreeze-freeze-list describe both command behavior and success response. Move behavior out, so "Returns:" is only about success response. Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-12-armbru@redhat.com> --- qga/qapi-schema.json | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 326d324901..2ea1022092 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -437,15 +437,16 @@ # command succeeded, you may call @guest-fsfreeze-thaw later to # unfreeze. # +# On error, all filesystems will be thawed. If no filesystems are +# frozen as a result of this call, then @guest-fsfreeze-status will +# remain "thawed" and calling @guest-fsfreeze-thaw is not necessary. +# +# Returns: Number of file systems currently frozen. +# # Note: On Windows, the command is implemented with the help of a # Volume Shadow-copy Service DLL helper. The frozen state is # limited for up to 10 seconds by VSS. # -# Returns: Number of file systems currently frozen. On error, all -# filesystems will be thawed. If no filesystems are frozen as a -# result of this call, then @guest-fsfreeze-status will remain -# "thawed" and calling @guest-fsfreeze-thaw is not necessary. -# # Since: 0.15.0 ## { 'command': 'guest-fsfreeze-freeze', @@ -457,12 +458,13 @@ # Sync and freeze specified guest filesystems. See also # @guest-fsfreeze-freeze. # +# On error, all filesystems will be thawed. +# # @mountpoints: an array of mountpoints of filesystems to be frozen. # If omitted, every mounted filesystem is frozen. Invalid mount # points are ignored. # -# Returns: Number of file systems currently frozen. On error, all -# filesystems will be thawed. +# Returns: Number of file systems currently frozen. # # Since: 2.2 ## From patchwork Mon Mar 4 06:32:30 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580097 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 046A0C54E4A for ; Mon, 4 Mar 2024 06:33:37 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1sg-0005b7-Dv; Mon, 04 Mar 2024 01:32:58 -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 1rh1sY-0005YP-Oh for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:51 -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 1rh1sR-00008C-C9 for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:50 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533961; 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=iHMJul9hE3doCe7D7amA+cRrXJpIV0krVUJKRcjWfrU=; b=Qhm4tr/zA/7AP3YZUPIctMQw+e0Cb0AkjfX5/+ptrPZW9LbiXCBJelN0u4GntbAYwZOb4b mmirmqN9h3oI/N7uwRS5h5t9OhDRDmEXCuOPe+brXhYDsFKyEmME0ZkQvl7e6sDvfpU8VZ ZTdU0Zrmfw38nB0oUn3+KpsYscLUyu4= 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-537-m2ioRJrmNc2glNsqoTymbg-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: m2ioRJrmNc2glNsqoTymbg-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 308261064F7E; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0EEF028D; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8C14021E682A; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 12/18] qga/qapi-schema: Fix guest-set-memory-blocks documentation Date: Mon, 4 Mar 2024 07:32:30 +0100 Message-ID: <20240304063236.213955-13-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Documentation claims the command can "return NULL". "NULL" doesn't exist in JSON. "null" does, but the command returns lists, and null isn't. Correct documentation to "return an empty list". Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-13-armbru@redhat.com> --- qga/qapi-schema.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 2ea1022092..9554b566a7 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -1176,9 +1176,9 @@ # @GuestMemoryBlockResponse, which is corresponding to the input # list. # -# Note: it will return NULL if the @mem-blks list was empty on -# input, or there is an error, and in this case, guest state will -# not be changed. +# Note: it will return an empty list if the @mem-blks list was +# empty on input, or there is an error, and in this case, guest +# state will not be changed. # # Since: 2.3 ## From patchwork Mon Mar 4 06:32:31 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580106 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 7602DC48BF6 for ; Mon, 4 Mar 2024 06:34:34 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1tD-00063U-2p; Mon, 04 Mar 2024 01:33: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 1rh1sX-0005YI-FY for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:50 -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 1rh1sR-00008H-IA for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:49 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533961; 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=C0RuL1Qwg1qvrtn12kstdflDO5kngKZEh/ycmJgdVY8=; b=Oku7QvXX1MPUERxRuaqN2Ukxo7vb//vfJCr8satFbi3nmzlTP7CqqSnZDNe6Rn4D/3gxlR 0LYdKFWig7WawmyjGRuJd4cKyt86YfDfOXpqHVlNY6tpR58ZbKZzUJP9+E2HXUz6GL1Tfq 2JXIlAW9WdrTSikn79MQIPpb4VdUwSs= 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-563-VC7O7hY4NJq8ka1iJw6uaA-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: VC7O7hY4NJq8ka1iJw6uaA-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 6BFC23816447; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 4899640C6EBA; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8EB5121E682B; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org Subject: [PULL 13/18] qapi: Reject "Returns" section when command doesn't return anything Date: Mon, 4 Mar 2024 07:32:31 +0100 Message-ID: <20240304063236.213955-14-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 Signed-off-by: Markus Armbruster Message-ID: <20240227113921.236097-14-armbru@redhat.com> --- scripts/qapi/parser.py | 7 ++++++- tests/qapi-schema/doc-invalid-return2.err | 1 + tests/qapi-schema/doc-invalid-return2.json | 7 +++++++ tests/qapi-schema/doc-invalid-return2.out | 0 tests/qapi-schema/meson.build | 1 + 5 files changed, 15 insertions(+), 1 deletion(-) create mode 100644 tests/qapi-schema/doc-invalid-return2.err create mode 100644 tests/qapi-schema/doc-invalid-return2.json create mode 100644 tests/qapi-schema/doc-invalid-return2.out diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index a32b2c7e7f..d8f76060b8 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -721,7 +721,12 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: self.features[feature.name].connect(feature) def check_expr(self, expr: QAPIExpression) -> None: - if 'command' not in expr: + if 'command' in expr: + if self.returns and 'returns' not in expr: + raise QAPISemError( + self.returns.info, + "'Returns' section, but command doesn't return anything") + else: if self.returns: raise QAPISemError( self.returns.info, diff --git a/tests/qapi-schema/doc-invalid-return2.err b/tests/qapi-schema/doc-invalid-return2.err new file mode 100644 index 0000000000..c3d0c7a452 --- /dev/null +++ b/tests/qapi-schema/doc-invalid-return2.err @@ -0,0 +1 @@ +doc-invalid-return2.json:5: 'Returns' section, but command doesn't return anything diff --git a/tests/qapi-schema/doc-invalid-return2.json b/tests/qapi-schema/doc-invalid-return2.json new file mode 100644 index 0000000000..37883d4fea --- /dev/null +++ b/tests/qapi-schema/doc-invalid-return2.json @@ -0,0 +1,7 @@ +# Command doesn't return anything + +## +# @foo: +# Returns: blah +## +{ 'command': 'foo' } diff --git a/tests/qapi-schema/doc-invalid-return2.out b/tests/qapi-schema/doc-invalid-return2.out new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 4b8329d070..0f479d9317 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -79,6 +79,7 @@ schemas = [ 'doc-invalid-end.json', 'doc-invalid-end2.json', 'doc-invalid-return.json', + 'doc-invalid-return2.json', 'doc-invalid-section.json', 'doc-invalid-start.json', 'doc-missing-colon.json', From patchwork Mon Mar 4 06:32:32 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580102 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 936F1C48BF6 for ; Mon, 4 Mar 2024 06:33:57 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1so-0005bh-8S; Mon, 04 Mar 2024 01:33:08 -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 1rh1sa-0005Yw-Nb for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:54 -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 1rh1sS-0000A2-OM for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:52 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533963; 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=KLlsNUKUtVhfU2Q7o2WN82R+wfW9DYiKnsyqY8ZASrY=; b=hY2b0KrhTMBvmKP3tJ3ITggQpL4wCUXsC+eVq+6TpP34lBhKapiCMgmqbJhtegSXPZgJBY gHY2MFk88F4V7EVwrtgBfODTwpoCqn12KZtrvs/zzd1+iKTG3TkcCc76gZbFhwiBauHq+M 0jtmS3ia4+J/778J9ddhLKNFc9QZwi4= 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-266-jquXoRyXPbijFKxcWR45Jw-1; Mon, 04 Mar 2024 01:32:39 -0500 X-MC-Unique: jquXoRyXPbijFKxcWR45Jw-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (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 A66EB3816441; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 48996C04325; Mon, 4 Mar 2024 06:32:39 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 91C4221E682C; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, Eric Blake Subject: [PULL 14/18] docs/devel/writing-monitor-commands: Repair a decade of rot Date: Mon, 4 Mar 2024 07:32:32 +0100 Message-ID: <20240304063236.213955-15-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.8 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 tutorial doesn't match reality since at least 2013. Repairing it involves fixing the following issues: * Update for commit 6d327171551 (aio / timers: Remove alarm timers): replace the broken examples. Instead of having one for returning a struct and another for returning a list of structs, do just one for the latter. This resolves the FIXME added in commit e218052f928 (aio / timers: De-document -clock) back in 2014. * Update for commit 895a2a80e0e (qapi: Use 'struct' instead of 'type' in schema). * Update for commit 3313b6124b5 (qapi: add qapi2texi script): add required documentation to the schema snippets, and drop section "Command Documentation". * Update for commit a3c45b3e629 (qapi: New special feature flag "unstable"): supply the required feature, deemphasize the x- prefix. * Update for commit dd98234c059 (qapi: introduce x-query-roms QMP command): rephrase from "add new command" to "examine existing command". * Update for commit 9492718b7c0 (qapi misc: Elide redundant has_FOO in generated C): hello-world's message argument no longer comes with a has_message, add a second argument that does. * Update for moved and renamed files. While there, update QMP version output to current output. Signed-off-by: Markus Armbruster Message-ID: <20240227115617.237875-2-armbru@redhat.com> Reviewed-by: Eric Blake [Whitespace tidied up, typo fixed] --- docs/devel/writing-monitor-commands.rst | 466 ++++++++++-------------- 1 file changed, 184 insertions(+), 282 deletions(-) diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index b6ee4fa063..cd57f46082 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -66,12 +66,13 @@ Then, in a different terminal:: "version": { "qemu": { "micro": 50, - "minor": 15, - "major": 0 + "minor": 2, + "major": 8 }, - "package": "" + "package": ... }, "capabilities": [ + "oob" ] } } @@ -107,6 +108,11 @@ The first step is defining the command in the appropriate QAPI schema module. We pick module qapi/misc.json, and add the following line at the bottom:: + ## + # @hello-world: + # + # Since: 9.0 + ## { 'command': 'hello-world' } The "command" keyword defines a new QMP command. It's an JSON object. All @@ -148,37 +154,50 @@ you don't see it then something went wrong. Arguments ~~~~~~~~~ -Let's add an argument called "message" to our "hello-world" command. The new -argument will contain the string to be printed to stdout. It's an optional -argument, if it's not present we print our default "Hello, World" string. +Let's add arguments to our "hello-world" command. The first change we have to do is to modify the command specification in the schema file to the following:: - { 'command': 'hello-world', 'data': { '*message': 'str' } } + ## + # @hello-world: + # + # @message: message to be printed (default: "Hello, world!") + # + # @times: how many times to print the message (default: 1) + # + # Since: 9.0 + ## + { 'command': 'hello-world', + 'data': { '*message': 'str', '*times': 'int' } } -Notice the new 'data' member in the schema. It's an JSON object whose each -element is an argument to the command in question. Also notice the asterisk, -it's used to mark the argument optional (that means that you shouldn't use it -for mandatory arguments). Finally, 'str' is the argument's type, which -stands for "string". The QAPI also supports integers, booleans, enumerations -and user defined types. +Notice the new 'data' member in the schema. It specifies an argument +'message' of QAPI type 'str', and an argument 'times' of QAPI type +'int'. Also notice the asterisk, it's used to mark the argument +optional. Now, let's update our C implementation in monitor/qmp-cmds.c:: - void qmp_hello_world(const char *message, Error **errp) + void qmp_hello_world(const char *message, bool has_times, int64_t times, + Error **errp) { - if (message) { + if (!message) { + message = "Hello, world"; + } + if (!has_times) { + times = 1; + } + + for (int i = 0; i < times; i++) { printf("%s\n", message); - } else { - printf("Hello, world\n"); } } There are two important details to be noticed: -1. All optional arguments are accompanied by a 'has\_' boolean, which is set - if the optional argument is present or false otherwise +1. Optional arguments other than pointers are accompanied by a 'has\_' + boolean, which is set if the optional argument is present or false + otherwise 2. The C implementation signature must follow the schema's argument ordering, which is defined by the "data" member @@ -254,35 +273,6 @@ If the failure you want to report falls into one of the two cases above, use error_set() with a second argument of an ErrorClass value. -Command Documentation -~~~~~~~~~~~~~~~~~~~~~ - -There's only one step missing to make "hello-world"'s implementation complete, -and that's its documentation in the schema file. - -There are many examples of such documentation in the schema file already, but -here goes "hello-world"'s new entry for qapi/misc.json:: - - ## - # @hello-world: - # - # Print a client provided string to the standard output stream. - # - # @message: string to be printed - # - # Returns: Nothing on success. - # - # Notes: if @message is not provided, the "Hello, world" string will - # be printed instead - # - # Since: - ## - { 'command': 'hello-world', 'data': { '*message': 'str' } } - -Please, note that the "Returns" clause is optional if a command doesn't return -any data nor any errors. - - Implementing the HMP command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -306,18 +296,20 @@ Here's the implementation of the "hello-world" HMP command:: } } -Also, you have to add the function's prototype to the hmp.h file. +Add it to monitor/hmp-cmds.c. Also, add its prototype to +include/monitor/hmp.h. -There are three important points to be noticed: +There are four important points to be noticed: 1. The "mon" and "qdict" arguments are mandatory for all HMP functions. The former is the monitor object. The latter is how the monitor passes arguments entered by the user to the command implementation -2. hmp_hello_world() performs error checking. In this example we just call +2. We chose not to support the "times" argument in HMP +3. hmp_hello_world() performs error checking. In this example we just call hmp_handle_error() which prints a message to the user, but we could do more, like taking different actions depending on the error qmp_hello_world() returns -3. The "err" variable must be initialized to NULL before performing the +4. The "err" variable must be initialized to NULL before performing the QMP call There's one last step to actually make the command available to monitor users, @@ -372,7 +364,7 @@ data, it is not expected that machines will need to parse the result. The overhead of defining a fine grained QAPI type for the data may not be justified by the potential benefit. In such cases, it is permitted to have a command return a simple string that contains formatted data, -however, it is mandatory for the command to use the 'x-' name prefix. +however, it is mandatory for the command to be marked unstable. This indicates that the command is not guaranteed to be long term stable / liable to change in future and is not following QAPI design best practices. An example where this approach is taken is the QMP @@ -386,302 +378,207 @@ an illustration. User Defined Types ~~~~~~~~~~~~~~~~~~ -FIXME This example needs to be redone after commit 6d32717 +For this example we will write the query-option-roms command, which +returns information about ROMs loaded into the option ROM space. For +more information about it, please check the "-option-rom" command-line +option. -For this example we will write the query-alarm-clock command, which returns -information about QEMU's timer alarm. For more information about it, please -check the "-clock" command-line option. - -We want to return two pieces of information. The first one is the alarm clock's -name. The second one is when the next alarm will fire. The former information is -returned as a string, the latter is an integer in nanoseconds (which is not -very useful in practice, as the timer has probably already fired when the -information reaches the client). - -The best way to return that data is to create a new QAPI type, as shown below:: +For each option ROM, we want to return two pieces of information: the +ROM image's file name, and its bootindex, if any. We need to create a +new QAPI type for that, as shown below:: ## - # @QemuAlarmClock + # @OptionRomInfo: # - # QEMU alarm clock information. + # @filename: option ROM image file name # - # @clock-name: The alarm clock method's name. + # @bootindex: option ROM's bootindex # - # @next-deadline: The time (in nanoseconds) the next alarm will fire. - # - # Since: 1.0 + # Since: 9.0 ## - { 'type': 'QemuAlarmClock', - 'data': { 'clock-name': 'str', '*next-deadline': 'int' } } + { 'struct': 'OptionRomInfo', + 'data': { 'filename': 'str', '*bootindex': 'int' } } -The "type" keyword defines a new QAPI type. Its "data" member contains the -type's members. In this example our members are the "clock-name" and the -"next-deadline" one, which is optional. +The "struct" keyword defines a new QAPI type. Its "data" member +contains the type's members. In this example our members are +"filename" and "bootindex". The latter is optional. -Now let's define the query-alarm-clock command:: +Now let's define the query-option-roms command:: ## - # @query-alarm-clock + # @query-option-roms: # - # Return information about QEMU's alarm clock. + # Query information on ROMs loaded into the option ROM space. # - # Returns a @QemuAlarmClock instance describing the alarm clock method - # being currently used by QEMU (this is usually set by the '-clock' - # command-line option). + # Returns: OptionRomInfo # - # Since: 1.0 + # Since: 9.0 ## - { 'command': 'query-alarm-clock', 'returns': 'QemuAlarmClock' } + { 'command': 'query-option-roms', + 'returns': ['OptionRomInfo'] } Notice the "returns" keyword. As its name suggests, it's used to define the data returned by a command. -It's time to implement the qmp_query_alarm_clock() function, you can put it -in the qemu-timer.c file:: +Notice the syntax ['OptionRomInfo']". This should be read as "returns +a list of OptionRomInfo". - QemuAlarmClock *qmp_query_alarm_clock(Error **errp) +It's time to implement the qmp_query_option_roms() function. Add to +monitor/qmp-cmds.c:: + + OptionRomInfoList *qmp_query_option_roms(Error **errp) { - QemuAlarmClock *clock; - int64_t deadline; + OptionRomInfoList *info_list = NULL; + OptionRomInfoList **tailp = &info_list; + OptionRomInfo *info; - clock = g_malloc0(sizeof(*clock)); - - deadline = qemu_next_alarm_deadline(); - if (deadline > 0) { - clock->has_next_deadline = true; - clock->next_deadline = deadline; + for (int i = 0; i < nb_option_roms; i++) { + info = g_malloc0(sizeof(*info)); + info->filename = g_strdup(option_rom[i].name); + info->has_bootindex = option_rom[i].bootindex >= 0; + if (info->has_bootindex) { + info->bootindex = option_rom[i].bootindex; + } + QAPI_LIST_APPEND(tailp, info); } - clock->clock_name = g_strdup(alarm_timer->name); - return clock; + return info_list; } There are a number of things to be noticed: -1. The QemuAlarmClock type is automatically generated by the QAPI framework, - its members correspond to the type's specification in the schema file -2. As specified in the schema file, the function returns a QemuAlarmClock - instance and takes no arguments (besides the "errp" one, which is mandatory - for all QMP functions) -3. The "clock" variable (which will point to our QAPI type instance) is - allocated by the regular g_malloc0() function. Note that we chose to - initialize the memory to zero. This is recommended for all QAPI types, as - it helps avoiding bad surprises (specially with booleans) -4. Remember that "next_deadline" is optional? Non-pointer optional - members have a 'has_TYPE_NAME' member that should be properly set +1. Type OptionRomInfo is automatically generated by the QAPI framework, + its members correspond to the type's specification in the schema + file +2. Type OptionRomInfoList is also generated. It's a singly linked + list. +3. As specified in the schema file, the function returns a + OptionRomInfoList, and takes no arguments (besides the "errp" one, + which is mandatory for all QMP functions) +4. The returned object is dynamically allocated +5. All strings are dynamically allocated. This is so because QAPI also + generates a function to free its types and it cannot distinguish + between dynamically or statically allocated strings +6. Remember that "bootindex" is optional? As a non-pointer optional + member, it comes with a 'has_bootindex' member that needs to be set by the implementation, as shown above -5. Even static strings, such as "alarm_timer->name", should be dynamically - allocated by the implementation. This is so because the QAPI also generates - a function to free its types and it cannot distinguish between dynamically - or statically allocated strings -6. You have to include "qapi/qapi-commands-misc.h" in qemu-timer.c Time to test the new command. Build qemu, run it as described in the "Testing" section and try this:: - { "execute": "query-alarm-clock" } + { "execute": "query-option-rom" } { - "return": { - "next-deadline": 2368219, - "clock-name": "dynticks" - } + "return": [ + { + "filename": "kvmvapic.bin" + } + ] } The HMP command ~~~~~~~~~~~~~~~ -Here's the HMP counterpart of the query-alarm-clock command:: +Here's the HMP counterpart of the query-option-roms command:: - void hmp_info_alarm_clock(Monitor *mon) + void hmp_info_option_roms(Monitor *mon, const QDict *qdict) { - QemuAlarmClock *clock; Error *err = NULL; + OptionRomInfoList *info_list, *tail; + OptionRomInfo *info; - clock = qmp_query_alarm_clock(&err); + info_list = qmp_query_option_roms(&err); if (hmp_handle_error(mon, err)) { return; } - monitor_printf(mon, "Alarm clock method in use: '%s'\n", clock->clock_name); - if (clock->has_next_deadline) { - monitor_printf(mon, "Next alarm will fire in %" PRId64 " nanoseconds\n", - clock->next_deadline); - } - - qapi_free_QemuAlarmClock(clock); - } - -It's important to notice that hmp_info_alarm_clock() calls -qapi_free_QemuAlarmClock() to free the data returned by qmp_query_alarm_clock(). -For user defined types, the QAPI will generate a qapi_free_QAPI_TYPE_NAME() -function and that's what you have to use to free the types you define and -qapi_free_QAPI_TYPE_NAMEList() for list types (explained in the next section). -If the QMP call returns a string, then you should g_free() to free it. - -Also note that hmp_info_alarm_clock() performs error handling. That's not -strictly required if you're sure the QMP function doesn't return errors, but -it's good practice to always check for errors. - -Another important detail is that HMP's "info" commands don't go into the -hmp-commands.hx. Instead, they go into the info_cmds[] table, which is defined -in the monitor/misc.c file. The entry for the "info alarmclock" follows:: - - { - .name = "alarmclock", - .args_type = "", - .params = "", - .help = "show information about the alarm clock", - .cmd = hmp_info_alarm_clock, - }, - -To test this, run qemu and type "info alarmclock" in the user monitor. - - -Returning Lists -~~~~~~~~~~~~~~~ - -For this example, we're going to return all available methods for the timer -alarm, which is pretty much what the command-line option "-clock ?" does, -except that we're also going to inform which method is in use. - -This first step is to define a new type:: - - ## - # @TimerAlarmMethod - # - # Timer alarm method information. - # - # @method-name: The method's name. - # - # @current: true if this alarm method is currently in use, false otherwise - # - # Since: 1.0 - ## - { 'type': 'TimerAlarmMethod', - 'data': { 'method-name': 'str', 'current': 'bool' } } - -The command will be called "query-alarm-methods", here is its schema -specification:: - - ## - # @query-alarm-methods - # - # Returns information about available alarm methods. - # - # Returns: a list of @TimerAlarmMethod for each method - # - # Since: 1.0 - ## - { 'command': 'query-alarm-methods', 'returns': ['TimerAlarmMethod'] } - -Notice the syntax for returning lists "'returns': ['TimerAlarmMethod']", this -should be read as "returns a list of TimerAlarmMethod instances". - -The C implementation follows:: - - TimerAlarmMethodList *qmp_query_alarm_methods(Error **errp) - { - TimerAlarmMethodList *method_list = NULL; - const struct qemu_alarm_timer *p; - bool current = true; - - for (p = alarm_timers; p->name; p++) { - TimerAlarmMethod *value = g_malloc0(*value); - value->method_name = g_strdup(p->name); - value->current = current; - QAPI_LIST_PREPEND(method_list, value); - current = false; - } - - return method_list; - } - -The most important difference from the previous examples is the -TimerAlarmMethodList type, which is automatically generated by the QAPI from -the TimerAlarmMethod type. - -Each list node is represented by a TimerAlarmMethodList instance. We have to -allocate it, and that's done inside the for loop: the "info" pointer points to -an allocated node. We also have to allocate the node's contents, which is -stored in its "value" member. In our example, the "value" member is a pointer -to an TimerAlarmMethod instance. - -Notice that the "current" variable is used as "true" only in the first -iteration of the loop. That's because the alarm timer method in use is the -first element of the alarm_timers array. Also notice that QAPI lists are handled -by hand and we return the head of the list. - -Now Build qemu, run it as explained in the "Testing" section and try our new -command:: - - { "execute": "query-alarm-methods" } - { - "return": [ - { - "current": false, - "method-name": "unix" - }, - { - "current": true, - "method-name": "dynticks" + for (tail = info_list; tail; tail = tail->next) { + info = tail->value; + monitor_printf(mon, "%s", info->filename); + if (info->has_bootindex) { + monitor_printf(mon, " %" PRId64, info->bootindex); } - ] - } - -The HMP counterpart is a bit more complex than previous examples because it -has to traverse the list, it's shown below for reference:: - - void hmp_info_alarm_methods(Monitor *mon) - { - TimerAlarmMethodList *method_list, *method; - Error *err = NULL; - - method_list = qmp_query_alarm_methods(&err); - if (hmp_handle_error(mon, err)) { - return; + monitor_printf(mon, "\n"); } - for (method = method_list; method; method = method->next) { - monitor_printf(mon, "%c %s\n", method->value->current ? '*' : ' ', - method->value->method_name); - } - - qapi_free_TimerAlarmMethodList(method_list); + qapi_free_OptionRomInfoList(info_list); } +It's important to notice that hmp_info_option_roms() calls +qapi_free_OptionRomInfoList() to free the data returned by +qmp_query_option_roms(). For user defined types, QAPI will generate a +qapi_free_QAPI_TYPE_NAME() function, and that's what you have to use to +free the types you define and qapi_free_QAPI_TYPE_NAMEList() for list +types (explained in the next section). If the QMP function returns a +string, then you should g_free() to free it. + +Also note that hmp_info_option_roms() performs error handling. That's +not strictly required when you're sure the QMP function doesn't return +errors; you could instead pass it &error_abort then. + +Another important detail is that HMP's "info" commands go into +hmp-commands-info.hx, not hmp-commands.hx. The entry for the "info +option-roms" follows:: + + { + .name = "option-roms", + .args_type = "", + .params = "", + .help = "show roms", + .cmd = hmp_info_option_roms, + }, + SRST + ``info option-roms`` + Show the option ROMs. + ERST + +To test this, run qemu and type "info option-roms" in the user monitor. + + Writing a debugging aid returning unstructured text --------------------------------------------------- As discussed in section `Modelling data in QAPI`_, it is required that commands expecting machine usage be using fine-grained QAPI data types. The exception to this rule applies when the command is solely intended -as a debugging aid and allows for returning unstructured text. This is -commonly needed for query commands that report aspects of QEMU's -internal state that are useful to human operators. +as a debugging aid and allows for returning unstructured text, such as +a query command that report aspects of QEMU's internal state that are +useful only to human operators. -In this example we will consider a simplified variant of the HMP -command ``info roms``. Following the earlier rules, this command will -need to live under the ``x-`` name prefix, so its QMP implementation -will be called ``x-query-roms``. It will have no parameters and will -return a single text string:: - - { 'struct': 'HumanReadableText', - 'data': { 'human-readable-text': 'str' } } +In this example we will consider the existing QMP command +``x-query-roms`` in qapi/machine.json. It has no parameters and +returns a ``HumanReadableText``:: + ## + # @x-query-roms: + # + # Query information on the registered ROMS + # + # Features: + # + # @unstable: This command is meant for debugging. + # + # Returns: registered ROMs + # + # Since: 6.2 + ## { 'command': 'x-query-roms', - 'returns': 'HumanReadableText' } + 'returns': 'HumanReadableText', + 'features': [ 'unstable' ] } -The ``HumanReadableText`` struct is intended to be used for all -commands, under the ``x-`` name prefix that are returning unstructured -text targeted at humans. It should never be used for commands outside -the ``x-`` name prefix, as those should be using structured QAPI types. +The ``HumanReadableText`` struct is defined in qapi/common.json as a +struct with a string member. It is intended to be used for all +commands that are returning unstructured text targeted at +humans. These should all have feature 'unstable'. Note that the +feature's documentation states why the command is unstable. We +commonly use a ``x-`` command name prefix to make lack of stability +obvious to human users. Implementing the QMP command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The QMP implementation will typically involve creating a ``GString`` -object and printing formatted data into it:: +object and printing formatted data into it, like this:: HumanReadableText *qmp_x_query_roms(Error **errp) { @@ -698,6 +595,9 @@ object and printing formatted data into it:: return human_readable_text_from_str(buf); } +The actual implementation emits more information. You can find it in +hw/core/loader.c. + Implementing the HMP command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -706,7 +606,7 @@ Now that the QMP command is in place, we can also make it available in the human monitor (HMP) as shown in previous examples. The HMP implementations will all look fairly similar, as all they need do is invoke the QMP command and then print the resulting text or error -message. Here's the implementation of the "info roms" HMP command:: +message. Here's an implementation of the "info roms" HMP command:: void hmp_info_roms(Monitor *mon, const QDict *qdict) { @@ -746,3 +646,5 @@ field NULL:: .help = "show roms", .cmd_info_hrt = qmp_x_query_roms, }, + +This is how the actual HMP command is done. From patchwork Mon Mar 4 06:32:33 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580111 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 D2C9DC54E49 for ; Mon, 4 Mar 2024 06:34:59 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1tA-0005v6-Sz; Mon, 04 Mar 2024 01:33: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 1rh1sd-0005aT-Rr for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:56 -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 1rh1sR-00009K-DD for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:55 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533962; 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=1k05FKtNN7IYC6F5eocShFpTw77V9Va5LeseCiYOTB8=; b=Nh2kiWl0hV4BT94U3PCKqspMgC4vHq9MXXqyQudZWEW4YRXgUy55TmujIYzOCxJa2jAQM9 mv8MKhC69XA5YPEvK2aZm3B8sKok5KAHpmmXm7y/LHXVePajsAtQYwfjpLKWG3/W39QmT9 /6ZFqDGqV9phswqi+SMPk9Kht8sgHgI= 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-418-d5ZDgEysO4eIm5UnCBz9ug-1; Mon, 04 Mar 2024 01:32:40 -0500 X-MC-Unique: d5ZDgEysO4eIm5UnCBz9ug-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (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 9FFE21C0BB41; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5E1A6C04323; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9477821E682D; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, Eric Blake Subject: [PULL 15/18] docs/devel/writing-monitor-commands: Minor improvements Date: Mon, 4 Mar 2024 07:32:33 +0100 Message-ID: <20240304063236.213955-16-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.8 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, 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 Avoid "JSON" when talking about the QAPI schema syntax. Capitalize QEMU. Don't claim all HMP commands live in monitor/hmp-cmds.c (this was never true). Fix punctuation and drop inappropriate "the" here and there. Signed-off-by: Markus Armbruster Message-ID: <20240227115617.237875-3-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/devel/writing-monitor-commands.rst | 32 ++++++++++++------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index cd57f46082..930da5cd06 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -115,8 +115,7 @@ the bottom:: ## { 'command': 'hello-world' } -The "command" keyword defines a new QMP command. It's an JSON object. All -schema entries are JSON objects. The line above will instruct the QAPI to +The "command" keyword defines a new QMP command. It instructs QAPI to generate any prototypes and the necessary code to marshal and unmarshal protocol data. @@ -138,16 +137,16 @@ There are a few things to be noticed: 3. It takes an "Error \*\*" argument. This is required. Later we will see how to return errors and take additional arguments. The Error argument should not be touched if the command doesn't return errors -4. We won't add the function's prototype. That's automatically done by the QAPI +4. We won't add the function's prototype. That's automatically done by QAPI 5. Printing to the terminal is discouraged for QMP commands, we do it here because it's the easiest way to demonstrate a QMP command -You're done. Now build qemu, run it as suggested in the "Testing" section, +You're done. Now build QEMU, run it as suggested in the "Testing" section, and then type the following QMP command:: { "execute": "hello-world" } -Then check the terminal running qemu and look for the "Hello, world" string. If +Then check the terminal running QEMU and look for the "Hello, world" string. If you don't see it then something went wrong. @@ -201,7 +200,7 @@ There are two important details to be noticed: 2. The C implementation signature must follow the schema's argument ordering, which is defined by the "data" member -Time to test our new version of the "hello-world" command. Build qemu, run it as +Time to test our new version of the "hello-world" command. Build QEMU, run it as described in the "Testing" section and then send two commands:: { "execute": "hello-world" } @@ -210,13 +209,13 @@ described in the "Testing" section and then send two commands:: } } - { "execute": "hello-world", "arguments": { "message": "We love qemu" } } + { "execute": "hello-world", "arguments": { "message": "We love QEMU" } } { "return": { } } -You should see "Hello, world" and "We love qemu" in the terminal running qemu, +You should see "Hello, world" and "We love QEMU" in the terminal running QEMU, if you don't see these strings, then something went wrong. @@ -246,7 +245,7 @@ The first argument to the error_setg() function is the Error pointer to pointer, which is passed to all QMP functions. The next argument is a human description of the error, this is a free-form printf-like string. -Let's test the example above. Build qemu, run it as defined in the "Testing" +Let's test the example above. Build QEMU, run it as defined in the "Testing" section, and then issue the following command:: { "execute": "hello-world", "arguments": { "message": "all you need is love" } } @@ -279,9 +278,8 @@ Implementing the HMP command Now that the QMP command is in place, we can also make it available in the human monitor (HMP). -With the introduction of the QAPI, HMP commands make QMP calls. Most of the -time HMP commands are simple wrappers. All HMP commands implementation exist in -the monitor/hmp-cmds.c file. +With the introduction of QAPI, HMP commands make QMP calls. Most of the +time HMP commands are simple wrappers. Here's the implementation of the "hello-world" HMP command:: @@ -332,17 +330,17 @@ To test this you have to open a user monitor and issue the "hello-world" command. It might be instructive to check the command's documentation with HMP's "help" command. -Please, check the "-monitor" command-line option to know how to open a user +Please check the "-monitor" command-line option to know how to open a user monitor. Writing more complex commands ----------------------------- -A QMP command is capable of returning any data the QAPI supports like integers, +A QMP command is capable of returning any data QAPI supports like integers, strings, booleans, enumerations and user defined types. -In this section we will focus on user defined types. Please, check the QAPI +In this section we will focus on user defined types. Please check the QAPI documentation for information about the other types. @@ -463,7 +461,7 @@ There are a number of things to be noticed: member, it comes with a 'has_bootindex' member that needs to be set by the implementation, as shown above -Time to test the new command. Build qemu, run it as described in the "Testing" +Time to test the new command. Build QEMU, run it as described in the "Testing" section and try this:: { "execute": "query-option-rom" } @@ -532,7 +530,7 @@ option-roms" follows:: Show the option ROMs. ERST -To test this, run qemu and type "info option-roms" in the user monitor. +To test this, run QEMU and type "info option-roms" in the user monitor. Writing a debugging aid returning unstructured text From patchwork Mon Mar 4 06:32:34 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580098 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 004EBC48BF6 for ; Mon, 4 Mar 2024 06:33:37 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1so-0005bf-9O; Mon, 04 Mar 2024 01:33:08 -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 1rh1sa-0005Yx-Pc for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:54 -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 1rh1sU-0000B4-3Z for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:52 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533964; 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=M/xa+Ja4m0amupOF5TNMa9MFmkvy7veRUAgONKvmo9o=; b=a4oJIMXnQQE1DXzBLtPVj52EcnpInmbGkFKuSRmL0iBKHt2U+LoUV8J3eVBGUxHt5NqLZS YIIV2E905yaMpxmd8aFy4WIPAur3alTZRaGRzAwrpzKPamVaG2RDnIvlbQgPh/aMKgbA/Q tVc/a/hx53xqYnqZWL7Zx6R4qYLfrlE= 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-515-FMExj83TN-GtwDCVqJvM3A-1; Mon, 04 Mar 2024 01:32:40 -0500 X-MC-Unique: FMExj83TN-GtwDCVqJvM3A-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 82448185A784; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5C93A1C060AF; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9767D21E682E; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, Steve Sistare , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PULL 16/18] qapi: New QAPI_LIST_LENGTH() Date: Mon, 4 Mar 2024 07:32:34 +0100 Message-ID: <20240304063236.213955-17-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-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.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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: Steve Sistare Signed-off-by: Steve Sistare Reviewed-by: Marc-André Lureau Message-ID: <20240227153321.467343-2-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Markus Armbruster --- include/qapi/util.h | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/include/qapi/util.h b/include/qapi/util.h index 81a2b13a33..20dfea8a54 100644 --- a/include/qapi/util.h +++ b/include/qapi/util.h @@ -56,4 +56,17 @@ int parse_qapi_name(const char *name, bool complete); (tail) = &(*(tail))->next; \ } while (0) +/* + * For any GenericList @list, return its length. + */ +#define QAPI_LIST_LENGTH(list) \ + ({ \ + size_t _len = 0; \ + typeof(list) _tail; \ + for (_tail = list; _tail != NULL; _tail = _tail->next) { \ + _len++; \ + } \ + _len; \ + }) + #endif From patchwork Mon Mar 4 06:32:35 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580108 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 32856C48BF6 for ; Mon, 4 Mar 2024 06:34:41 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1t5-0005fJ-W9; Mon, 04 Mar 2024 01:33:24 -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 1rh1sa-0005Yv-H1 for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:54 -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 1rh1sS-0000AR-Q4 for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:52 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533964; 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=GkHnyanmJD/zvCJB2FWxZfzd7bqqUwhsCWjtX09AOzI=; b=cSJQw+wjBFXwWmxWT5LmeQ35yor26HDg4OfVITBCeg7lVwqxHTWXlJ7EYM94WBVCgeWVmK 87qHxgz93DdxwfhbTpMe6pgoOQdyqNjB17HQBpP0X1FJoGFIn/Xd5+0ozXMqFYm/xLr1fp Km25JUV+SgJXRcuIoUXRUGLG0vOaqBc= 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-50-BuNm6Jm0NoSF5BmgHtPZUw-1; Mon, 04 Mar 2024 01:32:40 -0500 X-MC-Unique: BuNm6Jm0NoSF5BmgHtPZUw-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 812C185A589; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5C786492BC7; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9A95121E683A; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, Steve Sistare , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PULL 17/18] qapi: New strv_from_str_list() Date: Mon, 4 Mar 2024 07:32:35 +0100 Message-ID: <20240304063236.213955-18-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-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.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 From: Steve Sistare Signed-off-by: Steve Sistare Reviewed-by: Marc-André Lureau Message-ID: <20240227153321.467343-3-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Markus Armbruster --- include/qapi/type-helpers.h | 8 ++++++++ qapi/qapi-type-helpers.c | 14 ++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/include/qapi/type-helpers.h b/include/qapi/type-helpers.h index be1f181526..fc8352cdec 100644 --- a/include/qapi/type-helpers.h +++ b/include/qapi/type-helpers.h @@ -12,3 +12,11 @@ #include "qapi/qapi-types-common.h" HumanReadableText *human_readable_text_from_str(GString *str); + +/* + * Produce and return a NULL-terminated array of strings from @list. + * The result is g_malloc()'d and all strings are g_strdup()'d. It + * can be freed with g_strfreev(), or by g_auto(GStrv) automatic + * cleanup. + */ +char **strv_from_str_list(const strList *list); diff --git a/qapi/qapi-type-helpers.c b/qapi/qapi-type-helpers.c index f76b34f647..266da013ad 100644 --- a/qapi/qapi-type-helpers.c +++ b/qapi/qapi-type-helpers.c @@ -21,3 +21,17 @@ HumanReadableText *human_readable_text_from_str(GString *str) return ret; } + +char **strv_from_str_list(const strList *list) +{ + const strList *tail; + int i = 0; + char **strv = g_new(char *, QAPI_LIST_LENGTH(list) + 1); + + for (tail = list; tail != NULL; tail = tail->next) { + strv[i++] = g_strdup(tail->value); + } + strv[i] = NULL; + + return strv; +} From patchwork Mon Mar 4 06:32:36 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13580104 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 06FEAC54E49 for ; Mon, 4 Mar 2024 06:34:13 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rh1tE-00066O-7U; Mon, 04 Mar 2024 01:33: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 1rh1sc-0005Zp-AI for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:54 -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 1rh1sV-0000Bi-4W for qemu-devel@nongnu.org; Mon, 04 Mar 2024 01:32:53 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709533966; 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=7NotQ5xIVKyws1mpCsTlsyJuN2gRQCKdulXiWWxT8xE=; b=SsIoAtB19C6a+Xqi2cTnKQrGJOpdB1SaYiV+1zDJKp5tCpfkJghWlHNQzrNEOIP+EOVWLc t0qINo8vJVjkzt4qpy6OK0+M74X5lZWqJ6UGmXj7ghPK045cmH/gwVjfTA1bnIwO3dNNf4 VuY+NeUvyzMAj/B1Ub6xGVgWuYpK4rg= 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-50-wHchecvuMV6CWDi9PK9kPw-1; Mon, 04 Mar 2024 01:32:40 -0500 X-MC-Unique: wHchecvuMV6CWDi9PK9kPw-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 822AC1064F8D; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.3]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5C7A11121306; Mon, 4 Mar 2024 06:32:40 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9D72421E66F1; Mon, 4 Mar 2024 07:32:36 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: peter.maydell@linaro.org, Steve Sistare , Fabiano Rosas Subject: [PULL 18/18] migration: simplify exec migration functions Date: Mon, 4 Mar 2024 07:32:36 +0100 Message-ID: <20240304063236.213955-19-armbru@redhat.com> In-Reply-To: <20240304063236.213955-1-armbru@redhat.com> References: <20240304063236.213955-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain 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: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.589, 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 From: Steve Sistare Simplify the exec migration code by using list utility functions. As a side effect, this also fixes a minor memory leak. On function return, "g_auto(GStrv) argv" frees argv and each element, which is wrong, because the function does not own the individual elements. To compensate, the code uses g_steal_pointer which NULLs argv and prevents the destructor from running, but argv is leaked. Fixes: cbab4face57b ("migration: convert exec backend ...") Signed-off-by: Steve Sistare Reviewed-by: Fabiano Rosas Message-ID: <20240227153321.467343-4-armbru@redhat.com> Signed-off-by: Markus Armbruster --- migration/exec.c | 57 +++++++----------------------------------------- 1 file changed, 8 insertions(+), 49 deletions(-) diff --git a/migration/exec.c b/migration/exec.c index 47d2f3b8fb..20e6cccf8c 100644 --- a/migration/exec.c +++ b/migration/exec.c @@ -18,6 +18,7 @@ */ #include "qemu/osdep.h" +#include "qapi/type-helpers.h" #include "qemu/error-report.h" #include "channel.h" #include "exec.h" @@ -39,51 +40,16 @@ const char *exec_get_cmd_path(void) } #endif -/* provides the length of strList */ -static int -str_list_length(strList *list) -{ - int len = 0; - strList *elem; - - for (elem = list; elem != NULL; elem = elem->next) { - len++; - } - - return len; -} - -static void -init_exec_array(strList *command, char **argv, Error **errp) -{ - int i = 0; - strList *lst; - - for (lst = command; lst; lst = lst->next) { - argv[i++] = lst->value; - } - - argv[i] = NULL; - return; -} - void exec_start_outgoing_migration(MigrationState *s, strList *command, Error **errp) { - QIOChannel *ioc; - - int length = str_list_length(command); - g_auto(GStrv) argv = (char **) g_new0(const char *, length + 1); - - init_exec_array(command, argv, errp); + QIOChannel *ioc = NULL; + g_auto(GStrv) argv = strv_from_str_list(command); + const char * const *args = (const char * const *) argv; g_autofree char *new_command = g_strjoinv(" ", (char **)argv); trace_migration_exec_outgoing(new_command); - ioc = QIO_CHANNEL( - qio_channel_command_new_spawn( - (const char * const *) g_steal_pointer(&argv), - O_RDWR, - errp)); + ioc = QIO_CHANNEL(qio_channel_command_new_spawn(args, O_RDWR, errp)); if (!ioc) { return; } @@ -105,19 +71,12 @@ static gboolean exec_accept_incoming_migration(QIOChannel *ioc, void exec_start_incoming_migration(strList *command, Error **errp) { QIOChannel *ioc; - - int length = str_list_length(command); - g_auto(GStrv) argv = (char **) g_new0(const char *, length + 1); - - init_exec_array(command, argv, errp); + g_auto(GStrv) argv = strv_from_str_list(command); + const char * const *args = (const char * const *) argv; g_autofree char *new_command = g_strjoinv(" ", (char **)argv); trace_migration_exec_incoming(new_command); - ioc = QIO_CHANNEL( - qio_channel_command_new_spawn( - (const char * const *) g_steal_pointer(&argv), - O_RDWR, - errp)); + ioc = QIO_CHANNEL(qio_channel_command_new_spawn(args, O_RDWR, errp)); if (!ioc) { return; }