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