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    
    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        };
   208    
   209        /*!
   210         *  ======== BasicView ========
   211         *  @_nodoc
   212         */
   213        metaonly struct BasicView {
   214            Ptr         halTimerHandle;
   215            String      label;
   216            UInt        id;
   217            String      startMode;
   218            String      runMode;
   219            UInt        period;
   220            String      periodType;
   221            UInt        intNum;
   222            String      tickFxn[];
   223            UArg        arg;
   224            String      extFreqLow;
   225            String      extFreqHigh;
   226            String      hwiHandle;
   227        };
   228    
   229    
   230        /*!
   231         *  ======== ModuleView ========
   232         *  @_nodoc
   233         */
   234        metaonly struct ModuleView {
   235            String          availMask;      /* avaliable 32-bit timer halves */
   236            String intFrequency;    /* internal frequency in Hz */
   237        }
   238    
   239        /*!
   240         *  ======== rovViewInfo ========
   241         *  @_nodoc
   242         */
   243        @Facet
   244        metaonly config ViewInfo.Instance rovViewInfo = 
   245            ViewInfo.create({
   246                viewMap: [
   247                [
   248                    'Basic',
   249                    {
   250                        type: ViewInfo.INSTANCE,
   251                        viewInitFxn: 'viewInitBasic',
   252                        structName: 'BasicView'
   253                    }
   254                ],
   255                [
   256                    'Module',
   257                    {
   258                        type: ViewInfo.MODULE,
   259                        viewInitFxn: 'viewInitModule',
   260                        structName: 'ModuleView'
   261                    }
   262                ],
   263                ]
   264            });
   265    
   266        /*!
   267         *  Error raised when timer id specified is not supported.
   268         */
   269        config Error.Id E_invalidTimer = {
   270            msg: "E_invalidTimer: Invalid Timer Id %d"
   271        };
   272    
   273        /*!
   274         *  Error raised when timer requested is in use
   275         */
   276        config Error.Id E_notAvailable  = {
   277            msg: "E_notAvailable: Timer not available %d"
   278        };
   279    
   280        /*!
   281         *  Error raised when period requested is not supported
   282         */
   283        config Error.Id E_cannotSupport = {
   284            msg: "E_cannotSupport: Timer cannot support requested period %d"
   285        };
   286    
   287        /*!
   288         *  ======== anyMask ========
   289         *  Available mask to be used when select = Timer_ANY. Set in xs file.
   290         */
   291        config Bits32 anyMask;
   292    
   293        /*!
   294         *  ======== timerSettings ========
   295         *  Global Control configuration for each physical timer.
   296         */
   297        metaonly config TimerSetting timerSettings[] = [];
   298        
   299        /*!
   300         *  ======== intFreq ========
   301         *  Internal frequency for Timer
   302         */
   303        metaonly config Types.FreqHz intFreq = {lo: 0, hi: 0};
   304        
   305        /*!
   306         *  ======== stub  ========
   307         *  @_nodoc
   308         *  Timer requires acknowledgement
   309         *
   310         *  @param(arg)     timer object passed in as argument.
   311         */
   312        @DirectCall
   313        Void stub(UArg arg);
   314    
   315    
   316    instance:
   317    
   318        /*! 
   319         *  ======== tiocpCfg ========
   320         */
   321        config TiocpCfg tiocpCfg = {autoidle: 0, softreset: 1, enawakeup: 0,
   322            idlemode: 0, emufree: 0, clockactivity: 0};
   323    
   324        /*! 
   325         *  ======== tier ========
   326         */
   327        config Tier tier = {mat_it_ena: 0, ovf_it_ena: 1, tcar_it_ena: 0};
   328    
   329        /*! 
   330         *  ======== twer ========
   331         */
   332        config Twer twer = {mat_wup_ena: 0, ovf_wup_ena: 0, tcar_wup_ena: 0};
   333    
   334        /*! 
   335         *  ======== tclr ========
   336         */
   337        config Tclr tclr = {ptv: 0, pre: 0, ce: 0, scpwm: 0, tcm: 0, trg: 0,
   338            pt: 0, captmode: 0, gpocfg: 0};
   339        
   340        /*! 
   341         *  ======== tsicr ========
   342         */
   343        config Tsicr tsicr = {sft: 0, posted: 1};
   344    
   345        /*! 
   346         *  ======== tmar ========
   347         */
   348        config UInt32 tmar = 0;
   349    
   350        /*! Hwi Params for Hwi Object. Default is null. */
   351        config Hwi.Params *hwiParams = null;
   352    
   353        /*!
   354         *  ======== reconfig ========
   355         *  Used to modify static timer instances at runtime.
   356         *
   357         *  @param(timerParams)     timer Params
   358         *  @param(tickFxn)         functions that runs when timer expires
   359         */
   360        @DirectCall
   361        Void reconfig(FuncPtr tickFxn, const Params *timerParams, Error.Block *eb);
   362    
   363    
   364    internal:   /* not for client use */
   365    
   366        /*! Device-specific Timer implementation. */
   367        proxy TimerSupportProxy inherits ti.sysbios.interfaces.ITimerSupport;
   368    
   369        /*!
   370         *  ======== startupNeeded ========
   371         *  This flag is use to prevent Timer_startup code (includes postInit(),
   372         *  deviceConfig(), initDevice() to be brought in un-necessarily.
   373         */
   374        config Bool startupNeeded = false;
   375    
   376        /*! Information about timer */
   377        struct TimerDevice {
   378            UInt intNum;
   379            UInt eventId;
   380            Ptr  baseAddr;
   381        };
   382    
   383        /*!
   384         *  ======== numTimerDevices ========
   385         *  The number of logical timers on a device.
   386         */
   387        config Int numTimerDevices;
   388    
   389        /*!
   390         *  ======== spinLoop ========
   391         *  used by trigger function.
   392         */
   393        Void spinLoop(UInt count);
   394    
   395        /*! Instance state structure */
   396        struct Instance_State {
   397            Bool                    staticInst;     /* statically created or not */
   398            Int                     id;             /* logical timer id. */
   399            UInt                    tiocpCfg;
   400            UInt                    tmar;
   401            UInt                    tier;
   402            UInt                    twer;
   403            UInt                    tclr;
   404            UInt                    tsicr;
   405            ITimer.RunMode          runMode;        /* timer mode */
   406            ITimer.StartMode        startMode;      /* timer mode */
   407            UInt                    period;         /* period */
   408            ITimer.PeriodType       periodType;     /* type (microsecs, inst) */
   409            UInt                    intNum;         /* intr num */
   410            UArg                    arg;            /* isrFxn arg */
   411            Hwi.FuncPtr             tickFxn;        /* Timer fxn plugged into Hwi */
   412            Types.FreqHz            extFreq;        /* ext freq */
   413            Hwi.Handle              hwi;            /* hwi inst */
   414        }
   415    
   416        /*! Module state structure */
   417        struct Module_State {
   418            Bits32          availMask;      /* avaliable 32-bit timer halves */
   419            Types.FreqHz    intFreq;        /* internal frequency in Hz */
   420            TimerDevice     device[];       /* timer device information */
   421            Handle          handles[];      /* handles based on logical id */
   422        }
   423    }
   424    /*
   425     *  @(#) ti.sysbios.timers.gptimer; 2, 0, 0, 0,324; 6-15-2011 16:26:38; /db/vtree/library/trees/avala/avala-p38x/src/ xlibrary
   426    
   427     */
   428