packages/ti/sdo/ipc/ListMP.xdc

   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 }