fb09a5656bb0be67bc43f29dcd6559cf0a33bb03
[ipc/ipcdev.git] / packages / ti / sdo / ipc / GateMP.xdc
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  *  ======== GateMP.xdc ========
34  *
35  */
37 package ti.sdo.ipc;
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;
45 import ti.sdo.utils.NameServer;
46 import ti.sdo.ipc.interfaces.IGateMPSupport;
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 &lt;ti/ipc/GateMP.h&gt;</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  */
74 @InstanceInitError
75 @InstanceFinalize
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     }
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     }
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         });
132     /*!
133      *  ======== Reserved space at the top of SharedRegion0 ========
134      */
135     struct Reserved {
136         Bits32  version;
137     };
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     };
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     };
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     };
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     };
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     };
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     };
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     };
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     };
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     };
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     };
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     };
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     };
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;
280     /*!
281      *  ======== maxNameLen ========
282      *  Maximum length for names
283      */
284     config UInt maxNameLen = 32;
286     /*!
287      *  ======== hostSupport ========
288      *  Support for host processor
289      */
290     metaonly config Bool hostSupport = false;
292     /*!
293      *  ======== tableSection ========
294      *  Section name is used to place the names table
295      */
296     metaonly config String tableSection = null;
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;
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;
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;
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);
339     /*! @_nodoc
340      *  ======== attach ========
341      */
342     Int attach(UInt16 remoteProcId, Ptr sharedAddr);
344     /*! @_nodoc
345      *  ======== detach ========
346      */
347     Int detach(UInt16 remoteProcId);
349     /*!
350      *  ======== getRegion0ReservedSize ========
351      *  @_nodoc
352      *  Amount of shared memory to be reserved for GateMP in region 0.
353      */
354     SizeT getRegion0ReservedSize();
356     /*!
357      *  ======== setRegion0Reserved ========
358      *  @_nodoc
359      *  Set and initialize GateMP reserved memory in Region 0.
360      */
361     Void setRegion0Reserved(Ptr sharedAddr);
363     /*!
364      *  ======== openRegion0Reserved ========
365      *  @_nodoc
366      *  Open shared memory reserved for GateMP in region 0.
367      */
368     Void openRegion0Reserved(Ptr sharedAddr);
370     /*!
371      *  ======== setDefaultRemote ========
372      *  @_nodoc
373      *  Set the default Remote Gate. Called by SharedRegion_start().
374      */
375      Void setDefaultRemote(Handle handle);
377     /*! @_nodoc
378      *  ======== start ========
379      */
380     Int start(Ptr sharedAddr);
382     /*! @_nodoc
383      *  ======== stop ========
384      */
385     Int stop();
387 instance:
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;
398     /*! @_nodoc
399      *  Set to true by the open() call. No one else should touch this!
400      */
401     config Bool openFlag = false;
403     /*! @_nodoc
404      *  Set by the open() call. No one else should touch this!
405      */
406     config Bits32 resourceId = 0;
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;
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;
426     /*!
427      *  ======== localProtect ========
428      */
429     config LocalProtect localProtect = LocalProtect_THREAD;
431     /*!
432      *  ======== localProtect ========
433      */
434     config RemoteProtect remoteProtect = RemoteProtect_SYSTEM;
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();
448 internal:
449     const UInt32 VERSION = 1;
450     const UInt32 CREATED = 0x11202009;
452     const Int ProxyOrder_SYSTEM  = 0;
453     const Int ProxyOrder_CUSTOM1 = 1;
454     const Int ProxyOrder_CUSTOM2 = 2;
455     const Int ProxyOrder_NUM     = 3;
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;
464     UInt getFreeResource(UInt8 *inUse, Int num, Error.Block *eb);
466     struct LocalGate {
467         IGateProvider.Handle    localGate;
468         Int                     refCount;
469     }
471     /* Structure of attributes in shared memory */
472     struct Attrs {
473         Bits16 mask;
474         Bits16 creatorProcId;
475         Bits32 arg;
476         Bits32 status;                  /* Created stamp                 */
477     };
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     };
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     };