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 <[email protected]>
   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
  26 typedef struct MemoryRegionOps MemoryRegionOps;
  27 typedef struct MemoryRegion MemoryRegion;
  28
  29 /* Must match *_DIRTY_FLAGS in cpu-all.h.  To be replaced with dynamic
  30  * registration.
  31  */
  32 #define DIRTY_MEMORY_VGA       0
  33 #define DIRTY_MEMORY_CODE      1
  34 #define DIRTY_MEMORY_MIGRATION 3
  35
  36 /*
  37  * Memory region callbacks
  38  */
  39 struct MemoryRegionOps {
  40     /* Read from the memory region. @addr is relative to @mr; @size is
  41      * in bytes. */
  42     uint64_t (*read)(void *opaque,
  43                      target_phys_addr_t addr,
  44                      unsigned size);
  45     /* Write to the memory region. @addr is relative to @mr; @size is
  46      * in bytes. */
  47     void (*write)(void *opaque,
  48                   target_phys_addr_t addr,
  49                   uint64_t data,
  50                   unsigned size);
  51
  52     enum device_endian endianness;
  53     /* Guest-visible constraints: */
  54     struct {
  55         /* If nonzero, specify bounds on access sizes beyond which a machine
  56          * check is thrown.
  57          */
  58         unsigned min_access_size;
  59         unsigned max_access_size;
  60         /* If true, unaligned accesses are supported.  Otherwise unaligned
  61          * accesses throw machine checks.
  62          */
  63          bool unaligned;
  64     } valid;
  65     /* Internal implementation constraints: */
  66     struct {
  67         /* If nonzero, specifies the minimum size implemented.  Smaller sizes
  68          * will be rounded upwards and a partial result will be returned.
  69          */
  70         unsigned min_access_size;
  71         /* If nonzero, specifies the maximum size implemented.  Larger sizes
  72          * will be done as a series of accesses with smaller sizes.
  73          */
  74         unsigned max_access_size;
  75         /* If true, unaligned accesses are supported.  Otherwise all accesses
  76          * are converted to (possibly multiple) naturally aligned accesses.
  77          */
  78          bool unaligned;
  79     } impl;
  80 };
  81
  82 typedef struct CoalescedMemoryRange CoalescedMemoryRange;
  83
  84 struct MemoryRegion {
  85     /* All fields are private - violators will be prosecuted */
  86     const MemoryRegionOps *ops;
  87     void *opaque;
  88     MemoryRegion *parent;
  89     uint64_t size;
  90     target_phys_addr_t addr;
  91     target_phys_addr_t offset;
  92     ram_addr_t ram_addr;
  93     bool has_ram_addr;
  94     MemoryRegion *alias;
  95     target_phys_addr_t alias_offset;
  96     unsigned priority;
  97     bool may_overlap;
  98     QTAILQ_HEAD(subregions, MemoryRegion) subregions;
  99     QTAILQ_ENTRY(MemoryRegion) subregions_link;
 100     QTAILQ_HEAD(coalesced_ranges, CoalescedMemoryRange) coalesced;
 101     const char *name;
 102 };
 103
 104 /**
 105  * memory_region_init: Initialize a memory region
 106  *
 107  * The region typically acts as a container for other memory regions.  Us
 108  * memory_region_add_subregion() to add subregions.
 109  *
 110  * @mr: the #MemoryRegion to be initialized
 111  * @name: used for debugging; not visible to the user or ABI
 112  * @size: size of the region; any subregions beyond this size will be clipped
 113  */
 114 void memory_region_init(MemoryRegion *mr,
 115                         const char *name,
 116                         uint64_t size);
 117 /**
 118  * memory_region_init_io: Initialize an I/O memory region.
 119  *
 120  * Accesses into the region will be cause the callbacks in @ops to be called.
 121  * if @size is nonzero, subregions will be clipped to @size.
 122  *
 123  * @mr: the #MemoryRegion to be initialized.
 124  * @ops: a structure containing read and write callbacks to be used when
 125  *       I/O is performed on the region.
 126  * @opaque: passed to to the read and write callbacks of the @ops structure.
 127  * @name: used for debugging; not visible to the user or ABI
 128  * @size: size of the region.
 129  */
 130 void memory_region_init_io(MemoryRegion *mr,
 131                            const MemoryRegionOps *ops,
 132                            void *opaque,
 133                            const char *name,
 134                            uint64_t size);
 135
 136 /**
 137  * memory_region_init_ram:  Initialize RAM memory region.  Accesses into the
 138  *                          region will be modify memory directly.
 139  *
 140  * @mr: the #MemoryRegion to be initialized.
 141  * @dev: a device associated with the region; may be %NULL.
 142  * @name: the name of the region; the pair (@dev, @name) must be globally
 143  *        unique.  The name is part of the save/restore ABI and so cannot be
 144  *        changed.
 145  * @size: size of the region.
 146  */
 147 void memory_region_init_ram(MemoryRegion *mr,
 148                             DeviceState *dev, /* FIXME: layering violation */
 149                             const char *name,
 150                             uint64_t size);
 151
 152 /**
 153  * memory_region_init_ram:  Initialize RAM memory region from a user-provided.
 154  *                          pointer.  Accesses into the region will be modify
 155  *                          memory directly.
 156  *
 157  * @mr: the #MemoryRegion to be initialized.
 158  * @dev: a device associated with the region; may be %NULL.
 159  * @name: the name of the region; the pair (@dev, @name) must be globally
 160  *        unique.  The name is part of the save/restore ABI and so cannot be
 161  *        changed.
 162  * @size: size of the region.
 163  * @ptr: memory to be mapped; must contain at least @size bytes.
 164  */
 165 void memory_region_init_ram_ptr(MemoryRegion *mr,
 166                                 DeviceState *dev, /* FIXME: layering violation */
 167                                 const char *name,
 168                                 uint64_t size,
 169                                 void *ptr);
 170
 171 /**
 172  * memory_region_init_alias: Initialize a memory region that aliases all or a
 173  *                           part of another memory region.
 174  *
 175  * @mr: the #MemoryRegion to be initialized.
 176  * @name: used for debugging; not visible to the user or ABI
 177  * @orig: the region to be referenced; @mr will be equivalent to
 178  *        @orig between @offset and @offset + @size - 1.
 179  * @offset: start of the section in @orig to be referenced.
 180  * @size: size of the region.
 181  */
 182 void memory_region_init_alias(MemoryRegion *mr,
 183                               const char *name,
 184                               MemoryRegion *orig,
 185                               target_phys_addr_t offset,
 186                               uint64_t size);
 187 /**
 188  * memory_region_destroy: Destroy a memory region and relaim all resources.
 189  *
 190  * @mr: the region to be destroyed.  May not currently be a subregion
 191  *      (see memory_region_add_subregion()) or referenced in an alias
 192  *      (see memory_region_init_alias()).
 193  */
 194 void memory_region_destroy(MemoryRegion *mr);
 195
 196 /**
 197  * memory_region_size: get a memory region's size.
 198  *
 199  * @mr: the memory region being queried.
 200  */
 201 uint64_t memory_region_size(MemoryRegion *mr);
 202
 203 /**
 204  * memory_region_get_ram_ptr: Get a pointer into a RAM memory region.
 205  *
 206  * Returns a host pointer to a RAM memory region (created with
 207  * memory_region_init_ram() or memory_region_init_ram_ptr()).  Use with
 208  * care.
 209  *
 210  * @mr: the memory region being queried.
 211  */
 212 void *memory_region_get_ram_ptr(MemoryRegion *mr);
 213
 214 /**
 215  * memory_region_set_offset: Sets an offset to be added to MemoryRegionOps
 216  *                           callbacks.
 217  *
 218  * This function is deprecated and should not be used in new code.
 219  */
 220 void memory_region_set_offset(MemoryRegion *mr, target_phys_addr_t offset);
 221
 222 /**
 223  * memory_region_set_log: Turn dirty logging on or off for a region.
 224  *
 225  * Turns dirty logging on or off for a specified client (display, migration).
 226  * Only meaningful for RAM regions.
 227  *
 228  * @mr: the memory region being updated.
 229  * @log: whether dirty logging is to be enabled or disabled.
 230  * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
 231  *          %DIRTY_MEMORY_VGA.
 232  */
 233 void memory_region_set_log(MemoryRegion *mr, bool log, unsigned client);
 234
 235 /**
 236  * memory_region_get_dirty: Check whether a page is dirty for a specified
 237  *                          client.
 238  *
 239  * Checks whether a page has been written to since the last
 240  * call to memory_region_reset_dirty() with the same @client.  Dirty logging
 241  * must be enabled.
 242  *
 243  * @mr: the memory region being queried.
 244  * @addr: the address (relative to the start of the region) being queried.
 245  * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
 246  *          %DIRTY_MEMORY_VGA.
 247  */
 248 bool memory_region_get_dirty(MemoryRegion *mr, target_phys_addr_t addr,
 249                              unsigned client);
 250
 251 /**
 252  * memory_region_set_dirty: Mark a page as dirty in a memory region.
 253  *
 254  * Marks a page as dirty, after it has been dirtied outside guest code.
 255  *
 256  * @mr: the memory region being queried.
 257  * @addr: the address (relative to the start of the region) being dirtied.
 258  */
 259 void memory_region_set_dirty(MemoryRegion *mr, target_phys_addr_t addr);
 260
 261 /**
 262  * memory_region_sync_dirty_bitmap: Synchronize a region's dirty bitmap with
 263  *                                  any external TLBs (e.g. kvm)
 264  *
 265  * Flushes dirty information from accelerators such as kvm and vhost-net
 266  * and makes it available to users of the memory API.
 267  *
 268  * @mr: the region being flushed.
 269  */
 270 void memory_region_sync_dirty_bitmap(MemoryRegion *mr);
 271
 272 /**
 273  * memory_region_reset_dirty: Mark a range of pages as clean, for a specified
 274  *                            client.
 275  *
 276  * Marks a range of pages as no longer dirty.
 277  *
 278  * @mr: the region being updated.
 279  * @addr: the start of the subrange being cleaned.
 280  * @size: the size of the subrange being cleaned.
 281  * @client: the user of the logging information; %DIRTY_MEMORY_MIGRATION or
 282  *          %DIRTY_MEMORY_VGA.
 283  */
 284 void memory_region_reset_dirty(MemoryRegion *mr, target_phys_addr_t addr,
 285                                target_phys_addr_t size, unsigned client);
 286
 287 /**
 288  * memory_region_set_readonly: Turn a memory region read-only (or read-write)
 289  *
 290  * Allows a memory region to be marked as read-only (turning it into a ROM).
 291  * only useful on RAM regions.
 292  *
 293  * @mr: the region being updated.
 294  * @readonly: whether rhe region is to be ROM or RAM.
 295  */
 296 void memory_region_set_readonly(MemoryRegion *mr, bool readonly);
 297
 298 /**
 299  * memory_region_set_coalescing: Enable memory coalescing for the region.
 300  *
 301  * Enabled writes to a region to be queued for later processing. MMIO ->write
 302  * callbacks may be delayed until a non-coalesced MMIO is issued.
 303  * Only useful for IO regions.  Roughly similar to write-combining hardware.
 304  *
 305  * @mr: the memory region to be write coalesced
 306  */
 307 void memory_region_set_coalescing(MemoryRegion *mr);
 308
 309 /**
 310  * memory_region_add_coalescing: Enable memory coalescing for a sub-range of
 311  *                               a region.
 312  *
 313  * Like memory_region_set_coalescing(), but works on a sub-range of a region.
 314  * Multiple calls can be issued coalesced disjoint ranges.
 315  *
 316  * @mr: the memory region to be updated.
 317  * @offset: the start of the range within the region to be coalesced.
 318  * @size: the size of the subrange to be coalesced.
 319  */
 320 void memory_region_add_coalescing(MemoryRegion *mr,
 321                                   target_phys_addr_t offset,
 322                                   uint64_t size);
 323
 324 /**
 325  * memory_region_clear_coalescing: Disable MMIO coalescing for the region.
 326  *
 327  * Disables any coalescing caused by memory_region_set_coalescing() or
 328  * memory_region_add_coalescing().  Roughly equivalent to uncacheble memory
 329  * hardware.
 330  *
 331  * @mr: the memory region to be updated.
 332  */
 333 void memory_region_clear_coalescing(MemoryRegion *mr);
 334
 335 /**
 336  * memory_region_add_subregion: Add a sub-region to a container.
 337  *
 338  * Adds a sub-region at @offset.  The sub-region may not overlap with other
 339  * subregions (except for those explicitly marked as overlapping).  A region
 340  * may only be added once as a subregion (unless removed with
 341  * memory_region_del_subregion()); use memory_region_init_alias() if you
 342  * want a region to be a subregion in multiple locations.
 343  *
 344  * @mr: the region to contain the new subregion; must be a container
 345  *      initialized with memory_region_init().
 346  * @offset: the offset relative to @mr where @subregion is added.
 347  * @subregion: the subregion to be added.
 348  */
 349 void memory_region_add_subregion(MemoryRegion *mr,
 350                                  target_phys_addr_t offset,
 351                                  MemoryRegion *subregion);
 352 /**
 353  * memory_region_add_subregion: Add a sub-region to a container, with overlap.
 354  *
 355  * Adds a sub-region at @offset.  The sub-region may overlap with other
 356  * subregions.  Conflicts are resolved by having a higher @priority hide a
 357  * lower @priority. Subregions without priority are taken as @priority 0.
 358  * A region may only be added once as a subregion (unless removed with
 359  * memory_region_del_subregion()); use memory_region_init_alias() if you
 360  * want a region to be a subregion in multiple locations.
 361  *
 362  * @mr: the region to contain the new subregion; must be a container
 363  *      initialized with memory_region_init().
 364  * @offset: the offset relative to @mr where @subregion is added.
 365  * @subregion: the subregion to be added.
 366  * @priority: used for resolving overlaps; highest priority wins.
 367  */
 368 void memory_region_add_subregion_overlap(MemoryRegion *mr,
 369                                          target_phys_addr_t offset,
 370                                          MemoryRegion *subregion,
 371                                          unsigned priority);
 372 /**
 373  * memory_region_del_subregion: Remove a subregion.
 374  *
 375  * Removes a subregion from its container.
 376  *
 377  * @mr: the container to be updated.
 378  * @subregion: the region being removed; must be a current subregion of @mr.
 379  */
 380 void memory_region_del_subregion(MemoryRegion *mr,
 381                                  MemoryRegion *subregion);
 382
 383 #endif
 384
 385 #endif