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
typedef struct HeapTrack_Tracker {
UInt32 scribble;
SizeT size;
UInt32 tick;
} 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
extern const Assert_Id HeapTrack_A_bufOverflow;
config HeapTrack_A_doubleFree // module-wide |
|
Assert raised when freeing a buffer that was already freed
extern const Assert_Id HeapTrack_A_doubleFree;
config HeapTrack_A_notEmpty // module-wide |
|
Assert raised when deleting a non-empty heap
config HeapTrack_A_nullObject // module-wide |
|
Assert raised when calling printTask with a null HeapTrack object
extern const Assert_Id HeapTrack_A_nullObject;
HeapTrack_printTask() // module-wide |
|
Print out the blocks that are currently allocated by a task
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 |
|
// Get this module's unique id
Bool HeapTrack_Module_startupDone();
// Test if this module has completed startup
// 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 |
|
typedef struct HeapTrack_Object HeapTrack_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapTrack_Struct HeapTrack_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
|
typedef struct HeapTrack_Params {
// Instance config-params structure
// Common per-instance configs
// Heap to use with HeapTrack
} HeapTrack_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapTrack_Params.heap // instance |
|
Heap to use with HeapTrack
Runtime Instance Creation |
|
// Allocate and initialize a new instance object and return its handle
// 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 |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
HeapTrack_alloc() // instance |
|
Allocates a block of memory from the heap
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
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
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()
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
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 |
|
// unconditionally move one level up the inheritance hierarchy
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins |
|
Int HeapTrack_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object
struct HeapTrack.Tracker |
|
Structure added to the end of each allocated block
var obj = new HeapTrack.Tracker;
obj.scribble = UInt32 ...
obj.size = SizeT ...
obj.tick = UInt32 ...
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
msg: "A_bufOverflow: Buffer overflow"
};
C SYNOPSIS
config HeapTrack.A_doubleFree // module-wide |
|
Assert raised when freeing a buffer that was already freed
msg: "A_doubleFree: Buffer already free"
};
C SYNOPSIS
config HeapTrack.A_notEmpty // module-wide |
|
Assert raised when deleting a non-empty heap
msg: "A_notEmpty: Heap not empty"
};
C SYNOPSIS
config HeapTrack.A_nullObject // module-wide |
|
Assert raised when calling printTask with a null HeapTrack object
msg: "A_nullObject: HeapTrack_printHeap called with null obj"
};
C SYNOPSIS
metaonly config HeapTrack.common$ // module-wide |
|
Common module configuration parameters
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 |
|
var params = new HeapTrack.Params;
// Instance config-params object
// Heap to use with HeapTrack
config HeapTrack.Params.heap // instance |
|
Heap to use with HeapTrack
var params = new HeapTrack.Params;
...
C SYNOPSIS
Static Instance Creation |
|
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.