1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 34 35 36 37 38 39 40 41 42 43 44
45
46 package ti.sdo.ipc;
47
48 import xdc.runtime.Error;
49 import xdc.runtime.Assert;
50 import xdc.runtime.IGateProvider;
51 import xdc.runtime.Log;
52 import xdc.runtime.Diags;
53
54 import ti.sdo.utils.NameServer;
55 import ti.sdo.ipc.interfaces.IGateMPSupport;
56
57 /*!
58 * ======== GateMP ========
59 * Multiple processor gate that provides local and remote context protection.
60 *
61 * @p(html)
62 * This module has a common header that can be found in the {@link ti.ipc}
63 * package. Application code should include the common header file (not the
64 * RTSC-generated one):
65 *
66 * <PRE>#include <ti/ipc/GateMP.h></PRE>
67 *
68 * The RTSC module must be used in the application's RTSC configuration file
69 * (.cfg) if runtime APIs will be used in the application:
70 *
71 * <PRE>GateMP = xdc.useModule('ti.sdo.ipc.GateMP');</PRE>
72 *
73 * Documentation for all runtime APIs, instance configuration parameters,
74 * error codes macros and type definitions available to the application
75 * integrator can be found in the
76 * <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
77 * for the IPC product. However, the documentation presented on this page
78 * should be referred to for information specific to the RTSC module, such as
79 * module configuration, Errors, and Asserts.
80 * @p
81 */
82
83 @InstanceInitError
84 @InstanceFinalize
85
86 module GateMP
87 {
88 /*!
89 * ======== BasicView ========
90 * @_nodoc
91 */
92 metaonly struct BasicView {
93 String name;
94 String remoteProtect;
95 String remoteStatus;
96 String localProtect;
97 UInt numOpens;
98 Bits32 resourceId;
99 UInt creatorProcId;
100 String objType;
101 }
102
103 /*!
104 * ======== ModuleView ========
105 * @_nodoc
106 */
107 metaonly struct ModuleView {
108 UInt numGatesSystem;
109 UInt numUsedSystem;
110 UInt numGatesCustom1;
111 UInt numUsedCustom1;
112 UInt numGatesCustom2;
113 UInt numUsedCustom2;
114 }
115
116 /*!
117 * ======== rovViewInfo ========
118 * @_nodoc
119 */
120 @Facet
121 metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
122 xdc.rov.ViewInfo.create({
123 viewMap: [
124 ['Basic',
125 {
126 type: xdc.rov.ViewInfo.INSTANCE,
127 viewInitFxn: 'viewInitBasic',
128 structName: 'BasicView'
129 }
130 ],
131 ['Gate Resources',
132 {
133 type: xdc.rov.ViewInfo.MODULE,
134 viewInitFxn: 'viewInitModule',
135 structName: 'ModuleView'
136 }
137 ]
138 ]
139 });
140
141 /*!
142 * ======== Reserved space at the top of SharedRegion0 ========
143 */
144 struct Reserved {
145 Bits32 version;
146 };
147
148 /*!
149 * ======== E_gateUnavailable ========
150 * Error raised no gates of the requested type are available
151 */
152 config Error.Id E_gateUnavailable = {
153 msg: "E_gateUnavailable: No gates of requested type are available"
154 };
155
156 /*!
157 * ======== E_localGate ========
158 * Error raised when remote side tried to open local gate
159 */
160 config Error.Id E_localGate = {
161 msg: "E_localGate: Only creator can open local Gate"
162 };
163
164 /*!
165 * Assert raised when calling GateMP_close with the wrong handle
166 */
167 config Assert.Id A_invalidClose = {
168 msg: "A_invalidContext: Calling GateMP_close with the wrong handle"
169 };
170
171 /*!
172 * Assert raised when calling GateMP_delete incorrectly
173 */
174 config Assert.Id A_invalidDelete = {
175 msg: "A_invalidDelete: Calling GateMP_delete incorrectly"
176 };
177
178 /*!
179 * ======== LM_enter ========
180 * Logged on gate enter
181 */
182 config Log.Event LM_enter = {
183 mask: Diags.USER1,
184 msg: "LM_enter: Gate (remoteGate = %d, resourceId = %d) entered, returning key = %d"
185 };
186
187 /*!
188 * ======== LM_leave ========
189 * Logged on gate leave
190 */
191 config Log.Event LM_leave = {
192 mask: Diags.USER1,
193 msg: "LM_leave: Gate (remoteGate = %d, resourceId = %d) left using key = %d"
194 };
195
196 /*!
197 * ======== LM_create ========
198 * Logged on gate create
199 */
200 config Log.Event LM_create = {
201 mask: Diags.USER1,
202 msg: "LM_create: Gate (remoteGate = %d, resourceId = %d) created"
203 };
204
205 /*!
206 * ======== LM_open ========
207 * Logged on gate open
208 */
209 config Log.Event LM_open = {
210 mask: Diags.USER1,
211 msg: "LM_open: Remote gate (remoteGate = %d, resourceId = %d) opened"
212 };
213
214 /*!
215 * ======== LM_delete ========
216 * Logged on gate deletion
217 */
218 config Log.Event LM_delete = {
219 mask: Diags.USER1,
220 msg: "LM_delete: Gate (remoteGate = %d, resourceId = %d) deleted"
221 };
222
223 /*!
224 * ======== LM_close ========
225 * Logged on gate close
226 */
227 config Log.Event LM_close = {
228 mask: Diags.USER1,
229 msg: "LM_close: Gate (remoteGate = %d, resourceId = %d) closed"
230 };
231
232 /*!
233 * A set of local context protection levels
234 *
235 * Each member corresponds to a specific local processor gates used for
236 * local protection.
237 *
238 * For SYS/BIOS users, the following are the mappings for the constants
239 * @p(blist)
240 * -INTERRUPT -> GateAll: disables interrupts
241 * -TASKLET -> GateSwi: disables Swis (software interrupts)
242 * -THREAD -> GateMutexPri: based on Semaphores
243 * -PROCESS -> GateMutexPri: based on Semaphores
244 * @p
245 */
246 enum LocalProtect {
247 LocalProtect_NONE = 0,
248 LocalProtect_INTERRUPT = 1,
249 LocalProtect_TASKLET = 2,
250 LocalProtect_THREAD = 3,
251 LocalProtect_PROCESS = 4
252 };
253
254 /*!
255 * Type of remote Gate
256 *
257 * Each member corresponds to a specific type of remote gate.
258 * Each enum value corresponds to the following remote protection levels:
259 * @p(blist)
260 * -NONE -> No remote protection (the GateMP instance will exclusively
261 * offer local protection configured in {@link #localProtect})
262 * -SYSTEM -> Use the SYSTEM remote protection level (default for remote
263 * protection
264 * -CUSTOM1 -> Use the CUSTOM1 remote protection level
265 * -CUSTOM2 -> Use the CUSTOM2 remote protection level
266 * @p
267 */
268 enum RemoteProtect {
269 RemoteProtect_NONE = 0,
270 RemoteProtect_SYSTEM = 1,
271 RemoteProtect_CUSTOM1 = 2,
272 RemoteProtect_CUSTOM2 = 3
273 };
274
275 /*!
276 * ======== maxRuntimeEntries ========
277 * Maximum runtime entries
278 *
279 * Maximum number of GateMP's that can be dynamically created and
280 * added to the NameServer.
281 *
282 * To minimize the amount of runtime allocation, this parameter allows
283 * the pre-allocation of memory for the GateMP's NameServer table.
284 * The default is to allow growth (i.e. memory allocation when
285 * creating a new instance).
286 */
287 metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
288
289 /*!
290 * ======== maxNameLen ========
291 * Maximum length for names
292 */
293 config UInt maxNameLen = 32;
294
295 /*!
296 * ======== tableSection ========
297 * Section name is used to place the names table
298 */
299 metaonly config String tableSection = null;
300
301 /*!
302 * ======== remoteSystemProxy ========
303 * System remote gate proxy
304 *
305 * By default, GateMP instances use the 'System' proxy for locking between
306 * multiple processors by setting the 'localProtect' setting to . This
307 * remote gate proxy defaults to a device-specific remote GateMP delegate
308 * and typically should not be modified.
309 */
310 proxy RemoteSystemProxy inherits IGateMPSupport;
311
312 /*!
313 * ======== remoteCustom1Proxy ========
314 * Custom1 remote gate proxy
315 *
316 * GateMP instances may use the 'Custom1' proxy for locking between
317 * multiple processors. This proxy defaults to
318 * {@link ti.sdo.ipc.gates.GatePeterson}.
319 */
320 proxy RemoteCustom1Proxy inherits IGateMPSupport;
321
322 /*!
323 * ======== remoteCustom2Proxy ========
324 * Custom2 remote gate proxy
325 *
326 * GateMP instances may use the 'Custom2' proxy for locking between
327 * multiple processors. This proxy defaults to
328 * {@link ti.sdo.ipc.gates.GateMPSupportNull}.
329 */
330 proxy RemoteCustom2Proxy inherits IGateMPSupport;
331
332 /*!
333 * ======== createLocal ========
334 * @_nodoc
335 * Get a local IGateProvider instance
336 *
337 * This function is designed to be used by the IGateMPSupport modules
338 * to get a local Gate easily.
339 */
340 IGateProvider.Handle createLocal(LocalProtect localProtect);
341
342 /*! @_nodoc
343 * ======== attach ========
344 */
345 Int attach(UInt16 remoteProcId, Ptr sharedAddr);
346
347 /*!
348 * ======== getRegion0ReservedSize ========
349 * @_nodoc
350 * Amount of shared memory to be reserved for GateMP in region 0.
351 */
352 SizeT getRegion0ReservedSize();
353
354 /*!
355 * ======== setRegion0Reserved ========
356 * @_nodoc
357 * Set and initialize GateMP reserved memory in Region 0.
358 */
359 Void setRegion0Reserved(Ptr sharedAddr);
360
361 /*!
362 * ======== openRegion0Reserved ========
363 * @_nodoc
364 * Open shared memory reserved for GateP in region 0.
365 */
366 Void openRegion0Reserved(Ptr sharedAddr);
367
368 /*!
369 * ======== setDefaultRemote ========
370 * @_nodoc
371 * Set the default Remote Gate. Called by SharedRegion_start().
372 */
373 Void setDefaultRemote(Handle handle);
374
375 /*! @_nodoc
376 * ======== start ========
377 */
378 Int start(Ptr sharedAddr);
379
380 instance:
381
382 /*!
383 * ======== name ========
384 * Name of the instance
385 *
386 * Name needs to be unique. Used only if {@link #useNameServer}
387 * is set to TRUE.
388 */
389 config String name = null;
390
391 /*! @_nodoc
392 * Set to true by the open() call. No one else should touch this!
393 */
394 config Bool openFlag = false;
395
396 /*! @_nodoc
397 * Set by the open() call. No one else should touch this!
398 */
399 config Bits32 resourceId = 0;
400
401 /*!
402 * Shared Region Id
403 *
404 * The ID corresponding to the shared region in which this shared instance
405 * is to be placed.
406 */
407 config UInt16 regionId = 0;
408
409 /*!
410 * ======== sharedAddr ========
411 * Physical address of the shared memory
412 *
413 * The creator must supply the shared memory that will be used
414 * for maintaining shared state information. This parameter is used
415 * only when {@link #Type} is set to {@link #Type_SHARED}
416 */
417 config Ptr sharedAddr = null;
418
419 /*!
420 * ======== localProtect ========
421 */
422 config LocalProtect localProtect = LocalProtect_THREAD;
423
424 /*!
425 * ======== localProtect ========
426 */
427 config RemoteProtect remoteProtect = RemoteProtect_SYSTEM;
428
429 /*!
430 * ======== getSharedAddr ========
431 * @_nodoc
432 * Return the SRPtr that points to a GateMP instance's shared memory
433 *
434 * getSharedAddr is typically used internally by other IPC modules to save
435 * the shared address to a GateMP instance in the other modules' shared
436 * state. This allows the other module's open() call to open the GateMP
437 * instance by address.
438 */
439 SharedRegion.SRPtr getSharedAddr();
440
441 internal:
442 const UInt32 VERSION = 1;
443 const UInt32 CREATED = 0x11202009;
444
445 const Int ProxyOrder_SYSTEM = 0;
446 const Int ProxyOrder_CUSTOM1 = 1;
447 const Int ProxyOrder_CUSTOM2 = 2;
448 const Int ProxyOrder_NUM = 3;
449
450 /*!
451 * ======== nameSrvPrms ========
452 * This Params object is used for temporary storage of the
453 * module wide parameters that are for setting the NameServer instance.
454 */
455 metaonly config NameServer.Params nameSrvPrms;
456
457 UInt getFreeResource(UInt8 *inUse, Int num, Error.Block *eb);
458
459 struct LocalGate {
460 IGateProvider.Handle localGate;
461 Int refCount;
462 }
463
464
465 struct Attrs {
466 Bits16 mask;
467 Bits16 creatorProcId;
468 Bits32 arg;
469 Bits32 status;
470 };
471
472 struct Instance_State {
473 RemoteProtect remoteProtect;
474 LocalProtect localProtect;
475 Ptr nsKey;
476 Int numOpens;
477 Bool cacheEnabled;
478 Attrs *attrs;
479 UInt16 regionId;
480 SizeT allocSize;
481 Ipc.ObjType objType;
482 Ptr proxyAttrs;
483 UInt resourceId;
484 IGateProvider.Handle gateHandle;
485 };
486
487 struct Module_State {
488 NameServer.Handle nameServer;
489 Int numRemoteSystem;
490 Int numRemoteCustom1;
491 Int numRemoteCustom2;
492 UInt8 remoteSystemInUse[];
493 UInt8 remoteCustom1InUse[];
494 UInt8 remoteCustom2InUse[];
495 Handle remoteSystemGates[];
496 Handle remoteCustom1Gates[];
497 Handle remoteCustom2Gates[];
498 IGateProvider.Handle gateAll;
499 IGateProvider.Handle gateSwi;
500 IGateProvider.Handle gateMutexPri;
501 IGateProvider.Handle gateNull;
502 Handle defaultGate;
503 Int proxyMap[ProxyOrder_NUM];
504 };
505 }