From patchwork Thu Mar 7 15:24:40 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 159864 Delivered-To: patch@linaro.org Received: by 2002:a02:5cc1:0:0:0:0:0 with SMTP id w62csp7569189jad; Thu, 7 Mar 2019 07:31:49 -0800 (PST) X-Google-Smtp-Source: APXvYqyhTketJJwWnIlOsqIsl/3vCjdjAtGVYtMDlW0acZhlqG2OKucyyrNWQsjcTx7XxQj3UJAz X-Received: by 2002:a25:9d07:: with SMTP id i7mr11526238ybp.454.1551972709387; Thu, 07 Mar 2019 07:31:49 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1551972709; cv=none; d=google.com; s=arc-20160816; b=B9mreOOLXhj2mOQyRcgpOQEV8rO7xsvdy6ctVvMygccLyaMZtkT9cde8Xid0v0VYF1 Tv0qXkvDJAvjL9xm9l7KBWsnyduzkFdytYvSwGeKQamw+IogLqh/rJ2GJ4wj06OLPp+U IJQCOWSDcPC0+hv5RuY3NWTzqJhwLZslZDKz9jziPEnCPpzBG4zHaI8AMQU58nDmpZKH H6rHyJqraq1NG1b0xBbivjaryGSqc9IeiwDPQ/a6XQiXPBZg6+p3c08dgno8W+Oo/xQR MoMpIy5QXNYYijBt0/jh9ZjU74UY5XbGYcpkTIPIChHT33KdMzV+2pxYfudxFXqI+KcI WSoA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=ouZcEyHHWbCH9g8wiJ8EsWwJ4cRIXkH+whqTdb4h1Xw=; b=L71lQyks6GOyKTocHquOeJevAnGenXVuqMEUN3hBZ0FEdqpVqvqv6/0VMcZFOZJ6lr QH1Cw9hUYDACx9pBiKoTpYbl69hNziS7Bb1/n1tmnSWjHzEt66vnyVTWBwgWw6Qp+6Wn JMSHW5NY418lzYFLtWx2L6Bhf8M9yvCHLTpN120wDoTzXoZo3gac3busS++pXvYCp1Hv OHBUsBoSb2x4QL5k/zx5kZQ4rRbOUC2gj+B6k9G/wGr2qQngo+Ro9MmycDK3r6ZgjmvF tFkH3gVCEiXb3aRBUUViZ6pKrLhkISRUlD/4/aQ/MoT0KJDCGtO8XqNjzw+XL1V/mp3E f1AQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=GXiEpH9k; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id d139si3073114ywb.251.2019.03.07.07.31.49 for (version=TLS1 cipher=AES128-SHA bits=128/128); Thu, 07 Mar 2019 07:31:49 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=GXiEpH9k; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:53888 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1uzs-0008Tk-Pi for patch@linaro.org; Thu, 07 Mar 2019 10:31:48 -0500 Received: from eggs.gnu.org ([209.51.188.92]:33891) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1utF-0002XJ-Vm for qemu-devel@nongnu.org; Thu, 07 Mar 2019 10:24:59 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h1utE-0004mB-HT for qemu-devel@nongnu.org; Thu, 07 Mar 2019 10:24:57 -0500 Received: from mail-wm1-x343.google.com ([2a00:1450:4864:20::343]:38501) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h1utE-0004lL-7a for qemu-devel@nongnu.org; Thu, 07 Mar 2019 10:24:56 -0500 Received: by mail-wm1-x343.google.com with SMTP id a188so9577618wmf.3 for ; Thu, 07 Mar 2019 07:24:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; bh=ouZcEyHHWbCH9g8wiJ8EsWwJ4cRIXkH+whqTdb4h1Xw=; b=GXiEpH9k2OjWIJQE3RNxVjzDV2nnHx2B9zY2uhyXnfs46TKXIdPKo0Q/WR2+hhXAdc 6D3lu24DtQLC/vYJuWcw/S1Lqy/Qv5FkiPcEiybDlILgNNLsAKcXHXWVeqbkGNr8fb6Y cmhefK3LdHnEigeH0mmNu/L2ynztExu5hBcvmtan8ksuGWS9VSpxyIDu0kx5kFrYG8VH 6DOIFzfOLEXgbrpjGRrHK/bGrrrexjTMOOc2rNZmNjzz3VGWSBwGSHR7Ugc/1mWTir2c DhV9wU9n7Pa03D58yEiaU98BV1csZPuqmVtyHX7FqmrjP6F7CgdoZlSjaxd9F0f+sTdu bopw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=ouZcEyHHWbCH9g8wiJ8EsWwJ4cRIXkH+whqTdb4h1Xw=; b=dky6njDKwDVIfhQuJhMrf/1uqcKeYzlZOjk3uMB3CiXchTCdQdg71NaNWW3tE6PXCe jDsEMEmXDXAincWWsfJpAGKLBLic3xoRTj5C+4jZEQsUQ91N7WxFcL/85a1Q+SRHDnob jR/bhky4VVcyLRVap7L+RqA4wx9UR2JWzVjBpVY4wwz/7rZTTbe/0XenhtS4V9vGJ2Kr wBdDlgzWkWM5p8pbMPcpUux66cgFeAaCcX7xuIKua4ftlmKmg01GC+I+wzHcgPYRF7P+ 51MT8nGnLX/fyQUPMvI0rtH+NNKYjEuBmlDL6iscOMhjuHt/NQKTH/t4AYwAvEumj5+X Swrg== X-Gm-Message-State: APjAAAVpbr5YBFyGmRWPuLIvnu+spgatQmQQZG9GQ8IZcuzuu+XvNbme pfSMyFx7yambDy4qHhJ47w4nakA+fZo= X-Received: by 2002:a05:600c:2210:: with SMTP id z16mr5992797wml.57.1551972294663; Thu, 07 Mar 2019 07:24:54 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d1sm5338345wrs.13.2019.03.07.07.24.53 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 07 Mar 2019 07:24:53 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 7 Mar 2019 15:24:40 +0000 Message-Id: <20190307152450.20340-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190307152450.20340-1-peter.maydell@linaro.org> References: <20190307152450.20340-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::343 Subject: [Qemu-devel] [PULL 02/12] 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: , Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" 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 Acked-by: Aleksandar Markovic Reviewed-by: Richard Henderson Reviewed-by: Cleber Rosa Message-id: 20190305172139.32662-3-peter.maydell@linaro.org Message-id: 20190228145624.24885-3-peter.maydell@linaro.org --- 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 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.