1    /* --COPYRIGHT--,TI
     2     * Copyright (c) $(CPYYEAR)
     3     * Texas Instruments
     4     *
     5     *  All rights reserved.  Property of Texas Instruments
     6     *  Restricted rights to use, duplicate or disclose this code are
     7     *  granted through contract.
     8     * 
     9     * --/COPYRIGHT--*/
    10    /*
    11     *  ======== GateMP.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     *! 11-Feb-2010 skp     Added Module-wide ROV view
    16     *! 14-Dec-2009 skp     Added ROV views
    17     *! 20-Nov-2009 jv      Added CREATED stamp and status field in Attrs.
    18     *! 24-Oct-2009 skp     cdoc revisions, getAddr changed to getSharedAddr
    19     *! 11-Aug-2009 toddm   created
    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 &lt;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        /* Structure of attributes in shared memory */
   428        struct Attrs {
   429            Bits16 mask; 
   430            Bits16 creatorProcId;        
   431            Bits32 arg;
   432            Bits32 status;                  /* Created stamp                 */
   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    }