memobj-r0drv.h@ 1

Last change on this file since 1 was 1, checked in by vboxsync, 55 years ago
import
Property svn:keywords set to `Id`
File size: 13.1 KB

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

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

source: vbox/trunk/src/VBox/Runtime/r0drv/memobj-r0drv.h@ 1

Download in other formats: