More minor coding convention fixes
[ipc/ipcdev.git] / packages / ti / ipc / rpmsg / RPMessage.h
1 /*
2  * Copyright (c) 2011-2013, Texas Instruments Incorporated
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  */
32 /** ============================================================================
33  *  @file       RPMessage.h
34  *
35  *  @brief      A simple copy-based MessageQ, to work with Linux virtio_rp_msg.
36  *
37  *  The following are key features of the RPMessage module:
38  *  - Multiple writers, single reader.
39  *  - Timeouts are allowed when receiving messages.
40  *  - Supports processor copy transfers only.
41  *  - Sending/receiving also works between enpoints on the same processor.
42  *
43  *  Non-Features (as compared to MessageQ):
44  *  - zero copy messaging, using registered heaps.
45  *  - Dependence on a NameServer (Client furnishes the endpoint IDs)
46  *  - Arbitrary reply endpoints can be embedded in message header.
47  *  - Priority Queues.
48  *
49  *  Conceptually, the reader thread owns a message queue. The reader thread
50  *  creates a message queue. The writer threads opens a created message queue
51  *  to get access to it.
52  *
53  *  Message queues are identified by a system-wide unique 32 bit queueID,
54  *  which encodes the (MultiProc) 16 bit core ID and a local 16 bit index ID.
55  *
56  *  The RPMessage header should be included in an application as follows:
57  *  @code
58  *  #include <ti/ipc/rpmsg/RPMessage.h>
59  *  @endcode
60  *
61  *  Questions:
62  *  - Workout how connections exist: how does Ducati side cleanup when Linux
63  *    side goes down?
64  *  - Client needs to know max size of data buffer to allocate for receive.
65  *  - Do we need procID's buried in the message header addresses anymore, or
66  *    isn't that now implicit in the vrings/transport.
67  *  - Do we want MessageQ_Unblock in this version?  (Normally used in RCM).
68  *  - Do we want the generic ISync ability to create our own synchronizers,
69  *    or just hard-code semaphore usage or callbacks for simplicity?
70  *
71  *  ============================================================================
72  */
74 #ifndef ti_ipc_RPMessage__include
75 #define ti_ipc_RPMessage__include
77 #if defined (__cplusplus)
78 extern "C" {
79 #endif
82 /* =============================================================================
83  *  Structures & Definitions
84  * =============================================================================
85  */
87 /*!
88  *  @brief      Used as the timeout value to specify wait forever
89  */
90 #define RPMessage_FOREVER                (~(0))
92 /*!
93    *  @def    RPMessage_S_SUCCESS
94  *  @brief  Operation is successful.
95  */
96 #define RPMessage_S_SUCCESS              (0)
98 /*!
99  *  @def    RPMessage_E_FAIL
100  *  @brief  Operation is not successful.
101  */
102 #define RPMessage_E_FAIL                 (-1)
104 /*!
105  *  @def    RPMessage_E_MEMORY
106  *  @brief  Operation resulted in memory failure.
107  */
108 #define RPMessage_E_MEMORY               (-3)
110 /*!
111  *  @def    RPMessage_E_TIMEOUT
112  *  @brief  Operation timed out.
113  */
114 #define RPMessage_E_TIMEOUT              (-6)
116 /*!
117  *  @def    RPMessage_E_NOENDPT
118  *  @brief  No endpoint for a message.
119  */
120 #define RPMessage_E_NOENDPT              (-7)
122 /*!
123  *  @def    MessageQ_E_UNBLOCKED
124  *  @brief  RPMessage was unblocked
125  */
126 #define RPMessage_E_UNBLOCKED            (-19)
128 /*!
129  *  @def    RPMessage_MAX_RESERVED_ENDPOINT
130  *  @brief  Maximum Value for System Reserved Endpoints.
131  */
132 #define RPMessage_MAX_RESERVED_ENDPOINT  (100)
134 /*!
135  *  @def    RPMessage_MAX_RESERVED_ENDPOINT
136  *  @brief  Maximum Value for System Reserved Endpoints.
137  */
138 #define RPMessage_ASSIGN_ANY             (0xFFFFFFFF)
139 /*!
140  *  @brief  RPMessage_Handle type
141  */
142 typedef struct RPMessage_Object *RPMessage_Handle;
145 typedef Void (*RPMessage_callback)(RPMessage_Handle, UArg, Ptr,
146                                       UInt16, UInt32);
148 /* =============================================================================
149  *  RPMessage Functions:
150  * =============================================================================
151  */
154 /*!
155  *  @brief      Create a RPMessage instance for receiving, with callback.
156  *
157  *  This is an extension of RPMessage_create(), with the option of passing
158  *  a callback function and its argument to be called when a message is
159  *  received.
160  *
161  *  @param[in]   reserved     If value is RPMessage_ASSIGN_ANY, then
162  *                            any Endpoint can be assigned; otherwise, value is
163  *                            a reserved Endpoint ID, which must be less than
164  *                            or equal to RPMessage_MAX_RESERVED_ENDPOINT.
165  *  @param[in]   callback     If non-NULL, on received data, this callback is
166  *                            called instead of posting the internal semaphore.
167  *  @param[in]   arg          Argument for the callback.
168  *  @param[out]  endpoint     Endpoint ID for this side of the connection.
169  *
170  *
171  *  @return     RPMessage Handle, or NULL if:
172  *                            - reserved endpoint already taken;
173  *                            - could not allocate object
174  */
175 RPMessage_Handle RPMessage_create(UInt32 reserved,
176                                         RPMessage_callback callback,
177                                         UArg arg,
178                                         UInt32 * endpoint);
179 /*!
180  *  @brief      Receives a message from a message queue
181  *
182  *  This function returns a status. It also copies data to the client.
183  *  If no message is available, it blocks on the semaphore object
184  *  until the semaphore is signaled or a timeout occurs.
185  *  The semaphore is signaled, when Message_send is called to deliver a message
186  *  to this endpoint. If a timeout occurs, len is set to zero and the status is
187  *  #RPMessage_E_TIMEOUT. If a timeout of zero is specified, the function
188  *  returns immediately and if no message is available, the len is set to zero
189  *  and the status is #RPMessage_E_TIMEOUT.
190  *  The #RPMessage_E_UNBLOCKED status is returned, if MessageQ_unblock is called
191  *  on the RPMessage handle.
192  *  If a message is successfully retrieved, the message
193  *  data is copied into the data pointer, and a #RPMessage_S_SUCCESS
194  *  status is returned.
195  *
196  *  @param[in]  handle      RPMessage handle
197  *  @param[out] data        Pointer to the client's data buffer.
198  *  @param[out] len         Amount of data received.
199  *  @param[out] rplyEndpt   Endpoint of source (for replies).
200  *  @param[in]  timeout     Maximum duration to wait for a message in
201  *                          microseconds.
202  *
203  *  @return     RPMessage status:
204  *              - #RPMessage_S_SUCCESS: Message successfully returned
205  *              - #RPMessage_E_TIMEOUT: RPMessage_recv timed out
206  *              - #RPMessage_E_UNBLOCKED: MessageQ_get was unblocked
207  *              - #RPMessage_E_FAIL:    A general failure has occurred
208  *
209  *  @sa         RPMessage_send RPMessage_unblock
210  */
211 Int RPMessage_recv(RPMessage_Handle handle, Ptr data, UInt16 *len,
212                       UInt32 *rplyEndpt, UInt timeout);
214 /*!
215  *  @brief      Sends data to a remote processor, or copies onto a local
216  *              messageQ.
217  *
218  *  If the message is placed onto a local Message queue, the queue's
219  *  #RPMessage_Params::semaphore signal function is called.
220  *
221  *  @param[in]  dstProc     Destination ProcId.
222  *  @param[in]  dstEndpt    Destination Endpoint.
223  *  @param[in]  srcEndpt    Source Endpoint.
224  *  @param[in]  data        Data payload to be copied and sent.
225  *  @param[in]  len         Amount of data to be copied, including Msg header.
226  *
227  *  @return     Status of the call.
228  *              - #RPMessage_S_SUCCESS denotes success.
229  *              - #RPMessage_E_FAIL denotes failure.
230  *                The send was not successful.
231  */
232 Int RPMessage_send(UInt16 dstProc,
233                       UInt32 dstEndpt,
234                       UInt32 srcEndpt,
235                       Ptr    data,
236                       UInt16 len);
238 /*!
239  *  @brief      Delete a created RPMessage instance.
240  *
241  *  This function deletes a created message queue instance. If the
242  *  message queue is non-empty, any messages remaining in the queue
243  *  will be lost.
244  *
245  *  @param[in,out]  handlePtr   Pointer to handle to delete.
246  *
247  *  @return     RPMessage status:
248  *              - #RPMessage_E_FAIL: delete failed
249  *              - #RPMessage_S_SUCCESS: delete successful, *handlePtr = NULL.
250  */
251 Int RPMessage_delete(RPMessage_Handle *handlePtr);
253 /*!
254  *  @brief      Unblocks a MessageQ
255  *
256  *  Unblocks a reader thread that is blocked on a RPMessage_recv.  The
257  *  RPMessage_recv call will return with status #MessageQ_E_UNBLOCKED
258  *  indicating that it returned due to a RPMessage_unblock rather than by
259  *  a timeout or receiving a message.
260  *
261  *  Restrictions:
262  *  -  A queue may not be used after it has been unblocked.
263  *  -  MessageQ_unblock may only be called on a local queue.
264  *
265  *  @param[in]  handle      RPMessage handle
266  *
267  *  @sa         RPMessage_recv
268  */
269 Void RPMessage_unblock(RPMessage_Handle handle);
271 #if defined (__cplusplus)
273 #endif /* defined (__cplusplus) */
274 #endif /* ti_ipc_RPMessage__include */