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"
29 typedef struct MemoryRegionOps MemoryRegionOps
;
30 typedef struct MemoryRegion MemoryRegion
;
31 typedef struct MemoryRegionPortio MemoryRegionPortio
;
32 typedef struct MemoryRegionMmio MemoryRegionMmio
;
34 /* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
37 #define DIRTY_MEMORY_VGA 0
38 #define DIRTY_MEMORY_CODE 1
39 #define DIRTY_MEMORY_MIGRATION 3
41 struct MemoryRegionMmio
{
42 CPUReadMemoryFunc
*read
[3];
43 CPUWriteMemoryFunc
*write
[3];
46 /* Internal use; thunks between old-style IORange and MemoryRegions. */
47 typedef struct MemoryRegionIORange MemoryRegionIORange
;
48 struct MemoryRegionIORange
{
51 target_phys_addr_t offset
;
55 * Memory region callbacks
57 struct MemoryRegionOps
{
58 /* Read from the memory region. @addr is relative to @mr; @size is
60 uint64_t (*read
)(void *opaque
,
61 target_phys_addr_t addr
,
63 /* Write to the memory region. @addr is relative to @mr; @size is
65 void (*write
)(void *opaque
,
66 target_phys_addr_t addr
,
70 enum device_endian endianness
;
71 /* Guest-visible constraints: */
73 /* If nonzero, specify bounds on access sizes beyond which a machine
76 unsigned min_access_size
;
77 unsigned max_access_size
;
78 /* If true, unaligned accesses are supported. Otherwise unaligned
79 * accesses throw machine checks.
83 * If present, and returns #false, the transaction is not accepted
84 * by the device (and results in machine dependent behaviour such
85 * as a machine check exception).
87 bool (*accepts
)(void *opaque
, target_phys_addr_t addr
,
88 unsigned size
, bool is_write
);
90 /* Internal implementation constraints: */
92 /* If nonzero, specifies the minimum size implemented. Smaller sizes
93 * will be rounded upwards and a partial result will be returned.
95 unsigned min_access_size
;
96 /* If nonzero, specifies the maximum size implemented. Larger sizes
97 * will be done as a series of accesses with smaller sizes.
99 unsigned max_access_size
;
100 /* If true, unaligned accesses are supported. Otherwise all accesses
101 * are converted to (possibly multiple) naturally aligned accesses.
106 /* If .read and .write are not present, old_portio may be used for
107 * backwards compatibility with old portio registration
109 const MemoryRegionPortio
*old_portio
;
110 /* If .read and .write are not present, old_mmio may be used for
111 * backwards compatibility with old mmio registration
113 const MemoryRegionMmio old_mmio
;
116 typedef struct CoalescedMemoryRange CoalescedMemoryRange
;
117 typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd
;
119 struct MemoryRegion
{
120 /* All fields are private - violators will be prosecuted */
121 const MemoryRegionOps
*ops
;
123 MemoryRegion
*parent
;
125 target_phys_addr_t addr
;
126 void (*destructor
)(MemoryRegion
*mr
);
132 bool readonly
; /* For RAM regions */
135 bool warning_printed
; /* For reservations */
137 target_phys_addr_t alias_offset
;
140 QTAILQ_HEAD(subregions
, MemoryRegion
) subregions
;
141 QTAILQ_ENTRY(MemoryRegion
) subregions_link
;
142 QTAILQ_HEAD(coalesced_ranges
, CoalescedMemoryRange
) coalesced
;
144 uint8_t dirty_log_mask
;
145 unsigned ioeventfd_nb
;
146 MemoryRegionIoeventfd
*ioeventfds
;
149 struct MemoryRegionPortio
{
153 IOPortReadFunc
*read
;
154 IOPortWriteFunc
*write
;
157 #define PORTIO_END_OF_LIST() { }
159 typedef struct MemoryRegionSection MemoryRegionSection
;
162 * MemoryRegionSection: describes a fragment of a #MemoryRegion
164 * @mr: the region, or %NULL if empty
165 * @address_space: the address space the region is mapped in
166 * @offset_within_region: the beginning of the section, relative to @mr's start
167 * @size: the size of the section; will not exceed @mr's boundaries
168 * @offset_within_address_space: the address of the first byte of the section
169 * relative to the region's address space
170 * @readonly: writes to this section are ignored
172 struct MemoryRegionSection
{
174 MemoryRegion
*address_space
;
175 target_phys_addr_t offset_within_region
;
177 target_phys_addr_t offset_within_address_space
;
181 typedef struct MemoryListener MemoryListener
;
184 * MemoryListener: callbacks structure for updates to the physical memory map
186 * Allows a component to adjust to changes in the guest-visible memory map.
187 * Use with memory_listener_register() and memory_listener_unregister().
189 struct MemoryListener
{
190 void (*begin
)(MemoryListener
*listener
);
191 void (*commit
)(MemoryListener
*listener
);
192 void (*region_add
)(MemoryListener
*listener
, MemoryRegionSection
*section
);
193 void (*region_del
)(MemoryListener
*listener
, MemoryRegionSection
*section
);
194 void (*region_nop
)(MemoryListener
*listener
, MemoryRegionSection
*section
);
195 void (*log_start
)(MemoryListener
*listener
, MemoryRegionSection
*section
);
196 void (*log_stop
)(MemoryListener
*listener
, MemoryRegionSection
*section
);
197 void (*log_sync
)(MemoryListener
*listener
, MemoryRegionSection
*section
);
198 void (*log_global_start
)(MemoryListener
*listener
);
199 void (*log_global_stop
)(MemoryListener
*listener
);
200 void (*eventfd_add
)(MemoryListener
*listener
, MemoryRegionSection
*section
,
201 bool match_data
, uint64_t data
, int fd
);
202 void (*eventfd_del
)(MemoryListener
*listener
, MemoryRegionSection
*section
,
203 bool match_data
, uint64_t data
, int fd
);
204 /* Lower = earlier (during add), later (during del) */
206 MemoryRegion
*address_space_filter
;
207 QTAILQ_ENTRY(MemoryListener
) link
;
211 * memory_region_init: Initialize a memory region
213 * The region typically acts as a container for other memory regions. Use
214 * memory_region_add_subregion() to add subregions.
216 * @mr: the #MemoryRegion to be initialized
217 * @name: used for debugging; not visible to the user or ABI
218 * @size: size of the region; any subregions beyond this size will be clipped
220 void memory_region_init(MemoryRegion
*mr
,
224 * memory_region_init_io: Initialize an I/O memory region.
226 * Accesses into the region will cause the callbacks in @ops to be called.
227 * if @size is nonzero, subregions will be clipped to @size.
229 * @mr: the #MemoryRegion to be initialized.
230 * @ops: a structure containing read and write callbacks to be used when
231 * I/O is performed on the region.
232 * @opaque: passed to to the read and write callbacks of the @ops structure.
233 * @name: used for debugging; not visible to the user or ABI
234 * @size: size of the region.
236 void memory_region_init_io(MemoryRegion
*mr
,
237 const MemoryRegionOps
*ops
,
243 * memory_region_init_ram: Initialize RAM memory region. Accesses into the
244 * region will modify memory directly.
246 * @mr: the #MemoryRegion to be initialized.
247 * @name: the name of the region.
248 * @size: size of the region.
250 void memory_region_init_ram(MemoryRegion
*mr
,
255 * memory_region_init_ram: Initialize RAM memory region from a user-provided.
256 * pointer. Accesses into the region will modify
259 * @mr: the #MemoryRegion to be initialized.
260 * @name: the name of the region.
261 * @size: size of the region.
262 * @ptr: memory to be mapped; must contain at least @size bytes.
264 void memory_region_init_ram_ptr(MemoryRegion
*mr
,
270 * memory_region_init_alias: Initialize a memory region that aliases all or a
271 * part of another memory region.
273 * @mr: the #MemoryRegion to be initialized.
274 * @name: used for debugging; not visible to the user or ABI
275 * @orig: the region to be referenced; @mr will be equivalent to
276 * @orig between @offset and @offset + @size - 1.
277 * @offset: start of the section in @orig to be referenced.
278 * @size: size of the region.
280 void memory_region_init_alias(MemoryRegion
*mr
,
283 target_phys_addr_t offset
,
287 * memory_region_init_rom_device: Initialize a ROM memory region. Writes are
288 * handled via callbacks.
290 * @mr: the #MemoryRegion to be initialized.
291 * @ops: callbacks for write access handling.
292 * @name: the name of the region.
293 * @size: size of the region.
295 void memory_region_init_rom_device(MemoryRegion
*mr
,
296 const MemoryRegionOps
*ops
,
302 * memory_region_init_reservation: Initialize a memory region that reserves
305 * A reservation region primariy serves debugging purposes. It claims I/O
306 * space that is not supposed to be handled by QEMU itself. Any access via
307 * the memory API will cause an abort().
309 * @mr: the #MemoryRegion to be initialized
310 * @name: used for debugging; not visible to the user or ABI
311 * @size: size of the region.
313 void memory_region_init_reservation(MemoryRegion
*mr
,
317 * memory_region_destroy: Destroy a memory region and reclaim all resources.
319 * @mr: the region to be destroyed. May not currently be a subregion
320 * (see memory_region_add_subregion()) or referenced in an alias
321 * (see memory_region_init_alias()).
323 void memory_region_destroy(MemoryRegion
*mr
);
326 * memory_region_size: get a memory region's size.
328 * @mr: the memory region being queried.
330 uint64_t memory_region_size(MemoryRegion
*mr
);
333 * memory_region_is_ram: check whether a memory region is random access
335 * Returns %true is a memory region is random access.
337 * @mr: the memory region being queried
339 bool memory_region_is_ram(MemoryRegion
*mr
);
342 * memory_region_is_romd: check whether a memory region is ROMD
344 * Returns %true is a memory region is ROMD and currently set to allow
347 * @mr: the memory region being queried
349 static inline bool memory_region_is_romd(MemoryRegion
*mr
)
351 return mr
->rom_device
&& mr
->readable
;
355 * memory_region_name: get a memory region's name
357 * Returns the string that was used to initialize the memory region.
359 * @mr: the memory region being queried
361 const char *memory_region_name(MemoryRegion
*mr
);
364 * memory_region_is_logging: return whether a memory region is logging writes
366 * Returns %true if the memory region is logging writes
368 * @mr: the memory region being queried
370 bool memory_region_is_logging(MemoryRegion
*mr
);
373 * memory_region_is_rom: check whether a memory region is ROM
375 * Returns %true is a memory region is read-only memory.
377 * @mr: the memory region being queried
379 bool memory_region_is_rom(MemoryRegion
*mr
);
382 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
384 * Returns a host pointer to a RAM memory region (created with
385 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
388 * @mr: the memory region being queried.
390 void *memory_region_get_ram_ptr(MemoryRegion
*mr
);
393 * memory_region_set_log: Turn dirty logging on or off for a region.
395 * Turns dirty logging on or off for a specified client (display, migration).
396 * Only meaningful for RAM regions.
398 * @mr: the memory region being updated.
399 * @log: whether dirty logging is to be enabled or disabled.
400 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
403 void memory_region_set_log(MemoryRegion
*mr
, bool log
, unsigned client
);
406 * memory_region_get_dirty: Check whether a range of bytes is dirty
407 * for a specified client.
409 * Checks whether a range of bytes has been written to since the last
410 * call to memory_region_reset_dirty() with the same @client. Dirty logging
413 * @mr: the memory region being queried.
414 * @addr: the address (relative to the start of the region) being queried.
415 * @size: the size of the range being queried.
416 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
419 bool memory_region_get_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
420 target_phys_addr_t size
, unsigned client
);
423 * memory_region_set_dirty: Mark a range of bytes as dirty in a memory region.
425 * Marks a range of bytes as dirty, after it has been dirtied outside
428 * @mr: the memory region being dirtied.
429 * @addr: the address (relative to the start of the region) being dirtied.
430 * @size: size of the range being dirtied.
432 void memory_region_set_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
433 target_phys_addr_t size
);
436 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
437 * any external TLBs (e.g. kvm)
439 * Flushes dirty information from accelerators such as kvm and vhost-net
440 * and makes it available to users of the memory API.
442 * @mr: the region being flushed.
444 void memory_region_sync_dirty_bitmap(MemoryRegion
*mr
);
447 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
450 * Marks a range of pages as no longer dirty.
452 * @mr: the region being updated.
453 * @addr: the start of the subrange being cleaned.
454 * @size: the size of the subrange being cleaned.
455 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
458 void memory_region_reset_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
459 target_phys_addr_t size
, unsigned client
);
462 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
464 * Allows a memory region to be marked as read-only (turning it into a ROM).
465 * only useful on RAM regions.
467 * @mr: the region being updated.
468 * @readonly: whether rhe region is to be ROM or RAM.
470 void memory_region_set_readonly(MemoryRegion
*mr
, bool readonly
);
473 * memory_region_rom_device_set_readable: enable/disable ROM readability
475 * Allows a ROM device (initialized with memory_region_init_rom_device() to
476 * to be marked as readable (default) or not readable. When it is readable,
477 * the device is mapped to guest memory. When not readable, reads are
478 * forwarded to the #MemoryRegion.read function.
480 * @mr: the memory region to be updated
481 * @readable: whether reads are satisified directly (%true) or via callbacks
484 void memory_region_rom_device_set_readable(MemoryRegion
*mr
, bool readable
);
487 * memory_region_set_coalescing: Enable memory coalescing for the region.
489 * Enabled writes to a region to be queued for later processing. MMIO ->write
490 * callbacks may be delayed until a non-coalesced MMIO is issued.
491 * Only useful for IO regions. Roughly similar to write-combining hardware.
493 * @mr: the memory region to be write coalesced
495 void memory_region_set_coalescing(MemoryRegion
*mr
);
498 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
501 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
502 * Multiple calls can be issued coalesced disjoint ranges.
504 * @mr: the memory region to be updated.
505 * @offset: the start of the range within the region to be coalesced.
506 * @size: the size of the subrange to be coalesced.
508 void memory_region_add_coalescing(MemoryRegion
*mr
,
509 target_phys_addr_t offset
,
513 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
515 * Disables any coalescing caused by memory_region_set_coalescing() or
516 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
519 * @mr: the memory region to be updated.
521 void memory_region_clear_coalescing(MemoryRegion
*mr
);
524 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
525 * is written to a location.
527 * Marks a word in an IO region (initialized with memory_region_init_io())
528 * as a trigger for an eventfd event. The I/O callback will not be called.
529 * The caller must be prepared to handle failure (that is, take the required
530 * action if the callback _is_ called).
532 * @mr: the memory region being updated.
533 * @addr: the address within @mr that is to be monitored
534 * @size: the size of the access to trigger the eventfd
535 * @match_data: whether to match against @data, instead of just @addr
536 * @data: the data to match against the guest write
537 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
539 void memory_region_add_eventfd(MemoryRegion
*mr
,
540 target_phys_addr_t addr
,
547 * memory_region_del_eventfd: Cancel an eventfd.
549 * Cancels an eventfd trigger requested by a previous
550 * memory_region_add_eventfd() call.
552 * @mr: the memory region being updated.
553 * @addr: the address within @mr that is to be monitored
554 * @size: the size of the access to trigger the eventfd
555 * @match_data: whether to match against @data, instead of just @addr
556 * @data: the data to match against the guest write
557 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
559 void memory_region_del_eventfd(MemoryRegion
*mr
,
560 target_phys_addr_t addr
,
566 * memory_region_add_subregion: Add a subregion to a container.
568 * Adds a subregion at @offset. The subregion may not overlap with other
569 * subregions (except for those explicitly marked as overlapping). A region
570 * may only be added once as a subregion (unless removed with
571 * memory_region_del_subregion()); use memory_region_init_alias() if you
572 * want a region to be a subregion in multiple locations.
574 * @mr: the region to contain the new subregion; must be a container
575 * initialized with memory_region_init().
576 * @offset: the offset relative to @mr where @subregion is added.
577 * @subregion: the subregion to be added.
579 void memory_region_add_subregion(MemoryRegion
*mr
,
580 target_phys_addr_t offset
,
581 MemoryRegion
*subregion
);
583 * memory_region_add_subregion: Add a subregion to a container, with overlap.
585 * Adds a subregion at @offset. The subregion may overlap with other
586 * subregions. Conflicts are resolved by having a higher @priority hide a
587 * lower @priority. Subregions without priority are taken as @priority 0.
588 * A region may only be added once as a subregion (unless removed with
589 * memory_region_del_subregion()); use memory_region_init_alias() if you
590 * want a region to be a subregion in multiple locations.
592 * @mr: the region to contain the new subregion; must be a container
593 * initialized with memory_region_init().
594 * @offset: the offset relative to @mr where @subregion is added.
595 * @subregion: the subregion to be added.
596 * @priority: used for resolving overlaps; highest priority wins.
598 void memory_region_add_subregion_overlap(MemoryRegion
*mr
,
599 target_phys_addr_t offset
,
600 MemoryRegion
*subregion
,
604 * memory_region_get_ram_addr: Get the ram address associated with a memory
607 * DO NOT USE THIS FUNCTION. This is a temporary workaround while the Xen
608 * code is being reworked.
610 ram_addr_t
memory_region_get_ram_addr(MemoryRegion
*mr
);
613 * memory_region_del_subregion: Remove a subregion.
615 * Removes a subregion from its container.
617 * @mr: the container to be updated.
618 * @subregion: the region being removed; must be a current subregion of @mr.
620 void memory_region_del_subregion(MemoryRegion
*mr
,
621 MemoryRegion
*subregion
);
624 * memory_region_set_enabled: dynamically enable or disable a region
626 * Enables or disables a memory region. A disabled memory region
627 * ignores all accesses to itself and its subregions. It does not
628 * obscure sibling subregions with lower priority - it simply behaves as
629 * if it was removed from the hierarchy.
631 * Regions default to being enabled.
633 * @mr: the region to be updated
634 * @enabled: whether to enable or disable the region
636 void memory_region_set_enabled(MemoryRegion
*mr
, bool enabled
);
639 * memory_region_set_address: dynamically update the address of a region
641 * Dynamically updates the address of a region, relative to its parent.
642 * May be used on regions are currently part of a memory hierarchy.
644 * @mr: the region to be updated
645 * @addr: new address, relative to parent region
647 void memory_region_set_address(MemoryRegion
*mr
, target_phys_addr_t addr
);
650 * memory_region_set_alias_offset: dynamically update a memory alias's offset
652 * Dynamically updates the offset into the target region that an alias points
653 * to, as if the fourth argument to memory_region_init_alias() has changed.
655 * @mr: the #MemoryRegion to be updated; should be an alias.
656 * @offset: the new offset into the target memory region
658 void memory_region_set_alias_offset(MemoryRegion
*mr
,
659 target_phys_addr_t offset
);
662 * memory_region_find: locate a MemoryRegion in an address space
664 * Locates the first #MemoryRegion within an address space given by
665 * @address_space that overlaps the range given by @addr and @size.
667 * Returns a #MemoryRegionSection that describes a contiguous overlap.
668 * It will have the following characteristics:
669 * .@offset_within_address_space >= @addr
670 * .@offset_within_address_space + .@size <= @addr + @size
671 * .@size = 0 iff no overlap was found
672 * .@mr is non-%NULL iff an overlap was found
674 * @address_space: a top-level (i.e. parentless) region that contains
675 * the region to be found
676 * @addr: start of the area within @address_space to be searched
677 * @size: size of the area to be searched
679 MemoryRegionSection
memory_region_find(MemoryRegion
*address_space
,
680 target_phys_addr_t addr
, uint64_t size
);
683 * memory_region_section_addr: get offset within MemoryRegionSection
685 * Returns offset within MemoryRegionSection
687 * @section: the memory region section being queried
688 * @addr: address in address space
690 static inline target_phys_addr_t
691 memory_region_section_addr(MemoryRegionSection
*section
,
692 target_phys_addr_t addr
)
694 addr
-= section
->offset_within_address_space
;
695 addr
+= section
->offset_within_region
;
700 * memory_global_sync_dirty_bitmap: synchronize the dirty log for all memory
702 * Synchronizes the dirty page log for an entire address space.
703 * @address_space: a top-level (i.e. parentless) region that contains the
704 * memory being synchronized
706 void memory_global_sync_dirty_bitmap(MemoryRegion
*address_space
);
709 * memory_region_transaction_begin: Start a transaction.
711 * During a transaction, changes will be accumulated and made visible
712 * only when the transaction ends (is committed).
714 void memory_region_transaction_begin(void);
717 * memory_region_transaction_commit: Commit a transaction and make changes
718 * visible to the guest.
720 void memory_region_transaction_commit(void);
723 * memory_listener_register: register callbacks to be called when memory
724 * sections are mapped or unmapped into an address
727 * @listener: an object containing the callbacks to be called
728 * @filter: if non-%NULL, only regions in this address space will be observed
730 void memory_listener_register(MemoryListener
*listener
, MemoryRegion
*filter
);
733 * memory_listener_unregister: undo the effect of memory_listener_register()
735 * @listener: an object containing the callbacks to be removed
737 void memory_listener_unregister(MemoryListener
*listener
);
740 * memory_global_dirty_log_start: begin dirty logging for all regions
742 void memory_global_dirty_log_start(void);
745 * memory_global_dirty_log_stop: begin dirty logging for all regions
747 void memory_global_dirty_log_stop(void);
749 void mtree_info(fprintf_function mon_printf
, void *f
);