1    /*
     2     * Copyright (c) 2018, 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.v8m;
    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    
    46    
    47    /*!
    48     *  ======== Timer ========
    49     *  Cortex V8M Timer Peripherals Manager.
    50     *
    51     *  The Cortex V8M Timer Manager utilizes the V8M's internal NVIC SysTick Timer.
    52     *  The SysTick timer is clocked at the CPU clock rate.
    53     *  The SysTick timer has only 24 bits of period resolution.
    54     *
    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 = 0x00ffffff;
   108    
   109        /*! Number of timer peripherals on chip */
   110        const Int NUM_TIMER_DEVICES = 1;
   111    
   112        /*! Timer clock divider wrt cpu clock */
   113        const Int TIMER_CLOCK_DIVIDER = 1;
   114    
   115        /*! @_nodoc
   116         *  Min instructions to use in trigger().
   117         */
   118        const Int MIN_SWEEP_PERIOD = 1;
   119    
   120        /*! @_nodoc */
   121        @XmlDtd
   122        metaonly struct BasicView {
   123            Ptr         halTimerHandle;
   124            String      label;
   125            UInt        id;
   126            String      device;
   127            String      startMode;
   128            String      runMode;
   129            UInt        period;
   130            String      periodType;
   131            UInt        intNum;
   132            String      tickFxn[];
   133            UArg        arg;
   134            String      extFreq;
   135            String      hwiHandle;
   136        };
   137    
   138    
   139        /*! @_nodoc */
   140        metaonly struct ModuleView {
   141            String      availMask;
   142            UInt        tickCount;
   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        };
   156    
   157        /*! @_nodoc */
   158        @Facet
   159        metaonly config ViewInfo.Instance rovViewInfo =
   160            ViewInfo.create({
   161                viewMap: [
   162                [
   163                    'Basic',
   164                    {
   165                        type: ViewInfo.INSTANCE,
   166                        viewInitFxn: 'viewInitBasic',
   167                        structName: 'BasicView'
   168                    }
   169                ],
   170                [
   171                    'Device',
   172                    {
   173                        type: ViewInfo.INSTANCE,
   174                        viewInitFxn: 'viewInitDevice',
   175                        structName: 'DeviceView'
   176                    }
   177                ],
   178                [
   179                    'Module',
   180                    {
   181                        type: ViewInfo.MODULE,
   182                        viewInitFxn: 'viewInitModule',
   183                        structName: 'ModuleView'
   184                    }
   185                ],
   186                ]
   187            });
   188        /*!
   189    
   190         *  Error raised when timer id specified is not supported.
   191         */
   192        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   193    
   194        /*!
   195         *  Error raised when timer requested is in use
   196         */
   197        config Error.Id E_notAvailable  =
   198            {msg: "E_notAvailable: Timer not available %d"};
   199    
   200        /*!
   201         *  Error raised when period requested is not supported
   202         */
   203        config Error.Id E_cannotSupport  =
   204            {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   205    
   206        /*!
   207         *  ======== anyMask ========
   208         *  Available mask to be used when select = Timer_ANY
   209         */
   210        config UInt anyMask = 0x1;
   211    
   212        /*!
   213         *  ======== getHandle ========
   214         *  @_nodoc
   215         *  Used by TimestampProvider module to get hold of timer handle.
   216         *
   217         *  @param(id)      timer Id.
   218         */
   219        Handle getHandle(UInt id);
   220    
   221        /*!
   222         *  ======== getTickCount ========
   223         *  @_nodoc
   224         *  Used by TimestampProvider.
   225         */
   226        UInt32 getTickCount();
   227    
   228    instance:
   229    
   230        /*! Hwi Params for Hwi Object. Default is null. */
   231        config Hwi.Params *hwiParams = null;
   232    
   233        /*!
   234         *  ======== reconfig ========
   235         *  Used to modify static timer instances at runtime.
   236         *
   237         *  @param(timerParams)     timer Params
   238         *  @param(tickFxn)         function that runs when timer expires
   239         */
   240        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   241    
   242    
   243    internal:   /* not for client use */
   244    
   245        metaonly config Bool timerInUse = false;
   246    
   247        /*
   248         *  ======== initDevice ========
   249         *  reset timer to its resting state
   250         */
   251        Void initDevice(Object *timer);
   252    
   253        /*
   254         *  ======== postInit ========
   255         *  finish initializing static and dynamic Timers
   256         */
   257        Int postInit(Object *timer, Error.Block *eb);
   258    
   259        /*!
   260         *  ======== oneShotStub ========
   261         *  SysTick timer does not support one shot mode. This stub stops timer
   262         *  and clears the pending timer interrupt.
   263         *
   264         *  @param(arg)     Timer object.
   265         */
   266        Void oneShotStub(UArg arg);
   267    
   268        /*!
   269         *  ======== periodicStub ========
   270         *  SysTick timer interrupt must be acknowledged. This stub acknowledges timer
   271         *
   272         *  @param(arg)     Timer object.
   273         */
   274        Void periodicStub(UArg arg);
   275    
   276        /*!
   277         *  ======== noStartupNeeded ========
   278         *  Flag used to prevent misc code from being brought in
   279         *  un-necessarily
   280         */
   281        config UInt startupNeeded = false;
   282    
   283        struct Instance_State {
   284            Bool            staticInst;
   285            Int             id;
   286            RunMode         runMode;
   287            StartMode       startMode;
   288            UInt            period;
   289            PeriodType      periodType;
   290            UInt            intNum;
   291            UArg            arg;
   292            Hwi.FuncPtr     tickFxn;
   293            Types.FreqHz    extFreq;        /* external frequency in Hz */
   294            Hwi.Handle      hwi;
   295        }
   296    
   297        struct Module_State {
   298            volatile UInt   tickCount;      /* SysTick Rollover counter */
   299            UInt            availMask;      /* available peripherals */
   300            Handle          handle;         /* NVIC timer handle */
   301        }
   302    }
   303