memobj.h@ 4218

Last change on this file since 4218 was 4218, checked in by vboxsync, 17 years ago
docs.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Rev`
File size: 14.5 KB

Line
1	/* $Revision: 4218 $ */
2	/** @file
3	* innotek Portable Runtime - Ring-0 Memory Objects.
4	*/
5
6	/*
7	* Copyright (C) 2006-2007 innotek GmbH
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 as published by the Free Software Foundation,
13	* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
14	* distribution. VirtualBox OSE is distributed in the hope that it will
15	* be useful, but WITHOUT ANY WARRANTY of any kind.
16	*/
17
18	#ifndef ___internal_memobj_h
19	#define ___internal_memobj_h
20
21	#include <iprt/memobj.h>
22	#include <iprt/assert.h>
23	#include "internal/magics.h"
24
25	__BEGIN_DECLS
26
27	/** @defgroup grp_rt_memobj_int Internals.
28	* @ingroup grp_rt_memobj
29	* @internal
30	* @{
31	*/
32
33	/**
34	* Ring-0 memory object type.
35	*/
36	typedef enum RTR0MEMOBJTYPE
37	{
38	/** The traditional invalid value. */
39	RTR0MEMOBJTYPE_INVALID = 0,
40
41	/** @name Primary types (parents)
42	* @{ */
43	/** RTR0MemObjAllocPage.
44	* This memory is page aligned and fixed. */
45	RTR0MEMOBJTYPE_PAGE,
46	/** RTR0MemObjAllocLow.
47	* This memory is page aligned, fixed and is backed by physical memory below 4GB. */
48	RTR0MEMOBJTYPE_LOW,
49	/** RTR0MemObjAllocCont.
50	* This memory is page aligned, fixed and is backed by contiguous physical memory below 4GB. */
51	RTR0MEMOBJTYPE_CONT,
52	/** RTR0MemObjLockKernel, RTR0MemObjLockUser.
53	* This memory is page aligned and fixed. It was locked/pinned/wired down by the API call. */
54	RTR0MEMOBJTYPE_LOCK,
55	/** RTR0MemObjAllocPhys, RTR0MemObjEnterPhys.
56	* This memory is physical memory, page aligned, contiguous and doesn't need to have a mapping. */
57	RTR0MEMOBJTYPE_PHYS,
58	/** RTR0MemObjAllocPhysNC.
59	* This memory is physical memory, page aligned and doesn't need to have a mapping. */
60	RTR0MEMOBJTYPE_PHYS_NC,
61	/** RTR0MemObjReserveKernel, RTR0MemObjReserveUser.
62	* This memory is page aligned and has no backing. */
63	RTR0MEMOBJTYPE_RES_VIRT,
64	/** @} */
65
66	/** @name Secondary types (children)
67	* @{
68	*/
69	/** RTR0MemObjMapUser, RTR0MemObjMapKernel.
70	* This is a user or kernel context mapping of another ring-0 memory object. */
71	RTR0MEMOBJTYPE_MAPPING,
72	/** @} */
73
74	/** The end of the valid types. Used for sanity checking. */
75	RTR0MEMOBJTYPE_END
76	} RTR0MEMOBJTYPE;
77
78
79	typedef struct RTR0MEMOBJINTERNAL *PRTR0MEMOBJINTERNAL;
80	typedef struct RTR0MEMOBJINTERNAL **PPRTR0MEMOBJINTERNAL;
81
82	/**
83	* Ring-0 memory object.
84	*
85	* When using the PRTR0MEMOBJINTERNAL and PPRTR0MEMOBJINTERNAL types
86	* we get pMem and ppMem variable names.
87	*
88	* When using the RTR0MEMOBJ and PRTR0MEMOBJ types we get MemObj and
89	* pMemObj variable names. We never dereference variables of the RTR0MEMOBJ
90	* type, we always convert it to a PRTR0MEMOBJECTINTERNAL variable first.
91	*/
92	typedef struct RTR0MEMOBJINTERNAL
93	{
94	/** Magic number (RTR0MEM_MAGIC). */
95	uint32_t u32Magic;
96	/** The size of this structure. */
97	uint32_t cbSelf;
98	/** The type of allocation. */
99	RTR0MEMOBJTYPE enmType;
100	/** The size of the memory allocated, pinned down, or mapped. */
101	size_t cb;
102	/** The memory address.
103	* What this really is varies with the type.
104	* For PAGE, CONT, LOW, RES_VIRT/R0, LOCK/R0 and MAP/R0 it's the ring-0 mapping.
105	* For LOCK/R3, RES_VIRT/R3 and MAP/R3 it is the ring-3 mapping.
106	* For PHYS this might actually be NULL if there isn't any mapping.
107	*/
108	void *pv;
109
110	/** Object relations. */
111	union
112	{
113	/** This is for tracking child memory handles mapping the
114	* memory described by the primary handle. */
115	struct
116	{
117	/** Number of mappings. */
118	uint32_t cMappingsAllocated;
119	/** Number of mappings in the array. */
120	uint32_t cMappings;
121	/** Pointers to child handles mapping this memory. */
122	PPRTR0MEMOBJINTERNAL papMappings;
123	} Parent;
124
125	/** Pointer to the primary handle. */
126	struct
127	{
128	/** Pointer to the parent. */
129	PRTR0MEMOBJINTERNAL pParent;
130	} Child;
131	} uRel;
132
133	/** Type specific data for the memory types that requires that. */
134	union
135	{
136	/** RTR0MEMTYPE_PAGE. */
137	struct
138	{
139	unsigned iDummy;
140	} Page;
141
142	/** RTR0MEMTYPE_LOW. */
143	struct
144	{
145	unsigned iDummy;
146	} Low;
147
148	/** RTR0MEMTYPE_CONT. */
149	struct
150	{
151	/** The physical address of the first page. */
152	RTHCPHYS Phys;
153	} Cont;
154
155	/** RTR0MEMTYPE_LOCK_USER. */
156	struct
157	{
158	/** The process that owns the locked memory.
159	* This is NIL_RTR0PROCESS if it's kernel memory. */
160	RTR0PROCESS R0Process;
161	} Lock;
162
163	/** RTR0MEMTYPE_PHYS. */
164	struct
165	{
166	/** The base address of the physical memory. */
167	RTHCPHYS PhysBase;
168	/** If set this object was created by RTR0MemPhysAlloc, otherwise it was
169	* created by RTR0MemPhysEnter. */
170	bool fAllocated;
171	} Phys;
172
173	/** RTR0MEMTYPE_PHYS_NC. */
174	struct
175	{
176	unsigned iDummy;
177	} PhysNC;
178
179	/** RTR0MEMOBJTYPE_RES_VIRT */
180	struct
181	{
182	/** The process that owns the reserved memory.
183	* This is NIL_RTR0PROCESS if it's kernel memory. */
184	RTR0PROCESS R0Process;
185	} ResVirt;
186
187	/** RTR0MEMOBJTYPE_MAPPING */
188	struct
189	{
190	/** The process that owns the reserved memory.
191	* This is NIL_RTR0PROCESS if it's kernel memory. */
192	RTR0PROCESS R0Process;
193	} Mapping;
194	} u;
195
196	} RTR0MEMOBJINTERNAL;
197
198
199	/**
200	* Checks if this is mapping or not.
201	*
202	* @returns true if it's a mapping, otherwise false.
203	* @param MemObj The ring-0 memory object handle.
204	* @see RTR0MemObjIsMapping
205	*/
206	DECLINLINE(bool) rtR0MemObjIsMapping(PRTR0MEMOBJINTERNAL pMem)
207	{
208	switch (pMem->enmType)
209	{
210	case RTR0MEMOBJTYPE_MAPPING:
211	return true;
212
213	default:
214	return false;
215	}
216	}
217
218
219	/**
220	* Checks if RTR0MEMOBJ::pv is a ring-3 pointer or not.
221	*
222	* @returns true if it's a object with a ring-3 address, otherwise false.
223	* @param MemObj The ring-0 memory object handle.
224	*/
225	DECLINLINE(bool) rtR0MemObjIsRing3(PRTR0MEMOBJINTERNAL pMem)
226	{
227	switch (pMem->enmType)
228	{
229	case RTR0MEMOBJTYPE_RES_VIRT:
230	return pMem->u.ResVirt.R0Process != NIL_RTR0PROCESS;
231	case RTR0MEMOBJTYPE_LOCK:
232	return pMem->u.Lock.R0Process != NIL_RTR0PROCESS;
233	case RTR0MEMOBJTYPE_MAPPING:
234	return pMem->u.Mapping.R0Process != NIL_RTR0PROCESS;
235	default:
236	return false;
237	}
238	}
239
240
241	/**
242	* Frees the memory object (but not the handle).
243	* Any OS specific handle resources will be freed by this call.
244	*
245	* @returns IPRT status code. On failure it is assumed that the object remains valid.
246	* @param pMem The ring-0 memory object handle to the memory which should be freed.
247	*/
248	int rtR0MemObjNativeFree(PRTR0MEMOBJINTERNAL pMem);
249
250	/**
251	* Allocates page aligned virtual kernel memory.
252	*
253	* The memory is taken from a non paged (= fixed physical memory backing) pool.
254	*
255	* @returns IPRT status code.
256	* @param ppMem Where to store the ring-0 memory object handle.
257	* @param cb Number of bytes to allocate, page aligned.
258	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
259	*/
260	int rtR0MemObjNativeAllocPage(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
261
262	/**
263	* Allocates page aligned virtual kernel memory with physical backing below 4GB.
264	*
265	* The physical memory backing the allocation is fixed.
266	*
267	* @returns IPRT status code.
268	* @param ppMem Where to store the ring-0 memory object handle.
269	* @param cb Number of bytes to allocate, page aligned.
270	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
271	*/
272	int rtR0MemObjNativeAllocLow(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
273
274	/**
275	* Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
276	*
277	* The physical memory backing the allocation is fixed.
278	*
279	* @returns IPRT status code.
280	* @param ppMem Where to store the ring-0 memory object handle.
281	* @param cb Number of bytes to allocate, page aligned.
282	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
283	*/
284	int rtR0MemObjNativeAllocCont(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
285
286	/**
287	* Locks a range of user virtual memory.
288	*
289	* @returns IPRT status code.
290	* @param ppMem Where to store the ring-0 memory object handle.
291	* @param R3Ptr User virtual address, page aligned.
292	* @param cb Number of bytes to lock, page aligned.
293	* @param R0Process The process to lock pages in.
294	*/
295	int rtR0MemObjNativeLockUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3Ptr, size_t cb, RTR0PROCESS R0Process);
296
297	/**
298	* Locks a range of kernel virtual memory.
299	*
300	* @returns IPRT status code.
301	* @param ppMem Where to store the ring-0 memory object handle.
302	* @param pv Kernel virtual address, page aligned.
303	* @param cb Number of bytes to lock, page aligned.
304	*/
305	int rtR0MemObjNativeLockKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pv, size_t cb);
306
307	/**
308	* Allocates contiguous page aligned physical memory without (necessarily) any kernel mapping.
309	*
310	* @returns IPRT status code.
311	* @param ppMem Where to store the ring-0 memory object handle.
312	* @param cb Number of bytes to allocate, page aligned.
313	* @param PhysHighest The highest permittable address (inclusive).
314	* NIL_RTHCPHYS if any address is acceptable.
315	*/
316	int rtR0MemObjNativeAllocPhys(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest);
317
318	/**
319	* Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
320	*
321	* @returns IPRT status code.
322	* @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
323	* physical memory on this platform.
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 rtR0MemObjNativeAllocPhysNC(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest);
330
331	/**
332	* Creates a page aligned, contiguous, physical memory object.
333	*
334	* @returns IPRT status code.
335	* @param ppMem Where to store the ring-0 memory object handle.
336	* @param Phys The physical address to start at, page aligned.
337	* @param cb The size of the object in bytes, page aligned.
338	*/
339	int rtR0MemObjNativeEnterPhys(PPRTR0MEMOBJINTERNAL ppMem, RTHCPHYS Phys, size_t cb);
340
341	/**
342	* Reserves kernel virtual address space.
343	*
344	* @returns IPRT status code.
345	* Return VERR_NOT_SUPPORTED to indicate that the user should employ fallback strategies.
346	* @param ppMem Where to store the ring-0 memory object handle.
347	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
348	* @param cb The number of bytes to reserve, page aligned.
349	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
350	*/
351	int rtR0MemObjNativeReserveKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pvFixed, size_t cb, size_t uAlignment);
352
353	/**
354	* Reserves user virtual address space in the current process.
355	*
356	* @returns IPRT status code.
357	* @param ppMem Where to store the ring-0 memory object handle.
358	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
359	* @param cb The number of bytes to reserve, page aligned.
360	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
361	* @param R0Process The process to reserve the memory in.
362	*/
363	int rtR0MemObjNativeReserveUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment, RTR0PROCESS R0Process);
364
365	/**
366	* Maps a memory object into user virtual address space in the current process.
367	*
368	* @returns IPRT status code.
369	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
370	* @param pMemToMap The object to be map.
371	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
372	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
373	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
374	*/
375	int rtR0MemObjNativeMapKernel(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, void *pvFixed, size_t uAlignment, unsigned fProt);
376
377	/**
378	* Maps a memory object into user virtual address space in the current process.
379	*
380	* @returns IPRT status code.
381	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
382	* @param pMemToMap The object to be map.
383	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
384	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
385	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
386	* @param R0Process The process to map the memory into.
387	*/
388	int rtR0MemObjNativeMapUser(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, RTR3PTR R3PtrFixed, size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process);
389
390	/**
391	* Get the physical address of an page in the memory object.
392	*
393	* @returns The physical address.
394	* @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
395	* @returns NIL_RTHCPHYS if the iPage is out of range.
396	* @returns NIL_RTHCPHYS if the object handle isn't valid.
397	* @param pMem The ring-0 memory object handle.
398	* @param iPage The page number within the object (valid).
399	*/
400	RTHCPHYS rtR0MemObjNativeGetPagePhysAddr(PRTR0MEMOBJINTERNAL pMem, size_t iPage);
401
402	PRTR0MEMOBJINTERNAL rtR0MemObjNew(size_t cbSelf, RTR0MEMOBJTYPE enmType, void *pv, size_t cb);
403	void rtR0MemObjDelete(PRTR0MEMOBJINTERNAL pMem);
404
405	/** @} */
406
407	__END_DECLS
408
409	#endif
410

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

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

Download in other formats: