VirtualBox

source: vbox/trunk/include/VBox/gmm.h@ 21217

Last change on this file since 21217 was 21217, checked in by vboxsync, 15 years ago

include/VBox/*.h: Mark which components the header files relate to.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 15.7 KB
Line 
1/** @file
2 * GMM - The Global Memory Manager. (VMM)
3 */
4
5/*
6 * Copyright (C) 2007 Sun Microsystems, Inc.
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_gmm_h
31#define ___VBox_gmm_h
32
33#include <VBox/types.h>
34#include <VBox/gvmm.h>
35#include <VBox/sup.h>
36
37RT_C_DECLS_BEGIN
38
39/** @defgroup grp_gmm GMM - The Global Memory Manager
40 * @{
41 */
42
43/** @def IN_GMM_R0
44 * Used to indicate whether we're inside the same link module as the ring 0
45 * part of the Global Memory Manager or not.
46 */
47#ifdef DOXYGEN_RUNNING
48# define IN_GMM_R0
49#endif
50/** @def GMMR0DECL
51 * Ring 0 GMM export or import declaration.
52 * @param type The return type of the function declaration.
53 */
54#ifdef IN_GMM_R0
55# define GMMR0DECL(type) DECLEXPORT(type) VBOXCALL
56#else
57# define GMMR0DECL(type) DECLIMPORT(type) VBOXCALL
58#endif
59
60/** @def IN_GMM_R3
61 * Used to indicate whether we're inside the same link module as the ring 3
62 * part of the Global Memory Manager or not.
63 */
64#ifdef DOXYGEN_RUNNING
65# define IN_GMM_R3
66#endif
67/** @def GMMR3DECL
68 * Ring 3 GMM export or import declaration.
69 * @param type The return type of the function declaration.
70 */
71#ifdef IN_GMM_R3
72# define GMMR3DECL(type) DECLEXPORT(type) VBOXCALL
73#else
74# define GMMR3DECL(type) DECLIMPORT(type) VBOXCALL
75#endif
76
77
78/** The chunk shift. (2^20 = 1 MB) */
79#define GMM_CHUNK_SHIFT 20
80/** The allocation chunk size. */
81#define GMM_CHUNK_SIZE (1U << GMM_CHUNK_SHIFT)
82/** The allocation chunk size in pages. */
83#define GMM_CHUNK_NUM_PAGES (1U << (GMM_CHUNK_SHIFT - PAGE_SHIFT))
84/** The shift factor for converting a page id into a chunk id. */
85#define GMM_CHUNKID_SHIFT (GMM_CHUNK_SHIFT - PAGE_SHIFT)
86/** The last valid Chunk ID value. */
87#define GMM_CHUNKID_LAST (GMM_PAGEID_LAST >> GMM_CHUNKID_SHIFT)
88/** The last valid Page ID value.
89 * The current limit is 2^28 - 1, or almost 1TB if you like.
90 * The constraints are currently dictated by PGMPAGE. */
91#define GMM_PAGEID_LAST (RT_BIT_32(28) - 1)
92/** Mask out the page index from the Page ID. */
93#define GMM_PAGEID_IDX_MASK ((1U << GMM_CHUNKID_SHIFT) - 1)
94/** The NIL Chunk ID value. */
95#define NIL_GMM_CHUNKID 0
96/** The NIL Page ID value. */
97#define NIL_GMM_PAGEID 0
98
99#if 0 /* wrong - these are guest page pfns and not page ids! */
100/** Special Page ID used by unassigned pages. */
101#define GMM_PAGEID_UNASSIGNED 0x0fffffffU
102/** Special Page ID used by unsharable pages.
103 * Like MMIO2, shadow and heap. This is for later, obviously. */
104#define GMM_PAGEID_UNSHARABLE 0x0ffffffeU
105/** The end of the valid Page IDs. This is the first special one. */
106#define GMM_PAGEID_END 0x0ffffff0U
107#endif
108
109
110/** @def GMM_GCPHYS_LAST
111 * The last of the valid guest physical address as it applies to GMM pages.
112 *
113 * This must reflect the constraints imposed by the RTGCPHYS type and
114 * the guest page frame number used internally in GMMPAGE.
115 *
116 * @note Note this corresponds to GMM_PAGE_PFN_LAST. */
117#if HC_ARCH_BITS == 64
118# define GMM_GCPHYS_LAST UINT64_C(0x00000fffffff0000) /* 2^44 (16TB) - 0x10000 */
119#else
120# define GMM_GCPHYS_LAST UINT64_C(0x0000000fffff0000) /* 2^36 (64GB) - 0x10000 */
121#endif
122
123/**
124 * Over-commitment policy.
125 */
126typedef enum GMMOCPOLICY
127{
128 /** The usual invalid 0 value. */
129 GMMOCPOLICY_INVALID = 0,
130 /** No over-commitment, fully backed.
131 * The GMM guarantees that it will be able to allocate all of the
132 * guest RAM for a VM with OC policy. */
133 GMMOCPOLICY_NO_OC,
134 /** to-be-determined. */
135 GMMOCPOLICY_TBD,
136 /** The end of the valid policy range. */
137 GMMOCPOLICY_END,
138 /** The usual 32-bit hack. */
139 GMMOCPOLICY_32BIT_HACK = 0x7fffffff
140} GMMOCPOLICY;
141
142/**
143 * VM / Memory priority.
144 */
145typedef enum GMMPRIORITY
146{
147 /** The usual invalid 0 value. */
148 GMMPRIORITY_INVALID = 0,
149 /** High.
150 * When ballooning, ask these VMs last.
151 * When running out of memory, try not to interrupt these VMs. */
152 GMMPRIORITY_HIGH,
153 /** Normal.
154 * When ballooning, don't wait to ask these.
155 * When running out of memory, pause, save and/or kill these VMs. */
156 GMMPRIORITY_NORMAL,
157 /** Low.
158 * When ballooning, maximize these first.
159 * When running out of memory, save or kill these VMs. */
160 GMMPRIORITY_LOW,
161 /** The end of the valid priority range. */
162 GMMPRIORITY_END,
163 /** The custom 32-bit type blowup. */
164 GMMPRIORITY_32BIT_HACK = 0x7fffffff
165} GMMPRIORITY;
166
167
168/**
169 * GMM Memory Accounts.
170 */
171typedef enum GMMACCOUNT
172{
173 /** The customary invalid zero entry. */
174 GMMACCOUNT_INVALID = 0,
175 /** Account with the base allocations. */
176 GMMACCOUNT_BASE,
177 /** Account with the shadow allocations. */
178 GMMACCOUNT_SHADOW,
179 /** Account with the fixed allocations. */
180 GMMACCOUNT_FIXED,
181 /** The end of the valid values. */
182 GMMACCOUNT_END,
183 /** The usual 32-bit value to finish it off. */
184 GMMACCOUNT_32BIT_HACK = 0x7fffffff
185} GMMACCOUNT;
186
187
188/**
189 * A page descriptor for use when freeing pages.
190 * See GMMR0FreePages, GMMR0BalloonedPages.
191 */
192typedef struct GMMFREEPAGEDESC
193{
194 /** The Page ID of the page to be freed. */
195 uint32_t idPage;
196} GMMFREEPAGEDESC;
197/** Pointer to a page descriptor for freeing pages. */
198typedef GMMFREEPAGEDESC *PGMMFREEPAGEDESC;
199
200
201/**
202 * A page descriptor for use when updating and allocating pages.
203 *
204 * This is a bit complicated because we want to do as much as possible
205 * with the same structure.
206 */
207typedef struct GMMPAGEDESC
208{
209 /** The physical address of the page.
210 *
211 * @input GMMR0AllocateHandyPages expects the guest physical address
212 * to update the GMMPAGE structure with. Pass GMM_GCPHYS_UNSHAREABLE
213 * when appropriate and NIL_RTHCPHYS when the page wasn't used
214 * for any specific guest address.
215 *
216 * GMMR0AllocatePage expects the guest physical address to put in
217 * the GMMPAGE structure for the page it allocates for this entry.
218 * Pass NIL_RTHCPHYS and GMM_GCPHYS_UNSHAREABLE as above.
219 *
220 * @output The host physical address of the allocated page.
221 * NIL_RTHCPHYS on allocation failure.
222 *
223 * ASSUMES: sizeof(RTHCPHYS) >= sizeof(RTGCPHYS).
224 */
225 RTHCPHYS HCPhysGCPhys;
226
227 /** The Page ID.
228 *
229 * @intput GMMR0AllocateHandyPages expects the Page ID of the page to
230 * update here. NIL_GMM_PAGEID means no page should be updated.
231 *
232 * GMMR0AllocatePages requires this to be initialized to
233 * NIL_GMM_PAGEID currently.
234 *
235 * @output The ID of the page, NIL_GMM_PAGEID if the allocation failed.
236 */
237 uint32_t idPage;
238
239 /** The Page ID of the shared page was replaced by this page.
240 *
241 * @input GMMR0AllocateHandyPages expects this to indicate a shared
242 * page that has been replaced by this page and should have its
243 * reference counter decremented and perhaps be freed up. Use
244 * NIL_GMM_PAGEID if no shared page was involved.
245 *
246 * All other APIs expects NIL_GMM_PAGEID here.
247 *
248 * @output All APIs sets this to NIL_GMM_PAGEID.
249 */
250 uint32_t idSharedPage;
251} GMMPAGEDESC;
252AssertCompileSize(GMMPAGEDESC, 16);
253/** Pointer to a page allocation. */
254typedef GMMPAGEDESC *PGMMPAGEDESC;
255
256/** GMMPAGEDESC::HCPhysGCPhys value that indicates that the page is unsharable.
257 * @note This corresponds to GMM_PAGE_PFN_UNSHAREABLE. */
258#if HC_ARCH_BITS == 64
259# define GMM_GCPHYS_UNSHAREABLE UINT64_C(0x00000fffffff1000)
260#else
261# define GMM_GCPHYS_UNSHAREABLE UINT64_C(0x0000000fffff1000)
262#endif
263
264GMMR0DECL(int) GMMR0Init(void);
265GMMR0DECL(void) GMMR0Term(void);
266GMMR0DECL(void) GMMR0InitPerVMData(PGVM pGVM);
267GMMR0DECL(void) GMMR0CleanupVM(PGVM pGVM);
268GMMR0DECL(int) GMMR0InitialReservation(PVM pVM, VMCPUID idCpu, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages,
269 GMMOCPOLICY enmPolicy, GMMPRIORITY enmPriority);
270GMMR0DECL(int) GMMR0UpdateReservation(PVM pVM, VMCPUID idCpu, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages);
271GMMR0DECL(int) GMMR0AllocateHandyPages(PVM pVM, VMCPUID idCpu, uint32_t cPagesToUpdate, uint32_t cPagesToAlloc, PGMMPAGEDESC paPages);
272GMMR0DECL(int) GMMR0AllocatePages(PVM pVM, VMCPUID idCpu, uint32_t cPages, PGMMPAGEDESC paPages, GMMACCOUNT enmAccount);
273GMMR0DECL(int) GMMR0FreePages(PVM pVM, VMCPUID idCpu, uint32_t cPages, PGMMFREEPAGEDESC paPages, GMMACCOUNT enmAccount);
274GMMR0DECL(int) GMMR0BalloonedPages(PVM pVM, VMCPUID idCpu, uint32_t cBalloonedPages, uint32_t cPagesToFree, PGMMFREEPAGEDESC paPages, bool fCompleted);
275GMMR0DECL(int) GMMR0DeflatedBalloon(PVM pVM, VMCPUID idCpu, uint32_t cPages);
276GMMR0DECL(int) GMMR0MapUnmapChunk(PVM pVM, VMCPUID idCpu, uint32_t idChunkMap, uint32_t idChunkUnmap, PRTR3PTR ppvR3);
277GMMR0DECL(int) GMMR0SeedChunk(PVM pVM, VMCPUID idCpu, RTR3PTR pvR3);
278
279
280
281/**
282 * Request buffer for GMMR0InitialReservationReq / VMMR0_DO_GMM_INITIAL_RESERVATION.
283 * @see GMMR0InitialReservation
284 */
285typedef struct GMMINITIALRESERVATIONREQ
286{
287 /** The header. */
288 SUPVMMR0REQHDR Hdr;
289 uint64_t cBasePages; /**< @see GMMR0InitialReservation */
290 uint32_t cShadowPages; /**< @see GMMR0InitialReservation */
291 uint32_t cFixedPages; /**< @see GMMR0InitialReservation */
292 GMMOCPOLICY enmPolicy; /**< @see GMMR0InitialReservation */
293 GMMPRIORITY enmPriority; /**< @see GMMR0InitialReservation */
294} GMMINITIALRESERVATIONREQ;
295/** Pointer to a GMMR0InitialReservationReq / VMMR0_DO_GMM_INITIAL_RESERVATION request buffer. */
296typedef GMMINITIALRESERVATIONREQ *PGMMINITIALRESERVATIONREQ;
297
298GMMR0DECL(int) GMMR0InitialReservationReq(PVM pVM, VMCPUID idCpu, PGMMINITIALRESERVATIONREQ pReq);
299
300
301/**
302 * Request buffer for GMMR0UpdateReservationReq / VMMR0_DO_GMM_UPDATE_RESERVATION.
303 * @see GMMR0UpdateReservation
304 */
305typedef struct GMMUPDATERESERVATIONREQ
306{
307 /** The header. */
308 SUPVMMR0REQHDR Hdr;
309 uint64_t cBasePages; /**< @see GMMR0UpdateReservation */
310 uint32_t cShadowPages; /**< @see GMMR0UpdateReservation */
311 uint32_t cFixedPages; /**< @see GMMR0UpdateReservation */
312} GMMUPDATERESERVATIONREQ;
313/** Pointer to a GMMR0InitialReservationReq / VMMR0_DO_GMM_INITIAL_RESERVATION request buffer. */
314typedef GMMUPDATERESERVATIONREQ *PGMMUPDATERESERVATIONREQ;
315
316GMMR0DECL(int) GMMR0UpdateReservationReq(PVM pVM, VMCPUID idCpu, PGMMUPDATERESERVATIONREQ pReq);
317
318
319/**
320 * Request buffer for GMMR0AllocatePagesReq / VMMR0_DO_GMM_ALLOCATE_PAGES.
321 * @see GMMR0AllocatePages.
322 */
323typedef struct GMMALLOCATEPAGESREQ
324{
325 /** The header. */
326 SUPVMMR0REQHDR Hdr;
327 /** The account to charge the allocation to. */
328 GMMACCOUNT enmAccount;
329 /** The number of pages to allocate. */
330 uint32_t cPages;
331 /** Array of page descriptors. */
332 GMMPAGEDESC aPages[1];
333} GMMALLOCATEPAGESREQ;
334/** Pointer to a GMMR0AllocatePagesReq / VMMR0_DO_GMM_ALLOCATE_PAGES request buffer. */
335typedef GMMALLOCATEPAGESREQ *PGMMALLOCATEPAGESREQ;
336
337GMMR0DECL(int) GMMR0AllocatePagesReq(PVM pVM, VMCPUID idCpu, PGMMALLOCATEPAGESREQ pReq);
338
339
340/**
341 * Request buffer for GMMR0FreePagesReq / VMMR0_DO_GMM_FREE_PAGES.
342 * @see GMMR0FreePages.
343 */
344typedef struct GMMFREEPAGESREQ
345{
346 /** The header. */
347 SUPVMMR0REQHDR Hdr;
348 /** The account this relates to. */
349 GMMACCOUNT enmAccount;
350 /** The number of pages to free. */
351 uint32_t cPages;
352 /** Array of free page descriptors. */
353 GMMFREEPAGEDESC aPages[1];
354} GMMFREEPAGESREQ;
355/** Pointer to a GMMR0FreePagesReq / VMMR0_DO_GMM_FREE_PAGES request buffer. */
356typedef GMMFREEPAGESREQ *PGMMFREEPAGESREQ;
357
358GMMR0DECL(int) GMMR0FreePagesReq(PVM pVM, VMCPUID idCpu, PGMMFREEPAGESREQ pReq);
359
360
361/**
362 * Request buffer for GMMR0BalloonedPagesReq / VMMR0_DO_GMM_BALLOONED_PAGES.
363 * @see GMMR0BalloonedPages.
364 */
365typedef struct GMMBALLOONEDPAGESREQ
366{
367 /** The header. */
368 SUPVMMR0REQHDR Hdr;
369 /** The number of ballooned pages. */
370 uint32_t cBalloonedPages;
371 /** The number of pages to free. */
372 uint32_t cPagesToFree;
373 /** Whether the ballooning request is completed or more pages are still to come. */
374 bool fCompleted;
375 /** Array of free page descriptors. */
376 GMMFREEPAGEDESC aPages[1];
377} GMMBALLOONEDPAGESREQ;
378/** Pointer to a GMMR0BalloonedPagesReq / VMMR0_DO_GMM_BALLOONED_PAGES request buffer. */
379typedef GMMBALLOONEDPAGESREQ *PGMMBALLOONEDPAGESREQ;
380
381GMMR0DECL(int) GMMR0BalloonedPagesReq(PVM pVM, VMCPUID idCpu, PGMMBALLOONEDPAGESREQ pReq);
382
383
384/**
385 * Request buffer for GMMR0MapUnmapChunkReq / VMMR0_DO_GMM_MAP_UNMAP_CHUNK.
386 * @see GMMR0MapUnmapChunk
387 */
388typedef struct GMMMAPUNMAPCHUNKREQ
389{
390 /** The header. */
391 SUPVMMR0REQHDR Hdr;
392 /** The chunk to map, NIL_GMM_CHUNKID if unmap only. (IN) */
393 uint32_t idChunkMap;
394 /** The chunk to unmap, NIL_GMM_CHUNKID if map only. (IN) */
395 uint32_t idChunkUnmap;
396 /** Where the mapping address is returned. (OUT) */
397 RTR3PTR pvR3;
398} GMMMAPUNMAPCHUNKREQ;
399/** Pointer to a GMMR0MapUnmapChunkReq / VMMR0_DO_GMM_MAP_UNMAP_CHUNK request buffer. */
400typedef GMMMAPUNMAPCHUNKREQ *PGMMMAPUNMAPCHUNKREQ;
401
402GMMR0DECL(int) GMMR0MapUnmapChunkReq(PVM pVM, VMCPUID idCpu, PGMMMAPUNMAPCHUNKREQ pReq);
403
404
405#ifdef IN_RING3
406/** @defgroup grp_gmm_r3 The Global Memory Manager Ring-3 API Wrappers
407 * @ingroup grp_gmm
408 * @{
409 */
410GMMR3DECL(int) GMMR3InitialReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages,
411 GMMOCPOLICY enmPolicy, GMMPRIORITY enmPriority);
412GMMR3DECL(int) GMMR3UpdateReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages);
413GMMR3DECL(int) GMMR3AllocatePagesPrepare(PVM pVM, PGMMALLOCATEPAGESREQ *ppReq, uint32_t cPages, GMMACCOUNT enmAccount);
414GMMR3DECL(int) GMMR3AllocatePagesPerform(PVM pVM, PGMMALLOCATEPAGESREQ pReq);
415GMMR3DECL(void) GMMR3AllocatePagesCleanup(PGMMALLOCATEPAGESREQ pReq);
416GMMR3DECL(int) GMMR3FreePagesPrepare(PVM pVM, PGMMFREEPAGESREQ *ppReq, uint32_t cPages, GMMACCOUNT enmAccount);
417GMMR3DECL(void) GMMR3FreePagesRePrep(PVM pVM, PGMMFREEPAGESREQ pReq, uint32_t cPages, GMMACCOUNT enmAccount);
418GMMR3DECL(int) GMMR3FreePagesPerform(PVM pVM, PGMMFREEPAGESREQ pReq, uint32_t cActualPages);
419GMMR3DECL(void) GMMR3FreePagesCleanup(PGMMFREEPAGESREQ pReq);
420GMMR3DECL(void) GMMR3FreeAllocatedPages(PVM pVM, GMMALLOCATEPAGESREQ const *pAllocReq);
421GMMR3DECL(int) GMMR3DeflatedBalloon(PVM pVM, uint32_t cPages);
422GMMR3DECL(int) GMMR3MapUnmapChunk(PVM pVM, uint32_t idChunkMap, uint32_t idChunkUnmap, PRTR3PTR ppvR3);
423GMMR3DECL(int) GMMR3SeedChunk(PVM pVM, RTR3PTR pvR3);
424/** @} */
425#endif /* IN_RING3 */
426
427/** @} */
428
429RT_C_DECLS_END
430
431#endif
432
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use