home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / library / dos / zen / ztimer / read.me < prev    next >
Encoding:
Text File  |  1992-01-30  |  8.2 KB  |  175 lines
  1.  
  2.                         The Zen Timer Library
  3.                         =====================
  4.  
  5.    This is a memory model independant 'C' callable library for timing code
  6. fragments with an accuracy of better than 10 microseconds (less when using
  7. the long period zen timer). The code was originally written by Michael Abrash
  8. for his book "Zen of Assembly language - Volume I, Knowledge". I modified the
  9. code and made it into a 'C' callable, memory model independant library and
  10. added the utility routines LZTimerCount() and PZTimerCount() to return an
  11. unsigned long integer representing the timed count in microseconds.
  12.  
  13. Using the timer
  14. ---------------
  15.  
  16.    To use the timer, isolate the piece of code you wish to time and bracket
  17. it with calls to PZTimerON (LZTimerON respectively) and PZTimerOff (LZTimerOff
  18. respectively). You can either call PZTimerReport (LZTimerReport respectively)
  19. which will display the count on the standard output device, or you can call
  20. PZTimerCount (LZTimerCount respectively) to obtain the count use it from
  21. within your C program. For example:
  22.  
  23. int i;
  24.  
  25. void main(void)
  26. {
  27.     LZTimerOn();
  28.     for (i = 0; i < 20000; i++)
  29.         i = i;                      /* Do some work */
  30.     LZTimerOff();
  31.     LZTimerReport();
  32. }
  33.  
  34. shows the simplest way to use the timer. The file "main.c" contains code
  35. to test both the precision and long period timers, so have a look at it to
  36. get an idea of how to use the timer.
  37.  
  38.    The precision timer gives the most accurate results, but can only be
  39. used for code that executes in less than 54ms, and you CANNOT turn
  40. interrupts on while the code is being timed (if you code goes into an
  41. infinite loop while using the precision timer you will need to reach for
  42. that elusive reset switch :-). Personally the long period timer is
  43. accurate enough for me and I generally use this exclusively.
  44.  
  45.    One point to note when using the long period time however, interrupts
  46. are ON while this timer executes. This means that every time you hit a key
  47. or move the mouse, the timed count will be longer that normal. Thus you
  48. should avoid hitting any keys or moving the mouse while timing code fragments
  49. if you want highly accurate results. It is also a good idea to insert a
  50. delay of about 1-2 seconds before turning the long period timer on if
  51. a key has just been pressed by the user (this includes the return key used
  52. to start the program from the command line!). Otherwise you may measure the
  53. time taken by the keyboard ISR to process the upstroke of the key that was
  54. just pressed.
  55.  
  56. Notes on compiling the library
  57. ------------------------------
  58.  
  59.    The library was compiled using Borland C++ 3.0 and Turbo Assembler 3.0.
  60. The code will NOT assemble under MASM, since it is written using
  61. Turbo Assemblers IDEAL mode syntax. You will need to modify it significantly
  62. to get it to assemble under MASM.
  63.  
  64.    I write all my code with 4 space tabs, so if you wish to view the source
  65. code the way I see it :-), you will need to set you editor to 4 space tabs
  66. (even the .ASM files use 4 space tabs). Alternatively you can view the
  67. source code files with "m.exe" included in the archive, a more replacement
  68. that I have written. It automatically expands tabs to 4 spaces (or any
  69. size you like with the -t option).
  70.  
  71.    The long period Zen Timer has been assembled to run on all computers,
  72. including the IBM PS/2 range of computers whose timer chips are not
  73. 100% compatible with the 8253. If you have read Michael's book, or you
  74. have had a look at the source code for the long period timer, you will
  75. know that you can re-assemble it with the PS2 equate set to 0 which will
  76. give more accurate results on computers with 100% compatible 8253 timer
  77. chips (note that this does not affect the precision Zen Timer - this works
  78. on all computers). I personally leave the PS2 equate set to 1, so that my
  79. code will work on any computer. Occasionally (and this is very rare - it
  80. has happend only once in the 3 odd months I have been using this code),
  81. the timer count will be out by 54 ms, but I find that I can live with
  82. this.
  83.  
  84.    The makefile included in the distribution is set up to build the library
  85. on my computer, but it should be very easy to modify for another installation
  86. (it took me five minutes to move it from my old 286 machine to my new
  87. 486/33 with a larger hard disk!). Consult the makefile to see how to do it.
  88.  
  89.    I have included the turboc.cfg file that I use to compile code from
  90. the command line using Borland C++ 3.0. You will need to modify the include
  91. file and library file directories for your system. If you have an earlier
  92. version of Borland C++, or Turbo C++ then most of the optimisation switches
  93. will not be valid.
  94.  
  95. Files in this archive
  96. ---------------------
  97.  
  98.     debug.h             - Header file for portable code
  99.     lztest.asm          - Shell program for timing assembler code
  100.     lztime.bat          - Batch file to automate assembler code timing
  101.     lztimer.asm         - Long Period Zen Timer source code
  102.     m.exe               - Replacement for more (with tab expansion!).
  103.     main.c              - Sample program source code
  104.     makefile            - Makefile for the Zen Timer library
  105.     model.mac           - Memory model independant macros for TASM
  106.     pztest.asm          - Shell program for timing assemble code
  107.     pztime.bat          - Batch file to automate assembler code timing
  108.     pztimer.asm         - Precision Zen Timer source code
  109.     read.me             - What you are reading :-)
  110.     turboc.cfg          - Configutation file for Borland C++ 3.0
  111.     ztimer.h            - Header file for the library
  112.     ztimer.lib          - The library itself
  113.     movtst.asm          - Sample assember test code
  114.     movtst2.asm         - Sample assembler code to overflow PZTimer
  115.  
  116.     Turbo Pascal related files:
  117.  
  118.     lztimer.pas         - Source code for the TP interface unit
  119.     lztimer.tpu         - Prebuilt Turbo Pascal unit for the interface
  120.     main.pas            - Turbo Pascal version of sample test code
  121.  
  122. Turbo Pascal Notes
  123. ------------------
  124.  
  125.    Duncan Murdoch kindly took the time to build a Turbo Pascal interface
  126. for the Zen Timer library, which requires Turbo Pascal 6.0 or above (so
  127. he tells me :-). Following are his notes on the interface unit.
  128.  
  129.    The interface to the assembler routines is written to be as simple as
  130. possible.  Void functions became procedures; the count functions returning
  131. unsigned long integers return signed longints.  Leading underscores were added
  132. to the procedure/function names to match the assembler source.
  133.  
  134.    Because of limitations in the linker, TP versions prior to 6.0 will
  135. *not* be able to use this unit.
  136.  
  137. Interfaced routines:
  138.  
  139. procedure _PZTimerOn;              Starts precision timer.
  140.  
  141. procedure _PZTimerOff;             Stops precision timer.
  142.  
  143. procedure _PZTimerReport;          Reports result of precision timing to
  144.                                    standard output.
  145.  
  146. function  _PZTimerCount : longint; Returns microsecond count for precision
  147.                                    timer.  May overflow, and return negative
  148.                                    value.  Value -1 signals timer overflow.
  149.  
  150. procedure _LZTimerOn;              The LZ routines are as above, but for
  151. procedure _LZTimerOff;             the long period timer.
  152. procedure _LZTimerReport;
  153. function  _LZTimerCount : longint;
  154.  
  155.    I have asked Duncan if it is possible for Turbo Pascal to handle 
  156. unsigned long integers, since times greater than about 35 minutes will 
  157. become negative when interpreted as a signed long integer. If this is not
  158. possible, then you will have to take this into account when using the
  159. library.
  160.  
  161. Well, thats it. I hope you find this library useful (I use it all the time
  162. to time my graphics routines). You can contact me with comments, queries and
  163. bug fixes as show below:
  164.  
  165. Internet:
  166.  
  167. Kendall Bennett                                 kjb@godzilla.cgl.citri.edu.au
  168. Duncan Murdoch (Turbo Pascal unit)              dmurdoch@watstat.uwaterloo.ca
  169.  
  170. Snail mail:                                     Kendall Bennett
  171.                                                 15 Stevenson Street
  172.                                                 Kew Melbourne Victoria 3101
  173.                                                 Australia
  174.  
  175.