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-2015, 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
133 * messages between RM instances. The Rm_Packet pointer will point to
134 * start of the data buffer containing the RM packet data. The
135 * pktHandle will point to the start of the application data path
136 * "packet" data structure. The Rm_Packet pointer and pktHandle cannot
137 * be NULL. They will either be different or the same value based on
138 * the application 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,
160 uint32_t pktSize,
161 Rm_PacketHandle *pktHandle);
162 /**
163 * @b Description
164 * @n
165 * This function pointer describes the RM transport layer packet
166 * send function. The application must supply a send function
167 * to RM instances at transport registration if the RM instance is
168 * intended to communicate with other RM instances. The function
169 * provided by the application must match this prototype. The provided
170 * function implements the sending of application data path packets,
171 * encapsulating RM packets, between RM instances. The pktHandle will
172 * point to the start of the application data path "packet" data
173 * structure.
174 *
175 * RM assumes that the application will free application data
176 * path packet and the buffer containing the Rm_Packet after
177 * the send operation.
178 *
179 * @param[in] appTransport
180 * Application transport handle to send packet on. This value
181 * is provided by the application at transport registration.
182 *
183 * @param[in] pktHandle
184 * Pointer to the start of the application's transport "packet".
185 * Could be the pointer to the start of a QMSS descriptor,
186 * network packet, etc.
187 *
188 * @retval
189 * 0 - Packet sent okay.
190 * @retval
191 * < 0 - Packet send failed.
192 */
193 int32_t (*rmSendPkt)(Rm_AppTransportHandle appTransport,
194 Rm_PacketHandle pktHandle);
195 } Rm_TransportCallouts;
197 /**
198 * @brief RM transport registration configuration structure
199 */
200 typedef struct {
201 /** RM Handle for which the transport is being registered */
202 Rm_Handle rmHandle;
203 /** Application transport handle associated with the registered
204 * transport. This value can be anything that helps the application
205 * identify the application transport "pipe" for which a RM packet
206 * should be sent on. For example, a QMSS queue number, network
207 * port data structure, etc. */
208 Rm_AppTransportHandle appTransportHandle;
209 /** Remote RM instance type at other end of the application transport
210 * "pipe". */
211 Rm_InstType remoteInstType;
212 /** Pointers to application implemented transport APIs. The APIs for the
213 * provided functions must match the prototypes defined in the
214 * #Rm_TransportCallouts structure. Callouts need to be defined
215 * for each registered transport. However, based on the application's
216 * implementation of transport code the same function can be provided
217 * for each transport registration. In these cases, the transport
218 * must mux/demux the packets it receives from RM based on the
219 * #Rm_TransportHandle. */
220 Rm_TransportCallouts transportCallouts;
221 } Rm_TransportCfg;
223 /**
224 * @brief RM transport reconfiguration structure
225 */
226 typedef struct {
227 /** Application transport handle associated with the registered
228 * transport. This value can be anything that helps the application
229 * identify the application transport "pipe" for which a RM packet
230 * should be sent on. For example, a QMSS queue number, network
231 * port data structure, etc. */
232 Rm_AppTransportHandle appTransportHandle;
233 /** Pointers to application implemented transport APIs. The APIs for the
234 * provided functions must match the prototypes defined in the
235 * #Rm_TransportCallouts structure. Callouts need to be defined
236 * for each registered transport. However, based on the application's
237 * implementation of transport code the same function can be provided
238 * for each transport registration. In these cases, the transport
239 * must mux/demux the packets it receives from RM based on the
240 * #Rm_TransportHandle. */
241 Rm_TransportCallouts transportCallouts;
242 } Rm_TransportReCfg;
244 /**
245 * @b Description
246 * @n
247 * This function is used to register transports with RM for sending and
248 * receiving packets between RM instances over application transport
249 * data paths.
250 *
251 * RM Transport Restrictions:
252 * a) RM Servers cannot register with other Servers
253 * b) RM CDs cannot register with other CDs
254 * c) RM Clients cannot register with other Clients
255 * d) Clients cannot register with more than one CD or Server
256 * e) Clients cannot register with both a CD and Server (either or)
257 * f) CDs cannot register with more than one Server
258 *
259 * @param[in] transportCfg
260 * Pointer to the transport registration configuration structure.
261 *
262 * @param[out] result
263 * Pointer to a signed int used to return any errors encountered during
264 * the transport registration process.
265 *
266 * @retval
267 * Success - RM_TransportHandle and result = #RM_OK
268 * @retval
269 * Failure - NULL RM_TransportHandle and
270 * result = #RM_ERROR_INVALID_REMOTE_INST_TYPE
271 * @retval
272 * Failure - NULL RM_TransportHandle and
273 * result = #RM_ERROR_ALREADY_REGD_SERVER_OR_CD
274 * @retval
275 * Failure - NULL RM_TransportHandle and
276 * result = #RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD
277 * @retval
278 * Failure - NULL RM_TransportHandle and
279 * result = #RM_ERROR_TRANSPORT_SEND_NOT_REGD
280 */
281 Rm_TransportHandle Rm_transportRegister(const Rm_TransportCfg *transportCfg,
282 int32_t *result);
284 /**
285 * @b Description
286 * @n
287 * This function reconfigures an existing transport handle using the
288 * provided transport configurations
289 *
290 * @param[in] transportHandle
291 * Transport handle to unregister. The RM instance that the handle will
292 * be unregistered from is contained within the transportHandle.
293 *
294 * @param[in] transportReCfg
295 * Pointer to the transport registration configuration structure.
296 *
297 * @retval
298 * Success - #RM_OK
299 * @retval
300 * Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
301 */
302 int32_t Rm_transportReconfig(Rm_TransportHandle transportHandle,
303 const Rm_TransportReCfg *transportReCfg);
305 /**
306 * @b Description
307 * @n
308 * This function unregisters the provided transportHandle from the
309 * RM instance
310 *
311 * @param[in] transportHandle
312 * Transport handle to unregister. The RM instance that the handle will
313 * be unregistered from is contained within the transportHandle.
314 *
315 * @retval
316 * Success - #RM_OK
317 * @retval
318 * Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
319 */
320 int32_t Rm_transportUnregister(Rm_TransportHandle transportHandle);
322 /**
323 * @b Description
324 * @n
325 * This function returns the RM instance name from which the service
326 * encapsulated within the RM packet originated
327 *
328 * Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
329 * and Rm_pktType_NAMESERVER_REQUEST packet types
330 *
331 * @param[in] pkt
332 * RM packet to extract service source instance name from.
333 *
334 * @param[out] serviceInstName
335 * Pointer to a character array that will contain the RM instance name
336 * that originated the service request. The character array MUST be
337 * #RM_NAME_MAX_CHARS bytes in length
338 *
339 * @param[in] charBufLen
340 * Length of the provided pktInstName buffer
341 *
342 * @retval
343 * Success - #RM_OK
344 * @retval
345 * Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
346 * Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
347 */
348 int32_t Rm_receiveGetPktServiceSrcName(const Rm_Packet *pkt,
349 char *serviceInstName,
350 int32_t charBufLen);
352 /**
353 * @b Description
354 * @n
355 * This function returns the RM instance name from which the RM packet
356 * originated
357 *
358 * Restrictions: This API is only valid for Rm_pktType_RESOURCE_REQUEST
359 * and Rm_pktType_NAMESERVER_REQUEST packet types
360 *
361 * @param[in] pkt
362 * RM packet to extract packet source instance name from.
363 *
364 * @param[out] pktInstName
365 * Pointer to a character array that will contain the RM instance name
366 * that originated the RM request packet. The character array MUST be
367 * #RM_NAME_MAX_CHARS bytes in length
368 *
369 * @param[in] charBufLen
370 * Length of the provided pktInstName buffer
371 *
372 * @retval
373 * Success - #RM_OK
374 * @retval
375 * Failure - #RM_ERROR_PKT_AND_SERVICE_SRC_NOT_AVAIL
376 * Failure - #RM_ERROR_SRC_NAME_BUF_INVALID_SIZE
377 */
378 int32_t Rm_receiveGetPktSrcName(const Rm_Packet *pkt,
379 char *pktInstName,
380 int32_t charBufLen);
382 /**
383 * @b Description
384 * @n
385 * This function is called by the application when it has received a RM
386 * packet for processing. The application provides the transportHandle
387 * associated with the RM instance that should receive the packet and
388 * a pointer to the data buffer containing the Rm_Packet.
389 *
390 * RM assumes that the application will free the data buffer containing
391 * the Rm_Packet after RM has finished processing the packet.
392 *
393 * @param[in] transportHandle
394 * RM transportHandle containing the instance that should process the
395 * received packet.
396 *
397 * @param[in] pkt
398 * Pointer to the data buffer containing the Rm_Packet
399 *
400 * @retval
401 * Success - #RM_OK
402 * @retval
403 * Failure - < #RM_OK
404 */
405 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle,
406 const Rm_Packet *pkt);
408 /**
409 @}
410 */
412 #ifdef __cplusplus
413 }
414 #endif
416 #endif /* RM_TRANSPORT_H_ */