include/system/memory.h

2  * Physical memory management API
35 #define TYPE_MEMORY_REGION "memory-region"
39 #define TYPE_IOMMU_MEMORY_REGION "iommu-memory-region"
235 /* RAM is a persistent kind memory */
249  * set, the OS will do the reservation, if supported for the memory type.
291  * Memory region callbacks
294     /* Read from the memory region. @addr is relative to @mr; @size is
299     /* Write to the memory region. @addr is relative to @mr; @size is
370  * to handle requests to the memory region. Other methods are optional.
378  * to an output TLB entry. If the IOMMU is aware of memory transaction
423      * @hwaddr: address to be translated within the memory region
458      * IOMMU memory region. In case of failure, the error object
500      * @data: memory to fill in with the attribute data
520      * @attrs: memory transaction attributes
548      * Notification that previously discarded memory is about to get populated.
554      *           is aligned within the memory region to the minimum granularity
565      * Notification that previously populated memory was discarded successfully
566      * and listeners should drop all references to such memory and prevent
571      *           is aligned within the memory region to the minimum granularity
618  * after parts were discarded (freeing up memory) and before parts will be
619  * populated (consuming memory), to be used/accessed by the VM.
628  * memory inside a #MemoryRegion), and require proper coordination to only
630  * remain discarded from silently getting populated and consuming memory.
635  * memory within an assigned RAM #MemoryRegion, coordinated with the VM.
636  * Logically unplugging memory consists of discarding RAM. The VM agreed to not
637  * access unplugged (discarded) memory - especially via DMA. virtio-mem will
638  * properly coordinate with listeners before memory is plugged (populated),
639  * and after memory is unplugged (discarded).
643  * granularity within the #MemoryRegion. Listeners have to prepare for memory
821  * A struct representing a memory region.
886  * struct MemoryListener: callbacks structure for updates to the physical memory map
888  * Allows a component to adjust to changes in the guest-visible memory map.
958      * #MemoryListener.region_nop(), if dirty memory logging clients have
963      * @old: A bitmap of dirty memory logging clients that were active in
965      * @new: A bitmap of dirty memory logging clients that are active in
977      * #MemoryListener.log_start(), if dirty memory logging clients have
982      * @old: A bitmap of dirty memory logging clients that were active in
984      * @new: A bitmap of dirty memory logging clients that are active in
995      * copy of the dirty memory bitmap for a #MemoryRegionSection.
1020      * Called before reading the dirty memory bitmap for a
1032      * enables the %DIRTY_LOG_MIGRATION client on all memory regions in
1048      * disables the %DIRTY_LOG_MIGRATION client on all memory regions in
1058      * Called after reading the dirty memory bitmap
1129      * Govern the order in which memory listeners are invoked. Lower priorities
1139      * identify one memory listener with the rest.
1175      * Maximum DMA bounce buffer size used for indirect memory map requests.
1177      * DMA requests to indirect memory regions within this AddressSpace. DMA
1193 /* Flattened global view of current active memory hierarchy.  Kept in sorted
1254  * memory_region_section_new_copy: Copy a memory region section
1256  * Allocate memory for a new copy, copy the memory region section, and
1264  * memory_region_section_free_copy: Free a copied memory region section
1266  * Free a copy of a memory section created via memory_region_section_new_copy().
1274  * memory_region_section_intersect_range: Adjust the memory section to cover
1278  * @offset: the offset of the given range in the memory region
1304  * memory_region_init: Initialize a memory region
1306  * The region typically acts as a container for other memory regions.  Use
1320  * memory_region_ref: Add 1 to a memory region's reference count
1322  * Whenever memory regions are accessed outside the BQL, they need to be
1337  * memory_region_unref: Remove 1 to a memory region's reference count
1339  * Whenever memory regions are accessed outside the BQL, they need to be
1349  * memory_region_init_io: Initialize an I/O memory region.
1370  * memory_region_init_ram_nomigrate:  Initialize RAM memory region.  Accesses
1371  *                                    into the region will modify memory
1382  * RAM memory region to be migrated; that is the responsibility of the caller.
1393  * memory_region_init_ram_flags_nomigrate:  Initialize RAM memory region.
1395  *                                          modify memory directly.
1407  * RAM memory region to be migrated; that is the responsibility of the caller.
1419  * memory_region_init_resizeable_ram:  Initialize memory region with resizable
1421  *                                     modify memory directly.  Only an initial
1437  * RAM memory region to be migrated; that is the responsibility of the caller.
1453  * memory_region_init_ram_from_file:  Initialize RAM memory region with a
1471  * RAM memory region to be migrated; that is the responsibility of the caller.
1486  * memory_region_init_ram_from_fd:  Initialize RAM memory region with a
1501  * RAM memory region to be migrated; that is the responsibility of the caller.
1516  * memory_region_init_ram_ptr:  Initialize RAM memory region from a
1518  *                              region will modify memory directly.
1525  * @ptr: memory to be mapped; must contain at least @size bytes.
1528  * RAM memory region to be migrated; that is the responsibility of the caller.
1537  * memory_region_init_ram_device_ptr:  Initialize RAM device memory region from
1541  * MMIO BAR of an vfio-pci assigned device.  The memory region may be mapped
1542  * into the VM address space and access to the region will modify memory
1543  * directly.  However, the memory region should not be included in a memory
1552  * @ptr: memory to be mapped; must contain at least @size bytes.
1555  * RAM memory region to be migrated; that is the responsibility of the caller.
1556  * (For RAM device memory regions, migrating the contents rarely makes sense.)
1565  * memory_region_init_alias: Initialize a memory region that aliases all or a
1566  *                           part of another memory region.
1584  * memory_region_init_rom_nomigrate: Initialize a ROM memory region.
1591  * RAM side of the memory region to be migrated; that is the responsibility
1610  * memory_region_init_rom_device_nomigrate:  Initialize a ROM memory region.
1614  * RAM side of the memory region to be migrated; that is the responsibility
1637  * memory_region_init_iommu: Initialize a memory region of a custom type
1641  * memory region.
1644  * @_iommu_mr should be a pointer to enough memory for an instance of
1648  * accesses to the memory region. See the documentation of
1666  * memory_region_init_ram - Initialize RAM memory region.  Accesses into the
1667  *                          region will modify memory directly.
1672  * @name: name of the memory region
1702  * memory_region_init_rom: Initialize a ROM memory region.
1731  * memory_region_init_rom_device:  Initialize a ROM memory region.
1734  * This function initializes a memory region backed by RAM for reads
1767  * memory_region_owner: get a memory region's owner.
1769  * @mr: the memory region being queried.
1774  * memory_region_size: get a memory region's size.
1776  * @mr: the memory region being queried.
1781  * memory_region_is_ram: check whether a memory region is random access
1783  * Returns %true if a memory region is random access.
1785  * @mr: the memory region being queried
1793  * memory_region_is_ram_device: check whether a memory region is a ram device
1795  * Returns %true if a memory region is a device backed ram region
1797  * @mr: the memory region being queried
1802  * memory_region_is_romd: check whether a memory region is in ROMD mode
1804  * Returns %true if a memory region is a ROM device and currently set to allow
1807  * @mr: the memory region being queried
1815  * memory_region_is_protected: check whether a memory region is protected
1817  * Returns %true if a memory region is protected RAM and cannot be accessed
1820  * @mr: the memory region being queried
1825  * memory_region_has_guest_memfd: check whether a memory region has guest_memfd
1828  * Returns %true if a memory region's ram_block has valid guest_memfd assigned.
1830  * @mr: the memory region being queried
1835  * memory_region_get_iommu: check whether a memory region is an iommu
1837  * Returns pointer to IOMMUMemoryRegion if a memory region is an iommu,
1840  * @mr: the memory region being queried
1854  * memory_region_get_iommu_class_nocheck: returns iommu memory region class
1857  * Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu,
1860  * @iommu_mr: the memory region being queried
1876  * @iommu_mr: the memory region being queried
1886  * @iommu_mr: the memory region that was changed
1927  * is not supported (flag/range) by the IOMMU memory region. In case of error
1930  * @mr: the memory region to observe
1946  * @iommu_mr: the memory region to observe
1955  * @mr: the memory region which was observed and for which notify_stopped()
1970  * @iommu_mr: the memory region
1980  * use for translations with the given memory transaction attributes.
1982  * @iommu_mr: the memory region
1983  * @attrs: the memory transaction attributes
1992  * @iommu_mr: the memory region
1997  * memory_region_name: get a memory region's name
1999  * Returns the string that was used to initialize the memory region.
2001  * @mr: the memory region being queried
2006  * memory_region_is_logging: return whether a memory region is logging writes
2008  * Returns %true if the memory region is logging writes for the given client
2010  * @mr: the memory region being queried
2017  * memory region is logging writes.
2022  * @mr: the memory region being queried
2027  * memory_region_is_rom: check whether a memory region is ROM
2029  * Returns %true if a memory region is read-only memory.
2031  * @mr: the memory region being queried
2039  * memory_region_is_nonvolatile: check whether a memory region is non-volatile
2041  * Returns %true is a memory region is non-volatile memory.
2043  * @mr: the memory region being queried
2051  * memory_region_get_fd: Get a file descriptor backing a RAM memory region.
2053  * Returns a file descriptor backing a file-based RAM memory region,
2054  * or -1 if the region is not a file-based RAM memory region.
2056  * @mr: the RAM or alias memory region being queried.
2061  * memory_region_from_host: Convert a pointer into a RAM memory region
2064  * Given a host pointer inside a RAM memory region (created with
2075  * @offset: the offset within memory region
2080  * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
2082  * Returns a host pointer to a RAM memory region (created with
2091  * @mr: the memory region being queried.
2098  * Care has to be taken if the guest might have already detected the memory.
2100  * @mr: a memory region created with @memory_region_init_resizeable_ram.
2109  * a memory mapped region
2111  * @mr: the memory region to be msync
2121  * @mr: the memory region to be updated
2133  * @mr: the memory region being updated.
2140  * memory_region_set_dirty: Mark a range of bytes as dirty in a memory region.
2145  * @mr: the memory region being dirtied.
2153  * memory_region_clear_dirty_bitmap - clear dirty bitmap for memory range
2156  * dirty bitmap of a memory range within the memory region.  This can
2161  * @mr:     the memory region to clear the dirty log upon
2162  * @start:  start address offset within the memory region
2163  * @len:    length of the memory region to clear dirty bitmap
2190  * @mr: the memory region being queried.
2204  * @mr: the memory region being queried.
2234  * accessing the memory returned by memory_region_get_ram_ptr().
2247  * memory_region_set_readonly: Turn a memory region read-only (or read-write)
2249  * Allows a memory region to be marked as read-only (turning it into a ROM).
2258  * memory_region_set_nonvolatile: Turn a memory region non-volatile
2260  * Allows a memory region to be marked as non-volatile.
2273  * device is mapped to guest memory and satisfies read access directly.
2277  * @mr: the memory region to be updated
2283  * memory_region_set_coalescing: Enable memory coalescing for the region.
2289  * @mr: the memory region to be write coalesced
2294  * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
2300  * @mr: the memory region to be updated.
2312  * memory_region_add_coalescing().  Roughly equivalent to uncacheble memory
2315  * @mr: the memory region to be updated.
2320  * memory_region_set_flush_coalesced: Enforce memory coalescing flush before
2323  * Ensure that pending coalesced MMIO request are flushed before the memory
2327  * @mr: the memory region to be updated.
2332  * memory_region_clear_flush_coalesced: Disable memory coalescing flush before
2337  * memory regions that have MMIO coalescing enabled for themselves. For them,
2340  * @mr: the memory region to be updated.
2353  * @mr: the memory region being updated.
2373  * @mr: the memory region being updated.
2427  * memory_region_get_ram_addr: Get the ram address associated with a memory
2449  * Enables or disables a memory region.  A disabled memory region
2465  * May be used on regions are currently part of a memory hierarchy.
2483  * memory_region_set_alias_offset: dynamically update a memory alias's offset
2489  * @offset: the new offset into the target memory region
2495  * memory_region_set_unmergeable: Set a memory region unmergeable
2497  * Mark a memory region unmergeable, resulting in the memory region (or
2498  * everything contained in a memory region container) not getting merged when
2499  * simplifying the address space and notifying memory listeners. Consequently,
2500  * memory listeners will never get notified about ranges that are larger than
2501  * the original memory regions.
2503  * This is primarily useful when multiple aliases to a RAM memory region are
2504  * mapped into a memory region container, and updates (e.g., enable/disable or
2505  * map/unmap) of individual memory region aliases are not supposed to affect
2506  * other memory regions in the same container.
2527  * into another memory region, which does not necessarily imply that it is
2538  * The #RamDiscardManager cannot change while a memory region is mapped.
2601  * memory_global_dirty_log_sync: synchronize the dirty log for all memory
2610  * memory_global_after_dirty_log_sync: synchronize the dirty log for all memory
2614  * before dirty guest memory pages are read.  If you are using
2635  * memory_listener_register: register callbacks to be called when memory
2681  * @op: size, sign, and endianness of the memory operation
2682  * @attrs: memory transaction attributes to use for the access
2696  * @op: size, sign, and endianness of the memory operation
2697  * @attrs: memory transaction attributes to use for the access
2719  * is destroyed, its root memory region (given by address_space_init()) may be destroyed
2740  * or failed (eg unassigned memory, device rejected the transaction,
2745  * @attrs: memory transaction attributes
2758  * or failed (eg unassigned memory, device rejected the transaction,
2763  * @attrs: memory transaction attributes
2784  * or failed (eg unassigned memory, device rejected the transaction,
2789  * @attrs: memory transaction attributes
2813  * @attrs: memory transaction attributes
2862  * @attrs: memory transaction attributes
2910  * memory region
2939  * Initializes #MemoryRegionCache structure without memory region attached.
2964  * @cache: The #MemoryRegionCache whose memory should be released.
2981  * @xlat: pointer to address within the returned memory region section's
2985  * @attrs: memory attributes
3004  * Check whether memory is assigned to the given address space range, and
3015  * @attrs: memory attributes
3020 /* address_space_map: map a physical memory region into a host virtual address
3033  * @attrs: memory attributes
3038 /* address_space_unmap: Unmaps a memory region previously mapped by address_space_map()
3040  * Will also mark the memory as dirty if @is_write == %true.  @access_len gives
3041  * the amount of memory that was actually read or written by the caller.
3057  * such as when bounce buffer memory would exceed the limit. The callback can
3129  * or failed (eg unassigned memory, device rejected the transaction,
3134  * @attrs: memory transaction attributes
3216  * or failed (eg unassigned memory, device rejected the transaction,
3221  * @c: constant byte to fill the memory
3223  * @attrs: memory transaction attributes
3230  * to manage the actual amount of memory consumed by the VM (then, the memory
3231  * provided by RAM blocks might be bigger than the desired memory consumption).
3235  * - All memory in RAM blocks is pinned or duplicated, invaldiating any previous
3274  * Test if any discarding of memory in ram blocks is disabled.
3279  * Test if any discarding of memory in ram blocks is required to work reliably.