VirtualBox

source: vbox/trunk/include/iprt/mem.h@ 2247

Last change on this file since 2247 was 331, checked in by vboxsync, 18 years ago

Bool and AMD64 hacking.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.2 KB
Line 
1/** @file
2 * InnoTek Portable Runtime - Memory Management and Manipulation.
3 */
4
5/*
6 * Copyright (C) 2006 InnoTek Systemberatung GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * If you received this file as part of a commercial VirtualBox
17 * distribution, then only the terms of your commercial VirtualBox
18 * license agreement apply instead of the previous paragraph.
19 */
20
21#ifndef __iprt_mem_h__
22#define __iprt_mem_h__
23
24
25#include <iprt/cdefs.h>
26#include <iprt/types.h>
27
28#ifdef IN_GC
29# error "There are no RTMem APIs available Guest Context!"
30#endif
31
32__BEGIN_DECLS
33
34/** @defgroup grp_rt_mem RTMem - Memory Management and Manipulation
35 * @ingroup grp_rt
36 * @{
37 */
38
39/** @def RTMEM_ALIGNMENT
40 * The alignment of the memory blocks returned by RTMemAlloc(), RTMemAllocZ(),
41 * RTMemRealloc(), RTMemTmpAlloc() and RTMemTmpAllocZ() for allocations greater
42 * than RTMEM_ALIGNMENT.
43 */
44#ifdef __L4ENV__
45# define RTMEM_ALIGNMENT 4 /**< @todo Michael, can you check that this is still true with ucLibc, please. */
46#else
47# define RTMEM_ALIGNMENT 8
48#endif
49
50/**
51 * Allocates temporary memory.
52 *
53 * Temporary memory blocks are used for not too large memory blocks which
54 * are believed not to stick around for too long. Using this API instead
55 * of RTMemAlloc() not only gives the heap manager room for optimization
56 * but makes the code easier to read.
57 *
58 * @returns Pointer to the allocated memory.
59 * @returns NULL on failure.
60 * @param cb Size in bytes of the memory block to allocated.
61 */
62RTDECL(void *) RTMemTmpAlloc(size_t cb);
63
64/**
65 * Allocates zero'ed temporary memory.
66 *
67 * Same as RTMemTmpAlloc() but the memory will be zero'ed.
68 *
69 * @returns Pointer to the allocated memory.
70 * @returns NULL on failure.
71 * @param cb Size in bytes of the memory block to allocated.
72 */
73RTDECL(void *) RTMemTmpAllocZ(size_t cb);
74
75/**
76 * Free temporary memory.
77 *
78 * @param pv Pointer to memory block.
79 */
80RTDECL(void) RTMemTmpFree(void *pv);
81
82
83/**
84 * Allocates memory.
85 *
86 * @returns Pointer to the allocated memory.
87 * @returns NULL on failure.
88 * @param cb Size in bytes of the memory block to allocated.
89 */
90RTDECL(void *) RTMemAlloc(size_t cb);
91
92/**
93 * Allocates zero'ed memory.
94 *
95 * Instead of memset(pv, 0, sizeof()) use this when you want zero'ed
96 * memory. This keeps the code smaller and the heap can skip the memset
97 * in about 0.42% of calls :-).
98 *
99 * @returns Pointer to the allocated memory.
100 * @returns NULL on failure.
101 * @param cb Size in bytes of the memory block to allocated.
102 */
103RTDECL(void *) RTMemAllocZ(size_t cb);
104
105/**
106 * Duplicates a chunk of memory into a new heap block.
107 *
108 * @returns New heap block with the duplicate data.
109 * @returns NULL if we're out of memory.
110 * @param pvSrc The memory to duplicate.
111 * @param cb The amount of memory to duplicate.
112 */
113RTDECL(void *) RTMemDup(const void *pvSrc, size_t cb);
114
115/**
116 * Duplicates a chunk of memory into a new heap block with some
117 * additional zeroed memory.
118 *
119 * @returns New heap block with the duplicate data.
120 * @returns NULL if we're out of memory.
121 * @param pvSrc The memory to duplicate.
122 * @param cbSrc The amount of memory to duplicate.
123 * @param cbExtra The amount of extra memory to allocate and zero.
124 */
125RTDECL(void *) RTMemDupEx(const void *pvSrc, size_t cbSrc, size_t cbExtra);
126
127/**
128 * Reallocates memory.
129 *
130 * @returns Pointer to the allocated memory.
131 * @returns NULL on failure.
132 * @param pvOld The memory block to reallocate.
133 * @param cbNew The new block size (in bytes).
134 */
135RTDECL(void *) RTMemRealloc(void *pvOld, size_t cbNew);
136
137/**
138 * Free memory related to an virtual machine
139 *
140 * @param pv Pointer to memory block.
141 */
142RTDECL(void) RTMemFree(void *pv);
143
144/**
145 * Allocates memory which may contain code.
146 *
147 * @returns Pointer to the allocated memory.
148 * @returns NULL on failure.
149 * @param cb Size in bytes of the memory block to allocate.
150 */
151RTDECL(void *) RTMemExecAlloc(size_t cb);
152
153/**
154 * Free executable/read/write memory allocated by RTMemExecAlloc().
155 *
156 * @param pv Pointer to memory block.
157 */
158RTDECL(void) RTMemExecFree(void *pv);
159
160#if defined(IN_RING0) && defined(__AMD64__) && defined(__LINUX__)
161/**
162 * Donate read+write+execute memory to the exec heap.
163 *
164 * This API is specific to AMD64 and Linux/GNU. A kernel module that desires to
165 * use RTMemExecAlloc on AMD64 Linux/GNU will have to donate some statically
166 * allocated memory in the module if it wishes for GCC generated code to work.
167 * GCC can only generate modules that work in the address range ~2GB to ~0
168 * currently.
169 *
170 * The API only accept one single donation.
171 *
172 * @returns IPRT status code.
173 * @param pvMemory Pointer to the memory block.
174 * @param cb The size of the memory block.
175 */
176RTR0DECL(int) RTR0MemExecDonate(void *pvMemory, size_t cb);
177#endif /* R0+AMD64+LINUX */
178
179/**
180 * Allocate page aligned memory.
181 *
182 * @returns Pointer to the allocated memory.
183 * @returns NULL if we're out of memory.
184 * @param cb Size of the memory block. Will be rounded up to page size.
185 */
186RTDECL(void *) RTMemPageAlloc(size_t cb);
187
188/**
189 * Allocate zero'ed page aligned memory.
190 *
191 * @returns Pointer to the allocated memory.
192 * @returns NULL if we're out of memory.
193 * @param cb Size of the memory block. Will be rounded up to page size.
194 */
195RTDECL(void *) RTMemPageAllocZ(size_t cb);
196
197/**
198 * Free a memory block allocated with RTMemPageAlloc() or RTMemPageAllocZ().
199 *
200 * @param pv Pointer to the block as it was returned by the allocation function.
201 * NULL will be ignored.
202 */
203RTDECL(void) RTMemPageFree(void *pv);
204
205/** Page level protection flags for RTMemProtect().
206 * @{
207 */
208/** Read access. */
209#define RTMEM_PROT_NONE 0
210/** Read access. */
211#define RTMEM_PROT_READ 1
212/** Write access. */
213#define RTMEM_PROT_WRITE 2
214/** Execute access. */
215#define RTMEM_PROT_EXEC 4
216/** @} */
217
218/**
219 * Change the page level protection of a memory region.
220 *
221 * @returns iprt status code.
222 * @param pv Start of the region. Will be rounded down to nearest page boundary.
223 * @param cb Size of the region. Will be rounded up to the nearest page boundary.
224 * @param fProtect The new protection, a combination of the RTMEM_PROT_* defines.
225 */
226RTDECL(int) RTMemProtect(void *pv, size_t cb, unsigned fProtect);
227
228
229#ifdef IN_RING0
230
231/**
232 * Allocates physical contiguous memory (below 4GB).
233 * The allocation is page aligned and the content is undefined.
234 *
235 * @returns Pointer to the memory block. This is page aligned.
236 * @param pPhys Where to store the physical address.
237 * @param cb The allocation size in bytes. This is always
238 * rounded up to PAGE_SIZE.
239 */
240RTR0DECL(void *) RTMemContAlloc(PRTCCPHYS pPhys, size_t cb);
241
242/**
243 * Frees memory allocated ysing RTMemContAlloc().
244 *
245 * @param pv Pointer to return from RTMemContAlloc().
246 * @param cb The cb parameter passed to RTMemContAlloc().
247 */
248RTR0DECL(void) RTMemContFree(void *pv, size_t cb);
249
250#endif
251
252
253/** @name Electrical Fence Version of some APIs.
254 * @{
255 */
256
257/**
258 * Same as RTMemTmpAlloc() except that it's fenced.
259 *
260 * @returns Pointer to the allocated memory.
261 * @returns NULL on failure.
262 * @param cb Size in bytes of the memory block to allocate.
263 */
264RTDECL(void *) RTMemEfTmpAlloc(size_t cb);
265
266/**
267 * Same as RTMemTmpAllocZ() except that it's fenced.
268 *
269 * @returns Pointer to the allocated memory.
270 * @returns NULL on failure.
271 * @param cb Size in bytes of the memory block to allocate.
272 */
273RTDECL(void *) RTMemEfTmpAllocZ(size_t cb);
274
275/**
276 * Same as RTMemTmpFree() except that it's for fenced memory.
277 *
278 * @param pv Pointer to memory block.
279 */
280RTDECL(void) RTMemEfTmpFree(void *pv);
281
282/**
283 * Same as RTMemAlloc() except that it's fenced.
284 *
285 * @returns Pointer to the allocated memory. Free with RTMemEfFree().
286 * @returns NULL on failure.
287 * @param cb Size in bytes of the memory block to allocate.
288 */
289RTDECL(void *) RTMemEfAlloc(size_t cb);
290
291/**
292 * Same as RTMemAllocZ() except that it's fenced.
293 *
294 * @returns Pointer to the allocated memory.
295 * @returns NULL on failure.
296 * @param cb Size in bytes of the memory block to allocate.
297 */
298RTDECL(void *) RTMemEfAllocZ(size_t cb);
299
300/**
301 * Same as RTMemRealloc() except that it's fenced.
302 *
303 * @returns Pointer to the allocated memory.
304 * @returns NULL on failure.
305 * @param pvOld The memory block to reallocate.
306 * @param cbNew The new block size (in bytes).
307 */
308RTDECL(void *) RTMemEfRealloc(void *pvOld, size_t cbNew);
309
310/**
311 * Free memory allocated by any of the RTMemEf* allocators.
312 *
313 * @param pv Pointer to memory block.
314 */
315RTDECL(void) RTMemEfFree(void *pv);
316
317/**
318 * Same as RTMemDup() except that it's fenced.
319 *
320 * @returns New heap block with the duplicate data.
321 * @returns NULL if we're out of memory.
322 * @param pvSrc The memory to duplicate.
323 * @param cb The amount of memory to duplicate.
324 */
325RTDECL(void *) RTMemEfDup(const void *pvSrc, size_t cb);
326
327/**
328 * Same as RTMemEfDupEx except that it's fenced.
329 *
330 * @returns New heap block with the duplicate data.
331 * @returns NULL if we're out of memory.
332 * @param pvSrc The memory to duplicate.
333 * @param cbSrc The amount of memory to duplicate.
334 * @param cbExtra The amount of extra memory to allocate and zero.
335 */
336RTDECL(void *) RTMemEfDupEx(const void *pvSrc, size_t cbSrc, size_t cbExtra);
337
338/** @def RTMEM_WRAP_TO_EF_APIS
339 * Define RTMEM_WRAP_TO_EF_APIS to wrap RTMem APIs to RTMemEf APIs.
340 */
341#ifdef RTMEM_WRAP_TO_EF_APIS
342# define RTMemTmpAlloc RTMemEfTmpAlloc
343# define RTMemTmpAllocZ RTMemEfTmpAllocZ
344# define RTMemTmpFree RTMemEfTmpFree
345# define RTMemAlloc RTMemEfAlloc
346# define RTMemAllocZ RTMemEfAllocZ
347# define RTMemRealloc RTMemEfRealloc
348# define RTMemFree RTMemEfFree
349# define RTMemDup RTMemEfDup
350# define RTMemDupEx RTMemEfDupEx
351#endif
352#ifdef __DOXYGEN__
353# define RTMEM_WRAP_TO_EF_APIS
354#endif
355
356/** @} */
357
358/** @} */
359
360__END_DECLS
361
362#endif
363
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