]>
Commit | Line | Data |
---|---|---|
9d3a4736 AK |
1 | The memory API |
2 | ============== | |
3 | ||
4 | The memory API models the memory and I/O buses and controllers of a QEMU | |
5 | machine. It attempts to allow modelling of: | |
6 | ||
7 | - ordinary RAM | |
8 | - memory-mapped I/O (MMIO) | |
9 | - memory controllers that can dynamically reroute physical memory regions | |
69ddaf66 | 10 | to different destinations |
9d3a4736 AK |
11 | |
12 | The memory model provides support for | |
13 | ||
14 | - tracking RAM changes by the guest | |
15 | - setting up coalesced memory for kvm | |
16 | - setting up ioeventfd regions for kvm | |
17 | ||
2d40178a PB |
18 | Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks |
19 | (leaves) are RAM and MMIO regions, while other nodes represent | |
20 | buses, memory controllers, and memory regions that have been rerouted. | |
21 | ||
22 | In addition to MemoryRegion objects, the memory API provides AddressSpace | |
23 | objects for every root and possibly for intermediate MemoryRegions too. | |
24 | These represent memory as seen from the CPU or a device's viewpoint. | |
9d3a4736 AK |
25 | |
26 | Types of regions | |
27 | ---------------- | |
28 | ||
29 | There are four types of memory regions (all represented by a single C type | |
30 | MemoryRegion): | |
31 | ||
32 | - RAM: a RAM region is simply a range of host memory that can be made available | |
33 | to the guest. | |
34 | ||
35 | - MMIO: a range of guest memory that is implemented by host callbacks; | |
36 | each read or write causes a callback to be called on the host. | |
37 | ||
38 | - container: a container simply includes other memory regions, each at | |
39 | a different offset. Containers are useful for grouping several regions | |
40 | into one unit. For example, a PCI BAR may be composed of a RAM region | |
41 | and an MMIO region. | |
42 | ||
43 | A container's subregions are usually non-overlapping. In some cases it is | |
44 | useful to have overlapping regions; for example a memory controller that | |
45 | can overlay a subregion of RAM with MMIO or ROM, or a PCI controller | |
46 | that does not prevent card from claiming overlapping BARs. | |
47 | ||
48 | - alias: a subsection of another region. Aliases allow a region to be | |
49 | split apart into discontiguous regions. Examples of uses are memory banks | |
50 | used when the guest address space is smaller than the amount of RAM | |
51 | addressed, or a memory controller that splits main memory to expose a "PCI | |
52 | hole". Aliases may point to any type of region, including other aliases, | |
53 | but an alias may not point back to itself, directly or indirectly. | |
54 | ||
55 | ||
56 | Region names | |
57 | ------------ | |
58 | ||
59 | Regions are assigned names by the constructor. For most regions these are | |
60 | only used for debugging purposes, but RAM regions also use the name to identify | |
61 | live migration sections. This means that RAM region names need to have ABI | |
62 | stability. | |
63 | ||
64 | Region lifecycle | |
65 | ---------------- | |
66 | ||
67 | A region is created by one of the constructor functions (memory_region_init*()) | |
68 | and destroyed by the destructor (memory_region_destroy()). In between, | |
69 | a region can be added to an address space by using memory_region_add_subregion() | |
70 | and removed using memory_region_del_subregion(). Region attributes may be | |
71 | changed at any point; they take effect once the region becomes exposed to the | |
72 | guest. | |
73 | ||
74 | Overlapping regions and priority | |
75 | -------------------------------- | |
76 | Usually, regions may not overlap each other; a memory address decodes into | |
77 | exactly one target. In some cases it is useful to allow regions to overlap, | |
78 | and sometimes to control which of an overlapping regions is visible to the | |
79 | guest. This is done with memory_region_add_subregion_overlap(), which | |
80 | allows the region to overlap any other region in the same container, and | |
81 | specifies a priority that allows the core to decide which of two regions at | |
82 | the same address are visible (highest wins). | |
8002ccd6 MA |
83 | Priority values are signed, and the default value is zero. This means that |
84 | you can use memory_region_add_subregion_overlap() both to specify a region | |
85 | that must sit 'above' any others (with a positive priority) and also a | |
86 | background region that sits 'below' others (with a negative priority). | |
9d3a4736 AK |
87 | |
88 | Visibility | |
89 | ---------- | |
90 | The memory core uses the following rules to select a memory region when the | |
91 | guest accesses an address: | |
92 | ||
93 | - all direct subregions of the root region are matched against the address, in | |
94 | descending priority order | |
95 | - if the address lies outside the region offset/size, the subregion is | |
96 | discarded | |
7075ba30 | 97 | - if the subregion is a leaf (RAM or MMIO), the search terminates |
9d3a4736 AK |
98 | - if the subregion is a container, the same algorithm is used within the |
99 | subregion (after the address is adjusted by the subregion offset) | |
100 | - if the subregion is an alias, the search is continues at the alias target | |
101 | (after the address is adjusted by the subregion offset and alias offset) | |
102 | ||
103 | Example memory map | |
104 | ------------------ | |
105 | ||
106 | system_memory: container@0-2^48-1 | |
107 | | | |
108 | +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) | |
109 | | | |
110 | +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) | |
111 | | | |
112 | +---- vga-window: alias@0xa0000-0xbfffff ---> #pci (0xa0000-0xbffff) | |
113 | | (prio 1) | |
114 | | | |
115 | +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) | |
116 | ||
117 | pci (0-2^32-1) | |
118 | | | |
119 | +--- vga-area: container@0xa0000-0xbffff | |
120 | | | | |
121 | | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) | |
122 | | | | |
123 | | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) | |
124 | | | |
125 | +---- vram: ram@0xe1000000-0xe1ffffff | |
126 | | | |
127 | +---- vga-mmio: mmio@0xe2000000-0xe200ffff | |
128 | ||
129 | ram: ram@0x00000000-0xffffffff | |
130 | ||
69ddaf66 | 131 | This is a (simplified) PC memory map. The 4GB RAM block is mapped into the |
9d3a4736 AK |
132 | system address space via two aliases: "lomem" is a 1:1 mapping of the first |
133 | 3.5GB; "himem" maps the last 0.5GB at address 4GB. This leaves 0.5GB for the | |
134 | so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with | |
135 | 4GB of memory. | |
136 | ||
137 | The memory controller diverts addresses in the range 640K-768K to the PCI | |
7075ba30 | 138 | address space. This is modelled using the "vga-window" alias, mapped at a |
9d3a4736 AK |
139 | higher priority so it obscures the RAM at the same addresses. The vga window |
140 | can be removed by programming the memory controller; this is modelled by | |
141 | removing the alias and exposing the RAM underneath. | |
142 | ||
143 | The pci address space is not a direct child of the system address space, since | |
144 | we only want parts of it to be visible (we accomplish this using aliases). | |
145 | It has two subregions: vga-area models the legacy vga window and is occupied | |
146 | by two 32K memory banks pointing at two sections of the framebuffer. | |
147 | In addition the vram is mapped as a BAR at address e1000000, and an additional | |
148 | BAR containing MMIO registers is mapped after it. | |
149 | ||
150 | Note that if the guest maps a BAR outside the PCI hole, it would not be | |
151 | visible as the pci-hole alias clips it to a 0.5GB range. | |
152 | ||
153 | Attributes | |
154 | ---------- | |
155 | ||
156 | Various region attributes (read-only, dirty logging, coalesced mmio, ioeventfd) | |
157 | can be changed during the region lifecycle. They take effect once the region | |
158 | is made visible (which can be immediately, later, or never). | |
159 | ||
160 | MMIO Operations | |
161 | --------------- | |
162 | ||
163 | MMIO regions are provided with ->read() and ->write() callbacks; in addition | |
164 | various constraints can be supplied to control how these callbacks are called: | |
165 | ||
166 | - .valid.min_access_size, .valid.max_access_size define the access sizes | |
167 | (in bytes) which the device accepts; accesses outside this range will | |
168 | have device and bus specific behaviour (ignored, or machine check) | |
169 | - .valid.aligned specifies that the device only accepts naturally aligned | |
170 | accesses. Unaligned accesses invoke device and bus specific behaviour. | |
171 | - .impl.min_access_size, .impl.max_access_size define the access sizes | |
172 | (in bytes) supported by the *implementation*; other access sizes will be | |
173 | emulated using the ones available. For example a 4-byte write will be | |
69ddaf66 | 174 | emulated using four 1-byte writes, if .impl.max_access_size = 1. |
9d3a4736 AK |
175 | - .impl.valid specifies that the *implementation* only supports unaligned |
176 | accesses; unaligned accesses will be emulated by two aligned accesses. | |
177 | - .old_portio and .old_mmio can be used to ease porting from code using | |
178 | cpu_register_io_memory() and register_ioport(). They should not be used | |
179 | in new code. |