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