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 <stdint.h> 25 #include <stdbool.h> 26 #include "qemu-common.h" 27 #include "exec/cpu-common.h" 28 #ifndef CONFIG_USER_ONLY 29 #include "exec/hwaddr.h" 30 #endif 31 #include "exec/memattrs.h" 32 #include "qemu/queue.h" 33 #include "qemu/int128.h" 34 #include "qemu/notify.h" 35 #include "qapi/error.h" 36 #include "qom/object.h" 37 #include "qemu/rcu.h" 38 39 #define MAX_PHYS_ADDR_SPACE_BITS 62 40 #define MAX_PHYS_ADDR (((hwaddr)1 << MAX_PHYS_ADDR_SPACE_BITS) - 1) 41 42 #define TYPE_MEMORY_REGION "qemu:memory-region" 43 #define MEMORY_REGION(obj) \ 44 OBJECT_CHECK(MemoryRegion, (obj), TYPE_MEMORY_REGION) 45 46 typedef struct MemoryRegionOps MemoryRegionOps; 47 typedef struct MemoryRegionMmio MemoryRegionMmio; 48 49 struct MemoryRegionMmio { 50 CPUReadMemoryFunc *read[3]; 51 CPUWriteMemoryFunc *write[3]; 52 }; 53 54 typedef struct IOMMUTLBEntry IOMMUTLBEntry; 55 56 /* See address_space_translate: bit 0 is read, bit 1 is write. */ 57 typedef enum { 58 IOMMU_NONE = 0, 59 IOMMU_RO = 1, 60 IOMMU_WO = 2, 61 IOMMU_RW = 3, 62 } IOMMUAccessFlags; 63 64 struct IOMMUTLBEntry { 65 AddressSpace *target_as; 66 hwaddr iova; 67 hwaddr translated_addr; 68 hwaddr addr_mask; /* 0xfff = 4k translation */ 69 IOMMUAccessFlags perm; 70 }; 71 72 /* New-style MMIO accessors can indicate that the transaction failed. 73 * A zero (MEMTX_OK) response means success; anything else is a failure 74 * of some kind. The memory subsystem will bitwise-OR together results 75 * if it is synthesizing an operation from multiple smaller accesses. 76 */ 77 #define MEMTX_OK 0 78 #define MEMTX_ERROR (1U << 0) /* device returned an error */ 79 #define MEMTX_DECODE_ERROR (1U << 1) /* nothing at that address */ 80 typedef uint32_t MemTxResult; 81 82 /* 83 * Memory region callbacks 84 */ 85 struct MemoryRegionOps { 86 /* Read from the memory region. @addr is relative to @mr; @size is 87 * in bytes. */ 88 uint64_t (*read)(void *opaque, 89 hwaddr addr, 90 unsigned size); 91 /* Write to the memory region. @addr is relative to @mr; @size is 92 * in bytes. */ 93 void (*write)(void *opaque, 94 hwaddr addr, 95 uint64_t data, 96 unsigned size); 97 98 MemTxResult (*read_with_attrs)(void *opaque, 99 hwaddr addr, 100 uint64_t *data, 101 unsigned size, 102 MemTxAttrs attrs); 103 MemTxResult (*write_with_attrs)(void *opaque, 104 hwaddr addr, 105 uint64_t data, 106 unsigned size, 107 MemTxAttrs attrs); 108 109 enum device_endian endianness; 110 /* Guest-visible constraints: */ 111 struct { 112 /* If nonzero, specify bounds on access sizes beyond which a machine 113 * check is thrown. 114 */ 115 unsigned min_access_size; 116 unsigned max_access_size; 117 /* If true, unaligned accesses are supported. Otherwise unaligned 118 * accesses throw machine checks. 119 */ 120 bool unaligned; 121 /* 122 * If present, and returns #false, the transaction is not accepted 123 * by the device (and results in machine dependent behaviour such 124 * as a machine check exception). 125 */ 126 bool (*accepts)(void *opaque, hwaddr addr, 127 unsigned size, bool is_write); 128 } valid; 129 /* Internal implementation constraints: */ 130 struct { 131 /* If nonzero, specifies the minimum size implemented. Smaller sizes 132 * will be rounded upwards and a partial result will be returned. 133 */ 134 unsigned min_access_size; 135 /* If nonzero, specifies the maximum size implemented. Larger sizes 136 * will be done as a series of accesses with smaller sizes. 137 */ 138 unsigned max_access_size; 139 /* If true, unaligned accesses are supported. Otherwise all accesses 140 * are converted to (possibly multiple) naturally aligned accesses. 141 */ 142 bool unaligned; 143 } impl; 144 145 /* If .read and .write are not present, old_mmio may be used for 146 * backwards compatibility with old mmio registration 147 */ 148 const MemoryRegionMmio old_mmio; 149 }; 150 151 typedef struct MemoryRegionIOMMUOps MemoryRegionIOMMUOps; 152 153 struct MemoryRegionIOMMUOps { 154 /* Return a TLB entry that contains a given address. */ 155 IOMMUTLBEntry (*translate)(MemoryRegion *iommu, hwaddr addr, bool is_write); 156 }; 157 158 typedef struct CoalescedMemoryRange CoalescedMemoryRange; 159 typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd; 160 161 struct MemoryRegion { 162 Object parent_obj; 163 /* All fields are private - violators will be prosecuted */ 164 const MemoryRegionOps *ops; 165 const MemoryRegionIOMMUOps *iommu_ops; 166 void *opaque; 167 MemoryRegion *container; 168 Int128 size; 169 hwaddr addr; 170 void (*destructor)(MemoryRegion *mr); 171 ram_addr_t ram_addr; 172 uint64_t align; 173 bool subpage; 174 bool terminates; 175 bool romd_mode; 176 bool ram; 177 bool skip_dump; 178 bool readonly; /* For RAM regions */ 179 bool enabled; 180 bool rom_device; 181 bool warning_printed; /* For reservations */ 182 bool flush_coalesced_mmio; 183 MemoryRegion *alias; 184 hwaddr alias_offset; 185 int32_t priority; 186 bool may_overlap; 187 QTAILQ_HEAD(subregions, MemoryRegion) subregions; 188 QTAILQ_ENTRY(MemoryRegion) subregions_link; 189 QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced; 190 const char *name; 191 uint8_t dirty_log_mask; 192 unsigned ioeventfd_nb; 193 MemoryRegionIoeventfd *ioeventfds; 194 NotifierList iommu_notify; 195 }; 196 197 /** 198 * MemoryListener: callbacks structure for updates to the physical memory map 199 * 200 * Allows a component to adjust to changes in the guest-visible memory map. 201 * Use with memory_listener_register() and memory_listener_unregister(). 202 */ 203 struct MemoryListener { 204 void (*begin)(MemoryListener *listener); 205 void (*commit)(MemoryListener *listener); 206 void (*region_add)(MemoryListener *listener, MemoryRegionSection *section); 207 void (*region_del)(MemoryListener *listener, MemoryRegionSection *section); 208 void (*region_nop)(MemoryListener *listener, MemoryRegionSection *section); 209 void (*log_start)(MemoryListener *listener, MemoryRegionSection *section); 210 void (*log_stop)(MemoryListener *listener, MemoryRegionSection *section); 211 void (*log_sync)(MemoryListener *listener, MemoryRegionSection *section); 212 void (*log_global_start)(MemoryListener *listener); 213 void (*log_global_stop)(MemoryListener *listener); 214 void (*eventfd_add)(MemoryListener *listener, MemoryRegionSection *section, 215 bool match_data, uint64_t data, EventNotifier *e); 216 void (*eventfd_del)(MemoryListener *listener, MemoryRegionSection *section, 217 bool match_data, uint64_t data, EventNotifier *e); 218 void (*coalesced_mmio_add)(MemoryListener *listener, MemoryRegionSection *section, 219 hwaddr addr, hwaddr len); 220 void (*coalesced_mmio_del)(MemoryListener *listener, MemoryRegionSection *section, 221 hwaddr addr, hwaddr len); 222 /* Lower = earlier (during add), later (during del) */ 223 unsigned priority; 224 AddressSpace *address_space_filter; 225 QTAILQ_ENTRY(MemoryListener) link; 226 }; 227 228 /** 229 * AddressSpace: describes a mapping of addresses to #MemoryRegion objects 230 */ 231 struct AddressSpace { 232 /* All fields are private. */ 233 struct rcu_head rcu; 234 char *name; 235 MemoryRegion *root; 236 237 /* Accessed via RCU. */ 238 struct FlatView *current_map; 239 240 int ioeventfd_nb; 241 struct MemoryRegionIoeventfd *ioeventfds; 242 struct AddressSpaceDispatch *dispatch; 243 struct AddressSpaceDispatch *next_dispatch; 244 MemoryListener dispatch_listener; 245 246 QTAILQ_ENTRY(AddressSpace) address_spaces_link; 247 }; 248 249 /** 250 * MemoryRegionSection: describes a fragment of a #MemoryRegion 251 * 252 * @mr: the region, or %NULL if empty 253 * @address_space: the address space the region is mapped in 254 * @offset_within_region: the beginning of the section, relative to @mr's start 255 * @size: the size of the section; will not exceed @mr's boundaries 256 * @offset_within_address_space: the address of the first byte of the section 257 * relative to the region's address space 258 * @readonly: writes to this section are ignored 259 */ 260 struct MemoryRegionSection { 261 MemoryRegion *mr; 262 AddressSpace *address_space; 263 hwaddr offset_within_region; 264 Int128 size; 265 hwaddr offset_within_address_space; 266 bool readonly; 267 }; 268 269 /** 270 * memory_region_init: Initialize a memory region 271 * 272 * The region typically acts as a container for other memory regions. Use 273 * memory_region_add_subregion() to add subregions. 274 * 275 * @mr: the #MemoryRegion to be initialized 276 * @owner: the object that tracks the region's reference count 277 * @name: used for debugging; not visible to the user or ABI 278 * @size: size of the region; any subregions beyond this size will be clipped 279 */ 280 void memory_region_init(MemoryRegion *mr, 281 struct Object *owner, 282 const char *name, 283 uint64_t size); 284 285 /** 286 * memory_region_ref: Add 1 to a memory region's reference count 287 * 288 * Whenever memory regions are accessed outside the BQL, they need to be 289 * preserved against hot-unplug. MemoryRegions actually do not have their 290 * own reference count; they piggyback on a QOM object, their "owner". 291 * This function adds a reference to the owner. 292 * 293 * All MemoryRegions must have an owner if they can disappear, even if the 294 * device they belong to operates exclusively under the BQL. This is because 295 * the region could be returned at any time by memory_region_find, and this 296 * is usually under guest control. 297 * 298 * @mr: the #MemoryRegion 299 */ 300 void memory_region_ref(MemoryRegion *mr); 301 302 /** 303 * memory_region_unref: Remove 1 to a memory region's reference count 304 * 305 * Whenever memory regions are accessed outside the BQL, they need to be 306 * preserved against hot-unplug. MemoryRegions actually do not have their 307 * own reference count; they piggyback on a QOM object, their "owner". 308 * This function removes a reference to the owner and possibly destroys it. 309 * 310 * @mr: the #MemoryRegion 311 */ 312 void memory_region_unref(MemoryRegion *mr); 313 314 /** 315 * memory_region_init_io: Initialize an I/O memory region. 316 * 317 * Accesses into the region will cause the callbacks in @ops to be called. 318 * if @size is nonzero, subregions will be clipped to @size. 319 * 320 * @mr: the #MemoryRegion to be initialized. 321 * @owner: the object that tracks the region's reference count 322 * @ops: a structure containing read and write callbacks to be used when 323 * I/O is performed on the region. 324 * @opaque: passed to to the read and write callbacks of the @ops structure. 325 * @name: used for debugging; not visible to the user or ABI 326 * @size: size of the region. 327 */ 328 void memory_region_init_io(MemoryRegion *mr, 329 struct Object *owner, 330 const MemoryRegionOps *ops, 331 void *opaque, 332 const char *name, 333 uint64_t size); 334 335 /** 336 * memory_region_init_ram: Initialize RAM memory region. Accesses into the 337 * region will modify memory directly. 338 * 339 * @mr: the #MemoryRegion to be initialized. 340 * @owner: the object that tracks the region's reference count 341 * @name: the name of the region. 342 * @size: size of the region. 343 * @errp: pointer to Error*, to store an error if it happens. 344 */ 345 void memory_region_init_ram(MemoryRegion *mr, 346 struct Object *owner, 347 const char *name, 348 uint64_t size, 349 Error **errp); 350 351 /** 352 * memory_region_init_resizeable_ram: Initialize memory region with resizeable 353 * RAM. Accesses into the region will 354 * modify memory directly. Only an initial 355 * portion of this RAM is actually used. 356 * The used size can change across reboots. 357 * 358 * @mr: the #MemoryRegion to be initialized. 359 * @owner: the object that tracks the region's reference count 360 * @name: the name of the region. 361 * @size: used size of the region. 362 * @max_size: max size of the region. 363 * @resized: callback to notify owner about used size change. 364 * @errp: pointer to Error*, to store an error if it happens. 365 */ 366 void memory_region_init_resizeable_ram(MemoryRegion *mr, 367 struct Object *owner, 368 const char *name, 369 uint64_t size, 370 uint64_t max_size, 371 void (*resized)(const char*, 372 uint64_t length, 373 void *host), 374 Error **errp); 375 #ifdef __linux__ 376 /** 377 * memory_region_init_ram_from_file: Initialize RAM memory region with a 378 * mmap-ed backend. 379 * 380 * @mr: the #MemoryRegion to be initialized. 381 * @owner: the object that tracks the region's reference count 382 * @name: the name of the region. 383 * @size: size of the region. 384 * @share: %true if memory must be mmaped with the MAP_SHARED flag 385 * @path: the path in which to allocate the RAM. 386 * @errp: pointer to Error*, to store an error if it happens. 387 */ 388 void memory_region_init_ram_from_file(MemoryRegion *mr, 389 struct Object *owner, 390 const char *name, 391 uint64_t size, 392 bool share, 393 const char *path, 394 Error **errp); 395 #endif 396 397 /** 398 * memory_region_init_ram_ptr: Initialize RAM memory region from a 399 * user-provided pointer. Accesses into the 400 * region will modify memory directly. 401 * 402 * @mr: the #MemoryRegion to be initialized. 403 * @owner: the object that tracks the region's reference count 404 * @name: the name of the region. 405 * @size: size of the region. 406 * @ptr: memory to be mapped; must contain at least @size bytes. 407 */ 408 void memory_region_init_ram_ptr(MemoryRegion *mr, 409 struct Object *owner, 410 const char *name, 411 uint64_t size, 412 void *ptr); 413 414 /** 415 * memory_region_init_alias: Initialize a memory region that aliases all or a 416 * part of another memory region. 417 * 418 * @mr: the #MemoryRegion to be initialized. 419 * @owner: the object that tracks the region's reference count 420 * @name: used for debugging; not visible to the user or ABI 421 * @orig: the region to be referenced; @mr will be equivalent to 422 * @orig between @offset and @offset + @size - 1. 423 * @offset: start of the section in @orig to be referenced. 424 * @size: size of the region. 425 */ 426 void memory_region_init_alias(MemoryRegion *mr, 427 struct Object *owner, 428 const char *name, 429 MemoryRegion *orig, 430 hwaddr offset, 431 uint64_t size); 432 433 /** 434 * memory_region_init_rom_device: Initialize a ROM memory region. Writes are 435 * handled via callbacks. 436 * 437 * @mr: the #MemoryRegion to be initialized. 438 * @owner: the object that tracks the region's reference count 439 * @ops: callbacks for write access handling. 440 * @name: the name of the region. 441 * @size: size of the region. 442 * @errp: pointer to Error*, to store an error if it happens. 443 */ 444 void memory_region_init_rom_device(MemoryRegion *mr, 445 struct Object *owner, 446 const MemoryRegionOps *ops, 447 void *opaque, 448 const char *name, 449 uint64_t size, 450 Error **errp); 451 452 /** 453 * memory_region_init_reservation: Initialize a memory region that reserves 454 * I/O space. 455 * 456 * A reservation region primariy serves debugging purposes. It claims I/O 457 * space that is not supposed to be handled by QEMU itself. Any access via 458 * the memory API will cause an abort(). 459 * 460 * @mr: the #MemoryRegion to be initialized 461 * @owner: the object that tracks the region's reference count 462 * @name: used for debugging; not visible to the user or ABI 463 * @size: size of the region. 464 */ 465 void memory_region_init_reservation(MemoryRegion *mr, 466 struct Object *owner, 467 const char *name, 468 uint64_t size); 469 470 /** 471 * memory_region_init_iommu: Initialize a memory region that translates 472 * addresses 473 * 474 * An IOMMU region translates addresses and forwards accesses to a target 475 * memory region. 476 * 477 * @mr: the #MemoryRegion to be initialized 478 * @owner: the object that tracks the region's reference count 479 * @ops: a function that translates addresses into the @target region 480 * @name: used for debugging; not visible to the user or ABI 481 * @size: size of the region. 482 */ 483 void memory_region_init_iommu(MemoryRegion *mr, 484 struct Object *owner, 485 const MemoryRegionIOMMUOps *ops, 486 const char *name, 487 uint64_t size); 488 489 /** 490 * memory_region_owner: get a memory region's owner. 491 * 492 * @mr: the memory region being queried. 493 */ 494 struct Object *memory_region_owner(MemoryRegion *mr); 495 496 /** 497 * memory_region_size: get a memory region's size. 498 * 499 * @mr: the memory region being queried. 500 */ 501 uint64_t memory_region_size(MemoryRegion *mr); 502 503 /** 504 * memory_region_is_ram: check whether a memory region is random access 505 * 506 * Returns %true is a memory region is random access. 507 * 508 * @mr: the memory region being queried 509 */ 510 bool memory_region_is_ram(MemoryRegion *mr); 511 512 /** 513 * memory_region_is_skip_dump: check whether a memory region should not be 514 * dumped 515 * 516 * Returns %true is a memory region should not be dumped(e.g. VFIO BAR MMAP). 517 * 518 * @mr: the memory region being queried 519 */ 520 bool memory_region_is_skip_dump(MemoryRegion *mr); 521 522 /** 523 * memory_region_set_skip_dump: Set skip_dump flag, dump will ignore this memory 524 * region 525 * 526 * @mr: the memory region being queried 527 */ 528 void memory_region_set_skip_dump(MemoryRegion *mr); 529 530 /** 531 * memory_region_is_romd: check whether a memory region is in ROMD mode 532 * 533 * Returns %true if a memory region is a ROM device and currently set to allow 534 * direct reads. 535 * 536 * @mr: the memory region being queried 537 */ 538 static inline bool memory_region_is_romd(MemoryRegion *mr) 539 { 540 return mr->rom_device && mr->romd_mode; 541 } 542 543 /** 544 * memory_region_is_iommu: check whether a memory region is an iommu 545 * 546 * Returns %true is a memory region is an iommu. 547 * 548 * @mr: the memory region being queried 549 */ 550 bool memory_region_is_iommu(MemoryRegion *mr); 551 552 /** 553 * memory_region_notify_iommu: notify a change in an IOMMU translation entry. 554 * 555 * @mr: the memory region that was changed 556 * @entry: the new entry in the IOMMU translation table. The entry 557 * replaces all old entries for the same virtual I/O address range. 558 * Deleted entries have .@perm == 0. 559 */ 560 void memory_region_notify_iommu(MemoryRegion *mr, 561 IOMMUTLBEntry entry); 562 563 /** 564 * memory_region_register_iommu_notifier: register a notifier for changes to 565 * IOMMU translation entries. 566 * 567 * @mr: the memory region to observe 568 * @n: the notifier to be added; the notifier receives a pointer to an 569 * #IOMMUTLBEntry as the opaque value; the pointer ceases to be 570 * valid on exit from the notifier. 571 */ 572 void memory_region_register_iommu_notifier(MemoryRegion *mr, Notifier *n); 573 574 /** 575 * memory_region_unregister_iommu_notifier: unregister a notifier for 576 * changes to IOMMU translation entries. 577 * 578 * @n: the notifier to be removed. 579 */ 580 void memory_region_unregister_iommu_notifier(Notifier *n); 581 582 /** 583 * memory_region_name: get a memory region's name 584 * 585 * Returns the string that was used to initialize the memory region. 586 * 587 * @mr: the memory region being queried 588 */ 589 const char *memory_region_name(const MemoryRegion *mr); 590 591 /** 592 * memory_region_is_logging: return whether a memory region is logging writes 593 * 594 * Returns %true if the memory region is logging writes 595 * 596 * @mr: the memory region being queried 597 */ 598 bool memory_region_is_logging(MemoryRegion *mr); 599 600 /** 601 * memory_region_is_rom: check whether a memory region is ROM 602 * 603 * Returns %true is a memory region is read-only memory. 604 * 605 * @mr: the memory region being queried 606 */ 607 bool memory_region_is_rom(MemoryRegion *mr); 608 609 /** 610 * memory_region_get_fd: Get a file descriptor backing a RAM memory region. 611 * 612 * Returns a file descriptor backing a file-based RAM memory region, 613 * or -1 if the region is not a file-based RAM memory region. 614 * 615 * @mr: the RAM or alias memory region being queried. 616 */ 617 int memory_region_get_fd(MemoryRegion *mr); 618 619 /** 620 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region. 621 * 622 * Returns a host pointer to a RAM memory region (created with 623 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with 624 * care. 625 * 626 * @mr: the memory region being queried. 627 */ 628 void *memory_region_get_ram_ptr(MemoryRegion *mr); 629 630 /* memory_region_ram_resize: Resize a RAM region. 631 * 632 * Only legal before guest might have detected the memory size: e.g. on 633 * incoming migration, or right after reset. 634 * 635 * @mr: a memory region created with @memory_region_init_resizeable_ram. 636 * @newsize: the new size the region 637 * @errp: pointer to Error*, to store an error if it happens. 638 */ 639 void memory_region_ram_resize(MemoryRegion *mr, ram_addr_t newsize, 640 Error **errp); 641 642 /** 643 * memory_region_set_log: Turn dirty logging on or off for a region. 644 * 645 * Turns dirty logging on or off for a specified client (display, migration). 646 * Only meaningful for RAM regions. 647 * 648 * @mr: the memory region being updated. 649 * @log: whether dirty logging is to be enabled or disabled. 650 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 651 * %DIRTY_MEMORY_VGA. 652 */ 653 void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client); 654 655 /** 656 * memory_region_get_dirty: Check whether a range of bytes is dirty 657 * for a specified client. 658 * 659 * Checks whether a range of bytes has been written to since the last 660 * call to memory_region_reset_dirty() with the same @client. Dirty logging 661 * must be enabled. 662 * 663 * @mr: the memory region being queried. 664 * @addr: the address (relative to the start of the region) being queried. 665 * @size: the size of the range being queried. 666 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 667 * %DIRTY_MEMORY_VGA. 668 */ 669 bool memory_region_get_dirty(MemoryRegion *mr, hwaddr addr, 670 hwaddr size, unsigned client); 671 672 /** 673 * memory_region_set_dirty: Mark a range of bytes as dirty in a memory region. 674 * 675 * Marks a range of bytes as dirty, after it has been dirtied outside 676 * guest code. 677 * 678 * @mr: the memory region being dirtied. 679 * @addr: the address (relative to the start of the region) being dirtied. 680 * @size: size of the range being dirtied. 681 */ 682 void memory_region_set_dirty(MemoryRegion *mr, hwaddr addr, 683 hwaddr size); 684 685 /** 686 * memory_region_test_and_clear_dirty: Check whether a range of bytes is dirty 687 * for a specified client. It clears them. 688 * 689 * Checks whether a range of bytes has been written to since the last 690 * call to memory_region_reset_dirty() with the same @client. Dirty logging 691 * must be enabled. 692 * 693 * @mr: the memory region being queried. 694 * @addr: the address (relative to the start of the region) being queried. 695 * @size: the size of the range being queried. 696 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 697 * %DIRTY_MEMORY_VGA. 698 */ 699 bool memory_region_test_and_clear_dirty(MemoryRegion *mr, hwaddr addr, 700 hwaddr size, unsigned client); 701 /** 702 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with 703 * any external TLBs (e.g. kvm) 704 * 705 * Flushes dirty information from accelerators such as kvm and vhost-net 706 * and makes it available to users of the memory API. 707 * 708 * @mr: the region being flushed. 709 */ 710 void memory_region_sync_dirty_bitmap(MemoryRegion *mr); 711 712 /** 713 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified 714 * client. 715 * 716 * Marks a range of pages as no longer dirty. 717 * 718 * @mr: the region being updated. 719 * @addr: the start of the subrange being cleaned. 720 * @size: the size of the subrange being cleaned. 721 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or 722 * %DIRTY_MEMORY_VGA. 723 */ 724 void memory_region_reset_dirty(MemoryRegion *mr, hwaddr addr, 725 hwaddr size, unsigned client); 726 727 /** 728 * memory_region_set_readonly: Turn a memory region read-only (or read-write) 729 * 730 * Allows a memory region to be marked as read-only (turning it into a ROM). 731 * only useful on RAM regions. 732 * 733 * @mr: the region being updated. 734 * @readonly: whether rhe region is to be ROM or RAM. 735 */ 736 void memory_region_set_readonly(MemoryRegion *mr, bool readonly); 737 738 /** 739 * memory_region_rom_device_set_romd: enable/disable ROMD mode 740 * 741 * Allows a ROM device (initialized with memory_region_init_rom_device() to 742 * set to ROMD mode (default) or MMIO mode. When it is in ROMD mode, the 743 * device is mapped to guest memory and satisfies read access directly. 744 * When in MMIO mode, reads are forwarded to the #MemoryRegion.read function. 745 * Writes are always handled by the #MemoryRegion.write function. 746 * 747 * @mr: the memory region to be updated 748 * @romd_mode: %true to put the region into ROMD mode 749 */ 750 void memory_region_rom_device_set_romd(MemoryRegion *mr, bool romd_mode); 751 752 /** 753 * memory_region_set_coalescing: Enable memory coalescing for the region. 754 * 755 * Enabled writes to a region to be queued for later processing. MMIO ->write 756 * callbacks may be delayed until a non-coalesced MMIO is issued. 757 * Only useful for IO regions. Roughly similar to write-combining hardware. 758 * 759 * @mr: the memory region to be write coalesced 760 */ 761 void memory_region_set_coalescing(MemoryRegion *mr); 762 763 /** 764 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of 765 * a region. 766 * 767 * Like memory_region_set_coalescing(), but works on a sub-range of a region. 768 * Multiple calls can be issued coalesced disjoint ranges. 769 * 770 * @mr: the memory region to be updated. 771 * @offset: the start of the range within the region to be coalesced. 772 * @size: the size of the subrange to be coalesced. 773 */ 774 void memory_region_add_coalescing(MemoryRegion *mr, 775 hwaddr offset, 776 uint64_t size); 777 778 /** 779 * memory_region_clear_coalescing: Disable MMIO coalescing for the region. 780 * 781 * Disables any coalescing caused by memory_region_set_coalescing() or 782 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory 783 * hardware. 784 * 785 * @mr: the memory region to be updated. 786 */ 787 void memory_region_clear_coalescing(MemoryRegion *mr); 788 789 /** 790 * memory_region_set_flush_coalesced: Enforce memory coalescing flush before 791 * accesses. 792 * 793 * Ensure that pending coalesced MMIO request are flushed before the memory 794 * region is accessed. This property is automatically enabled for all regions 795 * passed to memory_region_set_coalescing() and memory_region_add_coalescing(). 796 * 797 * @mr: the memory region to be updated. 798 */ 799 void memory_region_set_flush_coalesced(MemoryRegion *mr); 800 801 /** 802 * memory_region_clear_flush_coalesced: Disable memory coalescing flush before 803 * accesses. 804 * 805 * Clear the automatic coalesced MMIO flushing enabled via 806 * memory_region_set_flush_coalesced. Note that this service has no effect on 807 * memory regions that have MMIO coalescing enabled for themselves. For them, 808 * automatic flushing will stop once coalescing is disabled. 809 * 810 * @mr: the memory region to be updated. 811 */ 812 void memory_region_clear_flush_coalesced(MemoryRegion *mr); 813 814 /** 815 * memory_region_add_eventfd: Request an eventfd to be triggered when a word 816 * is written to a location. 817 * 818 * Marks a word in an IO region (initialized with memory_region_init_io()) 819 * as a trigger for an eventfd event. The I/O callback will not be called. 820 * The caller must be prepared to handle failure (that is, take the required 821 * action if the callback _is_ called). 822 * 823 * @mr: the memory region being updated. 824 * @addr: the address within @mr that is to be monitored 825 * @size: the size of the access to trigger the eventfd 826 * @match_data: whether to match against @data, instead of just @addr 827 * @data: the data to match against the guest write 828 * @fd: the eventfd to be triggered when @addr, @size, and @data all match. 829 **/ 830 void memory_region_add_eventfd(MemoryRegion *mr, 831 hwaddr addr, 832 unsigned size, 833 bool match_data, 834 uint64_t data, 835 EventNotifier *e); 836 837 /** 838 * memory_region_del_eventfd: Cancel an eventfd. 839 * 840 * Cancels an eventfd trigger requested by a previous 841 * memory_region_add_eventfd() call. 842 * 843 * @mr: the memory region being updated. 844 * @addr: the address within @mr that is to be monitored 845 * @size: the size of the access to trigger the eventfd 846 * @match_data: whether to match against @data, instead of just @addr 847 * @data: the data to match against the guest write 848 * @fd: the eventfd to be triggered when @addr, @size, and @data all match. 849 */ 850 void memory_region_del_eventfd(MemoryRegion *mr, 851 hwaddr addr, 852 unsigned size, 853 bool match_data, 854 uint64_t data, 855 EventNotifier *e); 856 857 /** 858 * memory_region_add_subregion: Add a subregion to a container. 859 * 860 * Adds a subregion at @offset. The subregion may not overlap with other 861 * subregions (except for those explicitly marked as overlapping). A region 862 * may only be added once as a subregion (unless removed with 863 * memory_region_del_subregion()); use memory_region_init_alias() if you 864 * want a region to be a subregion in multiple locations. 865 * 866 * @mr: the region to contain the new subregion; must be a container 867 * initialized with memory_region_init(). 868 * @offset: the offset relative to @mr where @subregion is added. 869 * @subregion: the subregion to be added. 870 */ 871 void memory_region_add_subregion(MemoryRegion *mr, 872 hwaddr offset, 873 MemoryRegion *subregion); 874 /** 875 * memory_region_add_subregion_overlap: Add a subregion to a container 876 * with overlap. 877 * 878 * Adds a subregion at @offset. The subregion may overlap with other 879 * subregions. Conflicts are resolved by having a higher @priority hide a 880 * lower @priority. Subregions without priority are taken as @priority 0. 881 * A region may only be added once as a subregion (unless removed with 882 * memory_region_del_subregion()); use memory_region_init_alias() if you 883 * want a region to be a subregion in multiple locations. 884 * 885 * @mr: the region to contain the new subregion; must be a container 886 * initialized with memory_region_init(). 887 * @offset: the offset relative to @mr where @subregion is added. 888 * @subregion: the subregion to be added. 889 * @priority: used for resolving overlaps; highest priority wins. 890 */ 891 void memory_region_add_subregion_overlap(MemoryRegion *mr, 892 hwaddr offset, 893 MemoryRegion *subregion, 894 int priority); 895 896 /** 897 * memory_region_get_ram_addr: Get the ram address associated with a memory 898 * region 899 * 900 * DO NOT USE THIS FUNCTION. This is a temporary workaround while the Xen 901 * code is being reworked. 902 */ 903 ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr); 904 905 uint64_t memory_region_get_alignment(const MemoryRegion *mr); 906 /** 907 * memory_region_del_subregion: Remove a subregion. 908 * 909 * Removes a subregion from its container. 910 * 911 * @mr: the container to be updated. 912 * @subregion: the region being removed; must be a current subregion of @mr. 913 */ 914 void memory_region_del_subregion(MemoryRegion *mr, 915 MemoryRegion *subregion); 916 917 /* 918 * memory_region_set_enabled: dynamically enable or disable a region 919 * 920 * Enables or disables a memory region. A disabled memory region 921 * ignores all accesses to itself and its subregions. It does not 922 * obscure sibling subregions with lower priority - it simply behaves as 923 * if it was removed from the hierarchy. 924 * 925 * Regions default to being enabled. 926 * 927 * @mr: the region to be updated 928 * @enabled: whether to enable or disable the region 929 */ 930 void memory_region_set_enabled(MemoryRegion *mr, bool enabled); 931 932 /* 933 * memory_region_set_address: dynamically update the address of a region 934 * 935 * Dynamically updates the address of a region, relative to its container. 936 * May be used on regions are currently part of a memory hierarchy. 937 * 938 * @mr: the region to be updated 939 * @addr: new address, relative to container region 940 */ 941 void memory_region_set_address(MemoryRegion *mr, hwaddr addr); 942 943 /* 944 * memory_region_set_size: dynamically update the size of a region. 945 * 946 * Dynamically updates the size of a region. 947 * 948 * @mr: the region to be updated 949 * @size: used size of the region. 950 */ 951 void memory_region_set_size(MemoryRegion *mr, uint64_t size); 952 953 /* 954 * memory_region_set_alias_offset: dynamically update a memory alias's offset 955 * 956 * Dynamically updates the offset into the target region that an alias points 957 * to, as if the fourth argument to memory_region_init_alias() has changed. 958 * 959 * @mr: the #MemoryRegion to be updated; should be an alias. 960 * @offset: the new offset into the target memory region 961 */ 962 void memory_region_set_alias_offset(MemoryRegion *mr, 963 hwaddr offset); 964 965 /** 966 * memory_region_present: checks if an address relative to a @container 967 * translates into #MemoryRegion within @container 968 * 969 * Answer whether a #MemoryRegion within @container covers the address 970 * @addr. 971 * 972 * @container: a #MemoryRegion within which @addr is a relative address 973 * @addr: the area within @container to be searched 974 */ 975 bool memory_region_present(MemoryRegion *container, hwaddr addr); 976 977 /** 978 * memory_region_is_mapped: returns true if #MemoryRegion is mapped 979 * into any address space. 980 * 981 * @mr: a #MemoryRegion which should be checked if it's mapped 982 */ 983 bool memory_region_is_mapped(MemoryRegion *mr); 984 985 /** 986 * memory_region_find: translate an address/size relative to a 987 * MemoryRegion into a #MemoryRegionSection. 988 * 989 * Locates the first #MemoryRegion within @mr that overlaps the range 990 * given by @addr and @size. 991 * 992 * Returns a #MemoryRegionSection that describes a contiguous overlap. 993 * It will have the following characteristics: 994 * .@size = 0 iff no overlap was found 995 * .@mr is non-%NULL iff an overlap was found 996 * 997 * Remember that in the return value the @offset_within_region is 998 * relative to the returned region (in the .@mr field), not to the 999 * @mr argument. 1000 * 1001 * Similarly, the .@offset_within_address_space is relative to the 1002 * address space that contains both regions, the passed and the 1003 * returned one. However, in the special case where the @mr argument 1004 * has no container (and thus is the root of the address space), the 1005 * following will hold: 1006 * .@offset_within_address_space >= @addr 1007 * .@offset_within_address_space + .@size <= @addr + @size 1008 * 1009 * @mr: a MemoryRegion within which @addr is a relative address 1010 * @addr: start of the area within @as to be searched 1011 * @size: size of the area to be searched 1012 */ 1013 MemoryRegionSection memory_region_find(MemoryRegion *mr, 1014 hwaddr addr, uint64_t size); 1015 1016 /** 1017 * address_space_sync_dirty_bitmap: synchronize the dirty log for all memory 1018 * 1019 * Synchronizes the dirty page log for an entire address space. 1020 * @as: the address space that contains the memory being synchronized 1021 */ 1022 void address_space_sync_dirty_bitmap(AddressSpace *as); 1023 1024 /** 1025 * memory_region_transaction_begin: Start a transaction. 1026 * 1027 * During a transaction, changes will be accumulated and made visible 1028 * only when the transaction ends (is committed). 1029 */ 1030 void memory_region_transaction_begin(void); 1031 1032 /** 1033 * memory_region_transaction_commit: Commit a transaction and make changes 1034 * visible to the guest. 1035 */ 1036 void memory_region_transaction_commit(void); 1037 1038 /** 1039 * memory_listener_register: register callbacks to be called when memory 1040 * sections are mapped or unmapped into an address 1041 * space 1042 * 1043 * @listener: an object containing the callbacks to be called 1044 * @filter: if non-%NULL, only regions in this address space will be observed 1045 */ 1046 void memory_listener_register(MemoryListener *listener, AddressSpace *filter); 1047 1048 /** 1049 * memory_listener_unregister: undo the effect of memory_listener_register() 1050 * 1051 * @listener: an object containing the callbacks to be removed 1052 */ 1053 void memory_listener_unregister(MemoryListener *listener); 1054 1055 /** 1056 * memory_global_dirty_log_start: begin dirty logging for all regions 1057 */ 1058 void memory_global_dirty_log_start(void); 1059 1060 /** 1061 * memory_global_dirty_log_stop: end dirty logging for all regions 1062 */ 1063 void memory_global_dirty_log_stop(void); 1064 1065 void mtree_info(fprintf_function mon_printf, void *f); 1066 1067 /** 1068 * memory_region_dispatch_read: perform a read directly to the specified 1069 * MemoryRegion. 1070 * 1071 * @mr: #MemoryRegion to access 1072 * @addr: address within that region 1073 * @pval: pointer to uint64_t which the data is written to 1074 * @size: size of the access in bytes 1075 * @attrs: memory transaction attributes to use for the access 1076 */ 1077 MemTxResult memory_region_dispatch_read(MemoryRegion *mr, 1078 hwaddr addr, 1079 uint64_t *pval, 1080 unsigned size, 1081 MemTxAttrs attrs); 1082 /** 1083 * memory_region_dispatch_write: perform a write directly to the specified 1084 * MemoryRegion. 1085 * 1086 * @mr: #MemoryRegion to access 1087 * @addr: address within that region 1088 * @data: data to write 1089 * @size: size of the access in bytes 1090 * @attrs: memory transaction attributes to use for the access 1091 */ 1092 MemTxResult memory_region_dispatch_write(MemoryRegion *mr, 1093 hwaddr addr, 1094 uint64_t data, 1095 unsigned size, 1096 MemTxAttrs attrs); 1097 1098 /** 1099 * address_space_init: initializes an address space 1100 * 1101 * @as: an uninitialized #AddressSpace 1102 * @root: a #MemoryRegion that routes addesses for the address space 1103 * @name: an address space name. The name is only used for debugging 1104 * output. 1105 */ 1106 void address_space_init(AddressSpace *as, MemoryRegion *root, const char *name); 1107 1108 1109 /** 1110 * address_space_destroy: destroy an address space 1111 * 1112 * Releases all resources associated with an address space. After an address space 1113 * is destroyed, its root memory region (given by address_space_init()) may be destroyed 1114 * as well. 1115 * 1116 * @as: address space to be destroyed 1117 */ 1118 void address_space_destroy(AddressSpace *as); 1119 1120 /** 1121 * address_space_rw: read from or write to an address space. 1122 * 1123 * Return a MemTxResult indicating whether the operation succeeded 1124 * or failed (eg unassigned memory, device rejected the transaction, 1125 * IOMMU fault). 1126 * 1127 * @as: #AddressSpace to be accessed 1128 * @addr: address within that address space 1129 * @attrs: memory transaction attributes 1130 * @buf: buffer with the data transferred 1131 * @is_write: indicates the transfer direction 1132 */ 1133 MemTxResult address_space_rw(AddressSpace *as, hwaddr addr, 1134 MemTxAttrs attrs, uint8_t *buf, 1135 int len, bool is_write); 1136 1137 /** 1138 * address_space_write: write to address space. 1139 * 1140 * Return a MemTxResult indicating whether the operation succeeded 1141 * or failed (eg unassigned memory, device rejected the transaction, 1142 * IOMMU fault). 1143 * 1144 * @as: #AddressSpace to be accessed 1145 * @addr: address within that address space 1146 * @attrs: memory transaction attributes 1147 * @buf: buffer with the data transferred 1148 */ 1149 MemTxResult address_space_write(AddressSpace *as, hwaddr addr, 1150 MemTxAttrs attrs, 1151 const uint8_t *buf, int len); 1152 1153 /** 1154 * address_space_read: read from an address space. 1155 * 1156 * Return a MemTxResult indicating whether the operation succeeded 1157 * or failed (eg unassigned memory, device rejected the transaction, 1158 * IOMMU fault). 1159 * 1160 * @as: #AddressSpace to be accessed 1161 * @addr: address within that address space 1162 * @attrs: memory transaction attributes 1163 * @buf: buffer with the data transferred 1164 */ 1165 MemTxResult address_space_read(AddressSpace *as, hwaddr addr, MemTxAttrs attrs, 1166 uint8_t *buf, int len); 1167 1168 /** 1169 * address_space_ld*: load from an address space 1170 * address_space_st*: store to an address space 1171 * 1172 * These functions perform a load or store of the byte, word, 1173 * longword or quad to the specified address within the AddressSpace. 1174 * The _le suffixed functions treat the data as little endian; 1175 * _be indicates big endian; no suffix indicates "same endianness 1176 * as guest CPU". 1177 * 1178 * The "guest CPU endianness" accessors are deprecated for use outside 1179 * target-* code; devices should be CPU-agnostic and use either the LE 1180 * or the BE accessors. 1181 * 1182 * @as #AddressSpace to be accessed 1183 * @addr: address within that address space 1184 * @val: data value, for stores 1185 * @attrs: memory transaction attributes 1186 * @result: location to write the success/failure of the transaction; 1187 * if NULL, this information is discarded 1188 */ 1189 uint32_t address_space_ldub(AddressSpace *as, hwaddr addr, 1190 MemTxAttrs attrs, MemTxResult *result); 1191 uint32_t address_space_lduw_le(AddressSpace *as, hwaddr addr, 1192 MemTxAttrs attrs, MemTxResult *result); 1193 uint32_t address_space_lduw_be(AddressSpace *as, hwaddr addr, 1194 MemTxAttrs attrs, MemTxResult *result); 1195 uint32_t address_space_ldl_le(AddressSpace *as, hwaddr addr, 1196 MemTxAttrs attrs, MemTxResult *result); 1197 uint32_t address_space_ldl_be(AddressSpace *as, hwaddr addr, 1198 MemTxAttrs attrs, MemTxResult *result); 1199 uint64_t address_space_ldq_le(AddressSpace *as, hwaddr addr, 1200 MemTxAttrs attrs, MemTxResult *result); 1201 uint64_t address_space_ldq_be(AddressSpace *as, hwaddr addr, 1202 MemTxAttrs attrs, MemTxResult *result); 1203 void address_space_stb(AddressSpace *as, hwaddr addr, uint32_t val, 1204 MemTxAttrs attrs, MemTxResult *result); 1205 void address_space_stw_le(AddressSpace *as, hwaddr addr, uint32_t val, 1206 MemTxAttrs attrs, MemTxResult *result); 1207 void address_space_stw_be(AddressSpace *as, hwaddr addr, uint32_t val, 1208 MemTxAttrs attrs, MemTxResult *result); 1209 void address_space_stl_le(AddressSpace *as, hwaddr addr, uint32_t val, 1210 MemTxAttrs attrs, MemTxResult *result); 1211 void address_space_stl_be(AddressSpace *as, hwaddr addr, uint32_t val, 1212 MemTxAttrs attrs, MemTxResult *result); 1213 void address_space_stq_le(AddressSpace *as, hwaddr addr, uint64_t val, 1214 MemTxAttrs attrs, MemTxResult *result); 1215 void address_space_stq_be(AddressSpace *as, hwaddr addr, uint64_t val, 1216 MemTxAttrs attrs, MemTxResult *result); 1217 1218 #ifdef NEED_CPU_H 1219 uint32_t address_space_lduw(AddressSpace *as, hwaddr addr, 1220 MemTxAttrs attrs, MemTxResult *result); 1221 uint32_t address_space_ldl(AddressSpace *as, hwaddr addr, 1222 MemTxAttrs attrs, MemTxResult *result); 1223 uint64_t address_space_ldq(AddressSpace *as, hwaddr addr, 1224 MemTxAttrs attrs, MemTxResult *result); 1225 void address_space_stl_notdirty(AddressSpace *as, hwaddr addr, uint32_t val, 1226 MemTxAttrs attrs, MemTxResult *result); 1227 void address_space_stw(AddressSpace *as, hwaddr addr, uint32_t val, 1228 MemTxAttrs attrs, MemTxResult *result); 1229 void address_space_stl(AddressSpace *as, hwaddr addr, uint32_t val, 1230 MemTxAttrs attrs, MemTxResult *result); 1231 void address_space_stq(AddressSpace *as, hwaddr addr, uint64_t val, 1232 MemTxAttrs attrs, MemTxResult *result); 1233 #endif 1234 1235 /* address_space_translate: translate an address range into an address space 1236 * into a MemoryRegion and an address range into that section. Should be 1237 * called from an RCU critical section, to avoid that the last reference 1238 * to the returned region disappears after address_space_translate returns. 1239 * 1240 * @as: #AddressSpace to be accessed 1241 * @addr: address within that address space 1242 * @xlat: pointer to address within the returned memory region section's 1243 * #MemoryRegion. 1244 * @len: pointer to length 1245 * @is_write: indicates the transfer direction 1246 */ 1247 MemoryRegion *address_space_translate(AddressSpace *as, hwaddr addr, 1248 hwaddr *xlat, hwaddr *len, 1249 bool is_write); 1250 1251 /* address_space_access_valid: check for validity of accessing an address 1252 * space range 1253 * 1254 * Check whether memory is assigned to the given address space range, and 1255 * access is permitted by any IOMMU regions that are active for the address 1256 * space. 1257 * 1258 * For now, addr and len should be aligned to a page size. This limitation 1259 * will be lifted in the future. 1260 * 1261 * @as: #AddressSpace to be accessed 1262 * @addr: address within that address space 1263 * @len: length of the area to be checked 1264 * @is_write: indicates the transfer direction 1265 */ 1266 bool address_space_access_valid(AddressSpace *as, hwaddr addr, int len, bool is_write); 1267 1268 /* address_space_map: map a physical memory region into a host virtual address 1269 * 1270 * May map a subset of the requested range, given by and returned in @plen. 1271 * May return %NULL if resources needed to perform the mapping are exhausted. 1272 * Use only for reads OR writes - not for read-modify-write operations. 1273 * Use cpu_register_map_client() to know when retrying the map operation is 1274 * likely to succeed. 1275 * 1276 * @as: #AddressSpace to be accessed 1277 * @addr: address within that address space 1278 * @plen: pointer to length of buffer; updated on return 1279 * @is_write: indicates the transfer direction 1280 */ 1281 void *address_space_map(AddressSpace *as, hwaddr addr, 1282 hwaddr *plen, bool is_write); 1283 1284 /* address_space_unmap: Unmaps a memory region previously mapped by address_space_map() 1285 * 1286 * Will also mark the memory as dirty if @is_write == %true. @access_len gives 1287 * the amount of memory that was actually read or written by the caller. 1288 * 1289 * @as: #AddressSpace used 1290 * @addr: address within that address space 1291 * @len: buffer length as returned by address_space_map() 1292 * @access_len: amount of data actually transferred 1293 * @is_write: indicates the transfer direction 1294 */ 1295 void address_space_unmap(AddressSpace *as, void *buffer, hwaddr len, 1296 int is_write, hwaddr access_len); 1297 1298 1299 #endif 1300 1301 #endif 1302