Detailed Description

Variable size buffer heap manager.

HeapMem manager provides functions to allocate and free storage from a heap of type HeapMem which inherits from IHeap.

In addition to allowing multiple static HeapMem instances to be created who's buffer placements and sizes are defined by their instance configuration parameters, HeapMem allows one Heap instance to be defined who's heap memory is defined by buffer start and end symbols in the linker command file. This singular Heap instance is referred to as the 'Primary Heap'.

HeapMem Gate

A HeapMem instance will use the HeapMem module Gate to protect any accesses to its list of free memory blocks. The HeapMem instance will enter and leave the module Gate when allocating blocks, freeing blocks, and retrieving statistics about the HeapMem. By default, the Gate is of type GateMutex. A different Gate can be specified using the common$.gate parameter. For example, to use a GateTask to protect HeapMem: HeapMem.common$.gate = GateTask.create(); To save on overhead, HeapMem does not create additional Gate instances on a per-instance basis; there is only one Gate instance shared across all of the HeapMem instances. Therefore, the HeapMem.common$.gateParams parameter (used for configuring per-instance Gates) is ignored. The type of Gate used should be chosen based on the type of threads (Hwi, Swi, Task, etc.) using the heap. It should also consider the non-deterministic nature of the HeapMem. A call to alloc or free will traverse a list of free blocks, so a GateHwi, for example, is likely an inappropriate Gate for HeapMem.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Params_init	Y	Y	Y	Y	Y
alloc	N**	N**	Y**	Y	N
construct	Y	Y	Y	Y	N
create	N*	N*	Y	Y	N
delete	N*	N*	Y	Y	N
destruct	Y	Y	Y	Y	N
free	N**	N**	Y**	Y	N
getExtendedStats	Y	Y	Y	Y	N
getStats	N**	N**	Y**	Y	N
isBlocking	Y	Y	Y	Y	N
restore	Y+	Y+	Y+	Y	N
Definitions: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. HeapMem_Module_startupDone() returns true). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. HeapMem_Module_startupDone() returns false). * : Assuming blocking Heap is used for creation. **: Assuming GateMutex is used as HeapMem's Gate. + : Cannot use HeapMem object while it is being restored.

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/runtime/Error.h>
#include <ti/sysbios/runtime/IHeap.h>
#include <ti/sysbios/runtime/Memory.h>

Include dependency graph for HeapMem.h:

Go to the source code of this file.

Data Structures
struct	HeapMem_ExtendedStats
	Stat structure for the HeapMem_getExtendedStats function. More...

struct	HeapMem_Params

Macros
#define	HeapMem_reqAlign sizeof(HeapMem_Header)

#define	HeapMem_A_align "Requested align is not a power of 2"
	Assert raised when the requested alignment is not a power of 2. More...

#define	HeapMem_A_heapSize "Requested heap size is too small"
	Assert raised when the requested heap size is too small. More...

#define	HeapMem_A_invalidFree "Heap-block free operations must not leave the heap in an invalid state"
	Assert raised when the free detects that an invalid addr or size. More...

#define	HeapMem_A_zeroBlock "Cannot allocate size 0"
	Assert raised when a block of size 0 is requested. More...

#define	HeapMem_E_memory "out of memory: handle = 0x%x, size=%u"
	Raised when requested size exceeds largest free block. More...

#define	ti_sysbios_heaps_HeapMem_Handle_upCast(handle) ((IHeap_Handle)(handle))
	cast handle to an IHeap_Handle for use by Memory_alloc, etc. More...

Typedefs
typedef HeapMem_Struct	HeapMem_Object

Functions
void *	HeapMem_alloc (HeapMem_Handle heap, size_t size, size_t align, Error_Block *eb)
	The actual block returned may be larger than requested to satisfy alignment requirements, and its size will always be a multiple of the size of the HeapMem_Header data structure (usually 8 bytes) More...

void	HeapMem_free (HeapMem_Handle heap, void *buf, size_t size)
	HeapMem_free() places the memory block specified by addr and size back into the free pool of the heap specified. The newly freed block is combined with any adjacent free blocks. The space is then available for further allocation by alloc(). More...

bool	HeapMem_isBlocking (HeapMem_Handle heap)
	This function queries the gate to determine if the alloc/free can be blocking. More...

void	HeapMem_getStats (HeapMem_Handle heap, Memory_Stats *statBuf)
	HeapMem_getStats will lock the heap using the HeapMem Gate while it retrieves the HeapMem's statistics. More...

void	HeapMem_getExtendedStats (HeapMem_Handle heap, HeapMem_ExtendedStats *statBuf)
	Retrieves the extended statistics for a HeapMem instance. More...

HeapMem_Handle	HeapMem_create (const HeapMem_Params params, Error_Block eb)
	Create a `HeapMem` heap. More...

HeapMem_Handle	HeapMem_construct (HeapMem_Struct obj, const HeapMem_Params params)
	Construct a `HeapMem` heap. More...

void	HeapMem_delete (HeapMem_Handle *heap)
	Delete a `HeapMem` heap. More...

void	HeapMem_destruct (HeapMem_Struct *obj)
	Destruct a `HeapMem` heap. More...

void	HeapMem_restore (HeapMem_Handle heap)
	Restore heap to its original created state. More...

void	HeapMem_init (void)
	Initialize instance at runtime. More...

void	HeapMem_Params_init (HeapMem_Params *prms)
	Initialize the HeapMem_Params structure with default values. More...

HeapMem_Handle	HeapMem_Object_first (void)
	return handle of the first HeapMem on HeapMem list More...

HeapMem_Handle	HeapMem_Object_next (HeapMem_Handle heap)
	return handle of the next HeapMem on HeapMem list More...

Macro Definition Documentation

§ HeapMem_reqAlign

#define HeapMem_reqAlign sizeof(HeapMem_Header)

§ HeapMem_A_align

#define HeapMem_A_align "Requested align is not a power of 2"

Assert raised when the requested alignment is not a power of 2.

§ HeapMem_A_heapSize

#define HeapMem_A_heapSize "Requested heap size is too small"

Assert raised when the requested heap size is too small.

§ HeapMem_A_invalidFree

#define HeapMem_A_invalidFree "Heap-block free operations must not leave the heap in an invalid state"

Assert raised when the free detects that an invalid addr or size.

This could arise when multiple frees are done on the same buffer or if corruption occurred.

This also could occur when an alloc is made with size N and the free for this buffer specifies size M where M > N. Note: not every case is detectable.

This assert can also be caused when passing an invalid addr to free or if the size is causing the end of the buffer to be out of the expected range.

§ HeapMem_A_zeroBlock

#define HeapMem_A_zeroBlock "Cannot allocate size 0"

Assert raised when a block of size 0 is requested.

This error can also be raised if the requested size wraps the contents of a SizeT type when it is adjusted for a minimum alignment. For example, when SizeT is 16-bits and a size request is made for 0xFFFB.

§ HeapMem_E_memory

#define HeapMem_E_memory "out of memory: handle = 0x%x, size=%u"

Raised when requested size exceeds largest free block.

§ ti_sysbios_heaps_HeapMem_Handle_upCast

#define ti_sysbios_heaps_HeapMem_Handle_upCast ( handle ) ((IHeap_Handle)(handle))

cast handle to an IHeap_Handle for use by Memory_alloc, etc.

Parameters

handle heap handle

Return values

IHeap_Handle

Typedef Documentation

§ HeapMem_Object

typedef HeapMem_Struct HeapMem_Object

Function Documentation

§ HeapMem_alloc()

void* HeapMem_alloc	(	HeapMem_Handle	heap,
		size_t	size,
		size_t	align,
		Error_Block *	eb
	)

The actual block returned may be larger than requested to satisfy alignment requirements, and its size will always be a multiple of the size of the HeapMem_Header data structure (usually 8 bytes)

HeapMem_alloc() will lock the heap using the HeapMem Gate while it traverses the list of free blocks to find a large enough block for the request.

HeapMem_alloc() should not be called directly. Application code should use Memory_alloc() with a HeapMem_Handle as the first parameter. Among other things, Memory_alloc() makes sure that the alignment parameter is greater than or equal to the minimum alignment required for the HeapMem_Header data structure for a given C compiler (8 bytes in most cases). HeapMem_alloc() may crash if you pass a smaller alignment.

Guidelines for using large heaps and multiple alloc() calls.

     - If possible, allocate larger blocks first. Previous
       allocations of small memory blocks can reduce the size
       of the blocks available for larger memory allocations.
     - Realize that alloc() can fail even if the heap contains a
       sufficient absolute amount of unallocated space. This is
       because the largest free memory block may be smaller than
       total amount of unallocated memory.

Parameters

heap	heap handle
size	Requested size
align	Requested alignment
eb	Error_Block used to denote location in case of a failure

Return values

allocated block or NULL is request cannot be honored

§ HeapMem_free()

void HeapMem_free	(	HeapMem_Handle	heap,
		void *	buf,
		size_t	size
	)

HeapMem_free() places the memory block specified by addr and size back into the free pool of the heap specified. The newly freed block is combined with any adjacent free blocks. The space is then available for further allocation by alloc().

free() will lock the heap using the HeapMem Gate, if one is specified using 'HeapMem.common$.gate'.

Parameters

heap	heap handle
buf	block of memory to be freed
size	size of block to free

§ HeapMem_isBlocking()

bool HeapMem_isBlocking ( HeapMem_Handle heap )

This function queries the gate to determine if the alloc/free can be blocking.

Parameters

heap	heap handle

Return values

returns true if the gate can block, false otherwise

§ HeapMem_getStats()

void HeapMem_getStats	(	HeapMem_Handle	heap,
		Memory_Stats *	statBuf
	)

HeapMem_getStats will lock the heap using the HeapMem Gate while it retrieves the HeapMem's statistics.

The returned totalSize reflects the usable size of the buffer, not necessarily the size specified during create.

Parameters

heap	heap handle
statBuf	pointer to stat buffer

§ HeapMem_getExtendedStats()

void HeapMem_getExtendedStats	(	HeapMem_Handle	heap,
		HeapMem_ExtendedStats *	statBuf
	)

Retrieves the extended statistics for a HeapMem instance.

This function retrieves the extended statistics for a HeapMem instance. It does not retrieve the standard xdc.runtime.Memory.Stats information.

Parameters

heap	heap handle
statBuf	Location for the returned extended statistics.

§ HeapMem_create()

HeapMem_Handle HeapMem_create	(	const HeapMem_Params *	params,
		Error_Block *	eb
	)

Create a HeapMem heap.

This heap is a growth-only heap that is intended to be used by systems that never delete objects or free memory. Objects can be created at runtime based on values determined at runtime, but objects can not be deleted.

Parameters

params	optional parameters
eb	error block

Return values

HeapMem handle (NULL on failure)

§ HeapMem_construct()

HeapMem_Handle HeapMem_construct	(	HeapMem_Struct *	obj,
		const HeapMem_Params *	params
	)

Construct a HeapMem heap.

HeapMem_construct is equivalent to HeapMem_create except that the HeapMem_Struct is pre-allocated.

Parameters

obj	pointer to a HeapMem object
params	optional parameters

Return values

HeapMem handle (NULL on failure)

§ HeapMem_delete()

void HeapMem_delete ( HeapMem_Handle * heap )

Delete a HeapMem heap.

Note that HeapMem_delete takes a pointer to a HeapMem_Handle which enables HeapMem_delete to set the HeapMem handle to NULL.

Parameters

heap	pointer to a HeapMem handle

§ HeapMem_destruct()

void HeapMem_destruct ( HeapMem_Struct * obj )

Destruct a HeapMem heap.

Parameters

obj	pointer to a HeapMem objects

§ HeapMem_restore()

void HeapMem_restore ( HeapMem_Handle heap )

Restore heap to its original created state.

This function restores a heap to its original created state. Any memory previously allocated from the heap is no longer valid after this API is called. This function does not check whether there is allocated memory or not.

Parameters

heap	heap handle

§ HeapMem_init()

void HeapMem_init ( void )

Initialize instance at runtime.

This function is plugged as a Startup.firstFxn so that the HeapMem objects are ready and usable by malloc() and Memory_alloc() by the time the module startup functions get called so that any calls to atexit(), which in some targets invokes malloc(), will be handled cleanly.

§ HeapMem_Params_init()

void HeapMem_Params_init ( HeapMem_Params * prms )

Initialize the HeapMem_Params structure with default values.

HeapMem_Params_init initializes the HeapMem_Params structure with default values. HeapMem_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.

Parameters

prms	pointer to uninitialized params structure

§ HeapMem_Object_first()

HeapMem_Handle HeapMem_Object_first ( void )

return handle of the first HeapMem on HeapMem list

Return the handle of the first HeapMem on the create/construct list. NULL if no HeapMems have been created or constructed.

Return values

HeapMem handle

§ HeapMem_Object_next()

HeapMem_Handle HeapMem_Object_next ( HeapMem_Handle heap )

return handle of the next HeapMem on HeapMem list

Return the handle of the next HeapMem on the create/construct list. NULL if no more HeapMems are on the list.

Parameters

heap	HeapMem handle

Return values

HeapMem handle

Detailed Description

HeapMem Gate

Calling Context

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ HeapMem_reqAlign

§ HeapMem_A_align

§ HeapMem_A_heapSize

§ HeapMem_A_invalidFree

§ HeapMem_A_zeroBlock

§ HeapMem_E_memory

§ ti_sysbios_heaps_HeapMem_Handle_upCast

Typedef Documentation

§ HeapMem_Object

Function Documentation

§ HeapMem_alloc()

§ HeapMem_free()

§ HeapMem_isBlocking()

§ HeapMem_getStats()

§ HeapMem_getExtendedStats()

§ HeapMem_create()

§ HeapMem_construct()

§ HeapMem_delete()

§ HeapMem_destruct()

§ HeapMem_restore()

§ HeapMem_init()

§ HeapMem_Params_init()

§ HeapMem_Object_first()

§ HeapMem_Object_next()