HeapCallback.h File Reference

Detailed Description

A heap that calls user supplied callback functions.

The HeapCallback module enables users to provide a custom heap implementation by providing callback functions that will be invoked by HeapCallback for the various heap management functions.

The user-supplied HeapCallback.initInstFxn is called during boot time to initialize any HeapCallback objects that were created in the .cfg file. The user-supplied HeapCallback.createInstFxn is called during runtime for any calls to HeapCallback_create(). Both of these functions return a context value (typically a pointer to an object managed by the user-supplied heap code). This context value is passed to subsequent user allocInstFxn, freeInstFxn, etc. functions.

HeapCallback_alloc(), HeapCallback_free() and HeapCallback_getStats() call the user-supplied allocInstFxn, freeInstFxn and getStatsInstFxn functions with the context value returned by initInstFxn or createInstFxn.

HeapCallback_delete() calls the user-supplied instDeleteFxn with the context returned by the createInstFxn.

Examples

Configuration example: The following XDC configuration statements creates a HeapCallback instance and plugs in the user defined functions.

const HeapCallback = scripting.addModule("/ti/sysbios/heaps/HeapCallback");

HeapCallback.initInstFxn = "userInitFxn";
HeapCallback.createInstFxn = "userCreateFxn";
HeapCallback.deleteInstFxn = "userDeleteFxn";
HeapCallback.allocInstFxn = "userAllocFxn";
HeapCallback.freeInstFxn = "userFreeFxn";
HeapCallback.getStatsInstFxn = "userGetStatsFxn";
HeapCallback.isBlockingInstFxn = "userIsBlockingFxn";

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

Include dependency graph for HeapCallback.h:

Go to the source code of this file.

Data Structures
struct	HeapCallback_Params
struct	HeapCallback_Struct

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

Typedefs
typedef void *(*	HeapCallback_AllocInstFxn) (uintptr_t context, size_t size, size_t align)
	Instance alloc callback function signature. More...
typedef uintptr_t(*	HeapCallback_CreateInstFxn) (uintptr_t arg)
	Instance create callback function signature. More...
typedef void(*	HeapCallback_DeleteInstFxn) (uintptr_t context)
	Instance delete callback function signature. More...
typedef void(*	HeapCallback_FreeInstFxn) (uintptr_t context, void *addr, size_t size)
	Instance free callback function signature. More...
typedef void(*	HeapCallback_GetStatsInstFxn) (uintptr_t context, Memory_Stats *stats)
	Instance getStats callback function signature. More...
typedef bool(*	HeapCallback_IsBlockingInstFxn) (uintptr_t context)
	Instance isblocking callback function signature. More...
typedef struct HeapCallback_Struct *	HeapCallback_Handle
typedef HeapCallback_Struct	HeapCallback_Object

Functions
void *	HeapCallback_alloc (HeapCallback_Handle handle, size_t size, size_t align, Error_Block *eb)
	Allocate a block of memory from the heap. More...
void	HeapCallback_free (HeapCallback_Handle handle, void *buf, size_t size)
	Free a block of memory back to the heap. More...
bool	HeapCallback_isBlocking (HeapCallback_Handle handle)
	Can this heap block the caller. More...
void	HeapCallback_getStats (HeapCallback_Handle handle, Memory_Stats *stats)
	get memory stats for a HeapCallback object More...
HeapCallback_Handle	HeapCallback_create (const HeapCallback_Params *params, Error_Block *eb)
	Create a HeapCallback heap. More...
HeapCallback_Handle	HeapCallback_construct (HeapCallback_Struct *obj, const HeapCallback_Params *params)
	Construct a HeapCallback heap. More...
void	HeapCallback_delete (HeapCallback_Handle *handle)
	Delete a HeapCallback heap. More...
void	HeapCallback_destruct (HeapCallback_Struct *obj)
	Destruct a HeapCallback heap. More...
void	HeapCallback_Params_init (HeapCallback_Params *prms)
	Initialize the HeapCallback_Params structure with default values. More...
HeapCallback_Handle	HeapCallback_Object_first (void)
	return handle of the first HeapCallback on HeapCallback list More...
HeapCallback_Handle	HeapCallback_Object_next (HeapCallback_Handle heap)
	return handle of the next HeapCallback on HeapCallback list More...
static HeapCallback_Handle	HeapCallback_handle (HeapCallback_Struct *str)
static HeapCallback_Struct *	HeapCallback_struct (HeapCallback_Handle h)

Macro Definition Documentation

ti_sysbios_heaps_HeapCallback_Handle_upCast

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

HeapCallback_AllocInstFxn

typedef void*(* HeapCallback_AllocInstFxn) (uintptr_t context, size_t size, size_t align)

Instance alloc callback function signature.

This function takes the context return from createInstFxn(), the size to be allocated and the align value. The return value from this function is a pointer to the allocated memory block.

HeapCallback_CreateInstFxn

typedef uintptr_t(* HeapCallback_CreateInstFxn) (uintptr_t arg)

Instance create callback function signature.

The 'arg' is passed as an argument to this function. The return value from this function (context) will be passed as an argument to the other instance functions.

HeapCallback_DeleteInstFxn

typedef void(* HeapCallback_DeleteInstFxn) (uintptr_t context)

Instance delete callback function signature.

The context returned from createInstFxn() is passed as an argument to this function.

HeapCallback_FreeInstFxn

typedef void(* HeapCallback_FreeInstFxn) (uintptr_t context, void *addr, size_t size)

Instance free callback function signature.

This function takes the context returned by createInstFxn() and a pointer to the buffer to be freed and the size to be freed.

HeapCallback_GetStatsInstFxn

typedef void(* HeapCallback_GetStatsInstFxn) (uintptr_t context, Memory_Stats *stats)

Instance getStats callback function signature.

This function takes the context returned by createInstFxn() and a pointer to a memory stats object.

HeapCallback_IsBlockingInstFxn

typedef bool(* HeapCallback_IsBlockingInstFxn) (uintptr_t context)

Instance isblocking callback function signature.

The context return from createInstFxn() is passed as an argument to this function. The return value is 'true' or 'false'.

HeapCallback_Handle

typedef struct HeapCallback_Struct * HeapCallback_Handle

HeapCallback_Object

typedef HeapCallback_Struct HeapCallback_Object

Function Documentation

HeapCallback_alloc()

void* HeapCallback_alloc	(	HeapCallback_Handle	handle,
		size_t	size,
		size_t	align,
		Error_Block *	eb
	)

Allocate a block of memory from the heap.

HeapCallback_free()

void HeapCallback_free	(	HeapCallback_Handle	handle,
		void *	buf,
		size_t	size
	)

Free a block of memory back to the heap.

HeapCallback_isBlocking()

bool HeapCallback_isBlocking

(

HeapCallback_Handle

handle

)

Can this heap block the caller.

HeapCallback returns true if the configured callback heap can block. HeapCallback returns false if the configured callback heap cannot block.

Parameters

handle

heap handle

Return values

always

returns false

HeapCallback_getStats()

void HeapCallback_getStats	(	HeapCallback_Handle	handle,
		Memory_Stats *	stats
	)

get memory stats for a HeapCallback object

Parameters

handle	heap handle
stats	pointer to a Memory_Stats object

HeapCallback_create()

HeapCallback_Handle HeapCallback_create	(	const HeapCallback_Params *	params,
		Error_Block *	eb
	)

Create a HeapCallback heap.

Parameters

params	optional parameters
eb	error block

Return values

HeapMin

handle (NULL on failure)

HeapCallback_construct()

HeapCallback_Handle HeapCallback_construct	(	HeapCallback_Struct *	obj,
		const HeapCallback_Params *	params
	)

Construct a HeapCallback heap.

HeapCallback_construct is equivalent to HeapCallback_create except that the HeapCallback_Struct is pre-allocated.

Parameters

obj	pointer to a HeapCallback object
params	optional parameters

Return values

HeapCallback

handle (NULL on failure)

HeapCallback_delete()

void HeapCallback_delete

(

HeapCallback_Handle *

handle

)

Delete a HeapCallback heap.

Note that HeapCallback_delete takes a pointer to a HeapCallback_Handle which enables HeapCallback_delete to set the HeapCallback handle to NULL.

Parameters

handle

pointer to a HeapCallback handle

HeapCallback_destruct()

void HeapCallback_destruct

(

HeapCallback_Struct *

obj

)

Destruct a HeapCallback heap.

Parameters

obj	pointer to a HeapCallback objects

HeapCallback_Params_init()

void HeapCallback_Params_init

(

HeapCallback_Params *

prms

)

Initialize the HeapCallback_Params structure with default values.

HeapCallback_Params_init initializes the HeapCallback_Params structure with default values. HeapCallback_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

HeapCallback_Object_first()

HeapCallback_Handle HeapCallback_Object_first

(

void

)

return handle of the first HeapCallback on HeapCallback list

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

Return values

HeapCallback

handle

HeapCallback_Object_next()

HeapCallback_Handle HeapCallback_Object_next

(

HeapCallback_Handle

heap

)

return handle of the next HeapCallback on HeapCallback list

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

Parameters

heap	HeapCallback handle

Return values

HeapCallback

handle

HeapCallback_handle()

static HeapCallback_Handle HeapCallback_handle ( HeapCallback_Struct *  str )

inlinestatic

HeapCallback_struct()

static HeapCallback_Struct* HeapCallback_struct ( HeapCallback_Handle  h )

inlinestatic