VirtualBox

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

Last change on this file since 69010 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

  • Property eol-style set to native
  • Property svn:eol-style set to native
File size: 29.6 KB
Line 
1/** @file
2 * IPRT - Memory Objects (Ring-0).
3 */
4
5/*
6 * Copyright (C) 2006-2016 Oracle Corporation
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 (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_memobj_h
27#define ___iprt_memobj_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_memobj RTMemObj - Memory Object Manipulation (Ring-0)
35 * @ingroup grp_rt
36 * @{
37 */
38
39/** @def RTMEM_TAG
40 * The default allocation tag used by the RTMem allocation APIs.
41 *
42 * When not defined before the inclusion of iprt/memobj.h or iprt/mem.h, this
43 * will default to the pointer to the current file name. The memory API will
44 * make of use of this as pointer to a volatile but read-only string.
45 */
46#ifndef RTMEM_TAG
47# define RTMEM_TAG (__FILE__)
48#endif
49
50#ifdef IN_RING0
51
52/**
53 * Checks if this is mapping or not.
54 *
55 * @returns true if it's a mapping, otherwise false.
56 * @param MemObj The ring-0 memory object handle.
57 */
58RTR0DECL(bool) RTR0MemObjIsMapping(RTR0MEMOBJ MemObj);
59
60/**
61 * Gets the address of a ring-0 memory object.
62 *
63 * @returns The address of the memory object.
64 * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
65 * @param MemObj The ring-0 memory object handle.
66 */
67RTR0DECL(void *) RTR0MemObjAddress(RTR0MEMOBJ MemObj);
68
69/**
70 * Gets the ring-3 address of a ring-0 memory object.
71 *
72 * This only applies to ring-0 memory object with ring-3 mappings of some kind, i.e.
73 * locked user memory, reserved user address space and user mappings. This API should
74 * not be used on any other objects.
75 *
76 * @returns The address of the memory object.
77 * @returns NIL_RTR3PTR if the handle is invalid or if it's not an object with a ring-3 mapping.
78 * Strict builds will assert in both cases.
79 * @param MemObj The ring-0 memory object handle.
80 */
81RTR0DECL(RTR3PTR) RTR0MemObjAddressR3(RTR0MEMOBJ MemObj);
82
83/**
84 * Gets the size of a ring-0 memory object.
85 *
86 * The returned value may differ from the one specified to the API creating the
87 * object because of alignment adjustments. The minimal alignment currently
88 * employed by any API is PAGE_SIZE, so the result can safely be shifted by
89 * PAGE_SHIFT to calculate a page count.
90 *
91 * @returns The object size.
92 * @returns 0 if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
93 * @param MemObj The ring-0 memory object handle.
94 */
95RTR0DECL(size_t) RTR0MemObjSize(RTR0MEMOBJ MemObj);
96
97/**
98 * Get the physical address of an page in the memory object.
99 *
100 * @returns The physical address.
101 * @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
102 * @returns NIL_RTHCPHYS if the iPage is out of range.
103 * @returns NIL_RTHCPHYS if the object handle isn't valid.
104 * @param MemObj The ring-0 memory object handle.
105 * @param iPage The page number within the object.
106 */
107RTR0DECL(RTHCPHYS) RTR0MemObjGetPagePhysAddr(RTR0MEMOBJ MemObj, size_t iPage);
108
109/**
110 * Frees a ring-0 memory object.
111 *
112 * @returns IPRT status code.
113 * @retval VERR_INVALID_HANDLE if
114 * @param MemObj The ring-0 memory object to be freed. NULL is accepted.
115 * @param fFreeMappings Whether or not to free mappings of the object.
116 */
117RTR0DECL(int) RTR0MemObjFree(RTR0MEMOBJ MemObj, bool fFreeMappings);
118
119/**
120 * Allocates page aligned virtual kernel memory (default tag).
121 *
122 * The memory is taken from a non paged (= fixed physical memory backing) pool.
123 *
124 * @returns IPRT status code.
125 * @param pMemObj Where to store the ring-0 memory object handle.
126 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
127 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
128 */
129#define RTR0MemObjAllocPage(pMemObj, cb, fExecutable) \
130 RTR0MemObjAllocPageTag((pMemObj), (cb), (fExecutable), RTMEM_TAG)
131
132/**
133 * Allocates page aligned virtual kernel memory (custom tag).
134 *
135 * The memory is taken from a non paged (= fixed physical memory backing) pool.
136 *
137 * @returns IPRT status code.
138 * @param pMemObj Where to store the ring-0 memory object handle.
139 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
140 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
141 * @param pszTag Allocation tag used for statistics and such.
142 */
143RTR0DECL(int) RTR0MemObjAllocPageTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag);
144
145/**
146 * Allocates page aligned virtual kernel memory with physical backing below 4GB
147 * (default tag).
148 *
149 * The physical memory backing the allocation is fixed.
150 *
151 * @returns IPRT status code.
152 * @param pMemObj Where to store the ring-0 memory object handle.
153 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
154 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
155 */
156#define RTR0MemObjAllocLow(pMemObj, cb, fExecutable) \
157 RTR0MemObjAllocLowTag((pMemObj), (cb), (fExecutable), RTMEM_TAG)
158
159/**
160 * Allocates page aligned virtual kernel memory with physical backing below 4GB
161 * (custom tag).
162 *
163 * The physical memory backing the allocation is fixed.
164 *
165 * @returns IPRT status code.
166 * @param pMemObj Where to store the ring-0 memory object handle.
167 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
168 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
169 * @param pszTag Allocation tag used for statistics and such.
170 */
171RTR0DECL(int) RTR0MemObjAllocLowTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag);
172
173/**
174 * Allocates page aligned virtual kernel memory with contiguous physical backing
175 * below 4GB (default tag).
176 *
177 * The physical memory backing the allocation is fixed.
178 *
179 * @returns IPRT status code.
180 * @param pMemObj Where to store the ring-0 memory object handle.
181 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
182 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
183 */
184#define RTR0MemObjAllocCont(pMemObj, cb, fExecutable) \
185 RTR0MemObjAllocContTag((pMemObj), (cb), (fExecutable), RTMEM_TAG)
186
187/**
188 * Allocates page aligned virtual kernel memory with contiguous physical backing
189 * below 4GB (custom tag).
190 *
191 * The physical memory backing the allocation is fixed.
192 *
193 * @returns IPRT status code.
194 * @param pMemObj Where to store the ring-0 memory object handle.
195 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
196 * @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
197 * @param pszTag Allocation tag used for statistics and such.
198 */
199RTR0DECL(int) RTR0MemObjAllocContTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag);
200
201/**
202 * Locks a range of user virtual memory (default tag).
203 *
204 * @returns IPRT status code.
205 * @param pMemObj Where to store the ring-0 memory object handle.
206 * @param R3Ptr User virtual address. This is rounded down to a page
207 * boundary.
208 * @param cb Number of bytes to lock. This is rounded up to
209 * nearest page boundary.
210 * @param fAccess The desired access, a combination of RTMEM_PROT_READ
211 * and RTMEM_PROT_WRITE.
212 * @param R0Process The process to lock pages in. NIL_R0PROCESS is an
213 * alias for the current one.
214 *
215 * @remarks RTR0MemGetAddressR3() and RTR0MemGetAddress() will return therounded
216 * down address.
217 *
218 * @remarks Linux: This API requires that the memory begin locked is in a memory
219 * mapping that is not required in any forked off child process. This
220 * is not intented as permanent restriction, feel free to help out
221 * lifting it.
222 */
223#define RTR0MemObjLockUser(pMemObj, R3Ptr, cb, fAccess, R0Process) \
224 RTR0MemObjLockUserTag((pMemObj), (R3Ptr), (cb), (fAccess), (R0Process), RTMEM_TAG)
225
226/**
227 * Locks a range of user virtual memory (custom tag).
228 *
229 * @returns IPRT status code.
230 * @param pMemObj Where to store the ring-0 memory object handle.
231 * @param R3Ptr User virtual address. This is rounded down to a page
232 * boundary.
233 * @param cb Number of bytes to lock. This is rounded up to
234 * nearest page boundary.
235 * @param fAccess The desired access, a combination of RTMEM_PROT_READ
236 * and RTMEM_PROT_WRITE.
237 * @param R0Process The process to lock pages in. NIL_R0PROCESS is an
238 * alias for the current one.
239 * @param pszTag Allocation tag used for statistics and such.
240 *
241 * @remarks RTR0MemGetAddressR3() and RTR0MemGetAddress() will return therounded
242 * down address.
243 *
244 * @remarks Linux: This API requires that the memory begin locked is in a memory
245 * mapping that is not required in any forked off child process. This
246 * is not intented as permanent restriction, feel free to help out
247 * lifting it.
248 */
249RTR0DECL(int) RTR0MemObjLockUserTag(PRTR0MEMOBJ pMemObj, RTR3PTR R3Ptr, size_t cb, uint32_t fAccess,
250 RTR0PROCESS R0Process, const char *pszTag);
251
252/**
253 * Locks a range of kernel virtual memory (default tag).
254 *
255 * @returns IPRT status code.
256 * @param pMemObj Where to store the ring-0 memory object handle.
257 * @param pv Kernel virtual address. This is rounded down to a page boundary.
258 * @param cb Number of bytes to lock. This is rounded up to nearest page boundary.
259 * @param fAccess The desired access, a combination of RTMEM_PROT_READ
260 * and RTMEM_PROT_WRITE.
261 *
262 * @remark RTR0MemGetAddress() will return the rounded down address.
263 */
264#define RTR0MemObjLockKernel(pMemObj, pv, cb, fAccess) \
265 RTR0MemObjLockKernelTag((pMemObj), (pv), (cb), (fAccess), RTMEM_TAG)
266
267/**
268 * Locks a range of kernel virtual memory (custom tag).
269 *
270 * @returns IPRT status code.
271 * @param pMemObj Where to store the ring-0 memory object handle.
272 * @param pv Kernel virtual address. This is rounded down to a page boundary.
273 * @param cb Number of bytes to lock. This is rounded up to nearest page boundary.
274 * @param fAccess The desired access, a combination of RTMEM_PROT_READ
275 * and RTMEM_PROT_WRITE.
276 * @param pszTag Allocation tag used for statistics and such.
277 *
278 * @remark RTR0MemGetAddress() will return the rounded down address.
279 */
280RTR0DECL(int) RTR0MemObjLockKernelTag(PRTR0MEMOBJ pMemObj, void *pv, size_t cb, uint32_t fAccess, const char *pszTag);
281
282/**
283 * Allocates contiguous page aligned physical memory without (necessarily) any
284 * kernel mapping (default tag).
285 *
286 * @returns IPRT status code.
287 * @param pMemObj Where to store the ring-0 memory object handle.
288 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
289 * @param PhysHighest The highest permitable address (inclusive).
290 * Pass NIL_RTHCPHYS if any address is acceptable.
291 */
292#define RTR0MemObjAllocPhys(pMemObj, cb, PhysHighest) \
293 RTR0MemObjAllocPhysTag((pMemObj), (cb), (PhysHighest), RTMEM_TAG)
294
295/**
296 * Allocates contiguous page aligned physical memory without (necessarily) any
297 * kernel mapping (custom tag).
298 *
299 * @returns IPRT status code.
300 * @param pMemObj Where to store the ring-0 memory object handle.
301 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
302 * @param PhysHighest The highest permitable address (inclusive).
303 * Pass NIL_RTHCPHYS if any address is acceptable.
304 * @param pszTag Allocation tag used for statistics and such.
305 */
306RTR0DECL(int) RTR0MemObjAllocPhysTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, const char *pszTag);
307
308/**
309 * Allocates contiguous physical memory without (necessarily) any kernel mapping
310 * (default tag).
311 *
312 * @returns IPRT status code.
313 * @param pMemObj Where to store the ring-0 memory object handle.
314 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
315 * @param PhysHighest The highest permitable address (inclusive).
316 * Pass NIL_RTHCPHYS if any address is acceptable.
317 * @param uAlignment The alignment of the reserved memory.
318 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M, _4M and _1G.
319 */
320#define RTR0MemObjAllocPhysEx(pMemObj, cb, PhysHighest, uAlignment) \
321 RTR0MemObjAllocPhysExTag((pMemObj), (cb), (PhysHighest), (uAlignment), RTMEM_TAG)
322
323/**
324 * Allocates contiguous physical memory without (necessarily) any kernel mapping
325 * (custom tag).
326 *
327 * @returns IPRT status code.
328 * @param pMemObj Where to store the ring-0 memory object handle.
329 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
330 * @param PhysHighest The highest permitable address (inclusive).
331 * Pass NIL_RTHCPHYS if any address is acceptable.
332 * @param uAlignment The alignment of the reserved memory.
333 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M, _4M and _1G.
334 * @param pszTag Allocation tag used for statistics and such.
335 */
336RTR0DECL(int) RTR0MemObjAllocPhysExTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, size_t uAlignment, const char *pszTag);
337
338/**
339 * Allocates non-contiguous page aligned physical memory without (necessarily)
340 * any kernel mapping (default tag).
341 *
342 * This API is for allocating huge amounts of pages and will return
343 * VERR_NOT_SUPPORTED if this cannot be implemented in a satisfactory
344 * manner.
345 *
346 * @returns IPRT status code.
347 * @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
348 * physical memory on this platform. The caller should expect
349 * this error and have a fallback strategy for it.
350 *
351 * @param pMemObj Where to store the ring-0 memory object handle.
352 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
353 * @param PhysHighest The highest permitable address (inclusive).
354 * Pass NIL_RTHCPHYS if any address is acceptable.
355 */
356#define RTR0MemObjAllocPhysNC(pMemObj, cb, PhysHighest) \
357 RTR0MemObjAllocPhysNCTag((pMemObj), (cb), (PhysHighest), RTMEM_TAG)
358
359/**
360 * Allocates non-contiguous page aligned physical memory without (necessarily)
361 * any kernel mapping (custom tag).
362 *
363 * This API is for allocating huge amounts of pages and will return
364 * VERR_NOT_SUPPORTED if this cannot be implemented in a satisfactory
365 * manner.
366 *
367 * @returns IPRT status code.
368 * @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
369 * physical memory on this platform. The caller should expect
370 * this error and have a fallback strategy for it.
371 *
372 * @param pMemObj Where to store the ring-0 memory object handle.
373 * @param cb Number of bytes to allocate. This is rounded up to nearest page.
374 * @param PhysHighest The highest permitable address (inclusive).
375 * Pass NIL_RTHCPHYS if any address is acceptable.
376 * @param pszTag Allocation tag used for statistics and such.
377 */
378RTR0DECL(int) RTR0MemObjAllocPhysNCTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, const char *pszTag);
379
380/** Memory cache policy for RTR0MemObjEnterPhys.
381 * @{
382 */
383/** Default caching policy -- don't care. */
384#define RTMEM_CACHE_POLICY_DONT_CARE UINT32_C(0)
385/** MMIO caching policy -- uncachable. */
386#define RTMEM_CACHE_POLICY_MMIO UINT32_C(1)
387/** @} */
388
389/**
390 * Creates a page aligned, contiguous, physical memory object (default tag).
391 *
392 * No physical memory is allocated, we trust you do know what you're doing.
393 *
394 * @returns IPRT status code.
395 * @param pMemObj Where to store the ring-0 memory object handle.
396 * @param Phys The physical address to start at. This is rounded down to the
397 * nearest page boundary.
398 * @param cb The size of the object in bytes. This is rounded up to nearest page boundary.
399 * @param uCachePolicy One of the RTMEM_CACHE_XXX modes.
400 */
401#define RTR0MemObjEnterPhys(pMemObj, Phys, cb, uCachePolicy) \
402 RTR0MemObjEnterPhysTag((pMemObj), (Phys), (cb), (uCachePolicy), RTMEM_TAG)
403
404/**
405 * Creates a page aligned, contiguous, physical memory object (custom tag).
406 *
407 * No physical memory is allocated, we trust you do know what you're doing.
408 *
409 * @returns IPRT status code.
410 * @param pMemObj Where to store the ring-0 memory object handle.
411 * @param Phys The physical address to start at. This is rounded down to the
412 * nearest page boundary.
413 * @param cb The size of the object in bytes. This is rounded up to nearest page boundary.
414 * @param uCachePolicy One of the RTMEM_CACHE_XXX modes.
415 * @param pszTag Allocation tag used for statistics and such.
416 */
417RTR0DECL(int) RTR0MemObjEnterPhysTag(PRTR0MEMOBJ pMemObj, RTHCPHYS Phys, size_t cb, uint32_t uCachePolicy, const char *pszTag);
418
419/**
420 * Reserves kernel virtual address space (default tag).
421 *
422 * If this function fails with VERR_NOT_SUPPORTED, the idea is that you
423 * can use RTR0MemObjEnterPhys() + RTR0MemObjMapKernel() as a fallback if
424 * you have a safe physical address range to make use of...
425 *
426 * @returns IPRT status code.
427 * @param pMemObj Where to store the ring-0 memory object handle.
428 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
429 * @param cb The number of bytes to reserve. This is rounded up to nearest page.
430 * @param uAlignment The alignment of the reserved memory.
431 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
432 */
433#define RTR0MemObjReserveKernel(pMemObj, pvFixed, cb, uAlignment) \
434 RTR0MemObjReserveKernelTag((pMemObj), (pvFixed), (cb), (uAlignment), RTMEM_TAG)
435
436/**
437 * Reserves kernel virtual address space (custom tag).
438 *
439 * If this function fails with VERR_NOT_SUPPORTED, the idea is that you
440 * can use RTR0MemObjEnterPhys() + RTR0MemObjMapKernel() as a fallback if
441 * you have a safe physical address range to make use of...
442 *
443 * @returns IPRT status code.
444 * @param pMemObj Where to store the ring-0 memory object handle.
445 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
446 * @param cb The number of bytes to reserve. This is rounded up to nearest page.
447 * @param uAlignment The alignment of the reserved memory.
448 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
449 * @param pszTag Allocation tag used for statistics and such.
450 */
451RTR0DECL(int) RTR0MemObjReserveKernelTag(PRTR0MEMOBJ pMemObj, void *pvFixed, size_t cb, size_t uAlignment, const char *pszTag);
452
453/**
454 * Reserves user virtual address space in the current process (default tag).
455 *
456 * @returns IPRT status code.
457 * @param pMemObj Where to store the ring-0 memory object handle.
458 * @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
459 * @param cb The number of bytes to reserve. This is rounded up to nearest PAGE_SIZE.
460 * @param uAlignment The alignment of the reserved memory.
461 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
462 * @param R0Process The process to reserve the memory in. NIL_R0PROCESS is an alias for the current one.
463 */
464#define RTR0MemObjReserveUser(pMemObj, R3PtrFixed, cb, uAlignment, R0Process) \
465 RTR0MemObjReserveUserTag((pMemObj), (R3PtrFixed), (cb), (uAlignment), (R0Process), RTMEM_TAG)
466
467/**
468 * Reserves user virtual address space in the current process (custom tag).
469 *
470 * @returns IPRT status code.
471 * @param pMemObj Where to store the ring-0 memory object handle.
472 * @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
473 * @param cb The number of bytes to reserve. This is rounded up to nearest PAGE_SIZE.
474 * @param uAlignment The alignment of the reserved memory.
475 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
476 * @param R0Process The process to reserve the memory in. NIL_R0PROCESS is an alias for the current one.
477 * @param pszTag Allocation tag used for statistics and such.
478 */
479RTR0DECL(int) RTR0MemObjReserveUserTag(PRTR0MEMOBJ pMemObj, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment,
480 RTR0PROCESS R0Process, const char *pszTag);
481
482/**
483 * Maps a memory object into kernel virtual address space (default tag).
484 *
485 * This is the same as calling RTR0MemObjMapKernelEx with cbSub and offSub set
486 * to zero.
487 *
488 * @returns IPRT status code.
489 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
490 * @param MemObjToMap The object to be map.
491 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
492 * @param uAlignment The alignment of the reserved memory.
493 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
494 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
495 */
496#define RTR0MemObjMapKernel(pMemObj, MemObjToMap, pvFixed, uAlignment, fProt) \
497 RTR0MemObjMapKernelTag((pMemObj), (MemObjToMap), (pvFixed), (uAlignment), (fProt), RTMEM_TAG)
498
499/**
500 * Maps a memory object into kernel virtual address space (custom tag).
501 *
502 * This is the same as calling RTR0MemObjMapKernelEx with cbSub and offSub set
503 * to zero.
504 *
505 * @returns IPRT status code.
506 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
507 * @param MemObjToMap The object to be map.
508 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
509 * @param uAlignment The alignment of the reserved memory.
510 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
511 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
512 * @param pszTag Allocation tag used for statistics and such.
513 */
514RTR0DECL(int) RTR0MemObjMapKernelTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed,
515 size_t uAlignment, unsigned fProt, const char *pszTag);
516
517/**
518 * Maps a memory object into kernel virtual address space (default tag).
519 *
520 * The ability to map subsections of the object into kernel space is currently
521 * not implemented on all platforms. All/Most of platforms supports mapping the
522 * whole object into kernel space.
523 *
524 * @returns IPRT status code.
525 * @retval VERR_NOT_SUPPORTED if it's not possible to map a subsection of a
526 * memory object on this platform. When you hit this, try implement it.
527 *
528 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
529 * @param MemObjToMap The object to be map.
530 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
531 * @param uAlignment The alignment of the reserved memory.
532 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
533 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
534 * @param offSub Where in the object to start mapping. If non-zero
535 * the value must be page aligned and cbSub must be
536 * non-zero as well.
537 * @param cbSub The size of the part of the object to be mapped. If
538 * zero the entire object is mapped. The value must be
539 * page aligned.
540 */
541#define RTR0MemObjMapKernelEx(pMemObj, MemObjToMap, pvFixed, uAlignment, fProt, offSub, cbSub) \
542 RTR0MemObjMapKernelExTag((pMemObj), (MemObjToMap), (pvFixed), (uAlignment), (fProt), (offSub), (cbSub), RTMEM_TAG)
543
544/**
545 * Maps a memory object into kernel virtual address space (custom tag).
546 *
547 * The ability to map subsections of the object into kernel space is currently
548 * not implemented on all platforms. All/Most of platforms supports mapping the
549 * whole object into kernel space.
550 *
551 * @returns IPRT status code.
552 * @retval VERR_NOT_SUPPORTED if it's not possible to map a subsection of a
553 * memory object on this platform. When you hit this, try implement it.
554 *
555 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
556 * @param MemObjToMap The object to be map.
557 * @param pvFixed Requested address. (void *)-1 means any address. This must match the alignment.
558 * @param uAlignment The alignment of the reserved memory.
559 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
560 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
561 * @param offSub Where in the object to start mapping. If non-zero
562 * the value must be page aligned and cbSub must be
563 * non-zero as well.
564 * @param cbSub The size of the part of the object to be mapped. If
565 * zero the entire object is mapped. The value must be
566 * page aligned.
567 * @param pszTag Allocation tag used for statistics and such.
568 */
569RTR0DECL(int) RTR0MemObjMapKernelExTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed, size_t uAlignment,
570 unsigned fProt, size_t offSub, size_t cbSub, const char *pszTag);
571
572/**
573 * Maps a memory object into user virtual address space in the current process
574 * (default tag).
575 *
576 * @returns IPRT status code.
577 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
578 * @param MemObjToMap The object to be map.
579 * @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
580 * @param uAlignment The alignment of the reserved memory.
581 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
582 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
583 * @param R0Process The process to map the memory into. NIL_R0PROCESS is an alias for the current one.
584 */
585#define RTR0MemObjMapUser(pMemObj, MemObjToMap, R3PtrFixed, uAlignment, fProt, R0Process) \
586 RTR0MemObjMapUserTag((pMemObj), (MemObjToMap), (R3PtrFixed), (uAlignment), (fProt), (R0Process), RTMEM_TAG)
587
588/**
589 * Maps a memory object into user virtual address space in the current process
590 * (custom tag).
591 *
592 * @returns IPRT status code.
593 * @param pMemObj Where to store the ring-0 memory object handle of the mapping object.
594 * @param MemObjToMap The object to be map.
595 * @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This must match the alignment.
596 * @param uAlignment The alignment of the reserved memory.
597 * Supported values are 0 (alias for PAGE_SIZE), PAGE_SIZE, _2M and _4M.
598 * @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
599 * @param R0Process The process to map the memory into. NIL_R0PROCESS is an alias for the current one.
600 * @param pszTag Allocation tag used for statistics and such.
601 */
602RTR0DECL(int) RTR0MemObjMapUserTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, RTR3PTR R3PtrFixed,
603 size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process, const char *pszTag);
604
605/**
606 * Change the page level protection of one or more pages in a memory object.
607 *
608 * @returns IPRT status code.
609 * @retval VERR_NOT_SUPPORTED if the OS doesn't provide any way to manipulate
610 * page level protection. The caller must handle this status code
611 * gracefully. (Note that it may also occur if the implementation is
612 * missing, in which case just go ahead and implement it.)
613 *
614 * @param hMemObj Memory object handle.
615 * @param offSub Offset into the memory object. Must be page aligned.
616 * @param cbSub Number of bytes to change the protection of. Must be
617 * page aligned.
618 * @param fProt Combination of RTMEM_PROT_* flags.
619 */
620RTR0DECL(int) RTR0MemObjProtect(RTR0MEMOBJ hMemObj, size_t offSub, size_t cbSub, uint32_t fProt);
621
622#endif /* IN_RING0 */
623
624/** @} */
625
626RT_C_DECLS_END
627
628#endif
629
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