docs/devel/memory.rst

19 Memory is modelled as an acyclic graph of MemoryRegion objects.  Sinks
33 - RAM: a RAM region is simply a range of host memory that can be made available
39 - MMIO: a range of guest memory that is implemented by host callbacks;
63   A container's subregions are usually non-overlapping.  In some cases it is
72   banks used when the guest address space is smaller than the amount
82 - reservation region: a reservation region is primarily for debugging.
83   It claims I/O space that is not supposed to be handled by QEMU itself.
84   The typical use is to track parts of the address space which will be
85   handled by the host kernel when KVM is enabled.  You initialize these
88 It is valid to add subregions to a region which is not a pure container
89 (that is, to an MMIO, RAM or ROM region). This means that the region
93 it is generally possible to achieve the same effect with a pure container
94 one of whose subregions is a low priority "background" region covering
95 the whole address range; this is often clearer and is preferred.
101 Where the memory region is backed by host memory (RAM, ROM and
104 the host memory for you will also register the memory so it is
111 For most devices and boards this is the correct thing. If you
145 A region is created by one of the memory_region_init*() functions and
147 that the owner object remains alive as long as the region is visible to
148 the guest, or as long as the region is in use by a virtual CPU or another
158 as soon as the region is made visible.  This can be immediately, later,
164 If however the memory region is part of a dynamically allocated data
166 before the data structure is freed.  For an example see VFIOMSIXInfo
182 - the region is unparented, and has no owner anymore
184 - when address_space_unmap is called, the reference to the memory region's
185   owner is leaked.
188 There is an exception to the above rule: it is okay to call
189 object_unparent at any time for an alias or a container region.  It is
193 This exceptional usage is valid because aliases and containers only help
197 this exception is rarely necessary, and therefore it is discouraged,
198 but nevertheless it is used in a few places.
200 For regions that "have no owner" (NULL is passed at creation time), the
201 machine object is actually used as the owner.  Since instance_finalize is
209 exactly one target.  In some cases it is useful to allow regions to overlap,
210 and sometimes to control which of an overlapping regions is visible to the
211 guest.  This is done with memory_region_add_subregion_overlap(), which
215 Priority values are signed, and the default value is zero. This means that
220 If the higher priority region in an overlap is a container or alias, then
228 B and C. B is a container mapped at 0x2000, size 0x4000, priority 2; C is
261 they do not overlap each other. It is the relative priority of B and C
273   - if the address lies outside the region offset/size, the subregion is
275   - if the subregion is a leaf (RAM or MMIO), the search terminates, returning
277   - if the subregion is a container, the same algorithm is used within the
278     subregion (after the address is adjusted by the subregion offset)
279   - if the subregion is an alias, the search is continued at the alias target
280     (after the address is adjusted by the subregion offset and alias offset)
283     address range), then if this is a container with its own MMIO or RAM
320 This is a (simplified) PC memory map. The 4GB RAM block is mapped into the
321 system address space via two aliases: "lomem" is a 1:1 mapping of the first
327 address space.  This is modelled using the "vga-window" alias, mapped at a
329 can be removed by programming the memory controller; this is modelled by
332 The pci address space is not a direct child of the system address space, since
334 It has two subregions: vga-area models the legacy vga window and is occupied
336 In addition the vram is mapped as a BAR at address e1000000, and an additional
337 BAR containing MMIO registers is mapped after it.