2 * Physical memory management API
4 * Copyright 2011 Red Hat, Inc. and/or its affiliates
7 * Avi Kivity <avi@redhat.com>
9 * This work is licensed under the terms of the GNU GPL, version 2. See
10 * the COPYING file in the top-level directory.
17 #ifndef CONFIG_USER_ONLY
21 #include "qemu-common.h"
22 #include "cpu-common.h"
24 #include "qemu-queue.h"
28 typedef struct MemoryRegionOps MemoryRegionOps
;
29 typedef struct MemoryRegion MemoryRegion
;
30 typedef struct MemoryRegionPortio MemoryRegionPortio
;
31 typedef struct MemoryRegionMmio MemoryRegionMmio
;
33 /* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
36 #define DIRTY_MEMORY_VGA 0
37 #define DIRTY_MEMORY_CODE 1
38 #define DIRTY_MEMORY_MIGRATION 3
40 struct MemoryRegionMmio
{
41 CPUReadMemoryFunc
*read
[3];
42 CPUWriteMemoryFunc
*write
[3];
46 * Memory region callbacks
48 struct MemoryRegionOps
{
49 /* Read from the memory region. @addr is relative to @mr; @size is
51 uint64_t (*read
)(void *opaque
,
52 target_phys_addr_t addr
,
54 /* Write to the memory region. @addr is relative to @mr; @size is
56 void (*write
)(void *opaque
,
57 target_phys_addr_t addr
,
61 enum device_endian endianness
;
62 /* Guest-visible constraints: */
64 /* If nonzero, specify bounds on access sizes beyond which a machine
67 unsigned min_access_size
;
68 unsigned max_access_size
;
69 /* If true, unaligned accesses are supported. Otherwise unaligned
70 * accesses throw machine checks.
74 /* Internal implementation constraints: */
76 /* If nonzero, specifies the minimum size implemented. Smaller sizes
77 * will be rounded upwards and a partial result will be returned.
79 unsigned min_access_size
;
80 /* If nonzero, specifies the maximum size implemented. Larger sizes
81 * will be done as a series of accesses with smaller sizes.
83 unsigned max_access_size
;
84 /* If true, unaligned accesses are supported. Otherwise all accesses
85 * are converted to (possibly multiple) naturally aligned accesses.
90 /* If .read and .write are not present, old_portio may be used for
91 * backwards compatibility with old portio registration
93 const MemoryRegionPortio
*old_portio
;
94 /* If .read and .write are not present, old_mmio may be used for
95 * backwards compatibility with old mmio registration
97 const MemoryRegionMmio old_mmio
;
100 typedef struct CoalescedMemoryRange CoalescedMemoryRange
;
102 struct MemoryRegion
{
103 /* All fields are private - violators will be prosecuted */
104 const MemoryRegionOps
*ops
;
106 MemoryRegion
*parent
;
108 target_phys_addr_t addr
;
109 target_phys_addr_t offset
;
110 bool backend_registered
;
115 target_phys_addr_t alias_offset
;
118 QTAILQ_HEAD(subregions
, MemoryRegion
) subregions
;
119 QTAILQ_ENTRY(MemoryRegion
) subregions_link
;
120 QTAILQ_HEAD(coalesced_ranges
, CoalescedMemoryRange
) coalesced
;
122 uint8_t dirty_log_mask
;
125 struct MemoryRegionPortio
{
129 IOPortReadFunc
*read
;
130 IOPortWriteFunc
*write
;
133 #define PORTIO_END { }
136 * memory_region_init: Initialize a memory region
138 * The region typically acts as a container for other memory regions. Us
139 * memory_region_add_subregion() to add subregions.
141 * @mr: the #MemoryRegion to be initialized
142 * @name: used for debugging; not visible to the user or ABI
143 * @size: size of the region; any subregions beyond this size will be clipped
145 void memory_region_init(MemoryRegion
*mr
,
149 * memory_region_init_io: Initialize an I/O memory region.
151 * Accesses into the region will be cause the callbacks in @ops to be called.
152 * if @size is nonzero, subregions will be clipped to @size.
154 * @mr: the #MemoryRegion to be initialized.
155 * @ops: a structure containing read and write callbacks to be used when
156 * I/O is performed on the region.
157 * @opaque: passed to to the read and write callbacks of the @ops structure.
158 * @name: used for debugging; not visible to the user or ABI
159 * @size: size of the region.
161 void memory_region_init_io(MemoryRegion
*mr
,
162 const MemoryRegionOps
*ops
,
168 * memory_region_init_ram: Initialize RAM memory region. Accesses into the
169 * region will be modify memory directly.
171 * @mr: the #MemoryRegion to be initialized.
172 * @dev: a device associated with the region; may be %NULL.
173 * @name: the name of the region; the pair (@dev, @name) must be globally
174 * unique. The name is part of the save/restore ABI and so cannot be
176 * @size: size of the region.
178 void memory_region_init_ram(MemoryRegion
*mr
,
179 DeviceState
*dev
, /* FIXME: layering violation */
184 * memory_region_init_ram: Initialize RAM memory region from a user-provided.
185 * pointer. Accesses into the region will be modify
188 * @mr: the #MemoryRegion to be initialized.
189 * @dev: a device associated with the region; may be %NULL.
190 * @name: the name of the region; the pair (@dev, @name) must be globally
191 * unique. The name is part of the save/restore ABI and so cannot be
193 * @size: size of the region.
194 * @ptr: memory to be mapped; must contain at least @size bytes.
196 void memory_region_init_ram_ptr(MemoryRegion
*mr
,
197 DeviceState
*dev
, /* FIXME: layering violation */
203 * memory_region_init_alias: Initialize a memory region that aliases all or a
204 * part of another memory region.
206 * @mr: the #MemoryRegion to be initialized.
207 * @name: used for debugging; not visible to the user or ABI
208 * @orig: the region to be referenced; @mr will be equivalent to
209 * @orig between @offset and @offset + @size - 1.
210 * @offset: start of the section in @orig to be referenced.
211 * @size: size of the region.
213 void memory_region_init_alias(MemoryRegion
*mr
,
216 target_phys_addr_t offset
,
219 * memory_region_destroy: Destroy a memory region and relaim all resources.
221 * @mr: the region to be destroyed. May not currently be a subregion
222 * (see memory_region_add_subregion()) or referenced in an alias
223 * (see memory_region_init_alias()).
225 void memory_region_destroy(MemoryRegion
*mr
);
228 * memory_region_size: get a memory region's size.
230 * @mr: the memory region being queried.
232 uint64_t memory_region_size(MemoryRegion
*mr
);
235 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
237 * Returns a host pointer to a RAM memory region (created with
238 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
241 * @mr: the memory region being queried.
243 void *memory_region_get_ram_ptr(MemoryRegion
*mr
);
246 * memory_region_set_offset: Sets an offset to be added to MemoryRegionOps
249 * This function is deprecated and should not be used in new code.
251 void memory_region_set_offset(MemoryRegion
*mr
, target_phys_addr_t offset
);
254 * memory_region_set_log: Turn dirty logging on or off for a region.
256 * Turns dirty logging on or off for a specified client (display, migration).
257 * Only meaningful for RAM regions.
259 * @mr: the memory region being updated.
260 * @log: whether dirty logging is to be enabled or disabled.
261 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
264 void memory_region_set_log(MemoryRegion
*mr
, bool log
, unsigned client
);
267 * memory_region_get_dirty: Check whether a page is dirty for a specified
270 * Checks whether a page has been written to since the last
271 * call to memory_region_reset_dirty() with the same @client. Dirty logging
274 * @mr: the memory region being queried.
275 * @addr: the address (relative to the start of the region) being queried.
276 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
279 bool memory_region_get_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
283 * memory_region_set_dirty: Mark a page as dirty in a memory region.
285 * Marks a page as dirty, after it has been dirtied outside guest code.
287 * @mr: the memory region being queried.
288 * @addr: the address (relative to the start of the region) being dirtied.
290 void memory_region_set_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
);
293 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
294 * any external TLBs (e.g. kvm)
296 * Flushes dirty information from accelerators such as kvm and vhost-net
297 * and makes it available to users of the memory API.
299 * @mr: the region being flushed.
301 void memory_region_sync_dirty_bitmap(MemoryRegion
*mr
);
304 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
307 * Marks a range of pages as no longer dirty.
309 * @mr: the region being updated.
310 * @addr: the start of the subrange being cleaned.
311 * @size: the size of the subrange being cleaned.
312 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
315 void memory_region_reset_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
316 target_phys_addr_t size
, unsigned client
);
319 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
321 * Allows a memory region to be marked as read-only (turning it into a ROM).
322 * only useful on RAM regions.
324 * @mr: the region being updated.
325 * @readonly: whether rhe region is to be ROM or RAM.
327 void memory_region_set_readonly(MemoryRegion
*mr
, bool readonly
);
330 * memory_region_set_coalescing: Enable memory coalescing for the region.
332 * Enabled writes to a region to be queued for later processing. MMIO ->write
333 * callbacks may be delayed until a non-coalesced MMIO is issued.
334 * Only useful for IO regions. Roughly similar to write-combining hardware.
336 * @mr: the memory region to be write coalesced
338 void memory_region_set_coalescing(MemoryRegion
*mr
);
341 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
344 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
345 * Multiple calls can be issued coalesced disjoint ranges.
347 * @mr: the memory region to be updated.
348 * @offset: the start of the range within the region to be coalesced.
349 * @size: the size of the subrange to be coalesced.
351 void memory_region_add_coalescing(MemoryRegion
*mr
,
352 target_phys_addr_t offset
,
356 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
358 * Disables any coalescing caused by memory_region_set_coalescing() or
359 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
362 * @mr: the memory region to be updated.
364 void memory_region_clear_coalescing(MemoryRegion
*mr
);
367 * memory_region_add_subregion: Add a sub-region to a container.
369 * Adds a sub-region at @offset. The sub-region may not overlap with other
370 * subregions (except for those explicitly marked as overlapping). A region
371 * may only be added once as a subregion (unless removed with
372 * memory_region_del_subregion()); use memory_region_init_alias() if you
373 * want a region to be a subregion in multiple locations.
375 * @mr: the region to contain the new subregion; must be a container
376 * initialized with memory_region_init().
377 * @offset: the offset relative to @mr where @subregion is added.
378 * @subregion: the subregion to be added.
380 void memory_region_add_subregion(MemoryRegion
*mr
,
381 target_phys_addr_t offset
,
382 MemoryRegion
*subregion
);
384 * memory_region_add_subregion: Add a sub-region to a container, with overlap.
386 * Adds a sub-region at @offset. The sub-region may overlap with other
387 * subregions. Conflicts are resolved by having a higher @priority hide a
388 * lower @priority. Subregions without priority are taken as @priority 0.
389 * A region may only be added once as a subregion (unless removed with
390 * memory_region_del_subregion()); use memory_region_init_alias() if you
391 * want a region to be a subregion in multiple locations.
393 * @mr: the region to contain the new subregion; must be a container
394 * initialized with memory_region_init().
395 * @offset: the offset relative to @mr where @subregion is added.
396 * @subregion: the subregion to be added.
397 * @priority: used for resolving overlaps; highest priority wins.
399 void memory_region_add_subregion_overlap(MemoryRegion
*mr
,
400 target_phys_addr_t offset
,
401 MemoryRegion
*subregion
,
404 * memory_region_del_subregion: Remove a subregion.
406 * Removes a subregion from its container.
408 * @mr: the container to be updated.
409 * @subregion: the region being removed; must be a current subregion of @mr.
411 void memory_region_del_subregion(MemoryRegion
*mr
,
412 MemoryRegion
*subregion
);