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