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 Application transport handle
71 */
72 typedef void *Rm_AppTransportHandle;
74 typedef void *Rm_PacketHandle;
76 /**
77 * @brief RM packet types that can be sent between RM instances
78 */
79 typedef enum {
80 /** Allocate/Free request packet */
81 Rm_pktType_RESOURCE_REQUEST = 0,
82 /** Allocate/Free response packet */
83 Rm_pktType_RESOURCE_RESPONSE,
84 /** RM NameServer mapping request */
85 Rm_pktType_NAMESERVER_REQUEST,
86 /** RM NameServer mapping response */
87 Rm_pktType_NAMESERVER_RESPONSE
88 } Rm_pktType;
90 /**
91 * @brief RM transport layer packet
92 */
93 typedef struct {
94 /** Packet length in bytes. Written by application when allocated */
95 uint32_t pktLenBytes;
96 /** Type of RM packet contained in the byte data array */
97 Rm_pktType pktType;
98 /** Byte array containing RM packet data */
99 char data[RM_TRANSPORT_PACKET_MAX_SIZE_BYTES];
100 } Rm_Packet;
102 typedef struct {
103 /**
104 * @b Description
105 * @n
106 * This function pointer describes the RM transport layer packet
107 * allocation function. The application which integrates with RM must
108 * supply a function to RM at initialization time that matches this
109 * prototype. The provided function implements the allocation of packet
110 * buffers for use by the RM transport for sending messages between RM
111 * instances in the SOC.
112 *
113 * @param[in] transportHandle
114 * Which application transport to allocate a packet from.
115 *
116 * @param[in] pktSize
117 * Size of requested packet allocation.
118 *
119 * @retval
120 * Success - Pointer to allocated packet buffer.
121 * @retval
122 * Failure - NULL
123 */
125 /* Rm_Packet * and pktHandle cannot be NULL. They will either be different or the same
126 * value based on the transport */
127 Rm_Packet *(*rmAllocPkt)(Rm_AppTransportHandle appTransport, uint32_t pktSize,
128 Rm_PacketHandle *pktHandle);
129 /**
130 * @b Description
131 * @n
132 * This function pointer describes the RM transport layer send function.
133 * The application which integrates with RM must supply a function to RM
134 * at initialization time that matches this prototype. The provided
135 * function implements the send side of the transport between RM
136 * instances on different cores in the SOC.
137 *
138 * @param[in] transportHandle
139 * Which application transport to send the packet over.
140 *
141 * @param[in] pkt
142 * Pointer to resource packet to be sent to the destination RM.
143 *
144 * @retval
145 * 0 - Packet sent okay.
146 * @retval
147 * Non-zero - Send failed.
148 */
149 int32_t (*rmSendPkt)(Rm_AppTransportHandle appTransport, Rm_PacketHandle pktHandle);
150 } Rm_TransportCallouts;
152 /**
153 * @brief RM transport registration configuration structure
154 */
155 typedef struct {
156 /** The RM Handle for which the transport is being registered */
157 Rm_Handle rmHandle;
158 /** The Application transport handle associated with the registered
159 * transport */
160 Rm_AppTransportHandle appTransportHandle;
161 /** The transport's remote RM instance type */
162 Rm_InstType remoteInstType;
163 /** Pointer to the transport's remote RM instance name */
164 char *remoteInstName;
165 /** Used to specify whether the transport callouts are valid.
166 * TRUE - Transport callouts are valid and will be stored by the RM
167 * instance.
168 * FALSE - Transport callouts are not valid and will not be stored by
169 * the RM instance. */
170 bool transportCalloutsValid;
171 /** Pointers to application implemented transport APIs. The APIs for the
172 * provided functions must match the prototypes defined in the
173 * Rm_TransportCallouts structure. Callouts will typically only be defined
174 * for the first transport registered with an RM instance. The
175 * transportCalloutsValid field can be used to disable RM instance's from
176 * reading in new callout values are they're specified once. */
177 Rm_TransportCallouts transportCallouts;
178 } Rm_TransportCfg;
180 /**
181 * @b Description
182 * @n
183 * This function is used to register transports with RM for sending and
184 * receiving packets between RM instances over application transport
185 * data paths.
186 *
187 * @param[in] rmHandle
188 * RM instance to which the transport will be registered. Used internally
189 * by RM if there are more than one RM instances per core.
190 *
191 * @param[in] transportCfg
192 * Transport registration configuration structure. Provides information
193 * regarding the application transports remote entity. For example,
194 * if the transCfg structure specifies the remote type is the RM Server
195 * RM will know any Server requests must be pushed to the application
196 * transport API with the transport handle returned to the application
197 *
198 * @retval
199 * Success - non-NULL RM transport handle. No two transport handles
200 * returned by RM should be the same.
201 * @retval
202 * Failure - NULL
203 */
204 Rm_TransportHandle Rm_transportRegister(Rm_TransportCfg *transportCfg, int32_t *result);
205 int32_t Rm_transportUnregister (Rm_TransportHandle transportHandle);
206 /* Application will always free the packet */
207 int32_t Rm_receivePacket(Rm_TransportHandle transportHandle, Rm_Packet *pkt);
209 /**
210 @}
211 */
213 #ifdef __cplusplus
214 }
215 #endif
217 #endif /* RM_TRANSPORT_H_ */