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