docs/devel/memory.rst

8 - ordinary RAM
9 - memory-mapped I/O (MMIO)
10 - memory controllers that can dynamically reroute physical memory regions
15 - tracking RAM changes by the guest
16 - setting up coalesced memory for kvm
17 - setting up ioeventfd regions for kvm
28 ----------------
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;
44 - ROM: a ROM memory region works like RAM for reads (directly accessing
48 - ROM device: a ROM device memory region works like RAM for reads
53 - IOMMU region: an IOMMU region translates addresses of accesses made to it
58 - container: a container simply includes other memory regions, each at
63   A container's subregions are usually non-overlapping.  In some cases it is
70 - alias: a subsection of another region. Aliases allow a region to be
82 - reservation region: a reservation region is primarily for debugging.
99 ---------
107 - memory_region_init_ram()
108 - memory_region_init_rom()
109 - memory_region_init_rom_device()
115 - memory_region_init_ram_nomigrate()
116 - memory_region_init_rom_nomigrate()
117 - memory_region_init_rom_device_nomigrate()
124 - memory_region_init_resizeable_ram()
125 - memory_region_init_ram_from_file()
126 - memory_region_init_ram_from_fd()
127 - memory_region_init_ram_ptr()
128 - memory_region_init_ram_device_ptr()
135 ------------
143 ----------------
156 Various region attributes (read-only, dirty logging, coalesced mmio,
179 - the memory region's owner had a reference taken via memory_region_ref
182 - the region is unparented, and has no owner anymore
184 - when address_space_unmap is called, the reference to the memory region's
200 For regions that "have no owner" (NULL is passed at creation time), the
203 on regions that have no owner, unless they are aliases or containers.
207 --------------------------------
223 (This applies recursively -- if the subregions are themselves containers or
234         |------|------|------|------|------|------|------|------|
266 ----------
270 - all direct subregions of the root region are matched against the address, in
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
279   - if the subregion is an alias, the search is continued at the alias target
281   - if a recursive search within a container or alias subregion does not
287 - if none of the subregions match the address then the search terminates
288   with no match found
291 ------------------
295   system_memory: container@0-2^48-1
297    +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff)
299    +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff)
301    +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff)
304    +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff)
306   pci (0-2^32-1)
308    +--- vga-area: container@0xa0000-0xbffff
310    |      +--- alias@0x00000-0x7fff  ---> #vram (0x010000-0x017fff)
312    |      +--- alias@0x08000-0xffff  ---> #vram (0x020000-0x027fff)
314    +---- vram: ram@0xe1000000-0xe1ffffff
316    +---- vga-mmio: mmio@0xe2000000-0xe200ffff
318   ram: ram@0x00000000-0xffffffff
323 so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with
326 The memory controller diverts addresses in the range 640K-768K to the PCI
327 address space.  This is modelled using the "vga-window" alias, mapped at a
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
340 visible as the pci-hole alias clips it to a 0.5GB range.
343 ---------------
345 MMIO regions are provided with ->read() and ->write() callbacks,
348 to be able to respond that the access should provoke a bus error
350 ->read_with_attrs() and ->write_with_attrs() callbacks instead.
355 - .valid.min_access_size, .valid.max_access_size define the access sizes
358 - .valid.unaligned specifies that the *device being modelled* supports
359   unaligned accesses; if false, unaligned accesses will invoke the
361 - .impl.min_access_size, .impl.max_access_size define the access sizes
362   (in bytes) supported by the *implementation*; other access sizes will be
363   emulated using the ones available.  For example a 4-byte write will be
364   emulated using four 1-byte writes, if .impl.max_access_size = 1.
365 - .impl.unaligned specifies that the *implementation* supports unaligned
366   accesses; if false, unaligned accesses will be emulated by two aligned
370 -------------
372 .. kernel-doc:: include/exec/memory.h