memobj.h@ 98477

Last change on this file since 98477 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Id Rev Revision`
File size: 20.9 KB

Line
1	/* $Id: memobj.h 98103 2023-01-17 14:15:46Z 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
47	RT_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	*/
58	typedef 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
114	typedef struct RTR0MEMOBJINTERNAL *PRTR0MEMOBJINTERNAL;
115	typedef 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	*/
127	typedef 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	*/
249	DECLINLINE(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	*/
268	DECLINLINE(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	*/
290	DECLINLINE(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	*/
313	DECLHIDDEN(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	*/
326	DECLHIDDEN(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	*/
339	DECLHIDDEN(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	*/
353	DECLHIDDEN(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 fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
364	* @param pszTag Allocation tag used for statistics and such.
365	*/
366	DECLHIDDEN(int) rtR0MemObjNativeAllocCont(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable, const char *pszTag);
367
368	/**
369	* Locks a range of user virtual memory.
370	*
371	* @returns IPRT status code.
372	* @param ppMem Where to store the ring-0 memory object handle.
373	* @param R3Ptr User virtual address, page aligned.
374	* @param cb Number of bytes to lock, page aligned.
375	* @param fAccess The desired access, a combination of RTMEM_PROT_READ
376	* and RTMEM_PROT_WRITE.
377	* @param R0Process The process to lock pages in.
378	* @param pszTag Allocation tag used for statistics and such.
379	*/
380	DECLHIDDEN(int) rtR0MemObjNativeLockUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3Ptr, size_t cb, uint32_t fAccess,
381	RTR0PROCESS R0Process, const char *pszTag);
382
383	/**
384	* Locks a range of kernel virtual memory.
385	*
386	* @returns IPRT status code.
387	* @param ppMem Where to store the ring-0 memory object handle.
388	* @param pv Kernel virtual address, page aligned.
389	* @param cb Number of bytes to lock, page aligned.
390	* @param fAccess The desired access, a combination of RTMEM_PROT_READ
391	* and RTMEM_PROT_WRITE.
392	* @param pszTag Allocation tag used for statistics and such.
393	*/
394	DECLHIDDEN(int) rtR0MemObjNativeLockKernel(PPRTR0MEMOBJINTERNAL ppMem, void pv, size_t cb, uint32_t fAccess, const char pszTag);
395
396	/**
397	* Allocates contiguous page aligned physical memory without (necessarily) any
398	* kernel mapping.
399	*
400	* @returns IPRT status code.
401	* @param ppMem Where to store the ring-0 memory object handle.
402	* @param cb Number of bytes to allocate, page aligned.
403	* @param PhysHighest The highest permitable address (inclusive).
404	* NIL_RTHCPHYS if any address is acceptable.
405	* @param uAlignment The alignment of the reserved memory.
406	* Supported values are PAGE_SIZE, _2M, _4M and _1G.
407	* @param pszTag Allocation tag used for statistics and such.
408	*/
409	DECLHIDDEN(int) rtR0MemObjNativeAllocPhys(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest, size_t uAlignment,
410	const char *pszTag);
411
412	/**
413	* Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
414	*
415	* @returns IPRT status code.
416	* @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
417	* physical memory on this platform.
418	* @param ppMem Where to store the ring-0 memory object handle.
419	* @param cb Number of bytes to allocate, page aligned.
420	* @param PhysHighest The highest permitable address (inclusive).
421	* NIL_RTHCPHYS if any address is acceptable.
422	* @param pszTag Allocation tag used for statistics and such.
423	*/
424	DECLHIDDEN(int) rtR0MemObjNativeAllocPhysNC(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest, const char *pszTag);
425
426	/**
427	* Creates a page aligned, contiguous, physical memory object.
428	*
429	* @returns IPRT status code.
430	* @param ppMem Where to store the ring-0 memory object handle.
431	* @param Phys The physical address to start at, page aligned.
432	* @param cb The size of the object in bytes, page aligned.
433	* @param uCachePolicy One of the RTMEM_CACHE_XXX modes.
434	* @param pszTag Allocation tag used for statistics and such.
435	*/
436	DECLHIDDEN(int) rtR0MemObjNativeEnterPhys(PPRTR0MEMOBJINTERNAL ppMem, RTHCPHYS Phys, size_t cb, uint32_t uCachePolicy,
437	const char *pszTag);
438
439	/**
440	* Reserves kernel virtual address space.
441	*
442	* @returns IPRT status code.
443	* Return VERR_NOT_SUPPORTED to indicate that the user should employ fallback strategies.
444	* @param ppMem Where to store the ring-0 memory object handle.
445	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
446	* @param cb The number of bytes to reserve, page aligned.
447	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
448	* @param pszTag Allocation tag used for statistics and such.
449	*/
450	DECLHIDDEN(int) rtR0MemObjNativeReserveKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pvFixed, size_t cb, size_t uAlignment,
451	const char *pszTag);
452
453	/**
454	* Reserves user virtual address space in the current process.
455	*
456	* @returns IPRT status code.
457	* @param ppMem Where to store the ring-0 memory object handle.
458	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
459	* @param cb The number of bytes to reserve, page aligned.
460	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
461	* @param R0Process The process to reserve the memory in.
462	* @param pszTag Allocation tag used for statistics and such.
463	*/
464	DECLHIDDEN(int) rtR0MemObjNativeReserveUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment,
465	RTR0PROCESS R0Process, const char *pszTag);
466
467	/**
468	* Maps a memory object into user virtual address space in the current process.
469	*
470	* @returns IPRT status code.
471	* @retval VERR_NOT_SUPPORTED see RTR0MemObjMapKernelEx.
472	*
473	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
474	* @param pMemToMap The object to be map.
475	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
476	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
477	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
478	* @param offSub Where in the object to start mapping. If non-zero
479	* the value must be page aligned and cbSub must be
480	* non-zero as well.
481	* @param cbSub The size of the part of the object to be mapped. If
482	* zero the entire object is mapped. The value must be
483	* page aligned.
484	* @param pszTag Allocation tag used for statistics and such.
485	*/
486	DECLHIDDEN(int) rtR0MemObjNativeMapKernel(PPRTR0MEMOBJINTERNAL ppMem, RTR0MEMOBJ pMemToMap, void *pvFixed, size_t uAlignment,
487	unsigned fProt, size_t offSub, size_t cbSub, const char *pszTag);
488
489	/**
490	* Maps a memory object into user virtual address space in the current process.
491	*
492	* @returns IPRT status code.
493	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
494	* @param pMemToMap The object to be map.
495	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
496	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
497	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
498	* @param R0Process The process to map the memory into.
499	* @param offSub Where in the object to start mapping. If non-zero
500	* the value must be page aligned and cbSub must be
501	* non-zero as well.
502	* @param cbSub The size of the part of the object to be mapped. If
503	* zero the entire object is mapped. The value must be
504	* page aligned.
505	* @param pszTag Allocation tag used for statistics and such.
506	*/
507	DECLHIDDEN(int) rtR0MemObjNativeMapUser(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, RTR3PTR R3PtrFixed,
508	size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process, size_t offSub, size_t cbSub,
509	const char *pszTag);
510
511	/**
512	* Change the page level protection of one or more pages in a memory object.
513	*
514	* @returns IPRT status code.
515	* @retval VERR_NOT_SUPPORTED see RTR0MemObjProtect.
516	*
517	* @param pMem The memory object.
518	* @param offSub Offset into the memory object. Page aligned.
519	* @param cbSub Number of bytes to change the protection of. Page
520	* aligned.
521	* @param fProt Combination of RTMEM_PROT_* flags.
522	*/
523	DECLHIDDEN(int) rtR0MemObjNativeProtect(PRTR0MEMOBJINTERNAL pMem, size_t offSub, size_t cbSub, uint32_t fProt);
524
525	/**
526	* Get the physical address of an page in the memory object.
527	*
528	* @returns The physical address.
529	* @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
530	* @returns NIL_RTHCPHYS if the iPage is out of range.
531	* @returns NIL_RTHCPHYS if the object handle isn't valid.
532	* @param pMem The ring-0 memory object handle.
533	* @param iPage The page number within the object (valid).
534	*/
535	DECLHIDDEN(RTHCPHYS) rtR0MemObjNativeGetPagePhysAddr(PRTR0MEMOBJINTERNAL pMem, size_t iPage);
536
537	DECLHIDDEN(PRTR0MEMOBJINTERNAL) rtR0MemObjNew(size_t cbSelf, RTR0MEMOBJTYPE enmType, void pv, size_t cb, const char pszTag);
538	DECLHIDDEN(void) rtR0MemObjDelete(PRTR0MEMOBJINTERNAL pMem);
539	DECLHIDDEN(int) rtR0MemObjFallbackAllocLarge(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, size_t cbLargePage, uint32_t fFlags,
540	const char *pszTag);
541
542	/** @} */
543
544	RT_C_DECLS_END
545
546	#endif /* !IPRT_INCLUDED_INTERNAL_memobj_h */
547

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: