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 return mr->iommu_ops; 632 } 633 634 635 /** 636 * memory_region_iommu_get_min_page_size: get minimum supported page size 637 * for an iommu 638 * 639 * Returns minimum supported page size for an iommu. 640 * 641 * @mr: the memory region being queried 642 */ 643 uint64_t memory_region_iommu_get_min_page_size(MemoryRegion *mr); 644 645 /** 646 * memory_region_notify_iommu: notify a change in an IOMMU translation entry. 647 * 648 * The notification type will be decided by entry.perm bits: 649 * 650 * - For UNMAP (cache invalidation) notifies: set entry.perm to IOMMU_NONE. 651 * - For MAP (newly added entry) notifies: set entry.perm to the 652 * permission of the page (which is definitely !IOMMU_NONE). 653 * 654 * Note: for any IOMMU implementation, an in-place mapping change 655 * should be notified with an UNMAP followed by a MAP. 656 * 657 * @mr: the memory region that was changed 658 * @entry: the new entry in the IOMMU translation table. The entry 659 * replaces all old entries for the same virtual I/O address range. 660 * Deleted entries have .@perm == 0. 661 */ 662 void memory_region_notify_iommu(MemoryRegion *mr, 663 IOMMUTLBEntry entry); 664 665 /** 666 * memory_region_register_iommu_notifier: register a notifier for changes to 667 * IOMMU translation entries. 668 * 669 * @mr: the memory region to observe 670 * @n: the IOMMUNotifier to be added; the notify callback receives a 671 * pointer to an #IOMMUTLBEntry as the opaque value; the pointer 672 * ceases to be valid on exit from the notifier. 673 */ 674 void memory_region_register_iommu_notifier(MemoryRegion *mr, 675 IOMMUNotifier *n); 676 677 /** 678 * memory_region_iommu_replay: replay existing IOMMU translations to 679 * a notifier with the minimum page granularity returned by 680 * mr->iommu_ops->get_page_size(). 681 * 682 * @mr: the memory region to observe 683 * @n: the notifier to which to replay iommu mappings 684 * @is_write: Whether to treat the replay as a translate "write" 685 * through the iommu 686 */ 687 void memory_region_iommu_replay(MemoryRegion *mr, IOMMUNotifier *n, 688 bool is_write); 689 690 /** 691 * memory_region_unregister_iommu_notifier: unregister a notifier for 692 * changes to IOMMU translation entries. 693 * 694 * @mr: the memory region which was observed and for which notity_stopped() 695 * needs to be called 696 * @n: the notifier to be removed. 697 */ 698 void memory_region_unregister_iommu_notifier(MemoryRegion *mr, 699 IOMMUNotifier *n); 700 701 /** 702 * memory_region_name: get a memory region's name 703 * 704 * Returns the string that was used to initialize the memory region. 705 * 706 * @mr: the memory region being queried 707 */ 708 const char *memory_region_name(const MemoryRegion *mr); 709 710 /** 711 * memory_region_is_logging: return whether a memory region is logging writes 712 * 713 * Returns %true if the memory region is logging writes for the given client 714 * 715 * @mr: the memory region being queried 716 * @client: the client being queried 717 */ 718 bool memory_region_is_logging(MemoryRegion *mr, uint8_t client); 719 720 /** 721 * memory_region_get_dirty_log_mask: return the clients for which a 722 * memory region is logging writes. 723 * 724 * Returns a bitmap of clients, in which the DIRTY_MEMORY_* constants 725 * are the bit indices. 726 * 727 * @mr: the memory region being queried 728 */ 729 uint8_t memory_region_get_dirty_log_mask(MemoryRegion *mr); 730 731 /** 732 * memory_region_is_rom: check whether a memory region is ROM 733 * 734 * Returns %true is a memory region is read-only memory. 735 * 736 * @mr: the memory region being queried 737 */ 738 static inline bool memory_region_is_rom(MemoryRegion *mr) 739 { 740 return mr->ram && mr->readonly; 741 } 742 743 744 /** 745 * memory_region_get_fd: Get a file descriptor backing a RAM memory region. 746 * 747 * Returns a file descriptor backing a file-based RAM memory region, 748 * or -1 if the region is not a file-based RAM memory region. 749 * 750 * @mr: the RAM or alias memory region being queried. 751 */ 752 int memory_region_get_fd(MemoryRegion *mr); 753 754 /** 755 * memory_region_set_fd: Mark a RAM memory region as backed by a 756 * file descriptor. 757 * 758 * This function is typically used after memory_region_init_ram_ptr(). 759 * 760 * @mr: the memory region being queried. 761 * @fd: the file descriptor that backs @mr. 762 */ 763 void memory_region_set_fd(MemoryRegion *mr, int fd); 764 765 /** 766 * memory_region_from_host: Convert a pointer into a RAM memory region 767 * and an offset within it. 768 * 769 * Given a host pointer inside a RAM memory region (created with 770 * memory_region_init_ram() or memory_region_init_ram_ptr()), return 771 * the MemoryRegion and the offset within it. 772 * 773 * Use with care; by the time this function returns, the returned pointer is 774 * not protected by RCU anymore. If the caller is not within an RCU critical 775 * section and does not hold the iothread lock, it must have other means of 776 * protecting the pointer, such as a reference to the region that includes 777 * the incoming ram_addr_t. 778 * 779 * @mr: the memory region being queried. 780 */ 781 MemoryRegion *memory_region_from_host(void *ptr, ram_addr_t *offset); 782 783 /** 784 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region. 785 * 786 * Returns a host pointer to a RAM memory region (created with 787 * memory_region_init_ram() or memory_region_init_ram_ptr()). 788 * 789 * Use with care; by the time this function returns, the returned pointer is 790 * not protected by RCU anymore. If the caller is not within an RCU critical 791 * section and does not hold the iothread lock, it must have other means of 792 * protecting the pointer, such as a reference to the region that includes 793 * the incoming ram_addr_t. 794 * 795 * @mr: the memory region being queried. 796 */ 797 void *memory_region_get_ram_ptr(MemoryRegion *mr); 798 799 /* memory_region_ram_resize: Resize a RAM region. 800 * 801 * Only legal before guest might have detected the memory size: e.g. on 802 * incoming migration, or right after reset. 803 * 804 * @mr: a memory region created with @memory_region_init_resizeable_ram. 805 * @newsize: the new size the region 806 * @errp: pointer to Error*, to store an error if it happens. 807 */ 808 void memory_region_ram_resize(MemoryRegion *mr, ram_addr_t newsize, 809 Error **errp); 810 811 /** 812 * memory_region_set_log: Turn dirty logging on or off for a region. 813 * 814 * Turns dirty logging on or off for a specified client (display, migration). 815 * Only meaningful for RAM regions. 816 * 817 * @mr: the memory region being updated. 818 * @log: whether dirty logging is to be enabled or disabled. 819 * @client: the user of the logging information; %DIRTY_MEMORY_VGA only. 820 */ 821 void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client); 822 823 /** 824 * memory_region_get_dirty: Check whether a range of bytes is dirty 825 * for a specified client. 826 * 827 * Checks whether a range of bytes has been written to since the last 828 * call to memory_region_reset_dirty() with the same @client. Dirty logging 829 * must be enabled. 830 * 831 * @mr: the memory region being queried. 832 * @addr: the address (relative to the start of the region) being queried. 833 * @size: the size of the range being queried. 834 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 835 * %DIRTY_MEMORY_VGA. 836 */ 837 bool memory_region_get_dirty(MemoryRegion *mr, hwaddr addr, 838 hwaddr size, unsigned client); 839 840 /** 841 * memory_region_set_dirty: Mark a range of bytes as dirty in a memory region. 842 * 843 * Marks a range of bytes as dirty, after it has been dirtied outside 844 * guest code. 845 * 846 * @mr: the memory region being dirtied. 847 * @addr: the address (relative to the start of the region) being dirtied. 848 * @size: size of the range being dirtied. 849 */ 850 void memory_region_set_dirty(MemoryRegion *mr, hwaddr addr, 851 hwaddr size); 852 853 /** 854 * memory_region_test_and_clear_dirty: Check whether a range of bytes is dirty 855 * for a specified client. It clears them. 856 * 857 * Checks whether a range of bytes has been written to since the last 858 * call to memory_region_reset_dirty() with the same @client. Dirty logging 859 * must be enabled. 860 * 861 * @mr: the memory region being queried. 862 * @addr: the address (relative to the start of the region) being queried. 863 * @size: the size of the range being queried. 864 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 865 * %DIRTY_MEMORY_VGA. 866 */ 867 bool memory_region_test_and_clear_dirty(MemoryRegion *mr, hwaddr addr, 868 hwaddr size, unsigned client); 869 /** 870 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with 871 * any external TLBs (e.g. kvm) 872 * 873 * Flushes dirty information from accelerators such as kvm and vhost-net 874 * and makes it available to users of the memory API. 875 * 876 * @mr: the region being flushed. 877 */ 878 void memory_region_sync_dirty_bitmap(MemoryRegion *mr); 879 880 /** 881 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified 882 * client. 883 * 884 * Marks a range of pages as no longer dirty. 885 * 886 * @mr: the region being updated. 887 * @addr: the start of the subrange being cleaned. 888 * @size: the size of the subrange being cleaned. 889 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 890 * %DIRTY_MEMORY_VGA. 891 */ 892 void memory_region_reset_dirty(MemoryRegion *mr, hwaddr addr, 893 hwaddr size, unsigned client); 894 895 /** 896 * memory_region_set_readonly: Turn a memory region read-only (or read-write) 897 * 898 * Allows a memory region to be marked as read-only (turning it into a ROM). 899 * only useful on RAM regions. 900 * 901 * @mr: the region being updated. 902 * @readonly: whether rhe region is to be ROM or RAM. 903 */ 904 void memory_region_set_readonly(MemoryRegion *mr, bool readonly); 905 906 /** 907 * memory_region_rom_device_set_romd: enable/disable ROMD mode 908 * 909 * Allows a ROM device (initialized with memory_region_init_rom_device() to 910 * set to ROMD mode (default) or MMIO mode. When it is in ROMD mode, the 911 * device is mapped to guest memory and satisfies read access directly. 912 * When in MMIO mode, reads are forwarded to the #MemoryRegion.read function. 913 * Writes are always handled by the #MemoryRegion.write function. 914 * 915 * @mr: the memory region to be updated 916 * @romd_mode: %true to put the region into ROMD mode 917 */ 918 void memory_region_rom_device_set_romd(MemoryRegion *mr, bool romd_mode); 919 920 /** 921 * memory_region_set_coalescing: Enable memory coalescing for the region. 922 * 923 * Enabled writes to a region to be queued for later processing. MMIO ->write 924 * callbacks may be delayed until a non-coalesced MMIO is issued. 925 * Only useful for IO regions. Roughly similar to write-combining hardware. 926 * 927 * @mr: the memory region to be write coalesced 928 */ 929 void memory_region_set_coalescing(MemoryRegion *mr); 930 931 /** 932 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of 933 * a region. 934 * 935 * Like memory_region_set_coalescing(), but works on a sub-range of a region. 936 * Multiple calls can be issued coalesced disjoint ranges. 937 * 938 * @mr: the memory region to be updated. 939 * @offset: the start of the range within the region to be coalesced. 940 * @size: the size of the subrange to be coalesced. 941 */ 942 void memory_region_add_coalescing(MemoryRegion *mr, 943 hwaddr offset, 944 uint64_t size); 945 946 /** 947 * memory_region_clear_coalescing: Disable MMIO coalescing for the region. 948 * 949 * Disables any coalescing caused by memory_region_set_coalescing() or 950 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory 951 * hardware. 952 * 953 * @mr: the memory region to be updated. 954 */ 955 void memory_region_clear_coalescing(MemoryRegion *mr); 956 957 /** 958 * memory_region_set_flush_coalesced: Enforce memory coalescing flush before 959 * accesses. 960 * 961 * Ensure that pending coalesced MMIO request are flushed before the memory 962 * region is accessed. This property is automatically enabled for all regions 963 * passed to memory_region_set_coalescing() and memory_region_add_coalescing(). 964 * 965 * @mr: the memory region to be updated. 966 */ 967 void memory_region_set_flush_coalesced(MemoryRegion *mr); 968 969 /** 970 * memory_region_clear_flush_coalesced: Disable memory coalescing flush before 971 * accesses. 972 * 973 * Clear the automatic coalesced MMIO flushing enabled via 974 * memory_region_set_flush_coalesced. Note that this service has no effect on 975 * memory regions that have MMIO coalescing enabled for themselves. For them, 976 * automatic flushing will stop once coalescing is disabled. 977 * 978 * @mr: the memory region to be updated. 979 */ 980 void memory_region_clear_flush_coalesced(MemoryRegion *mr); 981 982 /** 983 * memory_region_set_global_locking: Declares the access processing requires 984 * QEMU's global lock. 985 * 986 * When this is invoked, accesses to the memory region will be processed while 987 * holding the global lock of QEMU. This is the default behavior of memory 988 * regions. 989 * 990 * @mr: the memory region to be updated. 991 */ 992 void memory_region_set_global_locking(MemoryRegion *mr); 993 994 /** 995 * memory_region_clear_global_locking: Declares that access processing does 996 * not depend on the QEMU global lock. 997 * 998 * By clearing this property, accesses to the memory region will be processed 999 * outside of QEMU's global lock (unless the lock is held on when issuing the 1000 * access request). In this case, the device model implementing the access 1001 * handlers is responsible for synchronization of concurrency. 1002 * 1003 * @mr: the memory region to be updated. 1004 */ 1005 void memory_region_clear_global_locking(MemoryRegion *mr); 1006 1007 /** 1008 * memory_region_add_eventfd: Request an eventfd to be triggered when a word 1009 * is written to a location. 1010 * 1011 * Marks a word in an IO region (initialized with memory_region_init_io()) 1012 * as a trigger for an eventfd event. The I/O callback will not be called. 1013 * The caller must be prepared to handle failure (that is, take the required 1014 * action if the callback _is_ called). 1015 * 1016 * @mr: the memory region being updated. 1017 * @addr: the address within @mr that is to be monitored 1018 * @size: the size of the access to trigger the eventfd 1019 * @match_data: whether to match against @data, instead of just @addr 1020 * @data: the data to match against the guest write 1021 * @fd: the eventfd to be triggered when @addr, @size, and @data all match. 1022 **/ 1023 void memory_region_add_eventfd(MemoryRegion *mr, 1024 hwaddr addr, 1025 unsigned size, 1026 bool match_data, 1027 uint64_t data, 1028 EventNotifier *e); 1029 1030 /** 1031 * memory_region_del_eventfd: Cancel an eventfd. 1032 * 1033 * Cancels an eventfd trigger requested by a previous 1034 * memory_region_add_eventfd() call. 1035 * 1036 * @mr: the memory region being updated. 1037 * @addr: the address within @mr that is to be monitored 1038 * @size: the size of the access to trigger the eventfd 1039 * @match_data: whether to match against @data, instead of just @addr 1040 * @data: the data to match against the guest write 1041 * @fd: the eventfd to be triggered when @addr, @size, and @data all match. 1042 */ 1043 void memory_region_del_eventfd(MemoryRegion *mr, 1044 hwaddr addr, 1045 unsigned size, 1046 bool match_data, 1047 uint64_t data, 1048 EventNotifier *e); 1049 1050 /** 1051 * memory_region_add_subregion: Add a subregion to a container. 1052 * 1053 * Adds a subregion at @offset. The subregion may not overlap with other 1054 * subregions (except for those explicitly marked as overlapping). A region 1055 * may only be added once as a subregion (unless removed with 1056 * memory_region_del_subregion()); use memory_region_init_alias() if you 1057 * want a region to be a subregion in multiple locations. 1058 * 1059 * @mr: the region to contain the new subregion; must be a container 1060 * initialized with memory_region_init(). 1061 * @offset: the offset relative to @mr where @subregion is added. 1062 * @subregion: the subregion to be added. 1063 */ 1064 void memory_region_add_subregion(MemoryRegion *mr, 1065 hwaddr offset, 1066 MemoryRegion *subregion); 1067 /** 1068 * memory_region_add_subregion_overlap: Add a subregion to a container 1069 * with overlap. 1070 * 1071 * Adds a subregion at @offset. The subregion may overlap with other 1072 * subregions. Conflicts are resolved by having a higher @priority hide a 1073 * lower @priority. Subregions without priority are taken as @priority 0. 1074 * A region may only be added once as a subregion (unless removed with 1075 * memory_region_del_subregion()); use memory_region_init_alias() if you 1076 * want a region to be a subregion in multiple locations. 1077 * 1078 * @mr: the region to contain the new subregion; must be a container 1079 * initialized with memory_region_init(). 1080 * @offset: the offset relative to @mr where @subregion is added. 1081 * @subregion: the subregion to be added. 1082 * @priority: used for resolving overlaps; highest priority wins. 1083 */ 1084 void memory_region_add_subregion_overlap(MemoryRegion *mr, 1085 hwaddr offset, 1086 MemoryRegion *subregion, 1087 int priority); 1088 1089 /** 1090 * memory_region_get_ram_addr: Get the ram address associated with a memory 1091 * region 1092 */ 1093 ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr); 1094 1095 uint64_t memory_region_get_alignment(const MemoryRegion *mr); 1096 /** 1097 * memory_region_del_subregion: Remove a subregion. 1098 * 1099 * Removes a subregion from its container. 1100 * 1101 * @mr: the container to be updated. 1102 * @subregion: the region being removed; must be a current subregion of @mr. 1103 */ 1104 void memory_region_del_subregion(MemoryRegion *mr, 1105 MemoryRegion *subregion); 1106 1107 /* 1108 * memory_region_set_enabled: dynamically enable or disable a region 1109 * 1110 * Enables or disables a memory region. A disabled memory region 1111 * ignores all accesses to itself and its subregions. It does not 1112 * obscure sibling subregions with lower priority - it simply behaves as 1113 * if it was removed from the hierarchy. 1114 * 1115 * Regions default to being enabled. 1116 * 1117 * @mr: the region to be updated 1118 * @enabled: whether to enable or disable the region 1119 */ 1120 void memory_region_set_enabled(MemoryRegion *mr, bool enabled); 1121 1122 /* 1123 * memory_region_set_address: dynamically update the address of a region 1124 * 1125 * Dynamically updates the address of a region, relative to its container. 1126 * May be used on regions are currently part of a memory hierarchy. 1127 * 1128 * @mr: the region to be updated 1129 * @addr: new address, relative to container region 1130 */ 1131 void memory_region_set_address(MemoryRegion *mr, hwaddr addr); 1132 1133 /* 1134 * memory_region_set_size: dynamically update the size of a region. 1135 * 1136 * Dynamically updates the size of a region. 1137 * 1138 * @mr: the region to be updated 1139 * @size: used size of the region. 1140 */ 1141 void memory_region_set_size(MemoryRegion *mr, uint64_t size); 1142 1143 /* 1144 * memory_region_set_alias_offset: dynamically update a memory alias's offset 1145 * 1146 * Dynamically updates the offset into the target region that an alias points 1147 * to, as if the fourth argument to memory_region_init_alias() has changed. 1148 * 1149 * @mr: the #MemoryRegion to be updated; should be an alias. 1150 * @offset: the new offset into the target memory region 1151 */ 1152 void memory_region_set_alias_offset(MemoryRegion *mr, 1153 hwaddr offset); 1154 1155 /** 1156 * memory_region_present: checks if an address relative to a @container 1157 * translates into #MemoryRegion within @container 1158 * 1159 * Answer whether a #MemoryRegion within @container covers the address 1160 * @addr. 1161 * 1162 * @container: a #MemoryRegion within which @addr is a relative address 1163 * @addr: the area within @container to be searched 1164 */ 1165 bool memory_region_present(MemoryRegion *container, hwaddr addr); 1166 1167 /** 1168 * memory_region_is_mapped: returns true if #MemoryRegion is mapped 1169 * into any address space. 1170 * 1171 * @mr: a #MemoryRegion which should be checked if it's mapped 1172 */ 1173 bool memory_region_is_mapped(MemoryRegion *mr); 1174 1175 /** 1176 * memory_region_find: translate an address/size relative to a 1177 * MemoryRegion into a #MemoryRegionSection. 1178 * 1179 * Locates the first #MemoryRegion within @mr that overlaps the range 1180 * given by @addr and @size. 1181 * 1182 * Returns a #MemoryRegionSection that describes a contiguous overlap. 1183 * It will have the following characteristics: 1184 * .@size = 0 iff no overlap was found 1185 * .@mr is non-%NULL iff an overlap was found 1186 * 1187 * Remember that in the return value the @offset_within_region is 1188 * relative to the returned region (in the .@mr field), not to the 1189 * @mr argument. 1190 * 1191 * Similarly, the .@offset_within_address_space is relative to the 1192 * address space that contains both regions, the passed and the 1193 * returned one. However, in the special case where the @mr argument 1194 * has no container (and thus is the root of the address space), the 1195 * following will hold: 1196 * .@offset_within_address_space >= @addr 1197 * .@offset_within_address_space + .@size <= @addr + @size 1198 * 1199 * @mr: a MemoryRegion within which @addr is a relative address 1200 * @addr: start of the area within @as to be searched 1201 * @size: size of the area to be searched 1202 */ 1203 MemoryRegionSection memory_region_find(MemoryRegion *mr, 1204 hwaddr addr, uint64_t size); 1205 1206 /** 1207 * memory_global_dirty_log_sync: synchronize the dirty log for all memory 1208 * 1209 * Synchronizes the dirty page log for all address spaces. 1210 */ 1211 void memory_global_dirty_log_sync(void); 1212 1213 /** 1214 * memory_region_transaction_begin: Start a transaction. 1215 * 1216 * During a transaction, changes will be accumulated and made visible 1217 * only when the transaction ends (is committed). 1218 */ 1219 void memory_region_transaction_begin(void); 1220 1221 /** 1222 * memory_region_transaction_commit: Commit a transaction and make changes 1223 * visible to the guest. 1224 */ 1225 void memory_region_transaction_commit(void); 1226 1227 /** 1228 * memory_listener_register: register callbacks to be called when memory 1229 * sections are mapped or unmapped into an address 1230 * space 1231 * 1232 * @listener: an object containing the callbacks to be called 1233 * @filter: if non-%NULL, only regions in this address space will be observed 1234 */ 1235 void memory_listener_register(MemoryListener *listener, AddressSpace *filter); 1236 1237 /** 1238 * memory_listener_unregister: undo the effect of memory_listener_register() 1239 * 1240 * @listener: an object containing the callbacks to be removed 1241 */ 1242 void memory_listener_unregister(MemoryListener *listener); 1243 1244 /** 1245 * memory_global_dirty_log_start: begin dirty logging for all regions 1246 */ 1247 void memory_global_dirty_log_start(void); 1248 1249 /** 1250 * memory_global_dirty_log_stop: end dirty logging for all regions 1251 */ 1252 void memory_global_dirty_log_stop(void); 1253 1254 void mtree_info(fprintf_function mon_printf, void *f); 1255 1256 /** 1257 * memory_region_dispatch_read: perform a read directly to the specified 1258 * MemoryRegion. 1259 * 1260 * @mr: #MemoryRegion to access 1261 * @addr: address within that region 1262 * @pval: pointer to uint64_t which the data is written to 1263 * @size: size of the access in bytes 1264 * @attrs: memory transaction attributes to use for the access 1265 */ 1266 MemTxResult memory_region_dispatch_read(MemoryRegion *mr, 1267 hwaddr addr, 1268 uint64_t *pval, 1269 unsigned size, 1270 MemTxAttrs attrs); 1271 /** 1272 * memory_region_dispatch_write: perform a write directly to the specified 1273 * MemoryRegion. 1274 * 1275 * @mr: #MemoryRegion to access 1276 * @addr: address within that region 1277 * @data: data to write 1278 * @size: size of the access in bytes 1279 * @attrs: memory transaction attributes to use for the access 1280 */ 1281 MemTxResult memory_region_dispatch_write(MemoryRegion *mr, 1282 hwaddr addr, 1283 uint64_t data, 1284 unsigned size, 1285 MemTxAttrs attrs); 1286 1287 /** 1288 * address_space_init: initializes an address space 1289 * 1290 * @as: an uninitialized #AddressSpace 1291 * @root: a #MemoryRegion that routes addresses for the address space 1292 * @name: an address space name. The name is only used for debugging 1293 * output. 1294 */ 1295 void address_space_init(AddressSpace *as, MemoryRegion *root, const char *name); 1296 1297 /** 1298 * address_space_init_shareable: return an address space for a memory region, 1299 * creating it if it does not already exist 1300 * 1301 * @root: a #MemoryRegion that routes addresses for the address space 1302 * @name: an address space name. The name is only used for debugging 1303 * output. 1304 * 1305 * This function will return a pointer to an existing AddressSpace 1306 * which was initialized with the specified MemoryRegion, or it will 1307 * create and initialize one if it does not already exist. The ASes 1308 * are reference-counted, so the memory will be freed automatically 1309 * when the AddressSpace is destroyed via address_space_destroy. 1310 */ 1311 AddressSpace *address_space_init_shareable(MemoryRegion *root, 1312 const char *name); 1313 1314 /** 1315 * address_space_destroy: destroy an address space 1316 * 1317 * Releases all resources associated with an address space. After an address space 1318 * is destroyed, its root memory region (given by address_space_init()) may be destroyed 1319 * as well. 1320 * 1321 * @as: address space to be destroyed 1322 */ 1323 void address_space_destroy(AddressSpace *as); 1324 1325 /** 1326 * address_space_rw: read from or write to an address space. 1327 * 1328 * Return a MemTxResult indicating whether the operation succeeded 1329 * or failed (eg unassigned memory, device rejected the transaction, 1330 * IOMMU fault). 1331 * 1332 * @as: #AddressSpace to be accessed 1333 * @addr: address within that address space 1334 * @attrs: memory transaction attributes 1335 * @buf: buffer with the data transferred 1336 * @is_write: indicates the transfer direction 1337 */ 1338 MemTxResult address_space_rw(AddressSpace *as, hwaddr addr, 1339 MemTxAttrs attrs, uint8_t *buf, 1340 int len, bool is_write); 1341 1342 /** 1343 * address_space_write: write to address space. 1344 * 1345 * Return a MemTxResult indicating whether the operation succeeded 1346 * or failed (eg unassigned memory, device rejected the transaction, 1347 * IOMMU fault). 1348 * 1349 * @as: #AddressSpace to be accessed 1350 * @addr: address within that address space 1351 * @attrs: memory transaction attributes 1352 * @buf: buffer with the data transferred 1353 */ 1354 MemTxResult address_space_write(AddressSpace *as, hwaddr addr, 1355 MemTxAttrs attrs, 1356 const uint8_t *buf, int len); 1357 1358 /* address_space_ld*: load from an address space 1359 * address_space_st*: store to an address space 1360 * 1361 * These functions perform a load or store of the byte, word, 1362 * longword or quad to the specified address within the AddressSpace. 1363 * The _le suffixed functions treat the data as little endian; 1364 * _be indicates big endian; no suffix indicates "same endianness 1365 * as guest CPU". 1366 * 1367 * The "guest CPU endianness" accessors are deprecated for use outside 1368 * target-* code; devices should be CPU-agnostic and use either the LE 1369 * or the BE accessors. 1370 * 1371 * @as #AddressSpace to be accessed 1372 * @addr: address within that address space 1373 * @val: data value, for stores 1374 * @attrs: memory transaction attributes 1375 * @result: location to write the success/failure of the transaction; 1376 * if NULL, this information is discarded 1377 */ 1378 uint32_t address_space_ldub(AddressSpace *as, hwaddr addr, 1379 MemTxAttrs attrs, MemTxResult *result); 1380 uint32_t address_space_lduw_le(AddressSpace *as, hwaddr addr, 1381 MemTxAttrs attrs, MemTxResult *result); 1382 uint32_t address_space_lduw_be(AddressSpace *as, hwaddr addr, 1383 MemTxAttrs attrs, MemTxResult *result); 1384 uint32_t address_space_ldl_le(AddressSpace *as, hwaddr addr, 1385 MemTxAttrs attrs, MemTxResult *result); 1386 uint32_t address_space_ldl_be(AddressSpace *as, hwaddr addr, 1387 MemTxAttrs attrs, MemTxResult *result); 1388 uint64_t address_space_ldq_le(AddressSpace *as, hwaddr addr, 1389 MemTxAttrs attrs, MemTxResult *result); 1390 uint64_t address_space_ldq_be(AddressSpace *as, hwaddr addr, 1391 MemTxAttrs attrs, MemTxResult *result); 1392 void address_space_stb(AddressSpace *as, hwaddr addr, uint32_t val, 1393 MemTxAttrs attrs, MemTxResult *result); 1394 void address_space_stw_le(AddressSpace *as, hwaddr addr, uint32_t val, 1395 MemTxAttrs attrs, MemTxResult *result); 1396 void address_space_stw_be(AddressSpace *as, hwaddr addr, uint32_t val, 1397 MemTxAttrs attrs, MemTxResult *result); 1398 void address_space_stl_le(AddressSpace *as, hwaddr addr, uint32_t val, 1399 MemTxAttrs attrs, MemTxResult *result); 1400 void address_space_stl_be(AddressSpace *as, hwaddr addr, uint32_t val, 1401 MemTxAttrs attrs, MemTxResult *result); 1402 void address_space_stq_le(AddressSpace *as, hwaddr addr, uint64_t val, 1403 MemTxAttrs attrs, MemTxResult *result); 1404 void address_space_stq_be(AddressSpace *as, hwaddr addr, uint64_t val, 1405 MemTxAttrs attrs, MemTxResult *result); 1406 1407 /* address_space_translate: translate an address range into an address space 1408 * into a MemoryRegion and an address range into that section. Should be 1409 * called from an RCU critical section, to avoid that the last reference 1410 * to the returned region disappears after address_space_translate returns. 1411 * 1412 * @as: #AddressSpace to be accessed 1413 * @addr: address within that address space 1414 * @xlat: pointer to address within the returned memory region section's 1415 * #MemoryRegion. 1416 * @len: pointer to length 1417 * @is_write: indicates the transfer direction 1418 */ 1419 MemoryRegion *address_space_translate(AddressSpace *as, hwaddr addr, 1420 hwaddr *xlat, hwaddr *len, 1421 bool is_write); 1422 1423 /* address_space_access_valid: check for validity of accessing an address 1424 * space range 1425 * 1426 * Check whether memory is assigned to the given address space range, and 1427 * access is permitted by any IOMMU regions that are active for the address 1428 * space. 1429 * 1430 * For now, addr and len should be aligned to a page size. This limitation 1431 * will be lifted in the future. 1432 * 1433 * @as: #AddressSpace to be accessed 1434 * @addr: address within that address space 1435 * @len: length of the area to be checked 1436 * @is_write: indicates the transfer direction 1437 */ 1438 bool address_space_access_valid(AddressSpace *as, hwaddr addr, int len, bool is_write); 1439 1440 /* address_space_map: map a physical memory region into a host virtual address 1441 * 1442 * May map a subset of the requested range, given by and returned in @plen. 1443 * May return %NULL if resources needed to perform the mapping are exhausted. 1444 * Use only for reads OR writes - not for read-modify-write operations. 1445 * Use cpu_register_map_client() to know when retrying the map operation is 1446 * likely to succeed. 1447 * 1448 * @as: #AddressSpace to be accessed 1449 * @addr: address within that address space 1450 * @plen: pointer to length of buffer; updated on return 1451 * @is_write: indicates the transfer direction 1452 */ 1453 void *address_space_map(AddressSpace *as, hwaddr addr, 1454 hwaddr *plen, bool is_write); 1455 1456 /* address_space_unmap: Unmaps a memory region previously mapped by address_space_map() 1457 * 1458 * Will also mark the memory as dirty if @is_write == %true. @access_len gives 1459 * the amount of memory that was actually read or written by the caller. 1460 * 1461 * @as: #AddressSpace used 1462 * @addr: address within that address space 1463 * @len: buffer length as returned by address_space_map() 1464 * @access_len: amount of data actually transferred 1465 * @is_write: indicates the transfer direction 1466 */ 1467 void address_space_unmap(AddressSpace *as, void *buffer, hwaddr len, 1468 int is_write, hwaddr access_len); 1469 1470 1471 /* Internal functions, part of the implementation of address_space_read. */ 1472 MemTxResult address_space_read_continue(AddressSpace *as, hwaddr addr, 1473 MemTxAttrs attrs, uint8_t *buf, 1474 int len, hwaddr addr1, hwaddr l, 1475 MemoryRegion *mr); 1476 MemTxResult address_space_read_full(AddressSpace *as, hwaddr addr, 1477 MemTxAttrs attrs, uint8_t *buf, int len); 1478 void *qemu_map_ram_ptr(RAMBlock *ram_block, ram_addr_t addr); 1479 1480 static inline bool memory_access_is_direct(MemoryRegion *mr, bool is_write) 1481 { 1482 if (is_write) { 1483 return memory_region_is_ram(mr) && 1484 !mr->readonly && !memory_region_is_ram_device(mr); 1485 } else { 1486 return (memory_region_is_ram(mr) && !memory_region_is_ram_device(mr)) || 1487 memory_region_is_romd(mr); 1488 } 1489 } 1490 1491 /** 1492 * address_space_read: read from an address space. 1493 * 1494 * Return a MemTxResult indicating whether the operation succeeded 1495 * or failed (eg unassigned memory, device rejected the transaction, 1496 * IOMMU fault). 1497 * 1498 * @as: #AddressSpace to be accessed 1499 * @addr: address within that address space 1500 * @attrs: memory transaction attributes 1501 * @buf: buffer with the data transferred 1502 */ 1503 static inline __attribute__((__always_inline__)) 1504 MemTxResult address_space_read(AddressSpace *as, hwaddr addr, MemTxAttrs attrs, 1505 uint8_t *buf, int len) 1506 { 1507 MemTxResult result = MEMTX_OK; 1508 hwaddr l, addr1; 1509 void *ptr; 1510 MemoryRegion *mr; 1511 1512 if (__builtin_constant_p(len)) { 1513 if (len) { 1514 rcu_read_lock(); 1515 l = len; 1516 mr = address_space_translate(as, addr, &addr1, &l, false); 1517 if (len == l && memory_access_is_direct(mr, false)) { 1518 ptr = qemu_map_ram_ptr(mr->ram_block, addr1); 1519 memcpy(buf, ptr, len); 1520 } else { 1521 result = address_space_read_continue(as, addr, attrs, buf, len, 1522 addr1, l, mr); 1523 } 1524 rcu_read_unlock(); 1525 } 1526 } else { 1527 result = address_space_read_full(as, addr, attrs, buf, len); 1528 } 1529 return result; 1530 } 1531 1532 #endif 1533 1534 #endif 1535