Increased number of infra Qs used by Kernel on K2l for UDMA
[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-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
403 #endif
405 #endif /* RM_TRANSPORT_H_ */