More minor coding convention fixes
[ipc/ipcdev.git] / packages / ti / ipc / Ipc.h
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)
363 #endif /* defined (__cplusplus) */
365 #endif /* ti_ipc_Ipc__include */