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-2013, 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 /** Maximum size of the RM transport packet */
62 #define RM_TRANSPORT_PACKET_MAX_SIZE_BYTES (256)
64 /**
65 * @brief RM transport handle
66 */
67 typedef void *Rm_TransportHandle;
69 /**
70 * @brief RM packet types that can be sent between RM instances
71 */
72 typedef enum {
73 /** Allocate/Free request packet */
74 Rm_pktType_RESOURCE_REQUEST = 0,
75 /** Allocate/Free response packet */
76 Rm_pktType_RESOURCE_RESPONSE,
77 /** RM NameServer mapping request */
78 Rm_pktType_NAMESERVER_REQUEST,
79 /** RM NameServer mapping response */
80 Rm_pktType_NAMESERVER_RESPONSE
81 } Rm_pktType;
83 /**
84 * @brief RM transport layer packet
85 */
86 typedef struct {
87 /** Packet length in bytes. Written by application when allocated */
88 uint32_t pktLenBytes;
89 /** Type of RM packet contained in the byte data array */
90 Rm_pktType pktType;
91 /** Byte array containing RM packet data */
92 char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
93 } Rm_Packet;
95 typedef struct {
96 /**
97 * @b Description
98 * @n
99 * This function pointer describes the RM transport layer packet
100 * allocation function. The application which integrates with RM must
101 * supply a function to RM at initialization time that matches this
102 * prototype. The provided function implements the allocation of packet
103 * buffers for use by the RM transport for sending messages between RM
104 * instances in the SOC.
105 *
106 * @param[in] transportHandle
107 * Which application transport to allocate a packet from.
108 *
109 * @param[in] pktSize
110 * Size of requested packet allocation.
111 *
112 * @retval
113 * Success - Pointer to allocated packet buffer.
114 * @retval
115 * Failure - NULL
116 */
117 Rm_Packet *(*rmAllocPkt)(Rm_TransportHandle transportHandle, uint32_t pktSize);
119 /**
120 * @b Description
121 * @n
122 * This function pointer describes the RM transport layer packet
123 * free function. The application which integrates with RM must
124 * supply a function to RM at initialization time that matches this
125 * prototype. The provided function implements the free of packet
126 * buffers used by the RM transport for sending/receiving messages
127 * between RM instances in the SOC.
128 *
129 * @param[in] transportHandle
130 * Which application transport to free the packet to.
131 *
132 * @param[in] pkt
133 * Pointer to resource packet to be freed.
134 *
135 * @retval
136 * 0 - Packet free okay.
137 * @retval
138 * Non-zero - Send failed.
139 */
140 int32_t (*rmFreePkt)(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
142 /**
143 * @b Description
144 * @n
145 * This function pointer describes the RM transport layer send function.
146 * The application which integrates with RM must supply a function to RM
147 * at initialization time that matches this prototype. The provided
148 * function implements the send side of the transport between RM
149 * instances on different cores in the SOC.
150 *
151 * @param[in] transportHandle
152 * Which application transport to send the packet over.
153 *
154 * @param[in] pkt
155 * Pointer to resource packet to be sent to the destination RM.
156 *
157 * @retval
158 * 0 - Packet sent okay.
159 * @retval
160 * Non-zero - Send failed.
161 */
162 int32_t (*rmSend)(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
164 /**
165 * @b Description
166 * @n
167 * This function pointer describes the RM transport layer receive
168 * function. The application which integrates with RM must supply a
169 * function to RM at initialization time that matches this prototype.
170 * The provided function implements the receive side of the transport
171 * between RM instances on different cores in the SOC.
172 *
173 * @param[in] transportHandle
174 * Which application transport to retrieve a packet from
175 *
176 * @retval
177 * Non-NULL - Pointer to received RM packet.
178 * @retval
179 * NULL - Packet receive failed.
180 */
181 void * (*rmReceive)(Rm_TransportHandle transportHandle);
183 /**
184 * @b Description
185 * @n
186 * This function pointer describes the RM transport layer number of
187 * packets received function. The application which integrates with RM
188 * must supply a function to RM at initialization time that matches this
189 * prototype. The provided function implements a query of the number of
190 * RM packets received on a specified transport.
191 *
192 * @param[in] transportHandle
193 * Which application transport to check for received packets.
194 *
195 * @retval
196 * Success - Number of packets received over transport interfaces for
197 * a RM instance.
198 * @retval
199 * Failure - -1
200 */
201 int32_t (*rmNumPktsReceived)(Rm_TransportHandle transportHandle);
202 } Rm_TransportCallouts;
204 /**
205 * @brief RM transport registration configuration structure
206 */
207 typedef struct {
208 /** The RM Handle for which the transport is being registered */
209 Rm_Handle rmHandle;
210 /** The transport's remote RM instance type */
211 Rm_InstType remoteInstType;
212 /** Pointer to the transport's remote RM instance name */
213 char *remoteInstName;
214 /** Used to specify whether the transport callouts are valid.
215 * TRUE - Transport callouts are valid and will be stored by the RM
216 * instance.
217 * FALSE - Transport callouts are not valid and will not be stored by
218 * the RM instance. */
219 bool transportCalloutsValid;
220 /** Pointers to application implemented transport APIs. The APIs for the
221 * provided functions must match the prototypes defined in the
222 * Rm_TransportCallouts structure. Callouts will typically only be defined
223 * for the first transport registered with an RM instance. The
224 * transportCalloutsValid field can be used to disable RM instance's from
225 * reading in new callout values are they're specified once. */
226 Rm_TransportCallouts transportCallouts;
227 } Rm_TransportCfg;
229 /**
230 * @b Description
231 * @n
232 * This function is used to register transports with RM for sending and
233 * receiving packets between RM instances over application transport
234 * data paths.
235 *
236 * @param[in] rmHandle
237 * RM instance to which the transport will be registered. Used internally
238 * by RM if there are more than one RM instances per core.
239 *
240 * @param[in] transportCfg
241 * Transport registration configuration structure. Provides information
242 * regarding the application transports remote entity. For example,
243 * if the transCfg structure specifies the remote type is the RM Server
244 * RM will know any Server requests must be pushed to the application
245 * transport API with the transport handle returned to the application
246 *
247 * @retval
248 * Success - non-NULL RM transport handle. No two transport handles
249 * returned by RM should be the same.
250 * @retval
251 * Failure - NULL
252 */
253 Rm_TransportHandle Rm_transportRegister (Rm_TransportCfg *transportCfg, int32_t *result);
254 int32_t Rm_transportUnregister (Rm_Handle rmHandle, Rm_TransportHandle transportHandle);
255 int32_t Rm_receivePktIsr(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
256 int32_t Rm_receivePktPolling(Rm_TransportHandle transportHandle);
259 /**
260 @}
261 */
263 #ifdef __cplusplus
264 }
265 #endif
267 #endif /* RM_TRANSPORT_H_ */