@@ -16,6 +16,7 @@
<chapter>
<title>Core Device APIs</title>
+ <xi:include href="xml/memory.xml"/>
</chapter>
<index id="api-index-full">
new file mode 100644
@@ -0,0 +1,566 @@
+/*
+ * Physical memory management API
+ *
+ * Copyright 2011 Red Hat, Inc. and/or its affiliates
+ *
+ * Authors:
+ * Avi Kivity <avi@redhat.com>
+ *
+ * This work is licensed under the terms of the GNU GPL, version 2. See
+ * the COPYING file in the top-level directory.
+ *
+ */
+
+#ifndef MEMORY_H
+#define MEMORY_H
+
+#ifndef CONFIG_USER_ONLY
+
+/**
+ * SECTION:memory
+ * @title:Memory API
+ * @short_description: interfaces for dispatching I/O to devices
+ *
+ * The memory API models the memory and I/O buses and controllers of a QEMU
+ * machine.
+ */
+
+#include <stdint.h>
+#include <stdbool.h>
+#include "qemu-common.h"
+#include "cpu-common.h"
+#include "targphys.h"
+#include "qemu-queue.h"
+#include "iorange.h"
+#include "ioport.h"
+#include "int128.h"
+
+typedef struct MemoryRegionOps MemoryRegionOps;
+typedef struct MemoryRegion MemoryRegion;
+typedef struct MemoryRegionPortio MemoryRegionPortio;
+typedef struct MemoryRegionMmio MemoryRegionMmio;
+typedef struct MemoryRegionGuestConstraints MemoryRegionGuestConstraints;
+typedef struct MemoryRegionInternalConstraints MemoryRegionInternalConstraints;
+
+/* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
+ * registration.
+ */
+#define DIRTY_MEMORY_VGA 0
+#define DIRTY_MEMORY_CODE 1
+#define DIRTY_MEMORY_MIGRATION 3
+
+struct MemoryRegionMmio {
+ CPUReadMemoryFunc *read[3];
+ CPUWriteMemoryFunc *write[3];
+};
+
+/**
+ * MemoryRegionGuestConstraints:
+ * @min_access_size: If nonzero, specify bounds on access sizes beyond which a
+ * machine check is thrown.
+ * @max_access_size: If nonzero, specify bounds on access sizes beyond which a
+ * machine check is thrown.
+ * @unaligned: If true, unaligned accesses are supported. Otherwise unaligned
+ * accesses throw machine checks.
+ * @accepts: If present, and returns #false, the transaction is not accepted
+ * by the device (and results in machine dependent behaviour such
+ * as a machine check exception).
+ *
+ * Guest-visible constraints.
+ */
+struct MemoryRegionGuestConstraints
+{
+ unsigned min_access_size;
+ unsigned max_access_size;
+ bool unaligned;
+ bool (*accepts)(void *opaque, target_phys_addr_t addr,
+ unsigned size, bool is_write);
+};
+
+/**
+ * MemoryRegionInternalConstraints:
+ * @min_access_size: If nonzero, specifies the minimum size implemented.
+ * Smaller sizes will be rounded upwards and a partial result will be
+ * returned.
+ * @max_access_size: If nonzero, specifies the maximum size implemented.
+ * Larger sizes will be done as a series of accesses with smaller sizes.
+ * @unaligned: If true, unaligned accesses are supported. Otherwise all
+ * accesses are converted to (possibly multiple) naturally aligned accesses.
+ *
+ * Internal implementation constraints.
+ */
+struct MemoryRegionInternalConstraints
+{
+ unsigned min_access_size;
+ unsigned max_access_size;
+ bool unaligned;
+};
+
+/**
+ * MemoryRegionOps:
+ * @read: Read from the memory region. addr is relative to mr; size is in bytes.
+ * @write: Write to the memory region. addr is relative to mr; size is in bytes.
+ * @valid: Guest visible constraints.
+ * @impl: Internal implementation constraints.
+ * @old_portio: If @read and @write are not present, may be used for
+ * backwards compatibility with old portio registration.
+ * @old_mmio: If @read and @write are not present, may be used for
+ * backwards compatibility with old mmio registration.
+ *
+ * Memory region callbacks.
+ */
+struct MemoryRegionOps {
+ uint64_t (*read)(void *opaque,
+ target_phys_addr_t addr,
+ unsigned size);
+ void (*write)(void *opaque,
+ target_phys_addr_t addr,
+ uint64_t data,
+ unsigned size);
+
+ enum device_endian endianness;
+
+ MemoryRegionGuestConstraints valid;
+ MemoryRegionInternalConstraints impl;
+
+ const MemoryRegionPortio *old_portio;
+ const MemoryRegionMmio old_mmio;
+};
+
+typedef struct CoalescedMemoryRange CoalescedMemoryRange;
+typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
+
+struct MemoryRegion {
+ /* All fields are private - violators will be prosecuted */
+ /*< private >*/
+ const MemoryRegionOps *ops;
+ void *opaque;
+ MemoryRegion *parent;
+ Int128 size;
+ target_phys_addr_t addr;
+ target_phys_addr_t offset;
+ bool backend_registered;
+ void (*destructor)(MemoryRegion *mr);
+ ram_addr_t ram_addr;
+ IORange iorange;
+ bool terminates;
+ bool readable;
+ bool readonly; /* For RAM regions */
+ MemoryRegion *alias;
+ target_phys_addr_t alias_offset;
+ unsigned priority;
+ bool may_overlap;
+ QTAILQ_HEAD(subregions, MemoryRegion) subregions;
+ QTAILQ_ENTRY(MemoryRegion) subregions_link;
+ QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
+ const char *name;
+ uint8_t dirty_log_mask;
+ unsigned ioeventfd_nb;
+ MemoryRegionIoeventfd *ioeventfds;
+};
+
+struct MemoryRegionPortio {
+ uint32_t offset;
+ uint32_t len;
+ unsigned size;
+ IOPortReadFunc *read;
+ IOPortWriteFunc *write;
+};
+
+#define PORTIO_END_OF_LIST() { }
+
+/**
+ * memory_region_init:
+ * @mr: the #MemoryRegion to be initialized
+ * @name: used for debugging; not visible to the user or ABI
+ * @size: size of the region; any subregions beyond this size will be clipped
+ *
+ * Initialize a memory region
+ *
+ * The region typically acts as a container for other memory regions. Use
+ * memory_region_add_subregion() to add subregions.
+ */
+void memory_region_init(MemoryRegion *mr,
+ const char *name,
+ uint64_t size);
+/**
+ * memory_region_init_io:
+ * @mr: the #MemoryRegion to be initialized.
+ * @ops: a structure containing read and write callbacks to be used when
+ * I/O is performed on the region.
+ * @opaque: passed to to the read and write callbacks of the @ops structure.
+ * @name: used for debugging; not visible to the user or ABI
+ * @size: size of the region.
+ *
+ * Initialize an I/O memory region.
+ *
+ * Accesses into the region will cause the callbacks in @ops to be called.
+ * if @size is nonzero, subregions will be clipped to @size.
+ */
+void memory_region_init_io(MemoryRegion *mr,
+ const MemoryRegionOps *ops,
+ void *opaque,
+ const char *name,
+ uint64_t size);
+
+/**
+ * memory_region_init_ram:
+ * @mr: the #MemoryRegion to be initialized.
+ * @dev: a device associated with the region; may be #NULL.
+ * @name: the name of the region; the pair (@dev, @name) must be globally
+ * unique. The name is part of the save/restore ABI and so cannot be
+ * changed.
+ * @size: size of the region.
+ *
+ * Initialize RAM memory region. Accesses into the region will modify memory
+ * directly.
+ */
+void memory_region_init_ram(MemoryRegion *mr,
+ DeviceState *dev, /* FIXME: layering violation */
+ const char *name,
+ uint64_t size);
+
+/**
+ * memory_region_init_ram:
+ * @mr: the #MemoryRegion to be initialized.
+ * @dev: a device associated with the region; may be #NULL.
+ * @name: the name of the region; the pair (@dev, @name) must be globally
+ * unique. The name is part of the save/restore ABI and so cannot be
+ * changed.
+ * @size: size of the region.
+ * @ptr: memory to be mapped; must contain at least @size bytes.
+ *
+ * Initialize RAM memory region from a user-provided pointer. Accesses into
+ * the region will modify memory directly.
+ */
+void memory_region_init_ram_ptr(MemoryRegion *mr,
+ DeviceState *dev, /* FIXME: layering violation */
+ const char *name,
+ uint64_t size,
+ void *ptr);
+
+/**
+ * memory_region_init_alias:
+ * @mr: the #MemoryRegion to be initialized.
+ * @name: used for debugging; not visible to the user or ABI
+ * @orig: the region to be referenced; @mr will be equivalent to
+ * @orig between @offset and @offset + @size - 1.
+ * @offset: start of the section in @orig to be referenced.
+ * @size: size of the region.
+ *
+ * Initialize a memory region that aliases all or a part of another memory
+ * region.
+ */
+void memory_region_init_alias(MemoryRegion *mr,
+ const char *name,
+ MemoryRegion *orig,
+ target_phys_addr_t offset,
+ uint64_t size);
+
+/**
+ * memory_region_init_rom_device:
+ * @mr: the #MemoryRegion to be initialized.
+ * @ops: callbacks for write access handling.
+ * @dev: a device associated with the region; may be #NULL.
+ * @name: the name of the region; the pair (@dev, @name) must be globally
+ * unique. The name is part of the save/restore ABI and so cannot be
+ * changed.
+ * @size: size of the region.
+ *
+ * Initialize a ROM memory region. Writes are handled via callbacks.
+ */
+void memory_region_init_rom_device(MemoryRegion *mr,
+ const MemoryRegionOps *ops,
+ void *opaque,
+ DeviceState *dev, /* FIXME: layering violation */
+ const char *name,
+ uint64_t size);
+
+/**
+ * memory_region_destroy:
+ * @mr: the region to be destroyed. May not currently be a subregion
+ * (see memory_region_add_subregion()) or referenced in an alias
+ * (see memory_region_init_alias()).
+ *
+ * Destroy a memory region and reclaim all resources.
+ */
+void memory_region_destroy(MemoryRegion *mr);
+
+/**
+ * memory_region_size:
+ * @mr: the memory region being queried.
+ *
+ * get a memory region's size.
+ */
+uint64_t memory_region_size(MemoryRegion *mr);
+
+/**
+ * memory_region_get_ram_ptr:
+ * @mr: the memory region being queried.
+ *
+ * Get a pointer into a RAM memory region.
+ *
+ * Returns a host pointer to a RAM memory region (created with
+ * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
+ * care.
+ */
+void *memory_region_get_ram_ptr(MemoryRegion *mr);
+
+/**
+ * memory_region_set_offset:
+ *
+ * Sets an offset to be added to MemoryRegionOps callbacks.
+ *
+ * Deprecated: This should not be used in new code.
+ */
+void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
+
+/**
+ * memory_region_set_log:
+ * @mr: the memory region being updated.
+ * @log: whether dirty logging is to be enabled or disabled.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Turn dirty logging on or off for a region.
+ *
+ * Turns dirty logging on or off for a specified client (display, migration).
+ * Only meaningful for RAM regions.
+ */
+void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
+
+/**
+ * memory_region_get_dirty:
+ * @mr: the memory region being queried.
+ * @addr: the address (relative to the start of the region) being queried.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Check whether a page is dirty for a specified client.
+ *
+ * Checks whether a page has been written to since the last
+ * call to memory_region_reset_dirty() with the same @client. Dirty logging
+ * must be enabled.
+ */
+bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
+ unsigned client);
+
+/**
+ * memory_region_set_dirty:
+ * @mr: the memory region being queried.
+ * @addr: the address (relative to the start of the region) being dirtied.
+ *
+ * Mark a page as dirty in a memory region.
+ *
+ * Marks a page as dirty, after it has been dirtied outside guest code.
+ */
+void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
+
+/**
+ * memory_region_sync_dirty_bitmap:
+ * @mr: the region being flushed.
+ *
+ * Synchronize a region's dirty bitmap with any external TLBs (e.g. kvm)
+ *
+ * Flushes dirty information from accelerators such as kvm and vhost-net
+ * and makes it available to users of the memory API.
+ */
+void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
+
+/**
+ * memory_region_reset_dirty:
+ * @mr: the region being updated.
+ * @addr: the start of the subrange being cleaned.
+ * @size: the size of the subrange being cleaned.
+ * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
+ * #DIRTY_MEMORY_VGA.
+ *
+ * Mark a range of pages as clean, for a specified client.
+ *
+ * Marks a range of pages as no longer dirty.
+ */
+void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
+ target_phys_addr_t size, unsigned client);
+
+/**
+ * memory_region_set_readonly:
+ * @mr: the region being updated.
+ * @readonly: whether rhe region is to be ROM or RAM.
+ *
+ * Turn a memory region read-only (or read-write)
+ *
+ * Allows a memory region to be marked as read-only (turning it into a ROM).
+ * only useful on RAM regions.
+ */
+void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
+
+/**
+ * memory_region_rom_device_set_readable:
+ * @mr: the memory region to be updated
+ * @readable: whether reads are satisified directly (#true) or via callbacks
+ * (#false)
+ *
+ * Enable/disable ROM readability
+ *
+ * Allows a ROM device (initialized with memory_region_init_rom_device() to
+ * to be marked as readable (default) or not readable. When it is readable,
+ * the device is mapped to guest memory. When not readable, reads are
+ * forwarded to the #MemoryRegion.read function.
+ */
+void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
+
+/**
+ * memory_region_set_coalescing:
+ * @mr: the memory region to be write coalesced
+ *
+ * Enable memory coalescing for the region.
+ *
+ * Enabled writes to a region to be queued for later processing. MMIO ->write
+ * callbacks may be delayed until a non-coalesced MMIO is issued.
+ * Only useful for IO regions. Roughly similar to write-combining hardware.
+ */
+void memory_region_set_coalescing(MemoryRegion *mr);
+
+/**
+ * memory_region_add_coalescing:
+ * @mr: the memory region to be updated.
+ * @offset: the start of the range within the region to be coalesced.
+ * @size: the size of the subrange to be coalesced.
+ *
+ * Enable memory coalescing for a sub-range of a region.
+ *
+ * Like memory_region_set_coalescing(), but works on a sub-range of a region.
+ * Multiple calls can be issued coalesced disjoint ranges.
+ */
+void memory_region_add_coalescing(MemoryRegion *mr,
+ target_phys_addr_t offset,
+ uint64_t size);
+
+/**
+ * memory_region_clear_coalescing:
+ * @mr: the memory region to be updated.
+ *
+ * Disable MMIO coalescing for the region.
+ *
+ * Disables any coalescing caused by memory_region_set_coalescing() or
+ * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
+ * hardware.
+ */
+void memory_region_clear_coalescing(MemoryRegion *mr);
+
+/**
+ * memory_region_add_eventfd:
+ * @mr: the memory region being updated.
+ * @addr: the address within @mr that is to be monitored
+ * @size: the size of the access to trigger the eventfd
+ * @match_data: whether to match against @data, instead of just @addr
+ * @data: the data to match against the guest write
+ * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
+ *
+ * Request an eventfd to be triggered when a word is written to a location.
+ *
+ * Marks a word in an IO region (initialized with memory_region_init_io())
+ * as a trigger for an eventfd event. The I/O callback will not be called.
+ * The caller must be prepared to handle failure (that is, take the required
+ * action if the callback _is_ called).
+ **/
+void memory_region_add_eventfd(MemoryRegion *mr,
+ target_phys_addr_t addr,
+ unsigned size,
+ bool match_data,
+ uint64_t data,
+ int fd);
+
+/**
+ * memory_region_del_eventfd:
+ * @mr: the memory region being updated.
+ * @addr: the address within @mr that is to be monitored
+ * @size: the size of the access to trigger the eventfd
+ * @match_data: whether to match against @data, instead of just @addr
+ * @data: the data to match against the guest write
+ * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
+ *
+ * Cancel an eventfd.
+ *
+ * Cancels an eventfd trigger requested by a previous
+ * memory_region_add_eventfd() call.
+ */
+void memory_region_del_eventfd(MemoryRegion *mr,
+ target_phys_addr_t addr,
+ unsigned size,
+ bool match_data,
+ uint64_t data,
+ int fd);
+/**
+ * memory_region_add_subregion:
+ * @mr: the region to contain the new subregion; must be a container
+ * initialized with memory_region_init().
+ * @offset: the offset relative to @mr where @subregion is added.
+ * @subregion: the subregion to be added.
+ *
+ * Add a subregion to a container.
+ *
+ * Adds a subregion at @offset. The subregion may not overlap with other
+ * subregions (except for those explicitly marked as overlapping). A region
+ * may only be added once as a subregion (unless removed with
+ * memory_region_del_subregion()); use memory_region_init_alias() if you
+ * want a region to be a subregion in multiple locations.
+ */
+void memory_region_add_subregion(MemoryRegion *mr,
+ target_phys_addr_t offset,
+ MemoryRegion *subregion);
+/**
+ * memory_region_add_subregion:
+ * @mr: the region to contain the new subregion; must be a container
+ * initialized with memory_region_init().
+ * @offset: the offset relative to @mr where @subregion is added.
+ * @subregion: the subregion to be added.
+ * @priority: used for resolving overlaps; highest priority wins.
+ *
+ * Add a subregion to a container, with overlap.
+ *
+ * Adds a subregion at @offset. The subregion may overlap with other
+ * subregions. Conflicts are resolved by having a higher @priority hide a
+ * lower @priority. Subregions without priority are taken as @priority 0.
+ * A region may only be added once as a subregion (unless removed with
+ * memory_region_del_subregion()); use memory_region_init_alias() if you
+ * want a region to be a subregion in multiple locations.
+ */
+void memory_region_add_subregion_overlap(MemoryRegion *mr,
+ target_phys_addr_t offset,
+ MemoryRegion *subregion,
+ unsigned priority);
+/**
+ * memory_region_del_subregion:
+ * @mr: the container to be updated.
+ * @subregion: the region being removed; must be a current subregion of @mr.
+ *
+ * Remove a subregion.
+ *
+ * Removes a subregion from its container.
+ */
+void memory_region_del_subregion(MemoryRegion *mr,
+ MemoryRegion *subregion);
+
+/**
+ * memory_region_transaction_begin:
+ *
+ * Start a transaction.
+ *
+ * During a transaction, changes will be accumulated and made visible
+ * only when the transaction ends (is commited).
+ */
+void memory_region_transaction_begin(void);
+
+/**
+ * memory_region_transaction_commit:
+ *
+ * Commit a transaction and make changes visible to the guest.
+ */
+void memory_region_transaction_commit(void);
+
+void mtree_info(fprintf_function mon_printf, void *f);
+
+#endif
+
+#endif
deleted file mode 100644
@@ -1,566 +0,0 @@
-/*
- * Physical memory management API
- *
- * Copyright 2011 Red Hat, Inc. and/or its affiliates
- *
- * Authors:
- * Avi Kivity <avi@redhat.com>
- *
- * This work is licensed under the terms of the GNU GPL, version 2. See
- * the COPYING file in the top-level directory.
- *
- */
-
-#ifndef MEMORY_H
-#define MEMORY_H
-
-#ifndef CONFIG_USER_ONLY
-
-/**
- * SECTION:memory
- * @title:Memory API
- * @short_description: interfaces for dispatching I/O to devices
- *
- * The memory API models the memory and I/O buses and controllers of a QEMU
- * machine.
- */
-
-#include <stdint.h>
-#include <stdbool.h>
-#include "qemu-common.h"
-#include "cpu-common.h"
-#include "targphys.h"
-#include "qemu-queue.h"
-#include "iorange.h"
-#include "ioport.h"
-#include "int128.h"
-
-typedef struct MemoryRegionOps MemoryRegionOps;
-typedef struct MemoryRegion MemoryRegion;
-typedef struct MemoryRegionPortio MemoryRegionPortio;
-typedef struct MemoryRegionMmio MemoryRegionMmio;
-typedef struct MemoryRegionGuestConstraints MemoryRegionGuestConstraints;
-typedef struct MemoryRegionInternalConstraints MemoryRegionInternalConstraints;
-
-/* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
- * registration.
- */
-#define DIRTY_MEMORY_VGA 0
-#define DIRTY_MEMORY_CODE 1
-#define DIRTY_MEMORY_MIGRATION 3
-
-struct MemoryRegionMmio {
- CPUReadMemoryFunc *read[3];
- CPUWriteMemoryFunc *write[3];
-};
-
-/**
- * MemoryRegionGuestConstraints:
- * @min_access_size: If nonzero, specify bounds on access sizes beyond which a
- * machine check is thrown.
- * @max_access_size: If nonzero, specify bounds on access sizes beyond which a
- * machine check is thrown.
- * @unaligned: If true, unaligned accesses are supported. Otherwise unaligned
- * accesses throw machine checks.
- * @accepts: If present, and returns #false, the transaction is not accepted
- * by the device (and results in machine dependent behaviour such
- * as a machine check exception).
- *
- * Guest-visible constraints.
- */
-struct MemoryRegionGuestConstraints
-{
- unsigned min_access_size;
- unsigned max_access_size;
- bool unaligned;
- bool (*accepts)(void *opaque, target_phys_addr_t addr,
- unsigned size, bool is_write);
-};
-
-/**
- * MemoryRegionInternalConstraints:
- * @min_access_size: If nonzero, specifies the minimum size implemented.
- * Smaller sizes will be rounded upwards and a partial result will be
- * returned.
- * @max_access_size: If nonzero, specifies the maximum size implemented.
- * Larger sizes will be done as a series of accesses with smaller sizes.
- * @unaligned: If true, unaligned accesses are supported. Otherwise all
- * accesses are converted to (possibly multiple) naturally aligned accesses.
- *
- * Internal implementation constraints.
- */
-struct MemoryRegionInternalConstraints
-{
- unsigned min_access_size;
- unsigned max_access_size;
- bool unaligned;
-};
-
-/**
- * MemoryRegionOps:
- * @read: Read from the memory region. addr is relative to mr; size is in bytes.
- * @write: Write to the memory region. addr is relative to mr; size is in bytes.
- * @valid: Guest visible constraints.
- * @impl: Internal implementation constraints.
- * @old_portio: If @read and @write are not present, may be used for
- * backwards compatibility with old portio registration.
- * @old_mmio: If @read and @write are not present, may be used for
- * backwards compatibility with old mmio registration.
- *
- * Memory region callbacks.
- */
-struct MemoryRegionOps {
- uint64_t (*read)(void *opaque,
- target_phys_addr_t addr,
- unsigned size);
- void (*write)(void *opaque,
- target_phys_addr_t addr,
- uint64_t data,
- unsigned size);
-
- enum device_endian endianness;
-
- MemoryRegionGuestConstraints valid;
- MemoryRegionInternalConstraints impl;
-
- const MemoryRegionPortio *old_portio;
- const MemoryRegionMmio old_mmio;
-};
-
-typedef struct CoalescedMemoryRange CoalescedMemoryRange;
-typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
-
-struct MemoryRegion {
- /* All fields are private - violators will be prosecuted */
- /*< private >*/
- const MemoryRegionOps *ops;
- void *opaque;
- MemoryRegion *parent;
- Int128 size;
- target_phys_addr_t addr;
- target_phys_addr_t offset;
- bool backend_registered;
- void (*destructor)(MemoryRegion *mr);
- ram_addr_t ram_addr;
- IORange iorange;
- bool terminates;
- bool readable;
- bool readonly; /* For RAM regions */
- MemoryRegion *alias;
- target_phys_addr_t alias_offset;
- unsigned priority;
- bool may_overlap;
- QTAILQ_HEAD(subregions, MemoryRegion) subregions;
- QTAILQ_ENTRY(MemoryRegion) subregions_link;
- QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
- const char *name;
- uint8_t dirty_log_mask;
- unsigned ioeventfd_nb;
- MemoryRegionIoeventfd *ioeventfds;
-};
-
-struct MemoryRegionPortio {
- uint32_t offset;
- uint32_t len;
- unsigned size;
- IOPortReadFunc *read;
- IOPortWriteFunc *write;
-};
-
-#define PORTIO_END_OF_LIST() { }
-
-/**
- * memory_region_init:
- * @mr: the #MemoryRegion to be initialized
- * @name: used for debugging; not visible to the user or ABI
- * @size: size of the region; any subregions beyond this size will be clipped
- *
- * Initialize a memory region
- *
- * The region typically acts as a container for other memory regions. Use
- * memory_region_add_subregion() to add subregions.
- */
-void memory_region_init(MemoryRegion *mr,
- const char *name,
- uint64_t size);
-/**
- * memory_region_init_io:
- * @mr: the #MemoryRegion to be initialized.
- * @ops: a structure containing read and write callbacks to be used when
- * I/O is performed on the region.
- * @opaque: passed to to the read and write callbacks of the @ops structure.
- * @name: used for debugging; not visible to the user or ABI
- * @size: size of the region.
- *
- * Initialize an I/O memory region.
- *
- * Accesses into the region will cause the callbacks in @ops to be called.
- * if @size is nonzero, subregions will be clipped to @size.
- */
-void memory_region_init_io(MemoryRegion *mr,
- const MemoryRegionOps *ops,
- void *opaque,
- const char *name,
- uint64_t size);
-
-/**
- * memory_region_init_ram:
- * @mr: the #MemoryRegion to be initialized.
- * @dev: a device associated with the region; may be #NULL.
- * @name: the name of the region; the pair (@dev, @name) must be globally
- * unique. The name is part of the save/restore ABI and so cannot be
- * changed.
- * @size: size of the region.
- *
- * Initialize RAM memory region. Accesses into the region will modify memory
- * directly.
- */
-void memory_region_init_ram(MemoryRegion *mr,
- DeviceState *dev, /* FIXME: layering violation */
- const char *name,
- uint64_t size);
-
-/**
- * memory_region_init_ram:
- * @mr: the #MemoryRegion to be initialized.
- * @dev: a device associated with the region; may be #NULL.
- * @name: the name of the region; the pair (@dev, @name) must be globally
- * unique. The name is part of the save/restore ABI and so cannot be
- * changed.
- * @size: size of the region.
- * @ptr: memory to be mapped; must contain at least @size bytes.
- *
- * Initialize RAM memory region from a user-provided pointer. Accesses into
- * the region will modify memory directly.
- */
-void memory_region_init_ram_ptr(MemoryRegion *mr,
- DeviceState *dev, /* FIXME: layering violation */
- const char *name,
- uint64_t size,
- void *ptr);
-
-/**
- * memory_region_init_alias:
- * @mr: the #MemoryRegion to be initialized.
- * @name: used for debugging; not visible to the user or ABI
- * @orig: the region to be referenced; @mr will be equivalent to
- * @orig between @offset and @offset + @size - 1.
- * @offset: start of the section in @orig to be referenced.
- * @size: size of the region.
- *
- * Initialize a memory region that aliases all or a part of another memory
- * region.
- */
-void memory_region_init_alias(MemoryRegion *mr,
- const char *name,
- MemoryRegion *orig,
- target_phys_addr_t offset,
- uint64_t size);
-
-/**
- * memory_region_init_rom_device:
- * @mr: the #MemoryRegion to be initialized.
- * @ops: callbacks for write access handling.
- * @dev: a device associated with the region; may be #NULL.
- * @name: the name of the region; the pair (@dev, @name) must be globally
- * unique. The name is part of the save/restore ABI and so cannot be
- * changed.
- * @size: size of the region.
- *
- * Initialize a ROM memory region. Writes are handled via callbacks.
- */
-void memory_region_init_rom_device(MemoryRegion *mr,
- const MemoryRegionOps *ops,
- void *opaque,
- DeviceState *dev, /* FIXME: layering violation */
- const char *name,
- uint64_t size);
-
-/**
- * memory_region_destroy:
- * @mr: the region to be destroyed. May not currently be a subregion
- * (see memory_region_add_subregion()) or referenced in an alias
- * (see memory_region_init_alias()).
- *
- * Destroy a memory region and reclaim all resources.
- */
-void memory_region_destroy(MemoryRegion *mr);
-
-/**
- * memory_region_size:
- * @mr: the memory region being queried.
- *
- * get a memory region's size.
- */
-uint64_t memory_region_size(MemoryRegion *mr);
-
-/**
- * memory_region_get_ram_ptr:
- * @mr: the memory region being queried.
- *
- * Get a pointer into a RAM memory region.
- *
- * Returns a host pointer to a RAM memory region (created with
- * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
- * care.
- */
-void *memory_region_get_ram_ptr(MemoryRegion *mr);
-
-/**
- * memory_region_set_offset:
- *
- * Sets an offset to be added to MemoryRegionOps callbacks.
- *
- * Deprecated: This should not be used in new code.
- */
-void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
-
-/**
- * memory_region_set_log:
- * @mr: the memory region being updated.
- * @log: whether dirty logging is to be enabled or disabled.
- * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
- * #DIRTY_MEMORY_VGA.
- *
- * Turn dirty logging on or off for a region.
- *
- * Turns dirty logging on or off for a specified client (display, migration).
- * Only meaningful for RAM regions.
- */
-void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
-
-/**
- * memory_region_get_dirty:
- * @mr: the memory region being queried.
- * @addr: the address (relative to the start of the region) being queried.
- * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
- * #DIRTY_MEMORY_VGA.
- *
- * Check whether a page is dirty for a specified client.
- *
- * Checks whether a page has been written to since the last
- * call to memory_region_reset_dirty() with the same @client. Dirty logging
- * must be enabled.
- */
-bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
- unsigned client);
-
-/**
- * memory_region_set_dirty:
- * @mr: the memory region being queried.
- * @addr: the address (relative to the start of the region) being dirtied.
- *
- * Mark a page as dirty in a memory region.
- *
- * Marks a page as dirty, after it has been dirtied outside guest code.
- */
-void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
-
-/**
- * memory_region_sync_dirty_bitmap:
- * @mr: the region being flushed.
- *
- * Synchronize a region's dirty bitmap with any external TLBs (e.g. kvm)
- *
- * Flushes dirty information from accelerators such as kvm and vhost-net
- * and makes it available to users of the memory API.
- */
-void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
-
-/**
- * memory_region_reset_dirty:
- * @mr: the region being updated.
- * @addr: the start of the subrange being cleaned.
- * @size: the size of the subrange being cleaned.
- * @client: the user of the logging information; #DIRTY_MEMORY_MIGRATION or
- * #DIRTY_MEMORY_VGA.
- *
- * Mark a range of pages as clean, for a specified client.
- *
- * Marks a range of pages as no longer dirty.
- */
-void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
- target_phys_addr_t size, unsigned client);
-
-/**
- * memory_region_set_readonly:
- * @mr: the region being updated.
- * @readonly: whether rhe region is to be ROM or RAM.
- *
- * Turn a memory region read-only (or read-write)
- *
- * Allows a memory region to be marked as read-only (turning it into a ROM).
- * only useful on RAM regions.
- */
-void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
-
-/**
- * memory_region_rom_device_set_readable:
- * @mr: the memory region to be updated
- * @readable: whether reads are satisified directly (#true) or via callbacks
- * (#false)
- *
- * Enable/disable ROM readability
- *
- * Allows a ROM device (initialized with memory_region_init_rom_device() to
- * to be marked as readable (default) or not readable. When it is readable,
- * the device is mapped to guest memory. When not readable, reads are
- * forwarded to the #MemoryRegion.read function.
- */
-void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
-
-/**
- * memory_region_set_coalescing:
- * @mr: the memory region to be write coalesced
- *
- * Enable memory coalescing for the region.
- *
- * Enabled writes to a region to be queued for later processing. MMIO ->write
- * callbacks may be delayed until a non-coalesced MMIO is issued.
- * Only useful for IO regions. Roughly similar to write-combining hardware.
- */
-void memory_region_set_coalescing(MemoryRegion *mr);
-
-/**
- * memory_region_add_coalescing:
- * @mr: the memory region to be updated.
- * @offset: the start of the range within the region to be coalesced.
- * @size: the size of the subrange to be coalesced.
- *
- * Enable memory coalescing for a sub-range of a region.
- *
- * Like memory_region_set_coalescing(), but works on a sub-range of a region.
- * Multiple calls can be issued coalesced disjoint ranges.
- */
-void memory_region_add_coalescing(MemoryRegion *mr,
- target_phys_addr_t offset,
- uint64_t size);
-
-/**
- * memory_region_clear_coalescing:
- * @mr: the memory region to be updated.
- *
- * Disable MMIO coalescing for the region.
- *
- * Disables any coalescing caused by memory_region_set_coalescing() or
- * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
- * hardware.
- */
-void memory_region_clear_coalescing(MemoryRegion *mr);
-
-/**
- * memory_region_add_eventfd:
- * @mr: the memory region being updated.
- * @addr: the address within @mr that is to be monitored
- * @size: the size of the access to trigger the eventfd
- * @match_data: whether to match against @data, instead of just @addr
- * @data: the data to match against the guest write
- * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
- *
- * Request an eventfd to be triggered when a word is written to a location.
- *
- * Marks a word in an IO region (initialized with memory_region_init_io())
- * as a trigger for an eventfd event. The I/O callback will not be called.
- * The caller must be prepared to handle failure (that is, take the required
- * action if the callback _is_ called).
- **/
-void memory_region_add_eventfd(MemoryRegion *mr,
- target_phys_addr_t addr,
- unsigned size,
- bool match_data,
- uint64_t data,
- int fd);
-
-/**
- * memory_region_del_eventfd:
- * @mr: the memory region being updated.
- * @addr: the address within @mr that is to be monitored
- * @size: the size of the access to trigger the eventfd
- * @match_data: whether to match against @data, instead of just @addr
- * @data: the data to match against the guest write
- * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
- *
- * Cancel an eventfd.
- *
- * Cancels an eventfd trigger requested by a previous
- * memory_region_add_eventfd() call.
- */
-void memory_region_del_eventfd(MemoryRegion *mr,
- target_phys_addr_t addr,
- unsigned size,
- bool match_data,
- uint64_t data,
- int fd);
-/**
- * memory_region_add_subregion:
- * @mr: the region to contain the new subregion; must be a container
- * initialized with memory_region_init().
- * @offset: the offset relative to @mr where @subregion is added.
- * @subregion: the subregion to be added.
- *
- * Add a subregion to a container.
- *
- * Adds a subregion at @offset. The subregion may not overlap with other
- * subregions (except for those explicitly marked as overlapping). A region
- * may only be added once as a subregion (unless removed with
- * memory_region_del_subregion()); use memory_region_init_alias() if you
- * want a region to be a subregion in multiple locations.
- */
-void memory_region_add_subregion(MemoryRegion *mr,
- target_phys_addr_t offset,
- MemoryRegion *subregion);
-/**
- * memory_region_add_subregion:
- * @mr: the region to contain the new subregion; must be a container
- * initialized with memory_region_init().
- * @offset: the offset relative to @mr where @subregion is added.
- * @subregion: the subregion to be added.
- * @priority: used for resolving overlaps; highest priority wins.
- *
- * Add a subregion to a container, with overlap.
- *
- * Adds a subregion at @offset. The subregion may overlap with other
- * subregions. Conflicts are resolved by having a higher @priority hide a
- * lower @priority. Subregions without priority are taken as @priority 0.
- * A region may only be added once as a subregion (unless removed with
- * memory_region_del_subregion()); use memory_region_init_alias() if you
- * want a region to be a subregion in multiple locations.
- */
-void memory_region_add_subregion_overlap(MemoryRegion *mr,
- target_phys_addr_t offset,
- MemoryRegion *subregion,
- unsigned priority);
-/**
- * memory_region_del_subregion:
- * @mr: the container to be updated.
- * @subregion: the region being removed; must be a current subregion of @mr.
- *
- * Remove a subregion.
- *
- * Removes a subregion from its container.
- */
-void memory_region_del_subregion(MemoryRegion *mr,
- MemoryRegion *subregion);
-
-/**
- * memory_region_transaction_begin:
- *
- * Start a transaction.
- *
- * During a transaction, changes will be accumulated and made visible
- * only when the transaction ends (is commited).
- */
-void memory_region_transaction_begin(void);
-
-/**
- * memory_region_transaction_commit:
- *
- * Commit a transaction and make changes visible to the guest.
- */
-void memory_region_transaction_commit(void);
-
-void mtree_info(fprintf_function mon_printf, void *f);
-
-#endif
-
-#endif
Signed-off-by: Anthony Liguori <aliguori@us.ibm.com> --- QEMU-docs.xml | 1 + include/memory.h | 566 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ memory.h | 566 ------------------------------------------------------ 3 files changed, 567 insertions(+), 566 deletions(-) create mode 100644 include/memory.h delete mode 100644 memory.h