1    /* 
     2     * Copyright (c) 2010, 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></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         *  Error raised if all the entries in the instance Name/Value table
   134         *  are taken
   135         */
   136        config Error.Id E_maxReached  = {
   137            msg: "E_maxReached: All entries in use. NameServer.maxRuntimeEntries is %d"
   138        };
   139    
   140        /*!
   141         *  Error raised when the name already exists in the instance
   142         *  Name/Value table
   143         */
   144        config Error.Id E_entryExists  = {
   145            msg: "E_entryExists: %s name already in table "
   146        };
   147        
   148        /*!
   149         *  Allow dynamic growth of the NameServer instance table
   150         *
   151         *  This value can be used to set the {@link #maxRuntimeEntries}.
   152         *  This flag tells NameServer to allow dynamic growth 
   153         *  of the table.
   154         */
   155        const UInt ALLOWGROWTH = (~0);
   156    
   157        /*!
   158         *  Structure of entry in Name/Value table
   159         *
   160         *  This structure is returned from the {@link #getMeta} 
   161         *  API.
   162         *
   163         *  @field(name)  Name portion of the name/value pair.
   164         *  @field(len)   Length of the value field.
   165         *  @field(value) Value portion of the name/value entry.
   166         */
   167        metaonly struct Entry {
   168            String      name;
   169            UInt        len;
   170            UArg        value;
   171        };
   172    
   173        /*!
   174         *  ======== isRegistered ========
   175         *  Determines if a remote driver is registered for the specified id.
   176         *
   177         *  @param(procId)  The remote processor id.
   178         */
   179        Bool isRegistered(UInt16 procId);
   180    
   181        /*!
   182         *  ======== registerRemoteDriver ========
   183         *  Register the NameServer remote handle for the specified processor id.
   184         *
   185         *  This function is used by NameServer remote driver to register
   186         *  themselves with NameServer. Only one remote driver can be registered
   187         *  with a remote processor. The API returns {@link #Status_FAIL} if there
   188         *  is already a registered remote driver for the processor id.
   189         *
   190         *  @param(handle)  The handle for a NameServer remote driver instance.
   191         *  @param(procId)  The remote processor id.
   192         *
   193         *  @b(returns)     Returns {@link #Status_SUCCESS} if successful or
   194         *                  {@link #Status_FAIL} if the processor id has already
   195         *                  been set.
   196         */
   197        Int registerRemoteDriver(INameServerRemote.Handle handle, UInt16 procId);
   198            
   199        /*!
   200         *  ======== unregisterRemoteDriver ========
   201         *  Unregister the NameServer remote handle for the specified processor id.
   202         *
   203         *  This function is used by NameServer Remote implementations to unregister
   204         *  themselves with NameServer.
   205         *
   206         *  @param(procId)  The remote processor id to unregister.
   207         */
   208        Void unregisterRemoteDriver(UInt16 procId);
   209    
   210        /*!
   211         *  ======== modAddMeta ========
   212         *  Add a name/value pair into the specified instance's table during
   213         *  configuration
   214         *
   215         *  This function adds any length value into the local table. The function
   216         *  makes sure the name does not already exist in the local table.
   217         *
   218         *  This function should be used by modules when adding into a NameServer
   219         *  instance. The application configuration file, should 
   220         *  use {@link #addMeta}.
   221         *
   222         *  The function does not query remote processors to make sure the
   223         *  name is unique.
   224         *
   225         *  @param(instName)   NameServer instance name
   226         *  @param(name)       Name portion of the name/value pair
   227         *  @param(value)      Value portion of the name/value pair
   228         *  @param(len)        Length of the value buffer
   229         */
   230        metaonly Void modAddMeta(String instName, String name, Any value, UInt len);
   231    
   232        /*!
   233         *  ======== getName$view ========
   234         *  @_nodoc
   235         *  Used at ROV time to display reverse-lookup name from 32-bit value and
   236         *  tableName
   237         */
   238        metaonly String getName$view(String tableName, UInt32 value);
   239        
   240        /*! 
   241         *  ======== getNameByKey$view ========
   242         *  @_nodoc
   243         *  ROV function for retrieving an entry by its address. Throws an exception
   244         *  if the name was not found
   245         */
   246        metaonly String getNameByKey$view(Ptr addr);
   247    
   248    
   249    instance:
   250    
   251        /*!
   252         *  Maximum number of name/value pairs that can be dynamically created.
   253         *
   254         *  This parameter allows NameServer to pre-allocate memory. 
   255         *  When NameServer_add or NameServer_addUInt32 is called, no memory 
   256         *  allocation occurs.
   257         *
   258         *  If the number of pairs is not known at configuration time, set this
   259         *  value to {@link #ALLOWGROWTH}. This instructs NameServer to grow the
   260         *  table as needed. NameServer will allocate memory from the 
   261         *  {@link #tableHeap} when a name/value pair is added.
   262         *
   263         *  The default is {@link #ALLOWGROWTH}.
   264         */
   265        config UInt maxRuntimeEntries = ALLOWGROWTH;
   266    
   267        /*!
   268         *  Name/value table is allocated from this heap.
   269         *
   270         *  The instance table and related buffers are allocated out of this heap
   271         *  during the dynamic create. This heap is also used to allocate new
   272         *  name/value pairs when {@link #ALLOWGROWTH} for 
   273         *  {@link #maxRuntimeEntries}
   274         *
   275         *  The default is to use the same heap that instances are allocated
   276         *  from which can be configured via the 
   277         *  NameServer.common$.instanceHeap configuration parameter.
   278         */
   279        config IHeap.Handle tableHeap = null;
   280    
   281        /*!
   282         *  Name/value table is placed into this section on static creates.
   283         *
   284         *  The instance table and related buffers are placed into this section
   285         *  during the static create.
   286         *
   287         *  The default is no explicit section placement.
   288         */
   289        metaonly config String tableSection = null;
   290    
   291        /*!
   292         *  Check if a name already exists in the name/value table.
   293         *
   294         *  When a name/value pair is added during runtime, if this boolean is true,
   295         *  the table is searched to see if the name already exists. If it does,
   296         *  the name is not added and the {@link #E_entryExists} error is raised.
   297         *
   298         *  If this flag is false, the table will not be checked to see if the name
   299         *  already exists. It will simply be added. This mode has better
   300         *  performance at the expense of potentially having non-unique names in the
   301         *  table.
   302         *
   303         *  This flag is used for runtime adds only. Adding non-unique names during
   304         *  configuration results in a build error.
   305         */
   306        config Bool checkExisting = true;
   307    
   308        /*!
   309         *  Length, in MAUs, of the value field in the table.
   310         *
   311         *  Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32).
   312         */
   313        config UInt maxValueLen = 0;
   314    
   315        /*!
   316         *  Length, in MAUs, of the name field in the table.
   317         *
   318         *  The maximum length of the name portion of the name/value
   319         *  pair. The length includes the null terminator ('\0').
   320         */
   321        config UInt maxNameLen = 16;
   322    
   323        /*!
   324         *  ======== metaTable ========
   325         *  @_nodoc
   326         *  Table to hold the statically added name/value pairs until
   327         *  they ready to be added to the object.
   328         */
   329        metaonly config Entry metaTable[];
   330    
   331       /*!
   332         *  ======== create ========
   333         *  @_nodoc (Refer to doxygen for ti/ipc/NameServer.h)
   334         *  Create a NameServer instance
   335         *
   336         *  This function creates a NameServer instance. The name is
   337         *  used for remote processor queries and diagnostic tools. For
   338         *  single processor system (e.g. no remote queries), the name
   339         *  can be NULL.
   340         *
   341         *  @param(name)    Name of the instance
   342         */
   343        create(String name);
   344    
   345        /*!
   346         *  ======== addUInt32Meta ========
   347         *  Add a name/value pair into the instance's table during configuration
   348         *
   349         *  This function adds a UInt32 value into the local table. The function
   350         *  makes sure the name does not already exist in the local table.
   351         *
   352         *  The function does not query remote processors to make sure the
   353         *  name is unique.
   354         *
   355         *  @param(name)   Name portion of the name/value pair
   356         *  @param(value)  Value portion of the name/value pair
   357         */
   358        metaonly Void addUInt32Meta(String name, any value);
   359    
   360        /*!
   361         *  ======== addMeta ========
   362         *  Add a name/value pair into the instance's table during configuration
   363         *
   364         *  This function adds any length value into the local table. The function
   365         *  makes sure the name does not already exist in the local table.
   366         *
   367         *  This function should be used by within the application configuration
   368         *  file. XDC modules should use {@link #modAddMeta}.
   369         *
   370         *  The function does not query remote processors to make sure the
   371         *  name is unique.
   372         *
   373         *  @param(name)   Name portion of the name/value pair
   374         *  @param(value)  Value portion of the name/value pair
   375         *  @param(len)    Length of the value buffer
   376         */
   377        metaonly Void addMeta(String name, Any value, UInt len);
   378    
   379        /*!
   380         *  ======== getMeta ========
   381         *  Retrieves the name/value entry
   382         *
   383         *  If the name is found, the entry is returned. The caller can parse the
   384         *  entry as needed. If the name is not found, null is returned.
   385         *
   386         *  The search only occurs on the local table.
   387         *
   388         *  @param(name)     Name in question
   389         *
   390         *  @b(returns)      Name/value entry
   391         */
   392        metaonly Entry getMeta(String name);
   393    
   394        /*! 
   395         *  ======== getKey ========
   396         *  @_nodoc 
   397         *  Returns a pointer to the TableEntry containing the argument 'val'.
   398         *  This should only be used internally by Ipc modules during their
   399         *  initialization process.
   400         *
   401         *  This function can only be used when maxValueLen = sizeof(UInt32) 
   402         */
   403        Ptr getKey(UInt32 val);
   404        
   405    internal:
   406    
   407        /* Used to eliminate code when doing whole-program */
   408        config Bool singleProcessor = true;
   409    
   410        metaonly typedef Entry EntryMap[];
   411    
   412        /*! Structure of entry in Name/Value table */
   413        struct TableEntry {
   414            List.Elem   elem;
   415            String      name;
   416            UInt        len;
   417            UArg        value;
   418        };
   419    
   420        /*!
   421         *  ======== metaModTable ========
   422         *  Table to hold the static added name/value pairs until
   423         *  they ready to be added to the object.
   424         */
   425        metaonly config EntryMap metaModTable[string];
   426        
   427        /*
   428         *  ======== postInit ========
   429         *  Finish initializing static and dynamic NameServer instances
   430         */
   431        Int postInit(Object *obj);
   432    
   433        /*
   434         *  ======== findLocal ========
   435         *  Searches to the local instance table.
   436         *
   437         *  This is an internal function because it returns an internal structure.
   438         */
   439        TableEntry *findLocal(Object *obj, String name);
   440    
   441        /*
   442         *  ======== removeLocal ========
   443         *  removes an entry from the local instance table.
   444         */
   445        Void removeLocal(Object *obj, TableEntry *entry);
   446        
   447        /*
   448         *  ======== editLocal ========
   449         *  replaces the value of an entry from the local instance table.
   450         */
   451        Void editLocal(Object *obj, TableEntry *entry, Ptr newValue);
   452        
   453        /* instance object */
   454        struct Instance_State {
   455            String       name;           /* Name of the instance           */
   456            List.Object  freeList;       /* Empty entries list             */
   457            List.Object  nameList;       /* Filled entries list            */
   458            UInt         maxNameLen;     /* Max name length                */
   459            UInt         maxValueLen;    /* Max value length               */
   460            UInt         numStatic;      /* Total static entries in table  */
   461            UInt         numDynamic;     /* Total dynamic entries in table */
   462            TableEntry   table[];        /* Table                          */
   463            Char         names[];        /* Buffer for names               */
   464            UInt8        values[];       /* Buffer for values              */
   465            IHeap.Handle tableHeap;      /* Heap used to alloc table       */
   466            Bool         checkExisting;  /* check ig name already exists   */
   467        };
   468    
   469        struct Module_State {
   470            INameServerRemote.Handle nsRemoteHandle[];        
   471            GateSwi.Handle gate;
   472        };
   473    }
   474    /*
   475     *  @(#) ti.sdo.utils; 1, 0, 0, 0,419; 8-10-2010 17:49:45; /db/vtree/library/trees/ipc/ipc-e23x/src/
   476     */
   477