memory: include MemoryListener documentation and some missing function parameters
These cover the remaining warnings from kernel-doc. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Message-Id: <20191029162248.13383-7-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
This commit is contained in:
Paolo Bonzini
parent
f3224c5285
commit
5d24821318
@ -423,30 +423,232 @@ struct IOMMUMemoryRegion {
|
||||
* Use with memory_listener_register() and memory_listener_unregister().
|
||||
*/
|
||||
struct MemoryListener {
|
||||
/**
|
||||
* @begin:
|
||||
*
|
||||
* Called at the beginning of an address space update transaction.
|
||||
* Followed by calls to #MemoryListener.region_add(),
|
||||
* #MemoryListener.region_del(), #MemoryListener.region_nop(),
|
||||
* #MemoryListener.log_start() and #MemoryListener.log_stop() in
|
||||
* increasing address order.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
*/
|
||||
void (*begin)(MemoryListener *listener);
|
||||
|
||||
/**
|
||||
* @commit:
|
||||
*
|
||||
* Called at the end of an address space update transaction,
|
||||
* after the last call to #MemoryListener.region_add(),
|
||||
* #MemoryListener.region_del() or #MemoryListener.region_nop(),
|
||||
* #MemoryListener.log_start() and #MemoryListener.log_stop().
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
*/
|
||||
void (*commit)(MemoryListener *listener);
|
||||
|
||||
/**
|
||||
* @region_add:
|
||||
*
|
||||
* Called during an address space update transaction,
|
||||
* for a section of the address space that is new in this address space
|
||||
* space since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The new #MemoryRegionSection.
|
||||
*/
|
||||
void (*region_add)(MemoryListener *listener, MemoryRegionSection *section);
|
||||
|
||||
/**
|
||||
* @region_del:
|
||||
*
|
||||
* Called during an address space update transaction,
|
||||
* for a section of the address space that has disappeared in the address
|
||||
* space since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The old #MemoryRegionSection.
|
||||
*/
|
||||
void (*region_del)(MemoryListener *listener, MemoryRegionSection *section);
|
||||
|
||||
/**
|
||||
* @region_nop:
|
||||
*
|
||||
* Called during an address space update transaction,
|
||||
* for a section of the address space that is in the same place in the address
|
||||
* space as in the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The #MemoryRegionSection.
|
||||
*/
|
||||
void (*region_nop)(MemoryListener *listener, MemoryRegionSection *section);
|
||||
|
||||
/**
|
||||
* @log_start:
|
||||
*
|
||||
* Called during an address space update transaction, after
|
||||
* one of #MemoryListener.region_add(),#MemoryListener.region_del() or
|
||||
* #MemoryListener.region_nop(), if dirty memory logging clients have
|
||||
* become active since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The #MemoryRegionSection.
|
||||
* @old: A bitmap of dirty memory logging clients that were active in
|
||||
* the previous transaction.
|
||||
* @new: A bitmap of dirty memory logging clients that are active in
|
||||
* the current transaction.
|
||||
*/
|
||||
void (*log_start)(MemoryListener *listener, MemoryRegionSection *section,
|
||||
int old, int new);
|
||||
|
||||
/**
|
||||
* @log_stop:
|
||||
*
|
||||
* Called during an address space update transaction, after
|
||||
* one of #MemoryListener.region_add(), #MemoryListener.region_del() or
|
||||
* #MemoryListener.region_nop() and possibly after
|
||||
* #MemoryListener.log_start(), if dirty memory logging clients have
|
||||
* become inactive since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The #MemoryRegionSection.
|
||||
* @old: A bitmap of dirty memory logging clients that were active in
|
||||
* the previous transaction.
|
||||
* @new: A bitmap of dirty memory logging clients that are active in
|
||||
* the current transaction.
|
||||
*/
|
||||
void (*log_stop)(MemoryListener *listener, MemoryRegionSection *section,
|
||||
int old, int new);
|
||||
|
||||
/**
|
||||
* @log_sync:
|
||||
*
|
||||
* Called by memory_region_snapshot_and_clear_dirty() and
|
||||
* memory_global_dirty_log_sync(), before accessing QEMU's "official"
|
||||
* copy of the dirty memory bitmap for a #MemoryRegionSection.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The #MemoryRegionSection.
|
||||
*/
|
||||
void (*log_sync)(MemoryListener *listener, MemoryRegionSection *section);
|
||||
|
||||
/**
|
||||
* @log_clear:
|
||||
*
|
||||
* Called before reading the dirty memory bitmap for a
|
||||
* #MemoryRegionSection.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The #MemoryRegionSection.
|
||||
*/
|
||||
void (*log_clear)(MemoryListener *listener, MemoryRegionSection *section);
|
||||
|
||||
/**
|
||||
* @log_global_start:
|
||||
*
|
||||
* Called by memory_global_dirty_log_start(), which
|
||||
* enables the %DIRTY_LOG_MIGRATION client on all memory regions in
|
||||
* the address space. #MemoryListener.log_global_start() is also
|
||||
* called when a #MemoryListener is added, if global dirty logging is
|
||||
* active at that time.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
*/
|
||||
void (*log_global_start)(MemoryListener *listener);
|
||||
|
||||
/**
|
||||
* @log_global_stop:
|
||||
*
|
||||
* Called by memory_global_dirty_log_stop(), which
|
||||
* disables the %DIRTY_LOG_MIGRATION client on all memory regions in
|
||||
* the address space.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
*/
|
||||
void (*log_global_stop)(MemoryListener *listener);
|
||||
|
||||
/**
|
||||
* @log_global_after_sync:
|
||||
*
|
||||
* Called after reading the dirty memory bitmap
|
||||
* for any #MemoryRegionSection.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
*/
|
||||
void (*log_global_after_sync)(MemoryListener *listener);
|
||||
|
||||
/**
|
||||
* @eventfd_add:
|
||||
*
|
||||
* Called during an address space update transaction,
|
||||
* for a section of the address space that has had a new ioeventfd
|
||||
* registration since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The new #MemoryRegionSection.
|
||||
* @match_data: The @match_data parameter for the new ioeventfd.
|
||||
* @data: The @data parameter for the new ioeventfd.
|
||||
* @e: The #EventNotifier parameter for the new ioeventfd.
|
||||
*/
|
||||
void (*eventfd_add)(MemoryListener *listener, MemoryRegionSection *section,
|
||||
bool match_data, uint64_t data, EventNotifier *e);
|
||||
|
||||
/**
|
||||
* @eventfd_del:
|
||||
*
|
||||
* Called during an address space update transaction,
|
||||
* for a section of the address space that has dropped an ioeventfd
|
||||
* registration since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The new #MemoryRegionSection.
|
||||
* @match_data: The @match_data parameter for the dropped ioeventfd.
|
||||
* @data: The @data parameter for the dropped ioeventfd.
|
||||
* @e: The #EventNotifier parameter for the dropped ioeventfd.
|
||||
*/
|
||||
void (*eventfd_del)(MemoryListener *listener, MemoryRegionSection *section,
|
||||
bool match_data, uint64_t data, EventNotifier *e);
|
||||
|
||||
/**
|
||||
* @coalesced_io_add:
|
||||
*
|
||||
* Called during an address space update transaction,
|
||||
* for a section of the address space that has had a new coalesced
|
||||
* MMIO range registration since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The new #MemoryRegionSection.
|
||||
* @addr: The starting address for the coalesced MMIO range.
|
||||
* @len: The length of the coalesced MMIO range.
|
||||
*/
|
||||
void (*coalesced_io_add)(MemoryListener *listener, MemoryRegionSection *section,
|
||||
hwaddr addr, hwaddr len);
|
||||
|
||||
/**
|
||||
* @coalesced_io_del:
|
||||
*
|
||||
* Called during an address space update transaction,
|
||||
* for a section of the address space that has dropped a coalesced
|
||||
* MMIO range since the last transaction.
|
||||
*
|
||||
* @listener: The #MemoryListener.
|
||||
* @section: The new #MemoryRegionSection.
|
||||
* @addr: The starting address for the coalesced MMIO range.
|
||||
* @len: The length of the coalesced MMIO range.
|
||||
*/
|
||||
void (*coalesced_io_del)(MemoryListener *listener, MemoryRegionSection *section,
|
||||
hwaddr addr, hwaddr len);
|
||||
/* Lower = earlier (during add), later (during del) */
|
||||
/**
|
||||
* @priority:
|
||||
*
|
||||
* Govern the order in which memory listeners are invoked. Lower priorities
|
||||
* are invoked earlier for "add" or "start" callbacks, and later for "delete"
|
||||
* or "stop" callbacks.
|
||||
*/
|
||||
unsigned priority;
|
||||
|
||||
/* private: */
|
||||
AddressSpace *address_space;
|
||||
QTAILQ_ENTRY(MemoryListener) link;
|
||||
QTAILQ_ENTRY(MemoryListener) link_as;
|
||||
@ -940,6 +1142,7 @@ void memory_region_init_rom(MemoryRegion *mr,
|
||||
* @mr: the #MemoryRegion to be initialized.
|
||||
* @owner: the object that tracks the region's reference count
|
||||
* @ops: callbacks for write access handling (must not be NULL).
|
||||
* @opaque: passed to the read and write callbacks of the @ops structure.
|
||||
* @name: Region name, becomes part of RAMBlock name used in migration stream
|
||||
* must be unique within any device
|
||||
* @size: size of the region.
|
||||
@ -1028,7 +1231,7 @@ static inline IOMMUMemoryRegion *memory_region_get_iommu(MemoryRegion *mr)
|
||||
* Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu,
|
||||
* otherwise NULL. This is fast path avoiding QOM checking, use with caution.
|
||||
*
|
||||
* @mr: the memory region being queried
|
||||
* @iommu_mr: the memory region being queried
|
||||
*/
|
||||
static inline IOMMUMemoryRegionClass *memory_region_get_iommu_class_nocheck(
|
||||
IOMMUMemoryRegion *iommu_mr)
|
||||
@ -1098,6 +1301,7 @@ void memory_region_notify_one(IOMMUNotifier *notifier,
|
||||
* @n: the IOMMUNotifier to be added; the notify callback receives a
|
||||
* pointer to an #IOMMUTLBEntry as the opaque value; the pointer
|
||||
* ceases to be valid on exit from the notifier.
|
||||
* @errp: pointer to Error*, to store an error if it happens.
|
||||
*/
|
||||
int memory_region_register_iommu_notifier(MemoryRegion *mr,
|
||||
IOMMUNotifier *n, Error **errp);
|
||||
@ -1270,9 +1474,12 @@ void *memory_region_get_ram_ptr(MemoryRegion *mr);
|
||||
void memory_region_ram_resize(MemoryRegion *mr, ram_addr_t newsize,
|
||||
Error **errp);
|
||||
/**
|
||||
* memory_region_do_writeback: Trigger writeback for selected address range
|
||||
* [addr, addr + size]
|
||||
* memory_region_do_writeback: Trigger cache writeback or msync for
|
||||
* selected address range
|
||||
*
|
||||
* @mr: the memory region to be updated
|
||||
* @addr: the initial address of the range to be written back
|
||||
* @size: the size of the range to be written back
|
||||
*/
|
||||
void memory_region_do_writeback(MemoryRegion *mr, hwaddr addr, hwaddr size);
|
||||
|
||||
@ -1591,6 +1798,8 @@ void memory_region_add_subregion_overlap(MemoryRegion *mr,
|
||||
/**
|
||||
* memory_region_get_ram_addr: Get the ram address associated with a memory
|
||||
* region
|
||||
*
|
||||
* @mr: the region to be queried
|
||||
*/
|
||||
ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr);
|
||||
|
||||
@ -2161,6 +2370,7 @@ static inline bool memory_access_is_direct(MemoryRegion *mr, bool is_write)
|
||||
* @addr: address within that address space
|
||||
* @attrs: memory transaction attributes
|
||||
* @buf: buffer with the data transferred
|
||||
* @len: length of the data transferred
|
||||
*/
|
||||
static inline __attribute__((__always_inline__))
|
||||
MemTxResult address_space_read(AddressSpace *as, hwaddr addr,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user