From patchwork Mon Feb 5 07:46:55 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895147 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=ZSu+ZYMg; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz5d3dmxz23hQ for ; Mon, 5 Feb 2024 18:48:37 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWthR-000368-9t; Mon, 05 Feb 2024 02:47: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 1rWthN-000332-LA for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:25 -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 1rWthF-00062o-4E for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:21 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=YxLKRLQ/e4l6WYFr0iZQ7+sR0rV0kFS0B3bQEuT/3Mg=; b=ZSu+ZYMgPN5cLyN1yM+1PFuw3sozSVWfQbm7s8OKSp81HO6eVi/r7hHlvDQL7a0GK42cgE 5ZtjrQ6GEsCGa4+mMvyD+YmPYEAL24Dt6Iw9+I61pEh5PSwZR/AQ3tE5FwXUQ+EoNzKbSh t5YwWEy3VtDiUAh5tewRuCAImQ4ySK8= 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-343-ncymxqx1Oeq8btzzlspKaQ-1; Mon, 05 Feb 2024 02:47:11 -0500 X-MC-Unique: ncymxqx1Oeq8btzzlspKaQ-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 0EF83868905; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 3FAAE492BFA; Mon, 5 Feb 2024 07:47:10 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 3C83F21E66DA; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 01/15] docs/devel/qapi-code-gen: Normalize version refs x.y.0 to just x.y Date: Mon, 5 Feb 2024 08:46:55 +0100 Message-ID: <20240205074709.3613229-2-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Missed in commit 9bc6e893b72 (qapi: Normalize version references x.y.0 to just x.y). Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- docs/devel/qapi-code-gen.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 76be722f4c..13d38dbb09 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1023,7 +1023,7 @@ For example:: # # ... more members ... # - # Since: 0.14.0 + # Since: 0.14 ## { 'struct': 'BlockStats', 'data': {'*device': 'str', '*node-name': 'str', @@ -1039,7 +1039,7 @@ For example:: # # Returns: A list of @BlockStats for each virtual block devices. # - # Since: 0.14.0 + # Since: 0.14 # # Example: # From patchwork Mon Feb 5 07:46:56 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895157 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=PoVzzu9K; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7k68tjz23g7 for ; Mon, 5 Feb 2024 18:50:26 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWthV-00036x-H7; Mon, 05 Feb 2024 02:47:33 -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 1rWthH-00032V-7V for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:24 -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 1rWthE-00062P-0q for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:18 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119235; 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=R+A5qN1+B+3bWEQkLfmxFJRbRJWlEO5MpiR5sPFxOnI=; b=PoVzzu9KapNebCr11RTuOQN8fYndXY/mojnbFmbZnGcD+FoMqTPCqK7sP0P8jvKKUeRQUq dfufQHBPt6e5SUnmV1mwG8/Gt1q9QwPArRr5IMWqXOHgX48c22RadwCkT2u5/xwXyXuEGW OHaK7mq97Z3l9jhl/MdtVPWgpf+tqh0= 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-120-lCXd98iUM1C4DgWfXdUpBA-1; Mon, 05 Feb 2024 02:47:12 -0500 X-MC-Unique: lCXd98iUM1C4DgWfXdUpBA-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 0FD08280C299; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 853D41B97; Mon, 5 Feb 2024 07:47:10 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 407DA21E64D2; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 02/15] docs/devel/qapi-code-gen: Tweak doc comment whitespace Date: Mon, 5 Feb 2024 08:46:56 +0100 Message-ID: <20240205074709.3613229-3-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Missed in commit a937b6aa739 (qapi: Reformat doc comments to conform to current conventions). Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- docs/devel/qapi-code-gen.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 13d38dbb09..69c8a1e8bd 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1019,7 +1019,7 @@ For example:: # @device: If the stats are for a virtual block device, the name # corresponding to the virtual block device. # - # @node-name: The node name of the device. (since 2.3) + # @node-name: The node name of the device. (Since 2.3) # # ... more members ... # @@ -1035,7 +1035,8 @@ For example:: # Query the @BlockStats for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes - # ... explain, explain ... (since 2.3) + # ... explain, explain ... + # (Since 2.3) # # Returns: A list of @BlockStats for each virtual block devices. # From patchwork Mon Feb 5 07:46:57 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895154 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=Q+acoZ/F; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7Q29SPz23g7 for ; Mon, 5 Feb 2024 18:50:10 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtj3-0004wL-3H; Mon, 05 Feb 2024 02:49:10 -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 1rWthN-00033D-Qs for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -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 1rWthF-00063X-Nd for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:22 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=25mGRKXxxtZnr6fOsB71JDGeAaed4fcw8ckGV4seOEY=; b=Q+acoZ/FeZemd+2k86J/pUhikVq6oXWgyYRIpFRHUpxxMuGcYY1ruyDHcvcorUPqEyZBx/ +FZ6VmFo6G1DBA01rcuMgBKlzBq5WAKIUFSmFopDCRZh8N18J5kcJihY43iqUgy+PdvC/w DSGF4Qd7X3dR9ROuaY5bu7LEKnDJIDE= 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-655-hcqw85CpNJGiaSnyz3M80Q-1; Mon, 05 Feb 2024 02:47:11 -0500 X-MC-Unique: hcqw85CpNJGiaSnyz3M80Q-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 110F083B82A; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 4058D2166B32; Mon, 5 Feb 2024 07:47:10 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 4426821E64DA; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 03/15] qapi/block-core: Fix BlockLatencyHistogramInfo doc markup Date: Mon, 5 Feb 2024 08:46:57 +0100 Message-ID: <20240205074709.3613229-4-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The description of @bins ends with a literal block: # @bins: list of io request counts corresponding to histogram # intervals, one more element than @boundaries has. For the # example above, @bins may be something like [3, 1, 5, 2], and # corresponding histogram looks like: # # :: # # 5| * Except it actually ends *before* the block: the unindented '::' line starts a new section. Makes no sense. We could fix this by indenting the '::' line. Instead, double the colon at the end of the preceding paragraph, and drop the '::' line. This shifts the box for the literal block right in generated documentation, so it lines up with the description. Fixes: commit a0fcff383b34 (qapi: Use rST markup for literal blocks) Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/block-core.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 781c9bd03e..80ed4122f2 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -656,9 +656,7 @@ # @bins: list of io request counts corresponding to histogram # intervals, one more element than @boundaries has. For the # example above, @bins may be something like [3, 1, 5, 2], and -# corresponding histogram looks like: -# -# :: +# corresponding histogram looks like:: # # 5| * # 4| * From patchwork Mon Feb 5 07:46:58 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895146 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=JwrTH0YB; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz5d3GBjz23gT for ; Mon, 5 Feb 2024 18:48:37 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWti4-0003Cb-RZ; Mon, 05 Feb 2024 02:48:09 -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 1rWthN-00033L-Rd for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -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 1rWthF-00062j-54 for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:21 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=nBhBLc+jnhaSBhdtpMFKEdvoaU89WA+NIhp6+je1744=; b=JwrTH0YBj4OgWiRD3UGjJ9bpd3lOMX2V0R+zYv48mKrIrAy5cFool6DC74Jp/IXJUhDQOj oWCnfsg5/AYJ8yK8qSnCQ0Ew4pZToeqDC0J65NvdjPKAYHPTxZmUQ7Fu2WWzC6M5m9T1tF 9un+0k4CCejPah3R5hR5e7/N5wO371g= 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-343-ahEc7_NnNZekGKgqz-yKDA-1; Mon, 05 Feb 2024 02:47:11 -0500 X-MC-Unique: ahEc7_NnNZekGKgqz-yKDA-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 2C70B868906; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 40EC52B7; Mon, 5 Feb 2024 07:47:10 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 47FB121E64DB; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 04/15] qapi: Indent tagged doc comment sections properly Date: Mon, 5 Feb 2024 08:46:58 +0100 Message-ID: <20240205074709.3613229-5-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org docs/devel/qapi-code-gen demands that the "second and subsequent lines of sections other than "Example"/"Examples" should be indented". Commit a937b6aa739q (qapi: Reformat doc comments to conform to current conventions) missed a few instances, and messed up a few others. Clean that up. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/migration.json | 46 ++++++++++++++++----------------- qapi/misc.json | 12 +++++---- qapi/qdev.json | 12 ++++----- tests/qapi-schema/doc-good.json | 10 +++---- tests/qapi-schema/doc-good.out | 2 +- 5 files changed, 42 insertions(+), 40 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 819708321d..bf89765a26 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1699,24 +1699,24 @@ # # Notes: # -# 1. The 'query-migrate' command should be used to check migration's -# progress and final result (this information is provided by the -# 'status' member) +# 1. The 'query-migrate' command should be used to check +# migration's progress and final result (this information is +# provided by the 'status' member) # -# 2. All boolean arguments default to false +# 2. All boolean arguments default to false # -# 3. The user Monitor's "detach" argument is invalid in QMP and should -# not be used +# 3. The user Monitor's "detach" argument is invalid in QMP and +# should not be used # -# 4. The uri argument should have the Uniform Resource Identifier of -# default destination VM. This connection will be bound to default -# network. +# 4. The uri argument should have the Uniform Resource Identifier +# of default destination VM. This connection will be bound to +# default network. # -# 5. For now, number of migration streams is restricted to one, i.e -# number of items in 'channels' list is just 1. +# 5. For now, number of migration streams is restricted to one, +# i.e number of items in 'channels' list is just 1. # -# 6. The 'uri' and 'channels' arguments are mutually exclusive; -# exactly one of the two should be present. +# 6. The 'uri' and 'channels' arguments are mutually exclusive; +# exactly one of the two should be present. # # Example: # @@ -1781,20 +1781,20 @@ # # Notes: # -# 1. It's a bad idea to use a string for the uri, but it needs -# to stay compatible with -incoming and the format of the uri -# is already exposed above libvirt. +# 1. It's a bad idea to use a string for the uri, but it needs to +# stay compatible with -incoming and the format of the uri is +# already exposed above libvirt. # -# 2. QEMU must be started with -incoming defer to allow -# migrate-incoming to be used. +# 2. QEMU must be started with -incoming defer to allow +# migrate-incoming to be used. # -# 3. The uri format is the same as for -incoming +# 3. The uri format is the same as for -incoming # -# 5. For now, number of migration streams is restricted to one, i.e -# number of items in 'channels' list is just 1. +# 5. For now, number of migration streams is restricted to one, +# i.e number of items in 'channels' list is just 1. # -# 4. The 'uri' and 'channels' arguments are mutually exclusive; -# exactly one of the two should be present. +# 4. The 'uri' and 'channels' arguments are mutually exclusive; +# exactly one of the two should be present. # # Example: # diff --git a/qapi/misc.json b/qapi/misc.json index 2ca8c39874..4108a0c951 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -348,9 +348,10 @@ # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError # -# Notes: The list of fd sets is shared by all monitor connections. +# Notes: +# The list of fd sets is shared by all monitor connections. # -# If @fdset-id is not specified, a new fd set will be created. +# If @fdset-id is not specified, a new fd set will be created. # # Since: 1.2 # @@ -379,10 +380,11 @@ # # Since: 1.2 # -# Notes: The list of fd sets is shared by all monitor connections. +# Notes: +# The list of fd sets is shared by all monitor connections. # -# If @fd is not specified, all file descriptors in @fdset-id will be -# removed. +# If @fd is not specified, all file descriptors in @fdset-id will +# be removed. # # Example: # diff --git a/qapi/qdev.json b/qapi/qdev.json index 25bac5e611..3b3ccfa413 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -53,14 +53,14 @@ # # Notes: # -# 1. Additional arguments depend on the type. +# 1. Additional arguments depend on the type. # -# 2. For detailed information about this command, please refer to the -# 'docs/qdev-device-use.txt' file. +# 2. For detailed information about this command, please refer to +# the 'docs/qdev-device-use.txt' file. # -# 3. It's possible to list device properties by running QEMU with the -# "-device DEVICE,help" command-line argument, where DEVICE is the -# device's name +# 3. It's possible to list device properties by running QEMU with +# the "-device DEVICE,help" command-line argument, where DEVICE +# is the device's name # # Example: # diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 354dfdf461..976f9e1aaa 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -73,8 +73,8 @@ # @Base: # # @base1: -# description starts on a new line, -# not indented +# description starts on a new line, +# minimally indented ## { 'struct': 'Base', 'data': { 'base1': 'Enum' }, 'if': { 'all': ['IFALL1', 'IFALL2'] } } @@ -155,10 +155,10 @@ # TODO: frobnicate # Notes: # -# - Lorem ipsum dolor sit amet -# - Ut enim ad minim veniam +# - Lorem ipsum dolor sit amet +# - Ut enim ad minim veniam # -# Duis aute irure dolor +# Duis aute irure dolor # Example: # # -> in diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 24d9ea954d..34ee74af4b 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -118,7 +118,7 @@ doc symbol=Base arg=base1 description starts on a new line, -not indented +minimally indented doc symbol=Variant1 body= A paragraph From patchwork Mon Feb 5 07:46:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895152 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=FQUaGcKc; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz711WFcz23gT for ; Mon, 5 Feb 2024 18:49:49 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWti8-0003Js-TS; Mon, 05 Feb 2024 02:48:13 -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 1rWthN-00033J-RI for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -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 1rWthG-00064F-4b for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:23 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119237; 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=DI3xOKCAdTmIsVMcuw8btdqgochVN7h42E80Oq59w5c=; b=FQUaGcKc0kdbQJrbOtZE+Fh7Wk5JFBXaYu2j1fUMI3jAlJQYiAobIZ7xblkotLyRmAVQA0 rC2tsX0TZIAqrXtpgRvhwNpAf11bCj6NSscD+S+YvPChT3g0RlXAEl19F7U7pF4SvqfF2N ZE1oRMyQ8IfKFH8MU5GLtIFgtsGgFcU= 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-586-YbyUk7NeNQGyVzFlJlyRJw-1; Mon, 05 Feb 2024 02:47:12 -0500 X-MC-Unique: YbyUk7NeNQGyVzFlJlyRJw-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 1974E1C54465; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E82903C2E; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 4C57721E60DC; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 05/15] sphinx/qapidoc: Drop code to generate doc for simple union tag Date: Mon, 5 Feb 2024 08:46:59 +0100 Message-ID: <20240205074709.3613229-6-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org QAPISchemaGenRSTVisitor._nodes_for_members() has a special case to auto-generate documentation for a union tag member of implicit (enum) type that lacks documentation. This was useful for simple unions, where the tag member's type was implicitly. The only implicit enum type left today is 'QType'. Not worth a special case. Drop. No change to generated documentation. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- docs/sphinx/qapidoc.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 658c288f8f..05b809af27 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -168,12 +168,6 @@ def _nodes_for_members(self, doc, what, base=None, variants=None): # TODO drop fallbacks when undocumented members are outlawed if section.text: defn = section.text - elif (variants and variants.tag_member == section.member - and not section.member.type.doc_type()): - values = section.member.type.member_names() - defn = [nodes.Text('One of ')] - defn.extend(intersperse([nodes.literal('', v) for v in values], - nodes.Text(', '))) else: defn = [nodes.Text('Not documented')] From patchwork Mon Feb 5 07:47:00 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895151 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=ca1N/tQx; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz700hWkz23gT for ; Mon, 5 Feb 2024 18:49:48 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWti5-0003DH-JI; Mon, 05 Feb 2024 02:48:09 -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 1rWthN-000333-MM for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:25 -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 1rWthE-00062p-Uq for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:19 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=LPv8QHcSKcIkORJY71jJXnrGxJ9jo1EGmXY2UQzjY1E=; b=ca1N/tQxvHC3vazN/Lyi0ZyEwXZup1pPbhgl1OWJoNOa/WgDzSd1ktsC8kbVu7ti+7qKov KMl0Q6Zy6ZHKuo1euqAzwXuDN2viiMBRNDx01ghHaE7iB/mKc8ryJMq+VLYte95xXlMeEQ XE1gZQ4VCXWf3AeQYEB/RjbzNA21N00= 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-648-w_tG4-VvPRCPsPZDma5axg-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: w_tG4-VvPRCPsPZDma5axg-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 3835983B831; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E9A0A152E; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 5040221E60DD; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 06/15] qapi: Require member documentation (with loophole) Date: Mon, 5 Feb 2024 08:47:00 +0100 Message-ID: <20240205074709.3613229-7-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The QAPI generator forces you to document your stuff. Except for command arguments, event data, and members of enum and object types: these the generator silently "documents" as "Not documented". We can't require proper documentation there without first fixing all the offenders. We've always had too many offenders to pull that off. Right now, we have more than 500. Worse, we seem to fix old ones no faster than we add new ones: in the past year, we fixed 22 ones, but added 26 new ones. To help arrest the backsliding, make missing documentation an error unless the command, type, or event is in listed in new pragma documentation-exceptions. List all the current offenders: 117 commands and types in qapi/, and 9 in qga/. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- docs/devel/qapi-code-gen.rst | 5 + qapi/pragma.json | 119 ++++++++++++++++++ qga/qapi-schema.json | 13 +- scripts/qapi/parser.py | 7 +- scripts/qapi/source.py | 2 + .../qapi-schema/doc-bad-alternate-member.json | 2 + tests/qapi-schema/doc-good.json | 4 +- 7 files changed, 149 insertions(+), 3 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 69c8a1e8bd..756adc187e 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -167,6 +167,7 @@ Syntax:: '*doc-required': BOOL, '*command-name-exceptions': [ STRING, ... ], '*command-returns-exceptions': [ STRING, ... ], + '*documentation-exceptions': [ STRING, ... ], '*member-name-exceptions': [ STRING, ... ] } } The pragma directive lets you control optional generator behavior. @@ -183,6 +184,10 @@ may contain ``"_"`` instead of ``"-"``. Default is none. Pragma 'command-returns-exceptions' takes a list of commands that may violate the rules on permitted return types. Default is none. +Pragma 'documentation-exceptions' takes a list of types, commands, and +events whose members / arguments need not be documented. Default is +none. + Pragma 'member-name-exceptions' takes a list of types whose member names may contain uppercase letters, and ``"_"`` instead of ``"-"``. Default is none. diff --git a/qapi/pragma.json b/qapi/pragma.json index 0aa4eeddd3..0fa64742b5 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -31,6 +31,125 @@ 'query-tpm-models', 'query-tpm-types', 'ringbuf-read' ], + # Types, commands, and events with undocumented members / arguments: + 'documentation-exceptions': [ + 'AbortWrapper', + 'AudiodevDriver', + 'BlkdebugEvent', + 'BlockDirtyBitmapAddWrapper', + 'BlockDirtyBitmapMergeWrapper', + 'BlockDirtyBitmapWrapper', + 'BlockExportOptions', + 'BlockStatsSpecific', + 'BlockdevBackupWrapper', + 'BlockdevDriver', + 'BlockdevQcow2Encryption', + 'BlockdevQcow2EncryptionFormat', + 'BlockdevQcowEncryption', + 'BlockdevSnapshotInternalWrapper', + 'BlockdevSnapshotSyncWrapper', + 'BlockdevSnapshotWrapper', + 'BlockdevVmdkAdapterType', + 'ChardevBackend', + 'ChardevBackendKind', + 'ChardevCommonWrapper', + 'ChardevDBusWrapper', + 'ChardevFileWrapper', + 'ChardevHostdevWrapper', + 'ChardevMuxWrapper', + 'ChardevQemuVDAgentWrapper', + 'ChardevRingbufWrapper', + 'ChardevSocketWrapper', + 'ChardevSpiceChannelWrapper', + 'ChardevSpicePortWrapper', + 'ChardevStdioWrapper', + 'ChardevUdpWrapper', + 'ChardevVCWrapper', + 'CpuS390Entitlement', + 'CpuS390Polarization', + 'CpuS390State', + 'CxlCorErrorType', + 'DisplayProtocol', + 'DriveBackupWrapper', + 'DummyBlockCoreForceArrays', + 'DummyForceArrays', + 'DummyVirtioForceArrays', + 'DumpGuestMemoryCapability', + 'GrabToggleKeys', + 'GuestPanicInformationHyperV', + 'HotKeyMod', + 'HvBalloonDeviceInfoWrapper', + 'ImageInfoSpecific', + 'ImageInfoSpecificFileWrapper', + 'ImageInfoSpecificKind', + 'ImageInfoSpecificLUKSWrapper', + 'ImageInfoSpecificQCow2Wrapper', + 'ImageInfoSpecificRbdWrapper', + 'ImageInfoSpecificVmdkWrapper', + 'InetSocketAddressWrapper', + 'InputAxis', + 'InputBtnEventWrapper', + 'InputButton', + 'InputKeyEventWrapper', + 'InputMoveEventWrapper', + 'InputMultiTouchEvent', + 'InputMultiTouchEventWrapper', + 'InputMultiTouchType', + 'IntWrapper', + 'IscsiHeaderDigest', + 'IscsiTransport', + 'JSONType', + 'KeyValue', + 'KeyValueKind', + 'MemoryDeviceInfo', + 'MemoryDeviceInfoKind', + 'MigrateSetParameters', + 'MigrationAddress', + 'NetClientDriver', + 'NumaOptions', + 'ObjectType', + 'PCDIMMDeviceInfoWrapper', + 'PciMemoryRegion', + 'QCryptoAkCipherKeyType', + 'QCryptoAkCipherOptions', + 'QCryptodevBackendServiceType', + 'QKeyCode', + 'QKeyCodeWrapper', + 'Qcow2OverlapCheckFlags', + 'RbdAuthMode', + 'RbdEncryptionCreateOptions', + 'RbdImageEncryptionFormat', + 'SgxEPCDeviceInfoWrapper', + 'SocketAddressLegacy', + 'SshHostKeyCheck', + 'StatsFilter', + 'StatsValue', + 'String', + 'StringWrapper', + 'SysEmuTarget', + 'TPMEmulatorOptionsWrapper', + 'TPMPassthroughOptionsWrapper', + 'ThrottleGroupProperties', + 'TransactionAction', + 'UnixSocketAddressWrapper', + 'VirtioMEMDeviceInfoWrapper', + 'VirtioPMEMDeviceInfoWrapper', + 'VncPrimaryAuth', + 'VncVencryptSubAuth', + 'VsockSocketAddressWrapper', + 'X86CPURegister32', + 'XDbgBlockGraph', + 'YankInstance', + 'YankInstanceType', + 'blockdev-reopen', + 'query-cpu-model-baseline', + 'query-cpu-model-comparison', + 'query-cpu-model-expansion', + 'query-rocker', + 'query-rocker-ports', + 'query-stats-schemas', + 'watchdog-set-action', + 'yank' ], # Externally visible types whose member names may use uppercase 'member-name-exceptions': [ # visible in: 'ACPISlotType', # query-acpi-ospm-status diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 50b0a558c7..b9501c8c81 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -33,7 +33,18 @@ 'guest-get-time', 'guest-set-vcpus', 'guest-sync', - 'guest-sync-delimited' ] } } + 'guest-sync-delimited' ], + # Types and commands with undocumented members: + 'documentation-exceptions': [ + 'GuestCpuStats', + 'GuestCpuStatsType', + 'GuestDeviceId', + 'GuestDeviceType', + 'GuestDiskSmart', + 'GuestDiskStatsInfo', + 'GuestNVMeSmart', + 'guest-set-memory-blocks', + 'guest-set-vcpus' ] } } ## # @guest-sync-delimited: diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 48cd55a38c..88221b3c64 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -238,6 +238,8 @@ def check_list_str(name: str, value: object) -> List[str]: pragma.command_name_exceptions = check_list_str(name, value) elif name == 'command-returns-exceptions': pragma.command_returns_exceptions = check_list_str(name, value) + elif name == 'documentation-exceptions': + pragma.documentation_exceptions = check_list_str(name, value) elif name == 'member-name-exceptions': pragma.member_name_exceptions = check_list_str(name, value) else: @@ -739,7 +741,10 @@ def _append_freeform(self, line: str) -> None: def connect_member(self, member: 'QAPISchemaMember') -> None: if member.name not in self.args: - # Undocumented TODO outlaw + if self.symbol not in member.info.pragma.documentation_exceptions: + raise QAPISemError(member.info, + "%s '%s' lacks documentation" + % (member.role, member.name)) self.args[member.name] = QAPIDoc.ArgSection(self._parser, member.name) self.args[member.name].connect(member) diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py index 04193cc964..7b379fdc92 100644 --- a/scripts/qapi/source.py +++ b/scripts/qapi/source.py @@ -24,6 +24,8 @@ def __init__(self) -> None: self.command_name_exceptions: List[str] = [] # Commands allowed to return a non-dictionary self.command_returns_exceptions: List[str] = [] + # Types, commands, and events with undocumented members + self.documentation_exceptions: List[str] = [] # Types whose member names may violate case conventions self.member_name_exceptions: List[str] = [] diff --git a/tests/qapi-schema/doc-bad-alternate-member.json b/tests/qapi-schema/doc-bad-alternate-member.json index fa4143da4c..37593b6698 100644 --- a/tests/qapi-schema/doc-bad-alternate-member.json +++ b/tests/qapi-schema/doc-bad-alternate-member.json @@ -2,6 +2,8 @@ ## # @AorB: +# @a: a +# @b: b # @aa: a # @bb: b ## diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 976f9e1aaa..24a84fe6d7 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -3,7 +3,9 @@ # # Positive QAPI doc comment tests -{ 'pragma': { 'doc-required': true } } +{ 'pragma': { + 'doc-required': true, + 'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } } ## # = Section From patchwork Mon Feb 5 07:47:01 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895155 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=QgtYhxsh; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7R24f1z23g7 for ; Mon, 5 Feb 2024 18:50:11 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtj1-0004nl-QN; Mon, 05 Feb 2024 02:49:07 -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 1rWthP-000364-EN for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:29 -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 1rWthM-00066R-QN for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119239; 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=DJ/iFqjc6913VV02EMMyJyjWFx+82MWX8wjAg2ffje4=; b=QgtYhxshOM8eBdDE+Zs5aCrbe4gH2wnXORepXTPe0lp1YvbQY64j7L8okTlJw07hE5Vw5F kHH9jsXVzHIYFacOsmwkpXN+A/RsPFd0diOVSi1yYyEVySRs/OC36B+0rFqGjAQHtII0p5 ROYKrc0JHnHeQsugAd1h+Nmp19L44t0= 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-586--dZWXJp7M-C7kSrQXn_bPg-1; Mon, 05 Feb 2024 02:47:12 -0500 X-MC-Unique: -dZWXJp7M-C7kSrQXn_bPg-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 1A1AE86890A; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id E9C021C060B2; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 53FFC21E60F3; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 07/15] qga/qapi-schema: Clean up documentation of guest-set-memory-blocks Date: Mon, 5 Feb 2024 08:47:01 +0100 Message-ID: <20240205074709.3613229-8-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The command's doc comment describes the argument, but it's not marked up as such. Easy enough to fix. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé Reviewed-by: Konstantin Kostiuk --- qga/qapi-schema.json | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index b9501c8c81..35bde36a1f 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -43,7 +43,6 @@ 'GuestDiskSmart', 'GuestDiskStatsInfo', 'GuestNVMeSmart', - 'guest-set-memory-blocks', 'guest-set-vcpus' ] } } ## @@ -1174,14 +1173,16 @@ # Attempt to reconfigure (currently: enable/disable) state of memory # blocks inside the guest. # -# The input list is processed node by node in order. In each node -# @phys-index is used to look up the guest MEMORY BLOCK, for which -# @online specifies the requested state. The set of distinct -# @phys-index's is only required to be a subset of the guest-supported -# identifiers. There's no restriction on list length or on repeating -# the same @phys-index (with possibly different @online field). -# Preferably the input list should describe a modified subset of -# @guest-get-memory-blocks' return value. +# @mem-blks: The memory blocks to be reconfigured. This list is +# processed node by node in order. In each node @phys-index is +# used to look up the guest MEMORY BLOCK, for which @online +# specifies the requested state. The set of distinct +# @phys-index's is only required to be a subset of the +# guest-supported identifiers. There's no restriction on list +# length or on repeating the same @phys-index (with possibly +# different @online field). Preferably the input list should +# describe a modified subset of @guest-get-memory-blocks' return +# value. # # Returns: The operation results, it is a list of # @GuestMemoryBlockResponse, which is corresponding to the input From patchwork Mon Feb 5 07:47:02 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895160 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=dBd1BaZW; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7x5B01z23g7 for ; Mon, 5 Feb 2024 18:50:37 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtj0-0004eX-Kc; Mon, 05 Feb 2024 02:49:06 -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 1rWthN-000337-Oa for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:25 -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 1rWthF-000630-6f for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:21 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=ND0x3p3iuq2cuPfkUG05E4VZFd/JDGusCGJgHlpMh/4=; b=dBd1BaZWnRNIFtVae7TvlA/N1pP73FOga9luzYzgGsBkWYbGTFyq+brtmTJB4BcCLk1JIK qTDgJE/iky64eHFOfYLb7hCqn9umn7dRlH4i56xlamsHSGng4ScQQcx0DAT3fJAkPo1RpD ha4JJG/VzD0l4j5U8+EOWwEogxx9uXY= 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-401-hbL-30tgOAmquVcAbHX6fQ-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: hbL-30tgOAmquVcAbHX6fQ-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 6169683B834; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id EC00DC15E6A; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 5905421E60F4; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 08/15] qga/qapi-schema: Clean up documentation of guest-set-vcpus Date: Mon, 5 Feb 2024 08:47:02 +0100 Message-ID: <20240205074709.3613229-9-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The command's doc comment describes the argument, but it's not marked up as such. Easy enough to fix. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé Reviewed-by: Konstantin Kostiuk --- qga/qapi-schema.json | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 35bde36a1f..f3d168d542 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -42,8 +42,7 @@ 'GuestDeviceType', 'GuestDiskSmart', 'GuestDiskStatsInfo', - 'GuestNVMeSmart', - 'guest-set-vcpus' ] } } + 'GuestNVMeSmart' ] } } ## # @guest-sync-delimited: @@ -786,14 +785,15 @@ # Attempt to reconfigure (currently: enable/disable) logical # processors inside the guest. # -# The input list is processed node by node in order. In each node -# @logical-id is used to look up the guest VCPU, for which @online -# specifies the requested state. The set of distinct @logical-id's is -# only required to be a subset of the guest-supported identifiers. -# There's no restriction on list length or on repeating the same -# @logical-id (with possibly different @online field). Preferably the -# input list should describe a modified subset of @guest-get-vcpus' -# return value. +# @vcpus: The logical processors to be reconfigured. This list is +# processed node by node in order. In each node @logical-id is +# used to look up the guest VCPU, for which @online specifies the +# requested state. The set of distinct @logical-id's is only +# required to be a subset of the guest-supported identifiers. +# There's no restriction on list length or on repeating the same +# @logical-id (with possibly different @online field). Preferably +# the input list should describe a modified subset of +# @guest-get-vcpus' return value. # # Returns: The length of the initial sublist that has been # successfully processed. The guest agent maximizes this value. From patchwork Mon Feb 5 07:47:03 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895145 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=JVGnN6Ch; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz5d3JFqz23hK for ; Mon, 5 Feb 2024 18:48:37 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWti9-0003KC-UM; Mon, 05 Feb 2024 02:48:14 -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 1rWthN-000334-NP for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:25 -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 1rWthE-00062x-Vy for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:20 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=QNynqkKX4qBeTYspk/1SN2AngUmIP8zYz3tbq++y9GA=; b=JVGnN6ChoiB7XJqvkaDohYpVpGwNfp1LvoOQuVgBu3McWvd7qOWiMUmZuJDFkGgz14+794 s0Ba0ViN3bPnYPVCyY569R7wSgzwoH3PMFETsWRn5H5M6D5T8vd5ej/U0sLupkbu0RaKpN +0HPMTWiz3FSZJhBr6eXIsehahbNFvg= 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-144-7OHGOt5UNOekdql2fumkMg-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: 7OHGOt5UNOekdql2fumkMg-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 23B8D85A597; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id EFF8A2026F95; Mon, 5 Feb 2024 07:47:11 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 5B8D221E60F5; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 09/15] qga/qapi-schema: Plug trivial documentation holes Date: Mon, 5 Feb 2024 08:47:03 +0100 Message-ID: <20240205074709.3613229-10-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Add missing return member documentation of guest-get-disks, guest-get-devices, guest-get-diskstats, and guest-get-cpustats. The NVMe SMART information returned by guest-getdisks remains undocumented. Add a TODO there. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qga/qapi-schema.json | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index f3d168d542..b8efe31897 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -36,12 +36,6 @@ 'guest-sync-delimited' ], # Types and commands with undocumented members: 'documentation-exceptions': [ - 'GuestCpuStats', - 'GuestCpuStatsType', - 'GuestDeviceId', - 'GuestDeviceType', - 'GuestDiskSmart', - 'GuestDiskStatsInfo', 'GuestNVMeSmart' ] } } ## @@ -944,6 +938,8 @@ # NVMe smart information, based on NVMe specification, section # # +# TODO: document members briefly +# # Since: 7.1 ## { 'struct': 'GuestNVMeSmart', @@ -978,7 +974,7 @@ # # Disk type related smart information. # -# - @nvme: NVMe disk smart +# @type: disk bus type # # Since: 7.1 ## @@ -1499,6 +1495,8 @@ ## # @GuestDeviceType: +# +# @pci: PCI device ## { 'enum': 'GuestDeviceType', 'data': [ 'pci' ] } @@ -1518,7 +1516,9 @@ ## # @GuestDeviceId: # -# Id of the device - @pci: PCI ID, since: 5.2 +# Id of the device +# +# @type: device type # # Since: 5.2 ## @@ -1700,6 +1700,8 @@ # @major: major device number of disk # # @minor: minor device number of disk +# +# @stats: I/O statistics ## { 'struct': 'GuestDiskStatsInfo', 'data': {'name': 'str', @@ -1723,7 +1725,9 @@ ## # @GuestCpuStatsType: # -# An enumeration of OS type +# Guest operating systems supporting CPU statistics +# +# @linux: Linux # # Since: 7.1 ## @@ -1780,7 +1784,7 @@ # # Get statistics of each CPU in millisecond. # -# - @linux: Linux style CPU statistics +# @type: guest operating system # # Since: 7.1 ## From patchwork Mon Feb 5 07:47:04 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895153 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=h/YuMfaW; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7D2n66z23gT for ; Mon, 5 Feb 2024 18:50:00 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtiz-0004SO-Hp; Mon, 05 Feb 2024 02:49:05 -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 1rWthN-00033K-RM for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -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 1rWthE-000631-VJ for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:20 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=OQzW0p+QT9LYzfWwmryF3MrznKJEe76HrPn3qNYU0x0=; b=h/YuMfaWjR50dJzBQLFZSwop4tP7UWHoGZZ2dNbSZ/q0L+qTmpbn2UB+C4TQ29x+cMzNWv dPwe7fTliRiW8004cQ4kijrlg4NTkJbAiWMbdd6p+mtlsL/QIq6k34jHs2rOsVwsq9vbQS V/1jObs3tzU3cfP1sNJsdD4oesCuzjI= 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-606-Pi0tI1IUNBen1y80-2RCKQ-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: Pi0tI1IUNBen1y80-2RCKQ-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 270413816B61; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 008C72166B32; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 5F61021E5A40; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 10/15] qapi/yank: Clean up documentaion of yank Date: Mon, 5 Feb 2024 08:47:04 +0100 Message-ID: <20240205074709.3613229-11-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The command's doc comment describes the argument, but it's not marked up as such. Easy enough to fix. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/pragma.json | 3 +-- qapi/yank.json | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/qapi/pragma.json b/qapi/pragma.json index 0fa64742b5..544f138afa 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -148,8 +148,7 @@ 'query-rocker', 'query-rocker-ports', 'query-stats-schemas', - 'watchdog-set-action', - 'yank' ], + 'watchdog-set-action' ], # Externally visible types whose member names may use uppercase 'member-name-exceptions': [ # visible in: 'ACPISlotType', # query-acpi-ospm-status diff --git a/qapi/yank.json b/qapi/yank.json index 60eda20816..bfc71a07a6 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -74,7 +74,7 @@ # Try to recover from hanging QEMU by yanking the specified instances. # See @YankInstance for more information. # -# Takes a list of @YankInstance as argument. +# @instances: the instances to be yanked # # Returns: # - Nothing on success From patchwork Mon Feb 5 07:47:05 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895148 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=KndHZP2f; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz6R3mxPz23gT for ; Mon, 5 Feb 2024 18:49:19 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtik-0003vh-Sp; Mon, 05 Feb 2024 02:48:54 -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 1rWthR-00036R-Ap for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:29 -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 1rWthP-00066W-2J for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:28 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119239; 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=4Bvtob6WY5Em4EhLBslGYS83tQtR2ehIL/sitKkf5ds=; b=KndHZP2far4uZCU3g0P129/EhN4ayxggh942YQzTIKxEZ6eg/VQaVR7T6Se/7GJwugJ8Te m6fAQZmU7ZO2HzwspoKRaZsfzMbn4OW+wKcuMFtBLTsTN0cgvOYvbdo/xzL9lnD8EdFPdt gE4GWc887LGj1FpGEhXHGvlfCCrLf3E= 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-417--8eUfl7oNQumThJ_tLk4bA-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: -8eUfl7oNQumThJ_tLk4bA-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 38F9B1C54469; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 115FC400DF3E; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6313F21E5A41; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 11/15] qapi/dump: Clean up documentation of DumpGuestMemoryCapability Date: Mon, 5 Feb 2024 08:47:05 +0100 Message-ID: <20240205074709.3613229-12-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The type's doc comment describes its member, but it's not marked up as such. Easy enough to fix. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/dump.json | 2 +- qapi/pragma.json | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/qapi/dump.json b/qapi/dump.json index 5cbc237ad9..1997c1d1d4 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -186,7 +186,7 @@ ## # @DumpGuestMemoryCapability: # -# A list of the available formats for dump-guest-memory +# @formats: the available formats for dump-guest-memory # # Since: 2.0 ## diff --git a/qapi/pragma.json b/qapi/pragma.json index 544f138afa..aea6384255 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -74,7 +74,6 @@ 'DummyBlockCoreForceArrays', 'DummyForceArrays', 'DummyVirtioForceArrays', - 'DumpGuestMemoryCapability', 'GrabToggleKeys', 'GuestPanicInformationHyperV', 'HotKeyMod', From patchwork Mon Feb 5 07:47:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895156 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=gW4633sL; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7Z4JYFz23g7 for ; Mon, 5 Feb 2024 18:50:18 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtiC-0003MJ-En; Mon, 05 Feb 2024 02:48:16 -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 1rWthP-00035k-29 for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:27 -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 1rWthG-000651-TT for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:25 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119237; 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=qm8MY2V0NKeEMNWnhw/Y+eNccTF1/OEK/29fHiS7K18=; b=gW4633sL0NhCXD8Js7TQTJ0aEgo0ePL4Qf0g8m8zjWD+Jzllv1bHkbxtwbI7rGdEkISEXu N/VuTqYmnByqDCbsijOT3dVpxJcATqf1sTctQheEqNhXcrAoJsnuYaQZvdSEd35xRoBENj +vQuCBvzFGiwBmhjw0ZbI4T/6RbuOw0= 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-401-U_pVPo9eMymlUHAYvhlYyg-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: U_pVPo9eMymlUHAYvhlYyg-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 54FD683B833; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 117782166B31; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 66FF321E6806; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 12/15] qapi: Plug trivial documentation holes around former simple unions Date: Mon, 5 Feb 2024 08:47:06 +0100 Message-ID: <20240205074709.3613229-13-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The conversion of simple to flat unions left the @data members undocumented. Add documentation where it's trivial. Copy verbatim from the wrapped type's description where possible. Leftovers: String (to be taken care of in the next commit), and TransActionAction (left for another day). Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/block-core.json | 10 ++++++++++ qapi/char.json | 26 ++++++++++++++++++++++++++ qapi/machine.json | 10 ++++++++++ qapi/pragma.json | 34 ---------------------------------- qapi/sockets.json | 6 ++++++ qapi/tpm.json | 4 ++++ qapi/ui.json | 12 ++++++++++++ 7 files changed, 68 insertions(+), 34 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 80ed4122f2..55b583f079 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -196,6 +196,8 @@ ## # @ImageInfoSpecificQCow2Wrapper: # +# @data: image information specific to QCOW2 +# # Since: 1.7 ## { 'struct': 'ImageInfoSpecificQCow2Wrapper', @@ -204,6 +206,8 @@ ## # @ImageInfoSpecificVmdkWrapper: # +# @data: image information specific to VMDK +# # Since: 6.1 ## { 'struct': 'ImageInfoSpecificVmdkWrapper', @@ -212,6 +216,8 @@ ## # @ImageInfoSpecificLUKSWrapper: # +# @data: image information specific to LUKS +# # Since: 2.7 ## { 'struct': 'ImageInfoSpecificLUKSWrapper', @@ -223,6 +229,8 @@ ## # @ImageInfoSpecificRbdWrapper: # +# @data: image information specific to RBD +# # Since: 6.1 ## { 'struct': 'ImageInfoSpecificRbdWrapper', @@ -231,6 +239,8 @@ ## # @ImageInfoSpecificFileWrapper: # +# @data: image information specific to files +# # Since: 8.0 ## { 'struct': 'ImageInfoSpecificFileWrapper', diff --git a/qapi/char.json b/qapi/char.json index 6c6ad3b10c..e3e1b2c9f5 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -498,6 +498,8 @@ ## # @ChardevFileWrapper: # +# @data: Configuration info for file chardevs +# # Since: 1.4 ## { 'struct': 'ChardevFileWrapper', @@ -506,6 +508,8 @@ ## # @ChardevHostdevWrapper: # +# @data: Configuration info for device and pipe chardevs +# # Since: 1.4 ## { 'struct': 'ChardevHostdevWrapper', @@ -514,6 +518,8 @@ ## # @ChardevSocketWrapper: # +# @data: Configuration info for (stream) socket chardevs +# # Since: 1.4 ## { 'struct': 'ChardevSocketWrapper', @@ -522,6 +528,8 @@ ## # @ChardevUdpWrapper: # +# @data: Configuration info for datagram socket chardevs +# # Since: 1.5 ## { 'struct': 'ChardevUdpWrapper', @@ -530,6 +538,8 @@ ## # @ChardevCommonWrapper: # +# @data: Configuration shared across all chardev backends +# # Since: 2.6 ## { 'struct': 'ChardevCommonWrapper', @@ -538,6 +548,8 @@ ## # @ChardevMuxWrapper: # +# @data: Configuration info for mux chardevs +# # Since: 1.5 ## { 'struct': 'ChardevMuxWrapper', @@ -546,6 +558,8 @@ ## # @ChardevStdioWrapper: # +# @data: Configuration info for stdio chardevs +# # Since: 1.5 ## { 'struct': 'ChardevStdioWrapper', @@ -554,6 +568,8 @@ ## # @ChardevSpiceChannelWrapper: # +# @data: Configuration info for spice vm channel chardevs +# # Since: 1.5 ## { 'struct': 'ChardevSpiceChannelWrapper', @@ -563,6 +579,8 @@ ## # @ChardevSpicePortWrapper: # +# @data: Configuration info for spice port chardevs +# # Since: 1.5 ## { 'struct': 'ChardevSpicePortWrapper', @@ -572,6 +590,8 @@ ## # @ChardevQemuVDAgentWrapper: # +# @data: Configuration info for qemu vdagent implementation +# # Since: 6.1 ## { 'struct': 'ChardevQemuVDAgentWrapper', @@ -581,6 +601,8 @@ ## # @ChardevDBusWrapper: # +# @data: Configuration info for DBus chardevs +# # Since: 7.0 ## { 'struct': 'ChardevDBusWrapper', @@ -590,6 +612,8 @@ ## # @ChardevVCWrapper: # +# @data: Configuration info for virtual console chardevs +# # Since: 1.5 ## { 'struct': 'ChardevVCWrapper', @@ -598,6 +622,8 @@ ## # @ChardevRingbufWrapper: # +# @data: Configuration info for ring buffer chardevs +# # Since: 1.5 ## { 'struct': 'ChardevRingbufWrapper', diff --git a/qapi/machine.json b/qapi/machine.json index aa99fa333f..6a25e39f44 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1396,6 +1396,8 @@ ## # @PCDIMMDeviceInfoWrapper: # +# @data: PCDIMMDevice state information +# # Since: 2.1 ## { 'struct': 'PCDIMMDeviceInfoWrapper', @@ -1404,6 +1406,8 @@ ## # @VirtioPMEMDeviceInfoWrapper: # +# @data: VirtioPMEM state information +# # Since: 2.1 ## { 'struct': 'VirtioPMEMDeviceInfoWrapper', @@ -1412,6 +1416,8 @@ ## # @VirtioMEMDeviceInfoWrapper: # +# @data: VirtioMEMDevice state information +# # Since: 2.1 ## { 'struct': 'VirtioMEMDeviceInfoWrapper', @@ -1420,6 +1426,8 @@ ## # @SgxEPCDeviceInfoWrapper: # +# @data: Sgx EPC state information +# # Since: 6.2 ## { 'struct': 'SgxEPCDeviceInfoWrapper', @@ -1428,6 +1436,8 @@ ## # @HvBalloonDeviceInfoWrapper: # +# @data: hv-balloon provided memory state information +# # Since: 8.2 ## { 'struct': 'HvBalloonDeviceInfoWrapper', diff --git a/qapi/pragma.json b/qapi/pragma.json index aea6384255..d5e3f6f142 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -52,19 +52,6 @@ 'BlockdevVmdkAdapterType', 'ChardevBackend', 'ChardevBackendKind', - 'ChardevCommonWrapper', - 'ChardevDBusWrapper', - 'ChardevFileWrapper', - 'ChardevHostdevWrapper', - 'ChardevMuxWrapper', - 'ChardevQemuVDAgentWrapper', - 'ChardevRingbufWrapper', - 'ChardevSocketWrapper', - 'ChardevSpiceChannelWrapper', - 'ChardevSpicePortWrapper', - 'ChardevStdioWrapper', - 'ChardevUdpWrapper', - 'ChardevVCWrapper', 'CpuS390Entitlement', 'CpuS390Polarization', 'CpuS390State', @@ -77,24 +64,12 @@ 'GrabToggleKeys', 'GuestPanicInformationHyperV', 'HotKeyMod', - 'HvBalloonDeviceInfoWrapper', 'ImageInfoSpecific', - 'ImageInfoSpecificFileWrapper', 'ImageInfoSpecificKind', - 'ImageInfoSpecificLUKSWrapper', - 'ImageInfoSpecificQCow2Wrapper', - 'ImageInfoSpecificRbdWrapper', - 'ImageInfoSpecificVmdkWrapper', - 'InetSocketAddressWrapper', 'InputAxis', - 'InputBtnEventWrapper', 'InputButton', - 'InputKeyEventWrapper', - 'InputMoveEventWrapper', 'InputMultiTouchEvent', - 'InputMultiTouchEventWrapper', 'InputMultiTouchType', - 'IntWrapper', 'IscsiHeaderDigest', 'IscsiTransport', 'JSONType', @@ -107,18 +82,15 @@ 'NetClientDriver', 'NumaOptions', 'ObjectType', - 'PCDIMMDeviceInfoWrapper', 'PciMemoryRegion', 'QCryptoAkCipherKeyType', 'QCryptoAkCipherOptions', 'QCryptodevBackendServiceType', 'QKeyCode', - 'QKeyCodeWrapper', 'Qcow2OverlapCheckFlags', 'RbdAuthMode', 'RbdEncryptionCreateOptions', 'RbdImageEncryptionFormat', - 'SgxEPCDeviceInfoWrapper', 'SocketAddressLegacy', 'SshHostKeyCheck', 'StatsFilter', @@ -126,16 +98,10 @@ 'String', 'StringWrapper', 'SysEmuTarget', - 'TPMEmulatorOptionsWrapper', - 'TPMPassthroughOptionsWrapper', 'ThrottleGroupProperties', 'TransactionAction', - 'UnixSocketAddressWrapper', - 'VirtioMEMDeviceInfoWrapper', - 'VirtioPMEMDeviceInfoWrapper', 'VncPrimaryAuth', 'VncVencryptSubAuth', - 'VsockSocketAddressWrapper', 'X86CPURegister32', 'XDbgBlockGraph', 'YankInstance', diff --git a/qapi/sockets.json b/qapi/sockets.json index 6213154525..c3b616731d 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -119,6 +119,8 @@ ## # @InetSocketAddressWrapper: # +# @data: internet domain socket address +# # Since: 1.3 ## { 'struct': 'InetSocketAddressWrapper', @@ -127,6 +129,8 @@ ## # @UnixSocketAddressWrapper: # +# @data: UNIX domain socket address +# # Since: 1.3 ## { 'struct': 'UnixSocketAddressWrapper', @@ -135,6 +139,8 @@ ## # @VsockSocketAddressWrapper: # +# @data: VSOCK domain socket address +# # Since: 2.8 ## { 'struct': 'VsockSocketAddressWrapper', diff --git a/qapi/tpm.json b/qapi/tpm.json index a754455ca5..f9c1e866e7 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -102,6 +102,8 @@ ## # @TPMPassthroughOptionsWrapper: # +# @data: Information about the TPM passthrough type +# # Since: 1.5 ## { 'struct': 'TPMPassthroughOptionsWrapper', @@ -111,6 +113,8 @@ ## # @TPMEmulatorOptionsWrapper: # +# @data: Information about the TPM emulator type +# # Since: 2.11 ## { 'struct': 'TPMEmulatorOptionsWrapper', diff --git a/qapi/ui.json b/qapi/ui.json index a0158baf23..1eccad0a83 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -990,6 +990,8 @@ ## # @IntWrapper: # +# @data: a numeric key code +# # Since: 1.3 ## { 'struct': 'IntWrapper', @@ -998,6 +1000,8 @@ ## # @QKeyCodeWrapper: # +# @data: An enumeration of key name +# # Since: 1.3 ## { 'struct': 'QKeyCodeWrapper', @@ -1175,6 +1179,8 @@ ## # @InputKeyEventWrapper: # +# @data: Keyboard input event +# # Since: 2.0 ## { 'struct': 'InputKeyEventWrapper', @@ -1183,6 +1189,8 @@ ## # @InputBtnEventWrapper: # +# @data: Pointer button input event +# # Since: 2.0 ## { 'struct': 'InputBtnEventWrapper', @@ -1191,6 +1199,8 @@ ## # @InputMoveEventWrapper: # +# @data: Pointer motion input event +# # Since: 2.0 ## { 'struct': 'InputMoveEventWrapper', @@ -1199,6 +1209,8 @@ ## # @InputMultiTouchEventWrapper: # +# @data: MultiTouch input event +# # Since: 8.1 ## { 'struct': 'InputMultiTouchEventWrapper', From patchwork Mon Feb 5 07:47:07 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895159 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=aOQ2gB8V; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7v14fvz23g7 for ; Mon, 5 Feb 2024 18:50:35 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtiA-0003Kw-Js; Mon, 05 Feb 2024 02:48:14 -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 1rWthN-00033C-Qa for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -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 1rWthF-00063M-Ge for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:22 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119236; 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=/+Sr868r/4iV4NDQju9I19/S1X0MEXrwFr0PgrOCdX8=; b=aOQ2gB8VgS3UIjwuitdy0ENFnQb/y7d/2gXGs4oj5Wj4KOmjduLY3BCReXiMP4+E7zK+kH WfyVqr0iLlQmR9DROQJDSjPyVG4NqLjQ5A8HJBj40eS3X94f/TiykdyKhxlt3isj2XB4NQ OCDSC0oBrrCdXesD0L7fKv7No6ya7LY= 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-401-p4hB8VYMPfiUKQJos57lng-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: p4hB8VYMPfiUKQJos57lng-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 5530F1C5446A; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 136AF152F; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6AC3C21E5A47; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 13/15] qapi: Improve documentation of file descriptor socket addresses Date: Mon, 5 Feb 2024 08:47:07 +0100 Message-ID: <20240205074709.3613229-14-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org SocketAddress branch @fd is documented in enum SocketAddressType, unlike the other branches. That's because the branch's type is String from common.json. Use a local copy of String, so we can put the documentation in the usual place. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/sockets.json | 40 +++++++++++++++++--------- include/hw/virtio/vhost-vsock-common.h | 1 + chardev/char-socket.c | 2 +- util/qemu-sockets.c | 3 +- 4 files changed, 31 insertions(+), 15 deletions(-) diff --git a/qapi/sockets.json b/qapi/sockets.json index c3b616731d..5e6af5504d 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -5,8 +5,6 @@ # = Socket data types ## -{ 'include': 'common.json' } - ## # @NetworkAddressFamily: # @@ -116,6 +114,24 @@ 'cid': 'str', 'port': 'str' } } +## +# @FdSocketAddress: +# +# A file descriptor name or number. +# +# @str: decimal is for file descriptor number, otherwise it's a file +# descriptor name. Named file descriptors are permitted in +# monitor commands, in combination with the 'getfd' command. +# Decimal file descriptors are permitted at startup or other +# contexts where no monitor context is active. +# +# +# Since: 1.2 +## +{ 'struct': 'FdSocketAddress', + 'data': { + 'str': 'str' } } + ## # @InetSocketAddressWrapper: # @@ -147,12 +163,14 @@ 'data': { 'data': 'VsockSocketAddress' } } ## -# @StringWrapper: +# @FdSocketAddressWrapper: +# +# @data: file descriptor name or number # # Since: 1.3 ## -{ 'struct': 'StringWrapper', - 'data': { 'data': 'String' } } +{ 'struct': 'FdSocketAddressWrapper', + 'data': { 'data': 'FdSocketAddress' } } ## # @SocketAddressLegacy: @@ -173,7 +191,7 @@ 'inet': 'InetSocketAddressWrapper', 'unix': 'UnixSocketAddressWrapper', 'vsock': 'VsockSocketAddressWrapper', - 'fd': 'StringWrapper' } } + 'fd': 'FdSocketAddressWrapper' } } ## # @SocketAddressType: @@ -186,11 +204,7 @@ # # @vsock: VMCI address # -# @fd: decimal is for file descriptor number, otherwise a file -# descriptor name. Named file descriptors are permitted in -# monitor commands, in combination with the 'getfd' command. -# Decimal file descriptors are permitted at startup or other -# contexts where no monitor context is active. +# @fd: Socket file descriptor # # Since: 2.9 ## @@ -200,7 +214,7 @@ ## # @SocketAddress: # -# Captures the address of a socket, which could also be a named file +# Captures the address of a socket, which could also be a socket file # descriptor # # @type: Transport type @@ -213,4 +227,4 @@ 'data': { 'inet': 'InetSocketAddress', 'unix': 'UnixSocketAddress', 'vsock': 'VsockSocketAddress', - 'fd': 'String' } } + 'fd': 'FdSocketAddress' } } diff --git a/include/hw/virtio/vhost-vsock-common.h b/include/hw/virtio/vhost-vsock-common.h index 93c782101d..75a74e8a99 100644 --- a/include/hw/virtio/vhost-vsock-common.h +++ b/include/hw/virtio/vhost-vsock-common.h @@ -11,6 +11,7 @@ #ifndef QEMU_VHOST_VSOCK_COMMON_H #define QEMU_VHOST_VSOCK_COMMON_H +#include "qapi/qapi-types-common.h" #include "hw/virtio/virtio.h" #include "hw/virtio/vhost.h" #include "qom/object.h" diff --git a/chardev/char-socket.c b/chardev/char-socket.c index 73947da188..ff8f845cca 100644 --- a/chardev/char-socket.c +++ b/chardev/char-socket.c @@ -1504,7 +1504,7 @@ static void qemu_chr_parse_socket(QemuOpts *opts, ChardevBackend *backend, }; } else { addr->type = SOCKET_ADDRESS_TYPE_FD; - addr->u.fd.data = g_new(String, 1); + addr->u.fd.data = g_new(FdSocketAddress, 1); addr->u.fd.data->str = g_strdup(fd); } sock->addr = addr; diff --git a/util/qemu-sockets.c b/util/qemu-sockets.c index 83e84b1186..60c44b2b56 100644 --- a/util/qemu-sockets.c +++ b/util/qemu-sockets.c @@ -1464,7 +1464,8 @@ SocketAddress *socket_address_flatten(SocketAddressLegacy *addr_legacy) break; case SOCKET_ADDRESS_TYPE_FD: addr->type = SOCKET_ADDRESS_TYPE_FD; - QAPI_CLONE_MEMBERS(String, &addr->u.fd, addr_legacy->u.fd.data); + QAPI_CLONE_MEMBERS(FdSocketAddress, &addr->u.fd, + addr_legacy->u.fd.data); break; default: abort(); From patchwork Mon Feb 5 07:47:08 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895149 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=MiAgUNBl; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz6X0KSdz23gT for ; Mon, 5 Feb 2024 18:49:24 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtiK-0003bq-W4; Mon, 05 Feb 2024 02:48: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 1rWthP-000362-Bk for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:29 -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 1rWthH-00065n-1s for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119238; 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=PHA7tRn7nUvxem/Uo2QxrW7SfQ3jd87ksTPBsvxVTxk=; b=MiAgUNBlZs0rsagwSqmPSYLJ+kEeJCQszq7ulvgs66c8ZQgVK8XJ7CS8kuahV9lck02Qq/ xmXIecrHnJU1VgCpRK8Sb55KC6y2eSYaItXMpgVp3H9pEQyxMYz5KOcSnSat79AJz/Sc90 RaDbaaifqOSpfd0GoJiE0R+7eYu1+14= 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-421-aqOsMJa1O8CP45Nn2NpQKQ-1; Mon, 05 Feb 2024 02:47:13 -0500 X-MC-Unique: aqOsMJa1O8CP45Nn2NpQKQ-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 3E6DA85A59A; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 17F7F40C9444; Mon, 5 Feb 2024 07:47:12 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6E53921E5A5A; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 14/15] qapi: Move @String out of common.json to discourage reuse Date: Mon, 5 Feb 2024 08:47:08 +0100 Message-ID: <20240205074709.3613229-15-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Use of String is problematic, because it results in awkward interface documentation. The previous commit cleaned up one instance. Move String out of common.json next to its remaining users in net.json to discourage reuse elsewhere. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/common.json | 11 ----------- qapi/net.json | 12 +++++++++++- include/net/filter.h | 2 +- 3 files changed, 12 insertions(+), 13 deletions(-) diff --git a/qapi/common.json b/qapi/common.json index 6fed9cde1a..f1bb841951 100644 --- a/qapi/common.json +++ b/qapi/common.json @@ -51,17 +51,6 @@ { 'enum': 'OnOffSplit', 'data': [ 'on', 'off', 'split' ] } -## -# @String: -# -# A fat type wrapping 'str', to be embedded in lists. -# -# Since: 1.2 -## -{ 'struct': 'String', - 'data': { - 'str': 'str' } } - ## # @StrOrNull: # diff --git a/qapi/net.json b/qapi/net.json index 68493d6ac9..0a993e1a3d 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -6,7 +6,6 @@ # = Net devices ## -{ 'include': 'common.json' } { 'include': 'sockets.json' } ## @@ -105,6 +104,17 @@ '*addr': 'str', '*vectors': 'uint32' } } +## +# @String: +# +# A fat type wrapping 'str', to be embedded in lists. +# +# Since: 1.2 +## +{ 'struct': 'String', + 'data': { + 'str': 'str' } } + ## # @NetdevUserOptions: # diff --git a/include/net/filter.h b/include/net/filter.h index 27ffc630df..f15f7932b2 100644 --- a/include/net/filter.h +++ b/include/net/filter.h @@ -9,7 +9,7 @@ #ifndef QEMU_NET_FILTER_H #define QEMU_NET_FILTER_H -#include "qapi/qapi-types-net.h" +#include "qapi/qapi-types-common.h" #include "qemu/queue.h" #include "qom/object.h" #include "net/queue.h" From patchwork Mon Feb 5 07:47:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 1895158 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=buGNb+OS; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4TSz7p0hd3z23g7 for ; Mon, 5 Feb 2024 18:50:30 +1100 (AEDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rWtiC-0003MK-E8; Mon, 05 Feb 2024 02:48:16 -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 1rWthN-00033G-RE for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:26 -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 1rWthG-000650-B4 for qemu-devel@nongnu.org; Mon, 05 Feb 2024 02:47:23 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1707119237; 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=nisO7NDwANGkx/Ygd8b0iE9B6pGSK738IZE8IpZHy1Y=; b=buGNb+OS9oMinG/Sk28L01J0wDSiNG1rk7/t6dt0M/mfnfnctPAGoMXoV8T2vyFBBhTFWj J60p/GfWajUUHQVo2oHCH0qCf6NAyXn6euQxjfNzZb4nmvDll31mhmB9zHP8fkzg7F5xte kwd3/MySmyisQLIgyn9a4PX9CCxYTQY= 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-662-LQPSFQAgMtOrJsU66NZ-3Q-1; Mon, 05 Feb 2024 02:47:14 -0500 X-MC-Unique: LQPSFQAgMtOrJsU66NZ-3Q-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 445361C54463; Mon, 5 Feb 2024 07:47:13 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.123]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0177A1121313; Mon, 5 Feb 2024 07:47:13 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 71FD121E5A5B; Mon, 5 Feb 2024 08:47:09 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: arei.gonglei@huawei.com, armbru@redhat.com, berrange@redhat.com, eblake@redhat.com, eduardo@habkost.net, fan.ni@samsung.com, farosas@suse.de, hreitz@redhat.com, jasowang@redhat.com, jiri@resnulli.us, jonathan.cameron@huawei.com, kkostiuk@redhat.com, kraxel@redhat.com, kwolf@redhat.com, lukasstraub2@web.de, marcandre.lureau@redhat.com, marcel.apfelbaum@gmail.com, michael.roth@amd.com, mst@redhat.com, pbonzini@redhat.com, peter.maydell@linaro.org, peterx@redhat.com, philmd@linaro.org, pizhenwei@bytedance.com, qemu-block@nongnu.org, stefanb@linux.ibm.com, wangyanan55@huawei.com Subject: [PATCH 15/15] qapi: Add missing union tag documentation Date: Mon, 5 Feb 2024 08:47:09 +0100 Message-ID: <20240205074709.3613229-16-armbru@redhat.com> In-Reply-To: <20240205074709.3613229-1-armbru@redhat.com> References: <20240205074709.3613229-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: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.361, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Low-hanging fruit, and except for StatsFilter, the only members of these unions lacking documentation. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrangé --- qapi/block-core.json | 12 ++++++++++++ qapi/block-export.json | 2 ++ qapi/char.json | 2 ++ qapi/crypto.json | 2 ++ qapi/machine.json | 4 ++++ qapi/migration.json | 2 ++ qapi/pragma.json | 16 ---------------- qapi/sockets.json | 2 ++ qapi/stats.json | 2 ++ qapi/transaction.json | 2 ++ qapi/ui.json | 2 ++ qapi/yank.json | 2 ++ 12 files changed, 34 insertions(+), 16 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 55b583f079..ded6437c06 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -252,6 +252,8 @@ # A discriminated record of image format specific information # structures. # +# @type: block driver name +# # Since: 1.7 ## { 'union': 'ImageInfoSpecific', @@ -1102,6 +1104,8 @@ # # Block driver specific statistics # +# @driver: block driver name +# # Since: 4.2 ## { 'union': 'BlockStatsSpecific', @@ -3472,6 +3476,8 @@ ## # @BlockdevQcowEncryption: # +# @format: encryption format +# # Since: 2.10 ## { 'union': 'BlockdevQcowEncryption', @@ -3506,6 +3512,8 @@ ## # @BlockdevQcow2Encryption: # +# @format: encryption format +# # Since: 2.10 ## { 'union': 'BlockdevQcow2Encryption', @@ -3656,6 +3664,8 @@ ## # @SshHostKeyCheck: # +# @mode: How to check the host key +# # Since: 2.12 ## { 'union': 'SshHostKeyCheck', @@ -4225,6 +4235,8 @@ ## # @RbdEncryptionCreateOptions: # +# @format: Encryption format. +# # Since: 6.1 ## { 'union': 'RbdEncryptionCreateOptions', diff --git a/qapi/block-export.json b/qapi/block-export.json index e063e9255a..d9bd376b48 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -346,6 +346,8 @@ # Describes a block export, i.e. how single node should be exported on # an external interface. # +# @type: Block export type +# # @id: A unique identifier for the block export (across all export # types) # diff --git a/qapi/char.json b/qapi/char.json index e3e1b2c9f5..390e3ef1b9 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -634,6 +634,8 @@ # # Configuration info for the new chardev backend. # +# @type: backend type +# # Since: 1.4 ## { 'union': 'ChardevBackend', diff --git a/qapi/crypto.json b/qapi/crypto.json index fd3d46ebd1..03de66e6f6 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -645,6 +645,8 @@ # The options that are available for all asymmetric key algorithms # when creating a new QCryptoAkCipher. # +# @alg: encryption cipher algorithm +# # Since: 7.1 ## { 'union': 'QCryptoAkCipherOptions', diff --git a/qapi/machine.json b/qapi/machine.json index 6a25e39f44..d816c5c02e 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -443,6 +443,8 @@ # # A discriminated record of NUMA options. (for OptsVisitor) # +# @type: NUMA option type +# # Since: 2.1 ## { 'union': 'NumaOptions', @@ -1448,6 +1450,8 @@ # # Union containing information about a memory device # +# @type: memory device type +# # Since: 2.1 ## { 'union': 'MemoryDeviceInfo', diff --git a/qapi/migration.json b/qapi/migration.json index bf89765a26..7c8881abda 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1630,6 +1630,8 @@ # # Migration endpoint configuration. # +# @transport: The migration stream transport mechanism +# # Since: 8.2 ## { 'union': 'MigrationAddress', diff --git a/qapi/pragma.json b/qapi/pragma.json index d5e3f6f142..7ac05ccc26 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -39,18 +39,13 @@ 'BlockDirtyBitmapAddWrapper', 'BlockDirtyBitmapMergeWrapper', 'BlockDirtyBitmapWrapper', - 'BlockExportOptions', - 'BlockStatsSpecific', 'BlockdevBackupWrapper', 'BlockdevDriver', - 'BlockdevQcow2Encryption', 'BlockdevQcow2EncryptionFormat', - 'BlockdevQcowEncryption', 'BlockdevSnapshotInternalWrapper', 'BlockdevSnapshotSyncWrapper', 'BlockdevSnapshotWrapper', 'BlockdevVmdkAdapterType', - 'ChardevBackend', 'ChardevBackendKind', 'CpuS390Entitlement', 'CpuS390Polarization', @@ -64,7 +59,6 @@ 'GrabToggleKeys', 'GuestPanicInformationHyperV', 'HotKeyMod', - 'ImageInfoSpecific', 'ImageInfoSpecificKind', 'InputAxis', 'InputButton', @@ -73,38 +67,28 @@ 'IscsiHeaderDigest', 'IscsiTransport', 'JSONType', - 'KeyValue', 'KeyValueKind', - 'MemoryDeviceInfo', 'MemoryDeviceInfoKind', 'MigrateSetParameters', - 'MigrationAddress', 'NetClientDriver', - 'NumaOptions', 'ObjectType', 'PciMemoryRegion', 'QCryptoAkCipherKeyType', - 'QCryptoAkCipherOptions', 'QCryptodevBackendServiceType', 'QKeyCode', 'Qcow2OverlapCheckFlags', 'RbdAuthMode', - 'RbdEncryptionCreateOptions', 'RbdImageEncryptionFormat', - 'SocketAddressLegacy', - 'SshHostKeyCheck', 'StatsFilter', 'StatsValue', 'String', 'StringWrapper', 'SysEmuTarget', 'ThrottleGroupProperties', - 'TransactionAction', 'VncPrimaryAuth', 'VncVencryptSubAuth', 'X86CPURegister32', 'XDbgBlockGraph', - 'YankInstance', 'YankInstanceType', 'blockdev-reopen', 'query-cpu-model-baseline', diff --git a/qapi/sockets.json b/qapi/sockets.json index 5e6af5504d..ef777928e7 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -178,6 +178,8 @@ # Captures the address of a socket, which could also be a named file # descriptor # +# @type: Transport type +# # Note: This type is deprecated in favor of SocketAddress. The # difference between SocketAddressLegacy and SocketAddress is that # the latter has fewer {} on the wire. diff --git a/qapi/stats.json b/qapi/stats.json index 01791e86d5..ce9d8161ec 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -120,6 +120,8 @@ # - which providers to request statistics from # - which named values to return within each provider # +# @target: the kind of objects to query +# # Since: 7.1 ## { 'union': 'StatsFilter', diff --git a/qapi/transaction.json b/qapi/transaction.json index cffee2de28..7a95c081e9 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -158,6 +158,8 @@ # A discriminated record of operations that can be performed with # @transaction. # +# @type: the operation to be performed +# # Since: 1.1 ## { 'union': 'TransactionAction', diff --git a/qapi/ui.json b/qapi/ui.json index 1eccad0a83..b6d7e142b7 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1012,6 +1012,8 @@ # # Represents a keyboard key. # +# @type: key encoding +# # Since: 1.3 ## { 'union': 'KeyValue', diff --git a/qapi/yank.json b/qapi/yank.json index bfc71a07a6..ee038a11a1 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -49,6 +49,8 @@ # A yank instance can be yanked with the @yank qmp command to recover # from a hanging QEMU. # +# @type: yank instance type +# # Currently implemented yank instances: # # - nbd block device: Yanking it will shut down the connection to the