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     *  ======== DriverTable.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     *! 28-Apr-2008 nitya   review update
    16     *
    17     */
    18    
    19    import xdc.runtime.Error;
    20    import xdc.runtime.Assert;
    21    import xdc.runtime.IGateProvider;
    22    import ti.sdo.utils.NameServer;
    23    
    24    /*! 
    25     *  DriverTable module
    26     *
    27     *  This module maintains a table of {@link IDriver#Handle}. Other modules can
    28     *  lookup these handles by name and open channels for IO. The {@link Stream}
    29     *  module will open channels using this table. All names in this table have to
    30     *  be unique.
    31     *
    32     *  This module allows addition of IDriver handles into the table at 
    33     *  configuration time as well as at runtime. However, the total number of 
    34     *  runtime entries have to be decided at configuration time. There is no limit
    35     *  to entries added statically.
    36     *
    37     *  This module uses {@link ti.sdo.utils.NameServer} to maintain its table
    38     */
    39     
    40    module DriverTable {
    41        /*! 
    42         *  Max runtime entries that can be added.
    43         *
    44         *  Currently this module requires total number of entries that need
    45         *  to be added at runtime to be identified at configuration time.
    46         */
    47        config UInt maxRuntimeEntries = 0;
    48        
    49        /*! 
    50         *  Gate used to make the table thread safe.
    51         */
    52        config IGateProvider.Handle gate = null;
    53        
    54        /*! 
    55         *  Length, in MAUs, of the name field in the table.
    56         */
    57        config UInt maxNameLen = 16;
    58    
    59        /*! 
    60         *  Section name is used to place the IDriver table.
    61         */
    62        metaonly config String tableSection = null;
    63            
    64        /*!
    65         *  ======== add ========
    66         *  Add IDriver handle to the table at runtime.
    67         *
    68         *  Will raise an error when name already exists in table.
    69         *  This API is not thread safe. Set {@link #gate} parameter
    70         *  to protect table if called from multiple threads.
    71         *
    72         *  @param(name)            name of entry
    73         *  @param(driverHandle)    {@link IDriver#Handle}
    74         *  @param(eb)              Error Block
    75         */
    76        Void add(String name, IDriver.Handle driverHandle, Error.Block *eb);
    77    
    78        /*!
    79         *  ======== addMeta ========
    80         *  Add to IDriver handle to the table at configuration time.
    81         *
    82         *  @param(name)            name of entry
    83         *  @param(driverHandle)    {@link IDriver#Handle}
    84         */
    85        metaonly Void addMeta(String name, IDriver.Handle driverHandle);
    86    
    87        /*!
    88         *  ======== remove ========
    89         *  Remove entry from IDriver table at runtime.
    90         *
    91         *  Will raise an error when name not found in table
    92         *  This API is not thread safe. Set {@link #gate} parameter
    93         *  to protect table if called from multiple threads.
    94         *
    95         *  @param(name)    name of entry
    96         *  @param(eb)      error block
    97         */
    98        Void remove(String name, Error.Block *eb);
    99    
   100        /*!
   101         *  ======== match ========
   102         *  @_nodoc
   103         *  match entry in IDriver table.
   104         *
   105         *  This function matches the name with table entries and writes to
   106         *  the handle if it finds a match. If entry is not found it sets
   107         *  handle to null. It returns length matched.
   108         *  This API is not thread safe. Set {@link #gate} parameter
   109         *  to protect table if called from multiple threads.
   110         *
   111         *  @param(name)    name of entry
   112         *  @param(handle)  pointer to IDriver handle.
   113         *  @param(eb)      error block
   114         *  @b(returns)     length matched
   115         */
   116        Int match(String name, IDriver.Handle *handle, Error.Block *eb);
   117    
   118    internal:
   119    
   120        /*!
   121         * Structure of entry in metaonly table
   122         */
   123        struct Entry {
   124            String  name;
   125            Ptr     handle;
   126        };
   127    
   128        /*! 
   129         *  Array for all statically configured table entries 
   130         */
   131        metaonly config Entry staticEntries[];
   132            
   133        struct Module_State {
   134            NameServer.Handle   drvTable;
   135        };
   136    }