diff options
author | Peter Maydell <peter.maydell@linaro.org> | 2016-01-28 18:54:57 +0000 |
---|---|---|
committer | Paolo Bonzini <pbonzini@redhat.com> | 2016-02-09 15:46:55 +0100 |
commit | 5056c0c3de73c4d804a62d473039bc439718777d (patch) | |
tree | 306b5d0b057923e27d91afe1563877bde7f09d62 /docs | |
parent | 37eebb8693368d890b700cca6e39ec31c7e980e5 (diff) | |
download | qemu-5056c0c3de73c4d804a62d473039bc439718777d.zip qemu-5056c0c3de73c4d804a62d473039bc439718777d.tar.gz qemu-5056c0c3de73c4d804a62d473039bc439718777d.tar.bz2 |
docs/memory.txt: Improve list of different memory regions
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 <peter.maydell@linaro.org>
Message-Id: <1454007297-3971-1-git-send-email-peter.maydell@linaro.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/memory.txt | 26 |
1 files changed, 25 insertions, 1 deletions
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 |