module ti.sdo.ipc.GateMP

Multiple processor gate that provides local and remote context protection

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/GateMP.h>
The RTSC module must be used in the application's RTSC configuration file (.cfg) if runtime APIs will be used in the application:
GateMP = xdc.useModule('ti.sdo.ipc.GateMP');
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.
XDCspec summary sourced in ti/sdo/ipc/GateMP.xdc
module GateMP {  ...
    // inherits xdc.runtime.IModule
instance:  ...
C synopsis target-domain
#include <ti/sdo/ipc/GateMP.h>
module-wide constants & types
    #define GateMP_Q_BLOCKING// Blocking quality (Int)1
 
        GateMP_LocalProtect_NONE,
        GateMP_LocalProtect_TASKLET,
        GateMP_LocalProtect_THREAD,
        GateMP_LocalProtect_PROCESS
    } GateMP_LocalProtect;
 
        GateMP_RemoteProtect_NONE,
        GateMP_RemoteProtect_SYSTEM,
        GateMP_RemoteProtect_CUSTOM1,
 
    typedef struct GateMP_Reserved//  {
        Bits32 version;
    } GateMP_Reserved;
module-wide config parameters
    extern const UInt GateMP_maxNameLen// Maximum length for names;
module-wide functions
module-wide built-ins
per-instance object types
 
per-instance config parameters
        IInstance_Params *instance;
        String name// Name of the instance;
        Bool openFlag// ;
        UInt16 regionId// Shared Region Id;
        Bits32 resourceId// ;
    } GateMP_Params;
 
per-instance creation
per-instance deletion
per-instance functions
    Void GateMP_leave// Leave this gate( GateMP_Handle handle, IArg key );
per-instance convertors
per-instance built-ins
 
XDCscript usage meta-domain
var GateMP = xdc.useModule('ti.sdo.ipc.GateMP');
module-wide constants & types
 
        const GateMP.LocalProtect_NONE;
        const GateMP.LocalProtect_INTERRUPT;
        const GateMP.LocalProtect_TASKLET;
        const GateMP.LocalProtect_THREAD;
        const GateMP.LocalProtect_PROCESS;
 
        const GateMP.RemoteProtect_NONE;
        const GateMP.RemoteProtect_SYSTEM;
        const GateMP.RemoteProtect_CUSTOM1;
        const GateMP.RemoteProtect_CUSTOM2;
 
    var obj = new GateMP.Reserved// ;
        obj.version = Bits32  ...
module-wide config parameters
        msg: "A_invalidContext: Calling GateMP_close with the wrong handle"
    };
        msg: "A_invalidDelete: Calling GateMP_delete incorrectly"
    };
        msg: "E_gateUnavailable: No gates of requested type are available"
    };
        msg: "E_localGate: Only creator can open local Gate"
    };
        mask: Diags.USER1,
        msg: "LM_close: Gate (remoteGate = %d, resourceId = %d) closed"
    };
        mask: Diags.USER1,
        msg: "LM_create: Gate (remoteGate = %d, resourceId = %d) created"
    };
        mask: Diags.USER1,
        msg: "LM_delete: Gate (remoteGate = %d, resourceId = %d) deleted"
    };
        mask: Diags.USER1,
        msg: "LM_enter: Gate (remoteGate = %d, resourceId = %d) entered, returning key = %d"
    };
        mask: Diags.USER1,
        msg: "LM_leave: Gate (remoteGate = %d, resourceId = %d) left using key = %d"
    };
        mask: Diags.USER1,
        msg: "LM_open: Remote gate (remoteGate = %d, resourceId = %d) opened"
    };
 
module-wide functions
per-instance config parameters
    var params = new GateMP.Params// Instance config-params object;
        params.name// Name of the instance = String null;
        params.openFlag//  = Bool false;
        params.regionId// Shared Region Id = UInt16 0;
        params.resourceId//  = Bits32 0;
        params.sharedAddr// Physical address of the shared memory = Ptr null;
per-instance creation
    var inst = GateMP.create// Create an instance-object( params );
 
XDCspec declarations sourced in ti/sdo/ipc/GateMP.xdc
package ti.sdo.ipc;
 
module GateMP inherits IGateProvider {
module-wide constants & types
    const Int Q_BLOCKING// Blocking quality = 1;
    const Int Q_PREEMPTING// Preempting quality = 2;
 
        LocalProtect_NONE,
        LocalProtect_INTERRUPT,
        LocalProtect_TASKLET,
        LocalProtect_THREAD,
        LocalProtect_PROCESS
    };
 
        RemoteProtect_NONE,
        RemoteProtect_SYSTEM,
        RemoteProtect_CUSTOM1,
        RemoteProtect_CUSTOM2
    };
 
    struct Reserved//  {
        Bits32 version;
    };
module-wide config parameters
        msg: "A_invalidContext: Calling GateMP_close with the wrong handle"
    };
        msg: "A_invalidDelete: Calling GateMP_delete incorrectly"
    };
        msg: "E_gateUnavailable: No gates of requested type are available"
    };
        msg: "E_localGate: Only creator can open local Gate"
    };
        mask: Diags.USER1,
        msg: "LM_close: Gate (remoteGate = %d, resourceId = %d) closed"
    };
        mask: Diags.USER1,
        msg: "LM_create: Gate (remoteGate = %d, resourceId = %d) created"
    };
        mask: Diags.USER1,
        msg: "LM_delete: Gate (remoteGate = %d, resourceId = %d) deleted"
    };
        mask: Diags.USER1,
        msg: "LM_enter: Gate (remoteGate = %d, resourceId = %d) entered, returning key = %d"
    };
        mask: Diags.USER1,
        msg: "LM_leave: Gate (remoteGate = %d, resourceId = %d) left using key = %d"
    };
        mask: Diags.USER1,
        msg: "LM_open: Remote gate (remoteGate = %d, resourceId = %d) opened"
    };
    config UInt maxNameLen// Maximum length for names = 32;
 
    metaonly config String tableSection// Section name is used to place the names table = null;
module-wide functions
 
 
 
instance:
per-instance config parameters
    config String name// Name of the instance = null;
    config UInt16 regionId// Shared Region Id = 0;
per-instance creation
per-instance functions
    IArg enter// Enter this gate( );
    Void leave// Leave this gate( IArg key );
}
 
const GateMP.Q_BLOCKING

Blocking quality

XDCscript usage meta-domain
const GateMP.Q_BLOCKING = 1;
C synopsis target-domain
#define GateMP_Q_BLOCKING (Int)1
 
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
 
const GateMP.Q_PREEMPTING

Preempting quality

XDCscript usage meta-domain
const GateMP.Q_PREEMPTING = 2;
C synopsis target-domain
#define GateMP_Q_PREEMPTING (Int)2
 
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
 
enum GateMP.LocalProtect

A set of local context protection levels

XDCscript usage meta-domain
values of type GateMP.LocalProtect
    const GateMP.LocalProtect_NONE;
    const GateMP.LocalProtect_INTERRUPT;
    const GateMP.LocalProtect_TASKLET;
    const GateMP.LocalProtect_THREAD;
    const GateMP.LocalProtect_PROCESS;
C synopsis target-domain
typedef enum GateMP_LocalProtect {
    GateMP_LocalProtect_NONE,
    GateMP_LocalProtect_INTERRUPT,
    GateMP_LocalProtect_TASKLET,
    GateMP_LocalProtect_THREAD,
    GateMP_LocalProtect_PROCESS
} GateMP_LocalProtect;
 
DETAILS
Each member corresponds to a specific local processor gates used for local protection.
For SYS/BIOS users, the following are the mappings for the constants
  • INTERRUPT -> GateHwi: disables interrupts
  • TASKLET -> GateSwi: disables Swis (software interrupts)
  • THREAD -> GateMutexPri: based on Semaphores
  • PROCESS -> GateMutexPri: based on Semaphores
 
enum GateMP.RemoteProtect

Type of remote Gate

XDCscript usage meta-domain
values of type GateMP.RemoteProtect
    const GateMP.RemoteProtect_NONE;
    const GateMP.RemoteProtect_SYSTEM;
    const GateMP.RemoteProtect_CUSTOM1;
    const GateMP.RemoteProtect_CUSTOM2;
C synopsis target-domain
typedef enum GateMP_RemoteProtect {
    GateMP_RemoteProtect_NONE,
    GateMP_RemoteProtect_SYSTEM,
    GateMP_RemoteProtect_CUSTOM1,
    GateMP_RemoteProtect_CUSTOM2
} GateMP_RemoteProtect;
 
DETAILS
Each member corresponds to a specific type of remote gate. Each enum value corresponds to the following remote protection levels:
  • NONE -> No remote protection (the GateMP instance will exclusively offer local protection configured in localProtect)
  • SYSTEM -> Use the SYSTEM remote protection level (default for remote protection
  • CUSTOM1 -> Use the CUSTOM1 remote protection level
  • CUSTOM2 -> Use the CUSTOM2 remote protection level
 
struct GateMP.Reserved
XDCscript usage meta-domain
var obj = new GateMP.Reserved;
 
    obj.version = Bits32  ...
C synopsis target-domain
typedef struct GateMP_Reserved {
    Bits32 version;
} GateMP_Reserved;
 
 
config GateMP.A_invalidClose  // module-wide

Assert raised when calling GateMP_close with the wrong handle

XDCscript usage meta-domain
GateMP.A_invalidClose = Assert.Desc {
    msg: "A_invalidContext: Calling GateMP_close with the wrong handle"
};
C synopsis target-domain
extern const Assert_Id GateMP_A_invalidClose;
 
 
config GateMP.A_invalidDelete  // module-wide

Assert raised when calling GateMP_delete incorrectly

XDCscript usage meta-domain
GateMP.A_invalidDelete = Assert.Desc {
    msg: "A_invalidDelete: Calling GateMP_delete incorrectly"
};
C synopsis target-domain
extern const Assert_Id GateMP_A_invalidDelete;
 
 
config GateMP.E_gateUnavailable  // module-wide

Error raised no gates of the requested type are available

XDCscript usage meta-domain
GateMP.E_gateUnavailable = Error.Desc {
    msg: "E_gateUnavailable: No gates of requested type are available"
};
C synopsis target-domain
extern const Error_Id GateMP_E_gateUnavailable;
 
 
config GateMP.E_localGate  // module-wide

Error raised when remote side tried to open local gate

XDCscript usage meta-domain
GateMP.E_localGate = Error.Desc {
    msg: "E_localGate: Only creator can open local Gate"
};
C synopsis target-domain
extern const Error_Id GateMP_E_localGate;
 
 
config GateMP.LM_close  // module-wide

Logged on gate close

XDCscript usage meta-domain
GateMP.LM_close = Log.EventDesc {
    mask: Diags.USER1,
    msg: "LM_close: Gate (remoteGate = %d, resourceId = %d) closed"
};
C synopsis target-domain
extern const Log_Event GateMP_LM_close;
 
 
config GateMP.LM_create  // module-wide

Logged on gate create

XDCscript usage meta-domain
GateMP.LM_create = Log.EventDesc {
    mask: Diags.USER1,
    msg: "LM_create: Gate (remoteGate = %d, resourceId = %d) created"
};
C synopsis target-domain
extern const Log_Event GateMP_LM_create;
 
 
config GateMP.LM_delete  // module-wide

Logged on gate deletion

XDCscript usage meta-domain
GateMP.LM_delete = Log.EventDesc {
    mask: Diags.USER1,
    msg: "LM_delete: Gate (remoteGate = %d, resourceId = %d) deleted"
};
C synopsis target-domain
extern const Log_Event GateMP_LM_delete;
 
 
config GateMP.LM_enter  // module-wide

Logged on gate enter

XDCscript usage meta-domain
GateMP.LM_enter = Log.EventDesc {
    mask: Diags.USER1,
    msg: "LM_enter: Gate (remoteGate = %d, resourceId = %d) entered, returning key = %d"
};
C synopsis target-domain
extern const Log_Event GateMP_LM_enter;
 
 
config GateMP.LM_leave  // module-wide

Logged on gate leave

XDCscript usage meta-domain
GateMP.LM_leave = Log.EventDesc {
    mask: Diags.USER1,
    msg: "LM_leave: Gate (remoteGate = %d, resourceId = %d) left using key = %d"
};
C synopsis target-domain
extern const Log_Event GateMP_LM_leave;
 
 
config GateMP.LM_open  // module-wide

Logged on gate open

XDCscript usage meta-domain
GateMP.LM_open = Log.EventDesc {
    mask: Diags.USER1,
    msg: "LM_open: Remote gate (remoteGate = %d, resourceId = %d) opened"
};
C synopsis target-domain
extern const Log_Event GateMP_LM_open;
 
 
config GateMP.maxNameLen  // module-wide

Maximum length for names

XDCscript usage meta-domain
GateMP.maxNameLen = UInt 32;
C synopsis target-domain
extern const UInt GateMP_maxNameLen;
 
 
metaonly config GateMP.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
GateMP.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 GateMP.maxRuntimeEntries  // module-wide

Maximum runtime entries

XDCscript usage meta-domain
GateMP.maxRuntimeEntries = UInt NameServer.ALLOWGROWTH;
 
DETAILS
Maximum number of GateMP'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 GateMP's NameServer table. The default is to allow growth (i.e. memory allocation when creating a new instance).
 
metaonly config GateMP.tableSection  // module-wide

Section name is used to place the names table

XDCscript usage meta-domain
GateMP.tableSection = String null;
 
 
GateMP.query( )  // module-wide

Runtime test for a particular gate quality

C synopsis target-domain
Bool GateMP_query( Int qual );
 
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
 
metaonly GateMP.queryMeta( )  // module-wide

Configuration time test for a particular gate quality

XDCscript usage meta-domain
GateMP.queryMeta( Int qual ) returns Bool
 
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
 
module-wide built-ins

C synopsis target-domain
Types_ModuleId GateMP_Module_id( );
// Get this module's unique id
 
Bool GateMP_Module_startupDone( );
// Test if this module has completed startup
 
IHeap_Handle GateMP_Module_heap( );
// The heap from which this module allocates memory
 
Bool GateMP_Module_hasMask( );
// Test whether this module has a diagnostics mask
 
Bits16 GateMP_Module_getMask( );
// Returns the diagnostics mask for this module
 
Void GateMP_Module_setMask( Bits16 mask );
// Set the diagnostics mask for this module
 
per-instance object types

C synopsis target-domain
typedef struct GateMP_Object GateMP_Object;
// Opaque internal representation of an instance object
 
typedef GateMP_Object *GateMP_Handle;
// Client reference to an instance object
 
typedef struct GateMP_Struct GateMP_Struct;
// Opaque client structure large enough to hold an instance object
 
GateMP_Handle GateMP_handle( GateMP_Struct *structP );
// Convert this instance structure pointer into an instance handle
 
GateMP_Struct *GateMP_struct( GateMP_Handle handle );
// Convert this instance handle into an instance structure pointer
 
per-instance config parameters

XDCscript usage meta-domain
var params = new GateMP.Params;
// Instance config-params object
    params.localProtect = GateMP.LocalProtect GateMP.LocalProtect_THREAD;
    // 
    params.name = String null;
    // Name of the instance
    params.openFlag = Bool false;
    // 
    params.regionId = UInt16 0;
    // Shared Region Id
    params.remoteProtect = GateMP.RemoteProtect GateMP.RemoteProtect_SYSTEM;
    // 
    params.resourceId = Bits32 0;
    // 
    params.sharedAddr = Ptr null;
    // Physical address of the shared memory
C synopsis target-domain
typedef struct GateMP_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    GateMP_LocalProtect localProtect;
    // 
    String name;
    // Name of the instance
    Bool openFlag;
    // 
    UInt16 regionId;
    // Shared Region Id
    GateMP_RemoteProtect remoteProtect;
    // 
    Bits32 resourceId;
    // 
    Ptr sharedAddr;
    // Physical address of the shared memory
} GateMP_Params;
 
Void GateMP_Params_init( GateMP_Params *params );
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config GateMP.localProtect  // per-instance
XDCscript usage meta-domain
var params = new GateMP.Params;
  ...
C synopsis target-domain
struct GateMP_Params {
      ...
    GateMP_LocalProtect localProtect;
 
 
config GateMP.name  // per-instance

Name of the instance

XDCscript usage meta-domain
var params = new GateMP.Params;
  ...
params.name = String null;
C synopsis target-domain
struct GateMP_Params {
      ...
    String name;
 
DETAILS
Name needs to be unique. Used only if useNameServer is set to TRUE.
 
config GateMP.regionId  // per-instance

Shared Region Id

XDCscript usage meta-domain
var params = new GateMP.Params;
  ...
params.regionId = UInt16 0;
C synopsis target-domain
struct GateMP_Params {
      ...
    UInt16 regionId;
 
DETAILS
The ID corresponding to the shared region in which this shared instance is to be placed.
 
config GateMP.remoteProtect  // per-instance
XDCscript usage meta-domain
var params = new GateMP.Params;
  ...
C synopsis target-domain
struct GateMP_Params {
      ...
    GateMP_RemoteProtect remoteProtect;
 
 
config GateMP.sharedAddr  // per-instance

Physical address of the shared memory

XDCscript usage meta-domain
var params = new GateMP.Params;
  ...
params.sharedAddr = Ptr null;
C synopsis target-domain
struct GateMP_Params {
      ...
    Ptr sharedAddr;
 
DETAILS
The creator must supply the shared memory that will be used for maintaining shared state information. This parameter is used only when Type is set to Type_SHARED
 
per-instance creation

XDCscript usage meta-domain
var params = new GateMP.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = GateMP.create( params );
// Create an instance-object
C synopsis target-domain
GateMP_Handle GateMP_create( const GateMP_Params *params, Error_Block *eb );
// Allocate and initialize a new instance object and return its handle
 
Void GateMP_construct( GateMP_Struct *structP, const GateMP_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)
 
per-instance deletion

C synopsis target-domain
Void GateMP_delete( GateMP_Handle *handleP );
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void GateMP_destruct( GateMP_Struct *structP );
// Finalize the instance object inside the provided structure
 
GateMP.enter( )  // per-instance

Enter this gate

C synopsis target-domain
IArg GateMP_enter( GateMP_Handle handle );
 
ARGUMENTS
handle — handle of a previously-created GateMP instance object
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
 
GateMP.leave( )  // per-instance

Leave this gate

C synopsis target-domain
Void GateMP_leave( GateMP_Handle handle, IArg key );
 
ARGUMENTS
handle — handle of a previously-created GateMP instance object
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
 
per-instance convertors

C synopsis target-domain
IGateProvider_Handle GateMP_Handle_upCast( GateMP_Handle handle );
// unconditionally move one level up the inheritance hierarchy
 
GateMP_Handle GateMP_Handle_downCast( IGateProvider_Handle handle );
// conditionally move one level down the inheritance hierarchy; NULL upon failure
 
per-instance built-ins

C synopsis target-domain
Int GateMP_Object_count( );
// The number of statically-created instance objects
 
GateMP_Handle GateMP_Object_get( GateMP_Object *array, Int i );
// The handle of the i-th statically-created instance object (array == NULL)
 
GateMP_Handle GateMP_Object_first( );
// The handle of the first dynamically-created instance object, or NULL
 
GateMP_Handle GateMP_Object_next( GateMP_Handle handle );
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle GateMP_Object_heap( );
// The heap used to allocate dynamically-created instance objects
 
Types_Label *GateMP_Handle_label( GateMP_Handle handle, Types_Label *buf );
// The label associated with this instance object
 
String GateMP_Handle_name( GateMP_Handle handle );
// The name of this instance object
generated on Fri, 09 Apr 2010 01:41:05 GMT