1    /* 
     2     * Copyright (c) 2012, 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    @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        /*! Max value of Timer period for PeriodType_COUNTS*/
   108        const UInt MAX_PERIOD = 0xffffffff;
   109    
   110        /*! Timer clock divider wrt cpu clock */
   111        const Int TIMER_CLOCK_DIVIDER = 1;
   112    
   113        /*! @_nodoc
   114         *  Min instructions to use in trigger(). 
   115         */
   116        const Int MIN_SWEEP_PERIOD = 1;
   117    
   118        /*! @_nodoc */
   119        @XmlDtd
   120        metaonly struct BasicView {
   121            Ptr         halTimerHandle;
   122            String      label;
   123            UInt        id;
   124            String      device;
   125            String      startMode;
   126            String      runMode;
   127            UInt        period;
   128            String      periodType;
   129            UInt        intNum;
   130            String      tickFxn[];
   131            UArg        arg;
   132            String      extFreq;
   133            String      hwiHandle;
   134        };
   135    
   136    
   137        /*! @_nodoc */
   138        metaonly struct ModuleView {
   139            String      availMask;      /* available 32-bit timer halves */
   140        }
   141    
   142        /*! @_nodoc */
   143        metaonly struct DeviceView {
   144            UInt        id;
   145            String      device;
   146            String      devAddr;
   147            UInt        intNum;
   148            String      runMode;
   149            UInt        period;
   150            UInt        currCount;
   151            UInt        remainingCount;
   152            String      state;
   153        };
   154    
   155        /*! @_nodoc */
   156        @Facet
   157        metaonly config ViewInfo.Instance rovViewInfo = 
   158            ViewInfo.create({
   159                viewMap: [
   160                [
   161                    'Basic',
   162                    {
   163                        type: ViewInfo.INSTANCE,
   164                        viewInitFxn: 'viewInitBasic',
   165                        structName: 'BasicView'
   166                    }
   167                ],
   168                [
   169                    'Device',
   170                    {
   171                        type: ViewInfo.INSTANCE,
   172                        viewInitFxn: 'viewInitDevice',
   173                        structName: 'DeviceView'
   174                    }
   175                ],
   176                [
   177                    'Module',
   178                    {
   179                        type: ViewInfo.MODULE,
   180                        viewInitFxn: 'viewInitModule',
   181                        structName: 'ModuleView'
   182                    }
   183                ],
   184                ]
   185            });
   186    
   187        /*! 
   188         *  Error raised when timer id specified is not supported.
   189         */
   190        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"}; 
   191    
   192        /*! 
   193         *  Error raised when timer requested is in use
   194         */
   195        config Error.Id E_notAvailable  = 
   196            {msg: "E_notAvailable: Timer not available %d"}; 
   197    
   198        /*! 
   199         *  Error raised when period requested is not supported
   200         */
   201        config Error.Id E_cannotSupport  = 
   202            {msg: "E_cannotSupport: Timer cannot support requested period %d"}; 
   203    
   204        /*!
   205         *  ======== anyMask ========
   206         *  Available mask to be used when select = Timer_ANY
   207         */
   208        config UInt anyMask = 0x3;
   209    
   210        /*!
   211         *  ======== getHandle ========
   212         *  Get Handle associated with a timer id.
   213         *
   214         *  @param(id)      timer Id.
   215         *  @b(returns)     timer Handle
   216         */
   217        @DirectCall
   218        Handle getHandle(UInt id);
   219    
   220        /*!
   221         *  ======== isrStub ========
   222         *  @_nodoc
   223         *  Timer interrupts must be acknowledged
   224         *
   225         *  @param(arg)     Timer object.
   226         */
   227        @DirectCall
   228        Void isrStub(UArg arg);
   229    
   230    instance:
   231    
   232        /*! Hwi Params for Hwi Object. Default is null. */
   233        config Hwi.Params *hwiParams = null;
   234    
   235        /*!
   236         *  ======== reconfig ========
   237         *  Used to modify static timer instances at runtime.
   238         *
   239         *  @param(timerParams)     timer Params
   240         *  @param(tickFxn)         function that runs when timer expires
   241         */
   242        @DirectCall
   243        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   244    
   245    
   246    internal:   /* not for client use */
   247    
   248        /*
   249         *  ======== noStartupNeeded ========
   250         *  Flag used to prevent misc code from being brought in
   251         *  un-necessarily
   252         */
   253        config UInt startupNeeded = false;
   254    
   255        /*! Information about timer */
   256        struct TimerDevice {
   257            UInt intNum;
   258            Ptr  baseAddr;
   259        };
   260    
   261        /*!
   262         *  ======== numTimerDevices ========
   263         *  The number of logical timers on a device.
   264         */
   265        config Int numTimerDevices;
   266    
   267        /*!
   268         *  ======== WRALLOW ========
   269         *  Write protection register for critical registers;
   270         */
   271        config Ptr WRALLOW = null;
   272    
   273        /*
   274         *  ======== enableTimers ========
   275         *  enable timer register access
   276         *  called as a Startup.firstFxnw
   277         */
   278        Void enableTimers();
   279    
   280        struct Instance_State {
   281            Bool            staticInst;
   282            Int             id;
   283            RunMode         runMode;    
   284            StartMode       startMode;
   285            UInt            period; 
   286            PeriodType      periodType;    
   287            UInt            intNum;
   288            UArg            arg;  
   289            Hwi.FuncPtr     tickFxn;
   290            Types.FreqHz    extFreq;        /* external frequency in Hz */
   291            Hwi.Handle      hwi;
   292        }
   293    
   294        struct Module_State {
   295            UInt            availMask;      /* available peripherals */
   296            TimerDevice     device[];       /* timer device information */
   297            Handle          handles[];      /* array of handles based on id */
   298        }
   299    }
   300    
   301    /*
   302     *  @(#) ti.sysbios.family.arm.lm3; 2, 0, 0, 0,220; 2-24-2012 11:39:36; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   303    
   304     */
   305