VirtualBox

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

Last change on this file since 8155 was 8155, checked in by vboxsync, 16 years ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use