| 1 | ============== |
| 2 | The memory API |
| 3 | ============== |
| 4 | |
| 5 | The memory API models the memory and I/O buses and controllers of a QEMU |
| 6 | machine. It attempts to allow modelling of: |
| 7 | |
| 8 | - ordinary RAM |
| 9 | - memory-mapped I/O (MMIO) |
| 10 | - memory controllers that can dynamically reroute physical memory regions |
| 11 | to different destinations |
| 12 | |
| 13 | The memory model provides support for |
| 14 | |
| 15 | - tracking RAM changes by the guest |
| 16 | - setting up coalesced memory for kvm |
| 17 | - setting up ioeventfd regions for kvm |
| 18 | |
| 19 | Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks |
| 20 | (leaves) are RAM and MMIO regions, while other nodes represent |
| 21 | buses, memory controllers, and memory regions that have been rerouted. |
| 22 | |
| 23 | In addition to MemoryRegion objects, the memory API provides AddressSpace |
| 24 | objects for every root and possibly for intermediate MemoryRegions too. |
| 25 | These represent memory as seen from the CPU or a device's viewpoint. |
| 26 | |
| 27 | Types of regions |
| 28 | ---------------- |
| 29 | |
| 30 | There are multiple types of memory regions (all represented by a single C type |
| 31 | MemoryRegion): |
| 32 | |
| 33 | - RAM: a RAM region is simply a range of host memory that can be made available |
| 34 | to the guest. |
| 35 | You typically initialize these with memory_region_init_ram(). Some special |
| 36 | purposes require the variants memory_region_init_resizeable_ram(), |
| 37 | memory_region_init_ram_from_file(), or memory_region_init_ram_ptr(). |
| 38 | |
| 39 | - MMIO: a range of guest memory that is implemented by host callbacks; |
| 40 | each read or write causes a callback to be called on the host. |
| 41 | You initialize these with memory_region_init_io(), passing it a |
| 42 | MemoryRegionOps structure describing the callbacks. |
| 43 | |
| 44 | - ROM: a ROM memory region works like RAM for reads (directly accessing |
| 45 | a region of host memory), and forbids writes. You initialize these with |
| 46 | memory_region_init_rom(). |
| 47 | |
| 48 | - ROM device: a ROM device memory region works like RAM for reads |
| 49 | (directly accessing a region of host memory), but like MMIO for |
| 50 | writes (invoking a callback). You initialize these with |
| 51 | memory_region_init_rom_device(). |
| 52 | |
| 53 | - IOMMU region: an IOMMU region translates addresses of accesses made to it |
| 54 | and forwards them to some other target memory region. As the name suggests, |
| 55 | these are only needed for modelling an IOMMU, not for simple devices. |
| 56 | You initialize these with memory_region_init_iommu(). |
| 57 | |
| 58 | - container: a container simply includes other memory regions, each at |
| 59 | a different offset. Containers are useful for grouping several regions |
| 60 | into one unit. For example, a PCI BAR may be composed of a RAM region |
| 61 | and an MMIO region. |
| 62 | |
| 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 |
| 65 | can overlay a subregion of RAM with MMIO or ROM, or a PCI controller |
| 66 | that does not prevent card from claiming overlapping BARs. |
| 67 | |
| 68 | You initialize a pure container with memory_region_init(). |
| 69 | |
| 70 | - alias: a subsection of another region. Aliases allow a region to be |
| 71 | split apart into discontiguous regions. Examples of uses are memory |
| 72 | banks used when the guest address space is smaller than the amount |
| 73 | of RAM addressed, or a memory controller that splits main memory to |
| 74 | expose a "PCI hole". You can also create aliases to avoid trying to |
| 75 | add the original region to multiple parents via |
| 76 | `memory_region_add_subregion`. |
| 77 | |
| 78 | Aliases may point to any type of region, including other aliases, |
| 79 | but an alias may not point back to itself, directly or indirectly. |
| 80 | You initialize these with memory_region_init_alias(). |
| 81 | |
| 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 |
| 86 | by passing a NULL callback parameter to memory_region_init_io(). |
| 87 | |
| 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 |
| 90 | will act like a container, except that any addresses within the container's |
| 91 | region which are not claimed by any subregion are handled by the |
| 92 | container itself (ie by its MMIO callbacks or RAM backing). However |
| 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. |
| 96 | Subregions cannot be added to an alias region. |
| 97 | |
| 98 | Migration |
| 99 | --------- |
| 100 | |
| 101 | Where the memory region is backed by host memory (RAM, ROM and |
| 102 | ROM device memory region types), this host memory needs to be |
| 103 | copied to the destination on migration. These APIs which allocate |
| 104 | the host memory for you will also register the memory so it is |
| 105 | migrated: |
| 106 | |
| 107 | - memory_region_init_ram() |
| 108 | - memory_region_init_rom() |
| 109 | - memory_region_init_rom_device() |
| 110 | |
| 111 | For most devices and boards this is the correct thing. If you |
| 112 | have a special case where you need to manage the migration of |
| 113 | the backing memory yourself, you can call the function |
| 114 | memory_region_init_ram_flags_nomigrate() |
| 115 | which only initializes the MemoryRegion and leaves handling |
| 116 | migration to the caller. |
| 117 | |
| 118 | The functions: |
| 119 | |
| 120 | - memory_region_init_resizeable_ram() |
| 121 | - memory_region_init_ram_from_file() |
| 122 | - memory_region_init_ram_from_fd() |
| 123 | - memory_region_init_ram_ptr() |
| 124 | - memory_region_init_ram_device_ptr() |
| 125 | |
| 126 | are for special cases only, and so they do not automatically |
| 127 | register the backing memory for migration; the caller must |
| 128 | manage migration if necessary. |
| 129 | |
| 130 | Region names |
| 131 | ------------ |
| 132 | |
| 133 | Regions are assigned names by the constructor. For most regions these are |
| 134 | only used for debugging purposes, but RAM regions also use the name to identify |
| 135 | live migration sections. This means that RAM region names need to have ABI |
| 136 | stability. |
| 137 | |
| 138 | Region lifecycle |
| 139 | ---------------- |
| 140 | |
| 141 | A region is created by one of the memory_region_init*() functions and |
| 142 | attached to an object, which acts as its owner or parent. QEMU ensures |
| 143 | that the owner object remains alive as long as the region is visible to |
| 144 | the guest, or as long as the region is in use by a virtual CPU or another |
| 145 | device. For example, the owner object will not die between an |
| 146 | address_space_map operation and the corresponding address_space_unmap. |
| 147 | |
| 148 | After creation, a region can be added to an address space or a |
| 149 | container with memory_region_add_subregion(), and removed using |
| 150 | memory_region_del_subregion(). |
| 151 | |
| 152 | Various region attributes (read-only, dirty logging, coalesced mmio, |
| 153 | ioeventfd) can be changed during the region lifecycle. They take effect |
| 154 | as soon as the region is made visible. This can be immediately, later, |
| 155 | or never. |
| 156 | |
| 157 | Destruction of a memory region happens automatically when the owner object |
| 158 | dies. When there are multiple memory regions under the same owner object, |
| 159 | the memory API will guarantee all memory regions will be properly detached |
| 160 | and finalized one by one. The order in which memory regions will be |
| 161 | finalized is not guaranteed. |
| 162 | |
| 163 | If however the memory region is part of a dynamically allocated data |
| 164 | structure, you should free the memory region in the instance_finalize |
| 165 | callback. For an example see VFIOMSIXInfo and VFIOQuirk in |
| 166 | hw/vfio/pci.c. |
| 167 | |
| 168 | You must not destroy a memory region as long as it may be in use by a |
| 169 | device or CPU. In order to do this, as a general rule do not create or |
| 170 | destroy memory regions dynamically during a device's lifetime, and never |
| 171 | call object_unparent(). |
| 172 | |
| 173 | If you break this rule, the following situation can happen: |
| 174 | |
| 175 | - the memory region's owner had a reference taken via memory_region_ref |
| 176 | (for example by address_space_map) |
| 177 | |
| 178 | - the region is unparented, and has no owner anymore |
| 179 | |
| 180 | - when address_space_unmap is called, the reference to the memory region's |
| 181 | owner is leaked. |
| 182 | |
| 183 | |
| 184 | There is an exception to the above rule: it is okay to call |
| 185 | object_unparent at any time for an alias or a container region. It is |
| 186 | therefore also okay to create or destroy alias and container regions |
| 187 | dynamically during a device's lifetime. |
| 188 | |
| 189 | This exceptional usage is valid because aliases and containers only help |
| 190 | QEMU building the guest's memory map; they are never accessed directly. |
| 191 | memory_region_ref and memory_region_unref are never called on aliases |
| 192 | or containers, and the above situation then cannot happen. Exploiting |
| 193 | this exception is rarely necessary, and therefore it is discouraged, |
| 194 | but nevertheless it is used in a few places. |
| 195 | |
| 196 | For regions that "have no owner" (NULL is passed at creation time), the |
| 197 | machine object is actually used as the owner. |
| 198 | |
| 199 | |
| 200 | Overlapping regions and priority |
| 201 | -------------------------------- |
| 202 | Usually, regions may not overlap each other; a memory address decodes into |
| 203 | exactly one target. In some cases it is useful to allow regions to overlap, |
| 204 | and sometimes to control which of an overlapping regions is visible to the |
| 205 | guest. This is done with memory_region_add_subregion_overlap(), which |
| 206 | allows the region to overlap any other region in the same container, and |
| 207 | specifies a priority that allows the core to decide which of two regions at |
| 208 | the same address are visible (highest wins). |
| 209 | Priority values are signed, and the default value is zero. This means that |
| 210 | you can use memory_region_add_subregion_overlap() both to specify a region |
| 211 | that must sit 'above' any others (with a positive priority) and also a |
| 212 | background region that sits 'below' others (with a negative priority). |
| 213 | |
| 214 | If the higher priority region in an overlap is a container or alias, then |
| 215 | the lower priority region will appear in any "holes" that the higher priority |
| 216 | region has left by not mapping subregions to that area of its address range. |
| 217 | (This applies recursively -- if the subregions are themselves containers or |
| 218 | aliases that leave holes then the lower priority region will appear in these |
| 219 | holes too.) |
| 220 | |
| 221 | For example, suppose we have a container A of size 0x8000 with two subregions |
| 222 | B and C. B is a container mapped at 0x2000, size 0x4000, priority 2; C is |
| 223 | an MMIO region mapped at 0x0, size 0x6000, priority 1. B currently has two |
| 224 | of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at |
| 225 | offset 0x2000. As a diagram:: |
| 226 | |
| 227 | 0 1000 2000 3000 4000 5000 6000 7000 8000 |
| 228 | |------|------|------|------|------|------|------|------| |
| 229 | A: [ ] |
| 230 | C: [CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC] |
| 231 | B: [ ] |
| 232 | D: [DDDDD] |
| 233 | E: [EEEEE] |
| 234 | |
| 235 | The regions that will be seen within this address range then are:: |
| 236 | |
| 237 | [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] |
| 238 | |
| 239 | Since B has higher priority than C, its subregions appear in the flat map |
| 240 | even where they overlap with C. In ranges where B has not mapped anything |
| 241 | C's region appears. |
| 242 | |
| 243 | If B had provided its own MMIO operations (ie it was not a pure container) |
| 244 | then these would be used for any addresses in its range not handled by |
| 245 | D or E, and the result would be:: |
| 246 | |
| 247 | [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] |
| 248 | |
| 249 | Priority values are local to a container, because the priorities of two |
| 250 | regions are only compared when they are both children of the same container. |
| 251 | This means that the device in charge of the container (typically modelling |
| 252 | a bus or a memory controller) can use them to manage the interaction of |
| 253 | its child regions without any side effects on other parts of the system. |
| 254 | In the example above, the priorities of D and E are unimportant because |
| 255 | they do not overlap each other. It is the relative priority of B and C |
| 256 | that causes D and E to appear on top of C: D and E's priorities are never |
| 257 | compared against the priority of C. |
| 258 | |
| 259 | Visibility |
| 260 | ---------- |
| 261 | The memory core uses the following rules to select a memory region when the |
| 262 | guest accesses an address: |
| 263 | |
| 264 | - all direct subregions of the root region are matched against the address, in |
| 265 | descending priority order |
| 266 | |
| 267 | - if the address lies outside the region offset/size, the subregion is |
| 268 | discarded |
| 269 | - if the subregion is a leaf (RAM or MMIO), the search terminates, returning |
| 270 | this leaf region |
| 271 | - if the subregion is a container, the same algorithm is used within the |
| 272 | subregion (after the address is adjusted by the subregion offset) |
| 273 | - if the subregion is an alias, the search is continued at the alias target |
| 274 | (after the address is adjusted by the subregion offset and alias offset) |
| 275 | - if a recursive search within a container or alias subregion does not |
| 276 | find a match (because of a "hole" in the container's coverage of its |
| 277 | address range), then if this is a container with its own MMIO or RAM |
| 278 | backing the search terminates, returning the container itself. Otherwise |
| 279 | we continue with the next subregion in priority order |
| 280 | |
| 281 | - if none of the subregions match the address then the search terminates |
| 282 | with no match found |
| 283 | |
| 284 | Example memory map |
| 285 | ------------------ |
| 286 | |
| 287 | :: |
| 288 | |
| 289 | system_memory: container@0-2^48-1 |
| 290 | | |
| 291 | +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) |
| 292 | | |
| 293 | +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) |
| 294 | | |
| 295 | +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) |
| 296 | | (prio 1) |
| 297 | | |
| 298 | +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) |
| 299 | |
| 300 | pci (0-2^32-1) |
| 301 | | |
| 302 | +--- vga-area: container@0xa0000-0xbffff |
| 303 | | | |
| 304 | | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) |
| 305 | | | |
| 306 | | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) |
| 307 | | |
| 308 | +---- vram: ram@0xe1000000-0xe1ffffff |
| 309 | | |
| 310 | +---- vga-mmio: mmio@0xe2000000-0xe200ffff |
| 311 | |
| 312 | ram: ram@0x00000000-0xffffffff |
| 313 | |
| 314 | This is a (simplified) PC memory map. The 4GB RAM block is mapped into the |
| 315 | system address space via two aliases: "lomem" is a 1:1 mapping of the first |
| 316 | 3.5GB; "himem" maps the last 0.5GB at address 4GB. This leaves 0.5GB for the |
| 317 | so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with |
| 318 | 4GB of memory. |
| 319 | |
| 320 | The memory controller diverts addresses in the range 640K-768K to the PCI |
| 321 | address space. This is modelled using the "vga-window" alias, mapped at a |
| 322 | higher priority so it obscures the RAM at the same addresses. The vga window |
| 323 | can be removed by programming the memory controller; this is modelled by |
| 324 | removing the alias and exposing the RAM underneath. |
| 325 | |
| 326 | The pci address space is not a direct child of the system address space, since |
| 327 | we only want parts of it to be visible (we accomplish this using aliases). |
| 328 | It has two subregions: vga-area models the legacy vga window and is occupied |
| 329 | by two 32K memory banks pointing at two sections of the framebuffer. |
| 330 | In addition the vram is mapped as a BAR at address e1000000, and an additional |
| 331 | BAR containing MMIO registers is mapped after it. |
| 332 | |
| 333 | Note that if the guest maps a BAR outside the PCI hole, it would not be |
| 334 | visible as the pci-hole alias clips it to a 0.5GB range. |
| 335 | |
| 336 | MMIO Operations |
| 337 | --------------- |
| 338 | |
| 339 | MMIO regions are provided with ->read() and ->write() callbacks, |
| 340 | which are sufficient for most devices. Some devices change behaviour |
| 341 | based on the attributes used for the memory transaction, or need |
| 342 | to be able to respond that the access should provoke a bus error |
| 343 | rather than completing successfully; those devices can use the |
| 344 | ->read_with_attrs() and ->write_with_attrs() callbacks instead. |
| 345 | |
| 346 | In addition various constraints can be supplied to control how these |
| 347 | callbacks are called: |
| 348 | |
| 349 | - .valid.min_access_size, .valid.max_access_size define the access sizes |
| 350 | (in bytes) which the device accepts; accesses outside this range will |
| 351 | have device and bus specific behaviour (ignored, or machine check) |
| 352 | - .valid.unaligned specifies that the *device being modelled* supports |
| 353 | unaligned accesses; if false, unaligned accesses will invoke the |
| 354 | appropriate bus or CPU specific behaviour. |
| 355 | - .impl.min_access_size, .impl.max_access_size define the access sizes |
| 356 | (in bytes) supported by the *implementation*; other access sizes will be |
| 357 | emulated using the ones available. For example a 4-byte write will be |
| 358 | emulated using four 1-byte writes, if .impl.max_access_size = 1. |
| 359 | - .impl.unaligned specifies that the *implementation* supports unaligned |
| 360 | accesses; if false, unaligned accesses will be emulated by two aligned |
| 361 | accesses. |
| 362 | |
| 363 | API Reference |
| 364 | ------------- |
| 365 | |
| 366 | .. kernel-doc:: include/system/memory.h |