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.family.windows;
    39    
    40    import xdc.runtime.Types;
    41    import xdc.runtime.Error;
    42    import ti.sysbios.interfaces.ITimer;
    43    
    44    /*!
    45     *  ======== Timer ========
    46     *  Timer Peripherals Manager for Windows family.
    47     *
    48     *  @p(html)
    49     *  <h3> Calling Context </h3>
    50     *  <table border="1" cellpadding="3">
    51     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    52     *
    53     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    54     *    <!--                                                                                                                 -->
    55     *    <tr><td> {@link #getNumTimers}            </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    56     *    <tr><td> {@link #getStatus}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    57     *    <tr><td> {@link #Params_init}             </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    58     *    <tr><td> {@link #construct}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    59     *    <tr><td> {@link #create}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    60     *    <tr><td> {@link #delete}                  </td><td>   N    </td><td>   N    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    61     *    <tr><td> {@link #destruct}                </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    62     *    <tr><td> {@link #getFreq}                 </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    63     *    <tr><td> {@link #getPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    64     *    <tr><td> {@link #setPeriod}               </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    65     *    <tr><td> {@link #setPeriodMicroSecs}      </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    66     *    <tr><td> {@link #start}                   </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    67     *    <tr><td> {@link #stop}                    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td><td>   N    </td></tr>
    68     *    <tr><td colspan="6"> Definitions: <br />
    69     *       <ul>
    70     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    71     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    72     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    73     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    74     *           <ul>
    75     *             <li> In your module startup after this module is started (e.g. Timer_Module_startupDone() returns TRUE). </li>
    76     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    77     *             <li> During main().</li>
    78     *             <li> During BIOS.startupFxns.</li>
    79     *           </ul>
    80     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    81     *           <ul>
    82     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    83     *             <li> In your module startup before this module is started (e.g. Timer_Module_startupDone() returns FALSE).</li>
    84     *           </ul>
    85     *       </ul>
    86     *    </td></tr>
    87     *
    88     *  </table>
    89     *  @p
    90     *
    91     */
    92    
    93    @ModuleStartup
    94    @InstanceFinalize       /* To cleanup */
    95    @InstanceInitError      /* To report unavailability of timer */
    96    
    97    module Timer inherits ti.sysbios.interfaces.ITimer
    98    {
    99        // -------- Module Constants --------
   100    
   101        /*! Emulation supports 2 timers. */
   102        const Int NUM_TIMER_DEVICES = 2;
   103    
   104        /*! Max value of Timer period for PeriodType_COUNTS*/
   105        const UInt MAX_PERIOD = 0xffffffff;
   106    
   107        /*! Error: memory allocation request failed.
   108         *
   109         *  A request into the Windows runtime library for memory has failed.
   110         *
   111         *  @a(Raised_In)
   112         *  @p(html)
   113         *  {@link #startup}<br />
   114         *  @p
   115         */
   116        config Error.Id E_calloc = {
   117            msg: "calloc failed"
   118        };
   119    
   120        /*! Error: unsupported timer period
   121         *
   122         *  On Windows, the timer period cannot be less than one millisecond.
   123         *  However, the actual minimum timer period (even when set to one
   124         *  millisecond) is 10 - 15 milliseconds. This latency results from the
   125         *  Windows clock ticking at 10 milliseconds with additional delays in
   126         *  the Windows kernel.
   127         *
   128         *  @a(Raised_In)
   129         *  @p(html)
   130         *  {@link #startup}<br />
   131         *  @p
   132         */
   133        config Error.Id E_cannotSupport = {
   134            msg: "Timer cannot support requested period %d"
   135        };
   136    
   137        /*! Error: CreateEvent failed.
   138         *
   139         *  A CreateEvent call into the Win32 API has failed.
   140         *
   141         *  @a(Raised_In)
   142         *  @p(html)
   143         *  {@link #startup}<br />
   144         *  @p
   145         */
   146        config Error.Id E_event = {
   147            msg: "CreateEvent failed"
   148        };
   149    
   150        /*! Error: Invalid timer specified.
   151         *
   152         *  An invalid timer id was specified. Timer id must be in the range
   153         *  0 to ({@link #NUM_TIMER_DEVICES} - 1). In the {@link #create()} call,
   154         *  an id of -1 may be used to request any available timer.
   155         *
   156         *  @a(Raised_In)
   157         *  @p(html)
   158         *  {@link #init}<br />
   159         *  {@link #postInit}<br />
   160         *  {@link #start}<br />
   161         *  {@link #stop}<br />
   162         *  @p
   163         */
   164        config Error.Id E_invalidTimer = {
   165            msg: "E_invalidTimer: Invalid Timer Id %d"
   166        };
   167    
   168        /*! Error: no timers available.
   169         *
   170         *  A request was made for any available timer, but there are none
   171         *  available at this time.
   172         *
   173         *  @a(Raised_In)
   174         *  @p(html)
   175         *  {@link #postInit}<br />
   176         *  @p
   177         */
   178        config Error.Id E_noneAvailable = {
   179            msg: "no available timer"
   180        };
   181    
   182        /*! Error: API not supported on Windows
   183         *
   184         *  This timer API is not supported on Windows.
   185         *
   186         *  @a(Raised_In)
   187         *  @p(html)
   188         *  {@link #trigger}<br />
   189         *  @p
   190         */
   191        config Error.Id E_notSupported = {
   192            msg: "API not supported on Windows"
   193        };
   194    
   195        /*! Error: CreateThread failed.
   196         *
   197         *  A CreateThread call into the Win32 API has failed.
   198         *
   199         *  @a(Raised_In)
   200         *  @p(html)
   201         *  {@link #startup}<br />
   202         *  @p
   203         */
   204        config Error.Id E_thread = {
   205            msg: "CreateThread failed"
   206        };
   207    
   208        /*! Error: requested timer not available.
   209         *
   210         *  A request was made for a timer, but it is not available at this time.
   211         *  It is currently in use.
   212         *
   213         *  @a(Raised_In)
   214         *  @p(html)
   215         *  {@link #init}<br />
   216         *  {@link #postInit}<br />
   217         *  @p
   218         */
   219        config Error.Id E_notAvailable = {
   220            msg: "E_notAvailable: Timer not available %d"
   221        };
   222    
   223        /*! Error: WaitForSingleObject failed.
   224         *
   225         *  A WaitForSingleObject call into the Win32 API has failed.
   226         *
   227         *  @a(Raised_In)
   228         *  @p(html)
   229         *  {@link #processInterrupt}<br />
   230         *  {@link #start}<br />
   231         *  @p
   232         */
   233        config Error.Id E_wait = {
   234            msg: "WaitForSingleObject failed"
   235        };
   236    
   237        //! Available mask to be used when select = TIMER_ANY.
   238        config UInt anyMask = 0x3;
   239    
   240    
   241    internal:   /* not for client use */
   242       
   243        struct PrivateData;
   244    
   245        struct Instance_State {
   246            Int                     id;
   247            ITimer.RunMode          runMode;
   248            ITimer.StartMode        startMode;
   249            UInt                    period;
   250            ITimer.PeriodType       periodType;    
   251            Types.FreqHz            extFreq;
   252            UInt                    intNum;
   253            FuncPtr                 tickFxn;
   254            UArg                    tickFxnArg;
   255            Hwi.Handle              hwi;
   256        };
   257    
   258        struct Module_State {
   259            Char            availMask;
   260            Handle          handles[NUM_TIMER_DEVICES];
   261            PrivateData     *privateData;   /* Windows types not allowed in xdc */
   262        };
   263    }
   264    /*
   265     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,543; 2-24-2012 11:40:29; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   266    
   267     */
   268