simpletrace: fix process() argument count
[qemu.git] / memory.h
blob06b83ae76b3ec050f20d6a02b7b262750b42c66e
1 /*
2 * Physical memory management API
4 * Copyright 2011 Red Hat, Inc. and/or its affiliates
6 * Authors:
7 * Avi Kivity <avi@redhat.com>
9 * This work is licensed under the terms of the GNU GPL, version 2. See
10 * the COPYING file in the top-level directory.
14 #ifndef MEMORY_H
15 #define MEMORY_H
17 #ifndef CONFIG_USER_ONLY
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"
28 typedef struct MemoryRegionOps MemoryRegionOps;
29 typedef struct MemoryRegion MemoryRegion;
30 typedef struct MemoryRegionPortio MemoryRegionPortio;
31 typedef struct MemoryRegionMmio MemoryRegionMmio;
33 /* Must match *_DIRTY_FLAGS in cpu-all.h. To be replaced with dynamic
34 * registration.
36 #define DIRTY_MEMORY_VGA 0
37 #define DIRTY_MEMORY_CODE 1
38 #define DIRTY_MEMORY_MIGRATION 3
40 struct MemoryRegionMmio {
41 CPUReadMemoryFunc *read[3];
42 CPUWriteMemoryFunc *write[3];
46 * Memory region callbacks
48 struct MemoryRegionOps {
49 /* Read from the memory region. @addr is relative to @mr; @size is
50 * in bytes. */
51 uint64_t (*read)(void *opaque,
52 target_phys_addr_t addr,
53 unsigned size);
54 /* Write to the memory region. @addr is relative to @mr; @size is
55 * in bytes. */
56 void (*write)(void *opaque,
57 target_phys_addr_t addr,
58 uint64_t data,
59 unsigned size);
61 enum device_endian endianness;
62 /* Guest-visible constraints: */
63 struct {
64 /* If nonzero, specify bounds on access sizes beyond which a machine
65 * check is thrown.
67 unsigned min_access_size;
68 unsigned max_access_size;
69 /* If true, unaligned accesses are supported. Otherwise unaligned
70 * accesses throw machine checks.
72 bool unaligned;
73 } valid;
74 /* Internal implementation constraints: */
75 struct {
76 /* If nonzero, specifies the minimum size implemented. Smaller sizes
77 * will be rounded upwards and a partial result will be returned.
79 unsigned min_access_size;
80 /* If nonzero, specifies the maximum size implemented. Larger sizes
81 * will be done as a series of accesses with smaller sizes.
83 unsigned max_access_size;
84 /* If true, unaligned accesses are supported. Otherwise all accesses
85 * are converted to (possibly multiple) naturally aligned accesses.
87 bool unaligned;
88 } impl;
90 /* If .read and .write are not present, old_portio may be used for
91 * backwards compatibility with old portio registration
93 const MemoryRegionPortio *old_portio;
94 /* If .read and .write are not present, old_mmio may be used for
95 * backwards compatibility with old mmio registration
97 const MemoryRegionMmio old_mmio;
100 typedef struct CoalescedMemoryRange CoalescedMemoryRange;
101 typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd;
103 struct MemoryRegion {
104 /* All fields are private - violators will be prosecuted */
105 const MemoryRegionOps *ops;
106 void *opaque;
107 MemoryRegion *parent;
108 uint64_t size;
109 target_phys_addr_t addr;
110 target_phys_addr_t offset;
111 bool backend_registered;
112 void (*destructor)(MemoryRegion *mr);
113 ram_addr_t ram_addr;
114 IORange iorange;
115 bool terminates;
116 bool readable;
117 MemoryRegion *alias;
118 target_phys_addr_t alias_offset;
119 unsigned priority;
120 bool may_overlap;
121 QTAILQ_HEAD(subregions, MemoryRegion) subregions;
122 QTAILQ_ENTRY(MemoryRegion) subregions_link;
123 QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
124 const char *name;
125 uint8_t dirty_log_mask;
126 unsigned ioeventfd_nb;
127 MemoryRegionIoeventfd *ioeventfds;
130 struct MemoryRegionPortio {
131 uint32_t offset;
132 uint32_t len;
133 unsigned size;
134 IOPortReadFunc *read;
135 IOPortWriteFunc *write;
138 #define PORTIO_END_OF_LIST() { }
141 * memory_region_init: Initialize a memory region
143 * The region typically acts as a container for other memory regions. Us
144 * memory_region_add_subregion() to add subregions.
146 * @mr: the #MemoryRegion to be initialized
147 * @name: used for debugging; not visible to the user or ABI
148 * @size: size of the region; any subregions beyond this size will be clipped
150 void memory_region_init(MemoryRegion *mr,
151 const char *name,
152 uint64_t size);
154 * memory_region_init_io: Initialize an I/O memory region.
156 * Accesses into the region will be cause the callbacks in @ops to be called.
157 * if @size is nonzero, subregions will be clipped to @size.
159 * @mr: the #MemoryRegion to be initialized.
160 * @ops: a structure containing read and write callbacks to be used when
161 * I/O is performed on the region.
162 * @opaque: passed to to the read and write callbacks of the @ops structure.
163 * @name: used for debugging; not visible to the user or ABI
164 * @size: size of the region.
166 void memory_region_init_io(MemoryRegion *mr,
167 const MemoryRegionOps *ops,
168 void *opaque,
169 const char *name,
170 uint64_t size);
173 * memory_region_init_ram: Initialize RAM memory region. Accesses into the
174 * region will be modify memory directly.
176 * @mr: the #MemoryRegion to be initialized.
177 * @dev: a device associated with the region; may be %NULL.
178 * @name: the name of the region; the pair (@dev, @name) must be globally
179 * unique. The name is part of the save/restore ABI and so cannot be
180 * changed.
181 * @size: size of the region.
183 void memory_region_init_ram(MemoryRegion *mr,
184 DeviceState *dev, /* FIXME: layering violation */
185 const char *name,
186 uint64_t size);
189 * memory_region_init_ram: Initialize RAM memory region from a user-provided.
190 * pointer. Accesses into the region will be modify
191 * memory directly.
193 * @mr: the #MemoryRegion to be initialized.
194 * @dev: a device associated with the region; may be %NULL.
195 * @name: the name of the region; the pair (@dev, @name) must be globally
196 * unique. The name is part of the save/restore ABI and so cannot be
197 * changed.
198 * @size: size of the region.
199 * @ptr: memory to be mapped; must contain at least @size bytes.
201 void memory_region_init_ram_ptr(MemoryRegion *mr,
202 DeviceState *dev, /* FIXME: layering violation */
203 const char *name,
204 uint64_t size,
205 void *ptr);
208 * memory_region_init_alias: Initialize a memory region that aliases all or a
209 * part of another memory region.
211 * @mr: the #MemoryRegion to be initialized.
212 * @name: used for debugging; not visible to the user or ABI
213 * @orig: the region to be referenced; @mr will be equivalent to
214 * @orig between @offset and @offset + @size - 1.
215 * @offset: start of the section in @orig to be referenced.
216 * @size: size of the region.
218 void memory_region_init_alias(MemoryRegion *mr,
219 const char *name,
220 MemoryRegion *orig,
221 target_phys_addr_t offset,
222 uint64_t size);
225 * memory_region_init_rom_device: Initialize a ROM memory region. Writes are
226 * handled via callbacks.
228 * @mr: the #MemoryRegion to be initialized.
229 * @ops: callbacks for write access handling.
230 * @dev: a device associated with the region; may be %NULL.
231 * @name: the name of the region; the pair (@dev, @name) must be globally
232 * unique. The name is part of the save/restore ABI and so cannot be
233 * changed.
234 * @size: size of the region.
236 void memory_region_init_rom_device(MemoryRegion *mr,
237 const MemoryRegionOps *ops,
238 void *opaque,
239 DeviceState *dev, /* FIXME: layering violation */
240 const char *name,
241 uint64_t size);
244 * memory_region_destroy: Destroy a memory region and relaim all resources.
246 * @mr: the region to be destroyed. May not currently be a subregion
247 * (see memory_region_add_subregion()) or referenced in an alias
248 * (see memory_region_init_alias()).
250 void memory_region_destroy(MemoryRegion *mr);
253 * memory_region_size: get a memory region's size.
255 * @mr: the memory region being queried.
257 uint64_t memory_region_size(MemoryRegion *mr);
260 * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
262 * Returns a host pointer to a RAM memory region (created with
263 * memory_region_init_ram() or memory_region_init_ram_ptr()). Use with
264 * care.
266 * @mr: the memory region being queried.
268 void *memory_region_get_ram_ptr(MemoryRegion *mr);
271 * memory_region_set_offset: Sets an offset to be added to MemoryRegionOps
272 * callbacks.
274 * This function is deprecated and should not be used in new code.
276 void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
279 * memory_region_set_log: Turn dirty logging on or off for a region.
281 * Turns dirty logging on or off for a specified client (display, migration).
282 * Only meaningful for RAM regions.
284 * @mr: the memory region being updated.
285 * @log: whether dirty logging is to be enabled or disabled.
286 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
287 * %DIRTY_MEMORY_VGA.
289 void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
292 * memory_region_get_dirty: Check whether a page is dirty for a specified
293 * client.
295 * Checks whether a page has been written to since the last
296 * call to memory_region_reset_dirty() with the same @client. Dirty logging
297 * must be enabled.
299 * @mr: the memory region being queried.
300 * @addr: the address (relative to the start of the region) being queried.
301 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
302 * %DIRTY_MEMORY_VGA.
304 bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
305 unsigned client);
308 * memory_region_set_dirty: Mark a page as dirty in a memory region.
310 * Marks a page as dirty, after it has been dirtied outside guest code.
312 * @mr: the memory region being queried.
313 * @addr: the address (relative to the start of the region) being dirtied.
315 void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
318 * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
319 * any external TLBs (e.g. kvm)
321 * Flushes dirty information from accelerators such as kvm and vhost-net
322 * and makes it available to users of the memory API.
324 * @mr: the region being flushed.
326 void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
329 * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
330 * client.
332 * Marks a range of pages as no longer dirty.
334 * @mr: the region being updated.
335 * @addr: the start of the subrange being cleaned.
336 * @size: the size of the subrange being cleaned.
337 * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
338 * %DIRTY_MEMORY_VGA.
340 void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
341 target_phys_addr_t size, unsigned client);
344 * memory_region_set_readonly: Turn a memory region read-only (or read-write)
346 * Allows a memory region to be marked as read-only (turning it into a ROM).
347 * only useful on RAM regions.
349 * @mr: the region being updated.
350 * @readonly: whether rhe region is to be ROM or RAM.
352 void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
355 * memory_region_rom_device_set_readable: enable/disable ROM readability
357 * Allows a ROM device (initialized with memory_region_init_rom_device() to
358 * to be marked as readable (default) or not readable. When it is readable,
359 * the device is mapped to guest memory. When not readable, reads are
360 * forwarded to the #MemoryRegion.read function.
362 * @mr: the memory region to be updated
363 * @readable: whether reads are satisified directly (%true) or via callbacks
364 * (%false)
366 void memory_region_rom_device_set_readable(MemoryRegion *mr, bool readable);
369 * memory_region_set_coalescing: Enable memory coalescing for the region.
371 * Enabled writes to a region to be queued for later processing. MMIO ->write
372 * callbacks may be delayed until a non-coalesced MMIO is issued.
373 * Only useful for IO regions. Roughly similar to write-combining hardware.
375 * @mr: the memory region to be write coalesced
377 void memory_region_set_coalescing(MemoryRegion *mr);
380 * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
381 * a region.
383 * Like memory_region_set_coalescing(), but works on a sub-range of a region.
384 * Multiple calls can be issued coalesced disjoint ranges.
386 * @mr: the memory region to be updated.
387 * @offset: the start of the range within the region to be coalesced.
388 * @size: the size of the subrange to be coalesced.
390 void memory_region_add_coalescing(MemoryRegion *mr,
391 target_phys_addr_t offset,
392 uint64_t size);
395 * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
397 * Disables any coalescing caused by memory_region_set_coalescing() or
398 * memory_region_add_coalescing(). Roughly equivalent to uncacheble memory
399 * hardware.
401 * @mr: the memory region to be updated.
403 void memory_region_clear_coalescing(MemoryRegion *mr);
406 * memory_region_add_eventfd: Request an eventfd to be triggered when a word
407 * is written to a location.
409 * Marks a word in an IO region (initialized with memory_region_init_io())
410 * as a trigger for an eventfd event. The I/O callback will not be called.
411 * The caller must be prepared to handle failure (hat is, take the required
412 * action if the callback _is_ called).
414 * @mr: the memory region being updated.
415 * @addr: the address within @mr that is to be monitored
416 * @size: the size of the access to trigger the eventfd
417 * @match_data: whether to match against @data, instead of just @addr
418 * @data: the data to match against the guest write
419 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
421 void memory_region_add_eventfd(MemoryRegion *mr,
422 target_phys_addr_t addr,
423 unsigned size,
424 bool match_data,
425 uint64_t data,
426 int fd);
429 * memory_region_del_eventfd: Cancel and eventfd.
431 * Cancels an eventfd trigger request by a previous memory_region_add_eventfd()
432 * call.
434 * @mr: the memory region being updated.
435 * @addr: the address within @mr that is to be monitored
436 * @size: the size of the access to trigger the eventfd
437 * @match_data: whether to match against @data, instead of just @addr
438 * @data: the data to match against the guest write
439 * @fd: the eventfd to be triggered when @addr, @size, and @data all match.
441 void memory_region_del_eventfd(MemoryRegion *mr,
442 target_phys_addr_t addr,
443 unsigned size,
444 bool match_data,
445 uint64_t data,
446 int fd);
448 * memory_region_add_subregion: Add a sub-region to a container.
450 * Adds a sub-region at @offset. The sub-region may not overlap with other
451 * subregions (except for those explicitly marked as overlapping). A region
452 * may only be added once as a subregion (unless removed with
453 * memory_region_del_subregion()); use memory_region_init_alias() if you
454 * want a region to be a subregion in multiple locations.
456 * @mr: the region to contain the new subregion; must be a container
457 * initialized with memory_region_init().
458 * @offset: the offset relative to @mr where @subregion is added.
459 * @subregion: the subregion to be added.
461 void memory_region_add_subregion(MemoryRegion *mr,
462 target_phys_addr_t offset,
463 MemoryRegion *subregion);
465 * memory_region_add_subregion: Add a sub-region to a container, with overlap.
467 * Adds a sub-region at @offset. The sub-region may overlap with other
468 * subregions. Conflicts are resolved by having a higher @priority hide a
469 * lower @priority. Subregions without priority are taken as @priority 0.
470 * A region may only be added once as a subregion (unless removed with
471 * memory_region_del_subregion()); use memory_region_init_alias() if you
472 * want a region to be a subregion in multiple locations.
474 * @mr: the region to contain the new subregion; must be a container
475 * initialized with memory_region_init().
476 * @offset: the offset relative to @mr where @subregion is added.
477 * @subregion: the subregion to be added.
478 * @priority: used for resolving overlaps; highest priority wins.
480 void memory_region_add_subregion_overlap(MemoryRegion *mr,
481 target_phys_addr_t offset,
482 MemoryRegion *subregion,
483 unsigned priority);
485 * memory_region_del_subregion: Remove a subregion.
487 * Removes a subregion from its container.
489 * @mr: the container to be updated.
490 * @subregion: the region being removed; must be a current subregion of @mr.
492 void memory_region_del_subregion(MemoryRegion *mr,
493 MemoryRegion *subregion);
495 /* Start a transaction; changes will be accumulated and made visible only
496 * when the transaction ends.
498 void memory_region_transaction_begin(void);
499 /* Commit a transaction and make changes visible to the guest.
501 void memory_region_transaction_commit(void);
503 #endif
505 #endif