NOTICE OF RELOCATION
[keystone-rtos/rm-lld.git] / rm_transport.h
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
414 #endif
416 #endif /* RM_TRANSPORT_H_ */