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