More minor coding convention fixes
[ipc/ipcdev.git] / packages / ti / ipc / GateMP.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/GateMP.h
34  *
35  *  @brief      Multiple processor gate that provides local and remote context
36  *              protection.
37  *
38  *  @note       GateMP is currently only available for SYS/BIOS.
39  *
40  *  A GateMP instance can be used to enforce both local and remote context
41  *  context protection.  That is, entering a GateMP can prevent preemption by
42  *  another thread running on the same processor and simultaneously prevent a
43  *  remote processor from entering the same gate.  GateMP's are typically used
44  *  to protect reads/writes to a shared resource, such as shared memory.
45  *
46  *  Creating a GateMP requires supplying the following configuration
47  *      - Instance name (see #GateMP_Params.name)
48  *      - Region id (see #GateMP_Params.regionId)
49  *
50  *  In addition, the following parameters should be configured as necessary:
51  *      - The level of local protection (interrupt, thread, tasklet, process
52  *        or none) can be configured using the #GateMP_Params.localProtect
53  *        config parameter.
54  *      - The type of remote system gate that can be used.  Most devices will
55  *        typically have a single type of system gate so this configuration
56  *        should typically be left alone.  See #GateMP_Params.remoteProtect for
57  *        more information.
59  *  Once created, GateMP allows the gate to be opened on another processor
60  *  using GateMP_open() and the name that was used in GateMP_create().
61  *
62  *  A GateMP can be entered and left using GateMP_enter() and GateMP_leave()
63  *  like any other gate that implements the IGateProvider interface.
64  *
65  *  GateMP has the following proxies - RemoteSystemProxy, RemoteCustom1Proxy
66  *  and RemoteCustom2Proxy which are automatically plugged with device-specific
67  *  delegates that implement multiple processor mutexes using a variety of
68  *  hardware mechanisms.
69  *
70  *  GateMP creates a default system gate whose handle may be obtained
71  *  using GateMP_getDefaultRemote().  Most IPC modules typically use this gate
72  *  by default if they require gates and no instance gate is configured by the
73  *  user.
74  *
75  *  The GateMP header should be included in an application as follows:
76  *  @code
77  *  #include <ti/ipc/GateMP.h>
78  *  @endcode
79  */
81 #ifndef ti_ipc_GateMP__include
82 #define ti_ipc_GateMP__include
84 #if defined (__cplusplus)
85 extern "C" {
86 #endif
88 /* =============================================================================
89  *  All success and failure codes for the module
90  * =============================================================================
91  */
93 /*!
94  *  @brief  The resource is still in use
95  */
96 #define GateMP_S_BUSY               (2)
98 /*!
99  *  @brief  The module has been already setup
100  */
101 #define GateMP_S_ALREADYSETUP       (1)
103 /*!
104  *  @brief  Operation is successful.
105  */
106 #define GateMP_S_SUCCESS            (0)
108 /*!
109  *  @brief  Generic failure.
110  */
111 #define GateMP_E_FAIL              (-1)
113 /*!
114  *  @brief  Argument passed to function is invalid.
115  */
116 #define GateMP_E_INVALIDARG        (-2)
118 /*!
119  *  @brief  Operation resulted in memory failure.
120  */
121 #define GateMP_E_MEMORY            (-3)
123 /*!
124  *  @brief  The specified entity already exists.
125  */
126 #define GateMP_E_ALREADYEXISTS     (-4)
128 /*!
129  *  @brief  Unable to find the specified entity.
130  */
131 #define GateMP_E_NOTFOUND          (-5)
133 /*!
134  *  @brief  Operation timed out.
135  */
136 #define GateMP_E_TIMEOUT           (-6)
138 /*!
139  *  @brief  Module is not initialized.
140  */
141 #define GateMP_E_INVALIDSTATE      (-7)
143 /*!
144  *  @brief  A failure occurred in an OS-specific call  */
145 #define GateMP_E_OSFAILURE         (-8)
147 /*!
148  *  @brief  Specified resource is not available  */
149 #define GateMP_E_RESOURCE          (-9)
151 /*!
152  *  @brief  Operation was interrupted. Please restart the operation  */
153 #define GateMP_E_RESTART           (-10)
155 /* =============================================================================
156  *  Structures & Enums
157  * =============================================================================
158  */
160 /*!
161  *  @brief  A set of local context protection levels
162  *
163  *  Each member corresponds to a specific local processor gates used for
164  *  local protection.
165  *
166  *  For SYS/BIOS users, the following are the mappings for the constants
167  *      - INTERRUPT -> GateAll: disables interrupts, Swis and Tasks
168  *      - TASKLET   -> GateSwi: disables Swis and Tasks
169  *      - THREAD    -> GateMutexPri: based on Semaphores
170  *      - PROCESS   -> GateMutexPri: based on Semaphores
171  */
172 typedef enum GateMP_LocalProtect {
173     GateMP_LocalProtect_NONE      = 0,
174     /*!< Use no local protection */
176     GateMP_LocalProtect_INTERRUPT = 1,
177     /*!< Use the INTERRUPT local protection level */
179     GateMP_LocalProtect_TASKLET   = 2,
180     /*!< Use the TASKLET local protection level */
182     GateMP_LocalProtect_THREAD    = 3,
183     /*!< Use the THREAD local protection level */
185     GateMP_LocalProtect_PROCESS   = 4
186     /*!< Use the PROCESS local protection level */
188 } GateMP_LocalProtect;
191 /*!
192  *  @brief  Type of remote Gate
193  *
194  *  Each member corresponds to a specific type of remote gate.
195  *  Each enum value corresponds to the following remote protection levels:
196  *      - NONE      -> No remote protection (the GateMP instance will
197  *                     exclusively offer local protection configured in
198  *                     #GateMP_Params.localProtect
199  *      - SYSTEM    -> Use the SYSTEM remote protection level (default for
200  *                     remote protection
201  *      - CUSTOM1   -> Use the CUSTOM1 remote protection level
202  *      - CUSTOM2   -> Use the CUSTOM2 remote protection level
203  */
204 typedef enum GateMP_RemoteProtect {
205     GateMP_RemoteProtect_NONE     = 0,
206     /*!< No remote protection (the GateMP instance will exclusively
207      *  offer local protection configured in #GateMP_Params.localProtect)
208      */
210     GateMP_RemoteProtect_SYSTEM   = 1,
211     /*!< Use the SYSTEM remote protection level (default remote protection) */
213     GateMP_RemoteProtect_CUSTOM1  = 2,
214     /*!< Use the CUSTOM1 remote protection level */
216     GateMP_RemoteProtect_CUSTOM2  = 3
217     /*!< Use the CUSTOM2 remote protection level */
219 } GateMP_RemoteProtect;
221 /*!
222  *  @brief  GateMP_Handle type
223  */
224 typedef struct GateMP_Object *GateMP_Handle;
226 /*!
227  *  @brief  Structure defining parameters for the GateMP module.
228  */
229 typedef struct GateMP_Params {
230     String name;
231     /*!< Name of this instance.
232      *
233      *  The name (if not NULL) must be unique among all GateMP instances
234      *  in the entire system.  The name does not have to be in persistent
235      *  memory.  The supplied string is copied into persistent memory.
236      *  If no name is supplied, the instance cannot be opened calling
237      *  GateMP_open().  The max length of the name is defined by the
238      *  maxNameLen of the NameServer instance.
239      */
241     UInt16 regionId;
242     /*!< Shared region ID
243      *
244      *  The index corresponding to the shared region from which shared memory
245      *  is allocated for the instance.  If not specified, the default of '0'
246      *  is used, otherwise the specified SharedRegion is used.  The amount
247      *  of shared memory allocated can be determined by calling
248      *  GateMP_sharedMemReq().
249      */
251     /*! @cond */
252     Ptr sharedAddr;
253     /*!< Physical address of the shared memory
254      *
255      *  This value can be left as 'null' unless it is required to place the
256      *  instance at a specific location in shared memory.  If specified,
257      *  it must be from a valid SharedRegion and the regionId is ignored.
258      *  If sharedAddr is null, then shared memory for a new instance is
259      *  allocated from the heap belonging to the region identified by
260      *  #GateMP_Params.regionId.  The amount of shared memory allocated
261      *  can be determined by calling GateMP_sharedMemReq().
262      */
263     /*! @endcond */
266     GateMP_LocalProtect localProtect;
267     /*!< Local protection level
268      *
269      *   The default value is #GateMP_LocalProtect_THREAD
270      */
272     GateMP_RemoteProtect remoteProtect;
273     /*!< Remote protection level
274      *
275      *   The default value is #GateMP_RemoteProtect_SYSTEM
276      */
277 } GateMP_Params;
279 /* =============================================================================
280  *  GateMP Module-wide Functions
281  * =============================================================================
282  */
284 /*!
285  *  @brief      Close an opened gate
286  *
287  *  @param[in,out]  handlePtr   Pointer to handle to opened GateMP instance
288  *
289  *  @return     GateMP status
290  */
291 Int GateMP_close(GateMP_Handle *handlePtr);
293 /*!
294  *  @brief      Create a GateMP instance
295  *
296  *  The params structure should be initialized using GateMP_Params_init().
297  *
298  *  @param[in]  params      GateMP parameters
299  *
300  *  @return     GateMP Handle
301  */
302 GateMP_Handle GateMP_create(const GateMP_Params *params);
304 /*!
305  *  @brief      Delete a created GateMP instance
306  *
307  *  @param[in,out]  handlePtr       Pointer to GateMP handle
308  *
309  *  @return     GateMP Status
310  */
311 Int GateMP_delete(GateMP_Handle *handlePtr);
313 /*!
314  *  @brief      Get the default remote gate
315  *
316  *  @return     GateMP handle
317  */
318 GateMP_Handle GateMP_getDefaultRemote(Void);
320 /*!
321  *  @brief      Get the local protection level configured in a GateMP instance
322  *
323  *  @return     GateMP_LocalProtect corresponding to local protection level
324  */
325 GateMP_LocalProtect GateMP_getLocalProtect(GateMP_Handle handle);
327 /*!
328  *  @brief      Get the remote protection level configured in a GateMP instance
329  *
330  *  @return     GateMP_RemoteProtect corresponding to remote protection level
331  */
332 GateMP_RemoteProtect GateMP_getRemoteProtect(GateMP_Handle handle);
334 /*!
335  *  @brief      Open a created GateMP by name
336  *
337  *  @param[in]  name        Name of the GateMP instance
338  *  @param[out] handlePtr   Pointer to GateMP handle to be opened
339  *
340  *  @return     GateMP status:
341  *              - #GateMP_E_NOTFOUND: open failed (name not found on any
342  *                processor)
343  *              - #GateMP_E_FAIL: open failed (general failure occurred)
344  *              - #GateMP_S_SUCCESS: open successful
345  */
346 Int GateMP_open(String name, GateMP_Handle *handlePtr);
348 /*! @cond */
349 Int GateMP_openByAddr(Ptr sharedAddr, GateMP_Handle *handlePtr);
351 /*! @endcond */
353 /*!
354  *  @brief      Initialize a GateMP parameters struct
355  *
356  *  @param[out] params      Pointer to GateMP parameters
357  *
358  */
359 Void GateMP_Params_init(GateMP_Params *params);
361 /*! @cond */
362 /*!
363  *  @brief      Amount of shared memory required for creation of each instance
364  *
365  *  @param[in]  params      Pointer to the parameters that will be used in
366  *                          the create.
367  *
368  *  @return     Number of MAUs needed to create the instance.
369  */
370 SizeT GateMP_sharedMemReq(const GateMP_Params *params);
372 /*! @endcond */
374 /* =============================================================================
375  *  GateMP Per-instance Functions
376  * =============================================================================
377  */
379 /*!
380  *  @brief      Enter the GateMP
381  *
382  *  @param[in]  handle      GateMP handle
383  *
384  *  @return     key that must be used to leave the gate
385  */
386 IArg GateMP_enter(GateMP_Handle handle);
388 /*!
389  *  @brief      Leave the GateMP
390  *
391  *  @param[in]  handle      GateMP handle
392  *  @param[in]  key         key returned from GateMP_enter
393  */
394 Void GateMP_leave(GateMP_Handle handle, IArg key);
396 #if defined (__cplusplus)
398 #endif /* defined (__cplusplus) */
399 #endif /* ti_ipc_GateMP__include */