1 /*
2 * Copyright (c) 2014-2015 Texas Instruments Incorporated - http://www.ti.com
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
33 /**
34 * @file linux/include/ti/ipc/interfaces/INetworkTransport.h
35 *
36 * @brief Secondary interface for MessageQ transports
37 *
38 * This interface is suitable for implementing a secondary message
39 * transport for the MessageQ module.
40 *
41 * The INetworkTransport interface includes the following instance methods:
42 *
43 * bind - create transport resources on behalf of the given queue
44 * unbind - delete transport resources used by the given queue
45 * put - send the message
46 */
48 /*
49 * ======== INetworkTransport.h ========
50 */
52 #ifndef INETWORKTRANSPORT_H
53 #define INETWORKTRANSPORT_H
55 #include <ti/ipc/interfaces/ITransport.h>
57 #if defined (__cplusplus)
58 extern "C" {
59 #endif
61 /*!
62 * @brief Interface type ID
63 *
64 * This ID uniquely identifies this interface type.
65 */
66 #define INetworkTransport_TypeId 0x03
68 /*!
69 * @brief INetworkTransport_Handle type
70 *
71 * An opaque instance handle.
72 */
73 typedef struct INetworkTransport_Object *INetworkTransport_Handle;
75 /*!
76 * @brief The interface function table
77 *
78 * All transports must provide a concrete implementation for each of
79 * these virtual functions. The transport user (e.g. MessageQ) will
80 * invoke the implementation functions through the interface function
81 * stubs defined below.
82 */
83 typedef struct INetworkTransport_Fxns {
85 Int (*bind)(void *handle, UInt32 queueId);
86 /*!< function pointer for bind method
87 *
88 * This method allows the transport to bind/create resources
89 * needed for message delivery. The method is invoked when a
90 * new message queue is created and for all existing queues
91 * when attaching to a processor.
92 *
93 * @param[in] inst Transport instance handle
94 * @param[in] queueId Message queue identifier
95 *
96 * @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
97 */
99 Int (*unbind)(void *handle, UInt32 queueId);
100 /*!< function pointer for unbind method
101 *
102 * This method allows the transport to unbind/delete resources
103 * which where allocated on behalf of the given message queue.
104 * This method is invoked when deleting a message queue and for
105 * all existing queues when detaching from a processor.
106 *
107 * @param[in] inst Transport instance handle
108 * @param[in] queueId Message queue identifier
109 *
110 * @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
111 */
113 Bool (*put)(void *handle, Ptr msg);
114 /*!< function pointer for put method
115 *
116 * Invoked to deliver the given message. Once MessageQ calls into this
117 * method, the message ownership has been transferred to the transport.
118 * Regardless of the outcome of message delivery, the message ownership
119 * is *never* returned back to MessageQ. If delivery fails, the message
120 * is lost but all resources must be reclaimed.
121 *
122 * @param[in] inst Transport instance handle
123 * @param[in] msg Pointer to the message (MessageQ_Msg)
124 *
125 * @return Status result:
126 * - TRUE: message was delivered
127 * - FALSE: delivery failure, message lost
128 */
129 } INetworkTransport_Fxns;
131 /*!
132 * @brief The instance object definition for INetworkTransport
133 *
134 * All instances of this interface type must define this object
135 * within the implementation object. It must be the first element
136 * of the instance object and it must be named 'base'. Otherwise,
137 * the converter functions below will fail.
138 *
139 * typedef TransportAcme_Object {
140 * INetworkTransport_Object base;
141 * ...
142 * } TransportAcme_Object;
143 */
144 typedef struct INetworkTransport_Object {
146 ITransport_Object base;
147 /*!< Base class inheritance
148 *
149 * The instance constructor must initialize this base object.
150 */
152 INetworkTransport_Fxns *fxns;
153 /*!< Address of interface function table
154 *
155 * The instance constructor must initialize this field to contain
156 * the address of the instance function table.
157 *
158 * INetworkTransport_Fxns TransportAcme_fxns = {
159 * .bind = TransportAcme_bind,
160 * .unbind = TransportAcme_unbind,
161 * .put = TransportAcme_put
162 * };
163 *
164 * obj->base.fxns = &TransportAcme_fxns;
165 */
166 } INetworkTransport_Object;
168 /*!
169 * @brief Bind transport resources on behalf of the given message queue
170 *
171 * Interface function to invoke transport implementation.
172 *
173 * @sa INetworkTransport_Fxns.bind()
174 *
175 * @param[in] inst Transport instance handle
176 * @param[in] queueId Message queue identifier
177 *
178 * @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
179 */
180 static inline
181 Bool INetworkTransport_bind(INetworkTransport_Handle inst, UInt32 queueId)
182 {
183 INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
184 return (obj->fxns->bind((void *)inst, queueId));
185 }
187 /*!
188 * @brief Unbind transport resources allocated for the given message queue
189 *
190 * Interface function to invoke transport implementation.
191 *
192 * @sa INetworkTransport_Fxns.unbind()
193 *
194 * @param[in] inst Transport instance handle
195 * @param[in] queueId Message queue identifier
196 *
197 * @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
198 */
199 static inline
200 Bool INetworkTransport_unbind(INetworkTransport_Handle inst, UInt32 queueId)
201 {
202 INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
203 return (obj->fxns->unbind((void *)inst, queueId));
204 }
206 /*!
207 * @brief Deliver the given message
208 *
209 * Interface function to invoke transport implementation.
210 *
211 * @sa INetworkTransport_Fxns.put()
212 *
213 * @param[in] inst Transport instance handle
214 * @param[in] msg Pointer to the message (MessageQ_Msg)
215 *
216 * @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
217 */
218 static inline
219 Bool INetworkTransport_put(INetworkTransport_Handle inst, Ptr msg)
220 {
221 INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
222 return (obj->fxns->put((void *)inst, msg));
223 }
225 /*!
226 * @brief Convert the instance handle to a base class handle
227 *
228 * Use this method to safely get a handle to the base interface.
229 * The returned handle can be used to invoke methods on the base
230 * interface.
231 *
232 * @param[in] inst Transport instance handle
233 *
234 * @return An ITransport_Handle for the given instance object
235 */
236 static inline
237 ITransport_Handle INetworkTransport_upCast(INetworkTransport_Handle inst)
238 {
239 INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
240 return ((ITransport_Handle)&obj->base);
241 }
243 /*!
244 * @brief Convert the base class handle into and instance handle
245 *
246 * Use this method to safely get a handle to the interface instance.
247 * The returned handle can be used to invoke methods on the instance
248 * object.
249 *
250 * @param[in] inst ITransport_handle of the instance object
251 *
252 * @return An ITransport_Handle for the given instance
253 */
254 static inline
255 INetworkTransport_Handle INetworkTransport_downCast(ITransport_Handle base)
256 {
257 return ((INetworkTransport_Handle)base);
258 }
260 #if defined (__cplusplus)
261 }
262 #endif
263 #endif /* INETWORKTRANSPORT_H */