memobj.h@ 28777

Last change on this file since 28777 was 28777, checked in by vboxsync, 15 years ago
iprt: added CachePolicy parameter to RTR0MemObjEnterPhys()
Property svn:eol-style set to `native` Property svn:keywords set to `Id Rev`
File size: 17.5 KB

Line
1	/* $Revision: 28777 $ */
2	/** @file
3	* IPRT - Ring-0 Memory Objects.
4	*/
5
6	/*
7	* Copyright (C) 2006-2007 Sun Microsystems, Inc.
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*
26	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
27	* Clara, CA 95054 USA or visit http://www.sun.com if you need
28	* additional information or have any questions.
29	*/
30
31	#ifndef ___internal_memobj_h
32	#define ___internal_memobj_h
33
34	#include <iprt/memobj.h>
35	#include <iprt/assert.h>
36	#include "internal/magics.h"
37
38	RT_C_DECLS_BEGIN
39
40	/** @defgroup grp_rt_memobj_int Internals.
41	* @ingroup grp_rt_memobj
42	* @internal
43	* @{
44	*/
45
46	/**
47	* Ring-0 memory object type.
48	*/
49	typedef enum RTR0MEMOBJTYPE
50	{
51	/** The traditional invalid value. */
52	RTR0MEMOBJTYPE_INVALID = 0,
53
54	/** @name Primary types (parents)
55	* @{ */
56	/** RTR0MemObjAllocPage.
57	* This memory is page aligned and fixed. */
58	RTR0MEMOBJTYPE_PAGE,
59	/** RTR0MemObjAllocLow.
60	* This memory is page aligned, fixed and is backed by physical memory below 4GB. */
61	RTR0MEMOBJTYPE_LOW,
62	/** RTR0MemObjAllocCont.
63	* This memory is page aligned, fixed and is backed by contiguous physical memory below 4GB. */
64	RTR0MEMOBJTYPE_CONT,
65	/** RTR0MemObjLockKernel, RTR0MemObjLockUser.
66	* This memory is page aligned and fixed. It was locked/pinned/wired down by the API call. */
67	RTR0MEMOBJTYPE_LOCK,
68	/** RTR0MemObjAllocPhys, RTR0MemObjEnterPhys.
69	* This memory is physical memory, page aligned, contiguous and doesn't need to have a mapping. */
70	RTR0MEMOBJTYPE_PHYS,
71	/** RTR0MemObjAllocPhysNC.
72	* This memory is physical memory, page aligned and doesn't need to have a mapping. */
73	RTR0MEMOBJTYPE_PHYS_NC,
74	/** RTR0MemObjReserveKernel, RTR0MemObjReserveUser.
75	* This memory is page aligned and has no backing. */
76	RTR0MEMOBJTYPE_RES_VIRT,
77	/** @} */
78
79	/** @name Secondary types (children)
80	* @{
81	*/
82	/** RTR0MemObjMapUser, RTR0MemObjMapKernel.
83	* This is a user or kernel context mapping of another ring-0 memory object. */
84	RTR0MEMOBJTYPE_MAPPING,
85	/** @} */
86
87	/** The end of the valid types. Used for sanity checking. */
88	RTR0MEMOBJTYPE_END
89	} RTR0MEMOBJTYPE;
90
91
92	/** @name RTR0MEMOBJINTERNAL::fFlags
93	* @{ */
94	/** Page level protection was changed. */
95	#define RTR0MEMOBJ_FLAGS_PROT_CHANGED RT_BIT_32(0)
96	/** @} */
97
98
99	typedef struct RTR0MEMOBJINTERNAL *PRTR0MEMOBJINTERNAL;
100	typedef struct RTR0MEMOBJINTERNAL **PPRTR0MEMOBJINTERNAL;
101
102	/**
103	* Ring-0 memory object.
104	*
105	* When using the PRTR0MEMOBJINTERNAL and PPRTR0MEMOBJINTERNAL types
106	* we get pMem and ppMem variable names.
107	*
108	* When using the RTR0MEMOBJ and PRTR0MEMOBJ types we get MemObj and
109	* pMemObj variable names. We never dereference variables of the RTR0MEMOBJ
110	* type, we always convert it to a PRTR0MEMOBJECTINTERNAL variable first.
111	*/
112	typedef struct RTR0MEMOBJINTERNAL
113	{
114	/** Magic number (RTR0MEMOBJ_MAGIC). */
115	uint32_t u32Magic;
116	/** The size of this structure. */
117	uint32_t cbSelf;
118	/** The type of allocation. */
119	RTR0MEMOBJTYPE enmType;
120	/** Flags, RTR0MEMOBJ_FLAGS_. /
121	uint32_t fFlags;
122	/** The size of the memory allocated, pinned down, or mapped. */
123	size_t cb;
124	/** The memory address.
125	* What this really is varies with the type.
126	* For PAGE, CONT, LOW, RES_VIRT/R0, LOCK/R0 and MAP/R0 it's the ring-0 mapping.
127	* For LOCK/R3, RES_VIRT/R3 and MAP/R3 it is the ring-3 mapping.
128	* For PHYS this might actually be NULL if there isn't any mapping.
129	*/
130	void *pv;
131
132	/** Object relations. */
133	union
134	{
135	/** This is for tracking child memory handles mapping the
136	* memory described by the primary handle. */
137	struct
138	{
139	/** Number of mappings. */
140	uint32_t cMappingsAllocated;
141	/** Number of mappings in the array. */
142	uint32_t cMappings;
143	/** Pointers to child handles mapping this memory. */
144	PPRTR0MEMOBJINTERNAL papMappings;
145	} Parent;
146
147	/** Pointer to the primary handle. */
148	struct
149	{
150	/** Pointer to the parent. */
151	PRTR0MEMOBJINTERNAL pParent;
152	} Child;
153	} uRel;
154
155	/** Type specific data for the memory types that requires that. */
156	union
157	{
158	/** RTR0MEMTYPE_PAGE. */
159	struct
160	{
161	unsigned iDummy;
162	} Page;
163
164	/** RTR0MEMTYPE_LOW. */
165	struct
166	{
167	unsigned iDummy;
168	} Low;
169
170	/** RTR0MEMTYPE_CONT. */
171	struct
172	{
173	/** The physical address of the first page. */
174	RTHCPHYS Phys;
175	} Cont;
176
177	/** RTR0MEMTYPE_LOCK_USER. */
178	struct
179	{
180	/** The process that owns the locked memory.
181	* This is NIL_RTR0PROCESS if it's kernel memory. */
182	RTR0PROCESS R0Process;
183	} Lock;
184
185	/** RTR0MEMTYPE_PHYS. */
186	struct
187	{
188	/** The base address of the physical memory. */
189	RTHCPHYS PhysBase;
190	/** If set this object was created by RTR0MemPhysAlloc, otherwise it was
191	* created by RTR0MemPhysEnter. */
192	bool fAllocated;
193	/** See RTMEM_CACHE_POLICY_XXX constants */
194	unsigned CachePolicy;
195	} Phys;
196
197	/** RTR0MEMTYPE_PHYS_NC. */
198	struct
199	{
200	unsigned iDummy;
201	} PhysNC;
202
203	/** RTR0MEMOBJTYPE_RES_VIRT */
204	struct
205	{
206	/** The process that owns the reserved memory.
207	* This is NIL_RTR0PROCESS if it's kernel memory. */
208	RTR0PROCESS R0Process;
209	} ResVirt;
210
211	/** RTR0MEMOBJTYPE_MAPPING */
212	struct
213	{
214	/** The process that owns the reserved memory.
215	* This is NIL_RTR0PROCESS if it's kernel memory. */
216	RTR0PROCESS R0Process;
217	} Mapping;
218	} u;
219
220	} RTR0MEMOBJINTERNAL;
221
222
223	/**
224	* Checks if this is mapping or not.
225	*
226	* @returns true if it's a mapping, otherwise false.
227	* @param pMem The ring-0 memory object handle.
228	* @see RTR0MemObjIsMapping
229	*/
230	DECLINLINE(bool) rtR0MemObjIsMapping(PRTR0MEMOBJINTERNAL pMem)
231	{
232	switch (pMem->enmType)
233	{
234	case RTR0MEMOBJTYPE_MAPPING:
235	return true;
236
237	default:
238	return false;
239	}
240	}
241
242
243	/**
244	* Checks page level protection can be changed on this object.
245	*
246	* @returns true / false.
247	* @param pMem The ring-0 memory object handle.
248	*/
249	DECLINLINE(bool) rtR0MemObjIsProtectable(PRTR0MEMOBJINTERNAL pMem)
250	{
251	switch (pMem->enmType)
252	{
253	case RTR0MEMOBJTYPE_MAPPING:
254	case RTR0MEMOBJTYPE_PAGE:
255	case RTR0MEMOBJTYPE_LOW:
256	case RTR0MEMOBJTYPE_CONT:
257	return true;
258
259	default:
260	return false;
261	}
262	}
263
264
265	/**
266	* Checks if RTR0MEMOBJ::pv is a ring-3 pointer or not.
267	*
268	* @returns true if it's a object with a ring-3 address, otherwise false.
269	* @param pMem The ring-0 memory object handle.
270	*/
271	DECLINLINE(bool) rtR0MemObjIsRing3(PRTR0MEMOBJINTERNAL pMem)
272	{
273	switch (pMem->enmType)
274	{
275	case RTR0MEMOBJTYPE_RES_VIRT:
276	return pMem->u.ResVirt.R0Process != NIL_RTR0PROCESS;
277	case RTR0MEMOBJTYPE_LOCK:
278	return pMem->u.Lock.R0Process != NIL_RTR0PROCESS;
279	case RTR0MEMOBJTYPE_MAPPING:
280	return pMem->u.Mapping.R0Process != NIL_RTR0PROCESS;
281	default:
282	return false;
283	}
284	}
285
286
287	/**
288	* Frees the memory object (but not the handle).
289	* Any OS specific handle resources will be freed by this call.
290	*
291	* @returns IPRT status code. On failure it is assumed that the object remains valid.
292	* @param pMem The ring-0 memory object handle to the memory which should be freed.
293	*/
294	int rtR0MemObjNativeFree(PRTR0MEMOBJINTERNAL pMem);
295
296	/**
297	* Allocates page aligned virtual kernel memory.
298	*
299	* The memory is taken from a non paged (= fixed physical memory backing) pool.
300	*
301	* @returns IPRT status code.
302	* @param ppMem Where to store the ring-0 memory object handle.
303	* @param cb Number of bytes to allocate, page aligned.
304	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
305	*/
306	int rtR0MemObjNativeAllocPage(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
307
308	/**
309	* Allocates page aligned virtual kernel memory with physical backing below 4GB.
310	*
311	* The physical memory backing the allocation is fixed.
312	*
313	* @returns IPRT status code.
314	* @param ppMem Where to store the ring-0 memory object handle.
315	* @param cb Number of bytes to allocate, page aligned.
316	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
317	*/
318	int rtR0MemObjNativeAllocLow(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
319
320	/**
321	* Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
322	*
323	* The physical memory backing the allocation is fixed.
324	*
325	* @returns IPRT status code.
326	* @param ppMem Where to store the ring-0 memory object handle.
327	* @param cb Number of bytes to allocate, page aligned.
328	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
329	*/
330	int rtR0MemObjNativeAllocCont(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
331
332	/**
333	* Locks a range of user virtual memory.
334	*
335	* @returns IPRT status code.
336	* @param ppMem Where to store the ring-0 memory object handle.
337	* @param R3Ptr User virtual address, page aligned.
338	* @param cb Number of bytes to lock, page aligned.
339	* @param fAccess The desired access, a combination of RTMEM_PROT_READ
340	* and RTMEM_PROT_WRITE.
341	* @param R0Process The process to lock pages in.
342	*/
343	int rtR0MemObjNativeLockUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3Ptr, size_t cb, uint32_t fAccess, RTR0PROCESS R0Process);
344
345	/**
346	* Locks a range of kernel virtual memory.
347	*
348	* @returns IPRT status code.
349	* @param ppMem Where to store the ring-0 memory object handle.
350	* @param pv Kernel virtual address, page aligned.
351	* @param cb Number of bytes to lock, page aligned.
352	* @param fAccess The desired access, a combination of RTMEM_PROT_READ
353	* and RTMEM_PROT_WRITE.
354	*/
355	int rtR0MemObjNativeLockKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pv, size_t cb, uint32_t fAccess);
356
357	/**
358	* Allocates contiguous page aligned physical memory without (necessarily) any
359	* kernel mapping.
360	*
361	* @returns IPRT status code.
362	* @param ppMem Where to store the ring-0 memory object handle.
363	* @param cb Number of bytes to allocate, page aligned.
364	* @param PhysHighest The highest permittable address (inclusive).
365	* NIL_RTHCPHYS if any address is acceptable.
366	* @param uAlignment The alignment of the reserved memory.
367	* Supported values are PAGE_SIZE, _2M, _4M and _1G.
368	*/
369	int rtR0MemObjNativeAllocPhys(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest, size_t uAlignment);
370
371	/**
372	* Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
373	*
374	* @returns IPRT status code.
375	* @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
376	* physical memory on this platform.
377	* @param ppMem Where to store the ring-0 memory object handle.
378	* @param cb Number of bytes to allocate, page aligned.
379	* @param PhysHighest The highest permittable address (inclusive).
380	* NIL_RTHCPHYS if any address is acceptable.
381	*/
382	int rtR0MemObjNativeAllocPhysNC(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest);
383
384	/**
385	* Creates a page aligned, contiguous, physical memory object.
386	*
387	* @returns IPRT status code.
388	* @param ppMem Where to store the ring-0 memory object handle.
389	* @param Phys The physical address to start at, page aligned.
390	* @param cb The size of the object in bytes, page aligned.
391	* @param CachePolicy One of the RTMEM_CACHE_XXX modes.
392	*/
393	int rtR0MemObjNativeEnterPhys(PPRTR0MEMOBJINTERNAL ppMem, RTHCPHYS Phys, size_t cb, unsigned CachePolicy);
394
395	/**
396	* Reserves kernel virtual address space.
397	*
398	* @returns IPRT status code.
399	* Return VERR_NOT_SUPPORTED to indicate that the user should employ fallback strategies.
400	* @param ppMem Where to store the ring-0 memory object handle.
401	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
402	* @param cb The number of bytes to reserve, page aligned.
403	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
404	*/
405	int rtR0MemObjNativeReserveKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pvFixed, size_t cb, size_t uAlignment);
406
407	/**
408	* Reserves user virtual address space in the current process.
409	*
410	* @returns IPRT status code.
411	* @param ppMem Where to store the ring-0 memory object handle.
412	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
413	* @param cb The number of bytes to reserve, page aligned.
414	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
415	* @param R0Process The process to reserve the memory in.
416	*/
417	int rtR0MemObjNativeReserveUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment, RTR0PROCESS R0Process);
418
419	/**
420	* Maps a memory object into user virtual address space in the current process.
421	*
422	* @returns IPRT status code.
423	* @retval VERR_NOT_SUPPORTED see RTR0MemObjMapKernelEx.
424	*
425	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
426	* @param pMemToMap The object to be map.
427	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
428	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
429	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
430	* @param offSub Where in the object to start mapping. If non-zero
431	* the value must be page aligned and cbSub must be
432	* non-zero as well.
433	* @param cbSub The size of the part of the object to be mapped. If
434	* zero the entire object is mapped. The value must be
435	* page aligned.
436	*/
437	int rtR0MemObjNativeMapKernel(PPRTR0MEMOBJINTERNAL ppMem, RTR0MEMOBJ pMemToMap, void *pvFixed, size_t uAlignment,
438	unsigned fProt, size_t offSub, size_t cbSub);
439
440	/**
441	* Maps a memory object into user virtual address space in the current process.
442	*
443	* @returns IPRT status code.
444	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
445	* @param pMemToMap The object to be map.
446	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
447	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
448	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
449	* @param R0Process The process to map the memory into.
450	*/
451	int rtR0MemObjNativeMapUser(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, RTR3PTR R3PtrFixed, size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process);
452
453	/**
454	* Change the page level protection of one or more pages in a memory object.
455	*
456	* @returns IPRT status code.
457	* @retval VERR_NOT_SUPPORTED see RTR0MemObjProtect.
458	*
459	* @param pMem The memory object.
460	* @param offSub Offset into the memory object. Page aligned.
461	* @param cbSub Number of bytes to change the protection of. Page
462	* aligned.
463	* @param fProt Combination of RTMEM_PROT_* flags.
464	*/
465	int rtR0MemObjNativeProtect(PRTR0MEMOBJINTERNAL pMem, size_t offSub, size_t cbSub, uint32_t fProt);
466
467	/**
468	* Get the physical address of an page in the memory object.
469	*
470	* @returns The physical address.
471	* @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
472	* @returns NIL_RTHCPHYS if the iPage is out of range.
473	* @returns NIL_RTHCPHYS if the object handle isn't valid.
474	* @param pMem The ring-0 memory object handle.
475	* @param iPage The page number within the object (valid).
476	*/
477	RTHCPHYS rtR0MemObjNativeGetPagePhysAddr(PRTR0MEMOBJINTERNAL pMem, size_t iPage);
478
479	PRTR0MEMOBJINTERNAL rtR0MemObjNew(size_t cbSelf, RTR0MEMOBJTYPE enmType, void *pv, size_t cb);
480	void rtR0MemObjDelete(PRTR0MEMOBJINTERNAL pMem);
481
482	/** @} */
483
484	RT_C_DECLS_END
485
486	#endif
487

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

source: vbox/trunk/src/VBox/Runtime/include/internal/memobj.h@ 28777

Download in other formats: