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