786462c564c0d81f2954f68daa990a96969b4404
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 MessageQCopy.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 MessageQCopy 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 MessageQCopy header should be included in an application as follows:
57 * @code
58 * #include <ti/ipc/rpmsg/MessageQCopy.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_MessageQCopy__include
75 #define ti_ipc_MessageQCopy__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 MessageQCopy_FOREVER ~(0)
92 /*!
93 * @def MessageQCopy_S_SUCCESS
94 * @brief Operation is successful.
95 */
96 #define MessageQCopy_S_SUCCESS 0
98 /*!
99 * @def MessageQCopy_E_FAIL
100 * @brief Operation is not successful.
101 */
102 #define MessageQCopy_E_FAIL -1
104 /*!
105 * @def MessageQCopy_E_MEMORY
106 * @brief Operation resulted in memory failure.
107 */
108 #define MessageQCopy_E_MEMORY -3
110 /*!
111 * @def MessageQCopy_E_TIMEOUT
112 * @brief Operation timed out.
113 */
114 #define MessageQCopy_E_TIMEOUT -6
116 /*!
117 * @def MessageQCopy_E_NOENDPT
118 * @brief No endpoint for a message.
119 */
120 #define MessageQCopy_E_NOENDPT -7
122 /*!
123 * @def MessageQ_E_UNBLOCKED
124 * @brief MessageQCopy was unblocked
125 */
126 #define MessageQCopy_E_UNBLOCKED -19
128 /*!
129 * @def MessageQCopy_MAX_RESERVED_ENDPOINT
130 * @brief Maximum Value for System Reserved Endpoints.
131 */
132 #define MessageQCopy_MAX_RESERVED_ENDPOINT 100
134 /*!
135 * @def MessageQCopy_MAX_RESERVED_ENDPOINT
136 * @brief Maximum Value for System Reserved Endpoints.
137 */
138 #define MessageQCopy_ASSIGN_ANY 0xFFFFFFFF
139 /*!
140 * @brief MessageQCopy_Handle type
141 */
142 typedef struct MessageQCopy_Object *MessageQCopy_Handle;
145 typedef Void (*MessageQCopy_callback)(MessageQCopy_Handle, UArg, Ptr,
146 UInt16, UInt32);
148 /* =============================================================================
149 * MessageQCopy Functions:
150 * =============================================================================
151 */
154 /*!
155 * @brief Create a MessageQCopy instance for receiving, with callback.
156 *
157 * This is an extension of MessageQCopy_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 MessageQCopy_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 MessageQCopy_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 MessageQCopy Handle, or NULL if:
172 * - reserved endpoint already taken;
173 * - could not allocate object
174 */
175 MessageQCopy_Handle MessageQCopy_create(UInt32 reserved,
176 MessageQCopy_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 * #MessageQCopy_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 #MessageQCopy_E_TIMEOUT.
190 * The #MessageQCopy_E_UNBLOCKED status is returned, if MessageQ_unblock is called
191 * on the MessageQCopy handle.
192 * If a message is successfully retrieved, the message
193 * data is copied into the data pointer, and a #MessageQCopy_S_SUCCESS
194 * status is returned.
195 *
196 * @param[in] handle MessageQCopy 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 MessageQCopy status:
204 * - #MessageQCopy_S_SUCCESS: Message successfully returned
205 * - #MessageQCopy_E_TIMEOUT: MessageQCopy_recv timed out
206 * - #MessageQCopy_E_UNBLOCKED: MessageQ_get was unblocked
207 * - #MessageQCopy_E_FAIL: A general failure has occurred
208 *
209 * @sa MessageQCopy_send MessageQCopy_unblock
210 */
211 Int MessageQCopy_recv(MessageQCopy_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 * #MessageQCopy_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 * - #MessageQCopy_S_SUCCESS denotes success.
229 * - #MessageQCopy_E_FAIL denotes failure.
230 * The send was not successful.
231 */
232 Int MessageQCopy_send(UInt16 dstProc,
233 UInt32 dstEndpt,
234 UInt32 srcEndpt,
235 Ptr data,
236 UInt16 len);
238 /*!
239 * @brief Delete a created MessageQCopy 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 MessageQCopy status:
248 * - #MessageQCopy_E_FAIL: delete failed
249 * - #MessageQCopy_S_SUCCESS: delete successful, *handlePtr = NULL.
250 */
251 Int MessageQCopy_delete(MessageQCopy_Handle *handlePtr);
253 /*!
254 * @brief Unblocks a MessageQ
255 *
256 * Unblocks a reader thread that is blocked on a MessageQCopy_recv. The
257 * MessageQCopy_recv call will return with status #MessageQ_E_UNBLOCKED
258 * indicating that it returned due to a MessageQCopy_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 MessageQCopy handle
266 *
267 * @sa MessageQCopy_recv
268 */
269 Void MessageQCopy_unblock(MessageQCopy_Handle handle);
271 #if defined (__cplusplus)
272 }
273 #endif /* defined (__cplusplus) */
274 #endif /* ti_ipc_MessageQCopy__include */