Removed receipts started basic testing on infrastructure code
[keystone-rtos/rm-lld.git] / rm_transport.h
1 /**
2  *   @file  rmtransport.h
3  *
4  *   @brief   
5  *      This is the RM include file for the generic transport interface used by RM to exchange
6  *      RM control signals and data between RM instances
7  *
8  *  \par
9  *  ============================================================================
10  *  @n   (C) Copyright 2012, 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 RMTRANSPORT_H_
44 #define RMTRANSPORT_H_
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
50 /* RM includes */
51 #include <ti/drv/rm/rm.h>
53 /**
54 @addtogroup RMTRANSPORT_API
55 @{
56 */
58 /** RM Transport Result Return Codes */
59 /** RM Transport Success Code Base */
60 #define RM_TRANSPORT_OK_BASE (0)
61 /** RM transport action was successful. */
62 #define RM_TRANSPORT_SUCCESSFUL (RM_TRANSPORT_OK_BASE)
64 /** RM Transport Error Code Base */
65 #define RM_TRANSPORT_ERROR_BASE (-64)
66 /** RM transport handle has not been registered with the RM instance */
67 #define RM_TRANSPORT_ERROR_HANDLE_HAS_NOT_BEEN_REGISTERED (RM_TRANSPORT_ERROR_BASE-1)
68 /** No transports have been registered with the RM instance */
69 #define RM_TRANSPORT_ERROR_NO_TRANSPORTS_REGISTERED  (RM_TRANSPORT_ERROR_BASE-2)
70 /** RM packets are available but an error was encountered during reception */
71 #define RM_TRANSPORT_ERROR_PACKET_RECEPTION_ERROR (RM_TRANSPORT_ERROR_BASE-3)
72 /** RM received a packet with an unknown RM packet type */
73 #define RM_TRANSPORT_ERROR_INVALID_PACKET_TYPE (RM_TRANSPORT_ERROR_BASE-4)
74 /** RM resource request transaction could not be found matching the response received */
75 #define RM_TRANSPORT_ERROR_MATCHING_RESOURCE_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-5)
76 /** RM NameServer request transaction could not be found matching the response received */
77 #define RM_TRANSPORT_ERROR_MATCHING_NAME_SERVER_REQUEST_NOT_FOUND (RM_TRANSPORT_ERROR_BASE-6)
79 /** 
80  * @brief Result of RM transport layer operations
81  */
82 typedef int32_t   Rm_TransportResult;
84 /** Maximum size of the RM transport packet */
85 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (128)  // Placeholder: This will 
86                                                  // change during development
88 /** 
89  * @brief RM transport handle
90  */
91 typedef void *Rm_TransportHandle;
93 /**
94  * @brief RM packet types that can be sent between RM instances
95  */
96 typedef enum {
97     /** Allocate/Free request packet */
98     Rm_pktType_RESOURCE_REQUEST = 0,
99     /** Allocate/Free response packet */ 
100     Rm_pktType_RESOURCE_RESPONSE = 1,
101     /** RM NameServer mapping request */
102     Rm_pktType_NAMESERVER_REQUEST = 2,
103     /** RM NameServer mapping response */
104     Rm_pktType_NAMESERVER_RESPONSE = 3,    
105     /** Policy request packet */
106     Rm_pktType_POLICY_REQUEST = 4,
107     /** Policy response packet */
108     Rm_pktType_POLICY_CHANGE = 5,
109     /** Resource pool modification request */
110     Rm_pktType_RESOURCE_POOL_MODIFICATION_REQUEST = 6,
111     /** Resource pool modification response */
112     Rm_pktType_RESOURCE_POOL_MODIFICATION_RESPONSE = 7
113 } Rm_pktType;
115 /** 
116  * @brief RM transport layer packet
117  */
118 typedef struct {
119     /** Packet length in bytes.  Written by application when allocated */
120     uint32_t pktLenBytes;
121     /** Type of RM packet contained in the byte data array */
122     Rm_pktType pktType;
123     /** Byte array containing RM packet data */
124     char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
125 } Rm_Packet;
127 typedef struct {
128     /**
129      *  @b Description
130      *  @n  
131      *      This function pointer describes the RM transport layer packet 
132      *      allocation function.  The application which integrates with RM must 
133      *      supply a function to RM at initialization time that matches this  
134      *      prototype.  The provided function implements the allocation of packet
135      *      buffers for use by the RM transport for sending messages between RM
136      *      instances in the SOC.
137      *
138      *  @param[in]  transportHandle
139      *      Which application transport to allocate a packet from.
140      *
141      *  @param[in]  pktSize
142      *      Size of requested packet allocation.
143      *
144      *  @retval
145      *      Success - Pointer to allocated packet buffer.
146      *  @retval
147      *      Failure - NULL
148      */
149     Rm_Packet *(*rmAllocPkt)(Rm_TransportHandle transportHandle, uint32_t pktSize);
150     
151     /**
152      *  @b Description
153      *  @n  
154      *      This function pointer describes the RM transport layer packet 
155      *      free function.  The application which integrates with RM must 
156      *      supply a function to RM at initialization time that matches this  
157      *      prototype.  The provided function implements the free of packet
158      *      buffers used by the RM transport for sending/receiving messages 
159      *      between RM instances in the SOC.
160      *
161      *  @param[in]  transportHandle
162      *      Which application transport to free the packet to.
163      *
164      *  @param[in]  pkt
165      *      Pointer to resource packet to be freed.
166      *
167      *  @retval
168      *      0 - Packet free okay.
169      *  @retval
170      *      Non-zero - Send failed.
171      */
172     int32_t (*rmFreePkt)(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
173     
174     /**
175      *  @b Description
176      *  @n  
177      *      This function pointer describes the RM transport layer send function.
178      *      The application which integrates with RM must supply a function to RM
179      *      at initialization time that matches this prototype.  The provided 
180      *      function implements the send side of the transport between RM 
181      *      instances on different cores in the SOC.
182      *
183      *  @param[in]  transportHandle
184      *      Which application transport to send the packet over.
185      *
186      *  @param[in]  pkt
187      *      Pointer to resource packet to be sent to the destination RM.
188      *
189      *  @retval
190      *      0 - Packet sent okay.
191      *  @retval
192      *      Non-zero - Send failed.
193      */
194     int32_t (*rmSend)(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
195     
196     /**
197      *  @b Description
198      *  @n  
199      *      This function pointer describes the RM transport layer receive 
200      *      function. The application which integrates with RM must supply a 
201      *      function to RM at initialization time that matches this prototype.
202      *      The provided function implements the receive side of the transport 
203      *      between RM instances on different cores in the SOC.
204      *
205      *  @param[in]  transportHandle
206      *      Which application transport to retrieve a packet from
207      *
208      *  @retval
209      *      Non-NULL - Pointer to received RM packet.
210      *  @retval
211      *      NULL - Packet receive failed.
212      */
213     void * (*rmReceive)(Rm_TransportHandle transportHandle);
214     
215     /**
216      *  @b Description
217      *  @n  
218      *      This function pointer describes the RM transport layer number of
219      *      packets received function. The application which integrates with RM 
220      *      must supply a function to RM at initialization time that matches this 
221      *      prototype.  The provided function implements a query of the number of
222      *      RM packets received on a specified transport.
223      *
224      *  @param[in]  transportHandle
225      *      Which application transport to check for received packets.
226      *
227      *  @retval
228      *      Success -   Number of packets received over transport interfaces for
229      *                  a RM instance.
230      *  @retval
231      *      Failure -   -1
232      */
233     int32_t (*rmNumPktsReceived)(Rm_TransportHandle transportHandle);
234 } Rm_TransportCallouts;
236 /** 
237  * @brief RM transport registration configuration structure
238  */
239 typedef struct {
240     /** The transport's remote RM instance type */
241     Rm_InstType remoteInstType;
242     /** Pointer to the transport's remote RM instance name */
243     char *remoteInstName;
244     /** Used to specify whether the transport callouts are valid.
245      *  TRUE - Transport callouts are valid and will be stored by the RM
246      *         instance.
247      *  FALSE - Transport callouts are not valid and will not be stored by
248      *          the RM instance. */
249     bool transportCalloutsValid;
250     /** Pointers to application implemented transport APIs.  The APIs for the
251      *  provided functions must match the prototypes defined in the
252      *  Rm_TransportCallouts structure.  Callouts will typically only be defined
253      *  for the first transport registered with an RM instance.  The 
254      *  transportCalloutsValid field can be used to disable RM instance's from
255      *  reading in new callout values are they're specified once. */
256     Rm_TransportCallouts transportCallouts;   
257 } Rm_TransportCfg;
259 /**
260  *  @b Description
261  *  @n  
262  *      This function is used to register transports with RM for sending and
263  *      receiving packets between RM instances over application transport
264  *      data paths.
265  *
266  *  @param[in]  rmHandle
267  *      RM instance to which the transport will be registered.  Used internally
268  *      by RM if there are more than one RM instances per core.
269  *
270  *  @param[in]  transportCfg
271  *      Transport registration configuration structure.  Provides information
272  *      regarding the application transports remote entity.  For example,
273  *      if the transCfg structure specifies the remote type is the RM Server
274  *      RM will know any Server requests must be pushed to the application
275  *      transport API with the transport handle returned to the application
276  *
277  *  @retval
278  *      Success - non-NULL RM transport handle.  No two transport handles
279  *                returned by RM should be the same.
280  *  @retval
281  *      Failure - NULL
282  */
283 Rm_TransportHandle Rm_transportRegister (Rm_Handle rmHandle, 
284                                          Rm_TransportCfg *transportCfg);
286 Rm_TransportResult Rm_transportUnregister (Rm_Handle rmHandle, 
287                                            Rm_TransportHandle transportHandle);
289 int32_t Rm_receivePktIsr(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
291 int32_t Rm_receivePktPolling(Rm_TransportHandle transportHandle);
294 /** 
295 @} 
296 */
298 #ifdef __cplusplus
300 #endif
302 #endif /* RMTRANSPORT_H_ */