1    /* --COPYRIGHT--,BSD
     2     * Copyright (c) $(CPYYEAR), 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     * --/COPYRIGHT--*/
    32    /*
    33     *  ======== MultiProc.xdc ========
    34     *
    35     *! Revision History
    36     *! ================
    37     *! 07-May-2010 skp     Removed MultiProc_getSlot()
    38     *! 23-Oct-2009 skp     Many cdoc changes
    39     *! 10-Oct-2009 skp     Changes to support new Notify
    40     *! 16-Apr-2009 toddm   Code review comments
    41     *! 16-May-2008 jv      Made modifications per review.
    42     */
    43    
    44    import xdc.rov.ViewInfo;
    45    
    46    import xdc.runtime.Assert;
    47    
    48    /*!
    49     *  ======== MultiProc ========
    50     *  Processor Id Module Manager
    51     *
    52     *  Many IPC modules require identifying processors in a
    53     *  multi-processor environment. The MultiProc module centralizes
    54     *  processor id management into one module.  Since this configuration
    55     *  is almost always universally required, most IPC applications 
    56     *  require supplying configuration of this module.
    57     *
    58     *  Each processor in the MultiProc module may be uniquely identified by
    59     *  either a name string or an integer ranging from 0 to MAXPROCESSORS - 1.
    60     *  Configuration is supplied using the {@link #setConfig} meta function,
    61     *  the {@link #numProcessors} and {@link #baseIdOfCluster}.
    62     *
    63     *  The setConfig function tells the MultiProc module:
    64     *  @p(blist)
    65     *      - The specific processor for which the application is being built
    66     *      - The number of processors in the cluster
    67     *  @p
    68     *
    69     *  A cluster is a set of processors within a system which share some share
    70     *  shared memory and supports notifications. Typically most systems contain
    71     *  one cluster.  When there are multiple clusters in the system, the
    72     *  {@link #numProcessors} and {@link #baseIdOfCluster} configuration
    73     *  paramaters are required to be set before calling {@link #setConfig}
    74     *  
    75     *  For examle in a system with 2 C6678 devices [each C6678 contains 8
    76     *  homogeneuous cores].  For first C6678 device: 
    77     *  @p(code)
    78     *  var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
    79     *  MultiProc.baseIdOfCluster = 0;
    80     *  MultiProc.numProcessors = 16;
    81     *  MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2", "CORE3",
    82     *                             "CORE4", "CORE5", "CORE6", "CORE7"]);
    83     *  @p
    84     *
    85     *  For second C6678 device:
    86     *  @p(code)
    87     *  var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
    88     *  MultiProc.baseIdOfCluster = 8;
    89     *  MultiProc.numProcessors = 16;
    90     *  MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2", "CORE3",
    91     *                             "CORE4", "CORE5", "CORE6", "CORE7"]);
    92     *  @p
    93     *
    94     *  Using the information supplied using the {@link #setConfig} meta function
    95     *  and the {@link #baseIdOfCluster} module configuration, the processor IDs
    96     *  are internally set.  Please refer to the documentation for
    97     *  {@link #setConfig} and {@link #baseIdOfCluster} for more details.
    98     *
    99     *  At runtime, the {@link #getId} call returns the MultiProc id of those
   100     *  processors within its cluster. At config-time, the {@link #getIdMeta}
   101     *  call returns the the same value.
   102     *
   103     */
   104    
   105    module MultiProc
   106    {
   107        metaonly struct ModuleView {
   108            UInt16       id;                /* Own ID                           */
   109            UInt16       numProcessors;     /* # of processors                  */
   110            String       nameList[];        /* Proc names ordered by procId     */
   111        }
   112    
   113        @Facet
   114        metaonly config ViewInfo.Instance rovViewInfo =
   115            ViewInfo.create({
   116                viewMap: [
   117                [
   118                    'Module',
   119                    {
   120                        type: ViewInfo.MODULE,
   121                        viewInitFxn: 'viewInitModule',
   122                        structName: 'ModuleView'
   123                    }
   124                ],
   125                ]
   126            });
   127    
   128        /*!
   129         *  Assert raised when an invalid processor id is used
   130         */
   131        config Assert.Id A_invalidMultiProcId  = {
   132            msg: "A_invalidMultiProcId: Invalid MultiProc id"
   133        };
   134        
   135        /*!
   136         *  Assert raised when a NULL processor name is encountered
   137         */
   138        config Assert.Id A_invalidProcName  = {
   139            msg: "A_invalidProcName: NULL MultiProc name encountered"
   140        };
   141    
   142        /*!
   143         *  Invalid processor id constant
   144         *
   145         *  This constant denotes that the processor id is not valid.
   146         */
   147        const UInt16 INVALIDID = 0xFFFF;
   148        
   149        /*! @_nodoc
   150         *  ======== nameList ========
   151         *  Unique name for the each processor used in a multi-processor app
   152         *
   153         *  This array should never be set or read directly by the MultiProc user.
   154         *  The nameList is used to store names configuration supplied via the
   155         *  {@link #setConfig} static function.  
   156         *
   157         *  At runtime, the {@link #getName} function may be used to retrieve
   158         *  the name of any processor given it's MultiProc id.
   159         */
   160        config String nameList[];
   161    
   162        /*! @_nodoc
   163         *  ======== id ========
   164         *  Unique software id number for the processor
   165         *
   166         *  This value should never be set or read directly by the MultiProc user.
   167         *  Instead, the {@link #getId}, {@link #getIdMeta}, and 
   168         *  {@link #setLocalId} calls should be used to respectively retrieve any
   169         *  processors' MultiProc ids or set the local processor's MultiProc id.
   170         */
   171        metaonly config UInt16 id = 0;
   172        
   173        /*! @_nodoc
   174         *  ======== numProcsInCluster ========
   175         *  Number of processors in a cluster
   176         *
   177         *  This parameter should never be set: numProcsInCluster is
   178         *  internally set by the {@link #setConfig} meta function.
   179         *  setConfig statically sets the value of this configuration to the
   180         *  length of the supplied nameList array.
   181         */
   182        config UInt16 numProcsInCluster = 1;
   183    
   184        /*!
   185         *  ======== baseIdOfCluster ========
   186         *  The base id of the cluster.
   187         *
   188         *  Using this base id, the id of each processor in the cluster
   189         *  is set based up its position in {@link #setConfig}. When more
   190         *  more than one cluster exists in the system, this parameter must
   191         *  be set before calling {@link #setConfig}.
   192         */
   193        metaonly config UInt16 baseIdOfCluster = 0;
   194    
   195        /*!
   196         *  ======== numProcessors ========
   197         *  Number of processors in the system
   198         *
   199         *  This configuration should only be set when there is more than one
   200         *  cluster in the system.  It must be set before calling
   201         *  {@link #setConfig}. If the system contains only one cluster,
   202         *  it is internally set by the {@link #setConfig} meta function to the
   203         *  length of the supplied nameList array.
   204         *  After {@link #setConfig} has been  called, it is possible to
   205         *  retrive the maximum # of processors by reading this module config
   206         *  either at run-time or at config time.
   207         */
   208        config UInt16 numProcessors = 1;
   209    
   210        /*! @_nodoc
   211         *  ======== getClusterId ========
   212         */
   213        UInt16 getClusterId(UInt16 procId);
   214        
   215        /*!
   216         *  ======== getIdMeta ========
   217         *  Meta version of {@link #getId}
   218         *
   219         *  Statically returns the internally set ID based on configuration 
   220         *  supplied via {@link #setConfig}.
   221         *
   222         *  @param(name)        MultiProc procName
   223         */
   224        metaonly UInt16 getIdMeta(String name);
   225        
   226        /*! 
   227         *  ======== getDeviceProcNames ========
   228         *  Returns an array of all possible processor names on the build device
   229         *
   230         *  @(return)           Array of valid MultiProc processor names    
   231         */
   232        metaonly Any getDeviceProcNames();
   233    
   234        /*!
   235         *  ======== setConfig ========
   236         *  Configure the MultiProc module
   237         *
   238         *  Configuration of the MultiProc module is primarily accomplished using
   239         *  the setConfig API at config time.  The setConfig API allows the
   240         *  MultiProc module to identify:
   241         *  @p(blist)
   242         *      - Which is the local processor
   243         *      - Which processors are being used
   244         *      - Which processors can synchronize
   245         *  @p
   246         *  The second of these two pieces of information is supplied via the 
   247         *  nameList argument.  The nameList is a non-empty set of distinct
   248         *  processors valid for the particular device.  For a list of valid 
   249         *  processor names for a given device, please refer to the :
   250         *  {@link ./../ipc/family/doc-files/procNames.html Table of     
   251         *   Valid Names for Each Device}.
   252         *
   253         *  The local processor is identified by using a single name from 
   254         *  nameList.  A MultiProc id is internally set to the index of
   255         *  'name' in the supplied 'nameList'.  I.e. in the example:
   256         *  
   257         *  @p(code)
   258         *  MultiProc.setConfig("DSP", ["HOST", "DSP", "OTHERCORE"]);
   259         *  @p
   260         *
   261         *  The processors, "HOST", "DSP" and "OTHERCORE" get assigned MultiProc
   262         *  IDs 0, 1, and 2, respectively.  The local processor, "DSP" is assigned
   263         *  an ID of '1'.
   264         *  
   265         *  If the local processor is not known at static time, it is possible to 
   266         *  supply a null name. MultiProc will set the local id to 
   267         *  {@link #INVALIDID} until it is set at runtime using 
   268         *  MultiProc_setLocalId.
   269         *
   270         *  @param(name)        MultiProc name for the local processor
   271         *  @param(nameList)    Array of all processors used by the application
   272         */
   273        metaonly Void setConfig(String name, String nameList[]);
   274    
   275        /*! @_nodoc
   276         *  ======== getName$view ========
   277         *  ROV-time version of {@link #getName}
   278         */
   279        metaonly String getName$view(UInt id);
   280        
   281        /*! @_nodoc
   282         *  ======== self$view ========
   283         *  ROV-time version of {@link #self}
   284         */
   285        metaonly UInt self$view();
   286        
   287        /*! @_nodoc
   288         *  This is needed to prevent the MultiProc module from being optimized away
   289         *  during the whole_program[_debug] partial link.
   290         */
   291        Void dummy();
   292    
   293    internal:
   294    
   295        /* list of processor id's in cluster */
   296        config UInt16 procIdList[];
   297    
   298        /* id is in Module_State to support the changing of it via setLocalId */
   299        struct Module_State {
   300            UInt16 id;
   301            UInt16 baseIdOfCluster;
   302        };
   303    }
   304