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     *  ======== ListMP.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     *! 12-Feb-2009 skp     SDOCM00066723 (Remove 'version' field from Attrs)
    16     *! 22-Jan-2010 jv      Addec cacheLineSize to instance to reduce calls to SR.
    17     *! 29-Sep-2009 jv      remove cacheFlag from params and Attrs.
    18     *!                     collapse ListMP and remove proxys.
    19     *! 20-Mar-2009 jv      remove unneeded functions. Support NS key.
    20     *! 13-Mar-2009 jv      Add proxy support for Fast Hw Queues
    21     *! 10-Feb-2009 jv      Add cacheFlag, add size to Elem, add sharedCreate()
    22     *! 15-Jan-2009 jv      Remove Error id from here and put in Ipc Module.
    23     *! 02-May-2008 nitya   created
    24     */
    25     
    26    import xdc.runtime.Error;
    27    import ti.sdo.utils.NameServer;
    28    
    29    /*!
    30     *  ======== ListMP ========
    31     *  Shared memory linked list
    32     *
    33     *  @p(html)
    34     *  This module has a common header that can be found in the {@link ti.ipc}
    35     *  package.  Application code should include the common header file (not the 
    36     *  RTSC-generated one):
    37     *
    38     *  <PRE>#include &lt;ti/ipc/ListMP.h></PRE>
    39     *   
    40     *  The RTSC module must be used in the application's RTSC configuration file 
    41     *  (.cfg):
    42     *  
    43     *  <PRE>ListMP = xdc.useModule('ti.sdo.ipc.ListMP');</PRE>
    44     *
    45     *  Documentation for all runtime APIs, instance configuration parameters, 
    46     *  error codes macros and type definitions available to the application 
    47     *  integrator can be found in the 
    48     *  <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
    49     *  for the IPC product.  However, the documentation presented on this page 
    50     *  should be referred to for information specific to the RTSC module, such as
    51     *  module configuration, Errors, and Asserts.
    52     *  @p
    53     */
    54    @InstanceInitError /* Initialization may throw errors */
    55    @InstanceFinalize
    56    
    57    module ListMP
    58    {
    59        /*!
    60         *  ======== BasicView ========
    61         *  @_nodoc
    62         *  ROV view structure representing a ListMP instance.
    63         */
    64        metaonly struct BasicView {
    65            String      label;
    66            String      type;
    67            String      gate;
    68        }
    69        
    70        /*! 
    71         *  ======== ElemView ========
    72         *  @_nodoc
    73         *  ROV view structure representing a single list element.
    74         */
    75        metaonly struct ElemView {
    76            Int        index;
    77            String     srPtr;
    78            String     addr;
    79        }
    80        
    81        /*!
    82         *  ======== rovViewInfo ========
    83         *  @_nodoc
    84         */
    85        @Facet
    86        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo = 
    87            xdc.rov.ViewInfo.create({
    88                viewMap: [
    89                    ['Basic',
    90                        {
    91                            type: xdc.rov.ViewInfo.INSTANCE,
    92                            viewInitFxn: 'viewInitBasic',
    93                            structName: 'BasicView'
    94                        }
    95                    ],
    96                    ['Lists', 
    97                        {
    98                            type: xdc.rov.ViewInfo.INSTANCE_DATA,
    99                            viewInitFxn: 'viewInitLists',
   100                            structName: 'ElemView'
   101                        }
   102                    ],
   103                ]
   104            });
   105    
   106        /*! 
   107         *  ======== maxRuntimeEntries ========
   108         *  Maximum number of ListMP's that can be dynamically created
   109         *  and added to the NameServer.
   110         */
   111        metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH; 
   112    
   113        /*!
   114         *  ======== maxNameLen ========
   115         *  Maximum length for names.
   116         */
   117        metaonly config UInt maxNameLen = 32;
   118    
   119        /*!
   120         *  ======== tableSection ========
   121         *  Section name is used to place the names table
   122         */
   123        metaonly config String tableSection = null;
   124        
   125    
   126    instance:
   127    
   128        /*! 
   129         *  ======== gate ========
   130         *  GateMP used for critical region management of the shared memory 
   131         *
   132         *  Using the default value of NULL will result in the default GateMP
   133         *  being used for context protection.
   134         */
   135        config GateMP.Handle gate = null; 
   136        
   137        /*! @_nodoc
   138         *  ======== openFlag ========
   139         *  Set to 'true' by the {@link #open}.
   140         */
   141        config Bool openFlag = false;
   142    
   143        /*! @_nodoc
   144         *  ======== sharedAddr ========
   145         *  Physical address of the shared memory
   146         *
   147         *  The shared memory that will be used for maintaining shared state
   148         *  information.  This is an optional parameter to create.  If value
   149         *  is null, then the shared memory for the new instance will be
   150         *  allocated from the heap in {@link #regionId}.
   151         */
   152        config Ptr sharedAddr = null;
   153        
   154        /*!
   155         *  ======== name ========
   156         *  Name of the instance
   157         *
   158         *  The name must be unique among all ListMP instances in the sytem.
   159         *  When using {@link regionId} to create a new instance, the name must
   160         *  not be null.
   161         */
   162        config String name = null;
   163        
   164        /*! 
   165         *  ======== regionId ========
   166         *  SharedRegion ID.
   167         *
   168         *  The ID corresponding to the index of the shared region in which this
   169         *  shared instance is to be placed.  This is used in create() only when
   170         *  {@link #name} is not null.
   171         */
   172        config UInt16 regionId = 0;
   173    
   174        /*! @_nodoc
   175         *  ======== metaListMP ========
   176         *  Used to store elem before the object is initialized.
   177         */
   178        metaonly config any metaListMP[];
   179        
   180    
   181    internal:    /* not for client use */
   182    
   183        const UInt32 CREATED = 0x12181964;
   184    
   185        /*!
   186         *  ======== Elem ========
   187         *  Opaque ListMP element
   188         *
   189         *  A field of this type must be placed at the head of client structs.
   190         */
   191        @Opaque struct Elem {
   192            volatile SharedRegion.SRPtr next;       /* volatile for whole_program */
   193            volatile SharedRegion.SRPtr prev;       /* volatile for whole_program */
   194        };
   195    
   196        
   197        /*!
   198         *  ======== nameSrvPrms ========
   199         *  This Params object is used for temporary storage of the
   200         *  module wide parameters that are for setting the NameServer instance.
   201         */
   202        metaonly config NameServer.Params nameSrvPrms;
   203        
   204        /*!
   205         *  ======== elemClear ========
   206         *  Clears a ListMP element's pointers
   207         *
   208         *  This API is not for removing elements from a ListMP, and
   209         *  should never be called on an element in a ListMP--only on deListed
   210         *  elements.
   211         *
   212         *  @param(elem)    element to be cleared
   213         */
   214        Void elemClear(Elem *elem);
   215        
   216        /* Initialize shared memory */
   217        Void postInit(Object *obj, Error.Block *eb);
   218    
   219        /*! Structure of attributes in shared memory */    
   220        struct Attrs {
   221            Bits32              status;     /* Created stamp                 */
   222            SharedRegion.SRPtr  gateMPAddr; /* GateMP SRPtr (shm safe)       */
   223            Elem                head;       /* head of list                  */
   224        };
   225        
   226        /* instance object */
   227        struct Instance_State {
   228            Attrs           *attrs;         /* local pointer to attrs        */
   229            Ptr             nsKey;          /* for removing NS entry         */
   230            Ipc.ObjType     objType;        /* Static/Dynamic? open/creator? */
   231            GateMP.Handle   gate;           /* Gate for critical regions     */
   232            SizeT           allocSize;      /* Shared memory allocated       */
   233            UInt16          regionId;       /* SharedRegion ID               */
   234            Bool            cacheEnabled;   /* Whether to do cache calls     */
   235            SizeT           cacheLineSize;  /* The region cache line size    */
   236        };
   237    
   238        /* module object */
   239        struct Module_State {
   240            NameServer.Handle nameServer;
   241        };
   242    }