HeapMem manager provides functions to allocate and free storage from a
heap of type HeapMem which inherits from IHeap.
In addition to allowing multiple static HeapMem instances to be created
who's buffer placements and sizes are defined by their instance
configuration parameters,
HeapMem allows one Heap instance to be defined who's heap
memory is defined by buffer start and end symbols in the linker command
file. This singular Heap instance is referred to as the 'Primary Heap'.
struct HeapMem_ExtendedStats |
|
Stat structure for the HeapMem_getExtendedStats function
typedef struct HeapMem_ExtendedStats {
Ptr buf;
SizeT size;
} HeapMem_ExtendedStats;
FIELDS
buf
Base address of the internal buffer.
This may be different from the original buf
parameter due to alignment requirements.
size
Size of the internal buffer.
This may be different from the original size
parameter due to alignment requirements.
config HeapMem_A_align // module-wide |
|
Assert raised when the requested alignment is not a power of 2
config HeapMem_A_heapSize // module-wide |
|
Assert raised when the requested heap size is too small
config HeapMem_A_invalidFree // module-wide |
|
Assert raised when the free detects that an invalid addr or size
extern const Assert_Id HeapMem_A_invalidFree;
DETAILS
This could arise when multiple frees are done on the same buffer or
if corruption occurred.
This also could occur when an alloc is made with size N and the
free for this buffer specifies size M where M > N. Note: not every
case is detectable.
This assert can also be caused when passing an invalid addr to free
or if the size is causing the end of the buffer to be
out of the expected range.
config HeapMem_A_zeroBlock // module-wide |
|
Assert raised when a block of size 0 is requested
DETAILS
This error can also be raised if the requested size wraps
the contents of a SizeT type when it is adjusted for a minimum
alignment. For example, when SizeT is 16-bits and a size request
is made for 0xFFFB.
config HeapMem_E_memory // module-wide |
|
Raised when requested size exceeds largest free block
config HeapMem_primaryHeapBaseAddr // module-wide |
|
Base address of the 'Primary Heap' buffer
extern const Char *HeapMem_primaryHeapBaseAddr;
DETAILS
HeapMem allows one Heap instance to be defined who's heap
memory is defined by symbols in the linker command file.
This singular Heap instance is referred to as the 'Primary Heap'.
The following example will create a HeapMem instance whose
size and buffer will be determined at runtime based on the
values of the symbols __primary_heap_start__ and
__primary_heap_end__. It is assumed the user will define these
symbols in their linker command file.
var HeapMem = xdc.useModule('ti.sysbios.heaps.HeapMem');
HeapMem.primaryHeapBaseAddr = "&__primary_heap_start__";
HeapMem.primaryHeapEndAddr = "&__primary_heap_end__";
var heapMemParams = new HeapMem.Params;
heapMemParams.usePrimaryHeap = true;
var heap0 = HeapMem.create(heapMemParams);
config HeapMem_primaryHeapEndAddr // module-wide |
|
End address of the 'Primary Heap' buffer, plus one
extern const Char *HeapMem_primaryHeapEndAddr;
DETAILS
HeapMem.primaryHeapEndAddr = "&__primary_heap_end__";
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool HeapMem_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool HeapMem_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapMem_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapMem_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct HeapMem_Object HeapMem_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapMem_Struct HeapMem_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 HeapMem_Params {
// Instance config-params structure
// Common per-instance configs
Ptr buf;
// Buffer being managed by this heap instance
SizeT minBlockAlign;
// Minimum alignment for each block allocated
// Size of buffer being managed by this heap instance
} HeapMem_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapMem_Params.buf // instance |
|
Buffer being managed by this heap instance
DETAILS
This parameter is ignored in the static HeapMem.create() call. It is a
required parameter in the dynamic HeapMem_create() call.
HeapMem requires that the buffer be aligned on a target-specific minimum
alignment, and will adjust the buffer's start address and size as
necessary to satisfy this requirement.
config HeapMem_Params.minBlockAlign // instance |
|
Minimum alignment for each block allocated
DETAILS
This parameter dictates the minimum alignment for each
block that is allocated. If an alignment request of greater than
minBlockAlign is made in the alloc, it will be honored. If an
alignment request of less than minBlockAlign is made, the request will
be ignored and minBlockAlign will be used.
HeapMem_Params_init(&prms);
prms.minBlockAlign = 32;
handle = HeapMem_create(&prms, &eb);
...
// buf will be aligned on a 32 MAU boundary
buf = Memory_alloc(HeapMem_Handle_upCast(handle), SIZE, 8, &eb);
// buf will be aligned on a 64 MAU boundary
buf = Memory_alloc(HeapMem_Handle_upCast(handle), SIZE, 64, &eb);
The default alignment is 0 (which means this parameter is ignored).
config HeapMem_Params.size // instance |
|
Size of buffer being managed by this heap instance
DETAILS
The usable size may be smaller depending on alignment requirements.
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
HeapMem_alloc() // instance |
|
Allocates a block of memory from the heap
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
size
size (in MADUs) of the block
Requested size
align
alignment (in MADUs) of the block
Requested alignment
eb
pointer to error block
Error_Block used to denote location in case of a failure
RETURNS
allocated block or NULL is request cannot be honored
DETAILS
This method returns a block of memory from the heap.
It is called by the
xdc.runtime.Memory.alloc() function.
HeapMem_alloc() will lock the heap using the HeapMem Gate while it
traverses the list of free blocks to find a large enough block for
the request.
HeapMem_alloc() should not be called directly. Application code
should use Memory_alloc() with a HeapMem_Handle as the first
parameter. Among other things, Memory_alloc() makes sure that the
alignment parameter is greater than or equal to the minimum alignment
required for the HeapMem_Header data structure for a given C compiler
(8 bytes in most cases). HeapMem_alloc() may crash if you pass a
smaller alignment.
Guidelines for using large heaps and multiple alloc() calls.
- If possible, allocate larger blocks first. Previous
allocations of small memory blocks can reduce the size
of the blocks available for larger memory allocations.
- Realize that alloc() can fail even if the heap contains a
sufficient absolute amount of unallocated space. This is
because the largest free memory block may be smaller than
total amount of unallocated memory.
HEAPMEM
The actual block returned may be larger than requested to satisfy
alignment requirements, and its size will always be a multiple of
the size of the HeapMem_Header data structure (usually 8 bytes)
RETURNS
Returns the address of the allocated memory.
HeapMem_allocUnprotected() // instance |
|
Ptr HeapMem_allocUnprotected(
HeapMem_Handle handle,
SizeT size,
SizeT align);
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
size
Requested size
align
Requested alignment
RETURNS
allocated block or NULL is request cannot be honored
DETAILS
HeapMem_allocUnprotected() will
traverses the list of free blocks to find a large enough block for
the request.
The caller of this API must provider the thread-safety
of this call.
Guidelines for using large heaps and multiple alloc() calls.
- If possible, allocate larger blocks first. Previous
allocations of small memory blocks can reduce the size
of the blocks available for larger memory allocations.
- Realize that alloc() can fail even if the heap contains a
sufficient absolute amount of unallocated space. This is
because the largest free memory block may be smaller than
total amount of unallocated memory.
HEAPMEM
The actual block returned may be larger than requested to satisfy
alignment requirements
HeapMem_free() // instance |
|
Free a block of memory back to the heap
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
block
non-NULL address of allocated block to free
Block to be freed
size
size (in MADUs) of the block of memory to free
Size of block to free
DETAILS
This method gives back a block of memory to a heap.
It is called by the
xdc.runtime.Memory.free() function.
free() will lock the heap using the HeapMem Gate, if one is specified
using 'HeapMem.common$.gate'.
HEAPMEM
free() places the memory block specified by addr and size back into the
free pool of the heap specified. The newly freed block is combined with
any adjacent free blocks. The space is then available for further
allocation by alloc().
HeapMem_freeUnprotected() // instance |
|
Void HeapMem_freeUnprotected(
HeapMem_Handle handle,
Ptr block,
SizeT size);
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
block
Block to be freed
size
Size of block to free
DETAILS
The caller of this API must provider the thread-safety
of this call.
HEAPMEM
freeNoGate() places the memory block specified by addr and size back into the
free pool of the heap specified. The newly freed block is combined with
any adjacent free blocks. The space is then available for further
allocation by alloc().
HeapMem_getExtendedStats() // instance |
|
Retrieves the extended statistics for a HeapMem instance
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
stats
Location for the returned extended statistics.
DETAILS
This function retrieves the extended statistics for a HeapMem instance.
It does not retrieve the standard xdc.runtime.Memory.Stats information.
HeapMem_getStats() // instance |
|
Retrieve the statistics from the heap
ARGUMENTS
handle
handle of a previously-created HeapMem 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.
The returned totalSize reflects the usable size of the buffer, not
necessarily the size specified during create.
HEAPMEM
getStats() will lock the heap using the HeapMem Gate while it retrieves
the HeapMem's statistics.
HeapMem_isBlocking() // instance |
|
Returns whether the heap may block during an alloc() or
free()
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
HEAPMEM
This function queries the gate (as specified by 'HeapMem.common$.gate')
to determine if the alloc/free can be blocking.
RETURNS
If the heap might block, TRUE is returned.
If the heap does not block, FALSE is returned.
HeapMem_restore() // instance |
|
Restores an instance to its original created state
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
DETAILS
This function restores a static or dynamically created instance to
its original created state. Any memory previously allocated from the
heap is no longer valid after this API is called. This function
does not check whether there is allocated memory or not.
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 HeapMem_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 HeapMem.ExtendedStats |
|
Stat structure for the HeapMem_getExtendedStats function
var obj = new HeapMem.ExtendedStats;
obj.buf = Ptr ...
obj.size = SizeT ...
FIELDS
buf
Base address of the internal buffer.
This may be different from the original buf
parameter due to alignment requirements.
size
Size of the internal buffer.
This may be different from the original size
parameter due to alignment requirements.
C SYNOPSIS
config HeapMem.A_align // module-wide |
|
Assert raised when the requested alignment is not a power of 2
msg: "A_align: Requested align is not a power of 2"
};
C SYNOPSIS
config HeapMem.A_heapSize // module-wide |
|
Assert raised when the requested heap size is too small
msg: "A_heapSize: Requested heap size is too small"
};
C SYNOPSIS
config HeapMem.A_invalidFree // module-wide |
|
Assert raised when the free detects that an invalid addr or size
msg: "A_invalidFree: Invalid free"
};
DETAILS
This could arise when multiple frees are done on the same buffer or
if corruption occurred.
This also could occur when an alloc is made with size N and the
free for this buffer specifies size M where M > N. Note: not every
case is detectable.
This assert can also be caused when passing an invalid addr to free
or if the size is causing the end of the buffer to be
out of the expected range.
C SYNOPSIS
config HeapMem.A_zeroBlock // module-wide |
|
Assert raised when a block of size 0 is requested
msg: "A_zeroBlock: Cannot allocate size 0"
};
DETAILS
This error can also be raised if the requested size wraps
the contents of a SizeT type when it is adjusted for a minimum
alignment. For example, when SizeT is 16-bits and a size request
is made for 0xFFFB.
C SYNOPSIS
config HeapMem.E_memory // module-wide |
|
Raised when requested size exceeds largest free block
msg: "out of memory: handle=0x%x, size=%u"
};
C SYNOPSIS
config HeapMem.primaryHeapBaseAddr // module-wide |
|
Base address of the 'Primary Heap' buffer
HeapMem.primaryHeapBaseAddr = Char* null;
DETAILS
HeapMem allows one Heap instance to be defined who's heap
memory is defined by symbols in the linker command file.
This singular Heap instance is referred to as the 'Primary Heap'.
The following example will create a HeapMem instance whose
size and buffer will be determined at runtime based on the
values of the symbols __primary_heap_start__ and
__primary_heap_end__. It is assumed the user will define these
symbols in their linker command file.
var HeapMem = xdc.useModule('ti.sysbios.heaps.HeapMem');
HeapMem.primaryHeapBaseAddr = "&__primary_heap_start__";
HeapMem.primaryHeapEndAddr = "&__primary_heap_end__";
var heapMemParams = new HeapMem.Params;
heapMemParams.usePrimaryHeap = true;
var heap0 = HeapMem.create(heapMemParams);
C SYNOPSIS
config HeapMem.primaryHeapEndAddr // module-wide |
|
End address of the 'Primary Heap' buffer, plus one
HeapMem.primaryHeapEndAddr = Char* null;
DETAILS
HeapMem.primaryHeapEndAddr = "&__primary_heap_end__";
C SYNOPSIS
metaonly config HeapMem.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 HeapMem.Params;
// Instance config-params object
params.align = SizeT 0;
// Alignment of the buffer being managed by this heap instance
params.buf = Ptr 0;
// Buffer being managed by this heap instance
params.minBlockAlign = SizeT 0;
// Minimum alignment for each block allocated
params.sectionName = String null;
// Section name for the buffer managed by the instance
params.size = UArg 0;
// Size of buffer being managed by this heap instance
params.usePrimaryHeap = Bool false;
config HeapMem.Params.buf // instance |
|
Buffer being managed by this heap instance
var params = new HeapMem.Params;
...
params.buf = Ptr 0;
DETAILS
This parameter is ignored in the static HeapMem.create() call. It is a
required parameter in the dynamic HeapMem_create() call.
HeapMem requires that the buffer be aligned on a target-specific minimum
alignment, and will adjust the buffer's start address and size as
necessary to satisfy this requirement.
C SYNOPSIS
config HeapMem.Params.minBlockAlign // instance |
|
Minimum alignment for each block allocated
var params = new HeapMem.Params;
...
params.minBlockAlign = SizeT 0;
DETAILS
This parameter dictates the minimum alignment for each
block that is allocated. If an alignment request of greater than
minBlockAlign is made in the alloc, it will be honored. If an
alignment request of less than minBlockAlign is made, the request will
be ignored and minBlockAlign will be used.
HeapMem_Params_init(&prms);
prms.minBlockAlign = 32;
handle = HeapMem_create(&prms, &eb);
...
// buf will be aligned on a 32 MAU boundary
buf = Memory_alloc(HeapMem_Handle_upCast(handle), SIZE, 8, &eb);
// buf will be aligned on a 64 MAU boundary
buf = Memory_alloc(HeapMem_Handle_upCast(handle), SIZE, 64, &eb);
The default alignment is 0 (which means this parameter is ignored).
C SYNOPSIS
config HeapMem.Params.size // instance |
|
Size of buffer being managed by this heap instance
var params = new HeapMem.Params;
...
params.size = UArg 0;
DETAILS
The usable size may be smaller depending on alignment requirements.
C SYNOPSIS
metaonly config HeapMem.Params.align // instance |
|
Alignment of the buffer being managed by this heap instance
var params = new HeapMem.Params;
...
params.align = SizeT 0;
DETAILS
In the static HeapMem.create() call, the buffer allocated for the
HeapMem instance will have the alignment specified by this parameter.
In the dynamic case, the client must supply the buffer, so it is the
client's responsibility to manage the buffer's alignment, and there is
no 'align' parameter.
The specified alignment must be a power of 2.
HeapMem requires that the buffer be aligned on a target-specific minimum
alignment, and will adjust (round up) the requested alignment as
necessary to satisfy this requirement.
The default alignment is 0.
metaonly config HeapMem.Params.sectionName // instance |
|
Section name for the buffer managed by the instance
var params = new HeapMem.Params;
...
params.sectionName = String null;
DETAILS
The default section is the 'dataSection' in the platform.
metaonly config HeapMem.Params.usePrimaryHeap // instance |
|
Use primaryHeapBaseAddr and primaryHeapEndAddr
to define the Heap buffer managed by this static instance
var params = new HeapMem.Params;
...
params.usePrimaryHeap = Bool false;
WARNING
This instance parameter only exists for statically defined
HeapMem objects and can only be set to true in the creation
of one static HeapMem object!
Static Instance Creation |
|
var params =
new HeapMem.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapMem.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.