memobj.h@ 91481

Last change on this file since 91481 was 91481, checked in by vboxsync, 3 years ago
IPRT/memobj: Passing pszTag around...
Property svn:eol-style set to `native` Property svn:keywords set to `Id Rev Revision`
File size: 19.9 KB

Line
1	/* $Id: memobj.h 91481 2021-09-30 00:06:31Z 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
37	RT_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	*/
48	typedef 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
98	typedef struct RTR0MEMOBJINTERNAL *PRTR0MEMOBJINTERNAL;
99	typedef 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	*/
111	typedef 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	#if defined(DEBUG)
220	/** Allocation tag string. */
221	const char *pszTag;
222	#endif
223	} RTR0MEMOBJINTERNAL;
224
225
226	/**
227	* Checks if this is mapping or not.
228	*
229	* @returns true if it's a mapping, otherwise false.
230	* @param pMem The ring-0 memory object handle.
231	* @see RTR0MemObjIsMapping
232	*/
233	DECLINLINE(bool) rtR0MemObjIsMapping(PRTR0MEMOBJINTERNAL pMem)
234	{
235	switch (pMem->enmType)
236	{
237	case RTR0MEMOBJTYPE_MAPPING:
238	return true;
239
240	default:
241	return false;
242	}
243	}
244
245
246	/**
247	* Checks page level protection can be changed on this object.
248	*
249	* @returns true / false.
250	* @param pMem The ring-0 memory object handle.
251	*/
252	DECLINLINE(bool) rtR0MemObjIsProtectable(PRTR0MEMOBJINTERNAL pMem)
253	{
254	switch (pMem->enmType)
255	{
256	case RTR0MEMOBJTYPE_MAPPING:
257	case RTR0MEMOBJTYPE_PAGE:
258	case RTR0MEMOBJTYPE_LOW:
259	case RTR0MEMOBJTYPE_CONT:
260	return true;
261
262	default:
263	return false;
264	}
265	}
266
267
268	/**
269	* Checks if RTR0MEMOBJ::pv is a ring-3 pointer or not.
270	*
271	* @returns true if it's a object with a ring-3 address, otherwise false.
272	* @param pMem The ring-0 memory object handle.
273	*/
274	DECLINLINE(bool) rtR0MemObjIsRing3(PRTR0MEMOBJINTERNAL pMem)
275	{
276	switch (pMem->enmType)
277	{
278	case RTR0MEMOBJTYPE_RES_VIRT:
279	return pMem->u.ResVirt.R0Process != NIL_RTR0PROCESS;
280	case RTR0MEMOBJTYPE_LOCK:
281	return pMem->u.Lock.R0Process != NIL_RTR0PROCESS;
282	case RTR0MEMOBJTYPE_MAPPING:
283	return pMem->u.Mapping.R0Process != NIL_RTR0PROCESS;
284	default:
285	return false;
286	}
287	}
288
289
290	/**
291	* Frees the memory object (but not the handle).
292	* Any OS specific handle resources will be freed by this call.
293	*
294	* @returns IPRT status code. On failure it is assumed that the object remains valid.
295	* @param pMem The ring-0 memory object handle to the memory which should be freed.
296	*/
297	DECLHIDDEN(int) rtR0MemObjNativeFree(PRTR0MEMOBJINTERNAL pMem);
298
299	/**
300	* Allocates page aligned virtual kernel memory.
301	*
302	* The memory is taken from a non paged (= fixed physical memory backing) pool.
303	*
304	* @returns IPRT status code.
305	* @param ppMem Where to store the ring-0 memory object handle.
306	* @param cb Number of bytes to allocate, page aligned.
307	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
308	*/
309	DECLHIDDEN(int) rtR0MemObjNativeAllocPage(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
310
311	/**
312	* Worker for RTR0MemObjAllocLargeTag.
313	*
314	* @returns IPRT status code.
315	* @param ppMem Where to store the ring-0 memory object handle.
316	* @param cb Number of bytes to allocate, aligned to @a
317	* cbLargePage.
318	* @param cbLargePage The large page size.
319	* @param fFlags RTMEMOBJ_ALLOC_LARGE_F_XXX, validated.
320	* @param pszTag The allocation tag.
321	*/
322	DECLHIDDEN(int) rtR0MemObjNativeAllocLarge(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, size_t cbLargePage, uint32_t fFlags,
323	const char *pszTag);
324
325	/**
326	* Allocates page aligned virtual kernel memory with physical backing below 4GB.
327	*
328	* The physical memory backing the allocation is fixed.
329	*
330	* @returns IPRT status code.
331	* @param ppMem Where to store the ring-0 memory object handle.
332	* @param cb Number of bytes to allocate, page aligned.
333	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
334	*/
335	DECLHIDDEN(int) rtR0MemObjNativeAllocLow(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
336
337	/**
338	* Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
339	*
340	* The physical memory backing the allocation is fixed.
341	*
342	* @returns IPRT status code.
343	* @param ppMem Where to store the ring-0 memory object handle.
344	* @param cb Number of bytes to allocate, page aligned.
345	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
346	*/
347	DECLHIDDEN(int) rtR0MemObjNativeAllocCont(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable);
348
349	/**
350	* Locks a range of user virtual memory.
351	*
352	* @returns IPRT status code.
353	* @param ppMem Where to store the ring-0 memory object handle.
354	* @param R3Ptr User virtual address, page aligned.
355	* @param cb Number of bytes to lock, page aligned.
356	* @param fAccess The desired access, a combination of RTMEM_PROT_READ
357	* and RTMEM_PROT_WRITE.
358	* @param R0Process The process to lock pages in.
359	*/
360	DECLHIDDEN(int) rtR0MemObjNativeLockUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3Ptr, size_t cb, uint32_t fAccess, RTR0PROCESS R0Process);
361
362	/**
363	* Locks a range of kernel virtual memory.
364	*
365	* @returns IPRT status code.
366	* @param ppMem Where to store the ring-0 memory object handle.
367	* @param pv Kernel virtual address, page aligned.
368	* @param cb Number of bytes to lock, page aligned.
369	* @param fAccess The desired access, a combination of RTMEM_PROT_READ
370	* and RTMEM_PROT_WRITE.
371	*/
372	DECLHIDDEN(int) rtR0MemObjNativeLockKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pv, size_t cb, uint32_t fAccess);
373
374	/**
375	* Allocates contiguous page aligned physical memory without (necessarily) any
376	* kernel mapping.
377	*
378	* @returns IPRT status code.
379	* @param ppMem Where to store the ring-0 memory object handle.
380	* @param cb Number of bytes to allocate, page aligned.
381	* @param PhysHighest The highest permitable address (inclusive).
382	* NIL_RTHCPHYS if any address is acceptable.
383	* @param uAlignment The alignment of the reserved memory.
384	* Supported values are PAGE_SIZE, _2M, _4M and _1G.
385	* @param pszTag Allocation tag used for statistics and such.
386	*/
387	DECLHIDDEN(int) rtR0MemObjNativeAllocPhys(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest, size_t uAlignment,
388	const char *pszTag);
389
390	/**
391	* Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
392	*
393	* @returns IPRT status code.
394	* @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
395	* physical memory on this platform.
396	* @param ppMem Where to store the ring-0 memory object handle.
397	* @param cb Number of bytes to allocate, page aligned.
398	* @param PhysHighest The highest permitable address (inclusive).
399	* NIL_RTHCPHYS if any address is acceptable.
400	* @param pszTag Allocation tag used for statistics and such.
401	*/
402	DECLHIDDEN(int) rtR0MemObjNativeAllocPhysNC(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest, const char *pszTag);
403
404	/**
405	* Creates a page aligned, contiguous, physical memory object.
406	*
407	* @returns IPRT status code.
408	* @param ppMem Where to store the ring-0 memory object handle.
409	* @param Phys The physical address to start at, page aligned.
410	* @param cb The size of the object in bytes, page aligned.
411	* @param uCachePolicy One of the RTMEM_CACHE_XXX modes.
412	* @param pszTag Allocation tag used for statistics and such.
413	*/
414	DECLHIDDEN(int) rtR0MemObjNativeEnterPhys(PPRTR0MEMOBJINTERNAL ppMem, RTHCPHYS Phys, size_t cb, uint32_t uCachePolicy,
415	const char *pszTag);
416
417	/**
418	* Reserves kernel virtual address space.
419	*
420	* @returns IPRT status code.
421	* Return VERR_NOT_SUPPORTED to indicate that the user should employ fallback strategies.
422	* @param ppMem Where to store the ring-0 memory object handle.
423	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
424	* @param cb The number of bytes to reserve, page aligned.
425	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
426	* @param pszTag Allocation tag used for statistics and such.
427	*/
428	DECLHIDDEN(int) rtR0MemObjNativeReserveKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pvFixed, size_t cb, size_t uAlignment,
429	const char *pszTag);
430
431	/**
432	* Reserves user virtual address space in the current process.
433	*
434	* @returns IPRT status code.
435	* @param ppMem Where to store the ring-0 memory object handle.
436	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
437	* @param cb The number of bytes to reserve, page aligned.
438	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
439	* @param R0Process The process to reserve the memory in.
440	* @param pszTag Allocation tag used for statistics and such.
441	*/
442	DECLHIDDEN(int) rtR0MemObjNativeReserveUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment,
443	RTR0PROCESS R0Process, const char *pszTag);
444
445	/**
446	* Maps a memory object into user virtual address space in the current process.
447	*
448	* @returns IPRT status code.
449	* @retval VERR_NOT_SUPPORTED see RTR0MemObjMapKernelEx.
450	*
451	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
452	* @param pMemToMap The object to be map.
453	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
454	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
455	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
456	* @param offSub Where in the object to start mapping. If non-zero
457	* the value must be page aligned and cbSub must be
458	* non-zero as well.
459	* @param cbSub The size of the part of the object to be mapped. If
460	* zero the entire object is mapped. The value must be
461	* page aligned.
462	* @param pszTag Allocation tag used for statistics and such.
463	*/
464	DECLHIDDEN(int) rtR0MemObjNativeMapKernel(PPRTR0MEMOBJINTERNAL ppMem, RTR0MEMOBJ pMemToMap, void *pvFixed, size_t uAlignment,
465	unsigned fProt, size_t offSub, size_t cbSub, 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	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
472	* @param pMemToMap The object to be map.
473	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
474	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
475	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
476	* @param R0Process The process to map the memory into.
477	* @param offSub Where in the object to start mapping. If non-zero
478	* the value must be page aligned and cbSub must be
479	* non-zero as well.
480	* @param cbSub The size of the part of the object to be mapped. If
481	* zero the entire object is mapped. The value must be
482	* page aligned.
483	* @param pszTag Allocation tag used for statistics and such.
484	*/
485	DECLHIDDEN(int) rtR0MemObjNativeMapUser(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, RTR3PTR R3PtrFixed,
486	size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process, size_t offSub, size_t cbSub,
487	const char *pszTag);
488
489	/**
490	* Change the page level protection of one or more pages in a memory object.
491	*
492	* @returns IPRT status code.
493	* @retval VERR_NOT_SUPPORTED see RTR0MemObjProtect.
494	*
495	* @param pMem The memory object.
496	* @param offSub Offset into the memory object. Page aligned.
497	* @param cbSub Number of bytes to change the protection of. Page
498	* aligned.
499	* @param fProt Combination of RTMEM_PROT_* flags.
500	*/
501	DECLHIDDEN(int) rtR0MemObjNativeProtect(PRTR0MEMOBJINTERNAL pMem, size_t offSub, size_t cbSub, uint32_t fProt);
502
503	/**
504	* Get the physical address of an page in the memory object.
505	*
506	* @returns The physical address.
507	* @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
508	* @returns NIL_RTHCPHYS if the iPage is out of range.
509	* @returns NIL_RTHCPHYS if the object handle isn't valid.
510	* @param pMem The ring-0 memory object handle.
511	* @param iPage The page number within the object (valid).
512	*/
513	DECLHIDDEN(RTHCPHYS) rtR0MemObjNativeGetPagePhysAddr(PRTR0MEMOBJINTERNAL pMem, size_t iPage);
514
515	DECLHIDDEN(PRTR0MEMOBJINTERNAL) rtR0MemObjNew(size_t cbSelf, RTR0MEMOBJTYPE enmType, void pv, size_t cb, const char pszTag);
516	DECLHIDDEN(void) rtR0MemObjDelete(PRTR0MEMOBJINTERNAL pMem);
517	DECLHIDDEN(int) rtR0MemObjFallbackAllocLarge(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, size_t cbLargePage, uint32_t fFlags,
518	const char *pszTag);
519
520	/** @} */
521
522	RT_C_DECLS_END
523
524	#endif /* !IPRT_INCLUDED_INTERNAL_memobj_h */
525

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

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

Download in other formats: