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)
397 }
398 #endif /* defined (__cplusplus) */
399 #endif /* ti_ipc_GateMP__include */