1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32
33 34 35
36
37 package ti.uia.runtime;
38
39 /*!
40 * ======== Transport ========
41 * Transport function specification module
42 *
43 * This module defines the function prototypes for the transport functions
44 * that can be plugged into the ServiceMgr. UIA ships several
45 * implementations of this interface in the ti/uia/sysbios directory.
46 *
47 * The implementations do not have to be XDC modules. They are simply standard
48 * 'C' functions (i.e look at ti/uia/sysbios/TransportNdk.c). Only one
49 * transport set can be used on a target and it needs to be set up at build
50 * time via the {@link ti.uia.runtime.ServiceMgr#transportFxns} parameter. The
51 * ServiceMgr plugs the transportFxns automatically based on the TransportType
52 * {@link ti.uia.runtime.ServiceMgr#transportType}.
53 *
54 * If someone writes an new transport
55 * (e.g. RapidIO), they can be plugged in by setting the TransportType
56 * to {@link ti.uia.runtime.ServiceMgr#TransportType_USER} and then plugging
57 * the transportFxns manually. It must also set up the following parameters
58 * as directed by the new transport developer.
59 * @p(blist)
60 * -ServiceMgr.supportControl: does the transport support receiving messages
61 * from the host. For example TransportFile does not.
62 * -ServiceMgr.maxEventPacketSize: Max size of an outgoing event packet. For
63 * example TransportNdk uses 1472 (emac size minus headers)
64 * -ServiceMgr.maxCtrlPacketSize: Max size of the message packets. This can
65 * be zero if supportControl is false.
66 * @p
67 *
68 * Here is an example of plugging the transport XYZ into the ServiceMgr:
69 * @p(code)
70 * var ServiceMgr = xdc.useModule('ti.uia.runtime.ServiceMgr');
71 * ServiceMgr.transportType = ServiceMgr.TransportType_USER;
72 * var xyzTransport = {
73 * initFxn: '&TransportXYZ_init',
74 * startFxn: '&TransportXYZ_start',
75 * recvFxn: '&TransportXYZ_recv',
76 * sendFxn: '&TransportXYZ_send',
77 * stopFxn: '&TransportXYZ_stop',
78 * exitFxn: '&TransportXYZ_exit',
79 * };
80 * ServiceMgr.transportFxns = xyzTransport;
81 *
82 * ServiceMgr.maxEventPacketSize = 1024
83 * ServiceMgr.maxCtrlPacketSize = 1024;
84 * ServiceMgr.supportControl = true;
85 * @p
86 *
87 * @p(html)
88 * <a name="transportfxn"></a>
89 *
90 * @a(Transport Functions)
91 *
92 * The following are the transport functions. Note
93 * all of these functions
94 * are called by the ServiceMgr. The application should not be calling
95 * these functions directly.
96 * @p(blist)
97 * -initFxn: Called during module startup (which is before main()). Minimal
98 * actions can take place here since there are no interrupts and
99 * the state of the application is just starting up. Generally only
100 * internal initialization is done in this function.
101 *
102 * -startFxn: The start function is called at once or twice after the SYS/BIOS
103 * tasks have started to run. The start
104 * function is called with UIAPacket_HdrType_EventPkt before any
105 * events are sent. This allows the transport to initialize
106 * anything needed for event transmission. The function returns a
107 * handle to a transport specific structure (or NULL if not needed).
108 * This handle is passed into the sendFxn and stopFxn.
109 *
110 * If the transport supports control messages from a host, the
111 * start function is called with UIAPacket_HdrType_Msg.
112 * This allows the transport to initialize anything needed for
113 * msg transmission (both sending and receiving). Again, the
114 * transport can return a transport specific structure. This
115 * structure can be different from the one returned in the
116 * UIAPacket_HdrType_EventPkt start.
117 *
118 * -recvFxn: The recv function is called to receive incoming messages
119 * from the host. The handle returned from the start is passed
120 * into the recv. Also passed in is a buffer and its size.
121 * The buffer is passed in as a double pointer. This allows
122 * the transport to double-buffer. For example, the recv
123 * function can return a different buffer than what was
124 * passed in. This potentially reduces extra copies of the data.
125 *
126 * The recv can be a blocking call.
127 *
128 * The recv returns the actual number of bytes that are placed into
129 * the buffer. If the transport does not
130 * support control messages, this function can simply return zero.
131 *
132 * -sendFxn: The send function is called to send either events or msgs. If
133 * send is called to transmit a event, the first parameter is the
134 * handle returned from the start(UIAPacket_HdrType_EventPkt).
135 * Similiarily, if a message is being sent, the first parameter is
136 * the handle returned from the start(UIAPacket_HdrType_Msg).
137 * The size of the packet is maintained in the UIAPacket_Hdr.
138 *
139 * The send can be a blocking call.
140 *
141 * This function returns whether the send was successful or not.
142 *
143 * Again a double pointer is used to allow the transport to return
144 * a different buffer to allow double-buffering.
145 *
146 * -stopFxn: The stop function is to counterpart to the start function. The
147 * stop will be called the same number of times as the start. The
148 * calls will contain handles returned from the start.
149 *
150 * -exitFxn: The exit function is to counterpart to the init function.
151 * @p
152 *
153 * Transport are allowed to have additional functions that can be directly
154 * called by the application. For example in ti/uia/sysbiosTransportFile,
155 * there is a TransportFile_setFile function. The downside to the extended
156 * functions is portability.
157 */
158 module Transport
159 {
160 /*!
161 * Task hook set type definition.
162 *
163 * See {@link #transportfxn Transport Functions} for details.
164 */
165 struct FxnSet {
166 Void (*initFxn)();
167 Ptr (*startFxn)(UIAPacket.HdrType);
168 SizeT (*recvFxn)(Ptr, UIAPacket.Hdr **, SizeT);
169 Bool (*sendFxn)(Ptr, UIAPacket.Hdr **);
170 Void (*stopFxn)(Ptr);
171 Void (*exitFxn)(Void);
172 };
173 }