module ti.sdo.ipc.heaps.HeapBufMP

Multi-processor fixed-size buffer heap implementation

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): [ more ... ]
XDCspec summary sourced in ti/sdo/ipc/heaps/HeapBufMP.xdc
module HeapBufMP {  ...
// inherits xdc.runtime.IHeap
    // inherits xdc.runtime.IModule
instance:  ...
C synopsis target-domain
#include <ti/sdo/ipc/heaps/HeapBufMP.h>
module-wide config parameters
module-wide built-ins
per-instance object types
 
per-instance config parameters
        IInstance_Params *instance;
        Bool exact// Use exact matching;
        String name// Name of this instance;
        Bool openFlag// ;
        UInt32 regionId// Shared region ID;
        Ptr sharedAddr// ;
    } HeapBufMP_Params;
 
per-instance creation
per-instance deletion
per-instance functions
    Ptr HeapBufMP_alloc// Allocates a block of memory from the heap( HeapBufMP_Handle handle, SizeT size, SizeT align, Error_Block *eb );
    Void HeapBufMP_free// Free a block of memory back to the heap( HeapBufMP_Handle handle, Ptr block, SizeT size );
per-instance convertors
per-instance built-ins
 
XDCscript usage meta-domain
var HeapBufMP = xdc.useModule('ti.sdo.ipc.heaps.HeapBufMP');
module-wide config parameters
        msg: "A_invBlockFreed: Invalid block being freed"
    };
        msg: "E_alignTooLarge: Requested alignment size of %d is greater than %d"
    };
        msg: "E_exactFail: Exact allocation failed (requested size = 0x%x and buffer size = 0x%x)"
    };
        msg: "E_sizeTooLarge: Requested alloc size of 0x%x is greater than 0x%x"
    };
 
per-instance config parameters
    var params = new HeapBufMP.Params// Instance config-params object;
        params.align// Alignment (in MAUs) of each block = SizeT 0;
        params.blockSize// Size (in MAUs) of each block = SizeT 0;
        params.exact// Use exact matching = Bool false;
        params.name// Name of this instance = String null;
        params.numBlocks// Number of fixed-size blocks = UInt 0;
        params.openFlag//  = Bool false;
        params.regionId// Shared region ID = UInt32 0;
        params.sharedAddr//  = Ptr null;
per-instance creation
    var inst = HeapBufMP.create// Create an instance-object( params );
 
XDCspec declarations sourced in ti/sdo/ipc/heaps/HeapBufMP.xdc
package ti.sdo.ipc.heaps;
 
module HeapBufMP inherits IHeap {
module-wide config parameters
        msg: "A_invBlockFreed: Invalid block being freed"
    };
        msg: "E_alignTooLarge: Requested alignment size of %d is greater than %d"
    };
        msg: "E_exactFail: Exact allocation failed (requested size = 0x%x and buffer size = 0x%x)"
    };
        msg: "E_sizeTooLarge: Requested alloc size of 0x%x is greater than 0x%x"
    };
    config UInt maxNameLen// Maximum length for heap names = 32;
 
    metaonly config String tableSection// Section name is used to place the names table = null;
 
 
instance:
per-instance config parameters
    config SizeT align// Alignment (in MAUs) of each block = 0;
    config SizeT blockSize// Size (in MAUs) of each block = 0;
    config Bool exact// Use exact matching = false;
    config String name// Name of this instance = null;
    config UInt numBlocks// Number of fixed-size blocks = 0;
    config UInt32 regionId// Shared region ID = 0;
per-instance creation
per-instance functions
    Ptr alloc// Allocates a block of memory from the heap( SizeT size, SizeT align, Error.Block *eb );
    Void free// Free a block of memory back to the heap( Ptr block, SizeT size );
}
DETAILS
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):
<PRE>#include &lt;ti/ipc/HeapBufMP.h&gt;</PRE>
The RTSC module must be used in the application's RTSC configuration file (.cfg) if runtime APIs will be used in the application:
<PRE>HeapBufMP = xdc.useModule('ti.sdo.ipc.heaps.HeapBufMP');</PRE>
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.
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_invBlockFreed  // module-wide

Assert raised when freeing a block that is not in the buffer's range

XDCscript usage meta-domain
HeapBufMP.A_invBlockFreed = Assert.Desc {
    msg: "A_invBlockFreed: Invalid block being freed"
};
C synopsis target-domain
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
HeapBufMP.E_alignTooLarge = Error.Desc {
    msg: "E_alignTooLarge: Requested alignment size of %d is greater than %d"
};
C synopsis target-domain
extern const Error_Id HeapBufMP_E_alignTooLarge;
 
 
config HeapBufMP.E_exactFail  // module-wide

Error raised when exact matching failed

XDCscript usage meta-domain
HeapBufMP.E_exactFail = Error.Desc {
    msg: "E_exactFail: Exact allocation failed (requested size = 0x%x and buffer size = 0x%x)"
};
C synopsis target-domain
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
HeapBufMP.E_sizeTooLarge = Error.Desc {
    msg: "E_sizeTooLarge: Requested alloc size of 0x%x is greater than 0x%x"
};
C synopsis target-domain
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;
C synopsis target-domain
extern const UInt HeapBufMP_maxNameLen;
 
 
config HeapBufMP.trackAllocs  // module-wide

Track the number of allocated blocks

XDCscript usage meta-domain
HeapBufMP.trackAllocs = Bool false;
C synopsis target-domain
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
HeapBufMP.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.
 
metaonly config HeapBufMP.maxRuntimeEntries  // module-wide

Maximum runtime entries

XDCscript usage meta-domain
HeapBufMP.maxRuntimeEntries = UInt NameServer.ALLOWGROWTH;
 
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

C synopsis target-domain
Types_ModuleId HeapBufMP_Module_id( );
// Get this module's unique id
 
Bool HeapBufMP_Module_startupDone( );
// Test if this module has completed startup
 
IHeap_Handle HeapBufMP_Module_heap( );
// 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

C synopsis target-domain
typedef struct HeapBufMP_Object HeapBufMP_Object;
// Opaque internal representation of an instance object
 
typedef HeapBufMP_Object *HeapBufMP_Handle;
// Client reference to an instance object
 
typedef struct HeapBufMP_Struct HeapBufMP_Struct;
// Opaque client structure large enough to hold an instance object
 
HeapBufMP_Handle HeapBufMP_handle( HeapBufMP_Struct *structP );
// Convert this instance structure pointer into an instance handle
 
HeapBufMP_Struct *HeapBufMP_struct( HeapBufMP_Handle 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
    params.gate = GateMP.Handle null;
    // 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;
    // 
C synopsis target-domain
typedef struct HeapBufMP_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // 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_Handle gate;
    // 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;
 
Void HeapBufMP_Params_init( HeapBufMP_Params *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;
C synopsis target-domain
struct HeapBufMP_Params {
      ...
    SizeT align;
 
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;
C synopsis target-domain
struct HeapBufMP_Params {
      ...
    SizeT blockSize;
 
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;
C synopsis target-domain
struct HeapBufMP_Params {
      ...
    Bool exact;
 
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;
  ...
params.gate = GateMP.Handle null;
C synopsis target-domain
struct HeapBufMP_Params {
      ...
    GateMP_Handle gate;
 
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;
C synopsis target-domain
struct HeapBufMP_Params {
      ...
    String name;
 
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;
C synopsis target-domain
struct HeapBufMP_Params {
      ...
    UInt numBlocks;
 
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;
C synopsis target-domain
struct HeapBufMP_Params {
      ...
    UInt32 regionId;
 
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
C synopsis target-domain
HeapBufMP_Handle HeapBufMP_create( const HeapBufMP_Params *params, Error_Block *eb );
// Allocate and initialize a new instance object and return its handle
 
Void HeapBufMP_construct( HeapBufMP_Struct *structP, const HeapBufMP_Params *params, Error_Block *eb );
// 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 HeapBufMP_delete( HeapBufMP_Handle *handleP );
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void HeapBufMP_destruct( HeapBufMP_Struct *structP );
// Finalize the instance object inside the provided structure
 
HeapBufMP.alloc( )  // per-instance

Allocates a block of memory from the heap

C synopsis target-domain
Ptr HeapBufMP_alloc( HeapBufMP_Handle handle, SizeT size, SizeT align, Error_Block *eb );
 
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

C synopsis target-domain
Void HeapBufMP_free( HeapBufMP_Handle handle, Ptr block, SizeT size );
 
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

C synopsis target-domain
Void HeapBufMP_getStats( HeapBufMP_Handle handle, Memory_Stats *stats );
 
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()

C synopsis target-domain
Bool HeapBufMP_isBlocking( HeapBufMP_Handle handle );
 
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

C synopsis target-domain
IHeap_Handle HeapBufMP_Handle_upCast( HeapBufMP_Handle handle );
// unconditionally move one level up the inheritance hierarchy
 
HeapBufMP_Handle HeapBufMP_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 HeapBufMP_Object_count( );
// The number of statically-created instance objects
 
HeapBufMP_Handle HeapBufMP_Object_get( HeapBufMP_Object *array, Int i );
// The handle of the i-th statically-created instance object (array == NULL)
 
HeapBufMP_Handle HeapBufMP_Object_first( );
// The handle of the first dynamically-created instance object, or NULL
 
HeapBufMP_Handle HeapBufMP_Object_next( HeapBufMP_Handle handle );
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle HeapBufMP_Object_heap( );
// The heap used to allocate dynamically-created instance objects
 
Types_Label *HeapBufMP_Handle_label( HeapBufMP_Handle handle, Types_Label *buf );
// The label associated with this instance object
 
String HeapBufMP_Handle_name( HeapBufMP_Handle handle );
// The name of this instance object
generated on Fri, 09 Apr 2010 01:41:08 GMT