Checking in RMv2 progress
[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 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 RM_TRANSPORT_H_
44 #define RM_TRANSPORT_H_
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
50 /**
51 @addtogroup RM_TRANSPORT_API
52 @{
53 */
55 /** Maximum size of the RM transport packet */
56 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (128)  // Placeholder: This will 
57                                                  // change during development
59 /** 
60  * @brief RM transport handle
61  */
62 typedef void *Rm_TransportHandle;
64 /** 
65  * @brief Result of RM transport layer operations
66  */
67 typedef int32_t   Rm_TransportResult;
69 /** 
70  * @brief RM transport layer packet packet descriptor structure
71  */
72 typedef struct {
73     /** Length of packet.  Written by application when allocated */
74     uint32_t rmPktLen;
75     /** Pointer to RM resource packet */
76     char rmData[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
77 } Rm_Packet;
80 typedef struct {
81     /**
82      *  @b Description
83      *  @n  
84      *      This function pointer describes the RM transport layer packet 
85      *      allocation function.  The application which integrates with RM must 
86      *      supply a function to RM at initialization time that matches this  
87      *      prototype.  The provided function implements the allocation of packet
88      *      buffers for use by the RM transport for sending messages between RM
89      *      instances in the SOC.
90      *
91      *  @param[in]  transHandle
92      *      Which application transport to allocate a packet from.
93      *
94      *  @param[in]  pktSize
95      *      Size of requested packet allocation.
96      *
97      *  @retval
98      *      Success - Pointer to allocated packet buffer.
99      *  @retval
100      *      Failure - NULL
101      */
102     Rm_Packet *(*rmAllocPkt)(Rm_TransHandle transHandle, uint32_t pktSize);
103     
104     /**
105      *  @b Description
106      *  @n  
107      *      This function pointer describes the RM transport layer packet 
108      *      free function.  The application which integrates with RM must 
109      *      supply a function to RM at initialization time that matches this  
110      *      prototype.  The provided function implements the free of packet
111      *      buffers used by the RM transport for sending/receiving messages 
112      *      between RM instances in the SOC.
113      *
114      *  @param[in]  transHandle
115      *      Which application transport to free the packet to.
116      *
117      *  @param[in]  pkt
118      *      Pointer to resource packet to be freed.
119      *
120      *  @retval
121      *      0 - Packet free okay.
122      *  @retval
123      *      Non-zero - Send failed.
124      */
125     Rm_TransportResult  (*rmFreePkt)(Rm_TransHandle transHandle, Rm_Packet *pkt);
126     
127     /**
128      *  @b Description
129      *  @n  
130      *      This function pointer describes the RM transport layer send function.
131      *      The application which integrates with RM must supply a function to RM
132      *      at initialization time that matches this prototype.  The provided 
133      *      function implements the send side of the transport between RM 
134      *      instances on different cores in the SOC.
135      *
136      *  @param[in]  transHandle
137      *      Which application transport to send the packet over.
138      *
139      *  @param[in]  pkt
140      *      Pointer to resource packet to be sent to the destination RM.
141      *
142      *  @retval
143      *      0 - Packet sent okay.
144      *  @retval
145      *      Non-zero - Send failed.
146      */
147     Rm_TransportResult  (*rmSend)(Rm_TransHandle transHandle, Rm_Packet *pkt);
148     
149     /**
150      *  @b Description
151      *  @n  
152      *      This function pointer describes the RM transport layer receive 
153      *      function. The application which integrates with RM must supply a 
154      *      function to RM at initialization time that matches this prototype.
155      *      The provided function implements the receive side of the transport 
156      *      between RM instances on different cores in the SOC.
157      *
158      *  @param[in]  transHandle
159      *      Which application transport to retrieve a packet from
160      *
161      *  @param[in]  pkt
162      *      Pointer to received resource packet.
163      *
164      *  @retval
165      *      0 - Packet reception okay.
166      *  @retval
167      *      Non-zero - Packet receive failed.
168      */
169     Rm_TransportResult  (*rmReceive)(Rm_TransHandle transHandle, Rm_Packet *pkt);
170     
171     /**
172      *  @b Description
173      *  @n  
174      *      This function pointer describes the RM transport layer number of
175      *      packets received function. The application which integrates with RM 
176      *      must supply a function to RM at initialization time that matches this 
177      *      prototype.  The provided function implements a query of the number of
178      *      RM packets received on a specified transport.
179      *
180      *  @param[in]  transHandle
181      *      Which application transport to check for received packets.
182      *
183      *  @retval
184      *      Success -   Number of packets received over transport interfaces for
185      *                  a RM instance.
186      *  @retval
187      *      Failure -   -1
188      */
189     int32_t (*rmNumPktsReceived)(Rm_TransHandle transHandle);
190 } Rm_TransportCallouts;
192 /**
193  *  @b Description
194  *  @n  
195  *      This is the RM transport layer function available for application
196  *      transport code callbacks.  This API can be called if the application
197  *      transport wants to report a received RM packet to the RM instance.
198  *      This API can be used if RM polling the application code for received
199  *      packets is not desired.
200  *
201  *  @param[in]  transHandle
202  *      Transport handle.  Used to distinguish which RM instance the packet
203  *      was received from and how to internally route the packet if more than
204  *      one RM instance exists on the core.
205  *
206  *  @param[in]  pkt
207  *      Pointer to received resource packet.
208  *
209  *  @retval
210  *      Success - 0
211  *  @retval
212  *      Failure - Non-zero RM error
213  */
214 Rm_Result rmTransportCallback(Rm_TransHandle transHandle, Rm_Packet *pkt);
217 /** 
218 @} 
219 */
221 #ifdef __cplusplus
223 #endif
225 #endif /* RM_TRANSPORT_H_ */