vga: make Cirrus ISA device optional
[qemu.git] / memory.h
1 /*
2 * Physical memory management API
3 *
4 * Copyright 2011 Red Hat, Inc. and/or its affiliates
5 *
6 * Authors:
7 * Avi Kivity <avi@redhat.com>
8 *
9 * This work is licensed under the terms of the GNU GPL, version 2. See
10 * the COPYING file in the top-level directory.
11 *
12 */
13
14 #ifndef MEMORY_H
15 #define MEMORY_H
16
17 #ifndef CONFIG_USER_ONLY
18
19 #include <stdint.h>
20 #include <stdbool.h>
21 #include "qemu-common.h"
22 #include "cpu-common.h"
23 #include "targphys.h"
24 #include "qemu-queue.h"
25 #include "iorange.h"
26 #include "ioport.h"
27 #include "int128.h"
28
29 typedef struct MemoryRegionOps MemoryRegionOps;
30 typedef struct MemoryRegion MemoryRegion;
31 typedef struct MemoryRegionPortio MemoryRegionPortio;
32 typedef struct MemoryRegionMmio MemoryRegionMmio;
33
34 /* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
35 * registration.
36 */
37 #define DIRTY_MEMORY_VGA 0
38 #define DIRTY_MEMORY_CODE 1
39 #define DIRTY_MEMORY_MIGRATION 3
40
41 struct MemoryRegionMmio {
42 CPUReadMemoryFunc *read[3];
43 CPUWriteMemoryFunc *write[3];
44 };
45
46 /*
47 * Memory region callbacks
48 */
49 struct MemoryRegionOps {
50 /* Read from the memory region. @addr is relative to @mr; @size is
51 * in bytes. */
52 uint64_t (*read)(void *opaque,
53 target_phys_addr_t addr,
54 unsigned size);
55 /* Write to the memory region. @addr is relative to @mr; @size is
56 * in bytes. */
57 void (*write)(void *opaque,
58 target_phys_addr_t addr,
59 uint64_t data,
60 unsigned size);
61
62 enum device_endian endianness;
63 /* Guest-visible constraints: */
64 struct {
65 /* If nonzero, specify bounds on access sizes beyond which a machine
66 * check is thrown.
67 */
68 unsigned min_access_size;
69 unsigned max_access_size;
70 /* If true, unaligned accesses are supported. Otherwise unaligned
71 * accesses throw machine checks.
72 */
73 bool unaligned;
74 /*
75 * If present, and returns #false, the transaction is not accepted
76 * by the device (and results in machine dependent behaviour such
77 * as a machine check exception).
78 */
79 bool (*accepts)(void *opaque, target_phys_addr_t addr,
80 unsigned size, bool is_write);
81 } valid;
82 /* Internal implementation constraints: */
83 struct {
84 /* If nonzero, specifies the minimum size implemented. Smaller sizes
85 * will be rounded upwards and a partial result will be returned.
86 */
87 unsigned min_access_size;
88 /* If nonzero, specifies the maximum size implemented. Larger sizes
89 * will be done as a series of accesses with smaller sizes.
90 */
91 unsigned max_access_size;
92 /* If true, unaligned accesses are supported. Otherwise all accesses
93 * are converted to (possibly multiple) naturally aligned accesses.
94 */
95 bool unaligned;
96 } impl;
97
98 /* If .read and .write are not present, old_portio may be used for
99 * backwards compatibility with old portio registration
100 */
101 const MemoryRegionPortio *old_portio;
102 /* If .read and .write are not present, old_mmio may be used for
103 * backwards compatibility with old mmio registration
104 */
105 const MemoryRegionMmio old_mmio;
106 };
107
108 typedef struct CoalescedMemoryRange CoalescedMemoryRange;
109 typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
110
111 struct MemoryRegion {
112 /* All fields are private - violators will be prosecuted */
113 const MemoryRegionOps *ops;
114 void *opaque;
115 MemoryRegion *parent;
116 Int128 size;
117 target_phys_addr_t addr;
118 target_phys_addr_t offset;
119 void (*destructor)(MemoryRegion *mr);
120 ram_addr_t ram_addr;
121 IORange iorange;
122 bool subpage;
123 bool terminates;
124 bool readable;
125 bool ram;
126 bool readonly; /* For RAM regions */
127 bool enabled;
128 bool rom_device;
129 MemoryRegion *alias;
130 target_phys_addr_t alias_offset;
131 unsigned priority;
132 bool may_overlap;
133 QTAILQ_HEAD(subregions, MemoryRegion) subregions;
134 QTAILQ_ENTRY(MemoryRegion) subregions_link;
135 QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
136 const char *name;
137 uint8_t dirty_log_mask;
138 unsigned ioeventfd_nb;
139 MemoryRegionIoeventfd *ioeventfds;
140 };
141
142 struct MemoryRegionPortio {
143 uint32_t offset;
144 uint32_t len;
145 unsigned size;
146 IOPortReadFunc *read;
147 IOPortWriteFunc *write;
148 };
149
150 #define PORTIO_END_OF_LIST() { }
151
152 typedef struct MemoryRegionSection MemoryRegionSection;
153
154 /**
155 * MemoryRegionSection: describes a fragment of a #MemoryRegion
156 *
157 * @mr: the region, or %NULL if empty
158 * @address_space: the address space the region is mapped in
159 * @offset_within_region: the beginning of the section, relative to @mr's start
160 * @size: the size of the section; will not exceed @mr's boundaries
161 * @offset_within_address_space: the address of the first byte of the section
162 * relative to the region's address space
163 */
164 struct MemoryRegionSection {
165 MemoryRegion *mr;
166 MemoryRegion *address_space;
167 target_phys_addr_t offset_within_region;
168 uint64_t size;
169 target_phys_addr_t offset_within_address_space;
170 };
171
172 typedef struct MemoryListener MemoryListener;
173
174 /**
175 * MemoryListener: callbacks structure for updates to the physical memory map
176 *
177 * Allows a component to adjust to changes in the guest-visible memory map.
178 * Use with memory_listener_register() and memory_listener_unregister().
179 */
180 struct MemoryListener {
181 void (*region_add)(MemoryListener *listener, MemoryRegionSection *section);
182 void (*region_del)(MemoryListener *listener, MemoryRegionSection *section);
183 void (*log_start)(MemoryListener *listener, MemoryRegionSection *section);
184 void (*log_stop)(MemoryListener *listener, MemoryRegionSection *section);
185 void (*log_sync)(MemoryListener *listener, MemoryRegionSection *section);
186 void (*log_global_start)(MemoryListener *listener);
187 void (*log_global_stop)(MemoryListener *listener);
188 QLIST_ENTRY(MemoryListener) link;
189 };
190
191 /**
192 * memory_region_init: Initialize a memory region
193 *
194 * The region typically acts as a container for other memory regions. Use
195 * memory_region_add_subregion() to add subregions.
196 *
197 * @mr: the #MemoryRegion to be initialized
198 * @name: used for debugging; not visible to the user or ABI
199 * @size: size of the region; any subregions beyond this size will be clipped
200 */
201 void memory_region_init(MemoryRegion *mr,
202 const char *name,
203 uint64_t size);
204 /**
205 * memory_region_init_io: Initialize an I/O memory region.
206 *
207 * Accesses into the region will cause the callbacks in @ops to be called.
208 * if @size is nonzero, subregions will be clipped to @size.
209 *
210 * @mr: the #MemoryRegion to be initialized.
211 * @ops: a structure containing read and write callbacks to be used when
212 * I/O is performed on the region.
213 * @opaque: passed to to the read and write callbacks of the @ops structure.
214 * @name: used for debugging; not visible to the user or ABI
215 * @size: size of the region.
216 */
217 void memory_region_init_io(MemoryRegion *mr,
218 const MemoryRegionOps *ops,
219 void *opaque,
220 const char *name,
221 uint64_t size);
222
223 /**
224 * memory_region_init_ram: Initialize RAM memory region. Accesses into the
225 * region will modify memory directly.
226 *
227 * @mr: the #MemoryRegion to be initialized.
228 * @name: the name of the region.
229 * @size: size of the region.
230 */
231 void memory_region_init_ram(MemoryRegion *mr,
232 const char *name,
233 uint64_t size);
234
235 /**
236 * memory_region_init_ram: Initialize RAM memory region from a user-provided.
237 * pointer. Accesses into the region will modify
238 * memory directly.
239 *
240 * @mr: the #MemoryRegion to be initialized.
241 * @name: the name of the region.
242 * @size: size of the region.
243 * @ptr: memory to be mapped; must contain at least @size bytes.
244 */
245 void memory_region_init_ram_ptr(MemoryRegion *mr,
246 const char *name,
247 uint64_t size,
248 void *ptr);
249
250 /**
251 * memory_region_init_alias: Initialize a memory region that aliases all or a
252 * part of another memory region.
253 *
254 * @mr: the #MemoryRegion to be initialized.
255 * @name: used for debugging; not visible to the user or ABI
256 * @orig: the region to be referenced; @mr will be equivalent to
257 * @orig between @offset and @offset + @size - 1.
258 * @offset: start of the section in @orig to be referenced.
259 * @size: size of the region.
260 */
261 void memory_region_init_alias(MemoryRegion *mr,
262 const char *name,
263 MemoryRegion *orig,
264 target_phys_addr_t offset,
265 uint64_t size);
266
267 /**
268 * memory_region_init_rom_device: Initialize a ROM memory region. Writes are
269 * handled via callbacks.
270 *
271 * @mr: the #MemoryRegion to be initialized.
272 * @ops: callbacks for write access handling.
273 * @name: the name of the region.
274 * @size: size of the region.
275 */
276 void memory_region_init_rom_device(MemoryRegion *mr,
277 const MemoryRegionOps *ops,
278 void *opaque,
279 const char *name,
280 uint64_t size);
281
282 /**
283 * memory_region_destroy: Destroy a memory region and reclaim all resources.
284 *
285 * @mr: the region to be destroyed. May not currently be a subregion
286 * (see memory_region_add_subregion()) or referenced in an alias
287 * (see memory_region_init_alias()).
288 */
289 void memory_region_destroy(MemoryRegion *mr);
290
291 /**
292 * memory_region_size: get a memory region's size.
293 *
294 * @mr: the memory region being queried.
295 */
296 uint64_t memory_region_size(MemoryRegion *mr);
297
298 /**
299 * memory_region_is_ram: check whether a memory region is random access
300 *
301 * Returns %true is a memory region is random access.
302 *
303 * @mr: the memory region being queried
304 */
305 bool memory_region_is_ram(MemoryRegion *mr);
306
307 /**
308 * memory_region_name: get a memory region's name
309 *
310 * Returns the string that was used to initialize the memory region.
311 *
312 * @mr: the memory region being queried
313 */
314 const char *memory_region_name(MemoryRegion *mr);
315
316 /**
317 * memory_region_is_logging: return whether a memory region is logging writes
318 *
319 * Returns %true if the memory region is logging writes
320 *
321 * @mr: the memory region being queried
322 */
323 bool memory_region_is_logging(MemoryRegion *mr);
324
325 /**
326 * memory_region_is_rom: check whether a memory region is ROM
327 *
328 * Returns %true is a memory region is read-only memory.
329 *
330 * @mr: the memory region being queried
331 */
332 bool memory_region_is_rom(MemoryRegion *mr);
333
334 /**
335 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
336 *
337 * Returns a host pointer to a RAM memory region (created with
338 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
339 * care.
340 *
341 * @mr: the memory region being queried.
342 */
343 void *memory_region_get_ram_ptr(MemoryRegion *mr);
344
345 /**
346 * memory_region_set_offset: Sets an offset to be added to MemoryRegionOps
347 * callbacks.
348 *
349 * This function is deprecated and should not be used in new code.
350 */
351 void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
352
353 /**
354 * memory_region_set_log: Turn dirty logging on or off for a region.
355 *
356 * Turns dirty logging on or off for a specified client (display, migration).
357 * Only meaningful for RAM regions.
358 *
359 * @mr: the memory region being updated.
360 * @log: whether dirty logging is to be enabled or disabled.
361 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
362 * %DIRTY_MEMORY_VGA.
363 */
364 void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
365
366 /**
367 * memory_region_get_dirty: Check whether a page is dirty for a specified
368 * client.
369 *
370 * Checks whether a page has been written to since the last
371 * call to memory_region_reset_dirty() with the same @client. Dirty logging
372 * must be enabled.
373 *
374 * @mr: the memory region being queried.
375 * @addr: the address (relative to the start of the region) being queried.
376 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
377 * %DIRTY_MEMORY_VGA.
378 */
379 bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
380 unsigned client);
381
382 /**
383 * memory_region_set_dirty: Mark a page as dirty in a memory region.
384 *
385 * Marks a page as dirty, after it has been dirtied outside guest code.
386 *
387 * @mr: the memory region being queried.
388 * @addr: the address (relative to the start of the region) being dirtied.
389 */
390 void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
391
392 /**
393 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
394 * any external TLBs (e.g. kvm)
395 *
396 * Flushes dirty information from accelerators such as kvm and vhost-net
397 * and makes it available to users of the memory API.
398 *
399 * @mr: the region being flushed.
400 */
401 void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
402
403 /**
404 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
405 * client.
406 *
407 * Marks a range of pages as no longer dirty.
408 *
409 * @mr: the region being updated.
410 * @addr: the start of the subrange being cleaned.
411 * @size: the size of the subrange being cleaned.
412 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
413 * %DIRTY_MEMORY_VGA.
414 */
415 void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
416 target_phys_addr_t size, unsigned client);
417
418 /**
419 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
420 *
421 * Allows a memory region to be marked as read-only (turning it into a ROM).
422 * only useful on RAM regions.
423 *
424 * @mr: the region being updated.
425 * @readonly: whether rhe region is to be ROM or RAM.
426 */
427 void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
428
429 /**
430 * memory_region_rom_device_set_readable: enable/disable ROM readability
431 *
432 * Allows a ROM device (initialized with memory_region_init_rom_device() to
433 * to be marked as readable (default) or not readable. When it is readable,
434 * the device is mapped to guest memory. When not readable, reads are
435 * forwarded to the #MemoryRegion.read function.
436 *
437 * @mr: the memory region to be updated
438 * @readable: whether reads are satisified directly (%true) or via callbacks
439 * (%false)
440 */
441 void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
442
443 /**
444 * memory_region_set_coalescing: Enable memory coalescing for the region.
445 *
446 * Enabled writes to a region to be queued for later processing. MMIO ->write
447 * callbacks may be delayed until a non-coalesced MMIO is issued.
448 * Only useful for IO regions. Roughly similar to write-combining hardware.
449 *
450 * @mr: the memory region to be write coalesced
451 */
452 void memory_region_set_coalescing(MemoryRegion *mr);
453
454 /**
455 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
456 * a region.
457 *
458 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
459 * Multiple calls can be issued coalesced disjoint ranges.
460 *
461 * @mr: the memory region to be updated.
462 * @offset: the start of the range within the region to be coalesced.
463 * @size: the size of the subrange to be coalesced.
464 */
465 void memory_region_add_coalescing(MemoryRegion *mr,
466 target_phys_addr_t offset,
467 uint64_t size);
468
469 /**
470 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
471 *
472 * Disables any coalescing caused by memory_region_set_coalescing() or
473 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
474 * hardware.
475 *
476 * @mr: the memory region to be updated.
477 */
478 void memory_region_clear_coalescing(MemoryRegion *mr);
479
480 /**
481 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
482 * is written to a location.
483 *
484 * Marks a word in an IO region (initialized with memory_region_init_io())
485 * as a trigger for an eventfd event. The I/O callback will not be called.
486 * The caller must be prepared to handle failure (that is, take the required
487 * action if the callback _is_ called).
488 *
489 * @mr: the memory region being updated.
490 * @addr: the address within @mr that is to be monitored
491 * @size: the size of the access to trigger the eventfd
492 * @match_data: whether to match against @data, instead of just @addr
493 * @data: the data to match against the guest write
494 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
495 **/
496 void memory_region_add_eventfd(MemoryRegion *mr,
497 target_phys_addr_t addr,
498 unsigned size,
499 bool match_data,
500 uint64_t data,
501 int fd);
502
503 /**
504 * memory_region_del_eventfd: Cancel an eventfd.
505 *
506 * Cancels an eventfd trigger requested by a previous
507 * memory_region_add_eventfd() call.
508 *
509 * @mr: the memory region being updated.
510 * @addr: the address within @mr that is to be monitored
511 * @size: the size of the access to trigger the eventfd
512 * @match_data: whether to match against @data, instead of just @addr
513 * @data: the data to match against the guest write
514 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
515 */
516 void memory_region_del_eventfd(MemoryRegion *mr,
517 target_phys_addr_t addr,
518 unsigned size,
519 bool match_data,
520 uint64_t data,
521 int fd);
522 /**
523 * memory_region_add_subregion: Add a subregion to a container.
524 *
525 * Adds a subregion at @offset. The subregion may not overlap with other
526 * subregions (except for those explicitly marked as overlapping). A region
527 * may only be added once as a subregion (unless removed with
528 * memory_region_del_subregion()); use memory_region_init_alias() if you
529 * want a region to be a subregion in multiple locations.
530 *
531 * @mr: the region to contain the new subregion; must be a container
532 * initialized with memory_region_init().
533 * @offset: the offset relative to @mr where @subregion is added.
534 * @subregion: the subregion to be added.
535 */
536 void memory_region_add_subregion(MemoryRegion *mr,
537 target_phys_addr_t offset,
538 MemoryRegion *subregion);
539 /**
540 * memory_region_add_subregion: Add a subregion to a container, with overlap.
541 *
542 * Adds a subregion at @offset. The subregion may overlap with other
543 * subregions. Conflicts are resolved by having a higher @priority hide a
544 * lower @priority. Subregions without priority are taken as @priority 0.
545 * A region may only be added once as a subregion (unless removed with
546 * memory_region_del_subregion()); use memory_region_init_alias() if you
547 * want a region to be a subregion in multiple locations.
548 *
549 * @mr: the region to contain the new subregion; must be a container
550 * initialized with memory_region_init().
551 * @offset: the offset relative to @mr where @subregion is added.
552 * @subregion: the subregion to be added.
553 * @priority: used for resolving overlaps; highest priority wins.
554 */
555 void memory_region_add_subregion_overlap(MemoryRegion *mr,
556 target_phys_addr_t offset,
557 MemoryRegion *subregion,
558 unsigned priority);
559
560 /**
561 * memory_region_get_ram_addr: Get the ram address associated with a memory
562 * region
563 *
564 * DO NOT USE THIS FUNCTION. This is a temporary workaround while the Xen
565 * code is being reworked.
566 */
567 ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr);
568
569 /**
570 * memory_region_del_subregion: Remove a subregion.
571 *
572 * Removes a subregion from its container.
573 *
574 * @mr: the container to be updated.
575 * @subregion: the region being removed; must be a current subregion of @mr.
576 */
577 void memory_region_del_subregion(MemoryRegion *mr,
578 MemoryRegion *subregion);
579
580 /*
581 * memory_region_set_enabled: dynamically enable or disable a region
582 *
583 * Enables or disables a memory region. A disabled memory region
584 * ignores all accesses to itself and its subregions. It does not
585 * obscure sibling subregions with lower priority - it simply behaves as
586 * if it was removed from the hierarchy.
587 *
588 * Regions default to being enabled.
589 *
590 * @mr: the region to be updated
591 * @enabled: whether to enable or disable the region
592 */
593 void memory_region_set_enabled(MemoryRegion *mr, bool enabled);
594
595 /*
596 * memory_region_set_address: dynamically update the address of a region
597 *
598 * Dynamically updates the address of a region, relative to its parent.
599 * May be used on regions are currently part of a memory hierarchy.
600 *
601 * @mr: the region to be updated
602 * @addr: new address, relative to parent region
603 */
604 void memory_region_set_address(MemoryRegion *mr, target_phys_addr_t addr);
605
606 /*
607 * memory_region_set_alias_offset: dynamically update a memory alias's offset
608 *
609 * Dynamically updates the offset into the target region that an alias points
610 * to, as if the fourth argument to memory_region_init_alias() has changed.
611 *
612 * @mr: the #MemoryRegion to be updated; should be an alias.
613 * @offset: the new offset into the target memory region
614 */
615 void memory_region_set_alias_offset(MemoryRegion *mr,
616 target_phys_addr_t offset);
617
618 /**
619 * memory_region_find: locate a MemoryRegion in an address space
620 *
621 * Locates the first #MemoryRegion within an address space given by
622 * @address_space that overlaps the range given by @addr and @size.
623 *
624 * Returns a #MemoryRegionSection that describes a contiguous overlap.
625 * It will have the following characteristics:
626 * .@offset_within_address_space >= @addr
627 * .@offset_within_address_space + .@size <= @addr + @size
628 * .@size = 0 iff no overlap was found
629 * .@mr is non-%NULL iff an overlap was found
630 *
631 * @address_space: a top-level (i.e. parentless) region that contains
632 * the region to be found
633 * @addr: start of the area within @address_space to be searched
634 * @size: size of the area to be searched
635 */
636 MemoryRegionSection memory_region_find(MemoryRegion *address_space,
637 target_phys_addr_t addr, uint64_t size);
638
639
640 /**
641 * memory_global_sync_dirty_bitmap: synchronize the dirty log for all memory
642 *
643 * Synchronizes the dirty page log for an entire address space.
644 * @address_space: a top-level (i.e. parentless) region that contains the
645 * memory being synchronized
646 */
647 void memory_global_sync_dirty_bitmap(MemoryRegion *address_space);
648
649 /**
650 * memory_region_transaction_begin: Start a transaction.
651 *
652 * During a transaction, changes will be accumulated and made visible
653 * only when the transaction ends (is committed).
654 */
655 void memory_region_transaction_begin(void);
656
657 /**
658 * memory_region_transaction_commit: Commit a transaction and make changes
659 * visible to the guest.
660 */
661 void memory_region_transaction_commit(void);
662
663 /**
664 * memory_listener_register: register callbacks to be called when memory
665 * sections are mapped or unmapped into an address
666 * space
667 *
668 * @listener: an object containing the callbacks to be called
669 */
670 void memory_listener_register(MemoryListener *listener);
671
672 /**
673 * memory_listener_unregister: undo the effect of memory_listener_register()
674 *
675 * @listener: an object containing the callbacks to be removed
676 */
677 void memory_listener_unregister(MemoryListener *listener);
678
679 /**
680 * memory_global_dirty_log_start: begin dirty logging for all regions
681 */
682 void memory_global_dirty_log_start(void);
683
684 /**
685 * memory_global_dirty_log_stop: begin dirty logging for all regions
686 */
687 void memory_global_dirty_log_stop(void);
688
689 void mtree_info(fprintf_function mon_printf, void *f);
690
691 #endif
692
693 #endif