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
;
101 typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd
;
103 struct MemoryRegion
{
104 /* All fields are private - violators will be prosecuted */
105 const MemoryRegionOps
*ops
;
107 MemoryRegion
*parent
;
109 target_phys_addr_t addr
;
110 target_phys_addr_t offset
;
111 bool backend_registered
;
112 void (*destructor
)(MemoryRegion
*mr
);
117 target_phys_addr_t alias_offset
;
120 QTAILQ_HEAD(subregions
, MemoryRegion
) subregions
;
121 QTAILQ_ENTRY(MemoryRegion
) subregions_link
;
122 QTAILQ_HEAD(coalesced_ranges
, CoalescedMemoryRange
) coalesced
;
124 uint8_t dirty_log_mask
;
125 unsigned ioeventfd_nb
;
126 MemoryRegionIoeventfd
*ioeventfds
;
129 struct MemoryRegionPortio
{
133 IOPortReadFunc
*read
;
134 IOPortWriteFunc
*write
;
137 #define PORTIO_END_OF_LIST() { }
140 * memory_region_init: Initialize a memory region
142 * The region typically acts as a container for other memory regions. Us
143 * memory_region_add_subregion() to add subregions.
145 * @mr: the #MemoryRegion to be initialized
146 * @name: used for debugging; not visible to the user or ABI
147 * @size: size of the region; any subregions beyond this size will be clipped
149 void memory_region_init(MemoryRegion
*mr
,
153 * memory_region_init_io: Initialize an I/O memory region.
155 * Accesses into the region will be cause the callbacks in @ops to be called.
156 * if @size is nonzero, subregions will be clipped to @size.
158 * @mr: the #MemoryRegion to be initialized.
159 * @ops: a structure containing read and write callbacks to be used when
160 * I/O is performed on the region.
161 * @opaque: passed to to the read and write callbacks of the @ops structure.
162 * @name: used for debugging; not visible to the user or ABI
163 * @size: size of the region.
165 void memory_region_init_io(MemoryRegion
*mr
,
166 const MemoryRegionOps
*ops
,
172 * memory_region_init_ram: Initialize RAM memory region. Accesses into the
173 * region will be modify memory directly.
175 * @mr: the #MemoryRegion to be initialized.
176 * @dev: a device associated with the region; may be %NULL.
177 * @name: the name of the region; the pair (@dev, @name) must be globally
178 * unique. The name is part of the save/restore ABI and so cannot be
180 * @size: size of the region.
182 void memory_region_init_ram(MemoryRegion
*mr
,
183 DeviceState
*dev
, /* FIXME: layering violation */
188 * memory_region_init_ram: Initialize RAM memory region from a user-provided.
189 * pointer. Accesses into the region will be modify
192 * @mr: the #MemoryRegion to be initialized.
193 * @dev: a device associated with the region; may be %NULL.
194 * @name: the name of the region; the pair (@dev, @name) must be globally
195 * unique. The name is part of the save/restore ABI and so cannot be
197 * @size: size of the region.
198 * @ptr: memory to be mapped; must contain at least @size bytes.
200 void memory_region_init_ram_ptr(MemoryRegion
*mr
,
201 DeviceState
*dev
, /* FIXME: layering violation */
207 * memory_region_init_alias: Initialize a memory region that aliases all or a
208 * part of another memory region.
210 * @mr: the #MemoryRegion to be initialized.
211 * @name: used for debugging; not visible to the user or ABI
212 * @orig: the region to be referenced; @mr will be equivalent to
213 * @orig between @offset and @offset + @size - 1.
214 * @offset: start of the section in @orig to be referenced.
215 * @size: size of the region.
217 void memory_region_init_alias(MemoryRegion
*mr
,
220 target_phys_addr_t offset
,
223 * memory_region_destroy: Destroy a memory region and relaim all resources.
225 * @mr: the region to be destroyed. May not currently be a subregion
226 * (see memory_region_add_subregion()) or referenced in an alias
227 * (see memory_region_init_alias()).
229 void memory_region_destroy(MemoryRegion
*mr
);
232 * memory_region_size: get a memory region's size.
234 * @mr: the memory region being queried.
236 uint64_t memory_region_size(MemoryRegion
*mr
);
239 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
241 * Returns a host pointer to a RAM memory region (created with
242 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
245 * @mr: the memory region being queried.
247 void *memory_region_get_ram_ptr(MemoryRegion
*mr
);
250 * memory_region_set_offset: Sets an offset to be added to MemoryRegionOps
253 * This function is deprecated and should not be used in new code.
255 void memory_region_set_offset(MemoryRegion
*mr
, target_phys_addr_t offset
);
258 * memory_region_set_log: Turn dirty logging on or off for a region.
260 * Turns dirty logging on or off for a specified client (display, migration).
261 * Only meaningful for RAM regions.
263 * @mr: the memory region being updated.
264 * @log: whether dirty logging is to be enabled or disabled.
265 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
268 void memory_region_set_log(MemoryRegion
*mr
, bool log
, unsigned client
);
271 * memory_region_get_dirty: Check whether a page is dirty for a specified
274 * Checks whether a page has been written to since the last
275 * call to memory_region_reset_dirty() with the same @client. Dirty logging
278 * @mr: the memory region being queried.
279 * @addr: the address (relative to the start of the region) being queried.
280 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
283 bool memory_region_get_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
287 * memory_region_set_dirty: Mark a page as dirty in a memory region.
289 * Marks a page as dirty, after it has been dirtied outside guest code.
291 * @mr: the memory region being queried.
292 * @addr: the address (relative to the start of the region) being dirtied.
294 void memory_region_set_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
);
297 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
298 * any external TLBs (e.g. kvm)
300 * Flushes dirty information from accelerators such as kvm and vhost-net
301 * and makes it available to users of the memory API.
303 * @mr: the region being flushed.
305 void memory_region_sync_dirty_bitmap(MemoryRegion
*mr
);
308 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
311 * Marks a range of pages as no longer dirty.
313 * @mr: the region being updated.
314 * @addr: the start of the subrange being cleaned.
315 * @size: the size of the subrange being cleaned.
316 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
319 void memory_region_reset_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
320 target_phys_addr_t size
, unsigned client
);
323 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
325 * Allows a memory region to be marked as read-only (turning it into a ROM).
326 * only useful on RAM regions.
328 * @mr: the region being updated.
329 * @readonly: whether rhe region is to be ROM or RAM.
331 void memory_region_set_readonly(MemoryRegion
*mr
, bool readonly
);
334 * memory_region_set_coalescing: Enable memory coalescing for the region.
336 * Enabled writes to a region to be queued for later processing. MMIO ->write
337 * callbacks may be delayed until a non-coalesced MMIO is issued.
338 * Only useful for IO regions. Roughly similar to write-combining hardware.
340 * @mr: the memory region to be write coalesced
342 void memory_region_set_coalescing(MemoryRegion
*mr
);
345 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
348 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
349 * Multiple calls can be issued coalesced disjoint ranges.
351 * @mr: the memory region to be updated.
352 * @offset: the start of the range within the region to be coalesced.
353 * @size: the size of the subrange to be coalesced.
355 void memory_region_add_coalescing(MemoryRegion
*mr
,
356 target_phys_addr_t offset
,
360 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
362 * Disables any coalescing caused by memory_region_set_coalescing() or
363 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
366 * @mr: the memory region to be updated.
368 void memory_region_clear_coalescing(MemoryRegion
*mr
);
371 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
372 * is written to a location.
374 * Marks a word in an IO region (initialized with memory_region_init_io())
375 * as a trigger for an eventfd event. The I/O callback will not be called.
376 * The caller must be prepared to handle failure (hat is, take the required
377 * action if the callback _is_ called).
379 * @mr: the memory region being updated.
380 * @addr: the address within @mr that is to be monitored
381 * @size: the size of the access to trigger the eventfd
382 * @match_data: whether to match against @data, instead of just @addr
383 * @data: the data to match against the guest write
384 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
386 void memory_region_add_eventfd(MemoryRegion
*mr
,
387 target_phys_addr_t addr
,
394 * memory_region_del_eventfd: Cancel and eventfd.
396 * Cancels an eventfd trigger request by a previous memory_region_add_eventfd()
399 * @mr: the memory region being updated.
400 * @addr: the address within @mr that is to be monitored
401 * @size: the size of the access to trigger the eventfd
402 * @match_data: whether to match against @data, instead of just @addr
403 * @data: the data to match against the guest write
404 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
406 void memory_region_del_eventfd(MemoryRegion
*mr
,
407 target_phys_addr_t addr
,
413 * memory_region_add_subregion: Add a sub-region to a container.
415 * Adds a sub-region at @offset. The sub-region may not overlap with other
416 * subregions (except for those explicitly marked as overlapping). A region
417 * may only be added once as a subregion (unless removed with
418 * memory_region_del_subregion()); use memory_region_init_alias() if you
419 * want a region to be a subregion in multiple locations.
421 * @mr: the region to contain the new subregion; must be a container
422 * initialized with memory_region_init().
423 * @offset: the offset relative to @mr where @subregion is added.
424 * @subregion: the subregion to be added.
426 void memory_region_add_subregion(MemoryRegion
*mr
,
427 target_phys_addr_t offset
,
428 MemoryRegion
*subregion
);
430 * memory_region_add_subregion: Add a sub-region to a container, with overlap.
432 * Adds a sub-region at @offset. The sub-region may overlap with other
433 * subregions. Conflicts are resolved by having a higher @priority hide a
434 * lower @priority. Subregions without priority are taken as @priority 0.
435 * A region may only be added once as a subregion (unless removed with
436 * memory_region_del_subregion()); use memory_region_init_alias() if you
437 * want a region to be a subregion in multiple locations.
439 * @mr: the region to contain the new subregion; must be a container
440 * initialized with memory_region_init().
441 * @offset: the offset relative to @mr where @subregion is added.
442 * @subregion: the subregion to be added.
443 * @priority: used for resolving overlaps; highest priority wins.
445 void memory_region_add_subregion_overlap(MemoryRegion
*mr
,
446 target_phys_addr_t offset
,
447 MemoryRegion
*subregion
,
450 * memory_region_del_subregion: Remove a subregion.
452 * Removes a subregion from its container.
454 * @mr: the container to be updated.
455 * @subregion: the region being removed; must be a current subregion of @mr.
457 void memory_region_del_subregion(MemoryRegion
*mr
,
458 MemoryRegion
*subregion
);
460 /* Start a transaction; changes will be accumulated and made visible only
461 * when the transaction ends.
463 void memory_region_transaction_begin(void);
464 /* Commit a transaction and make changes visible to the guest.
466 void memory_region_transaction_commit(void);