memobj.h@ 3977

Last change on this file since 3977 was 3977, checked in by vboxsync, 18 years ago
Implemented the timer and time apis for freebsd, stubbed the memobj ones.
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 13.0 KB

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

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

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

Download in other formats: