[libvirt] [PULL v2 24/43] memory-device: document MemoryDeviceClass
From: David Hildenbrand <david(a)redhat.com>
Document the functions. Don't document get_region_size(), as we will be
dropping/replacing that one soon.
Use same documentation style as in include/exec/memory.h, but don't
document the parameters, as they are self-explanatory.
Reviewed-by: David Gibson <david(a)gibson.dropbear.id.au>
Reviewed-by: Igor Mammedov <imammedo(a)redhat.com>
Signed-off-by: David Hildenbrand <david(a)redhat.com>
Message-Id: <20181005092024.14344-9-david(a)redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost(a)redhat.com>
---
include/hw/mem/memory-device.h | 36 ++++++++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
diff --git a/include/hw/mem/memory-device.h b/include/hw/mem/memory-device.h
index f02b229837..0474a3dd11 100644
--- a/include/hw/mem/memory-device.h
+++ b/include/hw/mem/memory-device.h
@@ -29,12 +29,48 @@ typedef struct MemoryDeviceState {
Object parent_obj;
} MemoryDeviceState;
+/**
+ * MemoryDeviceClass:
+ *
+ * All memory devices need to implement TYPE_MEMORY_DEVICE as an interface.
+ *
+ * A memory device is a device that owns a memory region which is
+ * mapped into guest physical address space at a certain address. The
+ * address in guest physical memory can either be specified explicitly
+ * or get assigned automatically.
+ */
typedef struct MemoryDeviceClass {
+ /* private */
InterfaceClass parent_class;
+ /*
+ * Return the address of the memory device in guest physical memory.
+ *
+ * Called when (un)plugging a memory device or when iterating over
+ * all memory devices mapped into guest physical address space.
+ *
+ * If "0" is returned, no address has been specified by the user and
+ * no address has been assigned to this memory device yet.
+ */
uint64_t (*get_addr)(const MemoryDeviceState *md);
+
+ /*
+ * Return the amount of memory provided by the memory device currently
+ * usable ("plugged") by the VM.
+ *
+ * Called when calculating the total amount of ram available to the
+ * VM (e.g. to report memory stats to the user).
+ *
+ * This is helpful for devices that dynamically manage the amount of
+ * memory accessible by the guest via the reserved memory region. For
+ * most devices, this corresponds to the size of the memory region.
+ */
uint64_t (*get_plugged_size)(const MemoryDeviceState *md, Error **errp);
uint64_t (*get_region_size)(const MemoryDeviceState *md, Error **errp);
+
+ /*
+ * Translate the memory device into #MemoryDeviceInfo.
+ */
void (*fill_device_info)(const MemoryDeviceState *md,
MemoryDeviceInfo *info);
} MemoryDeviceClass;
--
2.18.0.rc1.1.g3f1ff2140