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/ramlist.h" 23 #include "qemu/queue.h" 24 #include "qemu/int128.h" 25 #include "qemu/notify.h" 26 #include "qom/object.h" 27 #include "qemu/rcu.h" 28 29 #define RAM_ADDR_INVALID (~(ram_addr_t)0) 30 31 #define MAX_PHYS_ADDR_SPACE_BITS 62 32 #define MAX_PHYS_ADDR (((hwaddr)1 << MAX_PHYS_ADDR_SPACE_BITS) - 1) 33 34 #define TYPE_MEMORY_REGION "qemu:memory-region" 35 #define MEMORY_REGION(obj) \ 36 OBJECT_CHECK(MemoryRegion, (obj), TYPE_MEMORY_REGION) 37 38 typedef struct MemoryRegionOps MemoryRegionOps; 39 typedef struct MemoryRegionMmio MemoryRegionMmio; 40 41 struct MemoryRegionMmio { 42 CPUReadMemoryFunc *read[3]; 43 CPUWriteMemoryFunc *write[3]; 44 }; 45 46 typedef struct IOMMUTLBEntry IOMMUTLBEntry; 47 48 /* See address_space_translate: bit 0 is read, bit 1 is write. */ 49 typedef enum { 50 IOMMU_NONE = 0, 51 IOMMU_RO = 1, 52 IOMMU_WO = 2, 53 IOMMU_RW = 3, 54 } IOMMUAccessFlags; 55 56 #define IOMMU_ACCESS_FLAG(r, w) (((r) ? IOMMU_RO : 0) | ((w) ? IOMMU_WO : 0)) 57 58 struct IOMMUTLBEntry { 59 AddressSpace *target_as; 60 hwaddr iova; 61 hwaddr translated_addr; 62 hwaddr addr_mask; /* 0xfff = 4k translation */ 63 IOMMUAccessFlags perm; 64 }; 65 66 /* 67 * Bitmap for different IOMMUNotifier capabilities. Each notifier can 68 * register with one or multiple IOMMU Notifier capability bit(s). 69 */ 70 typedef enum { 71 IOMMU_NOTIFIER_NONE = 0, 72 /* Notify cache invalidations */ 73 IOMMU_NOTIFIER_UNMAP = 0x1, 74 /* Notify entry changes (newly created entries) */ 75 IOMMU_NOTIFIER_MAP = 0x2, 76 } IOMMUNotifierFlag; 77 78 #define IOMMU_NOTIFIER_ALL (IOMMU_NOTIFIER_MAP | IOMMU_NOTIFIER_UNMAP) 79 80 struct IOMMUNotifier; 81 typedef void (*IOMMUNotify)(struct IOMMUNotifier *notifier, 82 IOMMUTLBEntry *data); 83 84 struct IOMMUNotifier { 85 IOMMUNotify notify; 86 IOMMUNotifierFlag notifier_flags; 87 /* Notify for address space range start <= addr <= end */ 88 hwaddr start; 89 hwaddr end; 90 QLIST_ENTRY(IOMMUNotifier) node; 91 }; 92 typedef struct IOMMUNotifier IOMMUNotifier; 93 94 static inline void iommu_notifier_init(IOMMUNotifier *n, IOMMUNotify fn, 95 IOMMUNotifierFlag flags, 96 hwaddr start, hwaddr end) 97 { 98 n->notify = fn; 99 n->notifier_flags = flags; 100 n->start = start; 101 n->end = end; 102 } 103 104 /* New-style MMIO accessors can indicate that the transaction failed. 105 * A zero (MEMTX_OK) response means success; anything else is a failure 106 * of some kind. The memory subsystem will bitwise-OR together results 107 * if it is synthesizing an operation from multiple smaller accesses. 108 */ 109 #define MEMTX_OK 0 110 #define MEMTX_ERROR (1U << 0) /* device returned an error */ 111 #define MEMTX_DECODE_ERROR (1U << 1) /* nothing at that address */ 112 typedef uint32_t MemTxResult; 113 114 /* 115 * Memory region callbacks 116 */ 117 struct MemoryRegionOps { 118 /* Read from the memory region. @addr is relative to @mr; @size is 119 * in bytes. */ 120 uint64_t (*read)(void *opaque, 121 hwaddr addr, 122 unsigned size); 123 /* Write to the memory region. @addr is relative to @mr; @size is 124 * in bytes. */ 125 void (*write)(void *opaque, 126 hwaddr addr, 127 uint64_t data, 128 unsigned size); 129 130 MemTxResult (*read_with_attrs)(void *opaque, 131 hwaddr addr, 132 uint64_t *data, 133 unsigned size, 134 MemTxAttrs attrs); 135 MemTxResult (*write_with_attrs)(void *opaque, 136 hwaddr addr, 137 uint64_t data, 138 unsigned size, 139 MemTxAttrs attrs); 140 /* Instruction execution pre-callback: 141 * @addr is the address of the access relative to the @mr. 142 * @size is the size of the area returned by the callback. 143 * @offset is the location of the pointer inside @mr. 144 * 145 * Returns a pointer to a location which contains guest code. 146 */ 147 void *(*request_ptr)(void *opaque, hwaddr addr, unsigned *size, 148 unsigned *offset); 149 150 enum device_endian endianness; 151 /* Guest-visible constraints: */ 152 struct { 153 /* If nonzero, specify bounds on access sizes beyond which a machine 154 * check is thrown. 155 */ 156 unsigned min_access_size; 157 unsigned max_access_size; 158 /* If true, unaligned accesses are supported. Otherwise unaligned 159 * accesses throw machine checks. 160 */ 161 bool unaligned; 162 /* 163 * If present, and returns #false, the transaction is not accepted 164 * by the device (and results in machine dependent behaviour such 165 * as a machine check exception). 166 */ 167 bool (*accepts)(void *opaque, hwaddr addr, 168 unsigned size, bool is_write); 169 } valid; 170 /* Internal implementation constraints: */ 171 struct { 172 /* If nonzero, specifies the minimum size implemented. Smaller sizes 173 * will be rounded upwards and a partial result will be returned. 174 */ 175 unsigned min_access_size; 176 /* If nonzero, specifies the maximum size implemented. Larger sizes 177 * will be done as a series of accesses with smaller sizes. 178 */ 179 unsigned max_access_size; 180 /* If true, unaligned accesses are supported. Otherwise all accesses 181 * are converted to (possibly multiple) naturally aligned accesses. 182 */ 183 bool unaligned; 184 } impl; 185 186 /* If .read and .write are not present, old_mmio may be used for 187 * backwards compatibility with old mmio registration 188 */ 189 const MemoryRegionMmio old_mmio; 190 }; 191 192 typedef struct MemoryRegionIOMMUOps MemoryRegionIOMMUOps; 193 194 struct MemoryRegionIOMMUOps { 195 /* 196 * Return a TLB entry that contains a given address. Flag should 197 * be the access permission of this translation operation. We can 198 * set flag to IOMMU_NONE to mean that we don't need any 199 * read/write permission checks, like, when for region replay. 200 */ 201 IOMMUTLBEntry (*translate)(MemoryRegion *iommu, hwaddr addr, 202 IOMMUAccessFlags flag); 203 /* Returns minimum supported page size */ 204 uint64_t (*get_min_page_size)(MemoryRegion *iommu); 205 /* Called when IOMMU Notifier flag changed */ 206 void (*notify_flag_changed)(MemoryRegion *iommu, 207 IOMMUNotifierFlag old_flags, 208 IOMMUNotifierFlag new_flags); 209 /* Set this up to provide customized IOMMU replay function */ 210 void (*replay)(MemoryRegion *iommu, IOMMUNotifier *notifier); 211 }; 212 213 typedef struct CoalescedMemoryRange CoalescedMemoryRange; 214 typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd; 215 216 struct MemoryRegion { 217 Object parent_obj; 218 219 /* All fields are private - violators will be prosecuted */ 220 221 /* The following fields should fit in a cache line */ 222 bool romd_mode; 223 bool ram; 224 bool subpage; 225 bool readonly; /* For RAM regions */ 226 bool rom_device; 227 bool flush_coalesced_mmio; 228 bool global_locking; 229 uint8_t dirty_log_mask; 230 RAMBlock *ram_block; 231 Object *owner; 232 const MemoryRegionIOMMUOps *iommu_ops; 233 234 const MemoryRegionOps *ops; 235 void *opaque; 236 MemoryRegion *container; 237 Int128 size; 238 hwaddr addr; 239 void (*destructor)(MemoryRegion *mr); 240 uint64_t align; 241 bool terminates; 242 bool ram_device; 243 bool enabled; 244 bool warning_printed; /* For reservations */ 245 uint8_t vga_logging_count; 246 MemoryRegion *alias; 247 hwaddr alias_offset; 248 int32_t priority; 249 QTAILQ_HEAD(subregions, MemoryRegion) subregions; 250 QTAILQ_ENTRY(MemoryRegion) subregions_link; 251 QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced; 252 const char *name; 253 unsigned ioeventfd_nb; 254 MemoryRegionIoeventfd *ioeventfds; 255 QLIST_HEAD(, IOMMUNotifier) iommu_notify; 256 IOMMUNotifierFlag iommu_notify_flags; 257 }; 258 259 #define IOMMU_NOTIFIER_FOREACH(n, mr) \ 260 QLIST_FOREACH((n), &(mr)->iommu_notify, node) 261 262 /** 263 * MemoryListener: callbacks structure for updates to the physical memory map 264 * 265 * Allows a component to adjust to changes in the guest-visible memory map. 266 * Use with memory_listener_register() and memory_listener_unregister(). 267 */ 268 struct MemoryListener { 269 void (*begin)(MemoryListener *listener); 270 void (*commit)(MemoryListener *listener); 271 void (*region_add)(MemoryListener *listener, MemoryRegionSection *section); 272 void (*region_del)(MemoryListener *listener, MemoryRegionSection *section); 273 void (*region_nop)(MemoryListener *listener, MemoryRegionSection *section); 274 void (*log_start)(MemoryListener *listener, MemoryRegionSection *section, 275 int old, int new); 276 void (*log_stop)(MemoryListener *listener, MemoryRegionSection *section, 277 int old, int new); 278 void (*log_sync)(MemoryListener *listener, MemoryRegionSection *section); 279 void (*log_global_start)(MemoryListener *listener); 280 void (*log_global_stop)(MemoryListener *listener); 281 void (*eventfd_add)(MemoryListener *listener, MemoryRegionSection *section, 282 bool match_data, uint64_t data, EventNotifier *e); 283 void (*eventfd_del)(MemoryListener *listener, MemoryRegionSection *section, 284 bool match_data, uint64_t data, EventNotifier *e); 285 void (*coalesced_mmio_add)(MemoryListener *listener, MemoryRegionSection *section, 286 hwaddr addr, hwaddr len); 287 void (*coalesced_mmio_del)(MemoryListener *listener, MemoryRegionSection *section, 288 hwaddr addr, hwaddr len); 289 /* Lower = earlier (during add), later (during del) */ 290 unsigned priority; 291 AddressSpace *address_space; 292 QTAILQ_ENTRY(MemoryListener) link; 293 QTAILQ_ENTRY(MemoryListener) link_as; 294 }; 295 296 /** 297 * AddressSpace: describes a mapping of addresses to #MemoryRegion objects 298 */ 299 struct AddressSpace { 300 /* All fields are private. */ 301 struct rcu_head rcu; 302 char *name; 303 MemoryRegion *root; 304 int ref_count; 305 bool malloced; 306 307 /* Accessed via RCU. */ 308 struct FlatView *current_map; 309 310 int ioeventfd_nb; 311 struct MemoryRegionIoeventfd *ioeventfds; 312 struct AddressSpaceDispatch *dispatch; 313 struct AddressSpaceDispatch *next_dispatch; 314 MemoryListener dispatch_listener; 315 QTAILQ_HEAD(memory_listeners_as, MemoryListener) listeners; 316 QTAILQ_ENTRY(AddressSpace) address_spaces_link; 317 }; 318 319 /** 320 * MemoryRegionSection: describes a fragment of a #MemoryRegion 321 * 322 * @mr: the region, or %NULL if empty 323 * @address_space: the address space the region is mapped in 324 * @offset_within_region: the beginning of the section, relative to @mr's start 325 * @size: the size of the section; will not exceed @mr's boundaries 326 * @offset_within_address_space: the address of the first byte of the section 327 * relative to the region's address space 328 * @readonly: writes to this section are ignored 329 */ 330 struct MemoryRegionSection { 331 MemoryRegion *mr; 332 AddressSpace *address_space; 333 hwaddr offset_within_region; 334 Int128 size; 335 hwaddr offset_within_address_space; 336 bool readonly; 337 }; 338 339 /** 340 * memory_region_init: Initialize a memory region 341 * 342 * The region typically acts as a container for other memory regions. Use 343 * memory_region_add_subregion() to add subregions. 344 * 345 * @mr: the #MemoryRegion to be initialized 346 * @owner: the object that tracks the region's reference count 347 * @name: used for debugging; not visible to the user or ABI 348 * @size: size of the region; any subregions beyond this size will be clipped 349 */ 350 void memory_region_init(MemoryRegion *mr, 351 struct Object *owner, 352 const char *name, 353 uint64_t size); 354 355 /** 356 * memory_region_ref: Add 1 to a memory region's reference count 357 * 358 * Whenever memory regions are accessed outside the BQL, they need to be 359 * preserved against hot-unplug. MemoryRegions actually do not have their 360 * own reference count; they piggyback on a QOM object, their "owner". 361 * This function adds a reference to the owner. 362 * 363 * All MemoryRegions must have an owner if they can disappear, even if the 364 * device they belong to operates exclusively under the BQL. This is because 365 * the region could be returned at any time by memory_region_find, and this 366 * is usually under guest control. 367 * 368 * @mr: the #MemoryRegion 369 */ 370 void memory_region_ref(MemoryRegion *mr); 371 372 /** 373 * memory_region_unref: Remove 1 to a memory region's reference count 374 * 375 * Whenever memory regions are accessed outside the BQL, they need to be 376 * preserved against hot-unplug. MemoryRegions actually do not have their 377 * own reference count; they piggyback on a QOM object, their "owner". 378 * This function removes a reference to the owner and possibly destroys it. 379 * 380 * @mr: the #MemoryRegion 381 */ 382 void memory_region_unref(MemoryRegion *mr); 383 384 /** 385 * memory_region_init_io: Initialize an I/O memory region. 386 * 387 * Accesses into the region will cause the callbacks in @ops to be called. 388 * if @size is nonzero, subregions will be clipped to @size. 389 * 390 * @mr: the #MemoryRegion to be initialized. 391 * @owner: the object that tracks the region's reference count 392 * @ops: a structure containing read and write callbacks to be used when 393 * I/O is performed on the region. 394 * @opaque: passed to the read and write callbacks of the @ops structure. 395 * @name: used for debugging; not visible to the user or ABI 396 * @size: size of the region. 397 */ 398 void memory_region_init_io(MemoryRegion *mr, 399 struct Object *owner, 400 const MemoryRegionOps *ops, 401 void *opaque, 402 const char *name, 403 uint64_t size); 404 405 /** 406 * memory_region_init_ram: Initialize RAM memory region. Accesses into the 407 * region will modify memory directly. 408 * 409 * @mr: the #MemoryRegion to be initialized. 410 * @owner: the object that tracks the region's reference count 411 * @name: Region name, becomes part of RAMBlock name used in migration stream 412 * must be unique within any device 413 * @size: size of the region. 414 * @errp: pointer to Error*, to store an error if it happens. 415 */ 416 void memory_region_init_ram(MemoryRegion *mr, 417 struct Object *owner, 418 const char *name, 419 uint64_t size, 420 Error **errp); 421 422 /** 423 * memory_region_init_resizeable_ram: Initialize memory region with resizeable 424 * RAM. Accesses into the region will 425 * modify memory directly. Only an initial 426 * portion of this RAM is actually used. 427 * The used size can change across reboots. 428 * 429 * @mr: the #MemoryRegion to be initialized. 430 * @owner: the object that tracks the region's reference count 431 * @name: Region name, becomes part of RAMBlock name used in migration stream 432 * must be unique within any device 433 * @size: used size of the region. 434 * @max_size: max size of the region. 435 * @resized: callback to notify owner about used size change. 436 * @errp: pointer to Error*, to store an error if it happens. 437 */ 438 void memory_region_init_resizeable_ram(MemoryRegion *mr, 439 struct Object *owner, 440 const char *name, 441 uint64_t size, 442 uint64_t max_size, 443 void (*resized)(const char*, 444 uint64_t length, 445 void *host), 446 Error **errp); 447 #ifdef __linux__ 448 /** 449 * memory_region_init_ram_from_file: Initialize RAM memory region with a 450 * mmap-ed backend. 451 * 452 * @mr: the #MemoryRegion to be initialized. 453 * @owner: the object that tracks the region's reference count 454 * @name: Region name, becomes part of RAMBlock name used in migration stream 455 * must be unique within any device 456 * @size: size of the region. 457 * @share: %true if memory must be mmaped with the MAP_SHARED flag 458 * @path: the path in which to allocate the RAM. 459 * @errp: pointer to Error*, to store an error if it happens. 460 */ 461 void memory_region_init_ram_from_file(MemoryRegion *mr, 462 struct Object *owner, 463 const char *name, 464 uint64_t size, 465 bool share, 466 const char *path, 467 Error **errp); 468 469 /** 470 * memory_region_init_ram_from_fd: Initialize RAM memory region with a 471 * mmap-ed backend. 472 * 473 * @mr: the #MemoryRegion to be initialized. 474 * @owner: the object that tracks the region's reference count 475 * @name: the name of the region. 476 * @size: size of the region. 477 * @share: %true if memory must be mmaped with the MAP_SHARED flag 478 * @fd: the fd to mmap. 479 * @errp: pointer to Error*, to store an error if it happens. 480 */ 481 void memory_region_init_ram_from_fd(MemoryRegion *mr, 482 struct Object *owner, 483 const char *name, 484 uint64_t size, 485 bool share, 486 int fd, 487 Error **errp); 488 #endif 489 490 /** 491 * memory_region_init_ram_ptr: Initialize RAM memory region from a 492 * user-provided pointer. Accesses into the 493 * region will modify memory directly. 494 * 495 * @mr: the #MemoryRegion to be initialized. 496 * @owner: the object that tracks the region's reference count 497 * @name: Region name, becomes part of RAMBlock name used in migration stream 498 * must be unique within any device 499 * @size: size of the region. 500 * @ptr: memory to be mapped; must contain at least @size bytes. 501 */ 502 void memory_region_init_ram_ptr(MemoryRegion *mr, 503 struct Object *owner, 504 const char *name, 505 uint64_t size, 506 void *ptr); 507 508 /** 509 * memory_region_init_ram_device_ptr: Initialize RAM device memory region from 510 * a user-provided pointer. 511 * 512 * A RAM device represents a mapping to a physical device, such as to a PCI 513 * MMIO BAR of an vfio-pci assigned device. The memory region may be mapped 514 * into the VM address space and access to the region will modify memory 515 * directly. However, the memory region should not be included in a memory 516 * dump (device may not be enabled/mapped at the time of the dump), and 517 * operations incompatible with manipulating MMIO should be avoided. Replaces 518 * skip_dump flag. 519 * 520 * @mr: the #MemoryRegion to be initialized. 521 * @owner: the object that tracks the region's reference count 522 * @name: the name of the region. 523 * @size: size of the region. 524 * @ptr: memory to be mapped; must contain at least @size bytes. 525 */ 526 void memory_region_init_ram_device_ptr(MemoryRegion *mr, 527 struct Object *owner, 528 const char *name, 529 uint64_t size, 530 void *ptr); 531 532 /** 533 * memory_region_init_alias: Initialize a memory region that aliases all or a 534 * part of another memory region. 535 * 536 * @mr: the #MemoryRegion to be initialized. 537 * @owner: the object that tracks the region's reference count 538 * @name: used for debugging; not visible to the user or ABI 539 * @orig: the region to be referenced; @mr will be equivalent to 540 * @orig between @offset and @offset + @size - 1. 541 * @offset: start of the section in @orig to be referenced. 542 * @size: size of the region. 543 */ 544 void memory_region_init_alias(MemoryRegion *mr, 545 struct Object *owner, 546 const char *name, 547 MemoryRegion *orig, 548 hwaddr offset, 549 uint64_t size); 550 551 /** 552 * memory_region_init_rom: Initialize a ROM memory region. 553 * 554 * This has the same effect as calling memory_region_init_ram() 555 * and then marking the resulting region read-only with 556 * memory_region_set_readonly(). 557 * 558 * @mr: the #MemoryRegion to be initialized. 559 * @owner: the object that tracks the region's reference count 560 * @name: Region name, becomes part of RAMBlock name used in migration stream 561 * must be unique within any device 562 * @size: size of the region. 563 * @errp: pointer to Error*, to store an error if it happens. 564 */ 565 void memory_region_init_rom(MemoryRegion *mr, 566 struct Object *owner, 567 const char *name, 568 uint64_t size, 569 Error **errp); 570 571 /** 572 * memory_region_init_rom_device: Initialize a ROM memory region. Writes are 573 * handled via callbacks. 574 * 575 * @mr: the #MemoryRegion to be initialized. 576 * @owner: the object that tracks the region's reference count 577 * @ops: callbacks for write access handling (must not be NULL). 578 * @name: Region name, becomes part of RAMBlock name used in migration stream 579 * must be unique within any device 580 * @size: size of the region. 581 * @errp: pointer to Error*, to store an error if it happens. 582 */ 583 void memory_region_init_rom_device(MemoryRegion *mr, 584 struct Object *owner, 585 const MemoryRegionOps *ops, 586 void *opaque, 587 const char *name, 588 uint64_t size, 589 Error **errp); 590 591 /** 592 * memory_region_init_reservation: Initialize a memory region that reserves 593 * I/O space. 594 * 595 * A reservation region primariy serves debugging purposes. It claims I/O 596 * space that is not supposed to be handled by QEMU itself. Any access via 597 * the memory API will cause an abort(). 598 * This function is deprecated. Use memory_region_init_io() with NULL 599 * callbacks instead. 600 * 601 * @mr: the #MemoryRegion to be initialized 602 * @owner: the object that tracks the region's reference count 603 * @name: used for debugging; not visible to the user or ABI 604 * @size: size of the region. 605 */ 606 static inline void memory_region_init_reservation(MemoryRegion *mr, 607 Object *owner, 608 const char *name, 609 uint64_t size) 610 { 611 memory_region_init_io(mr, owner, NULL, mr, name, size); 612 } 613 614 /** 615 * memory_region_init_iommu: Initialize a memory region that translates 616 * addresses 617 * 618 * An IOMMU region translates addresses and forwards accesses to a target 619 * memory region. 620 * 621 * @mr: the #MemoryRegion to be initialized 622 * @owner: the object that tracks the region's reference count 623 * @ops: a function that translates addresses into the @target region 624 * @name: used for debugging; not visible to the user or ABI 625 * @size: size of the region. 626 */ 627 void memory_region_init_iommu(MemoryRegion *mr, 628 struct Object *owner, 629 const MemoryRegionIOMMUOps *ops, 630 const char *name, 631 uint64_t size); 632 633 /** 634 * memory_region_owner: get a memory region's owner. 635 * 636 * @mr: the memory region being queried. 637 */ 638 struct Object *memory_region_owner(MemoryRegion *mr); 639 640 /** 641 * memory_region_size: get a memory region's size. 642 * 643 * @mr: the memory region being queried. 644 */ 645 uint64_t memory_region_size(MemoryRegion *mr); 646 647 /** 648 * memory_region_is_ram: check whether a memory region is random access 649 * 650 * Returns %true is a memory region is random access. 651 * 652 * @mr: the memory region being queried 653 */ 654 static inline bool memory_region_is_ram(MemoryRegion *mr) 655 { 656 return mr->ram; 657 } 658 659 /** 660 * memory_region_is_ram_device: check whether a memory region is a ram device 661 * 662 * Returns %true is a memory region is a device backed ram region 663 * 664 * @mr: the memory region being queried 665 */ 666 bool memory_region_is_ram_device(MemoryRegion *mr); 667 668 /** 669 * memory_region_is_romd: check whether a memory region is in ROMD mode 670 * 671 * Returns %true if a memory region is a ROM device and currently set to allow 672 * direct reads. 673 * 674 * @mr: the memory region being queried 675 */ 676 static inline bool memory_region_is_romd(MemoryRegion *mr) 677 { 678 return mr->rom_device && mr->romd_mode; 679 } 680 681 /** 682 * memory_region_is_iommu: check whether a memory region is an iommu 683 * 684 * Returns %true is a memory region is an iommu. 685 * 686 * @mr: the memory region being queried 687 */ 688 static inline bool memory_region_is_iommu(MemoryRegion *mr) 689 { 690 if (mr->alias) { 691 return memory_region_is_iommu(mr->alias); 692 } 693 return mr->iommu_ops; 694 } 695 696 697 /** 698 * memory_region_iommu_get_min_page_size: get minimum supported page size 699 * for an iommu 700 * 701 * Returns minimum supported page size for an iommu. 702 * 703 * @mr: the memory region being queried 704 */ 705 uint64_t memory_region_iommu_get_min_page_size(MemoryRegion *mr); 706 707 /** 708 * memory_region_notify_iommu: notify a change in an IOMMU translation entry. 709 * 710 * The notification type will be decided by entry.perm bits: 711 * 712 * - For UNMAP (cache invalidation) notifies: set entry.perm to IOMMU_NONE. 713 * - For MAP (newly added entry) notifies: set entry.perm to the 714 * permission of the page (which is definitely !IOMMU_NONE). 715 * 716 * Note: for any IOMMU implementation, an in-place mapping change 717 * should be notified with an UNMAP followed by a MAP. 718 * 719 * @mr: the memory region that was changed 720 * @entry: the new entry in the IOMMU translation table. The entry 721 * replaces all old entries for the same virtual I/O address range. 722 * Deleted entries have .@perm == 0. 723 */ 724 void memory_region_notify_iommu(MemoryRegion *mr, 725 IOMMUTLBEntry entry); 726 727 /** 728 * memory_region_notify_one: notify a change in an IOMMU translation 729 * entry to a single notifier 730 * 731 * This works just like memory_region_notify_iommu(), but it only 732 * notifies a specific notifier, not all of them. 733 * 734 * @notifier: the notifier to be notified 735 * @entry: the new entry in the IOMMU translation table. The entry 736 * replaces all old entries for the same virtual I/O address range. 737 * Deleted entries have .@perm == 0. 738 */ 739 void memory_region_notify_one(IOMMUNotifier *notifier, 740 IOMMUTLBEntry *entry); 741 742 /** 743 * memory_region_register_iommu_notifier: register a notifier for changes to 744 * IOMMU translation entries. 745 * 746 * @mr: the memory region to observe 747 * @n: the IOMMUNotifier to be added; the notify callback receives a 748 * pointer to an #IOMMUTLBEntry as the opaque value; the pointer 749 * ceases to be valid on exit from the notifier. 750 */ 751 void memory_region_register_iommu_notifier(MemoryRegion *mr, 752 IOMMUNotifier *n); 753 754 /** 755 * memory_region_iommu_replay: replay existing IOMMU translations to 756 * a notifier with the minimum page granularity returned by 757 * mr->iommu_ops->get_page_size(). 758 * 759 * @mr: the memory region to observe 760 * @n: the notifier to which to replay iommu mappings 761 */ 762 void memory_region_iommu_replay(MemoryRegion *mr, IOMMUNotifier *n); 763 764 /** 765 * memory_region_iommu_replay_all: replay existing IOMMU translations 766 * to all the notifiers registered. 767 * 768 * @mr: the memory region to observe 769 */ 770 void memory_region_iommu_replay_all(MemoryRegion *mr); 771 772 /** 773 * memory_region_unregister_iommu_notifier: unregister a notifier for 774 * changes to IOMMU translation entries. 775 * 776 * @mr: the memory region which was observed and for which notity_stopped() 777 * needs to be called 778 * @n: the notifier to be removed. 779 */ 780 void memory_region_unregister_iommu_notifier(MemoryRegion *mr, 781 IOMMUNotifier *n); 782 783 /** 784 * memory_region_name: get a memory region's name 785 * 786 * Returns the string that was used to initialize the memory region. 787 * 788 * @mr: the memory region being queried 789 */ 790 const char *memory_region_name(const MemoryRegion *mr); 791 792 /** 793 * memory_region_is_logging: return whether a memory region is logging writes 794 * 795 * Returns %true if the memory region is logging writes for the given client 796 * 797 * @mr: the memory region being queried 798 * @client: the client being queried 799 */ 800 bool memory_region_is_logging(MemoryRegion *mr, uint8_t client); 801 802 /** 803 * memory_region_get_dirty_log_mask: return the clients for which a 804 * memory region is logging writes. 805 * 806 * Returns a bitmap of clients, in which the DIRTY_MEMORY_* constants 807 * are the bit indices. 808 * 809 * @mr: the memory region being queried 810 */ 811 uint8_t memory_region_get_dirty_log_mask(MemoryRegion *mr); 812 813 /** 814 * memory_region_is_rom: check whether a memory region is ROM 815 * 816 * Returns %true is a memory region is read-only memory. 817 * 818 * @mr: the memory region being queried 819 */ 820 static inline bool memory_region_is_rom(MemoryRegion *mr) 821 { 822 return mr->ram && mr->readonly; 823 } 824 825 826 /** 827 * memory_region_get_fd: Get a file descriptor backing a RAM memory region. 828 * 829 * Returns a file descriptor backing a file-based RAM memory region, 830 * or -1 if the region is not a file-based RAM memory region. 831 * 832 * @mr: the RAM or alias memory region being queried. 833 */ 834 int memory_region_get_fd(MemoryRegion *mr); 835 836 /** 837 * memory_region_from_host: Convert a pointer into a RAM memory region 838 * and an offset within it. 839 * 840 * Given a host pointer inside a RAM memory region (created with 841 * memory_region_init_ram() or memory_region_init_ram_ptr()), return 842 * the MemoryRegion and the offset within it. 843 * 844 * Use with care; by the time this function returns, the returned pointer is 845 * not protected by RCU anymore. If the caller is not within an RCU critical 846 * section and does not hold the iothread lock, it must have other means of 847 * protecting the pointer, such as a reference to the region that includes 848 * the incoming ram_addr_t. 849 * 850 * @mr: the memory region being queried. 851 */ 852 MemoryRegion *memory_region_from_host(void *ptr, ram_addr_t *offset); 853 854 /** 855 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region. 856 * 857 * Returns a host pointer to a RAM memory region (created with 858 * memory_region_init_ram() or memory_region_init_ram_ptr()). 859 * 860 * Use with care; by the time this function returns, the returned pointer is 861 * not protected by RCU anymore. If the caller is not within an RCU critical 862 * section and does not hold the iothread lock, it must have other means of 863 * protecting the pointer, such as a reference to the region that includes 864 * the incoming ram_addr_t. 865 * 866 * @mr: the memory region being queried. 867 */ 868 void *memory_region_get_ram_ptr(MemoryRegion *mr); 869 870 /* memory_region_ram_resize: Resize a RAM region. 871 * 872 * Only legal before guest might have detected the memory size: e.g. on 873 * incoming migration, or right after reset. 874 * 875 * @mr: a memory region created with @memory_region_init_resizeable_ram. 876 * @newsize: the new size the region 877 * @errp: pointer to Error*, to store an error if it happens. 878 */ 879 void memory_region_ram_resize(MemoryRegion *mr, ram_addr_t newsize, 880 Error **errp); 881 882 /** 883 * memory_region_set_log: Turn dirty logging on or off for a region. 884 * 885 * Turns dirty logging on or off for a specified client (display, migration). 886 * Only meaningful for RAM regions. 887 * 888 * @mr: the memory region being updated. 889 * @log: whether dirty logging is to be enabled or disabled. 890 * @client: the user of the logging information; %DIRTY_MEMORY_VGA only. 891 */ 892 void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client); 893 894 /** 895 * memory_region_get_dirty: Check whether a range of bytes is dirty 896 * for a specified client. 897 * 898 * Checks whether a range of bytes has been written to since the last 899 * call to memory_region_reset_dirty() with the same @client. Dirty logging 900 * must be enabled. 901 * 902 * @mr: the memory region being queried. 903 * @addr: the address (relative to the start of the region) being queried. 904 * @size: the size of the range being queried. 905 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 906 * %DIRTY_MEMORY_VGA. 907 */ 908 bool memory_region_get_dirty(MemoryRegion *mr, hwaddr addr, 909 hwaddr size, unsigned client); 910 911 /** 912 * memory_region_set_dirty: Mark a range of bytes as dirty in a memory region. 913 * 914 * Marks a range of bytes as dirty, after it has been dirtied outside 915 * guest code. 916 * 917 * @mr: the memory region being dirtied. 918 * @addr: the address (relative to the start of the region) being dirtied. 919 * @size: size of the range being dirtied. 920 */ 921 void memory_region_set_dirty(MemoryRegion *mr, hwaddr addr, 922 hwaddr size); 923 924 /** 925 * memory_region_test_and_clear_dirty: Check whether a range of bytes is dirty 926 * for a specified client. It clears them. 927 * 928 * Checks whether a range of bytes has been written to since the last 929 * call to memory_region_reset_dirty() with the same @client. Dirty logging 930 * must be enabled. 931 * 932 * @mr: the memory region being queried. 933 * @addr: the address (relative to the start of the region) being queried. 934 * @size: the size of the range being queried. 935 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 936 * %DIRTY_MEMORY_VGA. 937 */ 938 bool memory_region_test_and_clear_dirty(MemoryRegion *mr, hwaddr addr, 939 hwaddr size, unsigned client); 940 941 /** 942 * memory_region_snapshot_and_clear_dirty: Get a snapshot of the dirty 943 * bitmap and clear it. 944 * 945 * Creates a snapshot of the dirty bitmap, clears the dirty bitmap and 946 * returns the snapshot. The snapshot can then be used to query dirty 947 * status, using memory_region_snapshot_get_dirty. Unlike 948 * memory_region_test_and_clear_dirty this allows to query the same 949 * page multiple times, which is especially useful for display updates 950 * where the scanlines often are not page aligned. 951 * 952 * The dirty bitmap region which gets copyed into the snapshot (and 953 * cleared afterwards) can be larger than requested. The boundaries 954 * are rounded up/down so complete bitmap longs (covering 64 pages on 955 * 64bit hosts) can be copied over into the bitmap snapshot. Which 956 * isn't a problem for display updates as the extra pages are outside 957 * the visible area, and in case the visible area changes a full 958 * display redraw is due anyway. Should other use cases for this 959 * function emerge we might have to revisit this implementation 960 * detail. 961 * 962 * Use g_free to release DirtyBitmapSnapshot. 963 * 964 * @mr: the memory region being queried. 965 * @addr: the address (relative to the start of the region) being queried. 966 * @size: the size of the range being queried. 967 * @client: the user of the logging information; typically %DIRTY_MEMORY_VGA. 968 */ 969 DirtyBitmapSnapshot *memory_region_snapshot_and_clear_dirty(MemoryRegion *mr, 970 hwaddr addr, 971 hwaddr size, 972 unsigned client); 973 974 /** 975 * memory_region_snapshot_get_dirty: Check whether a range of bytes is dirty 976 * in the specified dirty bitmap snapshot. 977 * 978 * @mr: the memory region being queried. 979 * @snap: the dirty bitmap snapshot 980 * @addr: the address (relative to the start of the region) being queried. 981 * @size: the size of the range being queried. 982 */ 983 bool memory_region_snapshot_get_dirty(MemoryRegion *mr, 984 DirtyBitmapSnapshot *snap, 985 hwaddr addr, hwaddr size); 986 987 /** 988 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with 989 * any external TLBs (e.g. kvm) 990 * 991 * Flushes dirty information from accelerators such as kvm and vhost-net 992 * and makes it available to users of the memory API. 993 * 994 * @mr: the region being flushed. 995 */ 996 void memory_region_sync_dirty_bitmap(MemoryRegion *mr); 997 998 /** 999 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified 1000 * client. 1001 * 1002 * Marks a range of pages as no longer dirty. 1003 * 1004 * @mr: the region being updated. 1005 * @addr: the start of the subrange being cleaned. 1006 * @size: the size of the subrange being cleaned. 1007 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 1008 * %DIRTY_MEMORY_VGA. 1009 */ 1010 void memory_region_reset_dirty(MemoryRegion *mr, hwaddr addr, 1011 hwaddr size, unsigned client); 1012 1013 /** 1014 * memory_region_set_readonly: Turn a memory region read-only (or read-write) 1015 * 1016 * Allows a memory region to be marked as read-only (turning it into a ROM). 1017 * only useful on RAM regions. 1018 * 1019 * @mr: the region being updated. 1020 * @readonly: whether rhe region is to be ROM or RAM. 1021 */ 1022 void memory_region_set_readonly(MemoryRegion *mr, bool readonly); 1023 1024 /** 1025 * memory_region_rom_device_set_romd: enable/disable ROMD mode 1026 * 1027 * Allows a ROM device (initialized with memory_region_init_rom_device() to 1028 * set to ROMD mode (default) or MMIO mode. When it is in ROMD mode, the 1029 * device is mapped to guest memory and satisfies read access directly. 1030 * When in MMIO mode, reads are forwarded to the #MemoryRegion.read function. 1031 * Writes are always handled by the #MemoryRegion.write function. 1032 * 1033 * @mr: the memory region to be updated 1034 * @romd_mode: %true to put the region into ROMD mode 1035 */ 1036 void memory_region_rom_device_set_romd(MemoryRegion *mr, bool romd_mode); 1037 1038 /** 1039 * memory_region_set_coalescing: Enable memory coalescing for the region. 1040 * 1041 * Enabled writes to a region to be queued for later processing. MMIO ->write 1042 * callbacks may be delayed until a non-coalesced MMIO is issued. 1043 * Only useful for IO regions. Roughly similar to write-combining hardware. 1044 * 1045 * @mr: the memory region to be write coalesced 1046 */ 1047 void memory_region_set_coalescing(MemoryRegion *mr); 1048 1049 /** 1050 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of 1051 * a region. 1052 * 1053 * Like memory_region_set_coalescing(), but works on a sub-range of a region. 1054 * Multiple calls can be issued coalesced disjoint ranges. 1055 * 1056 * @mr: the memory region to be updated. 1057 * @offset: the start of the range within the region to be coalesced. 1058 * @size: the size of the subrange to be coalesced. 1059 */ 1060 void memory_region_add_coalescing(MemoryRegion *mr, 1061 hwaddr offset, 1062 uint64_t size); 1063 1064 /** 1065 * memory_region_clear_coalescing: Disable MMIO coalescing for the region. 1066 * 1067 * Disables any coalescing caused by memory_region_set_coalescing() or 1068 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory 1069 * hardware. 1070 * 1071 * @mr: the memory region to be updated. 1072 */ 1073 void memory_region_clear_coalescing(MemoryRegion *mr); 1074 1075 /** 1076 * memory_region_set_flush_coalesced: Enforce memory coalescing flush before 1077 * accesses. 1078 * 1079 * Ensure that pending coalesced MMIO request are flushed before the memory 1080 * region is accessed. This property is automatically enabled for all regions 1081 * passed to memory_region_set_coalescing() and memory_region_add_coalescing(). 1082 * 1083 * @mr: the memory region to be updated. 1084 */ 1085 void memory_region_set_flush_coalesced(MemoryRegion *mr); 1086 1087 /** 1088 * memory_region_clear_flush_coalesced: Disable memory coalescing flush before 1089 * accesses. 1090 * 1091 * Clear the automatic coalesced MMIO flushing enabled via 1092 * memory_region_set_flush_coalesced. Note that this service has no effect on 1093 * memory regions that have MMIO coalescing enabled for themselves. For them, 1094 * automatic flushing will stop once coalescing is disabled. 1095 * 1096 * @mr: the memory region to be updated. 1097 */ 1098 void memory_region_clear_flush_coalesced(MemoryRegion *mr); 1099 1100 /** 1101 * memory_region_set_global_locking: Declares the access processing requires 1102 * QEMU's global lock. 1103 * 1104 * When this is invoked, accesses to the memory region will be processed while 1105 * holding the global lock of QEMU. This is the default behavior of memory 1106 * regions. 1107 * 1108 * @mr: the memory region to be updated. 1109 */ 1110 void memory_region_set_global_locking(MemoryRegion *mr); 1111 1112 /** 1113 * memory_region_clear_global_locking: Declares that access processing does 1114 * not depend on the QEMU global lock. 1115 * 1116 * By clearing this property, accesses to the memory region will be processed 1117 * outside of QEMU's global lock (unless the lock is held on when issuing the 1118 * access request). In this case, the device model implementing the access 1119 * handlers is responsible for synchronization of concurrency. 1120 * 1121 * @mr: the memory region to be updated. 1122 */ 1123 void memory_region_clear_global_locking(MemoryRegion *mr); 1124 1125 /** 1126 * memory_region_add_eventfd: Request an eventfd to be triggered when a word 1127 * is written to a location. 1128 * 1129 * Marks a word in an IO region (initialized with memory_region_init_io()) 1130 * as a trigger for an eventfd event. The I/O callback will not be called. 1131 * The caller must be prepared to handle failure (that is, take the required 1132 * action if the callback _is_ called). 1133 * 1134 * @mr: the memory region being updated. 1135 * @addr: the address within @mr that is to be monitored 1136 * @size: the size of the access to trigger the eventfd 1137 * @match_data: whether to match against @data, instead of just @addr 1138 * @data: the data to match against the guest write 1139 * @fd: the eventfd to be triggered when @addr, @size, and @data all match. 1140 **/ 1141 void memory_region_add_eventfd(MemoryRegion *mr, 1142 hwaddr addr, 1143 unsigned size, 1144 bool match_data, 1145 uint64_t data, 1146 EventNotifier *e); 1147 1148 /** 1149 * memory_region_del_eventfd: Cancel an eventfd. 1150 * 1151 * Cancels an eventfd trigger requested by a previous 1152 * memory_region_add_eventfd() call. 1153 * 1154 * @mr: the memory region being updated. 1155 * @addr: the address within @mr that is to be monitored 1156 * @size: the size of the access to trigger the eventfd 1157 * @match_data: whether to match against @data, instead of just @addr 1158 * @data: the data to match against the guest write 1159 * @fd: the eventfd to be triggered when @addr, @size, and @data all match. 1160 */ 1161 void memory_region_del_eventfd(MemoryRegion *mr, 1162 hwaddr addr, 1163 unsigned size, 1164 bool match_data, 1165 uint64_t data, 1166 EventNotifier *e); 1167 1168 /** 1169 * memory_region_add_subregion: Add a subregion to a container. 1170 * 1171 * Adds a subregion at @offset. The subregion may not overlap with other 1172 * subregions (except for those explicitly marked as overlapping). A region 1173 * may only be added once as a subregion (unless removed with 1174 * memory_region_del_subregion()); use memory_region_init_alias() if you 1175 * want a region to be a subregion in multiple locations. 1176 * 1177 * @mr: the region to contain the new subregion; must be a container 1178 * initialized with memory_region_init(). 1179 * @offset: the offset relative to @mr where @subregion is added. 1180 * @subregion: the subregion to be added. 1181 */ 1182 void memory_region_add_subregion(MemoryRegion *mr, 1183 hwaddr offset, 1184 MemoryRegion *subregion); 1185 /** 1186 * memory_region_add_subregion_overlap: Add a subregion to a container 1187 * with overlap. 1188 * 1189 * Adds a subregion at @offset. The subregion may overlap with other 1190 * subregions. Conflicts are resolved by having a higher @priority hide a 1191 * lower @priority. Subregions without priority are taken as @priority 0. 1192 * A region may only be added once as a subregion (unless removed with 1193 * memory_region_del_subregion()); use memory_region_init_alias() if you 1194 * want a region to be a subregion in multiple locations. 1195 * 1196 * @mr: the region to contain the new subregion; must be a container 1197 * initialized with memory_region_init(). 1198 * @offset: the offset relative to @mr where @subregion is added. 1199 * @subregion: the subregion to be added. 1200 * @priority: used for resolving overlaps; highest priority wins. 1201 */ 1202 void memory_region_add_subregion_overlap(MemoryRegion *mr, 1203 hwaddr offset, 1204 MemoryRegion *subregion, 1205 int priority); 1206 1207 /** 1208 * memory_region_get_ram_addr: Get the ram address associated with a memory 1209 * region 1210 */ 1211 ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr); 1212 1213 uint64_t memory_region_get_alignment(const MemoryRegion *mr); 1214 /** 1215 * memory_region_del_subregion: Remove a subregion. 1216 * 1217 * Removes a subregion from its container. 1218 * 1219 * @mr: the container to be updated. 1220 * @subregion: the region being removed; must be a current subregion of @mr. 1221 */ 1222 void memory_region_del_subregion(MemoryRegion *mr, 1223 MemoryRegion *subregion); 1224 1225 /* 1226 * memory_region_set_enabled: dynamically enable or disable a region 1227 * 1228 * Enables or disables a memory region. A disabled memory region 1229 * ignores all accesses to itself and its subregions. It does not 1230 * obscure sibling subregions with lower priority - it simply behaves as 1231 * if it was removed from the hierarchy. 1232 * 1233 * Regions default to being enabled. 1234 * 1235 * @mr: the region to be updated 1236 * @enabled: whether to enable or disable the region 1237 */ 1238 void memory_region_set_enabled(MemoryRegion *mr, bool enabled); 1239 1240 /* 1241 * memory_region_set_address: dynamically update the address of a region 1242 * 1243 * Dynamically updates the address of a region, relative to its container. 1244 * May be used on regions are currently part of a memory hierarchy. 1245 * 1246 * @mr: the region to be updated 1247 * @addr: new address, relative to container region 1248 */ 1249 void memory_region_set_address(MemoryRegion *mr, hwaddr addr); 1250 1251 /* 1252 * memory_region_set_size: dynamically update the size of a region. 1253 * 1254 * Dynamically updates the size of a region. 1255 * 1256 * @mr: the region to be updated 1257 * @size: used size of the region. 1258 */ 1259 void memory_region_set_size(MemoryRegion *mr, uint64_t size); 1260 1261 /* 1262 * memory_region_set_alias_offset: dynamically update a memory alias's offset 1263 * 1264 * Dynamically updates the offset into the target region that an alias points 1265 * to, as if the fourth argument to memory_region_init_alias() has changed. 1266 * 1267 * @mr: the #MemoryRegion to be updated; should be an alias. 1268 * @offset: the new offset into the target memory region 1269 */ 1270 void memory_region_set_alias_offset(MemoryRegion *mr, 1271 hwaddr offset); 1272 1273 /** 1274 * memory_region_present: checks if an address relative to a @container 1275 * translates into #MemoryRegion within @container 1276 * 1277 * Answer whether a #MemoryRegion within @container covers the address 1278 * @addr. 1279 * 1280 * @container: a #MemoryRegion within which @addr is a relative address 1281 * @addr: the area within @container to be searched 1282 */ 1283 bool memory_region_present(MemoryRegion *container, hwaddr addr); 1284 1285 /** 1286 * memory_region_is_mapped: returns true if #MemoryRegion is mapped 1287 * into any address space. 1288 * 1289 * @mr: a #MemoryRegion which should be checked if it's mapped 1290 */ 1291 bool memory_region_is_mapped(MemoryRegion *mr); 1292 1293 /** 1294 * memory_region_find: translate an address/size relative to a 1295 * MemoryRegion into a #MemoryRegionSection. 1296 * 1297 * Locates the first #MemoryRegion within @mr that overlaps the range 1298 * given by @addr and @size. 1299 * 1300 * Returns a #MemoryRegionSection that describes a contiguous overlap. 1301 * It will have the following characteristics: 1302 * .@size = 0 iff no overlap was found 1303 * .@mr is non-%NULL iff an overlap was found 1304 * 1305 * Remember that in the return value the @offset_within_region is 1306 * relative to the returned region (in the .@mr field), not to the 1307 * @mr argument. 1308 * 1309 * Similarly, the .@offset_within_address_space is relative to the 1310 * address space that contains both regions, the passed and the 1311 * returned one. However, in the special case where the @mr argument 1312 * has no container (and thus is the root of the address space), the 1313 * following will hold: 1314 * .@offset_within_address_space >= @addr 1315 * .@offset_within_address_space + .@size <= @addr + @size 1316 * 1317 * @mr: a MemoryRegion within which @addr is a relative address 1318 * @addr: start of the area within @as to be searched 1319 * @size: size of the area to be searched 1320 */ 1321 MemoryRegionSection memory_region_find(MemoryRegion *mr, 1322 hwaddr addr, uint64_t size); 1323 1324 /** 1325 * memory_global_dirty_log_sync: synchronize the dirty log for all memory 1326 * 1327 * Synchronizes the dirty page log for all address spaces. 1328 */ 1329 void memory_global_dirty_log_sync(void); 1330 1331 /** 1332 * memory_region_transaction_begin: Start a transaction. 1333 * 1334 * During a transaction, changes will be accumulated and made visible 1335 * only when the transaction ends (is committed). 1336 */ 1337 void memory_region_transaction_begin(void); 1338 1339 /** 1340 * memory_region_transaction_commit: Commit a transaction and make changes 1341 * visible to the guest. 1342 */ 1343 void memory_region_transaction_commit(void); 1344 1345 /** 1346 * memory_listener_register: register callbacks to be called when memory 1347 * sections are mapped or unmapped into an address 1348 * space 1349 * 1350 * @listener: an object containing the callbacks to be called 1351 * @filter: if non-%NULL, only regions in this address space will be observed 1352 */ 1353 void memory_listener_register(MemoryListener *listener, AddressSpace *filter); 1354 1355 /** 1356 * memory_listener_unregister: undo the effect of memory_listener_register() 1357 * 1358 * @listener: an object containing the callbacks to be removed 1359 */ 1360 void memory_listener_unregister(MemoryListener *listener); 1361 1362 /** 1363 * memory_global_dirty_log_start: begin dirty logging for all regions 1364 */ 1365 void memory_global_dirty_log_start(void); 1366 1367 /** 1368 * memory_global_dirty_log_stop: end dirty logging for all regions 1369 */ 1370 void memory_global_dirty_log_stop(void); 1371 1372 void mtree_info(fprintf_function mon_printf, void *f, bool flatview); 1373 1374 /** 1375 * memory_region_request_mmio_ptr: request a pointer to an mmio 1376 * MemoryRegion. If it is possible map a RAM MemoryRegion with this pointer. 1377 * When the device wants to invalidate the pointer it will call 1378 * memory_region_invalidate_mmio_ptr. 1379 * 1380 * @mr: #MemoryRegion to check 1381 * @addr: address within that region 1382 * 1383 * Returns true on success, false otherwise. 1384 */ 1385 bool memory_region_request_mmio_ptr(MemoryRegion *mr, hwaddr addr); 1386 1387 /** 1388 * memory_region_invalidate_mmio_ptr: invalidate the pointer to an mmio 1389 * previously requested. 1390 * In the end that means that if something wants to execute from this area it 1391 * will need to request the pointer again. 1392 * 1393 * @mr: #MemoryRegion associated to the pointer. 1394 * @addr: address within that region 1395 * @size: size of that area. 1396 */ 1397 void memory_region_invalidate_mmio_ptr(MemoryRegion *mr, hwaddr offset, 1398 unsigned size); 1399 1400 /** 1401 * memory_region_dispatch_read: perform a read directly to the specified 1402 * MemoryRegion. 1403 * 1404 * @mr: #MemoryRegion to access 1405 * @addr: address within that region 1406 * @pval: pointer to uint64_t which the data is written to 1407 * @size: size of the access in bytes 1408 * @attrs: memory transaction attributes to use for the access 1409 */ 1410 MemTxResult memory_region_dispatch_read(MemoryRegion *mr, 1411 hwaddr addr, 1412 uint64_t *pval, 1413 unsigned size, 1414 MemTxAttrs attrs); 1415 /** 1416 * memory_region_dispatch_write: perform a write directly to the specified 1417 * MemoryRegion. 1418 * 1419 * @mr: #MemoryRegion to access 1420 * @addr: address within that region 1421 * @data: data to write 1422 * @size: size of the access in bytes 1423 * @attrs: memory transaction attributes to use for the access 1424 */ 1425 MemTxResult memory_region_dispatch_write(MemoryRegion *mr, 1426 hwaddr addr, 1427 uint64_t data, 1428 unsigned size, 1429 MemTxAttrs attrs); 1430 1431 /** 1432 * address_space_init: initializes an address space 1433 * 1434 * @as: an uninitialized #AddressSpace 1435 * @root: a #MemoryRegion that routes addresses for the address space 1436 * @name: an address space name. The name is only used for debugging 1437 * output. 1438 */ 1439 void address_space_init(AddressSpace *as, MemoryRegion *root, const char *name); 1440 1441 /** 1442 * address_space_init_shareable: return an address space for a memory region, 1443 * creating it if it does not already exist 1444 * 1445 * @root: a #MemoryRegion that routes addresses for the address space 1446 * @name: an address space name. The name is only used for debugging 1447 * output. 1448 * 1449 * This function will return a pointer to an existing AddressSpace 1450 * which was initialized with the specified MemoryRegion, or it will 1451 * create and initialize one if it does not already exist. The ASes 1452 * are reference-counted, so the memory will be freed automatically 1453 * when the AddressSpace is destroyed via address_space_destroy. 1454 */ 1455 AddressSpace *address_space_init_shareable(MemoryRegion *root, 1456 const char *name); 1457 1458 /** 1459 * address_space_destroy: destroy an address space 1460 * 1461 * Releases all resources associated with an address space. After an address space 1462 * is destroyed, its root memory region (given by address_space_init()) may be destroyed 1463 * as well. 1464 * 1465 * @as: address space to be destroyed 1466 */ 1467 void address_space_destroy(AddressSpace *as); 1468 1469 /** 1470 * address_space_rw: read from or write to an address space. 1471 * 1472 * Return a MemTxResult indicating whether the operation succeeded 1473 * or failed (eg unassigned memory, device rejected the transaction, 1474 * IOMMU fault). 1475 * 1476 * @as: #AddressSpace to be accessed 1477 * @addr: address within that address space 1478 * @attrs: memory transaction attributes 1479 * @buf: buffer with the data transferred 1480 * @is_write: indicates the transfer direction 1481 */ 1482 MemTxResult address_space_rw(AddressSpace *as, hwaddr addr, 1483 MemTxAttrs attrs, uint8_t *buf, 1484 int len, bool is_write); 1485 1486 /** 1487 * address_space_write: write to address space. 1488 * 1489 * Return a MemTxResult indicating whether the operation succeeded 1490 * or failed (eg unassigned memory, device rejected the transaction, 1491 * IOMMU fault). 1492 * 1493 * @as: #AddressSpace to be accessed 1494 * @addr: address within that address space 1495 * @attrs: memory transaction attributes 1496 * @buf: buffer with the data transferred 1497 */ 1498 MemTxResult address_space_write(AddressSpace *as, hwaddr addr, 1499 MemTxAttrs attrs, 1500 const uint8_t *buf, int len); 1501 1502 /* address_space_ld*: load from an address space 1503 * address_space_st*: store to an address space 1504 * 1505 * These functions perform a load or store of the byte, word, 1506 * longword or quad to the specified address within the AddressSpace. 1507 * The _le suffixed functions treat the data as little endian; 1508 * _be indicates big endian; no suffix indicates "same endianness 1509 * as guest CPU". 1510 * 1511 * The "guest CPU endianness" accessors are deprecated for use outside 1512 * target-* code; devices should be CPU-agnostic and use either the LE 1513 * or the BE accessors. 1514 * 1515 * @as #AddressSpace to be accessed 1516 * @addr: address within that address space 1517 * @val: data value, for stores 1518 * @attrs: memory transaction attributes 1519 * @result: location to write the success/failure of the transaction; 1520 * if NULL, this information is discarded 1521 */ 1522 uint32_t address_space_ldub(AddressSpace *as, hwaddr addr, 1523 MemTxAttrs attrs, MemTxResult *result); 1524 uint32_t address_space_lduw_le(AddressSpace *as, hwaddr addr, 1525 MemTxAttrs attrs, MemTxResult *result); 1526 uint32_t address_space_lduw_be(AddressSpace *as, hwaddr addr, 1527 MemTxAttrs attrs, MemTxResult *result); 1528 uint32_t address_space_ldl_le(AddressSpace *as, hwaddr addr, 1529 MemTxAttrs attrs, MemTxResult *result); 1530 uint32_t address_space_ldl_be(AddressSpace *as, hwaddr addr, 1531 MemTxAttrs attrs, MemTxResult *result); 1532 uint64_t address_space_ldq_le(AddressSpace *as, hwaddr addr, 1533 MemTxAttrs attrs, MemTxResult *result); 1534 uint64_t address_space_ldq_be(AddressSpace *as, hwaddr addr, 1535 MemTxAttrs attrs, MemTxResult *result); 1536 void address_space_stb(AddressSpace *as, hwaddr addr, uint32_t val, 1537 MemTxAttrs attrs, MemTxResult *result); 1538 void address_space_stw_le(AddressSpace *as, hwaddr addr, uint32_t val, 1539 MemTxAttrs attrs, MemTxResult *result); 1540 void address_space_stw_be(AddressSpace *as, hwaddr addr, uint32_t val, 1541 MemTxAttrs attrs, MemTxResult *result); 1542 void address_space_stl_le(AddressSpace *as, hwaddr addr, uint32_t val, 1543 MemTxAttrs attrs, MemTxResult *result); 1544 void address_space_stl_be(AddressSpace *as, hwaddr addr, uint32_t val, 1545 MemTxAttrs attrs, MemTxResult *result); 1546 void address_space_stq_le(AddressSpace *as, hwaddr addr, uint64_t val, 1547 MemTxAttrs attrs, MemTxResult *result); 1548 void address_space_stq_be(AddressSpace *as, hwaddr addr, uint64_t val, 1549 MemTxAttrs attrs, MemTxResult *result); 1550 1551 uint32_t ldub_phys(AddressSpace *as, hwaddr addr); 1552 uint32_t lduw_le_phys(AddressSpace *as, hwaddr addr); 1553 uint32_t lduw_be_phys(AddressSpace *as, hwaddr addr); 1554 uint32_t ldl_le_phys(AddressSpace *as, hwaddr addr); 1555 uint32_t ldl_be_phys(AddressSpace *as, hwaddr addr); 1556 uint64_t ldq_le_phys(AddressSpace *as, hwaddr addr); 1557 uint64_t ldq_be_phys(AddressSpace *as, hwaddr addr); 1558 void stb_phys(AddressSpace *as, hwaddr addr, uint32_t val); 1559 void stw_le_phys(AddressSpace *as, hwaddr addr, uint32_t val); 1560 void stw_be_phys(AddressSpace *as, hwaddr addr, uint32_t val); 1561 void stl_le_phys(AddressSpace *as, hwaddr addr, uint32_t val); 1562 void stl_be_phys(AddressSpace *as, hwaddr addr, uint32_t val); 1563 void stq_le_phys(AddressSpace *as, hwaddr addr, uint64_t val); 1564 void stq_be_phys(AddressSpace *as, hwaddr addr, uint64_t val); 1565 1566 struct MemoryRegionCache { 1567 hwaddr xlat; 1568 hwaddr len; 1569 AddressSpace *as; 1570 }; 1571 1572 #define MEMORY_REGION_CACHE_INVALID ((MemoryRegionCache) { .as = NULL }) 1573 1574 /* address_space_cache_init: prepare for repeated access to a physical 1575 * memory region 1576 * 1577 * @cache: #MemoryRegionCache to be filled 1578 * @as: #AddressSpace to be accessed 1579 * @addr: address within that address space 1580 * @len: length of buffer 1581 * @is_write: indicates the transfer direction 1582 * 1583 * Will only work with RAM, and may map a subset of the requested range by 1584 * returning a value that is less than @len. On failure, return a negative 1585 * errno value. 1586 * 1587 * Because it only works with RAM, this function can be used for 1588 * read-modify-write operations. In this case, is_write should be %true. 1589 * 1590 * Note that addresses passed to the address_space_*_cached functions 1591 * are relative to @addr. 1592 */ 1593 int64_t address_space_cache_init(MemoryRegionCache *cache, 1594 AddressSpace *as, 1595 hwaddr addr, 1596 hwaddr len, 1597 bool is_write); 1598 1599 /** 1600 * address_space_cache_invalidate: complete a write to a #MemoryRegionCache 1601 * 1602 * @cache: The #MemoryRegionCache to operate on. 1603 * @addr: The first physical address that was written, relative to the 1604 * address that was passed to @address_space_cache_init. 1605 * @access_len: The number of bytes that were written starting at @addr. 1606 */ 1607 void address_space_cache_invalidate(MemoryRegionCache *cache, 1608 hwaddr addr, 1609 hwaddr access_len); 1610 1611 /** 1612 * address_space_cache_destroy: free a #MemoryRegionCache 1613 * 1614 * @cache: The #MemoryRegionCache whose memory should be released. 1615 */ 1616 void address_space_cache_destroy(MemoryRegionCache *cache); 1617 1618 /* address_space_ld*_cached: load from a cached #MemoryRegion 1619 * address_space_st*_cached: store into a cached #MemoryRegion 1620 * 1621 * These functions perform a load or store of the byte, word, 1622 * longword or quad to the specified address. The address is 1623 * a physical address in the AddressSpace, but it must lie within 1624 * a #MemoryRegion that was mapped with address_space_cache_init. 1625 * 1626 * The _le suffixed functions treat the data as little endian; 1627 * _be indicates big endian; no suffix indicates "same endianness 1628 * as guest CPU". 1629 * 1630 * The "guest CPU endianness" accessors are deprecated for use outside 1631 * target-* code; devices should be CPU-agnostic and use either the LE 1632 * or the BE accessors. 1633 * 1634 * @cache: previously initialized #MemoryRegionCache to be accessed 1635 * @addr: address within the address space 1636 * @val: data value, for stores 1637 * @attrs: memory transaction attributes 1638 * @result: location to write the success/failure of the transaction; 1639 * if NULL, this information is discarded 1640 */ 1641 uint32_t address_space_ldub_cached(MemoryRegionCache *cache, hwaddr addr, 1642 MemTxAttrs attrs, MemTxResult *result); 1643 uint32_t address_space_lduw_le_cached(MemoryRegionCache *cache, hwaddr addr, 1644 MemTxAttrs attrs, MemTxResult *result); 1645 uint32_t address_space_lduw_be_cached(MemoryRegionCache *cache, hwaddr addr, 1646 MemTxAttrs attrs, MemTxResult *result); 1647 uint32_t address_space_ldl_le_cached(MemoryRegionCache *cache, hwaddr addr, 1648 MemTxAttrs attrs, MemTxResult *result); 1649 uint32_t address_space_ldl_be_cached(MemoryRegionCache *cache, hwaddr addr, 1650 MemTxAttrs attrs, MemTxResult *result); 1651 uint64_t address_space_ldq_le_cached(MemoryRegionCache *cache, hwaddr addr, 1652 MemTxAttrs attrs, MemTxResult *result); 1653 uint64_t address_space_ldq_be_cached(MemoryRegionCache *cache, hwaddr addr, 1654 MemTxAttrs attrs, MemTxResult *result); 1655 void address_space_stb_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val, 1656 MemTxAttrs attrs, MemTxResult *result); 1657 void address_space_stw_le_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val, 1658 MemTxAttrs attrs, MemTxResult *result); 1659 void address_space_stw_be_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val, 1660 MemTxAttrs attrs, MemTxResult *result); 1661 void address_space_stl_le_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val, 1662 MemTxAttrs attrs, MemTxResult *result); 1663 void address_space_stl_be_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val, 1664 MemTxAttrs attrs, MemTxResult *result); 1665 void address_space_stq_le_cached(MemoryRegionCache *cache, hwaddr addr, uint64_t val, 1666 MemTxAttrs attrs, MemTxResult *result); 1667 void address_space_stq_be_cached(MemoryRegionCache *cache, hwaddr addr, uint64_t val, 1668 MemTxAttrs attrs, MemTxResult *result); 1669 1670 uint32_t ldub_phys_cached(MemoryRegionCache *cache, hwaddr addr); 1671 uint32_t lduw_le_phys_cached(MemoryRegionCache *cache, hwaddr addr); 1672 uint32_t lduw_be_phys_cached(MemoryRegionCache *cache, hwaddr addr); 1673 uint32_t ldl_le_phys_cached(MemoryRegionCache *cache, hwaddr addr); 1674 uint32_t ldl_be_phys_cached(MemoryRegionCache *cache, hwaddr addr); 1675 uint64_t ldq_le_phys_cached(MemoryRegionCache *cache, hwaddr addr); 1676 uint64_t ldq_be_phys_cached(MemoryRegionCache *cache, hwaddr addr); 1677 void stb_phys_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val); 1678 void stw_le_phys_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val); 1679 void stw_be_phys_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val); 1680 void stl_le_phys_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val); 1681 void stl_be_phys_cached(MemoryRegionCache *cache, hwaddr addr, uint32_t val); 1682 void stq_le_phys_cached(MemoryRegionCache *cache, hwaddr addr, uint64_t val); 1683 void stq_be_phys_cached(MemoryRegionCache *cache, hwaddr addr, uint64_t val); 1684 /* address_space_get_iotlb_entry: translate an address into an IOTLB 1685 * entry. Should be called from an RCU critical section. 1686 */ 1687 IOMMUTLBEntry address_space_get_iotlb_entry(AddressSpace *as, hwaddr addr, 1688 bool is_write); 1689 1690 /* address_space_translate: translate an address range into an address space 1691 * into a MemoryRegion and an address range into that section. Should be 1692 * called from an RCU critical section, to avoid that the last reference 1693 * to the returned region disappears after address_space_translate returns. 1694 * 1695 * @as: #AddressSpace to be accessed 1696 * @addr: address within that address space 1697 * @xlat: pointer to address within the returned memory region section's 1698 * #MemoryRegion. 1699 * @len: pointer to length 1700 * @is_write: indicates the transfer direction 1701 */ 1702 MemoryRegion *address_space_translate(AddressSpace *as, hwaddr addr, 1703 hwaddr *xlat, hwaddr *len, 1704 bool is_write); 1705 1706 /* address_space_access_valid: check for validity of accessing an address 1707 * space range 1708 * 1709 * Check whether memory is assigned to the given address space range, and 1710 * access is permitted by any IOMMU regions that are active for the address 1711 * space. 1712 * 1713 * For now, addr and len should be aligned to a page size. This limitation 1714 * will be lifted in the future. 1715 * 1716 * @as: #AddressSpace to be accessed 1717 * @addr: address within that address space 1718 * @len: length of the area to be checked 1719 * @is_write: indicates the transfer direction 1720 */ 1721 bool address_space_access_valid(AddressSpace *as, hwaddr addr, int len, bool is_write); 1722 1723 /* address_space_map: map a physical memory region into a host virtual address 1724 * 1725 * May map a subset of the requested range, given by and returned in @plen. 1726 * May return %NULL if resources needed to perform the mapping are exhausted. 1727 * Use only for reads OR writes - not for read-modify-write operations. 1728 * Use cpu_register_map_client() to know when retrying the map operation is 1729 * likely to succeed. 1730 * 1731 * @as: #AddressSpace to be accessed 1732 * @addr: address within that address space 1733 * @plen: pointer to length of buffer; updated on return 1734 * @is_write: indicates the transfer direction 1735 */ 1736 void *address_space_map(AddressSpace *as, hwaddr addr, 1737 hwaddr *plen, bool is_write); 1738 1739 /* address_space_unmap: Unmaps a memory region previously mapped by address_space_map() 1740 * 1741 * Will also mark the memory as dirty if @is_write == %true. @access_len gives 1742 * the amount of memory that was actually read or written by the caller. 1743 * 1744 * @as: #AddressSpace used 1745 * @addr: address within that address space 1746 * @len: buffer length as returned by address_space_map() 1747 * @access_len: amount of data actually transferred 1748 * @is_write: indicates the transfer direction 1749 */ 1750 void address_space_unmap(AddressSpace *as, void *buffer, hwaddr len, 1751 int is_write, hwaddr access_len); 1752 1753 1754 /* Internal functions, part of the implementation of address_space_read. */ 1755 MemTxResult address_space_read_continue(AddressSpace *as, hwaddr addr, 1756 MemTxAttrs attrs, uint8_t *buf, 1757 int len, hwaddr addr1, hwaddr l, 1758 MemoryRegion *mr); 1759 MemTxResult address_space_read_full(AddressSpace *as, hwaddr addr, 1760 MemTxAttrs attrs, uint8_t *buf, int len); 1761 void *qemu_map_ram_ptr(RAMBlock *ram_block, ram_addr_t addr); 1762 1763 static inline bool memory_access_is_direct(MemoryRegion *mr, bool is_write) 1764 { 1765 if (is_write) { 1766 return memory_region_is_ram(mr) && 1767 !mr->readonly && !memory_region_is_ram_device(mr); 1768 } else { 1769 return (memory_region_is_ram(mr) && !memory_region_is_ram_device(mr)) || 1770 memory_region_is_romd(mr); 1771 } 1772 } 1773 1774 /** 1775 * address_space_read: read from an address space. 1776 * 1777 * Return a MemTxResult indicating whether the operation succeeded 1778 * or failed (eg unassigned memory, device rejected the transaction, 1779 * IOMMU fault). 1780 * 1781 * @as: #AddressSpace to be accessed 1782 * @addr: address within that address space 1783 * @attrs: memory transaction attributes 1784 * @buf: buffer with the data transferred 1785 */ 1786 static inline __attribute__((__always_inline__)) 1787 MemTxResult address_space_read(AddressSpace *as, hwaddr addr, MemTxAttrs attrs, 1788 uint8_t *buf, int len) 1789 { 1790 MemTxResult result = MEMTX_OK; 1791 hwaddr l, addr1; 1792 void *ptr; 1793 MemoryRegion *mr; 1794 1795 if (__builtin_constant_p(len)) { 1796 if (len) { 1797 rcu_read_lock(); 1798 l = len; 1799 mr = address_space_translate(as, addr, &addr1, &l, false); 1800 if (len == l && memory_access_is_direct(mr, false)) { 1801 ptr = qemu_map_ram_ptr(mr->ram_block, addr1); 1802 memcpy(buf, ptr, len); 1803 } else { 1804 result = address_space_read_continue(as, addr, attrs, buf, len, 1805 addr1, l, mr); 1806 } 1807 rcu_read_unlock(); 1808 } 1809 } else { 1810 result = address_space_read_full(as, addr, attrs, buf, len); 1811 } 1812 return result; 1813 } 1814 1815 /** 1816 * address_space_read_cached: read from a cached RAM region 1817 * 1818 * @cache: Cached region to be addressed 1819 * @addr: address relative to the base of the RAM region 1820 * @buf: buffer with the data transferred 1821 * @len: length of the data transferred 1822 */ 1823 static inline void 1824 address_space_read_cached(MemoryRegionCache *cache, hwaddr addr, 1825 void *buf, int len) 1826 { 1827 assert(addr < cache->len && len <= cache->len - addr); 1828 address_space_read(cache->as, cache->xlat + addr, MEMTXATTRS_UNSPECIFIED, buf, len); 1829 } 1830 1831 /** 1832 * address_space_write_cached: write to a cached RAM region 1833 * 1834 * @cache: Cached region to be addressed 1835 * @addr: address relative to the base of the RAM region 1836 * @buf: buffer with the data transferred 1837 * @len: length of the data transferred 1838 */ 1839 static inline void 1840 address_space_write_cached(MemoryRegionCache *cache, hwaddr addr, 1841 void *buf, int len) 1842 { 1843 assert(addr < cache->len && len <= cache->len - addr); 1844 address_space_write(cache->as, cache->xlat + addr, MEMTXATTRS_UNSPECIFIED, buf, len); 1845 } 1846 1847 #endif 1848 1849 #endif 1850