windows-nt/Source/XPSP1/NT/sdktools/perftool/timer
2020-09-26 16:20:57 +08:00
..
makefile Add source files 2020-09-26 16:20:57 +08:00
readme Add source files 2020-09-26 16:20:57 +08:00
sources Add source files 2020-09-26 16:20:57 +08:00
timer.c Add source files 2020-09-26 16:20:57 +08:00
timerw32.def Add source files 2020-09-26 16:20:57 +08:00
updlib.cmd Add source files 2020-09-26 16:20:57 +08:00

This directory and its subdirectories contain source and 
binary files for the timer support packages that can
be run across multiple platforms.  

NOTE:  The dll under CR286 can be run under Cruiser only,
since it uses the PerfView "thunked" timer.  For Sloop/Cutter 
programs, use the dll under the Sloop directory.  This uses
the new 16BitTmr.sys, a timer driver.  For using the Sloop/Cutter
timer, read the section titled "Using the Cutter Timer".

The directory is organized as follows:

1) .\ ->  
          a) timer.c      (single c source)

          b) makefile.rst (common for windows, CR286, Sloop and 
                           OS2 386 and WOW)

          c) makefile     (for Windows NT)

          d) sources      (  -do-  )

          e) The header file, timing.h, is under .\inc\.
 
2) .\win  (FOR WINDOWS)

          a) .\src      (contains the .asm files for init and 8253io, and the 
                         module def file)

          b) .\bin      (the binary timerwin.dll file)

3) .\WIN32  (FOR Win32 NT)

          a) .\src      (contains the .def file and an i386 sub-dir.
                         that has an asm file) 

          b) .\bin      (the binary file)

4) .\Sloop  (FOR Sloop apps)

          a) .\src      (contains the initializing .asm file, and the 
                         module def file)

          b) .\bin      (the binary timerslp.dll file)

5) .\cr286 (FOR 16 bit OS/2 Cruiser apps)

          a) .\src      (contains the initializing asm file
                         and the module def file)

          b) .\bin      (the binary timer286.dll file)
         
6) .\os2386 (FOR 32 bit OS/2 Cruiser apps)

          a) .\src      (contains the initializing and math .asm
                         files, and the module def file)

          b) .\bin      (the binary timer386.dll file)

7) .\wow  (FOR 16 bit WOW on Windows NT - built for Win 3.0)

          a) .\src      (contains the .asm and the 
                         module def file)

          b) .\bin      (the binary timerwow.dll file)
**********************************************************************

To Use a timer DLL:
------------------

To use one of the above binaries, please read the USAGE NOTES at the
end of this document.  Please copy the timing.h file from this
directory to the directory where you are building your application.
Copy the relevant .dll to your libpath.

It is essential that you define the type of system you are building
your application for, since the header file uses some special types
that are dependent on the system.  While compiling your application,
add the following flag: -DXXX where XXX stands for one of: 

          WIN       - for Windows applications on Windows 3.x.
          WIN32     - for Win32 applications.
          WOW16     - for Windows applications on Windows NT.
          SLOOP     - for 16 bit Sloop (OS/2 1.2, 1.3) applications
          OS2286    - for 16 bit Cruiser (OS/2 2.0) applications
          OS2386    - for 32 bit OS/2 applications


**********************************************************************

To build one of the dlls:
------------------------

If building a Windows, WOW, Sloop, Cutter, CR286 or OS/2 32 bit dll:
--------------------------------------------------------------

NOTE: To build for Wow on NT, you must be setup to build for Win 3.0
      and not Win 3.1.  Also, you need the special Windows libraries.
      These need to be built on NT.

a)   Copy the timer.c from this dir. and the timing.h from ..\inc\.
     to a local directory.  

b)   Also copy the "makefile.rst" from here to the same directory.  

c)   From ???\src copy the remaining files to the local directory, 
     where ??? represents win, Sloop, cr286 or os2386.

d)   Edit makefile.rst to define the system that you are making the
     dll for.  Eg. if you are making the dll for windows, remove
     the comment sign (#) from the line "WIN=TRUE" in the makefile
     and ensure that the other system defines (WOW16, SLOOP, OS2286 
     and OS2386) are commented out.  

f)   Type "nmake -f makefile.rst" and the dll will be created for
     you.   (Ensure that your development environment is set up for 
     the right system).

If building the Win32 dll:
-------------------------

a)   Copy timer.c, makefile and sources files found under this 
     directory and timing.h from ..\inc\. to a local directory.  

b)   tc the win32\src directory to your local directory.  This 
     will create an i386 sub-directory containing an asm file on 
     your local machine.

c)   From the directory where you have your sources file, type
     "build -xxx timerw32" from the command line, where xxx represents
     your target system.  It is 386 by default.

c)   A binary file "timerw32.dll" will be created along with the
     .obj file under .\xxx\obj where xxx is your target system.
     It is i386 by default.

Using the Cutter Timer: (For use on machines running OS/2 1.2x, 1.3x)
----------------------

Note:  This driver cannot be used when the DOS box is running.
So edit your config.sys file so that the line "PROTECTONLY=YES"
is present.

a)   Copy the 16BitTmr.* files from the .\sloop\bin directory
to your machine.  

b)   Edit your Config.sys file to add the line
"DEVICE=xxx\16BitTmr.sys,  where xxx is the full path name where
the driver resides.  

c)   Copy the timerslp.dll from the .\sloop\bin directory to your
libpath.

c)   Reboot your machine and use the timerslp.dll as explained
elsewhere.

In case you have any questions, or if you run into any problems, 
contact vaidy (936-7812).

*****************************************************************

USAGE NOTES
-----------

This document  describes the  usage of the functions available 
through the Timer.dll.  This dll can be  used by  all application  
programs  that  require  a microsecond timer.  Send all 
comments/suggestions to vaidy (ph. 936-7812) or 
JohnOw (ph. 936-5557).

1) TimerOpen:
   ---------

Description:  Opens a timer object and returns a handle for use
              in timing operations.

#include "timing.h"    /* for error codes */

    SHORT FAR PASCAL
    TimerOpen (
        SHORT far * phTimer,
        _TimerUnits TimerUnits
        );

    phTimer    - Address to which to return the handle to the 
                 timer.

    TimerUnits - Will be one of the enumerated types listed below, that 
                 determines the units for the elapsed time values
                 returned by TimerRead.  The selected units may be
                 greater or less than the underlying clock frequency:
 
                     typedef enum {
                         KILOSECONDS,
                         SECONDS,
                         MILLISECONDS,
                         MICROSECONDS,
                         TENTHMICROSECS,
                         NANOSECONDS,
                         TIMER_FREE
                     } _TimerUnits;

Remarks:  This call should be made by each application, every time
          a new timer is required.  This call should precede any 
          other timer function calls.  Each call to TimerOpen will 
          return a new handle, so that multiple threads within a 
          process may use different timers for measuring time.  
          The handle obtained from this call should be used by 
          the other timing functions, viz. TimerOpen and TimerRead.  
          The handle is an index into an array of timer objects that
          are made available by this function.

          The number of timers will depend upon the implementation,
          but will usually be in the order of 100's or 1000's per
          process.  Use TimerClose to release unused timers in case
          there is a need to reuse a large number of timers.  Any
          opened timers will be automatically closed when the process
          using them terminates.
          
          The scaling factor decides the units of the time returned 
          by TimerRead.  The calling application should be careful 
          over the choice of units, to avoid possible overflow 
          and consequently, incorrect results.

Return:   0 if a timer handle is made available.

          An error code, on failure, which may be one of: 

              TIMERERR_TIMER_NOT_AVAILABLE
              TIMERERR_NO_MORE_HANDLES
              TIMERERR_INVALID_UNITS

See also: TimerInit, TimerRead, TimerClose.

2) TimerInit:
   ---------

Description:  Initializes the elements of an internal structure
              to the current time, obtained from the low level
              timer.

#include "timing.h"    /* for error codes */

    SHORT FAR PASCAL
    TimerInit (
        SHORT hTimer
        );

    hTimer - The handle, to the timer, that was made available by
             a call to TimerOpen.

Remarks:  This function should be called after opening the timer
          object.  Each call to this function should just precede
          the operation that is being timed.  Passing a handle
          to a timer object that has not been opened, will result
          in an error code being returned.  

Return:   0 if the call is successful.

          An error code is returned, if the call failed.  The error code is:

              TIMERERR_INVALID_HANDLE

See also: TimerOpen, TimerRead, TimerClose.

3) TimerRead:
   ---------

Description:  Returns the elapsed time since the previous call to
              TimerInit.

#include "timing.h"    /* for error codes */

    ULONG FAR PASCAL
    TimerRead (
        SHORT hTimer
        );

    hTimer - handle to the timer object that was opened with a call
             to TimerOpen and initialized by calling TimerInit.

Remarks:  This call should have been preceded by a call to TimerOpen
          and TimerInit.  This call gets the current time from the
          low level timer and, using the initialized values in the
          internal structure, computes the elapsed time from the
          previous call to TimerInit.  Any number of calls to 
          TimerRead may be made, as long they are preceded by at least
          one call to TimerInit.  A timer overflow error code is 
          returned if the scaling factor was so chosen as to
          cause an overflow in the time being returned.  A bad
          handle to this call will also result in an error code 
          being returned.  

Return:   A successful call returns the elapsed time since the last
          call to TimerInit.  

          A failure, either invalid handle or overflow, is indicated 
          by returning the maximum ULONG value (0xffffffff).

See also: TimerOpen, TimerInit, TimerClose.

4) TimerClose:
   ----------

Description:  Closes a timer object that was opened with a call to
              TimerInit.

#include "timing.h"

    SHORT FAR PASCAL
    TimerClose (
        SHORT hTimer
        );

    hTimer - Handle to the timer object that was opened with a call to
             TimerInit.
  
Remarks:  This function closes the specfied timer object and returns 
          it to the pool of available timer objects.  The object then 
          is considered as available for use, when a call to TimerOpen is
          made.
          
Return:   0 if the timer was successfully closed.

          An error code on failure:
            
              TIMERERR_INVALID_HANDLE

See also: TimerOpen, TimerInit, TimerRead.

----------------------------------------------------------------------

Usage:
-----

Test Application Body:

{
    SHORT hTimerHandle1;
    SHORT sRetVal;

    if ((sRetVal = TimerOpen ((SHORT far *) &hTimerHandle1, MICROSECONDS)) {
        could not open timer 
        Do not perform any timing operation
    }
    :
    :
    Do Stuff
    :
    :
    /* Commence timing operations */
    
    for (some conditions) {
        TimerInit (hTimerHandle1);
        Do Timed Operation
        ulElapsedTime = TimerRead (hTimerHandle1);
    }

    if (TimerClose (hTimerHandle1)) {
        Could not close timer.  Check handle and take corrective
        action   
    }
    :
    :
}

--------------------------------------------------------------------

Debugging Routine
-----------------

5) TimerReport:
   -----------

Description:  Used as a debugging tool, this routine fetches the
              the time from the last call to TimerInit and TimerRead.


#include "timing.h"    /* for error codes */

    SHORT BOOL PASCAL
    TimerReport (
        PSZ pszReportString,
        SHORT hHandleHandle;
        );

    pszReportString - Address to which to return the string containing
                      the time obtained in the last call to
                      TimerInit, TimerRead and the time returned
                      from the last call to TimerRead.

    hTimerHandle    - Handle to the timer from whom the information is
                      sought.
 
Remarks:  This call can be used as a debugging device in case there
          is a doubt as to what values are being returned by the
          timer.  This routine should normally be called after a call
          to TimerRead.  The routines TimerInit and TimerRead call an
          underlying timer to obtain clock tics/time.  The call
          to TimerRead uses this information and returns the
          time (clock tics are converted to time using the clock
          frequency on NT) as a ULONG.  TimerReport obtains the 
          information stored by the last call to TimerInit and 
          last call to TimerRead.  It also obtains the time that 
          is returned by TimerRead (after converting clock tics 
          to time whereever applicable, and subtracting the 
          overhead) and prints the information into a string whose 
          address is passed in as the first parameter to this routine.

          The format of the string is as follows:

          "Init Time %lu:%lu Current Time %lu:%lu Returned Time %lu".
       
          Both the times are printed as 64 bit values (high:low).

          On NT, the init and current times are clock tics while
          the returned time is in time units.  The returned time
          will be about 0.8 times the difference between the clock
          tics.

          Note that the returned time takes into account the calling
          overhead also and hence, is not exactly the difference
          between the current time and init time.

Return:   TRUE if timer exists and has been opened.
          FALSE otherwise.

See also: TimerOpen, TimerInit, TimerRead, TimerClose.

-------------------------------------------------------------------------

Additional Routines:
-------------------

6) TimerQueryPerformanceCounter:
   ----------------------------

Description:  Makes the raw counts, (tics), and the timer frequency
              available.

#include "timing.h"    /* for error codes */

    VOID BOOL PASCAL
    TimerQueryPerformanceCounter (
        PQWORD pCurrentTic,
        PQWORD pFrequency [OPTIONAL]
        );

    pCurrentTic     - Address to a 64-bit location to which the raw
                      tic count is written on returning from the call.
                      PQWORD is defined a PLARGE_INTEGER for the Win32
                      platform in timing.h.  PQWORD is a pointer to a
                      QWORD structure (consisting of two ULONG
                      elements), on Win 3.x and OS/2 platforms.

    pFrequency      - Address to a 64-bit location to which the 
                      timer frequency is written on returning from
                      the call, if this pointer is not NULL.  This
                      is OPTIONAL.  If NULL, only the current tic
                      count is written to the location pointed by 
                      pCurrentTic.
 
Remarks:  This call can be used by any application to return the
          timer frequency and current tic count.  The frequency needs
          to be obtained only once.  All other calls to this routine
          can have NULL as the second parameter.

          The calling application should perform its own calibration
          to determine the overhead when this routine is called
          back-to-back.  

          To time an operation, this routine should immediately
          precede and follow the operation.  The difference of
          the tic counts should be computed.  The overhead for
          calling this routine back to back should be subtracted from
          this difference, and then divided by the frequency to
          obtain the time in seconds.  (To obtain the time in 
          microseconds, multiply the raw tics by a million before 
          dividing by the frequency.  To convert the time to units 
          other than seconds, the conversion factor should be applied
          before performing the division by the frequency, to 
          avoid loss of precision).

          There is no need to open or initialize the timer if this
          routine is used to obtain the tic count.
          
Return:   None.

See also: TimerOpen, TimerInit, TimerRead, TimerClose.

7) TimerConvertTicsToUSec:
   ----------------------

Description:  Used as a utility tool, this routine returns
              the time in microseconds when the tic difference and
              timer frequency are passed in.


#include "timing.h"    /* for error codes */

    ULONG BOOL PASCAL
    TimerConvertTicsToUSec (
        ULONG ulTicDifference,
        ULONG ulTimerFreq;
        );

    ulTicDifference - The duration of an operation in tics.  This is
                      obtained by calling
                      TimerQueryPerformanceCounter immediately before
                      and following the desired operation and
                      subtracting the overhead of calling 
                      TimerQueryPerformanceCounter back to back.

    ulTimerFreq    -  The timer frequency. This is obtained by
                      calling TimerQueryPerformanceCounter.
 
Remarks:  This routine just accepts the duration of an operation in
          timer counts and the timer frequency.  It returns the
          actual time in microseconds corresponding to the tic
          count.  

          There is no need to open or initialize the timer if this
          routine is used to obtain the tic count.

Return:   The time in microseconds that corresponds to the input
          tics and frequency.

          A zero if the frequency is zero.

See also: TimerOpen, TimerInit, TimerRead, TimerClose.