memory.h · samitouri/QOSamiQemu · siGit Code & Deploy

Code Commits Issues Pulls Sessions CI/CD

master

h 2,865 lines 104 KB

Raw

1	/*
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 SYSTEM_MEMORY_H
15	#define SYSTEM_MEMORY_H
16
17	#include "exec/hwaddr.h"
18	#include "system/ram_addr.h"
19	#include "system/ram-discard-manager.h"
20	#include "exec/memattrs.h"
21	#include "exec/memop.h"
22	#include "qemu/bswap.h"
23	#include "qemu/queue.h"
24	#include "qemu/int128.h"
25	#include "qemu/range.h"
26	#include "qemu/notify.h"
27	#include "qom/object.h"
28	#include "qemu/rcu.h"
29
30	enum device_endian {
31	#ifndef TARGET_NOT_USING_LEGACY_NATIVE_ENDIAN_API
32	DEVICE_NATIVE_ENDIAN = 0,
33	#endif
34	DEVICE_BIG_ENDIAN = 1,
35	DEVICE_LITTLE_ENDIAN = 2,
36	};
37
38	#define RAM_ADDR_INVALID (~(ram_addr_t)0)
39
40	#define TYPE_MEMORY_REGION "memory-region"
41	DECLARE_INSTANCE_CHECKER(MemoryRegion, MEMORY_REGION,
42	TYPE_MEMORY_REGION)
43
44	#define TYPE_IOMMU_MEMORY_REGION "iommu-memory-region"
45	typedef struct IOMMUMemoryRegionClass IOMMUMemoryRegionClass;
46	DECLARE_OBJ_CHECKERS(IOMMUMemoryRegion, IOMMUMemoryRegionClass,
47	IOMMU_MEMORY_REGION, TYPE_IOMMU_MEMORY_REGION)
48
49	#ifdef CONFIG_FUZZ
50	void fuzz_dma_read_cb(size_t addr,
51	size_t len,
52	MemoryRegion *mr);
53	#else
54	static inline void fuzz_dma_read_cb(size_t addr,
55	size_t len,
56	MemoryRegion *mr)
57	{
58	/* Do Nothing */
59	}
60	#endif
61
62	/* Possible bits for global_dirty_log_{start\|stop} */
63
64	/* Dirty tracking enabled because migration is running */
65	#define GLOBAL_DIRTY_MIGRATION (1U << 0)
66
67	/* Dirty tracking enabled because measuring dirty rate */
68	#define GLOBAL_DIRTY_DIRTY_RATE (1U << 1)
69
70	/* Dirty tracking enabled because dirty limit */
71	#define GLOBAL_DIRTY_LIMIT (1U << 2)
72
73	#define GLOBAL_DIRTY_MASK (0x7)
74
75	extern unsigned int global_dirty_tracking;
76
77	typedef struct MemoryRegionOps MemoryRegionOps;
78
79	struct ReservedRegion {
80	Range range;
81	unsigned type;
82	};
83
84	/**
85	* struct MemoryRegionSection: describes a fragment of a #MemoryRegion
86	*
87	* @mr: the region, or %NULL if empty
88	* @fv: the flat view of the address space the region is mapped in
89	* @offset_within_region: the beginning of the section, relative to @mr's start
90	* @size: the size of the section; will not exceed @mr's boundaries
91	* @offset_within_address_space: the address of the first byte of the section
92	* relative to the region's address space
93	* @readonly: writes to this section are ignored
94	* @nonvolatile: this section is non-volatile
95	* @unmergeable: this section should not get merged with adjacent sections
96	*/
97	struct MemoryRegionSection {
98	Int128 size;
99	MemoryRegion *mr;
100	FlatView *fv;
101	hwaddr offset_within_region;
102	hwaddr offset_within_address_space;
103	bool readonly;
104	bool nonvolatile;
105	bool unmergeable;
106	};
107
108	typedef struct IOMMUTLBEntry IOMMUTLBEntry;
109
110	/*
111	* See address_space_translate:
112	* - bit 0 : read
113	* - bit 1 : write
114	* - bit 2 : exec
115	* - bit 3 : priv
116	* - bit 4 : global
117	* - bit 5 : untranslated only
118	*/
119	typedef enum {
120	IOMMU_NONE = 0,
121	IOMMU_RO = 1,
122	IOMMU_WO = 2,
123	IOMMU_RW = 3,
124	IOMMU_EXEC = 4,
125	IOMMU_PRIV = 8,
126	IOMMU_GLOBAL = 16,
127	IOMMU_UNTRANSLATED_ONLY = 32,
128	} IOMMUAccessFlags;
129
130	#define IOMMU_ACCESS_FLAG(r, w) (((r) ? IOMMU_RO : 0) \| \
131	((w) ? IOMMU_WO : 0))
132	#define IOMMU_ACCESS_FLAG_FULL(r, w, x, p, g, uo) \
133	(IOMMU_ACCESS_FLAG(r, w) \| \
134	((x) ? IOMMU_EXEC : 0) \| \
135	((p) ? IOMMU_PRIV : 0) \| \
136	((g) ? IOMMU_GLOBAL : 0) \| \
137	((uo) ? IOMMU_UNTRANSLATED_ONLY : 0))
138
139	struct IOMMUTLBEntry {
140	AddressSpace *target_as;
141	hwaddr iova;
142	hwaddr translated_addr;
143	hwaddr addr_mask; /* 0xfff = 4k translation */
144	IOMMUAccessFlags perm;
145	uint32_t pasid; /* PCI pasid */
146	};
147
148	/*
149	* Bitmap for different IOMMUNotifier capabilities. Each notifier can
150	* register with one or multiple IOMMU Notifier capability bit(s).
151	*
152	* Normally there're two use cases for the notifiers:
153	*
154	* (1) When the device needs accurate synchronizations of the vIOMMU page
155	* tables, it needs to register with both MAP\|UNMAP notifies (which
156	* is defined as IOMMU_NOTIFIER_IOTLB_EVENTS below).
157	*
158	* Regarding to accurate synchronization, it's when the notified
159	* device maintains a shadow page table and must be notified on each
160	* guest MAP (page table entry creation) and UNMAP (invalidation)
161	* events (e.g. VFIO). Both notifications must be accurate so that
162	* the shadow page table is fully in sync with the guest view.
163	*
164	* (2) When the device doesn't need accurate synchronizations of the
165	* vIOMMU page tables, it needs to register only with UNMAP or
166	* DEVIOTLB_UNMAP notifies.
167	*
168	* It's when the device maintains a cache of IOMMU translations
169	* (IOTLB) and is able to fill that cache by requesting translations
170	* from the vIOMMU through a protocol similar to ATS (Address
171	* Translation Service).
172	*
173	* Note that in this mode the vIOMMU will not maintain a shadowed
174	* page table for the address space, and the UNMAP messages can cover
175	* more than the pages that used to get mapped. The IOMMU notifiee
176	* should be able to take care of over-sized invalidations.
177	*/
178	typedef enum {
179	IOMMU_NOTIFIER_NONE = 0,
180	/* Notify cache invalidations */
181	IOMMU_NOTIFIER_UNMAP = 0x1,
182	/* Notify entry changes (newly created entries) */
183	IOMMU_NOTIFIER_MAP = 0x2,
184	/* Notify changes on device IOTLB entries */
185	IOMMU_NOTIFIER_DEVIOTLB_UNMAP = 0x04,
186	} IOMMUNotifierFlag;
187
188	#define IOMMU_NOTIFIER_IOTLB_EVENTS (IOMMU_NOTIFIER_MAP \| IOMMU_NOTIFIER_UNMAP)
189	#define IOMMU_NOTIFIER_DEVIOTLB_EVENTS IOMMU_NOTIFIER_DEVIOTLB_UNMAP
190	#define IOMMU_NOTIFIER_ALL (IOMMU_NOTIFIER_IOTLB_EVENTS \| \
191	IOMMU_NOTIFIER_DEVIOTLB_EVENTS)
192
193	struct IOMMUNotifier;
194	typedef void (IOMMUNotify)(struct IOMMUNotifier notifier,
195	IOMMUTLBEntry *data);
196
197	struct IOMMUNotifier {
198	IOMMUNotify notify;
199	IOMMUNotifierFlag notifier_flags;
200	/* Notify for address space range start <= addr <= end */
201	hwaddr start;
202	hwaddr end;
203	int iommu_idx;
204	void *opaque;
205	QLIST_ENTRY(IOMMUNotifier) node;
206	};
207	typedef struct IOMMUNotifier IOMMUNotifier;
208
209	typedef struct IOMMUTLBEvent {
210	IOMMUNotifierFlag type;
211	IOMMUTLBEntry entry;
212	} IOMMUTLBEvent;
213
214	/* RAM is pre-allocated and passed into qemu_ram_alloc_from_ptr */
215	#define RAM_PREALLOC (1 << 0)
216
217	/* RAM is mmap-ed with MAP_SHARED */
218	#define RAM_SHARED (1 << 1)
219
220	/* Only a portion of RAM (used_length) is actually used, and migrated.
221	* Resizing RAM while migrating can result in the migration being canceled.
222	*/
223	#define RAM_RESIZEABLE (1 << 2)
224
225	/* UFFDIO_ZEROPAGE is available on this RAMBlock to atomically
226	* zero the page and wake waiting processes.
227	* (Set during postcopy)
228	*/
229	#define RAM_UF_ZEROPAGE (1 << 3)
230
231	/* RAM can be migrated */
232	#define RAM_MIGRATABLE (1 << 4)
233
234	/* RAM is a persistent kind memory */
235	#define RAM_PMEM (1 << 5)
236
237
238	/*
239	* UFFDIO_WRITEPROTECT is used on this RAMBlock to
240	* support 'write-tracking' migration type.
241	* Implies ram_state->ram_wt_enabled.
242	*/
243	#define RAM_UF_WRITEPROTECT (1 << 6)
244
245	/*
246	* RAM is mmap-ed with MAP_NORESERVE. When set, reserving swap space (or huge
247	* pages if applicable) is skipped: will bail out if not supported. When not
248	* set, the OS will do the reservation, if supported for the memory type.
249	*/
250	#define RAM_NORESERVE (1 << 7)
251
252	/* RAM that isn't accessible through normal means. */
253	#define RAM_PROTECTED (1 << 8)
254
255	/* RAM is an mmap-ed named file */
256	#define RAM_NAMED_FILE (1 << 9)
257
258	/* RAM is mmap-ed read-only */
259	#define RAM_READONLY (1 << 10)
260
261	/* RAM FD is opened read-only */
262	#define RAM_READONLY_FD (1 << 11)
263
264	/* RAM can be private that has kvm guest memfd backend */
265	#define RAM_GUEST_MEMFD (1 << 12)
266
267	/*
268	* In RAMBlock creation functions, if MAP_SHARED is 0 in the flags parameter,
269	* the implementation may still create a shared mapping if other conditions
270	* require it. Callers who specifically want a private mapping, eg objects
271	* specified by the user, must pass RAM_PRIVATE.
272	* After RAMBlock creation, MAP_SHARED in the block's flags indicates whether
273	* the block is shared or private, and MAP_PRIVATE is omitted.
274	*/
275	#define RAM_PRIVATE (1 << 13)
276
277	static inline void iommu_notifier_init(IOMMUNotifier *n, IOMMUNotify fn,
278	IOMMUNotifierFlag flags,
279	hwaddr start, hwaddr end,
280	int iommu_idx)
281	{
282	n->notify = fn;
283	n->notifier_flags = flags;
284	n->start = start;
285	n->end = end;
286	n->iommu_idx = iommu_idx;
287	}
288
289	/*
290	* Memory region callbacks
291	*/
292	struct MemoryRegionOps {
293	/* Read from the memory region. @addr is relative to @mr; @size is
294	* in bytes. */
295	uint64_t (read)(void opaque,
296	hwaddr addr,
297	unsigned size);
298	/* Write to the memory region. @addr is relative to @mr; @size is
299	* in bytes. */
300	void (write)(void opaque,
301	hwaddr addr,
302	uint64_t data,
303	unsigned size);
304
305	MemTxResult (read_with_attrs)(void opaque,
306	hwaddr addr,
307	uint64_t *data,
308	unsigned size,
309	MemTxAttrs attrs);
310	MemTxResult (write_with_attrs)(void opaque,
311	hwaddr addr,
312	uint64_t data,
313	unsigned size,
314	MemTxAttrs attrs);
315
316	enum device_endian endianness;
317	/* Guest-visible constraints: */
318	struct {
319	/* If nonzero, specify bounds on access sizes beyond which a machine
320	* check is thrown.
321	*/
322	unsigned min_access_size;
323	unsigned max_access_size;
324	/* If true, unaligned accesses are supported. Otherwise unaligned
325	* accesses throw machine checks.
326	*/
327	bool unaligned;
328	/*
329	* If present, and returns #false, the transaction is not accepted
330	* by the device (and results in machine dependent behaviour such
331	* as a machine check exception).
332	*/
333	bool (accepts)(void opaque, hwaddr addr,
334	unsigned size, bool is_write,
335	MemTxAttrs attrs);
336	} valid;
337	/* Internal implementation constraints: */
338	struct {
339	/* If nonzero, specifies the minimum size implemented. Smaller sizes
340	* will be rounded upwards and a partial result will be returned.
341	*/
342	unsigned min_access_size;
343	/* If nonzero, specifies the maximum size implemented. Larger sizes
344	* will be done as a series of accesses with smaller sizes.
345	*/
346	unsigned max_access_size;
347	/* If true, unaligned accesses are supported. Otherwise all accesses
348	* are converted to (possibly multiple) naturally aligned accesses.
349	*/
350	bool unaligned;
351	} impl;
352	};
353
354	typedef struct MemoryRegionClass {
355	/* private */
356	ObjectClass parent_class;
357	} MemoryRegionClass;
358
359
360	enum IOMMUMemoryRegionAttr {
361	IOMMU_ATTR_SPAPR_TCE_FD
362	};
363
364	/*
365	* IOMMUMemoryRegionClass:
366	*
367	* All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION
368	* and provide an implementation of at least the @translate method here
369	* to handle requests to the memory region. Other methods are optional.
370	*
371	* The IOMMU implementation must use the IOMMU notifier infrastructure
372	* to report whenever mappings are changed, by calling
373	* memory_region_notify_iommu() (or, if necessary, by calling
374	* memory_region_notify_iommu_one() for each registered notifier).
375	*
376	* Conceptually an IOMMU provides a mapping from input address
377	* to an output TLB entry. If the IOMMU is aware of memory transaction
378	* attributes and the output TLB entry depends on the transaction
379	* attributes, we represent this using IOMMU indexes. Each index
380	* selects a particular translation table that the IOMMU has:
381	*
382	* @attrs_to_index returns the IOMMU index for a set of transaction attributes
383	*
384	* @translate takes an input address and an IOMMU index
385	*
386	* and the mapping returned can only depend on the input address and the
387	* IOMMU index.
388	*
389	* Most IOMMUs don't care about the transaction attributes and support
390	* only a single IOMMU index. A more complex IOMMU might have one index
391	* for secure transactions and one for non-secure transactions.
392	*/
393	struct IOMMUMemoryRegionClass {
394	/* private: */
395	MemoryRegionClass parent_class;
396
397	/* public: */
398	/**
399	* @translate:
400	*
401	* Return a TLB entry that contains a given address.
402	*
403	* The IOMMUAccessFlags indicated via @flag are optional and may
404	* be specified as IOMMU_NONE to indicate that the caller needs
405	* the full translation information for both reads and writes. If
406	* the access flags are specified then the IOMMU implementation
407	* may use this as an optimization, to stop doing a page table
408	* walk as soon as it knows that the requested permissions are not
409	* allowed. If IOMMU_NONE is passed then the IOMMU must do the
410	* full page table walk and report the permissions in the returned
411	* IOMMUTLBEntry. (Note that this implies that an IOMMU may not
412	* return different mappings for reads and writes.)
413	*
414	* The returned information remains valid while the caller is
415	* holding the big QEMU lock or is inside an RCU critical section;
416	* if the caller wishes to cache the mapping beyond that it must
417	* register an IOMMU notifier so it can invalidate its cached
418	* information when the IOMMU mapping changes.
419	*
420	* @iommu: the IOMMUMemoryRegion
421	*
422	* @hwaddr: address to be translated within the memory region
423	*
424	* @flag: requested access permission
425	*
426	* @iommu_idx: IOMMU index for the translation
427	*/
428	IOMMUTLBEntry (translate)(IOMMUMemoryRegion iommu, hwaddr addr,
429	IOMMUAccessFlags flag, int iommu_idx);
430	/**
431	* @get_min_page_size:
432	*
433	* Returns minimum supported page size in bytes.
434	*
435	* If this method is not provided then the minimum is assumed to
436	* be TARGET_PAGE_SIZE.
437	*
438	* @iommu: the IOMMUMemoryRegion
439	*/
440	uint64_t (get_min_page_size)(IOMMUMemoryRegion iommu);
441	/**
442	* @notify_flag_changed:
443	*
444	* Called when IOMMU Notifier flag changes (ie when the set of
445	* events which IOMMU users are requesting notification for changes).
446	* Optional method -- need not be provided if the IOMMU does not
447	* need to know exactly which events must be notified.
448	*
449	* @iommu: the IOMMUMemoryRegion
450	*
451	* @old_flags: events which previously needed to be notified
452	*
453	* @new_flags: events which now need to be notified
454	*
455	* Returns 0 on success, or a negative errno; in particular
456	* returns -EINVAL if the new flag bitmap is not supported by the
457	* IOMMU memory region. In case of failure, the error object
458	* must be created
459	*/
460	int (notify_flag_changed)(IOMMUMemoryRegion iommu,
461	IOMMUNotifierFlag old_flags,
462	IOMMUNotifierFlag new_flags,
463	Error **errp);
464	/**
465	* @replay:
466	*
467	* Called to handle memory_region_iommu_replay().
468	*
469	* The default implementation of memory_region_iommu_replay() is to
470	* call the IOMMU translate method for every page in the address space
471	* with flag == IOMMU_NONE and then call the notifier if translate
472	* returns a valid mapping. If this method is implemented then it
473	* overrides the default behaviour, and must provide the full semantics
474	* of memory_region_iommu_replay(), by calling @notifier for every
475	* translation present in the IOMMU.
476	*
477	* Optional method -- an IOMMU only needs to provide this method
478	* if the default is inefficient or produces undesirable side effects.
479	*
480	* Note: this is not related to record-and-replay functionality.
481	*/
482	void (replay)(IOMMUMemoryRegion iommu, IOMMUNotifier *notifier);
483
484	/**
485	* @get_attr:
486	*
487	* Get IOMMU misc attributes. This is an optional method that
488	* can be used to allow users of the IOMMU to get implementation-specific
489	* information. The IOMMU implements this method to handle calls
490	* by IOMMU users to memory_region_iommu_get_attr() by filling in
491	* the arbitrary data pointer for any IOMMUMemoryRegionAttr values that
492	* the IOMMU supports. If the method is unimplemented then
493	* memory_region_iommu_get_attr() will always return -EINVAL.
494	*
495	* @iommu: the IOMMUMemoryRegion
496	*
497	* @attr: attribute being queried
498	*
499	* @data: memory to fill in with the attribute data
500	*
501	* Returns 0 on success, or a negative errno; in particular
502	* returns -EINVAL for unrecognized or unimplemented attribute types.
503	*/
504	int (get_attr)(IOMMUMemoryRegion iommu, enum IOMMUMemoryRegionAttr attr,
505	void *data);
506
507	/**
508	* @attrs_to_index:
509	*
510	* Return the IOMMU index to use for a given set of transaction attributes.
511	*
512	* Optional method: if an IOMMU only supports a single IOMMU index then
513	* the default implementation of memory_region_iommu_attrs_to_index()
514	* will return 0.
515	*
516	* The indexes supported by an IOMMU must be contiguous, starting at 0.
517	*
518	* @iommu: the IOMMUMemoryRegion
519	* @attrs: memory transaction attributes
520	*/
521	int (attrs_to_index)(IOMMUMemoryRegion iommu, MemTxAttrs attrs);
522
523	/**
524	* @num_indexes:
525	*
526	* Return the number of IOMMU indexes this IOMMU supports.
527	*
528	* Optional method: if this method is not provided, then
529	* memory_region_iommu_num_indexes() will return 1, indicating that
530	* only a single IOMMU index is supported.
531	*
532	* @iommu: the IOMMUMemoryRegion
533	*/
534	int (num_indexes)(IOMMUMemoryRegion iommu);
535	};
536
537	/**
538	* memory_translate_iotlb: Extract addresses from a TLB entry.
539	* Called with rcu_read_lock held.
540	*
541	* @iotlb: pointer to an #IOMMUTLBEntry
542	* @xlat_p: return the offset of the entry from the start of the returned
543	* MemoryRegion.
544	* @errp: pointer to Error*, to store an error if it happens.
545	*
546	* Return: On success, return the MemoryRegion containing the @iotlb translated
547	* addr. The MemoryRegion must not be accessed after rcu_read_unlock.
548	* On failure, return NULL, setting @errp with error.
549	*/
550	MemoryRegion memory_translate_iotlb(IOMMUTLBEntry iotlb, hwaddr *xlat_p,
551	Error **errp);
552
553	typedef struct CoalescedMemoryRange CoalescedMemoryRange;
554	typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
555
556	/** MemoryRegion:
557	*
558	* A struct representing a memory region.
559	*/
560	struct MemoryRegion {
561	Object parent_obj;
562
563	/* private: */
564
565	/* The following fields should fit in a cache line */
566	bool romd_mode;
567	bool ram;
568	bool subpage;
569	bool readonly; /* For RAM regions */
570	bool nonvolatile;
571	bool rom_device;
572	bool flush_coalesced_mmio;
573	bool lockless_io;
574	bool unmergeable;
575	uint8_t dirty_log_mask;
576	bool is_iommu;
577	RAMBlock *ram_block;
578	Object *owner;
579	/* owner as TYPE_DEVICE. Used for re-entrancy checks in MR access hotpath */
580	DeviceState *dev;
581
582	const MemoryRegionOps *ops;
583	void *opaque;
584	MemoryRegion *container;
585	int mapped_via_alias; /* Mapped via an alias, container might be NULL */
586	Int128 size;
587	hwaddr addr;
588	void (destructor)(MemoryRegion mr);
589	uint64_t align;
590	bool terminates;
591	bool ram_device;
592	bool enabled;
593	uint8_t vga_logging_count;
594	MemoryRegion *alias;
595	hwaddr alias_offset;
596	int32_t priority;
597	QTAILQ_HEAD(, MemoryRegion) subregions;
598	QTAILQ_ENTRY(MemoryRegion) subregions_link;
599	QTAILQ_HEAD(, CoalescedMemoryRange) coalesced;
600	const char *name;
601	unsigned ioeventfd_nb;
602	MemoryRegionIoeventfd *ioeventfds;
603	RamDiscardManager rdm; / Only for RAM */
604
605	/* For devices designed to perform re-entrant IO into their own IO MRs */
606	bool disable_reentrancy_guard;
607	/* RAM device region that does not require IOMMU mapping for P2P */
608	bool ram_device_skip_iommu_map;
609	};
610
611	struct IOMMUMemoryRegion {
612	MemoryRegion parent_obj;
613
614	QLIST_HEAD(, IOMMUNotifier) iommu_notify;
615	IOMMUNotifierFlag iommu_notify_flags;
616	};
617
618	#define IOMMU_NOTIFIER_FOREACH(n, mr) \
619	QLIST_FOREACH((n), &(mr)->iommu_notify, node)
620
621	#define MEMORY_LISTENER_PRIORITY_MIN 0
622	#define MEMORY_LISTENER_PRIORITY_ACCEL 10
623	#define MEMORY_LISTENER_PRIORITY_DEV_BACKEND 10
624
625	/**
626	* struct MemoryListener: callbacks structure for updates to the physical memory map
627	*
628	* Allows a component to adjust to changes in the guest-visible memory map.
629	* Use with memory_listener_register() and memory_listener_unregister().
630	*/
631	struct MemoryListener {
632	/**
633	* @begin:
634	*
635	* Called at the beginning of an address space update transaction.
636	* Followed by calls to #MemoryListener.region_add(),
637	* #MemoryListener.region_del(), #MemoryListener.region_nop(),
638	* #MemoryListener.log_start() and #MemoryListener.log_stop() in
639	* increasing address order.
640	*
641	* @listener: The #MemoryListener.
642	*/
643	void (begin)(MemoryListener listener);
644
645	/**
646	* @commit:
647	*
648	* Called at the end of an address space update transaction,
649	* after the last call to #MemoryListener.region_add(),
650	* #MemoryListener.region_del() or #MemoryListener.region_nop(),
651	* #MemoryListener.log_start() and #MemoryListener.log_stop().
652	*
653	* @listener: The #MemoryListener.
654	*/
655	void (commit)(MemoryListener listener);
656
657	/**
658	* @region_add:
659	*
660	* Called during an address space update transaction,
661	* for a section of the address space that is new in this address space
662	* space since the last transaction.
663	*
664	* @listener: The #MemoryListener.
665	* @section: The new #MemoryRegionSection.
666	*/
667	void (region_add)(MemoryListener listener, MemoryRegionSection *section);
668
669	/**
670	* @region_del:
671	*
672	* Called during an address space update transaction,
673	* for a section of the address space that has disappeared in the address
674	* space since the last transaction.
675	*
676	* @listener: The #MemoryListener.
677	* @section: The old #MemoryRegionSection.
678	*/
679	void (region_del)(MemoryListener listener, MemoryRegionSection *section);
680
681	/**
682	* @region_nop:
683	*
684	* Called during an address space update transaction,
685	* for a section of the address space that is in the same place in the address
686	* space as in the last transaction.
687	*
688	* @listener: The #MemoryListener.
689	* @section: The #MemoryRegionSection.
690	*/
691	void (region_nop)(MemoryListener listener, MemoryRegionSection *section);
692
693	/**
694	* @log_start:
695	*
696	* Called during an address space update transaction, after
697	* one of #MemoryListener.region_add(), #MemoryListener.region_del() or
698	* #MemoryListener.region_nop(), if dirty memory logging clients have
699	* become active since the last transaction.
700	*
701	* @listener: The #MemoryListener.
702	* @section: The #MemoryRegionSection.
703	* @old: A bitmap of dirty memory logging clients that were active in
704	* the previous transaction.
705	* @new: A bitmap of dirty memory logging clients that are active in
706	* the current transaction.
707	*/
708	void (log_start)(MemoryListener listener, MemoryRegionSection *section,
709	int old_val, int new_val);
710
711	/**
712	* @log_stop:
713	*
714	* Called during an address space update transaction, after
715	* one of #MemoryListener.region_add(), #MemoryListener.region_del() or
716	* #MemoryListener.region_nop() and possibly after
717	* #MemoryListener.log_start(), if dirty memory logging clients have
718	* become inactive since the last transaction.
719	*
720	* @listener: The #MemoryListener.
721	* @section: The #MemoryRegionSection.
722	* @old: A bitmap of dirty memory logging clients that were active in
723	* the previous transaction.
724	* @new: A bitmap of dirty memory logging clients that are active in
725	* the current transaction.
726	*/
727	void (log_stop)(MemoryListener listener, MemoryRegionSection *section,
728	int old_val, int new_val);
729
730	/**
731	* @log_sync:
732	*
733	* Called by memory_region_snapshot_and_clear_dirty() and
734	* memory_global_dirty_log_sync(), before accessing QEMU's "official"
735	* copy of the dirty memory bitmap for a #MemoryRegionSection.
736	*
737	* @listener: The #MemoryListener.
738	* @section: The #MemoryRegionSection.
739	*/
740	void (log_sync)(MemoryListener listener, MemoryRegionSection *section);
741
742	/**
743	* @log_sync_global:
744	*
745	* This is the global version of @log_sync when the listener does
746	* not have a way to synchronize the log with finer granularity.
747	* When the listener registers with @log_sync_global defined, then
748	* its @log_sync must be NULL. Vice versa.
749	*
750	* @listener: The #MemoryListener.
751	* @last_stage: The last stage to synchronize the log during migration.
752	* The caller should guarantee that the synchronization with true for
753	* @last_stage is triggered for once after all VCPUs have been stopped.
754	*/
755	void (log_sync_global)(MemoryListener listener, bool last_stage);
756
757	/**
758	* @log_clear:
759	*
760	* Called before reading the dirty memory bitmap for a
761	* #MemoryRegionSection.
762	*
763	* @listener: The #MemoryListener.
764	* @section: The #MemoryRegionSection.
765	*/
766	void (log_clear)(MemoryListener listener, MemoryRegionSection *section);
767
768	/**
769	* @log_global_start:
770	*
771	* Called by memory_global_dirty_log_start(), which
772	* enables the %DIRTY_LOG_MIGRATION client on all memory regions in
773	* the address space. #MemoryListener.log_global_start() is also
774	* called when a #MemoryListener is added, if global dirty logging is
775	* active at that time.
776	*
777	* @listener: The #MemoryListener.
778	* @errp: pointer to Error*, to store an error if it happens.
779	*
780	* Return: true on success, else false setting @errp with error.
781	*/
782	bool (log_global_start)(MemoryListener listener, Error **errp);
783
784	/**
785	* @log_global_stop:
786	*
787	* Called by memory_global_dirty_log_stop(), which
788	* disables the %DIRTY_LOG_MIGRATION client on all memory regions in
789	* the address space.
790	*
791	* @listener: The #MemoryListener.
792	*/
793	void (log_global_stop)(MemoryListener listener);
794
795	/**
796	* @log_global_after_sync:
797	*
798	* Called after reading the dirty memory bitmap
799	* for any #MemoryRegionSection.
800	*
801	* @listener: The #MemoryListener.
802	*/
803	void (log_global_after_sync)(MemoryListener listener);
804
805	/**
806	* @eventfd_add:
807	*
808	* Called during an address space update transaction,
809	* for a section of the address space that has had a new ioeventfd
810	* registration since the last transaction.
811	*
812	* @listener: The #MemoryListener.
813	* @section: The new #MemoryRegionSection.
814	* @match_data: The @match_data parameter for the new ioeventfd.
815	* @data: The @data parameter for the new ioeventfd.
816	* @e: The #EventNotifier parameter for the new ioeventfd.
817	*/
818	void (eventfd_add)(MemoryListener listener, MemoryRegionSection *section,
819	bool match_data, uint64_t data, EventNotifier *e);
820
821	/**
822	* @eventfd_del:
823	*
824	* Called during an address space update transaction,
825	* for a section of the address space that has dropped an ioeventfd
826	* registration since the last transaction.
827	*
828	* @listener: The #MemoryListener.
829	* @section: The new #MemoryRegionSection.
830	* @match_data: The @match_data parameter for the dropped ioeventfd.
831	* @data: The @data parameter for the dropped ioeventfd.
832	* @e: The #EventNotifier parameter for the dropped ioeventfd.
833	*/
834	void (eventfd_del)(MemoryListener listener, MemoryRegionSection *section,
835	bool match_data, uint64_t data, EventNotifier *e);
836
837	/**
838	* @coalesced_io_add:
839	*
840	* Called during an address space update transaction,
841	* for a section of the address space that has had a new coalesced
842	* MMIO range registration since the last transaction.
843	*
844	* @listener: The #MemoryListener.
845	* @section: The new #MemoryRegionSection.
846	* @addr: The starting address for the coalesced MMIO range.
847	* @len: The length of the coalesced MMIO range.
848	*/
849	void (coalesced_io_add)(MemoryListener listener, MemoryRegionSection *section,
850	hwaddr addr, hwaddr len);
851
852	/**
853	* @coalesced_io_del:
854	*
855	* Called during an address space update transaction,
856	* for a section of the address space that has dropped a coalesced
857	* MMIO range since the last transaction.
858	*
859	* @listener: The #MemoryListener.
860	* @section: The new #MemoryRegionSection.
861	* @addr: The starting address for the coalesced MMIO range.
862	* @len: The length of the coalesced MMIO range.
863	*/
864	void (coalesced_io_del)(MemoryListener listener, MemoryRegionSection *section,
865	hwaddr addr, hwaddr len);
866	/**
867	* @priority:
868	*
869	* Govern the order in which memory listeners are invoked. Lower priorities
870	* are invoked earlier for "add" or "start" callbacks, and later for "delete"
871	* or "stop" callbacks.
872	*/
873	unsigned priority;
874
875	/**
876	* @name:
877	*
878	* Name of the listener. It can be used in contexts where we'd like to
879	* identify one memory listener with the rest.
880	*/
881	const char *name;
882
883	/* private: */
884	AddressSpace *address_space;
885	QTAILQ_ENTRY(MemoryListener) link;
886	QTAILQ_ENTRY(MemoryListener) link_as;
887	};
888
889	typedef struct AddressSpaceMapClient {
890	QEMUBH *bh;
891	QLIST_ENTRY(AddressSpaceMapClient) link;
892	} AddressSpaceMapClient;
893
894	#define DEFAULT_MAX_BOUNCE_BUFFER_SIZE (4096)
895
896	/**
897	* struct AddressSpace: describes a mapping of addresses to #MemoryRegion objects
898	*/
899	struct AddressSpace {
900	/* private: */
901	struct rcu_head rcu;
902	char *name;
903	MemoryRegion *root;
904
905	/* Accessed via RCU. */
906	struct FlatView *current_map;
907
908	int ioeventfd_nb;
909	int ioeventfd_notifiers;
910	struct MemoryRegionIoeventfd *ioeventfds;
911	QTAILQ_HEAD(, MemoryListener) listeners;
912	QTAILQ_ENTRY(AddressSpace) address_spaces_link;
913
914	/*
915	* Maximum DMA bounce buffer size used for indirect memory map requests.
916	* This limits the total size of bounce buffer allocations made for
917	* DMA requests to indirect memory regions within this AddressSpace. DMA
918	* requests that exceed the limit (e.g. due to overly large requested size
919	* or concurrent DMA requests having claimed too much buffer space) will be
920	* rejected and left to the caller to handle.
921	*/
922	size_t max_bounce_buffer_size;
923	/* Total size of bounce buffers currently allocated, atomically accessed */
924	size_t bounce_buffer_size;
925	/* List of callbacks to invoke when buffers free up */
926	QemuMutex map_client_list_lock;
927	QLIST_HEAD(, AddressSpaceMapClient) map_client_list;
928	};
929
930	typedef struct AddressSpaceDispatch AddressSpaceDispatch;
931	typedef struct FlatRange FlatRange;
932
933	/* Flattened global view of current active memory hierarchy. Kept in sorted
934	* order.
935	*/
936	struct FlatView {
937	struct rcu_head rcu;
938	unsigned ref;
939	FlatRange *ranges;
940	unsigned nr;
941	unsigned nr_allocated;
942	struct AddressSpaceDispatch *dispatch;
943	MemoryRegion *root;
944	};
945
946	static inline FlatView address_space_to_flatview(const AddressSpace as)
947	{
948	return qatomic_rcu_read(&as->current_map);
949	}
950
951	/**
952	* typedef flatview_cb: callback for flatview_for_each_range()
953	*
954	* @start: start address of the range within the FlatView
955	* @len: length of the range in bytes
956	* @mr: MemoryRegion covering this range
957	* @offset_in_region: offset of the first byte of the range within @mr
958	* @opaque: data pointer passed to flatview_for_each_range()
959	*
960	* Returns: true to stop the iteration, false to keep going.
961	*/
962	typedef bool (*flatview_cb)(Int128 start,
963	Int128 len,
964	const MemoryRegion *mr,
965	hwaddr offset_in_region,
966	void *opaque);
967
968	/**
969	* flatview_for_each_range: Iterate through a FlatView
970	* @fv: the FlatView to iterate through
971	* @cb: function to call for each range
972	* @opaque: opaque data pointer to pass to @cb
973	*
974	* A FlatView is made up of a list of non-overlapping ranges, each of
975	* which is a slice of a MemoryRegion. This function iterates through
976	* each range in @fv, calling @cb. The callback function can terminate
977	* iteration early by returning 'true'.
978	*/
979	void flatview_for_each_range(FlatView fv, flatview_cb cb, void opaque);
980
981	static inline bool MemoryRegionSection_eq(MemoryRegionSection *a,
982	MemoryRegionSection *b)
983	{
984	return a->mr == b->mr &&
985	a->fv == b->fv &&
986	a->offset_within_region == b->offset_within_region &&
987	a->offset_within_address_space == b->offset_within_address_space &&
988	int128_eq(a->size, b->size) &&
989	a->readonly == b->readonly &&
990	a->nonvolatile == b->nonvolatile;
991	}
992
993	/**
994	* memory_region_section_new_copy: Copy a memory region section
995	*
996	* Allocate memory for a new copy, copy the memory region section, and
997	* properly take a reference on all relevant members.
998	*
999	* @s: the #MemoryRegionSection to copy
1000	*/
1001	MemoryRegionSection memory_region_section_new_copy(MemoryRegionSection s);
1002
1003	/**
1004	* memory_region_section_free_copy: Free a copied memory region section
1005	*
1006	* Free a copy of a memory section created via memory_region_section_new_copy().
1007	* properly dropping references on all relevant members.
1008	*
1009	* @s: the #MemoryRegionSection to copy
1010	*/
1011	void memory_region_section_free_copy(MemoryRegionSection *s);
1012
1013	/**
1014	* memory_region_section_intersect_range: Adjust the memory section to cover
1015	* the intersection with the given range.
1016	*
1017	* @s: the #MemoryRegionSection to be adjusted
1018	* @offset: the offset of the given range in the memory region
1019	* @size: the size of the given range
1020	*
1021	* Returns false if the intersection is empty, otherwise returns true.
1022	*/
1023	static inline bool memory_region_section_intersect_range(MemoryRegionSection *s,
1024	uint64_t offset,
1025	uint64_t size)
1026	{
1027	uint64_t start = MAX(s->offset_within_region, offset);
1028	Int128 end = int128_min(int128_add(int128_make64(s->offset_within_region),
1029	s->size),
1030	int128_add(int128_make64(offset),
1031	int128_make64(size)));
1032
1033	if (int128_le(end, int128_make64(start))) {
1034	return false;
1035	}
1036
1037	s->offset_within_address_space += start - s->offset_within_region;
1038	s->offset_within_region = start;
1039	s->size = int128_sub(end, int128_make64(start));
1040	return true;
1041	}
1042
1043	/**
1044	* memory_region_init: Initialize a memory region
1045	*
1046	* The region typically acts as a container for other memory regions. Use
1047	* memory_region_add_subregion() to add subregions.
1048	*
1049	* @mr: the #MemoryRegion to be initialized
1050	* @owner: the object that tracks the region's reference count
1051	* @name: used for debugging; not visible to the user or ABI
1052	* @size: size of the region; any subregions beyond this size will be clipped
1053	*/
1054	void memory_region_init(MemoryRegion *mr,
1055	Object *owner,
1056	const char *name,
1057	uint64_t size);
1058
1059	/**
1060	* memory_region_ref: Add 1 to a memory region's reference count
1061	*
1062	* Whenever memory regions are accessed outside the BQL, they need to be
1063	* preserved against hot-unplug. MemoryRegions actually do not have their
1064	* own reference count; they piggyback on a QOM object, their "owner".
1065	* This function adds a reference to the owner.
1066	*
1067	* All MemoryRegions must have an owner if they can disappear, even if the
1068	* device they belong to operates exclusively under the BQL. This is because
1069	* the region could be returned at any time by memory_region_find, and this
1070	* is usually under guest control.
1071	*
1072	* @mr: the #MemoryRegion
1073	*/
1074	void memory_region_ref(MemoryRegion *mr);
1075
1076	/**
1077	* memory_region_unref: Remove 1 to a memory region's reference count
1078	*
1079	* Whenever memory regions are accessed outside the BQL, they need to be
1080	* preserved against hot-unplug. MemoryRegions actually do not have their
1081	* own reference count; they piggyback on a QOM object, their "owner".
1082	* This function removes a reference to the owner and possibly destroys it.
1083	*
1084	* @mr: the #MemoryRegion
1085	*/
1086	void memory_region_unref(MemoryRegion *mr);
1087
1088	G_DEFINE_AUTOPTR_CLEANUP_FUNC(MemoryRegion, memory_region_unref)
1089
1090	/**
1091	* memory_region_init_io: Initialize an I/O memory region.
1092	*
1093	* Accesses into the region will cause the callbacks in @ops to be called.
1094	* if @size is nonzero, subregions will be clipped to @size.
1095	*
1096	* @mr: the #MemoryRegion to be initialized.
1097	* @owner: the object that tracks the region's reference count
1098	* @ops: a structure containing read and write callbacks to be used when
1099	* I/O is performed on the region.
1100	* @opaque: passed to the read and write callbacks of the @ops structure.
1101	* @name: used for debugging; not visible to the user or ABI
1102	* @size: size of the region.
1103	*/
1104	void memory_region_init_io(MemoryRegion *mr,
1105	Object *owner,
1106	const MemoryRegionOps *ops,
1107	void *opaque,
1108	const char *name,
1109	uint64_t size);
1110
1111	/**
1112	* memory_region_init_ram_flags_nomigrate: Initialize RAM memory region.
1113	* Accesses into the region will
1114	* modify memory directly.
1115	*
1116	* @mr: the #MemoryRegion to be initialized.
1117	* @owner: the object that tracks the region's reference count
1118	* @name: Region name, becomes part of RAMBlock name used in migration stream
1119	* must be unique within any device
1120	* @size: size of the region.
1121	* @ram_flags: RamBlock flags. Supported flags: RAM_SHARED, RAM_NORESERVE,
1122	* RAM_GUEST_MEMFD.
1123	* @errp: pointer to Error*, to store an error if it happens.
1124	*
1125	* Note that this function does not do anything to cause the data in the
1126	* RAM memory region to be migrated; that is the responsibility of the caller.
1127	*
1128	* Return: true on success, else false setting @errp with error.
1129	*/
1130	bool memory_region_init_ram_flags_nomigrate(MemoryRegion *mr,
1131	Object *owner,
1132	const char *name,
1133	uint64_t size,
1134	uint32_t ram_flags,
1135	Error **errp);
1136
1137	/**
1138	* memory_region_init_resizeable_ram: Initialize memory region with resizable
1139	* RAM. Accesses into the region will
1140	* modify memory directly. Only an initial
1141	* portion of this RAM is actually used.
1142	* Changing the size while migrating
1143	* can result in the migration being
1144	* canceled.
1145	*
1146	* @mr: the #MemoryRegion to be initialized.
1147	* @owner: the object that tracks the region's reference count
1148	* @name: Region name, becomes part of RAMBlock name used in migration stream
1149	* must be unique within any device
1150	* @size: used size of the region.
1151	* @max_size: max size of the region.
1152	* @resized: callback to notify owner about used size change.
1153	* @errp: pointer to Error*, to store an error if it happens.
1154	*
1155	* Note that this function does not do anything to cause the data in the
1156	* RAM memory region to be migrated; that is the responsibility of the caller.
1157	*
1158	* Return: true on success, else false setting @errp with error.
1159	*/
1160	bool memory_region_init_resizeable_ram(MemoryRegion *mr,
1161	Object *owner,
1162	const char *name,
1163	uint64_t size,
1164	uint64_t max_size,
1165	void (resized)(const char,
1166	uint64_t length,
1167	void *host),
1168	Error **errp);
1169	#ifdef CONFIG_POSIX
1170
1171	/**
1172	* memory_region_init_ram_from_file: Initialize RAM memory region with a
1173	* mmap-ed backend.
1174	*
1175	* @mr: the #MemoryRegion to be initialized.
1176	* @owner: the object that tracks the region's reference count
1177	* @name: Region name, becomes part of RAMBlock name used in migration stream
1178	* must be unique within any device
1179	* @size: size of the region.
1180	* @align: alignment of the region base address; if 0, the default alignment
1181	* (getpagesize()) will be used.
1182	* @ram_flags: RamBlock flags. Supported flags: RAM_SHARED, RAM_PMEM,
1183	* RAM_NORESERVE, RAM_PROTECTED, RAM_NAMED_FILE, RAM_READONLY,
1184	* RAM_READONLY_FD, RAM_GUEST_MEMFD
1185	* @path: the path in which to allocate the RAM.
1186	* @offset: offset within the file referenced by path
1187	* @errp: pointer to Error*, to store an error if it happens.
1188	*
1189	* Note that this function does not do anything to cause the data in the
1190	* RAM memory region to be migrated; that is the responsibility of the caller.
1191	*
1192	* Return: true on success, else false setting @errp with error.
1193	*/
1194	bool memory_region_init_ram_from_file(MemoryRegion *mr,
1195	Object *owner,
1196	const char *name,
1197	uint64_t size,
1198	uint64_t align,
1199	uint32_t ram_flags,
1200	const char *path,
1201	ram_addr_t offset,
1202	Error **errp);
1203	#endif
1204
1205	/**
1206	* memory_region_init_ram_from_fd: Initialize RAM memory region with a
1207	* mmap-ed backend.
1208	*
1209	* @mr: the #MemoryRegion to be initialized.
1210	* @owner: the object that tracks the region's reference count
1211	* @name: the name of the region.
1212	* @size: size of the region.
1213	* @ram_flags: RamBlock flags. Supported flags: RAM_SHARED, RAM_PMEM,
1214	* RAM_NORESERVE, RAM_PROTECTED, RAM_NAMED_FILE, RAM_READONLY,
1215	* RAM_READONLY_FD, RAM_GUEST_MEMFD
1216	* @fd: the fd to mmap.
1217	* @offset: offset within the file referenced by fd
1218	* @errp: pointer to Error*, to store an error if it happens.
1219	*
1220	* Note that this function does not do anything to cause the data in the
1221	* RAM memory region to be migrated; that is the responsibility of the caller.
1222	*
1223	* Return: true on success, else false setting @errp with error.
1224	*/
1225	bool memory_region_init_ram_from_fd(MemoryRegion *mr,
1226	Object *owner,
1227	const char *name,
1228	uint64_t size,
1229	uint32_t ram_flags,
1230	int fd,
1231	ram_addr_t offset,
1232	Error **errp);
1233
1234	/**
1235	* memory_region_init_ram_ptr: Initialize RAM memory region from a
1236	* user-provided pointer. Accesses into the
1237	* region will modify memory directly.
1238	*
1239	* @mr: the #MemoryRegion to be initialized.
1240	* @owner: the object that tracks the region's reference count
1241	* @name: Region name, becomes part of RAMBlock name used in migration stream
1242	* must be unique within any device
1243	* @size: size of the region.
1244	* @ptr: memory to be mapped; must contain at least @size bytes.
1245	*
1246	* Note that this function does not do anything to cause the data in the
1247	* RAM memory region to be migrated; that is the responsibility of the caller.
1248	*/
1249	void memory_region_init_ram_ptr(MemoryRegion *mr,
1250	Object *owner,
1251	const char *name,
1252	uint64_t size,
1253	void *ptr);
1254
1255	/**
1256	* memory_region_init_ram_device_ptr: Initialize RAM device memory region from
1257	* a user-provided pointer.
1258	*
1259	* A RAM device represents a mapping to a physical device, such as to a PCI
1260	* MMIO BAR of an vfio-pci assigned device. The memory region may be mapped
1261	* into the VM address space and access to the region will modify memory
1262	* directly. However, the memory region should not be included in a memory
1263	* dump (device may not be enabled/mapped at the time of the dump), and
1264	* operations incompatible with manipulating MMIO should be avoided. Replaces
1265	* skip_dump flag.
1266	*
1267	* @mr: the #MemoryRegion to be initialized.
1268	* @owner: the object that tracks the region's reference count
1269	* @name: the name of the region.
1270	* @size: size of the region.
1271	* @ptr: memory to be mapped; must contain at least @size bytes.
1272	*
1273	* Note that this function does not do anything to cause the data in the
1274	* RAM memory region to be migrated; that is the responsibility of the caller.
1275	* (For RAM device memory regions, migrating the contents rarely makes sense.)
1276	*/
1277	void memory_region_init_ram_device_ptr(MemoryRegion *mr,
1278	Object *owner,
1279	const char *name,
1280	uint64_t size,
1281	void *ptr);
1282
1283	/**
1284	* memory_region_init_alias: Initialize a memory region that aliases all or a
1285	* part of another memory region.
1286	*
1287	* @mr: the #MemoryRegion to be initialized.
1288	* @owner: the object that tracks the region's reference count
1289	* @name: used for debugging; not visible to the user or ABI
1290	* @orig: the region to be referenced; @mr will be equivalent to
1291	* @orig between @offset and @offset + @size - 1.
1292	* @offset: start of the section in @orig to be referenced.
1293	* @size: size of the region.
1294	*/
1295	void memory_region_init_alias(MemoryRegion *mr,
1296	Object *owner,
1297	const char *name,
1298	MemoryRegion *orig,
1299	hwaddr offset,
1300	uint64_t size);
1301
1302	/**
1303	* memory_region_init_iommu: Initialize a memory region of a custom type
1304	* that translates addresses
1305	*
1306	* An IOMMU region translates addresses and forwards accesses to a target
1307	* memory region.
1308	*
1309	* The IOMMU implementation must define a subclass of TYPE_IOMMU_MEMORY_REGION.
1310	* @_iommu_mr should be a pointer to enough memory for an instance of
1311	* that subclass, @instance_size is the size of that subclass, and
1312	* @mrtypename is its name. This function will initialize @_iommu_mr as an
1313	* instance of the subclass, and its methods will then be called to handle
1314	* accesses to the memory region. See the documentation of
1315	* #IOMMUMemoryRegionClass for further details.
1316	*
1317	* @_iommu_mr: the #IOMMUMemoryRegion to be initialized
1318	* @instance_size: the IOMMUMemoryRegion subclass instance size
1319	* @mrtypename: the type name of the #IOMMUMemoryRegion
1320	* @owner: the object that tracks the region's reference count
1321	* @name: used for debugging; not visible to the user or ABI
1322	* @size: size of the region.
1323	*/
1324	void memory_region_init_iommu(void *_iommu_mr,
1325	size_t instance_size,
1326	const char *mrtypename,
1327	Object *owner,
1328	const char *name,
1329	uint64_t size);
1330
1331	/**
1332	* memory_region_init_ram - Initialize RAM memory region. Accesses into the
1333	* region will modify memory directly.
1334	*
1335	* @mr: the #MemoryRegion to be initialized
1336	* @owner: the object that tracks the region's reference count (must be
1337	* TYPE_DEVICE or a subclass of TYPE_DEVICE, or NULL)
1338	* @name: name of the memory region
1339	* @size: size of the region in bytes
1340	* @errp: pointer to Error*, to store an error if it happens.
1341	*
1342	* This function allocates RAM for a board model or device, and
1343	* arranges for it to be migrated (by calling vmstate_register_ram()
1344	* if @owner is a DeviceState, or vmstate_register_ram_global() if
1345	* @owner is NULL).
1346	*
1347	* TODO: Currently we restrict @owner to being either NULL (for
1348	* global RAM regions with no owner) or devices, so that we can
1349	* give the RAM block a unique name for migration purposes.
1350	* We should lift this restriction and allow arbitrary Objects.
1351	* If you pass a non-NULL non-device @owner then we will assert.
1352	*
1353	* Return: true on success, else false setting @errp with error.
1354	*/
1355	bool memory_region_init_ram(MemoryRegion *mr,
1356	Object *owner,
1357	const char *name,
1358	uint64_t size,
1359	Error **errp);
1360
1361	bool memory_region_init_ram_guest_memfd(MemoryRegion *mr,
1362	Object *owner,
1363	const char *name,
1364	uint64_t size,
1365	Error **errp);
1366
1367	/**
1368	* memory_region_init_rom: Initialize a ROM memory region.
1369	*
1370	* This has the same effect as calling memory_region_init_ram()
1371	* and then marking the resulting region read-only with
1372	* memory_region_set_readonly(). This includes arranging for the
1373	* contents to be migrated.
1374	*
1375	* TODO: Currently we restrict @owner to being either NULL (for
1376	* global RAM regions with no owner) or devices, so that we can
1377	* give the RAM block a unique name for migration purposes.
1378	* We should lift this restriction and allow arbitrary Objects.
1379	* If you pass a non-NULL non-device @owner then we will assert.
1380	*
1381	* @mr: the #MemoryRegion to be initialized.
1382	* @owner: the object that tracks the region's reference count
1383	* @name: Region name, becomes part of RAMBlock name used in migration stream
1384	* must be unique within any device
1385	* @size: size of the region.
1386	* @errp: pointer to Error*, to store an error if it happens.
1387	*
1388	* Return: true on success, else false setting @errp with error.
1389	*/
1390	bool memory_region_init_rom(MemoryRegion *mr,
1391	Object *owner,
1392	const char *name,
1393	uint64_t size,
1394	Error **errp);
1395
1396	/**
1397	* memory_region_init_rom_device: Initialize a ROM memory region.
1398	* Writes are handled via callbacks.
1399	*
1400	* This function initializes a memory region backed by RAM for reads
1401	* and callbacks for writes, and arranges for the RAM backing to
1402	* be migrated (by calling vmstate_register_ram()
1403	* if @owner is a DeviceState, or vmstate_register_ram_global() if
1404	* @owner is NULL).
1405	*
1406	* TODO: Currently we restrict @owner to being either NULL (for
1407	* global RAM regions with no owner) or devices, so that we can
1408	* give the RAM block a unique name for migration purposes.
1409	* We should lift this restriction and allow arbitrary Objects.
1410	* If you pass a non-NULL non-device @owner then we will assert.
1411	*
1412	* @mr: the #MemoryRegion to be initialized.
1413	* @owner: the object that tracks the region's reference count
1414	* @ops: callbacks for write access handling (must not be NULL).
1415	* @opaque: passed to the read and write callbacks of the @ops structure.
1416	* @name: Region name, becomes part of RAMBlock name used in migration stream
1417	* must be unique within any device
1418	* @size: size of the region.
1419	* @errp: pointer to Error*, to store an error if it happens.
1420	*
1421	* Return: true on success, else false setting @errp with error.
1422	*/
1423	bool memory_region_init_rom_device(MemoryRegion *mr,
1424	Object *owner,
1425	const MemoryRegionOps *ops,
1426	void *opaque,
1427	const char *name,
1428	uint64_t size,
1429	Error **errp);
1430
1431
1432	/**
1433	* memory_region_owner: get a memory region's owner.
1434	*
1435	* @mr: the memory region being queried.
1436	*/
1437	Object memory_region_owner(const MemoryRegion mr);
1438
1439	/**
1440	* memory_region_size: get a memory region's size.
1441	*
1442	* @mr: the memory region being queried.
1443	*/
1444	uint64_t memory_region_size(const MemoryRegion *mr);
1445
1446	/**
1447	* memory_region_is_ram: check whether a memory region is random access
1448	*
1449	* Returns %true if a memory region is random access.
1450	*
1451	* @mr: the memory region being queried
1452	*/
1453	static inline bool memory_region_is_ram(const MemoryRegion *mr)
1454	{
1455	return mr->ram;
1456	}
1457
1458	/**
1459	* memory_region_is_ram_device: check whether a memory region is a ram device
1460	*
1461	* Returns %true if a memory region is a device backed ram region
1462	*
1463	* @mr: the memory region being queried
1464	*/
1465	bool memory_region_is_ram_device(const MemoryRegion *mr);
1466
1467	/**
1468	* memory_region_is_romd: check whether a memory region is in ROMD mode
1469	*
1470	* Returns %true if a memory region is a ROM device and currently set to allow
1471	* direct reads.
1472	*
1473	* @mr: the memory region being queried
1474	*/
1475	static inline bool memory_region_is_romd(const MemoryRegion *mr)
1476	{
1477	return mr->rom_device && mr->romd_mode;
1478	}
1479
1480	/**
1481	* memory_region_is_protected: check whether a memory region is protected
1482	*
1483	* Returns %true if a memory region is protected RAM and cannot be accessed
1484	* via standard mechanisms, e.g. DMA.
1485	*
1486	* @mr: the memory region being queried
1487	*/
1488	bool memory_region_is_protected(const MemoryRegion *mr);
1489
1490	/**
1491	* memory_region_skip_iommu_map: check whether a memory region is excluded
1492	* from IOMMU mapping
1493	*
1494	* Returns %true if @mr is a RAM device region marked to skip IOMMU mapping.
1495	*
1496	* @mr: the memory region being queried
1497	*/
1498	bool memory_region_skip_iommu_map(const MemoryRegion *mr);
1499
1500	/**
1501	* memory_region_set_skip_iommu_map: mark a RAM device region to skip IOMMU
1502	* mapping
1503	*
1504	* @mr: the memory region being modified
1505	* @skip: %true to skip IOMMU mapping, %false to allow it
1506	*/
1507	void memory_region_set_skip_iommu_map(MemoryRegion *mr, bool skip);
1508
1509	/**
1510	* memory_region_has_guest_memfd: check whether a memory region has guest_memfd
1511	* associated
1512	*
1513	* Returns %true if a memory region's ram_block has valid guest_memfd assigned.
1514	*
1515	* @mr: the memory region being queried
1516	*/
1517	bool memory_region_has_guest_memfd(const MemoryRegion *mr);
1518
1519	/**
1520	* memory_region_get_iommu: check whether a memory region is an iommu
1521	*
1522	* Returns pointer to IOMMUMemoryRegion if a memory region is an iommu,
1523	* otherwise NULL.
1524	*
1525	* @mr: the memory region being queried
1526	*/
1527	static inline IOMMUMemoryRegion memory_region_get_iommu(const MemoryRegion mr)
1528	{
1529	if (mr->alias) {
1530	return memory_region_get_iommu(mr->alias);
1531	}
1532	if (mr->is_iommu) {
1533	return (IOMMUMemoryRegion *) mr;
1534	}
1535	return NULL;
1536	}
1537
1538	/**
1539	* memory_region_get_iommu_class_nocheck: returns iommu memory region class
1540	* if an iommu or NULL if not
1541	*
1542	* Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu,
1543	* otherwise NULL. This is fast path avoiding QOM checking, use with caution.
1544	*
1545	* @iommu_mr: the memory region being queried
1546	*/
1547	static inline IOMMUMemoryRegionClass *memory_region_get_iommu_class_nocheck(
1548	IOMMUMemoryRegion *iommu_mr)
1549	{
1550	return (IOMMUMemoryRegionClass ) (((Object )iommu_mr)->class);
1551	}
1552
1553	#define memory_region_is_iommu(mr) (memory_region_get_iommu(mr) != NULL)
1554
1555	/**
1556	* memory_region_iommu_get_min_page_size: get minimum supported page size
1557	* for an iommu
1558	*
1559	* Returns minimum supported page size for an iommu.
1560	*
1561	* @iommu_mr: the memory region being queried
1562	*/
1563	uint64_t memory_region_iommu_get_min_page_size(IOMMUMemoryRegion *iommu_mr);
1564
1565	/**
1566	* memory_region_notify_iommu: notify a change in an IOMMU translation entry.
1567	*
1568	* Note: for any IOMMU implementation, an in-place mapping change
1569	* should be notified with an UNMAP followed by a MAP.
1570	*
1571	* @iommu_mr: the memory region that was changed
1572	* @iommu_idx: the IOMMU index for the translation table which has changed
1573	* @event: TLB event with the new entry in the IOMMU translation table.
1574	* The entry replaces all old entries for the same virtual I/O address
1575	* range.
1576	*/
1577	void memory_region_notify_iommu(IOMMUMemoryRegion *iommu_mr,
1578	int iommu_idx,
1579	const IOMMUTLBEvent event);
1580
1581	/**
1582	* memory_region_notify_iommu_one: notify a change in an IOMMU translation
1583	* entry to a single notifier
1584	*
1585	* This works just like memory_region_notify_iommu(), but it only
1586	* notifies a specific notifier, not all of them.
1587	*
1588	* @notifier: the notifier to be notified
1589	* @event: TLB event with the new entry in the IOMMU translation table.
1590	* The entry replaces all old entries for the same virtual I/O address
1591	* range.
1592	*/
1593	void memory_region_notify_iommu_one(IOMMUNotifier *notifier,
1594	const IOMMUTLBEvent *event);
1595
1596	/**
1597	* memory_region_unmap_iommu_notifier_range: notify a unmap for an IOMMU
1598	* translation that covers the
1599	* range of a notifier
1600	*
1601	* @notifier: the notifier to be notified
1602	*/
1603	void memory_region_unmap_iommu_notifier_range(IOMMUNotifier *notifier);
1604
1605
1606	/**
1607	* memory_region_register_iommu_notifier: register a notifier for changes to
1608	* IOMMU translation entries.
1609	*
1610	* Returns 0 on success, or a negative errno otherwise. In particular,
1611	* -EINVAL indicates that at least one of the attributes of the notifier
1612	* is not supported (flag/range) by the IOMMU memory region. In case of error
1613	* the error object must be created.
1614	*
1615	* @mr: the memory region to observe
1616	* @n: the IOMMUNotifier to be added; the notify callback receives a
1617	* pointer to an #IOMMUTLBEntry as the opaque value; the pointer
1618	* ceases to be valid on exit from the notifier.
1619	* @errp: pointer to Error*, to store an error if it happens.
1620	*/
1621	int memory_region_register_iommu_notifier(MemoryRegion *mr,
1622	IOMMUNotifier n, Error *errp);
1623
1624	/**
1625	* memory_region_iommu_replay: replay existing IOMMU translations to
1626	* a notifier with the minimum page granularity returned by
1627	* mr->iommu_ops->get_page_size().
1628	*
1629	* Note: this is not related to record-and-replay functionality.
1630	*
1631	* @iommu_mr: the memory region to observe
1632	* @n: the notifier to which to replay iommu mappings
1633	*/
1634	void memory_region_iommu_replay(IOMMUMemoryRegion iommu_mr, IOMMUNotifier n);
1635
1636	/**
1637	* memory_region_unregister_iommu_notifier: unregister a notifier for
1638	* changes to IOMMU translation entries.
1639	*
1640	* @mr: the memory region which was observed and for which notify_stopped()
1641	* needs to be called
1642	* @n: the notifier to be removed.
1643	*/
1644	void memory_region_unregister_iommu_notifier(MemoryRegion *mr,
1645	IOMMUNotifier *n);
1646
1647	/**
1648	* memory_region_iommu_get_attr: return an IOMMU attr if get_attr() is
1649	* defined on the IOMMU.
1650	*
1651	* Returns 0 on success, or a negative errno otherwise. In particular,
1652	* -EINVAL indicates that the IOMMU does not support the requested
1653	* attribute.
1654	*
1655	* @iommu_mr: the memory region
1656	* @attr: the requested attribute
1657	* @data: a pointer to the requested attribute data
1658	*/
1659	int memory_region_iommu_get_attr(IOMMUMemoryRegion *iommu_mr,
1660	enum IOMMUMemoryRegionAttr attr,
1661	void *data);
1662
1663	/**
1664	* memory_region_iommu_attrs_to_index: return the IOMMU index to
1665	* use for translations with the given memory transaction attributes.
1666	*
1667	* @iommu_mr: the memory region
1668	* @attrs: the memory transaction attributes
1669	*/
1670	int memory_region_iommu_attrs_to_index(IOMMUMemoryRegion *iommu_mr,
1671	MemTxAttrs attrs);
1672
1673	/**
1674	* memory_region_iommu_num_indexes: return the total number of IOMMU
1675	* indexes that this IOMMU supports.
1676	*
1677	* @iommu_mr: the memory region
1678	*/
1679	int memory_region_iommu_num_indexes(IOMMUMemoryRegion *iommu_mr);
1680
1681	/**
1682	* memory_region_name: get a memory region's name
1683	*
1684	* Returns the string that was used to initialize the memory region.
1685	*
1686	* @mr: the memory region being queried
1687	*/
1688	const char memory_region_name(const MemoryRegion mr);
1689
1690	/**
1691	* memory_region_is_logging: return whether a memory region is logging writes
1692	*
1693	* Returns %true if the memory region is logging writes for the given client
1694	*
1695	* @mr: the memory region being queried
1696	* @client: the client being queried
1697	*/
1698	bool memory_region_is_logging(const MemoryRegion *mr, uint8_t client);
1699
1700	/**
1701	* memory_region_get_dirty_log_mask: return the clients for which a
1702	* memory region is logging writes.
1703	*
1704	* Returns a bitmap of clients, in which the DIRTY_MEMORY_* constants
1705	* are the bit indices.
1706	*
1707	* @mr: the memory region being queried
1708	*/
1709	uint8_t memory_region_get_dirty_log_mask(const MemoryRegion *mr);
1710
1711	/**
1712	* memory_region_is_rom: check whether a memory region is ROM
1713	*
1714	* Returns %true if a memory region is read-only memory.
1715	*
1716	* @mr: the memory region being queried
1717	*/
1718	static inline bool memory_region_is_rom(const MemoryRegion *mr)
1719	{
1720	return mr->ram && mr->readonly;
1721	}
1722
1723	/**
1724	* memory_region_is_nonvolatile: check whether a memory region is non-volatile
1725	*
1726	* Returns %true is a memory region is non-volatile memory.
1727	*
1728	* @mr: the memory region being queried
1729	*/
1730	static inline bool memory_region_is_nonvolatile(const MemoryRegion *mr)
1731	{
1732	return mr->nonvolatile;
1733	}
1734
1735	/**
1736	* memory_region_get_fd: Get a file descriptor backing a RAM memory region.
1737	*
1738	* Returns a file descriptor backing a file-based RAM memory region,
1739	* or -1 if the region is not a file-based RAM memory region.
1740	*
1741	* @mr: the RAM or alias memory region being queried.
1742	*/
1743	int memory_region_get_fd(const MemoryRegion *mr);
1744
1745	/**
1746	* memory_region_from_host: Convert a pointer into a RAM memory region
1747	* and an offset within it.
1748	*
1749	* Given a host pointer inside a RAM memory region (created with
1750	* memory_region_init_ram() or memory_region_init_ram_ptr()), return
1751	* the MemoryRegion and the offset within it.
1752	*
1753	* Use with care; by the time this function returns, the returned pointer is
1754	* not protected by RCU anymore. If the caller is not within an RCU critical
1755	* section and does not hold the BQL, it must have other means of
1756	* protecting the pointer, such as a reference to the region that includes
1757	* the incoming ram_addr_t.
1758	*
1759	* @ptr: the host pointer to be converted
1760	* @offset: the offset within memory region
1761	*/
1762	MemoryRegion memory_region_from_host(void ptr, ram_addr_t *offset);
1763
1764	/**
1765	* memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
1766	*
1767	* Returns a host pointer to a RAM memory region (created with
1768	* memory_region_init_ram() or memory_region_init_ram_ptr()).
1769	*
1770	* Use with care; by the time this function returns, the returned pointer is
1771	* not protected by RCU anymore. If the caller is not within an RCU critical
1772	* section and does not hold the BQL, it must have other means of
1773	* protecting the pointer, such as a reference to the region that includes
1774	* the incoming ram_addr_t.
1775	*
1776	* @mr: the memory region being queried.
1777	*/
1778	void memory_region_get_ram_ptr(const MemoryRegion mr);
1779
1780	/* memory_region_ram_resize: Resize a RAM region.
1781	*
1782	* Resizing RAM while migrating can result in the migration being canceled.
1783	* Care has to be taken if the guest might have already detected the memory.
1784	*
1785	* @mr: a memory region created with @memory_region_init_resizeable_ram.
1786	* @newsize: the new size the region
1787	* @errp: pointer to Error*, to store an error if it happens.
1788	*/
1789	void memory_region_ram_resize(MemoryRegion *mr, ram_addr_t newsize,
1790	Error **errp);
1791
1792	/**
1793	* memory_region_msync: Synchronize selected address range of
1794	* a memory mapped region
1795	*
1796	* @mr: the memory region to be msync
1797	* @addr: the initial address of the range to be sync
1798	* @size: the size of the range to be sync
1799	*/
1800	void memory_region_msync(MemoryRegion *mr, hwaddr addr, hwaddr size);
1801
1802	/**
1803	* memory_region_writeback: Trigger cache writeback for
1804	* selected address range
1805	*
1806	* @mr: the memory region to be updated
1807	* @addr: the initial address of the range to be written back
1808	* @size: the size of the range to be written back
1809	*/
1810	void memory_region_writeback(MemoryRegion *mr, hwaddr addr, hwaddr size);
1811
1812	/**
1813	* memory_region_set_log: Turn dirty logging on or off for a region.
1814	*
1815	* Turns dirty logging on or off for a specified client (display, migration).
1816	* Only meaningful for RAM regions.
1817	*
1818	* @mr: the memory region being updated.
1819	* @log: whether dirty logging is to be enabled or disabled.
1820	* @client: the user of the logging information; %DIRTY_MEMORY_VGA only.
1821	*/
1822	void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
1823
1824	/**
1825	* memory_region_set_dirty: Mark a range of bytes as dirty in a memory region.
1826	*
1827	* Marks a range of bytes as dirty, after it has been dirtied outside
1828	* guest code.
1829	*
1830	* @mr: the memory region being dirtied.
1831	* @addr: the address (relative to the start of the region) being dirtied.
1832	* @size: size of the range being dirtied.
1833	*/
1834	void memory_region_set_dirty(MemoryRegion *mr, hwaddr addr,
1835	hwaddr size);
1836
1837	/**
1838	* memory_region_clear_dirty_bitmap - clear dirty bitmap for memory range
1839	*
1840	* This function is called when the caller wants to clear the remote
1841	* dirty bitmap of a memory range within the memory region. This can
1842	* be used by e.g. KVM to manually clear dirty log when
1843	* KVM_CAP_MANUAL_DIRTY_LOG_PROTECT is declared support by the host
1844	* kernel.
1845	*
1846	* @mr: the memory region to clear the dirty log upon
1847	* @start: start address offset within the memory region
1848	* @len: length of the memory region to clear dirty bitmap
1849	*/
1850	void memory_region_clear_dirty_bitmap(MemoryRegion *mr, hwaddr start,
1851	hwaddr len);
1852
1853	/**
1854	* memory_region_snapshot_and_clear_dirty: Get a snapshot of the dirty
1855	* bitmap and clear it.
1856	*
1857	* Creates a snapshot of the dirty bitmap, clears the dirty bitmap and
1858	* returns the snapshot. The snapshot can then be used to query dirty
1859	* status, using memory_region_snapshot_get_dirty. Snapshotting allows
1860	* querying the same page multiple times, which is especially useful for
1861	* display updates where the scanlines often are not page aligned.
1862	*
1863	* The dirty bitmap region which gets copied into the snapshot (and
1864	* cleared afterwards) can be larger than requested. The boundaries
1865	* are rounded up/down so complete bitmap longs (covering 64 pages on
1866	* 64bit hosts) can be copied over into the bitmap snapshot. Which
1867	* isn't a problem for display updates as the extra pages are outside
1868	* the visible area, and in case the visible area changes a full
1869	* display redraw is due anyway. Should other use cases for this
1870	* function emerge we might have to revisit this implementation
1871	* detail.
1872	*
1873	* Use g_free to release DirtyBitmapSnapshot.
1874	*
1875	* @mr: the memory region being queried.
1876	* @addr: the address (relative to the start of the region) being queried.
1877	* @size: the size of the range being queried.
1878	* @client: the user of the logging information; typically %DIRTY_MEMORY_VGA.
1879	*/
1880	DirtyBitmapSnapshot memory_region_snapshot_and_clear_dirty(MemoryRegion mr,
1881	hwaddr addr,
1882	hwaddr size,
1883	unsigned client);
1884
1885	/**
1886	* memory_region_snapshot_get_dirty: Check whether a range of bytes is dirty
1887	* in the specified dirty bitmap snapshot.
1888	*
1889	* @mr: the memory region being queried.
1890	* @snap: the dirty bitmap snapshot
1891	* @addr: the address (relative to the start of the region) being queried.
1892	* @size: the size of the range being queried.
1893	*/
1894	bool memory_region_snapshot_get_dirty(MemoryRegion *mr,
1895	DirtyBitmapSnapshot *snap,
1896	hwaddr addr, hwaddr size);
1897
1898	/**
1899	* memory_region_reset_dirty: Mark a range of pages as clean, for a specified
1900	* client.
1901	*
1902	* Marks a range of pages as no longer dirty.
1903	*
1904	* @mr: the region being updated.
1905	* @addr: the start of the subrange being cleaned.
1906	* @size: the size of the subrange being cleaned.
1907	* @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
1908	* %DIRTY_MEMORY_VGA.
1909	*/
1910	void memory_region_reset_dirty(MemoryRegion *mr, hwaddr addr,
1911	hwaddr size, unsigned client);
1912
1913	/**
1914	* memory_region_flush_rom_device: Mark a range of pages dirty and invalidate
1915	* TBs (for self-modifying code).
1916	*
1917	* The MemoryRegionOps->write() callback of a ROM device must use this function
1918	* to mark byte ranges that have been modified internally, such as by directly
1919	* accessing the memory returned by memory_region_get_ram_ptr().
1920	*
1921	* This function marks the range dirty and invalidates TBs so that TCG can
1922	* detect self-modifying code.
1923	*
1924	* @mr: the region being flushed.
1925	* @addr: the start, relative to the start of the region, of the range being
1926	* flushed.
1927	* @size: the size, in bytes, of the range being flushed.
1928	*/
1929	void memory_region_flush_rom_device(MemoryRegion *mr, hwaddr addr, hwaddr size);
1930
1931	/**
1932	* memory_region_set_readonly: Turn a memory region read-only (or read-write)
1933	*
1934	* Allows a memory region to be marked as read-only (turning it into a ROM).
1935	* only useful on RAM regions.
1936	*
1937	* @mr: the region being updated.
1938	* @readonly: whether the region is to be ROM or RAM.
1939	*/
1940	void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
1941
1942	/**
1943	* memory_region_set_nonvolatile: Turn a memory region non-volatile
1944	*
1945	* Allows a memory region to be marked as non-volatile.
1946	* only useful on RAM regions.
1947	*
1948	* @mr: the region being updated.
1949	* @nonvolatile: whether the region is to be non-volatile.
1950	*/
1951	void memory_region_set_nonvolatile(MemoryRegion *mr, bool nonvolatile);
1952
1953	/**
1954	* memory_region_rom_device_set_romd: enable/disable ROMD mode
1955	*
1956	* Allows a ROM device (initialized with memory_region_init_rom_device() to
1957	* set to ROMD mode (default) or MMIO mode. When it is in ROMD mode, the
1958	* device is mapped to guest memory and satisfies read access directly.
1959	* When in MMIO mode, reads are forwarded to the #MemoryRegion.read function.
1960	* Writes are always handled by the #MemoryRegion.write function.
1961	*
1962	* @mr: the memory region to be updated
1963	* @romd_mode: %true to put the region into ROMD mode
1964	*/
1965	void memory_region_rom_device_set_romd(MemoryRegion *mr, bool romd_mode);
1966
1967	/**
1968	* memory_region_set_coalescing: Enable memory coalescing for the region.
1969	*
1970	* Enabled writes to a region to be queued for later processing. MMIO ->write
1971	* callbacks may be delayed until a non-coalesced MMIO is issued.
1972	* Only useful for IO regions. Roughly similar to write-combining hardware.
1973	*
1974	* @mr: the memory region to be write coalesced
1975	*/
1976	void memory_region_set_coalescing(MemoryRegion *mr);
1977
1978	/**
1979	* memory_region_add_coalescing: Enable memory coalescing for a sub-range of
1980	* a region.
1981	*
1982	* Like memory_region_set_coalescing(), but works on a sub-range of a region.
1983	* Multiple calls can be issued coalesced disjoint ranges.
1984	*
1985	* @mr: the memory region to be updated.
1986	* @offset: the start of the range within the region to be coalesced.
1987	* @size: the size of the subrange to be coalesced.
1988	*/
1989	void memory_region_add_coalescing(MemoryRegion *mr,
1990	hwaddr offset,
1991	uint64_t size);
1992
1993	/**
1994	* memory_region_clear_coalescing: Disable MMIO coalescing for the region.
1995	*
1996	* Disables any coalescing caused by memory_region_set_coalescing() or
1997	* memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
1998	* hardware.
1999	*
2000	* @mr: the memory region to be updated.
2001	*/
2002	void memory_region_clear_coalescing(MemoryRegion *mr);
2003
2004	/**
2005	* memory_region_set_flush_coalesced: Enforce memory coalescing flush before
2006	* accesses.
2007	*
2008	* Ensure that pending coalesced MMIO request are flushed before the memory
2009	* region is accessed. This property is automatically enabled for all regions
2010	* passed to memory_region_set_coalescing() and memory_region_add_coalescing().
2011	*
2012	* @mr: the memory region to be updated.
2013	*/
2014	void memory_region_set_flush_coalesced(MemoryRegion *mr);
2015
2016	/**
2017	* memory_region_clear_flush_coalesced: Disable memory coalescing flush before
2018	* accesses.
2019	*
2020	* Clear the automatic coalesced MMIO flushing enabled via
2021	* memory_region_set_flush_coalesced. Note that this service has no effect on
2022	* memory regions that have MMIO coalescing enabled for themselves. For them,
2023	* automatic flushing will stop once coalescing is disabled.
2024	*
2025	* @mr: the memory region to be updated.
2026	*/
2027	void memory_region_clear_flush_coalesced(MemoryRegion *mr);
2028
2029	/**
2030	* memory_region_enable_lockless_io: Enable lockless (BQL free) acceess.
2031	*
2032	* Enable BQL-free access for devices that are well prepared to handle
2033	* locking during I/O themselves: either by doing fine grained locking or
2034	* by providing lock-free I/O schemes.
2035	*
2036	* @mr: the memory region to be updated.
2037	*/
2038	void memory_region_enable_lockless_io(MemoryRegion *mr);
2039
2040	/**
2041	* memory_region_add_eventfd: Request an eventfd to be triggered when a word
2042	* is written to a location.
2043	*
2044	* Marks a word in an IO region (initialized with memory_region_init_io())
2045	* as a trigger for an eventfd event. The I/O callback will not be called.
2046	* The caller must be prepared to handle failure (that is, take the required
2047	* action if the callback _is_ called).
2048	*
2049	* @mr: the memory region being updated.
2050	* @addr: the address within @mr that is to be monitored
2051	* @size: the size of the access to trigger the eventfd
2052	* @match_data: whether to match against @data, instead of just @addr
2053	* @data: the data to match against the guest write
2054	* @e: event notifier to be triggered when @addr, @size, and @data all match.
2055	**/
2056	void memory_region_add_eventfd(MemoryRegion *mr,
2057	hwaddr addr,
2058	unsigned size,
2059	bool match_data,
2060	uint64_t data,
2061	EventNotifier *e);
2062
2063	/**
2064	* memory_region_del_eventfd: Cancel an eventfd.
2065	*
2066	* Cancels an eventfd trigger requested by a previous
2067	* memory_region_add_eventfd() call.
2068	*
2069	* @mr: the memory region being updated.
2070	* @addr: the address within @mr that is to be monitored
2071	* @size: the size of the access to trigger the eventfd
2072	* @match_data: whether to match against @data, instead of just @addr
2073	* @data: the data to match against the guest write
2074	* @e: event notifier to be triggered when @addr, @size, and @data all match.
2075	*/
2076	void memory_region_del_eventfd(MemoryRegion *mr,
2077	hwaddr addr,
2078	unsigned size,
2079	bool match_data,
2080	uint64_t data,
2081	EventNotifier *e);
2082
2083	/**
2084	* memory_region_add_subregion: Add a subregion to a container.
2085	*
2086	* Adds a subregion at @offset. The subregion may not overlap with other
2087	* subregions (except for those explicitly marked as overlapping). A region
2088	* may only be added once as a subregion (unless removed with
2089	* memory_region_del_subregion()); use memory_region_init_alias() if you
2090	* want a region to be a subregion in multiple locations.
2091	*
2092	* @mr: the region to contain the new subregion; must be a container
2093	* initialized with memory_region_init().
2094	* @offset: the offset relative to @mr where @subregion is added.
2095	* @subregion: the subregion to be added.
2096	*/
2097	void memory_region_add_subregion(MemoryRegion *mr,
2098	hwaddr offset,
2099	MemoryRegion *subregion);
2100	/**
2101	* memory_region_add_subregion_overlap: Add a subregion to a container
2102	* with overlap.
2103	*
2104	* Adds a subregion at @offset. The subregion may overlap with other
2105	* subregions. Conflicts are resolved by having a higher @priority hide a
2106	* lower @priority. Subregions without priority are taken as @priority 0.
2107	* A region may only be added once as a subregion (unless removed with
2108	* memory_region_del_subregion()); use memory_region_init_alias() if you
2109	* want a region to be a subregion in multiple locations.
2110	*
2111	* @mr: the region to contain the new subregion; must be a container
2112	* initialized with memory_region_init().
2113	* @offset: the offset relative to @mr where @subregion is added.
2114	* @subregion: the subregion to be added.
2115	* @priority: used for resolving overlaps; highest priority wins.
2116	*/
2117	void memory_region_add_subregion_overlap(MemoryRegion *mr,
2118	hwaddr offset,
2119	MemoryRegion *subregion,
2120	int priority);
2121
2122	/**
2123	* memory_region_get_ram_addr: Get the ram address associated with a memory
2124	* region
2125	*
2126	* @mr: the region to be queried
2127	*/
2128	ram_addr_t memory_region_get_ram_addr(const MemoryRegion *mr);
2129
2130	uint64_t memory_region_get_alignment(const MemoryRegion *mr);
2131	/**
2132	* memory_region_del_subregion: Remove a subregion.
2133	*
2134	* Removes a subregion from its container.
2135	*
2136	* @mr: the container to be updated.
2137	* @subregion: the region being removed; must be a current subregion of @mr.
2138	*/
2139	void memory_region_del_subregion(MemoryRegion *mr,
2140	MemoryRegion *subregion);
2141
2142	/*
2143	* memory_region_set_enabled: dynamically enable or disable a region
2144	*
2145	* Enables or disables a memory region. A disabled memory region
2146	* ignores all accesses to itself and its subregions. It does not
2147	* obscure sibling subregions with lower priority - it simply behaves as
2148	* if it was removed from the hierarchy.
2149	*
2150	* Regions default to being enabled.
2151	*
2152	* @mr: the region to be updated
2153	* @enabled: whether to enable or disable the region
2154	*/
2155	void memory_region_set_enabled(MemoryRegion *mr, bool enabled);
2156
2157	/*
2158	* memory_region_set_address: dynamically update the address of a region
2159	*
2160	* Dynamically updates the address of a region, relative to its container.
2161	* May be used on regions are currently part of a memory hierarchy.
2162	*
2163	* @mr: the region to be updated
2164	* @addr: new address, relative to container region
2165	*/
2166	void memory_region_set_address(MemoryRegion *mr, hwaddr addr);
2167
2168	/*
2169	* memory_region_set_size: dynamically update the size of a region.
2170	*
2171	* Dynamically updates the size of a region.
2172	*
2173	* @mr: the region to be updated
2174	* @size: used size of the region.
2175	*/
2176	void memory_region_set_size(MemoryRegion *mr, uint64_t size);
2177
2178	/*
2179	* memory_region_set_alias_offset: dynamically update a memory alias's offset
2180	*
2181	* Dynamically updates the offset into the target region that an alias points
2182	* to, as if the fourth argument to memory_region_init_alias() has changed.
2183	*
2184	* @mr: the #MemoryRegion to be updated; should be an alias.
2185	* @offset: the new offset into the target memory region
2186	*/
2187	void memory_region_set_alias_offset(MemoryRegion *mr,
2188	hwaddr offset);
2189
2190	/*
2191	* memory_region_set_unmergeable: Set a memory region unmergeable
2192	*
2193	* Mark a memory region unmergeable, resulting in the memory region (or
2194	* everything contained in a memory region container) not getting merged when
2195	* simplifying the address space and notifying memory listeners. Consequently,
2196	* memory listeners will never get notified about ranges that are larger than
2197	* the original memory regions.
2198	*
2199	* This is primarily useful when multiple aliases to a RAM memory region are
2200	* mapped into a memory region container, and updates (e.g., enable/disable or
2201	* map/unmap) of individual memory region aliases are not supposed to affect
2202	* other memory regions in the same container.
2203	*
2204	* @mr: the #MemoryRegion to be updated
2205	* @unmergeable: whether to mark the #MemoryRegion unmergeable
2206	*/
2207	void memory_region_set_unmergeable(MemoryRegion *mr, bool unmergeable);
2208
2209	/**
2210	* memory_region_present: checks if an address relative to a @container
2211	* translates into #MemoryRegion within @container
2212	*
2213	* Answer whether a #MemoryRegion within @container covers the address
2214	* @addr.
2215	*
2216	* @container: a #MemoryRegion within which @addr is a relative address
2217	* @addr: the area within @container to be searched
2218	*/
2219	bool memory_region_present(MemoryRegion *container, hwaddr addr);
2220
2221	/**
2222	* memory_region_is_mapped: returns true if #MemoryRegion is mapped
2223	* into another memory region, which does not necessarily imply that it is
2224	* mapped into an address space.
2225	*
2226	* @mr: a #MemoryRegion which should be checked if it's mapped
2227	*/
2228	bool memory_region_is_mapped(const MemoryRegion *mr);
2229
2230	/**
2231	* memory_region_get_ram_discard_manager: get the #RamDiscardManager for a
2232	* #MemoryRegion
2233	*
2234	* The #RamDiscardManager cannot change while a memory region is mapped.
2235	*
2236	* @mr: the #MemoryRegion
2237	*/
2238	RamDiscardManager memory_region_get_ram_discard_manager(MemoryRegion mr);
2239
2240	/**
2241	* memory_region_has_ram_discard_manager: check whether a #MemoryRegion has a
2242	* #RamDiscardManager assigned
2243	*
2244	* @mr: the #MemoryRegion
2245	*/
2246	static inline bool memory_region_has_ram_discard_manager(MemoryRegion *mr)
2247	{
2248	return !!memory_region_get_ram_discard_manager(mr);
2249	}
2250
2251	/**
2252	* memory_region_add_ram_discard_source: add a #RamDiscardSource for a
2253	* #MemoryRegion
2254	*
2255	* @mr: the #MemoryRegion
2256	* @source: #RamDiscardSource to add
2257	*/
2258	int memory_region_add_ram_discard_source(MemoryRegion mr, RamDiscardSource source);
2259
2260	/**
2261	* memory_region_del_ram_discard_source: remove a #RamDiscardSource for a
2262	* #MemoryRegion
2263	*
2264	* @mr: the #MemoryRegion
2265	* @source: #RamDiscardSource to remove
2266	*
2267	* Returns: 0 on success, or a negative error code on failure.
2268	*/
2269	int memory_region_del_ram_discard_source(MemoryRegion mr, RamDiscardSource source);
2270
2271	/**
2272	* memory_region_find: translate an address/size relative to a
2273	* MemoryRegion into a #MemoryRegionSection.
2274	*
2275	* Locates the first #MemoryRegion within @mr that overlaps the range
2276	* given by @addr and @size.
2277	*
2278	* Returns a #MemoryRegionSection that describes a contiguous overlap.
2279	* It will have the following characteristics:
2280	* - @size = 0 iff no overlap was found
2281	* - @mr is non-%NULL iff an overlap was found
2282	*
2283	* Remember that in the return value the @offset_within_region is
2284	* relative to the returned region (in the .@mr field), not to the
2285	* @mr argument.
2286	*
2287	* Similarly, the .@offset_within_address_space is relative to the
2288	* address space that contains both regions, the passed and the
2289	* returned one. However, in the special case where the @mr argument
2290	* has no container (and thus is the root of the address space), the
2291	* following will hold:
2292	* - @offset_within_address_space >= @addr
2293	* - @offset_within_address_space + .@size <= @addr + @size
2294	*
2295	* @mr: a MemoryRegion within which @addr is a relative address
2296	* @addr: start of the area within @as to be searched
2297	* @size: size of the area to be searched
2298	*/
2299	MemoryRegionSection memory_region_find(MemoryRegion *mr,
2300	hwaddr addr, uint64_t size);
2301
2302	/**
2303	* memory_global_dirty_log_sync: synchronize the dirty log for all memory
2304	*
2305	* Synchronizes the dirty page log for all address spaces.
2306	*
2307	* @last_stage: whether this is the last stage of live migration
2308	*/
2309	void memory_global_dirty_log_sync(bool last_stage);
2310
2311	/**
2312	* memory_global_after_dirty_log_sync: synchronize the dirty log for all memory
2313	*
2314	* Synchronizes the vCPUs with a thread that is reading the dirty bitmap.
2315	* This function must be called after the dirty log bitmap is cleared, and
2316	* before dirty guest memory pages are read. If you are using
2317	* #DirtyBitmapSnapshot, memory_region_snapshot_and_clear_dirty() takes
2318	* care of doing this.
2319	*/
2320	void memory_global_after_dirty_log_sync(void);
2321
2322	/**
2323	* memory_region_transaction_begin: Start a transaction.
2324	*
2325	* During a transaction, changes will be accumulated and made visible
2326	* only when the transaction ends (is committed).
2327	*/
2328	void memory_region_transaction_begin(void);
2329
2330	/**
2331	* memory_region_transaction_commit: Commit a transaction and make changes
2332	* visible to the guest.
2333	*/
2334	void memory_region_transaction_commit(void);
2335
2336	/**
2337	* memory_listener_register: register callbacks to be called when memory
2338	* sections are mapped or unmapped into an address
2339	* space
2340	*
2341	* @listener: an object containing the callbacks to be called
2342	* @filter: if non-%NULL, only regions in this address space will be observed
2343	*/
2344	void memory_listener_register(MemoryListener listener, AddressSpace filter);
2345
2346	/**
2347	* memory_listener_unregister: undo the effect of memory_listener_register()
2348	*
2349	* @listener: an object containing the callbacks to be removed
2350	*/
2351	void memory_listener_unregister(MemoryListener *listener);
2352
2353	/**
2354	* memory_global_dirty_log_start: begin dirty logging for all regions
2355	*
2356	* @flags: purpose of starting dirty log, migration or dirty rate
2357	* @errp: pointer to Error*, to store an error if it happens.
2358	*
2359	* Return: true on success, else false setting @errp with error.
2360	*/
2361	bool memory_global_dirty_log_start(unsigned int flags, Error **errp);
2362
2363	/**
2364	* memory_global_dirty_log_stop: end dirty logging for all regions
2365	*
2366	* @flags: purpose of stopping dirty log, migration or dirty rate
2367	*/
2368	void memory_global_dirty_log_stop(unsigned int flags);
2369
2370	void mtree_info(bool flatview, bool dispatch_tree, bool owner, bool disabled);
2371
2372	bool memory_region_access_valid(MemoryRegion *mr, hwaddr addr,
2373	unsigned size, bool is_write,
2374	MemTxAttrs attrs);
2375
2376	/**
2377	* memory_region_dispatch_read: perform a read directly to the specified
2378	* MemoryRegion.
2379	*
2380	* @mr: #MemoryRegion to access
2381	* @addr: address within that region
2382	* @pval: pointer to uint64_t which the data is written to
2383	* @op: size, sign, and endianness of the memory operation
2384	* @attrs: memory transaction attributes to use for the access
2385	*/
2386	MemTxResult memory_region_dispatch_read(MemoryRegion *mr,
2387	hwaddr addr,
2388	uint64_t *pval,
2389	MemOp op,
2390	MemTxAttrs attrs);
2391	/**
2392	* memory_region_dispatch_write: perform a write directly to the specified
2393	* MemoryRegion.
2394	*
2395	* @mr: #MemoryRegion to access
2396	* @addr: address within that region
2397	* @data: data to write
2398	* @op: size, sign, and endianness of the memory operation
2399	* @attrs: memory transaction attributes to use for the access
2400	*/
2401	MemTxResult memory_region_dispatch_write(MemoryRegion *mr,
2402	hwaddr addr,
2403	uint64_t data,
2404	MemOp op,
2405	MemTxAttrs attrs);
2406
2407	/**
2408	* address_space_init: initializes an address space
2409	*
2410	* @as: an uninitialized #AddressSpace
2411	* @root: a #MemoryRegion that routes addresses for the address space
2412	* @name: an address space name. The name is only used for debugging
2413	* output.
2414	*/
2415	void address_space_init(AddressSpace as, MemoryRegion root, const char *name);
2416
2417	/**
2418	* address_space_destroy: destroy an address space
2419	*
2420	* Releases all resources associated with an address space. After an
2421	* address space is destroyed, the reference the AddressSpace had to
2422	* its root memory region is dropped, which may result in the
2423	* destruction of that memory region as well.
2424	*
2425	* Note that destruction of the AddressSpace is done via RCU;
2426	* it is therefore not valid to free the memory the AddressSpace
2427	* struct is in until after that RCU callback has completed.
2428	* If you want to g_free() the AddressSpace after destruction you
2429	* can do that with address_space_destroy_free().
2430	*
2431	* @as: address space to be destroyed
2432	*/
2433	void address_space_destroy(AddressSpace *as);
2434
2435	/**
2436	* address_space_destroy_free: destroy an address space and free it
2437	*
2438	* This does the same thing as address_space_destroy(), and then also
2439	* frees (via g_free()) the AddressSpace itself once the destruction
2440	* is complete.
2441	*
2442	* @as: address space to be destroyed
2443	*/
2444	void address_space_destroy_free(AddressSpace *as);
2445
2446	/**
2447	* address_space_remove_listeners: unregister all listeners of an address space
2448	*
2449	* Removes all callbacks previously registered with memory_listener_register()
2450	* for @as.
2451	*
2452	* @as: an initialized #AddressSpace
2453	*/
2454	void address_space_remove_listeners(const AddressSpace *as);
2455
2456	/**
2457	* address_space_rw: read from or write to an address space.
2458	*
2459	* Return a MemTxResult indicating whether the operation succeeded
2460	* or failed (eg unassigned memory, device rejected the transaction,
2461	* IOMMU fault).
2462	*
2463	* @as: #AddressSpace to be accessed
2464	* @addr: address within that address space
2465	* @attrs: memory transaction attributes
2466	* @buf: buffer with the data transferred
2467	* @len: the number of bytes to read or write
2468	* @is_write: indicates the transfer direction
2469	*/
2470	MemTxResult address_space_rw(const AddressSpace *as, hwaddr addr,
2471	MemTxAttrs attrs, void *buf,
2472	hwaddr len, bool is_write);
2473
2474	/**
2475	* address_space_write: write to address space.
2476	*
2477	* Return a MemTxResult indicating whether the operation succeeded
2478	* or failed (eg unassigned memory, device rejected the transaction,
2479	* IOMMU fault).
2480	*
2481	* @as: #AddressSpace to be accessed
2482	* @addr: address within that address space
2483	* @attrs: memory transaction attributes
2484	* @buf: buffer with the data transferred
2485	* @len: the number of bytes to write
2486	*/
2487	MemTxResult address_space_write(const AddressSpace *as, hwaddr addr,
2488	MemTxAttrs attrs,
2489	const void *buf, hwaddr len);
2490
2491	/**
2492	* address_space_write_rom: write to address space, including ROM.
2493	*
2494	* This function writes to the specified address space, but will
2495	* write data to both ROM and RAM. This is used for non-guest
2496	* writes like writes from the gdb debug stub or initial loading
2497	* of ROM contents.
2498	*
2499	* Note that portions of the write which attempt to write data to
2500	* a device will be silently ignored -- only real RAM and ROM will
2501	* be written to.
2502	*
2503	* Return a MemTxResult indicating whether the operation succeeded
2504	* or failed (eg unassigned memory, device rejected the transaction,
2505	* IOMMU fault).
2506	*
2507	* @as: #AddressSpace to be accessed
2508	* @addr: address within that address space
2509	* @attrs: memory transaction attributes
2510	* @buf: buffer with the data transferred
2511	* @len: the number of bytes to write
2512	*/
2513	MemTxResult address_space_write_rom(AddressSpace *as, hwaddr addr,
2514	MemTxAttrs attrs,
2515	const void *buf, hwaddr len);
2516
2517	/* address_space_ld*: load from an address space
2518	* address_space_st*: store to an address space
2519	*
2520	* These functions perform a load or store of the byte, word,
2521	* longword or quad to the specified address within the AddressSpace.
2522	* The _le suffixed functions treat the data as little endian;
2523	* _be indicates big endian; no suffix indicates "same endianness
2524	* as guest CPU".
2525	*
2526	* The "guest CPU endianness" accessors are deprecated for use outside
2527	* target-* code; devices should be CPU-agnostic and use either the LE
2528	* or the BE accessors.
2529	*
2530	* @as #AddressSpace to be accessed
2531	* @addr: address within that address space
2532	* @val: data value, for stores
2533	* @attrs: memory transaction attributes
2534	* @result: location to write the success/failure of the transaction;
2535	* if NULL, this information is discarded
2536	*/
2537
2538	#define SUFFIX
2539	#define ARG1 as
2540	#define ARG1_DECL AddressSpace *as
2541	#include "system/memory_ldst.h.inc"
2542
2543	#ifndef TARGET_NOT_USING_LEGACY_LDST_PHYS_API
2544	#define SUFFIX
2545	#define ARG1 as
2546	#define ARG1_DECL AddressSpace *as
2547	#include "system/memory_ldst_phys.h.inc"
2548	#endif
2549
2550	void address_space_flush_icache_range(AddressSpace *as,
2551	hwaddr addr, hwaddr len);
2552
2553	/* address_space_get_iotlb_entry: translate an address into an IOTLB
2554	* entry. Should be called from an RCU critical section.
2555	*/
2556	IOMMUTLBEntry address_space_get_iotlb_entry(AddressSpace *as, hwaddr addr,
2557	bool is_write, MemTxAttrs attrs);
2558
2559	/* address_space_translate: translate an address range into an address space
2560	* into a MemoryRegion and an address range into that section. Should be
2561	* called from an RCU critical section, to avoid that the last reference
2562	* to the returned region disappears after address_space_translate returns.
2563	*
2564	* @fv: #FlatView to be accessed
2565	* @addr: address within that address space
2566	* @xlat: pointer to address within the returned memory region section's
2567	* #MemoryRegion.
2568	* @len: pointer to length
2569	* @is_write: indicates the transfer direction
2570	* @attrs: memory attributes
2571	*/
2572	MemoryRegion flatview_translate(FlatView fv,
2573	hwaddr addr, hwaddr *xlat,
2574	hwaddr *len, bool is_write,
2575	MemTxAttrs attrs);
2576
2577	static inline MemoryRegion address_space_translate(AddressSpace as,
2578	hwaddr addr, hwaddr *xlat,
2579	hwaddr *len, bool is_write,
2580	MemTxAttrs attrs)
2581	{
2582	return flatview_translate(address_space_to_flatview(as),
2583	addr, xlat, len, is_write, attrs);
2584	}
2585
2586	/* address_space_access_valid: check for validity of accessing an address
2587	* space range
2588	*
2589	* Check whether memory is assigned to the given address space range, and
2590	* access is permitted by any IOMMU regions that are active for the address
2591	* space.
2592	*
2593	* For now, addr and len should be aligned to a page size. This limitation
2594	* will be lifted in the future.
2595	*
2596	* @as: #AddressSpace to be accessed
2597	* @addr: address within that address space
2598	* @len: length of the area to be checked
2599	* @is_write: indicates the transfer direction
2600	* @attrs: memory attributes
2601	*/
2602	bool address_space_access_valid(const AddressSpace *as,
2603	hwaddr addr, hwaddr len,
2604	bool is_write, MemTxAttrs attrs);
2605
2606	/**
2607	* address_space_is_io: check whether an guest physical addresses
2608	* whithin an address space is I/O memory.
2609	*
2610	* @as: #AddressSpace to be accessed
2611	* @addr: address within that address space
2612	*/
2613	bool address_space_is_io(AddressSpace *as, hwaddr addr);
2614
2615	/* address_space_map: map a physical memory region into a host virtual address
2616	*
2617	* May map a subset of the requested range, given by and returned in @plen.
2618	* May return %NULL and set *@plen to zero(0), if resources needed to perform
2619	* the mapping are exhausted.
2620	* Use only for reads OR writes - not for read-modify-write operations.
2621	* Use address_space_register_map_client() to know when retrying the map
2622	* operation is likely to succeed.
2623	*
2624	* @as: #AddressSpace to be accessed
2625	* @addr: address within that address space
2626	* @plen: pointer to length of buffer; updated on return
2627	* @is_write: indicates the transfer direction
2628	* @attrs: memory attributes
2629	*/
2630	void address_space_map(AddressSpace as, hwaddr addr,
2631	hwaddr *plen, bool is_write, MemTxAttrs attrs);
2632
2633	/* address_space_unmap: Unmaps a memory region previously mapped by address_space_map()
2634	*
2635	* Will also mark the memory as dirty if @is_write == %true. @access_len gives
2636	* the amount of memory that was actually read or written by the caller.
2637	*
2638	* @as: #AddressSpace used
2639	* @buffer: host pointer as returned by address_space_map()
2640	* @len: buffer length as returned by address_space_map()
2641	* @access_len: amount of data actually transferred
2642	* @is_write: indicates the transfer direction
2643	*/
2644	void address_space_unmap(AddressSpace as, void buffer, hwaddr len,
2645	bool is_write, hwaddr access_len);
2646
2647	/*
2648	* address_space_register_map_client: Register a callback to invoke when
2649	* resources for address_space_map() are available again.
2650	*
2651	* address_space_map may fail when there are not enough resources available,
2652	* such as when bounce buffer memory would exceed the limit. The callback can
2653	* be used to retry the address_space_map operation. Note that the callback
2654	* gets automatically removed after firing.
2655	*
2656	* @as: #AddressSpace to be accessed
2657	* @bh: callback to invoke when address_space_map() retry is appropriate
2658	*/
2659	void address_space_register_map_client(AddressSpace as, QEMUBH bh);
2660
2661	/*
2662	* address_space_unregister_map_client: Unregister a callback that has
2663	* previously been registered and not fired yet.
2664	*
2665	* @as: #AddressSpace to be accessed
2666	* @bh: callback to unregister
2667	*/
2668	void address_space_unregister_map_client(AddressSpace as, QEMUBH bh);
2669
2670	/* Internal functions, part of the implementation of address_space_read. */
2671
2672	/**
2673	* qemu_ram_move: move data from or to ramblock
2674	*
2675	* @dst: destination where the data is moved to
2676	* @src: source where the data is moved from
2677	* @n: length of data to be moved
2678	*
2679	* Move @n bytes from @src to @dst, the memory areas may overlap. This
2680	* provides the same semantics as memmove(), plus an additional stronger
2681	* guarantee: if @n is 1, 2 or 4 or 8 bytes, and @src and @dst are both
2682	* naturally aligned for that access size, then both the load and the store
2683	* will be done as a single atomic access (with the semantics of
2684	* qatomic_read() and qatomic_set()).
2685	*
2686	* This is the underlying function that we use to implement accesses by
2687	* a guest vCPU or a device DMA operation to a ram block. The atomic
2688	* guarantee is needed for two major cases: (A) When the ram block is
2689	* backed by a PCI BAR passed through from a host device (and so it might
2690	* be hardware registers that must be accessed exactly once at the right
2691	* width); (B) When an emulated device updates a data structure shared in
2692	* guest memory with guest software (e.g. a network device's set of tx and
2693	* rx descriptor blocks), if a write to memory is accidentally performed
2694	* multiple times then it can break the guest code when it busy polls the
2695	* guest memory.
2696	*
2697	* We don't attempt to perform the exact access when it would be unaligned
2698	* because this can't be done on all host architectures. Although this is
2699	* strictly speaking not doing what would happen on real hardware, we don't
2700	* think there are going to be situations where that matters in practice.
2701	*/
2702	void qemu_ram_move(void dst, const void src, size_t n);
2703
2704	MemTxResult address_space_read_full(const AddressSpace *as, hwaddr addr,
2705	MemTxAttrs attrs, void *buf, hwaddr len);
2706	MemTxResult flatview_read_continue(FlatView *fv, hwaddr addr,
2707	MemTxAttrs attrs, void *buf,
2708	hwaddr len, hwaddr addr1, hwaddr l,
2709	MemoryRegion *mr);
2710	void qemu_map_ram_ptr(RAMBlock ram_block, ram_addr_t addr);
2711
2712	int memory_access_size(MemoryRegion *mr, unsigned l, hwaddr addr);
2713	bool prepare_mmio_access(MemoryRegion *mr);
2714
2715	static inline bool memory_region_supports_direct_access(const MemoryRegion *mr)
2716	{
2717	/* ROM DEVICE regions only allow direct access if in ROMD mode. */
2718	if (memory_region_is_romd(mr)) {
2719	return true;
2720	}
2721
2722	return memory_region_is_ram(mr);
2723	}
2724
2725	static inline bool memory_access_is_direct(const MemoryRegion *mr,
2726	bool is_write, MemTxAttrs attrs)
2727	{
2728	if (!memory_region_supports_direct_access(mr)) {
2729	return false;
2730	}
2731	/* Debug access can write to ROM. */
2732	if (is_write && !attrs.debug) {
2733	return !mr->readonly && !mr->rom_device;
2734	}
2735	return true;
2736	}
2737
2738	/**
2739	* address_space_read: read from an address space.
2740	*
2741	* Return a MemTxResult indicating whether the operation succeeded
2742	* or failed (eg unassigned memory, device rejected the transaction,
2743	* IOMMU fault). Called within RCU critical section.
2744	*
2745	* @as: #AddressSpace to be accessed
2746	* @addr: address within that address space
2747	* @attrs: memory transaction attributes
2748	* @buf: buffer with the data transferred
2749	* @len: length of the data transferred
2750	*/
2751	static inline __attribute__((__always_inline__))
2752	MemTxResult address_space_read(const AddressSpace *as, hwaddr addr,
2753	MemTxAttrs attrs, void *buf,
2754	hwaddr len)
2755	{
2756	MemTxResult result = MEMTX_OK;
2757	hwaddr l, addr1;
2758	void *ptr;
2759	MemoryRegion *mr;
2760	FlatView *fv;
2761
2762	if (__builtin_constant_p(len)) {
2763	if (len) {
2764	RCU_READ_LOCK_GUARD();
2765	fv = address_space_to_flatview(as);
2766	l = len;
2767	mr = flatview_translate(fv, addr, &addr1, &l, false, attrs);
2768	if (len == l && memory_access_is_direct(mr, false, attrs)) {
2769	ptr = qemu_map_ram_ptr(mr->ram_block, addr1);
2770	qemu_ram_move(buf, ptr, len);
2771	} else {
2772	result = flatview_read_continue(fv, addr, attrs, buf, len,
2773	addr1, l, mr);
2774	}
2775	}
2776	} else {
2777	result = address_space_read_full(as, addr, attrs, buf, len);
2778	}
2779	return result;
2780	}
2781
2782	/**
2783	* address_space_set: Fill address space with a constant byte.
2784	*
2785	* Return a MemTxResult indicating whether the operation succeeded
2786	* or failed (eg unassigned memory, device rejected the transaction,
2787	* IOMMU fault).
2788	*
2789	* @as: #AddressSpace to be accessed
2790	* @addr: address within that address space
2791	* @c: constant byte to fill the memory
2792	* @len: the number of bytes to fill with the constant byte
2793	* @attrs: memory transaction attributes
2794	*/
2795	MemTxResult address_space_set(const AddressSpace *as, hwaddr addr,
2796	uint8_t c, hwaddr len, MemTxAttrs attrs);
2797
2798	/* Coalesced MMIO regions are areas where write operations can be reordered.
2799	* This usually implies that write operations are side-effect free. This allows
2800	* batching which can make a major impact on performance when using
2801	* virtualization.
2802	*/
2803	void qemu_flush_coalesced_mmio_buffer(void);
2804
2805	/*
2806	* Inhibit technologies that require discarding of pages in RAM blocks, e.g.,
2807	* to manage the actual amount of memory consumed by the VM (then, the memory
2808	* provided by RAM blocks might be bigger than the desired memory consumption).
2809	* This must be set if:
2810	* - Discarding parts of a RAM blocks does not result in the change being
2811	* reflected in the VM and the pages getting freed.
2812	* - All memory in RAM blocks is pinned or duplicated, invaldiating any previous
2813	* discards blindly.
2814	* - Discarding parts of a RAM blocks will result in integrity issues (e.g.,
2815	* encrypted VMs).
2816	* Technologies that only temporarily pin the current working set of a
2817	* driver are fine, because we don't expect such pages to be discarded
2818	* (esp. based on guest action like balloon inflation).
2819	*
2820	* This is not to be used to protect from concurrent discards (esp.,
2821	* postcopy).
2822	*
2823	* Returns 0 if successful. Returns -EBUSY if a technology that relies on
2824	* discards to work reliably is active.
2825	*/
2826	int ram_block_discard_disable(bool state);
2827
2828	/*
2829	* See ram_block_discard_disable(): only disable uncoordinated discards,
2830	* keeping coordinated discards (via the RamDiscardManager) enabled.
2831	*/
2832	int ram_block_uncoordinated_discard_disable(bool state);
2833
2834	/*
2835	* Inhibit technologies that disable discarding of pages in RAM blocks.
2836	*
2837	* Returns 0 if successful. Returns -EBUSY if discards are already set to
2838	* broken.
2839	*/
2840	int ram_block_discard_require(bool state);
2841
2842	/*
2843	* See ram_block_discard_require(): only inhibit technologies that disable
2844	* uncoordinated discarding of pages in RAM blocks, allowing co-existence with
2845	* technologies that only inhibit uncoordinated discards (via the
2846	* RamDiscardManager).
2847	*/
2848	int ram_block_coordinated_discard_require(bool state);
2849
2850	/*
2851	* Test if any discarding of memory in ram blocks is disabled.
2852	*/
2853	bool ram_block_discard_is_disabled(void);
2854
2855	/*
2856	* Test if any discarding of memory in ram blocks is required to work reliably.
2857	*/
2858	bool ram_block_discard_is_required(void);
2859
2860	void ram_block_add_cpr_blocker(RAMBlock rb, Error *errp);
2861	void ram_block_del_cpr_blocker(RAMBlock *rb);
2862
2863	void gpa2hva(MemoryRegion p_mr, hwaddr addr, uint64_t size, Error *errp);
2864
2865	#endif