SDOCM00115293 Linux transport interfaces need documentation
[ipc/ipcdev.git] / linux / include / ti / ipc / interfaces / IMessageQTransport.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/IMessageQTransport.h
35  *
36  *  @brief Primary interface for all MessageQ transports
37  *
38  *  A typical memory based transport used as the primary transport for
39  *  MessageQ would implement this interface. The transport implementation
40  *  has to be registered with MessageQ using the MessageQ_registerTransport
41  *  method. This is typically done by the factor code.
42  *
43  *  The IMessageQTransport interface includes the following instance methods:
44  *
45  *  bind - create transport resources on behalf of the given queue
46  *  unbind - delete transport resources used by the given queue
47  *  put - send the message
48  */
50 /*
51  *  ======== IMessageQTransport.h ========
52  */
54 #ifndef IMESSAGEQTRANSPORT_H
55 #define IMESSAGEQTRANSPORT_H
57 #include <ti/ipc/interfaces/ITransport.h>
59 #if defined (__cplusplus)
60 extern "C" {
61 #endif
63 /*!
64  *  @brief  Interface type ID
65  *
66  *  This ID uniquely identifies this interface type.
67  */
68 #define IMessageQTransport_TypeId 0x02
70 /*!
71  *  @brief IMessageQTransport_Handle type
72  *
73  *  An opaque instance handle.
74  */
75 typedef struct IMessageQTransport_Object *IMessageQTransport_Handle;
77 /*!
78  *  @brief The interface function table
79  *
80  *  All transports must provide a concrete implementation for each of
81  *  these virtual functions. The transport user (e.g. MessageQ) will
82  *  invoke the implementation functions through the interface function
83  *  stubs defined below.
84  */
85 typedef struct IMessageQTransport_Fxns {
87     Int (*bind)(void *handle, UInt32 queueId);
88     /*!< function pointer for bind method
89      *
90      *  This method allows the transport to bind/create resources
91      *  needed for message delivery. The method is invoked when a
92      *  new message queue is created and for all existing queues
93      *  when attaching to a processor.
94      *
95      *  @param[in]  inst        Transport instance handle
96      *  @param[in]  queueId     Message queue identifier
97      *
98      *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
99      */
101     Int (*unbind)(void *handle, UInt32 queueId);
102     /*!< function pointer for unbind method
103      *
104      *  This method allows the transport to unbind/delete resources
105      *  which where allocated on behalf of the given message queue.
106      *  This method is invoked when deleting a message queue and for
107      *  all existing queues when detaching from a processor.
108      *
109      *  @param[in]  inst        Transport instance handle
110      *  @param[in]  queueId     Message queue identifier
111      *
112      *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
113      */
115     Bool (*put)(void *handle, Ptr msg);
116     /*!< function pointer for put method
117      *
118      *  Invoked to deliver the given message. Once MessageQ calls into this
119      *  method, the message ownership has been transferred to the transport.
120      *  Regardless of the outcome of message delivery, the message ownership
121      *  is *never* returned back to MessageQ. If delivery fails, the message
122      *  is lost but all resources must be reclaimed.
123      *
124      *  @param[in]  inst        Transport instance handle
125      *  @param[in]  msg         Pointer to the message (MessageQ_Msg)
126      *
127      *  @return Status result:
128      *          - TRUE: message was delivered
129      *          - FALSE: delivery failure, message lost
130      */
131 } IMessageQTransport_Fxns;
133 /*!
134  *  @brief The instance object definition for IMessageQTransport
135  *
136  *  All instances of this interface type must define this object
137  *  within the implementation object. It must be the first element
138  *  of the instance object and it must be named 'base'. Otherwise,
139  *  the converter functions below will fail.
140  *
141  *  typedef TransportAcme_Object {
142  *      IMessageQTransport_Object base;
143  *      ...
144  *  } TransportAcme_Object;
145  */
146 typedef struct IMessageQTransport_Object {
148     ITransport_Object base;
149     /*!< Base class inheritance
150      *
151      *  The instance constructor must initialize this base object.
152      */
154     IMessageQTransport_Fxns *fxns;
155     /*!< Address of interface function table
156      *
157      *  The instance constructor must initialize this field to contain
158      *  the address of the instance function table.
159      *
160      *  IMessageQTransport_Fxns TransportAcme_fxns = {
161      *      .bind   = TransportAcme_bind,
162      *      .unbind = TransportAcme_unbind,
163      *      .put    = TransportAcme_put
164      *  };
165      *
166      *  obj->base.fxns = &TransportAcme_fxns;
167      */
168 } IMessageQTransport_Object;
170 /*!
171  *  @brief Bind transport resources on behalf of the given message queue
172  *
173  *  Interface function to invoke transport implementation.
174  *
175  *  @sa IMessageQTransport_Fxns.bind()
176  *
177  *  @param[in]  inst        Transport instance handle
178  *  @param[in]  queueId     Message queue identifier
179  *
180  *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
181  */
182 static inline
183 Int IMessageQTransport_bind(IMessageQTransport_Handle inst, UInt32 queueId)
185     IMessageQTransport_Object *obj = (IMessageQTransport_Object *)inst;
186     return obj->fxns->bind((void *)inst, queueId);
189 /*!
190  *  @brief Unbind transport resources allocated for the given message queue
191  *
192  *  Interface function to invoke transport implementation.
193  *
194  *  @sa IMessageQTransport_Fxns.unbind()
195  *
196  *  @param[in]  inst        Transport instance handle
197  *  @param[in]  queueId     Message queue identifier
198  *
199  *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
200  */
201 static inline
202 Int IMessageQTransport_unbind(IMessageQTransport_Handle inst, UInt32 queueId)
204     IMessageQTransport_Object *obj = (IMessageQTransport_Object *)inst;
205     return obj->fxns->unbind((void *)inst, queueId);
208 /*!
209  *  @brief Deliver the given message
210  *
211  *  Interface function to invoke transport implementation.
212  *
213  *  @sa IMessageQTransport_Fxns.put()
214  *
215  *  @param[in]  inst        Transport instance handle
216  *  @param[in]  msg         Pointer to the message (MessageQ_Msg)
217  *
218  *  @return A MessageQ defined status code (e.g. MessageQ_S_SUCCESS)
219  */
220 static inline
221 Bool IMessageQTransport_put(IMessageQTransport_Handle inst, Ptr msg)
223     IMessageQTransport_Object *obj = (IMessageQTransport_Object *)inst;
224     return obj->fxns->put((void *)inst, msg);
227 /*!
228  *  @brief Convert the instance handle to a base class handle
229  *
230  *  Use this method to safely get a handle to the base interface.
231  *  The returned handle can be used to invoke methods on the base
232  *  interface.
233  *
234  *  @param[in]  inst        Transport instance handle
235  *
236  *  @return An ITransport_Handle for the given instance object
237  */
238 static inline
239 ITransport_Handle IMessageQTransport_upCast(IMessageQTransport_Handle inst)
241     IMessageQTransport_Object *obj = (IMessageQTransport_Object *)inst;
242     return (ITransport_Handle)&obj->base;
245 /*!
246  *  @brief Convert the base class handle into and instance handle
247  *
248  *  Use this method to safely get a handle to the interface instance.
249  *  The returned handle can be used to invoke methods on the instance
250  *  object.
251  *
252  *  @param[in]  inst        ITransport_handle of the instance object
253  *
254  *  @return An ITransport_Handle for the given instance
255  */
256 static inline
257 IMessageQTransport_Handle IMessageQTransport_downCast(ITransport_Handle base)
259     return (IMessageQTransport_Handle)base;
262 #if defined (__cplusplus)
264 #endif
265 #endif /* IMESSAGEQTRANSPORT_H */