module ti.sysbios.heaps.HeapTrack

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. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/heaps/HeapTrack.xdc
#include <ti/sysbios/heaps/HeapTrack.h>
Functions
Void
Void
Void
Void
Void 
Void 
Functions common to all IHeap modules
Ptr 
Void 
Void 
Bool 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef struct
typedef struct
typedef struct
typedef struct
Constants
extern const Assert_Id 
extern const Assert_Id 
extern const Assert_Id 
extern const Assert_Id 
 
DETAILS
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 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.
 
struct HeapTrack_Tracker

Structure added to the end of each allocated block

C synopsis target-domain
typedef struct HeapTrack_Tracker {
    UInt32 scribble;
    Queue_Elem queElem;
    SizeT size;
    UInt32 tick;
    Task_Handle taskHandle;
} HeapTrack_Tracker;
 
DETAILS
When a block is allocated from a HeapTrack heap with a size, internally HeapTrack calls Memory_alloc on the configured heap. The value of sizeof(HeapTrack_Tracker) is added to the requested size.
For example, if the caller makes the following call (where heapHandle is an HeapTrack handle that has been converted to an IHeap_Handle).
  buf = Memory_alloc(heapHandle, MYSIZE, MYALIGN, &eb);
Internally, HeapTrack will make the following call (where size is MYSIZE, align is MYALIGN and obj is the HeapTrack handle).
  block = Memory_alloc(obj->heap, size + sizeof(HeapTrack_Tracker), align, &eb);
When using HeapTrack, depending on the actual heap (i.e. heap), you might need to make adjustments to the heap (e.g. increase the blockSize if using a HeapBuf instance).
The HeapTrack module manages the contents of this structure and should not be directly accessing them.
 
config HeapTrack_A_bufOverflow  // module-wide

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

C synopsis target-domain
extern const Assert_Id HeapTrack_A_bufOverflow;
 
 
config HeapTrack_A_doubleFree  // module-wide

Assert raised when freeing a buffer that was already freed

C synopsis target-domain
extern const Assert_Id HeapTrack_A_doubleFree;
 
 
config HeapTrack_A_notEmpty  // module-wide

Assert raised when deleting a non-empty heap

C synopsis target-domain
extern const Assert_Id HeapTrack_A_notEmpty;
 
 
config HeapTrack_A_nullObject  // module-wide

Assert raised when calling printTask with a null HeapTrack object

C synopsis target-domain
extern const Assert_Id HeapTrack_A_nullObject;
 
 
HeapTrack_printTask()  // module-wide

Print out the blocks that are currently allocated by a task

C synopsis target-domain
Void HeapTrack_printTask(Task_Handle taskHandle);
 
DETAILS
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.
PARAMS
Task to print stats for
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId HeapTrack_Module_id();
// Get this module's unique id
 
Bool HeapTrack_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle HeapTrack_Module_heap();
// The heap from which this module allocates memory
 
Bool HeapTrack_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 HeapTrack_Module_getMask();
// Returns the diagnostics mask for this module
 
Void HeapTrack_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct HeapTrack_Object HeapTrack_Object;
// Opaque internal representation of an instance object
 
typedef HeapTrack_Object *HeapTrack_Handle;
// Client reference to an instance object
 
typedef struct HeapTrack_Struct HeapTrack_Struct;
// Opaque client structure large enough to hold an instance object
 
HeapTrack_Handle HeapTrack_handle(HeapTrack_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
HeapTrack_Struct *HeapTrack_struct(HeapTrack_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct HeapTrack_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    IHeap_Handle heap;
    // Heap to use with HeapTrack
} HeapTrack_Params;
 
Void HeapTrack_Params_init(HeapTrack_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config HeapTrack_Params.heap  // instance

Heap to use with HeapTrack

C synopsis target-domain
struct HeapTrack_Params {
      ...
    IHeap_Handle heap;
 
Runtime Instance Creation

C synopsis target-domain
HeapTrack_Handle HeapTrack_create(const HeapTrack_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void HeapTrack_construct(HeapTrack_Struct *structP, const HeapTrack_Params *params);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
Instance Deletion

C synopsis target-domain
Void HeapTrack_delete(HeapTrack_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void HeapTrack_destruct(HeapTrack_Struct *structP);
// Finalize the instance object inside the provided structure
 
HeapTrack_alloc()  // instance

Allocates a block of memory from the heap

C synopsis target-domain
Ptr HeapTrack_alloc(HeapTrack_Handle handle, SizeT size, SizeT align, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created HeapTrack instance object
size — size (in MADUs) of the block
align — alignment (in MADUs) of the block
eb — pointer to error block
DETAILS
This method returns a block of memory from the heap. It is called by the xdc.runtime.Memory.alloc() function.
RETURNS
Returns the address of the allocated memory.
 
HeapTrack_free()  // instance

Free a block of memory back to the heap

C synopsis target-domain
Void HeapTrack_free(HeapTrack_Handle handle, Ptr block, SizeT size);
 
ARGUMENTS
handle — handle of a previously-created HeapTrack instance object
block — non-NULL address of allocated block to free
size — size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap. It is called by the xdc.runtime.Memory.free() function.
 
HeapTrack_getStats()  // instance

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapTrack_getStats(HeapTrack_Handle handle, Memory_Stats *stats);
 
ARGUMENTS
handle — handle of a previously-created HeapTrack instance object
stats — non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a xdc.runtime.Memory.Stats structure and getStats fills in this structure.
This function is called by the xdc.runtime.Memory.getStats() function.
 
HeapTrack_isBlocking()  // instance

Returns whether the heap may block during an alloc() or free()

C synopsis target-domain
Bool HeapTrack_isBlocking(HeapTrack_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created HeapTrack instance object
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
 
HeapTrack_printHeap()  // instance

Print details for a HeapTrack instance

C synopsis target-domain
Void HeapTrack_printHeap(HeapTrack_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created HeapTrack instance object
DETAILS
Print the details of all allocated blocks of memory for a HeapTrack instance. This function is not thread safe.
Instance Convertors

C synopsis target-domain
IHeap_Handle HeapTrack_Handle_upCast(HeapTrack_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
HeapTrack_Handle HeapTrack_Handle_downCast(IHeap_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int HeapTrack_Object_count();
// The number of statically-created instance objects
 
HeapTrack_Handle HeapTrack_Object_get(HeapTrack_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
HeapTrack_Handle HeapTrack_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
HeapTrack_Handle HeapTrack_Object_next(HeapTrack_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle HeapTrack_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *HeapTrack_Handle_label(HeapTrack_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String HeapTrack_Handle_name(HeapTrack_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/heaps/HeapTrack.xdc
var HeapTrack = xdc.useModule('ti.sysbios.heaps.HeapTrack');
module-wide constants & types
        obj.scribble = UInt32  ...
        obj.queElem = Queue.Elem  ...
        obj.size = SizeT  ...
        obj.tick = UInt32  ...
        obj.taskHandle = Task.Handle  ...
module-wide config parameters
        msg: "A_bufOverflow: Buffer overflow"
    };
        msg: "A_doubleFree: Buffer already free"
    };
        msg: "A_notEmpty: Heap not empty"
    };
        msg: "A_nullObject: HeapTrack_printHeap called with null obj"
    };
 
per-instance config parameters
    var params = new HeapTrack.Params// Instance config-params object;
        params.heap// Heap to use with HeapTrack = IHeap.Handle null;
per-instance creation
    var inst = HeapTrack.create// Create an instance-object(params);
 
 
struct HeapTrack.Tracker

Structure added to the end of each allocated block

Configuration settings
var obj = new HeapTrack.Tracker;
 
    obj.scribble = UInt32  ...
    obj.queElem = Queue.Elem  ...
    obj.size = SizeT  ...
    obj.tick = UInt32  ...
    obj.taskHandle = Task.Handle  ...
 
DETAILS
When a block is allocated from a HeapTrack heap with a size, internally HeapTrack calls Memory_alloc on the configured heap. The value of sizeof(HeapTrack_Tracker) is added to the requested size.
For example, if the caller makes the following call (where heapHandle is an HeapTrack handle that has been converted to an IHeap_Handle).
  buf = Memory_alloc(heapHandle, MYSIZE, MYALIGN, &eb);
Internally, HeapTrack will make the following call (where size is MYSIZE, align is MYALIGN and obj is the HeapTrack handle).
  block = Memory_alloc(obj->heap, size + sizeof(HeapTrack_Tracker), align, &eb);
When using HeapTrack, depending on the actual heap (i.e. heap), you might need to make adjustments to the heap (e.g. increase the blockSize if using a HeapBuf instance).
The HeapTrack module manages the contents of this structure and should not be directly accessing them.
C SYNOPSIS
 
config HeapTrack.A_bufOverflow  // module-wide

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

Configuration settings
HeapTrack.A_bufOverflow = Assert.Desc {
    msg: "A_bufOverflow: Buffer overflow"
};
 
C SYNOPSIS
 
config HeapTrack.A_doubleFree  // module-wide

Assert raised when freeing a buffer that was already freed

Configuration settings
HeapTrack.A_doubleFree = Assert.Desc {
    msg: "A_doubleFree: Buffer already free"
};
 
C SYNOPSIS
 
config HeapTrack.A_notEmpty  // module-wide

Assert raised when deleting a non-empty heap

Configuration settings
HeapTrack.A_notEmpty = Assert.Desc {
    msg: "A_notEmpty: Heap not empty"
};
 
C SYNOPSIS
 
config HeapTrack.A_nullObject  // module-wide

Assert raised when calling printTask with a null HeapTrack object

Configuration settings
HeapTrack.A_nullObject = Assert.Desc {
    msg: "A_nullObject: HeapTrack_printHeap called with null obj"
};
 
C SYNOPSIS
 
metaonly config HeapTrack.common$  // module-wide

Common module configuration parameters

Configuration settings
HeapTrack.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters

Configuration settings
var params = new HeapTrack.Params;
// Instance config-params object
    params.heap = IHeap.Handle null;
    // Heap to use with HeapTrack
 
config HeapTrack.Params.heap  // instance

Heap to use with HeapTrack

Configuration settings
var params = new HeapTrack.Params;
  ...
params.heap = IHeap.Handle null;
 
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new HeapTrack.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = HeapTrack.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
generated on Tue, 09 Oct 2018 20:57:31 GMT