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