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     */
    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 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     */
    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_invalidClose: 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         *  ======== hostSupport ========
   288         *  Support for host processor
   289         */
   290        metaonly config Bool hostSupport = false;
   291    
   292        /*!
   293         *  ======== tableSection ========
   294         *  Section name is used to place the names table
   295         */
   296        metaonly config String tableSection = null;
   297    
   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;
   308    
   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;
   318    
   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;
   328    
   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);
   338    
   339        /*! @_nodoc
   340         *  ======== attach ========
   341         */
   342        Int attach(UInt16 remoteProcId, Ptr sharedAddr);
   343    
   344        /*! @_nodoc
   345         *  ======== detach ========
   346         */
   347        Int detach(UInt16 remoteProcId);
   348    
   349        /*!
   350         *  ======== getRegion0ReservedSize ========
   351         *  @_nodoc
   352         *  Amount of shared memory to be reserved for GateMP in region 0.
   353         */
   354        SizeT getRegion0ReservedSize();
   355    
   356        /*!
   357         *  ======== setRegion0Reserved ========
   358         *  @_nodoc
   359         *  Set and initialize GateMP reserved memory in Region 0.
   360         */
   361        Void setRegion0Reserved(Ptr sharedAddr);
   362    
   363        /*!
   364         *  ======== openRegion0Reserved ========
   365         *  @_nodoc
   366         *  Open shared memory reserved for GateMP in region 0.
   367         */
   368        Void openRegion0Reserved(Ptr sharedAddr);
   369    
   370        /*!
   371         *  ======== setDefaultRemote ========
   372         *  @_nodoc
   373         *  Set the default Remote Gate. Called by SharedRegion_start().
   374         */
   375         Void setDefaultRemote(Handle handle);
   376    
   377        /*! @_nodoc
   378         *  ======== start ========
   379         */
   380        Int start(Ptr sharedAddr);
   381    
   382        /*! @_nodoc
   383         *  ======== stop ========
   384         */
   385        Int stop();
   386    
   387    instance:
   388    
   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;
   397    
   398        /*! @_nodoc
   399         *  Set to true by the open() call. No one else should touch this!
   400         */
   401        config Bool openFlag = false;
   402    
   403        /*! @_nodoc
   404         *  Set by the open() call. No one else should touch this!
   405         */
   406        config Bits32 resourceId = 0;
   407    
   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;
   415    
   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;
   425    
   426        /*!
   427         *  ======== localProtect ========
   428         */
   429        config LocalProtect localProtect = LocalProtect_THREAD;
   430    
   431        /*!
   432         *  ======== localProtect ========
   433         */
   434        config RemoteProtect remoteProtect = RemoteProtect_SYSTEM;
   435    
   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();
   447    
   448    internal:
   449        const UInt32 VERSION = 1;
   450        const UInt32 CREATED = 0x11202009;
   451    
   452        const Int ProxyOrder_SYSTEM  = 0;
   453        const Int ProxyOrder_CUSTOM1 = 1;
   454        const Int ProxyOrder_CUSTOM2 = 2;
   455        const Int ProxyOrder_NUM     = 3;
   456    
   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;
   463    
   464        UInt getFreeResource(UInt8 *inUse, Int num, Error.Block *eb);
   465    
   466        struct LocalGate {
   467            IGateProvider.Handle    localGate;
   468            Int                     refCount;
   469        }
   470    
   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        };
   478    
   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        };
   493    
   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        };
   514    }