HeapBuf.h File Reference

Detailed Description

Fixed size buffer heap manager.

The HeapBuf manager provides functions to allocate and free storage from a heap of type HeapBuf which inherits from IHeap. HeapBuf manages a single fixed-size buffer, split into equally sized allocable blocks.

The HeapBuf manager is intended as a very fast and deterministic memory manager which can only allocate blocks of a single size. It is ideal for managing a heap that is only used for allocating a single type of object, or for objects that have very similar sizes.

Allocation from and freeing to a HeapBuf instance is non-blocking and deterministic: a call to alloc or free will always take the same amount of time.

Constraints:

• Align parameter must be set to 0 for default, or be a power of 2 that is greater than or equal to the value returned by Memory_getMaxDefaultTypeAlign.
• The buffer passed to dynamically create a HeapBuf must be aligned according to the alignment parameter, and must be large enough to account for the actual block size after it has been rounded up to a multiple of the alignment.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Params_init	Y	Y	Y	Y	Y
alloc	Y	Y	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	Y	Y	Y	Y	N
getStats	Y	Y	Y	Y	N
getExtendedStats	Y	Y	Y	Y	N
isBlocking	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. HeapBuf_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. HeapBuf_Module_startupDone() returns false). *: Assuming blocking Heap is used for creation.

#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 HeapBuf.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	HeapBuf_ExtendedStats
	Stat structure for the HeapBuf_getExtendedStats function. More...
struct	HeapBuf_Params
struct	HeapBuf_Struct

Macros
#define	HeapBuf_A_nullBuf   "buf parameter cannot be null"
	Null buf parameter. More...
#define	HeapBuf_A_bufAlign   "buf not properly aligned"
	Misalligned buffer. More...
#define	HeapBuf_A_invalidAlign   "align parameter must be 0 or a power of 2 >= the value of Memory_getMaxDefaultTypeAlign()"
	Invalid alignment. More...
#define	HeapBuf_A_invalidRequestedAlign   "align parameter 1) must be 0 or a power of 2 and 2) not greater than the heaps alignment"
	Invalid alignment parameter in the alloc. More...
#define	HeapBuf_A_invalidBlockSize   "blockSize must be large enough to hold at least two pointers"
	Assert raised when the blockSize parameter is not large enough to hold two pointers. More...
#define	HeapBuf_A_zeroBlocks   "numBlocks cannot be zero"
	Assert raised when the numBlocks parameter is 0. More...
#define	HeapBuf_A_zeroBufSize   "bufSize cannot be zero"
	Assert raised when the bufSize parameter is 0. More...
#define	HeapBuf_A_invalidBufSize   "HeapBuf_create's bufSize parameter is invalid (too small)"
	Invalid buffer size. More...
#define	HeapBuf_A_noBlocksToFree   "Cannot call HeapBuf_free when no blocks have been allocated"
	No allocated blocks. More...
#define	HeapBuf_A_invalidFree   "Invalid free"
	Assert raised when an invalid free occurs. More...
#define	HeapBuf_E_size   "requested size is too big: handle=0x%x, size=%u"
	Raised when requested size exceeds blockSize. More...
#define	ti_sysbios_heaps_HeapBuf_Handle_upCast(handle)   ((IHeap_Handle)(handle))
	cast handle to an IHeap_Handle for use by Memory_alloc, etc. More...

Typedefs
typedef struct HeapBuf_Struct *	HeapBuf_Handle
typedef HeapBuf_Struct	HeapBuf_Object

Functions
void *	HeapBuf_alloc (HeapBuf_Handle heap, size_t size, size_t align, Error_Block *eb)
	All alignment is handled in the create, therefore the align argument in alloc is ignored. More...
void	HeapBuf_free (HeapBuf_Handle heap, void *buf, size_t size)
bool	HeapBuf_isBlocking (HeapBuf_Handle heap)
	This function always returns false since the alloc/free never block on a resource. More...
void	HeapBuf_getStats (HeapBuf_Handle heap, Memory_Stats *statBuf)
	This function returns state information for a HeapBuf. More...
void	HeapBuf_getExtendedStats (HeapBuf_Handle heap, HeapBuf_ExtendedStats *statBuf)
	Retrieves the extended statistics for a HeapBuf instance. More...
HeapBuf_Handle	HeapBuf_create (const HeapBuf_Params *params, Error_Block *eb)
	Create a HeapBuf heap. More...
HeapBuf_Handle	HeapBuf_construct (HeapBuf_Struct *obj, const HeapBuf_Params *params, Error_Block *eb)
	Construct a HeapBuf heap. More...
void	HeapBuf_delete (HeapBuf_Handle *heap)
	Delete a HeapBuf heap. More...
void	HeapBuf_destruct (HeapBuf_Struct *obj)
	Destruct a HeapBuf heap. More...
void	HeapBuf_Params_init (HeapBuf_Params *prms)
	Initialize the HeapBuf_Params structure with default values. More...
HeapBuf_Handle	HeapBuf_Object_first (void)
	return handle of the first HeapBuf on HeapBuf list More...
HeapBuf_Handle	HeapBuf_Object_next (HeapBuf_Handle heap)
	return handle of the next HeapBuf on HeapBuf list More...

Macro Definition Documentation

HeapBuf_A_nullBuf

#define HeapBuf_A_nullBuf   "buf parameter cannot be null"

Null buf parameter.

This Assert is raised when the buf parameter has been omitted (null) for a dynamic create.

HeapBuf_A_bufAlign

#define HeapBuf_A_bufAlign   "buf not properly aligned"

Misalligned buffer.

This Assert is raised when the buf parameter has not been aligned on the requested alignment.

HeapBuf_A_invalidAlign

#define HeapBuf_A_invalidAlign   "align parameter must be 0 or a power of 2 >= the value of Memory_getMaxDefaultTypeAlign()"

Invalid alignment.

This Assert is raised when the align parameter is not the default value of zero, or a power of 2.

HeapBuf_A_invalidRequestedAlign

#define HeapBuf_A_invalidRequestedAlign   "align parameter 1) must be 0 or a power of 2 and 2) not greater than the heaps alignment"

Invalid alignment parameter in the alloc.

This Assert is raised when the align argument is not a power of 2 (or 0). It is also raised if the parameter is greater the alignment specified when creating the heap.

HeapBuf_A_invalidBlockSize

#define HeapBuf_A_invalidBlockSize   "blockSize must be large enough to hold at least two pointers"

Assert raised when the blockSize parameter is not large enough to hold two pointers.

HeapBuf_A_zeroBlocks

#define HeapBuf_A_zeroBlocks   "numBlocks cannot be zero"

Assert raised when the numBlocks parameter is 0.

HeapBuf_A_zeroBufSize

#define HeapBuf_A_zeroBufSize   "bufSize cannot be zero"

Assert raised when the bufSize parameter is 0.

HeapBuf_A_invalidBufSize

#define HeapBuf_A_invalidBufSize   "HeapBuf_create's bufSize parameter is invalid (too small)"

Invalid buffer size.

This Assert is raised when the bufSize parameter is too small to handle requested blocks.

HeapBuf_A_noBlocksToFree

#define HeapBuf_A_noBlocksToFree   "Cannot call HeapBuf_free when no blocks have been allocated"

No allocated blocks.

This Assert is raised when free is called and there are no blocks allocated.

HeapBuf_A_invalidFree

#define HeapBuf_A_invalidFree   "Invalid free"

Assert raised when an invalid free occurs.

This assert can be caused for the following reasons

• Passing a NULL pointer to the free.
• The block is not within the heap's buffer range. This can occur if the block is freed to the wrong heap.
• The block is not on the proper boundary. This can occur if the pointer returned from alloc is changed by the application and not set back to its original value when free is called.

HeapBuf_E_size

#define HeapBuf_E_size   "requested size is too big: handle=0x%x, size=%u"

Raised when requested size exceeds blockSize.

ti_sysbios_heaps_HeapBuf_Handle_upCast

#define ti_sysbios_heaps_HeapBuf_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

HeapBuf_Handle

typedef struct HeapBuf_Struct * HeapBuf_Handle

HeapBuf_Object

typedef HeapBuf_Struct HeapBuf_Object

Function Documentation

HeapBuf_alloc()

void* HeapBuf_alloc	(	HeapBuf_Handle	heap,
		size_t	size,
		size_t	align,
		Error_Block *	eb
	)

All alignment is handled in the create, therefore the align argument in alloc is ignored.

HeapBuf_alloc will only fail if there are no available blocks or if the requested block size is larger than the HeapBuf's blockSize. All other requests, regardless of size, will succeed.

Parameters

heap	heap handle
size	size
align	alignment
eb	error block

Return values

address

of allocated block (NULL on error)

HeapBuf_free()

void HeapBuf_free	(	HeapBuf_Handle	heap,
		void *	buf,
		size_t	size
	)

HeapBuf_isBlocking()

bool HeapBuf_isBlocking

(

HeapBuf_Handle

heap

)

This function always returns false since the alloc/free never block on a resource.

Parameters

heap	heap handle

Return values

always

returns false

HeapBuf_getStats()

void HeapBuf_getStats	(	HeapBuf_Handle	heap,
		Memory_Stats *	statBuf
	)

This function returns state information for a HeapBuf.

Parameters

heap	heap handle
statBuf	pointer to stats object

HeapBuf_getExtendedStats()

void HeapBuf_getExtendedStats	(	HeapBuf_Handle	heap,
		HeapBuf_ExtendedStats *	statBuf
	)

Retrieves the extended statistics for a HeapBuf instance.

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

Parameters

heap	heap handle
statBuf	pointer to the extended stats structure.

HeapBuf_create()

HeapBuf_Handle HeapBuf_create	(	const HeapBuf_Params *	params,
		Error_Block *	eb
	)

Create a HeapBuf heap.

Parameters

params	optional parameters
eb	error block

Return values

HeapBuf

handle (NULL on failure)

HeapBuf_construct()

HeapBuf_Handle HeapBuf_construct	(	HeapBuf_Struct *	obj,
		const HeapBuf_Params *	params,
		Error_Block *	eb
	)

Construct a HeapBuf heap.

HeapBuf_construct is equivalent to HeapBuf_create except that the HeapBuf_Struct is pre-allocated.

Parameters

obj	pointer to a HeapBuf object
params	optional parameters
eb	error block

Return values

HeapBuf

handle (NULL on failure)

HeapBuf_delete()

void HeapBuf_delete

(

HeapBuf_Handle *

heap

)

Delete a HeapBuf heap.

Note that HeapBuf_delete takes a pointer to a HeapBuf_Handle which enables HeapBuf_delete to set the HeapBuf handle to NULL.

Parameters

heap	pointer to a HeapBuf handle

HeapBuf_destruct()

void HeapBuf_destruct

(

HeapBuf_Struct *

obj

)

Destruct a HeapBuf heap.

Parameters

obj	pointer to a HeapBuf objects

HeapBuf_Params_init()

void HeapBuf_Params_init

(

HeapBuf_Params *

prms

)

Initialize the HeapBuf_Params structure with default values.

HeapBuf_Params_init initializes the HeapBuf_Params structure with default values. HeapBuf_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

HeapBuf_Object_first()

HeapBuf_Handle HeapBuf_Object_first

(

void

)

return handle of the first HeapBuf on HeapBuf list

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

Return values

HeapBuf

handle

HeapBuf_Object_next()

HeapBuf_Handle HeapBuf_Object_next

(

HeapBuf_Handle

heap

)

return handle of the next HeapBuf on HeapBuf list

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

Parameters

heap	HeapBuf handle

Return values

HeapBuf

handle