module ti.uia.runtime.Transport

Transport function specification module

This module defines the function prototypes for the transport functions that can be plugged into the ServiceMgr. UIA ships several implementations of this interface in the ti/uia/sysbios directory. [ more ... ]
C synopsis target-domain sourced in ti/uia/runtime/Transport.xdc
DETAILS
This module defines the function prototypes for the transport functions that can be plugged into the ServiceMgr. UIA ships several implementations of this interface in the ti/uia/sysbios directory.
The implementations do not have to be XDC modules. They are simply standard 'C' functions (i.e look at ti/uia/sysbios/TransportNdk.c). Only one transport set can be used on a target and it needs to be set up at build time via the ti.uia.runtime.ServiceMgr.transportFxns parameter. The ServiceMgr plugs the transportFxns automatically based on the TransportType ti.uia.runtime.ServiceMgr.transportType.
If someone writes an new transport (e.g. RapidIO), they can be plugged in by setting the TransportType to ti.uia.runtime.ServiceMgr.TransportType_USER and then plugging the transportFxns manually. It must also set up the following parameters as directed by the new transport developer.
  • ServiceMgr.supportControl: does the transport support receiving messages from the host. For example TransportFile does not.
  • ServiceMgr.maxEventPacketSize: Max size of an outgoing event packet. For example TransportNdk uses 1472 (emac size minus headers)
  • ServiceMgr.maxCtrlPacketSize: Max size of the message packets. This can be zero if supportControl is false.
Here is an example of plugging the transport XYZ into the ServiceMgr:
  var ServiceMgr = xdc.useModule('ti.uia.runtime.ServiceMgr');
  ServiceMgr.transportType = ServiceMgr.TransportType_USER;
  var xyzTransport = {
      initFxn: '&TransportXYZ_init',
      startFxn: '&TransportXYZ_start',
      recvFxn: '&TransportXYZ_recv',
      sendFxn: '&TransportXYZ_send',
      stopFxn: '&TransportXYZ_stop',
      exitFxn: '&TransportXYZ_exit',
  };
  ServiceMgr.transportFxns = xyzTransport;

  ServiceMgr.maxEventPacketSize = 1024
  ServiceMgr.maxCtrlPacketSize  = 1024;
  ServiceMgr.supportControl     = true;
TRANSPORT FUNCTIONS
The following are the transport functions. Note all of these functions are called by the ServiceMgr. The application should not be calling these functions directly.
  • initFxn: Called during module startup (which is before main()). Minimal actions can take place here since there are no interrupts and the state of the application is just starting up. Generally only internal initialization is done in this function.
  • startFxn: The start function is called at once or twice after the SYS/BIOS tasks have started to run. The start function is called with UIAPacket_HdrType_EventPkt before any events are sent. This allows the transport to initialize anything needed for event transmission. The function returns a handle to a transport specific structure (or NULL if not needed). This handle is passed into the sendFxn and stopFxn. If the transport supports control messages from a host, the start function is called with UIAPacket_HdrType_Msg. This allows the transport to initialize anything needed for msg transmission (both sending and receiving). Again, the transport can return a transport specific structure. This structure can be different from the one returned in the UIAPacket_HdrType_EventPkt start.
  • recvFxn: The recv function is called to receive incoming messages from the host. The handle returned from the start is passed into the recv. Also passed in is a buffer and its size. The buffer is passed in as a double pointer. This allows the transport to double-buffer. For example, the recv function can return a different buffer than what was passed in. This potentially reduces extra copies of the data. The recv can be a blocking call. The recv returns the actual number of bytes that are placed into the buffer. If the transport does not support control messages, this function can simply return zero.
  • sendFxn: The send function is called to send either events or msgs. If send is called to transmit a event, the first parameter is the handle returned from the start(UIAPacket_HdrType_EventPkt). Similiarily, if a message is being sent, the first parameter is the handle returned from the start(UIAPacket_HdrType_Msg). The size of the packet is maintained in the UIAPacket_Hdr. The send can be a blocking call. This function returns whether the send was successful or not. Again a double pointer is used to allow the transport to return a different buffer to allow double-buffering.
  • stopFxn: The stop function is to counterpart to the start function. The stop will be called the same number of times as the start. The calls will contain handles returned from the start.
  • exitFxn: The exit function is to counterpart to the init function.
Transport are allowed to have additional functions that can be directly called by the application. For example in ti/uia/sysbiosTransportFile, there is a TransportFile_setFile function. The downside to the extended functions is portability.
 
struct Transport_FxnSet

Task hook set type definition

C synopsis target-domain
typedef struct Transport_FxnSet {
    Void (*initFxn)();
    Ptr (*startFxn)(UIAPacket_HdrType);
    SizeT (*recvFxn)(Ptr,UIAPacket_Hdr**,SizeT);
    Bool (*sendFxn)(Ptr,UIAPacket_Hdr**);
    Void (*stopFxn)(Ptr);
    Void (*exitFxn)(Void);
} Transport_FxnSet;
 
DETAILS
See Transport Functions for details.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId Transport_Module_id();
// Get this module's unique id
 
Bool Transport_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Transport_Module_heap();
// The heap from which this module allocates memory
 
Bool Transport_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Transport_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Transport_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in ti/uia/runtime/Transport.xdc
var Transport = xdc.useModule('ti.uia.runtime.Transport');
module-wide constants & types
        obj.initFxn = Void(*)()  ...
        obj.startFxn = Ptr(*)(UIAPacket.HdrType)  ...
        obj.recvFxn = SizeT(*)(Ptr,UIAPacket.Hdr**,SizeT)  ...
        obj.sendFxn = Bool(*)(Ptr,UIAPacket.Hdr**)  ...
        obj.stopFxn = Void(*)(Ptr)  ...
        obj.exitFxn = Void(*)(Void)  ...
module-wide config parameters
 
 
struct Transport.FxnSet

Task hook set type definition

XDCscript usage meta-domain
var obj = new Transport.FxnSet;
 
    obj.initFxn = Void(*)()  ...
    obj.startFxn = Ptr(*)(UIAPacket.HdrType)  ...
    obj.recvFxn = SizeT(*)(Ptr,UIAPacket.Hdr**,SizeT)  ...
    obj.sendFxn = Bool(*)(Ptr,UIAPacket.Hdr**)  ...
    obj.stopFxn = Void(*)(Ptr)  ...
    obj.exitFxn = Void(*)(Void)  ...
 
DETAILS
See Transport Functions for details.
C SYNOPSIS
 
metaonly config Transport.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
Transport.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.
generated on Mon, 28 Jan 2013 17:45:45 GMT