1    /* 
     2     * Copyright (c) 2010, 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     */
    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 &lt;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 documenation</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_invalidContext: 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         *  ======== tableSection ========
   288         *  Section name is used to place the names table
   289         */
   290        metaonly config String tableSection = null;
   291            
   292        /*!
   293         *  ======== remoteSystemProxy ========     
   294         *  @_nodoc
   295         */
   296        proxy RemoteSystemProxy inherits IGateMPSupport;
   297        
   298        /*!
   299         *  ======== remoteCustom1Proxy ========     
   300         *  @_nodoc
   301         */
   302        proxy RemoteCustom1Proxy inherits IGateMPSupport;
   303        
   304        /*!
   305         *  ======== remoteCustom2Proxy ======== 
   306         *  @_nodoc     
   307         */
   308        proxy RemoteCustom2Proxy inherits IGateMPSupport;
   309        
   310        /*!
   311         *  ======== createLocal ========
   312         *  @_nodoc
   313         *  Get a local IGateProvider instance
   314         *
   315         *  This function is designed to be used by the IGateMPSupport modules
   316         *  to get a local Gate easily.
   317         */
   318        IGateProvider.Handle createLocal(LocalProtect localProtect);
   319    
   320        /*! @_nodoc
   321         *  ======== attach ========
   322         */
   323        Int attach(UInt16 remoteProcId, Ptr sharedAddr);
   324        
   325        /*!
   326         *  ======== getRegion0ReservedSize ========
   327         *  @_nodoc
   328         *  Amount of shared memory to be reserved for GateMP in region 0.
   329         */
   330        SizeT getRegion0ReservedSize();
   331    
   332        /*!
   333         *  ======== setRegion0Reserved ========
   334         *  @_nodoc
   335         *  Set and initialize GateMP reserved memory in Region 0.
   336         */
   337        Void setRegion0Reserved(Ptr sharedAddr);
   338    
   339        /*!
   340         *  ======== openRegion0Reserved ========
   341         *  @_nodoc
   342         *  Open shared memory reserved for GateP in region 0.
   343         */
   344        Void openRegion0Reserved(Ptr sharedAddr);
   345    
   346        /*!
   347         *  ======== setDefaultRemote ========
   348         *  @_nodoc
   349         *  Set the default Remote Gate. Called by SharedRegion_start().
   350         */
   351         Void setDefaultRemote(Handle handle);
   352         
   353        /*! @_nodoc
   354         *  ======== start ========
   355         */
   356        Int start(Ptr sharedAddr);
   357        
   358    instance: 
   359    
   360        /*!
   361         *  ======== name ========
   362         *  Name of the instance
   363         *
   364         *  Name needs to be unique. Used only if {@link #useNameServer}
   365         *  is set to TRUE.
   366         */
   367        config String name = null;
   368        
   369        /*! @_nodoc
   370         *  Set to true by the open() call. No one else should touch this!
   371         */
   372        config Bool openFlag = false;
   373            
   374        /*! @_nodoc
   375         *  Set by the open() call. No one else should touch this!
   376         */
   377        config Bits32 resourceId = 0;
   378    
   379        /*!
   380         *  Shared Region Id
   381         * 
   382         *  The ID corresponding to the shared region in which this shared instance
   383         *  is to be placed.
   384         */
   385        config UInt16 regionId = 0;
   386    
   387        /*!
   388         *  ======== sharedAddr ========
   389         *  Physical address of the shared memory
   390         *
   391         *  The creator must supply the shared memory that will be used
   392         *  for maintaining shared state information.  This parameter is used
   393         *  only when {@link #Type} is set to {@link #Type_SHARED}
   394         */
   395        config Ptr sharedAddr = null;
   396    
   397        /*! 
   398         *  ======== localProtect ========
   399         */
   400        config LocalProtect localProtect = LocalProtect_THREAD;
   401    
   402        /*! 
   403         *  ======== localProtect ========
   404         */
   405        config RemoteProtect remoteProtect = RemoteProtect_SYSTEM;
   406        
   407        /*!
   408         *  ======== getSharedAddr ========     
   409         *  @_nodoc
   410         *  Return the SRPtr that points to a GateMP instance's shared memory
   411         *
   412         *  getSharedAddr is typically used internally by other IPC modules to save
   413         *  the shared address to a GateMP instance in the other modules' shared
   414         *  state.  This allows the other module's open() call to open the GateMP
   415         *  instance by address.
   416         */
   417        SharedRegion.SRPtr getSharedAddr();
   418    
   419    internal:
   420        const UInt32 VERSION = 1;
   421        const UInt32 CREATED = 0x11202009;
   422    
   423        const Int ProxyOrder_SYSTEM  = 0;
   424        const Int ProxyOrder_CUSTOM1 = 1;
   425        const Int ProxyOrder_CUSTOM2 = 2;
   426        const Int ProxyOrder_NUM     = 3;
   427        
   428        /*! 
   429         *  ======== nameSrvPrms ========
   430         *  This Params object is used for temporary storage of the
   431         *  module wide parameters that are for setting the NameServer instance.
   432         */
   433        metaonly config NameServer.Params nameSrvPrms;
   434        
   435        UInt getFreeResource(UInt8 *inUse, Int num, Error.Block *eb);
   436        
   437        struct LocalGate {
   438            IGateProvider.Handle    localGate;
   439            Int                     refCount;
   440        }
   441      
   442        /* Structure of attributes in shared memory */
   443        struct Attrs {
   444            Bits16 mask; 
   445            Bits16 creatorProcId;        
   446            Bits32 arg;
   447            Bits32 status;                  /* Created stamp                 */
   448        };
   449    
   450        struct Instance_State {
   451            RemoteProtect           remoteProtect;
   452            LocalProtect            localProtect;
   453            Ptr                     nsKey;       
   454            Int                     numOpens;
   455            Bool                    cacheEnabled;
   456            Attrs                   *attrs;
   457            UInt16                  regionId;
   458            SizeT                   allocSize;
   459            Ipc.ObjType             objType;
   460            Ptr                     proxyAttrs;
   461            UInt                    resourceId;
   462            IGateProvider.Handle    gateHandle;    
   463        };
   464    
   465        struct Module_State {
   466            NameServer.Handle       nameServer;
   467            Int                     numRemoteSystem;
   468            Int                     numRemoteCustom1;
   469            Int                     numRemoteCustom2;        
   470            UInt8                   remoteSystemInUse[]; 
   471            UInt8                   remoteCustom1InUse[];
   472            UInt8                   remoteCustom2InUse[];
   473            Handle                  remoteSystemGates[]; 
   474            Handle                  remoteCustom1Gates[];
   475            Handle                  remoteCustom2Gates[];
   476            IGateProvider.Handle    gateAll;
   477            IGateProvider.Handle    gateSwi;
   478            IGateProvider.Handle    gateMutexPri;
   479            IGateProvider.Handle    gateNull;
   480            Handle                  defaultGate;
   481            Int                     proxyMap[ProxyOrder_NUM];
   482        };
   483    }
   484    /*
   485     *  @(#) ti.sdo.ipc; 1, 0, 0, 0,445; 8-10-2010 17:48:32; /db/vtree/library/trees/ipc/ipc-e23x/src/
   486     */
   487