mem.h revision 677833bc953b6cb418c701facbdcf4aa18d6c44e
0N/A/** @file
2362N/A * InnoTek Portable Runtime - Memory Management and Manipulation.
0N/A */
0N/A
0N/A/*
0N/A * Copyright (C) 2006 InnoTek Systemberatung GmbH
2362N/A *
0N/A * This file is part of VirtualBox Open Source Edition (OSE), as
2362N/A * available from http://www.virtualbox.org. This file is free software;
0N/A * you can redistribute it and/or modify it under the terms of the GNU
0N/A * General Public License as published by the Free Software Foundation,
0N/A * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
0N/A * distribution. VirtualBox OSE is distributed in the hope that it will
0N/A * be useful, but WITHOUT ANY WARRANTY of any kind.
0N/A *
0N/A * If you received this file as part of a commercial VirtualBox
0N/A * distribution, then only the terms of your commercial VirtualBox
0N/A * license agreement apply instead of the previous paragraph.
0N/A */
0N/A
2362N/A#ifndef __iprt_mem_h__
2362N/A#define __iprt_mem_h__
2362N/A
0N/A
0N/A#include <iprt/cdefs.h>
0N/A#include <iprt/types.h>
0N/A
0N/A#ifdef IN_GC
0N/A# error "There are no RTMem APIs available Guest Context!"
0N/A#endif
0N/A
0N/A__BEGIN_DECLS
0N/A
0N/A/** @defgroup grp_rt_mem RTMem - Memory Management and Manipulation
0N/A * @ingroup grp_rt
0N/A * @{
0N/A */
0N/A
0N/A/** @def RTMEM_ALIGNMENT
0N/A * The alignment of the memory blocks returned by RTMemAlloc(), RTMemAllocZ(),
0N/A * RTMemRealloc(), RTMemTmpAlloc() and RTMemTmpAllocZ() for allocations greater
0N/A * than RTMEM_ALIGNMENT.
0N/A */
0N/A#ifdef __L4ENV__
0N/A# define RTMEM_ALIGNMENT 4 /**< @todo Michael, can you check that this is still true with ucLibc, please. */
0N/A#else
0N/A# define RTMEM_ALIGNMENT 8
0N/A#endif
0N/A
0N/A/**
0N/A * Allocates temporary memory.
0N/A *
0N/A * Temporary memory blocks are used for not too large memory blocks which
0N/A * are believed not to stick around for too long. Using this API instead
0N/A * of RTMemAlloc() not only gives the heap manager room for optimization
0N/A * but makes the code easier to read.
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL on failure.
0N/A * @param cb Size in bytes of the memory block to allocated.
0N/A */
0N/ARTDECL(void *) RTMemTmpAlloc(size_t cb);
0N/A
0N/A/**
0N/A * Allocates zero'ed temporary memory.
0N/A *
0N/A * Same as RTMemTmpAlloc() but the memory will be zero'ed.
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL on failure.
0N/A * @param cb Size in bytes of the memory block to allocated.
0N/A */
0N/ARTDECL(void *) RTMemTmpAllocZ(size_t cb);
0N/A
0N/A/**
0N/A * Free temporary memory.
0N/A *
0N/A * @param pv Pointer to memory block.
0N/A */
0N/ARTDECL(void) RTMemTmpFree(void *pv);
0N/A
0N/A
0N/A/**
0N/A * Allocates memory.
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL on failure.
0N/A * @param cb Size in bytes of the memory block to allocated.
0N/A */
0N/ARTDECL(void *) RTMemAlloc(size_t cb);
0N/A
0N/A/**
0N/A * Allocates zero'ed memory.
0N/A *
0N/A * Instead of memset(pv, 0, sizeof()) use this when you want zero'ed
0N/A * memory. This keeps the code smaller and the heap can skip the memset
0N/A * in about 0.42% of calls :-).
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL on failure.
0N/A * @param cb Size in bytes of the memory block to allocated.
0N/A */
0N/ARTDECL(void *) RTMemAllocZ(size_t cb);
0N/A
0N/A/**
0N/A * Duplicates a chunk of memory into a new heap block.
0N/A *
0N/A * @returns New heap block with the duplicate data.
0N/A * @returns NULL if we're out of memory.
0N/A * @param pvSrc The memory to duplicate.
0N/A * @param cb The amount of memory to duplicate.
0N/A */
0N/ARTDECL(void *) RTMemDup(const void *pvSrc, size_t cb);
0N/A
0N/A/**
0N/A * Duplicates a chunk of memory into a new heap block with some
0N/A * additional zeroed memory.
0N/A *
0N/A * @returns New heap block with the duplicate data.
0N/A * @returns NULL if we're out of memory.
0N/A * @param pvSrc The memory to duplicate.
0N/A * @param cbSrc The amount of memory to duplicate.
0N/A * @param cbExtra The amount of extra memory to allocate and zero.
0N/A */
0N/ARTDECL(void *) RTMemDupEx(const void *pvSrc, size_t cbSrc, size_t cbExtra);
0N/A
0N/A/**
0N/A * Reallocates memory.
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL on failure.
0N/A * @param pvOld The memory block to reallocate.
0N/A * @param cbNew The new block size (in bytes).
0N/A */
0N/ARTDECL(void *) RTMemRealloc(void *pvOld, size_t cbNew);
0N/A
0N/A/**
0N/A * Free memory related to an virtual machine
0N/A *
0N/A * @param pv Pointer to memory block.
0N/A */
0N/ARTDECL(void) RTMemFree(void *pv);
0N/A
0N/A/**
0N/A * Allocates memory which may contain code.
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL on failure.
0N/A * @param cb Size in bytes of the memory block to allocate.
0N/A */
0N/ARTDECL(void *) RTMemExecAlloc(size_t cb);
0N/A
0N/A/**
0N/A * Free executable/read/write memory allocated by RTMemExecAlloc().
0N/A *
0N/A * @param pv Pointer to memory block.
0N/A */
0N/ARTDECL(void) RTMemExecFree(void *pv);
0N/A
0N/A/**
0N/A * Allocate page aligned memory.
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL if we're out of memory.
0N/A * @param cb Size of the memory block. Will be rounded up to page size.
0N/A */
0N/ARTDECL(void *) RTMemPageAlloc(size_t cb);
0N/A
0N/A/**
0N/A * Allocate zero'ed page aligned memory.
0N/A *
0N/A * @returns Pointer to the allocated memory.
0N/A * @returns NULL if we're out of memory.
0N/A * @param cb Size of the memory block. Will be rounded up to page size.
0N/A */
0N/ARTDECL(void *) RTMemPageAllocZ(size_t cb);
0N/A
0N/A/**
0N/A * Free a memory block allocated with RTMemPageAlloc() or RTMemPageAllocZ().
0N/A *
0N/A * @param pv Pointer to the block as it was returned by the allocation function.
0N/A * NULL will be ignored.
0N/A */
RTDECL(void) RTMemPageFree(void *pv);
/** Page level protection flags for RTMemProtect().
* @{
*/
/** Read access. */
#define RTMEM_PROT_NONE 0
/** Read access. */
#define RTMEM_PROT_READ 1
/** Write access. */
#define RTMEM_PROT_WRITE 2
/** Execute access. */
#define RTMEM_PROT_EXEC 4
/** @} */
/**
* Change the page level protection of a memory region.
*
* @returns iprt status code.
* @param pv Start of the region. Will be rounded down to nearest page boundary.
* @param cb Size of the region. Will be rounded up to the nearest page boundary.
* @param fProtect The new protection, a combination of the RTMEM_PROT_* defines.
*/
RTDECL(int) RTMemProtect(void *pv, size_t cb, unsigned fProtect);
#ifdef IN_RING0
/**
* Allocates physical contiguous memory (below 4GB).
* The allocation is page aligned and the content is undefined.
*
* @returns Pointer to the memory block. This is page aligned.
* @param pPhys Where to store the physical address.
* @param cb The allocation size in bytes. This is always
* rounded up to PAGE_SIZE.
*/
RTR0DECL(void *) RTMemContAlloc(PRTCCPHYS pPhys, size_t cb);
/**
* Frees memory allocated ysing RTMemContAlloc().
*
* @param pv Pointer to return from RTMemContAlloc().
* @param cb The cb parameter passed to RTMemContAlloc().
*/
RTR0DECL(void) RTMemContFree(void *pv, size_t cb);
#endif
/** @name Electrical Fence Version of some APIs.
* @{
*/
/**
* Same as RTMemTmpAlloc() except that it's fenced.
*
* @returns Pointer to the allocated memory.
* @returns NULL on failure.
* @param cb Size in bytes of the memory block to allocate.
*/
RTDECL(void *) RTMemEfTmpAlloc(size_t cb);
/**
* Same as RTMemTmpAllocZ() except that it's fenced.
*
* @returns Pointer to the allocated memory.
* @returns NULL on failure.
* @param cb Size in bytes of the memory block to allocate.
*/
RTDECL(void *) RTMemEfTmpAllocZ(size_t cb);
/**
* Same as RTMemTmpFree() except that it's for fenced memory.
*
* @param pv Pointer to memory block.
*/
RTDECL(void) RTMemEfTmpFree(void *pv);
/**
* Same as RTMemAlloc() except that it's fenced.
*
* @returns Pointer to the allocated memory. Free with RTMemEfFree().
* @returns NULL on failure.
* @param cb Size in bytes of the memory block to allocate.
*/
RTDECL(void *) RTMemEfAlloc(size_t cb);
/**
* Same as RTMemAllocZ() except that it's fenced.
*
* @returns Pointer to the allocated memory.
* @returns NULL on failure.
* @param cb Size in bytes of the memory block to allocate.
*/
RTDECL(void *) RTMemEfAllocZ(size_t cb);
/**
* Same as RTMemRealloc() except that it's fenced.
*
* @returns Pointer to the allocated memory.
* @returns NULL on failure.
* @param pvOld The memory block to reallocate.
* @param cbNew The new block size (in bytes).
*/
RTDECL(void *) RTMemEfRealloc(void *pvOld, size_t cbNew);
/**
* Free memory allocated by any of the RTMemEf* allocators.
*
* @param pv Pointer to memory block.
*/
RTDECL(void) RTMemEfFree(void *pv);
/**
* Same as RTMemDup() except that it's fenced.
*
* @returns New heap block with the duplicate data.
* @returns NULL if we're out of memory.
* @param pvSrc The memory to duplicate.
* @param cb The amount of memory to duplicate.
*/
RTDECL(void *) RTMemEfDup(const void *pvSrc, size_t cb);
/**
* Same as RTMemEfDupEx except that it's fenced.
*
* @returns New heap block with the duplicate data.
* @returns NULL if we're out of memory.
* @param pvSrc The memory to duplicate.
* @param cbSrc The amount of memory to duplicate.
* @param cbExtra The amount of extra memory to allocate and zero.
*/
RTDECL(void *) RTMemEfDupEx(const void *pvSrc, size_t cbSrc, size_t cbExtra);
/** @def RTMEM_WRAP_TO_EF_APIS
* Define RTMEM_WRAP_TO_EF_APIS to wrap RTMem APIs to RTMemEf APIs.
*/
#ifdef RTMEM_WRAP_TO_EF_APIS
# define RTMemTmpAlloc RTMemEfTmpAlloc
# define RTMemTmpAllocZ RTMemEfTmpAllocZ
# define RTMemTmpFree RTMemEfTmpFree
# define RTMemAlloc RTMemEfAlloc
# define RTMemAllocZ RTMemEfAllocZ
# define RTMemRealloc RTMemEfRealloc
# define RTMemFree RTMemEfFree
# define RTMemDup RTMemEfDup
# define RTMemDupEx RTMemEfDupEx
#endif
#ifdef __DOXYGEN__
# define RTMEM_WRAP_TO_EF_APIS
#endif
/** @} */
/** @} */
__END_DECLS
#endif