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