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