1 /* 2 * Memory Device Interface 3 * 4 * Copyright (c) 2018 Red Hat, Inc. 5 * 6 * Authors: 7 * David Hildenbrand <david@redhat.com> 8 * 9 * This work is licensed under the terms of the GNU GPL, version 2 or later. 10 * See the COPYING file in the top-level directory. 11 */ 12 13 #ifndef MEMORY_DEVICE_H 14 #define MEMORY_DEVICE_H 15 16 #include "hw/qdev-core.h" 17 #include "qapi/qapi-types-machine.h" 18 #include "qom/object.h" 19 20 #define TYPE_MEMORY_DEVICE "memory-device" 21 22 typedef struct MemoryDeviceClass MemoryDeviceClass; 23 DECLARE_CLASS_CHECKERS(MemoryDeviceClass, MEMORY_DEVICE, 24 TYPE_MEMORY_DEVICE) 25 #define MEMORY_DEVICE(obj) \ 26 INTERFACE_CHECK(MemoryDeviceState, (obj), TYPE_MEMORY_DEVICE) 27 28 typedef struct MemoryDeviceState MemoryDeviceState; 29 30 /** 31 * MemoryDeviceClass: 32 * 33 * All memory devices need to implement TYPE_MEMORY_DEVICE as an interface. 34 * 35 * A memory device is a device that owns a memory region which is 36 * mapped into guest physical address space at a certain address. The 37 * address in guest physical memory can either be specified explicitly 38 * or get assigned automatically. 39 * 40 * Conceptually, memory devices only span one memory region. If multiple 41 * successive memory regions are used, a covering memory region has to 42 * be provided. Scattered memory regions are not supported for single 43 * devices. 44 * 45 * The device memory region returned via @get_memory_region may either be a 46 * single RAM memory region or a memory region container with subregions 47 * that are RAM memory regions or aliases to RAM memory regions. Other 48 * memory regions or subregions are not supported. 49 */ 50 struct MemoryDeviceClass { 51 /* private */ 52 InterfaceClass parent_class; 53 54 /* 55 * Return the address of the memory device in guest physical memory. 56 * 57 * Called when (un)plugging a memory device or when iterating over 58 * all memory devices mapped into guest physical address space. 59 * 60 * If "0" is returned, no address has been specified by the user and 61 * no address has been assigned to this memory device yet. 62 */ 63 uint64_t (*get_addr)(const MemoryDeviceState *md); 64 65 /* 66 * Set the address of the memory device in guest physical memory. 67 * 68 * Called when plugging the memory device to configure the determined 69 * address in guest physical memory. 70 */ 71 void (*set_addr)(MemoryDeviceState *md, uint64_t addr, Error **errp); 72 73 /* 74 * Return the amount of memory provided by the memory device currently 75 * usable ("plugged") by the VM. 76 * 77 * Called when calculating the total amount of ram available to the 78 * VM (e.g. to report memory stats to the user). 79 * 80 * This is helpful for devices that dynamically manage the amount of 81 * memory accessible by the guest via the reserved memory region. For 82 * most devices, this corresponds to the size of the memory region. 83 */ 84 uint64_t (*get_plugged_size)(const MemoryDeviceState *md, Error **errp); 85 86 /* 87 * Return the memory region of the memory device. 88 * 89 * Called when (un)plugging the memory device, to (un)map the 90 * memory region in guest physical memory, but also to detect the 91 * required alignment during address assignment or when the size of the 92 * memory region is required. 93 */ 94 MemoryRegion *(*get_memory_region)(MemoryDeviceState *md, Error **errp); 95 96 /* 97 * Optional for memory devices that require only a single memslot, 98 * required for all other memory devices: Return the number of memslots 99 * (distinct RAM memory regions in the device memory region) that are 100 * required by the device. 101 * 102 * If this function is not implemented, the assumption is "1". 103 * 104 * Called when (un)plugging the memory device, to check if the requirements 105 * can be satisfied, and to do proper accounting. 106 */ 107 unsigned int (*get_memslots)(MemoryDeviceState *md); 108 109 /* 110 * Optional: Return the desired minimum alignment of the device in guest 111 * physical address space. The final alignment is computed based on this 112 * alignment and the alignment requirements of the memory region. 113 * 114 * Called when plugging the memory device to detect the required alignment 115 * during address assignment. 116 */ 117 uint64_t (*get_min_alignment)(const MemoryDeviceState *md); 118 119 /* 120 * Translate the memory device into #MemoryDeviceInfo. 121 */ 122 void (*fill_device_info)(const MemoryDeviceState *md, 123 MemoryDeviceInfo *info); 124 }; 125 126 MemoryDeviceInfoList *qmp_memory_device_list(void); 127 uint64_t get_plugged_memory_size(void); 128 void memory_device_pre_plug(MemoryDeviceState *md, MachineState *ms, 129 const uint64_t *legacy_align, Error **errp); 130 void memory_device_plug(MemoryDeviceState *md, MachineState *ms); 131 void memory_device_unplug(MemoryDeviceState *md, MachineState *ms); 132 uint64_t memory_device_get_region_size(const MemoryDeviceState *md, 133 Error **errp); 134 135 #endif 136