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