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

Transport for MessageQ that acts on shared memory

TransportShmSingle is a simplified version of TransportShm. This transport uses the Notify module to do all the real work. The 'put' function passes the message to the other processor using the 'payload' parameter to Notify_sendEvent(). The receive side simply casts this payload parameter to a MessageQ_Msg and enqueues it locally. [ more ... ]
C synopsis target-domain sourced in ti/sdo/ipc/transports/TransportShmNotify.xdc
#include <ti/sdo/ipc/transports/TransportShmNotify.h>
Functions
Void
TransportShmNotify_construct// Initialize a new instance object inside the provided structure(TransportShmNotify_Struct *structP, UInt16 procId, const TransportShmNotify_Params *params, Error_Block *eb);
TransportShmNotify_Handle
TransportShmNotify_create// Allocate and initialize a new instance object and return its handle(UInt16 procId, const TransportShmNotify_Params *params, Error_Block *eb);
Void
TransportShmNotify_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(TransportShmNotify_Handle *handleP);
Void
TransportShmNotify_destruct// Finalize the instance object inside the provided structure(TransportShmNotify_Struct *structP);
Void
TransportShmNotify_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(TransportShmNotify_Params *params);
Functions common to all IMessageQTransport modules
Bool 
TransportShmNotify_control// Send a control command to the transport instance(TransportShmNotify_Handle handle, UInt cmd, UArg cmdArg);
Int 
TransportShmNotify_getStatus// Status of a Transport instance(TransportShmNotify_Handle handle);
Bool 
TransportShmNotify_put// Put the message to the remote processor(TransportShmNotify_Handle handle, Ptr msg);
Void 
TransportShmNotify_setErrFxn// Sets the asynchronous error function for the transport module(IMessageQTransport_ErrFxn errFxn);
Functions common to all target instances
TransportShmNotify_handle// Convert this instance structure pointer into an instance handle, TransportShmNotify_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, TransportShmNotify_Handle_label// The label associated with this instance object, TransportShmNotify_Handle_name// The name of this instance object, TransportShmNotify_Handle_upCast// unconditionally move one level up the inheritance hierarchy, TransportShmNotify_Object_count// The number of statically-created instance objects, TransportShmNotify_Object_first// The handle of the first dynamically-created instance object, or NULL, TransportShmNotify_Object_get// The handle of the i-th statically-created instance object (array == NULL), TransportShmNotify_Object_heap// The heap used to allocate dynamically-created instance objects, TransportShmNotify_Object_next// The handle of the next dynamically-created instance object, or NULL, TransportShmNotify_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
TransportShmNotify_Module_getMask// Returns the diagnostics mask for this module, TransportShmNotify_Module_hasMask// Test whether this module has a diagnostics mask, TransportShmNotify_Module_heap// The heap from which this module allocates memory, TransportShmNotify_Module_id// Get this module's unique id, TransportShmNotify_Module_setMask// Set the diagnostics mask for this module, TransportShmNotify_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Void 
(*TransportShmNotify_ErrFxn// Typedef for transport error callback function)(IMessageQTransport_Reason,IMessageQTransport_Handle,Ptr,UArg);
typedef TransportShmNotify_Object *
TransportShmNotify_Handle// Client reference to an instance object;
typedef struct
TransportShmNotify_Object// Opaque internal representation of an instance object TransportShmNotify_Object;
typedef struct
TransportShmNotify_Params// Instance config-params structure ...
typedef enum
TransportShmNotify_Reason// Reason for error function being called ...
typedef enum
TransportShmNotify_Status// Transport return values ...
typedef struct
TransportShmNotify_Struct// Opaque client structure large enough to hold an instance object TransportShmNotify_Struct;
Constants
extern const IMessageQTransport_ErrFxn 
TransportShmNotify_errFxn// Asynchronous error function for the transport module;
extern const UInt16 
TransportShmNotify_notifyEventId// Notify event ID for transport;
 
DETAILS
TransportShmSingle is a simplified version of TransportShm. This transport uses the Notify module to do all the real work. The 'put' function passes the message to the other processor using the 'payload' parameter to Notify_sendEvent(). The receive side simply casts this payload parameter to a MessageQ_Msg and enqueues it locally.
CAVEATS:
The sender will spin in Notify_sendEvent until the receive side has read the previous message. This is Notify-driver specific. NotifyDriverShm will spin before sending a new event if the prior event hasn't been handled. Some Notify drivers may support a FIFO or queue for these events to mitigate this busy-wait affect.
 
enum TransportShmNotify_Reason
index URL

Reason for error function being called

C synopsis target-domain
typedef enum TransportShmNotify_Reason {
    TransportShmNotify_Reason_FAILEDPUT,
    TransportShmNotify_Reason_INTERNALERR,
    TransportShmNotify_Reason_PHYSICALERR,
    TransportShmNotify_Reason_FAILEDALLOC
} TransportShmNotify_Reason;
 
DETAILS
First field in the errFxn
 
enum TransportShmNotify_Status
index URL

Transport return values

C synopsis target-domain
typedef enum TransportShmNotify_Status {
    TransportShmNotify_S_SUCCESS,
    TransportShmNotify_E_FAIL,
    TransportShmNotify_E_ERROR
} TransportShmNotify_Status;
 
DETAILS
  • S_SUCCESS: Operation was successful
  • E_FAIL: Operation resulted in a failure
  • E_ERROR: Operation resulted in an error.
 
typedef TransportShmNotify_ErrFxn
index URL

Typedef for transport error callback function

C synopsis target-domain
typedef Void (*TransportShmNotify_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 TransportShmNotify_errFxn  // module-wide
index URL

Asynchronous error function for the transport module

C synopsis target-domain
extern const IMessageQTransport_ErrFxn TransportShmNotify_errFxn;
 
 
config TransportShmNotify_notifyEventId  // module-wide
index URL

Notify event ID for transport

C synopsis target-domain
extern const UInt16 TransportShmNotify_notifyEventId;
 
 
TransportShmNotify_setErrFxn()  // module-wide
index URL

Sets the asynchronous error function for the transport module

C synopsis target-domain
Void TransportShmNotify_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 TransportShmNotify_Module_id();
// Get this module's unique id
 
Bool TransportShmNotify_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle TransportShmNotify_Module_heap();
// The heap from which this module allocates memory
 
Bool TransportShmNotify_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 TransportShmNotify_Module_getMask();
// Returns the diagnostics mask for this module
 
Void TransportShmNotify_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct TransportShmNotify_Object TransportShmNotify_Object;
// Opaque internal representation of an instance object
 
typedef TransportShmNotify_Object *TransportShmNotify_Handle;
// Client reference to an instance object
 
typedef struct TransportShmNotify_Struct TransportShmNotify_Struct;
// Opaque client structure large enough to hold an instance object
 
TransportShmNotify_Handle TransportShmNotify_handle(TransportShmNotify_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
TransportShmNotify_Struct *TransportShmNotify_struct(TransportShmNotify_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct TransportShmNotify_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    UInt priority;
    // Which priority messages should this transport manage
} TransportShmNotify_Params;
 
Void TransportShmNotify_Params_init(TransportShmNotify_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config TransportShmNotify_priority  // instance
index URL

Which priority messages should this transport manage

C synopsis target-domain
struct TransportShmNotify_Params {
      ...
    UInt priority;
 
Instance Creation
index URL

C synopsis target-domain
TransportShmNotify_Handle TransportShmNotify_create(UInt16 procId, const TransportShmNotify_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void TransportShmNotify_construct(TransportShmNotify_Struct *structP, UInt16 procId, const TransportShmNotify_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 TransportShmNotify_delete(TransportShmNotify_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void TransportShmNotify_destruct(TransportShmNotify_Struct *structP);
// Finalize the instance object inside the provided structure
 
TransportShmNotify_control()  // instance
index URL

Send a control command to the transport instance

C synopsis target-domain
Bool TransportShmNotify_control(TransportShmNotify_Handle handle, UInt cmd, UArg cmdArg);
 
ARGUMENTS
handle — handle of a previously-created TransportShmNotify 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.
 
TransportShmNotify_getStatus()  // instance
index URL

Status of a Transport instance

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

Put the message to the remote processor

C synopsis target-domain
Bool TransportShmNotify_put(TransportShmNotify_Handle handle, Ptr msg);
 
ARGUMENTS
handle — handle of a previously-created TransportShmNotify 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 TransportShmNotify_Handle_upCast(TransportShmNotify_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
TransportShmNotify_Handle TransportShmNotify_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 TransportShmNotify_Object_count();
// The number of statically-created instance objects
 
TransportShmNotify_Handle TransportShmNotify_Object_get(TransportShmNotify_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
TransportShmNotify_Handle TransportShmNotify_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
TransportShmNotify_Handle TransportShmNotify_Object_next(TransportShmNotify_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle TransportShmNotify_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *TransportShmNotify_Handle_label(TransportShmNotify_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String TransportShmNotify_Handle_name(TransportShmNotify_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sdo/ipc/transports/TransportShmNotify.xdc
var TransportShmNotify = xdc.useModule('ti.sdo.ipc.transports.TransportShmNotify');
module-wide constants & types
    values of type TransportShmNotify.Reason// Reason for error function being called
        const TransportShmNotify.Reason_FAILEDPUT;
        const TransportShmNotify.Reason_INTERNALERR;
        const TransportShmNotify.Reason_PHYSICALERR;
        const TransportShmNotify.Reason_FAILEDALLOC;
 
    values of type TransportShmNotify.Status// Transport return values
        const TransportShmNotify.S_SUCCESS;
        const TransportShmNotify.E_FAIL;
        const TransportShmNotify.E_ERROR;
module-wide config parameters
    TransportShmNotify.errFxn// Asynchronous error function for the transport module = Void(*)(IMessageQTransport.Reason,IMessageQTransport.Handle,Ptr,UArg) null;
    TransportShmNotify.notifyEventId// Notify event ID for transport = UInt16 2;
 
    TransportShmNotify.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new TransportShmNotify.Params// Instance config-params object;
        params.priority// Which priority messages should this transport manage = UInt 0;
per-instance creation
    var inst = TransportShmNotify.create// Create an instance-object(UInt16 procId, params);
 
 
enum TransportShmNotify.Reason
index URL

Reason for error function being called

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

Transport return values

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

Asynchronous error function for the transport module

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

Notify event ID for transport

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

Common module configuration parameters

XDCscript usage meta-domain
TransportShmNotify.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
index URL

XDCscript usage meta-domain
var params = new TransportShmNotify.Params;
// Instance config-params object
    params.priority = UInt 0;
    // Which priority messages should this transport manage
 
config TransportShmNotify.priority  // instance
index URL

Which priority messages should this transport manage

XDCscript usage meta-domain
var params = new TransportShmNotify.Params;
  ...
params.priority = UInt 0;
 
C SYNOPSIS
null
Instance Creation
index URL

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