iPXE
memory.h
Go to the documentation of this file.
00001 /******************************************************************************
00002  * memory.h
00003  *
00004  * Memory reservation and information.
00005  *
00006  * Permission is hereby granted, free of charge, to any person obtaining a copy
00007  * of this software and associated documentation files (the "Software"), to
00008  * deal in the Software without restriction, including without limitation the
00009  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
00010  * sell copies of the Software, and to permit persons to whom the Software is
00011  * furnished to do so, subject to the following conditions:
00012  *
00013  * The above copyright notice and this permission notice shall be included in
00014  * all copies or substantial portions of the Software.
00015  *
00016  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00017  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00018  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00019  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00020  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00021  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00022  * DEALINGS IN THE SOFTWARE.
00023  *
00024  * Copyright (c) 2005, Keir Fraser <keir@xensource.com>
00025  */
00026 
00027 #ifndef __XEN_PUBLIC_MEMORY_H__
00028 #define __XEN_PUBLIC_MEMORY_H__
00029 
00030 FILE_LICENCE ( MIT );
00031 
00032 #include "xen.h"
00033 
00034 /*
00035  * Increase or decrease the specified domain's memory reservation. Returns the
00036  * number of extents successfully allocated or freed.
00037  * arg == addr of struct xen_memory_reservation.
00038  */
00039 #define XENMEM_increase_reservation 0
00040 #define XENMEM_decrease_reservation 1
00041 #define XENMEM_populate_physmap     6
00042 
00043 #if __XEN_INTERFACE_VERSION__ >= 0x00030209
00044 /*
00045  * Maximum # bits addressable by the user of the allocated region (e.g., I/O
00046  * devices often have a 32-bit limitation even in 64-bit systems). If zero
00047  * then the user has no addressing restriction. This field is not used by
00048  * XENMEM_decrease_reservation.
00049  */
00050 #define XENMEMF_address_bits(x)     (x)
00051 #define XENMEMF_get_address_bits(x) ((x) & 0xffu)
00052 /* NUMA node to allocate from. */
00053 #define XENMEMF_node(x)     (((x) + 1) << 8)
00054 #define XENMEMF_get_node(x) ((((x) >> 8) - 1) & 0xffu)
00055 /* Flag to populate physmap with populate-on-demand entries */
00056 #define XENMEMF_populate_on_demand (1<<16)
00057 /* Flag to request allocation only from the node specified */
00058 #define XENMEMF_exact_node_request  (1<<17)
00059 #define XENMEMF_exact_node(n) (XENMEMF_node(n) | XENMEMF_exact_node_request)
00060 #endif
00061 
00062 struct xen_memory_reservation {
00063 
00064     /*
00065      * XENMEM_increase_reservation:
00066      *   OUT: MFN (*not* GMFN) bases of extents that were allocated
00067      * XENMEM_decrease_reservation:
00068      *   IN:  GMFN bases of extents to free
00069      * XENMEM_populate_physmap:
00070      *   IN:  GPFN bases of extents to populate with memory
00071      *   OUT: GMFN bases of extents that were allocated
00072      *   (NB. This command also updates the mach_to_phys translation table)
00073      * XENMEM_claim_pages:
00074      *   IN: must be zero
00075      */
00076     XEN_GUEST_HANDLE(xen_pfn_t) extent_start;
00077 
00078     /* Number of extents, and size/alignment of each (2^extent_order pages). */
00079     xen_ulong_t    nr_extents;
00080     unsigned int   extent_order;
00081 
00082 #if __XEN_INTERFACE_VERSION__ >= 0x00030209
00083     /* XENMEMF flags. */
00084     unsigned int   mem_flags;
00085 #else
00086     unsigned int   address_bits;
00087 #endif
00088 
00089     /*
00090      * Domain whose reservation is being changed.
00091      * Unprivileged domains can specify only DOMID_SELF.
00092      */
00093     domid_t        domid;
00094 };
00095 typedef struct xen_memory_reservation xen_memory_reservation_t;
00096 DEFINE_XEN_GUEST_HANDLE(xen_memory_reservation_t);
00097 
00098 /*
00099  * An atomic exchange of memory pages. If return code is zero then
00100  * @out.extent_list provides GMFNs of the newly-allocated memory.
00101  * Returns zero on complete success, otherwise a negative error code.
00102  * On complete success then always @nr_exchanged == @in.nr_extents.
00103  * On partial success @nr_exchanged indicates how much work was done.
00104  */
00105 #define XENMEM_exchange             11
00106 struct xen_memory_exchange {
00107     /*
00108      * [IN] Details of memory extents to be exchanged (GMFN bases).
00109      * Note that @in.address_bits is ignored and unused.
00110      */
00111     struct xen_memory_reservation in;
00112 
00113     /*
00114      * [IN/OUT] Details of new memory extents.
00115      * We require that:
00116      *  1. @in.domid == @out.domid
00117      *  2. @in.nr_extents  << @in.extent_order ==
00118      *     @out.nr_extents << @out.extent_order
00119      *  3. @in.extent_start and @out.extent_start lists must not overlap
00120      *  4. @out.extent_start lists GPFN bases to be populated
00121      *  5. @out.extent_start is overwritten with allocated GMFN bases
00122      */
00123     struct xen_memory_reservation out;
00124 
00125     /*
00126      * [OUT] Number of input extents that were successfully exchanged:
00127      *  1. The first @nr_exchanged input extents were successfully
00128      *     deallocated.
00129      *  2. The corresponding first entries in the output extent list correctly
00130      *     indicate the GMFNs that were successfully exchanged.
00131      *  3. All other input and output extents are untouched.
00132      *  4. If not all input exents are exchanged then the return code of this
00133      *     command will be non-zero.
00134      *  5. THIS FIELD MUST BE INITIALISED TO ZERO BY THE CALLER!
00135      */
00136     xen_ulong_t nr_exchanged;
00137 };
00138 typedef struct xen_memory_exchange xen_memory_exchange_t;
00139 DEFINE_XEN_GUEST_HANDLE(xen_memory_exchange_t);
00140 
00141 /*
00142  * Returns the maximum machine frame number of mapped RAM in this system.
00143  * This command always succeeds (it never returns an error code).
00144  * arg == NULL.
00145  */
00146 #define XENMEM_maximum_ram_page     2
00147 
00148 /*
00149  * Returns the current or maximum memory reservation, in pages, of the
00150  * specified domain (may be DOMID_SELF). Returns -ve errcode on failure.
00151  * arg == addr of domid_t.
00152  */
00153 #define XENMEM_current_reservation  3
00154 #define XENMEM_maximum_reservation  4
00155 
00156 /*
00157  * Returns the maximum GPFN in use by the guest, or -ve errcode on failure.
00158  */
00159 #define XENMEM_maximum_gpfn         14
00160 
00161 /*
00162  * Returns a list of MFN bases of 2MB extents comprising the machine_to_phys
00163  * mapping table. Architectures which do not have a m2p table do not implement
00164  * this command.
00165  * arg == addr of xen_machphys_mfn_list_t.
00166  */
00167 #define XENMEM_machphys_mfn_list    5
00168 struct xen_machphys_mfn_list {
00169     /*
00170      * Size of the 'extent_start' array. Fewer entries will be filled if the
00171      * machphys table is smaller than max_extents * 2MB.
00172      */
00173     unsigned int max_extents;
00174 
00175     /*
00176      * Pointer to buffer to fill with list of extent starts. If there are
00177      * any large discontiguities in the machine address space, 2MB gaps in
00178      * the machphys table will be represented by an MFN base of zero.
00179      */
00180     XEN_GUEST_HANDLE(xen_pfn_t) extent_start;
00181 
00182     /*
00183      * Number of extents written to the above array. This will be smaller
00184      * than 'max_extents' if the machphys table is smaller than max_e * 2MB.
00185      */
00186     unsigned int nr_extents;
00187 };
00188 typedef struct xen_machphys_mfn_list xen_machphys_mfn_list_t;
00189 DEFINE_XEN_GUEST_HANDLE(xen_machphys_mfn_list_t);
00190 
00191 /*
00192  * For a compat caller, this is identical to XENMEM_machphys_mfn_list.
00193  *
00194  * For a non compat caller, this functions similarly to
00195  * XENMEM_machphys_mfn_list, but returns the mfns making up the compatibility
00196  * m2p table.
00197  */
00198 #define XENMEM_machphys_compat_mfn_list     25
00199 
00200 /*
00201  * Returns the location in virtual address space of the machine_to_phys
00202  * mapping table. Architectures which do not have a m2p table, or which do not
00203  * map it by default into guest address space, do not implement this command.
00204  * arg == addr of xen_machphys_mapping_t.
00205  */
00206 #define XENMEM_machphys_mapping     12
00207 struct xen_machphys_mapping {
00208     xen_ulong_t v_start, v_end; /* Start and end virtual addresses.   */
00209     xen_ulong_t max_mfn;        /* Maximum MFN that can be looked up. */
00210 };
00211 typedef struct xen_machphys_mapping xen_machphys_mapping_t;
00212 DEFINE_XEN_GUEST_HANDLE(xen_machphys_mapping_t);
00213 
00214 /* Source mapping space. */
00215 /* ` enum phys_map_space { */
00216 #define XENMAPSPACE_shared_info  0 /* shared info page */
00217 #define XENMAPSPACE_grant_table  1 /* grant table page */
00218 #define XENMAPSPACE_gmfn         2 /* GMFN */
00219 #define XENMAPSPACE_gmfn_range   3 /* GMFN range, XENMEM_add_to_physmap only. */
00220 #define XENMAPSPACE_gmfn_foreign 4 /* GMFN from another dom,
00221                                     * XENMEM_add_to_physmap_batch only. */
00222 /* ` } */
00223 
00224 /*
00225  * Sets the GPFN at which a particular page appears in the specified guest's
00226  * pseudophysical address space.
00227  * arg == addr of xen_add_to_physmap_t.
00228  */
00229 #define XENMEM_add_to_physmap      7
00230 struct xen_add_to_physmap {
00231     /* Which domain to change the mapping for. */
00232     domid_t domid;
00233 
00234     /* Number of pages to go through for gmfn_range */
00235     uint16_t    size;
00236 
00237     unsigned int space; /* => enum phys_map_space */
00238 
00239 #define XENMAPIDX_grant_table_status 0x80000000
00240 
00241     /* Index into space being mapped. */
00242     xen_ulong_t idx;
00243 
00244     /* GPFN in domid where the source mapping page should appear. */
00245     xen_pfn_t     gpfn;
00246 };
00247 typedef struct xen_add_to_physmap xen_add_to_physmap_t;
00248 DEFINE_XEN_GUEST_HANDLE(xen_add_to_physmap_t);
00249 
00250 /* A batched version of add_to_physmap. */
00251 #define XENMEM_add_to_physmap_batch 23
00252 struct xen_add_to_physmap_batch {
00253     /* IN */
00254     /* Which domain to change the mapping for. */
00255     domid_t domid;
00256     uint16_t space; /* => enum phys_map_space */
00257 
00258     /* Number of pages to go through */
00259     uint16_t size;
00260     domid_t foreign_domid; /* IFF gmfn_foreign */
00261 
00262     /* Indexes into space being mapped. */
00263     XEN_GUEST_HANDLE(xen_ulong_t) idxs;
00264 
00265     /* GPFN in domid where the source mapping page should appear. */
00266     XEN_GUEST_HANDLE(xen_pfn_t) gpfns;
00267 
00268     /* OUT */
00269 
00270     /* Per index error code. */
00271     XEN_GUEST_HANDLE(int) errs;
00272 };
00273 typedef struct xen_add_to_physmap_batch xen_add_to_physmap_batch_t;
00274 DEFINE_XEN_GUEST_HANDLE(xen_add_to_physmap_batch_t);
00275 
00276 #if __XEN_INTERFACE_VERSION__ < 0x00040400
00277 #define XENMEM_add_to_physmap_range XENMEM_add_to_physmap_batch
00278 #define xen_add_to_physmap_range xen_add_to_physmap_batch
00279 typedef struct xen_add_to_physmap_batch xen_add_to_physmap_range_t;
00280 DEFINE_XEN_GUEST_HANDLE(xen_add_to_physmap_range_t);
00281 #endif
00282 
00283 /*
00284  * Unmaps the page appearing at a particular GPFN from the specified guest's
00285  * pseudophysical address space.
00286  * arg == addr of xen_remove_from_physmap_t.
00287  */
00288 #define XENMEM_remove_from_physmap      15
00289 struct xen_remove_from_physmap {
00290     /* Which domain to change the mapping for. */
00291     domid_t domid;
00292 
00293     /* GPFN of the current mapping of the page. */
00294     xen_pfn_t     gpfn;
00295 };
00296 typedef struct xen_remove_from_physmap xen_remove_from_physmap_t;
00297 DEFINE_XEN_GUEST_HANDLE(xen_remove_from_physmap_t);
00298 
00299 /*** REMOVED ***/
00300 /*#define XENMEM_translate_gpfn_list  8*/
00301 
00302 /*
00303  * Returns the pseudo-physical memory map as it was when the domain
00304  * was started (specified by XENMEM_set_memory_map).
00305  * arg == addr of xen_memory_map_t.
00306  */
00307 #define XENMEM_memory_map           9
00308 struct xen_memory_map {
00309     /*
00310      * On call the number of entries which can be stored in buffer. On
00311      * return the number of entries which have been stored in
00312      * buffer.
00313      */
00314     unsigned int nr_entries;
00315 
00316     /*
00317      * Entries in the buffer are in the same format as returned by the
00318      * BIOS INT 0x15 EAX=0xE820 call.
00319      */
00320     XEN_GUEST_HANDLE(void) buffer;
00321 };
00322 typedef struct xen_memory_map xen_memory_map_t;
00323 DEFINE_XEN_GUEST_HANDLE(xen_memory_map_t);
00324 
00325 /*
00326  * Returns the real physical memory map. Passes the same structure as
00327  * XENMEM_memory_map.
00328  * arg == addr of xen_memory_map_t.
00329  */
00330 #define XENMEM_machine_memory_map   10
00331 
00332 /*
00333  * Set the pseudo-physical memory map of a domain, as returned by
00334  * XENMEM_memory_map.
00335  * arg == addr of xen_foreign_memory_map_t.
00336  */
00337 #define XENMEM_set_memory_map       13
00338 struct xen_foreign_memory_map {
00339     domid_t domid;
00340     struct xen_memory_map map;
00341 };
00342 typedef struct xen_foreign_memory_map xen_foreign_memory_map_t;
00343 DEFINE_XEN_GUEST_HANDLE(xen_foreign_memory_map_t);
00344 
00345 #define XENMEM_set_pod_target       16
00346 #define XENMEM_get_pod_target       17
00347 struct xen_pod_target {
00348     /* IN */
00349     uint64_t target_pages;
00350     /* OUT */
00351     uint64_t tot_pages;
00352     uint64_t pod_cache_pages;
00353     uint64_t pod_entries;
00354     /* IN */
00355     domid_t domid;
00356 };
00357 typedef struct xen_pod_target xen_pod_target_t;
00358 
00359 #if defined(__XEN__) || defined(__XEN_TOOLS__)
00360 
00361 #ifndef uint64_aligned_t
00362 #define uint64_aligned_t uint64_t
00363 #endif
00364 
00365 /*
00366  * Get the number of MFNs saved through memory sharing.
00367  * The call never fails.
00368  */
00369 #define XENMEM_get_sharing_freed_pages    18
00370 #define XENMEM_get_sharing_shared_pages   19
00371 
00372 #define XENMEM_paging_op                    20
00373 #define XENMEM_paging_op_nominate           0
00374 #define XENMEM_paging_op_evict              1
00375 #define XENMEM_paging_op_prep               2
00376 
00377 struct xen_mem_event_op {
00378     uint8_t     op;         /* XENMEM_*_op_* */
00379     domid_t     domain;
00380 
00381 
00382     /* PAGING_PREP IN: buffer to immediately fill page in */
00383     uint64_aligned_t    buffer;
00384     /* Other OPs */
00385     uint64_aligned_t    gfn;           /* IN:  gfn of page being operated on */
00386 };
00387 typedef struct xen_mem_event_op xen_mem_event_op_t;
00388 DEFINE_XEN_GUEST_HANDLE(xen_mem_event_op_t);
00389 
00390 #define XENMEM_access_op                    21
00391 #define XENMEM_access_op_resume             0
00392 #define XENMEM_access_op_set_access         1
00393 #define XENMEM_access_op_get_access         2
00394 
00395 typedef enum {
00396     XENMEM_access_n,
00397     XENMEM_access_r,
00398     XENMEM_access_w,
00399     XENMEM_access_rw,
00400     XENMEM_access_x,
00401     XENMEM_access_rx,
00402     XENMEM_access_wx,
00403     XENMEM_access_rwx,
00404     /*
00405      * Page starts off as r-x, but automatically
00406      * change to r-w on a write
00407      */
00408     XENMEM_access_rx2rw,
00409     /*
00410      * Log access: starts off as n, automatically
00411      * goes to rwx, generating an event without
00412      * pausing the vcpu
00413      */
00414     XENMEM_access_n2rwx,
00415     /* Take the domain default */
00416     XENMEM_access_default
00417 } xenmem_access_t;
00418 
00419 struct xen_mem_access_op {
00420     /* XENMEM_access_op_* */
00421     uint8_t op;
00422     /* xenmem_access_t */
00423     uint8_t access;
00424     domid_t domid;
00425     /*
00426      * Number of pages for set op
00427      * Ignored on setting default access and other ops
00428      */
00429     uint32_t nr;
00430     /*
00431      * First pfn for set op
00432      * pfn for get op
00433      * ~0ull is used to set and get the default access for pages
00434      */
00435     uint64_aligned_t pfn;
00436 };
00437 typedef struct xen_mem_access_op xen_mem_access_op_t;
00438 DEFINE_XEN_GUEST_HANDLE(xen_mem_access_op_t);
00439 
00440 #define XENMEM_sharing_op                   22
00441 #define XENMEM_sharing_op_nominate_gfn      0
00442 #define XENMEM_sharing_op_nominate_gref     1
00443 #define XENMEM_sharing_op_share             2
00444 #define XENMEM_sharing_op_resume            3
00445 #define XENMEM_sharing_op_debug_gfn         4
00446 #define XENMEM_sharing_op_debug_mfn         5
00447 #define XENMEM_sharing_op_debug_gref        6
00448 #define XENMEM_sharing_op_add_physmap       7
00449 #define XENMEM_sharing_op_audit             8
00450 
00451 #define XENMEM_SHARING_OP_S_HANDLE_INVALID  (-10)
00452 #define XENMEM_SHARING_OP_C_HANDLE_INVALID  (-9)
00453 
00454 /* The following allows sharing of grant refs. This is useful
00455  * for sharing utilities sitting as "filters" in IO backends
00456  * (e.g. memshr + blktap(2)). The IO backend is only exposed
00457  * to grant references, and this allows sharing of the grefs */
00458 #define XENMEM_SHARING_OP_FIELD_IS_GREF_FLAG   (1ULL << 62)
00459 
00460 #define XENMEM_SHARING_OP_FIELD_MAKE_GREF(field, val)  \
00461     (field) = (XENMEM_SHARING_OP_FIELD_IS_GREF_FLAG | val)
00462 #define XENMEM_SHARING_OP_FIELD_IS_GREF(field)         \
00463     ((field) & XENMEM_SHARING_OP_FIELD_IS_GREF_FLAG)
00464 #define XENMEM_SHARING_OP_FIELD_GET_GREF(field)        \
00465     ((field) & (~XENMEM_SHARING_OP_FIELD_IS_GREF_FLAG))
00466 
00467 struct xen_mem_sharing_op {
00468     uint8_t     op;     /* XENMEM_sharing_op_* */
00469     domid_t     domain;
00470 
00471     union {
00472         struct mem_sharing_op_nominate {  /* OP_NOMINATE_xxx           */
00473             union {
00474                 uint64_aligned_t gfn;     /* IN: gfn to nominate       */
00475                 uint32_t      grant_ref;  /* IN: grant ref to nominate */
00476             } u;
00477             uint64_aligned_t  handle;     /* OUT: the handle           */
00478         } nominate;
00479         struct mem_sharing_op_share {     /* OP_SHARE/ADD_PHYSMAP */
00480             uint64_aligned_t source_gfn;    /* IN: the gfn of the source page */
00481             uint64_aligned_t source_handle; /* IN: handle to the source page */
00482             uint64_aligned_t client_gfn;    /* IN: the client gfn */
00483             uint64_aligned_t client_handle; /* IN: handle to the client page */
00484             domid_t  client_domain; /* IN: the client domain id */
00485         } share;
00486         struct mem_sharing_op_debug {     /* OP_DEBUG_xxx */
00487             union {
00488                 uint64_aligned_t gfn;      /* IN: gfn to debug          */
00489                 uint64_aligned_t mfn;      /* IN: mfn to debug          */
00490                 uint32_t gref;     /* IN: gref to debug         */
00491             } u;
00492         } debug;
00493     } u;
00494 };
00495 typedef struct xen_mem_sharing_op xen_mem_sharing_op_t;
00496 DEFINE_XEN_GUEST_HANDLE(xen_mem_sharing_op_t);
00497 
00498 /*
00499  * Attempt to stake a claim for a domain on a quantity of pages
00500  * of system RAM, but _not_ assign specific pageframes.  Only
00501  * arithmetic is performed so the hypercall is very fast and need
00502  * not be preemptible, thus sidestepping time-of-check-time-of-use
00503  * races for memory allocation.  Returns 0 if the hypervisor page
00504  * allocator has atomically and successfully claimed the requested
00505  * number of pages, else non-zero.
00506  *
00507  * Any domain may have only one active claim.  When sufficient memory
00508  * has been allocated to resolve the claim, the claim silently expires.
00509  * Claiming zero pages effectively resets any outstanding claim and
00510  * is always successful.
00511  *
00512  * Note that a valid claim may be staked even after memory has been
00513  * allocated for a domain.  In this case, the claim is not incremental,
00514  * i.e. if the domain's tot_pages is 3, and a claim is staked for 10,
00515  * only 7 additional pages are claimed.
00516  *
00517  * Caller must be privileged or the hypercall fails.
00518  */
00519 #define XENMEM_claim_pages                  24
00520 
00521 /*
00522  * XENMEM_claim_pages flags - the are no flags at this time.
00523  * The zero value is appropiate.
00524  */
00525 
00526 #endif /* defined(__XEN__) || defined(__XEN_TOOLS__) */
00527 
00528 /* Next available subop number is 26 */
00529 
00530 #endif /* __XEN_PUBLIC_MEMORY_H__ */
00531 
00532 /*
00533  * Local variables:
00534  * mode: C
00535  * c-file-style: "BSD"
00536  * c-basic-offset: 4
00537  * tab-width: 4
00538  * indent-tabs-mode: nil
00539  * End:
00540  */