blob: 6fa0b071f04d30a3d258b3fc864c8cd7a44f9e2c [file] [log] [blame]
Avi Kivity093bc2c2011-07-26 14:26:01 +03001/*
2 * Physical memory management API
3 *
4 * Copyright 2011 Red Hat, Inc. and/or its affiliates
5 *
6 * Authors:
7 * Avi Kivity <avi@redhat.com>
8 *
9 * This work is licensed under the terms of the GNU GPL, version 2. See
10 * the COPYING file in the top-level directory.
11 *
12 */
13
14#ifndef MEMORY_H
15#define MEMORY_H
16
17#ifndef CONFIG_USER_ONLY
18
Paolo Bonzini022c62c2012-12-17 18:19:49 +010019#include "exec/cpu-common.h"
20#include "exec/hwaddr.h"
Peter Maydellcc05c432015-04-26 16:49:23 +010021#include "exec/memattrs.h"
Tony Nguyene67c9042019-08-24 04:36:48 +100022#include "exec/memop.h"
Paolo Bonzini0987d732016-12-21 00:31:36 +080023#include "exec/ramlist.h"
Markus Armbruster1b53ecd2019-08-12 07:23:34 +020024#include "qemu/bswap.h"
Paolo Bonzini1de7afc2012-12-17 18:20:00 +010025#include "qemu/queue.h"
Paolo Bonzini1de7afc2012-12-17 18:20:00 +010026#include "qemu/int128.h"
David Gibson06866572013-05-14 19:13:56 +100027#include "qemu/notify.h"
Peter Crosthwaiteb4fefef2014-06-05 23:15:52 -070028#include "qom/object.h"
Paolo Bonzini374f2982013-05-17 12:37:03 +020029#include "qemu/rcu.h"
Avi Kivity093bc2c2011-07-26 14:26:01 +030030
Paolo Bonzini07bdaa42016-03-25 12:55:08 +010031#define RAM_ADDR_INVALID (~(ram_addr_t)0)
32
Paolo Bonzini052e87b2013-05-27 10:08:27 +020033#define MAX_PHYS_ADDR_SPACE_BITS 62
34#define MAX_PHYS_ADDR (((hwaddr)1 << MAX_PHYS_ADDR_SPACE_BITS) - 1)
35
Markus Armbrusterbb3c92e2021-03-04 15:02:29 +010036#define TYPE_MEMORY_REGION "memory-region"
Eduardo Habkost8110fa12020-08-31 17:07:33 -040037DECLARE_INSTANCE_CHECKER(MemoryRegion, MEMORY_REGION,
38 TYPE_MEMORY_REGION)
Peter Crosthwaiteb4fefef2014-06-05 23:15:52 -070039
Markus Armbrusterbb3c92e2021-03-04 15:02:29 +010040#define TYPE_IOMMU_MEMORY_REGION "iommu-memory-region"
Eduardo Habkostdb1015e2020-09-03 16:43:22 -040041typedef struct IOMMUMemoryRegionClass IOMMUMemoryRegionClass;
Eduardo Habkost8110fa12020-08-31 17:07:33 -040042DECLARE_OBJ_CHECKERS(IOMMUMemoryRegion, IOMMUMemoryRegionClass,
43 IOMMU_MEMORY_REGION, TYPE_IOMMU_MEMORY_REGION)
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +100044
David Hildenbrand8947d7f2021-04-13 11:55:19 +020045#define TYPE_RAM_DISCARD_MANAGER "qemu:ram-discard-manager"
46typedef struct RamDiscardManagerClass RamDiscardManagerClass;
47typedef struct RamDiscardManager RamDiscardManager;
48DECLARE_OBJ_CHECKERS(RamDiscardManager, RamDiscardManagerClass,
49 RAM_DISCARD_MANAGER, TYPE_RAM_DISCARD_MANAGER);
50
Alexander Bulekov20f5a302020-10-23 11:07:33 -040051#ifdef CONFIG_FUZZ
52void fuzz_dma_read_cb(size_t addr,
53 size_t len,
Alexander Bulekovfc1c8342021-01-20 01:02:55 -050054 MemoryRegion *mr);
Alexander Bulekove7d32222020-10-23 11:07:34 -040055#else
56static inline void fuzz_dma_read_cb(size_t addr,
57 size_t len,
Alexander Bulekovfc1c8342021-01-20 01:02:55 -050058 MemoryRegion *mr)
Alexander Bulekove7d32222020-10-23 11:07:34 -040059{
60 /* Do Nothing */
61}
Alexander Bulekov20f5a302020-10-23 11:07:33 -040062#endif
63
Hyman Huang(黄勇)63b41db2021-06-29 16:01:19 +000064/* Possible bits for global_dirty_log_{start|stop} */
65
66/* Dirty tracking enabled because migration is running */
67#define GLOBAL_DIRTY_MIGRATION (1U << 0)
68
69/* Dirty tracking enabled because measuring dirty rate */
70#define GLOBAL_DIRTY_DIRTY_RATE (1U << 1)
71
Hyman Huang(黄勇)cc2b33e2022-06-26 01:38:33 +080072/* Dirty tracking enabled because dirty limit */
73#define GLOBAL_DIRTY_LIMIT (1U << 2)
74
75#define GLOBAL_DIRTY_MASK (0x7)
Hyman Huang(黄勇)63b41db2021-06-29 16:01:19 +000076
77extern unsigned int global_dirty_tracking;
Peter Xuae7a2bc2019-06-03 14:50:48 +080078
Avi Kivity093bc2c2011-07-26 14:26:01 +030079typedef struct MemoryRegionOps MemoryRegionOps;
Avi Kivity74901c32011-07-26 14:26:10 +030080
Eric Augerf7806922020-07-03 16:59:41 +010081struct ReservedRegion {
82 hwaddr low;
83 hwaddr high;
84 unsigned type;
85};
86
David Hildenbrand8947d7f2021-04-13 11:55:19 +020087/**
88 * struct MemoryRegionSection: describes a fragment of a #MemoryRegion
89 *
90 * @mr: the region, or %NULL if empty
91 * @fv: the flat view of the address space the region is mapped in
92 * @offset_within_region: the beginning of the section, relative to @mr's start
93 * @size: the size of the section; will not exceed @mr's boundaries
94 * @offset_within_address_space: the address of the first byte of the section
95 * relative to the region's address space
96 * @readonly: writes to this section are ignored
97 * @nonvolatile: this section is non-volatile
98 */
99struct MemoryRegionSection {
100 Int128 size;
101 MemoryRegion *mr;
102 FlatView *fv;
103 hwaddr offset_within_region;
104 hwaddr offset_within_address_space;
105 bool readonly;
106 bool nonvolatile;
107};
108
Avi Kivity30951152012-10-30 13:47:46 +0200109typedef struct IOMMUTLBEntry IOMMUTLBEntry;
110
111/* See address_space_translate: bit 0 is read, bit 1 is write. */
112typedef enum {
113 IOMMU_NONE = 0,
114 IOMMU_RO = 1,
115 IOMMU_WO = 2,
116 IOMMU_RW = 3,
117} IOMMUAccessFlags;
118
Peter Xuf06a6962017-04-07 18:59:13 +0800119#define IOMMU_ACCESS_FLAG(r, w) (((r) ? IOMMU_RO : 0) | ((w) ? IOMMU_WO : 0))
120
Avi Kivity30951152012-10-30 13:47:46 +0200121struct IOMMUTLBEntry {
122 AddressSpace *target_as;
123 hwaddr iova;
124 hwaddr translated_addr;
125 hwaddr addr_mask; /* 0xfff = 4k translation */
126 IOMMUAccessFlags perm;
127};
128
Peter Xucdb30812016-09-23 13:02:26 +0800129/*
130 * Bitmap for different IOMMUNotifier capabilities. Each notifier can
131 * register with one or multiple IOMMU Notifier capability bit(s).
Peter Xu8a7c6062023-01-09 14:37:27 -0500132 *
133 * Normally there're two use cases for the notifiers:
134 *
135 * (1) When the device needs accurate synchronizations of the vIOMMU page
136 * tables, it needs to register with both MAP|UNMAP notifies (which
137 * is defined as IOMMU_NOTIFIER_IOTLB_EVENTS below).
138 *
139 * Regarding to accurate synchronization, it's when the notified
140 * device maintains a shadow page table and must be notified on each
141 * guest MAP (page table entry creation) and UNMAP (invalidation)
142 * events (e.g. VFIO). Both notifications must be accurate so that
143 * the shadow page table is fully in sync with the guest view.
144 *
145 * (2) When the device doesn't need accurate synchronizations of the
146 * vIOMMU page tables, it needs to register only with UNMAP or
147 * DEVIOTLB_UNMAP notifies.
148 *
149 * It's when the device maintains a cache of IOMMU translations
150 * (IOTLB) and is able to fill that cache by requesting translations
151 * from the vIOMMU through a protocol similar to ATS (Address
152 * Translation Service).
153 *
154 * Note that in this mode the vIOMMU will not maintain a shadowed
155 * page table for the address space, and the UNMAP messages can cover
156 * more than the pages that used to get mapped. The IOMMU notifiee
157 * should be able to take care of over-sized invalidations.
Peter Xucdb30812016-09-23 13:02:26 +0800158 */
159typedef enum {
160 IOMMU_NOTIFIER_NONE = 0,
161 /* Notify cache invalidations */
162 IOMMU_NOTIFIER_UNMAP = 0x1,
163 /* Notify entry changes (newly created entries) */
164 IOMMU_NOTIFIER_MAP = 0x2,
Eugenio Pérezb68ba1c2020-11-16 17:55:04 +0100165 /* Notify changes on device IOTLB entries */
166 IOMMU_NOTIFIER_DEVIOTLB_UNMAP = 0x04,
Peter Xucdb30812016-09-23 13:02:26 +0800167} IOMMUNotifierFlag;
168
Eugenio Pérezb68ba1c2020-11-16 17:55:04 +0100169#define IOMMU_NOTIFIER_IOTLB_EVENTS (IOMMU_NOTIFIER_MAP | IOMMU_NOTIFIER_UNMAP)
170#define IOMMU_NOTIFIER_DEVIOTLB_EVENTS IOMMU_NOTIFIER_DEVIOTLB_UNMAP
171#define IOMMU_NOTIFIER_ALL (IOMMU_NOTIFIER_IOTLB_EVENTS | \
172 IOMMU_NOTIFIER_DEVIOTLB_EVENTS)
Peter Xucdb30812016-09-23 13:02:26 +0800173
Peter Xu698feb52017-04-07 18:59:07 +0800174struct IOMMUNotifier;
175typedef void (*IOMMUNotify)(struct IOMMUNotifier *notifier,
176 IOMMUTLBEntry *data);
177
Peter Xucdb30812016-09-23 13:02:26 +0800178struct IOMMUNotifier {
Peter Xu698feb52017-04-07 18:59:07 +0800179 IOMMUNotify notify;
Peter Xucdb30812016-09-23 13:02:26 +0800180 IOMMUNotifierFlag notifier_flags;
Peter Xu698feb52017-04-07 18:59:07 +0800181 /* Notify for address space range start <= addr <= end */
182 hwaddr start;
183 hwaddr end;
Peter Maydellcb1efcf2018-06-15 14:57:16 +0100184 int iommu_idx;
Peter Xucdb30812016-09-23 13:02:26 +0800185 QLIST_ENTRY(IOMMUNotifier) node;
186};
187typedef struct IOMMUNotifier IOMMUNotifier;
188
Eugenio Pérez5039caf2020-11-16 17:55:03 +0100189typedef struct IOMMUTLBEvent {
190 IOMMUNotifierFlag type;
191 IOMMUTLBEntry entry;
192} IOMMUTLBEvent;
193
Junyan Heb0e5de92018-07-18 15:47:57 +0800194/* RAM is pre-allocated and passed into qemu_ram_alloc_from_ptr */
195#define RAM_PREALLOC (1 << 0)
196
197/* RAM is mmap-ed with MAP_SHARED */
198#define RAM_SHARED (1 << 1)
199
200/* Only a portion of RAM (used_length) is actually used, and migrated.
David Hildenbrandc7c0e722021-04-29 13:27:02 +0200201 * Resizing RAM while migrating can result in the migration being canceled.
Junyan Heb0e5de92018-07-18 15:47:57 +0800202 */
203#define RAM_RESIZEABLE (1 << 2)
204
205/* UFFDIO_ZEROPAGE is available on this RAMBlock to atomically
206 * zero the page and wake waiting processes.
207 * (Set during postcopy)
208 */
209#define RAM_UF_ZEROPAGE (1 << 3)
210
211/* RAM can be migrated */
212#define RAM_MIGRATABLE (1 << 4)
213
Junyan Hea4de8552018-07-18 15:48:00 +0800214/* RAM is a persistent kind memory */
215#define RAM_PMEM (1 << 5)
216
Andrey Gruzdev0e9b5cd2021-01-29 13:14:04 +0300217
Andrey Gruzdev278e2f52021-01-29 13:14:05 +0300218/*
219 * UFFDIO_WRITEPROTECT is used on this RAMBlock to
220 * support 'write-tracking' migration type.
221 * Implies ram_state->ram_wt_enabled.
222 */
223#define RAM_UF_WRITEPROTECT (1 << 6)
224
David Hildenbrand8dbe22c2021-05-10 13:43:21 +0200225/*
226 * RAM is mmap-ed with MAP_NORESERVE. When set, reserving swap space (or huge
227 * pages if applicable) is skipped: will bail out if not supported. When not
228 * set, the OS will do the reservation, if supported for the memory type.
229 */
230#define RAM_NORESERVE (1 << 7)
231
Sean Christopherson56918a12021-07-19 19:21:04 +0800232/* RAM that isn't accessible through normal means. */
233#define RAM_PROTECTED (1 << 8)
234
Peter Xu698feb52017-04-07 18:59:07 +0800235static inline void iommu_notifier_init(IOMMUNotifier *n, IOMMUNotify fn,
236 IOMMUNotifierFlag flags,
Peter Maydellcb1efcf2018-06-15 14:57:16 +0100237 hwaddr start, hwaddr end,
238 int iommu_idx)
Peter Xu698feb52017-04-07 18:59:07 +0800239{
240 n->notify = fn;
241 n->notifier_flags = flags;
242 n->start = start;
243 n->end = end;
Peter Maydellcb1efcf2018-06-15 14:57:16 +0100244 n->iommu_idx = iommu_idx;
Peter Xu698feb52017-04-07 18:59:07 +0800245}
246
Avi Kivity093bc2c2011-07-26 14:26:01 +0300247/*
248 * Memory region callbacks
249 */
250struct MemoryRegionOps {
251 /* Read from the memory region. @addr is relative to @mr; @size is
252 * in bytes. */
253 uint64_t (*read)(void *opaque,
Avi Kivitya8170e52012-10-23 12:30:10 +0200254 hwaddr addr,
Avi Kivity093bc2c2011-07-26 14:26:01 +0300255 unsigned size);
256 /* Write to the memory region. @addr is relative to @mr; @size is
257 * in bytes. */
258 void (*write)(void *opaque,
Avi Kivitya8170e52012-10-23 12:30:10 +0200259 hwaddr addr,
Avi Kivity093bc2c2011-07-26 14:26:01 +0300260 uint64_t data,
261 unsigned size);
262
Peter Maydellcc05c432015-04-26 16:49:23 +0100263 MemTxResult (*read_with_attrs)(void *opaque,
264 hwaddr addr,
265 uint64_t *data,
266 unsigned size,
267 MemTxAttrs attrs);
268 MemTxResult (*write_with_attrs)(void *opaque,
269 hwaddr addr,
270 uint64_t data,
271 unsigned size,
272 MemTxAttrs attrs);
273
Avi Kivity093bc2c2011-07-26 14:26:01 +0300274 enum device_endian endianness;
275 /* Guest-visible constraints: */
276 struct {
277 /* If nonzero, specify bounds on access sizes beyond which a machine
278 * check is thrown.
279 */
280 unsigned min_access_size;
281 unsigned max_access_size;
282 /* If true, unaligned accesses are supported. Otherwise unaligned
283 * accesses throw machine checks.
284 */
285 bool unaligned;
Avi Kivity897fa7c2011-11-13 13:05:27 +0200286 /*
287 * If present, and returns #false, the transaction is not accepted
288 * by the device (and results in machine dependent behaviour such
289 * as a machine check exception).
290 */
Avi Kivitya8170e52012-10-23 12:30:10 +0200291 bool (*accepts)(void *opaque, hwaddr addr,
Peter Maydell8372d382018-05-31 14:50:52 +0100292 unsigned size, bool is_write,
293 MemTxAttrs attrs);
Avi Kivity093bc2c2011-07-26 14:26:01 +0300294 } valid;
295 /* Internal implementation constraints: */
296 struct {
297 /* If nonzero, specifies the minimum size implemented. Smaller sizes
298 * will be rounded upwards and a partial result will be returned.
299 */
300 unsigned min_access_size;
301 /* If nonzero, specifies the maximum size implemented. Larger sizes
302 * will be done as a series of accesses with smaller sizes.
303 */
304 unsigned max_access_size;
305 /* If true, unaligned accesses are supported. Otherwise all accesses
306 * are converted to (possibly multiple) naturally aligned accesses.
307 */
Fam Zhengedc1ba72014-05-05 15:53:41 +0800308 bool unaligned;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300309 } impl;
310};
311
Markus Armbruster1b53ecd2019-08-12 07:23:34 +0200312typedef struct MemoryRegionClass {
313 /* private */
314 ObjectClass parent_class;
315} MemoryRegionClass;
316
317
Alexey Kardashevskiyf1334de2018-02-06 11:08:24 -0700318enum IOMMUMemoryRegionAttr {
319 IOMMU_ATTR_SPAPR_TCE_FD
320};
321
Eduardo Habkostacbef3c2020-09-08 13:36:50 -0400322/*
Peter Maydell2ce931d2018-05-31 14:50:52 +0100323 * IOMMUMemoryRegionClass:
324 *
325 * All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION
326 * and provide an implementation of at least the @translate method here
327 * to handle requests to the memory region. Other methods are optional.
328 *
329 * The IOMMU implementation must use the IOMMU notifier infrastructure
330 * to report whenever mappings are changed, by calling
331 * memory_region_notify_iommu() (or, if necessary, by calling
Eugenio Pérez3b5ebf82020-11-16 17:55:02 +0100332 * memory_region_notify_iommu_one() for each registered notifier).
Peter Maydell21f40202018-06-15 14:57:15 +0100333 *
334 * Conceptually an IOMMU provides a mapping from input address
335 * to an output TLB entry. If the IOMMU is aware of memory transaction
336 * attributes and the output TLB entry depends on the transaction
337 * attributes, we represent this using IOMMU indexes. Each index
338 * selects a particular translation table that the IOMMU has:
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400339 *
Peter Maydell21f40202018-06-15 14:57:15 +0100340 * @attrs_to_index returns the IOMMU index for a set of transaction attributes
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400341 *
Peter Maydell21f40202018-06-15 14:57:15 +0100342 * @translate takes an input address and an IOMMU index
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400343 *
Peter Maydell21f40202018-06-15 14:57:15 +0100344 * and the mapping returned can only depend on the input address and the
345 * IOMMU index.
346 *
347 * Most IOMMUs don't care about the transaction attributes and support
348 * only a single IOMMU index. A more complex IOMMU might have one index
349 * for secure transactions and one for non-secure transactions.
Peter Maydell2ce931d2018-05-31 14:50:52 +0100350 */
Eduardo Habkostdb1015e2020-09-03 16:43:22 -0400351struct IOMMUMemoryRegionClass {
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400352 /* private: */
Markus Armbruster1b53ecd2019-08-12 07:23:34 +0200353 MemoryRegionClass parent_class;
Avi Kivity30951152012-10-30 13:47:46 +0200354
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400355 /* public: */
356 /**
357 * @translate:
358 *
Peter Maydell2ce931d2018-05-31 14:50:52 +0100359 * Return a TLB entry that contains a given address.
360 *
361 * The IOMMUAccessFlags indicated via @flag are optional and may
362 * be specified as IOMMU_NONE to indicate that the caller needs
363 * the full translation information for both reads and writes. If
364 * the access flags are specified then the IOMMU implementation
365 * may use this as an optimization, to stop doing a page table
366 * walk as soon as it knows that the requested permissions are not
367 * allowed. If IOMMU_NONE is passed then the IOMMU must do the
368 * full page table walk and report the permissions in the returned
369 * IOMMUTLBEntry. (Note that this implies that an IOMMU may not
370 * return different mappings for reads and writes.)
371 *
372 * The returned information remains valid while the caller is
373 * holding the big QEMU lock or is inside an RCU critical section;
374 * if the caller wishes to cache the mapping beyond that it must
375 * register an IOMMU notifier so it can invalidate its cached
376 * information when the IOMMU mapping changes.
377 *
378 * @iommu: the IOMMUMemoryRegion
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400379 *
Peter Maydell2ce931d2018-05-31 14:50:52 +0100380 * @hwaddr: address to be translated within the memory region
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400381 *
382 * @flag: requested access permission
383 *
Peter Maydell2c91bcf2018-06-15 14:57:16 +0100384 * @iommu_idx: IOMMU index for the translation
Peter Xubf55b7a2017-05-19 11:19:40 +0800385 */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +1000386 IOMMUTLBEntry (*translate)(IOMMUMemoryRegion *iommu, hwaddr addr,
Peter Maydell2c91bcf2018-06-15 14:57:16 +0100387 IOMMUAccessFlags flag, int iommu_idx);
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400388 /**
389 * @get_min_page_size:
390 *
391 * Returns minimum supported page size in bytes.
392 *
Peter Maydell2ce931d2018-05-31 14:50:52 +0100393 * If this method is not provided then the minimum is assumed to
394 * be TARGET_PAGE_SIZE.
395 *
396 * @iommu: the IOMMUMemoryRegion
397 */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +1000398 uint64_t (*get_min_page_size)(IOMMUMemoryRegion *iommu);
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400399 /**
400 * @notify_flag_changed:
401 *
402 * Called when IOMMU Notifier flag changes (ie when the set of
Peter Maydell2ce931d2018-05-31 14:50:52 +0100403 * events which IOMMU users are requesting notification for changes).
404 * Optional method -- need not be provided if the IOMMU does not
405 * need to know exactly which events must be notified.
406 *
407 * @iommu: the IOMMUMemoryRegion
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400408 *
Peter Maydell2ce931d2018-05-31 14:50:52 +0100409 * @old_flags: events which previously needed to be notified
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400410 *
Peter Maydell2ce931d2018-05-31 14:50:52 +0100411 * @new_flags: events which now need to be notified
Eric Auger549d40052019-09-24 10:25:17 +0200412 *
413 * Returns 0 on success, or a negative errno; in particular
414 * returns -EINVAL if the new flag bitmap is not supported by the
415 * IOMMU memory region. In case of failure, the error object
416 * must be created
Peter Maydell2ce931d2018-05-31 14:50:52 +0100417 */
Eric Auger549d40052019-09-24 10:25:17 +0200418 int (*notify_flag_changed)(IOMMUMemoryRegion *iommu,
419 IOMMUNotifierFlag old_flags,
420 IOMMUNotifierFlag new_flags,
421 Error **errp);
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400422 /**
423 * @replay:
424 *
425 * Called to handle memory_region_iommu_replay().
Peter Maydell2ce931d2018-05-31 14:50:52 +0100426 *
427 * The default implementation of memory_region_iommu_replay() is to
428 * call the IOMMU translate method for every page in the address space
429 * with flag == IOMMU_NONE and then call the notifier if translate
430 * returns a valid mapping. If this method is implemented then it
431 * overrides the default behaviour, and must provide the full semantics
432 * of memory_region_iommu_replay(), by calling @notifier for every
433 * translation present in the IOMMU.
434 *
435 * Optional method -- an IOMMU only needs to provide this method
436 * if the default is inefficient or produces undesirable side effects.
437 *
438 * Note: this is not related to record-and-replay functionality.
439 */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +1000440 void (*replay)(IOMMUMemoryRegion *iommu, IOMMUNotifier *notifier);
Alexey Kardashevskiyf1334de2018-02-06 11:08:24 -0700441
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400442 /**
443 * @get_attr:
444 *
445 * Get IOMMU misc attributes. This is an optional method that
Peter Maydell2ce931d2018-05-31 14:50:52 +0100446 * can be used to allow users of the IOMMU to get implementation-specific
447 * information. The IOMMU implements this method to handle calls
448 * by IOMMU users to memory_region_iommu_get_attr() by filling in
449 * the arbitrary data pointer for any IOMMUMemoryRegionAttr values that
450 * the IOMMU supports. If the method is unimplemented then
451 * memory_region_iommu_get_attr() will always return -EINVAL.
452 *
453 * @iommu: the IOMMUMemoryRegion
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400454 *
Peter Maydell2ce931d2018-05-31 14:50:52 +0100455 * @attr: attribute being queried
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400456 *
Peter Maydell2ce931d2018-05-31 14:50:52 +0100457 * @data: memory to fill in with the attribute data
458 *
459 * Returns 0 on success, or a negative errno; in particular
460 * returns -EINVAL for unrecognized or unimplemented attribute types.
461 */
462 int (*get_attr)(IOMMUMemoryRegion *iommu, enum IOMMUMemoryRegionAttr attr,
Alexey Kardashevskiyf1334de2018-02-06 11:08:24 -0700463 void *data);
Peter Maydell21f40202018-06-15 14:57:15 +0100464
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400465 /**
466 * @attrs_to_index:
467 *
468 * Return the IOMMU index to use for a given set of transaction attributes.
Peter Maydell21f40202018-06-15 14:57:15 +0100469 *
470 * Optional method: if an IOMMU only supports a single IOMMU index then
471 * the default implementation of memory_region_iommu_attrs_to_index()
472 * will return 0.
473 *
474 * The indexes supported by an IOMMU must be contiguous, starting at 0.
475 *
476 * @iommu: the IOMMUMemoryRegion
477 * @attrs: memory transaction attributes
478 */
479 int (*attrs_to_index)(IOMMUMemoryRegion *iommu, MemTxAttrs attrs);
480
Eduardo Habkostffb716f2020-09-08 16:11:29 -0400481 /**
482 * @num_indexes:
483 *
484 * Return the number of IOMMU indexes this IOMMU supports.
Peter Maydell21f40202018-06-15 14:57:15 +0100485 *
486 * Optional method: if this method is not provided, then
487 * memory_region_iommu_num_indexes() will return 1, indicating that
488 * only a single IOMMU index is supported.
489 *
490 * @iommu: the IOMMUMemoryRegion
491 */
492 int (*num_indexes)(IOMMUMemoryRegion *iommu);
Bharat Bhushan457f8cb2020-10-30 19:05:07 +0100493
494 /**
495 * @iommu_set_page_size_mask:
496 *
497 * Restrict the page size mask that can be supported with a given IOMMU
498 * memory region. Used for example to propagate host physical IOMMU page
499 * size mask limitations to the virtual IOMMU.
500 *
501 * Optional method: if this method is not provided, then the default global
502 * page mask is used.
503 *
504 * @iommu: the IOMMUMemoryRegion
505 *
506 * @page_size_mask: a bitmask of supported page sizes. At least one bit,
507 * representing the smallest page size, must be set. Additional set bits
508 * represent supported block sizes. For example a host physical IOMMU that
509 * uses page tables with a page size of 4kB, and supports 2MB and 4GB
510 * blocks, will set mask 0x40201000. A granule of 4kB with indiscriminate
511 * block sizes is specified with mask 0xfffffffffffff000.
512 *
513 * Returns 0 on success, or a negative error. In case of failure, the error
514 * object must be created.
515 */
516 int (*iommu_set_page_size_mask)(IOMMUMemoryRegion *iommu,
517 uint64_t page_size_mask,
518 Error **errp);
Eduardo Habkostdb1015e2020-09-03 16:43:22 -0400519};
Avi Kivity30951152012-10-30 13:47:46 +0200520
David Hildenbrand8947d7f2021-04-13 11:55:19 +0200521typedef struct RamDiscardListener RamDiscardListener;
522typedef int (*NotifyRamPopulate)(RamDiscardListener *rdl,
523 MemoryRegionSection *section);
524typedef void (*NotifyRamDiscard)(RamDiscardListener *rdl,
525 MemoryRegionSection *section);
526
527struct RamDiscardListener {
528 /*
529 * @notify_populate:
530 *
531 * Notification that previously discarded memory is about to get populated.
532 * Listeners are able to object. If any listener objects, already
533 * successfully notified listeners are notified about a discard again.
534 *
535 * @rdl: the #RamDiscardListener getting notified
536 * @section: the #MemoryRegionSection to get populated. The section
537 * is aligned within the memory region to the minimum granularity
538 * unless it would exceed the registered section.
539 *
540 * Returns 0 on success. If the notification is rejected by the listener,
541 * an error is returned.
542 */
543 NotifyRamPopulate notify_populate;
544
545 /*
546 * @notify_discard:
547 *
548 * Notification that previously populated memory was discarded successfully
549 * and listeners should drop all references to such memory and prevent
550 * new population (e.g., unmap).
551 *
552 * @rdl: the #RamDiscardListener getting notified
553 * @section: the #MemoryRegionSection to get populated. The section
554 * is aligned within the memory region to the minimum granularity
555 * unless it would exceed the registered section.
556 */
557 NotifyRamDiscard notify_discard;
558
559 /*
560 * @double_discard_supported:
561 *
562 * The listener suppors getting @notify_discard notifications that span
563 * already discarded parts.
564 */
565 bool double_discard_supported;
566
567 MemoryRegionSection *section;
568 QLIST_ENTRY(RamDiscardListener) next;
569};
570
571static inline void ram_discard_listener_init(RamDiscardListener *rdl,
572 NotifyRamPopulate populate_fn,
573 NotifyRamDiscard discard_fn,
574 bool double_discard_supported)
575{
576 rdl->notify_populate = populate_fn;
577 rdl->notify_discard = discard_fn;
578 rdl->double_discard_supported = double_discard_supported;
579}
580
581typedef int (*ReplayRamPopulate)(MemoryRegionSection *section, void *opaque);
David Hildenbrandadaf9d92021-10-11 19:53:38 +0200582typedef void (*ReplayRamDiscard)(MemoryRegionSection *section, void *opaque);
David Hildenbrand8947d7f2021-04-13 11:55:19 +0200583
584/*
585 * RamDiscardManagerClass:
586 *
587 * A #RamDiscardManager coordinates which parts of specific RAM #MemoryRegion
588 * regions are currently populated to be used/accessed by the VM, notifying
589 * after parts were discarded (freeing up memory) and before parts will be
Stefan Weil2cb40d42022-11-10 20:08:25 +0100590 * populated (consuming memory), to be used/accessed by the VM.
David Hildenbrand8947d7f2021-04-13 11:55:19 +0200591 *
592 * A #RamDiscardManager can only be set for a RAM #MemoryRegion while the
593 * #MemoryRegion isn't mapped yet; it cannot change while the #MemoryRegion is
594 * mapped.
595 *
596 * The #RamDiscardManager is intended to be used by technologies that are
597 * incompatible with discarding of RAM (e.g., VFIO, which may pin all
598 * memory inside a #MemoryRegion), and require proper coordination to only
599 * map the currently populated parts, to hinder parts that are expected to
600 * remain discarded from silently getting populated and consuming memory.
601 * Technologies that support discarding of RAM don't have to bother and can
602 * simply map the whole #MemoryRegion.
603 *
604 * An example #RamDiscardManager is virtio-mem, which logically (un)plugs
605 * memory within an assigned RAM #MemoryRegion, coordinated with the VM.
606 * Logically unplugging memory consists of discarding RAM. The VM agreed to not
607 * access unplugged (discarded) memory - especially via DMA. virtio-mem will
608 * properly coordinate with listeners before memory is plugged (populated),
609 * and after memory is unplugged (discarded).
610 *
611 * Listeners are called in multiples of the minimum granularity (unless it
612 * would exceed the registered range) and changes are aligned to the minimum
613 * granularity within the #MemoryRegion. Listeners have to prepare for memory
Stefan Weil2cb40d42022-11-10 20:08:25 +0100614 * becoming discarded in a different granularity than it was populated and the
David Hildenbrand8947d7f2021-04-13 11:55:19 +0200615 * other way around.
616 */
617struct RamDiscardManagerClass {
618 /* private */
619 InterfaceClass parent_class;
620
621 /* public */
622
623 /**
624 * @get_min_granularity:
625 *
626 * Get the minimum granularity in which listeners will get notified
627 * about changes within the #MemoryRegion via the #RamDiscardManager.
628 *
629 * @rdm: the #RamDiscardManager
630 * @mr: the #MemoryRegion
631 *
632 * Returns the minimum granularity.
633 */
634 uint64_t (*get_min_granularity)(const RamDiscardManager *rdm,
635 const MemoryRegion *mr);
636
637 /**
638 * @is_populated:
639 *
640 * Check whether the given #MemoryRegionSection is completely populated
641 * (i.e., no parts are currently discarded) via the #RamDiscardManager.
642 * There are no alignment requirements.
643 *
644 * @rdm: the #RamDiscardManager
645 * @section: the #MemoryRegionSection
646 *
647 * Returns whether the given range is completely populated.
648 */
649 bool (*is_populated)(const RamDiscardManager *rdm,
650 const MemoryRegionSection *section);
651
652 /**
653 * @replay_populated:
654 *
655 * Call the #ReplayRamPopulate callback for all populated parts within the
656 * #MemoryRegionSection via the #RamDiscardManager.
657 *
658 * In case any call fails, no further calls are made.
659 *
660 * @rdm: the #RamDiscardManager
661 * @section: the #MemoryRegionSection
662 * @replay_fn: the #ReplayRamPopulate callback
663 * @opaque: pointer to forward to the callback
664 *
665 * Returns 0 on success, or a negative error if any notification failed.
666 */
667 int (*replay_populated)(const RamDiscardManager *rdm,
668 MemoryRegionSection *section,
669 ReplayRamPopulate replay_fn, void *opaque);
670
671 /**
David Hildenbrandadaf9d92021-10-11 19:53:38 +0200672 * @replay_discarded:
673 *
674 * Call the #ReplayRamDiscard callback for all discarded parts within the
675 * #MemoryRegionSection via the #RamDiscardManager.
676 *
677 * @rdm: the #RamDiscardManager
678 * @section: the #MemoryRegionSection
679 * @replay_fn: the #ReplayRamDiscard callback
680 * @opaque: pointer to forward to the callback
681 */
682 void (*replay_discarded)(const RamDiscardManager *rdm,
683 MemoryRegionSection *section,
684 ReplayRamDiscard replay_fn, void *opaque);
685
686 /**
David Hildenbrand8947d7f2021-04-13 11:55:19 +0200687 * @register_listener:
688 *
689 * Register a #RamDiscardListener for the given #MemoryRegionSection and
690 * immediately notify the #RamDiscardListener about all populated parts
691 * within the #MemoryRegionSection via the #RamDiscardManager.
692 *
693 * In case any notification fails, no further notifications are triggered
694 * and an error is logged.
695 *
696 * @rdm: the #RamDiscardManager
697 * @rdl: the #RamDiscardListener
698 * @section: the #MemoryRegionSection
699 */
700 void (*register_listener)(RamDiscardManager *rdm,
701 RamDiscardListener *rdl,
702 MemoryRegionSection *section);
703
704 /**
705 * @unregister_listener:
706 *
707 * Unregister a previously registered #RamDiscardListener via the
708 * #RamDiscardManager after notifying the #RamDiscardListener about all
709 * populated parts becoming unpopulated within the registered
710 * #MemoryRegionSection.
711 *
712 * @rdm: the #RamDiscardManager
713 * @rdl: the #RamDiscardListener
714 */
715 void (*unregister_listener)(RamDiscardManager *rdm,
716 RamDiscardListener *rdl);
717};
718
719uint64_t ram_discard_manager_get_min_granularity(const RamDiscardManager *rdm,
720 const MemoryRegion *mr);
721
722bool ram_discard_manager_is_populated(const RamDiscardManager *rdm,
723 const MemoryRegionSection *section);
724
725int ram_discard_manager_replay_populated(const RamDiscardManager *rdm,
726 MemoryRegionSection *section,
727 ReplayRamPopulate replay_fn,
728 void *opaque);
729
David Hildenbrandadaf9d92021-10-11 19:53:38 +0200730void ram_discard_manager_replay_discarded(const RamDiscardManager *rdm,
731 MemoryRegionSection *section,
732 ReplayRamDiscard replay_fn,
733 void *opaque);
734
David Hildenbrand8947d7f2021-04-13 11:55:19 +0200735void ram_discard_manager_register_listener(RamDiscardManager *rdm,
736 RamDiscardListener *rdl,
737 MemoryRegionSection *section);
738
739void ram_discard_manager_unregister_listener(RamDiscardManager *rdm,
740 RamDiscardListener *rdl);
741
Cindy Lubaa44bc2022-10-31 11:10:19 +0800742bool memory_get_xlat_addr(IOMMUTLBEntry *iotlb, void **vaddr,
743 ram_addr_t *ram_addr, bool *read_only,
744 bool *mr_has_discard_manager);
745
Avi Kivity093bc2c2011-07-26 14:26:01 +0300746typedef struct CoalescedMemoryRange CoalescedMemoryRange;
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300747typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300748
Paolo Bonzini08226b42019-10-29 17:22:46 +0100749/** MemoryRegion:
750 *
751 * A struct representing a memory region.
752 */
Avi Kivity093bc2c2011-07-26 14:26:01 +0300753struct MemoryRegion {
Peter Crosthwaiteb4fefef2014-06-05 23:15:52 -0700754 Object parent_obj;
Paolo Bonzinia6768542015-12-09 11:40:14 +0100755
Paolo Bonzini08226b42019-10-29 17:22:46 +0100756 /* private: */
Paolo Bonzinia6768542015-12-09 11:40:14 +0100757
758 /* The following fields should fit in a cache line */
759 bool romd_mode;
760 bool ram;
761 bool subpage;
762 bool readonly; /* For RAM regions */
Marc-André Lureauc26763f2018-10-03 15:44:52 +0400763 bool nonvolatile;
Paolo Bonzinia6768542015-12-09 11:40:14 +0100764 bool rom_device;
765 bool flush_coalesced_mmio;
Paolo Bonzinia6768542015-12-09 11:40:14 +0100766 uint8_t dirty_log_mask;
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +1000767 bool is_iommu;
Gonglei58eaa212016-02-22 16:34:55 +0800768 RAMBlock *ram_block;
Paolo Bonzini612263c2015-12-09 11:44:25 +0100769 Object *owner;
Paolo Bonzinia6768542015-12-09 11:40:14 +0100770
771 const MemoryRegionOps *ops;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300772 void *opaque;
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +0200773 MemoryRegion *container;
David Hildenbrand5ead6212021-11-02 17:43:16 +0100774 int mapped_via_alias; /* Mapped via an alias, container might be NULL */
Avi Kivity08dafab2011-10-16 13:19:17 +0200775 Int128 size;
Avi Kivitya8170e52012-10-23 12:30:10 +0200776 hwaddr addr;
Avi Kivity545e92e2011-08-08 19:58:48 +0300777 void (*destructor)(MemoryRegion *mr);
Igor Mammedova2b257d2014-10-31 16:38:37 +0000778 uint64_t align;
Avi Kivity14a3c102011-07-26 14:26:06 +0300779 bool terminates;
Alex Williamson21e00fa2016-10-31 09:53:03 -0600780 bool ram_device;
Avi Kivity6bba19b2011-09-14 11:54:58 +0300781 bool enabled;
Jan Kiszka1660e722011-10-23 16:01:19 +0200782 bool warning_printed; /* For reservations */
Paolo Bonzinideb809e2015-07-14 13:56:53 +0200783 uint8_t vga_logging_count;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300784 MemoryRegion *alias;
Avi Kivitya8170e52012-10-23 12:30:10 +0200785 hwaddr alias_offset;
Peter Crosthwaited33382d2014-06-05 23:17:01 -0700786 int32_t priority;
Paolo Bonzinib58deb32018-12-06 11:58:10 +0100787 QTAILQ_HEAD(, MemoryRegion) subregions;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300788 QTAILQ_ENTRY(MemoryRegion) subregions_link;
Paolo Bonzinib58deb32018-12-06 11:58:10 +0100789 QTAILQ_HEAD(, CoalescedMemoryRange) coalesced;
Peter Maydell302fa282014-08-19 20:05:46 +0100790 const char *name;
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300791 unsigned ioeventfd_nb;
792 MemoryRegionIoeventfd *ioeventfds;
David Hildenbrand8947d7f2021-04-13 11:55:19 +0200793 RamDiscardManager *rdm; /* Only for RAM */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +1000794};
795
796struct IOMMUMemoryRegion {
797 MemoryRegion parent_obj;
798
Peter Xucdb30812016-09-23 13:02:26 +0800799 QLIST_HEAD(, IOMMUNotifier) iommu_notify;
Peter Xu5bf3d312016-09-23 13:02:27 +0800800 IOMMUNotifierFlag iommu_notify_flags;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300801};
802
Peter Xu512fa402017-04-07 18:59:08 +0800803#define IOMMU_NOTIFIER_FOREACH(n, mr) \
804 QLIST_FOREACH((n), &(mr)->iommu_notify, node)
805
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200806/**
Eduardo Habkost301302f2020-10-02 22:41:22 -0400807 * struct MemoryListener: callbacks structure for updates to the physical memory map
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200808 *
809 * Allows a component to adjust to changes in the guest-visible memory map.
810 * Use with memory_listener_register() and memory_listener_unregister().
811 */
812struct MemoryListener {
Paolo Bonzini5d248212019-10-29 17:22:48 +0100813 /**
814 * @begin:
815 *
816 * Called at the beginning of an address space update transaction.
817 * Followed by calls to #MemoryListener.region_add(),
818 * #MemoryListener.region_del(), #MemoryListener.region_nop(),
819 * #MemoryListener.log_start() and #MemoryListener.log_stop() in
820 * increasing address order.
821 *
822 * @listener: The #MemoryListener.
823 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200824 void (*begin)(MemoryListener *listener);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100825
826 /**
827 * @commit:
828 *
829 * Called at the end of an address space update transaction,
830 * after the last call to #MemoryListener.region_add(),
831 * #MemoryListener.region_del() or #MemoryListener.region_nop(),
832 * #MemoryListener.log_start() and #MemoryListener.log_stop().
833 *
834 * @listener: The #MemoryListener.
835 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200836 void (*commit)(MemoryListener *listener);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100837
838 /**
839 * @region_add:
840 *
841 * Called during an address space update transaction,
842 * for a section of the address space that is new in this address space
843 * space since the last transaction.
844 *
845 * @listener: The #MemoryListener.
846 * @section: The new #MemoryRegionSection.
847 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200848 void (*region_add)(MemoryListener *listener, MemoryRegionSection *section);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100849
850 /**
851 * @region_del:
852 *
853 * Called during an address space update transaction,
854 * for a section of the address space that has disappeared in the address
855 * space since the last transaction.
856 *
857 * @listener: The #MemoryListener.
858 * @section: The old #MemoryRegionSection.
859 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200860 void (*region_del)(MemoryListener *listener, MemoryRegionSection *section);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100861
862 /**
863 * @region_nop:
864 *
865 * Called during an address space update transaction,
866 * for a section of the address space that is in the same place in the address
867 * space as in the last transaction.
868 *
869 * @listener: The #MemoryListener.
870 * @section: The #MemoryRegionSection.
871 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200872 void (*region_nop)(MemoryListener *listener, MemoryRegionSection *section);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100873
874 /**
875 * @log_start:
876 *
877 * Called during an address space update transaction, after
John Snowd7878872021-05-11 15:29:50 -0400878 * one of #MemoryListener.region_add(), #MemoryListener.region_del() or
Paolo Bonzini5d248212019-10-29 17:22:48 +0100879 * #MemoryListener.region_nop(), if dirty memory logging clients have
880 * become active since the last transaction.
881 *
882 * @listener: The #MemoryListener.
883 * @section: The #MemoryRegionSection.
884 * @old: A bitmap of dirty memory logging clients that were active in
885 * the previous transaction.
886 * @new: A bitmap of dirty memory logging clients that are active in
887 * the current transaction.
888 */
Paolo Bonzinib2dfd712015-04-25 14:38:30 +0200889 void (*log_start)(MemoryListener *listener, MemoryRegionSection *section,
890 int old, int new);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100891
892 /**
893 * @log_stop:
894 *
895 * Called during an address space update transaction, after
896 * one of #MemoryListener.region_add(), #MemoryListener.region_del() or
897 * #MemoryListener.region_nop() and possibly after
898 * #MemoryListener.log_start(), if dirty memory logging clients have
899 * become inactive since the last transaction.
900 *
901 * @listener: The #MemoryListener.
902 * @section: The #MemoryRegionSection.
903 * @old: A bitmap of dirty memory logging clients that were active in
904 * the previous transaction.
905 * @new: A bitmap of dirty memory logging clients that are active in
906 * the current transaction.
907 */
Paolo Bonzinib2dfd712015-04-25 14:38:30 +0200908 void (*log_stop)(MemoryListener *listener, MemoryRegionSection *section,
909 int old, int new);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100910
911 /**
912 * @log_sync:
913 *
914 * Called by memory_region_snapshot_and_clear_dirty() and
915 * memory_global_dirty_log_sync(), before accessing QEMU's "official"
916 * copy of the dirty memory bitmap for a #MemoryRegionSection.
917 *
918 * @listener: The #MemoryListener.
919 * @section: The #MemoryRegionSection.
920 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200921 void (*log_sync)(MemoryListener *listener, MemoryRegionSection *section);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100922
923 /**
Peter Xub87eaa92021-05-06 12:05:40 -0400924 * @log_sync_global:
925 *
926 * This is the global version of @log_sync when the listener does
927 * not have a way to synchronize the log with finer granularity.
928 * When the listener registers with @log_sync_global defined, then
929 * its @log_sync must be NULL. Vice versa.
930 *
931 * @listener: The #MemoryListener.
932 */
933 void (*log_sync_global)(MemoryListener *listener);
934
935 /**
Paolo Bonzini5d248212019-10-29 17:22:48 +0100936 * @log_clear:
937 *
938 * Called before reading the dirty memory bitmap for a
939 * #MemoryRegionSection.
940 *
941 * @listener: The #MemoryListener.
942 * @section: The #MemoryRegionSection.
943 */
Peter Xu077874e2019-06-03 14:50:51 +0800944 void (*log_clear)(MemoryListener *listener, MemoryRegionSection *section);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100945
946 /**
947 * @log_global_start:
948 *
949 * Called by memory_global_dirty_log_start(), which
950 * enables the %DIRTY_LOG_MIGRATION client on all memory regions in
951 * the address space. #MemoryListener.log_global_start() is also
952 * called when a #MemoryListener is added, if global dirty logging is
953 * active at that time.
954 *
955 * @listener: The #MemoryListener.
956 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200957 void (*log_global_start)(MemoryListener *listener);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100958
959 /**
960 * @log_global_stop:
961 *
962 * Called by memory_global_dirty_log_stop(), which
963 * disables the %DIRTY_LOG_MIGRATION client on all memory regions in
964 * the address space.
965 *
966 * @listener: The #MemoryListener.
967 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200968 void (*log_global_stop)(MemoryListener *listener);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100969
970 /**
971 * @log_global_after_sync:
972 *
973 * Called after reading the dirty memory bitmap
974 * for any #MemoryRegionSection.
975 *
976 * @listener: The #MemoryListener.
977 */
Paolo Bonzini9458a9a2018-02-06 18:37:39 +0100978 void (*log_global_after_sync)(MemoryListener *listener);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100979
980 /**
981 * @eventfd_add:
982 *
983 * Called during an address space update transaction,
984 * for a section of the address space that has had a new ioeventfd
985 * registration since the last transaction.
986 *
987 * @listener: The #MemoryListener.
988 * @section: The new #MemoryRegionSection.
989 * @match_data: The @match_data parameter for the new ioeventfd.
990 * @data: The @data parameter for the new ioeventfd.
991 * @e: The #EventNotifier parameter for the new ioeventfd.
992 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +0200993 void (*eventfd_add)(MemoryListener *listener, MemoryRegionSection *section,
994 bool match_data, uint64_t data, EventNotifier *e);
Paolo Bonzini5d248212019-10-29 17:22:48 +0100995
996 /**
997 * @eventfd_del:
998 *
999 * Called during an address space update transaction,
1000 * for a section of the address space that has dropped an ioeventfd
1001 * registration since the last transaction.
1002 *
1003 * @listener: The #MemoryListener.
1004 * @section: The new #MemoryRegionSection.
1005 * @match_data: The @match_data parameter for the dropped ioeventfd.
1006 * @data: The @data parameter for the dropped ioeventfd.
1007 * @e: The #EventNotifier parameter for the dropped ioeventfd.
1008 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +02001009 void (*eventfd_del)(MemoryListener *listener, MemoryRegionSection *section,
1010 bool match_data, uint64_t data, EventNotifier *e);
Paolo Bonzini5d248212019-10-29 17:22:48 +01001011
1012 /**
1013 * @coalesced_io_add:
1014 *
1015 * Called during an address space update transaction,
1016 * for a section of the address space that has had a new coalesced
1017 * MMIO range registration since the last transaction.
1018 *
1019 * @listener: The #MemoryListener.
1020 * @section: The new #MemoryRegionSection.
1021 * @addr: The starting address for the coalesced MMIO range.
1022 * @len: The length of the coalesced MMIO range.
1023 */
Peng Haoe6d34ae2018-10-18 00:52:54 +08001024 void (*coalesced_io_add)(MemoryListener *listener, MemoryRegionSection *section,
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +02001025 hwaddr addr, hwaddr len);
Paolo Bonzini5d248212019-10-29 17:22:48 +01001026
1027 /**
1028 * @coalesced_io_del:
1029 *
1030 * Called during an address space update transaction,
1031 * for a section of the address space that has dropped a coalesced
1032 * MMIO range since the last transaction.
1033 *
1034 * @listener: The #MemoryListener.
1035 * @section: The new #MemoryRegionSection.
1036 * @addr: The starting address for the coalesced MMIO range.
1037 * @len: The length of the coalesced MMIO range.
1038 */
Peng Haoe6d34ae2018-10-18 00:52:54 +08001039 void (*coalesced_io_del)(MemoryListener *listener, MemoryRegionSection *section,
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +02001040 hwaddr addr, hwaddr len);
Paolo Bonzini5d248212019-10-29 17:22:48 +01001041 /**
1042 * @priority:
1043 *
1044 * Govern the order in which memory listeners are invoked. Lower priorities
1045 * are invoked earlier for "add" or "start" callbacks, and later for "delete"
1046 * or "stop" callbacks.
1047 */
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +02001048 unsigned priority;
Paolo Bonzini5d248212019-10-29 17:22:48 +01001049
Peter Xu142518b2021-08-16 21:35:52 -04001050 /**
1051 * @name:
1052 *
1053 * Name of the listener. It can be used in contexts where we'd like to
1054 * identify one memory listener with the rest.
1055 */
1056 const char *name;
1057
Paolo Bonzini5d248212019-10-29 17:22:48 +01001058 /* private: */
Paolo Bonzinid45fa782016-09-22 16:11:54 +02001059 AddressSpace *address_space;
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +02001060 QTAILQ_ENTRY(MemoryListener) link;
Paolo Bonzini9a546352016-09-22 16:23:06 +02001061 QTAILQ_ENTRY(MemoryListener) link_as;
Paolo Bonzinic2fc83e2013-06-02 15:20:47 +02001062};
1063
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02001064/**
Eduardo Habkost301302f2020-10-02 22:41:22 -04001065 * struct AddressSpace: describes a mapping of addresses to #MemoryRegion objects
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02001066 */
1067struct AddressSpace {
Paolo Bonzini08226b42019-10-29 17:22:46 +01001068 /* private: */
Paolo Bonzini374f2982013-05-17 12:37:03 +02001069 struct rcu_head rcu;
Alexey Kardashevskiy7dca8042013-04-29 16:25:51 +00001070 char *name;
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02001071 MemoryRegion *root;
Paolo Bonzini374f2982013-05-17 12:37:03 +02001072
1073 /* Accessed via RCU. */
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02001074 struct FlatView *current_map;
Paolo Bonzini374f2982013-05-17 12:37:03 +02001075
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02001076 int ioeventfd_nb;
1077 struct MemoryRegionIoeventfd *ioeventfds;
Paolo Bonzinieae3eb32018-12-06 13:10:34 +01001078 QTAILQ_HEAD(, MemoryListener) listeners;
Avi Kivity0d673e32012-10-02 15:28:50 +02001079 QTAILQ_ENTRY(AddressSpace) address_spaces_link;
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02001080};
1081
Paolo Bonzini785a5072018-03-05 00:31:20 +01001082typedef struct AddressSpaceDispatch AddressSpaceDispatch;
1083typedef struct FlatRange FlatRange;
1084
1085/* Flattened global view of current active memory hierarchy. Kept in sorted
1086 * order.
1087 */
1088struct FlatView {
1089 struct rcu_head rcu;
1090 unsigned ref;
1091 FlatRange *ranges;
1092 unsigned nr;
1093 unsigned nr_allocated;
1094 struct AddressSpaceDispatch *dispatch;
1095 MemoryRegion *root;
1096};
1097
1098static inline FlatView *address_space_to_flatview(AddressSpace *as)
1099{
Stefan Hajnoczid73415a2020-09-23 11:56:46 +01001100 return qatomic_rcu_read(&as->current_map);
Paolo Bonzini785a5072018-03-05 00:31:20 +01001101}
1102
Peter Maydella5e32ec2021-03-18 17:48:20 +00001103/**
1104 * typedef flatview_cb: callback for flatview_for_each_range()
1105 *
1106 * @start: start address of the range within the FlatView
1107 * @len: length of the range in bytes
1108 * @mr: MemoryRegion covering this range
Peter Maydellb3566002021-03-18 17:48:21 +00001109 * @offset_in_region: offset of the first byte of the range within @mr
Peter Maydella5e32ec2021-03-18 17:48:20 +00001110 * @opaque: data pointer passed to flatview_for_each_range()
1111 *
1112 * Returns: true to stop the iteration, false to keep going.
1113 */
Peter Maydelld1e8cf72021-03-18 17:48:19 +00001114typedef bool (*flatview_cb)(Int128 start,
1115 Int128 len,
Peter Maydella5e32ec2021-03-18 17:48:20 +00001116 const MemoryRegion *mr,
Peter Maydellb3566002021-03-18 17:48:21 +00001117 hwaddr offset_in_region,
Peter Maydella5e32ec2021-03-18 17:48:20 +00001118 void *opaque);
Alexander Bulekovfb5ef4e2020-10-23 11:07:30 -04001119
Peter Maydella5e32ec2021-03-18 17:48:20 +00001120/**
1121 * flatview_for_each_range: Iterate through a FlatView
1122 * @fv: the FlatView to iterate through
1123 * @cb: function to call for each range
1124 * @opaque: opaque data pointer to pass to @cb
1125 *
1126 * A FlatView is made up of a list of non-overlapping ranges, each of
1127 * which is a slice of a MemoryRegion. This function iterates through
1128 * each range in @fv, calling @cb. The callback function can terminate
1129 * iteration early by returning 'true'.
1130 */
1131void flatview_for_each_range(FlatView *fv, flatview_cb cb, void *opaque);
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10001132
Dr. David Alan Gilbert9366cf02019-08-14 18:55:34 +01001133static inline bool MemoryRegionSection_eq(MemoryRegionSection *a,
1134 MemoryRegionSection *b)
1135{
1136 return a->mr == b->mr &&
1137 a->fv == b->fv &&
1138 a->offset_within_region == b->offset_within_region &&
1139 a->offset_within_address_space == b->offset_within_address_space &&
1140 int128_eq(a->size, b->size) &&
1141 a->readonly == b->readonly &&
1142 a->nonvolatile == b->nonvolatile;
1143}
1144
Avi Kivity093bc2c2011-07-26 14:26:01 +03001145/**
David Hildenbrand22843832021-04-13 11:55:20 +02001146 * memory_region_section_new_copy: Copy a memory region section
1147 *
1148 * Allocate memory for a new copy, copy the memory region section, and
1149 * properly take a reference on all relevant members.
1150 *
1151 * @s: the #MemoryRegionSection to copy
1152 */
1153MemoryRegionSection *memory_region_section_new_copy(MemoryRegionSection *s);
1154
1155/**
1156 * memory_region_section_new_copy: Free a copied memory region section
1157 *
1158 * Free a copy of a memory section created via memory_region_section_new_copy().
1159 * properly dropping references on all relevant members.
1160 *
1161 * @s: the #MemoryRegionSection to copy
1162 */
1163void memory_region_section_free_copy(MemoryRegionSection *s);
1164
1165/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03001166 * memory_region_init: Initialize a memory region
1167 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03001168 * The region typically acts as a container for other memory regions. Use
Avi Kivity093bc2c2011-07-26 14:26:01 +03001169 * memory_region_add_subregion() to add subregions.
1170 *
1171 * @mr: the #MemoryRegion to be initialized
Paolo Bonzini2c9b15c2013-06-06 05:41:28 -04001172 * @owner: the object that tracks the region's reference count
Avi Kivity093bc2c2011-07-26 14:26:01 +03001173 * @name: used for debugging; not visible to the user or ABI
1174 * @size: size of the region; any subregions beyond this size will be clipped
1175 */
1176void memory_region_init(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001177 Object *owner,
Avi Kivity093bc2c2011-07-26 14:26:01 +03001178 const char *name,
1179 uint64_t size);
Paolo Bonzini46637be2013-05-07 09:06:00 +02001180
1181/**
1182 * memory_region_ref: Add 1 to a memory region's reference count
1183 *
1184 * Whenever memory regions are accessed outside the BQL, they need to be
1185 * preserved against hot-unplug. MemoryRegions actually do not have their
1186 * own reference count; they piggyback on a QOM object, their "owner".
1187 * This function adds a reference to the owner.
1188 *
1189 * All MemoryRegions must have an owner if they can disappear, even if the
1190 * device they belong to operates exclusively under the BQL. This is because
1191 * the region could be returned at any time by memory_region_find, and this
1192 * is usually under guest control.
1193 *
1194 * @mr: the #MemoryRegion
1195 */
1196void memory_region_ref(MemoryRegion *mr);
1197
1198/**
1199 * memory_region_unref: Remove 1 to a memory region's reference count
1200 *
1201 * Whenever memory regions are accessed outside the BQL, they need to be
1202 * preserved against hot-unplug. MemoryRegions actually do not have their
1203 * own reference count; they piggyback on a QOM object, their "owner".
1204 * This function removes a reference to the owner and possibly destroys it.
1205 *
1206 * @mr: the #MemoryRegion
1207 */
1208void memory_region_unref(MemoryRegion *mr);
1209
Avi Kivity093bc2c2011-07-26 14:26:01 +03001210/**
1211 * memory_region_init_io: Initialize an I/O memory region.
1212 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03001213 * Accesses into the region will cause the callbacks in @ops to be called.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001214 * if @size is nonzero, subregions will be clipped to @size.
1215 *
1216 * @mr: the #MemoryRegion to be initialized.
Paolo Bonzini2c9b15c2013-06-06 05:41:28 -04001217 * @owner: the object that tracks the region's reference count
Avi Kivity093bc2c2011-07-26 14:26:01 +03001218 * @ops: a structure containing read and write callbacks to be used when
1219 * I/O is performed on the region.
Daniel P. Berrangeb6af0972015-08-26 12:17:13 +01001220 * @opaque: passed to the read and write callbacks of the @ops structure.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001221 * @name: used for debugging; not visible to the user or ABI
1222 * @size: size of the region.
1223 */
1224void memory_region_init_io(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001225 Object *owner,
Avi Kivity093bc2c2011-07-26 14:26:01 +03001226 const MemoryRegionOps *ops,
1227 void *opaque,
1228 const char *name,
1229 uint64_t size);
1230
1231/**
Peter Maydell1cfe48c2017-07-07 15:42:49 +01001232 * memory_region_init_ram_nomigrate: Initialize RAM memory region. Accesses
1233 * into the region will modify memory
1234 * directly.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001235 *
1236 * @mr: the #MemoryRegion to be initialized.
Paolo Bonzini2c9b15c2013-06-06 05:41:28 -04001237 * @owner: the object that tracks the region's reference count
Dr. David Alan Gilberte8f5fe22017-03-09 15:27:08 +00001238 * @name: Region name, becomes part of RAMBlock name used in migration stream
1239 * must be unique within any device
Avi Kivity093bc2c2011-07-26 14:26:01 +03001240 * @size: size of the region.
Hu Tao49946532014-09-09 13:27:55 +08001241 * @errp: pointer to Error*, to store an error if it happens.
Peter Maydella5c02342017-07-07 15:42:48 +01001242 *
1243 * Note that this function does not do anything to cause the data in the
1244 * RAM memory region to be migrated; that is the responsibility of the caller.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001245 */
Peter Maydell1cfe48c2017-07-07 15:42:49 +01001246void memory_region_init_ram_nomigrate(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001247 Object *owner,
Peter Maydell1cfe48c2017-07-07 15:42:49 +01001248 const char *name,
1249 uint64_t size,
1250 Error **errp);
Avi Kivity093bc2c2011-07-26 14:26:01 +03001251
Michael S. Tsirkin60786ef2014-11-17 00:24:36 +02001252/**
David Hildenbrand7f863cb2021-05-10 13:43:18 +02001253 * memory_region_init_ram_flags_nomigrate: Initialize RAM memory region.
1254 * Accesses into the region will
1255 * modify memory directly.
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02001256 *
1257 * @mr: the #MemoryRegion to be initialized.
1258 * @owner: the object that tracks the region's reference count
1259 * @name: Region name, becomes part of RAMBlock name used in migration stream
1260 * must be unique within any device
1261 * @size: size of the region.
David Hildenbrand8dbe22c2021-05-10 13:43:21 +02001262 * @ram_flags: RamBlock flags. Supported flags: RAM_SHARED, RAM_NORESERVE.
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02001263 * @errp: pointer to Error*, to store an error if it happens.
1264 *
David Hildenbrand7f863cb2021-05-10 13:43:18 +02001265 * Note that this function does not do anything to cause the data in the
1266 * RAM memory region to be migrated; that is the responsibility of the caller.
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02001267 */
David Hildenbrand7f863cb2021-05-10 13:43:18 +02001268void memory_region_init_ram_flags_nomigrate(MemoryRegion *mr,
1269 Object *owner,
1270 const char *name,
1271 uint64_t size,
1272 uint32_t ram_flags,
1273 Error **errp);
Marcel Apfelbaum06329cc2017-12-13 16:37:37 +02001274
1275/**
Stefan Weil2cb40d42022-11-10 20:08:25 +01001276 * memory_region_init_resizeable_ram: Initialize memory region with resizable
Michael S. Tsirkin60786ef2014-11-17 00:24:36 +02001277 * RAM. Accesses into the region will
1278 * modify memory directly. Only an initial
1279 * portion of this RAM is actually used.
David Hildenbrandc7c0e722021-04-29 13:27:02 +02001280 * Changing the size while migrating
1281 * can result in the migration being
1282 * canceled.
Michael S. Tsirkin60786ef2014-11-17 00:24:36 +02001283 *
1284 * @mr: the #MemoryRegion to be initialized.
1285 * @owner: the object that tracks the region's reference count
Dr. David Alan Gilberte8f5fe22017-03-09 15:27:08 +00001286 * @name: Region name, becomes part of RAMBlock name used in migration stream
1287 * must be unique within any device
Michael S. Tsirkin60786ef2014-11-17 00:24:36 +02001288 * @size: used size of the region.
1289 * @max_size: max size of the region.
1290 * @resized: callback to notify owner about used size change.
1291 * @errp: pointer to Error*, to store an error if it happens.
Peter Maydella5c02342017-07-07 15:42:48 +01001292 *
1293 * Note that this function does not do anything to cause the data in the
1294 * RAM memory region to be migrated; that is the responsibility of the caller.
Michael S. Tsirkin60786ef2014-11-17 00:24:36 +02001295 */
1296void memory_region_init_resizeable_ram(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001297 Object *owner,
Michael S. Tsirkin60786ef2014-11-17 00:24:36 +02001298 const char *name,
1299 uint64_t size,
1300 uint64_t max_size,
1301 void (*resized)(const char*,
1302 uint64_t length,
1303 void *host),
1304 Error **errp);
Hikaru Nishidad5dbde42018-09-24 21:32:05 +09001305#ifdef CONFIG_POSIX
Junyan Hecbfc0172018-07-18 15:47:58 +08001306
Paolo Bonzini0b183fc2014-05-14 17:43:19 +08001307/**
1308 * memory_region_init_ram_from_file: Initialize RAM memory region with a
1309 * mmap-ed backend.
1310 *
1311 * @mr: the #MemoryRegion to be initialized.
1312 * @owner: the object that tracks the region's reference count
Dr. David Alan Gilberte8f5fe22017-03-09 15:27:08 +00001313 * @name: Region name, becomes part of RAMBlock name used in migration stream
1314 * must be unique within any device
Paolo Bonzini0b183fc2014-05-14 17:43:19 +08001315 * @size: size of the region.
Haozhong Zhang98376842017-12-11 15:28:04 +08001316 * @align: alignment of the region base address; if 0, the default alignment
1317 * (getpagesize()) will be used.
David Hildenbrand8dbe22c2021-05-10 13:43:21 +02001318 * @ram_flags: RamBlock flags. Supported flags: RAM_SHARED, RAM_PMEM,
1319 * RAM_NORESERVE,
Paolo Bonzini0b183fc2014-05-14 17:43:19 +08001320 * @path: the path in which to allocate the RAM.
Stefan Hajnoczi369d6dc2021-01-04 17:13:18 +00001321 * @readonly: true to open @path for reading, false for read/write.
Paolo Bonzini7f56e742014-05-14 17:43:20 +08001322 * @errp: pointer to Error*, to store an error if it happens.
Peter Maydella5c02342017-07-07 15:42:48 +01001323 *
1324 * Note that this function does not do anything to cause the data in the
1325 * RAM memory region to be migrated; that is the responsibility of the caller.
Paolo Bonzini0b183fc2014-05-14 17:43:19 +08001326 */
1327void memory_region_init_ram_from_file(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001328 Object *owner,
Paolo Bonzini0b183fc2014-05-14 17:43:19 +08001329 const char *name,
1330 uint64_t size,
Haozhong Zhang98376842017-12-11 15:28:04 +08001331 uint64_t align,
Junyan Hecbfc0172018-07-18 15:47:58 +08001332 uint32_t ram_flags,
Paolo Bonzini7f56e742014-05-14 17:43:20 +08001333 const char *path,
Stefan Hajnoczi369d6dc2021-01-04 17:13:18 +00001334 bool readonly,
Paolo Bonzini7f56e742014-05-14 17:43:20 +08001335 Error **errp);
Marc-André Lureaufea617c2017-06-02 18:12:24 +04001336
1337/**
1338 * memory_region_init_ram_from_fd: Initialize RAM memory region with a
1339 * mmap-ed backend.
1340 *
1341 * @mr: the #MemoryRegion to be initialized.
1342 * @owner: the object that tracks the region's reference count
1343 * @name: the name of the region.
1344 * @size: size of the region.
David Hildenbrand8dbe22c2021-05-10 13:43:21 +02001345 * @ram_flags: RamBlock flags. Supported flags: RAM_SHARED, RAM_PMEM,
Sean Christopherson56918a12021-07-19 19:21:04 +08001346 * RAM_NORESERVE, RAM_PROTECTED.
Marc-André Lureaufea617c2017-06-02 18:12:24 +04001347 * @fd: the fd to mmap.
Jagannathan Raman44a4ff32021-01-29 11:46:04 -05001348 * @offset: offset within the file referenced by fd
Marc-André Lureaufea617c2017-06-02 18:12:24 +04001349 * @errp: pointer to Error*, to store an error if it happens.
Peter Maydella5c02342017-07-07 15:42:48 +01001350 *
1351 * Note that this function does not do anything to cause the data in the
1352 * RAM memory region to be migrated; that is the responsibility of the caller.
Marc-André Lureaufea617c2017-06-02 18:12:24 +04001353 */
1354void memory_region_init_ram_from_fd(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001355 Object *owner,
Marc-André Lureaufea617c2017-06-02 18:12:24 +04001356 const char *name,
1357 uint64_t size,
David Hildenbrandd5015b82021-05-10 13:43:17 +02001358 uint32_t ram_flags,
Marc-André Lureaufea617c2017-06-02 18:12:24 +04001359 int fd,
Jagannathan Raman44a4ff32021-01-29 11:46:04 -05001360 ram_addr_t offset,
Marc-André Lureaufea617c2017-06-02 18:12:24 +04001361 Error **errp);
Paolo Bonzini0b183fc2014-05-14 17:43:19 +08001362#endif
1363
Avi Kivity093bc2c2011-07-26 14:26:01 +03001364/**
BALATON Zoltan1a7e8ca2012-08-22 17:18:38 +02001365 * memory_region_init_ram_ptr: Initialize RAM memory region from a
1366 * user-provided pointer. Accesses into the
1367 * region will modify memory directly.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001368 *
1369 * @mr: the #MemoryRegion to be initialized.
Paolo Bonzini2c9b15c2013-06-06 05:41:28 -04001370 * @owner: the object that tracks the region's reference count
Dr. David Alan Gilberte8f5fe22017-03-09 15:27:08 +00001371 * @name: Region name, becomes part of RAMBlock name used in migration stream
1372 * must be unique within any device
Avi Kivity093bc2c2011-07-26 14:26:01 +03001373 * @size: size of the region.
1374 * @ptr: memory to be mapped; must contain at least @size bytes.
Peter Maydella5c02342017-07-07 15:42:48 +01001375 *
1376 * Note that this function does not do anything to cause the data in the
1377 * RAM memory region to be migrated; that is the responsibility of the caller.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001378 */
1379void memory_region_init_ram_ptr(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001380 Object *owner,
Avi Kivity093bc2c2011-07-26 14:26:01 +03001381 const char *name,
1382 uint64_t size,
1383 void *ptr);
1384
1385/**
Alex Williamson21e00fa2016-10-31 09:53:03 -06001386 * memory_region_init_ram_device_ptr: Initialize RAM device memory region from
1387 * a user-provided pointer.
1388 *
1389 * A RAM device represents a mapping to a physical device, such as to a PCI
1390 * MMIO BAR of an vfio-pci assigned device. The memory region may be mapped
1391 * into the VM address space and access to the region will modify memory
1392 * directly. However, the memory region should not be included in a memory
1393 * dump (device may not be enabled/mapped at the time of the dump), and
1394 * operations incompatible with manipulating MMIO should be avoided. Replaces
1395 * skip_dump flag.
1396 *
1397 * @mr: the #MemoryRegion to be initialized.
1398 * @owner: the object that tracks the region's reference count
1399 * @name: the name of the region.
1400 * @size: size of the region.
1401 * @ptr: memory to be mapped; must contain at least @size bytes.
Peter Maydella5c02342017-07-07 15:42:48 +01001402 *
1403 * Note that this function does not do anything to cause the data in the
1404 * RAM memory region to be migrated; that is the responsibility of the caller.
1405 * (For RAM device memory regions, migrating the contents rarely makes sense.)
Alex Williamson21e00fa2016-10-31 09:53:03 -06001406 */
1407void memory_region_init_ram_device_ptr(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001408 Object *owner,
Alex Williamson21e00fa2016-10-31 09:53:03 -06001409 const char *name,
1410 uint64_t size,
1411 void *ptr);
1412
1413/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03001414 * memory_region_init_alias: Initialize a memory region that aliases all or a
1415 * part of another memory region.
1416 *
1417 * @mr: the #MemoryRegion to be initialized.
Paolo Bonzini2c9b15c2013-06-06 05:41:28 -04001418 * @owner: the object that tracks the region's reference count
Avi Kivity093bc2c2011-07-26 14:26:01 +03001419 * @name: used for debugging; not visible to the user or ABI
1420 * @orig: the region to be referenced; @mr will be equivalent to
1421 * @orig between @offset and @offset + @size - 1.
1422 * @offset: start of the section in @orig to be referenced.
1423 * @size: size of the region.
1424 */
1425void memory_region_init_alias(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001426 Object *owner,
Avi Kivity093bc2c2011-07-26 14:26:01 +03001427 const char *name,
1428 MemoryRegion *orig,
Avi Kivitya8170e52012-10-23 12:30:10 +02001429 hwaddr offset,
Avi Kivity093bc2c2011-07-26 14:26:01 +03001430 uint64_t size);
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03001431
1432/**
Peter Maydellb59821a2017-07-07 15:42:50 +01001433 * memory_region_init_rom_nomigrate: Initialize a ROM memory region.
Peter Maydella1777f72016-07-04 13:06:35 +01001434 *
Peter Maydellb59821a2017-07-07 15:42:50 +01001435 * This has the same effect as calling memory_region_init_ram_nomigrate()
Peter Maydella1777f72016-07-04 13:06:35 +01001436 * and then marking the resulting region read-only with
1437 * memory_region_set_readonly().
1438 *
Peter Maydellb59821a2017-07-07 15:42:50 +01001439 * Note that this function does not do anything to cause the data in the
1440 * RAM side of the memory region to be migrated; that is the responsibility
1441 * of the caller.
1442 *
Peter Maydella1777f72016-07-04 13:06:35 +01001443 * @mr: the #MemoryRegion to be initialized.
1444 * @owner: the object that tracks the region's reference count
Dr. David Alan Gilberte8f5fe22017-03-09 15:27:08 +00001445 * @name: Region name, becomes part of RAMBlock name used in migration stream
1446 * must be unique within any device
Peter Maydella1777f72016-07-04 13:06:35 +01001447 * @size: size of the region.
1448 * @errp: pointer to Error*, to store an error if it happens.
1449 */
Peter Maydellb59821a2017-07-07 15:42:50 +01001450void memory_region_init_rom_nomigrate(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001451 Object *owner,
Peter Maydellb59821a2017-07-07 15:42:50 +01001452 const char *name,
1453 uint64_t size,
1454 Error **errp);
Peter Maydella1777f72016-07-04 13:06:35 +01001455
1456/**
Peter Maydellb59821a2017-07-07 15:42:50 +01001457 * memory_region_init_rom_device_nomigrate: Initialize a ROM memory region.
1458 * Writes are handled via callbacks.
1459 *
1460 * Note that this function does not do anything to cause the data in the
1461 * RAM side of the memory region to be migrated; that is the responsibility
1462 * of the caller.
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03001463 *
1464 * @mr: the #MemoryRegion to be initialized.
Paolo Bonzini2c9b15c2013-06-06 05:41:28 -04001465 * @owner: the object that tracks the region's reference count
Peter Maydell39e0b032016-07-04 13:06:35 +01001466 * @ops: callbacks for write access handling (must not be NULL).
Jay Zhou57914ec2018-01-04 13:29:48 +08001467 * @opaque: passed to the read and write callbacks of the @ops structure.
Dr. David Alan Gilberte8f5fe22017-03-09 15:27:08 +00001468 * @name: Region name, becomes part of RAMBlock name used in migration stream
1469 * must be unique within any device
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03001470 * @size: size of the region.
Hu Tao33e0eb52014-09-09 13:27:57 +08001471 * @errp: pointer to Error*, to store an error if it happens.
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03001472 */
Peter Maydellb59821a2017-07-07 15:42:50 +01001473void memory_region_init_rom_device_nomigrate(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001474 Object *owner,
Peter Maydellb59821a2017-07-07 15:42:50 +01001475 const MemoryRegionOps *ops,
1476 void *opaque,
1477 const char *name,
1478 uint64_t size,
1479 Error **errp);
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03001480
Avi Kivity093bc2c2011-07-26 14:26:01 +03001481/**
Alexey Kardashevskiy1221a472017-07-11 13:56:20 +10001482 * memory_region_init_iommu: Initialize a memory region of a custom type
1483 * that translates addresses
Avi Kivity30951152012-10-30 13:47:46 +02001484 *
1485 * An IOMMU region translates addresses and forwards accesses to a target
1486 * memory region.
1487 *
Peter Maydell2ce931d2018-05-31 14:50:52 +01001488 * The IOMMU implementation must define a subclass of TYPE_IOMMU_MEMORY_REGION.
1489 * @_iommu_mr should be a pointer to enough memory for an instance of
1490 * that subclass, @instance_size is the size of that subclass, and
1491 * @mrtypename is its name. This function will initialize @_iommu_mr as an
1492 * instance of the subclass, and its methods will then be called to handle
1493 * accesses to the memory region. See the documentation of
1494 * #IOMMUMemoryRegionClass for further details.
1495 *
Alexey Kardashevskiy1221a472017-07-11 13:56:20 +10001496 * @_iommu_mr: the #IOMMUMemoryRegion to be initialized
1497 * @instance_size: the IOMMUMemoryRegion subclass instance size
Jay Zhou57914ec2018-01-04 13:29:48 +08001498 * @mrtypename: the type name of the #IOMMUMemoryRegion
Paolo Bonzini2c9b15c2013-06-06 05:41:28 -04001499 * @owner: the object that tracks the region's reference count
Avi Kivity30951152012-10-30 13:47:46 +02001500 * @name: used for debugging; not visible to the user or ABI
1501 * @size: size of the region.
1502 */
Alexey Kardashevskiy1221a472017-07-11 13:56:20 +10001503void memory_region_init_iommu(void *_iommu_mr,
1504 size_t instance_size,
1505 const char *mrtypename,
1506 Object *owner,
Avi Kivity30951152012-10-30 13:47:46 +02001507 const char *name,
1508 uint64_t size);
1509
Jan Kiszka1660e722011-10-23 16:01:19 +02001510/**
Peter Maydellb08199c2017-07-07 15:42:51 +01001511 * memory_region_init_ram - Initialize RAM memory region. Accesses into the
1512 * region will modify memory directly.
1513 *
1514 * @mr: the #MemoryRegion to be initialized
1515 * @owner: the object that tracks the region's reference count (must be
1516 * TYPE_DEVICE or a subclass of TYPE_DEVICE, or NULL)
1517 * @name: name of the memory region
1518 * @size: size of the region in bytes
1519 * @errp: pointer to Error*, to store an error if it happens.
1520 *
1521 * This function allocates RAM for a board model or device, and
1522 * arranges for it to be migrated (by calling vmstate_register_ram()
1523 * if @owner is a DeviceState, or vmstate_register_ram_global() if
1524 * @owner is NULL).
1525 *
1526 * TODO: Currently we restrict @owner to being either NULL (for
1527 * global RAM regions with no owner) or devices, so that we can
1528 * give the RAM block a unique name for migration purposes.
1529 * We should lift this restriction and allow arbitrary Objects.
1530 * If you pass a non-NULL non-device @owner then we will assert.
1531 */
1532void memory_region_init_ram(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001533 Object *owner,
Peter Maydellb08199c2017-07-07 15:42:51 +01001534 const char *name,
1535 uint64_t size,
1536 Error **errp);
1537
1538/**
1539 * memory_region_init_rom: Initialize a ROM memory region.
1540 *
1541 * This has the same effect as calling memory_region_init_ram()
1542 * and then marking the resulting region read-only with
1543 * memory_region_set_readonly(). This includes arranging for the
1544 * contents to be migrated.
1545 *
1546 * TODO: Currently we restrict @owner to being either NULL (for
1547 * global RAM regions with no owner) or devices, so that we can
1548 * give the RAM block a unique name for migration purposes.
1549 * We should lift this restriction and allow arbitrary Objects.
1550 * If you pass a non-NULL non-device @owner then we will assert.
1551 *
1552 * @mr: the #MemoryRegion to be initialized.
1553 * @owner: the object that tracks the region's reference count
1554 * @name: Region name, becomes part of RAMBlock name used in migration stream
1555 * must be unique within any device
1556 * @size: size of the region.
1557 * @errp: pointer to Error*, to store an error if it happens.
1558 */
1559void memory_region_init_rom(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001560 Object *owner,
Peter Maydellb08199c2017-07-07 15:42:51 +01001561 const char *name,
1562 uint64_t size,
1563 Error **errp);
1564
1565/**
1566 * memory_region_init_rom_device: Initialize a ROM memory region.
1567 * Writes are handled via callbacks.
1568 *
1569 * This function initializes a memory region backed by RAM for reads
1570 * and callbacks for writes, and arranges for the RAM backing to
1571 * be migrated (by calling vmstate_register_ram()
1572 * if @owner is a DeviceState, or vmstate_register_ram_global() if
1573 * @owner is NULL).
1574 *
1575 * TODO: Currently we restrict @owner to being either NULL (for
1576 * global RAM regions with no owner) or devices, so that we can
1577 * give the RAM block a unique name for migration purposes.
1578 * We should lift this restriction and allow arbitrary Objects.
1579 * If you pass a non-NULL non-device @owner then we will assert.
1580 *
1581 * @mr: the #MemoryRegion to be initialized.
1582 * @owner: the object that tracks the region's reference count
1583 * @ops: callbacks for write access handling (must not be NULL).
Paolo Bonzini5d248212019-10-29 17:22:48 +01001584 * @opaque: passed to the read and write callbacks of the @ops structure.
Peter Maydellb08199c2017-07-07 15:42:51 +01001585 * @name: Region name, becomes part of RAMBlock name used in migration stream
1586 * must be unique within any device
1587 * @size: size of the region.
1588 * @errp: pointer to Error*, to store an error if it happens.
1589 */
1590void memory_region_init_rom_device(MemoryRegion *mr,
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001591 Object *owner,
Peter Maydellb08199c2017-07-07 15:42:51 +01001592 const MemoryRegionOps *ops,
1593 void *opaque,
1594 const char *name,
1595 uint64_t size,
1596 Error **errp);
1597
1598
1599/**
Paolo Bonzini803c0812013-05-07 06:59:09 +02001600 * memory_region_owner: get a memory region's owner.
1601 *
1602 * @mr: the memory region being queried.
1603 */
Philippe Mathieu-Daudéd32335e2021-02-25 19:20:03 +01001604Object *memory_region_owner(MemoryRegion *mr);
Paolo Bonzini803c0812013-05-07 06:59:09 +02001605
1606/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03001607 * memory_region_size: get a memory region's size.
1608 *
1609 * @mr: the memory region being queried.
1610 */
1611uint64_t memory_region_size(MemoryRegion *mr);
1612
1613/**
Avi Kivity8ea92522011-12-08 15:58:43 +02001614 * memory_region_is_ram: check whether a memory region is random access
1615 *
Li Qiang847b31f2018-10-09 03:21:07 -07001616 * Returns %true if a memory region is random access.
Avi Kivity8ea92522011-12-08 15:58:43 +02001617 *
1618 * @mr: the memory region being queried
1619 */
Paolo Bonzini1619d1f2015-12-09 17:47:39 +01001620static inline bool memory_region_is_ram(MemoryRegion *mr)
1621{
1622 return mr->ram;
1623}
Avi Kivity8ea92522011-12-08 15:58:43 +02001624
1625/**
Alex Williamson21e00fa2016-10-31 09:53:03 -06001626 * memory_region_is_ram_device: check whether a memory region is a ram device
Nikunj A Dadhaniae4dc3f52014-09-15 09:28:23 +05301627 *
Li Qiang847b31f2018-10-09 03:21:07 -07001628 * Returns %true if a memory region is a device backed ram region
Nikunj A Dadhaniae4dc3f52014-09-15 09:28:23 +05301629 *
1630 * @mr: the memory region being queried
1631 */
Alex Williamson21e00fa2016-10-31 09:53:03 -06001632bool memory_region_is_ram_device(MemoryRegion *mr);
Nikunj A Dadhaniae4dc3f52014-09-15 09:28:23 +05301633
1634/**
Jan Kiszka5f9a5ea2013-05-07 19:04:25 +02001635 * memory_region_is_romd: check whether a memory region is in ROMD mode
Blue Swirlfd062572012-04-09 17:38:52 +00001636 *
Jan Kiszka5f9a5ea2013-05-07 19:04:25 +02001637 * Returns %true if a memory region is a ROM device and currently set to allow
Blue Swirlfd062572012-04-09 17:38:52 +00001638 * direct reads.
1639 *
1640 * @mr: the memory region being queried
1641 */
1642static inline bool memory_region_is_romd(MemoryRegion *mr)
1643{
Jan Kiszka5f9a5ea2013-05-07 19:04:25 +02001644 return mr->rom_device && mr->romd_mode;
Blue Swirlfd062572012-04-09 17:38:52 +00001645}
1646
1647/**
Sean Christopherson56918a12021-07-19 19:21:04 +08001648 * memory_region_is_protected: check whether a memory region is protected
1649 *
1650 * Returns %true if a memory region is protected RAM and cannot be accessed
1651 * via standard mechanisms, e.g. DMA.
1652 *
1653 * @mr: the memory region being queried
1654 */
1655bool memory_region_is_protected(MemoryRegion *mr);
1656
1657/**
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001658 * memory_region_get_iommu: check whether a memory region is an iommu
Avi Kivity30951152012-10-30 13:47:46 +02001659 *
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001660 * Returns pointer to IOMMUMemoryRegion if a memory region is an iommu,
1661 * otherwise NULL.
Avi Kivity30951152012-10-30 13:47:46 +02001662 *
1663 * @mr: the memory region being queried
1664 */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001665static inline IOMMUMemoryRegion *memory_region_get_iommu(MemoryRegion *mr)
Paolo Bonzini1619d1f2015-12-09 17:47:39 +01001666{
Jason Wang12d37882016-12-30 18:09:18 +08001667 if (mr->alias) {
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001668 return memory_region_get_iommu(mr->alias);
Jason Wang12d37882016-12-30 18:09:18 +08001669 }
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001670 if (mr->is_iommu) {
1671 return (IOMMUMemoryRegion *) mr;
1672 }
1673 return NULL;
Paolo Bonzini1619d1f2015-12-09 17:47:39 +01001674}
1675
Alexey Kardashevskiy1221a472017-07-11 13:56:20 +10001676/**
1677 * memory_region_get_iommu_class_nocheck: returns iommu memory region class
1678 * if an iommu or NULL if not
1679 *
Jay Zhou57914ec2018-01-04 13:29:48 +08001680 * Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu,
1681 * otherwise NULL. This is fast path avoiding QOM checking, use with caution.
Alexey Kardashevskiy1221a472017-07-11 13:56:20 +10001682 *
Paolo Bonzini5d248212019-10-29 17:22:48 +01001683 * @iommu_mr: the memory region being queried
Alexey Kardashevskiy1221a472017-07-11 13:56:20 +10001684 */
1685static inline IOMMUMemoryRegionClass *memory_region_get_iommu_class_nocheck(
1686 IOMMUMemoryRegion *iommu_mr)
1687{
1688 return (IOMMUMemoryRegionClass *) (((Object *)iommu_mr)->class);
1689}
1690
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001691#define memory_region_is_iommu(mr) (memory_region_get_iommu(mr) != NULL)
Avi Kivity30951152012-10-30 13:47:46 +02001692
1693/**
Alexey Kardashevskiyf682e9c2016-06-21 11:14:01 +10001694 * memory_region_iommu_get_min_page_size: get minimum supported page size
1695 * for an iommu
1696 *
1697 * Returns minimum supported page size for an iommu.
1698 *
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001699 * @iommu_mr: the memory region being queried
Alexey Kardashevskiyf682e9c2016-06-21 11:14:01 +10001700 */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001701uint64_t memory_region_iommu_get_min_page_size(IOMMUMemoryRegion *iommu_mr);
Alexey Kardashevskiyf682e9c2016-06-21 11:14:01 +10001702
1703/**
David Gibson06866572013-05-14 19:13:56 +10001704 * memory_region_notify_iommu: notify a change in an IOMMU translation entry.
1705 *
Peter Xucdb30812016-09-23 13:02:26 +08001706 * Note: for any IOMMU implementation, an in-place mapping change
1707 * should be notified with an UNMAP followed by a MAP.
1708 *
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001709 * @iommu_mr: the memory region that was changed
Peter Maydellcb1efcf2018-06-15 14:57:16 +01001710 * @iommu_idx: the IOMMU index for the translation table which has changed
Eugenio Pérez5039caf2020-11-16 17:55:03 +01001711 * @event: TLB event with the new entry in the IOMMU translation table.
1712 * The entry replaces all old entries for the same virtual I/O address
1713 * range.
David Gibson06866572013-05-14 19:13:56 +10001714 */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001715void memory_region_notify_iommu(IOMMUMemoryRegion *iommu_mr,
Peter Maydellcb1efcf2018-06-15 14:57:16 +01001716 int iommu_idx,
Eugenio Pérez5039caf2020-11-16 17:55:03 +01001717 IOMMUTLBEvent event);
David Gibson06866572013-05-14 19:13:56 +10001718
1719/**
Eugenio Pérez3b5ebf82020-11-16 17:55:02 +01001720 * memory_region_notify_iommu_one: notify a change in an IOMMU translation
Peter Xubd2bfa42017-04-07 18:59:10 +08001721 * entry to a single notifier
1722 *
1723 * This works just like memory_region_notify_iommu(), but it only
1724 * notifies a specific notifier, not all of them.
1725 *
1726 * @notifier: the notifier to be notified
Eugenio Pérez5039caf2020-11-16 17:55:03 +01001727 * @event: TLB event with the new entry in the IOMMU translation table.
1728 * The entry replaces all old entries for the same virtual I/O address
1729 * range.
Peter Xubd2bfa42017-04-07 18:59:10 +08001730 */
Eugenio Pérez3b5ebf82020-11-16 17:55:02 +01001731void memory_region_notify_iommu_one(IOMMUNotifier *notifier,
Eugenio Pérez5039caf2020-11-16 17:55:03 +01001732 IOMMUTLBEvent *event);
Peter Xubd2bfa42017-04-07 18:59:10 +08001733
1734/**
Jason Wang7caebbf2023-02-23 14:59:22 +08001735 * memory_region_unmap_iommu_notifier_range: notify a unmap for an IOMMU
1736 * translation that covers the
1737 * range of a notifier
1738 *
1739 * @notifier: the notifier to be notified
1740 */
1741void memory_region_unmap_iommu_notifier_range(IOMMUNotifier *n);
1742
1743
1744/**
David Gibson06866572013-05-14 19:13:56 +10001745 * memory_region_register_iommu_notifier: register a notifier for changes to
1746 * IOMMU translation entries.
1747 *
Eric Auger549d40052019-09-24 10:25:17 +02001748 * Returns 0 on success, or a negative errno otherwise. In particular,
1749 * -EINVAL indicates that at least one of the attributes of the notifier
1750 * is not supported (flag/range) by the IOMMU memory region. In case of error
1751 * the error object must be created.
1752 *
David Gibson06866572013-05-14 19:13:56 +10001753 * @mr: the memory region to observe
Peter Xucdb30812016-09-23 13:02:26 +08001754 * @n: the IOMMUNotifier to be added; the notify callback receives a
1755 * pointer to an #IOMMUTLBEntry as the opaque value; the pointer
1756 * ceases to be valid on exit from the notifier.
Paolo Bonzini5d248212019-10-29 17:22:48 +01001757 * @errp: pointer to Error*, to store an error if it happens.
David Gibson06866572013-05-14 19:13:56 +10001758 */
Eric Auger549d40052019-09-24 10:25:17 +02001759int memory_region_register_iommu_notifier(MemoryRegion *mr,
1760 IOMMUNotifier *n, Error **errp);
David Gibson06866572013-05-14 19:13:56 +10001761
1762/**
David Gibsona788f222015-09-30 12:13:55 +10001763 * memory_region_iommu_replay: replay existing IOMMU translations to
Alexey Kardashevskiyf682e9c2016-06-21 11:14:01 +10001764 * a notifier with the minimum page granularity returned by
1765 * mr->iommu_ops->get_page_size().
David Gibsona788f222015-09-30 12:13:55 +10001766 *
Peter Maydell2ce931d2018-05-31 14:50:52 +01001767 * Note: this is not related to record-and-replay functionality.
1768 *
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001769 * @iommu_mr: the memory region to observe
David Gibsona788f222015-09-30 12:13:55 +10001770 * @n: the notifier to which to replay iommu mappings
David Gibsona788f222015-09-30 12:13:55 +10001771 */
Alexey Kardashevskiy3df9d742017-07-11 13:56:19 +10001772void memory_region_iommu_replay(IOMMUMemoryRegion *iommu_mr, IOMMUNotifier *n);
David Gibsona788f222015-09-30 12:13:55 +10001773
1774/**
David Gibson06866572013-05-14 19:13:56 +10001775 * memory_region_unregister_iommu_notifier: unregister a notifier for
1776 * changes to IOMMU translation entries.
1777 *
Alexey Kardashevskiyd22d8952016-06-30 13:00:23 -06001778 * @mr: the memory region which was observed and for which notity_stopped()
1779 * needs to be called
David Gibson06866572013-05-14 19:13:56 +10001780 * @n: the notifier to be removed.
1781 */
Peter Xucdb30812016-09-23 13:02:26 +08001782void memory_region_unregister_iommu_notifier(MemoryRegion *mr,
1783 IOMMUNotifier *n);
David Gibson06866572013-05-14 19:13:56 +10001784
1785/**
Alexey Kardashevskiyf1334de2018-02-06 11:08:24 -07001786 * memory_region_iommu_get_attr: return an IOMMU attr if get_attr() is
1787 * defined on the IOMMU.
1788 *
Peter Maydell2ce931d2018-05-31 14:50:52 +01001789 * Returns 0 on success, or a negative errno otherwise. In particular,
1790 * -EINVAL indicates that the IOMMU does not support the requested
1791 * attribute.
Alexey Kardashevskiyf1334de2018-02-06 11:08:24 -07001792 *
1793 * @iommu_mr: the memory region
1794 * @attr: the requested attribute
1795 * @data: a pointer to the requested attribute data
1796 */
1797int memory_region_iommu_get_attr(IOMMUMemoryRegion *iommu_mr,
1798 enum IOMMUMemoryRegionAttr attr,
1799 void *data);
1800
1801/**
Peter Maydell21f40202018-06-15 14:57:15 +01001802 * memory_region_iommu_attrs_to_index: return the IOMMU index to
1803 * use for translations with the given memory transaction attributes.
1804 *
1805 * @iommu_mr: the memory region
1806 * @attrs: the memory transaction attributes
1807 */
1808int memory_region_iommu_attrs_to_index(IOMMUMemoryRegion *iommu_mr,
1809 MemTxAttrs attrs);
1810
1811/**
1812 * memory_region_iommu_num_indexes: return the total number of IOMMU
1813 * indexes that this IOMMU supports.
1814 *
1815 * @iommu_mr: the memory region
1816 */
1817int memory_region_iommu_num_indexes(IOMMUMemoryRegion *iommu_mr);
1818
1819/**
Bharat Bhushan457f8cb2020-10-30 19:05:07 +01001820 * memory_region_iommu_set_page_size_mask: set the supported page
1821 * sizes for a given IOMMU memory region
1822 *
1823 * @iommu_mr: IOMMU memory region
1824 * @page_size_mask: supported page size mask
1825 * @errp: pointer to Error*, to store an error if it happens.
1826 */
1827int memory_region_iommu_set_page_size_mask(IOMMUMemoryRegion *iommu_mr,
1828 uint64_t page_size_mask,
1829 Error **errp);
1830
1831/**
Avi Kivity8991c792011-12-20 15:53:11 +02001832 * memory_region_name: get a memory region's name
1833 *
1834 * Returns the string that was used to initialize the memory region.
1835 *
1836 * @mr: the memory region being queried
1837 */
Peter Crosthwaite5d546d42014-08-14 23:55:03 -07001838const char *memory_region_name(const MemoryRegion *mr);
Avi Kivity8991c792011-12-20 15:53:11 +02001839
1840/**
Avi Kivity55043ba2011-12-15 17:20:34 +02001841 * memory_region_is_logging: return whether a memory region is logging writes
1842 *
Paolo Bonzini2d1a35b2015-03-23 10:50:57 +01001843 * Returns %true if the memory region is logging writes for the given client
1844 *
1845 * @mr: the memory region being queried
1846 * @client: the client being queried
1847 */
1848bool memory_region_is_logging(MemoryRegion *mr, uint8_t client);
1849
1850/**
1851 * memory_region_get_dirty_log_mask: return the clients for which a
1852 * memory region is logging writes.
1853 *
Paolo Bonzini677e7802015-03-23 10:53:21 +01001854 * Returns a bitmap of clients, in which the DIRTY_MEMORY_* constants
1855 * are the bit indices.
Avi Kivity55043ba2011-12-15 17:20:34 +02001856 *
1857 * @mr: the memory region being queried
1858 */
Paolo Bonzini2d1a35b2015-03-23 10:50:57 +01001859uint8_t memory_region_get_dirty_log_mask(MemoryRegion *mr);
Avi Kivity55043ba2011-12-15 17:20:34 +02001860
1861/**
Avi Kivityce7923d2011-12-08 16:05:11 +02001862 * memory_region_is_rom: check whether a memory region is ROM
1863 *
Li Qiang847b31f2018-10-09 03:21:07 -07001864 * Returns %true if a memory region is read-only memory.
Avi Kivityce7923d2011-12-08 16:05:11 +02001865 *
1866 * @mr: the memory region being queried
1867 */
Paolo Bonzini1619d1f2015-12-09 17:47:39 +01001868static inline bool memory_region_is_rom(MemoryRegion *mr)
1869{
1870 return mr->ram && mr->readonly;
1871}
1872
Marc-André Lureauc26763f2018-10-03 15:44:52 +04001873/**
1874 * memory_region_is_nonvolatile: check whether a memory region is non-volatile
1875 *
1876 * Returns %true is a memory region is non-volatile memory.
1877 *
1878 * @mr: the memory region being queried
1879 */
1880static inline bool memory_region_is_nonvolatile(MemoryRegion *mr)
1881{
1882 return mr->nonvolatile;
1883}
Avi Kivityce7923d2011-12-08 16:05:11 +02001884
1885/**
Paolo Bonzinia35ba7b2014-06-10 19:15:23 +08001886 * memory_region_get_fd: Get a file descriptor backing a RAM memory region.
1887 *
1888 * Returns a file descriptor backing a file-based RAM memory region,
1889 * or -1 if the region is not a file-based RAM memory region.
1890 *
1891 * @mr: the RAM or alias memory region being queried.
1892 */
1893int memory_region_get_fd(MemoryRegion *mr);
1894
1895/**
Paolo Bonzini07bdaa42016-03-25 12:55:08 +01001896 * memory_region_from_host: Convert a pointer into a RAM memory region
1897 * and an offset within it.
1898 *
1899 * Given a host pointer inside a RAM memory region (created with
1900 * memory_region_init_ram() or memory_region_init_ram_ptr()), return
1901 * the MemoryRegion and the offset within it.
1902 *
1903 * Use with care; by the time this function returns, the returned pointer is
1904 * not protected by RCU anymore. If the caller is not within an RCU critical
1905 * section and does not hold the iothread lock, it must have other means of
1906 * protecting the pointer, such as a reference to the region that includes
1907 * the incoming ram_addr_t.
1908 *
Jay Zhou57914ec2018-01-04 13:29:48 +08001909 * @ptr: the host pointer to be converted
1910 * @offset: the offset within memory region
Paolo Bonzini07bdaa42016-03-25 12:55:08 +01001911 */
1912MemoryRegion *memory_region_from_host(void *ptr, ram_addr_t *offset);
1913
1914/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03001915 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
1916 *
1917 * Returns a host pointer to a RAM memory region (created with
Paolo Bonzini49b24af2015-12-16 10:30:47 +01001918 * memory_region_init_ram() or memory_region_init_ram_ptr()).
1919 *
1920 * Use with care; by the time this function returns, the returned pointer is
1921 * not protected by RCU anymore. If the caller is not within an RCU critical
1922 * section and does not hold the iothread lock, it must have other means of
1923 * protecting the pointer, such as a reference to the region that includes
1924 * the incoming ram_addr_t.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001925 *
1926 * @mr: the memory region being queried.
1927 */
1928void *memory_region_get_ram_ptr(MemoryRegion *mr);
1929
Paolo Bonzini37d7c082015-03-23 10:21:46 +01001930/* memory_region_ram_resize: Resize a RAM region.
1931 *
David Hildenbrandc7c0e722021-04-29 13:27:02 +02001932 * Resizing RAM while migrating can result in the migration being canceled.
1933 * Care has to be taken if the guest might have already detected the memory.
Paolo Bonzini37d7c082015-03-23 10:21:46 +01001934 *
1935 * @mr: a memory region created with @memory_region_init_resizeable_ram.
1936 * @newsize: the new size the region
1937 * @errp: pointer to Error*, to store an error if it happens.
1938 */
1939void memory_region_ram_resize(MemoryRegion *mr, ram_addr_t newsize,
1940 Error **errp);
Philippe Mathieu-Daudé9ecc9962020-05-08 08:24:54 +02001941
Beata Michalska61c490e2019-11-21 00:08:41 +00001942/**
Philippe Mathieu-Daudé9ecc9962020-05-08 08:24:54 +02001943 * memory_region_msync: Synchronize selected address range of
1944 * a memory mapped region
1945 *
1946 * @mr: the memory region to be msync
1947 * @addr: the initial address of the range to be sync
1948 * @size: the size of the range to be sync
1949 */
1950void memory_region_msync(MemoryRegion *mr, hwaddr addr, hwaddr size);
1951
1952/**
1953 * memory_region_writeback: Trigger cache writeback for
Paolo Bonzini5d248212019-10-29 17:22:48 +01001954 * selected address range
Beata Michalska61c490e2019-11-21 00:08:41 +00001955 *
Paolo Bonzini5d248212019-10-29 17:22:48 +01001956 * @mr: the memory region to be updated
1957 * @addr: the initial address of the range to be written back
1958 * @size: the size of the range to be written back
Beata Michalska61c490e2019-11-21 00:08:41 +00001959 */
Philippe Mathieu-Daudé4dfe59d2020-05-08 08:24:53 +02001960void memory_region_writeback(MemoryRegion *mr, hwaddr addr, hwaddr size);
Paolo Bonzini37d7c082015-03-23 10:21:46 +01001961
Avi Kivity093bc2c2011-07-26 14:26:01 +03001962/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03001963 * memory_region_set_log: Turn dirty logging on or off for a region.
1964 *
1965 * Turns dirty logging on or off for a specified client (display, migration).
1966 * Only meaningful for RAM regions.
1967 *
1968 * @mr: the memory region being updated.
1969 * @log: whether dirty logging is to be enabled or disabled.
Paolo Bonzinidbddac62015-03-23 10:31:53 +01001970 * @client: the user of the logging information; %DIRTY_MEMORY_VGA only.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001971 */
1972void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
1973
1974/**
Blue Swirlfd4aa972011-10-16 16:04:59 +00001975 * memory_region_set_dirty: Mark a range of bytes as dirty in a memory region.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001976 *
Blue Swirlfd4aa972011-10-16 16:04:59 +00001977 * Marks a range of bytes as dirty, after it has been dirtied outside
1978 * guest code.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001979 *
Blue Swirlfd4aa972011-10-16 16:04:59 +00001980 * @mr: the memory region being dirtied.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001981 * @addr: the address (relative to the start of the region) being dirtied.
Blue Swirlfd4aa972011-10-16 16:04:59 +00001982 * @size: size of the range being dirtied.
Avi Kivity093bc2c2011-07-26 14:26:01 +03001983 */
Avi Kivitya8170e52012-10-23 12:30:10 +02001984void memory_region_set_dirty(MemoryRegion *mr, hwaddr addr,
1985 hwaddr size);
Avi Kivity093bc2c2011-07-26 14:26:01 +03001986
1987/**
Peter Xu077874e2019-06-03 14:50:51 +08001988 * memory_region_clear_dirty_bitmap - clear dirty bitmap for memory range
1989 *
1990 * This function is called when the caller wants to clear the remote
1991 * dirty bitmap of a memory range within the memory region. This can
1992 * be used by e.g. KVM to manually clear dirty log when
1993 * KVM_CAP_MANUAL_DIRTY_LOG_PROTECT is declared support by the host
1994 * kernel.
1995 *
1996 * @mr: the memory region to clear the dirty log upon
1997 * @start: start address offset within the memory region
1998 * @len: length of the memory region to clear dirty bitmap
1999 */
2000void memory_region_clear_dirty_bitmap(MemoryRegion *mr, hwaddr start,
2001 hwaddr len);
2002
2003/**
Gerd Hoffmann8deaf122017-04-21 11:16:25 +02002004 * memory_region_snapshot_and_clear_dirty: Get a snapshot of the dirty
2005 * bitmap and clear it.
2006 *
2007 * Creates a snapshot of the dirty bitmap, clears the dirty bitmap and
2008 * returns the snapshot. The snapshot can then be used to query dirty
Paolo Bonzini77302fb2018-02-06 18:30:04 +01002009 * status, using memory_region_snapshot_get_dirty. Snapshotting allows
2010 * querying the same page multiple times, which is especially useful for
2011 * display updates where the scanlines often are not page aligned.
Gerd Hoffmann8deaf122017-04-21 11:16:25 +02002012 *
Stefan Weil1e458f12022-10-30 11:59:44 +01002013 * The dirty bitmap region which gets copied into the snapshot (and
Gerd Hoffmann8deaf122017-04-21 11:16:25 +02002014 * cleared afterwards) can be larger than requested. The boundaries
2015 * are rounded up/down so complete bitmap longs (covering 64 pages on
2016 * 64bit hosts) can be copied over into the bitmap snapshot. Which
2017 * isn't a problem for display updates as the extra pages are outside
2018 * the visible area, and in case the visible area changes a full
2019 * display redraw is due anyway. Should other use cases for this
2020 * function emerge we might have to revisit this implementation
2021 * detail.
2022 *
2023 * Use g_free to release DirtyBitmapSnapshot.
2024 *
2025 * @mr: the memory region being queried.
2026 * @addr: the address (relative to the start of the region) being queried.
2027 * @size: the size of the range being queried.
2028 * @client: the user of the logging information; typically %DIRTY_MEMORY_VGA.
2029 */
2030DirtyBitmapSnapshot *memory_region_snapshot_and_clear_dirty(MemoryRegion *mr,
2031 hwaddr addr,
2032 hwaddr size,
2033 unsigned client);
2034
2035/**
2036 * memory_region_snapshot_get_dirty: Check whether a range of bytes is dirty
2037 * in the specified dirty bitmap snapshot.
2038 *
2039 * @mr: the memory region being queried.
2040 * @snap: the dirty bitmap snapshot
2041 * @addr: the address (relative to the start of the region) being queried.
2042 * @size: the size of the range being queried.
2043 */
2044bool memory_region_snapshot_get_dirty(MemoryRegion *mr,
2045 DirtyBitmapSnapshot *snap,
2046 hwaddr addr, hwaddr size);
2047
Juan Quintela6c279db2012-10-17 20:24:28 +02002048/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03002049 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
2050 * client.
2051 *
2052 * Marks a range of pages as no longer dirty.
2053 *
2054 * @mr: the region being updated.
2055 * @addr: the start of the subrange being cleaned.
2056 * @size: the size of the subrange being cleaned.
2057 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
2058 * %DIRTY_MEMORY_VGA.
2059 */
Avi Kivitya8170e52012-10-23 12:30:10 +02002060void memory_region_reset_dirty(MemoryRegion *mr, hwaddr addr,
2061 hwaddr size, unsigned client);
Avi Kivity093bc2c2011-07-26 14:26:01 +03002062
2063/**
Stefan Hajnoczi047be4e2019-01-29 11:46:04 +00002064 * memory_region_flush_rom_device: Mark a range of pages dirty and invalidate
2065 * TBs (for self-modifying code).
2066 *
2067 * The MemoryRegionOps->write() callback of a ROM device must use this function
2068 * to mark byte ranges that have been modified internally, such as by directly
2069 * accessing the memory returned by memory_region_get_ram_ptr().
2070 *
2071 * This function marks the range dirty and invalidates TBs so that TCG can
2072 * detect self-modifying code.
2073 *
2074 * @mr: the region being flushed.
2075 * @addr: the start, relative to the start of the region, of the range being
2076 * flushed.
2077 * @size: the size, in bytes, of the range being flushed.
2078 */
2079void memory_region_flush_rom_device(MemoryRegion *mr, hwaddr addr, hwaddr size);
2080
2081/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03002082 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
2083 *
2084 * Allows a memory region to be marked as read-only (turning it into a ROM).
2085 * only useful on RAM regions.
2086 *
2087 * @mr: the region being updated.
2088 * @readonly: whether rhe region is to be ROM or RAM.
2089 */
2090void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
2091
2092/**
Marc-André Lureauc26763f2018-10-03 15:44:52 +04002093 * memory_region_set_nonvolatile: Turn a memory region non-volatile
2094 *
2095 * Allows a memory region to be marked as non-volatile.
2096 * only useful on RAM regions.
2097 *
2098 * @mr: the region being updated.
2099 * @nonvolatile: whether rhe region is to be non-volatile.
2100 */
2101void memory_region_set_nonvolatile(MemoryRegion *mr, bool nonvolatile);
2102
2103/**
Jan Kiszka5f9a5ea2013-05-07 19:04:25 +02002104 * memory_region_rom_device_set_romd: enable/disable ROMD mode
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03002105 *
2106 * Allows a ROM device (initialized with memory_region_init_rom_device() to
Jan Kiszka5f9a5ea2013-05-07 19:04:25 +02002107 * set to ROMD mode (default) or MMIO mode. When it is in ROMD mode, the
2108 * device is mapped to guest memory and satisfies read access directly.
2109 * When in MMIO mode, reads are forwarded to the #MemoryRegion.read function.
2110 * Writes are always handled by the #MemoryRegion.write function.
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03002111 *
2112 * @mr: the memory region to be updated
Jan Kiszka5f9a5ea2013-05-07 19:04:25 +02002113 * @romd_mode: %true to put the region into ROMD mode
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03002114 */
Jan Kiszka5f9a5ea2013-05-07 19:04:25 +02002115void memory_region_rom_device_set_romd(MemoryRegion *mr, bool romd_mode);
Avi Kivityd0a9b5b2011-08-08 19:58:49 +03002116
2117/**
Avi Kivity093bc2c2011-07-26 14:26:01 +03002118 * memory_region_set_coalescing: Enable memory coalescing for the region.
2119 *
2120 * Enabled writes to a region to be queued for later processing. MMIO ->write
2121 * callbacks may be delayed until a non-coalesced MMIO is issued.
2122 * Only useful for IO regions. Roughly similar to write-combining hardware.
2123 *
2124 * @mr: the memory region to be write coalesced
2125 */
2126void memory_region_set_coalescing(MemoryRegion *mr);
2127
2128/**
2129 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
2130 * a region.
2131 *
2132 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
2133 * Multiple calls can be issued coalesced disjoint ranges.
2134 *
2135 * @mr: the memory region to be updated.
2136 * @offset: the start of the range within the region to be coalesced.
2137 * @size: the size of the subrange to be coalesced.
2138 */
2139void memory_region_add_coalescing(MemoryRegion *mr,
Avi Kivitya8170e52012-10-23 12:30:10 +02002140 hwaddr offset,
Avi Kivity093bc2c2011-07-26 14:26:01 +03002141 uint64_t size);
2142
2143/**
2144 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
2145 *
2146 * Disables any coalescing caused by memory_region_set_coalescing() or
2147 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
2148 * hardware.
2149 *
2150 * @mr: the memory region to be updated.
2151 */
2152void memory_region_clear_coalescing(MemoryRegion *mr);
2153
2154/**
Jan Kiszkad4105152012-08-23 13:02:29 +02002155 * memory_region_set_flush_coalesced: Enforce memory coalescing flush before
2156 * accesses.
2157 *
2158 * Ensure that pending coalesced MMIO request are flushed before the memory
2159 * region is accessed. This property is automatically enabled for all regions
2160 * passed to memory_region_set_coalescing() and memory_region_add_coalescing().
2161 *
2162 * @mr: the memory region to be updated.
2163 */
2164void memory_region_set_flush_coalesced(MemoryRegion *mr);
2165
2166/**
2167 * memory_region_clear_flush_coalesced: Disable memory coalescing flush before
2168 * accesses.
2169 *
2170 * Clear the automatic coalesced MMIO flushing enabled via
2171 * memory_region_set_flush_coalesced. Note that this service has no effect on
2172 * memory regions that have MMIO coalescing enabled for themselves. For them,
2173 * automatic flushing will stop once coalescing is disabled.
2174 *
2175 * @mr: the memory region to be updated.
2176 */
2177void memory_region_clear_flush_coalesced(MemoryRegion *mr);
2178
2179/**
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002180 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
2181 * is written to a location.
2182 *
2183 * Marks a word in an IO region (initialized with memory_region_init_io())
2184 * as a trigger for an eventfd event. The I/O callback will not be called.
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002185 * The caller must be prepared to handle failure (that is, take the required
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002186 * action if the callback _is_ called).
2187 *
2188 * @mr: the memory region being updated.
2189 * @addr: the address within @mr that is to be monitored
2190 * @size: the size of the access to trigger the eventfd
2191 * @match_data: whether to match against @data, instead of just @addr
2192 * @data: the data to match against the guest write
Jay Zhou57914ec2018-01-04 13:29:48 +08002193 * @e: event notifier to be triggered when @addr, @size, and @data all match.
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002194 **/
2195void memory_region_add_eventfd(MemoryRegion *mr,
Avi Kivitya8170e52012-10-23 12:30:10 +02002196 hwaddr addr,
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002197 unsigned size,
2198 bool match_data,
2199 uint64_t data,
Paolo Bonzini753d5e12012-07-05 17:16:27 +02002200 EventNotifier *e);
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002201
2202/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002203 * memory_region_del_eventfd: Cancel an eventfd.
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002204 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002205 * Cancels an eventfd trigger requested by a previous
2206 * memory_region_add_eventfd() call.
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002207 *
2208 * @mr: the memory region being updated.
2209 * @addr: the address within @mr that is to be monitored
2210 * @size: the size of the access to trigger the eventfd
2211 * @match_data: whether to match against @data, instead of just @addr
2212 * @data: the data to match against the guest write
Jay Zhou57914ec2018-01-04 13:29:48 +08002213 * @e: event notifier to be triggered when @addr, @size, and @data all match.
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002214 */
2215void memory_region_del_eventfd(MemoryRegion *mr,
Avi Kivitya8170e52012-10-23 12:30:10 +02002216 hwaddr addr,
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002217 unsigned size,
2218 bool match_data,
2219 uint64_t data,
Paolo Bonzini753d5e12012-07-05 17:16:27 +02002220 EventNotifier *e);
2221
Avi Kivity3e9d69e2011-07-26 14:26:11 +03002222/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002223 * memory_region_add_subregion: Add a subregion to a container.
Avi Kivity093bc2c2011-07-26 14:26:01 +03002224 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002225 * Adds a subregion at @offset. The subregion may not overlap with other
Avi Kivity093bc2c2011-07-26 14:26:01 +03002226 * subregions (except for those explicitly marked as overlapping). A region
2227 * may only be added once as a subregion (unless removed with
2228 * memory_region_del_subregion()); use memory_region_init_alias() if you
2229 * want a region to be a subregion in multiple locations.
2230 *
2231 * @mr: the region to contain the new subregion; must be a container
2232 * initialized with memory_region_init().
2233 * @offset: the offset relative to @mr where @subregion is added.
2234 * @subregion: the subregion to be added.
2235 */
2236void memory_region_add_subregion(MemoryRegion *mr,
Avi Kivitya8170e52012-10-23 12:30:10 +02002237 hwaddr offset,
Avi Kivity093bc2c2011-07-26 14:26:01 +03002238 MemoryRegion *subregion);
2239/**
BALATON Zoltan1a7e8ca2012-08-22 17:18:38 +02002240 * memory_region_add_subregion_overlap: Add a subregion to a container
2241 * with overlap.
Avi Kivity093bc2c2011-07-26 14:26:01 +03002242 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002243 * Adds a subregion at @offset. The subregion may overlap with other
Avi Kivity093bc2c2011-07-26 14:26:01 +03002244 * subregions. Conflicts are resolved by having a higher @priority hide a
2245 * lower @priority. Subregions without priority are taken as @priority 0.
2246 * A region may only be added once as a subregion (unless removed with
2247 * memory_region_del_subregion()); use memory_region_init_alias() if you
2248 * want a region to be a subregion in multiple locations.
2249 *
2250 * @mr: the region to contain the new subregion; must be a container
2251 * initialized with memory_region_init().
2252 * @offset: the offset relative to @mr where @subregion is added.
2253 * @subregion: the subregion to be added.
2254 * @priority: used for resolving overlaps; highest priority wins.
2255 */
2256void memory_region_add_subregion_overlap(MemoryRegion *mr,
Avi Kivitya8170e52012-10-23 12:30:10 +02002257 hwaddr offset,
Avi Kivity093bc2c2011-07-26 14:26:01 +03002258 MemoryRegion *subregion,
Marcel Apfelbauma1ff8ae2013-09-16 11:21:14 +03002259 int priority);
Avi Kivitye34911c2011-12-19 12:06:23 +02002260
2261/**
2262 * memory_region_get_ram_addr: Get the ram address associated with a memory
2263 * region
Paolo Bonzini5d248212019-10-29 17:22:48 +01002264 *
2265 * @mr: the region to be queried
Avi Kivitye34911c2011-12-19 12:06:23 +02002266 */
Fam Zheng7ebb2742016-03-01 14:18:20 +08002267ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr);
Avi Kivitye34911c2011-12-19 12:06:23 +02002268
Igor Mammedova2b257d2014-10-31 16:38:37 +00002269uint64_t memory_region_get_alignment(const MemoryRegion *mr);
Avi Kivity093bc2c2011-07-26 14:26:01 +03002270/**
2271 * memory_region_del_subregion: Remove a subregion.
2272 *
2273 * Removes a subregion from its container.
2274 *
2275 * @mr: the container to be updated.
2276 * @subregion: the region being removed; must be a current subregion of @mr.
2277 */
2278void memory_region_del_subregion(MemoryRegion *mr,
2279 MemoryRegion *subregion);
2280
Avi Kivity6bba19b2011-09-14 11:54:58 +03002281/*
2282 * memory_region_set_enabled: dynamically enable or disable a region
2283 *
2284 * Enables or disables a memory region. A disabled memory region
2285 * ignores all accesses to itself and its subregions. It does not
2286 * obscure sibling subregions with lower priority - it simply behaves as
2287 * if it was removed from the hierarchy.
2288 *
2289 * Regions default to being enabled.
2290 *
2291 * @mr: the region to be updated
2292 * @enabled: whether to enable or disable the region
2293 */
2294void memory_region_set_enabled(MemoryRegion *mr, bool enabled);
2295
Avi Kivity2282e1a2011-09-14 12:10:12 +03002296/*
2297 * memory_region_set_address: dynamically update the address of a region
2298 *
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +02002299 * Dynamically updates the address of a region, relative to its container.
Avi Kivity2282e1a2011-09-14 12:10:12 +03002300 * May be used on regions are currently part of a memory hierarchy.
2301 *
2302 * @mr: the region to be updated
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +02002303 * @addr: new address, relative to container region
Avi Kivity2282e1a2011-09-14 12:10:12 +03002304 */
Avi Kivitya8170e52012-10-23 12:30:10 +02002305void memory_region_set_address(MemoryRegion *mr, hwaddr addr);
Avi Kivity2282e1a2011-09-14 12:10:12 +03002306
Avi Kivity47033592011-12-04 19:16:50 +02002307/*
Michael S. Tsirkine7af4c62014-12-16 11:21:23 +02002308 * memory_region_set_size: dynamically update the size of a region.
2309 *
2310 * Dynamically updates the size of a region.
2311 *
2312 * @mr: the region to be updated
2313 * @size: used size of the region.
2314 */
2315void memory_region_set_size(MemoryRegion *mr, uint64_t size);
2316
2317/*
Avi Kivity47033592011-12-04 19:16:50 +02002318 * memory_region_set_alias_offset: dynamically update a memory alias's offset
2319 *
2320 * Dynamically updates the offset into the target region that an alias points
2321 * to, as if the fourth argument to memory_region_init_alias() has changed.
2322 *
2323 * @mr: the #MemoryRegion to be updated; should be an alias.
2324 * @offset: the new offset into the target memory region
2325 */
2326void memory_region_set_alias_offset(MemoryRegion *mr,
Avi Kivitya8170e52012-10-23 12:30:10 +02002327 hwaddr offset);
Avi Kivity47033592011-12-04 19:16:50 +02002328
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002329/**
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +02002330 * memory_region_present: checks if an address relative to a @container
2331 * translates into #MemoryRegion within @container
Paolo Bonzini3ce10902013-07-02 13:40:48 +02002332 *
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +02002333 * Answer whether a #MemoryRegion within @container covers the address
Paolo Bonzini3ce10902013-07-02 13:40:48 +02002334 * @addr.
2335 *
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +02002336 * @container: a #MemoryRegion within which @addr is a relative address
2337 * @addr: the area within @container to be searched
Paolo Bonzini3ce10902013-07-02 13:40:48 +02002338 */
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +02002339bool memory_region_present(MemoryRegion *container, hwaddr addr);
Paolo Bonzini3ce10902013-07-02 13:40:48 +02002340
2341/**
Igor Mammedoveed2bac2014-06-02 15:25:06 +02002342 * memory_region_is_mapped: returns true if #MemoryRegion is mapped
David Hildenbrand455faf02021-11-02 17:43:17 +01002343 * into another memory region, which does not necessarily imply that it is
2344 * mapped into an address space.
Igor Mammedoveed2bac2014-06-02 15:25:06 +02002345 *
2346 * @mr: a #MemoryRegion which should be checked if it's mapped
2347 */
2348bool memory_region_is_mapped(MemoryRegion *mr);
2349
2350/**
David Hildenbrand8947d7f2021-04-13 11:55:19 +02002351 * memory_region_get_ram_discard_manager: get the #RamDiscardManager for a
2352 * #MemoryRegion
2353 *
2354 * The #RamDiscardManager cannot change while a memory region is mapped.
2355 *
2356 * @mr: the #MemoryRegion
2357 */
2358RamDiscardManager *memory_region_get_ram_discard_manager(MemoryRegion *mr);
2359
2360/**
2361 * memory_region_has_ram_discard_manager: check whether a #MemoryRegion has a
2362 * #RamDiscardManager assigned
2363 *
2364 * @mr: the #MemoryRegion
2365 */
2366static inline bool memory_region_has_ram_discard_manager(MemoryRegion *mr)
2367{
2368 return !!memory_region_get_ram_discard_manager(mr);
2369}
2370
2371/**
2372 * memory_region_set_ram_discard_manager: set the #RamDiscardManager for a
2373 * #MemoryRegion
2374 *
2375 * This function must not be called for a mapped #MemoryRegion, a #MemoryRegion
2376 * that does not cover RAM, or a #MemoryRegion that already has a
2377 * #RamDiscardManager assigned.
2378 *
2379 * @mr: the #MemoryRegion
2380 * @rdm: #RamDiscardManager to set
2381 */
2382void memory_region_set_ram_discard_manager(MemoryRegion *mr,
2383 RamDiscardManager *rdm);
2384
2385/**
Paolo Bonzini73034e92013-05-07 15:48:28 +02002386 * memory_region_find: translate an address/size relative to a
2387 * MemoryRegion into a #MemoryRegionSection.
Avi Kivitye2177952011-12-08 15:00:18 +02002388 *
Paolo Bonzini73034e92013-05-07 15:48:28 +02002389 * Locates the first #MemoryRegion within @mr that overlaps the range
2390 * given by @addr and @size.
Avi Kivitye2177952011-12-08 15:00:18 +02002391 *
2392 * Returns a #MemoryRegionSection that describes a contiguous overlap.
2393 * It will have the following characteristics:
Paolo Bonzini08226b42019-10-29 17:22:46 +01002394 * - @size = 0 iff no overlap was found
2395 * - @mr is non-%NULL iff an overlap was found
Avi Kivitye2177952011-12-08 15:00:18 +02002396 *
Paolo Bonzini73034e92013-05-07 15:48:28 +02002397 * Remember that in the return value the @offset_within_region is
2398 * relative to the returned region (in the .@mr field), not to the
2399 * @mr argument.
2400 *
2401 * Similarly, the .@offset_within_address_space is relative to the
2402 * address space that contains both regions, the passed and the
2403 * returned one. However, in the special case where the @mr argument
Paolo Bonzinifeca4ac2014-06-11 11:18:09 +02002404 * has no container (and thus is the root of the address space), the
Paolo Bonzini73034e92013-05-07 15:48:28 +02002405 * following will hold:
Paolo Bonzini08226b42019-10-29 17:22:46 +01002406 * - @offset_within_address_space >= @addr
2407 * - @offset_within_address_space + .@size <= @addr + @size
Paolo Bonzini73034e92013-05-07 15:48:28 +02002408 *
2409 * @mr: a MemoryRegion within which @addr is a relative address
2410 * @addr: start of the area within @as to be searched
Avi Kivitye2177952011-12-08 15:00:18 +02002411 * @size: size of the area to be searched
2412 */
Paolo Bonzini73034e92013-05-07 15:48:28 +02002413MemoryRegionSection memory_region_find(MemoryRegion *mr,
Avi Kivitya8170e52012-10-23 12:30:10 +02002414 hwaddr addr, uint64_t size);
Avi Kivitye2177952011-12-08 15:00:18 +02002415
Blue Swirlfd062572012-04-09 17:38:52 +00002416/**
Paolo Bonzini9c1f8f42016-09-22 16:08:31 +02002417 * memory_global_dirty_log_sync: synchronize the dirty log for all memory
Avi Kivity86e775c2011-12-15 16:24:49 +02002418 *
Paolo Bonzini9c1f8f42016-09-22 16:08:31 +02002419 * Synchronizes the dirty page log for all address spaces.
Avi Kivity86e775c2011-12-15 16:24:49 +02002420 */
Paolo Bonzini9c1f8f42016-09-22 16:08:31 +02002421void memory_global_dirty_log_sync(void);
Avi Kivity86e775c2011-12-15 16:24:49 +02002422
Avi Kivitye2177952011-12-08 15:00:18 +02002423/**
Paolo Bonzini9458a9a2018-02-06 18:37:39 +01002424 * memory_global_dirty_log_sync: synchronize the dirty log for all memory
2425 *
2426 * Synchronizes the vCPUs with a thread that is reading the dirty bitmap.
2427 * This function must be called after the dirty log bitmap is cleared, and
2428 * before dirty guest memory pages are read. If you are using
2429 * #DirtyBitmapSnapshot, memory_region_snapshot_and_clear_dirty() takes
2430 * care of doing this.
2431 */
2432void memory_global_after_dirty_log_sync(void);
2433
2434/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002435 * memory_region_transaction_begin: Start a transaction.
2436 *
2437 * During a transaction, changes will be accumulated and made visible
Stefan Weildabdf392012-01-08 19:35:09 +01002438 * only when the transaction ends (is committed).
Avi Kivity4ef4db82011-07-26 14:26:13 +03002439 */
2440void memory_region_transaction_begin(void);
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -03002441
2442/**
2443 * memory_region_transaction_commit: Commit a transaction and make changes
2444 * visible to the guest.
Avi Kivity4ef4db82011-07-26 14:26:13 +03002445 */
2446void memory_region_transaction_commit(void);
2447
Avi Kivity7664e802011-12-11 14:47:25 +02002448/**
2449 * memory_listener_register: register callbacks to be called when memory
2450 * sections are mapped or unmapped into an address
2451 * space
2452 *
2453 * @listener: an object containing the callbacks to be called
Avi Kivity7376e582012-02-08 21:05:17 +02002454 * @filter: if non-%NULL, only regions in this address space will be observed
Avi Kivity7664e802011-12-11 14:47:25 +02002455 */
Avi Kivityf6790af2012-10-02 20:13:51 +02002456void memory_listener_register(MemoryListener *listener, AddressSpace *filter);
Avi Kivity7664e802011-12-11 14:47:25 +02002457
2458/**
2459 * memory_listener_unregister: undo the effect of memory_listener_register()
2460 *
2461 * @listener: an object containing the callbacks to be removed
2462 */
2463void memory_listener_unregister(MemoryListener *listener);
2464
2465/**
2466 * memory_global_dirty_log_start: begin dirty logging for all regions
Hyman Huang(黄勇)63b41db2021-06-29 16:01:19 +00002467 *
2468 * @flags: purpose of starting dirty log, migration or dirty rate
Avi Kivity7664e802011-12-11 14:47:25 +02002469 */
Hyman Huang(黄勇)63b41db2021-06-29 16:01:19 +00002470void memory_global_dirty_log_start(unsigned int flags);
Avi Kivity7664e802011-12-11 14:47:25 +02002471
2472/**
BALATON Zoltan1a7e8ca2012-08-22 17:18:38 +02002473 * memory_global_dirty_log_stop: end dirty logging for all regions
Hyman Huang(黄勇)63b41db2021-06-29 16:01:19 +00002474 *
2475 * @flags: purpose of stopping dirty log, migration or dirty rate
Avi Kivity7664e802011-12-11 14:47:25 +02002476 */
Hyman Huang(黄勇)63b41db2021-06-29 16:01:19 +00002477void memory_global_dirty_log_stop(unsigned int flags);
Avi Kivity7664e802011-12-11 14:47:25 +02002478
Philippe Mathieu-Daudé2261d392020-05-29 14:53:25 +02002479void mtree_info(bool flatview, bool dispatch_tree, bool owner, bool disabled);
Blue Swirl314e2982011-09-11 20:22:05 +00002480
Philippe Mathieu-Daudé94e273d2022-12-17 16:24:50 +01002481bool memory_region_access_valid(MemoryRegion *mr, hwaddr addr,
2482 unsigned size, bool is_write,
2483 MemTxAttrs attrs);
2484
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02002485/**
Peter Maydell3b643492015-04-26 16:49:23 +01002486 * memory_region_dispatch_read: perform a read directly to the specified
2487 * MemoryRegion.
2488 *
2489 * @mr: #MemoryRegion to access
2490 * @addr: address within that region
2491 * @pval: pointer to uint64_t which the data is written to
Tony Nguyene67c9042019-08-24 04:36:48 +10002492 * @op: size, sign, and endianness of the memory operation
Peter Maydell3b643492015-04-26 16:49:23 +01002493 * @attrs: memory transaction attributes to use for the access
2494 */
2495MemTxResult memory_region_dispatch_read(MemoryRegion *mr,
2496 hwaddr addr,
2497 uint64_t *pval,
Tony Nguyene67c9042019-08-24 04:36:48 +10002498 MemOp op,
Peter Maydell3b643492015-04-26 16:49:23 +01002499 MemTxAttrs attrs);
2500/**
2501 * memory_region_dispatch_write: perform a write directly to the specified
2502 * MemoryRegion.
2503 *
2504 * @mr: #MemoryRegion to access
2505 * @addr: address within that region
2506 * @data: data to write
Tony Nguyene67c9042019-08-24 04:36:48 +10002507 * @op: size, sign, and endianness of the memory operation
Peter Maydell3b643492015-04-26 16:49:23 +01002508 * @attrs: memory transaction attributes to use for the access
2509 */
2510MemTxResult memory_region_dispatch_write(MemoryRegion *mr,
2511 hwaddr addr,
2512 uint64_t data,
Tony Nguyene67c9042019-08-24 04:36:48 +10002513 MemOp op,
Peter Maydell3b643492015-04-26 16:49:23 +01002514 MemTxAttrs attrs);
2515
2516/**
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02002517 * address_space_init: initializes an address space
2518 *
2519 * @as: an uninitialized #AddressSpace
Veres Lajos67cc32e2015-09-08 22:45:14 +01002520 * @root: a #MemoryRegion that routes addresses for the address space
Alexey Kardashevskiy7dca8042013-04-29 16:25:51 +00002521 * @name: an address space name. The name is only used for debugging
2522 * output.
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02002523 */
Alexey Kardashevskiy7dca8042013-04-29 16:25:51 +00002524void address_space_init(AddressSpace *as, MemoryRegion *root, const char *name);
Avi Kivity9ad2bbc2012-10-02 14:59:23 +02002525
Peter Crosthwaitef0c02d12016-01-21 14:15:06 +00002526/**
Avi Kivity83f3c252012-10-07 12:59:55 +02002527 * address_space_destroy: destroy an address space
2528 *
2529 * Releases all resources associated with an address space. After an address space
2530 * is destroyed, its root memory region (given by address_space_init()) may be destroyed
2531 * as well.
2532 *
2533 * @as: address space to be destroyed
2534 */
2535void address_space_destroy(AddressSpace *as);
2536
Avi Kivityac1970f2012-10-03 16:22:53 +02002537/**
Greg Kurza2166412019-06-21 11:27:33 +02002538 * address_space_remove_listeners: unregister all listeners of an address space
2539 *
2540 * Removes all callbacks previously registered with memory_listener_register()
2541 * for @as.
2542 *
2543 * @as: an initialized #AddressSpace
2544 */
2545void address_space_remove_listeners(AddressSpace *as);
2546
2547/**
Avi Kivityac1970f2012-10-03 16:22:53 +02002548 * address_space_rw: read from or write to an address space.
2549 *
Peter Maydell5c9eb022015-04-26 16:49:24 +01002550 * Return a MemTxResult indicating whether the operation succeeded
2551 * or failed (eg unassigned memory, device rejected the transaction,
2552 * IOMMU fault).
Paolo Bonzinifd8aaa72013-05-21 09:56:55 +02002553 *
Avi Kivityac1970f2012-10-03 16:22:53 +02002554 * @as: #AddressSpace to be accessed
2555 * @addr: address within that address space
Peter Maydell5c9eb022015-04-26 16:49:24 +01002556 * @attrs: memory transaction attributes
Avi Kivityac1970f2012-10-03 16:22:53 +02002557 * @buf: buffer with the data transferred
Jay Zhou57914ec2018-01-04 13:29:48 +08002558 * @len: the number of bytes to read or write
Avi Kivityac1970f2012-10-03 16:22:53 +02002559 * @is_write: indicates the transfer direction
2560 */
Peter Maydell5c9eb022015-04-26 16:49:24 +01002561MemTxResult address_space_rw(AddressSpace *as, hwaddr addr,
Philippe Mathieu-Daudédaa3dda2020-02-19 19:54:35 +01002562 MemTxAttrs attrs, void *buf,
Li Zhijian0c249ff2019-01-17 20:49:01 +08002563 hwaddr len, bool is_write);
Avi Kivityac1970f2012-10-03 16:22:53 +02002564
2565/**
2566 * address_space_write: write to address space.
2567 *
Peter Maydell5c9eb022015-04-26 16:49:24 +01002568 * Return a MemTxResult indicating whether the operation succeeded
2569 * or failed (eg unassigned memory, device rejected the transaction,
2570 * IOMMU fault).
Avi Kivityac1970f2012-10-03 16:22:53 +02002571 *
2572 * @as: #AddressSpace to be accessed
2573 * @addr: address within that address space
Peter Maydell5c9eb022015-04-26 16:49:24 +01002574 * @attrs: memory transaction attributes
Avi Kivityac1970f2012-10-03 16:22:53 +02002575 * @buf: buffer with the data transferred
Jay Zhou57914ec2018-01-04 13:29:48 +08002576 * @len: the number of bytes to write
Avi Kivityac1970f2012-10-03 16:22:53 +02002577 */
Peter Maydell5c9eb022015-04-26 16:49:24 +01002578MemTxResult address_space_write(AddressSpace *as, hwaddr addr,
2579 MemTxAttrs attrs,
Philippe Mathieu-Daudédaa3dda2020-02-19 19:54:35 +01002580 const void *buf, hwaddr len);
Paolo Bonzinifd8aaa72013-05-21 09:56:55 +02002581
Peter Maydell3c8133f2018-12-14 13:30:48 +00002582/**
2583 * address_space_write_rom: write to address space, including ROM.
2584 *
2585 * This function writes to the specified address space, but will
2586 * write data to both ROM and RAM. This is used for non-guest
2587 * writes like writes from the gdb debug stub or initial loading
2588 * of ROM contents.
2589 *
2590 * Note that portions of the write which attempt to write data to
2591 * a device will be silently ignored -- only real RAM and ROM will
2592 * be written to.
2593 *
2594 * Return a MemTxResult indicating whether the operation succeeded
2595 * or failed (eg unassigned memory, device rejected the transaction,
2596 * IOMMU fault).
2597 *
2598 * @as: #AddressSpace to be accessed
2599 * @addr: address within that address space
2600 * @attrs: memory transaction attributes
2601 * @buf: buffer with the data transferred
2602 * @len: the number of bytes to write
2603 */
2604MemTxResult address_space_write_rom(AddressSpace *as, hwaddr addr,
2605 MemTxAttrs attrs,
Philippe Mathieu-Daudédaa3dda2020-02-19 19:54:35 +01002606 const void *buf, hwaddr len);
Peter Maydell3c8133f2018-12-14 13:30:48 +00002607
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002608/* address_space_ld*: load from an address space
Peter Maydell50013112015-04-26 16:49:24 +01002609 * address_space_st*: store to an address space
2610 *
2611 * These functions perform a load or store of the byte, word,
2612 * longword or quad to the specified address within the AddressSpace.
2613 * The _le suffixed functions treat the data as little endian;
2614 * _be indicates big endian; no suffix indicates "same endianness
2615 * as guest CPU".
2616 *
2617 * The "guest CPU endianness" accessors are deprecated for use outside
2618 * target-* code; devices should be CPU-agnostic and use either the LE
2619 * or the BE accessors.
2620 *
2621 * @as #AddressSpace to be accessed
2622 * @addr: address within that address space
2623 * @val: data value, for stores
2624 * @attrs: memory transaction attributes
2625 * @result: location to write the success/failure of the transaction;
2626 * if NULL, this information is discarded
2627 */
Peter Maydell50013112015-04-26 16:49:24 +01002628
Paolo Bonzini4269c822018-03-04 23:31:47 +01002629#define SUFFIX
2630#define ARG1 as
2631#define ARG1_DECL AddressSpace *as
Paolo Bonzini0979ed02020-02-04 12:41:01 +01002632#include "exec/memory_ldst.h.inc"
Paolo Bonzini4269c822018-03-04 23:31:47 +01002633
2634#define SUFFIX
2635#define ARG1 as
2636#define ARG1_DECL AddressSpace *as
Paolo Bonzini0979ed02020-02-04 12:41:01 +01002637#include "exec/memory_ldst_phys.h.inc"
Paolo Bonzini0ce265f2016-11-22 11:34:02 +01002638
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002639struct MemoryRegionCache {
Paolo Bonzini48564042018-03-18 18:26:36 +01002640 void *ptr;
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002641 hwaddr xlat;
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002642 hwaddr len;
Paolo Bonzini48564042018-03-18 18:26:36 +01002643 FlatView *fv;
2644 MemoryRegionSection mrs;
2645 bool is_write;
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002646};
2647
Paolo Bonzini48564042018-03-18 18:26:36 +01002648#define MEMORY_REGION_CACHE_INVALID ((MemoryRegionCache) { .mrs.mr = NULL })
2649
Paolo Bonzini5eba0402017-01-27 16:40:16 +01002650
Paolo Bonzini4269c822018-03-04 23:31:47 +01002651/* address_space_ld*_cached: load from a cached #MemoryRegion
2652 * address_space_st*_cached: store into a cached #MemoryRegion
2653 *
2654 * These functions perform a load or store of the byte, word,
2655 * longword or quad to the specified address. The address is
2656 * a physical address in the AddressSpace, but it must lie within
2657 * a #MemoryRegion that was mapped with address_space_cache_init.
2658 *
2659 * The _le suffixed functions treat the data as little endian;
2660 * _be indicates big endian; no suffix indicates "same endianness
2661 * as guest CPU".
2662 *
2663 * The "guest CPU endianness" accessors are deprecated for use outside
2664 * target-* code; devices should be CPU-agnostic and use either the LE
2665 * or the BE accessors.
2666 *
2667 * @cache: previously initialized #MemoryRegionCache to be accessed
2668 * @addr: address within the address space
2669 * @val: data value, for stores
2670 * @attrs: memory transaction attributes
2671 * @result: location to write the success/failure of the transaction;
2672 * if NULL, this information is discarded
2673 */
2674
Paolo Bonzini48564042018-03-18 18:26:36 +01002675#define SUFFIX _cached_slow
Paolo Bonzini4269c822018-03-04 23:31:47 +01002676#define ARG1 cache
2677#define ARG1_DECL MemoryRegionCache *cache
Paolo Bonzini0979ed02020-02-04 12:41:01 +01002678#include "exec/memory_ldst.h.inc"
Paolo Bonzini4269c822018-03-04 23:31:47 +01002679
Paolo Bonzini48564042018-03-18 18:26:36 +01002680/* Inline fast path for direct RAM access. */
2681static inline uint8_t address_space_ldub_cached(MemoryRegionCache *cache,
2682 hwaddr addr, MemTxAttrs attrs, MemTxResult *result)
2683{
2684 assert(addr < cache->len);
2685 if (likely(cache->ptr)) {
2686 return ldub_p(cache->ptr + addr);
2687 } else {
2688 return address_space_ldub_cached_slow(cache, addr, attrs, result);
2689 }
2690}
2691
2692static inline void address_space_stb_cached(MemoryRegionCache *cache,
Philippe Mathieu-Daudé4121f4b2021-05-18 20:36:36 +02002693 hwaddr addr, uint8_t val, MemTxAttrs attrs, MemTxResult *result)
Paolo Bonzini48564042018-03-18 18:26:36 +01002694{
2695 assert(addr < cache->len);
2696 if (likely(cache->ptr)) {
2697 stb_p(cache->ptr + addr, val);
2698 } else {
2699 address_space_stb_cached_slow(cache, addr, val, attrs, result);
2700 }
2701}
2702
2703#define ENDIANNESS _le
Paolo Bonzini0979ed02020-02-04 12:41:01 +01002704#include "exec/memory_ldst_cached.h.inc"
Paolo Bonzini48564042018-03-18 18:26:36 +01002705
2706#define ENDIANNESS _be
Paolo Bonzini0979ed02020-02-04 12:41:01 +01002707#include "exec/memory_ldst_cached.h.inc"
Paolo Bonzini48564042018-03-18 18:26:36 +01002708
Paolo Bonzini4269c822018-03-04 23:31:47 +01002709#define SUFFIX _cached
2710#define ARG1 cache
2711#define ARG1_DECL MemoryRegionCache *cache
Paolo Bonzini0979ed02020-02-04 12:41:01 +01002712#include "exec/memory_ldst_phys.h.inc"
Paolo Bonzini4269c822018-03-04 23:31:47 +01002713
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002714/* address_space_cache_init: prepare for repeated access to a physical
2715 * memory region
2716 *
2717 * @cache: #MemoryRegionCache to be filled
2718 * @as: #AddressSpace to be accessed
2719 * @addr: address within that address space
2720 * @len: length of buffer
2721 * @is_write: indicates the transfer direction
2722 *
2723 * Will only work with RAM, and may map a subset of the requested range by
2724 * returning a value that is less than @len. On failure, return a negative
2725 * errno value.
2726 *
2727 * Because it only works with RAM, this function can be used for
2728 * read-modify-write operations. In this case, is_write should be %true.
2729 *
2730 * Note that addresses passed to the address_space_*_cached functions
2731 * are relative to @addr.
2732 */
2733int64_t address_space_cache_init(MemoryRegionCache *cache,
2734 AddressSpace *as,
2735 hwaddr addr,
2736 hwaddr len,
2737 bool is_write);
2738
2739/**
2740 * address_space_cache_invalidate: complete a write to a #MemoryRegionCache
2741 *
2742 * @cache: The #MemoryRegionCache to operate on.
2743 * @addr: The first physical address that was written, relative to the
2744 * address that was passed to @address_space_cache_init.
2745 * @access_len: The number of bytes that were written starting at @addr.
2746 */
2747void address_space_cache_invalidate(MemoryRegionCache *cache,
2748 hwaddr addr,
2749 hwaddr access_len);
2750
2751/**
2752 * address_space_cache_destroy: free a #MemoryRegionCache
2753 *
2754 * @cache: The #MemoryRegionCache whose memory should be released.
2755 */
2756void address_space_cache_destroy(MemoryRegionCache *cache);
2757
Jason Wang052c8fa2016-12-30 18:09:13 +08002758/* address_space_get_iotlb_entry: translate an address into an IOTLB
2759 * entry. Should be called from an RCU critical section.
2760 */
2761IOMMUTLBEntry address_space_get_iotlb_entry(AddressSpace *as, hwaddr addr,
Peter Maydell7446eb02018-05-31 14:50:53 +01002762 bool is_write, MemTxAttrs attrs);
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002763
Paolo Bonzini149f54b2013-05-24 12:59:37 +02002764/* address_space_translate: translate an address range into an address space
Paolo Bonzini41063e12015-03-18 14:21:43 +01002765 * into a MemoryRegion and an address range into that section. Should be
2766 * called from an RCU critical section, to avoid that the last reference
2767 * to the returned region disappears after address_space_translate returns.
Paolo Bonzini149f54b2013-05-24 12:59:37 +02002768 *
Jay Zhou57914ec2018-01-04 13:29:48 +08002769 * @fv: #FlatView to be accessed
Paolo Bonzini149f54b2013-05-24 12:59:37 +02002770 * @addr: address within that address space
2771 * @xlat: pointer to address within the returned memory region section's
2772 * #MemoryRegion.
2773 * @len: pointer to length
2774 * @is_write: indicates the transfer direction
Peter Maydellbc6b1ce2018-05-31 14:50:52 +01002775 * @attrs: memory attributes
Paolo Bonzini149f54b2013-05-24 12:59:37 +02002776 */
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10002777MemoryRegion *flatview_translate(FlatView *fv,
2778 hwaddr addr, hwaddr *xlat,
Peter Maydellefa99a22018-05-31 14:50:52 +01002779 hwaddr *len, bool is_write,
2780 MemTxAttrs attrs);
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10002781
2782static inline MemoryRegion *address_space_translate(AddressSpace *as,
2783 hwaddr addr, hwaddr *xlat,
Peter Maydellbc6b1ce2018-05-31 14:50:52 +01002784 hwaddr *len, bool is_write,
2785 MemTxAttrs attrs)
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10002786{
2787 return flatview_translate(address_space_to_flatview(as),
Peter Maydellefa99a22018-05-31 14:50:52 +01002788 addr, xlat, len, is_write, attrs);
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10002789}
Paolo Bonzini149f54b2013-05-24 12:59:37 +02002790
Paolo Bonzini51644ab2013-04-11 15:40:59 +02002791/* address_space_access_valid: check for validity of accessing an address
2792 * space range
2793 *
Avi Kivity30951152012-10-30 13:47:46 +02002794 * Check whether memory is assigned to the given address space range, and
2795 * access is permitted by any IOMMU regions that are active for the address
2796 * space.
Paolo Bonzini51644ab2013-04-11 15:40:59 +02002797 *
2798 * For now, addr and len should be aligned to a page size. This limitation
2799 * will be lifted in the future.
2800 *
2801 * @as: #AddressSpace to be accessed
2802 * @addr: address within that address space
2803 * @len: length of the area to be checked
2804 * @is_write: indicates the transfer direction
Peter Maydellfddffa42018-05-31 14:50:52 +01002805 * @attrs: memory attributes
Paolo Bonzini51644ab2013-04-11 15:40:59 +02002806 */
Li Zhijian0c249ff2019-01-17 20:49:01 +08002807bool address_space_access_valid(AddressSpace *as, hwaddr addr, hwaddr len,
Peter Maydellfddffa42018-05-31 14:50:52 +01002808 bool is_write, MemTxAttrs attrs);
Paolo Bonzini51644ab2013-04-11 15:40:59 +02002809
Avi Kivityac1970f2012-10-03 16:22:53 +02002810/* address_space_map: map a physical memory region into a host virtual address
2811 *
2812 * May map a subset of the requested range, given by and returned in @plen.
Prasad J Pandit77f55ea2020-05-26 16:47:43 +05302813 * May return %NULL and set *@plen to zero(0), if resources needed to perform
2814 * the mapping are exhausted.
Avi Kivityac1970f2012-10-03 16:22:53 +02002815 * Use only for reads OR writes - not for read-modify-write operations.
2816 * Use cpu_register_map_client() to know when retrying the map operation is
2817 * likely to succeed.
2818 *
2819 * @as: #AddressSpace to be accessed
2820 * @addr: address within that address space
2821 * @plen: pointer to length of buffer; updated on return
2822 * @is_write: indicates the transfer direction
Peter Maydellf26404f2018-05-31 14:50:52 +01002823 * @attrs: memory attributes
Avi Kivityac1970f2012-10-03 16:22:53 +02002824 */
Avi Kivitya8170e52012-10-23 12:30:10 +02002825void *address_space_map(AddressSpace *as, hwaddr addr,
Peter Maydellf26404f2018-05-31 14:50:52 +01002826 hwaddr *plen, bool is_write, MemTxAttrs attrs);
Avi Kivityac1970f2012-10-03 16:22:53 +02002827
2828/* address_space_unmap: Unmaps a memory region previously mapped by address_space_map()
2829 *
2830 * Will also mark the memory as dirty if @is_write == %true. @access_len gives
2831 * the amount of memory that was actually read or written by the caller.
2832 *
2833 * @as: #AddressSpace used
Jay Zhou57914ec2018-01-04 13:29:48 +08002834 * @buffer: host pointer as returned by address_space_map()
Avi Kivityac1970f2012-10-03 16:22:53 +02002835 * @len: buffer length as returned by address_space_map()
2836 * @access_len: amount of data actually transferred
2837 * @is_write: indicates the transfer direction
2838 */
Avi Kivitya8170e52012-10-23 12:30:10 +02002839void address_space_unmap(AddressSpace *as, void *buffer, hwaddr len,
Philippe Mathieu-Daudéae5883a2020-02-19 20:12:01 +01002840 bool is_write, hwaddr access_len);
Avi Kivityac1970f2012-10-03 16:22:53 +02002841
2842
Paolo Bonzinia203ac72015-12-09 10:18:57 +01002843/* Internal functions, part of the implementation of address_space_read. */
Paolo Bonzinib2a44fc2018-03-05 00:19:49 +01002844MemTxResult address_space_read_full(AddressSpace *as, hwaddr addr,
Philippe Mathieu-Daudédaa3dda2020-02-19 19:54:35 +01002845 MemTxAttrs attrs, void *buf, hwaddr len);
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10002846MemTxResult flatview_read_continue(FlatView *fv, hwaddr addr,
Philippe Mathieu-Daudéa152be42020-02-19 19:52:44 +01002847 MemTxAttrs attrs, void *buf,
Li Zhijian0c249ff2019-01-17 20:49:01 +08002848 hwaddr len, hwaddr addr1, hwaddr l,
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10002849 MemoryRegion *mr);
Paolo Bonzini0878d0e2016-02-22 11:02:12 +01002850void *qemu_map_ram_ptr(RAMBlock *ram_block, ram_addr_t addr);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002851
Paolo Bonzini48564042018-03-18 18:26:36 +01002852/* Internal functions, part of the implementation of address_space_read_cached
2853 * and address_space_write_cached. */
Philippe Mathieu-Daudé38df19f2020-05-18 17:53:02 +02002854MemTxResult address_space_read_cached_slow(MemoryRegionCache *cache,
2855 hwaddr addr, void *buf, hwaddr len);
2856MemTxResult address_space_write_cached_slow(MemoryRegionCache *cache,
2857 hwaddr addr, const void *buf,
2858 hwaddr len);
Paolo Bonzini48564042018-03-18 18:26:36 +01002859
Jagannathan Raman3123f932022-06-13 16:26:32 -04002860int memory_access_size(MemoryRegion *mr, unsigned l, hwaddr addr);
2861bool prepare_mmio_access(MemoryRegion *mr);
2862
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002863static inline bool memory_access_is_direct(MemoryRegion *mr, bool is_write)
2864{
2865 if (is_write) {
Alexander Duyckd489ae42020-04-09 20:41:50 -07002866 return memory_region_is_ram(mr) && !mr->readonly &&
2867 !mr->rom_device && !memory_region_is_ram_device(mr);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002868 } else {
Alex Williamson4a2e2422016-10-31 09:53:03 -06002869 return (memory_region_is_ram(mr) && !memory_region_is_ram_device(mr)) ||
2870 memory_region_is_romd(mr);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002871 }
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002872}
2873
2874/**
2875 * address_space_read: read from an address space.
2876 *
2877 * Return a MemTxResult indicating whether the operation succeeded
2878 * or failed (eg unassigned memory, device rejected the transaction,
Paolo Bonzinib2a44fc2018-03-05 00:19:49 +01002879 * IOMMU fault). Called within RCU critical section.
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002880 *
Paolo Bonzinib2a44fc2018-03-05 00:19:49 +01002881 * @as: #AddressSpace to be accessed
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002882 * @addr: address within that address space
2883 * @attrs: memory transaction attributes
2884 * @buf: buffer with the data transferred
Paolo Bonzini5d248212019-10-29 17:22:48 +01002885 * @len: length of the data transferred
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002886 */
2887static inline __attribute__((__always_inline__))
Paolo Bonzinib2a44fc2018-03-05 00:19:49 +01002888MemTxResult address_space_read(AddressSpace *as, hwaddr addr,
Philippe Mathieu-Daudédaa3dda2020-02-19 19:54:35 +01002889 MemTxAttrs attrs, void *buf,
Li Zhijian0c249ff2019-01-17 20:49:01 +08002890 hwaddr len)
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002891{
2892 MemTxResult result = MEMTX_OK;
2893 hwaddr l, addr1;
2894 void *ptr;
2895 MemoryRegion *mr;
Paolo Bonzinib2a44fc2018-03-05 00:19:49 +01002896 FlatView *fv;
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002897
2898 if (__builtin_constant_p(len)) {
2899 if (len) {
Paolo Bonzini293a7332019-12-13 15:06:45 +01002900 RCU_READ_LOCK_GUARD();
Paolo Bonzinib2a44fc2018-03-05 00:19:49 +01002901 fv = address_space_to_flatview(as);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002902 l = len;
Peter Maydellefa99a22018-05-31 14:50:52 +01002903 mr = flatview_translate(fv, addr, &addr1, &l, false, attrs);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002904 if (len == l && memory_access_is_direct(mr, false)) {
Paolo Bonzini0878d0e2016-02-22 11:02:12 +01002905 ptr = qemu_map_ram_ptr(mr->ram_block, addr1);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002906 memcpy(buf, ptr, len);
2907 } else {
Alexey Kardashevskiy16620682017-09-21 18:50:58 +10002908 result = flatview_read_continue(fv, addr, attrs, buf, len,
2909 addr1, l, mr);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002910 }
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002911 }
2912 } else {
Paolo Bonzinib2a44fc2018-03-05 00:19:49 +01002913 result = address_space_read_full(as, addr, attrs, buf, len);
Paolo Bonzini3cc8f882015-12-09 10:34:13 +01002914 }
2915 return result;
2916}
Paolo Bonzinia203ac72015-12-09 10:18:57 +01002917
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002918/**
2919 * address_space_read_cached: read from a cached RAM region
2920 *
2921 * @cache: Cached region to be addressed
2922 * @addr: address relative to the base of the RAM region
2923 * @buf: buffer with the data transferred
2924 * @len: length of the data transferred
2925 */
Philippe Mathieu-Daudé38df19f2020-05-18 17:53:02 +02002926static inline MemTxResult
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002927address_space_read_cached(MemoryRegionCache *cache, hwaddr addr,
Li Zhijian0c249ff2019-01-17 20:49:01 +08002928 void *buf, hwaddr len)
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002929{
2930 assert(addr < cache->len && len <= cache->len - addr);
Alexander Bulekovfc1c8342021-01-20 01:02:55 -05002931 fuzz_dma_read_cb(cache->xlat + addr, len, cache->mrs.mr);
Paolo Bonzini48564042018-03-18 18:26:36 +01002932 if (likely(cache->ptr)) {
2933 memcpy(buf, cache->ptr + addr, len);
Philippe Mathieu-Daudé38df19f2020-05-18 17:53:02 +02002934 return MEMTX_OK;
Paolo Bonzini48564042018-03-18 18:26:36 +01002935 } else {
Philippe Mathieu-Daudé38df19f2020-05-18 17:53:02 +02002936 return address_space_read_cached_slow(cache, addr, buf, len);
Paolo Bonzini48564042018-03-18 18:26:36 +01002937 }
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002938}
2939
2940/**
2941 * address_space_write_cached: write to a cached RAM region
2942 *
2943 * @cache: Cached region to be addressed
2944 * @addr: address relative to the base of the RAM region
2945 * @buf: buffer with the data transferred
2946 * @len: length of the data transferred
2947 */
Philippe Mathieu-Daudé38df19f2020-05-18 17:53:02 +02002948static inline MemTxResult
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002949address_space_write_cached(MemoryRegionCache *cache, hwaddr addr,
Philippe Mathieu-Daudédaa3dda2020-02-19 19:54:35 +01002950 const void *buf, hwaddr len)
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002951{
2952 assert(addr < cache->len && len <= cache->len - addr);
Paolo Bonzini48564042018-03-18 18:26:36 +01002953 if (likely(cache->ptr)) {
2954 memcpy(cache->ptr + addr, buf, len);
Philippe Mathieu-Daudé38df19f2020-05-18 17:53:02 +02002955 return MEMTX_OK;
Paolo Bonzini48564042018-03-18 18:26:36 +01002956 } else {
Philippe Mathieu-Daudé38df19f2020-05-18 17:53:02 +02002957 return address_space_write_cached_slow(cache, addr, buf, len);
Paolo Bonzini48564042018-03-18 18:26:36 +01002958 }
Paolo Bonzini1f4e4962016-11-22 12:04:52 +01002959}
2960
Philippe Mathieu-Daudé75f01c62022-01-15 21:37:23 +01002961/**
2962 * address_space_set: Fill address space with a constant byte.
2963 *
2964 * Return a MemTxResult indicating whether the operation succeeded
2965 * or failed (eg unassigned memory, device rejected the transaction,
2966 * IOMMU fault).
2967 *
2968 * @as: #AddressSpace to be accessed
2969 * @addr: address within that address space
2970 * @c: constant byte to fill the memory
2971 * @len: the number of bytes to fill with the constant byte
2972 * @attrs: memory transaction attributes
2973 */
2974MemTxResult address_space_set(AddressSpace *as, hwaddr addr,
2975 uint8_t c, hwaddr len, MemTxAttrs attrs);
2976
Paolo Bonzini7a3df112019-09-12 16:02:42 +02002977#ifdef NEED_CPU_H
Tony Nguyend5d680c2019-08-24 04:36:52 +10002978/* enum device_endian to MemOp. */
Paolo Bonzini7a3df112019-09-12 16:02:42 +02002979static inline MemOp devend_memop(enum device_endian end)
2980{
2981 QEMU_BUILD_BUG_ON(DEVICE_HOST_ENDIAN != DEVICE_LITTLE_ENDIAN &&
2982 DEVICE_HOST_ENDIAN != DEVICE_BIG_ENDIAN);
2983
Marc-André Lureauee3eb3a2022-03-23 19:57:18 +04002984#if HOST_BIG_ENDIAN != TARGET_BIG_ENDIAN
Paolo Bonzini7a3df112019-09-12 16:02:42 +02002985 /* Swap if non-host endianness or native (target) endianness */
2986 return (end == DEVICE_HOST_ENDIAN) ? 0 : MO_BSWAP;
2987#else
2988 const int non_host_endianness =
2989 DEVICE_LITTLE_ENDIAN ^ DEVICE_BIG_ENDIAN ^ DEVICE_HOST_ENDIAN;
2990
2991 /* In this case, native (target) endianness needs no swap. */
2992 return (end == non_host_endianness) ? MO_BSWAP : 0;
2993#endif
2994}
2995#endif
Tony Nguyend5d680c2019-08-24 04:36:52 +10002996
David Hildenbrandd24f31d2020-06-26 09:22:29 +02002997/*
2998 * Inhibit technologies that require discarding of pages in RAM blocks, e.g.,
2999 * to manage the actual amount of memory consumed by the VM (then, the memory
3000 * provided by RAM blocks might be bigger than the desired memory consumption).
3001 * This *must* be set if:
3002 * - Discarding parts of a RAM blocks does not result in the change being
3003 * reflected in the VM and the pages getting freed.
3004 * - All memory in RAM blocks is pinned or duplicated, invaldiating any previous
3005 * discards blindly.
3006 * - Discarding parts of a RAM blocks will result in integrity issues (e.g.,
3007 * encrypted VMs).
3008 * Technologies that only temporarily pin the current working set of a
3009 * driver are fine, because we don't expect such pages to be discarded
3010 * (esp. based on guest action like balloon inflation).
3011 *
3012 * This is *not* to be used to protect from concurrent discards (esp.,
3013 * postcopy).
3014 *
3015 * Returns 0 if successful. Returns -EBUSY if a technology that relies on
3016 * discards to work reliably is active.
3017 */
3018int ram_block_discard_disable(bool state);
3019
3020/*
David Hildenbrand7e6d32e2021-04-13 11:55:29 +02003021 * See ram_block_discard_disable(): only disable uncoordinated discards,
3022 * keeping coordinated discards (via the RamDiscardManager) enabled.
3023 */
3024int ram_block_uncoordinated_discard_disable(bool state);
3025
3026/*
David Hildenbrandd24f31d2020-06-26 09:22:29 +02003027 * Inhibit technologies that disable discarding of pages in RAM blocks.
3028 *
3029 * Returns 0 if successful. Returns -EBUSY if discards are already set to
3030 * broken.
3031 */
3032int ram_block_discard_require(bool state);
3033
3034/*
David Hildenbrand7e6d32e2021-04-13 11:55:29 +02003035 * See ram_block_discard_require(): only inhibit technologies that disable
3036 * uncoordinated discarding of pages in RAM blocks, allowing co-existance with
3037 * technologies that only inhibit uncoordinated discards (via the
3038 * RamDiscardManager).
3039 */
3040int ram_block_coordinated_discard_require(bool state);
3041
3042/*
3043 * Test if any discarding of memory in ram blocks is disabled.
David Hildenbrandd24f31d2020-06-26 09:22:29 +02003044 */
3045bool ram_block_discard_is_disabled(void);
3046
3047/*
David Hildenbrand7e6d32e2021-04-13 11:55:29 +02003048 * Test if any discarding of memory in ram blocks is required to work reliably.
David Hildenbrandd24f31d2020-06-26 09:22:29 +02003049 */
3050bool ram_block_discard_is_required(void);
3051
Avi Kivity093bc2c2011-07-26 14:26:01 +03003052#endif
3053
3054#endif