Power-Programmierung/CD2.mdf/c/library/dos/timer/c_timr20/c-timer.doc

Text File | 1992-06-10 | 13.4 KB | 367 lines

                              C-Timer version 2.0

                                    6-10-92

                                      by

                                  J  Podolak


INTRODUCTION:

   C-timer is a C code optimization tool written for Microsoft C that allows
   the programmer to measure with great accuracy the execution time of a C
   function call. C-timer can measure both library functions and custom
   written functions, and provides results in both time per call and calls
   per second. C-timer provides results with an accuracy of one microsecond.

   C-timer is an invaluable tool for determining how to write the fastest
   possible code, and can show the effects of compiler optimizations on
   code execution time.


FEATURES:

   User modifiable setup function allows the programmer to access command line
      parameters and prepare variables before testing the function.

   Output redirectable to a log file using standard DOS redirection commands.

   Timing range from 1 microsecond to 20 seconds.

   Automatically calls fast functions up to 64000 times and subtracts function
      call overhead to achieve accurate results on fast functions.

   Compensates for the number of arguments of the test function (0 - 5) and
      subtracts argument pushing overhead to provide accurate results.

   Runs PC timer at ten times the normal speed to provide better timing
      granularity.


PACKAGE CONTENTS:

    C-timer.doc - This file, the documentation for the C-timer package.
    C-timer.inf - Update history & registration information.
   C-timerS.obj - The Microsoft C SMALL model .obj module.
   C-timerL.obj - The Microsoft C LARGE model .obj module.
   Userfunc.c   - A sample .c module illustrating how to use C-timer.
   C-timer.src  - A password encoded zip file of source for C-timer.obj.
                  REGISTERED users will receive the password for this zip.

DESCRIPTION & USE:

   C-timer was written to allow easy implementation of testing for any
   function, and provides machine-independent execution timings. C-timer
   consists of an .obj module (provided in SMALL and LARGE models), and
   a simple .c module which the programmer must modify to call the desired
   test function.

   To use C-timer, the programmer must modify the .c file to call the desired
   test function, then compile the .c file and link it to the C-timer .obj
   file (C-timerS.obj for SMALL model, C-timerL.obj for LARGE model). The
   resulting .exe file is then run to provide execution timing information.

   The sample .c module provided is called userfunc.c and provides a template
   for how to use the C-timer package. Please refer to this file for more
   clarification of the procedures discussed.


A SAMPLE SESSION:

   Suppose you have written a new strcpy() routine, and would like to test
   it for speed. Assume that your function looks like this:

      void my_strcpy(char *dest, char *srce)
      {
         while(*srce)
            *dest++ = *srce++;

      }

   Edit the file userfunc.c and do the following:

      1. Near the top of the file, replace the line:

            void userfunc(unsigned int a, unsigned int b, unsigned int c);

         with

            void my_strcpy(char *, char *);

         Now you have prototyped the function.


      2. Go to the function_call() routine and replace the line:

            userfunc(arg1, arg2, arg3);

         with

            my_strcpy(new_string, old_string);

         Now you have told C-timer to call your function, my_strcpy().


      3. Near to the top of the file, replace the three lines:

            unsigned int arg1;
            unsigned int arg2;
            unsigned int arg3;

         with

            char new_string[80];
            char old_string[80];

         Now you have created the variables needed for your function.

      4. Go to the setup_userfunc() routine and add the following line
         above the closing brace of the routine:

            sprintf(old_string, "This is a test string of 34 chars.");

         Now you have prepared the variable old_string for your function,
         my_strcpy. If you wish, you may delete the other lines in
         setup_userfunc(), they simply print out the command line (if you do
         this, and you have the compiler set to warning level 4, you may see
         compilation warnings about unreferenced formal parameters argc,
         and argv; this is a harmless warning).

      5. Go to the userfunc() routine and delete it completely, replacing it
         with your function, for example:

            void my_strcpy(char *dest, char *srce)
            {
               while(*srce)
                  *dest++ = *srce++;

            }

          ADVANCED NOTE: Alternatively, you may place the test function in a
                         separately compiled module, as long as you prototype
                         it and call it in function_call().


      6. Save the file userfunc.c.

      7. Compile the file userfunc.c, for example:

            cl /c userfunc.c

      8. Link the userfunc.obj file to the c-timerS.obj (c-timerL.obj if
         you are using LARGE model), for example:

            link userfunc + c-timers, mytest.exe;

         This will produce an executable called mytest.exe.

      9. Run the program mytest.exe with 2 command line parameters, for
         example:

            mytest test_of_my_strcpy_34 2

         The first parameter is a text label for C-timer to identify
         your test function with. The second parameter is the number of
         arguments that your test function takes (in this case, two).

     10. View the results of the timing test for my_strcpy(). On a 20Mhz
         386, the results were:

            c:\ mytest test_of_my_strcpy_34 2
            Timing test_of_my_strcpy_34(), 2 arguments.
                    This takes up to 20 seconds...Done.

            test_of_my_strcpy_34() takes 0.086 ms/call, 11627 calls/sec.
                    64000 calls at 182 interrupts/second

            c:\

         This means that your function, my_strcpy(), takes 86 microseconds
         per call, when called to copy 34 characters, and can be called
         11627 times per second. The next line says that C-timer timed your
         function 64000 times at 182 clock ticks per second (ten times the
         standard clock rate) to arrive at this result.

   This seems pretty fast, but lets compare it to the standard library
   strcpy() function. Follow the steps below:

      Edit the file userfunc.c and do the following:

      1. Near the top of the file, add the line:

            #include <string.h>

         Now you have provided the prototype for the library strcpy() function.


      2. Go to the function_call() routine and replace the line:

            my_strcpy(new_string, old_string);

         with

            strcpy(new_string, old_string);

         Now you have told C-timer to call the standard library function,
         strcpy().

      3. Save the file userfunc.c.

      4. Compile the file userfunc.c, for example:

            cl /c userfunc.c

      5. Link the userfunc.obj file to the c-timerS.obj (c-timerL.obj if
         you are using LARGE model), for example:

            link userfunc + c-timers, stdtest.exe;

         This will produce an executable called stdtest.exe.

      9. Run the program stdtest.exe with 2 command line parameters, for
         example:

            stdtest test_of_strcpy_34 2

         The first parameter is a text label for C-timer to identify
         your test function with. The second parameter is the number of
         arguments that your test function takes (in this case, two).

      10.View the results of the timing test for strcpy(). On a 20Mhz 386,
         the results were:

            c:\ stdtest test_of_strcpy_34 2
            Timing test_of_strcpy_34(), 2 arguments.
                    This takes up to 20 seconds...Done.

            test_of_strcpy_34() takes 0.018 ms/call, 55555 calls/sec.
                    64000 calls at 182 interrupts/second

            c:\

         This means that the standard library function, strcpy(), takes only
         18 microseconds per call, when called to copy 34 characters, and can
         be called 55555 times per second. The next line says that C-timer
         timed the function 64000 times at 182 clock ticks per second (ten
         times the standard clock rate) to arrive at this result.

   So it would seem that the standard library strcpy() function is about 5
   times faster than your test function, my_strcpy(). Why? The library function
   was written in assembly language. You could probably come close to the
   speed of the library function if you worked in assembly language, but why
   reinvent the wheel? Incidentally, if you do write an assembly language
   routine and assemble it with Microsoft assembler, you can link it to the
   C-timer and userfunc modules to test its execution time, as well. Just
   follow the rules for writing an assembler routine to be called from C.

   If you would like a more permanent copy of the timing results, try using
   the standard DOS redirection commands. In the examples given above, the
   command lines would be:

      mytest test_of_my_strcpy_34 2 >> test.log

   and:

      stdtest test_of_strcpy_34 2 >> test.log

   This would produce a file called test.log which would contain the lines:

      Timing test_of_my_strcpy_34(), 2 arguments.

      test_of_my_strcpy_34() takes 0.086 ms/call, 11627 calls/sec.
              64000 calls at 182 interrupts/second

      Timing test_of_strcpy_34(), 2 arguments.

      test_of_strcpy_34() takes 0.018 ms/call, 55555 calls/sec.
              64000 calls at 182 interrupts/second

   Now you can see the value of the text label command line parameter, it
   makes log files easy to read, especially if you are testing a large
   number of functions.

   Try compiling with different optimizations to increase the speed of your
   functions, and use C-timer to generate a log file of the timing results.
   If you use the text label parameter creatively, you can easily log your
   results (try 'mytest "my_strcpy34 Oi Oa " 2 >> test.log' for example, to
   log compiler options.


USERFUNC.C DESCRIPTION:

   This file contains a skeletal example of how to use C-timer. There are two
   functions that must be linked with C-timer, and examples are provided in
   userfunc.c ( setup_userfunc() and function_call() ). Below is a description
   of each of the two functions.


   setup_userfunc() - This function is called ONCE by C-timer, prior to
                      beginning the timing procedure. It is passed the command
                      line (argc and argv) for you to make use of. Keep in mind
                      that argv[0] is the name of C-timer, argv[1] is the
                      name of the test function (or other text string), and
                      argv[2] is the number of parameters to the test function.
                      If your function needs additional command line parameters,
                      read them here as argv[3] through argv[n].

                      This sample function just prints out the command line.
                      If you have no need for a setup routine, you must still
                      provide this function, although it may consist of only
                      empty {}.


   function_call() -  This function is called repeatedly by C-timer during
                      the timing procedure. It should contain only a call to
                      the test function. Any additional code you need to
                      execute before calling your test function should be
                      placed in setup_userfunc(), described above.

                      You must provide this function, although the test
                      function may be called whatever you like, as long as
                      you prototype it near the top of the file.


CHANGES SINCE VERSION 1.0:

   Protects against Ctrl-C interrupts.

   Addition of a setup function to allow programmer to prepare variables.

   Command line now available to programmer to allow user-specific command
      line parameters.

   Output redirection via standard DOS redirection commands.


KNOWN BUGS:

   None.


DISCLAIMER:

   The author assumes no responsibility for the use of this program, as it
   is the users responsibility to determine the applicability and safety of
   the application.


REGISTRATION:

   This program is NOT free, but is user-supported-software.
   If you find this program useful, please send $10.00 to:

      J Podolak
      25W037 Keswick Lane
      Naperville, Illinois 60540

   Registration will provide you with the password for the zip source, and
   free updates to this program.


COMMENTS:

   If you have any comments or questions about the program, please leave
   a message for J Podolak on America Online, or write to the address
   above.