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
64   useful to have overlapping regions; for example a memory controller that
66   that does not prevent card from claiming overlapping BARs.
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
206 Overlapping regions and priority
207 --------------------------------
210 and sometimes to control which of an overlapping regions is visible to the
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
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
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,
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
361 - .impl.min_access_size, .impl.max_access_size define the access sizes
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
370 -------------
372 .. kernel-doc:: include/exec/memory.h