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-2013, 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 /** Pointer to the remote RM instance name at other end of the
211 * application transport "pipe". */
212 const char *remoteInstName;
213 /** Pointers to application implemented transport APIs. The APIs for the
214 * provided functions must match the prototypes defined in the
215 * #Rm_TransportCallouts structure. Callouts need to be defined
216 * for each registered transport. However, based on the application's
217 * implementation of transport code the same function can be provided
218 * for each transport registration. In these cases, the transport
219 * must mux/demux the packets it receives from RM based on the
220 * #Rm_TransportHandle. */
221 Rm_TransportCallouts transportCallouts;
222 } Rm_TransportCfg;
224 /**
225 * @b Description
226 * @n
227 * This function is used to register transports with RM for sending and
228 * receiving packets between RM instances over application transport
229 * data paths.
230 *
231 * RM Transport Restrictions:
232 * a) RM Servers cannot register with other Servers
233 * b) RM CDs cannot register with other CDs
234 * c) RM Clients cannot register with other Clients
235 * d) Clients cannot register with more than one CD or Server
236 * e) Clients cannot register with both a CD and Server (either or)
237 * f) CDs cannot register with more than one Server
238 *
239 * @param[in] transportCfg
240 * Pointer to the transport registration configuration structure.
241 *
242 * @param[out] result
243 * Pointer to a signed int used to return any errors encountered during
244 * the transport registration process.
245 *
246 * @retval
247 * Success - RM_TransportHandle and result = #RM_OK
248 * @retval
249 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_INVALID_REMOTE_INST_TYPE
250 * @retval
251 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_ALREADY_REGD_SERVER_OR_CD
252 * @retval
253 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_TRANSPORT_ALLOC_PKT_NOT_REGD
254 * @retval
255 * Failure - NULL RM_TransportHandle and result = #RM_ERROR_TRANSPORT_SEND_NOT_REGD
256 */
257 Rm_TransportHandle Rm_transportRegister(const Rm_TransportCfg *transportCfg, int32_t *result);
259 /**
260 * @b Description
261 * @n
262 * This function unregisters the provided transportHandle from the
263 * RM instance
264 *
265 * @param[in] transportHandle
266 * Transport handle to unregister. The RM instance that the handle will
267 * be unregistered from is contained within the transportHandle.
268 *
269 * @retval
270 * Success - #RM_OK
271 * @retval
272 * Failure - #RM_ERROR_TRANSPORT_HANDLE_DOES_NOT_EXIST
273 */
274 int32_t Rm_transportUnregister (Rm_TransportHandle transportHandle);
276 /**
277 * @b Description
278 * @n
279 * This function is called by the application when it has received a RM
280 * packet for processing. The application provides the transportHandle
281 * associated with the RM instance that should receive the packet and
282 * a pointer to the data buffer containing the Rm_Packet.
283 *
284 * RM assumes that the application will free the data buffer containing
285 * the Rm_Packet after RM has finished processing the packet.
286 *
287 * @param[in] transportHandle
288 * RM transportHandle containing the instance that should process the
289 * received packet.
290 *
291 * @param[in] pkt
292 * Pointer to the data buffer containing the Rm_Packet
293 *
294 * @retval
295 * Success - #RM_OK
296 * @retval
297 * Failure - < #RM_OK
298 */
299 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle, const Rm_Packet *pkt);
301 /**
302 @}
303 */
305 #ifdef __cplusplus
306 }
307 #endif
309 #endif /* RM_TRANSPORT_H_ */