memobj.h@ 92246

Last change on this file since 92246 was 92246, checked in by vboxsync, 3 years ago
IPRT/RTR0MemObj: Added RTR0MemObjWasZeroInitialized and a couple of flags with which the backend can feed it the necessary info. It would be good to try avoid zeroing memory twice when we can. bugref:10093
Property svn:eol-style set to `native` Property svn:keywords set to `Id Rev Revision`
File size: 20.6 KB

Line
1	/* $Id: memobj.h 92246 2021-11-06 03:10:49Z 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	/** Zero initialized at allocation. */
96	#define RTR0MEMOBJ_FLAGS_ZERO_AT_ALLOC RT_BIT_32(1)
97	/** Uninitialized at allocation. */
98	#define RTR0MEMOBJ_FLAGS_UNINITIALIZED_AT_ALLOC RT_BIT_32(2)
99	/** @} */
100
101
102	typedef struct RTR0MEMOBJINTERNAL *PRTR0MEMOBJINTERNAL;
103	typedef struct RTR0MEMOBJINTERNAL **PPRTR0MEMOBJINTERNAL;
104
105	/**
106	* Ring-0 memory object.
107	*
108	* When using the PRTR0MEMOBJINTERNAL and PPRTR0MEMOBJINTERNAL types
109	* we get pMem and ppMem variable names.
110	*
111	* When using the RTR0MEMOBJ and PRTR0MEMOBJ types we get MemObj and
112	* pMemObj variable names. We never dereference variables of the RTR0MEMOBJ
113	* type, we always convert it to a PRTR0MEMOBJECTINTERNAL variable first.
114	*/
115	typedef struct RTR0MEMOBJINTERNAL
116	{
117	/** Magic number (RTR0MEMOBJ_MAGIC). */
118	uint32_t u32Magic;
119	/** The size of this structure. */
120	uint32_t cbSelf;
121	/** The type of allocation. */
122	RTR0MEMOBJTYPE enmType;
123	/** Flags, RTR0MEMOBJ_FLAGS_. /
124	uint32_t fFlags;
125	/** The size of the memory allocated, pinned down, or mapped. */
126	size_t cb;
127	/** The memory address.
128	* What this really is varies with the type.
129	* For PAGE, CONT, LOW, RES_VIRT/R0, LOCK/R0 and MAP/R0 it's the ring-0 mapping.
130	* For LOCK/R3, RES_VIRT/R3 and MAP/R3 it is the ring-3 mapping.
131	* For PHYS this might actually be NULL if there isn't any mapping.
132	*/
133	void *pv;
134
135	/** Object relations. */
136	union
137	{
138	/** This is for tracking child memory handles mapping the
139	* memory described by the primary handle. */
140	struct
141	{
142	/** Number of mappings. */
143	uint32_t cMappingsAllocated;
144	/** Number of mappings in the array. */
145	uint32_t cMappings;
146	/** Pointers to child handles mapping this memory. */
147	PPRTR0MEMOBJINTERNAL papMappings;
148	} Parent;
149
150	/** Pointer to the primary handle. */
151	struct
152	{
153	/** Pointer to the parent. */
154	PRTR0MEMOBJINTERNAL pParent;
155	} Child;
156	} uRel;
157
158	/** Type specific data for the memory types that requires that. */
159	union
160	{
161	/** RTR0MEMTYPE_PAGE. */
162	struct
163	{
164	unsigned iDummy;
165	} Page;
166
167	/** RTR0MEMTYPE_LOW. */
168	struct
169	{
170	unsigned iDummy;
171	} Low;
172
173	/** RTR0MEMTYPE_CONT. */
174	struct
175	{
176	/** The physical address of the first page. */
177	RTHCPHYS Phys;
178	} Cont;
179
180	/** RTR0MEMTYPE_LOCK_USER. */
181	struct
182	{
183	/** The process that owns the locked memory.
184	* This is NIL_RTR0PROCESS if it's kernel memory. */
185	RTR0PROCESS R0Process;
186	} Lock;
187
188	/** RTR0MEMTYPE_PHYS. */
189	struct
190	{
191	/** The base address of the physical memory. */
192	RTHCPHYS PhysBase;
193	/** If set this object was created by RTR0MemPhysAlloc, otherwise it was
194	* created by RTR0MemPhysEnter. */
195	bool fAllocated;
196	/** See RTMEM_CACHE_POLICY_XXX constants */
197	uint32_t uCachePolicy;
198	} Phys;
199
200	/** RTR0MEMTYPE_PHYS_NC. */
201	struct
202	{
203	unsigned iDummy;
204	} PhysNC;
205
206	/** RTR0MEMOBJTYPE_RES_VIRT */
207	struct
208	{
209	/** The process that owns the reserved memory.
210	* This is NIL_RTR0PROCESS if it's kernel memory. */
211	RTR0PROCESS R0Process;
212	} ResVirt;
213
214	/** RTR0MEMOBJTYPE_MAPPING */
215	struct
216	{
217	/** The process that owns the reserved memory.
218	* This is NIL_RTR0PROCESS if it's kernel memory. */
219	RTR0PROCESS R0Process;
220	} Mapping;
221	} u;
222
223	#if defined(DEBUG)
224	/** Allocation tag string. */
225	const char *pszTag;
226	#endif
227	} RTR0MEMOBJINTERNAL;
228
229
230	/**
231	* Checks if this is mapping or not.
232	*
233	* @returns true if it's a mapping, otherwise false.
234	* @param pMem The ring-0 memory object handle.
235	* @see RTR0MemObjIsMapping
236	*/
237	DECLINLINE(bool) rtR0MemObjIsMapping(PRTR0MEMOBJINTERNAL pMem)
238	{
239	switch (pMem->enmType)
240	{
241	case RTR0MEMOBJTYPE_MAPPING:
242	return true;
243
244	default:
245	return false;
246	}
247	}
248
249
250	/**
251	* Checks page level protection can be changed on this object.
252	*
253	* @returns true / false.
254	* @param pMem The ring-0 memory object handle.
255	*/
256	DECLINLINE(bool) rtR0MemObjIsProtectable(PRTR0MEMOBJINTERNAL pMem)
257	{
258	switch (pMem->enmType)
259	{
260	case RTR0MEMOBJTYPE_MAPPING:
261	case RTR0MEMOBJTYPE_PAGE:
262	case RTR0MEMOBJTYPE_LOW:
263	case RTR0MEMOBJTYPE_CONT:
264	return true;
265
266	default:
267	return false;
268	}
269	}
270
271
272	/**
273	* Checks if RTR0MEMOBJ::pv is a ring-3 pointer or not.
274	*
275	* @returns true if it's a object with a ring-3 address, otherwise false.
276	* @param pMem The ring-0 memory object handle.
277	*/
278	DECLINLINE(bool) rtR0MemObjIsRing3(PRTR0MEMOBJINTERNAL pMem)
279	{
280	switch (pMem->enmType)
281	{
282	case RTR0MEMOBJTYPE_RES_VIRT:
283	return pMem->u.ResVirt.R0Process != NIL_RTR0PROCESS;
284	case RTR0MEMOBJTYPE_LOCK:
285	return pMem->u.Lock.R0Process != NIL_RTR0PROCESS;
286	case RTR0MEMOBJTYPE_MAPPING:
287	return pMem->u.Mapping.R0Process != NIL_RTR0PROCESS;
288	default:
289	return false;
290	}
291	}
292
293
294	/**
295	* Frees the memory object (but not the handle).
296	* Any OS specific handle resources will be freed by this call.
297	*
298	* @returns IPRT status code. On failure it is assumed that the object remains valid.
299	* @param pMem The ring-0 memory object handle to the memory which should be freed.
300	*/
301	DECLHIDDEN(int) rtR0MemObjNativeFree(PRTR0MEMOBJINTERNAL pMem);
302
303	/**
304	* Allocates page aligned virtual kernel memory.
305	*
306	* The memory is taken from a non paged (= fixed physical memory backing) pool.
307	*
308	* @returns IPRT status code.
309	* @param ppMem Where to store the ring-0 memory object handle.
310	* @param cb Number of bytes to allocate, page aligned.
311	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
312	* @param pszTag Allocation tag used for statistics and such.
313	*/
314	DECLHIDDEN(int) rtR0MemObjNativeAllocPage(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable, const char *pszTag);
315
316	/**
317	* Worker for RTR0MemObjAllocLargeTag.
318	*
319	* @returns IPRT status code.
320	* @param ppMem Where to store the ring-0 memory object handle.
321	* @param cb Number of bytes to allocate, aligned to @a
322	* cbLargePage.
323	* @param cbLargePage The large page size.
324	* @param fFlags RTMEMOBJ_ALLOC_LARGE_F_XXX, validated.
325	* @param pszTag The allocation tag.
326	*/
327	DECLHIDDEN(int) rtR0MemObjNativeAllocLarge(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, size_t cbLargePage, uint32_t fFlags,
328	const char *pszTag);
329
330	/**
331	* Allocates page aligned virtual kernel memory with physical backing below 4GB.
332	*
333	* The physical memory backing the allocation is fixed.
334	*
335	* @returns IPRT status code.
336	* @param ppMem Where to store the ring-0 memory object handle.
337	* @param cb Number of bytes to allocate, page aligned.
338	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
339	* @param pszTag Allocation tag used for statistics and such.
340	*/
341	DECLHIDDEN(int) rtR0MemObjNativeAllocLow(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable, const char *pszTag);
342
343	/**
344	* Allocates page aligned virtual kernel memory with contiguous physical backing below 4GB.
345	*
346	* The physical memory backing the allocation is fixed.
347	*
348	* @returns IPRT status code.
349	* @param ppMem Where to store the ring-0 memory object handle.
350	* @param cb Number of bytes to allocate, page aligned.
351	* @param fExecutable Flag indicating whether it should be permitted to executed code in the memory object.
352	* @param pszTag Allocation tag used for statistics and such.
353	*/
354	DECLHIDDEN(int) rtR0MemObjNativeAllocCont(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, bool fExecutable, const char *pszTag);
355
356	/**
357	* Locks a range of user virtual memory.
358	*
359	* @returns IPRT status code.
360	* @param ppMem Where to store the ring-0 memory object handle.
361	* @param R3Ptr User virtual address, page aligned.
362	* @param cb Number of bytes to lock, page aligned.
363	* @param fAccess The desired access, a combination of RTMEM_PROT_READ
364	* and RTMEM_PROT_WRITE.
365	* @param R0Process The process to lock pages in.
366	* @param pszTag Allocation tag used for statistics and such.
367	*/
368	DECLHIDDEN(int) rtR0MemObjNativeLockUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3Ptr, size_t cb, uint32_t fAccess,
369	RTR0PROCESS R0Process, const char *pszTag);
370
371	/**
372	* Locks a range of kernel virtual memory.
373	*
374	* @returns IPRT status code.
375	* @param ppMem Where to store the ring-0 memory object handle.
376	* @param pv Kernel 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 pszTag Allocation tag used for statistics and such.
381	*/
382	DECLHIDDEN(int) rtR0MemObjNativeLockKernel(PPRTR0MEMOBJINTERNAL ppMem, void pv, size_t cb, uint32_t fAccess, const char pszTag);
383
384	/**
385	* Allocates contiguous page aligned physical memory without (necessarily) any
386	* kernel mapping.
387	*
388	* @returns IPRT status code.
389	* @param ppMem Where to store the ring-0 memory object handle.
390	* @param cb Number of bytes to allocate, page aligned.
391	* @param PhysHighest The highest permitable address (inclusive).
392	* NIL_RTHCPHYS if any address is acceptable.
393	* @param uAlignment The alignment of the reserved memory.
394	* Supported values are PAGE_SIZE, _2M, _4M and _1G.
395	* @param pszTag Allocation tag used for statistics and such.
396	*/
397	DECLHIDDEN(int) rtR0MemObjNativeAllocPhys(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest, size_t uAlignment,
398	const char *pszTag);
399
400	/**
401	* Allocates non-contiguous page aligned physical memory without (necessarily) any kernel mapping.
402	*
403	* @returns IPRT status code.
404	* @retval VERR_NOT_SUPPORTED if it's not possible to allocated unmapped
405	* physical memory on this platform.
406	* @param ppMem Where to store the ring-0 memory object handle.
407	* @param cb Number of bytes to allocate, page aligned.
408	* @param PhysHighest The highest permitable address (inclusive).
409	* NIL_RTHCPHYS if any address is acceptable.
410	* @param pszTag Allocation tag used for statistics and such.
411	*/
412	DECLHIDDEN(int) rtR0MemObjNativeAllocPhysNC(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, RTHCPHYS PhysHighest, const char *pszTag);
413
414	/**
415	* Creates a page aligned, contiguous, physical memory object.
416	*
417	* @returns IPRT status code.
418	* @param ppMem Where to store the ring-0 memory object handle.
419	* @param Phys The physical address to start at, page aligned.
420	* @param cb The size of the object in bytes, page aligned.
421	* @param uCachePolicy One of the RTMEM_CACHE_XXX modes.
422	* @param pszTag Allocation tag used for statistics and such.
423	*/
424	DECLHIDDEN(int) rtR0MemObjNativeEnterPhys(PPRTR0MEMOBJINTERNAL ppMem, RTHCPHYS Phys, size_t cb, uint32_t uCachePolicy,
425	const char *pszTag);
426
427	/**
428	* Reserves kernel virtual address space.
429	*
430	* @returns IPRT status code.
431	* Return VERR_NOT_SUPPORTED to indicate that the user should employ fallback strategies.
432	* @param ppMem Where to store the ring-0 memory object handle.
433	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
434	* @param cb The number of bytes to reserve, page aligned.
435	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
436	* @param pszTag Allocation tag used for statistics and such.
437	*/
438	DECLHIDDEN(int) rtR0MemObjNativeReserveKernel(PPRTR0MEMOBJINTERNAL ppMem, void *pvFixed, size_t cb, size_t uAlignment,
439	const char *pszTag);
440
441	/**
442	* Reserves user virtual address space in the current process.
443	*
444	* @returns IPRT status code.
445	* @param ppMem Where to store the ring-0 memory object handle.
446	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
447	* @param cb The number of bytes to reserve, page aligned.
448	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
449	* @param R0Process The process to reserve the memory in.
450	* @param pszTag Allocation tag used for statistics and such.
451	*/
452	DECLHIDDEN(int) rtR0MemObjNativeReserveUser(PPRTR0MEMOBJINTERNAL ppMem, RTR3PTR R3PtrFixed, size_t cb, size_t uAlignment,
453	RTR0PROCESS R0Process, const char *pszTag);
454
455	/**
456	* Maps a memory object into user virtual address space in the current process.
457	*
458	* @returns IPRT status code.
459	* @retval VERR_NOT_SUPPORTED see RTR0MemObjMapKernelEx.
460	*
461	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
462	* @param pMemToMap The object to be map.
463	* @param pvFixed Requested address. (void *)-1 means any address. This matches uAlignment if specified.
464	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
465	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
466	* @param offSub Where in the object to start mapping. If non-zero
467	* the value must be page aligned and cbSub must be
468	* non-zero as well.
469	* @param cbSub The size of the part of the object to be mapped. If
470	* zero the entire object is mapped. The value must be
471	* page aligned.
472	* @param pszTag Allocation tag used for statistics and such.
473	*/
474	DECLHIDDEN(int) rtR0MemObjNativeMapKernel(PPRTR0MEMOBJINTERNAL ppMem, RTR0MEMOBJ pMemToMap, void *pvFixed, size_t uAlignment,
475	unsigned fProt, size_t offSub, size_t cbSub, const char *pszTag);
476
477	/**
478	* Maps a memory object into user virtual address space in the current process.
479	*
480	* @returns IPRT status code.
481	* @param ppMem Where to store the ring-0 memory object handle of the mapping object.
482	* @param pMemToMap The object to be map.
483	* @param R3PtrFixed Requested address. (RTR3PTR)-1 means any address. This matches uAlignment if specified.
484	* @param uAlignment The alignment of the reserved memory; PAGE_SIZE, _2M or _4M.
485	* @param fProt Combination of RTMEM_PROT_* flags (except RTMEM_PROT_NONE).
486	* @param R0Process The process to map the memory into.
487	* @param offSub Where in the object to start mapping. If non-zero
488	* the value must be page aligned and cbSub must be
489	* non-zero as well.
490	* @param cbSub The size of the part of the object to be mapped. If
491	* zero the entire object is mapped. The value must be
492	* page aligned.
493	* @param pszTag Allocation tag used for statistics and such.
494	*/
495	DECLHIDDEN(int) rtR0MemObjNativeMapUser(PPRTR0MEMOBJINTERNAL ppMem, PRTR0MEMOBJINTERNAL pMemToMap, RTR3PTR R3PtrFixed,
496	size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process, size_t offSub, size_t cbSub,
497	const char *pszTag);
498
499	/**
500	* Change the page level protection of one or more pages in a memory object.
501	*
502	* @returns IPRT status code.
503	* @retval VERR_NOT_SUPPORTED see RTR0MemObjProtect.
504	*
505	* @param pMem The memory object.
506	* @param offSub Offset into the memory object. Page aligned.
507	* @param cbSub Number of bytes to change the protection of. Page
508	* aligned.
509	* @param fProt Combination of RTMEM_PROT_* flags.
510	*/
511	DECLHIDDEN(int) rtR0MemObjNativeProtect(PRTR0MEMOBJINTERNAL pMem, size_t offSub, size_t cbSub, uint32_t fProt);
512
513	/**
514	* Get the physical address of an page in the memory object.
515	*
516	* @returns The physical address.
517	* @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
518	* @returns NIL_RTHCPHYS if the iPage is out of range.
519	* @returns NIL_RTHCPHYS if the object handle isn't valid.
520	* @param pMem The ring-0 memory object handle.
521	* @param iPage The page number within the object (valid).
522	*/
523	DECLHIDDEN(RTHCPHYS) rtR0MemObjNativeGetPagePhysAddr(PRTR0MEMOBJINTERNAL pMem, size_t iPage);
524
525	DECLHIDDEN(PRTR0MEMOBJINTERNAL) rtR0MemObjNew(size_t cbSelf, RTR0MEMOBJTYPE enmType, void pv, size_t cb, const char pszTag);
526	DECLHIDDEN(void) rtR0MemObjDelete(PRTR0MEMOBJINTERNAL pMem);
527	DECLHIDDEN(int) rtR0MemObjFallbackAllocLarge(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, size_t cbLargePage, uint32_t fFlags,
528	const char *pszTag);
529
530	/** @} */
531
532	RT_C_DECLS_END
533
534	#endif /* !IPRT_INCLUDED_INTERNAL_memobj_h */
535

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

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

Download in other formats: