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    
    38    package ti.sysbios.timers.gptimer;
    39    
    40    import xdc.rov.ViewInfo;
    41    
    42    import xdc.runtime.Error;
    43    import xdc.runtime.Types;
    44    import ti.sysbios.interfaces.ITimer;
    45    import ti.sysbios.hal.Hwi;
    46    
    47    /*!
    48     *  ======== Timer ========
    49     *  Timer Peripheral Manager.
    50     *
    51     *  This Timer module manages the general purpose timer (gptimer) peripherals
    52     *  available on the ARM and C6000 devices (see
    53     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables} for supported
    54     *  device information).
    55     *
    56     *  The gptimer Timer  module supports the timer in 'one shot' and 'continuous'
    57     *  modes.
    58     *
    59     *  In 'one shot' mode, a timer function will "fire" (run) when the timer period
    60     *  expires (counts down to zero). In 'one shot' mode this will only happen
    61     *  once.  In 'continuous' mode, the specified timer function will "fire" every
    62     *  time the period expires, throughout the lifetime of the program.  When the
    63     *  period expires in 'continuous mode', the period is then reset to its
    64     *  original value and then begins counting down to zero again.  At this point
    65     *  the timer function will fire again and the cycle repeats itself.
    66     *
    67     *  @p(html)
    68     *  <h3> Calling Context </h3>
    69     *  <table border="1" cellpadding="3">
    70     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    71     *    </colgroup>
    72     *
    73     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th>
    74     *    <th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    75     *    <!--                                    -->
    76     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td>
    77     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td>
    79     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    80     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td>
    81     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    82     *    <tr><td> {@link #construct}               </td><td>   Y    </td>
    83     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    84     *    <tr><td> {@link #create}                  </td><td>   N    </td>
    85     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    86     *    <tr><td> {@link #delete}                  </td><td>   N    </td>
    87     *    <td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    88     *    <tr><td> {@link #destruct}                </td><td>   Y    </td>
    89     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    90     *    <tr><td> {@link #getCount}                </td><td>   Y    </td>
    91     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    92     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td>
    93     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    94     *    <tr><td> {@link #getFunc}                 </td><td>   Y    </td>
    95     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    96     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td>
    97     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    98     *    <tr><td> {@link #reconfig}                </td><td>   Y    </td>
    99     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   100     *    <tr><td> {@link #setFunc}                 </td><td>   Y    </td>
   101     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   102     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td>
   103     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   104     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td>
   105     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
   106     *    <tr><td> {@link #start}                   </td><td>   Y    </td>
   107     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   108     *    <tr><td> {@link #stop}                    </td><td>   Y    </td>
   109     *    <td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
   110     *    <tr><td colspan="6"> Definitions: <br />
   111     *       <ul>
   112     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
   113     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
   114     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
   115     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
   116     *           <ul>
   117     *             <li> In your module startup after this module is started 
   118     *    (e.g. Timer_Module_startupDone() returns TRUE). </li>
   119     *             <li> During xdc.runtime.Startup.lastFxns. </li>
   120     *             <li> During main().</li>
   121     *             <li> During BIOS.startupFxns.</li>
   122     *           </ul>
   123     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
   124     *           <ul>
   125     *             <li> During xdc.runtime.Startup.firstFxns.</li>
   126     *             <li> In your module startup before this module is started 
   127     *    (e.g. Timer_Module_startupDone() returns FALSE).</li>
   128     *           </ul>
   129     *       </ul>
   130     *    </td></tr>
   131     *
   132     *  </table>
   133     *  @p
   134     *
   135     *  @p(html)
   136     *  <h3> Timer Mapping Tables </h3>
   137     *  <p>
   138     *  The Timer module allows the user to use and configure the various timers
   139     *  that exist on a particular device.  This is achieved by specifying a timer
   140     *  ID when calling {@link ti.sysbios.hal.Timer#Timer_create}.
   141     *  However, the timer ID
   142     *  specified may not always map to that timer; for example, specifying an ID
   143     *  value of 1 does not necessarily mean that this will map to "GPTimer1".
   144     *  These tables are provided to show which timers map to which timer IDs.
   145     *  </p>
   146     *  {@link ./doc-files/TimerTables.html Timer Mapping Tables}
   147     *  @p
   148     *
   149     */
   150    @InstanceFinalize       /* To cleanup */
   151    @InstanceInitError      /* To report unavailability of timer */
   152    @ModuleStartup          /* to configure static timers */
   153    
   154    module Timer inherits ti.sysbios.interfaces.ITimer
   155    {
   156        /*! Max value of Timer period for PeriodType_COUNTS*/
   157        const UInt MAX_PERIOD = 0xffffffff;
   158    
   159        /*! L4 interface Configuration Register (TIOCP_CFG). */
   160        struct TiocpCfg {
   161            Bits8 autoidle;  /*! 0=L4 interface is free running; 1=Automatic */
   162            Bits8 softreset; /*! 0=normal mode; 1=soft reset */
   163            Bits8 enawakeup; /*! 0=no wakeup; 1=wake-up line assertion enabled */
   164            Bits16 idlemode; /*! 0=force-idle; 1=no-idle; 2=Smart-idle */
   165            Bits8 emufree;   /*! 0=counter frozen; 1=counter free-running */
   166            Bits16 clockactivity; /*! Clock activity during wakeup mode period */
   167        };
   168    
   169        /*! Interrupt Enable Register (TIER). */
   170        struct Tier {
   171            Bits8 mat_it_ena;  /*! Enable match interrupt */
   172            Bits8 ovf_it_ena;  /*! Enable overflow interrupt */
   173            Bits8 tcar_it_ena; /*! Enable capture interrupt */
   174        };
   175    
   176        /*! WakepUp Enable Register (TWER). */
   177        struct Twer {
   178            Bits8 mat_wup_ena;  /*! Enable match wake-up */
   179            Bits8 ovf_wup_ena;  /*! Enable overflow wake-up */
   180            Bits8 tcar_wup_ena; /*! Enable capture wake-up */
   181        };
   182    
   183        /*! Control Register (TCLR). */
   184        struct Tclr {
   185            Bits32 ptv; /*! Trigger output mode */
   186            Bits8 pre;  /*! Prescalar enable */
   187            Bits8 ce;   /*! Compare enable */
   188            Bits8 scpwm;/*! Pulse-width modulation */
   189            Bits16 tcm; /*! Transition capture mode */
   190            Bits16 trg; /*! Trigger output mode */
   191            Bits8 pt;   /*! Pulse or toggle select bit */
   192            Bits8 captmode; /*! Capture mode select bit */
   193            Bits8 gpocfg; /*! PWM output/event detection input pin */
   194        };
   195    
   196        /*! L4 Interface Synchronization Control Register (TSICR). */
   197        struct Tsicr {
   198            Bits8 sft;    /*! Reset software functional registers */
   199            Bits8 posted; /*! Posted mode selection */
   200        };
   201    
   202        /*! Timer Settings. */
   203        metaonly struct TimerSetting {
   204            Bool master;    /*! specifies whether this is the master */
   205            Ptr baseAddr;   /*! specify the base address  */
   206            Int intNum;     /*! specify which interrupt vector */
   207            String name;    /*! specify the timer name */
   208        };
   209    
   210        /*!
   211         *  ======== BasicView ========
   212         *  @_nodoc
   213         */
   214        metaonly struct BasicView {
   215            Ptr         halTimerHandle;
   216            String      label;
   217            UInt        id;
   218            String      name;
   219            String      startMode;
   220            String      runMode;
   221            UInt        period;
   222            String      periodType;
   223            UInt        intNum;
   224            String      tickFxn[];
   225            UArg        arg;
   226            String      extFreqLow;
   227            String      extFreqHigh;
   228            String      hwiHandle;
   229        };
   230    
   231    
   232        /*!
   233         *  ======== ModuleView ========
   234         *  @_nodoc
   235         */
   236        metaonly struct ModuleView {
   237            String          availMask;      /* avaliable 32-bit timer halves */
   238            String intFrequency;    /* internal frequency in Hz */
   239        }
   240    
   241        /*!
   242         *  ======== rovViewInfo ========
   243         *  @_nodoc
   244         */
   245        @Facet
   246        metaonly config ViewInfo.Instance rovViewInfo = 
   247            ViewInfo.create({
   248                viewMap: [
   249                [
   250                    'Basic',
   251                    {
   252                        type: ViewInfo.INSTANCE,
   253                        viewInitFxn: 'viewInitBasic',
   254                        structName: 'BasicView'
   255                    }
   256                ],
   257                [
   258                    'Module',
   259                    {
   260                        type: ViewInfo.MODULE,
   261                        viewInitFxn: 'viewInitModule',
   262                        structName: 'ModuleView'
   263                    }
   264                ],
   265                ]
   266            });
   267    
   268        /*!
   269         *  Error raised when timer id specified is not supported.
   270         */
   271        config Error.Id E_invalidTimer = {
   272            msg: "E_invalidTimer: Invalid Timer Id %d"
   273        };
   274    
   275        /*!
   276         *  Error raised when timer requested is in use
   277         */
   278        config Error.Id E_notAvailable  = {
   279            msg: "E_notAvailable: Timer not available %d"
   280        };
   281    
   282        /*!
   283         *  Error raised when period requested is not supported
   284         */
   285        config Error.Id E_cannotSupport = {
   286            msg: "E_cannotSupport: Timer cannot support requested period %d"
   287        };
   288    
   289        /*!
   290         *  ======== anyMask ========
   291         *  Available mask to be used when select = Timer_ANY. 
   292         *
   293         *  Default value is device specific.
   294         */
   295        config Bits32 anyMask;
   296    
   297        /*!
   298         *  ======== timerSettings ========
   299         *  Global Control configuration for each physical timer.
   300         */
   301        metaonly config TimerSetting timerSettings[] = [];
   302        
   303        /*!
   304         *  ======== intFreq ========
   305         *  Default internal timer input clock frequency.
   306         */
   307        metaonly config Types.FreqHz intFreq = {lo: 0, hi: 0};
   308        
   309        /*!
   310         *  ======== stub  ========
   311         *  @_nodoc
   312         *  Timer requires acknowledgement
   313         *
   314         *  @param(arg)     timer object passed in as argument.
   315         */
   316        @DirectCall
   317        Void stub(UArg arg);
   318    
   319    
   320    instance:
   321    
   322        /*! 
   323         *  ======== tiocpCfg ========
   324         */
   325        config TiocpCfg tiocpCfg = {autoidle: 0, softreset: 1, enawakeup: 0,
   326            idlemode: 0, emufree: 0, clockactivity: 0};
   327    
   328        /*! 
   329         *  ======== tier ========
   330         */
   331        config Tier tier = {mat_it_ena: 0, ovf_it_ena: 1, tcar_it_ena: 0};
   332    
   333        /*! 
   334         *  ======== twer ========
   335         */
   336        config Twer twer = {mat_wup_ena: 0, ovf_wup_ena: 0, tcar_wup_ena: 0};
   337    
   338        /*! 
   339         *  ======== tclr ========
   340         */
   341        config Tclr tclr = {ptv: 0, pre: 0, ce: 0, scpwm: 0, tcm: 0, trg: 0,
   342            pt: 0, captmode: 0, gpocfg: 0};
   343        
   344        /*! 
   345         *  ======== tsicr ========
   346         */
   347        config Tsicr tsicr = {sft: 0, posted: 1};
   348    
   349        /*! 
   350         *  ======== tmar ========
   351         */
   352        config UInt32 tmar = 0;
   353    
   354        /*! Hwi Params for Hwi Object. Default is null. */
   355        config Hwi.Params *hwiParams = null;
   356    
   357        /*!
   358         *  ======== reconfig ========
   359         *  Used to modify static timer instances at runtime.
   360         *
   361         *  @param(timerParams)     timer Params
   362         *  @param(tickFxn)         functions that runs when timer expires
   363         */
   364        @DirectCall
   365        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   366    
   367    
   368    internal:   /* not for client use */
   369    
   370        /*! Device-specific Timer implementation. */
   371        proxy TimerSupportProxy inherits ti.sysbios.interfaces.ITimerSupport;
   372    
   373        /*!
   374         *  ======== startupNeeded ========
   375         *  This flag is use to prevent Timer_startup code (includes postInit(),
   376         *  deviceConfig(), initDevice() to be brought in un-necessarily.
   377         */
   378        config Bool startupNeeded = false;
   379    
   380        /*! Information about timer */
   381        struct TimerDevice {
   382            UInt intNum;
   383            UInt eventId;
   384            Ptr  baseAddr;
   385        };
   386    
   387        /*!
   388         *  ======== numTimerDevices ========
   389         *  The number of logical timers on a device.
   390         */
   391        config Int numTimerDevices;
   392    
   393        /*!
   394         *  ======== spinLoop ========
   395         *  used by trigger function.
   396         */
   397        Void spinLoop(UInt count);
   398    
   399        /*! Instance state structure */
   400        struct Instance_State {
   401            Bool                    staticInst;     /* statically created or not */
   402            Int                     id;             /* logical timer id. */
   403            UInt                    tiocpCfg;
   404            UInt                    tmar;
   405            UInt                    tier;
   406            UInt                    twer;
   407            UInt                    tclr;
   408            UInt                    tsicr;
   409            ITimer.RunMode          runMode;        /* timer mode */
   410            ITimer.StartMode        startMode;      /* timer mode */
   411            UInt                    period;         /* period */
   412            ITimer.PeriodType       periodType;     /* type (microsecs, inst) */
   413            UInt                    intNum;         /* intr num */
   414            UArg                    arg;            /* isrFxn arg */
   415            Hwi.FuncPtr             tickFxn;        /* Timer fxn plugged into Hwi */
   416            Types.FreqHz            extFreq;        /* ext freq */
   417            Hwi.Handle              hwi;            /* hwi inst */
   418        }
   419    
   420        /*! Module state structure */
   421        struct Module_State {
   422            Bits32          availMask;      /* avaliable 32-bit timer halves */
   423            Types.FreqHz    intFreq;        /* internal frequency in Hz */
   424            TimerDevice     device[];       /* timer device information */
   425            Handle          handles[];      /* handles based on logical id */
   426        }
   427    }
   428    /*
   429     *  @(#) ti.sysbios.timers.gptimer; 2, 0, 0, 0,388; 8-19-2012 16:45:59; /db/vtree/library/trees/avala/avala-q42x/src/ xlibrary
   430    
   431     */
   432