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_TransportHandle transHandle, uint32_t pktSize);
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_TransportHandle transHandle, Rm_Packet *pkt);
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_TransportHandle transHandle, Rm_Packet *pkt);
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_TransportHandle transHandle, Rm_Packet *pkt);
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_TransportHandle 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
222 }
223 #endif
225 #endif /* RM_TRANSPORT_H_ */