|
|
This directory and its subdirectories contain source and binary files for the timer support packages that canbe 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 usesthe new 16BitTmr.sys, a timer driver. For using the Sloop/Cuttertimer, 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 theend of this document. Please copy the timing.h file from thisdirectory 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 buildingyour application for, since the header file uses some special typesthat 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 directoryto your machine.
b) Edit your Config.sys file to add the line"DEVICE=xxx\16BitTmr.sys, where xxx is the full path name wherethe driver resides.
c) Copy the timerslp.dll from the .\sloop\bin directory to yourlibpath.
c) Reboot your machine and use the timerslp.dll as explainedelsewhere.
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.
|
