1    /*
     2     * Copyright (c) 2015, 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.arp32;
    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.arp32.Hwi;
    46    
    47    /*!
    48     *  ======== Timer ========
    49     *  Timer Peripherals Manager.
    50     *
    51     *  The timers used are the two CTM timers (0 and 1)
    52     *  that support interrupts.
    53     *
    54     *  @p(html)
    55     *  <h3> Calling Context </h3>
    56     *  <table border="1" cellpadding="3">
    57     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    58     *
    59     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    60     *    <!--                                                                                                                 -->
    61     *    <tr><td> {@link #getNumTimers}            </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    62     *    <tr><td> {@link #getStatus}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    63     *    <tr><td> {@link #Params_init}             </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    64     *    <tr><td> {@link #construct}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    65     *    <tr><td> {@link #create}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    66     *    <tr><td> {@link #delete}                  </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    67     *    <tr><td> {@link #destruct}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    68     *    <tr><td> {@link #getCount}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    69     *    <tr><td> {@link #getFreq}                 </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    70     *    <tr><td> {@link #getPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    71     *    <tr><td> {@link #reconfig}                </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    72     *    <tr><td> {@link #setPeriod}               </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    73     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    74     *    <tr><td> {@link #start}                   </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    75     *    <tr><td> {@link #stop}                    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td><td>   -    </td></tr>
    76     *    <tr><td colspan="6"> Definitions: <br />
    77     *       <ul>
    78     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    79     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    80     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    81     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    82     *           <ul>
    83     *             <li> In your module startup after this module is started (e.g. Cache_Module_startupDone() returns TRUE). </li>
    84     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    85     *             <li> During main().</li>
    86     *             <li> During BIOS.startupFxns.</li>
    87     *           </ul>
    88     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    89     *           <ul>
    90     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    91     *             <li> In your module startup before this module is started (e.g. Cache_Module_startupDone() returns FALSE).</li>
    92     *           </ul>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     */
    99    @ModuleStartup          /* to configure static timers */
   100    @InstanceInitStatic
   101    
   102    module Timer inherits ti.sysbios.interfaces.ITimer
   103    {
   104        /*! Max value of Timer period for PeriodType_COUNTS*/
   105        const UInt MAX_PERIOD = 0xffffffff;
   106    
   107        /*!
   108         *  Number of timer peripherals on chip
   109         *
   110         *  Only 2 are available to each core.
   111         */
   112        const Int NUM_TIMER_DEVICES = 2;
   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;      /* available 32-bit timer halves */
   144        }
   145    
   146        /*! @_nodoc */
   147        metaonly struct DeviceView {
   148            UInt        id;
   149            String      device;
   150            String      devAddr;
   151            UInt        intNum;
   152            String      runMode;
   153            UInt        period;
   154            UInt        currCount;
   155            UInt        remainingCount;
   156        };
   157    
   158        /*! @_nodoc */
   159        @Facet
   160        metaonly config ViewInfo.Instance rovViewInfo =
   161            ViewInfo.create({
   162                viewMap: [
   163                [
   164                    'Basic',
   165                    {
   166                        type: ViewInfo.INSTANCE,
   167                        viewInitFxn: 'viewInitBasic',
   168                        structName: 'BasicView'
   169                    }
   170                ],
   171                [
   172                    'Device',
   173                    {
   174                        type: ViewInfo.INSTANCE,
   175                        viewInitFxn: 'viewInitDevice',
   176                        structName: 'DeviceView'
   177                    }
   178                ],
   179                [
   180                    'Module',
   181                    {
   182                        type: ViewInfo.MODULE,
   183                        viewInitFxn: 'viewInitModule',
   184                        structName: 'ModuleView'
   185                    }
   186                ],
   187                ]
   188            });
   189    
   190        /*!
   191         *  Error raised when timer id specified is not supported.
   192         */
   193        config Error.Id E_invalidTimer  = {msg: "E_invalidTimer: Invalid Timer Id %d"};
   194    
   195        /*!
   196         *  Error raised when timer requested is in use
   197         */
   198        config Error.Id E_notAvailable  =
   199                {msg: "E_notAvailable: Timer not available %d"};
   200    
   201        /*!
   202         *  Error raised when period requested is not supported
   203         */
   204        config Error.Id E_cannotSupport  =
   205                {msg: "E_cannotSupport: Timer cannot support requested period %d"};
   206    
   207        /*!
   208         *  ======== anyMask ========
   209         *  Available mask to be used when select = Timer_ANY
   210         */
   211        config UInt anyMask = 0x3;
   212    
   213        /*!
   214         *  ======== getHandle ========
   215         *  Get Handle associated with a timer id.
   216         *
   217         *  @param(id)      timer Id.
   218         *  @b(returns)     timer Handle
   219         */
   220        Handle getHandle(UInt id);
   221    
   222    instance:
   223    
   224        /*! Hwi Params for Hwi Object. Default is null. */
   225        config Hwi.Params *hwiParams = null;
   226    
   227        /*!
   228         *  ======== reconfig ========
   229         *  Used to modify static timer instances at runtime.
   230         *
   231         *  @param(timerParams)     timer Params
   232         *  @param(tickFxn)         function that runs when timer expires
   233         */
   234        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   235    
   236    
   237    internal:   /* not for client use */
   238    
   239        /*!
   240         *  ======== noStartupNeeded ========
   241         *  Flag used to prevent misc code from being brought in
   242         *  un-necessarily
   243         */
   244        config UInt startupNeeded = false;
   245    
   246        /*
   247         *  ======== postInit ========
   248         */
   249        Int postInit(Object *timer, Error.Block *eb);
   250    
   251        /*
   252         *  ======== checkOverflow ========
   253         */
   254        Bool checkOverflow(UInt32 a, UInt32 b);
   255    
   256        /*
   257         *  ======== Timer_initDevice ========
   258         */
   259        Void initDevice(Object *obj);
   260    
   261        struct Instance_State {
   262            Bool        staticInst;
   263            Int         id;
   264            Int         ctmid;          /* CTM counter ID */
   265            RunMode     runMode;
   266            StartMode   startMode;
   267            UInt        period;
   268            PeriodType  periodType;
   269            UInt        intNum;
   270            UArg        arg;
   271            Hwi.FuncPtr tickFxn;
   272            Types.FreqHz extFreq;       /* external frequency in Hz */
   273            Hwi.Handle  hwi;
   274        }
   275    
   276        struct Module_State {
   277            UInt    availMask;                  /* available peripherals */
   278            UInt    *baseAddr;                  /* add this here to make it work */
   279            Handle  handles[NUM_TIMER_DEVICES]; /* array of handles based on id */
   280        }
   281    }