From patchwork Tue Sep 29 20:18:58 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304124 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 E9BB6C4727C for ; Tue, 29 Sep 2020 20:21:39 +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 52C992076B for ; Tue, 29 Sep 2020 20:21:39 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="TbhFWeIm" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 52C992076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:60118 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNM82-0003Xw-8O for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:21:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59564) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM63-0001kV-1i for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:35 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:44224) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM60-0003Sj-Pg for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:34 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410771; 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=by3mjscHzH8BrvrziJQjGxD6sRKUaSNInuuU6bh+wgE=; b=TbhFWeImOdJgysY3DdWhHrS/CopOrdIpCsLf+lj20NlPrksi5Ngk/mpeFsO6yhXQ5avFt2 Mdfojyyzk+bJVXI6GRsS5+t7JNxqFc23dTWzkqpXHRUXxQjZzDBkfTOf+E8+plZyvqeq8C kHoYAD/6Q2NQcpedkpYfbPHZDR1NIVE= 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-168-I6Tb2dknOKuk81D5jRqiuw-1; Tue, 29 Sep 2020 16:19:29 -0400 X-MC-Unique: I6Tb2dknOKuk81D5jRqiuw-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 5DC9118BE160; Tue, 29 Sep 2020 20:19:28 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0783D19C4F; Tue, 29 Sep 2020 20:19:28 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 8F11B11386A0; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 01/29] qapi: Restrict LostTickPolicy enum to machine code Date: Tue, 29 Sep 2020 22:18:58 +0200 Message-Id: <20200929201926.2155622-2-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Paolo Bonzini Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé Restricting LostTickPolicy to machine.json pulls slightly less QAPI-generated code into user-mode. Acked-by: Markus Armbruster Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-2-philmd@redhat.com> [Add rationale to commit message] Signed-off-by: Markus Armbruster --- qapi/machine.json | 32 ++++++++++++++++++++++++++++++++ qapi/misc.json | 32 -------------------------------- include/hw/rtc/mc146818rtc.h | 2 +- hw/core/qdev-properties.c | 1 + hw/i386/kvm/i8254.c | 2 +- 5 files changed, 35 insertions(+), 34 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index d8ed096e9a..8e2164a0b6 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -402,6 +402,38 @@ ## { 'command': 'query-target', 'returns': 'TargetInfo' } +## +# @LostTickPolicy: +# +# Policy for handling lost ticks in timer devices. Ticks end up getting +# lost when, for example, the guest is paused. +# +# @discard: throw away the missed ticks and continue with future injection +# normally. The guest OS will see the timer jump ahead by a +# potentially quite significant amount all at once, as if the +# intervening chunk of time had simply not existed; needless to +# say, such a sudden jump can easily confuse a guest OS which is +# not specifically prepared to deal with it. Assuming the guest +# OS can deal correctly with the time jump, the time in the guest +# and in the host should now match. +# +# @delay: continue to deliver ticks at the normal rate. The guest OS will +# not notice anything is amiss, as from its point of view time will +# have continued to flow normally. The time in the guest should now +# be behind the time in the host by exactly the amount of time during +# which ticks have been missed. +# +# @slew: deliver ticks at a higher rate to catch up with the missed ticks. +# The guest OS will not notice anything is amiss, as from its point +# of view time will have continued to flow normally. Once the timer +# has managed to catch up with all the missing ticks, the time in +# the guest and in the host should match. +# +# Since: 2.0 +## +{ 'enum': 'LostTickPolicy', + 'data': ['discard', 'delay', 'slew' ] } + ## # @NumaOptionsType: # diff --git a/qapi/misc.json b/qapi/misc.json index 8cf6ebe67c..b21963a176 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -8,38 +8,6 @@ { 'include': 'common.json' } -## -# @LostTickPolicy: -# -# Policy for handling lost ticks in timer devices. Ticks end up getting -# lost when, for example, the guest is paused. -# -# @discard: throw away the missed ticks and continue with future injection -# normally. The guest OS will see the timer jump ahead by a -# potentially quite significant amount all at once, as if the -# intervening chunk of time had simply not existed; needless to -# say, such a sudden jump can easily confuse a guest OS which is -# not specifically prepared to deal with it. Assuming the guest -# OS can deal correctly with the time jump, the time in the guest -# and in the host should now match. -# -# @delay: continue to deliver ticks at the normal rate. The guest OS will -# not notice anything is amiss, as from its point of view time will -# have continued to flow normally. The time in the guest should now -# be behind the time in the host by exactly the amount of time during -# which ticks have been missed. -# -# @slew: deliver ticks at a higher rate to catch up with the missed ticks. -# The guest OS will not notice anything is amiss, as from its point -# of view time will have continued to flow normally. Once the timer -# has managed to catch up with all the missing ticks, the time in -# the guest and in the host should match. -# -# Since: 2.0 -## -{ 'enum': 'LostTickPolicy', - 'data': ['discard', 'delay', 'slew' ] } - ## # @add_client: # diff --git a/include/hw/rtc/mc146818rtc.h b/include/hw/rtc/mc146818rtc.h index 6224b5276a..5b45b22924 100644 --- a/include/hw/rtc/mc146818rtc.h +++ b/include/hw/rtc/mc146818rtc.h @@ -9,7 +9,7 @@ #ifndef HW_RTC_MC146818RTC_H #define HW_RTC_MC146818RTC_H -#include "qapi/qapi-types-misc.h" +#include "qapi/qapi-types-machine.h" #include "qemu/queue.h" #include "qemu/timer.h" #include "hw/isa/isa.h" diff --git a/hw/core/qdev-properties.c b/hw/core/qdev-properties.c index 098298c78e..343c824da0 100644 --- a/hw/core/qdev-properties.c +++ b/hw/core/qdev-properties.c @@ -4,6 +4,7 @@ #include "qapi/error.h" #include "hw/pci/pci.h" #include "qapi/qapi-types-block.h" +#include "qapi/qapi-types-machine.h" #include "qapi/qapi-types-misc.h" #include "qapi/qmp/qerror.h" #include "qemu/ctype.h" diff --git a/hw/i386/kvm/i8254.c b/hw/i386/kvm/i8254.c index e18fd337fa..40d84734e7 100644 --- a/hw/i386/kvm/i8254.c +++ b/hw/i386/kvm/i8254.c @@ -25,7 +25,7 @@ #include "qemu/osdep.h" #include -#include "qapi/qapi-types-misc.h" +#include "qapi/qapi-types-machine.h" #include "qapi/error.h" #include "qemu/module.h" #include "qemu/timer.h" From patchwork Tue Sep 29 20:18:59 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304120 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=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 13E16C4727C for ; Tue, 29 Sep 2020 20:26:05 +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 7EF272076B for ; Tue, 29 Sep 2020 20:26:04 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="JOE0sdnX" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 7EF272076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:48208 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMCJ-0001w0-EY for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:26:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59786) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6F-0001tm-Mb for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:56533) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM65-0003VL-SZ for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410777; 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=nRqqfvjnibKSNEkaHraT0GWqdYhFJmPfI+ZcbTsn/sw=; b=JOE0sdnXLl99s9g53LzpKRQjZ6+56czomynld8LxMUkODJJlrO+0Th/RvmIcLvnaQ4hJg0 MRc62INqG1dbMdE3TWsEvCWEcAWYQOvNJ1Xb41k7Qh6KZZufykiZn6byNK+eRXI1HFxsBM 8DZnxpryd9ziDY9CRuBU8Avp+2rsV64= 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-49-19yzFXZtPiut5s0rAKxxMg-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: 19yzFXZtPiut5s0rAKxxMg-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id BB4ED802B69; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0BBA87A431; Tue, 29 Sep 2020 20:19:28 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 93F9C11386A3; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 02/29] qapi: Correct balloon documentation Date: Tue, 29 Sep 2020 22:18:59 +0200 Message-Id: <20200929201926.2155622-3-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Paolo Bonzini , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , David Hildenbrand Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé The documentation incorrectly uses the "size of the balloon" description when it should be "logical size of the VM". Fix it. The relation between both values is: logical_vm_size = vm_ram_size - balloon_size Reported-by: David Hildenbrand Suggested-by: David Hildenbrand Reviewed-by: David Hildenbrand Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-3-philmd@redhat.com> Signed-off-by: Markus Armbruster --- qapi/misc.json | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/qapi/misc.json b/qapi/misc.json index b21963a176..a667fdf03e 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -192,7 +192,8 @@ # # Information about the guest balloon device. # -# @actual: the number of bytes the balloon currently contains +# @actual: the logical size of the VM in bytes +# Formula used: logical_vm_size = vm_ram_size - balloon_size # # Since: 0.14.0 # @@ -228,7 +229,8 @@ # Emitted when the guest changes the actual BALLOON level. This value is # equivalent to the @actual field return by the 'query-balloon' command # -# @actual: actual level of the guest memory balloon in bytes +# @actual: the logical size of the VM in bytes +# Formula used: logical_vm_size = vm_ram_size - balloon_size # # Note: this event is rate-limited. # @@ -759,7 +761,10 @@ # # Request the balloon driver to change its balloon size. # -# @value: the target size of the balloon in bytes +# @value: the target logical size of the VM in bytes +# We can deduce the size of the balloon using this formula: +# logical_vm_size = vm_ram_size - balloon_size +# From it we have: balloon_size = vm_ram_size - @value # # Returns: - Nothing on success # - If the balloon driver is enabled but not functional because the KVM @@ -777,6 +782,8 @@ # -> { "execute": "balloon", "arguments": { "value": 536870912 } } # <- { "return": {} } # +# With a 2.5GiB guest this command inflated the balloon to 3GiB. +# ## { 'command': 'balloon', 'data': {'value': 'int'} } From patchwork Tue Sep 29 20:19:00 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272445 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=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 B2E1EC4727F for ; Tue, 29 Sep 2020 20:27:03 +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 D9F812076D for ; Tue, 29 Sep 2020 20:27:02 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="ddhBCiRz" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org D9F812076D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:51206 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMDF-0003GJ-KU for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:27:01 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59720) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6C-0001po-Hk for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:44 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:39257) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0003Uh-HY for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:44 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410775; 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=rVmHTDVApisUCQ44I1PLnIyMhzm7R6MJCbuFfCkfsGQ=; b=ddhBCiRzZi4D10BfVYf2h8EMIdP74RnGFVBj6wb8A8xJbLmoj7NGRgsBffmrDYtV5hLQZB tHEUFEQ/pCtULLpZFxZ8soFmqpQWNj4zmPuGMdeIdprXcuMZYGYTFhlm7Tpf2R/MI3XHf3 hg+iV9uH3fRuKWOi5R2LoXnqGHf+zsg= 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-275-mH8VvQNPNQeS1Am1SKP_IA-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: mH8VvQNPNQeS1Am1SKP_IA-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E4CC71040C21; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0E9F519D61; Tue, 29 Sep 2020 20:19:28 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 97C3A1138611; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 03/29] qapi: Restrict balloon-related commands to machine code Date: Tue, 29 Sep 2020 22:19:00 +0200 Message-Id: <20200929201926.2155622-4-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Paolo Bonzini , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , David Hildenbrand Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode emulation. Restricting the balloon-related commands to machine.json pulls less QAPI-generated code into user-mode. Reviewed-by: David Hildenbrand Acked-by: Markus Armbruster Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-4-philmd@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster --- qapi/machine.json | 90 ++++++++++++++++++++++++++++++++++++++ qapi/misc.json | 90 -------------------------------------- include/sysemu/balloon.h | 2 +- hw/virtio/virtio-balloon.c | 2 +- monitor/hmp-cmds.c | 1 + softmmu/balloon.c | 2 +- 6 files changed, 94 insertions(+), 93 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 8e2164a0b6..2accb3c4d2 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -945,3 +945,93 @@ 'data': 'NumaOptions', 'allow-preconfig': true } + +## +# @balloon: +# +# Request the balloon driver to change its balloon size. +# +# @value: the target logical size of the VM in bytes +# We can deduce the size of the balloon using this formula: +# logical_vm_size = vm_ram_size - balloon_size +# From it we have: balloon_size = vm_ram_size - @value +# +# Returns: - Nothing on success +# - If the balloon driver is enabled but not functional because the KVM +# kernel module cannot support it, KvmMissingCap +# - If no balloon device is present, DeviceNotActive +# +# Notes: This command just issues a request to the guest. When it returns, +# the balloon size may not have changed. A guest can change the balloon +# size independent of this command. +# +# Since: 0.14.0 +# +# Example: +# +# -> { "execute": "balloon", "arguments": { "value": 536870912 } } +# <- { "return": {} } +# +# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# +## +{ 'command': 'balloon', 'data': {'value': 'int'} } + +## +# @BalloonInfo: +# +# Information about the guest balloon device. +# +# @actual: the logical size of the VM in bytes +# Formula used: logical_vm_size = vm_ram_size - balloon_size +# +# Since: 0.14.0 +# +## +{ 'struct': 'BalloonInfo', 'data': {'actual': 'int' } } + +## +# @query-balloon: +# +# Return information about the balloon device. +# +# Returns: - @BalloonInfo on success +# - If the balloon driver is enabled but not functional because the KVM +# kernel module cannot support it, KvmMissingCap +# - If no balloon device is present, DeviceNotActive +# +# Since: 0.14.0 +# +# Example: +# +# -> { "execute": "query-balloon" } +# <- { "return": { +# "actual": 1073741824, +# } +# } +# +## +{ 'command': 'query-balloon', 'returns': 'BalloonInfo' } + +## +# @BALLOON_CHANGE: +# +# Emitted when the guest changes the actual BALLOON level. This value is +# equivalent to the @actual field return by the 'query-balloon' command +# +# @actual: the logical size of the VM in bytes +# Formula used: logical_vm_size = vm_ram_size - balloon_size +# +# Note: this event is rate-limited. +# +# Since: 1.2 +# +# Example: +# +# <- { "event": "BALLOON_CHANGE", +# "data": { "actual": 944766976 }, +# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } +# +## +{ 'event': 'BALLOON_CHANGE', + 'data': { 'actual': 'int' } } diff --git a/qapi/misc.json b/qapi/misc.json index a667fdf03e..7a14c50094 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -187,65 +187,6 @@ { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'], 'allow-preconfig': true } -## -# @BalloonInfo: -# -# Information about the guest balloon device. -# -# @actual: the logical size of the VM in bytes -# Formula used: logical_vm_size = vm_ram_size - balloon_size -# -# Since: 0.14.0 -# -## -{ 'struct': 'BalloonInfo', 'data': {'actual': 'int' } } - -## -# @query-balloon: -# -# Return information about the balloon device. -# -# Returns: - @BalloonInfo on success -# - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap -# - If no balloon device is present, DeviceNotActive -# -# Since: 0.14.0 -# -# Example: -# -# -> { "execute": "query-balloon" } -# <- { "return": { -# "actual": 1073741824, -# } -# } -# -## -{ 'command': 'query-balloon', 'returns': 'BalloonInfo' } - -## -# @BALLOON_CHANGE: -# -# Emitted when the guest changes the actual BALLOON level. This value is -# equivalent to the @actual field return by the 'query-balloon' command -# -# @actual: the logical size of the VM in bytes -# Formula used: logical_vm_size = vm_ram_size - balloon_size -# -# Note: this event is rate-limited. -# -# Since: 1.2 -# -# Example: -# -# <- { "event": "BALLOON_CHANGE", -# "data": { "actual": 944766976 }, -# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } -# -## -{ 'event': 'BALLOON_CHANGE', - 'data': { 'actual': 'int' } } - ## # @PciMemoryRange: # @@ -756,37 +697,6 @@ ## { 'command': 'inject-nmi' } -## -# @balloon: -# -# Request the balloon driver to change its balloon size. -# -# @value: the target logical size of the VM in bytes -# We can deduce the size of the balloon using this formula: -# logical_vm_size = vm_ram_size - balloon_size -# From it we have: balloon_size = vm_ram_size - @value -# -# Returns: - Nothing on success -# - If the balloon driver is enabled but not functional because the KVM -# kernel module cannot support it, KvmMissingCap -# - If no balloon device is present, DeviceNotActive -# -# Notes: This command just issues a request to the guest. When it returns, -# the balloon size may not have changed. A guest can change the balloon -# size independent of this command. -# -# Since: 0.14.0 -# -# Example: -# -# -> { "execute": "balloon", "arguments": { "value": 536870912 } } -# <- { "return": {} } -# -# With a 2.5GiB guest this command inflated the balloon to 3GiB. -# -## -{ 'command': 'balloon', 'data': {'value': 'int'} } - ## # @human-monitor-command: # diff --git a/include/sysemu/balloon.h b/include/sysemu/balloon.h index 20a2defe3a..867687b73a 100644 --- a/include/sysemu/balloon.h +++ b/include/sysemu/balloon.h @@ -15,7 +15,7 @@ #define QEMU_BALLOON_H #include "exec/cpu-common.h" -#include "qapi/qapi-types-misc.h" +#include "qapi/qapi-types-machine.h" typedef void (QEMUBalloonEvent)(void *opaque, ram_addr_t target); typedef void (QEMUBalloonStatus)(void *opaque, BalloonInfo *info); diff --git a/hw/virtio/virtio-balloon.c b/hw/virtio/virtio-balloon.c index 22cb5df717..b22b5beda3 100644 --- a/hw/virtio/virtio-balloon.c +++ b/hw/virtio/virtio-balloon.c @@ -24,7 +24,7 @@ #include "hw/virtio/virtio-balloon.h" #include "exec/address-spaces.h" #include "qapi/error.h" -#include "qapi/qapi-events-misc.h" +#include "qapi/qapi-events-machine.h" #include "qapi/visitor.h" #include "trace.h" #include "qemu/error-report.h" diff --git a/monitor/hmp-cmds.c b/monitor/hmp-cmds.c index 7711726fd2..de01ba2084 100644 --- a/monitor/hmp-cmds.c +++ b/monitor/hmp-cmds.c @@ -32,6 +32,7 @@ #include "qapi/qapi-commands-block.h" #include "qapi/qapi-commands-char.h" #include "qapi/qapi-commands-control.h" +#include "qapi/qapi-commands-machine.h" #include "qapi/qapi-commands-migration.h" #include "qapi/qapi-commands-misc.h" #include "qapi/qapi-commands-net.h" diff --git a/softmmu/balloon.c b/softmmu/balloon.c index 23452295cd..e0e8969a4b 100644 --- a/softmmu/balloon.c +++ b/softmmu/balloon.c @@ -29,7 +29,7 @@ #include "sysemu/kvm.h" #include "sysemu/balloon.h" #include "qapi/error.h" -#include "qapi/qapi-commands-misc.h" +#include "qapi/qapi-commands-machine.h" #include "qapi/qmp/qerror.h" #include "trace.h" From patchwork Tue Sep 29 20:19:01 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304123 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=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 2820BC4727F for ; Tue, 29 Sep 2020 20:21:42 +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 895E62076B for ; Tue, 29 Sep 2020 20:21:41 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="YvTI3AEl" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 895E62076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:60274 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNM84-0003bq-F7 for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:21:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59598) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0001lC-Q2 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:37 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:43283) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM61-0003Si-4k for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:36 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410771; 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=Nx5fqRl9E4W0g2eJkBKZ759n+CO2rmYE/zk+htF+dvU=; b=YvTI3AEltW8lMQhcFzV58hxV1jGaTSK5vmEkY7t1L8zcAcTM/ak/4iXREMP0Drxt925RHa nOLvzzdghd/YGIbzDyIN3QR6J8t0cWJJh+wOgmGbORx/AcTK9DkCuVvQBsiRkTte7kwzi/ rJ2CP/Lx0I4s9hpZaTCNQ2vxNyLU6g4= 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-116-Y8atyhpDNky-Mhf3bMtuZQ-1; Tue, 29 Sep 2020 16:19:29 -0400 X-MC-Unique: Y8atyhpDNky-Mhf3bMtuZQ-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 43D1910BBEC3; Tue, 29 Sep 2020 20:19:28 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1204B2C31E; Tue, 29 Sep 2020 20:19:28 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9B41E11385C3; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 04/29] qapi: Restrict query-vm-generation-id command to machine code Date: Tue, 29 Sep 2020 22:19:01 +0200 Message-Id: <20200929201926.2155622-5-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Paolo Bonzini , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Igor Mammedov Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode emulation. Restricting the query-vm-generation-id command to machine.json pulls less QAPI-generated code into user-mode. Acked-by: Igor Mammedov Acked-by: Markus Armbruster Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-5-philmd@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster --- qapi/machine.json | 20 ++++++++++++++++++++ qapi/misc.json | 21 --------------------- hw/acpi/vmgenid.c | 2 +- stubs/vmgenid.c | 2 +- 4 files changed, 22 insertions(+), 23 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 2accb3c4d2..15c8d606ab 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -402,6 +402,26 @@ ## { 'command': 'query-target', 'returns': 'TargetInfo' } +## +# @GuidInfo: +# +# GUID information. +# +# @guid: the globally unique identifier +# +# Since: 2.9 +## +{ 'struct': 'GuidInfo', 'data': {'guid': 'str'} } + +## +# @query-vm-generation-id: +# +# Show Virtual Machine Generation ID +# +# Since: 2.9 +## +{ 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' } + ## # @LostTickPolicy: # diff --git a/qapi/misc.json b/qapi/misc.json index 7a14c50094..edcc91e106 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -1479,24 +1479,3 @@ # ## { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} } - -## -# @GuidInfo: -# -# GUID information. -# -# @guid: the globally unique identifier -# -# Since: 2.9 -## -{ 'struct': 'GuidInfo', 'data': {'guid': 'str'} } - -## -# @query-vm-generation-id: -# -# Show Virtual Machine Generation ID -# -# Since: 2.9 -## -{ 'command': 'query-vm-generation-id', 'returns': 'GuidInfo' } - diff --git a/hw/acpi/vmgenid.c b/hw/acpi/vmgenid.c index 53db6af75d..2c8152d508 100644 --- a/hw/acpi/vmgenid.c +++ b/hw/acpi/vmgenid.c @@ -12,7 +12,7 @@ #include "qemu/osdep.h" #include "qapi/error.h" -#include "qapi/qapi-commands-misc.h" +#include "qapi/qapi-commands-machine.h" #include "qemu/module.h" #include "hw/acpi/acpi.h" #include "hw/acpi/aml-build.h" diff --git a/stubs/vmgenid.c b/stubs/vmgenid.c index 568e42b064..bfad656c6c 100644 --- a/stubs/vmgenid.c +++ b/stubs/vmgenid.c @@ -1,6 +1,6 @@ #include "qemu/osdep.h" #include "qapi/error.h" -#include "qapi/qapi-commands-misc.h" +#include "qapi/qapi-commands-machine.h" #include "qapi/qmp/qerror.h" GuidInfo *qmp_query_vm_generation_id(Error **errp) From patchwork Tue Sep 29 20:19:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304118 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 581FAC4727F for ; Tue, 29 Sep 2020 20:28:49 +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 BB4672076B for ; Tue, 29 Sep 2020 20:28:48 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="KihsvI+9" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org BB4672076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:56280 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMEx-0005PG-KM for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:28:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59838) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6I-0001v3-79 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:34277) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM69-0003W1-C2 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:49 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410780; 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=IpaPO/xyASpAHb6Tn9VNSQDlYnAL6prIqxyflpicY3k=; b=KihsvI+9oCO2SxK5M3ppljGX8phcjVb0IbDgeOAS2Fn8MH/EeresYQSdnIWX9DOz1SpHLU Sl7Gr1x12IYbqLtCQkXwkadB0ePaeGBq3rmmTmLXBY5w+6DQneO7W/U6YJgQOtWw+kYdCm HrshslLA5oRJ94OOWmRc4HIs367xD94= 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-297-boDGIgE1PdehE1ACTDIkBg-1; Tue, 29 Sep 2020 16:19:30 -0400 X-MC-Unique: boDGIgE1PdehE1ACTDIkBg-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id CAF3D801AE5; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 9C5E66198E; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 9EEFB11384A5; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 05/29] qapi: Restrict query-uuid command to machine code Date: Tue, 29 Sep 2020 22:19:02 +0200 Message-Id: <20200929201926.2155622-6-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Paolo Bonzini Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode emulation. Restricting the query-uuid command to machine.json pulls less QAPI-generated code into user-mode. Acked-by: Markus Armbruster Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-6-philmd@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster --- qapi/machine.json | 30 ++++++++++++++++++++++++++++++ qapi/misc.json | 30 ------------------------------ block/iscsi.c | 2 +- stubs/uuid.c | 2 +- 4 files changed, 32 insertions(+), 32 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 15c8d606ab..5e5ddd7a5e 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -402,6 +402,36 @@ ## { 'command': 'query-target', 'returns': 'TargetInfo' } +## +# @UuidInfo: +# +# Guest UUID information (Universally Unique Identifier). +# +# @UUID: the UUID of the guest +# +# Since: 0.14.0 +# +# Notes: If no UUID was specified for the guest, a null UUID is returned. +## +{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } + +## +# @query-uuid: +# +# Query the guest UUID information. +# +# Returns: The @UuidInfo for the guest +# +# Since: 0.14.0 +# +# Example: +# +# -> { "execute": "query-uuid" } +# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } +# +## +{ 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true } + ## # @GuidInfo: # diff --git a/qapi/misc.json b/qapi/misc.json index edcc91e106..05db6295fe 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -98,36 +98,6 @@ ## { 'command': 'query-kvm', 'returns': 'KvmInfo' } -## -# @UuidInfo: -# -# Guest UUID information (Universally Unique Identifier). -# -# @UUID: the UUID of the guest -# -# Since: 0.14.0 -# -# Notes: If no UUID was specified for the guest, a null UUID is returned. -## -{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } - -## -# @query-uuid: -# -# Query the guest UUID information. -# -# Returns: The @UuidInfo for the guest -# -# Since: 0.14.0 -# -# Example: -# -# -> { "execute": "query-uuid" } -# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } -# -## -{ 'command': 'query-uuid', 'returns': 'UuidInfo', 'allow-preconfig': true } - ## # @IOThreadInfo: # diff --git a/block/iscsi.c b/block/iscsi.c index bd2122a3a4..e30a7e3606 100644 --- a/block/iscsi.c +++ b/block/iscsi.c @@ -42,7 +42,7 @@ #include "qemu/uuid.h" #include "sysemu/replay.h" #include "qapi/error.h" -#include "qapi/qapi-commands-misc.h" +#include "qapi/qapi-commands-machine.h" #include "qapi/qmp/qdict.h" #include "qapi/qmp/qstring.h" #include "crypto/secret.h" diff --git a/stubs/uuid.c b/stubs/uuid.c index 67f182fa3a..e5112eb3f6 100644 --- a/stubs/uuid.c +++ b/stubs/uuid.c @@ -1,5 +1,5 @@ #include "qemu/osdep.h" -#include "qapi/qapi-commands-misc.h" +#include "qapi/qapi-commands-machine.h" #include "qemu/uuid.h" UuidInfo *qmp_query_uuid(Error **errp) From patchwork Tue Sep 29 20:19:03 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272449 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=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 DADD4C4727C for ; Tue, 29 Sep 2020 20:21: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 3F2E92076D for ; Tue, 29 Sep 2020 20:21:44 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="dU5xZ8YA" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 3F2E92076D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:60488 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNM86-0003h8-VI for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:21:42 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59660) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM68-0001nB-D9 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:21599) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM62-0003TZ-Dq for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:38 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410773; 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=MgitbMqeM3f1gxlb1eMc97YNGzeiuZxcB+VxofU9rrY=; b=dU5xZ8YADZBlS6Sg0gXwHHw0sIuoYgqKBsa14/3AXrLLqLXCyguNoDndjfLWzgUxbSzGLh A60fv/mHkzbTN5jGM5Hdsy/8sCRNp9kN3/T7j7Wk+9oM2HhRS+a4s3r/JjH8Aak3JUGP/p HY8MVdmdtsrnSaFTYaP87ZXxHFmFoJM= 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-348-D7wt7LcRNZm38h7zIUV9rg-1; Tue, 29 Sep 2020 16:19:31 -0400 X-MC-Unique: D7wt7LcRNZm38h7zIUV9rg-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 2EF8B1DDF3; Tue, 29 Sep 2020 20:19:30 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id A54FA19D7D; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id A2C4D113639D; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 06/29] qapi: Restrict device memory commands to machine code Date: Tue, 29 Sep 2020 22:19:03 +0200 Message-Id: <20200929201926.2155622-7-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Paolo Bonzini , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Igor Mammedov Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode emulation. Restricting the memory commands to machine.json pulls less QAPI-generated code into user-mode. Acked-by: Igor Mammedov Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-7-philmd@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster --- qapi/machine.json | 216 +++++++++++++++++++++++++++++++ qapi/misc.json | 217 -------------------------------- include/hw/mem/memory-device.h | 2 +- include/hw/virtio/virtio-pmem.h | 2 +- hw/acpi/memory_hotplug.c | 1 + hw/virtio/virtio-mem-pci.c | 1 + 6 files changed, 220 insertions(+), 219 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 5e5ddd7a5e..c061cce0e4 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1085,3 +1085,219 @@ ## { 'event': 'BALLOON_CHANGE', 'data': { 'actual': 'int' } } + +## +# @MemoryInfo: +# +# Actual memory information in bytes. +# +# @base-memory: size of "base" memory specified with command line +# option -m. +# +# @plugged-memory: size of memory that can be hot-unplugged. This field +# is omitted if target doesn't support memory hotplug +# (i.e. CONFIG_MEM_DEVICE not defined at build time). +# +# Since: 2.11.0 +## +{ 'struct': 'MemoryInfo', + 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } } + +## +# @query-memory-size-summary: +# +# Return the amount of initially allocated and present hotpluggable (if +# enabled) memory in bytes. +# +# Example: +# +# -> { "execute": "query-memory-size-summary" } +# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } +# +# Since: 2.11.0 +## +{ 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' } + +## +# @PCDIMMDeviceInfo: +# +# PCDIMMDevice state information +# +# @id: device's ID +# +# @addr: physical address, where device is mapped +# +# @size: size of memory that the device provides +# +# @slot: slot number at which device is plugged in +# +# @node: NUMA node number where device is plugged in +# +# @memdev: memory backend linked with device +# +# @hotplugged: true if device was hotplugged +# +# @hotpluggable: true if device if could be added/removed while machine is running +# +# Since: 2.1 +## +{ 'struct': 'PCDIMMDeviceInfo', + 'data': { '*id': 'str', + 'addr': 'int', + 'size': 'int', + 'slot': 'int', + 'node': 'int', + 'memdev': 'str', + 'hotplugged': 'bool', + 'hotpluggable': 'bool' + } +} + +## +# @VirtioPMEMDeviceInfo: +# +# VirtioPMEM state information +# +# @id: device's ID +# +# @memaddr: physical address in memory, where device is mapped +# +# @size: size of memory that the device provides +# +# @memdev: memory backend linked with device +# +# Since: 4.1 +## +{ 'struct': 'VirtioPMEMDeviceInfo', + 'data': { '*id': 'str', + 'memaddr': 'size', + 'size': 'size', + 'memdev': 'str' + } +} + +## +# @VirtioMEMDeviceInfo: +# +# VirtioMEMDevice state information +# +# @id: device's ID +# +# @memaddr: physical address in memory, where device is mapped +# +# @requested-size: the user requested size of the device +# +# @size: the (current) size of memory that the device provides +# +# @max-size: the maximum size of memory that the device can provide +# +# @block-size: the block size of memory that the device provides +# +# @node: NUMA node number where device is assigned to +# +# @memdev: memory backend linked with the region +# +# Since: 5.1 +## +{ 'struct': 'VirtioMEMDeviceInfo', + 'data': { '*id': 'str', + 'memaddr': 'size', + 'requested-size': 'size', + 'size': 'size', + 'max-size': 'size', + 'block-size': 'size', + 'node': 'int', + 'memdev': 'str' + } +} + +## +# @MemoryDeviceInfo: +# +# Union containing information about a memory device +# +# nvdimm is included since 2.12. virtio-pmem is included since 4.1. +# virtio-mem is included since 5.1. +# +# Since: 2.1 +## +{ 'union': 'MemoryDeviceInfo', + 'data': { 'dimm': 'PCDIMMDeviceInfo', + 'nvdimm': 'PCDIMMDeviceInfo', + 'virtio-pmem': 'VirtioPMEMDeviceInfo', + 'virtio-mem': 'VirtioMEMDeviceInfo' + } +} + +## +# @query-memory-devices: +# +# Lists available memory devices and their state +# +# Since: 2.1 +# +# Example: +# +# -> { "execute": "query-memory-devices" } +# <- { "return": [ { "data": +# { "addr": 5368709120, +# "hotpluggable": true, +# "hotplugged": true, +# "id": "d1", +# "memdev": "/objects/memX", +# "node": 0, +# "size": 1073741824, +# "slot": 0}, +# "type": "dimm" +# } ] } +# +## +{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } + +## +# @MEMORY_DEVICE_SIZE_CHANGE: +# +# Emitted when the size of a memory device changes. Only emitted for memory +# devices that can actually change the size (e.g., virtio-mem due to guest +# action). +# +# @id: device's ID +# @size: the new size of memory that the device provides +# +# Note: this event is rate-limited. +# +# Since: 5.1 +# +# Example: +# +# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", +# "data": { "id": "vm0", "size": 1073741824}, +# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } +# +## +{ 'event': 'MEMORY_DEVICE_SIZE_CHANGE', + 'data': { '*id': 'str', 'size': 'size' } } + + +## +# @MEM_UNPLUG_ERROR: +# +# Emitted when memory hot unplug error occurs. +# +# @device: device name +# +# @msg: Informative message +# +# Since: 2.4 +# +# Example: +# +# <- { "event": "MEM_UNPLUG_ERROR" +# "data": { "device": "dimm1", +# "msg": "acpi: device unplug for unsupported device" +# }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# +## +{ 'event': 'MEM_UNPLUG_ERROR', + 'data': { 'device': 'str', 'msg': 'str' } } diff --git a/qapi/misc.json b/qapi/misc.json index 05db6295fe..71d11365ea 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -826,39 +826,6 @@ ## { 'command': 'closefd', 'data': {'fdname': 'str'} } -## -# @MemoryInfo: -# -# Actual memory information in bytes. -# -# @base-memory: size of "base" memory specified with command line -# option -m. -# -# @plugged-memory: size of memory that can be hot-unplugged. This field -# is omitted if target doesn't support memory hotplug -# (i.e. CONFIG_MEM_DEVICE not defined at build time). -# -# Since: 2.11.0 -## -{ 'struct': 'MemoryInfo', - 'data' : { 'base-memory': 'size', '*plugged-memory': 'size' } } - -## -# @query-memory-size-summary: -# -# Return the amount of initially allocated and present hotpluggable (if -# enabled) memory in bytes. -# -# Example: -# -# -> { "execute": "query-memory-size-summary" } -# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } -# -# Since: 2.11.0 -## -{ 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' } - - ## # @AddfdInfo: # @@ -1154,190 +1121,6 @@ 'returns': ['CommandLineOptionInfo'], 'allow-preconfig': true } -## -# @PCDIMMDeviceInfo: -# -# PCDIMMDevice state information -# -# @id: device's ID -# -# @addr: physical address, where device is mapped -# -# @size: size of memory that the device provides -# -# @slot: slot number at which device is plugged in -# -# @node: NUMA node number where device is plugged in -# -# @memdev: memory backend linked with device -# -# @hotplugged: true if device was hotplugged -# -# @hotpluggable: true if device if could be added/removed while machine is running -# -# Since: 2.1 -## -{ 'struct': 'PCDIMMDeviceInfo', - 'data': { '*id': 'str', - 'addr': 'int', - 'size': 'int', - 'slot': 'int', - 'node': 'int', - 'memdev': 'str', - 'hotplugged': 'bool', - 'hotpluggable': 'bool' - } -} - -## -# @VirtioPMEMDeviceInfo: -# -# VirtioPMEM state information -# -# @id: device's ID -# -# @memaddr: physical address in memory, where device is mapped -# -# @size: size of memory that the device provides -# -# @memdev: memory backend linked with device -# -# Since: 4.1 -## -{ 'struct': 'VirtioPMEMDeviceInfo', - 'data': { '*id': 'str', - 'memaddr': 'size', - 'size': 'size', - 'memdev': 'str' - } -} - -## -# @VirtioMEMDeviceInfo: -# -# VirtioMEMDevice state information -# -# @id: device's ID -# -# @memaddr: physical address in memory, where device is mapped -# -# @requested-size: the user requested size of the device -# -# @size: the (current) size of memory that the device provides -# -# @max-size: the maximum size of memory that the device can provide -# -# @block-size: the block size of memory that the device provides -# -# @node: NUMA node number where device is assigned to -# -# @memdev: memory backend linked with the region -# -# Since: 5.1 -## -{ 'struct': 'VirtioMEMDeviceInfo', - 'data': { '*id': 'str', - 'memaddr': 'size', - 'requested-size': 'size', - 'size': 'size', - 'max-size': 'size', - 'block-size': 'size', - 'node': 'int', - 'memdev': 'str' - } -} - -## -# @MemoryDeviceInfo: -# -# Union containing information about a memory device -# -# nvdimm is included since 2.12. virtio-pmem is included since 4.1. -# virtio-mem is included since 5.1. -# -# Since: 2.1 -## -{ 'union': 'MemoryDeviceInfo', - 'data': { 'dimm': 'PCDIMMDeviceInfo', - 'nvdimm': 'PCDIMMDeviceInfo', - 'virtio-pmem': 'VirtioPMEMDeviceInfo', - 'virtio-mem': 'VirtioMEMDeviceInfo' - } -} - -## -# @query-memory-devices: -# -# Lists available memory devices and their state -# -# Since: 2.1 -# -# Example: -# -# -> { "execute": "query-memory-devices" } -# <- { "return": [ { "data": -# { "addr": 5368709120, -# "hotpluggable": true, -# "hotplugged": true, -# "id": "d1", -# "memdev": "/objects/memX", -# "node": 0, -# "size": 1073741824, -# "slot": 0}, -# "type": "dimm" -# } ] } -# -## -{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] } - -## -# @MEMORY_DEVICE_SIZE_CHANGE: -# -# Emitted when the size of a memory device changes. Only emitted for memory -# devices that can actually change the size (e.g., virtio-mem due to guest -# action). -# -# @id: device's ID -# @size: the new size of memory that the device provides -# -# Note: this event is rate-limited. -# -# Since: 5.1 -# -# Example: -# -# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", -# "data": { "id": "vm0", "size": 1073741824}, -# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } -# -## -{ 'event': 'MEMORY_DEVICE_SIZE_CHANGE', - 'data': { '*id': 'str', 'size': 'size' } } - - -## -# @MEM_UNPLUG_ERROR: -# -# Emitted when memory hot unplug error occurs. -# -# @device: device name -# -# @msg: Informative message -# -# Since: 2.4 -# -# Example: -# -# <- { "event": "MEM_UNPLUG_ERROR" -# "data": { "device": "dimm1", -# "msg": "acpi: device unplug for unsupported device" -# }, -# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } -# -## -{ 'event': 'MEM_UNPLUG_ERROR', - 'data': { 'device': 'str', 'msg': 'str' } } - ## # @ACPISlotType: # diff --git a/include/hw/mem/memory-device.h b/include/hw/mem/memory-device.h index cde52e83c9..30d7e99f52 100644 --- a/include/hw/mem/memory-device.h +++ b/include/hw/mem/memory-device.h @@ -14,7 +14,7 @@ #define MEMORY_DEVICE_H #include "hw/qdev-core.h" -#include "qapi/qapi-types-misc.h" +#include "qapi/qapi-types-machine.h" #include "qom/object.h" #define TYPE_MEMORY_DEVICE "memory-device" diff --git a/include/hw/virtio/virtio-pmem.h b/include/hw/virtio/virtio-pmem.h index 66b590821e..fc4fd1f7fe 100644 --- a/include/hw/virtio/virtio-pmem.h +++ b/include/hw/virtio/virtio-pmem.h @@ -15,7 +15,7 @@ #define HW_VIRTIO_PMEM_H #include "hw/virtio/virtio.h" -#include "qapi/qapi-types-misc.h" +#include "qapi/qapi-types-machine.h" #include "qom/object.h" #define TYPE_VIRTIO_PMEM "virtio-pmem" diff --git a/hw/acpi/memory_hotplug.c b/hw/acpi/memory_hotplug.c index 8d2e82240f..dfe57af429 100644 --- a/hw/acpi/memory_hotplug.c +++ b/hw/acpi/memory_hotplug.c @@ -7,6 +7,7 @@ #include "migration/vmstate.h" #include "trace.h" #include "qapi/error.h" +#include "qapi/qapi-events-machine.h" #include "qapi/qapi-events-misc.h" #define MEMORY_SLOTS_NUMBER "MDNR" diff --git a/hw/virtio/virtio-mem-pci.c b/hw/virtio/virtio-mem-pci.c index 590cec041b..913f4a3326 100644 --- a/hw/virtio/virtio-mem-pci.c +++ b/hw/virtio/virtio-mem-pci.c @@ -14,6 +14,7 @@ #include "virtio-mem-pci.h" #include "hw/mem/memory-device.h" #include "qapi/error.h" +#include "qapi/qapi-events-machine.h" #include "qapi/qapi-events-misc.h" static void virtio_mem_pci_realize(VirtIOPCIProxy *vpci_dev, Error **errp) From patchwork Tue Sep 29 20:19:04 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272448 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=-9.6 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 B1120C47420 for ; Tue, 29 Sep 2020 20:24: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 12B8A2076D for ; Tue, 29 Sep 2020 20:24:17 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="TgCm20UW" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 12B8A2076D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:40158 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMAZ-00072F-Rn for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:24:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59624) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM66-0001mD-Ge for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:57377) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM62-0003Ty-EM for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:38 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410773; 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=MBM/bVem2B9Oad7cMaVnTEsGxanjQ4A5fE9lM3vi2ps=; b=TgCm20UWgAnhu4Hwb8T7x9REtg7aGFJZ24tent+Z47FXFa+OCzI18EPPXUyfJiF9HqEhlZ AP3Fjn6Sfct+iRU4+BhmU0mad1VV2vZ3TsHmUN1xUcRf2+ceMa210B6RBNMLxS8a6mLkvG jA840wZbJrWdsde9MFTSEkWViRehUd8= 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-348-H5RWRhJUNNSsBYeeIJboVg-1; Tue, 29 Sep 2020 16:19:31 -0400 X-MC-Unique: H5RWRhJUNNSsBYeeIJboVg-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 335B21040C22; Tue, 29 Sep 2020 20:19:30 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id AD31D7BE49; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id A744411358BC; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 07/29] qapi: Extract ACPI commands to 'acpi.json' Date: Tue, 29 Sep 2020 22:19:04 +0200 Message-Id: <20200929201926.2155622-8-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Paolo Bonzini , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Igor Mammedov Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode emulation. Extracting the ACPI commands to their own schema reduces the size of the qapi-misc* headers generated, and pulls less QAPI-generated code into user-mode. Suggested-by: Markus Armbruster Acked-by: Igor Mammedov Acked-by: Markus Armbruster Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-8-philmd@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster --- qapi/acpi.json | 141 +++++++++++++++++++++++++++ qapi/misc.json | 131 ------------------------- qapi/qapi-schema.json | 1 + include/hw/acpi/acpi_dev_interface.h | 2 +- hw/acpi/core.c | 2 +- hw/acpi/cpu.c | 2 +- hw/acpi/memory_hotplug.c | 2 +- monitor/qmp-cmds.c | 1 + MAINTAINERS | 1 + qapi/meson.build | 1 + 10 files changed, 149 insertions(+), 135 deletions(-) create mode 100644 qapi/acpi.json diff --git a/qapi/acpi.json b/qapi/acpi.json new file mode 100644 index 0000000000..51f0d55db7 --- /dev/null +++ b/qapi/acpi.json @@ -0,0 +1,141 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. +# SPDX-License-Identifier: GPL-2.0-or-later + +## +# = ACPI +## + +## +# @AcpiTableOptions: +# +# Specify an ACPI table on the command line to load. +# +# At most one of @file and @data can be specified. The list of files specified +# by any one of them is loaded and concatenated in order. If both are omitted, +# @data is implied. +# +# Other fields / optargs can be used to override fields of the generic ACPI +# table header; refer to the ACPI specification 5.0, section 5.2.6 System +# Description Table Header. If a header field is not overridden, then the +# corresponding value from the concatenated blob is used (in case of @file), or +# it is filled in with a hard-coded value (in case of @data). +# +# String fields are copied into the matching ACPI member from lowest address +# upwards, and silently truncated / NUL-padded to length. +# +# @sig: table signature / identifier (4 bytes) +# +# @rev: table revision number (dependent on signature, 1 byte) +# +# @oem_id: OEM identifier (6 bytes) +# +# @oem_table_id: OEM table identifier (8 bytes) +# +# @oem_rev: OEM-supplied revision number (4 bytes) +# +# @asl_compiler_id: identifier of the utility that created the table +# (4 bytes) +# +# @asl_compiler_rev: revision number of the utility that created the +# table (4 bytes) +# +# @file: colon (:) separated list of pathnames to load and +# concatenate as table data. The resultant binary blob is expected to +# have an ACPI table header. At least one file is required. This field +# excludes @data. +# +# @data: colon (:) separated list of pathnames to load and +# concatenate as table data. The resultant binary blob must not have an +# ACPI table header. At least one file is required. This field excludes +# @file. +# +# Since: 1.5 +## +{ 'struct': 'AcpiTableOptions', + 'data': { + '*sig': 'str', + '*rev': 'uint8', + '*oem_id': 'str', + '*oem_table_id': 'str', + '*oem_rev': 'uint32', + '*asl_compiler_id': 'str', + '*asl_compiler_rev': 'uint32', + '*file': 'str', + '*data': 'str' }} + +## +# @ACPISlotType: +# +# @DIMM: memory slot +# @CPU: logical CPU slot (since 2.7) +## +{ 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } + +## +# @ACPIOSTInfo: +# +# OSPM Status Indication for a device +# For description of possible values of @source and @status fields +# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec. +# +# @device: device ID associated with slot +# +# @slot: slot ID, unique per slot of a given @slot-type +# +# @slot-type: type of the slot +# +# @source: an integer containing the source event +# +# @status: an integer containing the status code +# +# Since: 2.1 +## +{ 'struct': 'ACPIOSTInfo', + 'data' : { '*device': 'str', + 'slot': 'str', + 'slot-type': 'ACPISlotType', + 'source': 'int', + 'status': 'int' } } + +## +# @query-acpi-ospm-status: +# +# Return a list of ACPIOSTInfo for devices that support status +# reporting via ACPI _OST method. +# +# Since: 2.1 +# +# Example: +# +# -> { "execute": "query-acpi-ospm-status" } +# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, +# { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, +# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, +# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} +# ]} +# +## +{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } + +## +# @ACPI_DEVICE_OST: +# +# Emitted when guest executes ACPI _OST method. +# +# @info: OSPM Status Indication +# +# Since: 2.1 +# +# Example: +# +# <- { "event": "ACPI_DEVICE_OST", +# "data": { "device": "d1", "slot": "0", +# "slot-type": "DIMM", "source": 1, "status": 0 } } +# +## +{ 'event': 'ACPI_DEVICE_OST', + 'data': { 'info': 'ACPIOSTInfo' } } diff --git a/qapi/misc.json b/qapi/misc.json index 71d11365ea..4b00b18e54 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -970,64 +970,6 @@ ## { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] } -## -# @AcpiTableOptions: -# -# Specify an ACPI table on the command line to load. -# -# At most one of @file and @data can be specified. The list of files specified -# by any one of them is loaded and concatenated in order. If both are omitted, -# @data is implied. -# -# Other fields / optargs can be used to override fields of the generic ACPI -# table header; refer to the ACPI specification 5.0, section 5.2.6 System -# Description Table Header. If a header field is not overridden, then the -# corresponding value from the concatenated blob is used (in case of @file), or -# it is filled in with a hard-coded value (in case of @data). -# -# String fields are copied into the matching ACPI member from lowest address -# upwards, and silently truncated / NUL-padded to length. -# -# @sig: table signature / identifier (4 bytes) -# -# @rev: table revision number (dependent on signature, 1 byte) -# -# @oem_id: OEM identifier (6 bytes) -# -# @oem_table_id: OEM table identifier (8 bytes) -# -# @oem_rev: OEM-supplied revision number (4 bytes) -# -# @asl_compiler_id: identifier of the utility that created the table -# (4 bytes) -# -# @asl_compiler_rev: revision number of the utility that created the -# table (4 bytes) -# -# @file: colon (:) separated list of pathnames to load and -# concatenate as table data. The resultant binary blob is expected to -# have an ACPI table header. At least one file is required. This field -# excludes @data. -# -# @data: colon (:) separated list of pathnames to load and -# concatenate as table data. The resultant binary blob must not have an -# ACPI table header. At least one file is required. This field excludes -# @file. -# -# Since: 1.5 -## -{ 'struct': 'AcpiTableOptions', - 'data': { - '*sig': 'str', - '*rev': 'uint8', - '*oem_id': 'str', - '*oem_table_id': 'str', - '*oem_rev': 'uint32', - '*asl_compiler_id': 'str', - '*asl_compiler_rev': 'uint32', - '*file': 'str', - '*data': 'str' }} - ## # @CommandLineParameterType: # @@ -1121,79 +1063,6 @@ 'returns': ['CommandLineOptionInfo'], 'allow-preconfig': true } -## -# @ACPISlotType: -# -# @DIMM: memory slot -# @CPU: logical CPU slot (since 2.7) -## -{ 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } - -## -# @ACPIOSTInfo: -# -# OSPM Status Indication for a device -# For description of possible values of @source and @status fields -# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec. -# -# @device: device ID associated with slot -# -# @slot: slot ID, unique per slot of a given @slot-type -# -# @slot-type: type of the slot -# -# @source: an integer containing the source event -# -# @status: an integer containing the status code -# -# Since: 2.1 -## -{ 'struct': 'ACPIOSTInfo', - 'data' : { '*device': 'str', - 'slot': 'str', - 'slot-type': 'ACPISlotType', - 'source': 'int', - 'status': 'int' } } - -## -# @query-acpi-ospm-status: -# -# Return a list of ACPIOSTInfo for devices that support status -# reporting via ACPI _OST method. -# -# Since: 2.1 -# -# Example: -# -# -> { "execute": "query-acpi-ospm-status" } -# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, -# { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, -# { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, -# { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} -# ]} -# -## -{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } - -## -# @ACPI_DEVICE_OST: -# -# Emitted when guest executes ACPI _OST method. -# -# @info: OSPM Status Indication -# -# Since: 2.1 -# -# Example: -# -# <- { "event": "ACPI_DEVICE_OST", -# "data": { "device": "d1", "slot": "0", -# "slot-type": "DIMM", "source": 1, "status": 0 } } -# -## -{ 'event': 'ACPI_DEVICE_OST', - 'data': { 'info': 'ACPIOSTInfo' } } - ## # @ReplayMode: # diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index f03ff91ceb..4d8b3a9afe 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -85,3 +85,4 @@ { 'include': 'misc.json' } { 'include': 'misc-target.json' } { 'include': 'audio.json' } +{ 'include': 'acpi.json' } diff --git a/include/hw/acpi/acpi_dev_interface.h b/include/hw/acpi/acpi_dev_interface.h index 9adf1e4706..769ff55c7e 100644 --- a/include/hw/acpi/acpi_dev_interface.h +++ b/include/hw/acpi/acpi_dev_interface.h @@ -1,7 +1,7 @@ #ifndef ACPI_DEV_INTERFACE_H #define ACPI_DEV_INTERFACE_H -#include "qapi/qapi-types-misc.h" +#include "qapi/qapi-types-acpi.h" #include "qom/object.h" #include "hw/boards.h" #include "hw/qdev-core.h" diff --git a/hw/acpi/core.c b/hw/acpi/core.c index ac06db3450..ade9158cbf 100644 --- a/hw/acpi/core.c +++ b/hw/acpi/core.c @@ -27,7 +27,7 @@ #include "qapi/error.h" #include "qapi/opts-visitor.h" #include "qapi/qapi-events-run-state.h" -#include "qapi/qapi-visit-misc.h" +#include "qapi/qapi-visit-acpi.h" #include "qemu/error-report.h" #include "qemu/module.h" #include "qemu/option.h" diff --git a/hw/acpi/cpu.c b/hw/acpi/cpu.c index 8dd4d8ebbf..f099b50927 100644 --- a/hw/acpi/cpu.c +++ b/hw/acpi/cpu.c @@ -3,7 +3,7 @@ #include "migration/vmstate.h" #include "hw/acpi/cpu.h" #include "qapi/error.h" -#include "qapi/qapi-events-misc.h" +#include "qapi/qapi-events-acpi.h" #include "trace.h" #include "sysemu/numa.h" diff --git a/hw/acpi/memory_hotplug.c b/hw/acpi/memory_hotplug.c index dfe57af429..f2552b2a46 100644 --- a/hw/acpi/memory_hotplug.c +++ b/hw/acpi/memory_hotplug.c @@ -7,8 +7,8 @@ #include "migration/vmstate.h" #include "trace.h" #include "qapi/error.h" +#include "qapi/qapi-events-acpi.h" #include "qapi/qapi-events-machine.h" -#include "qapi/qapi-events-misc.h" #define MEMORY_SLOTS_NUMBER "MDNR" #define MEMORY_HOTPLUG_IO_REGION "HPMR" diff --git a/monitor/qmp-cmds.c b/monitor/qmp-cmds.c index 864cbfa32e..0ab5b78580 100644 --- a/monitor/qmp-cmds.c +++ b/monitor/qmp-cmds.c @@ -30,6 +30,7 @@ #include "sysemu/blockdev.h" #include "sysemu/block-backend.h" #include "qapi/error.h" +#include "qapi/qapi-commands-acpi.h" #include "qapi/qapi-commands-block.h" #include "qapi/qapi-commands-control.h" #include "qapi/qapi-commands-machine.h" diff --git a/MAINTAINERS b/MAINTAINERS index 5eed1e692b..f99b5db940 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1632,6 +1632,7 @@ F: hw/acpi/* F: hw/smbios/* F: hw/i386/acpi-build.[hc] F: hw/arm/virt-acpi-build.c +F: qapi/acpi.json F: tests/qtest/bios-tables-test* F: tests/qtest/acpi-utils.[hc] F: tests/data/acpi/ diff --git a/qapi/meson.build b/qapi/meson.build index 2b2872a41d..f57acc2402 100644 --- a/qapi/meson.build +++ b/qapi/meson.build @@ -14,6 +14,7 @@ util_ss.add(files( )) qapi_all_modules = [ + 'acpi', 'audio', 'authz', 'block-core', From patchwork Tue Sep 29 20:19:05 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304121 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, 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 0DD22C4727C for ; Tue, 29 Sep 2020 20:24:22 +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 5AF2F2076B for ; Tue, 29 Sep 2020 20:24:21 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Sof5tra3" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 5AF2F2076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:40554 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMAe-0007Cw-0O for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:24:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59662) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM68-0001nI-GI for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:26342) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM62-0003UF-NR for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:40 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410773; 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=hcxMoybGVAVk+zhb7G9oVk0b12g9DqOFO6UWlKHtzto=; b=Sof5tra3hyNGSlCI7NJSOVPG4Tt4aPJii4iyiE9Xy5/dqxOVDlcW5iYdNoQ+AqA2Z3tSfB egGVVnBBYiA4VcERDjXbpYn++WQiosXVJW5D5oHSH4T8HPo1pinsIUXUq9o/d9ms8b95cn ZMefcIsiwvTh4iO6efC5cR1r3TdhGGM= 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-337-QxlwWTU5Pz2GL62hGrfENg-1; Tue, 29 Sep 2020 16:19:31 -0400 X-MC-Unique: QxlwWTU5Pz2GL62hGrfENg-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3B62D801AE2; Tue, 29 Sep 2020 20:19:30 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B310F5C1C4; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id AB3A611358BE; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 08/29] qapi: Extract PCI commands to 'pci.json' Date: Tue, 29 Sep 2020 22:19:05 +0200 Message-Id: <20200929201926.2155622-9-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Paolo Bonzini Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Philippe Mathieu-Daudé Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode emulation. Extracting the PCI commands to their own schema reduces the size of the qapi-misc* headers generated, and pulls less QAPI-generated code into user-mode. Suggested-by: Markus Armbruster Acked-by: Markus Armbruster Acked-by: Paolo Bonzini Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20200913195348.1064154-9-philmd@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster --- qapi/misc.json | 306 ---------------------------------------- qapi/pci.json | 316 ++++++++++++++++++++++++++++++++++++++++++ qapi/qapi-schema.json | 1 + hw/pci/pci-stub.c | 2 +- hw/pci/pci.c | 2 +- monitor/hmp-cmds.c | 1 + MAINTAINERS | 1 + qapi/meson.build | 1 + 8 files changed, 322 insertions(+), 308 deletions(-) create mode 100644 qapi/pci.json diff --git a/qapi/misc.json b/qapi/misc.json index 4b00b18e54..694d2142f3 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -157,312 +157,6 @@ { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'], 'allow-preconfig': true } -## -# @PciMemoryRange: -# -# A PCI device memory region -# -# @base: the starting address (guest physical) -# -# @limit: the ending address (guest physical) -# -# Since: 0.14.0 -## -{ 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} } - -## -# @PciMemoryRegion: -# -# Information about a PCI device I/O region. -# -# @bar: the index of the Base Address Register for this region -# -# @type: - 'io' if the region is a PIO region -# - 'memory' if the region is a MMIO region -# -# @size: memory size -# -# @prefetch: if @type is 'memory', true if the memory is prefetchable -# -# @mem_type_64: if @type is 'memory', true if the BAR is 64-bit -# -# Since: 0.14.0 -## -{ 'struct': 'PciMemoryRegion', - 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int', - '*prefetch': 'bool', '*mem_type_64': 'bool' } } - -## -# @PciBusInfo: -# -# Information about a bus of a PCI Bridge device -# -# @number: primary bus interface number. This should be the number of the -# bus the device resides on. -# -# @secondary: secondary bus interface number. This is the number of the -# main bus for the bridge -# -# @subordinate: This is the highest number bus that resides below the -# bridge. -# -# @io_range: The PIO range for all devices on this bridge -# -# @memory_range: The MMIO range for all devices on this bridge -# -# @prefetchable_range: The range of prefetchable MMIO for all devices on -# this bridge -# -# Since: 2.4 -## -{ 'struct': 'PciBusInfo', - 'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int', - 'io_range': 'PciMemoryRange', - 'memory_range': 'PciMemoryRange', - 'prefetchable_range': 'PciMemoryRange' } } - -## -# @PciBridgeInfo: -# -# Information about a PCI Bridge device -# -# @bus: information about the bus the device resides on -# -# @devices: a list of @PciDeviceInfo for each device on this bridge -# -# Since: 0.14.0 -## -{ 'struct': 'PciBridgeInfo', - 'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} } - -## -# @PciDeviceClass: -# -# Information about the Class of a PCI device -# -# @desc: a string description of the device's class -# -# @class: the class code of the device -# -# Since: 2.4 -## -{ 'struct': 'PciDeviceClass', - 'data': {'*desc': 'str', 'class': 'int'} } - -## -# @PciDeviceId: -# -# Information about the Id of a PCI device -# -# @device: the PCI device id -# -# @vendor: the PCI vendor id -# -# @subsystem: the PCI subsystem id (since 3.1) -# -# @subsystem-vendor: the PCI subsystem vendor id (since 3.1) -# -# Since: 2.4 -## -{ 'struct': 'PciDeviceId', - 'data': {'device': 'int', 'vendor': 'int', '*subsystem': 'int', - '*subsystem-vendor': 'int'} } - -## -# @PciDeviceInfo: -# -# Information about a PCI device -# -# @bus: the bus number of the device -# -# @slot: the slot the device is located in -# -# @function: the function of the slot used by the device -# -# @class_info: the class of the device -# -# @id: the PCI device id -# -# @irq: if an IRQ is assigned to the device, the IRQ number -# -# @irq_pin: the IRQ pin, zero means no IRQ (since 5.1) -# -# @qdev_id: the device name of the PCI device -# -# @pci_bridge: if the device is a PCI bridge, the bridge information -# -# @regions: a list of the PCI I/O regions associated with the device -# -# Notes: the contents of @class_info.desc are not stable and should only be -# treated as informational. -# -# Since: 0.14.0 -## -{ 'struct': 'PciDeviceInfo', - 'data': {'bus': 'int', 'slot': 'int', 'function': 'int', - 'class_info': 'PciDeviceClass', 'id': 'PciDeviceId', - '*irq': 'int', 'irq_pin': 'int', 'qdev_id': 'str', - '*pci_bridge': 'PciBridgeInfo', 'regions': ['PciMemoryRegion'] }} - -## -# @PciInfo: -# -# Information about a PCI bus -# -# @bus: the bus index -# -# @devices: a list of devices on this bus -# -# Since: 0.14.0 -## -{ 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} } - -## -# @query-pci: -# -# Return information about the PCI bus topology of the guest. -# -# Returns: a list of @PciInfo for each PCI bus. Each bus is -# represented by a json-object, which has a key with a json-array of -# all PCI devices attached to it. Each device is represented by a -# json-object. -# -# Since: 0.14.0 -# -# Example: -# -# -> { "execute": "query-pci" } -# <- { "return": [ -# { -# "bus": 0, -# "devices": [ -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 0, -# "class_info": { -# "class": 1536, -# "desc": "Host bridge" -# }, -# "id": { -# "device": 32902, -# "vendor": 4663 -# }, -# "function": 0, -# "regions": [ -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 1, -# "class_info": { -# "class": 1537, -# "desc": "ISA bridge" -# }, -# "id": { -# "device": 32902, -# "vendor": 28672 -# }, -# "function": 0, -# "regions": [ -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 1, -# "class_info": { -# "class": 257, -# "desc": "IDE controller" -# }, -# "id": { -# "device": 32902, -# "vendor": 28688 -# }, -# "function": 1, -# "regions": [ -# { -# "bar": 4, -# "size": 16, -# "address": 49152, -# "type": "io" -# } -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "slot": 2, -# "class_info": { -# "class": 768, -# "desc": "VGA controller" -# }, -# "id": { -# "device": 4115, -# "vendor": 184 -# }, -# "function": 0, -# "regions": [ -# { -# "prefetch": true, -# "mem_type_64": false, -# "bar": 0, -# "size": 33554432, -# "address": 4026531840, -# "type": "memory" -# }, -# { -# "prefetch": false, -# "mem_type_64": false, -# "bar": 1, -# "size": 4096, -# "address": 4060086272, -# "type": "memory" -# }, -# { -# "prefetch": false, -# "mem_type_64": false, -# "bar": 6, -# "size": 65536, -# "address": -1, -# "type": "memory" -# } -# ] -# }, -# { -# "bus": 0, -# "qdev_id": "", -# "irq": 11, -# "slot": 4, -# "class_info": { -# "class": 1280, -# "desc": "RAM controller" -# }, -# "id": { -# "device": 6900, -# "vendor": 4098 -# }, -# "function": 0, -# "regions": [ -# { -# "bar": 0, -# "size": 32, -# "address": 49280, -# "type": "io" -# } -# ] -# } -# ] -# } -# ] -# } -# -# Note: This example has been shortened as the real response is too long. -# -## -{ 'command': 'query-pci', 'returns': ['PciInfo'] } - ## # @stop: # diff --git a/qapi/pci.json b/qapi/pci.json new file mode 100644 index 0000000000..b79cbd787b --- /dev/null +++ b/qapi/pci.json @@ -0,0 +1,316 @@ +# -*- Mode: Python -*- +# vim: filetype=python +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. +# SPDX-License-Identifier: GPL-2.0-or-later + +## +# = PCI +## + +## +# @PciMemoryRange: +# +# A PCI device memory region +# +# @base: the starting address (guest physical) +# +# @limit: the ending address (guest physical) +# +# Since: 0.14.0 +## +{ 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} } + +## +# @PciMemoryRegion: +# +# Information about a PCI device I/O region. +# +# @bar: the index of the Base Address Register for this region +# +# @type: - 'io' if the region is a PIO region +# - 'memory' if the region is a MMIO region +# +# @size: memory size +# +# @prefetch: if @type is 'memory', true if the memory is prefetchable +# +# @mem_type_64: if @type is 'memory', true if the BAR is 64-bit +# +# Since: 0.14.0 +## +{ 'struct': 'PciMemoryRegion', + 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int', + '*prefetch': 'bool', '*mem_type_64': 'bool' } } + +## +# @PciBusInfo: +# +# Information about a bus of a PCI Bridge device +# +# @number: primary bus interface number. This should be the number of the +# bus the device resides on. +# +# @secondary: secondary bus interface number. This is the number of the +# main bus for the bridge +# +# @subordinate: This is the highest number bus that resides below the +# bridge. +# +# @io_range: The PIO range for all devices on this bridge +# +# @memory_range: The MMIO range for all devices on this bridge +# +# @prefetchable_range: The range of prefetchable MMIO for all devices on +# this bridge +# +# Since: 2.4 +## +{ 'struct': 'PciBusInfo', + 'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int', + 'io_range': 'PciMemoryRange', + 'memory_range': 'PciMemoryRange', + 'prefetchable_range': 'PciMemoryRange' } } + +## +# @PciBridgeInfo: +# +# Information about a PCI Bridge device +# +# @bus: information about the bus the device resides on +# +# @devices: a list of @PciDeviceInfo for each device on this bridge +# +# Since: 0.14.0 +## +{ 'struct': 'PciBridgeInfo', + 'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} } + +## +# @PciDeviceClass: +# +# Information about the Class of a PCI device +# +# @desc: a string description of the device's class +# +# @class: the class code of the device +# +# Since: 2.4 +## +{ 'struct': 'PciDeviceClass', + 'data': {'*desc': 'str', 'class': 'int'} } + +## +# @PciDeviceId: +# +# Information about the Id of a PCI device +# +# @device: the PCI device id +# +# @vendor: the PCI vendor id +# +# @subsystem: the PCI subsystem id (since 3.1) +# +# @subsystem-vendor: the PCI subsystem vendor id (since 3.1) +# +# Since: 2.4 +## +{ 'struct': 'PciDeviceId', + 'data': {'device': 'int', 'vendor': 'int', '*subsystem': 'int', + '*subsystem-vendor': 'int'} } + +## +# @PciDeviceInfo: +# +# Information about a PCI device +# +# @bus: the bus number of the device +# +# @slot: the slot the device is located in +# +# @function: the function of the slot used by the device +# +# @class_info: the class of the device +# +# @id: the PCI device id +# +# @irq: if an IRQ is assigned to the device, the IRQ number +# +# @irq_pin: the IRQ pin, zero means no IRQ (since 5.1) +# +# @qdev_id: the device name of the PCI device +# +# @pci_bridge: if the device is a PCI bridge, the bridge information +# +# @regions: a list of the PCI I/O regions associated with the device +# +# Notes: the contents of @class_info.desc are not stable and should only be +# treated as informational. +# +# Since: 0.14.0 +## +{ 'struct': 'PciDeviceInfo', + 'data': {'bus': 'int', 'slot': 'int', 'function': 'int', + 'class_info': 'PciDeviceClass', 'id': 'PciDeviceId', + '*irq': 'int', 'irq_pin': 'int', 'qdev_id': 'str', + '*pci_bridge': 'PciBridgeInfo', 'regions': ['PciMemoryRegion'] }} + +## +# @PciInfo: +# +# Information about a PCI bus +# +# @bus: the bus index +# +# @devices: a list of devices on this bus +# +# Since: 0.14.0 +## +{ 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} } + +## +# @query-pci: +# +# Return information about the PCI bus topology of the guest. +# +# Returns: a list of @PciInfo for each PCI bus. Each bus is +# represented by a json-object, which has a key with a json-array of +# all PCI devices attached to it. Each device is represented by a +# json-object. +# +# Since: 0.14.0 +# +# Example: +# +# -> { "execute": "query-pci" } +# <- { "return": [ +# { +# "bus": 0, +# "devices": [ +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 0, +# "class_info": { +# "class": 1536, +# "desc": "Host bridge" +# }, +# "id": { +# "device": 32902, +# "vendor": 4663 +# }, +# "function": 0, +# "regions": [ +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 1, +# "class_info": { +# "class": 1537, +# "desc": "ISA bridge" +# }, +# "id": { +# "device": 32902, +# "vendor": 28672 +# }, +# "function": 0, +# "regions": [ +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 1, +# "class_info": { +# "class": 257, +# "desc": "IDE controller" +# }, +# "id": { +# "device": 32902, +# "vendor": 28688 +# }, +# "function": 1, +# "regions": [ +# { +# "bar": 4, +# "size": 16, +# "address": 49152, +# "type": "io" +# } +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "slot": 2, +# "class_info": { +# "class": 768, +# "desc": "VGA controller" +# }, +# "id": { +# "device": 4115, +# "vendor": 184 +# }, +# "function": 0, +# "regions": [ +# { +# "prefetch": true, +# "mem_type_64": false, +# "bar": 0, +# "size": 33554432, +# "address": 4026531840, +# "type": "memory" +# }, +# { +# "prefetch": false, +# "mem_type_64": false, +# "bar": 1, +# "size": 4096, +# "address": 4060086272, +# "type": "memory" +# }, +# { +# "prefetch": false, +# "mem_type_64": false, +# "bar": 6, +# "size": 65536, +# "address": -1, +# "type": "memory" +# } +# ] +# }, +# { +# "bus": 0, +# "qdev_id": "", +# "irq": 11, +# "slot": 4, +# "class_info": { +# "class": 1280, +# "desc": "RAM controller" +# }, +# "id": { +# "device": 6900, +# "vendor": 4098 +# }, +# "function": 0, +# "regions": [ +# { +# "bar": 0, +# "size": 32, +# "address": 49280, +# "type": "io" +# } +# ] +# } +# ] +# } +# ] +# } +# +# Note: This example has been shortened as the real response is too long. +# +## +{ 'command': 'query-pci', 'returns': ['PciInfo'] } diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 4d8b3a9afe..54c8ba6444 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -86,3 +86,4 @@ { 'include': 'misc-target.json' } { 'include': 'audio.json' } { 'include': 'acpi.json' } +{ 'include': 'pci.json' } diff --git a/hw/pci/pci-stub.c b/hw/pci/pci-stub.c index cc2a2e1f73..3a027c42e4 100644 --- a/hw/pci/pci-stub.c +++ b/hw/pci/pci-stub.c @@ -22,7 +22,7 @@ #include "sysemu/sysemu.h" #include "monitor/monitor.h" #include "qapi/error.h" -#include "qapi/qapi-commands-misc.h" +#include "qapi/qapi-commands-pci.h" #include "qapi/qmp/qerror.h" #include "hw/pci/pci.h" #include "hw/pci/msi.h" diff --git a/hw/pci/pci.c b/hw/pci/pci.c index fce725474b..3c8f10b461 100644 --- a/hw/pci/pci.c +++ b/hw/pci/pci.c @@ -46,7 +46,7 @@ #include "hw/hotplug.h" #include "hw/boards.h" #include "qapi/error.h" -#include "qapi/qapi-commands-misc.h" +#include "qapi/qapi-commands-pci.h" #include "qemu/cutils.h" //#define DEBUG_PCI diff --git a/monitor/hmp-cmds.c b/monitor/hmp-cmds.c index de01ba2084..dc0de39219 100644 --- a/monitor/hmp-cmds.c +++ b/monitor/hmp-cmds.c @@ -36,6 +36,7 @@ #include "qapi/qapi-commands-migration.h" #include "qapi/qapi-commands-misc.h" #include "qapi/qapi-commands-net.h" +#include "qapi/qapi-commands-pci.h" #include "qapi/qapi-commands-rocker.h" #include "qapi/qapi-commands-run-state.h" #include "qapi/qapi-commands-tpm.h" diff --git a/MAINTAINERS b/MAINTAINERS index f99b5db940..be0a8e648c 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1617,6 +1617,7 @@ F: include/hw/pci/* F: hw/misc/pci-testdev.c F: hw/pci/* F: hw/pci-bridge/* +F: qapi/pci.json F: docs/pci* F: docs/specs/*pci* F: default-configs/pci.mak diff --git a/qapi/meson.build b/qapi/meson.build index f57acc2402..298b510492 100644 --- a/qapi/meson.build +++ b/qapi/meson.build @@ -35,6 +35,7 @@ qapi_all_modules = [ 'net', 'pragma', 'qdev', + 'pci', 'qom', 'rdma', 'rocker', From patchwork Tue Sep 29 20:19:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304122 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 85E1CC4727C for ; Tue, 29 Sep 2020 20:24: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 906432076B for ; Tue, 29 Sep 2020 20:24:16 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="RDVb3eJp" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 906432076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:40068 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMAZ-000704-Hy for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:24:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59702) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6B-0001oR-Eu for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:43 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:24693) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM62-0003Sv-Dv for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:43 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410773; 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=5lGTelQT9KRDYB0pvFHIOCxQ4Sh/H0ePPpMQppP0IWM=; b=RDVb3eJpdyvsrI4R9E86q+K7ME8n/jEXimV9dDpS6NnOJFavSNjj1YLRh9Cn9gOKHVJpjJ D17oBBg0t9bSmZ/9+kR0SZCVxHId2Tuul/uGBvhyiqrxDNMSLx5mZYyv5vRSiatM1B2C4o xZsENIXMa7XRGeKXI14v1yIzrv4qsWE= 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-400-apRKzlRNNxe4fhw8aNlhag-1; Tue, 29 Sep 2020 16:19:31 -0400 X-MC-Unique: apRKzlRNNxe4fhw8aNlhag-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 12A538030B4; Tue, 29 Sep 2020 20:19:30 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B3CDA5C1CF; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id AF01511358BF; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 09/29] qapi: Fix doc comment indentation again Date: Tue, 29 Sep 2020 22:19:06 +0200 Message-Id: <20200929201926.2155622-10-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell In commit 26ec4e53f2 and similar commits we fixed the indentation for doc comments in our qapi json files to follow a new stricter standard for indentation, which permits only: @arg: description line 1 description line 2 or: @arg: line 1 line 2 but because the script updates that enforce this are not yet in the tree we have had a steady trickle of subsequent changes which didn't follow the new rules. Fix the latest round of mis-indented doc comments. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-2-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Updated for commit 4c437254b807 and a83e24ba1a5] Signed-off-by: Markus Armbruster --- qapi/block-core.json | 4 +- qapi/machine.json | 4 +- qapi/migration.json | 108 +++++++++++++++++++++---------------------- 3 files changed, 59 insertions(+), 57 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 3c16f1e11d..dd77a91174 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -4316,8 +4316,8 @@ # @data-file-raw: True if the external data file must stay valid as a # standalone (read-only) raw image without looking at qcow2 # metadata (default: false; since: 4.0) -# @extended-l2 True to make the image have extended L2 entries -# (default: false; since 5.2) +# @extended-l2: True to make the image have extended L2 entries +# (default: false; since 5.2) # @size: Size of the virtual disk in bytes # @version: Compatibility level (default: v3) # @backing-file: File name of the backing file if a backing file diff --git a/qapi/machine.json b/qapi/machine.json index c061cce0e4..2c237563ea 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1001,9 +1001,11 @@ # # Request the balloon driver to change its balloon size. # -# @value: the target logical size of the VM in bytes +# @value: the target logical size of the VM in bytes. # We can deduce the size of the balloon using this formula: +# # logical_vm_size = vm_ram_size - balloon_size +# # From it we have: balloon_size = vm_ram_size - @value # # Returns: - Nothing on success diff --git a/qapi/migration.json b/qapi/migration.json index ce2216cfea..7f5e6fd681 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -681,23 +681,23 @@ # Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such +# aliases may for example be the corresponding names on the +# opposite site. +# The mapping must be one-to-one, but not necessarily +# complete: On the source, unmapped bitmaps and all bitmaps +# on unmapped nodes will be ignored. On the destination, +# encountering an unmapped alias in the incoming migration +# stream will result in a report, and all further bitmap +# migration data will then be discarded. +# Note that the destination does not know about bitmaps it +# does not receive, so there is no limitation or requirement +# regarding the number of bitmaps received, or how they are +# named, or on which nodes they are placed. +# By default (when this parameter has never been set), bitmap +# names are mapped to themselves. Nodes are mapped to their +# block device name if there is one, and to their node name +# otherwise. (Since 5.2) # # Since: 2.4 ## @@ -841,23 +841,23 @@ # Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such +# aliases may for example be the corresponding names on the +# opposite site. +# The mapping must be one-to-one, but not necessarily +# complete: On the source, unmapped bitmaps and all bitmaps +# on unmapped nodes will be ignored. On the destination, +# encountering an unmapped alias in the incoming migration +# stream will result in a report, and all further bitmap +# migration data will then be discarded. +# Note that the destination does not know about bitmaps it +# does not receive, so there is no limitation or requirement +# regarding the number of bitmaps received, or how they are +# named, or on which nodes they are placed. +# By default (when this parameter has never been set), bitmap +# names are mapped to themselves. Nodes are mapped to their +# block device name if there is one, and to their node name +# otherwise. (Since 5.2) # # Since: 2.4 ## @@ -1037,23 +1037,23 @@ # Defaults to 1. (Since 5.0) # # @block-bitmap-mapping: Maps block nodes and bitmaps on them to -# aliases for the purpose of dirty bitmap migration. Such -# aliases may for example be the corresponding names on the -# opposite site. -# The mapping must be one-to-one, but not necessarily -# complete: On the source, unmapped bitmaps and all bitmaps -# on unmapped nodes will be ignored. On the destination, -# encountering an unmapped alias in the incoming migration -# stream will result in a report, and all further bitmap -# migration data will then be discarded. -# Note that the destination does not know about bitmaps it -# does not receive, so there is no limitation or requirement -# regarding the number of bitmaps received, or how they are -# named, or on which nodes they are placed. -# By default (when this parameter has never been set), bitmap -# names are mapped to themselves. Nodes are mapped to their -# block device name if there is one, and to their node name -# otherwise. (Since 5.2) +# aliases for the purpose of dirty bitmap migration. Such +# aliases may for example be the corresponding names on the +# opposite site. +# The mapping must be one-to-one, but not necessarily +# complete: On the source, unmapped bitmaps and all bitmaps +# on unmapped nodes will be ignored. On the destination, +# encountering an unmapped alias in the incoming migration +# stream will result in a report, and all further bitmap +# migration data will then be discarded. +# Note that the destination does not know about bitmaps it +# does not receive, so there is no limitation or requirement +# regarding the number of bitmaps received, or how they are +# named, or on which nodes they are placed. +# By default (when this parameter has never been set), bitmap +# names are mapped to themselves. Nodes are mapped to their +# block device name if there is one, and to their node name +# otherwise. (Since 5.2) # # Since: 2.4 ## @@ -1744,9 +1744,9 @@ # Information about current dirty page rate of vm. # # @dirty-rate: @dirtyrate describing the dirty page rate of vm -# in units of MB/s. -# If this field returns '-1', it means querying has not -# yet started or completed. +# in units of MB/s. +# If this field returns '-1', it means querying has not +# yet started or completed. # # @status: status containing dirtyrate query status includes # 'unstarted' or 'measuring' or 'measured' From patchwork Tue Sep 29 20:19:07 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272450 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 5A8AAC47420 for ; Tue, 29 Sep 2020 20:21: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 AC9762076B for ; Tue, 29 Sep 2020 20:21:40 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="OlaomrJg" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org AC9762076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:60220 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNM83-0003aX-MQ for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:21:39 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59622) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM66-0001lQ-5r for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:38 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:23763) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM62-0003Su-EF for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:37 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410773; 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=RUESf4c7tu9j2EpuNq5laxTXxEk8TmEK8eJ9ksZ2j9Q=; b=OlaomrJglw1P09LEL7aDDLJTRsh2IqyqJyZZCU6H1LF7qxi/T3FR87bMZ+IStHK/eJ3LuB 36X/nfNK/oVPw9pLeOdqerI1oGYrMT6z0Wk071SJlB1jX4mSoqhQlh9jdOCHFwSK7D7Cou Nx1bb1xBfLt/RPv7YBr8r5N5lVF/OS0= 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-304-tQz5bF8FNcO7Kpioj_c6bw-1; Tue, 29 Sep 2020 16:19:30 -0400 X-MC-Unique: tQz5bF8FNcO7Kpioj_c6bw-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E370318BE164; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B70A578807; Tue, 29 Sep 2020 20:19:29 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B282F11358C0; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 10/29] qapi/block.json: Add newline after "Example:" for block-latency-histogram-set Date: Tue, 29 Sep 2020 22:19:07 +0200 Message-Id: <20200929201926.2155622-11-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell The block-latency-histogram-set command is the only one which uses the Example/Examples section with the first line of the documentation immediately following the ':'. Bring it into line with the rest. This will allow us to avoid special-casing the indentation handling for "Examples" sections; instead for Examples as for any other section header these two indentations will be equivalent: Examples: Line one Line two Examples: Line one Line two Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-3-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- qapi/block.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/qapi/block.json b/qapi/block.json index c54a393cf3..a009f7d3a2 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -528,7 +528,8 @@ # # Since: 4.0 # -# Example: set new histograms for all io types with intervals +# Example: +# set new histograms for all io types with intervals # [0, 10), [10, 50), [50, 100), [100, +inf): # # -> { "execute": "block-latency-histogram-set", @@ -536,7 +537,8 @@ # "boundaries": [10, 50, 100] } } # <- { "return": {} } # -# Example: set new histogram only for write, other histograms will remain +# Example: +# set new histogram only for write, other histograms will remain # not changed (or not created): # # -> { "execute": "block-latency-histogram-set", @@ -544,7 +546,8 @@ # "boundaries-write": [10, 50, 100] } } # <- { "return": {} } # -# Example: set new histograms with the following intervals: +# Example: +# set new histograms with the following intervals: # read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) # write: [0, 1000), [1000, 5000), [5000, +inf) # @@ -554,7 +557,8 @@ # "boundaries-write": [1000, 5000] } } # <- { "return": {} } # -# Example: remove all latency histograms: +# Example: +# remove all latency histograms: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } } From patchwork Tue Sep 29 20:19:08 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272447 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 40E9EC4727F for ; Tue, 29 Sep 2020 20:24:48 +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 878EB20848 for ; Tue, 29 Sep 2020 20:24:47 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="TnJBEGUm" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 878EB20848 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:42976 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMB4-0008Bq-HT for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:24:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59680) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM69-0001np-L4 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:42 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:32824) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0003UV-G7 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:41 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410774; 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=1wd6JHXx4E4iQnRlGQrgtI1OqrWGnVvKRipq4pNljDA=; b=TnJBEGUmSMaa4geElA/qhzTFNG8PQ2JSPkpd+qOr56aOHZjNMEingy3WpEhhc16L7+1+4Z nGAFkWfpQp/kblQvnxNawYgbLiEttZh0hZPPgQt480qypsNTilA3qOV6jsolSMqsi+h/UE EknWQYI8BHl8McjEQMnv8/nYdsJDBAI= 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-95-oB9M1F9TPvutS4k67C_PBA-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: oB9M1F9TPvutS4k67C_PBA-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3FA161040C24; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1105B19C4F; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B6AFE11358C2; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 11/29] tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension Date: Tue, 29 Sep 2020 22:19:08 +0200 Message-Id: <20200929201926.2155622-12-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell doc-good.json tests doc comment parser corner cases. We're about to largely replace it by a Sphinx extension, which will have different corner cases. Tweak the test so it passes both with the old parser and the Sphinx extension, by making it match the more restrictive rST syntax: * in a single list the bullet types must all match * lists must have leading and following blank lines * the rules on when and where indentation matters differ * the '|' example syntax is going to go away entirely, so stop testing it This will avoid the tests spuriously breaking when we tighten up the parser code in the following commits. Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-4-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster --- tests/qapi-schema/doc-good.json | 25 +++++++++++++------------ tests/qapi-schema/doc-good.out | 12 ++++++------ tests/qapi-schema/doc-good.texi | 12 +++--------- 3 files changed, 22 insertions(+), 27 deletions(-) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 9da72a1f55..c6822145c4 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -12,25 +12,25 @@ # # *strong* _with emphasis_ # @var {in braces} +# # * List item one -# - Two, multiple +# * Two, multiple # lines # -# 3. Three -# Still in list +# * Three +# Still in list +# +# Not in list # -# Not in list # - Second list -# Note: still in list +# Note: still in list # # Note: not in list +# # 1. Third list # is numbered # -# - another item -# -# | example -# | multiple lines +# 2. another item # # Returns: the King # Since: the first age @@ -68,7 +68,7 @@ ## # @Base: # @base1: -# the first member +# the first member ## { 'struct': 'Base', 'data': { 'base1': 'Enum' } } @@ -116,7 +116,7 @@ ## # @Alternate: # @i: an integer -# @b is undocumented +# @b is undocumented # # Features: # @alt-feat: a feature @@ -134,7 +134,7 @@ # @arg1: the first argument # # @arg2: the second -# argument +# argument # # Features: # @cmd-feat1: a feature @@ -143,6 +143,7 @@ # Returns: @Object # TODO: frobnicate # Notes: +# # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam # diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index d78a424cd9..acb00ade17 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -75,25 +75,25 @@ doc freeform *strong* _with emphasis_ @var {in braces} + * List item one -- Two, multiple +* Two, multiple lines -3. Three +* Three Still in list Not in list + - Second list Note: still in list Note: not in list + 1. Third list is numbered -- another item - -| example -| multiple lines +2. another item Returns: the King Since: the first age diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index 7f28fb7a0f..12808989ff 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -6,6 +6,7 @@ @strong{strong} @emph{with emphasis} @code{var} @{in braces@} + @itemize @bullet @item List item one @@ -20,6 +21,7 @@ Still in list @end itemize Not in list + @itemize @minus @item Second list @@ -28,6 +30,7 @@ Note: still in list @end itemize Note: not in list + @enumerate @item Third list @@ -36,15 +39,6 @@ is numbered @item another item -@example -example -@end example - -@example -multiple lines -@end example - - @end enumerate Returns: the King From patchwork Tue Sep 29 20:19:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272444 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 5261BC4727C for ; Tue, 29 Sep 2020 20:28:52 +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 A0ABE2076B for ; Tue, 29 Sep 2020 20:28:51 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Cr+jvLeV" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org A0ABE2076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:56556 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMF0-0005WB-GE for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:28:50 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59740) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6D-0001sD-Dy for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:48433) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0003Uu-P8 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:45 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410776; 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=5xXGdpZWFIbYsKeR6BJ9bRVsOlgEvEJGRYy4+ov2b0E=; b=Cr+jvLeVGOYfA03OZsALpLOm+wOyKBtF+3+JUcWM9nu3lzsB/fUdThu8nMdut5nZXDzy5G N2x+JpEnoXVYUgdyvj8iPeH+b0tjpHtrlFS4bX8md/duKsmkPVJ9CLOOjiEvpDYpn3G2Pa XT3cPVR7MP1XmS+kZd9aBtxIFfPD+l0= 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-462-XkbWE1Z2O723Dl8a1WF0Yw-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: XkbWE1Z2O723Dl8a1WF0Yw-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 6DFA710BBEC3; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 1B2FB6198E; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id BA56011358C3; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 12/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Tue, 29 Sep 2020 22:19:09 +0200 Message-Id: <20200929201926.2155622-13-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell As we accumulate lines from doc comments when parsing the JSON, the QAPIDoc class generally strips leading and trailing whitespace using line.strip() when it calls _append_freeform(). This is fine for Texinfo, but for rST leading whitespace is significant. We'd like to move to having the text in doc comments be rST format rather than a custom syntax, so move the removal of leading whitespace from the QAPIDoc class to the texinfo-specific processing code in texi_format() in qapi/doc.py. (Trailing whitespace will always be stripped by the rstrip() in Section::append regardless.) In a followup commit we will make the whitespace in the lines of doc comment sections more consistently follow the input source. There is no change to the generated .texi files before and after this commit. Because the qapi-schema test checks the exact values of the documentation comments against a reference, we need to update that reference to match the new whitespace. In the first four places this is now correctly checking that we did put in the amount of whitespace to pass a rST-formatted list to the backend; in the last two places the extra whitespace is 'wrong' and will go away again in the following commit. Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-5-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster --- scripts/qapi/doc.py | 1 + scripts/qapi/parser.py | 12 ++++-------- tests/qapi-schema/doc-good.out | 12 ++++++------ 3 files changed, 11 insertions(+), 14 deletions(-) diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 92f584edcf..7764de1e4b 100644 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -79,6 +79,7 @@ def texi_format(doc): inlist = '' lastempty = False for line in doc.split('\n'): + line = line.strip() empty = line == '' # FIXME: Doing this in a single if / elif chain is diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 165925ca72..04bf10db37 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -427,10 +427,10 @@ class QAPIDoc: self._append_line = self._append_various_line self._append_various_line(line) else: - self._append_freeform(line.strip()) + self._append_freeform(line) else: # This is a free-form documentation block - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_args_line(self, line): """ @@ -463,7 +463,7 @@ class QAPIDoc: self._append_various_line(line) return - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_features_line(self, line): name = line.split(' ', 1)[0] @@ -482,7 +482,7 @@ class QAPIDoc: self._append_various_line(line) return - self._append_freeform(line.strip()) + self._append_freeform(line) def _append_various_line(self, line): """ @@ -505,10 +505,6 @@ class QAPIDoc: line = line[len(name)+1:] self._start_section(name[:-1]) - if (not self._section.name or - not self._section.name.startswith('Example')): - line = line.strip() - self._append_freeform(line) def _start_symbol_section(self, symbols_dict, name): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index acb00ade17..9993ffcd89 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -78,20 +78,20 @@ doc freeform * List item one * Two, multiple -lines + lines * Three -Still in list + Still in list Not in list - Second list -Note: still in list + Note: still in list Note: not in list 1. Third list -is numbered + is numbered 2. another item @@ -159,7 +159,7 @@ doc symbol=Alternate arg=i an integer -@b is undocumented + @b is undocumented arg=b feature=alt-feat @@ -174,7 +174,7 @@ doc symbol=cmd the first argument arg=arg2 the second -argument + argument arg=arg3 feature=cmd-feat1 From patchwork Tue Sep 29 20:19:10 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304111 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 E24F8C47420 for ; Tue, 29 Sep 2020 20:46:14 +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 E3B1D2072E for ; Tue, 29 Sep 2020 20:46:13 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="iqF7nAb7" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E3B1D2072E Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:40044 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMVo-0006Xn-DH for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:46:12 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59906) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6Y-00025J-5Z for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:20:06 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:58558) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM6S-0003Xr-Li for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:20:05 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410800; 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=yN07+6aETQ0UOyiqHqTERmvN/o053m9kbVFNHPTfsRo=; b=iqF7nAb79ghQAS8uUJDui3mpV43SfSCxTb+2HcKJOqHUbvn6q5JBS4nUPJd85tycybbdq9 85j08DaWnDcH4FPMsCPqRGRQndZ851dosawsm02GTju3ywgiUGKpjLPC+/LcppawHpgS6W 0nkPVYAhT3QZcNCbTIaGKs+ZMKFZLW8= 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-231-9m1pedOJMFKzh8ovOZy_3Q-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: 9m1pedOJMFKzh8ovOZy_3Q-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A2F5E10BBED3; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 297D8619B5; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id BE11911358C4; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 13/29] scripts/qapi/parser.py: improve doc comment indent handling Date: Tue, 29 Sep 2020 22:19:10 +0200 Message-Id: <20200929201926.2155622-14-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some text some more text indented line 3 we save it for the doc-comment processing code as: some text some more text indented line 3 and when we see a section with the heading on its own line: Notes: some text some more text indented text we also accept that and save it in the same form. If we detect that the comment document text is not indented as much as we expect it to be, we throw a parse error. (We don't complain about over-indented sections, because for rST this can be legitimate markup.) The golden reference for the doc comment text is updated to remove the two 'wrong' indents; these now form a test case that we correctly stripped leading whitespace from an indented multi-line argument definition. We update the documentation in docs/devel/qapi-code-gen.txt to describe the new indentation rules. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-6-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Whitespace between sentences tweaked] Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.txt | 23 +++++++ scripts/qapi/parser.py | 93 +++++++++++++++++++++------ tests/qapi-schema/doc-bad-indent.err | 1 + tests/qapi-schema/doc-bad-indent.json | 8 +++ tests/qapi-schema/doc-bad-indent.out | 0 tests/qapi-schema/doc-good.out | 4 +- tests/qapi-schema/meson.build | 1 + 7 files changed, 109 insertions(+), 21 deletions(-) create mode 100644 tests/qapi-schema/doc-bad-indent.err create mode 100644 tests/qapi-schema/doc-bad-indent.json create mode 100644 tests/qapi-schema/doc-bad-indent.out diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 9eede44350..2a09d4d292 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -901,6 +901,22 @@ commands and events), member (for structs and unions), branch (for alternates), or value (for enums), and finally optional tagged sections. +Descriptions of arguments can span multiple lines. The description +text can start on the line following the '@argname:', in which case it +must not be indented at all. It can also start on the same line as +the '@argname:'. In this case if it spans multiple lines then second +and subsequent lines must be indented to line up with the first +character of the first line of the description: + +# @argone: +# This is a two line description +# in the first style. +# +# @argtwo: This is a two line description +# in the second style. + +The number of spaces between the ':' and the text is not significant. + FIXME: the parser accepts these things in almost any order. FIXME: union branches should be described, too. @@ -911,6 +927,13 @@ A tagged section starts with one of the following words: "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". The section ends with the start of a new section. +The text of a section can start on a new line, in +which case it must not be indented at all. It can also start +on the same line as the 'Note:', 'Returns:', etc tag. In this +case if it spans multiple lines then second and subsequent +lines must be indented to match the first, in the same way as +multiline argument descriptions. + A 'Since: x.y.z' tagged section lists the release that introduced the definition. diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 04bf10db37..9d1a3e2eea 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -319,17 +319,32 @@ class QAPIDoc: """ class Section: - def __init__(self, name=None): + def __init__(self, parser, name=None, indent=0): + # parser, for error messages about indentation + self._parser = parser # optional section name (argument/member or section name) self.name = name self.text = '' + # the expected indent level of the text of this section + self._indent = indent def append(self, line): + # Strip leading spaces corresponding to the expected indent level + # Blank lines are always OK. + if line: + indent = re.match(r'\s*', line).end() + if indent < self._indent: + raise QAPIParseError( + self._parser, + "unexpected de-indent (expected at least %d spaces)" % + self._indent) + line = line[self._indent:] + self.text += line.rstrip() + '\n' class ArgSection(Section): - def __init__(self, name): - super().__init__(name) + def __init__(self, parser, name, indent=0): + super().__init__(parser, name, indent) self.member = None def connect(self, member): @@ -343,7 +358,7 @@ class QAPIDoc: self._parser = parser self.info = info self.symbol = None - self.body = QAPIDoc.Section() + self.body = QAPIDoc.Section(parser) # dict mapping parameter name to ArgSection self.args = OrderedDict() self.features = OrderedDict() @@ -447,8 +462,21 @@ class QAPIDoc: name = line.split(' ', 1)[0] if name.startswith('@') and name.endswith(':'): - line = line[len(name)+1:] - self._start_args_section(name[1:-1]) + # If line is "@arg: first line of description", find + # the index of 'f', which is the indent we expect for any + # following lines. We then remove the leading "@arg:" + # from line and replace it with spaces so that 'f' has the + # same index as it did in the original line and can be + # handled the same way we will handle following lines. + indent = re.match(r'@\S*:\s*', line).end() + line = line[indent:] + if not line: + # Line was just the "@arg:" header; following lines + # are not indented + indent = 0 + else: + line = ' ' * indent + line + self._start_args_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line = self._append_various_line self._append_various_line(line) @@ -469,8 +497,21 @@ class QAPIDoc: name = line.split(' ', 1)[0] if name.startswith('@') and name.endswith(':'): - line = line[len(name)+1:] - self._start_features_section(name[1:-1]) + # If line is "@arg: first line of description", find + # the index of 'f', which is the indent we expect for any + # following lines. We then remove the leading "@arg:" + # from line and replace it with spaces so that 'f' has the + # same index as it did in the original line and can be + # handled the same way we will handle following lines. + indent = re.match(r'@\S*:\s*', line).end() + line = line[indent:] + if not line: + # Line was just the "@arg:" header; following lines + # are not indented + indent = 0 + else: + line = ' ' * indent + line + self._start_features_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line = self._append_various_line self._append_various_line(line) @@ -502,12 +543,25 @@ class QAPIDoc: "'%s' can't follow '%s' section" % (name, self.sections[0].name)) if self._is_section_tag(name): - line = line[len(name)+1:] - self._start_section(name[:-1]) + # If line is "Section: first line of description", find + # the index of 'f', which is the indent we expect for any + # following lines. We then remove the leading "Section:" + # from line and replace it with spaces so that 'f' has the + # same index as it did in the original line and can be + # handled the same way we will handle following lines. + indent = re.match(r'\S*:\s*', line).end() + line = line[indent:] + if not line: + # Line was just the "Section:" header; following lines + # are not indented + indent = 0 + else: + line = ' ' * indent + line + self._start_section(name[:-1], indent) self._append_freeform(line) - def _start_symbol_section(self, symbols_dict, name): + def _start_symbol_section(self, symbols_dict, name, indent): # FIXME invalid names other than the empty string aren't flagged if not name: raise QAPIParseError(self._parser, "invalid parameter name") @@ -516,21 +570,21 @@ class QAPIDoc: "'%s' parameter name duplicated" % name) assert not self.sections self._end_section() - self._section = QAPIDoc.ArgSection(name) + self._section = QAPIDoc.ArgSection(self._parser, name, indent) symbols_dict[name] = self._section - def _start_args_section(self, name): - self._start_symbol_section(self.args, name) + def _start_args_section(self, name, indent): + self._start_symbol_section(self.args, name, indent) - def _start_features_section(self, name): - self._start_symbol_section(self.features, name) + def _start_features_section(self, name, indent): + self._start_symbol_section(self.features, name, indent) - def _start_section(self, name=None): + def _start_section(self, name=None, indent=0): if name in ('Returns', 'Since') and self.has_section(name): raise QAPIParseError(self._parser, "duplicated '%s' section" % name) self._end_section() - self._section = QAPIDoc.Section(name) + self._section = QAPIDoc.Section(self._parser, name, indent) self.sections.append(self._section) def _end_section(self): @@ -553,7 +607,8 @@ class QAPIDoc: def connect_member(self, member): if member.name not in self.args: # Undocumented TODO outlaw - self.args[member.name] = QAPIDoc.ArgSection(member.name) + self.args[member.name] = QAPIDoc.ArgSection(self._parser, + member.name) self.args[member.name].connect(member) def connect_feature(self, feature): diff --git a/tests/qapi-schema/doc-bad-indent.err b/tests/qapi-schema/doc-bad-indent.err new file mode 100644 index 0000000000..67844539bd --- /dev/null +++ b/tests/qapi-schema/doc-bad-indent.err @@ -0,0 +1 @@ +doc-bad-indent.json:6:1: unexpected de-indent (expected at least 4 spaces) diff --git a/tests/qapi-schema/doc-bad-indent.json b/tests/qapi-schema/doc-bad-indent.json new file mode 100644 index 0000000000..edde8f21dc --- /dev/null +++ b/tests/qapi-schema/doc-bad-indent.json @@ -0,0 +1,8 @@ +# Multiline doc comments should have consistent indentation + +## +# @foo: +# @a: line one +# line two is wrongly indented +## +{ 'command': 'foo', 'data': { 'a': 'int' } } diff --git a/tests/qapi-schema/doc-bad-indent.out b/tests/qapi-schema/doc-bad-indent.out new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 9993ffcd89..b7e3f4313d 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -159,7 +159,7 @@ doc symbol=Alternate arg=i an integer - @b is undocumented +@b is undocumented arg=b feature=alt-feat @@ -174,7 +174,7 @@ doc symbol=cmd the first argument arg=arg2 the second - argument +argument arg=arg3 feature=cmd-feat1 diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index f1449298b0..83a0a68389 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -53,6 +53,7 @@ schemas = [ 'doc-bad-enum-member.json', 'doc-bad-event-arg.json', 'doc-bad-feature.json', + 'doc-bad-indent.json', 'doc-bad-section.json', 'doc-bad-symbol.json', 'doc-bad-union-member.json', From patchwork Tue Sep 29 20:19:11 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272440 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 A5C71C47427 for ; Tue, 29 Sep 2020 20:34:05 +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 15C2A20848 for ; Tue, 29 Sep 2020 20:34:05 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="RTA7v53w" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 15C2A20848 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:44998 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMK3-0004a5-VS for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:34:04 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59798) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6G-0001uy-6T for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:49 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:25539) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0003Uw-OR for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410776; 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=hYy5fXLPFF7+oFK459t2gVsfqFLOyasW9TQlugyCPhU=; b=RTA7v53w8zgPVFZPcokIvgukeyYWUTVfSiSGuaDmW+UP4531FO4BEuFQqsOyEMdpVGV/U6 nwp7u0mGATfKVETLImQm+SrSK+q2D3SbCi/oTUijHd5SBW6Ti8DkMO+zLfr/PkThcFC2Qk 9+ObCjikfouwu4nerpGctn+JE/B8XFg= 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-169-QVh-41Z-N3m8gq40y8ZBHw-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: QVh-41Z-N3m8gq40y8ZBHw-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 5F3DD801AE1; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2DFC919D7D; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C23C811358C6; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 14/29] qapi/machine.json: Escape a literal '*' in doc comment Date: Tue, 29 Sep 2020 22:19:11 +0200 Message-Id: <20200929201926.2155622-15-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell For rST, '*' is a kind of inline markup (for emphasis), so "*-softmmu" is a syntax error because of the missing closing '*'. Escape the '*' with a '\'. The texinfo document generator will leave the '\' in the output, which is not ideal, but that generator is going to go away in a subsequent commit. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-7-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/machine.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/machine.json b/qapi/machine.json index 2c237563ea..756dacb06f 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -13,7 +13,7 @@ # # The comprehensive enumeration of QEMU system emulation ("softmmu") # targets. Run "./configure --help" in the project root directory, and -# look for the *-softmmu targets near the "--target-list" option. The +# look for the \*-softmmu targets near the "--target-list" option. The # individual target constants are not documented here, for the time # being. # From patchwork Tue Sep 29 20:19:12 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304110 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 43117C49EC8 for ; Tue, 29 Sep 2020 20:48:10 +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 83BCE2072E for ; Tue, 29 Sep 2020 20:48:09 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="J4ppQen4" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 83BCE2072E Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:44374 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMXg-0008SO-GD for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:48:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59924) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6a-0002BR-GM for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:20:08 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:45519) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM6U-0003Y1-R2 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:20:08 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410801; 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=YVSrCysKbzt+1NRPXHbRfcvQNuRqv2Gw4RqG79mhiPA=; b=J4ppQen4Ovg8qq+UUV1oxBiecxBoa6aBb13lvi2T7GzGh+JkRyIhG7Vih1Q2vG4JW1uZHL qeypVanAYf3sus6QbN2XH1kmDG7BI3h4+aL3FopGOvxemsqo+1Qd2SS+VP61FYrMDvOH3C +H0gkfj3baLVzkRHKnfP3J15GJqINNY= 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-489-VKYWt6XwO2qQrnmna6UVcg-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: VKYWt6XwO2qQrnmna6UVcg-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id C97061040C28; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 4DDCC19C4F; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C639B11358C7; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 15/29] docs/sphinx: Add new qapi-doc Sphinx extension Date: Tue, 29 Sep 2020 22:19:12 +0200 Message-Id: <20200929201926.2155622-16-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Some of our documentation is auto-generated from documentation comments in the JSON schema. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which processes the JSON file and inserts documentation into the rST file being processed. This is the same approach that kerneldoc and hxtool use. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-8-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Comment and doc string formatting tweaked, unused method dropped, a few line breaks tweaked to follow PEP 8 more closely, MAINTAINERS section QAPI updated] Signed-off-by: Markus Armbruster --- docs/conf.py | 6 +- docs/sphinx/qapidoc.py | 549 +++++++++++++++++++++++++++++++++++++++++ MAINTAINERS | 2 + 3 files changed, 556 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/qapidoc.py diff --git a/docs/conf.py b/docs/conf.py index 0dbd90dc11..606f623211 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,7 +52,10 @@ except NameError: # add these directories to sys.path here. If the directory is relative to the # documentation root, use an absolute path starting from qemu_docdir. # +# Our extensions are in docs/sphinx; the qapidoc extension requires +# the QAPI modules from scripts/. sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) +sys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) # -- General configuration ------------------------------------------------ @@ -67,7 +70,7 @@ needs_sphinx = '1.6' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile'] +extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -241,3 +244,4 @@ texinfo_documents = [ kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc') kerneldoc_srctree = os.path.join(qemu_docdir, '..') hxtool_srctree = os.path.join(qemu_docdir, '..') +qapidoc_srctree = os.path.join(qemu_docdir, '..') diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py new file mode 100644 index 0000000000..6944ffa6aa --- /dev/null +++ b/docs/sphinx/qapidoc.py @@ -0,0 +1,549 @@ +# coding=utf-8 +# +# QEMU qapidoc QAPI file parsing extension +# +# Copyright (c) 2020 Linaro +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. + +""" +qapidoc is a Sphinx extension that implements the qapi-doc directive + +The purpose of this extension is to read the documentation comments +in QAPI schema files, and insert them all into the current document. + +It implements one new rST directive, "qapi-doc::". +Each qapi-doc:: directive takes one argument, which is the +pathname of the schema file to process, relative to the source tree. + +The docs/conf.py file must set the qapidoc_srctree config value to +the root of the QEMU source tree. + +The Sphinx documentation on writing extensions is at: +https://www.sphinx-doc.org/en/master/development/index.html +""" + +import os +import re + +from docutils import nodes +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from sphinx.errors import ExtensionError +from sphinx.util.nodes import nested_parse_with_titles +import sphinx +from qapi.gen import QAPISchemaVisitor +from qapi.schema import QAPIError, QAPISemError, QAPISchema + + +# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later +# use switch_source_input. Check borrowed from kerneldoc.py. +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + + +__version__ = '1.0' + + +# Function borrowed from pydash, which is under the MIT license +def intersperse(iterable, separator): + """Yield the members of *iterable* interspersed with *separator*.""" + iterable = iter(iterable) + yield next(iterable) + for item in iterable: + yield separator + yield item + + +class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which generates docutils/Sphinx nodes + + This class builds up a tree of docutils/Sphinx nodes corresponding + to documentation for the various QAPI objects. To use it, first + create a QAPISchemaGenRSTVisitor object, and call its + visit_begin() method. Then you can call one of the two methods + 'freeform' (to add documentation for a freeform documentation + chunk) or 'symbol' (to add documentation for a QAPI symbol). These + will cause the visitor to build up the tree of document + nodes. Once you've added all the documentation via 'freeform' and + 'symbol' method calls, you can call 'get_document_nodes' to get + the final list of document nodes (in a form suitable for returning + from a Sphinx directive's 'run' method). + """ + def __init__(self, sphinx_directive): + self._cur_doc = None + self._sphinx_directive = sphinx_directive + self._top_node = nodes.section() + self._active_headings = [self._top_node] + + def _make_dlitem(self, term, defn): + """Return a dlitem node with the specified term and definition. + + term should be a list of Text and literal nodes. + defn should be one of: + - a string, which will be handed to _parse_text_into_node + - a list of Text and literal nodes, which will be put into + a paragraph node + """ + dlitem = nodes.definition_list_item() + dlterm = nodes.term('', '', *term) + dlitem += dlterm + if defn: + dldef = nodes.definition() + if isinstance(defn, list): + dldef += nodes.paragraph('', '', *defn) + else: + self._parse_text_into_node(defn, dldef) + dlitem += dldef + return dlitem + + def _make_section(self, title): + """Return a section node with optional title""" + section = nodes.section(ids=[self._sphinx_directive.new_serialno()]) + if title: + section += nodes.title(title, title) + return section + + def _nodes_for_ifcond(self, ifcond, with_if=True): + """Return list of Text, literal nodes for the ifcond + + Return a list which gives text like ' (If: cond1, cond2, cond3)', where + the conditions are in literal-text and the commas are not. + If with_if is False, we don't return the "(If: " and ")". + """ + condlist = intersperse([nodes.literal('', c) for c in ifcond], + nodes.Text(', ')) + if not with_if: + return condlist + + nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')] + nodelist.extend(condlist) + nodelist.append(nodes.Text(')')) + return nodelist + + def _nodes_for_one_member(self, member): + """Return list of Text, literal nodes for this member + + Return a list of doctree nodes which give text like + 'name: type (optional) (If: ...)' suitable for use as the + 'term' part of a definition list item. + """ + term = [nodes.literal('', member.name)] + if member.type.doc_type(): + term.append(nodes.Text(': ')) + term.append(nodes.literal('', member.type.doc_type())) + if member.optional: + term.append(nodes.Text(' (optional)')) + if member.ifcond: + term.extend(self._nodes_for_ifcond(member.ifcond)) + return term + + def _nodes_for_variant_when(self, variants, variant): + """Return list of Text, literal nodes for variant 'when' clause + + Return a list of doctree nodes which give text like + 'when tagname is variant (If: ...)' suitable for use in + the 'variants' part of a definition list. + """ + term = [nodes.Text(' when '), + nodes.literal('', variants.tag_member.name), + nodes.Text(' is '), + nodes.literal('', '"%s"' % variant.name)] + if variant.ifcond: + term.extend(self._nodes_for_ifcond(variant.ifcond)) + return term + + def _nodes_for_members(self, doc, what, base=None, variants=None): + """Return list of doctree nodes for the table of members""" + dlnode = nodes.definition_list() + for section in doc.args.values(): + term = self._nodes_for_one_member(section.member) + # 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')] + + dlnode += self._make_dlitem(term, defn) + + if base: + dlnode += self._make_dlitem([nodes.Text('The members of '), + nodes.literal('', base.doc_type())], + None) + + if variants: + for v in variants.variants: + if v.type.is_implicit(): + assert not v.type.base and not v.type.variants + for m in v.type.local_members: + term = self._nodes_for_one_member(m) + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode += self._make_dlitem(term, None) + else: + term = [nodes.Text('The members of '), + nodes.literal('', v.type.doc_type())] + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode += self._make_dlitem(term, None) + + if not dlnode.children: + return [] + + section = self._make_section(what) + section += dlnode + return [section] + + def _nodes_for_enum_values(self, doc): + """Return list of doctree nodes for the table of enum values""" + seen_item = False + dlnode = nodes.definition_list() + for section in doc.args.values(): + termtext = [nodes.literal('', section.member.name)] + if section.member.ifcond: + termtext.extend(self._nodes_for_ifcond(section.member.ifcond)) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn = section.text + else: + defn = [nodes.Text('Not documented')] + + dlnode += self._make_dlitem(termtext, defn) + seen_item = True + + if not seen_item: + return [] + + section = self._make_section('Values') + section += dlnode + return [section] + + def _nodes_for_arguments(self, doc, boxed_arg_type): + """Return list of doctree nodes for the arguments section""" + if boxed_arg_type: + assert not doc.args + section = self._make_section('Arguments') + dlnode = nodes.definition_list() + dlnode += self._make_dlitem( + [nodes.Text('The members of '), + nodes.literal('', boxed_arg_type.name)], + None) + section += dlnode + return [section] + + return self._nodes_for_members(doc, 'Arguments') + + def _nodes_for_features(self, doc): + """Return list of doctree nodes for the table of features""" + seen_item = False + dlnode = nodes.definition_list() + for section in doc.features.values(): + dlnode += self._make_dlitem([nodes.literal('', section.name)], + section.text) + seen_item = True + + if not seen_item: + return [] + + section = self._make_section('Features') + section += dlnode + return [section] + + def _nodes_for_example(self, exampletext): + """Return list of doctree nodes for a code example snippet""" + return [nodes.literal_block(exampletext, exampletext)] + + def _nodes_for_sections(self, doc): + """Return list of doctree nodes for additional sections""" + nodelist = [] + for section in doc.sections: + snode = self._make_section(section.name) + if section.name and section.name.startswith('Example'): + snode += self._nodes_for_example(section.text) + else: + self._parse_text_into_node(section.text, snode) + nodelist.append(snode) + return nodelist + + def _nodes_for_if_section(self, ifcond): + """Return list of doctree nodes for the "If" section""" + nodelist = [] + if ifcond: + snode = self._make_section('If') + snode += self._nodes_for_ifcond(ifcond, with_if=False) + nodelist.append(snode) + return nodelist + + def _add_doc(self, typ, sections): + """Add documentation for a command/object/enum... + + We assume we're documenting the thing defined in self._cur_doc. + typ is the type of thing being added ("Command", "Object", etc) + + sections is a list of nodes for sections to add to the definition. + """ + + doc = self._cur_doc + snode = nodes.section(ids=[self._sphinx_directive.new_serialno()]) + snode += nodes.title('', '', *[nodes.literal(doc.symbol, doc.symbol), + nodes.Text(' (' + typ + ')')]) + self._parse_text_into_node(doc.body.text, snode) + for s in sections: + if s is not None: + snode += s + self._add_node_to_current_heading(snode) + + def visit_enum_type(self, name, info, ifcond, features, members, prefix): + doc = self._cur_doc + self._add_doc('Enum', + self._nodes_for_enum_values(doc) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_object_type(self, name, info, ifcond, features, + base, members, variants): + doc = self._cur_doc + if base and base.is_implicit(): + base = None + self._add_doc('Object', + self._nodes_for_members(doc, 'Members', base, variants) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_alternate_type(self, name, info, ifcond, features, variants): + doc = self._cur_doc + self._add_doc('Alternate', + self._nodes_for_members(doc, 'Members') + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_command(self, name, info, ifcond, features, arg_type, + ret_type, gen, success_response, boxed, allow_oob, + allow_preconfig): + doc = self._cur_doc + self._add_doc('Command', + self._nodes_for_arguments(doc, + arg_type if boxed else None) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def visit_event(self, name, info, ifcond, features, arg_type, boxed): + doc = self._cur_doc + self._add_doc('Event', + self._nodes_for_arguments(doc, + arg_type if boxed else None) + + self._nodes_for_features(doc) + + self._nodes_for_sections(doc) + + self._nodes_for_if_section(ifcond)) + + def symbol(self, doc, entity): + """Add documentation for one symbol to the document tree + + This is the main entry point which causes us to add documentation + nodes for a symbol (which could be a 'command', 'object', 'event', + etc). We do this by calling 'visit' on the schema entity, which + will then call back into one of our visit_* methods, depending + on what kind of thing this symbol is. + """ + self._cur_doc = doc + entity.visit(self) + self._cur_doc = None + + def _start_new_heading(self, heading, level): + """Start a new heading at the specified heading level + + Create a new section whose title is 'heading' and which is placed + in the docutils node tree as a child of the most recent level-1 + heading. Subsequent document sections (commands, freeform doc chunks, + etc) will be placed as children of this new heading section. + """ + if len(self._active_headings) < level: + raise QAPISemError(self._cur_doc.info, + 'Level %d subheading found outside a ' + 'level %d heading' + % (level, level - 1)) + snode = self._make_section(heading) + self._active_headings[level - 1] += snode + self._active_headings = self._active_headings[:level] + self._active_headings.append(snode) + + def _add_node_to_current_heading(self, node): + """Add the node to whatever the current active heading is""" + self._active_headings[-1] += node + + def freeform(self, doc): + """Add a piece of 'freeform' documentation to the document tree + + A 'freeform' document chunk doesn't relate to any particular + symbol (for instance, it could be an introduction). + + If the freeform document starts with a line of the form + '= Heading text', this is a section or subsection heading, with + the heading level indicated by the number of '=' signs. + """ + + # QAPIDoc documentation says free-form documentation blocks + # must have only a body section, nothing else. + assert not doc.sections + assert not doc.args + assert not doc.features + self._cur_doc = doc + + text = doc.body.text + if re.match(r'=+ ', text): + # Section/subsection heading (if present, will always be + # the first line of the block) + (heading, _, text) = text.partition('\n') + (leader, _, heading) = heading.partition(' ') + self._start_new_heading(heading, len(leader)) + if text == '': + return + + node = self._make_section(None) + self._parse_text_into_node(text, node) + self._add_node_to_current_heading(node) + self._cur_doc = None + + def _parse_text_into_node(self, doctext, node): + """Parse a chunk of QAPI-doc-format text into the node + + The doc comment can contain most inline rST markup, including + bulleted and enumerated lists. + As an extra permitted piece of markup, @var will be turned + into ``var``. + """ + + # Handle the "@var means ``var`` case + doctext = re.sub(r'@([\w-]+)', r'``\1``', doctext) + + rstlist = ViewList() + for line in doctext.splitlines(): + # The reported line number will always be that of the start line + # of the doc comment, rather than the actual location of the error. + # Being more precise would require overhaul of the QAPIDoc class + # to track lines more exactly within all the sub-parts of the doc + # comment, as well as counting lines here. + rstlist.append(line, self._cur_doc.info.fname, + self._cur_doc.info.line) + # Append a blank line -- in some cases rST syntax errors get + # attributed to the line after one with actual text, and if there + # isn't anything in the ViewList corresponding to that then Sphinx + # 1.6's AutodocReporter will then misidentify the source/line location + # in the error message (usually attributing it to the top-level + # .rst file rather than the offending .json file). The extra blank + # line won't affect the rendered output. + rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.line) + self._sphinx_directive.do_parse(rstlist, node) + + def get_document_nodes(self): + """Return the list of docutils nodes which make up the document""" + return self._top_node.children + + +class QAPISchemaGenDepVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which adds Sphinx dependencies each module + + This class calls the Sphinx note_dependency() function to tell Sphinx + that the generated documentation output depends on the input + schema file associated with each module in the QAPI input. + """ + def __init__(self, env, qapidir): + self._env = env + self._qapidir = qapidir + + def visit_module(self, name): + if name is not None: + qapifile = self._qapidir + '/' + name + self._env.note_dependency(os.path.abspath(qapifile)) + super().visit_module(name) + + +class QAPIDocDirective(Directive): + """Extract documentation from the specified QAPI .json file""" + required_argument = 1 + optional_arguments = 1 + option_spec = { + 'qapifile': directives.unchanged_required + } + has_content = False + + def new_serialno(self): + """Return a unique new ID string suitable for use as a node's ID""" + env = self.state.document.settings.env + return 'qapidoc-%d' % env.new_serialno('qapidoc') + + def run(self): + env = self.state.document.settings.env + qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0] + qapidir = os.path.dirname(qapifile) + + try: + schema = QAPISchema(qapifile) + + # First tell Sphinx about all the schema files that the + # output documentation depends on (including 'qapifile' itself) + schema.visit(QAPISchemaGenDepVisitor(env, qapidir)) + + vis = QAPISchemaGenRSTVisitor(self) + vis.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + vis.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + vis.freeform(doc) + return vis.get_document_nodes() + except QAPIError as err: + # Launder QAPI parse errors into Sphinx extension errors + # so they are displayed nicely to the user + raise ExtensionError(str(err)) + + def do_parse(self, rstlist, node): + """Parse rST source lines and add them to the specified node + + Take the list of rST source lines rstlist, parse them as + rST, and add the resulting docutils nodes as children of node. + The nodes are parsed in a way that allows them to include + subheadings (titles) without confusing the rendering of + anything else. + """ + # This is from kerneldoc.py -- it works around an API change in + # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use + # sphinx.util.nodes.nested_parse_with_titles() rather than the + # plain self.state.nested_parse(), and so we can drop the saving + # of title_styles and section_level that kerneldoc.py does, + # because nested_parse_with_titles() does that for us. + if Use_SSI: + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) + else: + save = self.state.memo.reporter + self.state.memo.reporter = AutodocReporter( + rstlist, self.state.memo.reporter) + try: + nested_parse_with_titles(self.state, rstlist, node) + finally: + self.state.memo.reporter = save + + +def setup(app): + """ Register qapi-doc directive with Sphinx""" + app.add_config_value('qapidoc_srctree', None, 'env') + app.add_directive('qapi-doc', QAPIDocDirective) + + return dict( + version=__version__, + parallel_read_safe=True, + parallel_write_safe=True + ) diff --git a/MAINTAINERS b/MAINTAINERS index be0a8e648c..ac3e4e465c 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2387,6 +2387,7 @@ F: tests/test-qmp-*.c F: tests/test-visitor-serialization.c F: scripts/qapi-gen.py F: scripts/qapi/* +F: docs/sphinx/qapidoc.py F: docs/devel/qapi* T: git https://repo.or.cz/qemu/armbru.git qapi-next @@ -3151,6 +3152,7 @@ M: Peter Maydell S: Maintained F: docs/conf.py F: docs/*/conf.py +F: docs/sphinx/ Miscellaneous ------------- From patchwork Tue Sep 29 20:19:13 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304116 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=-15.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 60730C4727C for ; Tue, 29 Sep 2020 20:31:47 +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 9F8AD20774 for ; Tue, 29 Sep 2020 20:31:46 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Sw1NgBSj" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 9F8AD20774 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:36200 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMHp-0000jo-95 for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:31:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59836) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6I-0001v2-5M for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:39009) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM68-0003Vi-4g for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:49 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410778; 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=nvxuauxtmIrz8mXp8WmGjf5Zvqj/tWEjYO7gCi8qjIU=; b=Sw1NgBSjjxvkj1gw0Rykx7dkcxXx40y7C90SlfPHiWx0lkjzgIDswlDENDawRhAbzXUENQ 1XSVwEIk6w3ld8CGH4Ho7RvzpvyrI+aVPmjoH80soiKOx9a4omPs4YmGYsWa/UJDLC+Jjv yZAsCQC2hvGJG6ZQNWEusCpVove8FKY= 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-229-wb-cTkCSPf20JQEtG-0EAg-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: wb-cTkCSPf20JQEtG-0EAg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id ABED11040C27; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 57F3878807; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C9D8F11358CA; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 16/29] docs/interop: Convert qemu-ga-ref to rST Date: Tue, 29 Sep 2020 22:19:13 +0200 Message-Id: <20200929201926.2155622-17-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Convert qemu-ga-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-ga-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. As the GA ref is now part of the Sphinx 'interop' manual, we can delete the direct link from index.html.in. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-9-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Unicode legacy literal dumbed down to plain string literal, TODO comment on displaying QEMU version added] Signed-off-by: Markus Armbruster --- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-ga-ref.rst | 13 ++++++ docs/interop/qemu-ga-ref.texi | 80 ----------------------------------- docs/meson.build | 1 + meson.build | 3 -- MAINTAINERS | 2 +- qga/meson.build | 3 +- 9 files changed, 19 insertions(+), 87 deletions(-) create mode 100644 docs/interop/qemu-ga-ref.rst delete mode 100644 docs/interop/qemu-ga-ref.texi diff --git a/docs/index.html.in b/docs/index.html.in index ca28047881..5b0f4e2bc2 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -13,7 +13,6 @@
  • System Emulation Management and Interoperability Guide
  • System Emulation Guest Hardware Specifications
  • QMP Reference Manual
    • -
  • Guest Agent Protocol Reference
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index 42ce7e3d36..4e5bbbbf95 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -19,4 +19,6 @@ html_theme_options['description'] = u'System Emulation Management and Interopera man_pages = [ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', ['Michael Roth '], 8), + ('qemu-ga-ref', 'qemu-ga-ref', 'QEMU Guest Agent Protocol Reference', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 006f986420..738cdbe185 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,6 +18,7 @@ Contents: live-block-operations pr-helper qemu-ga + qemu-ga-ref vhost-user vhost-user-gpu vhost-vdpa diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst new file mode 100644 index 0000000000..3f1c4f908f --- /dev/null +++ b/docs/interop/qemu-ga-ref.rst @@ -0,0 +1,13 @@ +QEMU Guest Agent Protocol Reference +=================================== + +.. + TODO: the old Texinfo manual used to note that this manual + is GPL-v2-or-later. We should make that reader-visible + both here and in our Sphinx manuals more generally. + +.. + TODO: display the QEMU version, both here and in our Sphinx manuals + more generally. + +.. qapi-doc:: qga/qapi-schema.json diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi deleted file mode 100644 index a23cc2ed7f..0000000000 --- a/docs/interop/qemu-ga-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-ga-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU Guest Agent Protocol Reference - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU Guest Agent Protocol reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference -@end direntry - -@titlepage -@title Guest Agent Protocol Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU Guest Agent protocol reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qga/qga-qapi-doc.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye diff --git a/docs/meson.build b/docs/meson.build index 50f367349b..2569dd52ad 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -15,6 +15,7 @@ if build_docs man_pages = { 'interop' : { 'qemu-ga.8': (have_tools ? 'man8' : ''), + 'qemu-ga-ref.7': 'man7', }, 'tools': { 'qemu-img.1': (have_tools ? 'man1' : ''), diff --git a/meson.build b/meson.build index d36dd085b5..c18764a408 100644 --- a/meson.build +++ b/meson.build @@ -1221,9 +1221,6 @@ if build_docs texi = { 'qemu-qmp-ref': ['docs/interop/qemu-qmp-ref.texi', qapi_doc_texi, version_texi], } - if 'CONFIG_GUEST_AGENT' in config_host - texi += {'qemu-ga-ref': ['docs/interop/qemu-ga-ref.texi', qga_qapi_doc_texi, version_texi]} - endif if makeinfo.found() cmd = [ diff --git a/MAINTAINERS b/MAINTAINERS index ac3e4e465c..e1e8ae277d 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2421,9 +2421,9 @@ M: Michael Roth S: Maintained F: qga/ F: docs/interop/qemu-ga.rst +F: docs/interop/qemu-ga-ref.rst F: scripts/qemu-guest-agent/ F: tests/test-qga.c -F: docs/interop/qemu-ga-ref.texi T: git https://github.com/mdroth/qemu.git qga QOM diff --git a/qga/meson.build b/qga/meson.build index e5c5778a3e..1c312b50cc 100644 --- a/qga/meson.build +++ b/qga/meson.build @@ -16,7 +16,7 @@ qga_qapi_outputs = [ ] qga_qapi_files = custom_target('QGA QAPI files', - output: qga_qapi_outputs + ['qga-qapi-doc.texi'], + output: qga_qapi_outputs, input: 'qapi-schema.json', command: [ qapi_gen, '-o', 'qga', '-p', 'qga-', '@INPUT0@' ], depend_files: qapi_gen_depends) @@ -27,7 +27,6 @@ foreach output: qga_qapi_outputs qga_ss.add(qga_qapi_files[i]) i = i + 1 endforeach -qga_qapi_doc_texi = qga_qapi_files[i] qga_ss.add(files( 'commands.c', From patchwork Tue Sep 29 20:19:14 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272439 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 44FEEC4743C for ; Tue, 29 Sep 2020 20:36:33 +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 63D20208B8 for ; Tue, 29 Sep 2020 20:36:32 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="V3GQyWrh" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 63D20208B8 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:50812 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMMR-0007AO-8j for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:36:31 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59864) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6L-0001xq-MU for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:55 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:26107) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM68-0003VY-61 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:52 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410778; 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=L5W3k18ZSTfgsiYylaOMUpqXy7MXAVSmY6xPiu5ylFg=; b=V3GQyWrhwvLWU0vLy5VWRtuaWcEcM4xuKQQhJvxV618z/Q1i3DzkZjCQSrGFlJuvwrN8sw v4Jd/gbdVj6MbluldXl2KDtIR88MiH9IB24Dzx9ufcPyTwAYywjP2mmhA/oxvpdX8XPXWq 3vyhzLFxKZenBAjubJd7QNlqVsgaTC0= 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-317-B-BWC0uSNxuB1DqinS4Qcg-1; Tue, 29 Sep 2020 16:19:33 -0400 X-MC-Unique: B-BWC0uSNxuB1DqinS4Qcg-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id BC4E6801AEA; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 684116715F; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CDC0B11358CB; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 17/29] docs/interop: Convert qemu-qmp-ref to rST Date: Tue, 29 Sep 2020 22:19:14 +0200 Message-Id: <20200929201926.2155622-18-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Convert qemu-qmp-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-qmp-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. Again, we drop the direct link from index.html.in now that the QMP ref is part of the interop manual. This commit removes the code from the root meson.build file that handled the various Texinfo-based outputs, because we no longer generate any documentation except for the Sphinx HTML manuals and the manpages, and the code can't handle having an empty list of files to process.. We'll do further cleanup of the remainders of Texinfo support in subsequent commits. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-10-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Unicode legacy literal dumbed down to plain string literal, TODO comment on displaying QEMU version added, "make html" fixed, storage-daemon/qapi/meson.build updated] Signed-off-by: Markus Armbruster --- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-qmp-ref.rst | 13 ++++++ docs/interop/qemu-qmp-ref.texi | 80 -------------------------------- docs/meson.build | 2 + Makefile | 2 +- meson.build | 82 --------------------------------- qapi/meson.build | 4 +- storage-daemon/qapi/meson.build | 2 +- 10 files changed, 21 insertions(+), 168 deletions(-) create mode 100644 docs/interop/qemu-qmp-ref.rst delete mode 100644 docs/interop/qemu-qmp-ref.texi diff --git a/docs/index.html.in b/docs/index.html.in index 5b0f4e2bc2..33db4396ac 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -12,7 +12,6 @@
  • Tools Guide
  • System Emulation Management and Interoperability Guide
  • System Emulation Guest Hardware Specifications
    • -
  • QMP Reference Manual
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index 4e5bbbbf95..2634ca3410 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -21,4 +21,6 @@ man_pages = [ ['Michael Roth '], 8), ('qemu-ga-ref', 'qemu-ga-ref', 'QEMU Guest Agent Protocol Reference', [], 7), + ('qemu-qmp-ref', 'qemu-qmp-ref', 'QEMU QMP Reference Manual', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 738cdbe185..cd78d679d8 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -19,6 +19,7 @@ Contents: pr-helper qemu-ga qemu-ga-ref + qemu-qmp-ref vhost-user vhost-user-gpu vhost-vdpa diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst new file mode 100644 index 0000000000..c8abaaf8e3 --- /dev/null +++ b/docs/interop/qemu-qmp-ref.rst @@ -0,0 +1,13 @@ +QEMU QMP Reference Manual +========================= + +.. + TODO: the old Texinfo manual used to note that this manual + is GPL-v2-or-later. We should make that reader-visible + both here and in our Sphinx manuals more generally. + +.. + TODO: display the QEMU version, both here and in our Sphinx manuals + more generally. + +.. qapi-doc:: qapi/qapi-schema.json diff --git a/docs/interop/qemu-qmp-ref.texi b/docs/interop/qemu-qmp-ref.texi deleted file mode 100644 index ea1d7fe6c2..0000000000 --- a/docs/interop/qemu-qmp-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-qmp-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU QMP Reference Manual - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU QMP reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual -@end direntry - -@titlepage -@title QMP Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU QMP reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qapi/qapi-doc.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye diff --git a/docs/meson.build b/docs/meson.build index 2569dd52ad..663bdb9073 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -16,6 +16,7 @@ if build_docs 'interop' : { 'qemu-ga.8': (have_tools ? 'man8' : ''), 'qemu-ga-ref.7': 'man7', + 'qemu-qmp-ref.7': 'man7', }, 'tools': { 'qemu-img.1': (have_tools ? 'man1' : ''), @@ -70,5 +71,6 @@ if build_docs endif endforeach alias_target('sphinxdocs', sphinxdocs) + alias_target('html', sphinxdocs) alias_target('man', sphinxmans) endif diff --git a/Makefile b/Makefile index 7c60b9dcb8..7b2655db08 100644 --- a/Makefile +++ b/Makefile @@ -280,7 +280,7 @@ endif $(call print-help,vm-help,Help about targets running tests inside VM) @echo '' @echo 'Documentation targets:' - $(call print-help,html info pdf txt man,Build documentation in specified format) + $(call print-help,html man,Build documentation in specified format) @echo '' ifdef CONFIG_WIN32 @echo 'Windows targets:' diff --git a/meson.build b/meson.build index c18764a408..7eb2c9c01a 100644 --- a/meson.build +++ b/meson.build @@ -1204,88 +1204,6 @@ if 'CONFIG_GTK' in config_host subdir('po') endif -if build_docs - makeinfo = find_program('makeinfo', required: build_docs) - - docs_inc = [ - '-I', meson.current_source_dir(), - '-I', meson.current_build_dir() / 'docs', - '-I', '@OUTDIR@', - ] - - version_texi = configure_file(output: 'version.texi', - input: 'version.texi.in', - configuration: {'VERSION': meson.project_version(), - 'qemu_confdir': config_host['qemu_confdir']}) - - texi = { - 'qemu-qmp-ref': ['docs/interop/qemu-qmp-ref.texi', qapi_doc_texi, version_texi], - } - - if makeinfo.found() - cmd = [ - 'env', 'LC_ALL=C', makeinfo, '--no-split', '--number-sections', docs_inc, - '@INPUT0@', '-o', '@OUTPUT@', - ] - foreach ext, args: { - 'info': [], - 'html': ['--no-headers', '--html'], - 'txt': ['--no-headers', '--plaintext'], - } - t = [] - foreach doc, input: texi - output = doc + '.' + ext - t += custom_target(output, - input: input, - output: output, - install: true, - install_dir: qemu_docdir / 'interop', - command: cmd + args) - endforeach - alias_target(ext, t) - endforeach - endif - - texi2pdf = find_program('texi2pdf', required: false) - - if texi2pdf.found() - pdfs = [] - foreach doc, input: texi - output = doc + '.pdf' - pdfs += custom_target(output, - input: input, - output: output, - command: [texi2pdf, '-q', docs_inc, '@INPUT0@', '-o', '@OUTPUT@'], - build_by_default: false) - endforeach - alias_target('pdf', pdfs) - endif - - texi2pod = find_program('scripts/texi2pod.pl') - pod2man = find_program('pod2man', required: build_docs) - - if pod2man.found() - foreach doc, input: texi - man = doc + '.7' - pod = custom_target(man + '.pod', - input: input, - output: man + '.pod', - command: [texi2pod, - '-DVERSION="' + meson.project_version() + '"', - '-DCONFDIR="' + config_host['qemu_confdir'] + '"', - '@INPUT0@', '@OUTPUT@']) - man = custom_target(man, - input: pod, - output: man, - capture: true, - install: true, - install_dir: get_option('mandir') / 'man7', - command: [pod2man, '--utf8', '--section=7', '--center=" "', - '--release=" "', '@INPUT@']) - endforeach - endif -endif - if host_machine.system() == 'windows' nsis_cmd = [ find_program('scripts/nsis.py'), diff --git a/qapi/meson.build b/qapi/meson.build index 298b510492..7c4a89a882 100644 --- a/qapi/meson.build +++ b/qapi/meson.build @@ -99,7 +99,7 @@ foreach module : qapi_all_modules endforeach qapi_files = custom_target('shared QAPI source files', - output: qapi_util_outputs + qapi_specific_outputs + qapi_nonmodule_outputs + ['qapi-doc.texi'], + output: qapi_util_outputs + qapi_specific_outputs + qapi_nonmodule_outputs, input: [ files('qapi-schema.json') ], command: [ qapi_gen, '-o', 'qapi', '-b', '@INPUT0@' ], depend_files: [ qapi_inputs, qapi_gen_depends ]) @@ -123,5 +123,3 @@ foreach output : qapi_specific_outputs + qapi_nonmodule_outputs specific_ss.add(when: 'CONFIG_SOFTMMU', if_true: qapi_files[i]) i = i + 1 endforeach - -qapi_doc_texi = qapi_files[i] diff --git a/storage-daemon/qapi/meson.build b/storage-daemon/qapi/meson.build index cea618bec0..cd064ac578 100644 --- a/storage-daemon/qapi/meson.build +++ b/storage-daemon/qapi/meson.build @@ -1,5 +1,5 @@ qsd_qapi_files = custom_target('QAPI files for qemu-storage-daemon', - output: qapi_nonmodule_outputs + ['qapi-doc.texi'], + output: qapi_nonmodule_outputs, input: [ files('qapi-schema.json') ], command: [ qapi_gen, '-o', 'storage-daemon/qapi', '@INPUT@' ], depend_files: [ qapi_inputs, qapi_gen_depends ]) From patchwork Tue Sep 29 20:19:15 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272443 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 081A9C47425 for ; Tue, 29 Sep 2020 20:29:55 +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 53D082076D for ; Tue, 29 Sep 2020 20:29:54 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="d+5eq0C8" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 53D082076D Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:59346 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMG1-0006mL-8J for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:29:53 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59724) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6C-0001qK-Rh for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:44 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:38399) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0003Us-Nh for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:44 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410776; 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=40f9tgZFYep5/ErNI9LfjYixYwjmeRJrENUq4jNkvEQ=; b=d+5eq0C84yG+Qoid+XWsLKS7avGvdId0S6+SUMhjfL7z7jw2rhMeI60V52k4cc+zZ2C5L0 VMAlMMWYuynjEZNPxW11DKT9uz8Y+2NZegZKOWhuEPa6BCiVQ+ZtKYi7o8mD5dlEbTYEaP qzkilHuisuuRsnOOTVx8TvqYy3dJlfA= 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-464-4wJvenHqOCGZSEnJtAvfvA-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: 4wJvenHqOCGZSEnJtAvfvA-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 9A5A510BBED1; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 6D0755C1C4; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D130C11358CF; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 18/29] qapi: Use rST markup for literal blocks Date: Tue, 29 Sep 2020 22:19:15 +0200 Message-Id: <20200929201926.2155622-19-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell There are exactly two places in our json doc comments where we use the markup accepted by the texi doc generator where a '|' in the first line of a doc comment means the line should be emitted as a literal block (fixed-width font, whitespace preserved). Since we use this syntax so rarely, instead of making the rST generator support it, instead just convert the two uses to rST-format literal blocks, which are indented and introduced with '::'. (The rST generator doesn't complain about the old style syntax, it just emits it with the '|' and with the whitespace not preserved, which looks odd, but means we can safely leave this change until after we've stopped generating texinfo.) Reviewed-by: Richard Henderson Reviewed-by: Markus Armbruster Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-11-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster --- qapi/block-core.json | 16 +++++++++------- qapi/qapi-schema.json | 6 ++++-- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index dd77a91174..86ed72ef9f 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -570,13 +570,15 @@ # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like: # -# | 5| * -# | 4| * -# | 3| * * -# | 2| * * * -# | 1| * * * * -# | +------------------ -# | 10 50 100 +# :: +# +# 5| * +# 4| * +# 3| * * +# 2| * * * +# 1| * * * * +# +------------------ +# 10 50 100 # # Since: 4.0 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 54c8ba6444..0c6ca5c000 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -21,8 +21,10 @@ # # Example: # -# | -> data issued by the Client -# | <- Server data response +# :: +# +# -> data issued by the Client +# <- Server data response # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. From patchwork Tue Sep 29 20:19:16 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304119 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 3EDA0C4727F for ; Tue, 29 Sep 2020 20:26:16 +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 934E22076B for ; Tue, 29 Sep 2020 20:26:15 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Y1IGnE0f" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 934E22076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:48930 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMCU-0002IF-Gm for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:26:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59690) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6A-0001o6-6W for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:43 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:53393) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0003Un-HF for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:41 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410775; 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=nOg1a9YwR7YW0EyB33GMn11hE2VS2AtABnD3nV5H5nQ=; b=Y1IGnE0fMeznxfK6u7B+3SoLxepGA0O1FYAs12mG5TcwwCrfs9fhTJYyn9XGAFcc6efmEX S9mAhVa+E9DZuASCDWrXiSruHkG1YpgPGabhZUcwDLPm/jVI5wUW7KeaABAS4s3ok71Hht z2VrHQqD0/QQvhHtnsPONJvfa2dH/ws= 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-229-6PF_GXwgNneQBRcMJZe6vQ-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: 6PF_GXwgNneQBRcMJZe6vQ-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A2DC71DE04; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 73DF75C1CF; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D63F311358D0; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 19/29] qga/qapi-schema.json: Add some headings Date: Tue, 29 Sep 2020 22:19:16 +0200 Message-Id: <20200929201926.2155622-20-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Add some section headings to the QGA json; this is purely so that we have some H1 headings, as otherwise each command ends up being visible in the interop/ manual's table of contents. In an ideal world there might be a proper 'Introduction' section the way there is in qapi/qapi-schema.json. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-12-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qga/qapi-schema.json | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index d2ea7446db..cec98c7e06 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -2,14 +2,16 @@ # vim: filetype=python ## -# -# General note concerning the use of guest agent interfaces: +# = General note concerning the use of guest agent interfaces # # "unsupported" is a higher-level error than the errors that individual # commands might document. The caller should always be prepared to receive # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't # document any failure mode at all. -# +## + +## +# = QEMU guest agent protocol commands and structs ## { 'pragma': { 'doc-required': true } } From patchwork Tue Sep 29 20:19:17 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272441 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 CF448C47423 for ; Tue, 29 Sep 2020 20:32:39 +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 36C082076B for ; Tue, 29 Sep 2020 20:32:39 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="VFkhrIwX" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 36C082076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:39262 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMIg-00027Q-5b for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:32:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59760) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6E-0001sd-3Q for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:24353) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM64-0003Ue-H5 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:45 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410775; 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=E4TiT38gDo8oyo8Muf7mhAiplRC9qSsQ4WSYb3ECKjE=; b=VFkhrIwXF2z/p8AhusyST5eyK6PI9iChOHzLwOOlwmr18cPGsZO6UJ1mPrJ9qMZIgtcbFt VWYY7OY2JnQ6GUM07K6150Ed55zgw84N4Ta2YBmwtGaX7gI6CG1FXEnZbqBkvHoZfZnY98 +APskQq2Y9ckScoED53KmHBCfiSQ8Fo= 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-464--oBLmtuJO_Sl_hk6d3KMUg-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: -oBLmtuJO_Sl_hk6d3KMUg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A26041DE02; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 750ED78822; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D83C411358D2; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 20/29] tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis Date: Tue, 29 Sep 2020 22:19:17 +0200 Message-Id: <20200929201926.2155622-21-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell doc-good.json currently uses the old *strong* and _emphasis_ markup. As part of the conversion to rST this needs to switch to **strong** and *emphasis*, because rST uses underscores as part of its markup of hyperlinks and will otherwise warn about the syntax error. In commit a660eed482063b we fixed up the in-tree uses of the old markup: 1) _this_ was replaced with *this* 2) the only in-tree use of *this* was left alone (turning a 'strong' into an 'emphasis') (and so currently in-tree nothing is using either new-style **strong** or old-style _emphasis_). Update doc-good.json in a similar way: 1) replace _this_ with *this* 2) remove the usage of old-style *this* (This slightly reduces the coverage for the old Texinfo generator, which is about to go away, but is fine for the new rST generator because that does not need to handle strong/emphasis itself because it is simply passing the entire text as raw rST to Sphinx.) Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-13-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- tests/qapi-schema/doc-good.json | 2 +- tests/qapi-schema/doc-good.out | 2 +- tests/qapi-schema/doc-good.texi | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index c6822145c4..e9af0857db 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -10,7 +10,7 @@ # # == Subsection # -# *strong* _with emphasis_ +# *with emphasis* # @var {in braces} # # * List item one diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index b7e3f4313d..419284dae2 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -73,7 +73,7 @@ doc freeform body= == Subsection -*strong* _with emphasis_ +*with emphasis* @var {in braces} * List item one diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi index 12808989ff..29abef33e9 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -4,7 +4,7 @@ @subsection Subsection -@strong{strong} @emph{with emphasis} +@strong{with emphasis} @code{var} @{in braces@} @itemize @bullet From patchwork Tue Sep 29 20:19:18 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304112 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 54C86C49EBF for ; Tue, 29 Sep 2020 20:36:37 +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 934ED2076B for ; Tue, 29 Sep 2020 20:36:35 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="W/maJruE" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 934ED2076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:51018 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMMU-0007Fs-6a for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:36:34 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59808) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6G-0001v0-Ph for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:20098) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM68-0003VT-5N for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:48 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410778; 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=+y8WBegVr1mcgYnZsDfm07hSSSb0R6NW2of1/YagVKY=; b=W/maJruEPvSuD4VKD+e3AhZvFxJhaFs1AD5DkDIWqVJw6C8+7fC6c5cg1TVxvxyFgUqFd/ ql3y8P29liqW8Zoj+XY1u8IY22wKZKkFdLZ5AW9DTcRatZ5MPBU0pWyPn+Q4XWX3bkUa33 KVtEH314Ijr4E0Ov5O9TzN+sJpRk2Vg= 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-229-WNEVgQ8_OIO56PmiFg-hbg-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: WNEVgQ8_OIO56PmiFg-hbg-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A8EB3801AE3; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7B8A91002C01; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id DBC7411358D3; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 21/29] meson.build: Move SPHINX_ARGS to top level meson.build file Date: Tue, 29 Sep 2020 22:19:18 +0200 Message-Id: <20200929201926.2155622-22-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We're going to want to use SPHINX_ARGS in both docs/meson.build and tests/qapi-schema/meson.build. Move the definition up to the top level file so it is available to both subdirectories. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-14-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/meson.build | 8 -------- meson.build | 8 ++++++++ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/meson.build b/docs/meson.build index 663bdb9073..52e384be17 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,11 +1,3 @@ -SPHINX_ARGS = [config_host['SPHINX_BUILD'], - '-Dversion=' + meson.project_version(), - '-Drelease=' + config_host['PKGVERSION']] - -if get_option('werror') - SPHINX_ARGS += [ '-W' ] -endif - if build_docs configure_file(output: 'index.html', input: files('index.html.in'), diff --git a/meson.build b/meson.build index 7eb2c9c01a..866321462e 100644 --- a/meson.build +++ b/meson.build @@ -672,6 +672,14 @@ foreach d : hx_headers endforeach genh += hxdep +SPHINX_ARGS = [config_host['SPHINX_BUILD'], + '-Dversion=' + meson.project_version(), + '-Drelease=' + config_host['PKGVERSION']] + +if get_option('werror') + SPHINX_ARGS += [ '-W' ] +endif + # Collect sourcesets. util_ss = ss.source_set() From patchwork Tue Sep 29 20:19:19 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272446 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 5C282C47420 for ; Tue, 29 Sep 2020 20:26:07 +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 8C6322076B for ; Tue, 29 Sep 2020 20:26:06 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="H7jAaqYI" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 8C6322076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:48366 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMCL-00021o-Bj for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:26:05 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59766) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6E-0001sf-Ni for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:54291) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM65-0003V9-Sa for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:46 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410776; 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=3yvUrJZ6eB2FREWIAHx+5JgnVLusjFVDhEfL4cA08Y8=; b=H7jAaqYIrW1gpfBClOgmBzozW4aULG6HbVU0+iVVSWilsRddPbdDGqrpRn5oprEFWD8zEC RFLuokd3sMs50x8JYy8Dtu6AmIgssCg9K6b7nvm/qeBORXl3rrCvtVl6KTuP0H7oQdjZqW D6svDJmL4ltTEpq7XJ2ymmcw9Sb1hdg= 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-487-O8hJCbMJPyytSdV1sXBL4w-1; Tue, 29 Sep 2020 16:19:32 -0400 X-MC-Unique: O8hJCbMJPyytSdV1sXBL4w-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id ADEF5801AE8; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 80FDE7882E; Tue, 29 Sep 2020 20:19:31 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id DFF3011358D4; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 22/29] meson.build: Make manuals depend on source to Sphinx extensions Date: Tue, 29 Sep 2020 22:19:19 +0200 Message-Id: <20200929201926.2155622-23-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell The automatic dependency handling for Sphinx manuals only makes the output depend on the input documentation files. This means that if you edit the Python source of an extension then the documentation won't be rebuilt. Create a list of all the source files for the extensions and add it to the dependencies for the manuals. This is similar to how we handle the qapi_gen_depends list. Because we don't try to identify which manuals are using which Sphinx extensions, a change to the source of one extension will always rebuild the entire manual set, not merely the manuals which have changed. This is acceptable because we don't change the extensions all that often. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-15-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Re rebuilding the enitre manual set being acceptable "because we don't change the extensions all that often": we also rebuild it when the QAPI generator code the qapidoc extension depends on changes. This will inconvenience QAPI developers. Can't be helped now.] Signed-off-by: Markus Armbruster --- docs/meson.build | 1 + meson.build | 8 ++++++++ 2 files changed, 9 insertions(+) diff --git a/docs/meson.build b/docs/meson.build index 52e384be17..0340d489ac 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -36,6 +36,7 @@ if build_docs output: [manual + '.stamp'], input: [files('conf.py'), files(manual / 'conf.py')], depfile: manual + '.d', + depend_files: sphinx_extn_depends, command: [SPHINX_ARGS, '-Ddepfile=@DEPFILE@', '-Ddepfile_stamp=@OUTPUT0@', '-b', 'html', '-d', private_dir, diff --git a/meson.build b/meson.build index 866321462e..6cb8aebd7d 100644 --- a/meson.build +++ b/meson.build @@ -680,6 +680,14 @@ if get_option('werror') SPHINX_ARGS += [ '-W' ] endif +sphinx_extn_depends = [ meson.source_root() / 'docs/sphinx/depfile.py', + meson.source_root() / 'docs/sphinx/hxtool.py', + meson.source_root() / 'docs/sphinx/kerneldoc.py', + meson.source_root() / 'docs/sphinx/kernellog.py', + meson.source_root() / 'docs/sphinx/qapidoc.py', + meson.source_root() / 'docs/sphinx/qmp_lexer.py', + qapi_gen_depends ] + # Collect sourcesets. util_ss = ss.source_set() From patchwork Tue Sep 29 20:19:20 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272437 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=-15.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,WEIRD_QUOTING 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 B3DF7C5516A for ; Tue, 29 Sep 2020 20:41:00 +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 1412D208B8 for ; Tue, 29 Sep 2020 20:41:00 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="DWh3RkFS" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 1412D208B8 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:33324 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMQl-0003g4-1Z for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:40:59 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59858) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6K-0001ww-1f for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:53 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:53356) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM6E-0003Wh-MY for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410786; 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=HBJPg+vCH4UXWdVqF/vNvoeuSOJbiwX5WR6hADxNMtU=; b=DWh3RkFSE7NXF5ire/5HZnD4/tDaAiFsgaN5z4rzuanKBl2pbf1JLjYWBAHcRkRvEB8JUZ eVqYZwOWc/DrNSClS5OpE8SBBLBAhcoV/yZ+4zaZfFAk3znt1T0xlzGSrtQoK4RTBUNG3s O+WO4H5TDfItYjc92kxrFITrCDqAjhI= 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-230-5tElGGFIOw-VxhxC2kXN8g-1; Tue, 29 Sep 2020 16:19:34 -0400 X-MC-Unique: 5tElGGFIOw-VxhxC2kXN8g-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E9C8610BBED8; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 962AF6198E; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id E39E911358D5; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 23/29] tests/qapi-schema: Add test of the rST QAPI doc-comment output Date: Tue, 29 Sep 2020 22:19:20 +0200 Message-Id: <20200929201926.2155622-24-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, WEIRD_QUOTING=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Add a test of the rST output from the QAPI doc-comment generator, similar to what we currently have that tests the Texinfo output. This is a bit more awkward with Sphinx, because the generated output is not 100% under our control the way the QAPI-to-Texinfo generator was. We can't observe the data we generate, only the Sphinx output. Two issues. One, the output can vary with the Sphinx version. In practice Sphinx's plaintext output generation has been identical between at least Sphinx 1.6 and 3.0, so we use that. (The HTML output has had changes across versions). We use an exact-match comparison check, with the understanding that perhaps changes in a future Sphinx version might require us to implement something more clever to cope with variation in the output. Two, the test can only protect us from changes in the data we generate that are visible in plain text. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-16-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Commit message improved] Signed-off-by: Markus Armbruster --- tests/qapi-schema/doc-good.rst | 5 + tests/qapi-schema/doc-good.txt | 288 +++++++++++++++++++++++++++++++++ tests/qapi-schema/meson.build | 55 +++++++ 3 files changed, 348 insertions(+) create mode 100644 tests/qapi-schema/doc-good.rst create mode 100644 tests/qapi-schema/doc-good.txt diff --git a/tests/qapi-schema/doc-good.rst b/tests/qapi-schema/doc-good.rst new file mode 100644 index 0000000000..1e4c23305a --- /dev/null +++ b/tests/qapi-schema/doc-good.rst @@ -0,0 +1,5 @@ +.. + Test Sphinx manual that pulls in the test schema file. We will generate + a plain-text output file and compare it against a reference. + +.. qapi-doc:: tests/qapi-schema/doc-good.json diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt new file mode 100644 index 0000000000..6ca03d49d0 --- /dev/null +++ b/tests/qapi-schema/doc-good.txt @@ -0,0 +1,288 @@ +Section +******* + + +Subsection +========== + +*with emphasis* "var" {in braces} + +* List item one + +* Two, multiple lines + +* Three Still in list + +Not in list + +* Second list Note: still in list + +Note: not in list + +1. Third list is numbered + +2. another item + +Returns: the King Since: the first age Notes: + +1. Lorem ipsum dolor sit amet + +2. Ut enim ad minim veniam + +Duis aute irure dolor + +Example: + +-> in <- out Examples: - *verbatim* - {braces} + + +"Enum" (Enum) +------------- + + +Values +~~~~~~ + +"one" (**If: **"defined(IFONE)") + The _one_ {and only} + +"two" + Not documented + + +Features +~~~~~~~~ + +"enum-feat" + Also _one_ {and only} + +"two" is undocumented + + +If +~~ + +"defined(IFCOND)" + + +"Base" (Object) +--------------- + + +Members +~~~~~~~ + +"base1": "Enum" + the first member + + +"Variant1" (Object) +------------------- + +A paragraph + +Another paragraph (but no "var": line) + + +Members +~~~~~~~ + +"var1": "string" (**If: **"defined(IFSTR)") + Not documented + + +Features +~~~~~~~~ + +"variant1-feat" + a feature + +"member-feat" + a member feature + + +"Variant2" (Object) +------------------- + + +"Object" (Object) +----------------- + + +Members +~~~~~~~ + +The members of "Base" +The members of "Variant1" when "base1" is ""one"" +The members of "Variant2" when "base1" is ""two"" (**If: **"IFTWO") + +Features +~~~~~~~~ + +"union-feat1" + a feature + + +"SugaredUnion" (Object) +----------------------- + + +Members +~~~~~~~ + +"type" + One of "one", "two" + +"data": "Variant1" when "type" is ""one"" +"data": "Variant2" when "type" is ""two"" (**If: **"IFTWO") + +Features +~~~~~~~~ + +"union-feat2" + a feature + + +"Alternate" (Alternate) +----------------------- + + +Members +~~~~~~~ + +"i": "int" + an integer "b" is undocumented + +"b": "boolean" + Not documented + + +Features +~~~~~~~~ + +"alt-feat" + a feature + + +Another subsection +================== + + +"cmd" (Command) +--------------- + + +Arguments +~~~~~~~~~ + +"arg1": "int" + the first argument + +"arg2": "string" (optional) + the second argument + +"arg3": "boolean" + Not documented + + +Features +~~~~~~~~ + +"cmd-feat1" + a feature + +"cmd-feat2" + another feature + + +Note +~~~~ + +"arg3" is undocumented + + +Returns +~~~~~~~ + +"Object" + + +TODO +~~~~ + +frobnicate + + +Notes +~~~~~ + +* Lorem ipsum dolor sit amet + +* Ut enim ad minim veniam + +Duis aute irure dolor + + +Example +~~~~~~~ + + -> in + <- out + + +Examples +~~~~~~~~ + + - *verbatim* + - {braces} + + +Since +~~~~~ + +2.10 + + +"cmd-boxed" (Command) +--------------------- + +If you're bored enough to read this, go see a video of boxed cats + + +Arguments +~~~~~~~~~ + +The members of "Object" + +Features +~~~~~~~~ + +"cmd-feat1" + a feature + +"cmd-feat2" + another feature + + +Example +~~~~~~~ + + -> in + + <- out + + +"EVT-BOXED" (Event) +------------------- + + +Arguments +~~~~~~~~~ + +The members of "Object" + +Features +~~~~~~~~ + +"feat3" + a feature diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 83a0a68389..0c4a6a2936 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -224,3 +224,58 @@ qapi_doc = custom_target('QAPI doc', test('QAPI doc', diff, args: ['-b', '-u', files('doc-good.texi'), qapi_doc[0].full_path()], depends: qapi_doc, suite: ['qapi-schema', 'qapi-doc']) + +# Test the document-comment document generation code by running a test schema +# file through Sphinx's plain-text builder and comparing the result against +# a golden reference. This is in theory susceptible to failures if Sphinx +# changes its output, but the text output has historically been very stable +# (no changes between Sphinx 1.6 and 3.0), so it is a better bet than +# texinfo or HTML generation, both of which have had changes. We might +# need to add more sophisticated logic here in future for some sort of +# fuzzy comparison if future Sphinx versions produce different text, +# but for now the simple comparison suffices. +qapi_doc_out = custom_target('QAPI rST doc', + output: ['doc-good.txt'], + input: files('doc-good.json', 'doc-good.rst'), + build_by_default: build_docs, + depend_files: sphinx_extn_depends, + # We use -E to suppress Sphinx's caching, because + # we want it to always really run the QAPI doc + # generation code. It also means we don't + # clutter up the build dir with the cache. + command: [SPHINX_ARGS, + '-b', 'text', '-E', + '-c', meson.source_root() / 'docs', + '-D', 'master_doc=doc-good', + meson.current_source_dir(), + meson.current_build_dir()]) + +# Fix possible inconsistency in line endings in generated output and +# in the golden reference (which could otherwise cause test failures +# on Windows hosts). Unfortunately diff --strip-trailing-cr +# is GNU-diff only. The odd-looking perl is because we must avoid +# using an explicit '\' character in the command arguments to +# a custom_target(), as Meson will unhelpfully replace it with a '/' +# (https://github.com/mesonbuild/meson/issues/1564) +qapi_doc_out_nocr = custom_target('QAPI rST doc newline-sanitized', + output: ['doc-good.txt.nocr'], + input: qapi_doc_out[0], + build_by_default: build_docs, + command: ['perl', '-pe', '$x = chr 13; s/$x$//', '@INPUT@'], + capture: true) + +qapi_doc_ref_nocr = custom_target('QAPI rST doc reference newline-sanitized', + output: ['doc-good.ref.nocr'], + input: files('doc-good.txt'), + build_by_default: build_docs, + command: ['perl', '-pe', '$x = chr 13; s/$x$//', '@INPUT@'], + capture: true) + +if build_docs + # "full_path()" needed here to work around + # https://github.com/mesonbuild/meson/issues/7585 + test('QAPI rST doc', diff, args: ['-u', qapi_doc_ref_nocr[0].full_path(), + qapi_doc_out_nocr[0].full_path()], + depends: [qapi_doc_ref_nocr, qapi_doc_out_nocr], + suite: ['qapi-schema', 'qapi-doc']) +endif From patchwork Tue Sep 29 20:19:21 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272436 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=-15.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 0480BC4743F for ; Tue, 29 Sep 2020 20:43:53 +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 2DFD6206B5 for ; Tue, 29 Sep 2020 20:43:52 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="UBVZPQvc" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 2DFD6206B5 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:37442 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMTX-0005Ox-7W for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:43:51 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59904) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6X-00022v-6x for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:20:05 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:41021) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM6T-0003Xw-D4 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:20:04 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410800; 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=Gn5jOCS0poa2UbE43hZTbm82Qmaz4lPjSJh43iQOt4c=; b=UBVZPQvcPIxBHn2bhHYkRclX4Uwpn0ZShvtN8OVXh0gF1Mazg4wZbMRxkLDV5hOAl4KzqO DRn0h+aLGV+stzD+Z0wD4YZYgCTtfMYZ/vGHiZiSaEi8wwPFwM+8HRVIk2kXiNydbcLW6i l6QjN+5n8yRPggCtDtn/xRUV0ku6oLs= 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-539-8zSW7Jn1O9-h9ovdmbnTTw-1; Tue, 29 Sep 2020 16:19:34 -0400 X-MC-Unique: 8zSW7Jn1O9-h9ovdmbnTTw-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 226721040C22; Tue, 29 Sep 2020 20:19:33 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 9A1865D9E8; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id E8D1E11358D6; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 24/29] scripts/qapi: Remove texinfo generation support Date: Tue, 29 Sep 2020 22:19:21 +0200 Message-Id: <20200929201926.2155622-25-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@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=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We no longer use the generated texinfo format documentation, so delete the code that generates it, and the test case for the generation. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-17-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- meson.build | 2 - scripts/qapi-gen.py | 2 - scripts/qapi/doc.py | 302 ------------------------------ scripts/qapi/gen.py | 7 - tests/qapi-schema/doc-good.texi | 313 -------------------------------- tests/qapi-schema/meson.build | 9 +- 6 files changed, 1 insertion(+), 634 deletions(-) delete mode 100644 scripts/qapi/doc.py delete mode 100644 tests/qapi-schema/doc-good.texi diff --git a/meson.build b/meson.build index 6cb8aebd7d..5b586afc38 100644 --- a/meson.build +++ b/meson.build @@ -619,7 +619,6 @@ qapi_gen = find_program('scripts/qapi-gen.py') qapi_gen_depends = [ meson.source_root() / 'scripts/qapi/__init__.py', meson.source_root() / 'scripts/qapi/commands.py', meson.source_root() / 'scripts/qapi/common.py', - meson.source_root() / 'scripts/qapi/doc.py', meson.source_root() / 'scripts/qapi/error.py', meson.source_root() / 'scripts/qapi/events.py', meson.source_root() / 'scripts/qapi/expr.py', @@ -631,7 +630,6 @@ qapi_gen_depends = [ meson.source_root() / 'scripts/qapi/__init__.py', meson.source_root() / 'scripts/qapi/types.py', meson.source_root() / 'scripts/qapi/visit.py', meson.source_root() / 'scripts/qapi/common.py', - meson.source_root() / 'scripts/qapi/doc.py', meson.source_root() / 'scripts/qapi-gen.py' ] diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py index 4b03f7d53b..541e8c1f55 100644 --- a/scripts/qapi-gen.py +++ b/scripts/qapi-gen.py @@ -10,7 +10,6 @@ import re import sys from qapi.commands import gen_commands -from qapi.doc import gen_doc from qapi.events import gen_events from qapi.introspect import gen_introspect from qapi.schema import QAPIError, QAPISchema @@ -51,7 +50,6 @@ def main(argv): gen_commands(schema, args.output_dir, args.prefix) gen_events(schema, args.output_dir, args.prefix) gen_introspect(schema, args.output_dir, args.prefix, args.unmask) - gen_doc(schema, args.output_dir, args.prefix) if __name__ == '__main__': diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py deleted file mode 100644 index 7764de1e4b..0000000000 --- a/scripts/qapi/doc.py +++ /dev/null @@ -1,302 +0,0 @@ -# QAPI texi generator -# -# This work is licensed under the terms of the GNU LGPL, version 2+. -# See the COPYING file in the top-level directory. -"""This script produces the documentation of a qapi schema in texinfo format""" - -import re -from qapi.gen import QAPIGenDoc, QAPISchemaVisitor - - -MSG_FMT = """ -@deftypefn {type} {{}} {name} - -{body}{members}{features}{sections} -@end deftypefn - -""".format - -TYPE_FMT = """ -@deftp {{{type}}} {name} - -{body}{members}{features}{sections} -@end deftp - -""".format - -EXAMPLE_FMT = """@example -{code} -@end example -""".format - - -def subst_strong(doc): - """Replaces *foo* by @strong{foo}""" - return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc) - - -def subst_emph(doc): - """Replaces _foo_ by @emph{foo}""" - return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc) - - -def subst_vars(doc): - """Replaces @var by @code{var}""" - return re.sub(r'@([\w-]+)', r'@code{\1}', doc) - - -def subst_braces(doc): - """Replaces {} with @{ @}""" - return doc.replace('{', '@{').replace('}', '@}') - - -def texi_example(doc): - """Format @example""" - # TODO: Neglects to escape @ characters. - # We should probably escape them in subst_braces(), and rename the - # function to subst_special() or subs_texi_special(). If we do that, we - # need to delay it until after subst_vars() in texi_format(). - doc = subst_braces(doc).strip('\n') - return EXAMPLE_FMT(code=doc) - - -def texi_format(doc): - """ - Format documentation - - Lines starting with: - - |: generates an @example - - =: generates @section - - ==: generates @subsection - - 1. or 1): generates an @enumerate @item - - */-: generates an @itemize list - """ - ret = '' - doc = subst_braces(doc) - doc = subst_vars(doc) - doc = subst_emph(doc) - doc = subst_strong(doc) - inlist = '' - lastempty = False - for line in doc.split('\n'): - line = line.strip() - empty = line == '' - - # FIXME: Doing this in a single if / elif chain is - # problematic. For instance, a line without markup terminates - # a list if it follows a blank line (reaches the final elif), - # but a line with some *other* markup, such as a = title - # doesn't. - # - # Make sure to update section "Documentation markup" in - # docs/devel/qapi-code-gen.txt when fixing this. - if line.startswith('| '): - line = EXAMPLE_FMT(code=line[2:]) - elif line.startswith('= '): - line = '@section ' + line[2:] - elif line.startswith('== '): - line = '@subsection ' + line[3:] - elif re.match(r'^([0-9]*\.) ', line): - if not inlist: - ret += '@enumerate\n' - inlist = 'enumerate' - ret += '@item\n' - line = line[line.find(' ')+1:] - elif re.match(r'^[*-] ', line): - if not inlist: - ret += '@itemize %s\n' % {'*': '@bullet', - '-': '@minus'}[line[0]] - inlist = 'itemize' - ret += '@item\n' - line = line[2:] - elif lastempty and inlist: - ret += '@end %s\n\n' % inlist - inlist = '' - - lastempty = empty - ret += line + '\n' - - if inlist: - ret += '@end %s\n\n' % inlist - return ret - - -def texi_body(doc): - """Format the main documentation body""" - return texi_format(doc.body.text) - - -def texi_if(ifcond, prefix='\n', suffix='\n'): - """Format the #if condition""" - if not ifcond: - return '' - return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix) - - -def texi_enum_value(value, desc, suffix): - """Format a table of members item for an enumeration value""" - return '@item @code{%s}\n%s%s' % ( - value.name, desc, texi_if(value.ifcond, prefix='@*')) - - -def texi_member(member, desc, suffix): - """Format a table of members item for an object type member""" - typ = member.type.doc_type() - membertype = ': ' + typ if typ else '' - return '@item @code{%s%s}%s%s\n%s%s' % ( - member.name, membertype, - ' (optional)' if member.optional else '', - suffix, desc, texi_if(member.ifcond, prefix='@*')) - - -def texi_members(doc, what, base=None, variants=None, - member_func=texi_member): - """Format the table of members""" - items = '' - for section in doc.args.values(): - # TODO Drop fallbacks when undocumented members are outlawed - if section.text: - desc = texi_format(section.text) - elif (variants and variants.tag_member == section.member - and not section.member.type.doc_type()): - values = section.member.type.member_names() - members_text = ', '.join(['@t{"%s"}' % v for v in values]) - desc = 'One of ' + members_text + '\n' - else: - desc = 'Not documented\n' - items += member_func(section.member, desc, suffix='') - if base: - items += '@item The members of @code{%s}\n' % base.doc_type() - if variants: - for v in variants.variants: - when = ' when @code{%s} is @t{"%s"}%s' % ( - variants.tag_member.name, v.name, texi_if(v.ifcond, " (", ")")) - if v.type.is_implicit(): - assert not v.type.base and not v.type.variants - for m in v.type.local_members: - items += member_func(m, desc='', suffix=when) - else: - items += '@item The members of @code{%s}%s\n' % ( - v.type.doc_type(), when) - if not items: - return '' - return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) - - -def texi_arguments(doc, boxed_arg_type): - if boxed_arg_type: - assert not doc.args - return ('\n@b{Arguments:} the members of @code{%s}\n' - % boxed_arg_type.name) - return texi_members(doc, 'Arguments') - - -def texi_features(doc): - """Format the table of features""" - items = '' - for section in doc.features.values(): - desc = texi_format(section.text) - items += '@item @code{%s}\n%s' % (section.name, desc) - if not items: - return '' - return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items) - - -def texi_sections(doc, ifcond): - """Format additional sections following arguments""" - body = '' - for section in doc.sections: - if section.name: - # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body += '\n@b{%s:}\n' % section.name - if section.name and section.name.startswith('Example'): - body += texi_example(section.text) - else: - body += texi_format(section.text) - body += texi_if(ifcond, suffix='') - return body - - -def texi_type(typ, doc, ifcond, members): - return TYPE_FMT(type=typ, - name=doc.symbol, - body=texi_body(doc), - members=members, - features=texi_features(doc), - sections=texi_sections(doc, ifcond)) - - -def texi_msg(typ, doc, ifcond, members): - return MSG_FMT(type=typ, - name=doc.symbol, - body=texi_body(doc), - members=members, - features=texi_features(doc), - sections=texi_sections(doc, ifcond)) - - -class QAPISchemaGenDocVisitor(QAPISchemaVisitor): - def __init__(self, prefix): - self._prefix = prefix - self._gen = QAPIGenDoc(self._prefix + 'qapi-doc.texi') - self.cur_doc = None - - def write(self, output_dir): - self._gen.write(output_dir) - - def visit_enum_type(self, name, info, ifcond, features, members, prefix): - doc = self.cur_doc - self._gen.add(texi_type('Enum', doc, ifcond, - texi_members(doc, 'Values', - member_func=texi_enum_value))) - - def visit_object_type(self, name, info, ifcond, features, - base, members, variants): - doc = self.cur_doc - if base and base.is_implicit(): - base = None - self._gen.add(texi_type('Object', doc, ifcond, - texi_members(doc, 'Members', base, variants))) - - def visit_alternate_type(self, name, info, ifcond, features, variants): - doc = self.cur_doc - self._gen.add(texi_type('Alternate', doc, ifcond, - texi_members(doc, 'Members'))) - - def visit_command(self, name, info, ifcond, features, - arg_type, ret_type, gen, success_response, boxed, - allow_oob, allow_preconfig): - doc = self.cur_doc - self._gen.add(texi_msg('Command', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None))) - - def visit_event(self, name, info, ifcond, features, arg_type, boxed): - doc = self.cur_doc - self._gen.add(texi_msg('Event', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None))) - - def symbol(self, doc, entity): - if self._gen._body: - self._gen.add('\n') - self.cur_doc = doc - entity.visit(self) - self.cur_doc = None - - def freeform(self, doc): - assert not doc.args - if self._gen._body: - self._gen.add('\n') - self._gen.add(texi_body(doc) + texi_sections(doc, None)) - - -def gen_doc(schema, output_dir, prefix): - vis = QAPISchemaGenDocVisitor(prefix) - vis.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - vis.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - vis.freeform(doc) - vis.write(output_dir) diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py index bf5552a4e7..ca66c82b5b 100644 --- a/scripts/qapi/gen.py +++ b/scripts/qapi/gen.py @@ -178,13 +178,6 @@ def ifcontext(ifcond, *args): arg.end_if() -class QAPIGenDoc(QAPIGen): - - def _top(self): - return (super()._top() - + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') - - class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor): def __init__(self, prefix, what, blurb, pydoc): diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi deleted file mode 100644 index 29abef33e9..0000000000 --- a/tests/qapi-schema/doc-good.texi +++ /dev/null @@ -1,313 +0,0 @@ -@c AUTOMATICALLY GENERATED, DO NOT MODIFY - -@section Section - -@subsection Subsection - -@strong{with emphasis} -@code{var} @{in braces@} - -@itemize @bullet -@item -List item one -@item -Two, multiple -lines - -@item -Three -Still in list - -@end itemize - -Not in list - -@itemize @minus -@item -Second list -Note: still in list - -@end itemize - -Note: not in list - -@enumerate -@item -Third list -is numbered - -@item -another item - -@end enumerate - -Returns: the King -Since: the first age -Notes: - -@enumerate -@item -Lorem ipsum dolor sit amet - -@item -Ut enim ad minim veniam - -@end enumerate - -Duis aute irure dolor - -Example: - --> in -<- out -Examples: -@itemize @minus -@item -@strong{verbatim} -@item -@{braces@} -@end itemize - - - -@deftp {Enum} Enum - - - -@b{Values:} -@table @asis -@item @code{one} -The @emph{one} @{and only@} -@*@b{If:} @code{defined(IFONE)} -@item @code{two} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{enum-feat} -Also @emph{one} @{and only@} -@end table -@code{two} is undocumented - -@b{If:} @code{defined(IFCOND)} -@end deftp - - - -@deftp {Object} Base - - - -@b{Members:} -@table @asis -@item @code{base1: Enum} -the first member -@end table - -@end deftp - - - -@deftp {Object} Variant1 - -A paragraph - -Another paragraph (but no @code{var}: line) - -@b{Members:} -@table @asis -@item @code{var1: string} -Not documented -@*@b{If:} @code{defined(IFSTR)} -@end table - -@b{Features:} -@table @asis -@item @code{variant1-feat} -a feature -@item @code{member-feat} -a member feature -@end table - -@end deftp - - - -@deftp {Object} Variant2 - - - -@end deftp - - - -@deftp {Object} Object - - - -@b{Members:} -@table @asis -@item The members of @code{Base} -@item The members of @code{Variant1} when @code{base1} is @t{"one"} -@item The members of @code{Variant2} when @code{base1} is @t{"two"} (@b{If:} @code{IFTWO}) -@end table - -@b{Features:} -@table @asis -@item @code{union-feat1} -a feature -@end table - -@end deftp - - - -@deftp {Object} SugaredUnion - - - -@b{Members:} -@table @asis -@item @code{type} -One of @t{"one"}, @t{"two"} -@item @code{data: Variant1} when @code{type} is @t{"one"} -@item @code{data: Variant2} when @code{type} is @t{"two"} (@b{If:} @code{IFTWO}) -@end table - -@b{Features:} -@table @asis -@item @code{union-feat2} -a feature -@end table - -@end deftp - - - -@deftp {Alternate} Alternate - - - -@b{Members:} -@table @asis -@item @code{i: int} -an integer -@code{b} is undocumented -@item @code{b: boolean} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{alt-feat} -a feature -@end table - -@end deftp - - -@subsection Another subsection - - -@deftypefn Command {} cmd - - - -@b{Arguments:} -@table @asis -@item @code{arg1: int} -the first argument -@item @code{arg2: string} (optional) -the second -argument -@item @code{arg3: boolean} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Note:} -@code{arg3} is undocumented - -@b{Returns:} -@code{Object} - -@b{TODO:} -frobnicate - -@b{Notes:} -@itemize @minus -@item -Lorem ipsum dolor sit amet -@item -Ut enim ad minim veniam - -@end itemize - -Duis aute irure dolor - -@b{Example:} -@example --> in -<- out -@end example - -@b{Examples:} -@example -- *verbatim* -- @{braces@} -@end example - -@b{Since:} -2.10 - -@end deftypefn - - - -@deftypefn Command {} cmd-boxed - -If you're bored enough to read this, go see a video of boxed cats - -@b{Arguments:} the members of @code{Object} - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Example:} -@example --> in - -<- out -@end example - -@end deftypefn - - - -@deftypefn Event {} EVT-BOXED - - - -@b{Arguments:} the members of @code{Object} - -@b{Features:} -@table @asis -@item @code{feat3} -a feature -@end table - -@end deftypefn - diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 0c4a6a2936..f08c902911 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -206,8 +206,7 @@ test('QAPI schema regression tests', python, args: files('test-qapi.py', schemas diff = find_program('diff') qapi_doc = custom_target('QAPI doc', - output: ['doc-good-qapi-doc.texi', - 'doc-good-qapi-commands.c', 'doc-good-qapi-commands.h', + output: ['doc-good-qapi-commands.c', 'doc-good-qapi-commands.h', 'doc-good-qapi-emit-events.c', 'doc-good-qapi-emit-events.h', 'doc-good-qapi-events.c', 'doc-good-qapi-events.h', 'doc-good-qapi-init-commands.c', 'doc-good-qapi-init-commands.h', @@ -219,12 +218,6 @@ qapi_doc = custom_target('QAPI doc', '-p', 'doc-good-', '@INPUT0@' ], depend_files: qapi_gen_depends) -# "full_path()" needed here to work around -# https://github.com/mesonbuild/meson/issues/7585 -test('QAPI doc', diff, args: ['-b', '-u', files('doc-good.texi'), qapi_doc[0].full_path()], - depends: qapi_doc, - suite: ['qapi-schema', 'qapi-doc']) - # Test the document-comment document generation code by running a test schema # file through Sphinx's plain-text builder and comparing the result against # a golden reference. This is in theory susceptible to failures if Sphinx From patchwork Tue Sep 29 20:19:22 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272442 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 01771C47420 for ; Tue, 29 Sep 2020 20:32:04 +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 7D50A2076B for ; Tue, 29 Sep 2020 20:32:03 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="RP4QHz84" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 7D50A2076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:36594 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMI6-0000vK-1l for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:32:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59802) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6G-0001uz-KF for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:57945) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM65-0003Uz-TR for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:48 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410776; 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=XDFJeVUsisnwDdRZpH272FpeMreIsJc+R3Xwkz1S64E=; b=RP4QHz84YQfhaA3cONV1MmUW5Bi1CIUR5mT7aP5YhVqGT6QJkCT7bO7SyLz1YDO+VFCjTB cIJtOG8r6jfAin2p40CBf5Zp9vGy3Jn68wOukoebfMNveMHC46Fu2dpRFF68ivsYuJFiws qih0mBcAoFoeTDxJg4G6sBuh5vteEd8= 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-240-w3dtr8e_OqeuXc4HY_u71A-1; Tue, 29 Sep 2020 16:19:34 -0400 X-MC-Unique: w3dtr8e_OqeuXc4HY_u71A-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 15AF5801AE9; Tue, 29 Sep 2020 20:19:33 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B435219C4F; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id ED04711358D8; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 25/29] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Date: Tue, 29 Sep 2020 22:19:22 +0200 Message-Id: <20200929201926.2155622-26-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell Update the documentation of QAPI document comment syntax to match the new rST backend requirements. The principal changes are: * whitespace is now significant, and multiline definitions must have their second and subsequent lines indented to match the first line * general rST format markup is permitted, not just the small set of markup the old texinfo generator handled. For most things (notably bulleted and itemized lists) the old format was the same as rST is. * Specific things that might trip people up: - instead of *bold* and _italic_ rST has **bold** and *italic* - lists need a preceding and following blank line - a lone literal '*' will need to be backslash-escaped to avoid a rST syntax error * the old leading '|' for example (literal text) blocks is replaced by the standard rST '::' literal block. * we support arbitrary levels of sub- and sub-sub-heading, not just a main and sub-heading like the old texinfo generator * lists can now be nested Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-18-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster [Commit message improved slightly] Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.txt | 83 +++++++++++++++++++++++------------- 1 file changed, 53 insertions(+), 30 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 2a09d4d292..5fc67c99cd 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -824,23 +824,37 @@ See below for more on definition documentation. Free-form documentation may be used to provide additional text and structuring content. +==== Headings and subheadings ==== + +A free-form documentation comment containing a line which starts with +some '=' symbols and then a space defines a section heading: + + ## + # = This is a top level heading + # + # This is a free-form comment which will go under the + # top level heading. + ## + + ## + # == This is a second level heading + ## + +A heading line must be the first line of the documentation +comment block. + +Section headings must always be correctly nested, so you can only +define a third-level heading inside a second-level heading, and so on. ==== Documentation markup ==== -Comment text starting with '=' is a section title: +Documentation comments can use most rST markup. In particular, +a '::' literal block can be used for examples: - # = Section title - -Double the '=' for a subsection title: - - # == Subsection title - -Both are only permitted in free-form documentation. - -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines + # :: + # + # Text of the example, may span + # multiple lines '*' starts an itemized list: @@ -856,34 +870,33 @@ A decimal number followed by '.' starts a numbered list: # multiple lines # 2. Second item -The actual number doesn't matter. You could even use '*' instead of -'2.' for the second item. +The actual number doesn't matter. -Lists can't be nested. Blank lines are currently not supported within -lists. +Lists of either kind must be preceded and followed by a blank line. +If a list item's text spans multiple lines, then the second and +subsequent lines must be correctly indented to line up with the +first character of the first line. -Additional whitespace between the initial '#' and the comment text is -permitted. - -*foo* and _foo_ are for strong and emphasis styles respectively (they -do not work over multiple lines). @foo is used to reference a name in -the schema. +The usual '**strong**', '*emphasised*' and '``literal``' markup should +be used. If you need a single literal '*' you will need to +backslash-escape it. As an extension beyond the usual rST syntax, you +can also use '@foo' to reference a name in the schema; this is +rendered the same way as '``foo``'. Example: ## -# = Section -# == Subsection -# -# Some text foo with *strong* and _emphasis_ +# Some text foo with **bold** and *emphasis* # 1. with a list # 2. like that # # And some code: -# | $ echo foo -# | -> do this -# | <- get that # +# :: +# +# $ echo foo +# -> do this +# <- get that ## @@ -937,6 +950,16 @@ multiline argument descriptions. A 'Since: x.y.z' tagged section lists the release that introduced the definition. +The text of a section can start on a new line, in +which case it must not be indented at all. It can also start +on the same line as the 'Note:', 'Returns:', etc tag. In this +case if it spans multiple lines then second and subsequent +lines must be indented to match the first. + +An 'Example' or 'Examples' section is automatically rendered +entirely as literal fixed-width text. In other sections, +the text is formatted, and rST markup can be used. + For example: ## From patchwork Tue Sep 29 20:19:23 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304114 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 38E95C47423 for ; Tue, 29 Sep 2020 20:34:00 +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 9157E20848 for ; Tue, 29 Sep 2020 20:33:59 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Ub5Wltix" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 9157E20848 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:44488 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMJy-0004Kq-JV for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:33:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59856) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6J-0001vq-MR for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:48189) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM68-0003Va-5O for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410778; 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=dQ/dcPZ69BPaO7eoiLLFu9hcpkuJWDz3vhNKfiFxln4=; b=Ub5WltixsjLt4id6H6qVS8RNrGJFhvURvibmTO1GGgT5XvtghWe+PRxUMywZMM8Y5LW83C Umq8tiZRl4pVoULI8Nsdvv9mYpX9nE5vYfV1vuexVtRfBQ1Md5UHHUzi3b8Cb55VCnhX6M ivGC8y/UZGeA/zhYyeJ8Je6Mn+zsz/E= 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-545-CLnpzKJ6NGGyF8-KHen64g-1; Tue, 29 Sep 2020 16:19:34 -0400 X-MC-Unique: CLnpzKJ6NGGyF8-KHen64g-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 2151818BE160; Tue, 29 Sep 2020 20:19:33 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 998DC5D9E4; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id F17EB11358D9; Tue, 29 Sep 2020 22:19:26 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 26/29] scripts/texi2pod: Delete unused script Date: Tue, 29 Sep 2020 22:19:23 +0200 Message-Id: <20200929201926.2155622-27-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@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=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We no longer need the texi2pod script, so we can delete it, and the special-casing it had in the checkpatch script. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-19-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- scripts/checkpatch.pl | 2 +- scripts/texi2pod.pl | 536 ------------------------------------------ 2 files changed, 1 insertion(+), 537 deletions(-) delete mode 100755 scripts/texi2pod.pl diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 50910899f2..1ba8a3810b 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -1659,7 +1659,7 @@ sub process { # tabs are only allowed in assembly source code, and in # some scripts we imported from other projects. next if ($realfile =~ /\.(s|S)$/); - next if ($realfile =~ /(checkpatch|get_maintainer|texi2pod)\.pl$/); + next if ($realfile =~ /(checkpatch|get_maintainer)\.pl$/); if ($rawline =~ /^\+.*\t/) { my $herevet = "$here\n" . cat_vet($rawline) . "\n"; diff --git a/scripts/texi2pod.pl b/scripts/texi2pod.pl deleted file mode 100755 index 8bfc6f6f4c..0000000000 --- a/scripts/texi2pod.pl +++ /dev/null @@ -1,536 +0,0 @@ -#! /usr/bin/env perl - -# Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc. - -# This file is part of GCC. - -# GCC is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# GCC is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GCC; see the file COPYING. If not, -# see . - -# This does trivial (and I mean _trivial_) conversion of Texinfo -# markup to Perl POD format. It's intended to be used to extract -# something suitable for a manpage from a Texinfo document. - -use warnings; - -$output = 0; -$skipping = 0; -%sects = (); -$section = ""; -@icstack = (); -@endwstack = (); -@skstack = (); -@instack = (); -$shift = ""; -%defs = (); -$fnno = 1; -$inf = ""; -$ibase = ""; -@ipath = (); -$encoding = undef; -@args = (); - -while ($_ = shift) { - if (/^-D(.*)$/) { - if ($1 ne "") { - $flag = $1; - } else { - $flag = shift; - } - $value = ""; - ($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/); - die "no flag specified for -D\n" - unless $flag ne ""; - die "flags may only contain letters, digits, hyphens, dashes and underscores\n" - unless $flag =~ /^[a-zA-Z0-9_-]+$/; - $defs{$flag} = $value; - } elsif (/^-I(.*)$/) { - if ($1 ne "") { - $flag = $1; - } else { - $flag = shift; - } - push (@ipath, $flag); - } elsif (/^-/) { - usage(); - } else { - $in = $_, next unless defined $in; - $out = $_, next unless defined $out; - usage(); - } -} - -if (defined $in) { - $inf = gensym(); - open($inf, "<$in") or die "opening \"$in\": $!\n"; - $ibase = $1 if $in =~ m|^(.+)/[^/]+$|; -} else { - $inf = \*STDIN; -} - -if (defined $out) { - open(STDOUT, ">$out") or die "opening \"$out\": $!\n"; -} - -while(defined $inf) { -while(<$inf>) { - # Certain commands are discarded without further processing. - /^\@(?: - [a-z]+index # @*index: useful only in complete manual - |need # @need: useful only in printed manual - |(?:end\s+)?group # @group .. @end group: ditto - |page # @page: ditto - |node # @node: useful only in .info file - |(?:end\s+)?ifnottex # @ifnottex .. @end ifnottex: use contents - )\b/x and next; - - chomp; - - # Look for filename and title markers. - /^\@setfilename\s+([^.]+)/ and $fn = $1, next; - /^\@settitle\s+([^.]+)/ and $tl = postprocess($1), next; - - # Look for document encoding - /^\@documentencoding\s+([^.]+)/ and do { - $encoding = $1 unless defined $encoding; - next; - }; - - # Identify a man title but keep only the one we are interested in. - /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do { - if (exists $defs{$1}) { - $fn = $1; - $tl = postprocess($2); - } - next; - }; - - # Look for blocks surrounded by @c man begin SECTION ... @c man end. - # This really oughta be @ifman ... @end ifman and the like, but such - # would require rev'ing all other Texinfo translators. - /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do { - $output = 1 if exists $defs{$2}; - $sect = $1; - next; - }; - /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect = $1, $output = 1, next; - /^\@c\s+man\s+end/ and do { - $sects{$sect} = "" unless exists $sects{$sect}; - $sects{$sect} .= postprocess($section); - $section = ""; - $output = 0; - next; - }; - - # handle variables - /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do { - $defs{$1} = $2; - next; - }; - /^\@clear\s+([a-zA-Z0-9_-]+)/ and do { - delete $defs{$1}; - next; - }; - - # Single line command handlers. - - /^\@include\s+(.+)$/ and do { - push @instack, $inf; - $inf = gensym(); - $file = postprocess($1); - - # Try cwd and $ibase, then explicit -I paths. - $done = 0; - foreach $path ("", $ibase, @ipath) { - $mypath = $file; - $mypath = $path . "/" . $mypath if ($path ne ""); - open($inf, "<" . $mypath) and ($done = 1, last); - } - die "cannot find $file" if !$done; - next; - }; - - next unless $output; - - # Discard comments. (Can't do it above, because then we'd never see - # @c man lines.) - /^\@c\b/ and next; - - # End-block handler goes up here because it needs to operate even - # if we are skipping. - /^\@end\s+([a-z]+)/ and do { - # Ignore @end foo, where foo is not an operation which may - # cause us to skip, if we are presently skipping. - my $ended = $1; - next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex|copying)$/; - - die "\@end $ended without \@$ended at line $.\n" unless defined $endw; - die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw; - - $endw = pop @endwstack; - - if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) { - $skipping = pop @skstack; - next; - } elsif ($ended =~ /^(?:example|smallexample|display - |quotation|deftp|deftypefn)$/x) { - $shift = ""; - $_ = ""; # need a paragraph break - } elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) { - $_ = "\n=back\n"; - $ic = pop @icstack; - } elsif ($ended eq "multitable") { - $_ = "\n=back\n"; - } else { - die "unknown command \@end $ended at line $.\n"; - } - }; - - # We must handle commands which can cause skipping even while we - # are skipping, otherwise we will not process nested conditionals - # correctly. - /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = "ifset"; - $skipping = 1 unless exists $defs{$1}; - next; - }; - - /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = "ifclear"; - $skipping = 1 if exists $defs{$1}; - next; - }; - - /^\@(ignore|menu|iftex|copying)\b/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw = $1; - $skipping = 1; - next; - }; - - next if $skipping; - - # Character entities. First the ones that can be replaced by raw text - # or discarded outright: - s/\@copyright\{\}/(c)/g; - s/\@dots\{\}/.../g; - s/\@enddots\{\}/..../g; - s/\@([.!? ])/$1/g; - s/\@[:-]//g; - s/\@bullet(?:\{\})?/*/g; - s/\@TeX\{\}/TeX/g; - s/\@pounds\{\}/\#/g; - s/\@minus(?:\{\})?/-/g; - s/\\,/,/g; - - # Now the ones that have to be replaced by special escapes - # (which will be turned back into text by unmunge()) - s/&/&/g; - s/\@\{/{/g; - s/\@\}/}/g; - s/\@\@/&at;/g; - - # Inside a verbatim block, handle @var specially. - if ($shift ne "") { - s/\@var\{([^\}]*)\}/<$1>/g; - } - - # POD doesn't interpret E<> inside a verbatim block. - if ($shift eq "") { - s//>/g; - } else { - s//>/g; - } - - /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/ - and $_ = "\n=head2 $1\n"; - /^\@subsection\s+(.+)$/ - and $_ = "\n=head3 $1\n"; - /^\@subsubsection\s+(.+)$/ - and $_ = "\n=head4 $1\n"; - - # Block command handlers: - /^\@itemize(?:\s+(\@[a-z]+|\*|-))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic = $1; - } else { - $ic = '*'; - } - $_ = "\n=over 4\n"; - $endw = "itemize"; - }; - - /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic = $1 . "."; - } else { - $ic = "1."; - } - $_ = "\n=over 4\n"; - $endw = "enumerate"; - }; - - /^\@multitable\s.*/ and do { - push @endwstack, $endw; - $endw = "multitable"; - $_ = "\n=over 4\n"; - }; - - /^\@([fv]?table)\s+(\@[a-z]+)/ and do { - push @endwstack, $endw; - push @icstack, $ic; - $endw = $1; - $ic = $2; - $ic =~ s/\@(?:samp|strong|key|gcctabopt|option|env)/B/; - $ic =~ s/\@(?:code|kbd)/C/; - $ic =~ s/\@(?:dfn|var|emph|cite|i)/I/; - $ic =~ s/\@(?:file)/F/; - $ic =~ s/\@(?:asis)//; - $_ = "\n=over 4\n"; - }; - - /^\@((?:small)?example|display)/ and do { - push @endwstack, $endw; - $endw = $1; - $shift = "\t"; - $_ = ""; # need a paragraph break - }; - - /^\@item\s+(.*\S)\s*$/ and $endw eq "multitable" and do { - @columns = (); - for $column (split (/\s*\@tab\s*/, $1)) { - # @strong{...} is used a @headitem work-alike - $column =~ s/^\@strong\{(.*)\}$/$1/; - push @columns, $column; - } - $_ = "\n=item ".join (" : ", @columns)."\n"; - }; - - /^\@(quotation)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw = $1; - $_ = "\n$2:" - }; - - /^{(.*)}$|^(.*)$/ and $#args > 0 and do { - $kind = $args[0]; - $arguments = $1 // ""; - if ($endw eq "deftypefn") { - $ret = $args[1]; - $fname = "B<$args[2]>"; - $_ = $ret ? "$ret " : ""; - $_ .= "$fname $arguments ($kind)"; - } else { - $_ = "B<$args[1]> ($kind)\n\n$arguments"; - } - @args = (); - }; - - /^\@(deftp)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw = $1; - $arg = $2; - $arg =~ s/{([^}]*)}/$1/g; - $arg =~ s/\@$//; - @args = split (/ /, $arg); - $_ = ""; - }; - - /^\@(deftypefn)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw = $1; - $arg = $2; - $arg =~ s/{([^}]*)}/$1/g; - $arg =~ s/\@$//; - @args = split (/ /, $arg); - $_ = ""; - }; - - /^\@itemx?\s*(.+)?$/ and do { - if (defined $1) { - if ($ic eq "") { - $_ = "\n=item $1\n"; - } else { - # Entity escapes prevent munging by the <> processing below. - $_ = "\n=item $ic\<$1\>\n"; - } - } else { - $_ = "\n=item $ic\n"; - $ic =~ y/A-Ya-y/B-Zb-z/; - $ic =~ s/(\d+)/$1 + 1/eg; - } - }; - - $section .= $shift.$_."\n"; -} -# End of current file. -close($inf); -$inf = pop @instack; -} - -die "No filename or title\n" unless defined $fn && defined $tl; - -print "=encoding $encoding\n\n" if defined $encoding; - -$sects{NAME} = "$fn \- $tl\n"; -$sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES}; - -for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES - BUGS NOTES FOOTNOTES EXAMPLES SEEALSO AUTHOR COPYRIGHT)) { - if(exists $sects{$sect}) { - $head = $sect; - $head =~ s/SEEALSO/SEE ALSO/; - print "=head1 $head\n\n"; - print scalar unmunge ($sects{$sect}); - print "\n"; - } -} - -sub usage -{ - die "usage: $0 [-D toggle...] [infile [outfile]]\n"; -} - -sub postprocess -{ - local $_ = $_[0]; - - # @value{foo} is replaced by whatever 'foo' is defined as. - while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) { - if (! exists $defs{$2}) { - print STDERR "Option $2 not defined\n"; - s/\Q$1\E//; - } else { - $value = $defs{$2}; - s/\Q$1\E/$value/; - } - } - - # Formatting commands. - # Temporary escape for @r. - s/\@r\{([^\}]*)\}/R<$1>/g; - s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g; - s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g; - s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g; - s/\@sc\{([^\}]*)\}/\U$1/g; - s/\@file\{([^\}]*)\}/F<$1>/g; - s/\@w\{([^\}]*)\}/S<$1>/g; - s/\@t\{([^\}]*)\}/$1/g; - s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; - - # keep references of the form @ref{...}, print them bold - s/\@(?:ref)\{([^\}]*)\}/B<$1>/g; - - # Change double single quotes to double quotes. - s/''/"/g; - s/``/"/g; - - # Cross references are thrown away, as are @noindent and @refill. - # (@noindent is impossible in .pod, and @refill is unnecessary.) - # @* is also impossible in .pod; we discard it and any newline that - # follows it. Similarly, our macro @gol must be discarded. - - s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g; - s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g; - s/;\s+\@pxref\{(?:[^\}]*)\}//g; - s/\@noindent\s*//g; - s/\@refill//g; - s/\@gol//g; - s/\@\*\s*\n?//g; - - # Anchors are thrown away - s/\@anchor\{(?:[^\}]*)\}//g; - - # @uref can take one, two, or three arguments, with different - # semantics each time. @url and @email are just like @uref with - # one argument, for our purposes. - s/\@(?:uref|url|email)\{([^\},]*)\}/<B<$1>>/g; - s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g; - s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g; - - # Un-escape <> at this point. - s/<//g; - - # Now un-nest all B<>, I<>, R<>. Theoretically we could have - # indefinitely deep nesting; in practice, one level suffices. - 1 while s/([BIR])<([^<>]*)([BIR])<([^<>]*)>/$1<$2>$3<$4>$1 with bare ...; eliminate empty markup, B<>; - # shift white space at the ends of [BI]<...> expressions outside - # the expression. - s/R<([^<>]*)>/$1/g; - s/[BI]<>//g; - s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g; - s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g; - - # Extract footnotes. This has to be done after all other - # processing because otherwise the regexp will choke on formatting - # inside @footnote. - while (/\@footnote/g) { - s/\@footnote\{([^\}]+)\}/[$fnno]/; - add_footnote($1, $fnno); - $fnno++; - } - - return $_; -} - -sub unmunge -{ - # Replace escaped symbols with their equivalents. - local $_ = $_[0]; - - s/</E/g; - s/>/E/g; - s/{/\{/g; - s/}/\}/g; - s/&at;/\@/g; - s/&/&/g; - return $_; -} - -sub add_footnote -{ - unless (exists $sects{FOOTNOTES}) { - $sects{FOOTNOTES} = "\n=over 4\n\n"; - } - - $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++; - $sects{FOOTNOTES} .= $_[0]; - $sects{FOOTNOTES} .= "\n\n"; -} - -# stolen from Symbol.pm -{ - my $genseq = 0; - sub gensym - { - my $name = "GEN" . $genseq++; - my $ref = \*{$name}; - delete $::{$name}; - return $ref; - } -} From patchwork Tue Sep 29 20:19:24 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 272438 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 5091EC54EE9 for ; Tue, 29 Sep 2020 20:39:25 +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 A5D892074B for ; Tue, 29 Sep 2020 20:39:23 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="XoOH8KDm" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org A5D892074B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:57378 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMPB-0001ma-Qp for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:39:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59862) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6K-0001x9-Cb for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:53 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:29934) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM68-0003Vq-70 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:52 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410779; 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=TGPfmmVhPIuqtM33c0UlJiypRZdavtKdmQaVymzvZLU=; b=XoOH8KDmpfuAh0J/HvMEuzam39glH+zDLyx1vXHaqptDRx7vBZFlnHClmu7qecbsaIs9iu sp+KW1NfZ4efh9g1NIOB9iU7kTJzLg+YVmC5GpUQ2PL1CHze0BYUWpJRsxuksbDGQYHtIL fUpeaw6mE5dkalLLXnhA1MACaytTFII= 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-126-Fm0ZRcnhNA-nW35d4GnBgg-1; Tue, 29 Sep 2020 16:19:33 -0400 X-MC-Unique: Fm0ZRcnhNA-nW35d4GnBgg-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D55A11DE03; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id A8674619B5; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 0171E11358DA; Tue, 29 Sep 2020 22:19:27 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 27/29] Remove Texinfo related line from git.orderfile Date: Tue, 29 Sep 2020 22:19:24 +0200 Message-Id: <20200929201926.2155622-28-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 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 Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We don't use Texinfo any more; we can remove the references to the .texi source file from our git.orderfile. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-20-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- scripts/git.orderfile | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/git.orderfile b/scripts/git.orderfile index a021afc2d5..3736c1d6af 100644 --- a/scripts/git.orderfile +++ b/scripts/git.orderfile @@ -12,7 +12,6 @@ # Documentation docs/* *.rst -*.texi # build system configure From patchwork Tue Sep 29 20:19:25 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304113 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 37B31C4727C for ; Tue, 29 Sep 2020 20:35:00 +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 870CF2076B for ; Tue, 29 Sep 2020 20:34:59 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="IRXJEsyW" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 870CF2076B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:46648 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMKw-0005GG-CC for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:34:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59860) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6K-0001x8-96 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:53 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:53941) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM6F-0003Wp-LI for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:51 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410786; 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=UyNoF6Vbf91KHQj0PbwDBku/9y2cJ8cDM2oIkeoQQH8=; b=IRXJEsyWF7eAjRu4Xv1SvL/MBeqPBAOcADcsWC7Pnkbvs/YL1TYnYeWgaeNYy/UtB3niq4 33L5iquO7iuYtN9LMHh4HBX9O3hAReTdMtAP76cNsCxneIayAYxlI1cEyS8o1YlfMHBHNI rM8jpRmzw81ljXUGyWchyOXfKAAH6fI= 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-428-kBSA0BSiN2OQ62r-vviXfg-1; Tue, 29 Sep 2020 16:19:33 -0400 X-MC-Unique: kBSA0BSiN2OQ62r-vviXfg-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 DAC6D1DE06; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id ACE215D9DC; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 0658611358DC; Tue, 29 Sep 2020 22:19:27 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 28/29] configure: Drop texinfo requirement Date: Tue, 29 Sep 2020 22:19:25 +0200 Message-Id: <20200929201926.2155622-29-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@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=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=63.128.21.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/28 22:47:55 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org, Richard Henderson Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We don't need the texinfo and pod2man programs to build our documentation any more, so remove them from configure's tests. Reviewed-by: Richard Henderson Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-21-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- configure | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/configure b/configure index 8ee15810c8..ecc8e90e8b 100755 --- a/configure +++ b/configure @@ -4874,14 +4874,14 @@ if test "$docs" != "no" ; then else sphinx_ok=no fi - if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then + if test "$sphinx_ok" = "yes"; then docs=yes else if test "$docs" = "yes" ; then if has $sphinx_build && test "$sphinx_ok" != "yes"; then echo "Warning: $sphinx_build exists but it is either too old or uses too old a Python version" >&2 fi - feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx" + feature_not_found "docs" "Install a Python 3 version of python-sphinx" fi docs=no fi @@ -6301,13 +6301,6 @@ if test "$solaris" = "no" && test "$tsan" = "no"; then fi fi -# test if pod2man has --utf8 option -if pod2man --help | grep -q utf8; then - POD2MAN="pod2man --utf8" -else - POD2MAN="pod2man" -fi - # Use ASLR, no-SEH and DEP if available if test "$mingw32" = "yes" ; then for flag in --dynamicbase --no-seh --nxcompat; do @@ -7456,7 +7449,6 @@ echo "HOST_DSOSUF=$HOST_DSOSUF" >> $config_host_mak echo "LIBS_QGA=$libs_qga" >> $config_host_mak echo "TASN1_LIBS=$tasn1_libs" >> $config_host_mak echo "TASN1_CFLAGS=$tasn1_cflags" >> $config_host_mak -echo "POD2MAN=$POD2MAN" >> $config_host_mak if test "$gcov" = "yes" ; then echo "CONFIG_GCOV=y" >> $config_host_mak fi From patchwork Tue Sep 29 20:19:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 304115 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=-10.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED 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 ACA39C4727F for ; Tue, 29 Sep 2020 20:32:14 +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 2083D20789 for ; Tue, 29 Sep 2020 20:32:14 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=redhat.com header.i=@redhat.com header.b="Do2UnsRw" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 2083D20789 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Received: from localhost ([::1]:37010 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kNMIG-000195-R2 for qemu-devel@archiver.kernel.org; Tue, 29 Sep 2020 16:32:12 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59778) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kNM6F-0001t8-Go for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:57405) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kNM65-0003VD-S1 for qemu-devel@nongnu.org; Tue, 29 Sep 2020 16:19:47 -0400 Dkim-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1601410776; 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=8K+DshiWKB+kYIq5FXrQuaN+d5b9nzNbf0RKpx257yo=; b=Do2UnsRwys+i7f5rDIytmnUUZ3NdJrEpD58m6WJqjJASUL6iERkRHNNxLFJg4LqIdK7dEE r/CNqaXZ+fYwBRBqA3WBEJJ4QiEDlJcM4YJveVk9JruLUs5algVYdWModUZ09cqDX2AelT EkeatB3Bqy94yqTs8i8hyrvmSETV3XE= 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-361-eMEXWI81PkChR_htW9pzoA-1; Tue, 29 Sep 2020 16:19:34 -0400 X-MC-Unique: eMEXWI81PkChR_htW9pzoA-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 0D47718BE165; Tue, 29 Sep 2020 20:19:33 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-101.ams2.redhat.com [10.36.112.101]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D425A73674; Tue, 29 Sep 2020 20:19:32 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 0A93E11358DD; Tue, 29 Sep 2020 22:19:27 +0200 (CEST) From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PULL 29/29] Remove texinfo dependency from docker and CI configs Date: Tue, 29 Sep 2020 22:19:26 +0200 Message-Id: <20200929201926.2155622-30-armbru@redhat.com> In-Reply-To: <20200929201926.2155622-1-armbru@redhat.com> References: <20200929201926.2155622-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 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 Received-SPF: pass client-ip=216.205.24.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/29 02:22:44 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.687, 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=0.001, RCVD_IN_MSPIKE_WL=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@linaro.org Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" From: Peter Maydell We don't need texinfo to build the docs any more, so we can drop that dependency from our docker and other CI configs. Signed-off-by: Peter Maydell Message-Id: <20200925162316.21205-22-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- .travis.yml | 1 - scripts/coverity-scan/coverity-scan.docker | 1 - tests/docker/dockerfiles/debian10.docker | 1 - tests/docker/dockerfiles/fedora.docker | 1 - tests/docker/dockerfiles/ubuntu.docker | 1 - tests/docker/dockerfiles/ubuntu1804.docker | 1 - tests/docker/dockerfiles/ubuntu2004.docker | 1 - 7 files changed, 7 deletions(-) diff --git a/.travis.yml b/.travis.yml index c75221dca3..bd9a6fc06c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -192,7 +192,6 @@ jobs: apt: packages: - python3-sphinx - - texinfo - perl diff --git a/scripts/coverity-scan/coverity-scan.docker b/scripts/coverity-scan/coverity-scan.docker index 018c03de6d..501ac67233 100644 --- a/scripts/coverity-scan/coverity-scan.docker +++ b/scripts/coverity-scan/coverity-scan.docker @@ -110,7 +110,6 @@ ENV PACKAGES \ systemd-devel \ systemtap-sdt-devel \ tar \ - texinfo \ usbredir-devel \ virglrenderer-devel \ vte291-devel \ diff --git a/tests/docker/dockerfiles/debian10.docker b/tests/docker/dockerfiles/debian10.docker index e3c11a454e..1e4188ba22 100644 --- a/tests/docker/dockerfiles/debian10.docker +++ b/tests/docker/dockerfiles/debian10.docker @@ -31,7 +31,6 @@ RUN apt update && \ python3 \ python3-setuptools \ python3-sphinx \ - texinfo \ $(apt-get -s build-dep qemu | egrep ^Inst | fgrep '[all]' | cut -d\ -f2) ENV FEATURES docs diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfiles/fedora.docker index 70b6186bd3..71e4b56977 100644 --- a/tests/docker/dockerfiles/fedora.docker +++ b/tests/docker/dockerfiles/fedora.docker @@ -96,7 +96,6 @@ ENV PACKAGES \ tar \ tesseract \ tesseract-langpack-eng \ - texinfo \ usbredir-devel \ virglrenderer-devel \ vte291-devel \ diff --git a/tests/docker/dockerfiles/ubuntu.docker b/tests/docker/dockerfiles/ubuntu.docker index 161806e6b8..b556ed17d2 100644 --- a/tests/docker/dockerfiles/ubuntu.docker +++ b/tests/docker/dockerfiles/ubuntu.docker @@ -63,7 +63,6 @@ ENV PACKAGES \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get -y install $PACKAGES diff --git a/tests/docker/dockerfiles/ubuntu1804.docker b/tests/docker/dockerfiles/ubuntu1804.docker index a10ea2850b..a6a7617da6 100644 --- a/tests/docker/dockerfiles/ubuntu1804.docker +++ b/tests/docker/dockerfiles/ubuntu1804.docker @@ -49,7 +49,6 @@ ENV PACKAGES \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get -y install $PACKAGES diff --git a/tests/docker/dockerfiles/ubuntu2004.docker b/tests/docker/dockerfiles/ubuntu2004.docker index 8d10934a2a..cafe8443fb 100644 --- a/tests/docker/dockerfiles/ubuntu2004.docker +++ b/tests/docker/dockerfiles/ubuntu2004.docker @@ -57,7 +57,6 @@ ENV PACKAGES flex bison \ sparse \ tesseract-ocr \ tesseract-ocr-eng \ - texinfo \ xfslibs-dev\ vim RUN apt-get update && \