VirtualBox

source: vbox/trunk/include/iprt/memobj.h@ 3007

Last change on this file since 3007 was 2981, checked in by vboxsync, 18 years ago

InnoTek -> innotek: all the headers and comments.

File size: 9.7 KB
Line 
1/** @file
2 * innotek Portable Runtime - Memory Objects (Ring-0).
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * If you received this file as part of a commercial VirtualBox
17 * distribution, then only the terms of your commercial VirtualBox
18 * license agreement apply instead of the previous paragraph.
19 */
20
21
22#ifndef __iprt_memobj_h__
23#define __iprt_memobj_h__
24
25#include <iprt/cdefs.h>
26#include <iprt/types.h>
27
28__BEGIN_DECLS
29
30/** @defgroup grp_rt_memobj RTMemObj - Memory Object Manipulation (Ring-0)
31 * @ingroup grp_rt
32 * @{
33 */
34
35#ifdef IN_RING0
36
37/**
38 * Checks if this is mapping or not.
39 *
40 * @returns true if it's a mapping, otherwise false.
41 * @param MemObj The ring-0 memory object handle.
42 */
43RTR0DECL(bool) RTR0MemObjIsMapping(RTR0MEMOBJ MemObj);
44
45/**
46 * Gets the address of a ring-0 memory object.
47 *
48 * @returns The address of the memory object.
49 * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
50 * @param MemObj The ring-0 memory object handle.
51 */
52RTR0DECL(void *) RTR0MemObjAddress(RTR0MEMOBJ MemObj);
53
54/**
55 * Gets the size of a ring-0 memory object.
56 *
57 * @returns The address of the memory object.
58 * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
59 * @param MemObj The ring-0 memory object handle.
60 */
61RTR0DECL(size_t) RTR0MemObjSize(RTR0MEMOBJ MemObj);
62
63/**
64 * Get the physical address of an page in the memory object.
65 *
66 * @returns The physical address.
67 * @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
68 * @returns NIL_RTHCPHYS if the iPage is out of range.
69 * @returns NIL_RTHCPHYS if the object handle isn't valid.
70 * @param MemObj The ring-0 memory object handle.
71 * @param iPage The page number within the object.
72 */
73RTR0DECL(RTHCPHYS) RTR0MemObjGetPagePhysAddr(RTR0MEMOBJ MemObj, unsigned iPage);
74
75/**
76 * Frees a ring-0 memory object.
77 *
78 * @returns IPRT status code.
79 * @retval VERR_INVALID_HANDLE if
80 * @param MemObj The ring-0 memory object to be freed. NULL is accepted.
81 * @param fFreeMappings Whether or not to free mappings of the object.
82 */
83RTR0DECL(int) RTR0MemObjFree(RTR0MEMOBJ MemObj, bool fFreeMappings);
84
85/**
86 * Allocates page aligned virtual kernel memory.
87 *
88 * The memory is taken from a non paged (= fixed physical memory backing) pool.
89 *
90 * @returns IPRT status code.
91 * @param pMemObj Where to store the ring-0 memory object handle.
92 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
93 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
94 */
95RTR0DECL(int) RTR0MemObjAllocPage(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable);
96
97/**
98 * Allocates page aligned virtual kernel memory with physical backing below 4GB.
99 *
100 * The physical memory backing the allocation is fixed.
101 *
102 * @returns IPRT status code.
103 * @param pMemObj Where to store the ring-0 memory object handle.
104 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
105 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
106 */
107RTR0DECL(int) RTR0MemObjAllocLow(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable);
108
109/**
110 * Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
111 *
112 * The physical memory backing the allocation is fixed.
113 *
114 * @returns IPRT status code.
115 * @param pMemObj Where to store the ring-0 memory object handle.
116 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
117 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
118 */
119RTR0DECL(int) RTR0MemObjAllocCont(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable);
120
121/**
122 * Locks a range of user virtual memory.
123 *
124 * @returns IPRT status code.
125 * @param pMemObj Where to store the ring-0 memory object handle.
126 * @param pv User virtual address. This is rounded down to a page boundrary.
127 * @param cb Number of bytes to lock. This is rounded up to nearest page boundrary.
128 * @param R0Process The process to lock pages in. NIL_R0PROCESS is an alias for the current one.
129 *
130 * @remark RTR0MemObjGetAddress() will return the rounded down address.
131 */
132RTR0DECL(int) RTR0MemObjLockUser(PRTR0MEMOBJ pMemObj, void *pv, size_t cb, RTR0PROCESS R0Process);
133
134/**
135 * Locks a range of kernel virtual memory.
136 *
137 * @returns IPRT status code.
138 * @param pMemObj Where to store the ring-0 memory object handle.
139 * @param pv Kernel virtual address. This is rounded down to a page boundrary.
140 * @param cb Number of bytes to lock. This is rounded up to nearest page boundrary.
141 *
142 * @remark RTR0MemObjGetAddress() will return the rounded down address.
143 */
144RTR0DECL(int) RTR0MemObjLockKernel(PRTR0MEMOBJ pMemObj, void *pv, size_t cb);
145
146/**
147 * Allocates page aligned physical memory without (necessarily) any kernel mapping.
148 *
149 * @returns IPRT status code.
150 * @param pMemObj Where to store the ring-0 memory object handle.
151 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
152 * @param PhysHighest The highest permittable address (inclusive).
153 * Pass NIL_RTHCPHYS if any address is acceptable.
154 */
155RTR0DECL(int) RTR0MemObjAllocPhys(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest);
156
157/**
158 * Creates a page aligned, contiguous, physical memory object.
159 *
160 * No physical memory is allocated, we trust you do know what you're doing.
161 *
162 * @returns IPRT status code.
163 * @param pMemObj Where to store the ring-0 memory object handle.
164 * @param Phys The physical address to start at. This is rounded down to the
165 * nearest page boundrary.
166 * @param cb The size of the object in bytes. This is rounded up to nearest page boundrary.
167 */
168RTR0DECL(int) RTR0MemObjEnterPhys(PRTR0MEMOBJ pMemObj, RTHCPHYS Phys, size_t cb);
169
170/**
171 * Reserves kernel virtual address space.
172 *
173 * @returns IPRT status code.
174 * @param pMemObj Where to store the ring-0 memory object handle.
175 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
176 * @param cb The number of bytes to reserve. This is rounded up to nearest page.
177 * @param uAlignment The alignment of the reserved memory.
178 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
179 */
180RTR0DECL(int) RTR0MemObjReserveKernel(PRTR0MEMOBJ pMemObj, void *pvFixed, size_t cb, size_t uAlignment);
181
182/**
183 * Reserves user virtual address space in the current process.
184 *
185 * @returns IPRT status code.
186 * @param pMemObj Where to store the ring-0 memory object handle.
187 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
188 * @param cb The number of bytes to reserve. This is rounded up to nearest PAGE_SIZE.
189 * @param uAlignment The alignment of the reserved memory.
190 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
191 * @param R0Process The process to reserve the memory in. NIL_R0PROCESS is an alias for the current one.
192 */
193RTR0DECL(int) RTR0MemObjReserveUser(PRTR0MEMOBJ pMemObj, void *pvFixed, size_t cb, size_t uAlignment, RTR0PROCESS R0Process);
194
195/**
196 * Maps a memory object into kernel virtual address space.
197 *
198 * @returns IPRT status code.
199 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
200 * @param MemObjToMap The object to be map.
201 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
202 * @param uAlignment The alignment of the reserved memory.
203 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
204 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
205 */
206RTR0DECL(int) RTR0MemObjMapKernel(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed, size_t uAlignment, unsigned fProt);
207
208/**
209 * Maps a memory object into user virtual address space in the current process.
210 *
211 * @returns IPRT status code.
212 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
213 * @param MemObjToMap The object to be map.
214 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
215 * @param uAlignment The alignment of the reserved memory.
216 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
217 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
218 * @param R0Process The process to map the memory into. NIL_R0PROCESS is an alias for the current one.
219 */
220RTR0DECL(int) RTR0MemObjMapUser(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed, size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process);
221
222#endif /* IN_RING0 */
223
224/** @} */
225
226__END_DECLS
227
228#endif
229
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette