VirtualBox

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

Last change on this file was 100357, checked in by vboxsync, 11 months ago

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use