1 /**
2 * @file rm_transport.h
3 *
4 * @brief
5 * This is the RM include file for the generic transport interface
6 * used by RM to exchange RM control signals and data between RM instances
7 *
8 * \par
9 * ============================================================================
10 * @n (C) Copyright 2012-2014, Texas Instruments, Inc.
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions
14 * are met:
15 *
16 * Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer.
18 *
19 * Redistributions in binary form must reproduce the above copyright
20 * notice, this list of conditions and the following disclaimer in the
21 * documentation and/or other materials provided with the
22 * distribution.
23 *
24 * Neither the name of Texas Instruments Incorporated nor the names of
25 * its contributors may be used to endorse or promote products derived
26 * from this software without specific prior written permission.
27 *
28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 *
40 * \par
41 */
43 #ifndef RM_TRANSPORT_H_
44 #define RM_TRANSPORT_H_
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
50 /* Standard includes */
51 #include <stdbool.h>
53 /* RM includes */
54 #include <ti/drv/rm/rm.h>
56 /**
57 @addtogroup RM_TRANSPORT_API
58 @{
59 */
61 /**
62 * @brief Maximum size of RM transport packet
63 */
64 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (256)
66 /**
67 * @brief RM transport handle
68 */
69 typedef void *Rm_TransportHandle;
71 /**
72 * @brief Application transport handle. Void casted application transport
73 * data structure. The Rm_AppTransportHandle provided by the
74 * application could be anything from a queue number to a pointer
75 * to an application transport data structure. RM will provide
76 * a Rm_AppTransportHandle to the application any time RM
77 * wants to alloc or send a packet via the transport callouts
78 */
79 typedef void *Rm_AppTransportHandle;
81 /**
82 * @brief A void pointer to the start of a registered application transport
83 * packet buffer. The Rm_PacketHandle may be different from the
84 * Rm_Packet pointer based on the application transport. For example,
85 * for a QMSS based transport the Rm_PacketHandle may point to the
86 * beginning of a Host descriptor where as the Rm_Packet pointer would
87 * point to the beginning of the data buffer linked with the Host
88 * descriptor.
89 */
90 typedef void *Rm_PacketHandle;
92 /**
93 * @brief RM packet types
94 */
95 typedef enum {
96 /** Allocate/Free request packet */
97 Rm_pktType_RESOURCE_REQUEST = 0,
98 /** Allocate/Free response packet */
99 Rm_pktType_RESOURCE_RESPONSE,
100 /** RM NameServer mapping request */
101 Rm_pktType_NAMESERVER_REQUEST,
102 /** RM NameServer mapping response */
103 Rm_pktType_NAMESERVER_RESPONSE
104 } Rm_pktType;
106 /**
107 * @brief RM transport layer packet
108 */
109 typedef struct {
110 /** Packet length in bytes. Written by application when allocated */
111 uint32_t pktLenBytes;
112 /** Type of RM packet contained in data byte array */
113 Rm_pktType pktType;
114 /** Byte array containing RM packet data */
115 char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
116 } Rm_Packet;
118 /**
119 * @brief RM transport callout functions used by RM to allocate and send
120 * RM packets via the application data paths between RM instances
121 */
122 typedef struct {
123 /**
124 * @b Description
125 * @n
126 * This function pointer describes the RM transport layer packet
127 * allocation function. The application must supply an alloc function
128 * to RM instances at transport registration if the RM instance is
129 * intended to communicate with other RM instances. The function
130 * provided by the application must match this prototype. The provided
131 * function implements the allocation of packet buffers from the
132 * application data path that the RM transport will use to send messages
133 * between RM instances. The Rm_Packet pointer will point to start of
134 * the data buffer containing the RM packet data. The pktHandle will
135 * point to the start of the application data path "packet" data
136 * structure. The Rm_Packet pointer and pktHandle cannot be NULL. They
137 * will either be different or the same value based on the application
138 * transport.
139 *
140 * @param[in] appTransport
141 * Application transport handle to allocate packet from. This value
142 * is provided by the application at transport registration.
143 *
144 * @param[in] pktSize
145 * Size of buffer needed by RM for the RM packet. The application
146 * must place this value in the pktLenBytes field of the Rm_Packet.
147 * after the buffer has been allocated.
148 *
149 * @param[out] pktHandle
150 * Pointer to the start of the application's transport "packet".
151 * Could be the pointer to the start of a QMSS descriptor,
152 * network packet, etc.
153 *
154 * @retval
155 * Success - Pointer to allocated packet buffer.
156 * @retval
157 * Failure - NULL
158 */
159 Rm_Packet *(*rmAllocPkt)(Rm_AppTransportHandle appTransport, uint32_t pktSize,
160 Rm_PacketHandle *pktHandle);
161 /**
162 * @b Description
163 * @n
164 * This function pointer describes the RM transport layer packet
165 * send function. The application must supply a send function
166 * to RM instances at transport registration if the RM instance is
167 * intended to communicate with other RM instances. The function
168 * provided by the application must match this prototype. The provided
169 * function implements the sending of application data path packets,
170 * encapsulating RM packets, between RM instances. The pktHandle will
171 * point to the start of the application data path "packet" data
172 * structure.
173 *
174 * RM assumes that the application will free application data
175 * path packet and the buffer containing the Rm_Packet after
176 * the send operation.
177 *
178 * @param[in] appTransport
179 * Application transport handle to send packet on. This value
180 * is provided by the application at transport registration.
181 *
182 * @param[in] pktHandle
183 * Pointer to the start of the application's transport "packet".
184 * Could be the pointer to the start of a QMSS descriptor,
185 * network packet, etc.
186 *
187 * @retval
188 * 0 - Packet sent okay.
189 * @retval
190 * < 0 - Packet send failed.
191 */
192 int32_t (*rmSendPkt)(Rm_AppTransportHandle appTransport, Rm_PacketHandle pktHandle);
193 } Rm_TransportCallouts;
195 /**
196 * @brief RM transport registration configuration structure
197 */
198 typedef struct {
199 /** RM Handle for which the transport is being registered */
200 Rm_Handle rmHandle;
201 /** Application transport handle associated with the registered
202 * transport. This value can be anything that helps the application
203 * identify the application transport "pipe" for which a RM packet
204 * should be sent on. For example, a QMSS queue number, network
205 * port data structure, etc. */
206 Rm_AppTransportHandle appTransportHandle;
207 /** Remote RM instance type at other end of the application transport
208 * "pipe". */
209 Rm_InstType remoteInstType;
210 /** Pointers to application implemented transport APIs. The APIs for the
211 * provided functions must match the prototypes defined in the
212 * #Rm_TransportCallouts structure. Callouts need to be defined
213 * for each registered transport. However, based on the application's
214 * implementation of transport code the same function can be provided
215 * for each transport registration. In these cases, the transport
216 * must mux/demux the packets it receives from RM based on the
217 * #Rm_TransportHandle. */
218 Rm_TransportCallouts transportCallouts;
219 } Rm_TransportCfg;
221 /**
222 * @brief RM transport reconfiguration structure
223 */
224 typedef struct {
225 /** Application transport handle associated with the registered
226 * transport. This value can be anything that helps the application
227 * identify the application transport "pipe" for which a RM packet
228 * should be sent on. For example, a QMSS queue number, network
229 * port data structure, etc. */
230 Rm_AppTransportHandle appTransportHandle;
231 /** Pointers to application implemented transport APIs. The APIs for the
232 * provided functions must match the prototypes defined in the
233 * #Rm_TransportCallouts structure. Callouts need to be defined
234 * for each registered transport. However, based on the application's
235 * implementation of transport code the same function can be provided
236 * for each transport registration. In these cases, the transport
237 * must mux/demux the packets it receives from RM based on the
238 * #Rm_TransportHandle. */
239 Rm_TransportCallouts transportCallouts;
240 } Rm_TransportReCfg;
242 /**
243 * @b Description
244 * @n
245 * This function is used to register transports with RM for sending and
246 * receiving packets between RM instances over application transport
247 * data paths.
248 *
249 * RM Transport Restrictions:
250 * a) RM Servers cannot register with other Servers
251 * b) RM CDs cannot register with other CDs
252 * c) RM Clients cannot register with other Clients
253 * d) Clients cannot register with more than one CD or Server
254 * e) Clients cannot register with both a CD and Server (either or)
255 * f) CDs cannot register with more than one Server
256 *
257 * @param[in] transportCfg
258 * Pointer to the transport registration configuration structure.
259 *
260 * @param[out] result
261 * Pointer to a signed int used to return any errors encountered during
262 * the transport registration process.
263 *
264 * @retval
265 * Success - RM_TransportHandle and result = #RM_OK
266 * @retval
267 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_INVALID_REMOTE_INST_TYPE
268 * @retval
269 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_ALREADY_REGD_SERVER_OR_CD
270 * @retval
271 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD
272 * @retval
273 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_TRANSPORT_SEND_NOT_REGD
274 */
275 Rm_TransportHandle Rm_transportRegister(const Rm_TransportCfg *transportCfg, int32_t *result);
277 /**
278 * @b Description
279 * @n
280 * This function reconfigures an existing transport handle using the
281 * provided transport configurations
282 *
283 * @param[in] transportHandle
284 * Transport handle to unregister. The RM instance that the handle will
285 * be unregistered from is contained within the transportHandle.
286 *
287 * @param[in] transportReCfg
288 * Pointer to the transport registration configuration structure.
289 *
290 * @retval
291 * Success - #RM_OK
292 * @retval
293 * Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
294 */
295 int32_t Rm_transportReconfig (Rm_TransportHandle transportHandle, const Rm_TransportReCfg *transportReCfg);
297 /**
298 * @b Description
299 * @n
300 * This function unregisters the provided transportHandle from the
301 * RM instance
302 *
303 * @param[in] transportHandle
304 * Transport handle to unregister. The RM instance that the handle will
305 * be unregistered from is contained within the transportHandle.
306 *
307 * @retval
308 * Success - #RM_OK
309 * @retval
310 * Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
311 */
312 int32_t Rm_transportUnregister (Rm_TransportHandle transportHandle);
314 /**
315 * @b Description
316 * @n
317 * This function returns the RM instance name from which the service
318 * encapsulated within the RM packet originated
319 *
320 * Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
321 * and Rm_pktType_NAMESERVER_REQUEST packet types
322 *
323 * @param[in] pkt
324 * RM packet to extract service source instance name from.
325 *
326 * @param[out] serviceInstName
327 * Pointer to a character array that will contain the RM instance name
328 * that originated the service request. The character array MUST be
329 * #RM_NAME_MAX_CHARS bytes in length
330 *
331 * @param[in] charBufLen
332 * Length of the provided pktInstName buffer
333 *
334 * @retval
335 * Success - #RM_OK
336 * @retval
337 * Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
338 * Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
339 */
340 int32_t Rm_receiveGetPktServiceSrcName(const Rm_Packet *pkt, char *serviceInstName,
341 int32_t charBufLen);
343 /**
344 * @b Description
345 * @n
346 * This function returns the RM instance name from which the RM packet
347 * originated
348 *
349 * Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
350 * and Rm_pktType_NAMESERVER_REQUEST packet types
351 *
352 * @param[in] pkt
353 * RM packet to extract packet source instance name from.
354 *
355 * @param[out] pktInstName
356 * Pointer to a character array that will contain the RM instance name
357 * that originated the RM request packet. The character array MUST be
358 * #RM_NAME_MAX_CHARS bytes in length
359 *
360 * @param[in] charBufLen
361 * Length of the provided pktInstName buffer
362 *
363 * @retval
364 * Success - #RM_OK
365 * @retval
366 * Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
367 * Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
368 */
369 int32_t Rm_receiveGetPktSrcName(const Rm_Packet *pkt, char *pktInstName,
370 int32_t charBufLen);
372 /**
373 * @b Description
374 * @n
375 * This function is called by the application when it has received a RM
376 * packet for processing. The application provides the transportHandle
377 * associated with the RM instance that should receive the packet and
378 * a pointer to the data buffer containing the Rm_Packet.
379 *
380 * RM assumes that the application will free the data buffer containing
381 * the Rm_Packet after RM has finished processing the packet.
382 *
383 * @param[in] transportHandle
384 * RM transportHandle containing the instance that should process the
385 * received packet.
386 *
387 * @param[in] pkt
388 * Pointer to the data buffer containing the Rm_Packet
389 *
390 * @retval
391 * Success - #RM_OK
392 * @retval
393 * Failure - < #RM_OK
394 */
395 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle, const Rm_Packet *pkt);
397 /**
398 @}
399 */
401 #ifdef __cplusplus
402 }
403 #endif
405 #endif /* RM_TRANSPORT_H_ */