From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-13.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id C3030C433F5 for ; Tue, 14 Sep 2021 14:29:44 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 3B02860FC0 for ; Tue, 14 Sep 2021 14:29:44 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 3B02860FC0 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=nongnu.org Received: from localhost ([::1]:57094 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mQ9RP-0003wu-7k for qemu-devel@archiver.kernel.org; Tue, 14 Sep 2021 10:29:43 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34514) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Kd-0001dx-LQ for qemu-devel@nongnu.org; Tue, 14 Sep 2021 10:22:43 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:30752) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Ka-00049F-Fc for qemu-devel@nongnu.org; Tue, 14 Sep 2021 10:22:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1631629359; 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=AKQ5Y6mKD8eeLMm/8Vj1U//cSS0HbEG9luA/4D8pINQ=; b=F1X8741Gv376tfj200L2vmhX2xs/UeoRrR6bX57kDAut85Jx4UA4ylku2dxcD3Dijki9FU BLBKwawbiX7bzfLDwIzaz2FWJOFgMOLtcpFWPjf32C942dzGjvanagR5uShZeOCBlQrouW RwGIv3AiNuHrytQqFejoFL+ezunkMac= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-451-3kvnxxzgOzWlZw_UBtYRjQ-1; Tue, 14 Sep 2021 10:22:38 -0400 X-MC-Unique: 3kvnxxzgOzWlZw_UBtYRjQ-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 1E49B1084681; Tue, 14 Sep 2021 14:22:34 +0000 (UTC) Received: from localhost.localdomain.com (unknown [10.39.193.47]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0E5B55D9CA; Tue, 14 Sep 2021 14:22:15 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Subject: [PATCH v2 04/53] docs/devel: add example of command returning unstructured text Date: Tue, 14 Sep 2021 15:19:53 +0100 Message-Id: <20210914142042.1655100-5-berrange@redhat.com> In-Reply-To: <20210914142042.1655100-1-berrange@redhat.com> References: <20210914142042.1655100-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=berrange@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=216.205.24.124; envelope-from=berrange@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -31 X-Spam_score: -3.2 X-Spam_bar: --- X-Spam_report: (-3.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.398, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Chris Wulff , David Hildenbrand , Bin Meng , Mark Cave-Ayland , Yuval Shaia , Laurent Vivier , Max Filippov , Taylor Simpson , Alistair Francis , Gerd Hoffmann , "Edgar E. Iglesias" , Eric Blake , Marek Vasut , Yoshinori Sato , Markus Armbruster , Halil Pasic , Christian Borntraeger , Palmer Dabbelt , Artyom Tarasenko , Laurent Vivier , Thomas Huth , Eduardo Habkost , Richard Henderson , Greg Kurz , "Dr. David Alan Gilbert" , qemu-s390x@nongnu.org, qemu-arm@nongnu.org, Michael Rolnik , Peter Xu , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Stafford Horne , David Gibson , qemu-riscv@nongnu.org, Bastian Koppelmann , Cornelia Huck , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , qemu-ppc@nongnu.org, Paolo Bonzini , Aleksandar Rikalo , Aurelien Jarno Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" This illustrates how to add a QMP command returning unstructured text, following the guidelines added in the previous patch. The example uses a simplified version of 'info roms'. Signed-off-by: Daniel P. Berrangé --- docs/devel/writing-monitor-commands.rst | 85 +++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index d68c552fdd..4cf51ab557 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -647,3 +647,88 @@ has to traverse the list, it's shown below for reference:: qapi_free_TimerAlarmMethodList(method_list); } + +Writing a debugging aid returning unstructured text +--------------------------------------------------- + +As discussed at the start of the previous example, it is required that +commands expecting machine usage be using fine-grained QAPI data types. +The exception to this rule applies when the command is solely intended +as a debugging aid and allows for returning unstructured text. This is +commonly needed for query commands that report aspects of QEMU's +internal state that are useful to human operators. + +In this example we will consider a simplified variant of the HMP +command ``info roms``. Following the earlier rules, this command will +need to live under the ``x-`` name prefix, so its QMP implementation +will be called ``x-query-roms``. It will have no parameters and will +return a single text string:: + + { 'struct': 'HumanReadableText', + 'data': { 'human-readable-text': 'str' } } + + { 'command': 'x-query-roms', + 'returns': 'HumanReadableText' } + +The ``HumanReadableText`` struct is intended to be used for all +commands, under the ``x-`` name prefix that are returning unstructured +text targetted at humans. It should never be used for commands outside +the ``x-`` name prefix, as those should be using structured QAPI types. + +Implementing the QMP command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The QMP implementation will typically involve creating a ``GString`` +object and printing formatted data into it:: + + HumanReadableText *qmp_x_query_roms(Error **errp) + { + GString buf = g_string_new(""); + HumanReadableText ret = g_new0(HumanReadableText, 1); + Rom *rom; + + QTAILQ_FOREACH(rom, &roms, next) { + g_string_append_printf("%s size=0x%06zx name=\"%s\"\n", + memory_region_name(rom->mr), + rom->romsize, + rom->name); + } + + ret->human_readable_text = g_string_free(buf, FALSE); + + return ret; + } + + +Implementing the HMP command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that the QMP command is in place, we can also make it available in +the human monitor (HMP) as shown in previous examples. The HMP +implementations will all look fairly similar, as all they need do is +invoke the QMP command and then print the resulting text or error +message. Here's the implementation of the "info roms" HMP command:: + + void hmp_info_roms(Monitor *mon, const QDict *qdict) + { + Error err = NULL; + g_autoptr(HumanReadableText) info = qmp_x_query_roms(&err); + if (err) { + error_report_err(err); + return; + } + monitor_printf(mon, "%s\n", info->human_readable_text); + } + +Also, you have to add the function's prototype to the hmp.h file. + +There's one last step to actually make the command available to +monitor users, we should add it to the hmp-commands-info.hx file:: + + { + .name = "roms", + .args_type = "", + .params = "", + .help = "show roms", + .cmd = hmp_info_roms, + }, -- 2.31.1 From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.90_1) id 1mQ9Kf-0001mv-OB for mharc-qemu-riscv@gnu.org; Tue, 14 Sep 2021 10:22:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34518) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Kd-0001eA-MO for qemu-riscv@nongnu.org; Tue, 14 Sep 2021 10:22:43 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:28180) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Ka-00049G-Gx for qemu-riscv@nongnu.org; Tue, 14 Sep 2021 10:22:43 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1631629359; 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=AKQ5Y6mKD8eeLMm/8Vj1U//cSS0HbEG9luA/4D8pINQ=; b=F1X8741Gv376tfj200L2vmhX2xs/UeoRrR6bX57kDAut85Jx4UA4ylku2dxcD3Dijki9FU BLBKwawbiX7bzfLDwIzaz2FWJOFgMOLtcpFWPjf32C942dzGjvanagR5uShZeOCBlQrouW RwGIv3AiNuHrytQqFejoFL+ezunkMac= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-451-3kvnxxzgOzWlZw_UBtYRjQ-1; Tue, 14 Sep 2021 10:22:38 -0400 X-MC-Unique: 3kvnxxzgOzWlZw_UBtYRjQ-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 1E49B1084681; Tue, 14 Sep 2021 14:22:34 +0000 (UTC) Received: from localhost.localdomain.com (unknown [10.39.193.47]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0E5B55D9CA; Tue, 14 Sep 2021 14:22:15 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Cc: Greg Kurz , Bin Meng , Yoshinori Sato , Stafford Horne , Cornelia Huck , David Hildenbrand , "Edgar E. Iglesias" , Jiaxun Yang , Peter Xu , Christian Borntraeger , qemu-ppc@nongnu.org, Mark Cave-Ayland , Paolo Bonzini , qemu-arm@nongnu.org, Michael Rolnik , Peter Maydell , Palmer Dabbelt , Alistair Francis , Halil Pasic , Taylor Simpson , Gerd Hoffmann , qemu-riscv@nongnu.org, Max Filippov , Yuval Shaia , Bastian Koppelmann , Artyom Tarasenko , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Thomas Huth , Aleksandar Rikalo , David Gibson , Marcel Apfelbaum , Laurent Vivier , "Dr. David Alan Gilbert" , Eduardo Habkost , Marek Vasut , Markus Armbruster , Aurelien Jarno , qemu-s390x@nongnu.org, Laurent Vivier , Eric Blake , Richard Henderson , Chris Wulff , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH v2 04/53] docs/devel: add example of command returning unstructured text Date: Tue, 14 Sep 2021 15:19:53 +0100 Message-Id: <20210914142042.1655100-5-berrange@redhat.com> In-Reply-To: <20210914142042.1655100-1-berrange@redhat.com> References: <20210914142042.1655100-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=berrange@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=216.205.24.124; envelope-from=berrange@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -31 X-Spam_score: -3.2 X-Spam_bar: --- X-Spam_report: (-3.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.398, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-riscv@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 14 Sep 2021 14:22:44 -0000 This illustrates how to add a QMP command returning unstructured text, following the guidelines added in the previous patch. The example uses a simplified version of 'info roms'. Signed-off-by: Daniel P. Berrangé --- docs/devel/writing-monitor-commands.rst | 85 +++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index d68c552fdd..4cf51ab557 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -647,3 +647,88 @@ has to traverse the list, it's shown below for reference:: qapi_free_TimerAlarmMethodList(method_list); } + +Writing a debugging aid returning unstructured text +--------------------------------------------------- + +As discussed at the start of the previous example, it is required that +commands expecting machine usage be using fine-grained QAPI data types. +The exception to this rule applies when the command is solely intended +as a debugging aid and allows for returning unstructured text. This is +commonly needed for query commands that report aspects of QEMU's +internal state that are useful to human operators. + +In this example we will consider a simplified variant of the HMP +command ``info roms``. Following the earlier rules, this command will +need to live under the ``x-`` name prefix, so its QMP implementation +will be called ``x-query-roms``. It will have no parameters and will +return a single text string:: + + { 'struct': 'HumanReadableText', + 'data': { 'human-readable-text': 'str' } } + + { 'command': 'x-query-roms', + 'returns': 'HumanReadableText' } + +The ``HumanReadableText`` struct is intended to be used for all +commands, under the ``x-`` name prefix that are returning unstructured +text targetted at humans. It should never be used for commands outside +the ``x-`` name prefix, as those should be using structured QAPI types. + +Implementing the QMP command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The QMP implementation will typically involve creating a ``GString`` +object and printing formatted data into it:: + + HumanReadableText *qmp_x_query_roms(Error **errp) + { + GString buf = g_string_new(""); + HumanReadableText ret = g_new0(HumanReadableText, 1); + Rom *rom; + + QTAILQ_FOREACH(rom, &roms, next) { + g_string_append_printf("%s size=0x%06zx name=\"%s\"\n", + memory_region_name(rom->mr), + rom->romsize, + rom->name); + } + + ret->human_readable_text = g_string_free(buf, FALSE); + + return ret; + } + + +Implementing the HMP command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that the QMP command is in place, we can also make it available in +the human monitor (HMP) as shown in previous examples. The HMP +implementations will all look fairly similar, as all they need do is +invoke the QMP command and then print the resulting text or error +message. Here's the implementation of the "info roms" HMP command:: + + void hmp_info_roms(Monitor *mon, const QDict *qdict) + { + Error err = NULL; + g_autoptr(HumanReadableText) info = qmp_x_query_roms(&err); + if (err) { + error_report_err(err); + return; + } + monitor_printf(mon, "%s\n", info->human_readable_text); + } + +Also, you have to add the function's prototype to the hmp.h file. + +There's one last step to actually make the command available to +monitor users, we should add it to the hmp-commands-info.hx file:: + + { + .name = "roms", + .args_type = "", + .params = "", + .help = "show roms", + .cmd = hmp_info_roms, + }, -- 2.31.1