From patchwork Thu Feb 28 14:56:14 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833269 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id B54D11515 for ; Thu, 28 Feb 2019 14:57:54 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 9ED302F256 for ; Thu, 28 Feb 2019 14:57:54 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 908F92F262; Thu, 28 Feb 2019 14:57:54 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 84B9B2F256 for ; Thu, 28 Feb 2019 14:57:53 +0000 (UTC) Received: from localhost ([127.0.0.1]:39652 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN8C-0005T2-5X for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 09:57:52 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52077) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN6v-0004eO-B3 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:34 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN6u-0007cJ-GL for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:33 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:44144) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN6u-0007bZ-9m for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:32 -0500 Received: by mail-wr1-x444.google.com with SMTP id w2so22281370wrt.11 for ; Thu, 28 Feb 2019 06:56:32 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=cBBB1m8jF2jswHhto8zHv2dtBq3GoufsacwfRGofNO4=; b=f4gj6RTZWAfMCmgLuX/+B3AwGpG2Je5FptvnXDxV9fkjk6NSr8Ihju5f0zfNN6LGRo Ehbeijhuo9NwNAGZjwgDXEsU9L30MuKVu+uUnQ/2j51ESVuI0W/4t/Lw6gO+gZG+eftb ix29N/VOVGxvmgmjwBXAbZx/F5nGxGe71wlPctMLbCd4Gi0yicF7bA/2o4UcwgibGI+O DRueD7KflbNNTlDvJ1AVUJYVyEH/MQCmukzmVG4Aj4xUh82RZi+LhCWCDuLvrHcmkScI fCfTriGSaNK0HLF71jUJA8TD13RIwPUYiymkn8Sk+zc3tSQb+k8P9n/7Yt+m6YEChMdb QyBg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=cBBB1m8jF2jswHhto8zHv2dtBq3GoufsacwfRGofNO4=; b=Ylcd2LK/Grzsit4H52gnsGiCvmDAedHngtNXS1YbkduH0LbrDeq5ja0P4hHEIMWPd8 VQ9rB1Ma57pgJdOsYtavHxlOiXvxFyx8oQCUREzHyEuU3TEcp4jNZqqekRGGKFyvgIz7 +r3oPpvzfzxcodVxOx1T4U/eJX9zmhUZzu/CMkh4RUHbb3+eEmY4M7LazdyUjQOvzGiJ y/gk8QiwA/lYm4LMNGg+OWCc8LVeYwK4yUvFbAm4ZeNC+oQqQzSiLDSNuD/QlfXc1s8M Qn20oF1tIaJWh3ebja1mTabG1e4MXuwtuHXxGxohyaCWQ0ZnpkTQvqOjSUs49qARv5yr 5RUA== X-Gm-Message-State: APjAAAXAWC2v55QR7JzFWJ84LSkdRmRkFAZ2TJKSFgZRX86/PU8QxbVz jYbS6tOTOsZqW0bZNx7V/SlGo0VaU18= X-Google-Smtp-Source: APXvYqxnmfI4ncyolLYoafkjgcXB5vLuKQGaWjNKyV4q060Af1lFq8ec+zNe41SJWciQ8Y0XdTeCeA== X-Received: by 2002:a05:6000:128f:: with SMTP id f15mr6413418wrx.74.1551365791023; Thu, 28 Feb 2019 06:56:31 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.29 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:30 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:14 +0000 Message-Id: <20190228145624.24885-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 Subject: [Qemu-devel] [PATCH v2 01/11] docs/cpu-hotplug.rst: Fix rST markup issues X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP sphinx-build complains: docs/cpu-hotplug.rst:67: ERROR: Unexpected indentation. docs/cpu-hotplug.rst:69: ERROR: Unexpected indentation. docs/cpu-hotplug.rst:74: WARNING: Block quote ends without a blank line; unexpected unindent. docs/cpu-hotplug.rst:75: WARNING: Block quote ends without a blank line; unexpected unindent. docs/cpu-hotplug.rst:76: SEVERE: Unexpected section title. } { docs/cpu-hotplug.rst:78: WARNING: Block quote ends without a blank line; unexpected unindent. These are the result of not indicating one of the literal blocks by finishing the preceding paragraph with the "::" marker. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé Tested-by: Philippe Mathieu-Daudé --- docs/cpu-hotplug.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cpu-hotplug.rst b/docs/cpu-hotplug.rst index 1c268e00b41..e2d4e893b01 100644 --- a/docs/cpu-hotplug.rst +++ b/docs/cpu-hotplug.rst @@ -60,7 +60,7 @@ vCPU hotplug hot-plugged (no "qom-path" member). From its output in step (3), we can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0, while hot-plugging a CPU into socket 1 requires passing the listed - properties to QMP ``device_add``: + properties to QMP ``device_add``:: (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0 { From patchwork Thu Feb 28 14:56:15 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833301 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id A5A8415AC for ; Thu, 28 Feb 2019 15:03:04 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 95BD72F309 for ; Thu, 28 Feb 2019 15:03:04 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 879D12F317; Thu, 28 Feb 2019 15:03:04 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 9EA3B2F285 for ; Thu, 28 Feb 2019 15:03:03 +0000 (UTC) Received: from localhost ([127.0.0.1]:39714 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNDC-0008HX-GM for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:03:02 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52100) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN6y-0004gL-SN for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN6x-0007f0-C5 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:36 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:36254) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN6x-0007ef-2d for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:35 -0500 Received: by mail-wr1-x444.google.com with SMTP id o17so22327617wrw.3 for ; Thu, 28 Feb 2019 06:56:35 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=/9IkpHPeqNX7XO2NeX1pgd8XrKlLxy6/RDfGr7GVXPk=; b=ed4X5hjG9+c3hWhTSW543Z9g5SrQTXHokFbGX8ubATmvbKie9xqgpQ0cO2RZA/a5V2 EcQQBLXojEAifeORI1BfSpzn+4Gq2+nXSDJfxkIcQiFTYdQscCBt6U7Bi1v0UBlnoLLm i9GEhM1wW0VFwHmkM7Y/w0g5bo+rZaaYtHYXRGZfqj59s2zYOQekkpiyG0FFaFwEqmuk Kva7x54EgeePp0BxfjEmecR66i13uaE07vB3evuU35gnHpCCUilmgtrzsSWsNi09iyqg QKq3w94bcAX3ivCARiL0fdhd6JUof8J0MGgcu4FJsnGHFPnpvaMZgG+ES40DFrk8EJIU +EbA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=/9IkpHPeqNX7XO2NeX1pgd8XrKlLxy6/RDfGr7GVXPk=; b=QA5BR1EcRyycwg1F+wG4FSe1q1wOaM5VXylc+uAo1c+jJkGDWFrvtonlXCD2/MHHfD FqL47yhrdJSAdvspgnXXy5d6nFLe04xyMchXBtaWbLslHlUV5tmGc7EqtZhTKFvdszbm jarIyoy7ulZmzfWX6Pk63AC2WoZL8Kxm0BXjn0IH3bk6jnxEKEpFab0H0r0OdeCol4Ne Y2m1UnpbDIaVMw93OWUcYY+Z2h0gQTghRtjt1WnLZCZe9D6urHFO9Ya9zdZxdT3mDD9e 0p2Ky5+jOFZi/yiwsYS8FFi/482CgBYdVdzLW2EnBBwPIUv/c4TBiEUvNvsNqOR9o3Ih /6nw== X-Gm-Message-State: APjAAAX50nrNNW5FkUsHGeAybgljRFBaV5VLiTtIXZwbYR5Q42GggEY6 KEgYN+RDhnvz5QZxNRrm+/ms9zlFJtE= X-Google-Smtp-Source: APXvYqxzNz8BxI1BojF5125GN6DIkulEAptxrH6DyKSEpFJ9ZqpqIbU4LAVsOQqiZLWC0KKgblbpAQ== X-Received: by 2002:a5d:51cd:: with SMTP id n13mr6482804wrv.310.1551365793421; Thu, 28 Feb 2019 06:56:33 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.31 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:32 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:15 +0000 Message-Id: <20190228145624.24885-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 Subject: [Qemu-devel] [PATCH v2 02/11] docs: Convert memory.txt to rst format X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Convert the memory API documentation from plain text to restructured text format. This is a very minimal conversion: all I had to change was to mark up the ASCII art parts as Sphinx expects for 'literal blocks', and fix up the bulleted lists (Sphinx expects no leading space before the bullet, and wants a blank line before after any list). Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/devel/{memory.txt => memory.rst} | 128 ++++++++++++++------------ 1 file changed, 70 insertions(+), 58 deletions(-) rename docs/devel/{memory.txt => memory.rst} (85%) diff --git a/docs/devel/memory.txt b/docs/devel/memory.rst similarity index 85% rename from docs/devel/memory.txt rename to docs/devel/memory.rst index 42577e1d860..b6a4c37ea5e 100644 --- a/docs/devel/memory.txt +++ b/docs/devel/memory.rst @@ -1,19 +1,20 @@ +============== The memory API ============== The memory API models the memory and I/O buses and controllers of a QEMU machine. It attempts to allow modelling of: - - ordinary RAM - - memory-mapped I/O (MMIO) - - memory controllers that can dynamically reroute physical memory regions - to different destinations +- ordinary RAM +- memory-mapped I/O (MMIO) +- memory controllers that can dynamically reroute physical memory regions + to different destinations The memory model provides support for - - tracking RAM changes by the guest - - setting up coalesced memory for kvm - - setting up ioeventfd regions for kvm +- tracking RAM changes by the guest +- setting up coalesced memory for kvm +- setting up ioeventfd regions for kvm Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks (leaves) are RAM and MMIO regions, while other nodes represent @@ -98,25 +99,30 @@ ROM device memory region types), this host memory needs to be copied to the destination on migration. These APIs which allocate the host memory for you will also register the memory so it is migrated: - - memory_region_init_ram() - - memory_region_init_rom() - - memory_region_init_rom_device() + +- memory_region_init_ram() +- memory_region_init_rom() +- memory_region_init_rom_device() For most devices and boards this is the correct thing. If you have a special case where you need to manage the migration of the backing memory yourself, you can call the functions: - - memory_region_init_ram_nomigrate() - - memory_region_init_rom_nomigrate() - - memory_region_init_rom_device_nomigrate() + +- memory_region_init_ram_nomigrate() +- memory_region_init_rom_nomigrate() +- memory_region_init_rom_device_nomigrate() + which only initialize the MemoryRegion and leave handling migration to the caller. The functions: - - memory_region_init_resizeable_ram() - - memory_region_init_ram_from_file() - - memory_region_init_ram_from_fd() - - memory_region_init_ram_ptr() - - memory_region_init_ram_device_ptr() + +- memory_region_init_resizeable_ram() +- memory_region_init_ram_from_file() +- memory_region_init_ram_from_fd() +- memory_region_init_ram_ptr() +- memory_region_init_ram_device_ptr() + are for special cases only, and so they do not automatically register the backing memory for migration; the caller must manage migration if necessary. @@ -218,7 +224,7 @@ For example, suppose we have a container A of size 0x8000 with two subregions B and C. B is a container mapped at 0x2000, size 0x4000, priority 2; C is an MMIO region mapped at 0x0, size 0x6000, priority 1. B currently has two of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at -offset 0x2000. As a diagram: +offset 0x2000. As a diagram:: 0 1000 2000 3000 4000 5000 6000 7000 8000 |------|------|------|------|------|------|------|------| @@ -228,8 +234,9 @@ offset 0x2000. As a diagram: D: [DDDDD] E: [EEEEE] -The regions that will be seen within this address range then are: - [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] +The regions that will be seen within this address range then are:: + + [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] Since B has higher priority than C, its subregions appear in the flat map even where they overlap with C. In ranges where B has not mapped anything @@ -237,8 +244,9 @@ C's region appears. If B had provided its own MMIO operations (ie it was not a pure container) then these would be used for any addresses in its range not handled by -D or E, and the result would be: - [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] +D or E, and the result would be:: + + [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] Priority values are local to a container, because the priorities of two regions are only compared when they are both children of the same container. @@ -257,6 +265,7 @@ guest accesses an address: - all direct subregions of the root region are matched against the address, in descending priority order + - if the address lies outside the region offset/size, the subregion is discarded - if the subregion is a leaf (RAM or MMIO), the search terminates, returning @@ -270,36 +279,39 @@ guest accesses an address: address range), then if this is a container with its own MMIO or RAM backing the search terminates, returning the container itself. Otherwise we continue with the next subregion in priority order + - if none of the subregions match the address then the search terminates with no match found Example memory map ------------------ -system_memory: container@0-2^48-1 - | - +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) - | - +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) - | - +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) - | (prio 1) - | - +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) +:: -pci (0-2^32-1) - | - +--- vga-area: container@0xa0000-0xbffff - | | - | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) - | | - | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) - | - +---- vram: ram@0xe1000000-0xe1ffffff - | - +---- vga-mmio: mmio@0xe2000000-0xe200ffff + system_memory: container@0-2^48-1 + | + +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) + | + +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) + | + +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) + | (prio 1) + | + +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) -ram: ram@0x00000000-0xffffffff + pci (0-2^32-1) + | + +--- vga-area: container@0xa0000-0xbffff + | | + | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) + | | + | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) + | + +---- vram: ram@0xe1000000-0xe1ffffff + | + +---- vga-mmio: mmio@0xe2000000-0xe200ffff + + ram: ram@0x00000000-0xffffffff This is a (simplified) PC memory map. The 4GB RAM block is mapped into the system address space via two aliases: "lomem" is a 1:1 mapping of the first @@ -336,16 +348,16 @@ rather than completing successfully; those devices can use the In addition various constraints can be supplied to control how these callbacks are called: - - .valid.min_access_size, .valid.max_access_size define the access sizes - (in bytes) which the device accepts; accesses outside this range will - have device and bus specific behaviour (ignored, or machine check) - - .valid.unaligned specifies that the *device being modelled* supports - unaligned accesses; if false, unaligned accesses will invoke the - appropriate bus or CPU specific behaviour. - - .impl.min_access_size, .impl.max_access_size define the access sizes - (in bytes) supported by the *implementation*; other access sizes will be - emulated using the ones available. For example a 4-byte write will be - emulated using four 1-byte writes, if .impl.max_access_size = 1. - - .impl.unaligned specifies that the *implementation* supports unaligned - accesses; if false, unaligned accesses will be emulated by two aligned - accesses. +- .valid.min_access_size, .valid.max_access_size define the access sizes + (in bytes) which the device accepts; accesses outside this range will + have device and bus specific behaviour (ignored, or machine check) +- .valid.unaligned specifies that the *device being modelled* supports + unaligned accesses; if false, unaligned accesses will invoke the + appropriate bus or CPU specific behaviour. +- .impl.min_access_size, .impl.max_access_size define the access sizes + (in bytes) supported by the *implementation*; other access sizes will be + emulated using the ones available. For example a 4-byte write will be + emulated using four 1-byte writes, if .impl.max_access_size = 1. +- .impl.unaligned specifies that the *implementation* supports unaligned + accesses; if false, unaligned accesses will be emulated by two aligned + accesses. From patchwork Thu Feb 28 14:56:16 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833273 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 83C471399 for ; Thu, 28 Feb 2019 14:59:03 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 690542AD15 for ; Thu, 28 Feb 2019 14:59:03 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 57EFF2CED6; Thu, 28 Feb 2019 14:59:03 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id A3E7B2CEB2 for ; Thu, 28 Feb 2019 14:59:02 +0000 (UTC) Received: from localhost ([127.0.0.1]:39656 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN9J-0006Fx-Tm for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 09:59:01 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52124) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN72-0004h2-0Y for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN70-0007gT-Kr for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:39 -0500 Received: from mail-wm1-x334.google.com ([2a00:1450:4864:20::334]:37815) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN70-0007g5-E7 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:38 -0500 Received: by mail-wm1-x334.google.com with SMTP id x10so9165459wmg.2 for ; Thu, 28 Feb 2019 06:56:38 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Rxr+pcO3DH+RyP3UrU1eG90LOTPrTLiWh8dZgCu/hhA=; b=vVk4ubpCtdX2upkiLC8Ar8ebTw3nrhy9j1vPrXoChUCknRN0qmCn9PK+Z6ZyfNVmKn UTuwMGwhuLXp0HQc53hAvGHEhauvOuowAoGib+ThHPLenQ8me0Fwbxdg71hPmjm4qU8x CV6GjzeED4gwfO13d1tqdfz++IQn51PwVKhhJrDevenJpVAFqUXJ/j8/ZTQ4pT0/nPiT vakV4v778ouv8KsPSQUpTwBvSWXHgx67jOIY9ttMFpg1XxYiVvkS51dXv3y9k80UCNR5 59fdEu2m1vGXjh9r65YVs7kBEoMmwdImFZvLEUoJwNYtKtmNbpJ3LkHF0aXUpl3xF23c TvJg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Rxr+pcO3DH+RyP3UrU1eG90LOTPrTLiWh8dZgCu/hhA=; b=uGmb8fJFpULMwysWioyK0cDX4rUHGCEzPXUxyFCLwQ9/nI8CuxAp0NWPTMpSUYBMLX exkM5FcRq4QTzlz8JQgk5rxGd/WJsP5/tvv3MtoTTi1Xz9EAtj0/XAX3zuxGQBrCE7/z HJGUIO5pt1kJ/TrFQXEZ365c95JQ8XZWI/tmKBr9r7Oe8N+IACoVsuiHT1lPDF/29P9q TZ04KfP6aQKR967LvLighwX+C5yBMlDMc7S/j+LzClSHckFyHAprk7krmxsrLXS9uZpX MotN8bxjPfRwra1RWPFuruID7yEPmKJlhw/AaR3qCApo1180Q3XNO0w8dUXav8oa8Wax XGCg== X-Gm-Message-State: APjAAAWi4P8l55gm3BU9/VAYGr+g97luO6xx4P35VofGfhjnf+ziTpFB dAMenPtl+C+QRTIsJ4Bwl5rnOV4KFPA= X-Google-Smtp-Source: APXvYqy/upr2rtjwglFkwkPG+TpSFHkwLq+Lc34bPGtOqkOeXVL4742wTrjDuRevtx/x05vtOyil1A== X-Received: by 2002:a1c:9c0e:: with SMTP id f14mr82479wme.78.1551365796870; Thu, 28 Feb 2019 06:56:36 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.33 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:36 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:16 +0000 Message-Id: <20190228145624.24885-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::334 Subject: [Qemu-devel] [PATCH v2 03/11] docs: Commit initial files from sphinx-quickstart X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Commit the initial Sphinx conf.py and skeleton index.rst as generated with sphinx-quickstart. We'll update these to add QEMU-specific tweaks in subsequent commits. Signed-off-by: Peter Maydell --- docs/conf.py | 168 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 20 ++++++ 2 files changed, 188 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000000..53a17506615 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,168 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file, created by +# sphinx-quickstart on Thu Jan 31 16:40:14 2019. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'QEMU' +copyright = u'2019, The QEMU Project Developers' +author = u'The QEMU Project Developers' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'4.0' +# The full version, including alpha/beta/rc tags. +release = u'4.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'QEMUdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'QEMU.tex', u'QEMU Documentation', + u'The QEMU Project Developers', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'qemu', u'QEMU Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'QEMU', u'QEMU Documentation', + author, 'QEMU', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000000..93f82228310 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. QEMU documentation master file, created by + sphinx-quickstart on Thu Jan 31 16:40:14 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to QEMU's documentation! +================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` From patchwork Thu Feb 28 14:56:17 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833271 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 166071399 for ; Thu, 28 Feb 2019 14:58:00 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 072562F256 for ; Thu, 28 Feb 2019 14:58:00 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id EF2292F262; Thu, 28 Feb 2019 14:57:59 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id A048D2F256 for ; Thu, 28 Feb 2019 14:57:59 +0000 (UTC) Received: from localhost ([127.0.0.1]:39654 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN8I-0005YP-T4 for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 09:57:58 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52133) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN72-0004h4-Ph for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN71-0007hN-UX for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:40 -0500 Received: from mail-wm1-x334.google.com ([2a00:1450:4864:20::334]:34534) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN71-0007gs-OA for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:39 -0500 Received: by mail-wm1-x334.google.com with SMTP id o10so6796310wmc.1 for ; Thu, 28 Feb 2019 06:56:39 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=0WIIPoRmlkIfnoJX3kVoDiy4fDpIeOZPt381EvlF+D0=; b=CeDnkDZtJe2pj3vSfir87vnpgZ70SN2l3A4gAWHrqFH2bzsixW+Qd3R/I0mdAnEli/ 53t/v6Zy5guub+MiGsycVRfclU1o5H46jowqwtyIzxP6NHEf7Nze0O6x15onGNnRYcEy yyXFtQvIAqCAumS3LxZd8/vCMK7Rx0gc8I/RKKcX021sJuZixn9ibn0M07MwIKFFPMsH tra4MbY/GLQ+yGFdASLAPD9GJMiDxItkSUfZ8jG+PVS8+bSgqW/5+veAgMiEVqvW1JcS SVD/vypiWENBhyYrq8iX2CalVHInNk5IIMdyWaw8pr0h+FVIMMLP1kuB733LtyL/xiUT y8Ug== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=0WIIPoRmlkIfnoJX3kVoDiy4fDpIeOZPt381EvlF+D0=; b=AWl3vZYN0ffa6eLJ0zQFvZ2E83ZYdlH00n+To5K3il891d3qijQ+IBZ0/ta0LbE4LD NR+TUQeeC3XCOV7pr02RFBUBFK5km14PvrTwfZACVk1Di5Z1qu1Zgy7kIANrKk3Qb+rM sMyLEANt9s8tfiKZPMlVre+pfGqnuC3H8lrcj2dsTdTHLdWq5Y6I+CAgEHvD1EKlhPrr QP2tVscDqVfLOcN5kF3REJjEC8F8spWIYEm3K40YTdC9m/mtqfNft3ejFdWw4reS5C0C ll6bkQwDT3laz28X0n0RGeamR4SF7wlNGkeKvpNFjZnGTxAeLo98nOZvsPfSzhImI9Uo w1LA== X-Gm-Message-State: AHQUAubiI8hK9QJ3+vBYcIl/IUUA9lvC24Bm8Vbrs8Yanry+j2DJmdEg 8zxMuEl7E3fu8ZYQ7jkf9srPJNigL9s= X-Google-Smtp-Source: APXvYqyMCM5qWpC1LRVRuZBWIBjPK7Q/hmoncIpJpzzl/3zQ3NJj2Lj3vCxIM0F8w64YCh3IRk2T8w== X-Received: by 2002:a1c:cc0c:: with SMTP id h12mr72647wmb.140.1551365798502; Thu, 28 Feb 2019 06:56:38 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.36 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:37 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:17 +0000 Message-Id: <20190228145624.24885-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::334 Subject: [Qemu-devel] [PATCH v2 04/11] docs/conf.py: Disable unused _static directory X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP We don't yet have any custom static files, so disable this config file setting to avoid a warning from sphinx about not being able to find the directory. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 53a17506615..e1d08a34a65 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,7 +93,11 @@ html_theme = 'alabaster' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +# QEMU doesn't yet have any static files, so comment this out so we don't +# get a warning about a missing directory. +# If we do ever add this then it would probably be better to call the +# subdirectory sphinx_static, as the Linux kernel does. +# html_static_path = ['_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. From patchwork Thu Feb 28 14:56:18 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833293 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 84CF01515 for ; Thu, 28 Feb 2019 15:01:33 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 73CD02F27C for ; Thu, 28 Feb 2019 15:01:32 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 701ED2F2EE; Thu, 28 Feb 2019 15:01:32 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 103212F23D for ; Thu, 28 Feb 2019 15:01:31 +0000 (UTC) Received: from localhost ([127.0.0.1]:39698 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNBj-0007GH-9q for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:01:31 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52165) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN76-0004hZ-2K for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN75-0007jM-6e for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:43 -0500 Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:44018) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN75-0007ij-05 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:43 -0500 Received: by mail-wr1-x42c.google.com with SMTP id d17so22255748wre.10 for ; Thu, 28 Feb 2019 06:56:42 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=6brYIWUE9IUiegxSjMz1IVVQX/amHvDgPltcC6gxlvM=; b=VNmFw3D1DiaXPERcKmDXcDBNaQ8P+2BV7TgRiMMlRP4U4lWa1NXjvpcpTF7SVWOdxC 7L8tc/KRCOUPK3AiqQ36utKX083Em4OJfq/ImHMvCD+U1DDCS4l49dAX6znb6zqIA1FS azEAt29TvJ/j2fPqnWLrybiAG2uCI+F8UnXN7U5lbkfFkeuY6QcdzyeBbL6gpmNd/1Zm ZiXRWqssAh9pQL7bN7/07tIBm/1ar92EMmoQk6ic1ZNDgcrLwAAMQA5BbYogmRfJa/X/ vebnw+GfNo15TzjYmNyvoRSMEp3/JQOr42OQlFwsPT3iVg95hL9wA8JSb8wuptW9cX2i hqjQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=6brYIWUE9IUiegxSjMz1IVVQX/amHvDgPltcC6gxlvM=; b=B2b1JvU9pSU91TrGf+9g3/u/w8RkbsXlLK+pM0/cH+Ox8XLs1Gxk24QLysz0ly3GQv ylq8nmzjgqhqLBPC37PVE6+6fi3KYpXwbcWvq/TH4mKIjy5cVh2wIJ1UDuah1WlEiUmc 370S98ZLKVeyDTFAk08EzOaOKzKJYiyA0BpfIpOVXg7DNQ+Et3eBSHlbBv0X6rxSwUe9 nDlPf7mkYR6g1wrCqDX/vQ1ZQfnGNu/ZRwA7jrb7fT9lc9D5/W5kfgekhrf8qU0pes8K wWDS0MgmVJlPIA8Rgi2zTBUtXBalN8m+SNfRMxqohwvpucr6IKg5RqASIFfwIpajyPxY a3jw== X-Gm-Message-State: APjAAAVLnQB1E5HTDEDYg9TveKRNm1Ok/9JizyzCAkC8CqNHxNEukXEb jcXDIIsyXIX/N/ZEDbOD6BioL8xEcuA= X-Google-Smtp-Source: APXvYqx6wFN5l3jW9RtuxYNxisfH6tLcJZBK5jbBRz5A7vIHQU90nuBTDw408XrB0K9+PerGiPLrzA== X-Received: by 2002:a5d:6810:: with SMTP id w16mr6528695wru.62.1551365801694; Thu, 28 Feb 2019 06:56:41 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:41 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:18 +0000 Message-Id: <20190228145624.24885-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42c Subject: [Qemu-devel] [PATCH v2 05/11] docs/conf.py: Configure the 'alabaster' theme X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Add the 'navigation' bar to the sidebar, which for some reason is not enabled by default. Remove 'relations', which is effectively disabled anyway and isn't useful for us. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index e1d08a34a65..348e6358740 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -106,7 +106,8 @@ html_theme = 'alabaster' # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars html_sidebars = { '**': [ - 'relations.html', # needs 'show_related': True theme option to display + 'about.html', + 'navigation.html', 'searchbox.html', ] } From patchwork Thu Feb 28 14:56:19 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833281 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id E8B3615AC for ; Thu, 28 Feb 2019 15:00:26 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id DA5882F24F for ; Thu, 28 Feb 2019 15:00:26 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id D876E2F265; Thu, 28 Feb 2019 15:00:26 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 859D62F256 for ; Thu, 28 Feb 2019 15:00:26 +0000 (UTC) Received: from localhost ([127.0.0.1]:39702 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNAf-0007OR-R5 for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:00:25 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52204) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7O-0004rz-Ga for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:03 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7C-0007qY-5d for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:54 -0500 Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]:44820) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN78-0007mx-Ef for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:46 -0500 Received: by mail-wr1-x433.google.com with SMTP id w2so22282359wrt.11 for ; Thu, 28 Feb 2019 06:56:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=fi6Lnp2ghamUUaG99hmuDpt41B0Seow/lJ3VHwLhnoo=; b=luKd0NcatLIN9lk0xwsTh3t2ii0zaDzytPHt9ALGSiVrsVkYKavlpuNzaIUMStAtR1 vZ/FpCq15XrLJ5Jsr6nvmaWPZfZUMtImP375JJoLQ39akZCdd7pbr4/qGygKSacs/0vF 4snUo92y3I6nFRgsfG3f1TnyYCfA5jN4Q9yOauIDPeAnwDu8VYeXcYgWR/2LQqpL961E sGGdvfw0pk7l+vQ6nuO04/Ldbytgy5/P7Hu5bQslyHxCxXGkf4xEJNQ1gK+ql6uCjPt7 /JtHMocV7IN8yK4dmhWT4Mqo+o4cSnp0Ahr/SpZBJr9YTdh1BUb2Wl7+93bohY6nZ/0+ GjUw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=fi6Lnp2ghamUUaG99hmuDpt41B0Seow/lJ3VHwLhnoo=; b=HrNBvolh5vr9/5enOOODJc2lEspC13Ivid3I737YUL2/5kmd2mG8zVAGN6TJg5eDYT wHd0F2nrVLQPT/gBS/lu0idV5K9/UpAyFNeWTRKuEwHYviQA3TsIoYCVEcd6Bh1o9fNU 7GiFkHG5qWVeRd1bbrqdESwSDJZ6LbzeRpRjTyz2ZzPv3Bf3lNlcsk3RGjmz6oTKbb3k iYCL6cjJd2XPVz7IpXwrfKHOE+ZjYNWZDPkuwX72ueNw3PtHfbLau+Rydu/bvRt91R+q 2ggAQJNOaPh9ewAm17+EiVFAW7lcISgDXhiYFmmaz8hiPzZrEVdyXO/f5uA3wFhwDvXm WJCg== X-Gm-Message-State: APjAAAVglQU3lToF7n0s/8KD8B+8qM7TfMcz5SZ7003hjTDPHP3lanpD dGowAvyMGwnd881DnL2gfBuOivYz8eM= X-Google-Smtp-Source: APXvYqzI6cMFGNsddvRzBLVuYI14Ljr/6thgJ1ecFSgOoQmn2kHjfmPmaKE2a463TzmhO1LeT/dJsQ== X-Received: by 2002:adf:c593:: with SMTP id m19mr6537948wrg.124.1551365805224; Thu, 28 Feb 2019 06:56:45 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.42 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:43 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:19 +0000 Message-Id: <20190228145624.24885-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::433 Subject: [Qemu-devel] [PATCH v2 06/11] docs/conf.py: Don't include rST sources in HTML build X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Sphinx defaults to including all the rST source files in the HTML build and making each HTML page link to the source file. Disable that. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 348e6358740..6ddaa549f28 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -112,6 +112,9 @@ html_sidebars = { ] } +# Don't copy the rST source files to the HTML output directory, +# and don't put links to the sources into the output HTML. +html_copy_source = False # -- Options for HTMLHelp output ------------------------------------------ From patchwork Thu Feb 28 14:56:20 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833303 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 67B0715AC for ; Thu, 28 Feb 2019 15:03:14 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 560232F235 for ; Thu, 28 Feb 2019 15:03:14 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 541542F33D; Thu, 28 Feb 2019 15:03:14 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id E54AC2F336 for ; Thu, 28 Feb 2019 15:03:13 +0000 (UTC) Received: from localhost ([127.0.0.1]:39728 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNDN-0000pd-5n for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:03:13 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52216) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7S-0004vI-D7 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:12 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7J-0007tS-DS for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:00 -0500 Received: from mail-wr1-x434.google.com ([2a00:1450:4864:20::434]:36191) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN7C-0007nh-FA for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:56:50 -0500 Received: by mail-wr1-x434.google.com with SMTP id o17so22328504wrw.3 for ; Thu, 28 Feb 2019 06:56:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Xz9rcfgVQuJnJoFG+Avx8+y87er9JZ52Zhelu60TAAY=; b=m+GeMQ7nfuFNEUTuZLdCxmZK4yHRM7p3x1pnaS6Es4wkL5fDf04kCX51gyvTCxws6Q mgdKkc7XxDqYKOdNqDH7P/oZrVO5yZDGRbuD4Acl0ffE6GDXI1Bm6rbDDaRAnU8Y6ULd UPI0D836OwBE6QcvP4goWQZjGGDSjI+kCaDFGgHnOb6DJABKZGe1FsTd/ZzEvxbpUmLM p2E9BZbMsxquGW9nL+aoevLrs6QmH51dLCW7tyoFNsapvFhSMlbMZ7S4HZX4nFKaB84W 6rkfCd9zbzl0mKD3+Qz9v3X9r2G0yPYXo3WmW7zLyj5u2qTNzrErfa3Ne8fwCiGYtSun OKWA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Xz9rcfgVQuJnJoFG+Avx8+y87er9JZ52Zhelu60TAAY=; b=k6Bbl3XSlNPWws/lyJCpas2YLc+kA3dRy20BB18oQU1JBV/G/A1guYBnZbqx0zUiAB DT40dyMSLYDoFCD56xdlWjRHZl/wP9BGcImB9ZDfXBmGdSlLs3pOKdzrVeBiR1+h3YDI xRBvGFuxww+QEB1C5E69uLqpo41AM/w4wNl6q9gwW5E1YPa1RiLBA46pQtCGxk7N487t 3hEU5EIDVHxYd85mgvsDgesWnJFMIev3l1I52SkW7de4IB64Z4zicwPITC+FUKtOloIg OxVtaN8Jtu7vj5iRFUB9JDvpj0J9WL6d542rqV0q773R/bJU4nf4UiexteN0Kst2p5Ob WRIw== X-Gm-Message-State: APjAAAWj5AjbmssSiMHXWlHQ7LhGDf2eJY80lGpdjkNS8dKuq7WIbV2J jqLOSRTWx9gfTPLFfe7af3x19F+TFDM= X-Google-Smtp-Source: APXvYqwal8NzVkHie45IORUEjbG1u8iuaKaWQrZqQhwL7/IVevs6Uh0pvOBoItrjFh1JztjZT5c9Ig== X-Received: by 2002:adf:f688:: with SMTP id v8mr6409914wrp.159.1551365806631; Thu, 28 Feb 2019 06:56:46 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.45 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:45 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:20 +0000 Message-Id: <20190228145624.24885-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::434 Subject: [Qemu-devel] [PATCH v2 07/11] docs/conf.py: Disable option warnings X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP sphinx-build complains about using :option: to mark up option flags that it doesn't know about (because they were not defined using the "option::" directive): docs/pr-manager.rst:68: WARNING: unknown option: -d Suppress these warnings. This way we get the semantic markup of the option flag but no cross-referencing hyperlink. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 6ddaa549f28..c04000e78e4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -76,6 +76,9 @@ pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False +# Sphinx defaults to warning about use of :option: for options not defined +# with "option::" in the document being processed. Turn that off. +suppress_warnings = ["ref.option"] # -- Options for HTML output ---------------------------------------------- From patchwork Thu Feb 28 14:56:21 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833305 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9C4D415AC for ; Thu, 28 Feb 2019 15:05:38 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 80ACF2EF0B for ; Thu, 28 Feb 2019 15:05:38 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 74D282EF12; Thu, 28 Feb 2019 15:05:38 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id A91322EF0B for ; Thu, 28 Feb 2019 15:05:37 +0000 (UTC) Received: from localhost ([127.0.0.1]:39734 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNFg-0001Pe-Q5 for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:05:36 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52238) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7V-0004y0-NR for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7T-0008Aa-N9 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:09 -0500 Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:38144) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN7M-0007qt-EX for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:04 -0500 Received: by mail-wr1-x42c.google.com with SMTP id g12so10229540wrm.5 for ; Thu, 28 Feb 2019 06:56:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=hcu4m0pryKTkWtamgwIRGgnhlBgoakr1uvVzDHoQjSI=; b=s33Kqupm98RJkfcTl/Yo/bEM4H11WgLWZMsGZ7LzToSB9Wzwqw77gWPVybk7qZvFg7 RCuGTcbSfl4LkvKds0uEHT9Jq1ym4f7NFQVOU30xhQkcMpob19rPfvK3hs4hHibRZzwS gqnknXeszVjuUdB20pu++i9YuYdxKpF8l8tavsEdcjBkTJLoVPIff/4jGi2nDwEU3+ux zel/n7a6UFLitLPwWa6cZANyxmXSsDUEk+vKDG+DJoV5FG6FYrXxFsZ91JS/5ylyqLPv uogUBhk4iARJWS9QDDjbdu/z8EarbZRJjxWl+ZlD9jSzqagc0iMRTeEY/l5yZSpb2z+/ LtYA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=hcu4m0pryKTkWtamgwIRGgnhlBgoakr1uvVzDHoQjSI=; b=kA+C9IOXyWFj+UMTSnnvBuxyG8ZHplQzhkqehcLCDfYm7RY1gTuZw02VTD0m17MmXK yFjSDh3pAt7xZETJOmLoGPkMtL06++RJdrl/W6SAfsbgDckzVZmVIa5Xl0toyJTfDK2S MWBdU7TfaM8L2n6NZ8FDnkqj4Az+S4592Rva7FIuxez+Vv2GHDv7+JmMJmpcdR3wE0/+ ad8DysCmx8nfczmv4oplh+hBLI6t2sC8VLEWHaaZNJPQteSF2gS+vOY9y8c8HA+hiUW4 FRGBwwiLi28kHKIBO+N/+K4IDpk29kKearPHv+u+aLZDREU3oWO7/+LMVacXpMCfhjpj d8MA== X-Gm-Message-State: APjAAAXzyyoFVVZ1fuFnui7SzsJQhYF6saHpzh3oJ76cuVketKAHwnau nGIwlHN1cpUIO2TjwvecaeyCWzo6guA= X-Google-Smtp-Source: APXvYqxlJ1Muq2noMq3m7bds1lopnpHtjD4QhJ2TdUNwgJCl3Pryo22s+kg617o3kJd5EuXd9La1FA== X-Received: by 2002:adf:ec10:: with SMTP id x16mr6742648wrn.171.1551365809871; Thu, 28 Feb 2019 06:56:49 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.46 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:49 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:21 +0000 Message-Id: <20190228145624.24885-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42c Subject: [Qemu-devel] [PATCH v2 08/11] docs: Provide separate conf.py for each manual we want X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP By default Sphinx wants to build a single manual at once. For QEMU, this doesn't suit us, because we want to have separate manuals for "Developer's Guide", "User Manual", and so on, and we don't want to ship the Developer's Guide to end-users. However, we don't want to completely duplicate conf.py for each manual, and we'd like to continue to support "build all docs in one run" for third-party sites like readthedocs.org. Make the top-level conf.py support two usage forms: (1) as a common config file which is included by the conf.py for each of QEMU's manuals: in this case sphinx-build is run multiple times, once per subdirectory. (2) as a top level conf file which will result in building all the manuals into a single document: in this case sphinx-build is run once, on the top-level docs directory. Provide per-manual conf.py files and top level pages for our first two manuals: * QEMU Developer's Guide (docs/devel) * QEMU System Emulation Management and Interoperability Guide (docs/interop) Reviewed-by: Alex Bennée Signed-off-by: Peter Maydell --- docs/conf.py | 37 +++++++++++++++++++++++++++++++------ docs/devel/conf.py | 15 +++++++++++++++ docs/devel/index.rst | 21 +++++++++++++++++++++ docs/index.rst | 9 ++------- docs/interop/conf.py | 15 +++++++++++++++ docs/interop/index.rst | 18 ++++++++++++++++++ 6 files changed, 102 insertions(+), 13 deletions(-) create mode 100644 docs/devel/conf.py create mode 100644 docs/devel/index.rst create mode 100644 docs/interop/conf.py create mode 100644 docs/interop/index.rst diff --git a/docs/conf.py b/docs/conf.py index c04000e78e4..6a334f545ec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,6 +3,20 @@ # QEMU documentation build configuration file, created by # sphinx-quickstart on Thu Jan 31 16:40:14 2019. # +# This config file can be used in one of two ways: +# (1) as a common config file which is included by the conf.py +# for each of QEMU's manuals: in this case sphinx-build is run multiple +# times, once per subdirectory. +# (2) as a top level conf file which will result in building all +# the manuals into a single document: in this case sphinx-build is +# run once, on the top-level docs directory. +# +# QEMU's makefiles take option (1), which allows us to install +# only the ones the user cares about (in particular we don't want +# to ship the 'devel' manual to end-users). +# Third-party sites such as readthedocs.org will take option (2). +# +# # This file is execfile()d with the current directory set to its # containing dir. # @@ -12,13 +26,22 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import os +import sys + +# The per-manual conf.py will set qemu_docdir for a single-manual build; +# otherwise set it here if this is an entire-manual-set build. +# This is always the absolute path of the docs/ directory in the source tree. +try: + qemu_docdir +except NameError: + qemu_docdir = os.path.abspath(".") + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. +# documentation root, use an absolute path starting from qemu_docdir. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir")) # -- General configuration ------------------------------------------------ @@ -90,8 +113,10 @@ html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# -# html_theme_options = {} +# We initialize this to empty here, so the per-manual conf.py can just +# add individual key/value entries. +html_theme_options = { +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/devel/conf.py b/docs/devel/conf.py new file mode 100644 index 00000000000..7441f87e7f5 --- /dev/null +++ b/docs/devel/conf.py @@ -0,0 +1,15 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file for the 'devel' manual. +# +# This includes the top level conf file and then makes any necessary tweaks. +import sys +import os + +qemu_docdir = os.path.abspath("..") +parent_config = os.path.join(qemu_docdir, "conf.py") +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) + +# This slightly misuses the 'description', but is the best way to get +# the manual title to appear in the sidebar. +html_theme_options['description'] = u'Developer''s Guide' diff --git a/docs/devel/index.rst b/docs/devel/index.rst new file mode 100644 index 00000000000..cd0fa6c9ba2 --- /dev/null +++ b/docs/devel/index.rst @@ -0,0 +1,21 @@ +.. This is the top level page for the 'devel' manual. + + +QEMU Developer's Guide +====================== + +This manual documents various parts of the internals of QEMU. +You only need to read it if you are interested in reading or +modifying QEMU's source code. + +Contents: + +.. toctree:: + :maxdepth: 2 + + loads-stores + memory + migration + stable-process + testing + diff --git a/docs/index.rst b/docs/index.rst index 93f82228310..3690955dd1f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,11 +10,6 @@ Welcome to QEMU's documentation! :maxdepth: 2 :caption: Contents: + interop/index + devel/index - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/interop/conf.py b/docs/interop/conf.py new file mode 100644 index 00000000000..cf3c69d4a7e --- /dev/null +++ b/docs/interop/conf.py @@ -0,0 +1,15 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file for the 'interop' manual. +# +# This includes the top level conf file and then makes any necessary tweaks. +import sys +import os + +qemu_docdir = os.path.abspath("..") +parent_config = os.path.join(qemu_docdir, "conf.py") +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) + +# This slightly misuses the 'description', but is the best way to get +# the manual title to appear in the sidebar. +html_theme_options['description'] = u'System Emulation Management and Interoperability Guide' diff --git a/docs/interop/index.rst b/docs/interop/index.rst new file mode 100644 index 00000000000..2df977dd529 --- /dev/null +++ b/docs/interop/index.rst @@ -0,0 +1,18 @@ +.. This is the top level page for the 'interop' manual. + + +QEMU System Emulation Management and Interoperability Guide +=========================================================== + +This manual contains documents and specifications that are useful +for making QEMU interoperate with other software. + +Contents: + +.. toctree:: + :maxdepth: 2 + + bitmaps + live-block-operations + pr-helper + From patchwork Thu Feb 28 14:56:22 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833323 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D2A4F1880 for ; Thu, 28 Feb 2019 15:11:54 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id C0F4C2F29A for ; Thu, 28 Feb 2019 15:11:54 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id BF7672F2CD; Thu, 28 Feb 2019 15:11:54 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 165A22F2D5 for ; Thu, 28 Feb 2019 15:11:53 +0000 (UTC) Received: from localhost ([127.0.0.1]:39879 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNLl-0006w6-5s for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:11:53 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52290) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7Z-000512-4h for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7X-0008Ct-Op for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:13 -0500 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:52943) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN7V-0007sE-Nk for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:11 -0500 Received: by mail-wm1-x344.google.com with SMTP id m1so9574099wml.2 for ; Thu, 28 Feb 2019 06:56:54 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=JizI2snDTt/q5TvanQhB9H8Wp5MTg1y47uEtiAt+lJM=; b=PKe1I1jEDB1BMGBAjhCOdjdwOCi0gZz4IhfdSRBxpU+XtbP60WkdZ/eJ/Lt1gScp/A POzx2x4XW7xI4S9bMkw+K+JhT7i3C8LBok/DRXeo6J8GiaUeMsHkg+8tfWTHa+dB9Xx1 SVm6wz8fGaU2vHLbCyYOv+2TADrrCS2LoEgOb5P9QXUUUrUYPInB6ZLc1ddFFEiRxPJ7 AXGxbpt/IkxOcHZWHj23cS11LohZqZeydjM0pvBAYklia7n7OE2iyhcwBMD9PenZuMWi Ho4oHAsPDNPeumCWt/jUpn3HFW/NSGV8uxb+28Zoo5sIwORhs7qrlEqMhjuhkNEl5okO hyQQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=JizI2snDTt/q5TvanQhB9H8Wp5MTg1y47uEtiAt+lJM=; b=PiiDatsABqV/AixHs/aINYyihBKEz5l5ombUqflLMa/Qea0+Q2pjxb1mZy6MIBTFQF JJ1VNGKQKlReUCRqFdRE0c5/8XB98BuktZkePnZ3MjGjJFeW8WLg7NXrfxRJGmoE3ld1 lUnXM1qdow/cP7OkndqTYzff9CZo86k5GK5LOSOk98n9z/716dAdJUh+J5vI+88ypY4W RaxbrkMKtCVacvokA2sP7QuDcSPAyAl6v+rnRnBhC4Kx8PQcxg1V5dn2vA5Pxt/BQljH 1BRAfVrsM5Dj9HkwDccJHsFO1U0wIgl27uKlK91Cm5wTVTSC7alKsIKGmo0g0Mh7sn/c lqBA== X-Gm-Message-State: APjAAAWchR2EtySGBy7/S1Iki59Lik6huaS24VVq8PV+1uvCXUXAqpjk V34JX5q0MtiRKVRiJMaEKZ6rZ389/+Q= X-Google-Smtp-Source: AHgI3IYI8PRzUlW55m8qJjGFojN3xlh+KSl6tsRart6igCkkA7DXG2skVCvGtIuciLniBcTU7t4l1w== X-Received: by 2002:a7b:c929:: with SMTP id h9mr73011wml.106.1551365813667; Thu, 28 Feb 2019 06:56:53 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.50 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:52 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:22 +0000 Message-Id: <20190228145624.24885-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::344 Subject: [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Add support to our configure and makefile machinery for building our rST docs into HTML files. Building the documentation now requires that sphinx-build is available; this seems better than allowing half the docs to be built if it is not present but having half of them missing. (In particular it means that assuming that distros configured with --enable-docs they'll get a helpful error from configure telling them the new build dependency.) Signed-off-by: Peter Maydell Reviewed-by: Philippe Mathieu-Daudé Tested-by: Philippe Mathieu-Daudé --- configure | 4 ++-- Makefile | 45 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 44 insertions(+), 5 deletions(-) diff --git a/configure b/configure index 694088a4ec9..bf6850d4bd9 100755 --- a/configure +++ b/configure @@ -4565,11 +4565,11 @@ fi # Check if tools are available to build documentation. if test "$docs" != "no" ; then - if has makeinfo && has pod2man; then + if has makeinfo && has pod2man && has sphinx-build; then docs=yes else if test "$docs" = "yes" ; then - feature_not_found "docs" "Install texinfo and Perl/perl-podlators" + feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx" fi docs=no fi diff --git a/Makefile b/Makefile index 7fa04e08212..d6b897be0bc 100644 --- a/Makefile +++ b/Makefile @@ -388,7 +388,7 @@ dummy := $(call unnest-vars,, \ include $(SRC_PATH)/tests/Makefile.include -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules +all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules qemu-version.h: FORCE $(call quiet-command, \ @@ -633,6 +633,14 @@ dist: qemu-$(VERSION).tar.bz2 qemu-%.tar.bz2: $(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)" +# Note that these commands assume that there are no HTML files in +# the docs subdir in the source tree! If there are then this will +# blow them away for an in-source-tree 'make clean'. +define clean-manual = +rm -rf docs/$1/_static +rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html +endef + distclean: clean rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi rm -f config-all-devices.mak config-all-disas.mak config.status @@ -653,6 +661,9 @@ distclean: clean rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html rm -f docs/qemu-block-drivers.7 rm -f docs/qemu-cpu-models.7 + rm -f .doctrees + $(call clean-manual,devel) + $(call clean-manual,interop) for d in $(TARGET_DIRS); do \ rm -rf $$d || exit 1 ; \ done @@ -686,7 +697,18 @@ else BLOBS= endif -install-doc: $(DOCS) +define install-manual = +for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done +for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +endef + +# Note that we deliberately do not install the "devel" manual: it is +# for QEMU developers, and not interesting to our users. +.PHONY: install-sphinxdocs +install-sphinxdocs: sphinxdocs + $(call install-manual,interop) + +install-doc: $(DOCS) install-sphinxdocs $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)" @@ -837,6 +859,23 @@ docs/version.texi: $(SRC_PATH)/VERSION %.pdf: %.texi docs/version.texi $(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@") +# Sphinx builds all its documentation at once in one invocation +# and handles "don't rebuild things unless necessary" itself. +# The '.doctrees' files are cached information to speed this up. +.PHONY: sphinxdocs +sphinxdocs: docs/devel/index.html docs/interop/index.html + +# Canned command to build a single manual +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1") +# We assume all RST files in the manual's directory are used in it +manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py + +docs/devel/index.html: $(call manual-deps,devel) + $(call build-manual,devel) + +docs/interop/index.html: $(call manual-deps,interop) + $(call build-manual,interop) + qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@") @@ -865,7 +904,7 @@ docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt From patchwork Thu Feb 28 14:56:23 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833307 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 4B1CD1390 for ; Thu, 28 Feb 2019 15:06:16 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3B64D2EF11 for ; Thu, 28 Feb 2019 15:06:16 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 2F9712EF14; Thu, 28 Feb 2019 15:06:16 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id CA5682EF11 for ; Thu, 28 Feb 2019 15:06:15 +0000 (UTC) Received: from localhost ([127.0.0.1]:39802 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNGJ-0003Im-53 for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:06:15 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52254) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7X-0004zm-PT for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:12 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7V-0008BO-LZ for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:11 -0500 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:54511) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN7S-0007tK-CQ for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:07 -0500 Received: by mail-wm1-x341.google.com with SMTP id a62so9573497wmh.4 for ; Thu, 28 Feb 2019 06:56:57 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=CdQeJ6sH6vZzcVaDPWqQdGDjNFU4YeawHVoENir51c8=; b=V7hNXuXMMZFhdORp0WTV+lGKxc+XyQKPketVcZNQtQ9Q1XZwy10KqF8DbCVBQpIdVZ p8JCp7H/+0b8qW2IGu/P26RtL+f7gelsX3U4jkcNNPjqL9J2SyXZo3e+JnoIe2Ij11RP ELR12XG4bPWX0o6JY8N10rxc6kufDtgQ+RQRxZ0I6SJ4lsDCZMDdmpKJukH8DETbEfv7 SjZqGhxE5kMrkc0deFjd5glo9DtWNJGOlBnyRr3P52I1Gg2sLp+8FjjGqQU2m440PLqG BmxfzaouilsFC520x7+y9Lnt8LJCi3UA036NYAIA2uTNU0ae/nKA6mdNfWXq6KJcwCqF QG1A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=CdQeJ6sH6vZzcVaDPWqQdGDjNFU4YeawHVoENir51c8=; b=n29I90GyXdb6sxov5e/DOAG7F5rgApx/xCU2sKEsl3MnKvthFAspuZAOipQLsk2T8j hdFLUIOhh5cY1P/REgnIdkLBQbR8vc7FyM6Aez8VbproCiCCXt7upd3jXZ+B7U6osb1F yMB96Q/geX+A5DMx6m1Mxi74BdYSTxmoPEM8/p3Inqk2pwl+atNe43AA84/euxa+dxWy 5H9V7wZIGqftFG2G1JsMSoTkYPfBz2n896i60dqzyQOXaiSBcFS+dXg/QdF+gdlEhDB1 6jxNW+r0z6T9oMMtinDvAzFB8uvGi6Y43EEaW4e63IrhK31rEZrSeRoF8GflvcENmiwL eH2g== X-Gm-Message-State: AHQUAubNlIzboYhvNjSbrbNUYRM2wJnjWGn9Ij+PjALO6oj4619SIlmg sOkL1GA9Rk2BC4IjlSkfkShsj3n/NX4= X-Google-Smtp-Source: AHgI3IZR12KnbTHCMoHVqMKN3orXDDQ6oYlvvgBztYBVmnx98U9BU3N9QUQXJQ9qI24eFAjB+2ZEzQ== X-Received: by 2002:a1c:7a1a:: with SMTP id v26mr39436wmc.129.1551365816705; Thu, 28 Feb 2019 06:56:56 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.53 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:56 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:23 +0000 Message-Id: <20190228145624.24885-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::341 Subject: [Qemu-devel] [PATCH v2 10/11] Makefile: Abstract out "identify the pkgversion" code X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Abstract out the "identify the pkgversion" code from the rule for creating qemu-version.h, so it sets makefile variables for QEMU_PKGVERSION and QEMU_FULL_VERSION. (We will want to use these when building the Sphinx docs.) Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- Makefile | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/Makefile b/Makefile index d6b897be0bc..46cb8e62571 100644 --- a/Makefile +++ b/Makefile @@ -87,6 +87,20 @@ endif include $(SRC_PATH)/rules.mak +# Create QEMU_PKGVERSION and FULL_VERSION strings +# If PKGVERSION is set, use that; otherwise get version and -dirty status from git +QEMU_PKGVERSION := $(if $(PKGVERSION),$(PKGVERSION),$(shell \ + cd $(SRC_PATH); \ + if test -d .git; then \ + git describe --match 'v*' 2>/dev/null | tr -d '\n'; \ + if ! git diff-index --quiet HEAD &>/dev/null; then \ + echo "-dirty"; \ + fi; \ + fi)) + +# Either "version (pkgversion)", or just "version" if pkgversion not set +FULL_VERSION := $(if $(QEMU_PKGVERSION),$(VERSION) ($(QEMU_PKGVERSION)),$(VERSION)) + GENERATED_FILES = qemu-version.h config-host.h qemu-options.def GENERATED_QAPI_FILES = qapi/qapi-builtin-types.h qapi/qapi-builtin-types.c @@ -392,23 +406,8 @@ all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all mo qemu-version.h: FORCE $(call quiet-command, \ - (cd $(SRC_PATH); \ - if test -n "$(PKGVERSION)"; then \ - pkgvers="$(PKGVERSION)"; \ - else \ - if test -d .git; then \ - pkgvers=$$(git describe --match 'v*' 2>/dev/null | tr -d '\n');\ - if ! git diff-index --quiet HEAD &>/dev/null; then \ - pkgvers="$${pkgvers}-dirty"; \ - fi; \ - fi; \ - fi; \ - printf "#define QEMU_PKGVERSION \"$${pkgvers}\"\n"; \ - if test -n "$${pkgvers}"; then \ - printf '#define QEMU_FULL_VERSION QEMU_VERSION " (" QEMU_PKGVERSION ")"\n'; \ - else \ - printf '#define QEMU_FULL_VERSION QEMU_VERSION\n'; \ - fi; \ + (printf '#define QEMU_PKGVERSION "$(QEMU_PKGVERSION)"\n'; \ + printf '#define QEMU_FULL_VERSION "$(FULL_VERSION)"\n'; \ ) > $@.tmp) $(call quiet-command, if ! cmp -s $@ $@.tmp; then \ mv $@.tmp $@; \ From patchwork Thu Feb 28 14:56:24 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10833317 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 6D4C015AC for ; Thu, 28 Feb 2019 15:09:11 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 5D4FD2D0E9 for ; Thu, 28 Feb 2019 15:09:11 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 519632D124; Thu, 28 Feb 2019 15:09:11 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id E25DE2D0E9 for ; Thu, 28 Feb 2019 15:09:10 +0000 (UTC) Received: from localhost ([127.0.0.1]:39833 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNJ8-0005eo-2a for patchwork-qemu-devel@patchwork.kernel.org; Thu, 28 Feb 2019 10:09:10 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52287) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7Z-00050s-03 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7X-0008Db-U0 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:12 -0500 Received: from mail-wm1-x336.google.com ([2a00:1450:4864:20::336]:55884) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN7X-000827-MD for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:11 -0500 Received: by mail-wm1-x336.google.com with SMTP id q187so9567143wme.5 for ; Thu, 28 Feb 2019 06:57:03 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=98Cdi6PAb8X+oP7Qn0lzznrDFrkDUmrC40KmQnveD2E=; b=Q9Kk/qoES+/S3qRBUWtujXpZ7KW9JW6bqVFYkH9tY6GgGGhc7r0xgsk1NgUDXTMmAx VLQdK8riSG44gLnbM3bzXNDgpr66W9ql+QHc4+iR4j/GJgaELmBk2VfFyPj/z7u4Bj80 LE3fieST7H7P/SYajt3R3HTA6BKPsi+3rxSrjfwEq3GZL0zlnoOGvWO48gey1A2mmwcJ Yse90Em+jGHiyPpEEUdjXNR+vniwKEZasNkFt6ZJL9Rh10YLZJAloCJLBHp80/FNL1E3 5MFoHnP6fUYXth3fuMvh4z1CYBiWNyyEQ5zMh4qvZrf48qdqnsV6QH8qX9dPnPHzoLnz OKzw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=98Cdi6PAb8X+oP7Qn0lzznrDFrkDUmrC40KmQnveD2E=; b=HIP+jaza9Rjwf8nPyl135fxjL2Htcn1iwuGa5yKxKU+5QVcFiJwK9vJ83MZT9pwtGC 09l+0n6F/qR8h4j+EFo0LyilNDwvzJTDONFyI9tPhhhqMc3ZqFhgp6LcVnaQaJYReabm Oxd+fe99275SOszaC1ztWZy1Es8O0iYZAMZBWhKV/VBJ8Zs9Bb07IBIQOHrIMDLkNeG9 KsjWTs4CCEuOW4Tm/7j40vmYiwX539OhV3F0Km3Be3j0EiaEQ4VwBNvAzKPDCXv9ZWi5 TTDkAs3Mvo59+/5Z9GhfRHTzNiWZBb6GABNwUzoHf6nLSmx3uPgm6s8n0mznLx8pmtP6 LxTA== X-Gm-Message-State: APjAAAUuyKsflbZwWws9phoGKbwf+PtwErMwUgEX2H4WoEkdxoBFPmDi rmtjEPY4jY9dovWpPnqkzQMFne9Ajfg= X-Google-Smtp-Source: APXvYqxXP7+rQp4W+nNwzH37nr2inxhjqdOoeECsQ7YhYCg82pualsQ/7egOok/mB5qOOWLWBSmqAQ== X-Received: by 2002:a1c:9693:: with SMTP id y141mr62688wmd.33.1551365821581; Thu, 28 Feb 2019 06:57:01 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.56 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:57:00 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:24 +0000 Message-Id: <20190228145624.24885-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::336 Subject: [Qemu-devel] [PATCH v2 11/11] docs/conf.py: Don't hard-code QEMU version X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Don't hard-code the QEMU version number into conf.py. Instead we either pass it to sphinx-build on the command line, or (if doing a standalone Sphinx run in a readthedocs.org setup) extract it from the VERSION file. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé Tested-by: Philippe Mathieu-Daudé --- Makefile | 2 +- docs/conf.py | 21 ++++++++++++++++----- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 46cb8e62571..526bac7f516 100644 --- a/Makefile +++ b/Makefile @@ -865,7 +865,7 @@ docs/version.texi: $(SRC_PATH)/VERSION sphinxdocs: docs/devel/index.html docs/interop/index.html # Canned command to build a single manual -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1") +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1") # We assume all RST files in the manual's directory are used in it manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py diff --git a/docs/conf.py b/docs/conf.py index 6a334f545ec..0842d44e930 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,11 +75,22 @@ author = u'The QEMU Project Developers' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. -# -# The short X.Y version. -version = u'4.0' -# The full version, including alpha/beta/rc tags. -release = u'4.0' + +# Extract this information from the VERSION file, for the benefit of +# standalone Sphinx runs as used by readthedocs.org. Builds run from +# the Makefile will pass version and release on the sphinx-build +# command line, which override this. +try: + extracted_version = None + with open(os.path.join(qemu_docdir, '../VERSION')) as f: + extracted_version = f.readline().strip() +except: + pass +finally: + if extracted_version: + version = release = extracted_version + else: + version = release = "unknown version" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages.