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    package ti.sysbios.family.arm.a9;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    import xdc.runtime.Error;
    41    import xdc.runtime.Types;
    42    
    43    import ti.sysbios.family.arm.gic.Hwi;
    44    import ti.sysbios.interfaces.ITimer;
    45    
    46    /*!
    47     *  ======== Timer ========
    48     *  Cortex A9 Timer Peripheral Manager
    49     *
    50     *  The Cortex A9 Timer Peripheral Manager utilizes the A9's internal Private
    51     *  Timer. The A9 Private Timer is clocked at half the CPU clock rate. The
    52     *  A9 Private Timer has 32 bits of period resolution and the interrupt
    53     *  generated by this timer is connected to private peripheral interrupt
    54     *  number 29 on the A9's generic interrupt controller, GIC
    55     *  (see {@link ti.sysbios.family.arm.gic.Hwi}).
    56     *
    57     *  The Cortex A9
    58     *
    59     *  @p(html)
    60     *  <h3> Calling Context </h3>
    61     *  <table border="1" cellpadding="3">
    62     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    63     *
    64     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    65     *    <!--                                                                                                                 -->
    66     *    <tr><td> {@link #construct}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    67     *    <tr><td> {@link #create}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    68     *    <tr><td> {@link #delete}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    69     *    <tr><td> {@link #destruct}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #getCount}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    71     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #getPrescale}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #setPrescale}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #start}                   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #stop}                    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    83     *    <tr><td colspan="6"> Definitions: <br />
    84     *       <ul>
    85     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    86     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    87     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    88     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    89     *           <ul>
    90     *             <li> In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE). </li>
    91     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    92     *             <li> During main().</li>
    93     *             <li> During BIOS.startupFxns.</li>
    94     *           </ul>
    95     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    96     *           <ul>
    97     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    98     *             <li> In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).</li>
    99     *           </ul>
   100     *       </ul>
   101     *    </td></tr>
   102     *
   103     *  </table>
   104     *  @p
   105     *
   106     */
   107    @ModuleStartup          /* to configure static timers */
   108    @InstanceInitStatic
   109    
   110    module Timer inherits ti.sysbios.interfaces.ITimer
   111    {
   112        /*! 
   113         *  Max value of Timer period for PeriodType_COUNTS
   114         */
   115        const UInt32 MAX_PERIOD = 0xFFFFFFFF;
   116    
   117        /*! Number of timer peripherals on chip */
   118        const Int NUM_TIMER_DEVICES = 1;
   119    
   120        /*! @_nodoc */
   121        @XmlDtd
   122        metaonly struct BasicView {
   123            Ptr         halTimerHandle;
   124            String      label;
   125            String      startMode;
   126            String      runMode;
   127            String      period;
   128            String      periodType;
   129            String      prescale;
   130            UInt        intNum;
   131            String      tickFxn[];
   132            UArg        arg;  
   133            String      extFreq;
   134            String      hwiHandle;
   135        };
   136    
   137        /*! @_nodoc */
   138        metaonly struct DeviceView {
   139            String      deviceAddr;
   140            UInt        intNum;
   141            String      period;
   142            String      currCount;
   143            String      remainingCount;
   144            String      prescale;
   145        }
   146    
   147        /*! @_nodoc */
   148        @Facet
   149        metaonly config ViewInfo.Instance rovViewInfo = 
   150            ViewInfo.create({
   151                viewMap: [
   152                [
   153                    'Basic',
   154                    {
   155                        type: ViewInfo.INSTANCE,
   156                        viewInitFxn: 'viewInitBasic',
   157                        structName: 'BasicView'
   158                    }
   159                ],
   160                [
   161                    'Device',
   162                    {
   163                        type: ViewInfo.INSTANCE,
   164                        viewInitFxn: 'viewInitDevice',
   165                        structName: 'DeviceView'
   166                    }
   167                ],
   168                ]
   169            });
   170    
   171        /*! 
   172         *  Error raised when timer id specified is not supported.
   173         */
   174        config Error.Id E_invalidTimer  = 
   175            {msg: "E_invalidTimer: Invalid Timer Id %d"}; 
   176    
   177        /*! 
   178         *  Error raised when timer requested is in use
   179         */
   180        config Error.Id E_notAvailable  = 
   181            {msg: "E_notAvailable: Timer not available %d"}; 
   182    
   183        /*! 
   184         *  Error raised when period requested is not supported
   185         */
   186        config Error.Id E_cannotSupport  = 
   187            {msg: "E_cannotSupport: Timer cannot support requested period %d"}; 
   188    
   189        /*!
   190         *  ======== intNumDef ========
   191         *  A9 Private Timer Interrupt number
   192         * 
   193         *  A9 Private Timer Interrupt is forwarded to GIC's private peripheral
   194         *  interrupt and has a architecture defined fixed mapping that should
   195         *  be same across all A9 variants.
   196         *
   197         *  Private Timer -> PPI1 or Interrupt #29
   198         */
   199        config UInt intNumDef;
   200    
   201        /*!
   202         *  @_nodoc
   203         *  ======== anyMask ========
   204         *  Available mask to be used when select = Timer_ANY
   205         */
   206        config UInt anyMask = 0x1;
   207    
   208        /*!
   209         *  @_nodoc
   210         *  ======== availMask ========
   211         *  Available mask tracks the available/free timer peripherals
   212         */
   213        config UInt availMask = 0x1;
   214    
   215        /*!
   216         *  @_nodoc
   217         *  Private timer registers. Symbol "Timer_deviceRegs" is a
   218         *  physical device.
   219         */
   220        struct DeviceRegs {
   221            UInt32 LOAD;
   222            UInt32 COUNTER;
   223            UInt32 CONTROL;
   224            UInt32 INTSTATUS;
   225        };
   226    
   227        extern volatile DeviceRegs deviceRegs;
   228    
   229        /*!
   230         *  @_nodoc
   231         *  ======== stub ========
   232         *  This stub is used to acknowledge a Timer interrupt.
   233         *
   234         *  @param(arg)     Timer Handle.
   235         */
   236        Void stub(UArg arg);
   237    
   238        /*!
   239         *  @_nodoc
   240         *  ======== getHandle ========
   241         *  Used by TimestampProvider module to get hold of timer handle used by 
   242         *  Clock.
   243         *
   244         *  @param(id)      timer Id.
   245         */
   246        Handle getHandle(UInt id);
   247    
   248    instance:
   249    
   250        /*! Hwi Params for Hwi Object. Default is null.*/
   251        config Hwi.Params *hwiParams = null;
   252    
   253        /*!
   254         *  ======== prescale ========
   255         *  Prescale factor.
   256         *
   257         *  The Prescale factor can be used to achieve longer timer periods.
   258         *  With a prescale factor specified, the actual timer period is
   259         *  period * (prescale + 1).
   260         */
   261        config UInt8 prescale = 0;
   262    
   263        /*!
   264         *  ======== reconfig ========
   265         *  Used to modify static timer instances at runtime.
   266         *
   267         *  @param(timerParams)     timer Params
   268         *  @param(tickFxn)         functions that runs when timer expires.
   269         */
   270        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   271    
   272        /*!
   273         *  ======== setPrescale ========
   274         *  Set timer prescale value.
   275         *
   276         *  This function sets the value of the prescaler, and will also reload
   277         *  the timer counter and prescale registers.
   278         *
   279         *  @param(preScaler)       prescale value
   280         */
   281        Void setPrescale(UInt8 preScaler);
   282    
   283        /*!
   284         *  ======== getPrescale ========
   285         *  Get timer prescale value.
   286         *
   287         *  @b(returns)             prescale value
   288         */
   289        UInt8 getPrescale();
   290    
   291    internal:   /* not for client use */
   292       
   293        /*!
   294         *  ======== startupNeeded ========
   295         *  Flag used to prevent misc code from being brought in
   296         *  un-necessarily
   297         */
   298        config Bool startupNeeded = false;
   299    
   300        /*!
   301         *  ======== privTimerRegBaseAddress ========
   302         *  Cortex-A9 Private Timer Register base address
   303         */
   304        metaonly config Ptr privTimerRegBaseAddress;
   305    
   306        /*
   307         *  ======== initDevice ========
   308         *  reset timer to its resting state
   309         */
   310        Void initDevice(Object *timer);
   311    
   312        /*
   313         *  ======== postInit ========
   314         *  finish initializing static and dynamic Timers
   315         */
   316        Int postInit(Object *timer, Error.Block *eb);
   317    
   318        /*
   319         *  ======== checkOverflow ========
   320         */
   321        Bool checkOverflow(UInt32 a, UInt32 b);
   322    
   323        struct Instance_State {
   324            Bool                staticInst;
   325            ITimer.RunMode      runMode;    
   326            ITimer.StartMode    startMode;
   327            UInt32              period;
   328            ITimer.PeriodType   periodType;    
   329            UInt                intNum;
   330            UInt8               prescale;
   331            UArg                arg;  
   332            Hwi.FuncPtr         tickFxn;
   333            Types.FreqHz        extFreq;
   334            Hwi.Handle          hwi;
   335        }
   336    
   337        struct Module_State {
   338            UInt                availMask;  /* available peripherals */
   339            Handle              handle;     /* timer handle */
   340        }
   341    }