module ti.sdo.ipc.transports.TransportShmCirc
index URL

Transport for MessageQ that uses a circular buffer to queue messages

This is a ti.sdo.ipc.MessageQ transport that utilizes shared memory for passing messages between multiple processors. [ more ... ]
C synopsis target-domain sourced in ti/sdo/ipc/transports/TransportShmCirc.xdc
#include <ti/sdo/ipc/transports/TransportShmCirc.h>
Functions
Void
TransportShmCirc_construct// Initialize a new instance object inside the provided structure(TransportShmCirc_Struct *structP, UInt16 procId, const TransportShmCirc_Params *params, Error_Block *eb);
TransportShmCirc_Handle
TransportShmCirc_create// Allocate and initialize a new instance object and return its handle(UInt16 procId, const TransportShmCirc_Params *params, Error_Block *eb);
Void
TransportShmCirc_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(TransportShmCirc_Handle *handleP);
Void
TransportShmCirc_destruct// Finalize the instance object inside the provided structure(TransportShmCirc_Struct *structP);
Void
TransportShmCirc_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(TransportShmCirc_Params *params);
Functions common to all IMessageQTransport modules
Bool 
TransportShmCirc_control// Send a control command to the transport instance(TransportShmCirc_Handle handle, UInt cmd, UArg cmdArg);
Int 
TransportShmCirc_getStatus// Status of a Transport instance(TransportShmCirc_Handle handle);
Bool 
TransportShmCirc_put// Put the message to the remote processor(TransportShmCirc_Handle handle, Ptr msg);
Void 
TransportShmCirc_setErrFxn// Sets the asynchronous error function for the transport module(IMessageQTransport_ErrFxn errFxn);
Functions common to all target instances
TransportShmCirc_handle// Convert this instance structure pointer into an instance handle, TransportShmCirc_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, TransportShmCirc_Handle_label// The label associated with this instance object, TransportShmCirc_Handle_name// The name of this instance object, TransportShmCirc_Handle_upCast// unconditionally move one level up the inheritance hierarchy, TransportShmCirc_Object_count// The number of statically-created instance objects, TransportShmCirc_Object_first// The handle of the first dynamically-created instance object, or NULL, TransportShmCirc_Object_get// The handle of the i-th statically-created instance object (array == NULL), TransportShmCirc_Object_heap// The heap used to allocate dynamically-created instance objects, TransportShmCirc_Object_next// The handle of the next dynamically-created instance object, or NULL, TransportShmCirc_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
TransportShmCirc_Module_getMask// Returns the diagnostics mask for this module, TransportShmCirc_Module_hasMask// Test whether this module has a diagnostics mask, TransportShmCirc_Module_heap// The heap from which this module allocates memory, TransportShmCirc_Module_id// Get this module's unique id, TransportShmCirc_Module_setMask// Set the diagnostics mask for this module, TransportShmCirc_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void 
(*TransportShmCirc_ErrFxn// Typedef for transport error callback function)(IMessageQTransport_Reason,IMessageQTransport_Handle,Ptr,UArg);
typedef TransportShmCirc_Object *
TransportShmCirc_Handle// Client reference to an instance object;
typedef struct
TransportShmCirc_Object// Opaque internal representation of an instance object TransportShmCirc_Object;
typedef struct
TransportShmCirc_Params// Instance config-params structure ...
typedef enum
TransportShmCirc_Reason// Reason for error function being called ...
typedef enum
TransportShmCirc_Status// Transport return values ...
typedef struct
TransportShmCirc_Struct// Opaque client structure large enough to hold an instance object TransportShmCirc_Struct;
Constants
extern const Bool 
TransportShmCirc_enableStats// Enable statistics for sending an event;
extern const IMessageQTransport_ErrFxn 
TransportShmCirc_errFxn// Asynchronous error function for the transport module;
extern const UInt16 
TransportShmCirc_notifyEventId// Notify event ID for transport;
extern const UInt 
TransportShmCirc_numMsgs// The number of messages or slots in the circular buffer;
 
DETAILS
This is a ti.sdo.ipc.MessageQ transport that utilizes shared memory for passing messages between multiple processors.
The transport implements a queue using a circular buffer in the manner indicated by the following diagram.
  
  NOTE: Processors '0' and '1' correspond to the processors with lower and
        higher MultiProc ids, respectively

 sharedAddr -> --------------------------- bytes
               |  entry0  (0) [Put]      | 4  
               |  entry1  (0)            | 4
               |  ...                    | 
               |  entryN  (0)            | 4
               |  [align to cache size]  | 
               |-------------------------|
               |  putWriteIndex (0)      | 4
               |  [align to cache size]  |
               |-------------------------|
               |  putReadIndex (0)       | 4
               |  [align to cache size]  |
               |-------------------------|
               |  entry0  (1) [Get]      | 4  
               |  entry1  (1)            | 4
               |  ...                    | 
               |  entryN  (1)            | 4
               |  [align to cache size]  |
               |-------------------------|
               |  getWriteIndex (1)      | 4
               |  [align to cache size]  |
               |-------------------------|
               |  getReadIndex (1)       | 4
               |  [align to cache size]  |
               |-------------------------|


  Legend:
  (0), (1) : Memory that belongs to the proc with lower and higher 
             MultiProc.id, respectively
   |----|  : Cache line boundary
 
enum TransportShmCirc_Reason
index URL

Reason for error function being called

C synopsis target-domain
typedef enum TransportShmCirc_Reason {
    TransportShmCirc_Reason_FAILEDPUT,
    TransportShmCirc_Reason_INTERNALERR,
    TransportShmCirc_Reason_PHYSICALERR,
    TransportShmCirc_Reason_FAILEDALLOC
} TransportShmCirc_Reason;
 
DETAILS
First field in the errFxn
 
enum TransportShmCirc_Status
index URL

Transport return values

C synopsis target-domain
typedef enum TransportShmCirc_Status {
    TransportShmCirc_S_SUCCESS,
    TransportShmCirc_E_FAIL,
    TransportShmCirc_E_ERROR
} TransportShmCirc_Status;
 
DETAILS
  • S_SUCCESS: Operation was successful
  • E_FAIL: Operation resulted in a failure
  • E_ERROR: Operation resulted in an error.
 
typedef TransportShmCirc_ErrFxn
index URL

Typedef for transport error callback function

C synopsis target-domain
typedef Void (*TransportShmCirc_ErrFxn)(IMessageQTransport_Reason,IMessageQTransport_Handle,Ptr,UArg);
 
DETAILS
First parameter: Why the error function is being called.
Second parameter: Handle of transport that had the error. NULL denotes that it is a system error, not a specific transport.
Third parameter: Pointer to the message. This is only valid for Reason_FAILEDPUT.
Fourth parameter: Transport specific information. Refer to individual transports for more details.
 
config TransportShmCirc_enableStats  // module-wide
index URL

Enable statistics for sending an event

C synopsis target-domain
extern const Bool TransportShmCirc_enableStats;
 
DETAILS
If this parameter is to 'TRUE' and 'waitClear' is also set to TRUE when calling (@link #sendEvent(), then the module keeps track of the number of times the processor spins waiting for an empty slot and the max amount of time it waits.
 
config TransportShmCirc_errFxn  // module-wide
index URL

Asynchronous error function for the transport module

C synopsis target-domain
extern const IMessageQTransport_ErrFxn TransportShmCirc_errFxn;
 
 
config TransportShmCirc_notifyEventId  // module-wide
index URL

Notify event ID for transport

C synopsis target-domain
extern const UInt16 TransportShmCirc_notifyEventId;
 
 
config TransportShmCirc_numMsgs  // module-wide
index URL

The number of messages or slots in the circular buffer

C synopsis target-domain
extern const UInt TransportShmCirc_numMsgs;
 
DETAILS
This is use to determine the size of the put and get buffers. Each eventEntry is two 32bits wide, therefore the total size of each circular buffer is [numMsgs * sizeof(eventEntry)]. The total size of each buffer must be a multiple of the the cache line size. For example, if the cacheLineSize = 128 then numMsgs could be 16, 32, etc...
 
TransportShmCirc_setErrFxn()  // module-wide
index URL

Sets the asynchronous error function for the transport module

C synopsis target-domain
Void TransportShmCirc_setErrFxn(IMessageQTransport_ErrFxn errFxn);
 
ARGUMENTS
errFxn — Function that is called when an asynchronous error occurs.
DETAILS
This API allows the user to set the function that will be called in case of an asynchronous error by the transport.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId TransportShmCirc_Module_id();
// Get this module's unique id
 
Bool TransportShmCirc_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle TransportShmCirc_Module_heap();
// The heap from which this module allocates memory
 
Bool TransportShmCirc_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 TransportShmCirc_Module_getMask();
// Returns the diagnostics mask for this module
 
Void TransportShmCirc_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct TransportShmCirc_Object TransportShmCirc_Object;
// Opaque internal representation of an instance object
 
typedef TransportShmCirc_Object *TransportShmCirc_Handle;
// Client reference to an instance object
 
typedef struct TransportShmCirc_Struct TransportShmCirc_Struct;
// Opaque client structure large enough to hold an instance object
 
TransportShmCirc_Handle TransportShmCirc_handle(TransportShmCirc_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
TransportShmCirc_Struct *TransportShmCirc_struct(TransportShmCirc_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct TransportShmCirc_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UInt priority;
    // Which priority messages should this transport manage
    Ptr sharedAddr;
    // Address in shared memory where this instance will be placed
} TransportShmCirc_Params;
 
Void TransportShmCirc_Params_init(TransportShmCirc_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config TransportShmCirc_priority  // instance
index URL

Which priority messages should this transport manage

C synopsis target-domain
struct TransportShmCirc_Params {
      ...
    UInt priority;
 
 
config TransportShmCirc_sharedAddr  // instance
index URL

Address in shared memory where this instance will be placed

C synopsis target-domain
struct TransportShmCirc_Params {
      ...
    Ptr sharedAddr;
 
DETAILS
Use sharedMemReq to determine the amount of shared memory required.
Instance Creation
index URL

C synopsis target-domain
TransportShmCirc_Handle TransportShmCirc_create(UInt16 procId, const TransportShmCirc_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void TransportShmCirc_construct(TransportShmCirc_Struct *structP, UInt16 procId, const TransportShmCirc_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
procId — Remote processor id that this instance will communicate with.
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
This function creates a transport instance. The transport is responsible for registering with MessageQ via the ti.sdo.ipc.MessageQ.registerTransport API.
Instance Deletion
index URL

C synopsis target-domain
Void TransportShmCirc_delete(TransportShmCirc_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void TransportShmCirc_destruct(TransportShmCirc_Struct *structP);
// Finalize the instance object inside the provided structure
 
TransportShmCirc_control()  // instance
index URL

Send a control command to the transport instance

C synopsis target-domain
Bool TransportShmCirc_control(TransportShmCirc_Handle handle, UInt cmd, UArg cmdArg);
 
ARGUMENTS
handle — handle of a previously-created TransportShmCirc instance object
cmd — Requested command
cmdArgs — Accompanying field for the command. This is command specific.
RETURNS
TRUE denotes acceptance of the command. FALSE denotes failure of the command.
DETAILS
This is function allows transport to specify control commands. Refer to individual transport implementions for more details.
 
TransportShmCirc_getStatus()  // instance
index URL

Status of a Transport instance

C synopsis target-domain
Int TransportShmCirc_getStatus(TransportShmCirc_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created TransportShmCirc instance object
RETURNS
Returns status of Transport instance
DETAILS
This function returns the status of the transport instance.
 
TransportShmCirc_put()  // instance
index URL

Put the message to the remote processor

C synopsis target-domain
Bool TransportShmCirc_put(TransportShmCirc_Handle handle, Ptr msg);
 
ARGUMENTS
handle — handle of a previously-created TransportShmCirc instance object
msg — Pointer the message to be sent
RETURNS
TRUE denotes acceptance of the message to be sent. FALSE denotes the message could not be sent.
DETAILS
If the transport can accept the message, it returns TRUE. Accepting a message does not mean that it is transmitted. It simply means that the transport should be able to send the message. If the actual transfer fails, the transport calls the {@#ErrFxn} (assuming it is set up via the {@#setErrFxn} API. If the {@#ErrFxn} is not set, the message is dropped. (also...should an error be raised or just System_printf?).
If the transport cannot send the message, it returns FALSE and a filled in Error_Block. The caller still owns the message.
Instance Convertors
index URL

C synopsis target-domain
IMessageQTransport_Handle TransportShmCirc_Handle_upCast(TransportShmCirc_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
TransportShmCirc_Handle TransportShmCirc_Handle_downCast(IMessageQTransport_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int TransportShmCirc_Object_count();
// The number of statically-created instance objects
 
TransportShmCirc_Handle TransportShmCirc_Object_get(TransportShmCirc_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
TransportShmCirc_Handle TransportShmCirc_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
TransportShmCirc_Handle TransportShmCirc_Object_next(TransportShmCirc_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle TransportShmCirc_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *TransportShmCirc_Handle_label(TransportShmCirc_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String TransportShmCirc_Handle_name(TransportShmCirc_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sdo/ipc/transports/TransportShmCirc.xdc
var TransportShmCirc = xdc.useModule('ti.sdo.ipc.transports.TransportShmCirc');
module-wide constants & types
    values of type TransportShmCirc.Reason// Reason for error function being called
        const TransportShmCirc.Reason_FAILEDPUT;
        const TransportShmCirc.Reason_INTERNALERR;
        const TransportShmCirc.Reason_PHYSICALERR;
        const TransportShmCirc.Reason_FAILEDALLOC;
 
    values of type TransportShmCirc.Status// Transport return values
        const TransportShmCirc.S_SUCCESS;
        const TransportShmCirc.E_FAIL;
        const TransportShmCirc.E_ERROR;
module-wide config parameters
    TransportShmCirc.enableStats// Enable statistics for sending an event = Bool false;
    TransportShmCirc.errFxn// Asynchronous error function for the transport module = Void(*)(IMessageQTransport.Reason,IMessageQTransport.Handle,Ptr,UArg) null;
    TransportShmCirc.notifyEventId// Notify event ID for transport = UInt16 2;
    TransportShmCirc.numMsgs// The number of messages or slots in the circular buffer = UInt 32;
 
    TransportShmCirc.common$// Common module configuration parameters = Types.Common$ undefined;
    TransportShmCirc.rovViewInfo//  = ViewInfo.Instance ViewInfo.create;
per-instance config parameters
    var params = new TransportShmCirc.Params// Instance config-params object;
        params.priority// Which priority messages should this transport manage = UInt 0;
        params.sharedAddr// Address in shared memory where this instance will be placed = Ptr null;
per-instance creation
    var inst = TransportShmCirc.create// Create an instance-object(UInt16 procId, params);
 
 
enum TransportShmCirc.Reason
index URL

Reason for error function being called

XDCscript usage meta-domain
values of type TransportShmCirc.Reason
    const TransportShmCirc.Reason_FAILEDPUT;
    const TransportShmCirc.Reason_INTERNALERR;
    const TransportShmCirc.Reason_PHYSICALERR;
    const TransportShmCirc.Reason_FAILEDALLOC;
 
DETAILS
First field in the errFxn
C SYNOPSIS
TransportShmCirc_Reason
 
enum TransportShmCirc.Status
index URL

Transport return values

XDCscript usage meta-domain
values of type TransportShmCirc.Status
    const TransportShmCirc.S_SUCCESS;
    const TransportShmCirc.E_FAIL;
    const TransportShmCirc.E_ERROR;
 
DETAILS
  • S_SUCCESS: Operation was successful
  • E_FAIL: Operation resulted in a failure
  • E_ERROR: Operation resulted in an error.
C SYNOPSIS
TransportShmCirc_Status
 
config TransportShmCirc.enableStats  // module-wide
index URL

Enable statistics for sending an event

XDCscript usage meta-domain
TransportShmCirc.enableStats = Bool false;
 
DETAILS
If this parameter is to 'TRUE' and 'waitClear' is also set to TRUE when calling (@link #sendEvent(), then the module keeps track of the number of times the processor spins waiting for an empty slot and the max amount of time it waits.
C SYNOPSIS
TransportShmCirc_enableStats
 
config TransportShmCirc.errFxn  // module-wide
index URL

Asynchronous error function for the transport module

XDCscript usage meta-domain
TransportShmCirc.errFxn = Void(*)(IMessageQTransport.Reason,IMessageQTransport.Handle,Ptr,UArg) null;
 
C SYNOPSIS
TransportShmCirc_errFxn
 
config TransportShmCirc.notifyEventId  // module-wide
index URL

Notify event ID for transport

XDCscript usage meta-domain
TransportShmCirc.notifyEventId = UInt16 2;
 
C SYNOPSIS
TransportShmCirc_notifyEventId
 
config TransportShmCirc.numMsgs  // module-wide
index URL

The number of messages or slots in the circular buffer

XDCscript usage meta-domain
TransportShmCirc.numMsgs = UInt 32;
 
DETAILS
This is use to determine the size of the put and get buffers. Each eventEntry is two 32bits wide, therefore the total size of each circular buffer is [numMsgs * sizeof(eventEntry)]. The total size of each buffer must be a multiple of the the cache line size. For example, if the cacheLineSize = 128 then numMsgs could be 16, 32, etc...
C SYNOPSIS
TransportShmCirc_numMsgs
 
metaonly config TransportShmCirc.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
TransportShmCirc.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 TransportShmCirc.rovViewInfo  // module-wide
index URL
XDCscript usage meta-domain
TransportShmCirc.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new TransportShmCirc.Params;
// Instance config-params object
    params.priority = UInt 0;
    // Which priority messages should this transport manage
    params.sharedAddr = Ptr null;
    // Address in shared memory where this instance will be placed
 
config TransportShmCirc.priority  // instance
index URL

Which priority messages should this transport manage

XDCscript usage meta-domain
var params = new TransportShmCirc.Params;
  ...
params.priority = UInt 0;
 
C SYNOPSIS
null
 
config TransportShmCirc.sharedAddr  // instance
index URL

Address in shared memory where this instance will be placed

XDCscript usage meta-domain
var params = new TransportShmCirc.Params;
  ...
params.sharedAddr = Ptr null;
 
DETAILS
Use sharedMemReq to determine the amount of shared memory required.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new TransportShmCirc.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = TransportShmCirc.create(UInt16 procId, params);
// Create an instance-object
ARGUMENTS
procId — Remote processor id that this instance will communicate with.
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
This function creates a transport instance. The transport is responsible for registering with MessageQ via the ti.sdo.ipc.MessageQ.registerTransport API.
generated on Sat, 11 Feb 2012 00:38:12 GMT