gmm.h@ 6981

Last change on this file since 6981 was 6839, checked in by vboxsync, 17 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	*/
103	typedef 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	*/
122	typedef 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	*/
148	typedef 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	*/
169	typedef 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. */
175	typedef 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	*/
184	typedef 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;
229	AssertCompileSize(GMMPAGEDESC, 16);
230	/** Pointer to a page allocation. */
231	typedef GMMPAGEDESC *PGMMPAGEDESC;
232
233	/** GMMPAGEDESC::HCPhysGCPhys value that indicates that the page is shared. */
234	#define GMM_GCPHYS_UNSHAREABLE (RTHCPHYS)(0xfffffff0)
235
236	GMMR0DECL(int) GMMR0Init(void);
237	GMMR0DECL(void) GMMR0Term(void);
238	GMMR0DECL(void) GMMR0InitPerVMData(PGVM pGVM);
239	GMMR0DECL(void) GMMR0CleanupVM(PGVM pGVM);
240	GMMR0DECL(int) GMMR0InitialReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages,
241	GMMOCPOLICY enmPolicy, GMMPRIORITY enmPriority);
242	GMMR0DECL(int) GMMR0UpdateReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages);
243	GMMR0DECL(int) GMMR0AllocateHandyPages(PVM pVM, uint32_t cPagesToUpdate, uint32_t cPagesToAlloc, PGMMPAGEDESC paPages);
244	GMMR0DECL(int) GMMR0AllocatePages(PVM pVM, uint32_t cPages, PGMMPAGEDESC paPages, GMMACCOUNT enmAccount);
245	GMMR0DECL(int) GMMR0FreePages(PVM pVM, uint32_t cPages, PGMMFREEPAGEDESC paPages, GMMACCOUNT enmAccount);
246	GMMR0DECL(int) GMMR0BalloonedPages(PVM pVM, uint32_t cBalloonedPages, uint32_t cPagesToFree, PGMMFREEPAGEDESC paPages, bool fCompleted);
247	GMMR0DECL(int) GMMR0DeflatedBalloon(PVM pVM, uint32_t cPages);
248	GMMR0DECL(int) GMMR0MapUnmapChunk(PVM pVM, uint32_t idChunkMap, uint32_t idChunkUnmap, PRTR3PTR ppvR3);
249	GMMR0DECL(int) GMMR0SeedChunk(PVM pVM, RTR3PTR pvR3);
250
251
252
253	/**
254	* Request buffer for GMMR0InitialReservationReq / VMMR0_DO_GMM_INITIAL_RESERVATION.
255	* @see GMMR0InitialReservation
256	*/
257	typedef 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. */
268	typedef GMMINITIALRESERVATIONREQ *PGMMINITIALRESERVATIONREQ;
269
270	GMMR0DECL(int) GMMR0InitialReservationReq(PVM pVM, PGMMINITIALRESERVATIONREQ pReq);
271
272
273	/**
274	* Request buffer for GMMR0UpdateReservationReq / VMMR0_DO_GMM_UPDATE_RESERVATION.
275	* @see GMMR0UpdateReservation
276	*/
277	typedef 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. */
286	typedef GMMUPDATERESERVATIONREQ *PGMMUPDATERESERVATIONREQ;
287
288	GMMR0DECL(int) GMMR0UpdateReservationReq(PVM pVM, PGMMUPDATERESERVATIONREQ pReq);
289
290
291	/**
292	* Request buffer for GMMR0AllocatePagesReq / VMMR0_DO_GMM_ALLOCATE_PAGES.
293	* @see GMMR0AllocatePages.
294	*/
295	typedef 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. */
307	typedef GMMALLOCATEPAGESREQ *PGMMALLOCATEPAGESREQ;
308
309	GMMR0DECL(int) GMMR0AllocatePagesReq(PVM pVM, PGMMALLOCATEPAGESREQ pReq);
310
311
312	/**
313	* Request buffer for GMMR0FreePagesReq / VMMR0_DO_GMM_FREE_PAGES.
314	* @see GMMR0FreePages.
315	*/
316	typedef 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. */
328	typedef GMMFREEPAGESREQ *PGMMFREEPAGESREQ;
329
330	GMMR0DECL(int) GMMR0FreePagesReq(PVM pVM, PGMMFREEPAGESREQ pReq);
331
332
333	/**
334	* Request buffer for GMMR0BalloonedPagesReq / VMMR0_DO_GMM_BALLOONED_PAGES.
335	* @see GMMR0BalloonedPages.
336	*/
337	typedef 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. */
351	typedef GMMBALLOONEDPAGESREQ *PGMMBALLOONEDPAGESREQ;
352
353	GMMR0DECL(int) GMMR0BalloonedPagesReq(PVM pVM, PGMMBALLOONEDPAGESREQ pReq);
354
355
356	/**
357	* Request buffer for GMMR0MapUnmapChunkReq / VMMR0_DO_GMM_MAP_UNMAP_CHUNK.
358	* @see GMMR0MapUnmapChunk
359	*/
360	typedef 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. */
372	typedef GMMMAPUNMAPCHUNKREQ *PGMMMAPUNMAPCHUNKREQ;
373
374	GMMR0DECL(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	*/
382	GMMR3DECL(int) GMMR3InitialReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages,
383	GMMOCPOLICY enmPolicy, GMMPRIORITY enmPriority);
384	GMMR3DECL(int) GMMR3UpdateReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages);
385	GMMR3DECL(int) GMMR3AllocatePagesPrepare(PVM pVM, PGMMALLOCATEPAGESREQ *ppReq, uint32_t cPages, GMMACCOUNT enmAccount);
386	GMMR3DECL(int) GMMR3AllocatePagesPerform(PVM pVM, PGMMALLOCATEPAGESREQ pReq);
387	GMMR3DECL(void) GMMR3AllocatePagesCleanup(PGMMALLOCATEPAGESREQ pReq);
388	GMMR3DECL(int) GMMR3FreePagesPrepare(PVM pVM, PGMMFREEPAGESREQ *ppReq, uint32_t cPages, GMMACCOUNT enmAccount);
389	GMMR3DECL(int) GMMR3FreePagesPerform(PVM pVM, PGMMFREEPAGESREQ pReq);
390	GMMR3DECL(void) GMMR3FreePagesCleanup(PGMMFREEPAGESREQ pReq);
391	GMMR3DECL(void) GMMR3FreeAllocatedPages(PVM pVM, GMMALLOCATEPAGESREQ const *pAllocReq);
392	GMMR3DECL(int) GMMR3DeflatedBalloon(PVM pVM, uint32_t cPages);
393	GMMR3DECL(int) GMMR3MapUnmapChunk(PVM pVM, uint32_t idChunkMap, uint32_t idChunkUnmap, PRTR3PTR ppvR3);
394	GMMR3DECL(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.

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

Download in other formats: