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