]>
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 | ||
6f1ce94a PM |
55 | It is valid to add subregions to a region which is not a pure container |
56 | (that is, to an MMIO, RAM or ROM region). This means that the region | |
57 | will act like a container, except that any addresses within the container's | |
58 | region which are not claimed by any subregion are handled by the | |
59 | container itself (ie by its MMIO callbacks or RAM backing). However | |
60 | it is generally possible to achieve the same effect with a pure container | |
61 | one of whose subregions is a low priority "background" region covering | |
62 | the whole address range; this is often clearer and is preferred. | |
63 | Subregions cannot be added to an alias region. | |
9d3a4736 AK |
64 | |
65 | Region names | |
66 | ------------ | |
67 | ||
68 | Regions are assigned names by the constructor. For most regions these are | |
69 | only used for debugging purposes, but RAM regions also use the name to identify | |
70 | live migration sections. This means that RAM region names need to have ABI | |
71 | stability. | |
72 | ||
73 | Region lifecycle | |
74 | ---------------- | |
75 | ||
76 | A region is created by one of the constructor functions (memory_region_init*()) | |
d8d95814 PB |
77 | and attached to an object. It is then destroyed by object_unparent() or simply |
78 | when the parent object dies. | |
79 | ||
80 | In between, a region can be added to an address space | |
81 | by using memory_region_add_subregion() and removed using | |
82 | memory_region_del_subregion(). Destroying the region implicitly | |
83 | removes the region from the address space. | |
84 | ||
85 | Region attributes may be changed at any point; they take effect once | |
86 | the region becomes exposed to the guest. | |
9d3a4736 AK |
87 | |
88 | Overlapping regions and priority | |
89 | -------------------------------- | |
90 | Usually, regions may not overlap each other; a memory address decodes into | |
91 | exactly one target. In some cases it is useful to allow regions to overlap, | |
92 | and sometimes to control which of an overlapping regions is visible to the | |
93 | guest. This is done with memory_region_add_subregion_overlap(), which | |
94 | allows the region to overlap any other region in the same container, and | |
95 | specifies a priority that allows the core to decide which of two regions at | |
96 | the same address are visible (highest wins). | |
8002ccd6 MA |
97 | Priority values are signed, and the default value is zero. This means that |
98 | you can use memory_region_add_subregion_overlap() both to specify a region | |
99 | that must sit 'above' any others (with a positive priority) and also a | |
100 | background region that sits 'below' others (with a negative priority). | |
9d3a4736 | 101 | |
6f1ce94a PM |
102 | If the higher priority region in an overlap is a container or alias, then |
103 | the lower priority region will appear in any "holes" that the higher priority | |
104 | region has left by not mapping subregions to that area of its address range. | |
105 | (This applies recursively -- if the subregions are themselves containers or | |
106 | aliases that leave holes then the lower priority region will appear in these | |
107 | holes too.) | |
108 | ||
109 | For example, suppose we have a container A of size 0x8000 with two subregions | |
110 | B and C. B is a container mapped at 0x2000, size 0x4000, priority 1; C is | |
111 | an MMIO region mapped at 0x0, size 0x6000, priority 2. B currently has two | |
112 | of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at | |
113 | offset 0x2000. As a diagram: | |
114 | ||
115 | 0 1000 2000 3000 4000 5000 6000 7000 8000 | |
116 | |------|------|------|------|------|------|------|-------| | |
117 | A: [ ] | |
118 | C: [CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC] | |
119 | B: [ ] | |
120 | D: [DDDDD] | |
121 | E: [EEEEE] | |
122 | ||
123 | The regions that will be seen within this address range then are: | |
124 | [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] | |
125 | ||
126 | Since B has higher priority than C, its subregions appear in the flat map | |
127 | even where they overlap with C. In ranges where B has not mapped anything | |
128 | C's region appears. | |
129 | ||
130 | If B had provided its own MMIO operations (ie it was not a pure container) | |
131 | then these would be used for any addresses in its range not handled by | |
132 | D or E, and the result would be: | |
133 | [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] | |
134 | ||
135 | Priority values are local to a container, because the priorities of two | |
136 | regions are only compared when they are both children of the same container. | |
137 | This means that the device in charge of the container (typically modelling | |
138 | a bus or a memory controller) can use them to manage the interaction of | |
139 | its child regions without any side effects on other parts of the system. | |
140 | In the example above, the priorities of D and E are unimportant because | |
141 | they do not overlap each other. It is the relative priority of B and C | |
142 | that causes D and E to appear on top of C: D and E's priorities are never | |
143 | compared against the priority of C. | |
144 | ||
9d3a4736 AK |
145 | Visibility |
146 | ---------- | |
147 | The memory core uses the following rules to select a memory region when the | |
148 | guest accesses an address: | |
149 | ||
150 | - all direct subregions of the root region are matched against the address, in | |
151 | descending priority order | |
152 | - if the address lies outside the region offset/size, the subregion is | |
153 | discarded | |
6f1ce94a PM |
154 | - if the subregion is a leaf (RAM or MMIO), the search terminates, returning |
155 | this leaf region | |
9d3a4736 AK |
156 | - if the subregion is a container, the same algorithm is used within the |
157 | subregion (after the address is adjusted by the subregion offset) | |
6f1ce94a | 158 | - if the subregion is an alias, the search is continued at the alias target |
9d3a4736 | 159 | (after the address is adjusted by the subregion offset and alias offset) |
6f1ce94a PM |
160 | - if a recursive search within a container or alias subregion does not |
161 | find a match (because of a "hole" in the container's coverage of its | |
162 | address range), then if this is a container with its own MMIO or RAM | |
163 | backing the search terminates, returning the container itself. Otherwise | |
164 | we continue with the next subregion in priority order | |
165 | - if none of the subregions match the address then the search terminates | |
166 | with no match found | |
9d3a4736 AK |
167 | |
168 | Example memory map | |
169 | ------------------ | |
170 | ||
171 | system_memory: container@0-2^48-1 | |
172 | | | |
173 | +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) | |
174 | | | |
175 | +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffffff) | |
176 | | | |
177 | +---- vga-window: alias@0xa0000-0xbfffff ---> #pci (0xa0000-0xbffff) | |
178 | | (prio 1) | |
179 | | | |
180 | +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xffffffff) | |
181 | ||
182 | pci (0-2^32-1) | |
183 | | | |
184 | +--- vga-area: container@0xa0000-0xbffff | |
185 | | | | |
186 | | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) | |
187 | | | | |
188 | | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) | |
189 | | | |
190 | +---- vram: ram@0xe1000000-0xe1ffffff | |
191 | | | |
192 | +---- vga-mmio: mmio@0xe2000000-0xe200ffff | |
193 | ||
194 | ram: ram@0x00000000-0xffffffff | |
195 | ||
69ddaf66 | 196 | This is a (simplified) PC memory map. The 4GB RAM block is mapped into the |
9d3a4736 AK |
197 | system address space via two aliases: "lomem" is a 1:1 mapping of the first |
198 | 3.5GB; "himem" maps the last 0.5GB at address 4GB. This leaves 0.5GB for the | |
199 | so-called PCI hole, that allows a 32-bit PCI bus to exist in a system with | |
200 | 4GB of memory. | |
201 | ||
202 | The memory controller diverts addresses in the range 640K-768K to the PCI | |
7075ba30 | 203 | address space. This is modelled using the "vga-window" alias, mapped at a |
9d3a4736 AK |
204 | higher priority so it obscures the RAM at the same addresses. The vga window |
205 | can be removed by programming the memory controller; this is modelled by | |
206 | removing the alias and exposing the RAM underneath. | |
207 | ||
208 | The pci address space is not a direct child of the system address space, since | |
209 | we only want parts of it to be visible (we accomplish this using aliases). | |
210 | It has two subregions: vga-area models the legacy vga window and is occupied | |
211 | by two 32K memory banks pointing at two sections of the framebuffer. | |
212 | In addition the vram is mapped as a BAR at address e1000000, and an additional | |
213 | BAR containing MMIO registers is mapped after it. | |
214 | ||
215 | Note that if the guest maps a BAR outside the PCI hole, it would not be | |
216 | visible as the pci-hole alias clips it to a 0.5GB range. | |
217 | ||
218 | Attributes | |
219 | ---------- | |
220 | ||
221 | Various region attributes (read-only, dirty logging, coalesced mmio, ioeventfd) | |
222 | can be changed during the region lifecycle. They take effect once the region | |
223 | is made visible (which can be immediately, later, or never). | |
224 | ||
225 | MMIO Operations | |
226 | --------------- | |
227 | ||
228 | MMIO regions are provided with ->read() and ->write() callbacks; in addition | |
229 | various constraints can be supplied to control how these callbacks are called: | |
230 | ||
231 | - .valid.min_access_size, .valid.max_access_size define the access sizes | |
232 | (in bytes) which the device accepts; accesses outside this range will | |
233 | have device and bus specific behaviour (ignored, or machine check) | |
234 | - .valid.aligned specifies that the device only accepts naturally aligned | |
235 | accesses. Unaligned accesses invoke device and bus specific behaviour. | |
236 | - .impl.min_access_size, .impl.max_access_size define the access sizes | |
237 | (in bytes) supported by the *implementation*; other access sizes will be | |
238 | emulated using the ones available. For example a 4-byte write will be | |
69ddaf66 | 239 | emulated using four 1-byte writes, if .impl.max_access_size = 1. |
edc1ba7a FZ |
240 | - .impl.unaligned specifies that the *implementation* supports unaligned |
241 | accesses; if false, unaligned accesses will be emulated by two aligned | |
242 | accesses. | |
243 | - .old_mmio can be used to ease porting from code using | |
244 | cpu_register_io_memory(). It should not be used in new code. |