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];
47 * Memory region callbacks
49 struct MemoryRegionOps
{
50 /* Read from the memory region. @addr is relative to @mr; @size is
52 uint64_t (*read
)(void *opaque
,
53 target_phys_addr_t addr
,
55 /* Write to the memory region. @addr is relative to @mr; @size is
57 void (*write
)(void *opaque
,
58 target_phys_addr_t addr
,
62 enum device_endian endianness
;
63 /* Guest-visible constraints: */
65 /* If nonzero, specify bounds on access sizes beyond which a machine
68 unsigned min_access_size
;
69 unsigned max_access_size
;
70 /* If true, unaligned accesses are supported. Otherwise unaligned
71 * accesses throw machine checks.
75 * If present, and returns #false, the transaction is not accepted
76 * by the device (and results in machine dependent behaviour such
77 * as a machine check exception).
79 bool (*accepts
)(void *opaque
, target_phys_addr_t addr
,
80 unsigned size
, bool is_write
);
82 /* Internal implementation constraints: */
84 /* If nonzero, specifies the minimum size implemented. Smaller sizes
85 * will be rounded upwards and a partial result will be returned.
87 unsigned min_access_size
;
88 /* If nonzero, specifies the maximum size implemented. Larger sizes
89 * will be done as a series of accesses with smaller sizes.
91 unsigned max_access_size
;
92 /* If true, unaligned accesses are supported. Otherwise all accesses
93 * are converted to (possibly multiple) naturally aligned accesses.
98 /* If .read and .write are not present, old_portio may be used for
99 * backwards compatibility with old portio registration
101 const MemoryRegionPortio
*old_portio
;
102 /* If .read and .write are not present, old_mmio may be used for
103 * backwards compatibility with old mmio registration
105 const MemoryRegionMmio old_mmio
;
108 typedef struct CoalescedMemoryRange CoalescedMemoryRange
;
109 typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd
;
111 struct MemoryRegion
{
112 /* All fields are private - violators will be prosecuted */
113 const MemoryRegionOps
*ops
;
115 MemoryRegion
*parent
;
117 target_phys_addr_t addr
;
118 target_phys_addr_t offset
;
119 bool backend_registered
;
120 void (*destructor
)(MemoryRegion
*mr
);
126 bool readonly
; /* For RAM regions */
129 target_phys_addr_t alias_offset
;
132 QTAILQ_HEAD(subregions
, MemoryRegion
) subregions
;
133 QTAILQ_ENTRY(MemoryRegion
) subregions_link
;
134 QTAILQ_HEAD(coalesced_ranges
, CoalescedMemoryRange
) coalesced
;
136 uint8_t dirty_log_mask
;
137 unsigned ioeventfd_nb
;
138 MemoryRegionIoeventfd
*ioeventfds
;
141 struct MemoryRegionPortio
{
145 IOPortReadFunc
*read
;
146 IOPortWriteFunc
*write
;
149 #define PORTIO_END_OF_LIST() { }
151 typedef struct MemoryRegionSection MemoryRegionSection
;
154 * MemoryRegionSection: describes a fragment of a #MemoryRegion
156 * @mr: the region, or %NULL if empty
157 * @offset_within_region: the beginning of the section, relative to @mr's start
158 * @size: the size of the section; will not exceed @mr's boundaries
159 * @offset_within_address_space: the address of the first byte of the section
160 * relative to the region's address space
162 struct MemoryRegionSection
{
164 target_phys_addr_t offset_within_region
;
166 target_phys_addr_t offset_within_address_space
;
170 * memory_region_init: Initialize a memory region
172 * The region typically acts as a container for other memory regions. Use
173 * memory_region_add_subregion() to add subregions.
175 * @mr: the #MemoryRegion to be initialized
176 * @name: used for debugging; not visible to the user or ABI
177 * @size: size of the region; any subregions beyond this size will be clipped
179 void memory_region_init(MemoryRegion
*mr
,
183 * memory_region_init_io: Initialize an I/O memory region.
185 * Accesses into the region will cause the callbacks in @ops to be called.
186 * if @size is nonzero, subregions will be clipped to @size.
188 * @mr: the #MemoryRegion to be initialized.
189 * @ops: a structure containing read and write callbacks to be used when
190 * I/O is performed on the region.
191 * @opaque: passed to to the read and write callbacks of the @ops structure.
192 * @name: used for debugging; not visible to the user or ABI
193 * @size: size of the region.
195 void memory_region_init_io(MemoryRegion
*mr
,
196 const MemoryRegionOps
*ops
,
202 * memory_region_init_ram: Initialize RAM memory region. Accesses into the
203 * region will modify memory directly.
205 * @mr: the #MemoryRegion to be initialized.
206 * @dev: a device associated with the region; may be %NULL.
207 * @name: the name of the region; the pair (@dev, @name) must be globally
208 * unique. The name is part of the save/restore ABI and so cannot be
210 * @size: size of the region.
212 void memory_region_init_ram(MemoryRegion
*mr
,
213 DeviceState
*dev
, /* FIXME: layering violation */
218 * memory_region_init_ram: Initialize RAM memory region from a user-provided.
219 * pointer. Accesses into the region will modify
222 * @mr: the #MemoryRegion to be initialized.
223 * @dev: a device associated with the region; may be %NULL.
224 * @name: the name of the region; the pair (@dev, @name) must be globally
225 * unique. The name is part of the save/restore ABI and so cannot be
227 * @size: size of the region.
228 * @ptr: memory to be mapped; must contain at least @size bytes.
230 void memory_region_init_ram_ptr(MemoryRegion
*mr
,
231 DeviceState
*dev
, /* FIXME: layering violation */
237 * memory_region_init_alias: Initialize a memory region that aliases all or a
238 * part of another memory region.
240 * @mr: the #MemoryRegion to be initialized.
241 * @name: used for debugging; not visible to the user or ABI
242 * @orig: the region to be referenced; @mr will be equivalent to
243 * @orig between @offset and @offset + @size - 1.
244 * @offset: start of the section in @orig to be referenced.
245 * @size: size of the region.
247 void memory_region_init_alias(MemoryRegion
*mr
,
250 target_phys_addr_t offset
,
254 * memory_region_init_rom_device: Initialize a ROM memory region. Writes are
255 * handled via callbacks.
257 * @mr: the #MemoryRegion to be initialized.
258 * @ops: callbacks for write access handling.
259 * @dev: a device associated with the region; may be %NULL.
260 * @name: the name of the region; the pair (@dev, @name) must be globally
261 * unique. The name is part of the save/restore ABI and so cannot be
263 * @size: size of the region.
265 void memory_region_init_rom_device(MemoryRegion
*mr
,
266 const MemoryRegionOps
*ops
,
268 DeviceState
*dev
, /* FIXME: layering violation */
273 * memory_region_destroy: Destroy a memory region and reclaim all resources.
275 * @mr: the region to be destroyed. May not currently be a subregion
276 * (see memory_region_add_subregion()) or referenced in an alias
277 * (see memory_region_init_alias()).
279 void memory_region_destroy(MemoryRegion
*mr
);
282 * memory_region_size: get a memory region's size.
284 * @mr: the memory region being queried.
286 uint64_t memory_region_size(MemoryRegion
*mr
);
289 * memory_region_is_ram: check whether a memory region is random access
291 * Returns %true is a memory region is random access.
293 * @mr: the memory region being queried
295 bool memory_region_is_ram(MemoryRegion
*mr
);
298 * memory_region_is_logging: return whether a memory region is logging writes
300 * Returns %true if the memory region is logging writes
302 * @mr: the memory region being queried
304 bool memory_region_is_logging(MemoryRegion
*mr
);
307 * memory_region_is_rom: check whether a memory region is ROM
309 * Returns %true is a memory region is read-only memory.
311 * @mr: the memory region being queried
313 bool memory_region_is_rom(MemoryRegion
*mr
);
316 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
318 * Returns a host pointer to a RAM memory region (created with
319 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
322 * @mr: the memory region being queried.
324 void *memory_region_get_ram_ptr(MemoryRegion
*mr
);
327 * memory_region_set_offset: Sets an offset to be added to MemoryRegionOps
330 * This function is deprecated and should not be used in new code.
332 void memory_region_set_offset(MemoryRegion
*mr
, target_phys_addr_t offset
);
335 * memory_region_set_log: Turn dirty logging on or off for a region.
337 * Turns dirty logging on or off for a specified client (display, migration).
338 * Only meaningful for RAM regions.
340 * @mr: the memory region being updated.
341 * @log: whether dirty logging is to be enabled or disabled.
342 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
345 void memory_region_set_log(MemoryRegion
*mr
, bool log
, unsigned client
);
348 * memory_region_get_dirty: Check whether a page is dirty for a specified
351 * Checks whether a page has been written to since the last
352 * call to memory_region_reset_dirty() with the same @client. Dirty logging
355 * @mr: the memory region being queried.
356 * @addr: the address (relative to the start of the region) being queried.
357 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
360 bool memory_region_get_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
364 * memory_region_set_dirty: Mark a page as dirty in a memory region.
366 * Marks a page as dirty, after it has been dirtied outside guest code.
368 * @mr: the memory region being queried.
369 * @addr: the address (relative to the start of the region) being dirtied.
371 void memory_region_set_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
);
374 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
375 * any external TLBs (e.g. kvm)
377 * Flushes dirty information from accelerators such as kvm and vhost-net
378 * and makes it available to users of the memory API.
380 * @mr: the region being flushed.
382 void memory_region_sync_dirty_bitmap(MemoryRegion
*mr
);
385 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
388 * Marks a range of pages as no longer dirty.
390 * @mr: the region being updated.
391 * @addr: the start of the subrange being cleaned.
392 * @size: the size of the subrange being cleaned.
393 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
396 void memory_region_reset_dirty(MemoryRegion
*mr
, target_phys_addr_t addr
,
397 target_phys_addr_t size
, unsigned client
);
400 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
402 * Allows a memory region to be marked as read-only (turning it into a ROM).
403 * only useful on RAM regions.
405 * @mr: the region being updated.
406 * @readonly: whether rhe region is to be ROM or RAM.
408 void memory_region_set_readonly(MemoryRegion
*mr
, bool readonly
);
411 * memory_region_rom_device_set_readable: enable/disable ROM readability
413 * Allows a ROM device (initialized with memory_region_init_rom_device() to
414 * to be marked as readable (default) or not readable. When it is readable,
415 * the device is mapped to guest memory. When not readable, reads are
416 * forwarded to the #MemoryRegion.read function.
418 * @mr: the memory region to be updated
419 * @readable: whether reads are satisified directly (%true) or via callbacks
422 void memory_region_rom_device_set_readable(MemoryRegion
*mr
, bool readable
);
425 * memory_region_set_coalescing: Enable memory coalescing for the region.
427 * Enabled writes to a region to be queued for later processing. MMIO ->write
428 * callbacks may be delayed until a non-coalesced MMIO is issued.
429 * Only useful for IO regions. Roughly similar to write-combining hardware.
431 * @mr: the memory region to be write coalesced
433 void memory_region_set_coalescing(MemoryRegion
*mr
);
436 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
439 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
440 * Multiple calls can be issued coalesced disjoint ranges.
442 * @mr: the memory region to be updated.
443 * @offset: the start of the range within the region to be coalesced.
444 * @size: the size of the subrange to be coalesced.
446 void memory_region_add_coalescing(MemoryRegion
*mr
,
447 target_phys_addr_t offset
,
451 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
453 * Disables any coalescing caused by memory_region_set_coalescing() or
454 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
457 * @mr: the memory region to be updated.
459 void memory_region_clear_coalescing(MemoryRegion
*mr
);
462 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
463 * is written to a location.
465 * Marks a word in an IO region (initialized with memory_region_init_io())
466 * as a trigger for an eventfd event. The I/O callback will not be called.
467 * The caller must be prepared to handle failure (that is, take the required
468 * action if the callback _is_ called).
470 * @mr: the memory region being updated.
471 * @addr: the address within @mr that is to be monitored
472 * @size: the size of the access to trigger the eventfd
473 * @match_data: whether to match against @data, instead of just @addr
474 * @data: the data to match against the guest write
475 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
477 void memory_region_add_eventfd(MemoryRegion
*mr
,
478 target_phys_addr_t addr
,
485 * memory_region_del_eventfd: Cancel an eventfd.
487 * Cancels an eventfd trigger requested by a previous
488 * memory_region_add_eventfd() call.
490 * @mr: the memory region being updated.
491 * @addr: the address within @mr that is to be monitored
492 * @size: the size of the access to trigger the eventfd
493 * @match_data: whether to match against @data, instead of just @addr
494 * @data: the data to match against the guest write
495 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
497 void memory_region_del_eventfd(MemoryRegion
*mr
,
498 target_phys_addr_t addr
,
504 * memory_region_add_subregion: Add a subregion to a container.
506 * Adds a subregion at @offset. The subregion may not overlap with other
507 * subregions (except for those explicitly marked as overlapping). A region
508 * may only be added once as a subregion (unless removed with
509 * memory_region_del_subregion()); use memory_region_init_alias() if you
510 * want a region to be a subregion in multiple locations.
512 * @mr: the region to contain the new subregion; must be a container
513 * initialized with memory_region_init().
514 * @offset: the offset relative to @mr where @subregion is added.
515 * @subregion: the subregion to be added.
517 void memory_region_add_subregion(MemoryRegion
*mr
,
518 target_phys_addr_t offset
,
519 MemoryRegion
*subregion
);
521 * memory_region_add_subregion: Add a subregion to a container, with overlap.
523 * Adds a subregion at @offset. The subregion may overlap with other
524 * subregions. Conflicts are resolved by having a higher @priority hide a
525 * lower @priority. Subregions without priority are taken as @priority 0.
526 * A region may only be added once as a subregion (unless removed with
527 * memory_region_del_subregion()); use memory_region_init_alias() if you
528 * want a region to be a subregion in multiple locations.
530 * @mr: the region to contain the new subregion; must be a container
531 * initialized with memory_region_init().
532 * @offset: the offset relative to @mr where @subregion is added.
533 * @subregion: the subregion to be added.
534 * @priority: used for resolving overlaps; highest priority wins.
536 void memory_region_add_subregion_overlap(MemoryRegion
*mr
,
537 target_phys_addr_t offset
,
538 MemoryRegion
*subregion
,
541 * memory_region_del_subregion: Remove a subregion.
543 * Removes a subregion from its container.
545 * @mr: the container to be updated.
546 * @subregion: the region being removed; must be a current subregion of @mr.
548 void memory_region_del_subregion(MemoryRegion
*mr
,
549 MemoryRegion
*subregion
);
552 * memory_region_set_enabled: dynamically enable or disable a region
554 * Enables or disables a memory region. A disabled memory region
555 * ignores all accesses to itself and its subregions. It does not
556 * obscure sibling subregions with lower priority - it simply behaves as
557 * if it was removed from the hierarchy.
559 * Regions default to being enabled.
561 * @mr: the region to be updated
562 * @enabled: whether to enable or disable the region
564 void memory_region_set_enabled(MemoryRegion
*mr
, bool enabled
);
567 * memory_region_set_address: dynamically update the address of a region
569 * Dynamically updates the address of a region, relative to its parent.
570 * May be used on regions are currently part of a memory hierarchy.
572 * @mr: the region to be updated
573 * @addr: new address, relative to parent region
575 void memory_region_set_address(MemoryRegion
*mr
, target_phys_addr_t addr
);
578 * memory_region_set_alias_offset: dynamically update a memory alias's offset
580 * Dynamically updates the offset into the target region that an alias points
581 * to, as if the fourth argument to memory_region_init_alias() has changed.
583 * @mr: the #MemoryRegion to be updated; should be an alias.
584 * @offset: the new offset into the target memory region
586 void memory_region_set_alias_offset(MemoryRegion
*mr
,
587 target_phys_addr_t offset
);
590 * memory_region_find: locate a MemoryRegion in an address space
592 * Locates the first #MemoryRegion within an address space given by
593 * @address_space that overlaps the range given by @addr and @size.
595 * Returns a #MemoryRegionSection that describes a contiguous overlap.
596 * It will have the following characteristics:
597 * .@offset_within_address_space >= @addr
598 * .@offset_within_address_space + .@size <= @addr + @size
599 * .@size = 0 iff no overlap was found
600 * .@mr is non-%NULL iff an overlap was found
602 * @address_space: a top-level (i.e. parentless) region that contains
603 * the region to be found
604 * @addr: start of the area within @address_space to be searched
605 * @size: size of the area to be searched
607 MemoryRegionSection
memory_region_find(MemoryRegion
*address_space
,
608 target_phys_addr_t addr
, uint64_t size
);
612 * memory_global_sync_dirty_bitmap: synchronize the dirty log for all memory
614 * Synchronizes the dirty page log for an entire address space.
615 * @address_space: a top-level (i.e. parentless) region that contains the
616 * memory being synchronized
618 void memory_global_sync_dirty_bitmap(MemoryRegion
*address_space
);
621 * memory_region_transaction_begin: Start a transaction.
623 * During a transaction, changes will be accumulated and made visible
624 * only when the transaction ends (is commited).
626 void memory_region_transaction_begin(void);
629 * memory_region_transaction_commit: Commit a transaction and make changes
630 * visible to the guest.
632 void memory_region_transaction_commit(void);
634 void mtree_info(fprintf_function mon_printf
, void *f
);