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