memobj.h@ 14059

Last change on this file since 14059 was 8245, checked in by vboxsync, 17 years ago
rebranding: IPRT files again.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Rev`
File size: 15.1 KB

Line
1	/* $Revision: 8245 $ */
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	__BEGIN_DECLS
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	typedef struct RTR0MEMOBJINTERNAL *PRTR0MEMOBJINTERNAL;
93	typedef struct RTR0MEMOBJINTERNAL **PPRTR0MEMOBJINTERNAL;
94
95	/**
96	* Ring-0 memory object.
97	*
98	* When using the PRTR0MEMOBJINTERNAL and PPRTR0MEMOBJINTERNAL types
99	* we get pMem and ppMem variable names.
100	*
101	* When using the RTR0MEMOBJ and PRTR0MEMOBJ types we get MemObj and
102	* pMemObj variable names. We never dereference variables of the RTR0MEMOBJ
103	* type, we always convert it to a PRTR0MEMOBJECTINTERNAL variable first.
104	*/
105	typedef struct RTR0MEMOBJINTERNAL
106	{
107	/** Magic number (RTR0MEM_MAGIC). */
108	uint32_t u32Magic;
109	/** The size of this structure. */
110	uint32_t cbSelf;
111	/** The type of allocation. */
112	RTR0MEMOBJTYPE enmType;
113	/** The size of the memory allocated, pinned down, or mapped. */
114	size_t cb;
115	/** The memory address.
116	* What this really is varies with the type.
117	* For PAGE, CONT, LOW, RES_VIRT/R0, LOCK/R0 and MAP/R0 it's the ring-0 mapping.
118	* For LOCK/R3, RES_VIRT/R3 and MAP/R3 it is the ring-3 mapping.
119	* For PHYS this might actually be NULL if there isn't any mapping.
120	*/
121	void *pv;
122
123	/** Object relations. */
124	union
125	{
126	/** This is for tracking child memory handles mapping the
127	* memory described by the primary handle. */
128	struct
129	{
130	/** Number of mappings. */
131	uint32_t cMappingsAllocated;
132	/** Number of mappings in the array. */
133	uint32_t cMappings;
134	/** Pointers to child handles mapping this memory. */
135	PPRTR0MEMOBJINTERNAL papMappings;
136	} Parent;
137
138	/** Pointer to the primary handle. */
139	struct
140	{
141	/** Pointer to the parent. */
142	PRTR0MEMOBJINTERNAL pParent;
143	} Child;
144	} uRel;
145
146	/** Type specific data for the memory types that requires that. */
147	union
148	{
149	/** RTR0MEMTYPE_PAGE. */
150	struct
151	{
152	unsigned iDummy;
153	} Page;
154
155	/** RTR0MEMTYPE_LOW. */
156	struct
157	{
158	unsigned iDummy;
159	} Low;
160
161	/** RTR0MEMTYPE_CONT. */
162	struct
163	{
164	/** The physical address of the first page. */
165	RTHCPHYS Phys;
166	} Cont;
167
168	/** RTR0MEMTYPE_LOCK_USER. */
169	struct
170	{
171	/** The process that owns the locked memory.
172	* This is NIL_RTR0PROCESS if it's kernel memory. */
173	RTR0PROCESS R0Process;
174	} Lock;
175
176	/** RTR0MEMTYPE_PHYS. */
177	struct
178	{
179	/** The base address of the physical memory. */
180	RTHCPHYS PhysBase;
181	/** If set this object was created by RTR0MemPhysAlloc, otherwise it was
182	* created by RTR0MemPhysEnter. */
183	bool fAllocated;
184	} Phys;
185
186	/** RTR0MEMTYPE_PHYS_NC. */
187	struct
188	{
189	unsigned iDummy;
190	} PhysNC;
191
192	/** RTR0MEMOBJTYPE_RES_VIRT */
193	struct
194	{
195	/** The process that owns the reserved memory.
196	* This is NIL_RTR0PROCESS if it's kernel memory. */
197	RTR0PROCESS R0Process;
198	} ResVirt;
199
200	/** RTR0MEMOBJTYPE_MAPPING */
201	struct
202	{
203	/** The process that owns the reserved memory.
204	* This is NIL_RTR0PROCESS if it's kernel memory. */
205	RTR0PROCESS R0Process;
206	} Mapping;
207	} u;
208
209	} RTR0MEMOBJINTERNAL;
210
211
212	/**
213	* Checks if this is mapping or not.
214	*
215	* @returns true if it's a mapping, otherwise false.
216	* @param pMem The ring-0 memory object handle.
217	* @see RTR0MemObjIsMapping
218	*/
219	DECLINLINE(bool) rtR0MemObjIsMapping(PRTR0MEMOBJINTERNAL pMem)
220	{
221	switch (pMem->enmType)
222	{
223	case RTR0MEMOBJTYPE_MAPPING:
224	return true;
225
226	default:
227	return false;
228	}
229	}
230
231
232	/**
233	* Checks if RTR0MEMOBJ::pv is a ring-3 pointer or not.
234	*
235	* @returns true if it's a object with a ring-3 address, otherwise false.
236	* @param pMem The ring-0 memory object handle.
237	*/
238	DECLINLINE(bool) rtR0MemObjIsRing3(PRTR0MEMOBJINTERNAL pMem)
239	{
240	switch (pMem->enmType)
241	{
242	case RTR0MEMOBJTYPE_RES_VIRT:
243	return pMem->u.ResVirt.R0Process != NIL_RTR0PROCESS;
244	case RTR0MEMOBJTYPE_LOCK:
245	return pMem->u.Lock.R0Process != NIL_RTR0PROCESS;
246	case RTR0MEMOBJTYPE_MAPPING:
247	return pMem->u.Mapping.R0Process != NIL_RTR0PROCESS;
248	default:
249	return false;
250	}
251	}
252
253
254	/**
255	* Frees the memory object (but not the handle).
256	* Any OS specific handle resources will be freed by this call.
257	*
258	* @returns IPRT status code. On failure it is assumed that the object remains valid.
259	* @param pMem The ring-0 memory object handle to the memory which should be freed.
260	*/
261	int rtR0MemObjNativeFree(PRTR0MEMOBJINTERNAL pMem);
262
263	/**
264	* Allocates page aligned virtual kernel memory.
265	*
266	* The memory is taken from a non paged (= fixed physical memory backing) pool.
267	*
268	* @returns IPRT status code.
269	* @param ppMem Where to store the ring-0 memory object handle.
270	* @param cb Number of bytes to allocate, page aligned.
271	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
272	*/
273	int rtR0MemObjNativeAllocPage(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
274
275	/**
276	* Allocates page aligned virtual kernel memory with physical backing below 4GB.
277	*
278	* The physical memory backing the allocation is fixed.
279	*
280	* @returns IPRT status code.
281	* @param ppMem Where to store the ring-0 memory object handle.
282	* @param cb Number of bytes to allocate, page aligned.
283	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
284	*/
285	int rtR0MemObjNativeAllocLow(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
286
287	/**
288	* Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
289	*
290	* The physical memory backing the allocation is fixed.
291	*
292	* @returns IPRT status code.
293	* @param ppMem Where to store the ring-0 memory object handle.
294	* @param cb Number of bytes to allocate, page aligned.
295	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
296	*/
297	int rtR0MemObjNativeAllocCont(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
298
299	/**
300	* Locks a range of user virtual memory.
301	*
302	* @returns IPRT status code.
303	* @param ppMem Where to store the ring-0 memory object handle.
304	* @param R3Ptr User virtual address, page aligned.
305	* @param cb Number of bytes to lock, page aligned.
306	* @param R0Process The process to lock pages in.
307	*/
308	int rtR0MemObjNativeLockUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3Ptr, size_t cb, RTR0PROCESS R0Process);
309
310	/**
311	* Locks a range of kernel virtual memory.
312	*
313	* @returns IPRT status code.
314	* @param ppMem Where to store the ring-0 memory object handle.
315	* @param pv Kernel virtual address, page aligned.
316	* @param cb Number of bytes to lock, page aligned.
317	*/
318	int rtR0MemObjNativeLockKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pv, size_t cb);
319
320	/**
321	* Allocates contiguous page aligned physical memory without (necessarily) any kernel mapping.
322	*
323	* @returns IPRT status code.
324	* @param ppMem Where to store the ring-0 memory object handle.
325	* @param cb Number of bytes to allocate, page aligned.
326	* @param PhysHighest The highest permittable address (inclusive).
327	* NIL_RTHCPHYS if any address is acceptable.
328	*/
329	int rtR0MemObjNativeAllocPhys(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest);
330
331	/**
332	* Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
333	*
334	* @returns IPRT status code.
335	* @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
336	* physical memory on this platform.
337	* @param ppMem Where to store the ring-0 memory object handle.
338	* @param cb Number of bytes to allocate, page aligned.
339	* @param PhysHighest The highest permittable address (inclusive).
340	* NIL_RTHCPHYS if any address is acceptable.
341	*/
342	int rtR0MemObjNativeAllocPhysNC(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest);
343
344	/**
345	* Creates a page aligned, contiguous, physical memory object.
346	*
347	* @returns IPRT status code.
348	* @param ppMem Where to store the ring-0 memory object handle.
349	* @param Phys The physical address to start at, page aligned.
350	* @param cb The size of the object in bytes, page aligned.
351	*/
352	int rtR0MemObjNativeEnterPhys(PPRTR0MEMOBJINTERNAL ppMem, RTHCPHYS Phys, size_t cb);
353
354	/**
355	* Reserves kernel virtual address space.
356	*
357	* @returns IPRT status code.
358	* Return VERR_NOT_SUPPORTED to indicate that the user should employ fallback strategies.
359	* @param ppMem Where to store the ring-0 memory object handle.
360	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
361	* @param cb The number of bytes to reserve, page aligned.
362	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
363	*/
364	int rtR0MemObjNativeReserveKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pvFixed, size_t cb, size_t uAlignment);
365
366	/**
367	* Reserves user virtual address space in the current process.
368	*
369	* @returns IPRT status code.
370	* @param ppMem Where to store the ring-0 memory object handle.
371	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
372	* @param cb The number of bytes to reserve, page aligned.
373	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
374	* @param R0Process The process to reserve the memory in.
375	*/
376	int rtR0MemObjNativeReserveUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment, RTR0PROCESS R0Process);
377
378	/**
379	* Maps a memory object into user virtual address space in the current process.
380	*
381	* @returns IPRT status code.
382	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
383	* @param pMemToMap The object to be map.
384	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
385	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
386	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
387	*/
388	int rtR0MemObjNativeMapKernel(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, void *pvFixed, size_t uAlignment, unsigned fProt);
389
390	/**
391	* Maps a memory object into user virtual address space in the current process.
392	*
393	* @returns IPRT status code.
394	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
395	* @param pMemToMap The object to be map.
396	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
397	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
398	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
399	* @param R0Process The process to map the memory into.
400	*/
401	int rtR0MemObjNativeMapUser(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, RTR3PTR R3PtrFixed, size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process);
402
403	/**
404	* Get the physical address of an page in the memory object.
405	*
406	* @returns The physical address.
407	* @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
408	* @returns NIL_RTHCPHYS if the iPage is out of range.
409	* @returns NIL_RTHCPHYS if the object handle isn't valid.
410	* @param pMem The ring-0 memory object handle.
411	* @param iPage The page number within the object (valid).
412	*/
413	RTHCPHYS rtR0MemObjNativeGetPagePhysAddr(PRTR0MEMOBJINTERNAL pMem, size_t iPage);
414
415	PRTR0MEMOBJINTERNAL rtR0MemObjNew(size_t cbSelf, RTR0MEMOBJTYPE enmType, void *pv, size_t cb);
416	void rtR0MemObjDelete(PRTR0MEMOBJINTERNAL pMem);
417
418	/** @} */
419
420	__END_DECLS
421
422	#endif
423

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

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

Download in other formats: