gmm.h@ 21111

Last change on this file since 21111 was 20374, checked in by vboxsync, 16 years ago
*: s/RT_\(BEGIN\|END\)_DECLS/RT_C_DECLS_\1/g
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.
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	RT_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	*/
126	typedef 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	*/
145	typedef 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	*/
171	typedef 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	*/
192	typedef 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. */
198	typedef 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	*/
207	typedef 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;
252	AssertCompileSize(GMMPAGEDESC, 16);
253	/** Pointer to a page allocation. */
254	typedef 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
264	GMMR0DECL(int) GMMR0Init(void);
265	GMMR0DECL(void) GMMR0Term(void);
266	GMMR0DECL(void) GMMR0InitPerVMData(PGVM pGVM);
267	GMMR0DECL(void) GMMR0CleanupVM(PGVM pGVM);
268	GMMR0DECL(int) GMMR0InitialReservation(PVM pVM, VMCPUID idCpu, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages,
269	GMMOCPOLICY enmPolicy, GMMPRIORITY enmPriority);
270	GMMR0DECL(int) GMMR0UpdateReservation(PVM pVM, VMCPUID idCpu, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages);
271	GMMR0DECL(int) GMMR0AllocateHandyPages(PVM pVM, VMCPUID idCpu, uint32_t cPagesToUpdate, uint32_t cPagesToAlloc, PGMMPAGEDESC paPages);
272	GMMR0DECL(int) GMMR0AllocatePages(PVM pVM, VMCPUID idCpu, uint32_t cPages, PGMMPAGEDESC paPages, GMMACCOUNT enmAccount);
273	GMMR0DECL(int) GMMR0FreePages(PVM pVM, VMCPUID idCpu, uint32_t cPages, PGMMFREEPAGEDESC paPages, GMMACCOUNT enmAccount);
274	GMMR0DECL(int) GMMR0BalloonedPages(PVM pVM, VMCPUID idCpu, uint32_t cBalloonedPages, uint32_t cPagesToFree, PGMMFREEPAGEDESC paPages, bool fCompleted);
275	GMMR0DECL(int) GMMR0DeflatedBalloon(PVM pVM, VMCPUID idCpu, uint32_t cPages);
276	GMMR0DECL(int) GMMR0MapUnmapChunk(PVM pVM, VMCPUID idCpu, uint32_t idChunkMap, uint32_t idChunkUnmap, PRTR3PTR ppvR3);
277	GMMR0DECL(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	*/
285	typedef 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. */
296	typedef GMMINITIALRESERVATIONREQ *PGMMINITIALRESERVATIONREQ;
297
298	GMMR0DECL(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	*/
305	typedef 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. */
314	typedef GMMUPDATERESERVATIONREQ *PGMMUPDATERESERVATIONREQ;
315
316	GMMR0DECL(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	*/
323	typedef 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. */
335	typedef GMMALLOCATEPAGESREQ *PGMMALLOCATEPAGESREQ;
336
337	GMMR0DECL(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	*/
344	typedef 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. */
356	typedef GMMFREEPAGESREQ *PGMMFREEPAGESREQ;
357
358	GMMR0DECL(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	*/
365	typedef 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. */
379	typedef GMMBALLOONEDPAGESREQ *PGMMBALLOONEDPAGESREQ;
380
381	GMMR0DECL(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	*/
388	typedef 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. */
400	typedef GMMMAPUNMAPCHUNKREQ *PGMMMAPUNMAPCHUNKREQ;
401
402	GMMR0DECL(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	*/
410	GMMR3DECL(int) GMMR3InitialReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages,
411	GMMOCPOLICY enmPolicy, GMMPRIORITY enmPriority);
412	GMMR3DECL(int) GMMR3UpdateReservation(PVM pVM, uint64_t cBasePages, uint32_t cShadowPages, uint32_t cFixedPages);
413	GMMR3DECL(int) GMMR3AllocatePagesPrepare(PVM pVM, PGMMALLOCATEPAGESREQ *ppReq, uint32_t cPages, GMMACCOUNT enmAccount);
414	GMMR3DECL(int) GMMR3AllocatePagesPerform(PVM pVM, PGMMALLOCATEPAGESREQ pReq);
415	GMMR3DECL(void) GMMR3AllocatePagesCleanup(PGMMALLOCATEPAGESREQ pReq);
416	GMMR3DECL(int) GMMR3FreePagesPrepare(PVM pVM, PGMMFREEPAGESREQ *ppReq, uint32_t cPages, GMMACCOUNT enmAccount);
417	GMMR3DECL(void) GMMR3FreePagesRePrep(PVM pVM, PGMMFREEPAGESREQ pReq, uint32_t cPages, GMMACCOUNT enmAccount);
418	GMMR3DECL(int) GMMR3FreePagesPerform(PVM pVM, PGMMFREEPAGESREQ pReq, uint32_t cActualPages);
419	GMMR3DECL(void) GMMR3FreePagesCleanup(PGMMFREEPAGESREQ pReq);
420	GMMR3DECL(void) GMMR3FreeAllocatedPages(PVM pVM, GMMALLOCATEPAGESREQ const *pAllocReq);
421	GMMR3DECL(int) GMMR3DeflatedBalloon(PVM pVM, uint32_t cPages);
422	GMMR3DECL(int) GMMR3MapUnmapChunk(PVM pVM, uint32_t idChunkMap, uint32_t idChunkUnmap, PRTR3PTR ppvR3);
423	GMMR3DECL(int) GMMR3SeedChunk(PVM pVM, RTR3PTR pvR3);
424	/** @} */
425	#endif /* IN_RING3 */
426
427	/** @} */
428
429	RT_C_DECLS_END
430
431	#endif
432

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: