This module has a common header that can be found in the
ti.ipc
package. Application code should include the common header file (not the
RTSC-generated one):
#include <ti/ipc/HeapBufMP.h>
The RTSC module must be used in the application's RTSC configuration file
(.cfg) if runtime APIs will be used in the application:
HeapBufMP = xdc.useModule('ti.sdo.ipc.heaps.HeapBufMP');
Documentation for all runtime APIs, instance configuration parameters,
error codes macros and type definitions available to the application
integrator can be found in the
Doxygen documenation
for the IPC product. However, the documentation presented on this page
should be referred to for information specific to the RTSC module, such as
module configuration, Errors, and Asserts.
It is important to note that allocation tracking is disabled by default in
trackAllocs. Disabling allocation tracking improves alloc/free
performance especially when cache calls are required in shared memory.
config HeapBufMP_A_badAlignment // module-wide |
|
Assert raised when freeing a block that isn't aligned properly
extern const Assert_Id HeapBufMP_A_badAlignment;
config HeapBufMP_A_invBlockFreed // module-wide |
|
Assert raised when freeing a block that is not in the buffer's range
extern const Assert_Id HeapBufMP_A_invBlockFreed;
config HeapBufMP_E_alignTooLarge // module-wide |
|
Error raised when a requested alignment is too large
extern const Error_Id HeapBufMP_E_alignTooLarge;
config HeapBufMP_E_exactFail // module-wide |
|
Error raised when exact matching failed
extern const Error_Id HeapBufMP_E_exactFail;
config HeapBufMP_E_noBlocksLeft // module-wide |
|
Error raised when there are no more blocks left in the buffer
extern const Error_Id HeapBufMP_E_noBlocksLeft;
config HeapBufMP_E_sizeTooLarge // module-wide |
|
Error raised when a requested alloc size is too large
extern const Error_Id HeapBufMP_E_sizeTooLarge;
config HeapBufMP_maxNameLen // module-wide |
|
Maximum length for heap names
extern const UInt HeapBufMP_maxNameLen;
config HeapBufMP_trackAllocs // module-wide |
|
Track the number of allocated blocks
extern const Bool HeapBufMP_trackAllocs;
DETAILS
This will enable/disable the tracking of the current and maximum number
of allocations for a HeapBufMP instance. This maximum refers to the
"all time" maximum number of allocations for the history of a HeapBufMP
instance.
Tracking allocations might adversely affect performance when allocating
and/or freeing. This is especially true if cache is enabled for the
shared region. If this feature is not needed, setting this to false
avoids the performance penalty.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool HeapBufMP_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool HeapBufMP_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapBufMP_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapBufMP_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct HeapBufMP_Object HeapBufMP_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapBufMP_Struct HeapBufMP_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 HeapBufMP_Params {
// Instance config-params structure
// Common per-instance configs
SizeT align;
// Alignment (in MAUs) of each block
SizeT blockSize;
// Size (in MAUs) of each block
Bool exact;
// Use exact matching
// GateMP used for critical region management of the shared memory
String name;
// Name of this instance
UInt numBlocks;
// Number of fixed-size blocks
UInt16 regionId;
// Shared region ID
} HeapBufMP_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapBufMP_Params.align // instance |
|
Alignment (in MAUs) of each block
DETAILS
The alignment must be a power of 2. If the value 0 is specified,
the value will be changed to meet the minimum structure alignment
requirements (refer to
xdc.runtime.Memory.getMaxDefaultTypeAlign and
xdc.runtime.Memory.getMaxDefaultTypeAlignMeta and
the cache alignment size of the region in which the heap will
be placed. Therefore, the actual alignment may be larger.
The default alignment is 0.
config HeapBufMP_Params.blockSize // instance |
|
Size (in MAUs) of each block
DETAILS
HeapBufMP will round the blockSize up to the nearest multiple of the
alignment, so the actual blockSize may be larger. When creating a
HeapBufMP dynamically, this needs to be taken into account to determine
the proper buffer size to pass in.
Required parameter.
The default size of the blocks is 0 MAUs.
config HeapBufMP_Params.exact // instance |
|
Use exact matching
DETAILS
Setting this flag will allow allocation only if the requested size
is equal to (rather than less than or equal to) the buffer's block
size.
config HeapBufMP_Params.gate // instance |
|
GateMP used for critical region management of the shared memory
DETAILS
Using the default value of NULL will result in use of the GateMP
system gate for context protection.
config HeapBufMP_Params.name // instance |
|
Name of this instance
DETAILS
The name (if not NULL) must be unique among all HeapBufMP
instances in the entire system. When creating a new
heap, it is necessary to supply an instance name.
config HeapBufMP_Params.numBlocks // instance |
|
Number of fixed-size blocks
DETAILS
This is a required parameter for all new HeapBufMP instances.
config HeapBufMP_Params.regionId // instance |
|
Shared region ID
DETAILS
The index corresponding to the shared region from which shared memory
will be allocated.
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
HeapBufMP_alloc() // instance |
|
Allocates a block of memory from the heap
ARGUMENTS
handle
handle of a previously-created HeapBufMP 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.
HeapBufMP_free() // instance |
|
Free a block of memory back to the heap
ARGUMENTS
handle
handle of a previously-created HeapBufMP 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.
HeapBufMP_getStats() // instance |
|
Retrieve the statistics from the heap
ARGUMENTS
handle
handle of a previously-created HeapBufMP 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.
HeapBufMP_isBlocking() // instance |
|
Returns whether the heap may block during an alloc() or
free()
ARGUMENTS
handle
handle of a previously-created HeapBufMP instance object
RETURNS
If the heap might block, TRUE is returned.
If the heap does not block, FALSE is returned.
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 HeapBufMP_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
config HeapBufMP.A_badAlignment // module-wide |
|
Assert raised when freeing a block that isn't aligned properly
msg: "A_badAlignment: Block being freed is not aligned properly "
};
C SYNOPSIS
config HeapBufMP.A_invBlockFreed // module-wide |
|
Assert raised when freeing a block that is not in the buffer's range
msg: "A_invBlockFreed: Invalid block being freed"
};
C SYNOPSIS
config HeapBufMP.E_alignTooLarge // module-wide |
|
Error raised when a requested alignment is too large
msg: "E_alignTooLarge: Requested alignment size of %u is greater than %u"
};
C SYNOPSIS
config HeapBufMP.E_exactFail // module-wide |
|
Error raised when exact matching failed
msg: "E_exactFail: Exact allocation failed (requested size = %u and buffer size = %u)"
};
C SYNOPSIS
config HeapBufMP.E_noBlocksLeft // module-wide |
|
Error raised when there are no more blocks left in the buffer
msg: "E_noBlocksLeft: No more blocks left in buffer (handle = 0x%x, requested size = %u)"
};
C SYNOPSIS
config HeapBufMP.E_sizeTooLarge // module-wide |
|
Error raised when a requested alloc size is too large
msg: "E_sizeTooLarge: Requested alloc size of %u is greater than %u"
};
C SYNOPSIS
config HeapBufMP.maxNameLen // module-wide |
|
Maximum length for heap names
HeapBufMP.maxNameLen = UInt 32;
C SYNOPSIS
config HeapBufMP.trackAllocs // module-wide |
|
Track the number of allocated blocks
HeapBufMP.trackAllocs = Bool false;
DETAILS
This will enable/disable the tracking of the current and maximum number
of allocations for a HeapBufMP instance. This maximum refers to the
"all time" maximum number of allocations for the history of a HeapBufMP
instance.
Tracking allocations might adversely affect performance when allocating
and/or freeing. This is especially true if cache is enabled for the
shared region. If this feature is not needed, setting this to false
avoids the performance penalty.
C SYNOPSIS
metaonly config HeapBufMP.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.
metaonly config HeapBufMP.maxRuntimeEntries // module-wide |
|
Maximum runtime entries
DETAILS
Maximum number of HeapBufMP's that can be dynamically created and
added to the NameServer.
To minimize the amount of runtime allocation, this parameter allows
the pre-allocation of memory for the HeapBufMP's NameServer table.
The default is to allow growth (i.e. memory allocation when
creating a new instance).
metaonly config HeapBufMP.tableSection // module-wide |
|
Section name is used to place the names table
HeapBufMP.tableSection = String null;
DETAILS
The default value of NULL implies that no explicit placement is
performed.
Instance Config Parameters |
|
var params = new HeapBufMP.Params;
// Instance config-params object
params.align = SizeT 0;
// Alignment (in MAUs) of each block
params.blockSize = SizeT 0;
// Size (in MAUs) of each block
params.exact = Bool false;
// Use exact matching
// GateMP used for critical region management of the shared memory
params.name = String null;
// Name of this instance
params.numBlocks = UInt 0;
// Number of fixed-size blocks
params.regionId = UInt16 0;
// Shared region ID
config HeapBufMP.Params.align // instance |
|
Alignment (in MAUs) of each block
var params = new HeapBufMP.Params;
...
params.align = SizeT 0;
DETAILS
The alignment must be a power of 2. If the value 0 is specified,
the value will be changed to meet the minimum structure alignment
requirements (refer to
xdc.runtime.Memory.getMaxDefaultTypeAlign and
xdc.runtime.Memory.getMaxDefaultTypeAlignMeta and
the cache alignment size of the region in which the heap will
be placed. Therefore, the actual alignment may be larger.
The default alignment is 0.
C SYNOPSIS
config HeapBufMP.Params.blockSize // instance |
|
Size (in MAUs) of each block
var params = new HeapBufMP.Params;
...
params.blockSize = SizeT 0;
DETAILS
HeapBufMP will round the blockSize up to the nearest multiple of the
alignment, so the actual blockSize may be larger. When creating a
HeapBufMP dynamically, this needs to be taken into account to determine
the proper buffer size to pass in.
Required parameter.
The default size of the blocks is 0 MAUs.
C SYNOPSIS
config HeapBufMP.Params.exact // instance |
|
Use exact matching
var params = new HeapBufMP.Params;
...
params.exact = Bool false;
DETAILS
Setting this flag will allow allocation only if the requested size
is equal to (rather than less than or equal to) the buffer's block
size.
C SYNOPSIS
config HeapBufMP.Params.gate // instance |
|
GateMP used for critical region management of the shared memory
var params = new HeapBufMP.Params;
...
DETAILS
Using the default value of NULL will result in use of the GateMP
system gate for context protection.
C SYNOPSIS
config HeapBufMP.Params.name // instance |
|
Name of this instance
var params = new HeapBufMP.Params;
...
params.name = String null;
DETAILS
The name (if not NULL) must be unique among all HeapBufMP
instances in the entire system. When creating a new
heap, it is necessary to supply an instance name.
C SYNOPSIS
config HeapBufMP.Params.numBlocks // instance |
|
Number of fixed-size blocks
var params = new HeapBufMP.Params;
...
params.numBlocks = UInt 0;
DETAILS
This is a required parameter for all new HeapBufMP instances.
C SYNOPSIS
config HeapBufMP.Params.regionId // instance |
|
Shared region ID
var params = new HeapBufMP.Params;
...
params.regionId = UInt16 0;
DETAILS
The index corresponding to the shared region from which shared memory
will be allocated.
C SYNOPSIS
Static Instance Creation |
|
var params =
new HeapBufMP.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapBufMP.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.