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.ducati;
    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     *  Ducati Cortex M3 Timer Peripherals Manager.
    50     *
    51     *  The timers used in Ducati are the NVIC SysTick timer
    52     *  and the two CTM timers (0 and 1) that support interrupts.
    53     *  The CTM timers are shared between the two M3 cores.
    54     *  Core 0 uses CTM timer 0 and Core 1 uses timer 1.
    55     *  Each core then supports 2 timers.
    56     *  Timer 0 is the core's SysTick timer
    57     *  and Timer 1 is the core's CTM timer.
    58     *  Both timers are clocked at the CPU clock rate, nominally 200MHz.
    59     *  Timer 0 (the SysTick timer) has only 24 bits of period resolution
    60     *  (up to 83ms).
    61     *  Timer 1 (the CTM timer) supports a full 32 bit period
    62     *  (up to 21 seconds).
    63     *
    64     *  @p(html)
    65     *  <h3> Calling Context </h3>
    66     *  <table border="1" cellpadding="3">
    67     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    68     *
    69     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    70     *    <!--                                                                                                                 -->
    71     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    74     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    75     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    76     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    77     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    78     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    79     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    80     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    81     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    82     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    83     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    84     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    85     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    86     *    <tr><td colspan="6"> Definitions: <br />
    87     *       <ul>
    88     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    89     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    90     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    91     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    92     *           <ul>
    93     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    94     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    95     *             <li> During main().</li>
    96     *             <li> During BIOS.startupFxns.</li>
    97     *           </ul>
    98     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    99     *           <ul>
   100     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   101     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
   102     *           </ul>
   103     *       </ul>
   104     *    </td></tr>
   105     *
   106     *  </table>
   107     *  @p
   108     */
   109    @ModuleStartup          /* to configure static timers */
   110    @InstanceInitStatic
   111    
   112    module Timer inherits ti.sysbios.interfaces.ITimer
   113    {
   114        /*! Max value of Timer period for PeriodType_COUNTS*/
   115        const UInt MAX_PERIOD = 0xffffffff;
   116    
   117        /*!
   118         *  Number of timer peripherals on chip
   119         *
   120         *  Only 2 are available to each core.
   121         */
   122        const Int NUM_TIMER_DEVICES = 2;
   123    
   124        /*! Timer clock divider wrt cpu clock */
   125        const Int TIMER_CLOCK_DIVIDER = 1;
   126    
   127        /*! @_nodoc
   128         *  Min instructions to use in trigger().
   129         */
   130        const Int MIN_SWEEP_PERIOD = 1;
   131    
   132        /*! @_nodoc */
   133        @XmlDtd
   134        metaonly struct BasicView {
   135            Ptr         halTimerHandle;
   136            String      label;
   137            UInt        id;
   138            String      device;
   139            String      startMode;
   140            String      runMode;
   141            UInt        period;
   142            String      periodType;
   143            UInt        intNum;
   144            String      tickFxn[];
   145            UArg        arg;
   146            String      extFreq;
   147            String      hwiHandle;
   148        };
   149    
   150    
   151        /*! @_nodoc */
   152        metaonly struct ModuleView {
   153            String      availMask;      /* available 32-bit timer halves */
   154        }
   155    
   156        /*! @_nodoc */
   157        metaonly struct DeviceView {
   158            UInt        id;
   159            String      device;
   160            String      devAddr;
   161            UInt        intNum;
   162            String      runMode;
   163            UInt        period;
   164            UInt        currCount;
   165            UInt        remainingCount;
   166        };
   167    
   168        /*! @_nodoc */
   169        @Facet
   170        metaonly config ViewInfo.Instance rovViewInfo =
   171            ViewInfo.create({
   172                viewMap: [
   173                [
   174                    'Basic',
   175                    {
   176                        type: ViewInfo.INSTANCE,
   177                        viewInitFxn: 'viewInitBasic',
   178                        structName: 'BasicView'
   179                    }
   180                ],
   181                [
   182                    'Device',
   183                    {
   184                        type: ViewInfo.INSTANCE,
   185                        viewInitFxn: 'viewInitDevice',
   186                        structName: 'DeviceView'
   187                    }
   188                ],
   189                [
   190                    'Module',
   191                    {
   192                        type: ViewInfo.MODULE,
   193                        viewInitFxn: 'viewInitModule',
   194                        structName: 'ModuleView'
   195                    }
   196                ],
   197                ]
   198            });
   199    
   200        /*!
   201         *  Error raised when timer id specified is not supported.
   202         */
   203        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   204    
   205        /*!
   206         *  Error raised when timer requested is in use
   207         */
   208        config Error.Id E_notAvailable  =
   209            {msg: "E_notAvailable: Timer not available %d"};
   210    
   211        /*!
   212         *  Error raised when period requested is not supported
   213         */
   214        config Error.Id E_cannotSupport  =
   215            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   216    
   217        /*!
   218         *  ======== anyMask ========
   219         *  Available mask to be used when select = Timer_ANY
   220         */
   221        config UInt anyMask = 0x3;
   222    
   223        /*!
   224         *  ======== getHandle ========
   225         *  Get Handle associated with a timer id.
   226         *
   227         *  @param(id)      timer Id.
   228         *  @b(returns)     timer Handle
   229         */
   230        Handle getHandle(UInt id);
   231    
   232        /*!
   233         *  ======== oneShotStub ========
   234         *  @_nodoc
   235         *  SysTick timer does not support one shot mode. This stub stops timer
   236         *  and clears the pending timer interrupt.
   237         *
   238         *  @param(arg)     Timer object.
   239         */
   240        Void oneShotStub(UArg arg);
   241    
   242        /*!
   243         *  ======== periodicStub ========
   244         *  @_nodoc
   245         *  SysTick timer interrupt must be acknowledged. This stub acknowledges timer
   246         *
   247         *  @param(arg)     Timer object.
   248         */
   249        Void periodicStub(UArg arg);
   250    
   251    instance:
   252    
   253        /*! Hwi Params for Hwi Object. Default is null. */
   254        config Hwi.Params *hwiParams = null;
   255    
   256        /*!
   257         *  ======== reconfig ========
   258         *  Used to modify static timer instances at runtime.
   259         *
   260         *  @param(timerParams)     timer Params
   261         *  @param(tickFxn)         function that runs when timer expires
   262         */
   263        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   264    
   265    
   266    internal:   /* not for client use */
   267    
   268        /*!
   269         *  ======== noStartupNeeded ========
   270         *  Flag used to prevent misc code from being brought in
   271         *  un-necessarily
   272         */
   273        config UInt startupNeeded = false;
   274    
   275        /*
   276         *  ======== initDevice ========
   277         *  reset timer to its resting state
   278         */
   279        Void initDevice(Object *timer);
   280    
   281        /*
   282         *  ======== postInit ========
   283         *  finish initializing static and dynamic Timers
   284         */
   285        Int postInit(Object *timer, Error.Block *eb);
   286    
   287        struct Instance_State {
   288            Bool            staticInst;
   289            Int             id;
   290            Int             ctmid;          /* CTM counter ID */
   291            RunMode         runMode;
   292            StartMode       startMode;
   293            UInt            period;
   294            PeriodType      periodType;
   295            UInt            intNum;
   296            UArg            arg;
   297            Hwi.FuncPtr     tickFxn;
   298            Types.FreqHz    extFreq;        /* external frequency in Hz */
   299            Hwi.Handle      hwi;
   300        }
   301    
   302        struct Module_State {
   303            UInt            availMask;      /* available peripherals */
   304            Handle          handles[NUM_TIMER_DEVICES];
   305                                            /* array of handles based on id */
   306        }
   307    }
   308