/** * @file rtems/score/protectedheap.h * * This include file contains the information pertaining to the * Protected Heap Handler. * * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.com/license/LICENSE. * * $Id$ */ #ifndef _RTEMS_SCORE_PROTECTED_HEAP_H #define _RTEMS_SCORE_PROTECTED_HEAP_H #include #include /** * @defgroup ScoreProtHeap Protected Heap Handler * * This handler encapsulates functionality which provides the foundation * Protected Heap services. * * It is a simple wrapper for the help with the addition of the * allocation mutex being used for protection. */ /**@{*/ #ifdef __cplusplus extern "C" { #endif /** * This routine initializes @a the_heap record to manage the * contiguous heap of @a size bytes which starts at @a starting_address. * Blocks of memory are allocated from the heap in multiples of * @a page_size byte units. If @a page_size is 0 or is not multiple of * CPU_ALIGNMENT, it's aligned up to the nearest CPU_ALIGNMENT boundary. * * @param[in] the_heap is the heap to operate upon * @param[in] starting_address is the starting address of the memory for * the heap * @param[in] size is the size in bytes of the memory area for the heap * @param[in] page_size is the size in bytes of the allocation unit * * @return This method returns the maximum memory available. If * unsuccessful, 0 will be returned. */ static inline uint32_t _Protected_heap_Initialize( Heap_Control *the_heap, void *starting_address, size_t size, uint32_t page_size ) { return _Heap_Initialize( the_heap, starting_address, size, page_size ); } /** * This routine grows @a the_heap memory area using the size bytes which * begin at @a starting_address. * * @param[in] the_heap is the heap to operate upon * @param[in] starting_address is the starting address of the memory * to add to the heap * @param[in] size is the size in bytes of the memory area to add * @return a status indicating success or the reason for failure */ boolean _Protected_heap_Extend( Heap_Control *the_heap, void *starting_address, size_t size ); /** * This function attempts to allocate a block of @a size bytes from * @a the_heap. If insufficient memory is free in @a the_heap to allocate * a block of the requested size, then NULL is returned. * * @param[in] the_heap is the heap to operate upon * @param[in] size is the amount of memory to allocate in bytes * @return NULL if unsuccessful and a pointer to the block if successful */ void *_Protected_heap_Allocate( Heap_Control *the_heap, size_t size ); /** * This function attempts to allocate a memory block of @a size bytes from * @a the_heap so that the start of the user memory is aligned on the * @a alignment boundary. If @a alignment is 0, it is set to CPU_ALIGNMENT. * Any other value of @a alignment is taken "as is", i.e., even odd * alignments are possible. * Returns pointer to the start of the memory block if success, NULL if * failure. * * @param[in] the_heap is the heap to operate upon * @param[in] size is the amount of memory to allocate in bytes * @param[in] alignment the required alignment * @return NULL if unsuccessful and a pointer to the block if successful */ void *_Protected_heap_Allocate_aligned( Heap_Control *the_heap, size_t size, uint32_t alignment ); /** * This function sets @a *size to the size of the block of user memory * which begins at @a starting_address. The size returned in @a *size could * be greater than the size requested for allocation. * Returns TRUE if the @a starting_address is in the heap, and FALSE * otherwise. * * @param[in] the_heap is the heap to operate upon * @param[in] starting_address is the starting address of the user block * to obtain the size of * @param[in] size points to a user area to return the size in * @return TRUE if successfully able to determine the size, FALSE otherwise * @return *size filled in with the size of the user area for this block */ boolean _Protected_heap_Get_block_size( Heap_Control *the_heap, void *starting_address, size_t *size ); /** * This function tries to resize in place the block that is pointed to by the * @a starting_address to the new @a size. * * @param[in] the_heap is the heap to operate upon * @param[in] starting_address is the starting address of the user block * to be resized * @param[in] size is the new size * * @return TRUE if successfully able to resize the block. * FALSE if the block can't be resized in place. */ boolean _Protected_heap_Resize_block( Heap_Control *the_heap, void *starting_address, size_t size ); /** * This routine returns the block of memory which begins * at @a starting_address to @a the_heap. Any coalescing which is * possible with the freeing of this routine is performed. * * @param[in] the_heap is the heap to operate upon * @param[in] start_address is the starting address of the user block * to free * @return TRUE if successfully freed, FALSE otherwise */ boolean _Protected_heap_Free( Heap_Control *the_heap, void *start_address ); /** * This routine walks the heap to verify its integrity. * * @param[in] the_heap is the heap to operate upon * @param[in] source is a user specified integer which may be used to * indicate where in the application this was invoked from * @param[in] do_dump is set to TRUE if errors should be printed * @return TRUE if the test passed fine, FALSE otherwise. */ boolean _Protected_heap_Walk( Heap_Control *the_heap, int source, boolean do_dump ); /** * This routine walks the heap and tots up the free and allocated * sizes. * * @param[in] the_heap pointer to heap header * @param[in] the_info pointer to a status information area */ void _Protected_heap_Get_information( Heap_Control *the_heap, Heap_Information_block *the_info ); /** * This heap routine returns information about the free blocks * in the specified heap. * * @param[in] the_heap pointer to heap header. * @param[in] info pointer to the free block information. * * @return free block information filled in. */ void _Protected_heap_Get_free_information( Heap_Control *the_heap, Heap_Information *info ); #ifdef __cplusplus } #endif /**@}*/ #endif /* end of include file */