1    /*
     2     * Copyright (c) 2014, 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.lm3;
    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 LM3 Timer Peripheral Driver
    50     *
    51     *  Stellaris LM3 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    @ModuleStartup          /* to configure static timers */
   102    @InstanceInitStatic
   103    
   104    module Timer inherits ti.sysbios.interfaces.ITimer
   105    {
   106        /*! Max value of Timer period for PeriodType_COUNTS*/
   107        const UInt MAX_PERIOD = 0xFFFFFFFF;
   108    
   109        /*! Timer clock divider wrt cpu clock */
   110        const Int TIMER_CLOCK_DIVIDER = 1;
   111    
   112        /*! @_nodoc
   113         *  Min instructions to use in trigger().
   114         */
   115        const Int MIN_SWEEP_PERIOD = 1;
   116    
   117        /*! @_nodoc */
   118        @XmlDtd
   119        metaonly struct BasicView {
   120            Ptr         halTimerHandle;
   121            String      label;
   122            UInt        id;
   123            String      device;
   124            String      startMode;
   125            String      runMode;
   126            UInt        period;
   127            String      periodType;
   128            UInt        intNum;
   129            String      tickFxn[];
   130            UArg        arg;
   131            String      extFreq;
   132            String      hwiHandle;
   133        };
   134    
   135    
   136        /*! @_nodoc */
   137        metaonly struct ModuleView {
   138            String      availMask;      /* available 32-bit timer halves */
   139        }
   140    
   141        /*! @_nodoc */
   142        metaonly struct DeviceView {
   143            UInt        id;
   144            String      device;
   145            String      devAddr;
   146            UInt        intNum;
   147            String      runMode;
   148            UInt        period;
   149            UInt        currCount;
   150            UInt        remainingCount;
   151            String      state;
   152        };
   153    
   154        /*! @_nodoc */
   155        @Facet
   156        metaonly config ViewInfo.Instance rovViewInfo =
   157            ViewInfo.create({
   158                viewMap: [
   159                [
   160                    'Basic',
   161                    {
   162                        type: ViewInfo.INSTANCE,
   163                        viewInitFxn: 'viewInitBasic',
   164                        structName: 'BasicView'
   165                    }
   166                ],
   167                [
   168                    'Device',
   169                    {
   170                        type: ViewInfo.INSTANCE,
   171                        viewInitFxn: 'viewInitDevice',
   172                        structName: 'DeviceView'
   173                    }
   174                ],
   175                [
   176                    'Module',
   177                    {
   178                        type: ViewInfo.MODULE,
   179                        viewInitFxn: 'viewInitModule',
   180                        structName: 'ModuleView'
   181                    }
   182                ],
   183                ]
   184            });
   185    
   186        /*! Timer enable function type definition. */
   187        typedef Void (*TimerEnableFuncPtr)(Int);
   188    
   189        /*! Timer disable function type definition. */
   190        typedef Void (*TimerDisableFuncPtr)(Int);
   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 = 0x3;
   214    
   215        /*!
   216         *  ======== enableFunc ========
   217         *  Pointer to Timer enable callback function
   218         *
   219         *  Timer enable callback function enables the timer clock and resets
   220         *  the timer.
   221         */
   222        config TimerEnableFuncPtr enableFunc = null;
   223    
   224        /*!
   225         *  ======== disableFunc ========
   226         *  Pointer to Timer disable callback function
   227         *
   228         *  Timer disable callback function disables the timer clock.
   229         */
   230        config TimerDisableFuncPtr disableFunc = null;
   231    
   232        /*!
   233         *  ======== getHandle ========
   234         *  Get Handle associated with a timer id.
   235         *
   236         *  @param(id)      timer Id.
   237         *  @b(returns)     timer Handle
   238         */
   239        Handle getHandle(UInt id);
   240    
   241        /*!
   242         *  ======== isrStub ========
   243         *  @_nodoc
   244         *  Timer interrupts must be acknowledged
   245         *
   246         *  @param(arg)     Timer object.
   247         */
   248        Void isrStub(UArg arg);
   249    
   250    instance:
   251    
   252        /*! Hwi Params for Hwi Object. Default is null. */
   253        config Hwi.Params *hwiParams = null;
   254    
   255        /*!
   256         *  ======== reconfig ========
   257         *  Used to modify static timer instances at runtime.
   258         *
   259         *  @param(timerParams)     timer Params
   260         *  @param(tickFxn)         function that runs when timer expires
   261         */
   262        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   263    
   264        /*!
   265         *  ======== getExpiredCounts64 ========
   266         *  Get current timer counter
   267         *
   268         *  @_nodoc
   269         *  Reads timer counter and adds period if IFR was set 
   270         *  before counter read. Used exclusively by TimestampProvider.
   271         *
   272         *  Must be called with interrupts disabled.
   273         *
   274         *  @b(returns)     expired counts.
   275         */
   276        UInt64 getExpiredCounts64();
   277    
   278    internal:   /* not for client use */
   279    
   280        /*
   281         *  ======== noStartupNeeded ========
   282         *  Flag used to prevent misc code from being brought in
   283         *  un-necessarily
   284         */
   285        config UInt startupNeeded = false;
   286    
   287        /*! Information about timer */
   288        struct TimerDevice {
   289            UInt intNum;
   290            Ptr  baseAddr;
   291        };
   292    
   293        /*!
   294         *  ======== numTimerDevices ========
   295         *  The number of logical timers on a device.
   296         */
   297        config Int numTimerDevices;
   298    
   299        /*!
   300         *  ======== WRALLOW ========
   301         *  Write protection register for critical registers;
   302         */
   303        config Ptr WRALLOW = null;
   304    
   305        /*!
   306         *  ======== disableStellaris ========
   307         */
   308        Void disableStellaris(Int id);
   309    
   310        /*!
   311         *  ======== enableStellaris ========
   312         */
   313        Void enableStellaris(Int id);
   314    
   315        /*
   316         *  ======== initDevice ========
   317         *  reset timer to its resting state
   318         */
   319        Void initDevice(Object *timer);
   320    
   321        /*
   322         *  ======== postInit ========
   323         *  finish initializing static and dynamic Timers
   324         */
   325        Int postInit(Object *timer, Error.Block *eb);
   326    
   327        /*
   328         *  ======== enableTimers ========
   329         *  enable timer register access
   330         *  called as a Startup.firstFxnw
   331         */
   332        Void enableTimers();
   333    
   334        struct Instance_State {
   335            Bool            staticInst;
   336            Int             id;
   337            RunMode         runMode;
   338            StartMode       startMode;
   339            UInt            period;
   340            PeriodType      periodType;
   341            UInt            intNum;
   342            UArg            arg;
   343            Hwi.FuncPtr     tickFxn;
   344            Types.FreqHz    extFreq;        /* external frequency in Hz */
   345            Hwi.Handle      hwi;
   346        }
   347    
   348        struct Module_State {
   349            UInt            availMask;      /* available peripherals */
   350            TimerDevice     device[];       /* timer device information */
   351            Handle          handles[];      /* array of handles based on id */
   352        }
   353    }
   354