memobj.h@ 53401

Last change on this file since 53401 was 36555, checked in by vboxsync, 14 years ago
Use DECLHIDDEN, especially in IPRT.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Rev`
File size: 17.5 KB

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

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

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

Download in other formats: