home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / TPHRTV2.ZIP / TPHRTV2.DOC < prev   
Encoding:
Text File  |  1989-02-03  |  17.7 KB  |  673 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                                   TPHRT V2.00
  24.  
  25.                    Turbo Pascal High Resolution Timer Toolbox
  26.  
  27.  
  28.  
  29.  
  30.                                   Ryle Design
  31.  
  32.                    P.O. Box 22, Mt. Pleasant, Michigan  48804
  33.  
  34.                              CompuServe 73047,1765
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.                                  What is TPHRT? 
  43.  
  44. TPHRT (Turbo Pascal High Resolution Timer) is a software "toolbox" of routines 
  45. to manipulate one hundred different timers each with one microsecond resolution. 
  46. TPHRT makes it easy to very accurately time nearly any synchronous or
  47. asynchronous event your PC can encounter.  Since the timer routines calibrate
  48. themselves to the host PC speed at run-time a single executable file will yield
  49. accurate timings across all 80xxx PC compatible environments.  A complete report
  50. of all timer activity can be generated with a single TPHRT function call.
  51.  
  52. Some uses for TPHRT are:
  53.  
  54.     Source Code Timer/Profiler
  55.     --------------------------
  56.     By adding calls to TPHRT in source code under development, the execution of
  57.     that code can generate a detailed summary of execution time by program
  58.     subroutine and immediately show the developer the program's "hot spots"
  59.     that might benefit from further code or algorithm optimization.   Unlike
  60.     "binning" profilers that display the number of "hits" in a range of program
  61.     counter addresses, TPHRT provides a direct one to one correspondence
  62.     between source code and elapsed time with user defined granularity.  A
  63.     single line of source code can easily be timed with the insertion of two
  64.     TPHRT procedure calls.
  65.  
  66.     Hardware Performance Evaluator
  67.     ------------------------------
  68.     The high resolution and self calibration features of TPHRT make it ideal
  69.     for insertion in code to evaluate hardware performance.  Disk drives,
  70.     numeric processors and video controllers can all have their throughput
  71.     measured very accurately with TPHRT, and with one hundred timers at the
  72.     user's disposal, many device functions can be independently measured in a
  73.     single run.  The formatted timer report generated by TPHRT makes
  74.     compilation and interpretation of the test results quick and simple.
  75.  
  76.     Process Control Applications
  77.     ----------------------------
  78.     With TPHRT, process control and data acquisition applications that require
  79.     precise timing are easy to implement.  No longer will the application
  80.     developer have to make an educated guess as to how long a critical hardware
  81.     interrupt is taking to service - TPHRT timer calls can be inserted in the
  82.     interrupt handler and precise, accurate timing of the critical procedure is
  83.     assured.
  84.  
  85.     Timing and Scoring Equipment
  86.     ----------------------------
  87.     TPHRT is the perfect "timer engine" to build a timing and scoring system
  88.     for nearly any competitive event that requires high resolution timing.  
  89.     With it's one microsecond (0.000001) resolution, TPHRT surpasses
  90.     conventional sports timing equipment resolution and thus allows the
  91.     application developer to package both high resolution timing and complete 
  92.     event scoring in a single package.
  93.  
  94.  
  95.  
  96.  
  97.  
  98.                                       -1-
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.                                Distribution List 
  106.  
  107. The distribution you have received should contain the following:
  108.  
  109.     TPHRTV2.DOC     This document
  110.     TPHRT.TPU       Turbo Pascal V5.00 unit
  111.     DEMOV2.PAS      Simple demonstration of TPHRT functions
  112.  
  113.  
  114.                            Version 2.00 Enhancements 
  115.  
  116. Version 2.00 of TPHRT brings six new functions to the timer toolbox.  Briefly
  117. they are as follows:
  118.  
  119.     t_reset     Allows resetting of one or all active timers
  120.     t_ask_timer Queries a specified timer and returns activation and elapsed
  121.                 time counts
  122.     t_fname     Allows the user to specify a file name for the timer report
  123.     t_rname     Allows the user to specify a title for the timer report
  124.     t_suspend   Suspends an active timer temporarily
  125.     t_resume    Causes a previously suspended timer to resume activity
  126.  
  127. In addition, the version 1.00 function t_calib has been integrated into the
  128. t_start function and no longer needs to be explicitly called after t_start.  In
  129. the interest of backward compatibility the t_calib function has been retained
  130. in the TPHRT unit, but users should remove the t_calib calls as they update
  131. their code to use the new functions in version 2.00.
  132.  
  133. Complete information on all TPHRT functions is available in the reference
  134. chapter of this document.
  135.             
  136.  
  137.                      Additional Functions With Registration 
  138.  
  139. This copy of TPHRT is a shareware evaluation copy which you are encouraged to
  140. experiment with without obligation.  If you find this timer toolbox to be useful
  141. you are encouraged to register your evaluation copy with Ryle Design, who will
  142. in turn provide you with the following:
  143.     
  144.     1.  Documentation of the low level TPHRT timer functions
  145.  
  146.     2.  Functions to profile selected BIOS interrupts 
  147.  
  148.             t_bios_start        enables BIOS interrupt profiling
  149.             t_bios_stop         disables BIOS interrupt profiling
  150.             t_bios_suspend      suspends BIOS interrupt profiling
  151.             t_bios_resume       resumes BIOS interrupt profiling
  152.             t_bios_reset        resets BIOS timers
  153.             t_bios_ask          returns time & count for BIOS interrupt  
  154.             t_bios_report       generates BIOS timer summary
  155.             t_bios_fname        specifies file name for BIOS timer summary
  156.             t_bios_rname        specifies title for BIOS timer summary
  157.                 
  158.  
  159.  
  160.                                       -2-
  161.  
  162.  
  163.  
  164.  
  165.  
  166.     3.  Enhancements for users inserting TPHRT timers in interrupt handlers
  167.  
  168.     4.  Example code:
  169.  
  170.             SEEKTEST.PAS  - tests disk seek time
  171.             WATCH.PAS     - dual stopwatch driven by keyboard interrupt 9h
  172.             HITIME.PAS    - TSR high resolution timer    
  173.  
  174.     5.  Complete, carefully commented source code to the entire TPHRT library
  175.         including the t_bios extensions.
  176.  
  177.     6.  Technical support via CompuServ Easyplex mail.
  178.  
  179.  
  180. Registration is $7.50 which includes return shipping by first class mail in a
  181. crush proof disk envelope.  Ryle Design also has versions of the timer toolbox
  182. available for Turbo C V2.00 (TCHRT) and Microsoft C V5.1 (MSCHRT).  These
  183. are also available for $7.50 each from Ryle Design.  Note that the code for
  184. Microsoft C and Turbo C is different as Microsoft C does not support inline asm
  185. statements as Borland does.
  186.  
  187. A registration form is provided for your convenience as the last page of this
  188. document.
  189.  
  190.  
  191.                              V2.00 Quick Reference
  192.  
  193.     unit TPHRT;
  194.  
  195.     interface
  196.  
  197.     uses
  198.         printer;
  199.                                                      
  200.     type
  201.         tname = string[20];
  202.  
  203.     { procedure prototypes }
  204.  
  205.         procedure t_start;
  206.         procedure t_stop;
  207.         procedure t_calib;
  208.         procedure t_entry(tnum : integer);
  209.         procedure t_exit(tnum : integer);
  210.         procedure t_name(tnum : integer; name : tname);
  211.         procedure t_report(whereto : integer);
  212.  
  213.         { V2.00 enhancements }
  214.  
  215.         procedure t_fname(fname : string);
  216.         procedure t_rname(rname : string);
  217.         procedure t_reset(tnum : integer);
  218.         procedure t_ask_timer(tnum : integer; var hits : longint; 
  219.                               var elapsed : longint);
  220.         procedure t_suspend(tnum : integer);
  221.         procedure t_resume(tnum : integer);
  222.  
  223.  
  224.     implementation
  225.                                       -3-
  226.  
  227.  
  228.  
  229.  
  230.  
  231.                             TPHRT Function Reference
  232.  
  233.  
  234. t_ask_timer
  235.  
  236.     
  237. Prototype       t_ask_timer(tnum : integer; var hits : longint; 
  238.                             var elapsed : longint);
  239.  
  240. Purpose         To get current activation counts and accumulated elapsed time
  241.                 for a specific timer.
  242.  
  243. Usage           t_start(2,hits,elapsed);
  244.         
  245. Side Effects    None.  Queries TPHRT data structure, makes no DOS or BIOS
  246.                 calls.
  247.  
  248. Explanation     This function and t_report are the means by which the user
  249.                 gets timer results.  This function returns the number of
  250.                 timer activations and the amount of elapsed time (in micro-
  251.                 seconds) those activations consumed for a specific timer. 
  252.                 This function is useful when the user wishes information on 
  253.                 a specific timer or wishes to format his/her own timer report.
  254.  
  255. See also        t_report
  256.  
  257.  
  258. ________________________________________________________________________________
  259.  
  260.  
  261.  
  262. t_entry
  263.  
  264.  
  265. Prototype       t_entry(timer : integer)
  266.  
  267. Purpose         Starts a specific timer.
  268.  
  269. Usage           t_entry(2);
  270.  
  271. Side Effects    Interrupts are ON when t_entry() returns.  Makes no DOS or
  272.                 BIOS calls.
  273.  
  274. Explanation     This function causes the specified timer to begin counting
  275.                 and to increment its activation count.  The counter stops
  276.                 counting and adds to its total elapsed time with a call to
  277.                 t_exit.
  278.  
  279.                 Timers should be used in ascending order starting at 1.
  280.                 Highest timer available is 100.
  281.  
  282. See also        t_exit
  283.  
  284.  
  285.  
  286.  
  287.  
  288.                                       -4-
  289.  
  290.  
  291.  
  292.  
  293. t_exit
  294.  
  295.  
  296. Prototype       t_exit(timer : integer)
  297.  
  298. Purpose         Stops a specific timer.
  299.  
  300. Usage           t_exit(2);
  301.  
  302. Side Effects    Interrupts are ON when t_exit() returns.  Makes no DOS or
  303.                 BIOS calls. 
  304.  
  305. Explanation     This function causes the specified timer to stop counting
  306.                 and to add the elapsed time for this activation to the total
  307.                 elapsed time for this timer.  Each t_entry call must have 
  308.                 a corresponding t_exit call.
  309.  
  310. See also        t_entry
  311.  
  312.  
  313. ________________________________________________________________________________
  314.  
  315.  
  316.  
  317. t_fname
  318.  
  319.  
  320. Prototype       t_fname(filename : string)
  321.  
  322. Purpose         Changes the default report summary file name from PROFILE.TXT
  323.                 to a user specified name.
  324.  
  325. Usage           t_fname('NEWNAME.TXT');
  326.  
  327. Side Effects    None.  Modifies TPHRT data structure, makes no DOS or BIOS
  328.                 calls.
  329.  
  330. Explanation     t_report can send a timer report to a disk file, which uses
  331.                 PROFILE.TXT as a default name.  This function allows the
  332.                 user to specify some other file name using the full DOS
  333.                 drive:\path\name specification.  Maximum string length is
  334.                 66 characters.
  335.  
  336. See also        t_report
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.                                       -5-
  353.  
  354.  
  355.  
  356.  
  357. t_name      
  358.  
  359.  
  360. Prototype       t_name(timer : integer; name : tname)
  361.  
  362. Purpose         Attaches a descriptive string to a specified timer.
  363.  
  364. Usage           t_name(2,'2D FFT');
  365.  
  366. Side Effects    None.  Modifies TPHRT data structure, makes no DOS or BIOS
  367.                 calls.
  368.  
  369. Explanation     t_name allows the user to associate a descriptive string
  370.                 with each timer.  This string will appear next to the timer
  371.                 number on the timer report generated by t_report.  Maximum
  372.                 string length is 20 characters.
  373.  
  374. See also        t_report
  375.  
  376.  
  377. ________________________________________________________________________________
  378.  
  379.  
  380.  
  381. t_report        
  382.  
  383.  
  384. Prototype       t_report(whereto : integer)
  385.  
  386. Purpose         Generates a summary of all timer activity
  387.  
  388. Usage           t_report(0);
  389.  
  390. Side Effects    Calls DOS to do output.  Not suitable for use in an interrupt
  391.                 handler.
  392.  
  393. Explanation     This function displays the following information on all
  394.                 active timers:
  395.                     Timer description (from t_name)
  396.                     Number of activations
  397.                     Total activation time
  398.                     Average activation time
  399.  
  400.                 A count is kept of the highest timer activated, and all
  401.                 timers up to that number are displayed, so timers should
  402.                 be used in ascending order starting at 1.
  403.  
  404.                 The timer report has a title, which defaults to 
  405.                 "Profile Summary".  This can be changed with t_rname.
  406.  
  407.                 The integer flag whereto specifies the report destination:
  408.                     0 = CRT
  409.                     1 = file PROFILE.TXT or change with t_fname
  410.                     2 = printer (PRN)
  411.                                 
  412. See also        t_name, t_rname, t_fname                    
  413.  
  414.  
  415.  
  416.                                       -6-
  417.  
  418.  
  419.  
  420.  
  421. t_reset
  422.  
  423.  
  424. Prototype       t_reset(timer : integer)
  425.  
  426. Purpose         Allows the user to reset one or all timers
  427.  
  428. Usage           t_reset(2);
  429.  
  430. Side Effects    None.  Modifies TPHRT data structure, makes no DOS or BIOS
  431.                 calls.
  432.  
  433. Explanation     This function zeros both activation count and elapsed time
  434.                 for a specified timer (1-100).  By passing -1 as the timer
  435.                 number, all timers will be reset.
  436.  
  437. See also        No other related functions.
  438.  
  439.  
  440.  
  441. ________________________________________________________________________________
  442.  
  443.  
  444.  
  445. t_resume
  446.  
  447.  
  448. Prototype       t_resume(timer : integer)
  449.  
  450. Purpose         Restarts a previously suspended timer
  451.  
  452. Usage           t_resume(2);
  453.  
  454. Side effects    Interrupts are ON when t_resume returns.  Makes no DOS or
  455.                 BIOS calls.
  456.  
  457. Explanation     This functions restarts a timer temporarily stopped with
  458.                 t_suspend.
  459.  
  460. See also        t_suspend
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.                                       -7-
  481.  
  482.  
  483.  
  484.  
  485. t_rname
  486.  
  487.  
  488. Prototype       t_rname(rname : string)
  489.  
  490. Purpose         Changes default timer report title from "Profile Summary"
  491.                 to a user specified string.
  492.  
  493. Usage           t_rname('Timings with 20 Mhz 80387');
  494.  
  495. Side effects    None.  Modifies TPHRT data structure, makes no DOS or BIOS
  496.                 calls.
  497.  
  498. Explanation     t_report generates a timer summary with the default title
  499.                 "Profile Summary".  This function allows the user to specify
  500.                 a different, more descriptive string.  Maximum string length
  501.                 is 80 characters.  The string is centered on the line.
  502.  
  503. See also        t_report
  504.  
  505.  
  506. ________________________________________________________________________________
  507.  
  508.  
  509.  
  510. t_start
  511.  
  512.                        
  513. Prototype       t_start
  514.  
  515. Purpose         Initializes TPHRT timing primitives.  
  516.  
  517. Usage           t_start;
  518.  
  519. Side effects    Changes 8253 timer to mode 2.  Makes no DOS or BIOS calls.
  520.  
  521. Explanation     This function initializes and calibrates the TPHRT timing 
  522.                 primitives, and must be called before any other TPHRT
  523.                 functions are invoked.
  524.  
  525. See also        t_stop
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.                                       -8-
  545.  
  546.  
  547.  
  548.  
  549. t_stop
  550.  
  551.  
  552. Prototype       t_stop
  553.  
  554. Purpose         Disables all TPHRT timing primitives.
  555.  
  556. Usage           t_stop;
  557.  
  558. Side effects    Changes 8253 timer back to mode 3.  Makes no DOS or BIOS calls.
  559.                 
  560. Explanation     This function should be called when all active timers have
  561.                 been stopped prior to program termination.
  562.  
  563. See also        t_start
  564.  
  565.  
  566. ________________________________________________________________________________
  567.  
  568.  
  569.  
  570. t_suspend
  571.  
  572.  
  573. Prototype       t_suspend(timer : integer)
  574.  
  575. Purpose         Temporarily stops an active timer.
  576.  
  577. Usage           t_suspend(2);
  578.  
  579. Side effects    Interrupts are ON when t_suspend returns.  Makes no DOS or
  580.                 BIOS calls.
  581.  
  582. Explanation     This function allows a timer to be stopped and restarted 
  583.                 without an additional activation count being added.  Useful
  584.                 if you use activation counts to track the number of function
  585.                 calls but for some reason want to stop the timer and restart
  586.                 it again later in the same function.
  587.  
  588. See also        t_resume.                
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.                                       -9-
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.                             TPHRT Registration Form
  618.  
  619.  
  620.  
  621.     Name __________________________________________________________________
  622.  
  623.     Address _______________________________________________________________
  624.  
  625.     City/State/Zip ________________________________________________________
  626.  
  627.     Daytime Telephone _____________________________________________________
  628.  
  629.     CompuServ ID (for tech support) _______________________________________
  630.  
  631.     Where did you get your copy of TPHRT?  ________________________________
  632.  
  633.     What is your primary use of TPHRT? ____________________________________
  634.  
  635.     Comments regarding this product _______________________________________
  636.  
  637.     _______________________________________________________________________
  638.  
  639.     _______________________________________________________________________
  640.  
  641.     _______________________________________________________________________
  642.  
  643.  
  644.     Check Products desired:
  645.  
  646.  
  647.     ____    TPHRT Registered Version (Turbo Pascal V5.0) ............  7.50
  648.  
  649.     ____    TCHRT Registered Version (Turbo C V2.0) .................  7.50
  650.  
  651.     ____    MSCHRT Registered Version (Microsoft C V5.1/MSDOS) ......  7.50
  652.  
  653.     ____    All three of the above (save 2.50) ...................... 20.00
  654.  
  655.  
  656.             Subtotal ................................................ _____
  657.  
  658.             
  659.             Michigan residents add 4% sales tax ..................... _____
  660.  
  661.  
  662.             Total enclosed (__check __money order) .................. _____
  663.  
  664.  
  665.     Remit to:   Ryle Design
  666.                 P.O. Box 22
  667.                 Mt. Pleasant, Michigan 48804
  668.  
  669.  
  670.  
  671.  
  672.  
  673.