The RTSC module must be used in the application's RTSC configuration file
(.cfg) if runtime APIs will be used in the application:
Documentation for all runtime APIs, instance configuration parameters,
error codes macros and type definitions available to the application
integrator can be found in the
<A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
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.
config HeapBufMP.A_invBlockFreed // module-wide |
 |
Assert raised when freeing a block that is not in the buffer's range
XDCscript usage |
meta-domain |
msg: "A_invBlockFreed: Invalid block being freed"
};
extern const Assert_Id HeapBufMP_A_invBlockFreed;
config HeapBufMP.E_alignTooLarge // module-wide |
 |
Error raised when a requested alignment is too large
XDCscript usage |
meta-domain |
msg: "E_alignTooLarge: Requested alignment size of %d is greater than %d"
};
extern const Error_Id HeapBufMP_E_alignTooLarge;
config HeapBufMP.E_exactFail // module-wide |
 |
Error raised when exact matching failed
XDCscript usage |
meta-domain |
msg: "E_exactFail: Exact allocation failed (requested size = 0x%x and buffer size = 0x%x)"
};
extern const Error_Id HeapBufMP_E_exactFail;
config HeapBufMP.E_sizeTooLarge // module-wide |
 |
Error raised when a requested alloc size is too large
XDCscript usage |
meta-domain |
msg: "E_sizeTooLarge: Requested alloc size of 0x%x is greater than 0x%x"
};
extern const Error_Id HeapBufMP_E_sizeTooLarge;
config HeapBufMP.maxNameLen // module-wide |
 |
Maximum length for heap names
XDCscript usage |
meta-domain |
HeapBufMP.maxNameLen = UInt 32;
extern const UInt HeapBufMP_maxNameLen;
config HeapBufMP.trackAllocs // module-wide |
 |
Track the number of allocated blocks
XDCscript usage |
meta-domain |
HeapBufMP.trackAllocs = Bool false;
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.
metaonly config HeapBufMP.common$ // module-wide |
 |
Common module configuration parameters
XDCscript usage |
meta-domain |
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
XDCscript usage |
meta-domain |
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
XDCscript usage |
meta-domain |
HeapBufMP.tableSection = String null;
DETAILS
The default value of NULL implies that no explicit placement is
performed.
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
per-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
per-instance config parameters |
 |
XDCscript usage |
meta-domain |
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.openFlag = Bool false;
//
params.regionId = UInt32 0;
// Shared region ID
params.sharedAddr = Ptr null;
//
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
Bool openFlag;
//
UInt32 regionId;
// Shared region ID
Ptr sharedAddr;
//
} HeapBufMP_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapBufMP.align // per-instance |
 |
Alignment (in MAUs) of each block
XDCscript usage |
meta-domain |
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.
config HeapBufMP.blockSize // per-instance |
 |
Size (in MAUs) of each block
XDCscript usage |
meta-domain |
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.
config HeapBufMP.exact // per-instance |
 |
Use exact matching
XDCscript usage |
meta-domain |
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.
config HeapBufMP.gate // per-instance |
 |
GateMP used for critical region management of the shared memory
XDCscript usage |
meta-domain |
var params = new HeapBufMP.Params;
...
DETAILS
Using the default value of NULL will result in use of the GateMP
system gate for context protection.
config HeapBufMP.name // per-instance |
 |
Name of this instance
XDCscript usage |
meta-domain |
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.
config HeapBufMP.numBlocks // per-instance |
 |
Number of fixed-size blocks
XDCscript usage |
meta-domain |
var params = new HeapBufMP.Params;
...
params.numBlocks = UInt 0;
DETAILS
This is a required parameter for all new HeapBufMP instances.
config HeapBufMP.regionId // per-instance |
 |
Shared region ID
XDCscript usage |
meta-domain |
var params = new HeapBufMP.Params;
...
params.regionId = UInt32 0;
DETAILS
The index corresponding to the shared region from which shared memory
will be allocated.
per-instance creation |
 |
XDCscript usage |
meta-domain |
var params =
new HeapBufMP.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapBufMP.create( params );
// Create an instance-object
// 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.
per-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( ) // per-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( ) // per-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( ) // per-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( ) // per-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.
per-instance convertors |
 |
// unconditionally move one level up the inheritance hierarchy
// conditionally move one level down the inheritance hierarchy; NULL upon failure
per-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