1    /*
     2     * Copyright (c) 2013, 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.arm.lm4;
    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.arm.m3.Hwi;
    46    
    47    /*!
    48     *  ======== Timer ========
    49     *  Stellaris LM4 Timer Peripheral Driver
    50     *
    51     *  Stellaris LM4 Timer Peripheral Driver for standalone use and
    52     *  as the {@link ti.sysbios.hal.Timer} delegate.
    53     *
    54     *  Implements {@link ti.sysbios.interfaces.ITimer}
    55     *
    56     *  @p(html)
    57     *  <h3> Calling Context </h3>
    58     *  <table border="1" cellpadding="3">
    59     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    60     *
    61     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    62     *    <!--                                                                                                                 -->
    63     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    64     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    65     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    66     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    67     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    68     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    69     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    70     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    71     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    74     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    75     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    76     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    77     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    78     *    <tr><td colspan="6"> Definitions: <br />
    79     *       <ul>
    80     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    81     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    82     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    83     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    84     *           <ul>
    85     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    86     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    87     *             <li> During main().</li>
    88     *             <li> During BIOS.startupFxns.</li>
    89     *           </ul>
    90     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    91     *           <ul>
    92     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    93     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    94     *           </ul>
    95     *       </ul>
    96     *    </td></tr>
    97     *
    98     *  </table>
    99     *  @p
   100     */
   101    @InstanceFinalize       /* To cleanup */
   102    @InstanceInitError      /* To report unavailability of timer */
   103    @ModuleStartup          /* to configure static timers */
   104    
   105    module Timer inherits ti.sysbios.interfaces.ITimer
   106    {
   107        /*! override supportsDynamic - this Timer DOES support RunMode_DYNAMIC */
   108        override metaonly config Bool supportsDynamic = true;
   109    
   110        /*! Max value of Timer period for PeriodType_COUNTS*/
   111        const UInt MAX_PERIOD = 0xFFFFFFFF;
   112    
   113        /*! Timer clock divider wrt cpu clock */
   114        const Int TIMER_CLOCK_DIVIDER = 1;
   115    
   116        /*! @_nodoc
   117         *  Min instructions to use in trigger().
   118         */
   119        const Int MIN_SWEEP_PERIOD = 1;
   120    
   121        /*! @_nodoc */
   122        @XmlDtd
   123        metaonly struct BasicView {
   124            Ptr         halTimerHandle;
   125            String      label;
   126            UInt        id;
   127            String      device;
   128            String      startMode;
   129            String      runMode;
   130            UInt        period;
   131            String      periodType;
   132            UInt        intNum;
   133            String      tickFxn[];
   134            UArg        arg;
   135            String      extFreq;
   136            String      hwiHandle;
   137        };
   138    
   139    
   140        /*! @_nodoc */
   141        metaonly struct ModuleView {
   142            String      availMask;      /* available 32-bit timer halves */
   143        }
   144    
   145        /*! @_nodoc */
   146        metaonly struct DeviceView {
   147            UInt        id;
   148            String      device;
   149            String      devAddr;
   150            UInt        intNum;
   151            String      runMode;
   152            UInt        period;
   153            UInt        currCount;
   154            UInt        remainingCount;
   155            UInt        prevThreshold;
   156            Bool        altclk;
   157            String      state;
   158        };
   159    
   160        /*! @_nodoc */
   161        @Facet
   162        metaonly config ViewInfo.Instance rovViewInfo =
   163            ViewInfo.create({
   164                viewMap: [
   165                [
   166                    'Basic',
   167                    {
   168                        type: ViewInfo.INSTANCE,
   169                        viewInitFxn: 'viewInitBasic',
   170                        structName: 'BasicView'
   171                    }
   172                ],
   173                [
   174                    'Device',
   175                    {
   176                        type: ViewInfo.INSTANCE,
   177                        viewInitFxn: 'viewInitDevice',
   178                        structName: 'DeviceView'
   179                    }
   180                ],
   181                [
   182                    'Module',
   183                    {
   184                        type: ViewInfo.MODULE,
   185                        viewInitFxn: 'viewInitModule',
   186                        structName: 'ModuleView'
   187                    }
   188                ],
   189                ]
   190            });
   191    
   192        /*!
   193         *  Error raised when timer id specified is not supported.
   194         */
   195        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   196    
   197        /*!
   198         *  Error raised when timer requested is in use
   199         */
   200        config Error.Id E_notAvailable  =
   201            {msg: "E_notAvailable: Timer not available %d"};
   202    
   203        /*!
   204         *  Error raised when period requested is not supported
   205         */
   206        config Error.Id E_cannotSupport  =
   207            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   208    
   209        /*!
   210         *  ======== anyMask ========
   211         *  Available mask to be used when select = Timer_ANY
   212         */
   213        config UInt anyMask = 0x3F;
   214    
   215        /*!
   216         *  ======== getHandle ========
   217         *  Get Handle associated with a timer id.
   218         *
   219         *  @param(id)      timer Id.
   220         *  @b(returns)     timer Handle
   221         */
   222        @DirectCall
   223        Handle getHandle(UInt id);
   224    
   225        /*!
   226         *  ======== isrStub ========
   227         *  @_nodoc
   228         *  Timer interrupts must be acknowledged
   229         *
   230         *  @param(arg)     Timer object.
   231         */
   232        @DirectCall
   233        Void isrStub(UArg arg);
   234    
   235    instance:
   236    
   237        /*! Hwi Params for Hwi Object. Default is null. */
   238        config Hwi.Params *hwiParams = null;
   239    
   240        /*! Previous threshold count value. */
   241        config UInt prevThreshold = 0xFFFFFFFF;
   242    
   243        /*! Should timer run off of altclk? Default is false. Note that altclk
   244         *  is only supported on a subset of LM4 devices. */
   245        config Bool altclk = false;
   246    
   247        /*!
   248         *  ======== reconfig ========
   249         *  Used to modify static timer instances at runtime.
   250         *
   251         *  @param(timerParams)     timer Params
   252         *  @param(tickFxn)         function that runs when timer expires
   253         */
   254        @DirectCall
   255        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   256    
   257    
   258    internal:   /* not for client use */
   259    
   260        /*
   261         *  ======== noStartupNeeded ========
   262         *  Flag used to prevent misc code from being brought in
   263         *  un-necessarily
   264         */
   265        config UInt startupNeeded = false;
   266    
   267        /*! Information about timer */
   268        struct TimerDevice {
   269            UInt intNum;
   270            Ptr  baseAddr;
   271        };
   272    
   273        /*!
   274         *  ======== numTimerDevices ========
   275         *  The number of logical timers on a device.
   276         */
   277        config Int numTimerDevices;
   278    
   279        /*
   280         *  ======== enableArcmGpTimerClock ========
   281         *  Flag used to signal to the timer instance init code that
   282         *  this device has a Apps-RCM module whose GPT clock needs to
   283         *  be enabled.
   284         */
   285        config Bool enableArcmGpTimerClock = false;
   286    
   287        /*
   288         *  ======== initDevice ========
   289         *  reset timer to its resting state
   290         */
   291        Void initDevice(Object *timer);
   292    
   293        /*
   294         *  ======== postInit ========
   295         *  finish initializing static and dynamic Timers
   296         */
   297        Int postInit(Object *timer, Error.Block *eb);
   298    
   299        /*
   300         *  ======== enableTimers ========
   301         *  enable timer register access
   302         *  called as a Startup.firstFxnw
   303         */
   304        Void enableTimers();
   305    
   306        /*
   307         *  ======== masterDisable ========
   308         *  disable all interrupts by clearing PRIMASK bit
   309         */
   310        Bool masterDisable();
   311    
   312        /*
   313         *  ======== masterEnable ========
   314         *  set PRIMASK bit to enable interrupts
   315         */
   316        Void masterEnable();
   317    
   318        /*
   319         *  ======== write ========
   320         *  write a value to a timer register
   321         */
   322        Void write(Bool altclk, volatile UInt32 *pReg, UInt32 val);
   323    
   324        struct Instance_State {
   325            Bool            staticInst;
   326            Int             id;
   327            RunMode         runMode;
   328            StartMode       startMode;
   329            UInt            period;
   330            PeriodType      periodType;
   331            UInt            intNum;
   332            UArg            arg;
   333            Hwi.FuncPtr     tickFxn;
   334            Types.FreqHz    extFreq;        /* external frequency in Hz */
   335            Hwi.Handle      hwi;
   336            UInt            prevThreshold;
   337            Bool            altclk;
   338        }
   339    
   340        struct Module_State {
   341            UInt            availMask;      /* available peripherals */
   342            TimerDevice     device[];       /* timer device information */
   343            Handle          handles[];      /* array of handles based on id */
   344        }
   345    }