1    /* 
     2     * Copyright (c) 2012, 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     *  ======== Timer.xdc ========
    34     *
    35     */
    36    
    37    package ti.sysbios.family.arp32;
    38    
    39    import xdc.rov.ViewInfo;
    40    
    41    import xdc.runtime.Types;
    42    import xdc.runtime.Error;
    43    
    44    import ti.sysbios.interfaces.ITimer;
    45    import ti.sysbios.family.arp32.Hwi;
    46    
    47    /*!
    48     *  ======== Timer ========
    49     *  Timer Peripherals Manager.
    50     *
    51     *  The timers used are the two CTM timers (0 and 1)
    52     *  that support interrupts.
    53     *
    54     *  @p(html)
    55     *  <h3> Calling Context </h3>
    56     *  <table border="1" cellpadding="3">
    57     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    58     *
    59     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    60     *    <!--                                                                                                                 -->
    61     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    62     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    63     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    64     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    65     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    66     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    67     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    68     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    69     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    70     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    71     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    74     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    75     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    76     *    <tr><td colspan="6"> Definitions: <br />
    77     *       <ul>
    78     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    79     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    80     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    81     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    82     *           <ul>
    83     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    84     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    85     *             <li> During main().</li>
    86     *             <li> During BIOS.startupFxns.</li>
    87     *           </ul>
    88     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    89     *           <ul>
    90     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    91     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    92     *           </ul>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     */
    99    @InstanceFinalize       /* To cleanup */
   100    @InstanceInitError      /* To report unavailability of timer */
   101    @ModuleStartup          /* to configure static timers */
   102    
   103    module Timer inherits ti.sysbios.interfaces.ITimer
   104    {
   105        /*! Max value of Timer period for PeriodType_COUNTS*/
   106        const UInt MAX_PERIOD = 0xffffffff;
   107    
   108        /*! 
   109         *  Number of timer peripherals on chip 
   110         *
   111         *  Only 2 are available to each core.
   112         */
   113        const Int NUM_TIMER_DEVICES = 2;
   114    
   115        /*! Timer clock divider wrt cpu clock */
   116        const Int TIMER_CLOCK_DIVIDER = 1;
   117    
   118        /*! @_nodoc
   119         *  Min instructions to use in trigger(). 
   120         */
   121        const Int MIN_SWEEP_PERIOD = 1;
   122    
   123        /*! @_nodoc */
   124        @XmlDtd
   125        metaonly struct BasicView {
   126            Ptr         halTimerHandle;
   127            String      label;
   128            UInt        id;
   129            String      device;
   130            String      startMode;
   131            String      runMode;
   132            UInt        period;
   133            String      periodType;
   134            UInt        intNum;
   135            String      tickFxn[];
   136            UArg        arg;
   137            String      extFreq;
   138            String      hwiHandle;
   139        };
   140    
   141    
   142        /*! @_nodoc */
   143        metaonly struct ModuleView {
   144            String      availMask;      /* available 32-bit timer halves */
   145        }
   146    
   147        /*! @_nodoc */
   148        metaonly struct DeviceView {
   149            UInt        id;
   150            String      device;
   151            String      devAddr;
   152            UInt        intNum;
   153            String      runMode;
   154            UInt        period;
   155            UInt        currCount;
   156            UInt        remainingCount;
   157        };
   158    
   159        /*! @_nodoc */
   160        @Facet
   161        metaonly config ViewInfo.Instance rovViewInfo = 
   162            ViewInfo.create({
   163                viewMap: [
   164                [
   165                    'Basic',
   166                    {
   167                        type: ViewInfo.INSTANCE,
   168                        viewInitFxn: 'viewInitBasic',
   169                        structName: 'BasicView'
   170                    }
   171                ],
   172                [
   173                    'Device',
   174                    {
   175                        type: ViewInfo.INSTANCE,
   176                        viewInitFxn: 'viewInitDevice',
   177                        structName: 'DeviceView'
   178                    }
   179                ],
   180                [
   181                    'Module',
   182                    {
   183                        type: ViewInfo.MODULE,
   184                        viewInitFxn: 'viewInitModule',
   185                        structName: 'ModuleView'
   186                    }
   187                ],
   188                ]
   189            });
   190    
   191        /*! 
   192         *  Error raised when timer id specified is not supported.
   193         */
   194        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"}; 
   195    
   196        /*! 
   197         *  Error raised when timer requested is in use
   198         */
   199        config Error.Id E_notAvailable  = 
   200                {msg: "E_notAvailable: Timer not available %d"}; 
   201    
   202        /*! 
   203         *  Error raised when period requested is not supported
   204         */
   205        config Error.Id E_cannotSupport  = 
   206                {msg: "E_cannotSupport: Timer cannot support requested period %d"}; 
   207    
   208        /*!
   209         *  ======== anyMask ========
   210         *  Available mask to be used when select = Timer_ANY
   211         */
   212        config UInt anyMask = 0x3;
   213    
   214        /*!
   215         *  ======== getHandle ========
   216         *  Get Handle associated with a timer id.
   217         *
   218         *  @param(id)      timer Id.
   219         *  @b(returns)     timer Handle
   220         */
   221        @DirectCall
   222        Handle getHandle(UInt id);
   223    
   224    instance:
   225    
   226        /*! Hwi Params for Hwi Object. Default is null. */
   227        config Hwi.Params *hwiParams = null;
   228    
   229        /*!
   230         *  ======== reconfig ========
   231         *  Used to modify static timer instances at runtime.
   232         *
   233         *  @param(timerParams)     timer Params
   234         *  @param(tickFxn)         function that runs when timer expires
   235         */
   236        @DirectCall
   237        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   238    
   239    
   240    internal:   /* not for client use */
   241       
   242        /*!
   243         *  ======== noStartupNeeded ========
   244         *  Flag used to prevent misc code from being brought in
   245         *  un-necessarily
   246         */
   247        config UInt startupNeeded = false;
   248    
   249        struct Instance_State {
   250            Bool        staticInst;
   251            Int         id;
   252            Int         ctmid;          /* CTM counter ID */
   253            RunMode     runMode;    
   254            StartMode   startMode;
   255            UInt        period;     
   256            PeriodType  periodType;    
   257            UInt        intNum;
   258            UArg        arg;  
   259            Hwi.FuncPtr tickFxn;
   260            Types.FreqHz extFreq;       /* external frequency in Hz */
   261            Hwi.Handle  hwi;
   262        }
   263    
   264        struct Module_State {
   265            UInt    availMask;                  /* available peripherals */
   266            UInt    *baseAddr;                  /* add this here to make it work */
   267            Handle  handles[NUM_TIMER_DEVICES]; /* array of handles based on id */
   268        }
   269    }
   270    /*
   271     *  @(#) ti.sysbios.family.arp32; 2, 0, 0, 0,69; 2-24-2012 11:39:50; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   272    
   273     */
   274