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