src/ti/sdo/utils/NameServer.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  *  ======== NameServer.xdc ========
  34  *
  35  */
  36
  37 import xdc.runtime.Error;
  38 import xdc.runtime.Assert;
  39 import xdc.runtime.IHeap;
  40 import ti.sysbios.gates.GateSwi;
  41 import xdc.rov.ViewInfo;
  42
  43 /*!
  44  *  ======== NameServer ========
  45  *  Manages and serves names to remote/local processor
  46  *
  47  *  @p(html)
  48  *  This module has a common header that can be found in the {@link ti.ipc}
  49  *  package.  Application code should include the common header file (not the
  50  *  RTSC-generated one):
  51  *
  52  *  <PRE>#include &lt;ti/ipc/NameServer.h&gt;</PRE>
  53  *
  54  *  The RTSC module must be used in the application's RTSC configuration file
  55  *  (.cfg) if runtime APIs will be used in the application:
  56  *
  57  *  <PRE>NameServer = xdc.useModule('ti.sdo.ipc.NameServer');</PRE>
  58  *
  59  *  Documentation for all runtime APIs, instance configuration parameters,
  60  *  error codes macros and type definitions available to the application
  61  *  integrator can be found in the
  62  *  <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
  63  *  for the IPC product.  However, the documentation presented on this page
  64  *  should be referred to for information specific to the RTSC module, such as
  65  *  module configuration, Errors, and Asserts.
  66  *  @p
  67  *
  68  */
  69
  70 @ModuleStartup
  71 @InstanceInitError /* Initialization may throw errors */
  72 @InstanceFinalize
  73
  74 module NameServer
  75 {
  76     /*!
  77      *  ======== BasicView ========
  78      *  @_nodoc
  79      */
  80     metaonly struct BasicView {
  81         String  name;
  82         Bool    checkExisting;
  83         UInt    maxNameLen;
  84         UInt    maxValueLen;
  85         UInt    numStatic;
  86         String  numDynamic;
  87     }
  88
  89     /*!
  90      *  ======== NamesListView ========
  91      *  @_nodoc
  92      */
  93     metaonly struct NamesListView {
  94         String  name;
  95         String  value;
  96         UInt    len;
  97         Ptr     nsKey;
  98     }
  99
 100     /*!
 101      *  ======== rovViewInfo ========
 102      *  @_nodoc
 103      */
 104     @Facet
 105     metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
 106         xdc.rov.ViewInfo.create({
 107             viewMap: [
 108                 ['Basic',
 109                     {
 110                         type: xdc.rov.ViewInfo.INSTANCE,
 111                         viewInitFxn: 'viewInitBasic',
 112                         structName: 'BasicView'
 113                     }
 114                 ],
 115                 ['NamesValues',
 116                     {
 117                         type: xdc.rov.ViewInfo.INSTANCE_DATA,
 118                         viewInitFxn: 'viewInitData',
 119                         structName: 'NamesListView'
 120                     }
 121                 ]
 122             ]
 123         });
 124
 125     /*!
 126      *  Assert raised when the name or value is too long
 127      */
 128     config Assert.Id A_invalidLen  = {
 129         msg: "A_invalidLen: Invalid length"
 130     };
 131
 132     /*!
 133      *  ======== A_invArgument ========
 134      *  Assert raised when an argument is invalid
 135      */
 136     config Assert.Id A_invArgument  = {
 137         msg: "A_invArgument: Invalid argument supplied"
 138     };
 139
 140     /*!
 141      *  Error raised if all the entries in the instance Name/Value table
 142      *  are taken
 143      */
 144     config Error.Id E_maxReached  = {
 145         msg: "E_maxReached: All entries in use. NameServer.maxRuntimeEntries is %d"
 146     };
 147
 148     /*!
 149      *  Error raised when the name already exists in the instance
 150      *  Name/Value table
 151      */
 152     config Error.Id E_entryExists  = {
 153         msg: "E_entryExists: %s name already in table "
 154     };
 155
 156     /*!
 157      *  Allow dynamic growth of the NameServer instance table
 158      *
 159      *  This value can be used to set the {@link #maxRuntimeEntries}.
 160      *  This flag tells NameServer to allow dynamic growth
 161      *  of the table.
 162      */
 163     const UInt ALLOWGROWTH = (~0);
 164
 165     /*!
 166      *  Structure of entry in Name/Value table
 167      *
 168      *  This structure is returned from the {@link #getMeta}
 169      *  API.
 170      *
 171      *  @field(name)  Name portion of the name/value pair.
 172      *  @field(len)   Length of the value field.
 173      *  @field(value) Value portion of the name/value entry.
 174      */
 175     metaonly struct Entry {
 176         String      name;
 177         UInt        len;
 178         UArg        value;
 179     };
 180
 181     /*!
 182      *  ======== SetupProxy ========
 183      *  NameServer setup proxy
 184      */
 185     proxy SetupProxy inherits INameServerRemote;
 186
 187     /*!
 188      *  ======== isRegistered ========
 189      *  Determines if a remote driver is registered for the specified id.
 190      *
 191      *  @param(procId)  The remote processor id.
 192      */
 193     @DirectCall
 194     Bool isRegistered(UInt16 procId);
 195
 196     /*!
 197      *  ======== registerRemoteDriver ========
 198      *  Register the NameServer remote handle for the specified processor id.
 199      *
 200      *  This function is used by NameServer remote driver to register
 201      *  themselves with NameServer. Only one remote driver can be registered
 202      *  with a remote processor. The API returns {@link #Status_FAIL} if there
 203      *  is already a registered remote driver for the processor id.
 204      *
 205      *  @param(handle)  The handle for a NameServer remote driver instance.
 206      *  @param(procId)  The remote processor id.
 207      *
 208      *  @b(returns)     Returns {@link #Status_SUCCESS} if successful or
 209      *                  {@link #Status_FAIL} if the processor id has already
 210      *                  been set.
 211      */
 212     @DirectCall
 213     Int registerRemoteDriver(INameServerRemote.Handle handle, UInt16 procId);
 214
 215     /*!
 216      *  ======== unregisterRemoteDriver ========
 217      *  Unregister the NameServer remote handle for the specified processor id.
 218      *
 219      *  This function is used by NameServer Remote implementations to unregister
 220      *  themselves with NameServer.
 221      *
 222      *  @param(procId)  The remote processor id to unregister.
 223      */
 224     @DirectCall
 225     Void unregisterRemoteDriver(UInt16 procId);
 226
 227     /*!
 228      *  ======== modAddMeta ========
 229      *  Add a name/value pair into the specified instance's table during
 230      *  configuration
 231      *
 232      *  This function adds any length value into the local table. The function
 233      *  makes sure the name does not already exist in the local table.
 234      *
 235      *  This function should be used by modules when adding into a NameServer
 236      *  instance. The application configuration file, should
 237      *  use {@link #addMeta}.
 238      *
 239      *  The function does not query remote processors to make sure the
 240      *  name is unique.
 241      *
 242      *  @param(instName)   NameServer instance name
 243      *  @param(name)       Name portion of the name/value pair
 244      *  @param(value)      Value portion of the name/value pair
 245      *  @param(len)        Length of the value buffer
 246      */
 247     metaonly Void modAddMeta(String instName, String name, Any value, UInt len);
 248
 249     /*!
 250      *  ======== getName$view ========
 251      *  @_nodoc
 252      *  Used at ROV time to display reverse-lookup name from 32-bit value and
 253      *  tableName
 254      */
 255     metaonly String getName$view(String tableName, UInt32 value);
 256
 257     /*!
 258      *  ======== getNameByKey$view ========
 259      *  @_nodoc
 260      *  ROV function for retrieving an entry by its address. Throws an exception
 261      *  if the name was not found
 262      */
 263     metaonly String getNameByKey$view(Ptr addr);
 264
 265
 266 instance:
 267
 268     /*!
 269      *  Maximum number of name/value pairs that can be dynamically created.
 270      *
 271      *  This parameter allows NameServer to pre-allocate memory.
 272      *  When NameServer_add or NameServer_addUInt32 is called, no memory
 273      *  allocation occurs.
 274      *
 275      *  If the number of pairs is not known at configuration time, set this
 276      *  value to {@link #ALLOWGROWTH}. This instructs NameServer to grow the
 277      *  table as needed. NameServer will allocate memory from the
 278      *  {@link #tableHeap} when a name/value pair is added.
 279      *
 280      *  The default is {@link #ALLOWGROWTH}.
 281      */
 282     config UInt maxRuntimeEntries = ALLOWGROWTH;
 283
 284     /*!
 285      *  Name/value table is allocated from this heap.
 286      *
 287      *  The instance table and related buffers are allocated out of this heap
 288      *  during the dynamic create. This heap is also used to allocate new
 289      *  name/value pairs when {@link #ALLOWGROWTH} for
 290      *  {@link #maxRuntimeEntries}
 291      *
 292      *  The default is to use the same heap that instances are allocated
 293      *  from which can be configured via the
 294      *  NameServer.common$.instanceHeap configuration parameter.
 295      */
 296     config IHeap.Handle tableHeap = null;
 297
 298     /*!
 299      *  Name/value table is placed into this section on static creates.
 300      *
 301      *  The instance table and related buffers are placed into this section
 302      *  during the static create.
 303      *
 304      *  The default is no explicit section placement.
 305      */
 306     metaonly config String tableSection = null;
 307
 308     /*!
 309      *  Check if a name already exists in the name/value table.
 310      *
 311      *  When a name/value pair is added during runtime, if this boolean is true,
 312      *  the table is searched to see if the name already exists. If it does,
 313      *  the name is not added and the {@link #E_entryExists} error is raised.
 314      *
 315      *  If this flag is false, the table will not be checked to see if the name
 316      *  already exists. It will simply be added. This mode has better
 317      *  performance at the expense of potentially having non-unique names in the
 318      *  table.
 319      *
 320      *  This flag is used for runtime adds only. Adding non-unique names during
 321      *  configuration results in a build error.
 322      */
 323     config Bool checkExisting = true;
 324
 325     /*!
 326      *  Length, in MAUs, of the value field in the table.
 327      *
 328      *  Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32).
 329      */
 330     config UInt maxValueLen = 0;
 331
 332     /*!
 333      *  Length, in MAUs, of the name field in the table.
 334      *
 335      *  The maximum length of the name portion of the name/value
 336      *  pair. The length includes the null terminator ('\0').
 337      */
 338     config UInt maxNameLen = 16;
 339
 340     /*!
 341      *  ======== metaTable ========
 342      *  @_nodoc
 343      *  Table to hold the statically added name/value pairs until
 344      *  they ready to be added to the object.
 345      */
 346     metaonly config Entry metaTable[];
 347
 348    /*!
 349      *  ======== create ========
 350      *  @_nodoc (Refer to doxygen for ti/ipc/NameServer.h)
 351      *  Create a NameServer instance
 352      *
 353      *  This function creates a NameServer instance. The name is
 354      *  used for remote processor queries and diagnostic tools. For
 355      *  single processor system (e.g. no remote queries), the name
 356      *  can be NULL.
 357      *
 358      *  @param(name)    Name of the instance
 359      */
 360     create(String name);
 361
 362     /*!
 363      *  ======== addUInt32Meta ========
 364      *  Add a name/value pair into the instance's table during configuration
 365      *
 366      *  This function adds a UInt32 value into the local table. The function
 367      *  makes sure the name does not already exist in the local table.
 368      *
 369      *  The function does not query remote processors to make sure the
 370      *  name is unique.
 371      *
 372      *  @param(name)   Name portion of the name/value pair
 373      *  @param(value)  Value portion of the name/value pair
 374      */
 375     metaonly Void addUInt32Meta(String name, any value);
 376
 377     /*!
 378      *  ======== addMeta ========
 379      *  Add a name/value pair into the instance's table during configuration
 380      *
 381      *  This function adds any length value into the local table. The function
 382      *  makes sure the name does not already exist in the local table.
 383      *
 384      *  This function should be used by within the application configuration
 385      *  file. XDC modules should use {@link #modAddMeta}.
 386      *
 387      *  The function does not query remote processors to make sure the
 388      *  name is unique.
 389      *
 390      *  @param(name)   Name portion of the name/value pair
 391      *  @param(value)  Value portion of the name/value pair
 392      *  @param(len)    Length of the value buffer
 393      */
 394     metaonly Void addMeta(String name, Any value, UInt len);
 395
 396     /*!
 397      *  ======== getMeta ========
 398      *  Retrieves the name/value entry
 399      *
 400      *  If the name is found, the entry is returned. The caller can parse the
 401      *  entry as needed. If the name is not found, null is returned.
 402      *
 403      *  The search only occurs on the local table.
 404      *
 405      *  @param(name)     Name in question
 406      *
 407      *  @b(returns)      Name/value entry
 408      */
 409     metaonly Entry getMeta(String name);
 410
 411     /*!
 412      *  ======== getKey ========
 413      *  @_nodoc
 414      *  Returns a pointer to the TableEntry containing the argument 'val'.
 415      *  This should only be used internally by Ipc modules during their
 416      *  initialization process.
 417      *
 418      *  This function can only be used when maxValueLen = sizeof(UInt32)
 419      */
 420     @DirectCall
 421     Ptr getKey(UInt32 val);
 422
 423 internal:
 424
 425     /* Used to eliminate code when doing whole-program */
 426     config Bool singleProcessor = true;
 427
 428     metaonly typedef Entry EntryMap[];
 429
 430     /*! Structure of entry in Name/Value table */
 431     struct TableEntry {
 432         List.Elem   elem;
 433         String      name;
 434         UInt        len;
 435         UArg        value;
 436     };
 437
 438     /*!
 439      *  ======== metaModTable ========
 440      *  Table to hold the static added name/value pairs until
 441      *  they ready to be added to the object.
 442      */
 443     metaonly config EntryMap metaModTable[string];
 444
 445     /*
 446      *  ======== postInit ========
 447      *  Finish initializing static and dynamic NameServer instances
 448      */
 449     Int postInit(Object *obj);
 450
 451     /*
 452      *  ======== findLocal ========
 453      *  Searches to the local instance table.
 454      *
 455      *  This is an internal function because it returns an internal structure.
 456      */
 457     TableEntry *findLocal(Object *obj, String name);
 458
 459     /*
 460      *  ======== removeLocal ========
 461      *  removes an entry from the local instance table.
 462      */
 463     Void removeLocal(Object *obj, TableEntry *entry);
 464
 465     /*
 466      *  ======== editLocal ========
 467      *  replaces the value of an entry from the local instance table.
 468      */
 469     Void editLocal(Object *obj, TableEntry *entry, Ptr newValue);
 470
 471     /* instance object */
 472     struct Instance_State {
 473         String       name;           /* Name of the instance           */
 474         List.Object  freeList;       /* Empty entries list             */
 475         List.Object  nameList;       /* Filled entries list            */
 476         UInt         maxNameLen;     /* Max name length                */
 477         UInt         maxValueLen;    /* Max value length               */
 478         UInt         numStatic;      /* Total static entries in table  */
 479         UInt         numDynamic;     /* Total dynamic entries in table */
 480         TableEntry   table[];        /* Table                          */
 481         Char         names[];        /* Buffer for names               */
 482         UInt8        values[];       /* Buffer for values              */
 483         IHeap.Handle tableHeap;      /* Heap used to alloc table       */
 484         Bool         checkExisting;  /* check ig name already exists   */
 485     };
 486
 487     struct Module_State {
 488         INameServerRemote.Handle nsRemoteHandle[];
 489         GateSwi.Handle gate;
 490     };
 491 }