From patchwork Fri Feb 1 14:50:25 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157229 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527087jaa; Fri, 1 Feb 2019 06:50:40 -0800 (PST) X-Received: by 2002:a1c:e18a:: with SMTP id y132mr2974354wmg.48.1549032639971; Fri, 01 Feb 2019 06:50:39 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032639; cv=none; d=google.com; s=arc-20160816; b=t0SF4we3CY+0Vve1MmAv1Q8QUuAGHzbPqNbNvJ4/zyPu1ZmiiM4U9IY/LjCHmrxiMR XQJ+Pp3yD2NioYD9wEkDanyR6g45VUgjm/ErkLDHZB/w1W+/QN14Df+t+qbdU5kAUruw aXaETE+6cJeVxW8zmPwX+4Y6pPwWYuNqBy6EkfHtjSO6lmiqRKBPLMeR6cu4Q3fWj/d7 0u0jtxEnQlabn2kffcko32o7/iYeE0d0ex0CkUXQwlEJG91EPf+9VRxvYIpaiomm7sbc tZfJKQEvjRTckyTvu+b80Tj0a1OghFKyhTBFc7sacBHgx5q3tn/QonFuz5PKeF3WXAqm +4PQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=yJ/I8VxqVDaXeAhcIT3pinTsIlP8Gad1oLNEkSfIb6o=; b=qR9se2GMDCGM1EnpiLhc1oKUaMgumjLiTakd3paHkYkZ6OnYCJMvFtmz4kC/yL3jcr Bivwz510jDBqS98q67D/6j3Ajl9zhi5BV76gEeDvxquNPNZE75O/UiadsgvPluPRZ7EM XzMvBei3LtCb+VGzfLbrbDdNR5GlpAIEexDjGemkoybSf53X1TZCzga9QVni+liNuhOh u61qeklEgvjdteasen+hJggE4YuJHy2vNEUTmJMzsD4dU0yg43kOlA/9LxdiKY8YGU3w wxtTSmNdKGGxJb2RSB4H5yrlW/JLVNy8jumSldgNpGqnQYfBsygvcfakhBNgvgUm5kf/ /BKA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="J/cVwzTp"; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id x6sor6004247wro.22.2019.02.01.06.50.39 for (Google Transport Security); Fri, 01 Feb 2019 06:50:39 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="J/cVwzTp"; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=yJ/I8VxqVDaXeAhcIT3pinTsIlP8Gad1oLNEkSfIb6o=; b=J/cVwzTpn2r9OZouoTa/oc8itwSesLlLQTQ6nEFZeGr3RPPc2zwLWuzgTi/G8jgjs4 Hv2h+k+eRDWR7bw+t3IdUrcJpJEwDnM1ZDuow63EVCwgpb9oTtDkBhDtGSG8OiOLnz6K OHvD6T8YeyeTJgooOnB/w4c8G4vdbGowKdQas= 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=yJ/I8VxqVDaXeAhcIT3pinTsIlP8Gad1oLNEkSfIb6o=; b=Qr8G6dTM6SEYr0hMBvROd0eZrFemWarwk+74XmbQw3/iD7eW5aCrP1XWr/nHiHpfEt rjuidkH89XFTZRmy1LPDBqweezTbPESYfubuUedN66qZXSOSALsxzDXyAMKVmjZ3jGkc I4cmnPS0dY2LbW4qz36pBPaMalqG43o0sUzoCr7sv0qDxdupvYT7Ubvaf5gXZhU/tGeq ILnNXR7drsp8RWU0pmhlIJ5+SIAYoFufQEWYu1augGglhn5+9C6KR929MizDxnfckplw jG/SpbVVIQD/O+XmPY+6A0wU1eDwjG+hddiGcOIbA1t92WkyvSABYXT0GmnSGK5L1ZLJ MjqA== X-Gm-Message-State: AJcUukeNVD4fnudZmFw/gY1vROOgY7I6ZcO+NZ1VdBt3XSE18Xt/MvNQ Z8NE84dum1WQoO/VEPx9PQLy3qGQ X-Google-Smtp-Source: ALg8bN4d8wmvIc2kMsVUO6yg1jq51Maw5WiUZ/0EcAvX+0vP5kNWEOVq8bskMfZ+Q7ZhVFERyiwfdg== X-Received: by 2002:adf:ec50:: with SMTP id w16mr40097927wrn.171.1549032639520; Fri, 01 Feb 2019 06:50:39 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:38 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 01/11] docs/cpu-hotplug.rst: Fix rST markup issues Date: Fri, 1 Feb 2019 14:50:25 +0000 Message-Id: <20190201145035.22739-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- docs/cpu-hotplug.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.20.1 Reviewed-by: Alex Bennée 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 Fri Feb 1 14:50:26 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157230 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527123jaa; Fri, 1 Feb 2019 06:50:41 -0800 (PST) X-Received: by 2002:a1c:7706:: with SMTP id t6mr2616817wmi.57.1549032641633; Fri, 01 Feb 2019 06:50:41 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032641; cv=none; d=google.com; s=arc-20160816; b=nUCL+XkfvReEPpJLgsGIjwZIXfkBIc93BxUN3Ek9TI6/IDzd00DbtDJt15nH9TcORk XmpAH139oWPXbhxXv70r5O0dQ5fu7Scaat1+UoUL77cBFGmTdPeq4PNoCTohiOVMsAr8 UXOWyqfeDc2qs1UfVuqqtUAEbTIzDrzNEU/5Vbr0qPJXnTMKRFBazZkgwHunKmkvmAI9 /cdsm58GS9djvkhs2UA3qDUELlqDlhGjcbh6V/A/oIwS5l6IlyyNHP4/ba9H5KaXaoxz /SSUKg90xbvDSC+VG8jpIbwZzb7s0JGkyXd9MhqRCX7B7DTQAM1P7W62VFVXkX9JqTXR 50VQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=5kL+Fc5FygULaSo3r/YzdydHS5WCkrxFyRXXNr0TIQw=; b=PjFC6UiiewMx8+MW/2PhNRrtl1YfglA8HuOVOfWpeXGYmPFl33OOGRANsx3rwJihI0 hp4OD91SOI1WXhDF2eLYttgt7w17GVas3/f/X1AaF/Sb6XkWkdTmjBL1gGZllGwqBzMW gJmrb9zDBzR8xVbw2ZOZi9KTdtXbLd0Fzyd8MwEkxOSGqHdVpz41Y0iiYzwu57ABKOhg cUQvyoIRc7lLmlIDm+xMNqXa319gBkItZJGaQWWvlEqfEltfaD+M0ROO72VpPdPbj80G dJgr+lREBj8IZnxqYAPenJQEKkPXvTaNiPpqJ6mHSxYoZw76BKAqdNuUE7uw71rF6A9R /CQA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=NWyU41GH; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id x7sor735209wrm.35.2019.02.01.06.50.41 for (Google Transport Security); Fri, 01 Feb 2019 06:50:41 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=NWyU41GH; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=5kL+Fc5FygULaSo3r/YzdydHS5WCkrxFyRXXNr0TIQw=; b=NWyU41GHwVlP6f+P06jCkcvf+FSxU/5b/UU4gzRpX7DdTSB1QtmsQWjnEUwjBdOifW U3csD3+Dg1DcZgWQhwcRyTPaY73Pxhyv9AXbI7zclAfsNo3L+oe2Ago/nyqNlOCnRIOR PP6le0eFfr+cnJyeyfM2Ttd464JZx/jOlogGQ= 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=5kL+Fc5FygULaSo3r/YzdydHS5WCkrxFyRXXNr0TIQw=; b=retYcIperdMIWvtTToXv+tnEOP1M0D/nUNT6wXL9wvaBiOc8Rw7bdDzOU0+DNvlXv1 xSwF9Af664fGFm8lCxV+MN/gGYLPCVMB1yAycoTnk0MYVkz+Xyb9z3FyPqKC4YbbETs6 /k/XT494N/wN9HN3EzRQPPlHffov9HtgY9RJ5qApSNqYrYwfpU8tgBH9n3qSaVidLX04 lDIKSDnXV/RGQEe45fNAMlzk987M8PmY6hfnqc3CDbyf15AOpMUCTb0p2GK7pi3eq/G8 6TBhoTMJLmkMI2ms5jIq9M5PDIls4XEwogK9eNKTQ0/sM4Xsn3qvEK9pew6yPls1PBlo 2N+w== X-Gm-Message-State: AHQUAuYmqImYK0Xeox8ksA2QtE9V1VqSQZhn34pSW+CQzsm463ZDMzqD 3CbD9SSJR1UBBpCkuRua5YdC+zr4m5PkVIaQ X-Google-Smtp-Source: AHgI3IYAxmSk2fVbp9Gj7FPZhXPMUI+qgopqRWNKWqBQ0UOqglgOIYnilQx1N0cLp9oxfKPSTXmG7Q== X-Received: by 2002:a5d:4046:: with SMTP id w6mr18725611wrp.92.1549032641101; Fri, 01 Feb 2019 06:50:41 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.39 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:40 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 02/11] docs: Convert memory.txt to rst format Date: Fri, 1 Feb 2019 14:50:26 +0000 Message-Id: <20190201145035.22739-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- docs/devel/{memory.txt => memory.rst} | 128 ++++++++++++++------------ 1 file changed, 70 insertions(+), 58 deletions(-) rename docs/devel/{memory.txt => memory.rst} (85%) -- 2.20.1 Reviewed-by: Alex Bennée 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 Fri Feb 1 14:50:27 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157231 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527143jaa; Fri, 1 Feb 2019 06:50:42 -0800 (PST) X-Received: by 2002:a7b:c397:: with SMTP id s23mr2653992wmj.127.1549032642760; Fri, 01 Feb 2019 06:50:42 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032642; cv=none; d=google.com; s=arc-20160816; b=EpyOVa19VOHbu54Crxf1MRu7cW3v880XJfy8EYZPc/T4XZrFEuacXknbJkTJTTU+Du jO9Px8Cm3Ck0R64v5wdnpc+i4oTjc8NbkgYqU2UopJ63BNkFHhfRSRdyoTdf248Zs86B 9Dy9f07kiNrBxVdRhHXH1jYoRI0VaIUqcONy1maJK3l+WqWKKvP8N+944aRtIGBjkuVd xyWAnQLZH4X56IEtRtyqgqRxHzs8yrnYMtJbf7j+44kVowRJ4iJk+Ow6LmrfxhmDHQB+ kH+VS3jDQ9khl5fb1s3b993d8jDodX94gf+CO5ctnxEoDtCcsqTuhaF925Fuqggzb9Bt +0Kg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=6mce9QSSNUlxaAEe6w3PiUziOPnSKM6yCS8EwWRp0C0=; b=AaOYriVXIemoTapQyQxAWPXiaCnolt4jMRkfbuIa66YBdgwOa/s8c9Hc8bTKZ8HszI TJRR35zGCSgBKKK6w3NxA+bNbKPnZCn3DfcUNIVzRZ0sACGQrcILjtcZo5ja25A6wS68 6xeh8NOipfnCBC6r6m0RJUL89UNJfVy08LkHd3Je0ZQR4y/5Ion1MltkWHuvn5zETZmq /6RE1rvmaTWocVnCZ9wVI77AWDziIyGniezQBAlHHSQiKlgKIXAE9H+Ax7HRlz2DJmic Gf+fiw3zYWz4NKhVD7/FemRUh8cy3ybbpHMFkzf4ZiIhOK4fHzWrqSOGq6Wfp2ADmXHb k4aQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=ITG+Imdo; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f41.google.com (mail-sor-f41.google.com. [209.85.220.41]) by mx.google.com with SMTPS id z17sor6093676wrw.33.2019.02.01.06.50.42 for (Google Transport Security); Fri, 01 Feb 2019 06:50:42 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) client-ip=209.85.220.41; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=ITG+Imdo; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=6mce9QSSNUlxaAEe6w3PiUziOPnSKM6yCS8EwWRp0C0=; b=ITG+ImdoW1C5reX/SCw2vtTLncoJUo+78Jm62pLZCq5OoklUBsCf9h2fzp9ntRCB1g LnYl5PxpSIwS3rm+eeorUema+f47Cv2FRvtQINqwFTVcuPbyXgVyn8HJ5+UOcXQ/FG+K EJSmEwuihZoik+N9qKoZWzR19c2Qcx8uMXG4o= 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=6mce9QSSNUlxaAEe6w3PiUziOPnSKM6yCS8EwWRp0C0=; b=MLJmQwH6ik5kb6d0vMHgQCsSJvNKX5xyBGyFhVgDCdNciu7iwO6ChaxTx2NE2VBIYC MsaQ6iVMQWxchd5gOjdU9KOAmlb9gBBKc22yyIno6sk3DKO3wrYvRWmj3fU358l0ysLX TEmmdVi01E218YiX8++ZUcINNDtuSQePOrBXWC71okesoL2neNuvvSu9cmhxLw2Yo0wI bEsvRu/Ko8LwhbuKe8k51s3cBQN1xLOsglbSeHwerPmZ/VyLXHwzLKDxBD7Kg+aCvif/ 6JvVrD6mUqFJUxCyakoKKdxopST36vLPPBpEFMaoZtk//dBNeK/hzjes5V6vippYRk+0 J0ew== X-Gm-Message-State: AJcUukdFErh8EJxkk8no0vgFydWFxlgyfEUMMWBEs0J3gHeoj4ovjn48 JpP3+PQwQSqhbLso4EF+QjMDc85I X-Google-Smtp-Source: ALg8bN5f5VWFEr/QtpvEzohwQkntH7eMvh4G3Gb1ZwSe98WSrHKdQB+h19sdaLQpx+Smw9VALpsJNQ== X-Received: by 2002:adf:b502:: with SMTP id a2mr41317554wrd.54.1549032642367; Fri, 01 Feb 2019 06:50:42 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.41 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:41 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 03/11] docs: Commit initial files from sphinx-quickstart Date: Fri, 1 Feb 2019 14:50:27 +0000 Message-Id: <20190201145035.22739-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 Commit the initial Sphinx conf.py and skeleton index.rst as generated with sphinx-quickstart --- 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 -- 2.20.1 Reviewed-by: Alex Bennée Signed-off-by: Peter Maydell 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 Fri Feb 1 14:50:28 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157232 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527165jaa; Fri, 1 Feb 2019 06:50:44 -0800 (PST) X-Received: by 2002:a1c:8148:: with SMTP id c69mr2734763wmd.126.1549032644320; Fri, 01 Feb 2019 06:50:44 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032644; cv=none; d=google.com; s=arc-20160816; b=CInrAJXhZX8xZx4efCSOS4Iqgwcj28ojbtQnX1PFHd/wo7xJKUFpDvteThR8WB45bL 6AwJ3XWP9vEgWy2lWxG41gTOVcnslruEGuzc2boa/jBFiys411BjCBQdKhEsrzqr71RH fWZJxSz2tQPdR6h5oziPYubL1ElaSTUezNYan1CihhrwdAZ0/OprFsBkgTkDXMllPemM URyl8WPRlOhiMP90FbX00rM4kfT+kl2mY8ylX5JIuTPcStp1rwwTrpaaBBTunI7iqZgZ fcxVIRPZ16Ac3/JNunnK0Wx5hftwuutcz+vm7sZNx03mPNsbD8UyjF0hChMrb92eMC0f Z3Eg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=vVcq4uPvDCVi9HBueMYXg++o0hzqesdl6sfILsn/e8Y=; b=v2UPMmSLMh3kHhKSKMsC8F0bihb04uIg0uJ4poGa4WogEdKCSRW4JoMLQPQw9XI+sN L4Y+X7EBHwx/SQga8yJATEvUrHnqba8PI5H6nNGILc+dXqxebJGnoGtO8r+FWfq73Xfa xHbYVOyspN1qSRaupoI3tSb3hi6W6LaeeiBSQVYfiOKSPnCvJBo2T+byjZfPW4ZT1Prk XPVSiLoGpO5T4eApm6cMv7PITZVDOCPVPecH/NJpk8UV3GTLGzIoSHH5xGEmsRPah1qe M4QdylpOrVKjeOXCLEsGzrKfZDc7hE6VhBJZhzUDY6t4J9i60V1smynG8G7z2KVwZdTY 9UVA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=AB68a6oY; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id x7sor735300wrm.35.2019.02.01.06.50.44 for (Google Transport Security); Fri, 01 Feb 2019 06:50:44 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=AB68a6oY; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=vVcq4uPvDCVi9HBueMYXg++o0hzqesdl6sfILsn/e8Y=; b=AB68a6oYM155A3CvsxM171Eq4Td3/O6n+o+NHE2NDB6IEaXZRUHSniRi9vL32vGOWH 061JcsOJgbTfv+fcYo7t6Asa6CuoCfvCMThUvWssu9NwZd7E7H59+K7TfPCljZVij72q moRnACk5ENlB6WLSlbNC/gDJe0J8uyi3X89o0= 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=vVcq4uPvDCVi9HBueMYXg++o0hzqesdl6sfILsn/e8Y=; b=htkQNhhKNQH/o5cb0iaVaQjftZHJEDmL3hVD5HLYQqkFYEbcbwl8UcjFSiUh3b0PGh GPy/TUNFcJiQElGH+K9UnDNeMhNUfrsHS8a7obZR4A7ul1e1AIxeKLOhDFsKQCIG6xZX kJqO7u63K2kIHQeHdHRYr+Yu3dt95RxuGjMVf107oocQcxsNWw4MLl+IPAQnGJ5tpJvz P1X+D9Xts7fN0UDXJOqUBlIKc8qrpH8Zoe6mrYhkOeMtWf423GaJS+EMtVo+AhGBssnH 0CGAK1n5oV84gquXvWVXPPBkYZfwVdq41cldO42IPhPOr6QYfnYhK82/ObCd8EKld0QC lhWA== X-Gm-Message-State: AJcUukfvcLTXMn60TrhbgzHcSmG+onB0o/zR3i52YHZp6PhBwWJAlE6q Nm0UXD+WCyrKnKeq6kUrCwFghSvR X-Google-Smtp-Source: ALg8bN4y8TSXrq8Jk0468CFa6JAkr7+NYWoMuZK4jOFjNThgmYPtcMX3TvS+gQZ3YRYkgDNlpZiJWw== X-Received: by 2002:adf:a14d:: with SMTP id r13mr37349525wrr.169.1549032643914; Fri, 01 Feb 2019 06:50:43 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.42 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:43 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 04/11] docs/conf.py: Disable unused _static directory Date: Fri, 1 Feb 2019 14:50:28 +0000 Message-Id: <20190201145035.22739-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- docs/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) -- 2.20.1 Reviewed-by: Alex Bennée 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 Fri Feb 1 14:50:29 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157233 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527182jaa; Fri, 1 Feb 2019 06:50:45 -0800 (PST) X-Received: by 2002:a5d:438a:: with SMTP id i10mr513588wrq.111.1549032645578; Fri, 01 Feb 2019 06:50:45 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032645; cv=none; d=google.com; s=arc-20160816; b=DlPvlO7Z52YJFxPqsclvMSTBKT5NMLvLcqas43YaEzNgxBT6HyY3rDnXf7e4Hmv8Z5 2ph7K8uUsahA8/+BGxYvBBhjslnQcqtZfI7CkYxdX8ao7J+LOsnNN5rrEpTriHi457l9 Br3b5eyoOW1YoiE32OJ6EMlOEqXf9qpxV6H/tRJXnaIsXbqBXA3jU314DX7jC31fzM7u QG4C2oiUMu1LNuGAmFhVEbmjYIP7iS7FWdJAX1WDHZozHw37doLRikMT/Fz8/GAOLP9u FWvlGAuUyPLLVhUWwrq9QGmAk8zA1Gs5iKstxGi0Ff4qGEHWnU+s9fhgjpAiZGFySXiE qnMA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=qdKXnGaIcRR1Ept+AtLXN0B4XgPtrXjB5PKfiWINGPQ=; b=Ax3D4KknOxLIyO5diKZZxhroP+H3wNb+ub76cbAMN3RKQQO0Zh8WfpvlqdscF3sT7X U/qBk37ZAjxltqPaCYMOLHavsDK06rec5u8u/G6aC1Xc3oH/518uV9RRCDVJ0arNPYfo mgVYbgnq/2w9P4NRD4FEl2G5FYqFLZ2ZbJ1wBzuY3d2BubHcMKptaKNlw2/O0vgqPi7s NVRPk0733N7pdUOuVDmn83AbatvkVetFKgJoAiZMy9WYMEnnI3DMwU/qEjvYQ2xwejt0 o/rWuVAlaTUzSeLEwNW2taVxc9Ut+cSqfawuUkl0tcyAyuwLc/mHQT/3v50xqJ4xhhpk angw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="IHtXZ/2r"; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id n12sor5995602wrm.10.2019.02.01.06.50.45 for (Google Transport Security); Fri, 01 Feb 2019 06:50:45 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="IHtXZ/2r"; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=qdKXnGaIcRR1Ept+AtLXN0B4XgPtrXjB5PKfiWINGPQ=; b=IHtXZ/2rjjXJZUR+DltzEdB3gabXpbsp+j/n7UZlMLE8VVjZ8zSXX2UJIWbJ/ssBWz Kuzfo4PAOH+8lios/xyYR7Hiqx5F2tS+7cw+r/ljbIlarkX/3rSs8E1oAwJlrsyQXTJA Ysn0PA2AceckANb6rFRscrdWfaVqrIvOnswP8= 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=qdKXnGaIcRR1Ept+AtLXN0B4XgPtrXjB5PKfiWINGPQ=; b=U0aErTtUS204SImJb9KX2U0jszUApwk/u9+ErCa9ER9JztE22YdhIcXz6umnLtl9Nq LDFO9dxfYznT8t+sVR9d1tbGeu/LFJ9FTmc9DI8BTRzvowANHboA34iUJaa2PgO473mW 1aB8SVXMSWeOfsLGJ5nh2/jEa+M2VVOg4q8ckRKQD3nACufRjT4rssthNkyxY1Uc7nN8 q4BRU2MxbQBcwhFYGN194NnNYnZedxW3PFQMM+k1c8JS5kqPxNvaPlggE2c+BvlGvEG2 rtcOUK9D1cp6ECVFOXOHdPZARpIuyxkexv5M8nJFFvre2nDFkPzj88Ls7/rePLZU/mMy i2QQ== X-Gm-Message-State: AJcUukc9wWFGch3NwE05N6dyIZ2PGt+s/c+sNzeyRHENzH6R7KZfuxvn J5eEvt3zZ0j55tuiAXtnVhCydNtY X-Google-Smtp-Source: ALg8bN7VXK64pLTKjfTpXl0RV1IWjrldZ5Lq25C+3sQ0MlhMwwE7gsOZDdYaXly/pVkuvAoR35se1w== X-Received: by 2002:adf:8506:: with SMTP id 6mr40531175wrh.128.1549032645214; Fri, 01 Feb 2019 06:50:45 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.43 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:44 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 05/11] docs/conf.py: Configure the 'alabaster' theme Date: Fri, 1 Feb 2019 14:50:29 +0000 Message-Id: <20190201145035.22739-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) -- 2.20.1 Reviewed-by: Alex Bennée 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 Fri Feb 1 14:50:30 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157234 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527199jaa; Fri, 1 Feb 2019 06:50:46 -0800 (PST) X-Received: by 2002:a1c:2d42:: with SMTP id t63mr2910913wmt.9.1549032646748; Fri, 01 Feb 2019 06:50:46 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032646; cv=none; d=google.com; s=arc-20160816; b=UfVf0yhX+vVX1rqyVLiIWzchatkSgKtOGjmzUFsVcLpSxKRpivgGKXl6vC2KdF0Y8t qr5gob1zCAMwK7icmu/MgIzHN21ger05Yt/g1O8l1NWePPPJDIJgIFpRSgPyGKgh2+fs CLbnLR4ZGRbL/PnAQvvexHhpPEnZlzkiwCdLjVPCLnD6EyaWUylppGErcTfxAxIKbhJH o3Q1Lxh4YJPeSM9t95D0f1mSl4P6NN213j3ACgZax4b3djN2s0+jI4VUIhljp4O2x6XR TEZ6cNrR39m+uPOuCT/bZ6vCIuiorv7RuMYeaIbMOyy02cvc4MsS3cZGV8kMJP04IBGL ex2A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=ZY0Hoyr2WjIv2JxshJowtprF9j8SAVs74kkDD+37vmY=; b=Ao7d+Yrh5SbF+CBmXyr8puB1UrB1rzDSMFrflp072LiAGLo3fhQq4j+tPsOXrP1sFD zRytlWCYP268c2XGQDkmeUjV7+lVmyptX216nSkq6XAJ2g/r1u7AFyFa6FXm72tiDOj6 cbI+eDA4m3gPvfZ5OMdtOQHmoCNznbKiLgVwakMEftawE3XJ++zk8l4+qryQIwLvrx+l b0+tpcL6d3Nxe2ALlNnm2mZBmp7xe01qbsqwCQvGJV/TMVz+cakQ/Y5zUu3CuGRleQGk Ojg67E+EWGb5D1ON9Hq71dvRjegonghGzng80/hjn/Q/biLxEcuunmP1dZOiRUmsZ5Gx 5tag== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=KpqYbQPh; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id p1sor5994844wrw.17.2019.02.01.06.50.46 for (Google Transport Security); Fri, 01 Feb 2019 06:50:46 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=KpqYbQPh; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=ZY0Hoyr2WjIv2JxshJowtprF9j8SAVs74kkDD+37vmY=; b=KpqYbQPhsgJT5ARxYyzF6HfhMDTDRodowZAyEPJvFFLbKChji840FWnQQkNJRp+Jti q6/iv7i6iSm1xfwblwHcPZz4C0Qv1bLKGIUguKDjP7m/LhQQkJVbLCTWwiFi/fa7t4d/ nd2ymBGNJdM2xHSovQg+ppxihCbvq/uCyknko= 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=ZY0Hoyr2WjIv2JxshJowtprF9j8SAVs74kkDD+37vmY=; b=tOsi5/ktZSSx8NtT4CSSwkYEXrHj6nTTotqlrHMqFyhly6Qn3EBYX/3RaoNf8FcZST WtmPu/Tye3gMSDONPLHV2IbN0g90aUN7avB097xUX8qDI7HXRylzKT1ikIAV2KqDtRxt s0nCuN4FLUFOORf3v2k29t3T5MWweu50/I0DzSZy42f5/B/E+knIbj5zKI3LQZ5THxcY Yrb9usxGIcRIS7yMKFgqYTVhbfJTVSIy85/yLP7k3DduFpcc1eOh/q1Kl4pMwRndvrX6 8P1Y3y+nCvCp5apilsfGGTiJfjZ6E8pEj8OEr+ocsa3oyUsDFjSidlmpnxLoxpVyUpYC XVPw== X-Gm-Message-State: AJcUukcLx8sLKF9UxrgGWXpfO8L72Lrk5wNS5RTAfS1GeQVf5v1z4Xil /Xqs2dU9ZAIgCF6L2r4WxtOdFLGF X-Google-Smtp-Source: ALg8bN6m0s3we5wVfGYRMz7zjrRJdQT/nhA8K6o06Mg7avRUv/oU1SqdrSGqU+VKBT7XSkw2myzfRg== X-Received: by 2002:a05:6000:104b:: with SMTP id c11mr39612354wrx.303.1549032646446; Fri, 01 Feb 2019 06:50:46 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.45 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:45 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 06/11] docs/conf.py: Don't include rST sources in HTML build Date: Fri, 1 Feb 2019 14:50:30 +0000 Message-Id: <20190201145035.22739-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) -- 2.20.1 Reviewed-by: Alex Bennée 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 Fri Feb 1 14:50:31 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157235 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527227jaa; Fri, 1 Feb 2019 06:50:48 -0800 (PST) X-Received: by 2002:adf:e7d0:: with SMTP id e16mr40746331wrn.142.1549032648161; Fri, 01 Feb 2019 06:50:48 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032648; cv=none; d=google.com; s=arc-20160816; b=yv1UTsgGb70zu4isa0esSJI5BErxihk4cgAQIrU/uzRwFb1LBpSMgjASPCteXL7U7r MyWom1Ta5/mE+zgYGia3okzmSEnI4uQZdAkhqnpYol77l8P+lsPXVJwhSqeKIEd2kh3l 8w2OgqBcX7vvbTXhT0tIM8L8hqmX91k8FXl1bwD8/njfAqEuPIbiosSuvKX7F/GZ9Ycd Rx4d4pw6e6TQkNp4ZjAlqKz5kIDcCVq+sz1eg7fI+q3Nj8uyCjYJHqv9/eaSm4V2SLlw bL9dDZppo/RBPbSS/jAz5R7SX9aB+bQG8cYLLKLGvLRkuZfzJOmDPmkUTbBmydcTbq+S HEdw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=8fOtyaNVqoJDUauRkZ23KSyTse3Vfwomv1ji9q1oFiI=; b=RlSHyZoNUv40t15Ty2VD9UBs1kmbNcLYYKK4qkxSDOidhOxgeMGOieeXi2wsP7ivOt xDQ8U/ZMXH9h7Pbc++/rT65feGNNiE27mU5hMjs++4+A58Sd7U2ZXOzAhtYciIEElNWt XcbygQpQX94cg8j/dosEqjWEMRoAMNmB5+v/+MUvn2smkAFB2xkhmULFfyBnnwEdJ1g2 Us0rHVxumAuiaMPErz69SnkgtQA4iTS3Sa1YyBPCBTyyHQTKP8oDPbjAmwnb7VVITt4Z HLm0MxdCTkldxK4Lxj1z5um31zrCbHDz+dBqwr2kDyOErgXAXbRDtrCt0s7eXIrZq1/Q h8Cw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=LZHcLUbC; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f41.google.com (mail-sor-f41.google.com. [209.85.220.41]) by mx.google.com with SMTPS id v8sor6069554wrs.40.2019.02.01.06.50.48 for (Google Transport Security); Fri, 01 Feb 2019 06:50:48 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) client-ip=209.85.220.41; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=LZHcLUbC; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=8fOtyaNVqoJDUauRkZ23KSyTse3Vfwomv1ji9q1oFiI=; b=LZHcLUbCCGYnMixiXUF6F2T+QHStBnncGpbbtGmrtd/J+0LShbwbXrhRkq772Binnt HM8CeMJ2JQyBdYoJLIgt3hWk4kHLgmoAKoRHm9+ASFdzMrTsHXz2XoV60vsV+iu6VHfJ 604LHnZySW8rIjD5UkSpa/WKQ0uIwDA54Qahk= 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=8fOtyaNVqoJDUauRkZ23KSyTse3Vfwomv1ji9q1oFiI=; b=bvyJ5JAeitPVzdj2hhr8tJBvpFX0N2pSx+FiAuArzeYv4UVOaw+xoj5g2r/l7dM71f v+sxc1KHLZGImB2gV+oRR/+P8NNqScNNQ14QfFi+1Xqx5eKpKMtdxDXncmJuKeSlBdmR E/Z57rnahiHMl8hs+DPQA8Dt39qvMi99IBWtZdUDfSSOvfaWq3igjcQHQ/M2Wk/+MXXy OI7vSP+5/FHb4+Fo8Xoi5uZMIhfG5Dwuf7lR1oAyHR3MC7QasPfoC14UigAWDtXw09We oB3oSeLzJIx519BycQetIhWLs8ulKeC1nnYgYrNHyWiMxLQGbf0vI2GAtD0tdepvCsG2 Maug== X-Gm-Message-State: AHQUAuZzQA7KsFD1x2vHVW4IOppahXsybvmwfeWPLQ3VPy3tLGNa/orm gmsGxzOIzI8qA8bnNZ9yht9UZSjg X-Google-Smtp-Source: AHgI3IZuiNMrM+ZRqzAUmjMAuvQK26LH7mas+cadCrstKlrIzpfMIFaG4QvMXxOdurPZHe4mMORRuQ== X-Received: by 2002:adf:f6c9:: with SMTP id y9mr1723466wrp.138.1549032647843; Fri, 01 Feb 2019 06:50:47 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.46 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:46 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 07/11] docs/conf.py: Disable option warnings Date: Fri, 1 Feb 2019 14:50:31 +0000 Message-Id: <20190201145035.22739-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) -- 2.20.1 Reviewed-by: Alex Bennée 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 Fri Feb 1 14:50:32 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157236 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527257jaa; Fri, 1 Feb 2019 06:50:49 -0800 (PST) X-Received: by 2002:a1c:2e0c:: with SMTP id u12mr2755939wmu.81.1549032649747; Fri, 01 Feb 2019 06:50:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032649; cv=none; d=google.com; s=arc-20160816; b=xgZhhG/+A5GVlKGfw+B3M9pgmAZfkwAM8pkNb8+ZEgFuiRGCgpnj2t5h/fNbgAahjX DHUhgl5aOoazY6Idoc5GAQsIkHfG/T2VGLwMEOnY532Q7bZhwhoqVWPHSM/fqurl/Y9/ cnfGnTG73gBN1DQYeJJcMNtEKp63mqjVuyfEQcrC/rsLYdSpxYIv2WQxkzmulX6WMQSp QgWDwv/VQ0zxgcLALUkWSFjfptiv6bYuQlujcVcqpNcX1WkqyCm/5Oo1d25bFIdmJPax pLToxWTJQoA9L9oEHRcXHmeuQ6gKvoIEKfdbY7ngqDw6qyOgjT7udS3h+A3Jbovp0xXU KJBw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=FKkFoERye0Qk2mAM+PAXMHGxGZKBwpoLIKSbeAC6HpM=; b=baOVrmUXkAeKL/0AfH+LYbuX+LoKyC9o66xN6LCVTftsSuqMQkXJT8B7i6HWnhCkDp 6DSdkIJ0uwBtrNSNvMAf7GwlcEa5b3TXRZ07ejD/L+12FKv1n9RGR2CAUwVxtQy4p1+9 Z5AY4DenEnHJG4VPLFWCtpi2f5IyfLsHHzmuZFAEs3zBusN7f4pTS220NMo3Esfft9CQ 6w/xFLw/yM+0jYucYXL4I/HZfBPgEi6zFm07ba02rZsWi10Md2XjK+Ed684bvTytsD00 3evea+hH/bO8ZSj/jtTtUgfp5cTylAGXBkbDIsHtSteNUpjoGPBoRlmdt/90UBPndKwW grRQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=inAQnf3j; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f41.google.com (mail-sor-f41.google.com. [209.85.220.41]) by mx.google.com with SMTPS id v23sor6040843wrd.4.2019.02.01.06.50.49 for (Google Transport Security); Fri, 01 Feb 2019 06:50:49 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) client-ip=209.85.220.41; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=inAQnf3j; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=FKkFoERye0Qk2mAM+PAXMHGxGZKBwpoLIKSbeAC6HpM=; b=inAQnf3jfOFWps/mcVKjhXNC5ohoPPwke3h73/GJp/+qk53khrcH+4HxMmXG5u8u4v nxAMK2beqW1QhhcjWOtVyIbFSquFLGrV/4D9UXzyimPh921ZLutM2NeY3k93WR6/D/w6 rSuheWZMpZhCYeZy80rMbSghvYNLoOAVjkYBY= 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=FKkFoERye0Qk2mAM+PAXMHGxGZKBwpoLIKSbeAC6HpM=; b=szf4u+lFCTQOQEFVM+mJbqqYTXea3b1aJouStLigy1bk3PUfYxkf70LXYij3xmERPi UPs22XmYhPttwYQ9kX33dXfx0MZDR/4BIDR3p+WoIJJtzQwrvUDN+TrUTkvUN9JpnJni Nx9XaOwk3dzBQzENg/SOPvShHaNvP2jfaMtyFQ+ENTRe0aRgaemor2tbxhZDTHFFccr4 dpHwjRAWSlnbuZWBpPQIzJ2z1qtdasiX8J20mm8F0pX0MGQJAMAUMG5lsbE+VqQPMALs RZU1A8g8qPx7L1Fw4/0dSRZfsk11XW+zJ41xcfCwHblxReXiXhFqz1pbdpOjnPf4Vn1b gnUQ== X-Gm-Message-State: AJcUukf6peJ1817qAh8VPWxUackbrl2xz4mOl/yZjpm3I9OO4zwxPwaE VhBTVhbN374GQdCHrDJmR3c5cB0C X-Google-Smtp-Source: ALg8bN7ZRzhsoSY+krurd2e092fnBjYC2vQ1TzrQ5NzrHYo4i+LeCafOwSHs3hblr1fWpVld2O8iPA== X-Received: by 2002:adf:b502:: with SMTP id a2mr41317968wrd.54.1549032649250; Fri, 01 Feb 2019 06:50:49 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.47 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:48 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 08/11] Separate conf.py for each manual we want Date: Fri, 1 Feb 2019 14:50:32 +0000 Message-Id: <20190201145035.22739-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 --- 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 -- 2.20.1 Reviewed-by: Alex Bennée 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 Fri Feb 1 14:50:33 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157237 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527302jaa; Fri, 1 Feb 2019 06:50:51 -0800 (PST) X-Received: by 2002:a1c:f518:: with SMTP id t24mr2831912wmh.26.1549032651035; Fri, 01 Feb 2019 06:50:51 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032651; cv=none; d=google.com; s=arc-20160816; b=MQ/MDrRlU33cW414qlUZTU5FWLPJbpWqHrDHjqpt9jJdAmrjFIF7/A3p3/yLjVMiLB gb0Es8zx2lfrvZREaNdEPEPoYPnOGwj8pP+AZIOmoxvsaPE3ZoRcz5t+X+E1Bg0MbKzJ rJFw0K/tBHx7i/lxAPxjwX80zRWKDCj93f60q1R+B6GsappuukEsOJQyIDlH4KwHg0jc p2smN158Y5zHEgWFO0Crn0qOZ7wK98ok/X5dDMBqKxQWUl7auq8YdhA+5yNwqVI1ElkF hIJ4nVQ9znZCyEznyuB5NC7U6Z04qcQKtVBocUtca80X2JCDDjJiX5mAnXQuOTWEwdn6 nAlw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=vdwqp6tUu+2j46vNAuDpciGt92Qn8b7MicvO/kAG+Oo=; b=WnnaWMFa+4awUCRLt0P0tEoNA6wXJE8jS1lK+BM0sDnSpVDXfowqo2yJI00SLJ0HpP o1gdgVTd4LMiwThyfOPKNTUES6FbeoJdfB/iJB25IWPwYpOh9sPKI+hd8cvVeV+JBCQP f7Is1nBfVXHOT6zTInuswsx7ZG/fgWQ/9jzFZRwtMN28sktlSfT84CRgFi0JEDbNTPQS MVAXqBq4HmRMLZ8SbyRHXrnspskTpGKJB7gnmrZTXRhgNkpGNwMuUmkddxgn4XJOi3vo ohFSv2l4E3Ca53b3KeyI5H1LQHH3UyRNaQI7Kx5CUhZySBEjZkjt+3hVdH3jgOY+YJCy 7pTg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=VwogaEyG; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id t129sor1901282wmb.0.2019.02.01.06.50.50 for (Google Transport Security); Fri, 01 Feb 2019 06:50:50 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=VwogaEyG; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=vdwqp6tUu+2j46vNAuDpciGt92Qn8b7MicvO/kAG+Oo=; b=VwogaEyGmiizJ3OLVG35kfJiA+CBgmDDVGvWUKi4IS+UhpNJIc9HczmfUEIchnAx6C 9rGRvWqLqj7c+lLO3bUeVGk60hMjinAt/FeKlgQhFywM67ZVn0nHnSRw1uX6yAXRRetQ 00H30gMsqNTtNYz0bUsmZR2rDqsSkaxK6u8w4= 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=vdwqp6tUu+2j46vNAuDpciGt92Qn8b7MicvO/kAG+Oo=; b=pR+ZRot4ugjUcvh2gx6MnyD1nyZ5M0N/YXkLXEofqnIVMko2jkpFi6vSSAFw9jG8hE y6ywbuS6n1Hc6Kd8w8Yfs1IpB7neQpEc11+DbGRUlleE/3/Qx6OfrhJ1ZcYgUzDe6HoY M6NGJkVJRXGYaRqEdi2mNPAwMHHi7NaY745SLNnLMcriCaNN34yClW0K+zfwXayrWuxQ YVnl+dBn/RpvlMa+MN8ZbINBh71dKrK+htS45HdmefUu+qaXQrXdpmUfqLphCNtbEb2P Mxuio/g5eu2vnRWrJhEqGPFJRlv9eDUNoU6m8piqvJD0bpbazacLS73s29D2S6YLFwaJ kkxA== X-Gm-Message-State: AHQUAuYseb/3GYG6SKNaOWOX45x1PYHbQdjEDXUFbRxk9P8TkTKCEz5x 3x9uhyhL2DC86E/AuLG4KyNl/Zbh X-Google-Smtp-Source: AHgI3Iap+kHa8HcGaDf6VaC54MlooKl+22ypmNNilnsG8zCrAAtalhW5QNonqH6umqN/jKd/0FgcQA== X-Received: by 2002:a1c:f71a:: with SMTP id v26mr2604941wmh.131.1549032650526; Fri, 01 Feb 2019 06:50:50 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.49 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:49 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 09/11] Makefile, configure: Support building rST documentation Date: Fri, 1 Feb 2019 14:50:33 +0000 Message-Id: <20190201145035.22739-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- configure | 4 ++-- Makefile | 45 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 44 insertions(+), 5 deletions(-) -- 2.20.1 diff --git a/configure b/configure index b18281c61f3..9cd5c0cd0bd 100755 --- a/configure +++ b/configure @@ -4561,11 +4561,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 1278a3eb529..d519fadee39 100644 --- a/Makefile +++ b/Makefile @@ -387,7 +387,7 @@ dummy := $(call unnest-vars,, \ include $(SRC_PATH)/tests/Makefile.include -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules +all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules qemu-version.h: FORCE $(call quiet-command, \ @@ -631,6 +631,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 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 @@ -651,6 +659,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 @@ -684,7 +695,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)" @@ -835,6 +857,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","$@") @@ -863,7 +902,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 Fri Feb 1 14:50:34 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157238 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527333jaa; Fri, 1 Feb 2019 06:50:52 -0800 (PST) X-Received: by 2002:a1c:a895:: with SMTP id r143mr2647270wme.95.1549032652071; Fri, 01 Feb 2019 06:50:52 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032652; cv=none; d=google.com; s=arc-20160816; b=KcGu44y2ZTeakCobsG+NiWi75WzI5ytzZZudL6VwCmLyznWwheOie5G97dRi/Wouir uUYzQGCQSRNx3CD/uLUlRg8X3iGNvuexlKInO7Nc8b5NpIQo1V+GwzavOFNkH/mDWQcl zMg54ZfiP0c6fU4ygE0Yb3L/Vdaz6iK+ZDhqJIbfnPA58NxZKEgx44euy+kDMbD0XOmf iPJMMlJUPZOSHHzZQ5l78BiMUriZiKlf/AW76+6XrbBHA95nk376Ed+PAuQ9OFc0lM0L YmR7Ysy3r1D2RZwTheEEUaC6U8Ty90TpdYqEK/tH0V96ZdrW64iiMskXXqdvsrZs2DQ9 lHUg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=tg0YYMVzNWa7GJGbDhPTQaivAnAM9h0rP6Nqt+KE/Nk=; b=cpZ5ZR27orX9Mo/2+MLfPhvhPmx1rtPl+hrONi+idYtue6rRkfi5m8N87XzLAdF3Bb 0AuAEQH9Is/jf6DxXSiLt9eKN7l6fmu6h4uprPr2bjQap/WIYF6tKNjcTo9JZEhfzKCv EH13xlVbNNsm+xNps4R9VrqATfnWp6W+b0SfhrIX92N8543VtnMK3IUrULyAjdxLZIcb p7pWSFT3+IrayI57rhmK6vcFYI8v7GIz+j2nuuc7DN6jfi8iA+JIiTzyTojZefasi0BD JDceQQ3+1OKs2rLkUKqAA2OLtyYexdMgfm9DnNADlUobqI/P+d2qGAjQG6iMlhAbd9on E7Fg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=iKmAIU5L; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f41.google.com (mail-sor-f41.google.com. [209.85.220.41]) by mx.google.com with SMTPS id r201sor1877931wmb.26.2019.02.01.06.50.51 for (Google Transport Security); Fri, 01 Feb 2019 06:50:52 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) client-ip=209.85.220.41; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=iKmAIU5L; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=tg0YYMVzNWa7GJGbDhPTQaivAnAM9h0rP6Nqt+KE/Nk=; b=iKmAIU5LAwVhUvnfmCUxrF60O1+OzMhHK2dWiQePrXFmo0vr04qQTYTyGV6BQ0xdEn ERKST7PAbuHlwDSecl9nHPw6UrIQznpJiEi1NgxQvwQNAGsUltfopBpvhAMjs3CgSHAZ qvlCpkz2pBZ/N6n/AWjhXW7SisyWNw0E0LgiI= 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=tg0YYMVzNWa7GJGbDhPTQaivAnAM9h0rP6Nqt+KE/Nk=; b=SH1y+mTZBXTtawRlNN4hm+5yO38znDuzS+L+5Gq7mcs8h1+8JMl3K3cfDk8LyAovH1 OjG9AD39jk+hU5L74PndwFz5G++hO85SrJeRbWXfsBMuPbIkdOfqZcv6gU9hrpiJGns5 hjDpkrhxcBZUtxxKl9KayPQI612rMeWTjxtfwuhGV62KxcuJYWgqUVnEMhYj0hgOCamj 8dPy3DRNs/hiFGVRTBS/9KQObVWILxMjl8BRJQnq6ED3qAYap4z1R10KSw4I/qEqM6Ij 93ImvCidpQFyxdk8JUUbYVbzGZHwpw70pQN24rHd/RpZ7hN2x8VLp1hyeb8/UTFopQ5y e9Mg== X-Gm-Message-State: AHQUAuZXR6uBUmuuAIKKGbY6BLD/oS/lU0oJlxL97J7Gxm+sqPorIop6 rczIZrbBJniqYymQMsnDf08z6s3B X-Google-Smtp-Source: AHgI3IZ+FVmMSpXoFL96f7OWlbPNj1UG5KhVWRKivDKfGI1ldsvWOnWSfveOgjJPxxXes5eh/dr/Nw== X-Received: by 2002:a1c:2804:: with SMTP id o4mr2896368wmo.150.1549032651670; Fri, 01 Feb 2019 06:50:51 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.50 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:51 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 10/11] Makefile: Abstract out "identify the pkgversion" code Date: Fri, 1 Feb 2019 14:50:34 +0000 Message-Id: <20190201145035.22739-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- Makefile | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) -- 2.20.1 Reviewed-by: Alex Bennée diff --git a/Makefile b/Makefile index d519fadee39..2d19d28a271 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 #see Makefile.objs for the definition of QAPI_MODULES @@ -391,23 +405,8 @@ all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules 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 Fri Feb 1 14:50:35 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157239 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527378jaa; Fri, 1 Feb 2019 06:50:53 -0800 (PST) X-Received: by 2002:a1c:ab87:: with SMTP id u129mr2816422wme.104.1549032653582; Fri, 01 Feb 2019 06:50:53 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032653; cv=none; d=google.com; s=arc-20160816; b=vhjOm/Id5nak+5DkPdb8BMjGUro4pBB76wtc1BeehkWZ1e4x2wZyqY8pdP+8l/RKqO HmZuz/fScmQO+OC1m0tlmZT1SI5F2/Tnm3hht48rPEKjxdWMKnVZBgIqL8o/tJuBlkum fU9ueHuTvw/1YZEKpJbt5xgmeV5maSp3uv6FIu/66/LsnVn+pjM+4WzXgLc0Ke9/a8AM z7gAMUrawf5a3wqYWRANAhXdUajyAFlL6336Ov006n3dKoDx48sc2VRkx3MxGivqli0A ynTBE0T5Zz0oo88YUsEEMVuYpktWns5e26aNLOx8U72py8Gd1OKhZrm2pWSO5hij8kZf ki3Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=R3OZlwN0C+JurXZGsDqJU+0OVCxF+OtX907vOXRxbwU=; b=u8Z6P9Mv7Fijls494U0XMduHO59GOqW3nhbDgin7aYgMJqCZfOkvElNcr3Ge4SFiEF fVT4xPeShj2m89Mqy8OeaYKRf6xEXEgEjkcLB2kGxUdlg+kR+ZBfLMGGKkeGJ7F1SAY6 +5LUdDTTFrfHHj1UuaEZsEkHR1sfYnMZ8Agrls4g8Y06g8XXY4eTeV3QGAbtvXRHiBn0 z1y/SuO8R1qeEg6GDLLisVGKqLtXroUQxrWtAixo5fE0fw9vnM8qfkanJU7QMfyvUuOc TM4CDjBkZAnkSqXCCJKZ/j3h4vh91FMpOoV0MqTMsIYBH3hc6pI5djlmIduE6gRJO5ew MnGw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="A/AmVQ99"; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f41.google.com (mail-sor-f41.google.com. [209.85.220.41]) by mx.google.com with SMTPS id d11sor6035694wro.24.2019.02.01.06.50.53 for (Google Transport Security); Fri, 01 Feb 2019 06:50:53 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) client-ip=209.85.220.41; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b="A/AmVQ99"; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.41 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org 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=R3OZlwN0C+JurXZGsDqJU+0OVCxF+OtX907vOXRxbwU=; b=A/AmVQ99h3iW8+cFveSQAqJALKxlggqAIA0TJKked7Q/yTTFLjlQ5HCX7LQkx1b1mv nZ9Aj5sz+m2uFHUOet1HD+/lNc/b+R8iSJZGmpkVTwolB4Xt0CbPdZCQ4rsCn3gFOpSM y/o0ob+ggfg9HFIQuUjKNuureAd+JHDwdT3bU= 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=R3OZlwN0C+JurXZGsDqJU+0OVCxF+OtX907vOXRxbwU=; b=G9fdzvAGOIrC4rnMJooZDsKhQM71gVmbwSlT22OkbLhV7WuM1BmZXwq/0PUlc987FW TeXrnpY9450nIl1SwxMgd0mjrvBFfblBsuopL7CsPhBKQ5BheSwa79GnuGnhdwtoF8nQ 2dxSRvInhcVjxyJs7xhiY/BlXiOjvv4X4NGYD3Ud+DxufJuF07KJlI9CyuQPtj3YIlA9 KB9eJn5Ks/R41Lie9644hB62NOkQA6uzqt3P09RZfw94aEa+PX4BIGPwPKWhpmJfBALx t6jEh/jvWQ7OrqCCcmOb2ZbQ+wrSZg3KSeU9bQc01BDBLqefv8XHJ7KkFfixD6FhshWI +2lg== X-Gm-Message-State: AHQUAuZUSTDLrpE6DUdxGM5HEZKXuVb1xNG1kFDpb8U1MBNjY7ZzEYR1 NS2tn16vkniH3lF5WPa7qTep/GD3 X-Google-Smtp-Source: AHgI3IZyfkd3dVBz44k+DTbPMMm1vddyYsxWbrG/IUFyReYZYbDOQFH8WrsS2qipwL7mr7kbF6+hUg== X-Received: by 2002:adf:f648:: with SMTP id x8mr2246168wrp.235.1549032653241; Fri, 01 Feb 2019 06:50:53 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.51 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:52 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 11/11] docs/conf.py: Don't hard-code QEMU version Date: Fri, 1 Feb 2019 14:50:35 +0000 Message-Id: <20190201145035.22739-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- Makefile | 2 +- docs/conf.py | 21 ++++++++++++++++----- 2 files changed, 17 insertions(+), 6 deletions(-) -- 2.20.1 Reviewed-by: Alex Bennée diff --git a/Makefile b/Makefile index 2d19d28a271..e342242d268 100644 --- a/Makefile +++ b/Makefile @@ -863,7 +863,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.