memobj.h@ 207

Last change on this file since 207 was 207, checked in by vboxsync, 18 years ago
cleaning up some header stuff.
Property svn:keywords set to `Id`
File size: 13.1 KB

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

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

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

Download in other formats: