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 BD8DCC433F5 for ; Mon, 20 Sep 2021 07:51:17 +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 24D5D60F23 for ; Mon, 20 Sep 2021 07:51:17 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 24D5D60F23 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]:54168 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mSE55-0001Ge-TT for qemu-devel@archiver.kernel.org; Mon, 20 Sep 2021 03:51:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:44222) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mSDwg-0005vQ-BL for qemu-devel@nongnu.org; Mon, 20 Sep 2021 03:42:34 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:27072) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mSDwa-00068r-Uy for qemu-devel@nongnu.org; Mon, 20 Sep 2021 03:42:34 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1632123747; 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=aGlG6X5zcUZtapoVEQwyZKqVBM2S7spm5mEeLF3p9bw=; b=PLZinzAeN9RsQQnYwrwfOt4ucJMGJ1YDJp/6c9Msku4HDte+cTdqKwV/jdmp9SaWXJIyST G8CFKoMYAgJqrMcU1D3Ej6K25FLovLsS2eJ84SJtuH23WuqANmkTAEwGTzjYmUe3PKV8zQ lQrX5MoP0eSU0mHSEDT9IT8tS8+F3Hs= 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-454-LKFaFSimN2OT3AduqAExgA-1; Mon, 20 Sep 2021 03:42:26 -0400 X-MC-Unique: LKFaFSimN2OT3AduqAExgA-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 3168718414C4; Mon, 20 Sep 2021 07:42:22 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-14.ams2.redhat.com [10.36.112.14]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2C00A5D9DC; Mon, 20 Sep 2021 07:42:04 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B4D3A113865F; Mon, 20 Sep 2021 09:42:02 +0200 (CEST) From: Markus Armbruster To: Daniel P. =?utf-8?Q?Berrang=C3=A9?= Subject: Re: [PATCH v2 01/53] docs/devel: rename file for writing monitor commands References: <20210914142042.1655100-1-berrange@redhat.com> <20210914142042.1655100-2-berrange@redhat.com> Date: Mon, 20 Sep 2021 09:42:02 +0200 In-Reply-To: <20210914142042.1655100-2-berrange@redhat.com> ("Daniel P. =?utf-8?Q?Berrang=C3=A9=22's?= message of "Tue, 14 Sep 2021 15:19:50 +0100") Message-ID: <87a6k74rsl.fsf@dusky.pond.sub.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) 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=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) DKIMWL_WL_HIGH=-1.476, 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=unavailable 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 , qemu-devel@nongnu.org, Laurent Vivier , Max Filippov , Taylor Simpson , Alistair Francis , Gerd Hoffmann , "Edgar E. Iglesias" , Eric Blake , Marek Vasut , Yoshinori Sato , Halil Pasic , Christian Borntraeger , Palmer Dabbelt , Artyom Tarasenko , Laurent Vivier , Thomas Huth , Eduardo Habkost , Richard Henderson , Greg Kurz , Yuval Shaia , qemu-s390x@nongnu.org, qemu-arm@nongnu.org, Michael Rolnik , Peter Xu , Stafford Horne , David Gibson , qemu-riscv@nongnu.org, Bastian Koppelmann , Cornelia Huck , Philippe =?utf-8?Q?Mathieu-Daud=C3=A9?= , qemu-ppc@nongnu.org, Aurelien Jarno , Paolo Bonzini , Aleksandar Rikalo , "Dr. David Alan Gilbert" Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" Daniel P. Berrang=C3=A9 writes: > The file already covers writing new style HMP commands, in addition to > the QMP commands, so it deserves a more general name. > > Signed-off-by: Daniel P. Berrang=C3=A9 > --- > docs/devel/index.rst | 2 +- > ...riting-qmp-commands.rst =3D> writing-monitor-commands.rst} | 6 +++--- > 2 files changed, 4 insertions(+), 4 deletions(-) > rename docs/devel/{writing-qmp-commands.rst =3D> writing-monitor-command= s.rst} (99%) > > diff --git a/docs/devel/index.rst b/docs/devel/index.rst > index f95df10b3e..7c25177c5d 100644 > --- a/docs/devel/index.rst > +++ b/docs/devel/index.rst > @@ -44,4 +44,4 @@ modifying QEMU's source code. > ebpf_rss > vfio-migration > qapi-code-gen > - writing-qmp-commands > + writing-monitor-commands > diff --git a/docs/devel/writing-qmp-commands.rst b/docs/devel/writing-mon= itor-commands.rst > similarity index 99% > rename from docs/devel/writing-qmp-commands.rst > rename to docs/devel/writing-monitor-commands.rst > index 6a10a06c48..497c9ce0d5 100644 > --- a/docs/devel/writing-qmp-commands.rst > +++ b/docs/devel/writing-monitor-commands.rst > @@ -1,8 +1,8 @@ > -How to write QMP commands using the QAPI framework > -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D > +How to write monitor commands > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > =20 > This document is a step-by-step guide on how to write new QMP commands u= sing > -the QAPI framework. It also shows how to implement new style HMP command= s. > +the QAPI framework and new style HMP commands. Recommend to drop "new style", here and in the commit message. Back when this file was written, we did have several "styles" of HMP commands: typedef struct mon_cmd_t { const char *name; const char *args_type; const char *params; const char *help; void (*user_print)(Monitor *mon, const QObject *data); union { void (*info)(Monitor *mon); void (*cmd)(Monitor *mon, const QDict *qdict); int (*cmd_new)(Monitor *mon, const QDict *params, QObject **re= t_data); int (*cmd_async)(Monitor *mon, const QDict *params, MonitorCompletion *cb, void *opaque); } mhandler; bool qapi; int flags; } mon_cmd_t; [...] static void handle_user_command(Monitor *mon, const char *cmdline) { QDict *qdict; const mon_cmd_t *cmd; qdict =3D qdict_new(); cmd =3D monitor_parse_command(mon, cmdline, qdict); if (!cmd) goto out; if (handler_is_async(cmd)) { user_async_cmd_handler(mon, cmd, qdict); } else if (handler_is_qobject(cmd)) { QObject *data =3D NULL; /* XXX: ignores the error code */ cmd->mhandler.cmd_new(mon, qdict, &data); assert(!monitor_has_error(mon)); if (data) { cmd->user_print(mon, data); qobject_decref(data); } } else { cmd->mhandler.cmd(mon, qdict); } out: QDECREF(qdict); } Async: add MONITOR_CMD_ASYNC to ->flags, use ->mhandler.async(). New: set ->user_print and ->mhandler.cmd_new. Old: keep ->user_print() null, and set ->mhandler.cmd(). "Async" style never really worked, and was buried in commit 65207c59d9 "monitor: Drop broken, unused asynchronous command interface". "New" style was buried in commit 8a4f501c09 "monitor: Drop unused "new" HMP command interface". Both burials got merged into master in June 2015. "Old" style has been the only style since then. > This document doesn't discuss QMP protocol level details, nor does it di= ve > into the QAPI framework implementation. From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.90_1) id 1mSDwi-0005wz-Uq for mharc-qemu-riscv@gnu.org; Mon, 20 Sep 2021 03:42:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:44218) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mSDwf-0005uA-OT for qemu-riscv@nongnu.org; Mon, 20 Sep 2021 03:42:33 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:27932) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mSDwb-00068q-0j for qemu-riscv@nongnu.org; Mon, 20 Sep 2021 03:42:33 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1632123747; 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=aGlG6X5zcUZtapoVEQwyZKqVBM2S7spm5mEeLF3p9bw=; b=PLZinzAeN9RsQQnYwrwfOt4ucJMGJ1YDJp/6c9Msku4HDte+cTdqKwV/jdmp9SaWXJIyST G8CFKoMYAgJqrMcU1D3Ej6K25FLovLsS2eJ84SJtuH23WuqANmkTAEwGTzjYmUe3PKV8zQ lQrX5MoP0eSU0mHSEDT9IT8tS8+F3Hs= 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-454-LKFaFSimN2OT3AduqAExgA-1; Mon, 20 Sep 2021 03:42:26 -0400 X-MC-Unique: LKFaFSimN2OT3AduqAExgA-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 3168718414C4; Mon, 20 Sep 2021 07:42:22 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-14.ams2.redhat.com [10.36.112.14]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2C00A5D9DC; Mon, 20 Sep 2021 07:42:04 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B4D3A113865F; Mon, 20 Sep 2021 09:42:02 +0200 (CEST) From: Markus Armbruster To: Daniel P. =?utf-8?Q?Berrang=C3=A9?= Cc: qemu-devel@nongnu.org, 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 , Philippe =?utf-8?Q?Mathieu-Daud=C3=A9?= , Thomas Huth , Aleksandar Rikalo , David Gibson , Marcel Apfelbaum , Laurent Vivier , "Dr. David Alan Gilbert" , Eduardo Habkost , Marek Vasut , Aurelien Jarno , qemu-s390x@nongnu.org, Laurent Vivier , Eric Blake , Richard Henderson , Chris Wulff Subject: Re: [PATCH v2 01/53] docs/devel: rename file for writing monitor commands References: <20210914142042.1655100-1-berrange@redhat.com> <20210914142042.1655100-2-berrange@redhat.com> Date: Mon, 20 Sep 2021 09:42:02 +0200 In-Reply-To: <20210914142042.1655100-2-berrange@redhat.com> ("Daniel P. =?utf-8?Q?Berrang=C3=A9=22's?= message of "Tue, 14 Sep 2021 15:19:50 +0100") Message-ID: <87a6k74rsl.fsf@dusky.pond.sub.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) 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=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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: -42 X-Spam_score: -4.3 X-Spam_bar: ---- X-Spam_report: (-4.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.476, 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=unavailable 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: Mon, 20 Sep 2021 07:42:34 -0000 Daniel P. Berrang=C3=A9 writes: > The file already covers writing new style HMP commands, in addition to > the QMP commands, so it deserves a more general name. > > Signed-off-by: Daniel P. Berrang=C3=A9 > --- > docs/devel/index.rst | 2 +- > ...riting-qmp-commands.rst =3D> writing-monitor-commands.rst} | 6 +++--- > 2 files changed, 4 insertions(+), 4 deletions(-) > rename docs/devel/{writing-qmp-commands.rst =3D> writing-monitor-command= s.rst} (99%) > > diff --git a/docs/devel/index.rst b/docs/devel/index.rst > index f95df10b3e..7c25177c5d 100644 > --- a/docs/devel/index.rst > +++ b/docs/devel/index.rst > @@ -44,4 +44,4 @@ modifying QEMU's source code. > ebpf_rss > vfio-migration > qapi-code-gen > - writing-qmp-commands > + writing-monitor-commands > diff --git a/docs/devel/writing-qmp-commands.rst b/docs/devel/writing-mon= itor-commands.rst > similarity index 99% > rename from docs/devel/writing-qmp-commands.rst > rename to docs/devel/writing-monitor-commands.rst > index 6a10a06c48..497c9ce0d5 100644 > --- a/docs/devel/writing-qmp-commands.rst > +++ b/docs/devel/writing-monitor-commands.rst > @@ -1,8 +1,8 @@ > -How to write QMP commands using the QAPI framework > -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D > +How to write monitor commands > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > =20 > This document is a step-by-step guide on how to write new QMP commands u= sing > -the QAPI framework. It also shows how to implement new style HMP command= s. > +the QAPI framework and new style HMP commands. Recommend to drop "new style", here and in the commit message. Back when this file was written, we did have several "styles" of HMP commands: typedef struct mon_cmd_t { const char *name; const char *args_type; const char *params; const char *help; void (*user_print)(Monitor *mon, const QObject *data); union { void (*info)(Monitor *mon); void (*cmd)(Monitor *mon, const QDict *qdict); int (*cmd_new)(Monitor *mon, const QDict *params, QObject **re= t_data); int (*cmd_async)(Monitor *mon, const QDict *params, MonitorCompletion *cb, void *opaque); } mhandler; bool qapi; int flags; } mon_cmd_t; [...] static void handle_user_command(Monitor *mon, const char *cmdline) { QDict *qdict; const mon_cmd_t *cmd; qdict =3D qdict_new(); cmd =3D monitor_parse_command(mon, cmdline, qdict); if (!cmd) goto out; if (handler_is_async(cmd)) { user_async_cmd_handler(mon, cmd, qdict); } else if (handler_is_qobject(cmd)) { QObject *data =3D NULL; /* XXX: ignores the error code */ cmd->mhandler.cmd_new(mon, qdict, &data); assert(!monitor_has_error(mon)); if (data) { cmd->user_print(mon, data); qobject_decref(data); } } else { cmd->mhandler.cmd(mon, qdict); } out: QDECREF(qdict); } Async: add MONITOR_CMD_ASYNC to ->flags, use ->mhandler.async(). New: set ->user_print and ->mhandler.cmd_new. Old: keep ->user_print() null, and set ->mhandler.cmd(). "Async" style never really worked, and was buried in commit 65207c59d9 "monitor: Drop broken, unused asynchronous command interface". "New" style was buried in commit 8a4f501c09 "monitor: Drop unused "new" HMP command interface". Both burials got merged into master in June 2015. "Old" style has been the only style since then. > This document doesn't discuss QMP protocol level details, nor does it di= ve > into the QAPI framework implementation.