completed request/response infrastructure
[keystone-rtos/rm-lld.git] / rmtransport.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 /**
51 @addtogroup RMTRANSPORT_API
52 @{
53 */
55 /** RM Transport Result Return Codes */
56 /** RM Transport Success Code Base */
57 #define RM_TRANSPORT_OK_BASE (0)
58 /** RM transport action was successful. */
59 #define RM_TRANSPORT_SUCCESSFUL (RM_TRANSPORT_OK_BASE)
61 /** RM Transport Error Code Base */
62 #define RM_TRANSPORT_ERROR_BASE (-64)
63 /** RM transport handle has not been registered with the RM instance */
64 #define RM_TRANSPORT_ERROR_HANDLE_HAS_NOT_BEEN_REGISTERED (RM_TRANSPORT_ERROR_BASE-1)
65 /** No transports have been registered with the RM instance */
66 #define RM_TRANSPORT_ERROR_NO_TRANSPORTS_REGISTERED  (RM_TRANSPORT_ERROR_BASE-2)
67 /** RM packets are available but an error was encountered during reception */
68 #define RM_TRANSPORT_ERROR_PACKET_RECEPTION_ERROR (RM_TRANSPORT_ERROR_BASE-3)
70 /** 
71  * @brief Result of RM transport layer operations
72  */
73 typedef int32_t   Rm_TransportResult;
77 /** Maximum size of the RM transport packet */
78 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (128)  // Placeholder: This will 
79                                                  // change during development
81 /** 
82  * @brief RM transport handle
83  */
84 typedef void *Rm_TransportHandle;
86 /** 
87  * @brief RM transport registration configuration structure
88  */
89 typedef struct {
90     /** The transport's remote RM instance type */
91     Rm_InstType remoteInstType;
92     /** Pointer to the transport's remote RM instance name */
93     char *remoteInstName;
94 } Rm_TransportCfg;
96 /**
97  * @brief RM packet types that can be sent between RM instances
98  */
99 typedef enum {
100     /** Allocate/Free request packet */
101     Rm_pktType_RESOURCE_REQUEST = 0,
102     /** Allocate/Free response packet */ 
103     Rm_pktType_RESOURCE_RESPONSE = 1,
104     /** RM NameServer mapping request */
105     Rm_pktType_NAMESERVER_REQUEST = 2,
106     /** RM NameServer mapping response */
107     Rm_pktType_NAMESERVER_RESPONSE = 3,    
108     /** Policy request packet */
109     Rm_pktType_POLICY_REQUEST = 4,
110     /** Policy response packet */
111     Rm_pktType_POLICY_CHANGE = 5,
112     /** Resource pool modification request */
113     Rm_pktType_RESOURCE_POOL_MODIFICATION_REQUEST = 6,
114     /** Resource pool modification response */
115     Rm_pktType_RESOURCE_POOL_MODIFICATION_RESPONSE = 7
116 } Rm_pktType;
118 /** 
119  * @brief RM transport layer packet
120  */
121 typedef struct {
122     /** Packet length in bytes.  Written by application when allocated */
123     uint32_t pktLenBytes;
124     /** Type of RM packet contained in the byte data array */
125     Rm_pktType pktType;
126     /** Byte array containing RM packet data */
127     char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
128 } Rm_Packet;
130 typedef struct {
131     /**
132      *  @b Description
133      *  @n  
134      *      This function pointer describes the RM transport layer packet 
135      *      allocation function.  The application which integrates with RM must 
136      *      supply a function to RM at initialization time that matches this  
137      *      prototype.  The provided function implements the allocation of packet
138      *      buffers for use by the RM transport for sending messages between RM
139      *      instances in the SOC.
140      *
141      *  @param[in]  transportHandle
142      *      Which application transport to allocate a packet from.
143      *
144      *  @param[in]  pktSize
145      *      Size of requested packet allocation.
146      *
147      *  @retval
148      *      Success - Pointer to allocated packet buffer.
149      *  @retval
150      *      Failure - NULL
151      */
152     Rm_Packet *(*rmAllocPkt)(Rm_TransportHandle transportHandle, uint32_t pktSize);
153     
154     /**
155      *  @b Description
156      *  @n  
157      *      This function pointer describes the RM transport layer packet 
158      *      free function.  The application which integrates with RM must 
159      *      supply a function to RM at initialization time that matches this  
160      *      prototype.  The provided function implements the free of packet
161      *      buffers used by the RM transport for sending/receiving messages 
162      *      between RM instances in the SOC.
163      *
164      *  @param[in]  transportHandle
165      *      Which application transport to free the packet to.
166      *
167      *  @param[in]  pkt
168      *      Pointer to resource packet to be freed.
169      *
170      *  @retval
171      *      0 - Packet free okay.
172      *  @retval
173      *      Non-zero - Send failed.
174      */
175     int32_t (*rmFreePkt)(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
176     
177     /**
178      *  @b Description
179      *  @n  
180      *      This function pointer describes the RM transport layer send function.
181      *      The application which integrates with RM must supply a function to RM
182      *      at initialization time that matches this prototype.  The provided 
183      *      function implements the send side of the transport between RM 
184      *      instances on different cores in the SOC.
185      *
186      *  @param[in]  transportHandle
187      *      Which application transport to send the packet over.
188      *
189      *  @param[in]  pkt
190      *      Pointer to resource packet to be sent to the destination RM.
191      *
192      *  @retval
193      *      0 - Packet sent okay.
194      *  @retval
195      *      Non-zero - Send failed.
196      */
197     int32_t (*rmSend)(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
198     
199     /**
200      *  @b Description
201      *  @n  
202      *      This function pointer describes the RM transport layer receive 
203      *      function. The application which integrates with RM must supply a 
204      *      function to RM at initialization time that matches this prototype.
205      *      The provided function implements the receive side of the transport 
206      *      between RM instances on different cores in the SOC.
207      *
208      *  @param[in]  transportHandle
209      *      Which application transport to retrieve a packet from
210      *
211      *  @retval
212      *      Non-NULL - Pointer to received RM packet.
213      *  @retval
214      *      NULL - Packet receive failed.
215      */
216     void * (*rmReceive)(Rm_TransportHandle transportHandle);
217     
218     /**
219      *  @b Description
220      *  @n  
221      *      This function pointer describes the RM transport layer number of
222      *      packets received function. The application which integrates with RM 
223      *      must supply a function to RM at initialization time that matches this 
224      *      prototype.  The provided function implements a query of the number of
225      *      RM packets received on a specified transport.
226      *
227      *  @param[in]  transportHandle
228      *      Which application transport to check for received packets.
229      *
230      *  @retval
231      *      Success -   Number of packets received over transport interfaces for
232      *                  a RM instance.
233      *  @retval
234      *      Failure -   -1
235      */
236     int32_t (*rmNumPktsReceived)(Rm_TransportHandle transportHandle);
237 } Rm_TransportCallouts;
239 /**
240  *  @b Description
241  *  @n  
242  *      This is the RM transport layer function available for application
243  *      transport code callbacks.  This API can be called if the application
244  *      transport wants to report a received RM packet to the RM instance.
245  *      This API can be used if RM polling the application code for received
246  *      packets is not desired.
247  *
248  *  @param[in]  transportHandle
249  *      Transport handle.  Used to distinguish which RM instance the packet
250  *      was received from and how to internally route the packet if more than
251  *      one RM instance exists on the core.
252  *
253  *  @param[in]  pkt
254  *      Pointer to received resource packet.
255  *
256  *  @retval
257  *      Success - 0
258  *  @retval
259  *      Failure - Non-zero RM error
260  */
261 Rm_Result rmTransportCallback(Rm_TransHandle transportHandle, Rm_Packet *pkt);
264 /**
265  *  @b Description
266  *  @n  
267  *      This function is used to register transports with RM for sending and
268  *      receiving packets between RM instances over application transport
269  *      data paths.
270  *
271  *  @param[in]  rmHandle
272  *      RM instance to which the transport will be registered.  Used internally
273  *      by RM if there are more than one RM instances per core.
274  *
275  *  @param[in]  transportCfg
276  *      Transport registration configuration structure.  Provides information
277  *      regarding the application transports remote entity.  For example,
278  *      if the transCfg structure specifies the remote type is the RM Server
279  *      RM will know any Server requests must be pushed to the application
280  *      transport API with the transport handle returned to the application
281  *
282  *  @retval
283  *      Success - non-NULL RM transport handle.  No two transport handles
284  *                returned by RM should be the same.
285  *  @retval
286  *      Failure - NULL
287  */
288 Rm_TransportHandle Rm_transportRegister (Rm_Handle rmHandle, 
289                                          Rm_TransportCfg *transportCfg);
291 /**
292  *  @b Description
293  *  @n  
294  *      This function places the selected RM instance into the transport
295  *      verification state.  When all RM instances in the tree are placed
296  *      in the transport verification state a transport path verification
297  *      test will take place to verify the application transport paths between
298  *      all RM tree nodes are connected correctly.
299  *
300  *      Note: This API should not be called until all transport have been
301  *            registered with RM
302  *
303  *  @param[in]  rmHandle
304  *      Which RM instance to begin the transport verification process
305  *
306  *  @param[in]  timeout
307  *      Number of ______ (cycles, usec, msec???) to wait before signaling a
308  *      transport path verification timeout
309  *
310  *  @param[in]  failData
311  *      Pointer to an empty Rm_TransFailData structure.  If the transport
312  *      verification process fails this structure will return with transport
313  *      failure data
314  *
315  *  @retval
316  *      Success - 0 - Transport Verification succeeded
317  *  @retval
318  *      Failure - non-0 - Transport Verification failed
319  */
320 Rm_TransVerifyResult Rm_transportVerify (Rm_Handle, uint32_t timeout, 
321                                          Rm_TransFailData *failData);
325 /** 
326 @} 
327 */
329 #ifdef __cplusplus
331 #endif
333 #endif /* RMTRANSPORT_H_ */