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