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     *  ======== TimestampProvider.xdc ========
    34     *
    35     *
    36     */
    37    
    38    package ti.sysbios.family.windows;
    39    
    40    import xdc.runtime.Error;
    41    import xdc.runtime.Types;
    42    
    43    /*!
    44     *  ======== TimestampProvider ========
    45     *  TimestampProvider implementation for Windows.
    46     *
    47     *  This module provides an implementation on Windows for the
    48     *  {@link xdc.runtime.ITimestampProvider xdc.runtime.ITimestampProvider}
    49     *  interface.
    50     *
    51     *  On Windows, the timestamp counter value is computed from the
    52     *  accumulated CPU user time spent running the SYS/BIOS application.
    53     *  This emulates a hardware timestamp counter by eliminating all
    54     *  the CPU time spent running the Windows kernel and other Windows
    55     *  applications.
    56     *
    57     *  It is important to understand that although Windows uses a 
    58     *  real-time counter to accumulate the user time of a process,
    59     *  the accumulated total is updated only once every 10 milliseconds.
    60     *  Therefore, it is quite likely that two consecutive calls to 
    61     *  {@link #get32 TimestampProvider_get32()} or
    62     *  {@link #get64 TimestampProvider_get64()} or will return the same
    63     *  value. In fact, the returned value will only change the next time
    64     *  Windows updates the accumulated user time.
    65     *
    66     *  @p(html)
    67     *  <h3> Calling Context </h3>
    68     *  <table border="1" cellpadding="3">
    69     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    70     *
    71     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    72     *    <!--                                                                                                                 -->
    73     *    <tr><td> {@link #get32}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #get64}           </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #getFreq}         </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   Y    </td><td>   N    </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. TimestampProvider_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. TimestampProvider_Module_startupDone() returns FALSE).</li>
    92     *           </ul>
    93     *       </ul>
    94     *    </td></tr>
    95     *
    96     *  </table>
    97     *  @p
    98     *
    99     */
   100    
   101    module TimestampProvider inherits xdc.runtime.ITimestampProvider
   102    {
   103        /*! Error: GetProcessTimes failed.
   104         *
   105         *  A call to GetProcessTimes in the Win32 API has failed.
   106         *
   107         *  @a(Raised_In)
   108         *  @p(html)
   109         *  {@link #getTimestampCount64}<br />
   110         *  @p
   111         */
   112        config Error.Id E_processTimes = {
   113            msg: "GetProcessTimes failed: %d"
   114        };
   115    
   116        /*!
   117         *  ======== get32 ========
   118         *  Return a 32-bit timestamp.
   119         *
   120         *  See the details section above for implementation details.
   121         */
   122        override Bits32 get32();
   123    
   124        /*!
   125         *  ======== get64 ========
   126         *  Return a 64-bit timestamp.
   127         *
   128         *  See the details section above for implementation details.
   129         */
   130        override Void get64(Types.Timestamp64* result);
   131        
   132        /*!
   133         *  ======== getFreq ========
   134         *  Return the timestamp counter tick rate.
   135         *
   136         *  This function returns the rate, specified in hertz, at which
   137         *  the timestamp counter ticks. In other words, it is how many ticks
   138         *  per second the timestamp counter will tick.
   139         */
   140        override Void getFreq(Types.FreqHz *freq);
   141    }
   142    /*
   143     *  @(#) ti.sysbios.family.windows; 2, 0, 0, 0,543; 2-24-2012 11:40:29; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   144    
   145     */
   146