d0aee848be7ba6c78e1f3f520b570be87b368876
[ipc/ipcdev.git] / linux / include / ti / ipc / interfaces / INetworkTransport.h
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)
183     INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
184     return (obj->fxns->bind((void *)inst, queueId));
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)
202     INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
203     return (obj->fxns->unbind((void *)inst, queueId));
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)
221     INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
222     return (obj->fxns->put((void *)inst, msg));
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)
239     INetworkTransport_Object *obj = (INetworkTransport_Object *)inst;
240     return ((ITransport_Handle)&obj->base);
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)
257     return ((INetworkTransport_Handle)base);
260 #if defined (__cplusplus)
262 #endif
263 #endif /* INETWORKTRANSPORT_H */