VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use