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