module ti.sdo.utils.MultiProc
index URL

Processor Id Module Manager

Many IPC modules require identifying processors in a multi-processor environment. The MultiProc module centralizes processor id management into one module. Since this configuration is almost always universally required, most IPC applications require supplying configuration of this module. [ more ... ]
C synopsis target-domain sourced in ti/sdo/utils/MultiProc.xdc
#include <ti/sdo/utils/MultiProc.h>
Functions common to all target modules
MultiProc_Module_getMask// Returns the diagnostics mask for this module, MultiProc_Module_hasMask// Test whether this module has a diagnostics mask, MultiProc_Module_heap// The heap from which this module allocates memory, MultiProc_Module_id// Get this module's unique id, MultiProc_Module_setMask// Set the diagnostics mask for this module, MultiProc_Module_startupDone// Test if this module has completed startup
Defines
#define
MultiProc_INVALIDID// Invalid processor id constant (UInt16)0xFFFF
Constants
extern const Assert_Id 
MultiProc_A_invalidMultiProcId// Assert raised when an invalid processor id is used;
extern const Assert_Id 
MultiProc_A_invalidProcName// Assert raised when a NULL processor name is encountered;
extern const UInt16 
MultiProc_numProcessors// Number of processors in the system;
 
DETAILS
Many IPC modules require identifying processors in a multi-processor environment. The MultiProc module centralizes processor id management into one module. Since this configuration is almost always universally required, most IPC applications require supplying configuration of this module.
Each processor in the MultiProc module may be uniquely identified by either a name string or an integer ranging from 0 to MAXPROCESSORS - 1. Configuration is supplied using the setConfig meta function, the numProcessors and baseIdOfCluster.
The setConfig function tells the MultiProc module:
  • The specific processor for which the application is being built
  • The number of processors in the cluster
A cluster is a set of processors within a system which share some share shared memory and supports notifications. Typically most systems contain one cluster. When there are multiple clusters in the system, the numProcessors and baseIdOfCluster configuration paramaters are required to be set before calling setConfig
For examle in a system with 2 C6678 devices [each C6678 contains 8 homogeneuous cores]. For first C6678 device:
  var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
  MultiProc.baseIdOfCluster = 0;
  MultiProc.numProcessors = 16;
  MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2", "CORE3",
                             "CORE4", "CORE5", "CORE6", "CORE7"]);
For second C6678 device:
  var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
  MultiProc.baseIdOfCluster = 8;
  MultiProc.numProcessors = 16;
  MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2", "CORE3",
                             "CORE4", "CORE5", "CORE6", "CORE7"]);
Using the information supplied using the setConfig meta function and the baseIdOfCluster module configuration, the processor IDs are internally set. Please refer to the documentation for setConfig and baseIdOfCluster for more details.
At runtime, the getId call returns the MultiProc id of those processors within its cluster. At config-time, the getIdMeta call returns the the same value.
 
const MultiProc_INVALIDID
index URL

Invalid processor id constant

C synopsis target-domain
#define MultiProc_INVALIDID (UInt16)0xFFFF
 
DETAILS
This constant denotes that the processor id is not valid.
 
config MultiProc_A_invalidMultiProcId  // module-wide
index URL

Assert raised when an invalid processor id is used

C synopsis target-domain
extern const Assert_Id MultiProc_A_invalidMultiProcId;
 
 
config MultiProc_A_invalidProcName  // module-wide
index URL

Assert raised when a NULL processor name is encountered

C synopsis target-domain
extern const Assert_Id MultiProc_A_invalidProcName;
 
 
config MultiProc_numProcessors  // module-wide
index URL

Number of processors in the system

C synopsis target-domain
extern const UInt16 MultiProc_numProcessors;
 
DETAILS
This configuration should only be set when there is more than one cluster in the system. It must be set before calling setConfig. If the system contains only one cluster, it is internally set by the setConfig meta function to the length of the supplied nameList array. After setConfig has been called, it is possible to retrive the maximum # of processors by reading this module config either at run-time or at config time.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId MultiProc_Module_id();
// Get this module's unique id
 
Bool MultiProc_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle MultiProc_Module_heap();
// The heap from which this module allocates memory
 
Bool MultiProc_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 MultiProc_Module_getMask();
// Returns the diagnostics mask for this module
 
Void MultiProc_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/sdo/utils/MultiProc.xdc
var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
module-wide constants & types
    const MultiProc.INVALIDID// Invalid processor id constant = 0xFFFF;
 
    var obj = new MultiProc.ModuleView// ;
        obj.id = UInt16  ...
        obj.numProcessors = UInt16  ...
        obj.nameList = String[]  ...
module-wide config parameters
    MultiProc.A_invalidMultiProcId// Assert raised when an invalid processor id is used = Assert.Desc {
        msg: "A_invalidMultiProcId: Invalid MultiProc id"
    };
    MultiProc.A_invalidProcName// Assert raised when a NULL processor name is encountered = Assert.Desc {
        msg: "A_invalidProcName: NULL MultiProc name encountered"
    };
    MultiProc.numProcessors// Number of processors in the system = UInt16 1;
 
    MultiProc.baseIdOfCluster// The base id of the cluster = UInt16 0;
    MultiProc.common$// Common module configuration parameters = Types.Common$ undefined;
    MultiProc.rovViewInfo//  = ViewInfo.Instance ViewInfo.create;
module-wide functions
    MultiProc.getDeviceProcNames// Returns an array of all possible processor names on the build device() returns Any
    MultiProc.getIdMeta// Meta version of getId(String name) returns UInt16
    MultiProc.setConfig// Configure the MultiProc module(String name, String[] nameList) returns Void
 
 
const MultiProc.INVALIDID
index URL

Invalid processor id constant

XDCscript usage meta-domain
const MultiProc.INVALIDID = 0xFFFF;
 
DETAILS
This constant denotes that the processor id is not valid.
C SYNOPSIS
MultiProc_INVALIDID
 
metaonly struct MultiProc.ModuleView
index URL
XDCscript usage meta-domain
var obj = new MultiProc.ModuleView;
 
    obj.id = UInt16  ...
    obj.numProcessors = UInt16  ...
    obj.nameList = String[]  ...
 
 
config MultiProc.A_invalidMultiProcId  // module-wide
index URL

Assert raised when an invalid processor id is used

XDCscript usage meta-domain
MultiProc.A_invalidMultiProcId = Assert.Desc {
    msg: "A_invalidMultiProcId: Invalid MultiProc id"
};
 
C SYNOPSIS
MultiProc_A_invalidMultiProcId
 
config MultiProc.A_invalidProcName  // module-wide
index URL

Assert raised when a NULL processor name is encountered

XDCscript usage meta-domain
MultiProc.A_invalidProcName = Assert.Desc {
    msg: "A_invalidProcName: NULL MultiProc name encountered"
};
 
C SYNOPSIS
MultiProc_A_invalidProcName
 
config MultiProc.numProcessors  // module-wide
index URL

Number of processors in the system

XDCscript usage meta-domain
MultiProc.numProcessors = UInt16 1;
 
DETAILS
This configuration should only be set when there is more than one cluster in the system. It must be set before calling setConfig. If the system contains only one cluster, it is internally set by the setConfig meta function to the length of the supplied nameList array. After setConfig has been called, it is possible to retrive the maximum # of processors by reading this module config either at run-time or at config time.
C SYNOPSIS
MultiProc_numProcessors
 
metaonly config MultiProc.baseIdOfCluster  // module-wide
index URL

The base id of the cluster

XDCscript usage meta-domain
MultiProc.baseIdOfCluster = UInt16 0;
 
DETAILS
Using this base id, the id of each processor in the cluster is set based up its position in setConfig. When more more than one cluster exists in the system, this parameter must be set before calling setConfig.
 
metaonly config MultiProc.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
MultiProc.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 MultiProc.rovViewInfo  // module-wide
index URL
XDCscript usage meta-domain
MultiProc.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly MultiProc.getDeviceProcNames()  // module-wide
index URL

Returns an array of all possible processor names on the build device

XDCscript usage meta-domain
MultiProc.getDeviceProcNames() returns Any
 
DETAILS
@(return) Array of valid MultiProc processor names
 
metaonly MultiProc.getIdMeta()  // module-wide
index URL

Meta version of getId

XDCscript usage meta-domain
MultiProc.getIdMeta(String name) returns UInt16
 
ARGUMENTS
name — MultiProc procName
DETAILS
Statically returns the internally set ID based on configuration supplied via setConfig.
 
metaonly MultiProc.setConfig()  // module-wide
index URL

Configure the MultiProc module

XDCscript usage meta-domain
MultiProc.setConfig(String name, String[] nameList) returns Void
 
ARGUMENTS
name — MultiProc name for the local processor
nameList — Array of all processors used by the application
DETAILS
Configuration of the MultiProc module is primarily accomplished using the setConfig API at config time. The setConfig API allows the MultiProc module to identify:
  • Which is the local processor
  • Which processors are being used
  • Which processors can synchronize
The second of these two pieces of information is supplied via the nameList argument. The nameList is a non-empty set of distinct processors valid for the particular device. For a list of valid processor names for a given device, please refer to the : Table of Valid Names for Each Device.
The local processor is identified by using a single name from nameList. A MultiProc id is internally set to the index of 'name' in the supplied 'nameList'. I.e. in the example:
  MultiProc.setConfig("DSP", ["HOST", "DSP", "OTHERCORE"]);
The processors, "HOST", "DSP" and "OTHERCORE" get assigned MultiProc IDs 0, 1, and 2, respectively. The local processor, "DSP" is assigned an ID of '1'.
If the local processor is not known at static time, it is possible to supply a null name. MultiProc will set the local id to INVALIDID until it is set at runtime using MultiProc_setLocalId.
generated on Sat, 11 Feb 2012 00:38:14 GMT