blob: 740c48e8e56767342ab3e47e05614c67e8495b02 [file] [log] [blame]
Avi Kivity093bc2c2011-07-26 14:26:01 +03001/*
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"
Avi Kivity658b2222011-07-26 14:26:08 +030025#include "iorange.h"
Avi Kivity627a0e92011-07-26 14:26:09 +030026#include "ioport.h"
Avi Kivity08dafab2011-10-16 13:19:17 +020027#include "int128.h"
Avi Kivity093bc2c2011-07-26 14:26:01 +030028
29typedef struct MemoryRegionOps MemoryRegionOps;
30typedef struct MemoryRegion MemoryRegion;
Avi Kivity627a0e92011-07-26 14:26:09 +030031typedef struct MemoryRegionPortio MemoryRegionPortio;
Avi Kivity74901c32011-07-26 14:26:10 +030032typedef struct MemoryRegionMmio MemoryRegionMmio;
Avi Kivity093bc2c2011-07-26 14:26:01 +030033
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
Avi Kivity74901c32011-07-26 14:26:10 +030041struct MemoryRegionMmio {
42 CPUReadMemoryFunc *read[3];
43 CPUWriteMemoryFunc *write[3];
44};
45
Avi Kivitya2d33522012-03-05 17:40:12 +020046/* Internal use; thunks between old-style IORange and MemoryRegions. */
47typedef struct MemoryRegionIORange MemoryRegionIORange;
48struct MemoryRegionIORange {
49 IORange iorange;
50 MemoryRegion *mr;
51 target_phys_addr_t offset;
52};
53
Avi Kivity093bc2c2011-07-26 14:26:01 +030054/*
55 * Memory region callbacks
56 */
57struct MemoryRegionOps {
58 /* Read from the memory region. @addr is relative to @mr; @size is
59 * in bytes. */
60 uint64_t (*read)(void *opaque,
61 target_phys_addr_t addr,
62 unsigned size);
63 /* Write to the memory region. @addr is relative to @mr; @size is
64 * in bytes. */
65 void (*write)(void *opaque,
66 target_phys_addr_t addr,
67 uint64_t data,
68 unsigned size);
69
70 enum device_endian endianness;
71 /* Guest-visible constraints: */
72 struct {
73 /* If nonzero, specify bounds on access sizes beyond which a machine
74 * check is thrown.
75 */
76 unsigned min_access_size;
77 unsigned max_access_size;
78 /* If true, unaligned accesses are supported. Otherwise unaligned
79 * accesses throw machine checks.
80 */
81 bool unaligned;
Avi Kivity897fa7c2011-11-13 13:05:27 +020082 /*
83 * If present, and returns #false, the transaction is not accepted
84 * by the device (and results in machine dependent behaviour such
85 * as a machine check exception).
86 */
87 bool (*accepts)(void *opaque, target_phys_addr_t addr,
88 unsigned size, bool is_write);
Avi Kivity093bc2c2011-07-26 14:26:01 +030089 } valid;
90 /* Internal implementation constraints: */
91 struct {
92 /* If nonzero, specifies the minimum size implemented. Smaller sizes
93 * will be rounded upwards and a partial result will be returned.
94 */
95 unsigned min_access_size;
96 /* If nonzero, specifies the maximum size implemented. Larger sizes
97 * will be done as a series of accesses with smaller sizes.
98 */
99 unsigned max_access_size;
100 /* If true, unaligned accesses are supported. Otherwise all accesses
101 * are converted to (possibly multiple) naturally aligned accesses.
102 */
103 bool unaligned;
104 } impl;
Avi Kivity627a0e92011-07-26 14:26:09 +0300105
106 /* If .read and .write are not present, old_portio may be used for
107 * backwards compatibility with old portio registration
108 */
109 const MemoryRegionPortio *old_portio;
Avi Kivity74901c32011-07-26 14:26:10 +0300110 /* If .read and .write are not present, old_mmio may be used for
111 * backwards compatibility with old mmio registration
112 */
113 const MemoryRegionMmio old_mmio;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300114};
115
116typedef struct CoalescedMemoryRange CoalescedMemoryRange;
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300117typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300118
119struct MemoryRegion {
120 /* All fields are private - violators will be prosecuted */
121 const MemoryRegionOps *ops;
122 void *opaque;
123 MemoryRegion *parent;
Avi Kivity08dafab2011-10-16 13:19:17 +0200124 Int128 size;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300125 target_phys_addr_t addr;
Avi Kivity545e92e2011-08-08 19:58:48 +0300126 void (*destructor)(MemoryRegion *mr);
Avi Kivity093bc2c2011-07-26 14:26:01 +0300127 ram_addr_t ram_addr;
Avi Kivityb3b00c72012-01-02 13:20:11 +0200128 bool subpage;
Avi Kivity14a3c102011-07-26 14:26:06 +0300129 bool terminates;
Avi Kivityd0a9b5b2011-08-08 19:58:49 +0300130 bool readable;
Avi Kivity8ea92522011-12-08 15:58:43 +0200131 bool ram;
Avi Kivityfb1cd6f2011-09-25 14:48:47 +0300132 bool readonly; /* For RAM regions */
Avi Kivity6bba19b2011-09-14 11:54:58 +0300133 bool enabled;
Avi Kivity75c578d2012-01-02 15:40:52 +0200134 bool rom_device;
Jan Kiszka1660e722011-10-23 16:01:19 +0200135 bool warning_printed; /* For reservations */
Avi Kivity093bc2c2011-07-26 14:26:01 +0300136 MemoryRegion *alias;
137 target_phys_addr_t alias_offset;
138 unsigned priority;
139 bool may_overlap;
140 QTAILQ_HEAD(subregions, MemoryRegion) subregions;
141 QTAILQ_ENTRY(MemoryRegion) subregions_link;
142 QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
143 const char *name;
Avi Kivity5a583342011-07-26 14:26:02 +0300144 uint8_t dirty_log_mask;
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300145 unsigned ioeventfd_nb;
146 MemoryRegionIoeventfd *ioeventfds;
Avi Kivity093bc2c2011-07-26 14:26:01 +0300147};
148
Avi Kivity627a0e92011-07-26 14:26:09 +0300149struct MemoryRegionPortio {
150 uint32_t offset;
151 uint32_t len;
152 unsigned size;
153 IOPortReadFunc *read;
154 IOPortWriteFunc *write;
155};
156
Avi Kivity2dd30222011-08-08 16:08:54 +0300157#define PORTIO_END_OF_LIST() { }
Avi Kivity627a0e92011-07-26 14:26:09 +0300158
Avi Kivitye2177952011-12-08 15:00:18 +0200159typedef struct MemoryRegionSection MemoryRegionSection;
160
161/**
162 * MemoryRegionSection: describes a fragment of a #MemoryRegion
163 *
164 * @mr: the region, or %NULL if empty
Avi Kivity7664e802011-12-11 14:47:25 +0200165 * @address_space: the address space the region is mapped in
Avi Kivitye2177952011-12-08 15:00:18 +0200166 * @offset_within_region: the beginning of the section, relative to @mr's start
167 * @size: the size of the section; will not exceed @mr's boundaries
168 * @offset_within_address_space: the address of the first byte of the section
169 * relative to the region's address space
Avi Kivity7a8499e2012-02-08 17:01:23 +0200170 * @readonly: writes to this section are ignored
Avi Kivitye2177952011-12-08 15:00:18 +0200171 */
172struct MemoryRegionSection {
173 MemoryRegion *mr;
Avi Kivity7664e802011-12-11 14:47:25 +0200174 MemoryRegion *address_space;
Avi Kivitye2177952011-12-08 15:00:18 +0200175 target_phys_addr_t offset_within_region;
176 uint64_t size;
177 target_phys_addr_t offset_within_address_space;
Avi Kivity7a8499e2012-02-08 17:01:23 +0200178 bool readonly;
Avi Kivitye2177952011-12-08 15:00:18 +0200179};
180
Avi Kivity7664e802011-12-11 14:47:25 +0200181typedef struct MemoryListener MemoryListener;
182
183/**
184 * MemoryListener: callbacks structure for updates to the physical memory map
185 *
186 * Allows a component to adjust to changes in the guest-visible memory map.
187 * Use with memory_listener_register() and memory_listener_unregister().
188 */
189struct MemoryListener {
Avi Kivity50c1e142012-02-08 21:36:02 +0200190 void (*begin)(MemoryListener *listener);
191 void (*commit)(MemoryListener *listener);
Avi Kivity7664e802011-12-11 14:47:25 +0200192 void (*region_add)(MemoryListener *listener, MemoryRegionSection *section);
193 void (*region_del)(MemoryListener *listener, MemoryRegionSection *section);
Avi Kivity50c1e142012-02-08 21:36:02 +0200194 void (*region_nop)(MemoryListener *listener, MemoryRegionSection *section);
Avi Kivity7664e802011-12-11 14:47:25 +0200195 void (*log_start)(MemoryListener *listener, MemoryRegionSection *section);
196 void (*log_stop)(MemoryListener *listener, MemoryRegionSection *section);
197 void (*log_sync)(MemoryListener *listener, MemoryRegionSection *section);
198 void (*log_global_start)(MemoryListener *listener);
199 void (*log_global_stop)(MemoryListener *listener);
Avi Kivity80a1ea32012-02-08 16:39:06 +0200200 void (*eventfd_add)(MemoryListener *listener, MemoryRegionSection *section,
201 bool match_data, uint64_t data, int fd);
202 void (*eventfd_del)(MemoryListener *listener, MemoryRegionSection *section,
203 bool match_data, uint64_t data, int fd);
Avi Kivity72e22d22012-02-08 15:05:50 +0200204 /* Lower = earlier (during add), later (during del) */
205 unsigned priority;
Avi Kivity7376e582012-02-08 21:05:17 +0200206 MemoryRegion *address_space_filter;
Avi Kivity72e22d22012-02-08 15:05:50 +0200207 QTAILQ_ENTRY(MemoryListener) link;
Avi Kivity7664e802011-12-11 14:47:25 +0200208};
209
Avi Kivity093bc2c2011-07-26 14:26:01 +0300210/**
211 * memory_region_init: Initialize a memory region
212 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300213 * The region typically acts as a container for other memory regions. Use
Avi Kivity093bc2c2011-07-26 14:26:01 +0300214 * memory_region_add_subregion() to add subregions.
215 *
216 * @mr: the #MemoryRegion to be initialized
217 * @name: used for debugging; not visible to the user or ABI
218 * @size: size of the region; any subregions beyond this size will be clipped
219 */
220void memory_region_init(MemoryRegion *mr,
221 const char *name,
222 uint64_t size);
223/**
224 * memory_region_init_io: Initialize an I/O memory region.
225 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300226 * Accesses into the region will cause the callbacks in @ops to be called.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300227 * if @size is nonzero, subregions will be clipped to @size.
228 *
229 * @mr: the #MemoryRegion to be initialized.
230 * @ops: a structure containing read and write callbacks to be used when
231 * I/O is performed on the region.
232 * @opaque: passed to to the read and write callbacks of the @ops structure.
233 * @name: used for debugging; not visible to the user or ABI
234 * @size: size of the region.
235 */
236void memory_region_init_io(MemoryRegion *mr,
237 const MemoryRegionOps *ops,
238 void *opaque,
239 const char *name,
240 uint64_t size);
241
242/**
243 * memory_region_init_ram: Initialize RAM memory region. Accesses into the
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300244 * region will modify memory directly.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300245 *
246 * @mr: the #MemoryRegion to be initialized.
Avi Kivityc5705a72011-12-20 15:59:12 +0200247 * @name: the name of the region.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300248 * @size: size of the region.
249 */
250void memory_region_init_ram(MemoryRegion *mr,
Avi Kivity093bc2c2011-07-26 14:26:01 +0300251 const char *name,
252 uint64_t size);
253
254/**
255 * memory_region_init_ram: Initialize RAM memory region from a user-provided.
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300256 * pointer. Accesses into the region will modify
Avi Kivity093bc2c2011-07-26 14:26:01 +0300257 * memory directly.
258 *
259 * @mr: the #MemoryRegion to be initialized.
Avi Kivityc5705a72011-12-20 15:59:12 +0200260 * @name: the name of the region.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300261 * @size: size of the region.
262 * @ptr: memory to be mapped; must contain at least @size bytes.
263 */
264void memory_region_init_ram_ptr(MemoryRegion *mr,
Avi Kivity093bc2c2011-07-26 14:26:01 +0300265 const char *name,
266 uint64_t size,
267 void *ptr);
268
269/**
270 * memory_region_init_alias: Initialize a memory region that aliases all or a
271 * part of another memory region.
272 *
273 * @mr: the #MemoryRegion to be initialized.
274 * @name: used for debugging; not visible to the user or ABI
275 * @orig: the region to be referenced; @mr will be equivalent to
276 * @orig between @offset and @offset + @size - 1.
277 * @offset: start of the section in @orig to be referenced.
278 * @size: size of the region.
279 */
280void memory_region_init_alias(MemoryRegion *mr,
281 const char *name,
282 MemoryRegion *orig,
283 target_phys_addr_t offset,
284 uint64_t size);
Avi Kivityd0a9b5b2011-08-08 19:58:49 +0300285
286/**
287 * memory_region_init_rom_device: Initialize a ROM memory region. Writes are
288 * handled via callbacks.
289 *
290 * @mr: the #MemoryRegion to be initialized.
291 * @ops: callbacks for write access handling.
Avi Kivityc5705a72011-12-20 15:59:12 +0200292 * @name: the name of the region.
Avi Kivityd0a9b5b2011-08-08 19:58:49 +0300293 * @size: size of the region.
294 */
295void memory_region_init_rom_device(MemoryRegion *mr,
296 const MemoryRegionOps *ops,
Avi Kivity75f59412011-08-26 00:35:15 +0300297 void *opaque,
Avi Kivityd0a9b5b2011-08-08 19:58:49 +0300298 const char *name,
299 uint64_t size);
300
Avi Kivity093bc2c2011-07-26 14:26:01 +0300301/**
Jan Kiszka1660e722011-10-23 16:01:19 +0200302 * memory_region_init_reservation: Initialize a memory region that reserves
303 * I/O space.
304 *
305 * A reservation region primariy serves debugging purposes. It claims I/O
306 * space that is not supposed to be handled by QEMU itself. Any access via
307 * the memory API will cause an abort().
308 *
309 * @mr: the #MemoryRegion to be initialized
310 * @name: used for debugging; not visible to the user or ABI
311 * @size: size of the region.
312 */
313void memory_region_init_reservation(MemoryRegion *mr,
314 const char *name,
315 uint64_t size);
316/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300317 * memory_region_destroy: Destroy a memory region and reclaim all resources.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300318 *
319 * @mr: the region to be destroyed. May not currently be a subregion
320 * (see memory_region_add_subregion()) or referenced in an alias
321 * (see memory_region_init_alias()).
322 */
323void memory_region_destroy(MemoryRegion *mr);
324
325/**
326 * memory_region_size: get a memory region's size.
327 *
328 * @mr: the memory region being queried.
329 */
330uint64_t memory_region_size(MemoryRegion *mr);
331
332/**
Avi Kivity8ea92522011-12-08 15:58:43 +0200333 * memory_region_is_ram: check whether a memory region is random access
334 *
335 * Returns %true is a memory region is random access.
336 *
337 * @mr: the memory region being queried
338 */
339bool memory_region_is_ram(MemoryRegion *mr);
340
341/**
Blue Swirlfd062572012-04-09 17:38:52 +0000342 * memory_region_is_romd: check whether a memory region is ROMD
343 *
344 * Returns %true is a memory region is ROMD and currently set to allow
345 * direct reads.
346 *
347 * @mr: the memory region being queried
348 */
349static inline bool memory_region_is_romd(MemoryRegion *mr)
350{
351 return mr->rom_device && mr->readable;
352}
353
354/**
Avi Kivity8991c792011-12-20 15:53:11 +0200355 * memory_region_name: get a memory region's name
356 *
357 * Returns the string that was used to initialize the memory region.
358 *
359 * @mr: the memory region being queried
360 */
361const char *memory_region_name(MemoryRegion *mr);
362
363/**
Avi Kivity55043ba2011-12-15 17:20:34 +0200364 * memory_region_is_logging: return whether a memory region is logging writes
365 *
366 * Returns %true if the memory region is logging writes
367 *
368 * @mr: the memory region being queried
369 */
370bool memory_region_is_logging(MemoryRegion *mr);
371
372/**
Avi Kivityce7923d2011-12-08 16:05:11 +0200373 * memory_region_is_rom: check whether a memory region is ROM
374 *
375 * Returns %true is a memory region is read-only memory.
376 *
377 * @mr: the memory region being queried
378 */
379bool memory_region_is_rom(MemoryRegion *mr);
380
381/**
Avi Kivity093bc2c2011-07-26 14:26:01 +0300382 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
383 *
384 * Returns a host pointer to a RAM memory region (created with
385 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
386 * care.
387 *
388 * @mr: the memory region being queried.
389 */
390void *memory_region_get_ram_ptr(MemoryRegion *mr);
391
392/**
Avi Kivity093bc2c2011-07-26 14:26:01 +0300393 * memory_region_set_log: Turn dirty logging on or off for a region.
394 *
395 * Turns dirty logging on or off for a specified client (display, migration).
396 * Only meaningful for RAM regions.
397 *
398 * @mr: the memory region being updated.
399 * @log: whether dirty logging is to be enabled or disabled.
400 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
401 * %DIRTY_MEMORY_VGA.
402 */
403void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
404
405/**
Blue Swirlcd7a45c2012-01-22 16:38:21 +0000406 * memory_region_get_dirty: Check whether a range of bytes is dirty
407 * for a specified client.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300408 *
Blue Swirlcd7a45c2012-01-22 16:38:21 +0000409 * Checks whether a range of bytes has been written to since the last
Avi Kivity093bc2c2011-07-26 14:26:01 +0300410 * call to memory_region_reset_dirty() with the same @client. Dirty logging
411 * must be enabled.
412 *
413 * @mr: the memory region being queried.
414 * @addr: the address (relative to the start of the region) being queried.
Blue Swirlcd7a45c2012-01-22 16:38:21 +0000415 * @size: the size of the range being queried.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300416 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
417 * %DIRTY_MEMORY_VGA.
418 */
419bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
Blue Swirlcd7a45c2012-01-22 16:38:21 +0000420 target_phys_addr_t size, unsigned client);
Avi Kivity093bc2c2011-07-26 14:26:01 +0300421
422/**
Blue Swirlfd4aa972011-10-16 16:04:59 +0000423 * memory_region_set_dirty: Mark a range of bytes as dirty in a memory region.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300424 *
Blue Swirlfd4aa972011-10-16 16:04:59 +0000425 * Marks a range of bytes as dirty, after it has been dirtied outside
426 * guest code.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300427 *
Blue Swirlfd4aa972011-10-16 16:04:59 +0000428 * @mr: the memory region being dirtied.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300429 * @addr: the address (relative to the start of the region) being dirtied.
Blue Swirlfd4aa972011-10-16 16:04:59 +0000430 * @size: size of the range being dirtied.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300431 */
Blue Swirlfd4aa972011-10-16 16:04:59 +0000432void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr,
433 target_phys_addr_t size);
Avi Kivity093bc2c2011-07-26 14:26:01 +0300434
435/**
436 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
437 * any external TLBs (e.g. kvm)
438 *
439 * Flushes dirty information from accelerators such as kvm and vhost-net
440 * and makes it available to users of the memory API.
441 *
442 * @mr: the region being flushed.
443 */
444void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
445
446/**
447 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
448 * client.
449 *
450 * Marks a range of pages as no longer dirty.
451 *
452 * @mr: the region being updated.
453 * @addr: the start of the subrange being cleaned.
454 * @size: the size of the subrange being cleaned.
455 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
456 * %DIRTY_MEMORY_VGA.
457 */
458void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
459 target_phys_addr_t size, unsigned client);
460
461/**
462 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
463 *
464 * Allows a memory region to be marked as read-only (turning it into a ROM).
465 * only useful on RAM regions.
466 *
467 * @mr: the region being updated.
468 * @readonly: whether rhe region is to be ROM or RAM.
469 */
470void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
471
472/**
Avi Kivityd0a9b5b2011-08-08 19:58:49 +0300473 * memory_region_rom_device_set_readable: enable/disable ROM readability
474 *
475 * Allows a ROM device (initialized with memory_region_init_rom_device() to
476 * to be marked as readable (default) or not readable. When it is readable,
477 * the device is mapped to guest memory. When not readable, reads are
478 * forwarded to the #MemoryRegion.read function.
479 *
480 * @mr: the memory region to be updated
481 * @readable: whether reads are satisified directly (%true) or via callbacks
482 * (%false)
483 */
484void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
485
486/**
Avi Kivity093bc2c2011-07-26 14:26:01 +0300487 * memory_region_set_coalescing: Enable memory coalescing for the region.
488 *
489 * Enabled writes to a region to be queued for later processing. MMIO ->write
490 * callbacks may be delayed until a non-coalesced MMIO is issued.
491 * Only useful for IO regions. Roughly similar to write-combining hardware.
492 *
493 * @mr: the memory region to be write coalesced
494 */
495void memory_region_set_coalescing(MemoryRegion *mr);
496
497/**
498 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
499 * a region.
500 *
501 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
502 * Multiple calls can be issued coalesced disjoint ranges.
503 *
504 * @mr: the memory region to be updated.
505 * @offset: the start of the range within the region to be coalesced.
506 * @size: the size of the subrange to be coalesced.
507 */
508void memory_region_add_coalescing(MemoryRegion *mr,
509 target_phys_addr_t offset,
510 uint64_t size);
511
512/**
513 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
514 *
515 * Disables any coalescing caused by memory_region_set_coalescing() or
516 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
517 * hardware.
518 *
519 * @mr: the memory region to be updated.
520 */
521void memory_region_clear_coalescing(MemoryRegion *mr);
522
523/**
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300524 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
525 * is written to a location.
526 *
527 * Marks a word in an IO region (initialized with memory_region_init_io())
528 * as a trigger for an eventfd event. The I/O callback will not be called.
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300529 * The caller must be prepared to handle failure (that is, take the required
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300530 * action if the callback _is_ called).
531 *
532 * @mr: the memory region being updated.
533 * @addr: the address within @mr that is to be monitored
534 * @size: the size of the access to trigger the eventfd
535 * @match_data: whether to match against @data, instead of just @addr
536 * @data: the data to match against the guest write
537 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
538 **/
539void memory_region_add_eventfd(MemoryRegion *mr,
540 target_phys_addr_t addr,
541 unsigned size,
542 bool match_data,
543 uint64_t data,
544 int fd);
545
546/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300547 * memory_region_del_eventfd: Cancel an eventfd.
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300548 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300549 * Cancels an eventfd trigger requested by a previous
550 * memory_region_add_eventfd() call.
Avi Kivity3e9d69e2011-07-26 14:26:11 +0300551 *
552 * @mr: the memory region being updated.
553 * @addr: the address within @mr that is to be monitored
554 * @size: the size of the access to trigger the eventfd
555 * @match_data: whether to match against @data, instead of just @addr
556 * @data: the data to match against the guest write
557 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
558 */
559void memory_region_del_eventfd(MemoryRegion *mr,
560 target_phys_addr_t addr,
561 unsigned size,
562 bool match_data,
563 uint64_t data,
564 int fd);
565/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300566 * memory_region_add_subregion: Add a subregion to a container.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300567 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300568 * Adds a subregion at @offset. The subregion may not overlap with other
Avi Kivity093bc2c2011-07-26 14:26:01 +0300569 * subregions (except for those explicitly marked as overlapping). A region
570 * may only be added once as a subregion (unless removed with
571 * memory_region_del_subregion()); use memory_region_init_alias() if you
572 * want a region to be a subregion in multiple locations.
573 *
574 * @mr: the region to contain the new subregion; must be a container
575 * initialized with memory_region_init().
576 * @offset: the offset relative to @mr where @subregion is added.
577 * @subregion: the subregion to be added.
578 */
579void memory_region_add_subregion(MemoryRegion *mr,
580 target_phys_addr_t offset,
581 MemoryRegion *subregion);
582/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300583 * memory_region_add_subregion: Add a subregion to a container, with overlap.
Avi Kivity093bc2c2011-07-26 14:26:01 +0300584 *
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300585 * Adds a subregion at @offset. The subregion may overlap with other
Avi Kivity093bc2c2011-07-26 14:26:01 +0300586 * subregions. Conflicts are resolved by having a higher @priority hide a
587 * lower @priority. Subregions without priority are taken as @priority 0.
588 * A region may only be added once as a subregion (unless removed with
589 * memory_region_del_subregion()); use memory_region_init_alias() if you
590 * want a region to be a subregion in multiple locations.
591 *
592 * @mr: the region to contain the new subregion; must be a container
593 * initialized with memory_region_init().
594 * @offset: the offset relative to @mr where @subregion is added.
595 * @subregion: the subregion to be added.
596 * @priority: used for resolving overlaps; highest priority wins.
597 */
598void memory_region_add_subregion_overlap(MemoryRegion *mr,
599 target_phys_addr_t offset,
600 MemoryRegion *subregion,
601 unsigned priority);
Avi Kivitye34911c2011-12-19 12:06:23 +0200602
603/**
604 * memory_region_get_ram_addr: Get the ram address associated with a memory
605 * region
606 *
Stefan Weildabdf392012-01-08 19:35:09 +0100607 * DO NOT USE THIS FUNCTION. This is a temporary workaround while the Xen
Avi Kivitye34911c2011-12-19 12:06:23 +0200608 * code is being reworked.
609 */
610ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr);
611
Avi Kivity093bc2c2011-07-26 14:26:01 +0300612/**
613 * memory_region_del_subregion: Remove a subregion.
614 *
615 * Removes a subregion from its container.
616 *
617 * @mr: the container to be updated.
618 * @subregion: the region being removed; must be a current subregion of @mr.
619 */
620void memory_region_del_subregion(MemoryRegion *mr,
621 MemoryRegion *subregion);
622
Avi Kivity6bba19b2011-09-14 11:54:58 +0300623/*
624 * memory_region_set_enabled: dynamically enable or disable a region
625 *
626 * Enables or disables a memory region. A disabled memory region
627 * ignores all accesses to itself and its subregions. It does not
628 * obscure sibling subregions with lower priority - it simply behaves as
629 * if it was removed from the hierarchy.
630 *
631 * Regions default to being enabled.
632 *
633 * @mr: the region to be updated
634 * @enabled: whether to enable or disable the region
635 */
636void memory_region_set_enabled(MemoryRegion *mr, bool enabled);
637
Avi Kivity2282e1a2011-09-14 12:10:12 +0300638/*
639 * memory_region_set_address: dynamically update the address of a region
640 *
641 * Dynamically updates the address of a region, relative to its parent.
642 * May be used on regions are currently part of a memory hierarchy.
643 *
644 * @mr: the region to be updated
645 * @addr: new address, relative to parent region
646 */
647void memory_region_set_address(MemoryRegion *mr, target_phys_addr_t addr);
648
Avi Kivity47033592011-12-04 19:16:50 +0200649/*
650 * memory_region_set_alias_offset: dynamically update a memory alias's offset
651 *
652 * Dynamically updates the offset into the target region that an alias points
653 * to, as if the fourth argument to memory_region_init_alias() has changed.
654 *
655 * @mr: the #MemoryRegion to be updated; should be an alias.
656 * @offset: the new offset into the target memory region
657 */
658void memory_region_set_alias_offset(MemoryRegion *mr,
659 target_phys_addr_t offset);
660
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300661/**
Avi Kivitye2177952011-12-08 15:00:18 +0200662 * memory_region_find: locate a MemoryRegion in an address space
663 *
664 * Locates the first #MemoryRegion within an address space given by
665 * @address_space that overlaps the range given by @addr and @size.
666 *
667 * Returns a #MemoryRegionSection that describes a contiguous overlap.
668 * It will have the following characteristics:
669 * .@offset_within_address_space >= @addr
670 * .@offset_within_address_space + .@size <= @addr + @size
671 * .@size = 0 iff no overlap was found
672 * .@mr is non-%NULL iff an overlap was found
673 *
674 * @address_space: a top-level (i.e. parentless) region that contains
675 * the region to be found
676 * @addr: start of the area within @address_space to be searched
677 * @size: size of the area to be searched
678 */
679MemoryRegionSection memory_region_find(MemoryRegion *address_space,
680 target_phys_addr_t addr, uint64_t size);
681
Blue Swirlfd062572012-04-09 17:38:52 +0000682/**
683 * memory_region_section_addr: get offset within MemoryRegionSection
684 *
685 * Returns offset within MemoryRegionSection
686 *
687 * @section: the memory region section being queried
688 * @addr: address in address space
689 */
690static inline target_phys_addr_t
691memory_region_section_addr(MemoryRegionSection *section,
692 target_phys_addr_t addr)
693{
694 addr -= section->offset_within_address_space;
695 addr += section->offset_within_region;
696 return addr;
697}
Avi Kivity86e775c2011-12-15 16:24:49 +0200698
699/**
700 * memory_global_sync_dirty_bitmap: synchronize the dirty log for all memory
701 *
702 * Synchronizes the dirty page log for an entire address space.
703 * @address_space: a top-level (i.e. parentless) region that contains the
704 * memory being synchronized
705 */
706void memory_global_sync_dirty_bitmap(MemoryRegion *address_space);
707
Avi Kivitye2177952011-12-08 15:00:18 +0200708/**
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300709 * memory_region_transaction_begin: Start a transaction.
710 *
711 * During a transaction, changes will be accumulated and made visible
Stefan Weildabdf392012-01-08 19:35:09 +0100712 * only when the transaction ends (is committed).
Avi Kivity4ef4db82011-07-26 14:26:13 +0300713 */
714void memory_region_transaction_begin(void);
Ademar de Souza Reis Jr69ddaf62011-12-05 16:54:14 -0300715
716/**
717 * memory_region_transaction_commit: Commit a transaction and make changes
718 * visible to the guest.
Avi Kivity4ef4db82011-07-26 14:26:13 +0300719 */
720void memory_region_transaction_commit(void);
721
Avi Kivity7664e802011-12-11 14:47:25 +0200722/**
723 * memory_listener_register: register callbacks to be called when memory
724 * sections are mapped or unmapped into an address
725 * space
726 *
727 * @listener: an object containing the callbacks to be called
Avi Kivity7376e582012-02-08 21:05:17 +0200728 * @filter: if non-%NULL, only regions in this address space will be observed
Avi Kivity7664e802011-12-11 14:47:25 +0200729 */
Avi Kivity7376e582012-02-08 21:05:17 +0200730void memory_listener_register(MemoryListener *listener, MemoryRegion *filter);
Avi Kivity7664e802011-12-11 14:47:25 +0200731
732/**
733 * memory_listener_unregister: undo the effect of memory_listener_register()
734 *
735 * @listener: an object containing the callbacks to be removed
736 */
737void memory_listener_unregister(MemoryListener *listener);
738
739/**
740 * memory_global_dirty_log_start: begin dirty logging for all regions
741 */
742void memory_global_dirty_log_start(void);
743
744/**
745 * memory_global_dirty_log_stop: begin dirty logging for all regions
746 */
747void memory_global_dirty_log_stop(void);
748
Blue Swirl314e2982011-09-11 20:22:05 +0000749void mtree_info(fprintf_function mon_printf, void *f);
750
Avi Kivity093bc2c2011-07-26 14:26:01 +0300751#endif
752
753#endif