Merge remote-tracking branch 'remotes/vivier/tags/trivial-branch-for-6.2-pull-request...
[qemu.git] / include / hw / mem / memory-device.h
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 struct MemoryDeviceClass {
46 /* private */
47 InterfaceClass parent_class;
48
49 /*
50 * Return the address of the memory device in guest physical memory.
51 *
52 * Called when (un)plugging a memory device or when iterating over
53 * all memory devices mapped into guest physical address space.
54 *
55 * If "0" is returned, no address has been specified by the user and
56 * no address has been assigned to this memory device yet.
57 */
58 uint64_t (*get_addr)(const MemoryDeviceState *md);
59
60 /*
61 * Set the address of the memory device in guest physical memory.
62 *
63 * Called when plugging the memory device to configure the determined
64 * address in guest physical memory.
65 */
66 void (*set_addr)(MemoryDeviceState *md, uint64_t addr, Error **errp);
67
68 /*
69 * Return the amount of memory provided by the memory device currently
70 * usable ("plugged") by the VM.
71 *
72 * Called when calculating the total amount of ram available to the
73 * VM (e.g. to report memory stats to the user).
74 *
75 * This is helpful for devices that dynamically manage the amount of
76 * memory accessible by the guest via the reserved memory region. For
77 * most devices, this corresponds to the size of the memory region.
78 */
79 uint64_t (*get_plugged_size)(const MemoryDeviceState *md, Error **errp);
80
81 /*
82 * Return the memory region of the memory device.
83 *
84 * Called when (un)plugging the memory device, to (un)map the
85 * memory region in guest physical memory, but also to detect the
86 * required alignment during address assignment or when the size of the
87 * memory region is required.
88 */
89 MemoryRegion *(*get_memory_region)(MemoryDeviceState *md, Error **errp);
90
91 /*
92 * Optional: Return the desired minimum alignment of the device in guest
93 * physical address space. The final alignment is computed based on this
94 * alignment and the alignment requirements of the memory region.
95 *
96 * Called when plugging the memory device to detect the required alignment
97 * during address assignment.
98 */
99 uint64_t (*get_min_alignment)(const MemoryDeviceState *md);
100
101 /*
102 * Translate the memory device into #MemoryDeviceInfo.
103 */
104 void (*fill_device_info)(const MemoryDeviceState *md,
105 MemoryDeviceInfo *info);
106 };
107
108 MemoryDeviceInfoList *qmp_memory_device_list(void);
109 uint64_t get_plugged_memory_size(void);
110 void memory_device_pre_plug(MemoryDeviceState *md, MachineState *ms,
111 const uint64_t *legacy_align, Error **errp);
112 void memory_device_plug(MemoryDeviceState *md, MachineState *ms);
113 void memory_device_unplug(MemoryDeviceState *md, MachineState *ms);
114 uint64_t memory_device_get_region_size(const MemoryDeviceState *md,
115 Error **errp);
116
117 #endif