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 34F9EC433F5 for ; Tue, 14 Sep 2021 14:37:41 +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 DD8FB610A2 for ; Tue, 14 Sep 2021 14:37:40 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org DD8FB610A2 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]:46342 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mQ9Z6-0008L7-5Y for qemu-devel@archiver.kernel.org; Tue, 14 Sep 2021 10:37:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34592) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Km-0001wQ-7c for qemu-devel@nongnu.org; Tue, 14 Sep 2021 10:22:52 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:53293) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Ki-0004Fu-O3 for qemu-devel@nongnu.org; Tue, 14 Sep 2021 10:22:52 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1631629367; 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=hnAoCdun/m6178yZjeWVfAYiK2xccClT/ddcqgE1vOc=; b=FGOP64Fvs/nl8G9/dB995ESfDBN5MIczfs2NBRZ/CDniTE7JtO0oWD+rjJLJaTLcqm833S S/hS1P8akCpkb6SJDdJB/HjkL9XCflEV4VxKV2By4MIz4blsfgtXUnRk7c6ekqrWuAEy3c RlNs/sAHIa7+kg+eKwINkxR0DdpRoQc= 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-16-CmXhOXUDPVO6dPAWyAYScw-1; Tue, 14 Sep 2021 10:22:45 -0400 X-MC-Unique: CmXhOXUDPVO6dPAWyAYScw-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 0A83A1006AA5; Tue, 14 Sep 2021 14:22:42 +0000 (UTC) Received: from localhost.localdomain.com (unknown [10.39.193.47]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6A7495D9CA; Tue, 14 Sep 2021 14:22:34 +0000 (UTC) From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: qemu-devel@nongnu.org Subject: [PATCH v2 05/53] docs/devel: document expectations for HMP commands in the future Date: Tue, 14 Sep 2021 15:19:54 +0100 Message-Id: <20210914142042.1655100-6-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=170.10.133.124; envelope-from=berrange@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -12 X-Spam_score: -1.3 X-Spam_bar: - X-Spam_report: (-1.3 / 5.0 requ) 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=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 , 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" We no longer wish to have commands implemented in HMP only. All commands should start with a QMP implementation and the HMP merely be a shim around this. To reduce the burden of implementing QMP commands where there is low expectation of machine usage, requirements for QAPI modelling are relaxed provided the command is under the "x-" name prefix. Signed-off-by: Daniel P. Berrangé --- docs/devel/writing-monitor-commands.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index 4cf51ab557..983130a793 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -11,6 +11,16 @@ For an in-depth introduction to the QAPI framework, please refer to docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol, start with docs/interop/qmp-intro.txt. +Historically QEMU has permitted new monitor commands to be implemented in HMP +only, QMP only, or both, depending on whether they needed to be accessible to +human operators, machines, or both. When both QMP and HMP are implemented it +is expected the HMP implementation is a shim around the QMP implementation. +Going forward, the expectation is that new commands are implemented in QMP +only, or both QMP and HMP. No further commands are to be added to HMP only. +The long term goal is that all HMP commands will be implemented in terms of +their QMP equivalent, enabling internals of QEMU to be fully isolated from +the HMP implementation. Refer to the later topic on modelling data in QAPI +for further guidance on commands that would have traditionally been HMP only. Overview -------- -- 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 1mQ9Kq-00021d-Ut for mharc-qemu-riscv@gnu.org; Tue, 14 Sep 2021 10:22:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34590) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Km-0001wP-5P for qemu-riscv@nongnu.org; Tue, 14 Sep 2021 10:22:52 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:53665) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQ9Ki-0004Fw-Nk for qemu-riscv@nongnu.org; Tue, 14 Sep 2021 10:22:51 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1631629367; 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=hnAoCdun/m6178yZjeWVfAYiK2xccClT/ddcqgE1vOc=; b=FGOP64Fvs/nl8G9/dB995ESfDBN5MIczfs2NBRZ/CDniTE7JtO0oWD+rjJLJaTLcqm833S S/hS1P8akCpkb6SJDdJB/HjkL9XCflEV4VxKV2By4MIz4blsfgtXUnRk7c6ekqrWuAEy3c RlNs/sAHIa7+kg+eKwINkxR0DdpRoQc= 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-16-CmXhOXUDPVO6dPAWyAYScw-1; Tue, 14 Sep 2021 10:22:45 -0400 X-MC-Unique: CmXhOXUDPVO6dPAWyAYScw-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 0A83A1006AA5; Tue, 14 Sep 2021 14:22:42 +0000 (UTC) Received: from localhost.localdomain.com (unknown [10.39.193.47]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6A7495D9CA; Tue, 14 Sep 2021 14:22:34 +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 05/53] docs/devel: document expectations for HMP commands in the future Date: Tue, 14 Sep 2021 15:19:54 +0100 Message-Id: <20210914142042.1655100-6-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=170.10.133.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=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: Tue, 14 Sep 2021 14:22:52 -0000 We no longer wish to have commands implemented in HMP only. All commands should start with a QMP implementation and the HMP merely be a shim around this. To reduce the burden of implementing QMP commands where there is low expectation of machine usage, requirements for QAPI modelling are relaxed provided the command is under the "x-" name prefix. Signed-off-by: Daniel P. Berrangé --- docs/devel/writing-monitor-commands.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst index 4cf51ab557..983130a793 100644 --- a/docs/devel/writing-monitor-commands.rst +++ b/docs/devel/writing-monitor-commands.rst @@ -11,6 +11,16 @@ For an in-depth introduction to the QAPI framework, please refer to docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol, start with docs/interop/qmp-intro.txt. +Historically QEMU has permitted new monitor commands to be implemented in HMP +only, QMP only, or both, depending on whether they needed to be accessible to +human operators, machines, or both. When both QMP and HMP are implemented it +is expected the HMP implementation is a shim around the QMP implementation. +Going forward, the expectation is that new commands are implemented in QMP +only, or both QMP and HMP. No further commands are to be added to HMP only. +The long term goal is that all HMP commands will be implemented in terms of +their QMP equivalent, enabling internals of QEMU to be fully isolated from +the HMP implementation. Refer to the later topic on modelling data in QAPI +for further guidance on commands that would have traditionally been HMP only. Overview -------- -- 2.31.1