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     *  ======== MultiProc.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     *! 23-Oct-2009 skp     Many cdoc changes
    16     *! 10-Oct-2009 skp     Changes to support new Notify
    17     *! 16-Apr-2009 toddm   Code review comments
    18     *! 16-May-2008 jv      Made modifications per review.
    19     */
    20    
    21    import xdc.rov.ViewInfo;
    22    
    23    import xdc.runtime.Assert;
    24    
    25    /*!
    26     *  ======== MultiProc ========
    27     *  Processor Id Module Manager
    28     *
    29     *  Many IPC modules require the ability to uniquely specify and identify
    30     *  processors in a multi-processor environment. The MultiProc module
    31     *  centeralizes processor id management into one module.  Since this 
    32     *  configuration is almost always universally required, most IPC applications 
    33     *  require supplying configuration of this module.
    34     *
    35     *  Each processor in the MultiProc module may be uniquely identified by
    36     *  either a name string or an integer ranging from 0 to MAXPROCESSORS - 1.
    37     *  Configuration is supplied using the {@link #setConfig} meta function.
    38     *
    39     *  The setConfig function tells the MultiProc module:
    40     *  @p(blist)
    41     *      - The specific processor for which the application is being built
    42     *      - Which processors out of a set of possible processors on a device are
    43     *        being used by the multi-processor application
    44     *  @p
    45     *
    46     *  Using the information supplied using the {@link #setConfig} meta function,
    47     *  The {@link #numProcessors} module configuration and the processor IDs are
    48     *  internally set.  Please refer to the documentation for {@link #setConfig}
    49     *  for more details.
    50     *
    51     *  At runtime, the {@link #getId} call returns the MultiProc id
    52     *  for any processor. At config-time, the {@link #getIdMeta} call returns the
    53     *  the same value.  At both run time and static time, the 
    54     *  {@link #numProcessors} module config is equal to the length of the 
    55     *  procNames array supplied in {@link #setConfig}.
    56     *
    57     */
    58    
    59    module MultiProc
    60    {
    61        metaonly struct ModuleView {
    62            UInt16       id;                /* Own ID                           */
    63            UInt16       numProcessors;     /* # of processors                  */
    64            String       nameList[];        /* Proc names ordered by procId     */
    65        }
    66    
    67        @Facet
    68        metaonly config ViewInfo.Instance rovViewInfo =
    69            ViewInfo.create({
    70                viewMap: [
    71                [
    72                    'Module',
    73                    {
    74                        type: ViewInfo.MODULE,
    75                        viewInitFxn: 'viewInitModule',
    76                        structName: 'ModuleView'
    77                    }
    78                ],
    79                ]
    80            });
    81    
    82        /*!
    83         *  Assert raised when an invalid processor id is used
    84         */
    85        config Assert.Id A_invalidMultiProcId  = {
    86            msg: "A_invalidMultiProcId: Invalid MultiProc id"
    87        };
    88    
    89        /*!
    90         *  Invalid processor id constant
    91         *
    92         *  This constant denotes that the processor id is not valid.
    93         */
    94        const UInt16 INVALIDID = 0xFFFF;
    95        
    96        /*! @_nodoc
    97         *  ======== nameList ========
    98         *  Unique name for the each processor used in a multi-processor app
    99         *
   100         *  This array should never be set or read directly by the MultiProc user.
   101         *  The nameList is used to store names configuration supplied via the
   102         *  {@link #setConfig} static function.  
   103         *
   104         *  At runtime, the {@link #getName} function may be used to retrieve
   105         *  the name of any processor given it's MultiProc id.
   106         */
   107        config String nameList[];
   108    
   109        /*! @_nodoc
   110         *  ======== id ========
   111         *  Unique software id number for the processor
   112         *
   113         *  This value should never be set or read directly by the MultiProc user.
   114         *  Instead, the {@link #getId}, {@link #getIdMeta}, and 
   115         *  {@link #setLocalId} calls should be used to respectively retrieve any
   116         *  processors' MultiProc ids or set the local processor's MultiProc id.
   117         */
   118        config UInt16 id = 0;
   119    
   120        /*!
   121         *  ======== numProcessors ========
   122         *  Number of processors in the system
   123         *
   124         *  This configuration should only be read from and should never be set:
   125         *  numProcessors is internally set by the {@link #setConfig} meta function.
   126         *  setConfig statically sets the value of this configuration to the length
   127         *  of the supplied nameList array. After {@link #setConfig} has been 
   128         *  called, it is possible to retrive the maximum # of processors by 
   129         *  reading this module config either at run-time or at config time.
   130         */
   131        config UInt16 numProcessors = 1;
   132    
   133        /*!
   134         *  ======== getIdMeta ========
   135         *  Meta version of {@link #getId}
   136         *
   137         *  Statically returns the internally set ID based on configuration 
   138         *  supplied via {@link #setConfig}.
   139         */
   140        metaonly UInt16 getIdMeta(String name);
   141    
   142        /*! @_nodoc
   143         *  ======== getName$view ========
   144         *  ROV-time version of {@link #getName}
   145         */
   146        metaonly String getName$view(UInt id);
   147    
   148        /*! @_nodoc
   149         *  ======== getSlot ========
   150         *  Determines the offset for any two processors.
   151         *
   152         *  @param(remoteProcId)    remote MultiProc id.
   153         *  @b(returns)             offset for creating an instance.
   154         */
   155        UInt getSlot(UInt16 remoteProcId);
   156    
   157        /*!
   158         *  ======== setConfig ========
   159         *  Configure the MultiProc module
   160         *
   161         *  Configuration of the MultiProc module is primarily accomplished using
   162         *  the setConfig API at config time.  The setConfig API allows the
   163         *  MultiProc module to identify:
   164         *  @p(blist)
   165         *      - Which is the local processor
   166         *      - Which processors are being used
   167         *  @p
   168         *  The second of these two pieces of information is supplied via the 
   169         *  nameList argument.  The nameList is a non-empty set of distinct
   170         *  processors valid for the particular device.  For a list of valid 
   171         *  processor names for a given device, please refer to the :
   172         *  {@link ./../ipc/family/doc-files/procNames.html Table of     
   173         *   Valid Names for Each Device}.
   174         *
   175         *  The local processor is identified by using a single name from 
   176         *  nameList.  A MultiProc id is internally set to the index of
   177         *  'name' in the supplied 'nameList'.  If the local processor is 
   178         *  not known at static time, it is possible to supply a null name.
   179         *  MultiProc will set the local id to {@link #INVALIDID} until it
   180         *  is set at runtime using {@link #setLocalId}.
   181         *  
   182         */
   183        metaonly Void setConfig(String name, String nameList[]);
   184    
   185    internal:
   186    
   187        /* id is in Module_State to support the changing of it via setLocalId */
   188        struct Module_State {
   189            UInt16 id;
   190        };
   191    }
   192