VirtualBox

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

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago

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

© 2024 Oracle
Contact – Privacy/Do Not Sell My Info – Terms of Use