VirtualBox

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

Last change on this file since 86669 was 82968, checked in by vboxsync, 5 years ago

Copyright year updates by scm.

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