module ti.sysbios.heaps.HeapMem

Variable size buffer heap manager

HeapMem manager provides functions to allocate and free storage from a heap of type HeapMem which inherits from IHeap. [ more ... ]
XDCspec summary sourced in ti/sysbios/heaps/HeapMem.xdc
@Gated @ModuleStartup
module HeapMem {  ...
// inherits xdc.runtime.IHeap
    // inherits xdc.runtime.IModule
instance:  ...
C synopsis target-domain
#include <ti/sysbios/heaps/HeapMem.h>
module-wide constants & types
        Ptr buf;
        SizeT size;
module-wide config parameters
module-wide built-ins
per-instance object types
 
per-instance config parameters
        IInstance_Params *instance;
    } HeapMem_Params;
 
per-instance creation
per-instance deletion
per-instance functions
    Ptr HeapMem_alloc// Allocates a block of memory from the heap( HeapMem_Handle handle, SizeT size, SizeT align, Error_Block *eb );
    Void HeapMem_free// Free a block of memory back to the heap( HeapMem_Handle handle, Ptr block, SizeT size );
    Void HeapMem_restore// ( HeapMem_Handle handle );
per-instance convertors
per-instance built-ins
 
XDCscript usage meta-domain
var HeapMem = xdc.useModule('ti.sysbios.heaps.HeapMem');
module-wide constants & types
        obj.buf = Ptr  ...
        obj.size = SizeT  ...
 
    var obj = new HeapMem.FreeBlockView// ;
        obj.address = String  ...
        obj.label = String  ...
        obj.size = String  ...
module-wide config parameters
        msg: "A_align: Requested align is not a power of 2"
    };
        msg: "A_heapSize: Requested heap size is too small"
    };
        msg: "A_invalidFree: Invalid free"
    };
        msg: "A_zeroBlock: Cannot allocate size 0"
    };
 
per-instance config parameters
    var params = new HeapMem.Params// Instance config-params object;
        params.buf// Buffer being managed by this heap instance = Ptr 0;
per-instance creation
    var inst = HeapMem.create// Create an instance-object( params );
 
XDCspec declarations sourced in ti/sysbios/heaps/HeapMem.xdc
package ti.sysbios.heaps;
 
@Gated @ModuleStartup
module HeapMem inherits IHeap {
module-wide constants & types
        Ptr buf;
        SizeT size;
    };
 
    metaonly struct FreeBlockView//  {
        String address;
        String label;
        String size;
    };
module-wide config parameters
        msg: "A_align: Requested align is not a power of 2"
    };
        msg: "A_heapSize: Requested heap size is too small"
    };
        msg: "A_invalidFree: Invalid free"
    };
        msg: "A_zeroBlock: Cannot allocate size 0"
    };
 
 
 
instance:
per-instance config parameters
 
per-instance creation
per-instance functions
    override Ptr alloc// Allocates a block of memory from the heap( SizeT size, SizeT align, Error.Block *eb );
    override Void free// Free a block of memory back to the heap( Ptr block, SizeT size );
    Void getExtendedStats// ( HeapMem.ExtendedStats *stats );
    Void restore// ( );
}
DETAILS
HeapMem manager provides functions to allocate and free storage from a heap of type HeapMem which inherits from IHeap.

HeapMem Gate

A HeapMem instance will use the HeapMem module Gate to protect any accesses to its list of free memory blocks. The HeapMem instance will enter and leave the module Gate when allocating blocks, freeing blocks, and retrieving statistics about the HeapMem. By default, the Gate is of type GateMutex. A different Gate can be specified using the common$.gate parameter. For example, to use a GateTask to protect HeapMem: HeapMem.common$.gate = GateTask.create(); To save on overhead, HeapMem does not create additional Gate instances on a per-instance basis; there is only one Gate instance shared across all of the HeapMem instances. Therefore, the HeapMem.common$.gateParams parameter (used for configuring per-instance Gates) is ignored. The type of Gate used should be chosen based on the type of threads (Hwi, Swi, Task, etc.) using the heap. It should also consider the non-deterministic nature of the HeapMem. A call to alloc or free will traverse a list of free blocks, so a GateHwi, for example, is likely an inappropriate Gate for HeapMem.

Calling Context

Function Hwi Swi Task Main Startup
Params_init Y Y Y Y Y
alloc N** N** Y** Y N
construct Y Y Y Y N
create N* N* Y Y N
delete N* N* Y Y N
destruct Y Y Y Y N
free N** N** Y** Y N
getExtendedStats Y Y Y Y N
getStats N** N** Y** Y N
isBlocking Y Y Y Y N
restore Y+ Y+ Y+ Y N
Definitions:
  • Hwi: API is callable from a Hwi thread.
  • Swi: API is callable from a Swi thread.
  • Task: API is callable from a Task thread.
  • Main: API is callable during any of these phases:
    • In your module startup after this module is started (e.g. HeapMem_Module_startupDone() returns TRUE).
    • During xdc.runtime.Startup.lastFxns.
    • During main().
    • During BIOS.startupFxns.
  • Startup: API is callable during any of these phases:
    • During xdc.runtime.Startup.firstFxns.
    • In your module startup before this module is started (e.g. HeapMem_Module_startupDone() returns FALSE).
  • * : Assuming blocking Heap is used for creation.
  • **: Assuming GateMutex is used as HeapMem's Gate.
  • + : Cannot use HeapMem object while it is being restored.
 
struct HeapMem.ExtendedStats

Stats structure for the getExtendedStats API

XDCscript usage meta-domain
var obj = new HeapMem.ExtendedStats;
 
    obj.buf = Ptr  ...
    obj.size = SizeT  ...
C synopsis target-domain
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.
 
metaonly struct HeapMem.FreeBlockView
XDCscript usage meta-domain
var obj = new HeapMem.FreeBlockView;
 
    obj.address = String  ...
    obj.label = String  ...
    obj.size = String  ...
 
 
config HeapMem.A_align  // module-wide

Assert raised when the requested alignment is not a power of 2

XDCscript usage meta-domain
HeapMem.A_align = Assert.Desc {
    msg: "A_align: Requested align is not a power of 2"
};
C synopsis target-domain
extern const Assert_Id HeapMem_A_align;
 
 
config HeapMem.A_heapSize  // module-wide

Assert raised when the requested heap size is too small

XDCscript usage meta-domain
HeapMem.A_heapSize = Assert.Desc {
    msg: "A_heapSize: Requested heap size is too small"
};
C synopsis target-domain
extern const Assert_Id HeapMem_A_heapSize;
 
 
config HeapMem.A_invalidFree  // module-wide

Assert raised when the free detects that an invalid addr or size

XDCscript usage meta-domain
HeapMem.A_invalidFree = Assert.Desc {
    msg: "A_invalidFree: Invalid free"
};
C synopsis target-domain
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

XDCscript usage meta-domain
HeapMem.A_zeroBlock = Assert.Desc {
    msg: "A_zeroBlock: Cannot allocate size 0"
};
C synopsis target-domain
extern const Assert_Id HeapMem_A_zeroBlock;
 
 
metaonly config HeapMem.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
HeapMem.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.
 
module-wide built-ins

C synopsis target-domain
Types_ModuleId HeapMem_Module_id( );
// Get this module's unique id
 
Bool HeapMem_Module_startupDone( );
// Test if this module has completed startup
 
IHeap_Handle HeapMem_Module_heap( );
// 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
 
per-instance object types

C synopsis target-domain
typedef struct HeapMem_Object HeapMem_Object;
// Opaque internal representation of an instance object
 
typedef HeapMem_Object *HeapMem_Handle;
// Client reference to an instance object
 
typedef struct HeapMem_Struct HeapMem_Struct;
// Opaque client structure large enough to hold an instance object
 
HeapMem_Handle HeapMem_handle( HeapMem_Struct *structP );
// Convert this instance structure pointer into an instance handle
 
HeapMem_Struct *HeapMem_struct( HeapMem_Handle handle );
// Convert this instance handle into an instance structure pointer
 
per-instance config parameters

XDCscript usage meta-domain
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.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
C synopsis target-domain
typedef struct HeapMem_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Ptr buf;
    // Buffer being managed by this heap instance
    Memory_Size size;
    // Size of buffer being managed by this heap instance
} HeapMem_Params;
 
Void HeapMem_Params_init( HeapMem_Params *params );
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config HeapMem.buf  // per-instance

Buffer being managed by this heap instance

XDCscript usage meta-domain
var params = new HeapMem.Params;
  ...
params.buf = Ptr 0;
C synopsis target-domain
struct HeapMem_Params {
      ...
    Ptr buf;
 
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 neccessary to satisfy this requirement.
 
config HeapMem.size  // per-instance

Size of buffer being managed by this heap instance

XDCscript usage meta-domain
var params = new HeapMem.Params;
  ...
params.size = UArg 0;
C synopsis target-domain
struct HeapMem_Params {
      ...
    Memory_Size size;
 
DETAILS
The usable size may be smaller depending on alignment requirements.
 
metaonly config HeapMem.align  // per-instance

Alignment of the buffer being managed by this heap instance

XDCscript usage meta-domain
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 neccessary to satisfy this requirement.
The default alignment is 0.
 
metaonly config HeapMem.sectionName  // per-instance

Section name for the buffer managed by the instance

XDCscript usage meta-domain
var params = new HeapMem.Params;
  ...
params.sectionName = String null;
 
DETAILS
The default section is the 'dataSection' in the platform.
 
per-instance creation

XDCscript usage meta-domain
var params = new HeapMem.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = HeapMem.create( params );
// Create an instance-object
C synopsis target-domain
HeapMem_Handle HeapMem_create( const HeapMem_Params *params, Error_Block *eb );
// Allocate and initialize a new instance object and return its handle
 
Void HeapMem_construct( HeapMem_Struct *structP, const HeapMem_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.
 
per-instance deletion

C synopsis target-domain
Void HeapMem_delete( HeapMem_Handle *handleP );
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void HeapMem_destruct( HeapMem_Struct *structP );
// Finalize the instance object inside the provided structure
 
HeapMem.alloc( )  // per-instance

Allocates a block of memory from the heap

C synopsis target-domain
Ptr HeapMem_alloc( HeapMem_Handle handle, SizeT size, SizeT align, Error_Block *eb );
 
ARGUMENTS
handle — handle of a previously-created HeapMem 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.
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.
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 unalloccated space. This is because the largest free memory block may be smaller than total amount of unallocated memory.
RETURNS
Returns the address of the allocated memory.
HEAPMEM
The actual block returned may be larger than requested to satisfy alignment requirements.
 
HeapMem.free( )  // per-instance

Free a block of memory back to the heap

C synopsis target-domain
Void HeapMem_free( HeapMem_Handle handle, Ptr block, SizeT size );
 
ARGUMENTS
handle — handle of a previously-created HeapMem 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.
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.getExtendedStats( )  // per-instance
C synopsis target-domain
Void HeapMem_getExtendedStats( HeapMem_Handle handle, HeapMem_ExtendedStats *stats );
 
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
Retrieves the extended statistics for a HeapMem instance.
 
HeapMem.getStats( )  // per-instance

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapMem_getStats( HeapMem_Handle handle, Memory_Stats *stats );
 
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( )  // per-instance

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

C synopsis target-domain
Bool HeapMem_isBlocking( HeapMem_Handle handle );
 
ARGUMENTS
handle — handle of a previously-created HeapMem instance object
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
HEAPMEM
This function queries the gate (as specified by 'HeapMem.common$.gate') to determine if the alloc/free can be blocking.
 
HeapMem.restore( )  // per-instance
C synopsis target-domain
Void HeapMem_restore( HeapMem_Handle handle );
 
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.
HEAPMEM
Restores an instance to it's original created state.
 
per-instance convertors

C synopsis target-domain
IHeap_Handle HeapMem_Handle_upCast( HeapMem_Handle handle );
// unconditionally move one level up the inheritance hierarchy
 
HeapMem_Handle HeapMem_Handle_downCast( IHeap_Handle handle );
// conditionally move one level down the inheritance hierarchy; NULL upon failure
 
per-instance built-ins

C synopsis target-domain
Int HeapMem_Object_count( );
// The number of statically-created instance objects
 
HeapMem_Handle HeapMem_Object_get( HeapMem_Object *array, Int i );
// The handle of the i-th statically-created instance object (array == NULL)
 
HeapMem_Handle HeapMem_Object_first( );
// The handle of the first dynamically-created instance object, or NULL
 
HeapMem_Handle HeapMem_Object_next( HeapMem_Handle handle );
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle HeapMem_Object_heap( );
// The heap used to allocate dynamically-created instance objects
 
Types_Label *HeapMem_Handle_label( HeapMem_Handle handle, Types_Label *buf );
// The label associated with this instance object
 
String HeapMem_Handle_name( HeapMem_Handle handle );
// The name of this instance object
generated on Mon, 21 Dec 2009 19:43:42 GMT