1 /*
2 * Copyright (c) 2012-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 ti/ipc/Ipc.h
34 *
35 * @brief Ipc Manager.
36 *
37 * This module is primarily used to configure IPC, synchronize processors, and
38 * initialize the IPC runtime.
39 *
40 * On SYS/BIOS, the memory for SharedRegion zero must be valid
41 * before Ipc_start() can be called. Ipc_start() must be called before any
42 * other IPC APIs are used.
43 *
44 * The Ipc header should be included in an application as follows:
45 * @code
46 * #include <ti/ipc/Ipc.h>
47 * @endcode
48 */
50 #ifndef ti_ipc_Ipc__include
51 #define ti_ipc_Ipc__include
53 #if defined (__cplusplus)
54 extern "C" {
55 #endif
57 /* =============================================================================
58 * All success and failure codes for the module
59 * =============================================================================
60 */
62 /*!
63 * @brief The resource is still in use
64 */
65 #define Ipc_S_BUSY 2
67 /*!
68 * @brief The module has been already setup
69 */
70 #define Ipc_S_ALREADYSETUP 1
72 /*!
73 * @brief Operation is successful.
74 */
75 #define Ipc_S_SUCCESS 0
77 /*!
78 * @brief Generic failure.
79 */
80 #define Ipc_E_FAIL -1
82 /*!
83 * @brief Argument passed to function is invalid.
84 */
85 #define Ipc_E_INVALIDARG -2
87 /*!
88 * @brief Operation resulted in memory failure.
89 */
90 #define Ipc_E_MEMORY -3
92 /*!
93 * @brief The specified entity already exists.
94 */
95 #define Ipc_E_ALREADYEXISTS -4
97 /*!
98 * @brief Unable to find the specified entity.
99 */
100 #define Ipc_E_NOTFOUND -5
102 /*!
103 * @brief Operation timed out.
104 */
105 #define Ipc_E_TIMEOUT -6
107 /*!
108 * @brief Module is not initialized or in an invalid state.
109 */
110 #define Ipc_E_INVALIDSTATE -7
112 /*!
113 * @brief A failure occurred in an OS-specific call
114 */
115 #define Ipc_E_OSFAILURE -8
117 /*!
118 * @brief Specified resource is not available
119 */
120 #define Ipc_E_RESOURCE -9
122 /*!
123 * @brief Operation was interrupted. Please restart the operation
124 */
125 #define Ipc_E_RESTART -10
127 /*!
128 * @brief Operation was not ready.
129 */
130 #define Ipc_E_NOTREADY -11
133 /* =============================================================================
134 * Ipc Module-wide Functions
135 * =============================================================================
136 */
138 /*!
139 * @brief Attach to remote processor
140 *
141 * @note This function is currently only supported on SYS/BIOS.
142 *
143 * This function synchronizes with the remote processor, typically via
144 * shared memory. Both processors must call this function to attach to each
145 * other. Ipc_start() must be called before calling Ipc_attach().
146 * A processor must attach to the owner of SharedRegion zero before
147 * it can successfully attach to another processor. Attempting to
148 * attach to another processor first returns #Ipc_E_FAIL.
149 *
150 * This function opens the default GateMP and SharedRegion zero heap.
151 * The Notify, NameServerRemoteNotify, and MessageQ transport
152 * instances are created for communicating with the specified remote
153 * processor in SharedRegion zero heap. The user's Ipc attach function
154 * is called.
155 *
156 * On SYS/BIOS, this function should be called within a 'while' loop
157 * within a Task. A Task_sleep() or Task_yield() should be called
158 * within the loop to allow other threads in the system to execute.
159 * This function needs to be called in a loop because the remote
160 * processor may not be in a ready state.
161 *
162 * @note For SYS/BIOS, if the config parameter Ipc.procSync is set to
163 * Ipc.ProcSync_ALL, there is no need to call this function as it is
164 * internally called by Ipc_start().
165 *
166 * @code
167 * while (Ipc_attach(remoteProcId) < 0) {
168 * Task_sleep(1);
169 * }
170 * @endcode
171 *
172 * @param remoteProcId remote processor's MultiProc id
173 *
174 * @return Status
175 * - #Ipc_S_SUCCESS: attach was successful
176 * - #Ipc_S_ALREADYSETUP: already attached
177 * - #Ipc_E_MEMORY: operation failed due to a memory error
178 * - #Ipc_E_FAIL: General failure
179 * - #Ipc_E_NOTREADY: remote processor not ready
180 *
181 * @sa Ipc_detach()
182 * @sa Ipc_isAttached()
183 */
184 Int Ipc_attach(UInt16 remoteProcId);
186 /*!
187 * @brief Detach from the remote processor
188 *
189 * @note This function is currently only supported on SYS/BIOS.
190 *
191 * A processor must detach from all other processors before it can
192 * successfully detach from the owner of SharedRegion zero. Attempting to
193 * detach from the owner of SharedRegion zero first returns #Ipc_E_FAIL.
194 *
195 * If a processor successfully attached to a remote processor 'N' times,
196 * it must call Ipc_detach 'N' times to be completely detached.
197 * Ipc_detach returns #Ipc_S_BUSY for the first 'N - 1' times its called.
198 * Ipc_detach returns #Ipc_S_SUCCESS, if successful, on the 'N' time its
199 * called. If called on a remote processor that is detached, #Ipc_S_SUCCESS
200 * is returned.
201 *
202 * This function should be called within a loop to make sure the processor
203 * successfully detached from the remote processor.
204 * If called from the processor with the bigger procId, this function closes
205 * the instances created for communicating with the specified remote processor.
206 * If called from the processor with the smaller procId, this function returns
207 * Ipc_E_NOTREADY while the processor with the bigger procId has not finished
208 * detaching. Once the processor with the bigger procId is finished detaching,
209 * this function deletes the instances created for communicating with the
210 * specified remote processor.
211 *
212 * For SYS/BIOS, this function should be called within a 'while' loop in a Task
213 * because the slave may have to wait for the master to detach. Furthermore,
214 * a Task_sleep() or Task_yield() should be called within the same 'while'
215 * loop to allow other threads in the system to execute.
216 *
217 * @code
218 * while (TRUE) {
219 * status = Ipc_detach(remoteProcId);
220 * if (status == Ipc_E_NOTREADY) {
221 * Task_sleep(1);
222 * }
223 * else if (status < 0) {
224 * System_printf("Ipc_detach failed \n");
225 * break;
226 * }
227 * else {
228 * break;
229 * }
230 * }
231 * @endcode
232 *
233 * @param remoteProcId remote processor's MultiProc id
234 *
235 * @return Status
236 * - #Ipc_S_SUCCESS: operation was successful
237 * - #Ipc_S_BUSY: attach count != 0
238 * - #Ipc_E_FAIL: operation failed
239 * - #Ipc_E_NOTREADY: processor not ready to detach
240 *
241 * @sa Ipc_attach()
242 * @sa Ipc_isAttached()
243 */
244 Int Ipc_detach(UInt16 remoteProcId);
246 /*!
247 * @brief Query whether attached to a remote processor
248 *
249 * @note This function is currently only supported on SYS/BIOS.
250 *
251 * @param remoteProcId remote processor's MultiProc id
252 *
253 * @return TRUE if attached, FALSE if not attached
254 *
255 * @remark If @c remoteProcId == MultiProc_self(), FALSE is always returned.
256 *
257 * @sa Ipc_attach()
258 * @sa Ipc_detach()
259 */
260 Bool Ipc_isAttached(UInt16 remoteProcId);
262 /*!
263 * @brief Reads the config entry from the config area.
264 *
265 * @note This function is currently only supported on SYS/BIOS.
266 *
267 * For more information about this API, refer to the documentation for
268 * Ipc_writeConfig()
269 *
270 * @param remoteProcId remote processor's MultiProc id
271 * @param tag tag to identify a config entry
272 * @param cfg address where the entry will be copied
273 * @param size size of config entry
274 *
275 * @return Status
276 * - #Ipc_S_SUCCESS: operation was successful
277 * - #Ipc_E_FAIL: operation failed
278 *
279 * @sa Ipc_writeConfig
280 */
281 Int Ipc_readConfig(UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size);
283 /*!
284 * @brief Reserves memory, creates default GateMP and HeapMemMP
285 *
286 * This function needs to be called before Ipc_attach(). It should
287 * only be called once, unless the return value is #Ipc_E_NOTREADY.
288 * This indicates that either the SharedRegion zero is not valid or
289 * has not been setup yet so Ipc_start may be called again. Once
290 * successfully started, subsequent calls returns #Ipc_S_ALREADYSETUP.
291 *
292 * Ipc reserves some shared memory in SharedRegion zero for synchronization.
293 * GateMP reserves some shared memory for managing the gates and for the
294 * default GateMP. The same amount of memory must be reserved by each
295 * processor, but only the owner of SharedRegion zero clears the reserved
296 * memory and creates the default GateMP. The default heap for each
297 * SharedRegion is created by the owner of each SharedRegion.
298 *
299 * @note For SYS/BIOS, if the config parameter Ipc.procSync is set to
300 * Ipc.ProcSync_ALL, this function calls Ipc_attach() internally.
301 *
302 * @return Status
303 * - #Ipc_S_SUCCESS: operation was successful
304 * - #Ipc_S_ALREADYSETUP: already successfully called
305 * - #Ipc_E_NOTREADY: shared memory is not ready
306 * - #Ipc_E_FAIL: operation failed
307 *
308 * @sa Ipc_stop()
309 */
310 Int Ipc_start(Void);
312 /*!
313 * @brief Resets the Ipc state
314 *
315 * This function should be called only once and only after detaching
316 * from all processors. Once called, Ipc is placed back to
317 * the same state as it was before Ipc_start() was called.
318 *
319 * @return Status
320 * - #Ipc_S_SUCCESS: operation was successful
321 *
322 * @sa Ipc_start()
323 */
324 Int Ipc_stop(Void);
326 /*!
327 * @brief Writes the config entry to the config area.
328 *
329 * @note This function is currently only supported on SYS/BIOS.
330 *
331 * Ipc_writeConfig() and Ipc_readConfig() are used to pass
332 * configuration information from one core to another. This 'information'
333 * is passed via a pointer to shared memory with a given size and is
334 * identified via a unique tag. A typical use case of this API would be
335 * passing configuration information at startup-time. For example, if
336 * MessageQ is used, this information might include the queue name, message
337 * heap sizes, etc.
338 *
339 * For Ipc_writeConfig(), if 'NULL' is passed in for the cfg parameter,
340 * it attempts to free the shared memory that is allocated by a previous
341 * Ipc_writeConfig() call. The @c remoteProcId, @c tag, and @c size must match
342 * the previous Ipc_writeConfig() call.
343 *
344 * Ipc_writeConfig() writes into SharedRegion 0 (SR0) and uses
345 * @c tag to uniquely identify the structure (@c cfg) and @c size written
346 * into SR0 which both sides must agree on.
347 *
348 * @param remoteProcId remote processor's MultiProc id
349 * @param tag tag to identify a config entry
350 * @param cfg address where the entry will be copied
351 * @param size size of config entry
352 *
353 * @return Status
354 * - #Ipc_S_SUCCESS: if operation was successful
355 * - #Ipc_E_FAIL: if operation failed
356 *
357 * @sa Ipc_readConfig()
358 */
359 Int Ipc_writeConfig(UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size);
361 #if defined (__cplusplus)
362 }
363 #endif /* defined (__cplusplus) */
365 #endif /* ti_ipc_Ipc__include */