Category : Pascal Source Code
Archive   : TPHRT2R.ZIP
Filename : TPHRTV2R.DOC

TPHRT V2.00R

Turbo Pascal High Resolution Timer Toolbox




Ryle Design

P.O. Box 22, Mt. Pleasant, Michigan 48804

CompuServe 73047,1765

517-773-0587






What is TPHRT?

TPHRT (Turbo Pascal High Resolution Timer) is a software "toolbox" of routines
to manipulate one hundred different timers each with one microsecond resolu-
tion. TPHRT makes it easy to very accurately time nearly any synchronous or
asynchronous event your PC can encounter. Since the timer routines calibrate
themselves to the host PC speed at run-time a single executable file will yield
accurate timings across all 80xxx PC compatible environments. A complete report
of all timer activity can be generated with a single TPHRT function call.

Some uses for TPHRT are:

Source Code Timer/Profiler
--------------------------
By adding calls to TPHRT in source code under development, the execution of
that code can generate a detailed summary of execution time by program
subroutine and immediately show the developer the program's "hot spots"
that might benefit from further code or algorithm optimization. Unlike
"binning" profilers that display the number of "hits" in a range of program
counter addresses, TPHRT provides a direct one to one correspondence
between source code and elapsed time with user defined granularity. A
single line of source code can easily be timed with the insertion of two
TPHRT procedure calls.

Hardware Performance Evaluator
------------------------------
The high resolution and self calibration features of TPHRT make it ideal
for insertion in code to evaluate hardware performance. Disk drives,
numeric processors and video controllers can all have their throughput
measured very accurately with TPHRT, and with one hundred timers at the
user's disposal, many device functions can be independently measured in a
single run. The formatted timer report generated by TPHRT makes
compilation and interpretation of the test results quick and simple.

Process Control Applications
----------------------------
With TPHRT, process control and data acquisition applications that require
precise timing are easy to implement. No longer will the application
developer have to make an educated guess as to how long a critical hardware
interrupt is taking to service - TPHRT timer calls can be inserted in the
interrupt handler and precise, accurate timing of the critical procedure is
assured.

Timing and Scoring Equipment
----------------------------
TPHRT is the perfect "timer engine" to build a timing and scoring system
for nearly any competitive event that requires high resolution timing.
With it's one microsecond (0.000001) resolution, TPHRT surpasses
conventional sports timing equipment resolution and thus allows the
application developer to package both high resolution timing and complete
event scoring in a single package.





-1-



Distribution List


The distribution you have received should contain the following:

TPHRTV2R.DOC This document
TPHRT.TPU Turbo Pascal V5 unit
DEMOV2.PAS Simple demonstration of TPHRT functions
WATCH.PAS Demo program showing TPHRT hardware interrupt trigger.
SEEKTEST.PAS Demo program to test disk seek performance.
TESTBIOS.PAS Demo program showing BIOS profiling.
TPHRT.PAS TPHRT source code.
TPHRTASM.ASM TPHRT assembly source code.
BLDLIBS.BAT Batch file to build TPHRT unit.


V1.xx Users

Remove the t_calib call from your TPHRT V1.xx code. t_calib is now called
by t_start. Multiple t_calib calls will degrade timer accuracy.


Registered Version Enhancements

Thank you for purchasing the full version of TPHRT. The following additional
features are at your disposal:

Documentation of low level functions:

t_get PC 8253 hardware timer interface
t_diff calculates elapsed time between two TPHRT timestamps

BIOS timing functions for INT 10h (video) & INT 13h (disk):

t_bios_start enables BIOS interrupt profiling
t_bios_stop disables BIOS interrupt profiling
t_bios_suspend suspends BIOS interrupt profiling
t_bios_resume resumes BIOS interrupt profiling
t_bios_reset resets BIOS timers
t_bios_ask returns time & count for BIOS interrupt function
t_bios_report generates BIOS timer summary
t_bios_fname specifies file name for BIOS timer summary
t_bios_rname specifies title for BIOS timer summary

Source and documentation to all functions and data structures.

Example programs.

Notes On BIOS Profiling

The t_bios functions represent a powerful tool to measure ROM BIOS activity.
The functions as supplied will profile interrupt 10h (video services) and
interrupt 13h (disk services). Users needing other interrupts profiled can
extend the t_bios functionality by using the source code provided and adding
timers and logic for additional interrupts as needed. Contact Ryle Design
if you are having problems doing this.

-2-




There are several items worth noting about t_bios functions:

1. There are several paths through the timer logic that a given
BIOS interrupt function can take, so the absolute accuracy of
each BIOS timer is less than a normal timer call. Depending
on PC speed, the inaccuracy may be as much as 100 microseconds.
To help compensate for this, the t_bios_report function gives
interrupt timer results both in absolute time and a percentage
of all time spent in the interrupt.

2. NEVER attempt to profile interrupt 13h (disk services) on a disk
that is not properly backed up.

3. If a program with BIOS profiling active fails before the t_bios_stop
function has been executed, reboot immediately. Your BIOS interrupt
vectors will be pointing to nonexistent code.



Notes On Demo Code


The supplied demonstration programs each attempt to show a different TPHRT
application. They are as follows:

DEMOV2.PAS This program demonstrates TPHRT timer usage by timing program
loops and a subroutine with high resolution. This is typical
of an execution profiling application.

WATCH.PAS This program shows how to place TPHRT timer calls in a hardware
interrupt handler. The demo code implements a stopwatch with
"Taylor Split" capability.

SEEKTEST.PAS This program shows how to time PC hardware activity to measure
performance characteristics with high resolution. The user
can select from the available physical hard disks present
on the system and measure their average seek and track to track
seek times. This test is "real world" as the BIOS interrupt
and disk controller microcode overhead are also measured.

TESTBIOS.PAS This program shows how to use the t_bios profiling functions
to measure ROM BIOS activity. The source code to the t_bios
functions illustrates how to add TPHRT timer calls to a software
interrupt handler. This is not a trivial task, as a software
ISR returns meaningful values in various registers, while
a hardware ISR generally does not. Study the t_bios functions
in TPHRT.C carefully before attempting to do this on your own.
Keep a good debugger handy while testing (here at Ryle Design
we use Borland's Turbo Debugger in remote mode) and make sure
any fixed media on the system is fully backed up before you
begin.

All of the source and demo code supplied is carefully commented, and many
of the comments run beyond the usual 80 text columns. None run beyond 132
columns, so printing the listings in a compressed mode is highly recommended.

-3-


V2.00R Quick Reference

Users already familiar with Ryle Design PC Timer Toolboxes can reference the
following unit interface to begin using TPHRT immediately.

unit TPHRT;

interface

uses
printer, dos;

const
crt = 1;
disk = 2;
crtdisk = 3;
maxtimers = 100;

type
tname = string[20];
tphrt_type = record { holds tphrt timestamps }
ticks : word;
tocks : word;
end;

tphrt_data = record { tphrt data structure }
maxentry : integer;
iohead : word;
entry : array [1..maxtimers] of longint;
elapsed : array [1..maxtimers] of longint;
timername : array [1..maxtimers] of tname;
tstart : array [1..maxtimers] of tphrt_type;
tstop : array [1..maxtimers] of tphrt_type;
end;

tbios_data = record { BIOS interrupt profiling data structure }
enabled : boolean;
hasdata : boolean;
tstack : array [1..100] of byte;
tstptr : byte;
entry : array [0..255] of longint;
elapsed : array [0..255] of longint;
bstart : array [0..255] of tphrt_type;
bstop : array [0..255] of tphrt_type;
end;

var
t_old_10 : pointer;
t_old_13 : pointer;

tdata : tphrt_data; { timer data }
i10data : tbios_data; { BIOS INT 10h timer data }
i13data : tbios_data; { BIOS INT 13h timer data }

{ procedure prototypes }

procedure t_start;
procedure t_stop;
procedure t_calib;
procedure t_entry(tnum : integer);

-4-


procedure t_exit(tnum : integer);
procedure t_name(tnum : integer; name : tname);
procedure t_report(whereto : integer);
procedure t_get(var timestamp : tphrt_type);
function t_diff(start, stop : tphrt_type) : longint;

{ V2.00 enhancements }

procedure t_fname(fname : string);
procedure t_rname(rname : string);
procedure t_reset(tnum : integer);
procedure t_ask_timer(tnum: integer; var hits : longint;
var elapsed : longint);
procedure t_suspend(tnum : integer);
procedure t_resume(tnum : integer);

{ V2.00R bios profiling enhancements }

procedure t_bios_start(whichint : integer);
procedure t_bios_stop;
procedure t_bios_suspend(whichint : integer);
procedure t_bios_resume(whichint : integer);
procedure t_bios_ask(whichint : integer; whichfunc : integer;
var hits : longint; var elapsed : longint);
procedure t_bios_reset(whichint : integer; whichfunc : integer);
procedure t_bios_fname(fname : string);
procedure t_bios_rname(rname : string);
procedure t_bios_report(whereto : integer);

procedure t_new_10;
procedure t_new_13;

implementation
























-5-




TPHRT Function Reference


t_ask_timer

Prototype t_ask_timer(tnum: integer; var hits : longint;
var elapsed : longint);

Purpose To get current activation counts and accumulated elapsed time
for a specific timer.

Usage t_start(2,hits,elapsed);

Side Effects None. Queries TPHRT data structure, makes no DOS or BIOS
calls.

Explanation This function and t_report are the means by which the user
gets timer results. This function returns the number of
timer activations and the amount of elapsed time (in micro-
seconds) those activations consumed for a specific timer.
This function is useful when the user wishes information on
a specific timer or wishes to format his/her own timer report.

See also t_report


_____________________________________________________________________________



t_bios_ask

Prototype t_bios_ask(whichint : integer; whichfunc : integer;
var hits : longint; var elapsed : longint);

Purpose To get current activations counts an accumulated elapsed time
for a specific BIOS interrupt timer.

Usage t_bios_ask(DISK,$03,count,elapsed);

Side Effects None. Queries TPHRT data structure, makes no DOS or BIOS
calls.

Explanation This function and t_bios_report are the means by which the
user can get timer results. This function returns timer
status for a BIOS interrupt function if the BIOS interrupt
is profiled.

Only CRT and DISK interrupt specifiers are valid.

See also t_report.


_____________________________________________________________________________


-6-




t_bios_entry

Prototype t_bios_entry(whichint : integer; whichfunc : integer)

Purpose This function handles BIOS interrupt TPHRT timer requests.

Usage t_bios_entry($10,$03);

Side Effects None.

Explanation This function accepts timer entry calls from ROM BIOS
interrupt handlers.

Only $10 and $13 interrupt specifiers are valid. This
function is not meant to be explicitly called by the user.

See also t_bios_exit, TPHRTASM.ASM source code.


_____________________________________________________________________________



t_bios_exit

Prototype t_bios_exit(whichint : integer, whichfunc : integer)

Purpose This function handles BIOS interrupt TPHRT timer requests

Usage t_bios_exit($10,$03);

Side Effects None.

Explanation This function accepts timer exit calls from ROM BIOS
interrupt handlers.

Only $10 and $13 interrupt specifiers are valid. This
function is not meant to be explicitly called by the user.

See also t_bios_entry, TPHRTASM.ASM source code.


_____________________________________________________________________________












-7-


t_bios_fname

Prototype t_bios_fname(fname : string)

Purpose This function allows the user to specify a file name for
the BIOS timer report generated by t_bios_report(1).

Usage t_bios_fname('DISKTST.DAT');

Side Effects None. Modifies TPHRT data structure, makes no DOS or BIOS
calls.

Explanation By call t_bios_report(1), the BIOS timer report is sent to a
disk file, with the default 'BIOSPRO.TXT' as the default file
name. This function allows the user to specify another file
name for output. The full DOS drive:\path\name format is
used, with maximum string length of 66 characters.

See also t_bios_report

_____________________________________________________________________________


t_bios_report

Prototype t_bios_report(whereto : integer)

Purpose This function generates the BIOS interrupt timer report.

Usage t_bios_report(0);

Side Effects Calls DOS to do output. Not suitable for use in an interrupt
handler.

Explanation This function displays the following information for each
function of a profiled interrupt that had any activations:

Function number (decimal)
Function name
Number of activations
Total activation time
% of total interrupt activation time
Average activation time

Total elapsed time and activation count for the profiled
interrupt is also displayed.

The timer report has a title, which defaults to
'BIOS Profile Summary'. This can be changed with t_bios_rname.

The integer flag whereto specifies the report destination:
0 = CRT
1 = file BIOSPRO.TXT or change with t_bios_fname
2 = printer (PRN)

If any BIOS interrupt profiling is active when t_bios_report
is called, that profiling is suspended while the timer report
is generated, then resumed.

See also t_bios_fname, t_bios_rname

-8-



t_bios_reset

Prototype t_bios_reset(whichint : integer; whichfunc : integer);

Purpose This function allows the user to reset any or all
function timers for a specific profiled interrupt.

Usage t_bios_reset(DISK,$03); resets write sector timer
t_bios_reset(DISK,-1); resets all INT 13h timers

Side Effects None. Modifies TPHRT data structure, makes no DOS or BIOS
calls.

Explanation This function zeros both activation count and elapsed time
for a specified interrupt function timer.By passing -1 as the
function number, all timers for that interrupt will be reset.

Only CRT and DISK interrupt specifiers are valid

See also No related functions.


_____________________________________________________________________________



t_bios_resume

Prototype t_bios_resume(whichint : integer)

Purpose This function restores previously suspended BIOS profiling
for a specified interrupt.

Usage t_bios_resume(DISK);

Side Effects Changes interrupt vector for the interrupt specified.

Explanation This function restores interrupt profiling to a BIOS interrupt
whose profiling was suspended with t_bios_suspend. Function
timers are not reset.

CRT, DISK, and CRTDISK interrupt specifiers are valid.

See also t_bios_suspend


_____________________________________________________________________________










-9-




t_bios_rname

Prototype t_bios_rname(rname : string)

Purpose This function allows the user to specify a title for the BIOS
timer report.

Usage t_bios_rname('Disk Activity With Interleave = 2');

Side Effects None. Modifies TPHRT data structure, makes no DOS or BIOS
calls.

Explanation t_bios_report generates a timer summary with the default
title 'BIOS Profile Summary'. This function allows the user
to specify a different, more descriptive string. Maximum
string length is 80 characters. The string is centered on
the line.

See also t_bios_fname, t_bios_report


_____________________________________________________________________________



t_bios_start

Prototype t_bios_start(whichint : integer)

Purpose Initializes BIOS interrupt profiling.

Usage t_bios_start(CRT); starts INT 10h profiling
t_bios_start(DISK); starts INT 13h profiling
t_bios_start(CRTDISK); starts both 10h & 13h profiling

Side Effects Changes ISR vectors for the specified interrupt.

Explanation This function is called to start BIOS interrupt profiling.
ISR vectors are changed, TPHRT BIOS timer data is reset,
and profiling begins. t_start MUST be called prior to
t_bios_start.

Only CRT, DISK, and CRTDISK interrupt specifiers are valid.

See also t_bios_stop, t_start


_____________________________________________________________________________








-10-




t_bios_stop

Prototype t_bios_stop

Purpose Stops all BIOS interrupt profiling.

Usage t_bios_stop;

Side Effects Restores original ISR vectors for profiled interrupts

Explanation This function is called to when BIOS interrupt profiling is
no longer desired. It MUST be called prior to program
execution completion, and prior to t_stop. If program
execution fails prior to the call to t_bios_stop, the PC
must be immediately rebooted.

See also t_bios_start, t_stop


_____________________________________________________________________________



t_bios_suspend

Prototype t_bios_suspend(whichint : integer)

Purpose Temporarily suspend BIOS interrupt profiling

Usage t_bios_suspend(DISK);

Side Effects Restores original ISR vectors for the specified interrupt

Explanation This function suspends profiling of the specified BIOS
interrupt. Profiling may be restarted without resetting
the interrupt function timers by calling t_bios_resume.

CRT, DISK, and CRTDISK interrupt specifiers are valid.

See also t_bios_resume


_____________________________________________________________________________













-11-




t_diff

Prototype t_diff(start : tphrt_type; stop : tphrt_type) : longint;

Purpose Computes elapsed time between two timer calls.

Usage elapsed := t_diff(start, stop);

Side Effects None. No DOS or BIOS calls, no floating point calls.

Explanation This function returns the elapsed time in microseconds
between two TPHRT timestamps which were acquired with t_get.

See also t_get


_____________________________________________________________________________



t_entry

Prototype t_entry(timer : integer)

Purpose Starts a specific timer.

Usage t_entry(2);

Side Effects Interrupts are ON when t_entry returns. Makes no DOS or
BIOS calls.

Explanation This function causes the specified timer to begin counting
and to increment its activation count. The counter stops
counting and adds to its total elapsed time with a call to
t_exit.

Timers should be used in ascending order starting at 1.
Highest timer available is 100.

See also t_exit


_____________________________________________________________________________













-12-




t_exit

Prototype t_exit(timer : integer)

Purpose Stops a specific timer.

Usage t_exit(2);

Side Effects Interrupts are ON when t_exit returns. Makes no DOS or
BIOS calls.

Explanation This function causes the specified timer to stop counting
and to add the elapsed time for this activation to the total
elapsed time for this timer. Each t_entry call must have
a corresponding t_exit call.

See also t_entry


_____________________________________________________________________________



t_fname

Prototype t_fname(fname : string)

Purpose Changes the default report summary file name from PROFILE.TXT
to a user specified name.

Usage t_fname('NEWNAME.TXT');

Side Effects None. Modifies TPHRT data structure, makes no DOS or BIOS
calls.

Explanation t_report can send a timer report to a disk file, which uses
PROFILE.TXT as a default name. This function allows the
user to specify some other file name using the full DOS
drive:\path\name specification. Maximum string length is
66 characters.

See also t_report


_____________________________________________________________________________












-13-




t_get

Prototype t_get(var timestamp : tphrt_type)

Purpose Low level 8253 timer interface

Usage t_get(timestamp);

Side Effects Interrupts are enabled when t_get returns.

Explanation This function reads the 8253 timer chip and the BIOS
time of day clock to get a four byte high resolution
timer count. The layout of the tphrt_type structure is:

tphrt_type = record
ticks : word; { 838 ns timer ticks }
tocks : word; { 54.925 ms DOS TOD tocks }
end;

See also t_diff


_____________________________________________________________________________



t_name

Prototype t_name(timer : integer, name : tname)

Purpose Attaches a descriptive string to a specified timer.

Usage t_name(2,'2D FFT');

Side Effects None. Modifies TPHRT data structure, makes no DOS or BIOS
calls.

Explanation t_name allows the user to associate a descriptive string
with each timer. This string will appear next to the timer
number on the timer report generated by t_report. Maximum
string length is 20 characters.

See also t_report


_____________________________________________________________________________








-14-



t_report

Prototype t_report(whereto : integer)

Purpose Generates a summary of all timer activity

Usage t_report(0);

Side Effects Calls DOS to do output. Not suitable for use in an interrupt
handler.

Explanation This function displays the following information on all
active timers:
Timer description (from t_name)
Number of activations
Total activation time
Average activation time

A count is kept of the highest timer activated, and all
timers up to that number are displayed, so timers should
be used in ascending order starting at 1.

The timer report has a title, which defaults to
'Profile Summary'. This can be changed with t_rname.

The integer flag whereto specifies the report destination:
0 = CRT
1 = file PROFILE.TXT or change with t_fname
2 = printer (PRN)

See also t_name, t_rname, t_fname


_____________________________________________________________________________



t_reset

Prototype t_reset(timer : integer)

Purpose Allows the user to reset one or all timers

Usage t_reset(2);

Side Effects None. Modifies TPHRT data structure, makes no DOS or BIOS
calls.

Explanation This function zeros both activation count and elapsed time
for a specified timer (1-100). By passing -1 as the timer
number, all timers will be reset.

See also No other related functions.


_____________________________________________________________________________

-15-



t_resume

Prototype t_resume(timer : integer)

Purpose Restarts a previously suspended timer

Usage t_resume(2);

Side effects Interrupts are ON when t_resume returns. Makes no DOS or
BIOS calls.

Explanation This functions restarts a timer temporarily stopped with
t_suspend.

See also t_suspend


_____________________________________________________________________________



t_rname

Prototype t_rname(report_title : stromg)

Purpose Changes default timer report title from 'Profile Summary'
to a user specified string.

Usage t_rname('Timings with 20 Mhz 80387');

Side effects None. Modifies TPHRT data structure, makes no DOS or BIOS
calls.

Explanation t_report generates a timer summary with the default title
'Profile Summary'. This function allows the user to specify
a different, more descriptive string. Maximum string length
is 80 characters. The string is centered on the line.

See also t_report


_____________________________________________________________________________














-16-




t_start

Prototype t_start;

Purpose Initializes TPHRT timing primitives.

Usage t_start;

Side effects Changes 8253 timer to mode 2. Makes no DOS or BIOS calls.

Explanation This function initializes and calibrates the TPHRT timing
primitives, and must be called before any other TPHRT
functions are invoked.

See also t_stop


_____________________________________________________________________________



t_stop


Prototype t_stop;

Purpose Disables all TPHRT timing primitives.

Usage t_stop;

Side effects Changes 8253 timer back to mode 3. Makes no DOS or BIOS calls.

Explanation This function should be called when all active timers have
been stopped prior to program termination.

See also t_start


_____________________________________________________________________________

















-17-




t_suspend


Prototype t_suspend(timer : integer)

Purpose Temporarily stops an active timer.

Usage t_suspend(2);

Side effects Interrupts are ON when t_suspend returns. Makes no DOS or
BIOS calls.

Explanation This function allows a timer to be stopped and restarted
without an additional activation count being added. Useful
if you use activation counts to track the number of function
calls but for some reason want to stop the timer and restart
it again later in the same function.

See also t_resume.




































-18-