From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:33709) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aSoiD-0001HP-IB for qemu-devel@nongnu.org; Mon, 08 Feb 2016 11:30:54 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aSoiC-0006gd-5m for qemu-devel@nongnu.org; Mon, 08 Feb 2016 11:30:53 -0500 Received: from mail-vk0-x235.google.com ([2607:f8b0:400c:c05::235]:36681) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aSoiB-0006gX-NJ for qemu-devel@nongnu.org; Mon, 08 Feb 2016 11:30:52 -0500 Received: by mail-vk0-x235.google.com with SMTP id c3so52226086vkb.3 for ; Mon, 08 Feb 2016 08:30:51 -0800 (PST) MIME-Version: 1.0 In-Reply-To: <1454007297-3971-1-git-send-email-peter.maydell@linaro.org> References: <1454007297-3971-1-git-send-email-peter.maydell@linaro.org> From: Peter Maydell Date: Mon, 8 Feb 2016 16:30:31 +0000 Message-ID: Content-Type: text/plain; charset=UTF-8 Subject: Re: [Qemu-devel] [PATCH] docs/memory.txt: Improve list of different memory regions List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: QEMU Developers Cc: Paolo Bonzini , Andrew Baumann , Patch Tracking Ping? thanks -- PMM On 28 January 2016 at 18:54, Peter Maydell wrote: > Improve the part of the memory region documentation which describes > the various different kinds of memory region: > * add the missing types ROM, IOMMU and reservation > * mention the functions used to initialize each type, as a hint > for finding the API docs and examples of use > > Signed-off-by: Peter Maydell > --- > docs/memory.txt | 26 +++++++++++++++++++++++++- > 1 file changed, 25 insertions(+), 1 deletion(-) > > diff --git a/docs/memory.txt b/docs/memory.txt > index 2ceb348..8745f76 100644 > --- a/docs/memory.txt > +++ b/docs/memory.txt > @@ -26,14 +26,28 @@ These represent memory as seen from the CPU or a device's viewpoint. > Types of regions > ---------------- > > -There are four types of memory regions (all represented by a single C type > +There are multiple types of memory regions (all represented by a single C type > MemoryRegion): > > - RAM: a RAM region is simply a range of host memory that can be made available > to the guest. > + You typically initialize these with memory_region_init_ram(). Some special > + purposes require the variants memory_region_init_resizeable_ram(), > + memory_region_init_ram_from_file(), or memory_region_init_ram_ptr(). > > - MMIO: a range of guest memory that is implemented by host callbacks; > each read or write causes a callback to be called on the host. > + You initialize these with memory_region_io(), passing it a MemoryRegionOps > + structure describing the callbacks. > + > +- ROM: a ROM memory region works like RAM for reads (directly accessing > + a region of host memory), but like MMIO for writes (invoking a callback). > + You initialize these with memory_region_init_rom_device(). > + > +- IOMMU region: an IOMMU region translates addresses of accesses made to it > + and forwards them to some other target memory region. As the name suggests, > + these are only needed for modelling an IOMMU, not for simple devices. > + You initialize these with memory_region_init_iommu(). > > - container: a container simply includes other memory regions, each at > a different offset. Containers are useful for grouping several regions > @@ -45,12 +59,22 @@ MemoryRegion): > can overlay a subregion of RAM with MMIO or ROM, or a PCI controller > that does not prevent card from claiming overlapping BARs. > > + You initialize a pure container with memory_region_init(). > + > - alias: a subsection of another region. Aliases allow a region to be > split apart into discontiguous regions. Examples of uses are memory banks > used when the guest address space is smaller than the amount of RAM > addressed, or a memory controller that splits main memory to expose a "PCI > hole". Aliases may point to any type of region, including other aliases, > but an alias may not point back to itself, directly or indirectly. > + You initialize these with memory_region_init_alias(). > + > +- reservation region: a reservation region is primarily for debugging. > + It claims I/O space that is not supposed to be handled by QEMU itself. > + The typical use is to track parts of the address space which will be > + handled by the host kernel when KVM is enabled. > + You initialize these with memory_region_init_reservation(), or by > + passing a NULL callback parameter to memory_region_init_io(). > > It is valid to add subregions to a region which is not a pure container > (that is, to an MMIO, RAM or ROM region). This means that the region > -- > 1.9.1 > >