memobj.h@ 4135

Last change on this file since 4135 was 4135, checked in by vboxsync, 17 years ago
Use size_t for the page index. Added API for querying the ring-3 address.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 12.8 KB

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

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

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

Download in other formats: