module ti.sdo.ipc.transports.TransportShm

Shared-memory MessageQ transport that uses ListMP to queue messages

Messages sent via TransportShm are temporarily queued in a shared memory ti.sdo.ipc.ListMP instance before the messages are moved by the receiver to the destination queue.
C synopsis target-domain sourced in ti/sdo/ipc/transports/TransportShm.xdc
#include <ti/sdo/ipc/transports/TransportShm.h>
Functions
Void 
Void
Void
Void
Void
Functions common to all IMessageQTransport modules
Bool 
Int 
Bool 
Void 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef Void 
typedef struct
typedef struct
typedef enum
typedef enum
typedef struct
Constants
extern const UInt16 
 
 
enum TransportShm_Reason

Reason for error function being called

C synopsis target-domain
typedef enum TransportShm_Reason {
    TransportShm_Reason_FAILEDPUT,
    TransportShm_Reason_INTERNALERR,
    TransportShm_Reason_PHYSICALERR,
    TransportShm_Reason_FAILEDALLOC
} TransportShm_Reason;
 
DETAILS
First field in the errFxn
 
enum TransportShm_Status

Transport return values

C synopsis target-domain
typedef enum TransportShm_Status {
    TransportShm_S_SUCCESS,
    TransportShm_E_FAIL,
    TransportShm_E_ERROR
} TransportShm_Status;
 
DETAILS
  • S_SUCCESS: Operation was successful
  • E_FAIL: Operation resulted in a failure
  • E_ERROR: Operation resulted in an error.
 
typedef TransportShm_ErrFxn

Typedef for transport error callback function

C synopsis target-domain
typedef Void (*TransportShm_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 TransportShm_errFxn  // module-wide

Asynchronous error function for the transport module

C synopsis target-domain
extern const IMessageQTransport_ErrFxn TransportShm_errFxn;
 
 
config TransportShm_notifyEventId  // module-wide

Notify event ID for transport

C synopsis target-domain
extern const UInt16 TransportShm_notifyEventId;
 
 
TransportShm_close()  // module-wide

Close an opened instance

C synopsis target-domain
Void TransportShm_close(TransportShm_Handle *handle);
 
ARGUMENTS
handle — handle that is returned from an openByAddr
DETAILS
Closing an instance will free local memory consumed by the opened instance. Instances that are opened should be closed before the instance is deleted.
 
TransportShm_setErrFxn()  // module-wide

Sets the asynchronous error function for the transport module

C synopsis target-domain
Void TransportShm_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

C synopsis target-domain
Types_ModuleId TransportShm_Module_id();
// Get this module's unique id
 
Bool TransportShm_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle TransportShm_Module_heap();
// The heap from which this module allocates memory
 
Bool TransportShm_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 TransportShm_Module_getMask();
// Returns the diagnostics mask for this module
 
Void TransportShm_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct TransportShm_Object TransportShm_Object;
// Opaque internal representation of an instance object
 
typedef TransportShm_Object *TransportShm_Handle;
// Client reference to an instance object
 
typedef struct TransportShm_Struct TransportShm_Struct;
// Opaque client structure large enough to hold an instance object
 
TransportShm_Handle TransportShm_handle(TransportShm_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
TransportShm_Struct *TransportShm_struct(TransportShm_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct TransportShm_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    GateMP_Handle gate;
    // GateMP used for critical region management of the shared memory
    UInt priority;
    // Which priority messages should this transport manage
    Ptr sharedAddr;
    // Physical address of the shared memory
} TransportShm_Params;
 
Void TransportShm_Params_init(TransportShm_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config TransportShm_gate  // instance

GateMP used for critical region management of the shared memory

C synopsis target-domain
      ...
    GateMP_Handle gate;
 
 
config TransportShm_priority  // instance

Which priority messages should this transport manage

C synopsis target-domain
      ...
    UInt priority;
 
 
config TransportShm_sharedAddr  // instance

Physical address of the shared memory

C synopsis target-domain
      ...
    Ptr sharedAddr;
 
DETAILS
The creator must supply the shared memory that is used to maintain shared state information.
Instance Creation

C synopsis target-domain
TransportShm_Handle TransportShm_create(UInt16 procId, const TransportShm_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void TransportShm_construct(TransportShm_Struct *structP, UInt16 procId, const TransportShm_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

C synopsis target-domain
Void TransportShm_delete(TransportShm_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void TransportShm_destruct(TransportShm_Struct *structP);
// Finalize the instance object inside the provided structure
 
TransportShm_control()  // instance

Send a control command to the transport instance

C synopsis target-domain
Bool TransportShm_control(TransportShm_Handle handle, UInt cmd, UArg cmdArg);
 
ARGUMENTS
handle — handle of a previously-created TransportShm 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.
 
TransportShm_getStatus()  // instance

Status of a Transport instance

C synopsis target-domain
Int TransportShm_getStatus(TransportShm_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created TransportShm instance object
RETURNS
Returns status of Transport instance
DETAILS
This function returns the status of the transport instance.
 
TransportShm_put()  // instance

Put the message to the remote processor

C synopsis target-domain
Bool TransportShm_put(TransportShm_Handle handle, Ptr msg);
 
ARGUMENTS
handle — handle of a previously-created TransportShm 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

C synopsis target-domain
IMessageQTransport_Handle TransportShm_Handle_upCast(TransportShm_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
TransportShm_Handle TransportShm_Handle_downCast(IMessageQTransport_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int TransportShm_Object_count();
// The number of statically-created instance objects
 
TransportShm_Handle TransportShm_Object_get(TransportShm_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
TransportShm_Handle TransportShm_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
TransportShm_Handle TransportShm_Object_next(TransportShm_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle TransportShm_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *TransportShm_Handle_label(TransportShm_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String TransportShm_Handle_name(TransportShm_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sdo/ipc/transports/TransportShm.xdc
var TransportShm = xdc.useModule('ti.sdo.ipc.transports.TransportShm');
module-wide constants & types
        const TransportShm.Reason_FAILEDPUT;
        const TransportShm.Reason_INTERNALERR;
        const TransportShm.Reason_PHYSICALERR;
        const TransportShm.Reason_FAILEDALLOC;
 
        const TransportShm.S_SUCCESS;
        const TransportShm.E_FAIL;
        const TransportShm.E_ERROR;
module-wide config parameters
 
per-instance config parameters
    var params = new TransportShm.Params// Instance config-params object;
        params.sharedAddr// Physical address of the shared memory = Ptr null;
per-instance creation
    var inst = TransportShm.create// Create an instance-object(UInt16 procId, params);
 
 
enum TransportShm.Reason

Reason for error function being called

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

Transport return values

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

Asynchronous error function for the transport module

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

Notify event ID for transport

XDCscript usage meta-domain
TransportShm.notifyEventId = UInt16 2;
 
C SYNOPSIS
 
metaonly config TransportShm.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
TransportShm.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.
Instance Config Parameters

XDCscript usage meta-domain
var params = new TransportShm.Params;
// Instance config-params object
    params.gate = GateMP.Handle null;
    // GateMP used for critical region management of the shared memory
    params.priority = UInt 0;
    // Which priority messages should this transport manage
    params.sharedAddr = Ptr null;
    // Physical address of the shared memory
 
config TransportShm.gate  // instance

GateMP used for critical region management of the shared memory

XDCscript usage meta-domain
var params = new TransportShm.Params;
  ...
params.gate = GateMP.Handle null;
 
C SYNOPSIS
 
config TransportShm.priority  // instance

Which priority messages should this transport manage

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

Physical address of the shared memory

XDCscript usage meta-domain
var params = new TransportShm.Params;
  ...
params.sharedAddr = Ptr null;
 
DETAILS
The creator must supply the shared memory that is used to maintain shared state information.
C SYNOPSIS
Instance Creation

XDCscript usage meta-domain
var params = new TransportShm.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = TransportShm.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