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