Detailed Description

Heap manager that enables tracking of all allocated blocks.

HeapTrack manager provides functions to allocate and free storage from a configured heap which inherits from IHeap. The calling context is going to match the heap being used.

HeapTrack is useful for detecting memory leaks, double frees and buffer overflows. There is a performance overhead cost when using heap track as well as a size impact. Every alloc will include a HeapTrack_Tracker structure (plus memory to get proper alignment of the stucture) at the end of the buffer that should not be modified by the user. It is important to remember this when deciding on heap sizes and you may have to adjust the total size or buffer sizes (for HeapBuf/HeapMultiBuf).

ROV displays peaks and current in-use for both allocated memory (requested size + Tracker structure) and requested memory (without Tracker).

The information stored in the tracker packet is used to display information in RTOS Object Viewer (ROV) as well as with the printTask and printHeap functions.

The asserts used in this module are listed below and include error checking for double frees, calling printHeap with a null handle, buffer overflows and deleting a non empty heap.

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

Include dependency graph for HeapTrack.h:

Go to the source code of this file.

Data Structures
struct	HeapTrack_Tracker
	Structure added to the end of each allocated block. More...

struct	HeapTrack_Params

struct	HeapTrack_Struct

struct	HeapTrack_Module_State

Macros
#define	HeapTrack_A_doubleFree "Buffer already free"
	Assert raised when freeing a buffer that was already freed. More...

#define	HeapTrack_A_bufOverflow "Buffer overflow"
	Assert raised when freeing memory with corrupted data or using the wrong size. More...

#define	HeapTrack_A_notEmpty "Heap not empty"
	Assert raised when deleting a non-empty heap. More...

#define	HeapTrack_A_nullObject "HeapTrack_printHeap called with null obj"
	Assert raised when calling printTask with a null HeapTrack object. More...

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

Typedefs
typedef struct HeapTrack_Struct *	HeapTrack_Handle

typedef HeapTrack_Struct	HeapTrack_Object

Functions
void *	HeapTrack_alloc (HeapTrack_Handle heap, size_t size, size_t align, Error_Block *eb)
	Allocate a block of memory from the heap. More...

void	HeapTrack_free (HeapTrack_Handle heap, void *buf, size_t size)
	Free a block of memory back to the heap. More...

bool	HeapTrack_isBlocking (HeapTrack_Handle heap)
	Can this heap block the caller. More...

void	HeapTrack_getStats (HeapTrack_Handle heap, Memory_Stats *stats)
	get memory stats for a HeapTrack object More...

void	HeapTrack_printTask (Task_Handle task)
	Print out the blocks that are currently allocated by a task. More...

void	HeapTrack_printHeap (HeapTrack_Handle heap)
	Print details for a HeapTrack instance. More...

HeapTrack_Handle	HeapTrack_Object_first (void)
	return handle of the first HeapTrack on HeapTrack list More...

HeapTrack_Handle	HeapTrack_Object_next (HeapTrack_Handle heap)
	return handle of the next HeapTrack on HeapTrack list More...

HeapTrack_Handle	HeapTrack_create (const HeapTrack_Params params, Error_Block eb)
	Create a `HeapTrack` heap. More...

HeapTrack_Handle	HeapTrack_construct (HeapTrack_Struct obj, const HeapTrack_Params params)
	Construct a `HeapTrack` heap. More...

void	HeapTrack_delete (HeapTrack_Handle *heap)
	Delete a `HeapTrack` heap. More...

void	HeapTrack_destruct (HeapTrack_Struct *obj)
	Destruct a `HeapTrack` heap. More...

void	HeapTrack_Params_init (HeapTrack_Params *prms)
	Initialize the HeapTrack_Params structure with default values. More...

static HeapTrack_Handle	HeapTrack_handle (HeapTrack_Struct *str)

static HeapTrack_Struct *	HeapTrack_struct (HeapTrack_Handle h)

Macro Definition Documentation

§ HeapTrack_A_doubleFree

#define HeapTrack_A_doubleFree "Buffer already free"

Assert raised when freeing a buffer that was already freed.

§ HeapTrack_A_bufOverflow

#define HeapTrack_A_bufOverflow "Buffer overflow"

Assert raised when freeing memory with corrupted data or using the wrong size.

§ HeapTrack_A_notEmpty

#define HeapTrack_A_notEmpty "Heap not empty"

Assert raised when deleting a non-empty heap.

§ HeapTrack_A_nullObject

#define HeapTrack_A_nullObject "HeapTrack_printHeap called with null obj"

Assert raised when calling printTask with a null HeapTrack object.

§ ti_sysbios_heaps_HeapTrack_Handle_upCast

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

§ HeapTrack_Handle

typedef struct HeapTrack_Struct * HeapTrack_Handle

§ HeapTrack_Object

typedef HeapTrack_Struct HeapTrack_Object

Function Documentation

§ HeapTrack_alloc()

void* HeapTrack_alloc	(	HeapTrack_Handle	heap,
		size_t	size,
		size_t	align,
		Error_Block *	eb
	)

Allocate a block of memory from the heap.

Precondition: The alignment must be a power of 2.

§ HeapTrack_free()

void HeapTrack_free	(	HeapTrack_Handle	heap,
		void *	buf,
		size_t	size
	)

Free a block of memory back to the heap.

§ HeapTrack_isBlocking()

bool HeapTrack_isBlocking ( HeapTrack_Handle heap )

Can this heap block the caller.

HeapTrack returns true if the underlying heap is blocking. HeapTrack returns false if the underlying heap not blocking.

Parameters

heap	heap handle

Return values

<tt>true</tt> if the underlying heap if blocking, false otherwise

§ HeapTrack_getStats()

void HeapTrack_getStats	(	HeapTrack_Handle	heap,
		Memory_Stats *	stats
	)

get memory stats for a HeapTrack object

Parameters

heap	heap handle
stats	pointer to a Memory_Stats object

§ HeapTrack_printTask()

void HeapTrack_printTask ( Task_Handle task )

Print out the blocks that are currently allocated by a task.

Iterates through all instances of HeapTrack and prints out information about all allocated blocks of memory for a given task handle. This function is not thread safe.

§ HeapTrack_printHeap()

void HeapTrack_printHeap ( HeapTrack_Handle heap )

Print details for a HeapTrack instance.

Print the details of all allocated blocks of memory for a HeapTrack instance. This function is not thread safe.

§ HeapTrack_Object_first()

HeapTrack_Handle HeapTrack_Object_first ( void )

return handle of the first HeapTrack on HeapTrack list

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

Return values

HeapTrack handle

§ HeapTrack_Object_next()

HeapTrack_Handle HeapTrack_Object_next ( HeapTrack_Handle heap )

return handle of the next HeapTrack on HeapTrack list

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

Parameters

heap	HeapTrack handle

Return values

HeapTrack handle

§ HeapTrack_create()

HeapTrack_Handle HeapTrack_create	(	const HeapTrack_Params *	params,
		Error_Block *	eb
	)

Create a HeapTrack heap.

Parameters

params	optional parameters
eb	error block

Return values

HeapTrack handle (NULL on failure)

§ HeapTrack_construct()

HeapTrack_Handle HeapTrack_construct	(	HeapTrack_Struct *	obj,
		const HeapTrack_Params *	params
	)

Construct a HeapTrack heap.

HeapTrack_construct is equivalent to HeapTrack_create except that the HeapTrack_Struct is pre-allocated.

Parameters

obj	pointer to a HeapTrack object
params	optional parameters

Return values

HeapTrack handle (NULL on failure)

§ HeapTrack_delete()

void HeapTrack_delete ( HeapTrack_Handle * heap )

Delete a HeapTrack heap.

Note that HeapTrack_delete takes a pointer to a HeapTrack_Handle which enables HeapTrack_delete to set the HeapTrack handle to NULL.

Parameters

heap	pointer to a HeapTrack handle

§ HeapTrack_destruct()

void HeapTrack_destruct ( HeapTrack_Struct * obj )

Destruct a HeapTrack heap.

Parameters

obj	pointer to a HeapTrack objects

§ HeapTrack_Params_init()

void HeapTrack_Params_init ( HeapTrack_Params * prms )

Initialize the HeapTrack_Params structure with default values.

HeapTrack_Params_init initializes the HeapTrack_Params structure with default values. HeapTrack_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

§ HeapTrack_handle()

static HeapTrack_Handle HeapTrack_handle ( HeapTrack_Struct * str )

inlinestatic

§ HeapTrack_struct()

static HeapTrack_Struct* HeapTrack_struct ( HeapTrack_Handle h )

inlinestatic

Detailed Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ HeapTrack_A_doubleFree

§ HeapTrack_A_bufOverflow

§ HeapTrack_A_notEmpty

§ HeapTrack_A_nullObject

§ ti_sysbios_heaps_HeapTrack_Handle_upCast

Typedef Documentation

§ HeapTrack_Handle

§ HeapTrack_Object

Function Documentation

§ HeapTrack_alloc()

§ HeapTrack_free()

§ HeapTrack_isBlocking()

§ HeapTrack_getStats()

§ HeapTrack_printTask()

§ HeapTrack_printHeap()

§ HeapTrack_Object_first()

§ HeapTrack_Object_next()

§ HeapTrack_create()

§ HeapTrack_construct()

§ HeapTrack_delete()

§ HeapTrack_destruct()

§ HeapTrack_Params_init()

§ HeapTrack_handle()

§ HeapTrack_struct()