home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / turbo_c / tcprof.arc / TCPROF.DOC next >
Text File  |  1988-10-04  |  41KB  |  1,239 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.                      Turbo C profiler (TCPROF version 1.5)
  33.                         Copyright (C) 1988 Andre Nancoz
  34.                               all rights reserved
  35.  
  36.  
  37.  
  38.  
  39.                                Contents
  40.  
  41.  
  42.  
  43.           INTRODUCTION                                               1
  44.              Overview  . . . . . . . . . . . . . . . . . . . . . . . 1
  45.              History . . . . . . . . . . . . . . . . . . . . . . . . 1
  46.              Copyright information . . . . . . . . . . . . . . . . . 1
  47.              Trademark information . . . . . . . . . . . . . . . . . 1
  48.              System requirements . . . . . . . . . . . . . . . . . . 2
  49.              Compilation and execution requirements  . . . . . . . . 2
  50.              Restrictions and caveats  . . . . . . . . . . . . . . . 2
  51.  
  52.           USING THE PROFILER                                         4
  53.              Executing the profiler  . . . . . . . . . . . . . . . . 4
  54.              Profiler options  . . . . . . . . . . . . . . . . . . . 4
  55.  
  56.           INPUT/OUTPUT                                               6
  57.              File usage  . . . . . . . . . . . . . . . . . . . . . . 6
  58.              Report content  . . . . . . . . . . . . . . . . . . . . 6
  59.  
  60.           MEMORY USAGE                                               9
  61.              Lines within functions  . . . . . . . . . . . . . . . . 9
  62.              Functions only  . . . . . . . . . . . . . . . . . . . . 9
  63.  
  64.           ERROR MESSAGES                                            10
  65.  
  66.           APPENDIX A                                                11
  67.              LISTING 1..............................................11
  68.              EXAMPLE 1..............................................12
  69.              EXAMPLE 2..............................................13
  70.  
  71.           APPENDIX B                                                14
  72.              Registered user information . . . . . . . . . . . . . .14
  73.              Registered user features  . . . . . . . . . . . . . . .14
  74.  
  75.           APPENDIX C                                                17
  76.              PROBLEM REPORT/SUGGESTIONS  . . . . . . . . . . . . . .17
  77.              REGISTERED USER ORDER FORM  . . . . . . . . . . . . . .18
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.                                        i
  101.  
  102.  
  103.  
  104.                              INTRODUCTION
  105.  
  106.  
  107.      Overview
  108.  
  109.           TCPROF will show you where the most time is being spent in a
  110.           program  written with Borlands' Turbo C.  The output report
  111.           indicates the percentage of time (numerically and
  112.           graphically) spent in each function and line of your program.
  113.           Several options allow you to vary the amount of information
  114.           shown on the report.  No changes to your source code are
  115.           required in order to run the profiler.  The hardware timer is
  116.           read but not modified.
  117.  
  118.           This program is distributed at no charge and is designed for
  119.           users who have an occasional need or curiosity about the
  120.           efficiency of their programs.  A registered user version of
  121.           this program (TCPROFRU) is available which allows more
  122.           extensive tailoring of the output and can reduce the amount
  123.           of overhead and size of the report (See Appendix B for more
  124.           information).
  125.  
  126.  
  127.      History
  128.  
  129.           Version 1.0   First release.
  130.  
  131.           Version 1.5   Update for Turbo C release 2.0.  Timing logic
  132.                         change to increase consistency.
  133.  
  134.  
  135.      Copyright information
  136.  
  137.                 Turbo C profiler program TCPROF and documentation
  138.                        Copyright (C) 1988 by Andre Nancoz
  139.                                all rights reserved
  140.  
  141.           The Turbo C profiler is not public domain software.  TCPROF
  142.           and it's accompanying documentation may be distributed freely
  143.           provided no fee is charged and it is not part of a package
  144.           for which a charge is made.  Furthermore, the program and
  145.           documentation must be distributed with no modifications.
  146.  
  147.           TCPROF is distributed as-is with no expressed or implied
  148.           warranties.
  149.  
  150.  
  151.      Trademark information
  152.  
  153.           Turbo C is a trademark of Borland International Inc.
  154.           IBM-PC is a trademark of International Business Machines
  155.           Corporation.
  156.           MS-DOS is a trademark of Microsoft Corporation.
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165. October 4, 1988                                                 INTRODUCTION - 1
  166.  
  167.  
  168.  
  169.      System requirements
  170.  
  171.           IBM-PC and true compatibles.
  172.           MS-DOS version 3.0 or above.
  173.           Minimum memory required is 39K above that required for the
  174.           program being profiled.  Additional memory may be required
  175.           depending on the program being profiled.  See the section on
  176.           memory usage for more information.
  177.  
  178.  
  179.      Compilation and execution requirements
  180.  
  181.           In order to run a program under the profiler the program must
  182.           be compiled with, at least, the following options:
  183.  
  184.           TCC command line;
  185.             -y generate line numbers in .obj file.
  186.             -M full link map.
  187.  
  188.           TLINK command line;
  189.             /m or /s to generate a link map.
  190.             /l output line numbers in link map.
  191.  
  192.           Integrated Development Environment;
  193.             O/C/Code generation/Line numbers..On
  194.             O/L/Map file..Publics or Detailed
  195.  
  196.           NOTE:  Line numbers and map options are required even if the
  197.           functions only option is used.
  198.  
  199.           When running the profiler the .EXE and the .MAP file must be
  200.           available using the standard DOS search path, i.e. the
  201.           current directory of the current drive is checked first.  If
  202.           not found, each directory in the environment PATH is checked.
  203.  
  204.  
  205.      Restrictions and caveats
  206.  
  207.           Timer
  208.           If your program steals the timer interrupt it must chain to
  209.           the previous owner of the interrupt.  The profiler does NOT
  210.           modify the timer rate but does read the timer chip.  If your
  211.           program modifies the timer rate the profiler may still
  212.           operate correctly.
  213.  
  214.           Single Step and Interrupt 3
  215.           If your program uses these, the profiler will not work
  216.           correctly.  It may be reboot time.
  217.  
  218.           longjmp
  219.           Likely to mess up timing.
  220.  
  221.           Static functions
  222.           All line numbers for a function defined as static will be
  223.           included with the last non-static function.  This will likely
  224.           cause the warning message regarding inaccurate timing.  The
  225.           profiler keeps track of entrances to and exits from
  226.  
  227.  
  228.  
  229.  
  230.                                                                 INTRODUCTION - 2
  231.  
  232.  
  233.  
  234.           functions.  Since static function addresses do not appear in
  235.           the link map the profiler does not have an accurate
  236.           indication of where the static function began or where the
  237.           previous non-static function ended.
  238.  
  239.           Assembler
  240.           Assembler modules should be assembled without the line number
  241.           option(TASM /ZD).  The profilers' timing resolution cannot
  242.           handle interrupts at each machine instruction.
  243.  
  244.           Unlike previous versions of Turbo C, version 2.0 passes the
  245.           line number option on to TASM when inline assembler is used.
  246.           When a single machine instruction is generated for a line of
  247.           C source it is likely that they will be reported as 0% due to
  248.           the profilers timing resolution.  Some functions such as
  249.           enable(), disable(), etc. will cause the same problem.  Use
  250.           of the emit() function to output one instruction per line
  251.           will also cause the problem.
  252.  
  253.           If you are using previous versions of Turbo C, use of the asm
  254.           keyword within a C module will cause no line numbers to be in
  255.           the map, TCC invokes MASM without the line number option.
  256.           Therefore, functions which contain the asm keyword should be
  257.           compiled in a separate module from functions which you wish
  258.           to time.
  259.  
  260.           TSRs
  261.           I have tested the profiler with several TSRs with no
  262.           problems.  The timing may be different for the same program
  263.           depending on which TSRs are loaded.  Therefore, in order to
  264.           compare results of two profiler runs, the same environment
  265.           should be used for each run.  Of course activating a TSR
  266.           during a profiler run would disturb the timing.
  267.  
  268.           Bugs
  269.           This program is not a debugger and expects a reasonably
  270.           behaved program.  The profiler may be useful in detecting
  271.           some problems such as loops or functions executing the wrong
  272.           number of times or not executing at all, etc.
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.                                                                 INTRODUCTION - 3
  296.  
  297.  
  298.  
  299.                           USING THE PROFILER
  300.  
  301.  
  302.      Executing the profiler
  303.  
  304.           TCPROF [prof options] program-name [program-name options]
  305.             The brackets [] denote optional information, they are
  306.             not entered.
  307.  
  308.           If the program-name is not entered, help information is
  309.           displayed.
  310.  
  311.           Program-name options are passed to program-name in the same
  312.           manner as if the program was executed stand-alone.  The
  313.           argv[0] parameter contains program-names' full path.  The
  314.           profiler report is written to stdout, any redirection applies
  315.           to both program-name and the profiler report.  The profiler
  316.           uses stderr for error messages which cause it to abort the
  317.           run, also for a few messages to the console when stdout is
  318.           redirected.
  319.  
  320.  
  321.      Profiler options
  322.  
  323.           Profiler options may be entered in upper or lower case.  The
  324.           leading character may be either a - or a /.  All profiler
  325.           options must precede the name of the program to be profiled.
  326.  
  327.           -F            Profile by function.  The default is a detailed
  328.                         report by line number within function.  Using
  329.                         this option creates an output report with only
  330.                         one line per function and substantially reduces
  331.                         the profiler overhead when your program is
  332.                         running.
  333.  
  334.  
  335.           -Cnn          Print only lines whose execution count is equal
  336.                         to or greater than nn. The default value is 0.
  337.                         This option only influences the amount of
  338.                         report output.  The option has no effect if the
  339.                         -F option is chosen.  The nn is interpreted as
  340.                         an unsigned long integer.
  341.  
  342.           -Lnn          Number of lines per page.  The default is 25.
  343.                         If nn is omitted, 0 or an invalid number, the
  344.                         default is 58 (a good value for 8.5 inch
  345.                         printed output).  This option does not change
  346.                         the "pause between each page" output action,
  347.                         which is controlled by whether or not stdout
  348.                         has been redirected.
  349.  
  350.           -Snn          This option controls an internal memory
  351.                         allocation parameter.  Entry to a function
  352.                         requires a word on an internal stack, the word
  353.                         is released at function exit.  The value
  354.                         specified is the number of words to allocate.
  355.                         The maximum is 32751 minus the number of
  356.  
  357.  
  358.  
  359.  
  360.                                                           USING THE PROFILER - 4
  361.  
  362.  
  363.  
  364.                         functions profiled.  It should only be required
  365.                         if your program uses recursion.   The default
  366.                         value is 10.  If the warning message "Timing
  367.                         may be inaccurate" occurs then this parameter
  368.                         should be used.  It should be set to the
  369.                         maximum level of recursions that can occur at
  370.                         any one time.
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.                                                           USING THE PROFILER - 5
  426.  
  427.  
  428.  
  429.                              INPUT/OUTPUT
  430.  
  431.  
  432.      File usage
  433.  
  434.           When the program to be profiled is run only the standard
  435.           Turbo C start up files are open.  The spawn function passes
  436.           these files to the program to be run.  The profiler uses
  437.           stdout and stderr before and after running your program.  Any
  438.           redirection applies to both the profiler and the program
  439.           being profiled.  Delimiter lines are written by the profiler
  440.           to stdout before and after running your program.
  441.  
  442.           Besides the program to be profiled, the .MAP file must be
  443.           available for read only access, this file is not open while
  444.           your program is running.  All file are located via the
  445.           standard DOS path search.
  446.  
  447.  
  448.      Report content
  449.  
  450.           The profile report is written to stdout with a default of 25
  451.           lines to the page, the L option can be used to change the
  452.           default.  If stdout has not been redirected the output will
  453.           pause at the end of each page and you may either display the
  454.           next page or cancel the remaining output, a clear screen is
  455.           issued between each page.  When output has been redirected,
  456.           no pause or clear screen occurs between pages.
  457.  
  458.           Appendix A contains a listing and two reports of a small test
  459.           program.  The first report is by line number.  This report
  460.           exhibits very high profiler overhead since majority of time
  461.           is spent within loops which generate a small number of
  462.           machine instructions per line of C code.  In more realistic
  463.           programs overhead is in the 30% range.  The second report is
  464.           the same program but it was run with the functions only
  465.           option.
  466.  
  467.           Only functions which are compiled with the line number option
  468.           "on" are shown on the report.  The time for functions
  469.           compiled without line numbers are included in the lines of
  470.           your program from where they are called.  As a consequence,
  471.           all the time for the system run time library functions (such
  472.           as printf) will be included in the lines from which they are
  473.           called.  In the test program line 23 took 1 percent of the
  474.           main functions' time, this includes the time it took to
  475.           execute the printf function (with redirection to disk).  On
  476.           the other hand, the time for line 19 only includes the time
  477.           to call and return from test_func, since test_func line
  478.           numbers are included in the map.
  479.  
  480.           The first page of output contains general information about
  481.           the program being profiled.  In reality this may be many
  482.           pages of output since it contains the stdout of the program
  483.           being profiled.  The options section on this page shows all
  484.           the profiler options which were in effect during this
  485.           execution.
  486.  
  487.  
  488.  
  489.  
  490.                                                                 INPUT/OUTPUT - 6
  491.  
  492.  
  493.  
  494.           Prior to running your program, the .MAP file is analyzed and
  495.           a table is built in memory.  After this is done the amount of
  496.           memory available to run your program is printed.
  497.  
  498.           The "parameters" line contains the argv[0] to be passed to
  499.           your program, subsequent line(s) contain argv[1] to argv[n]
  500.           parameters each enclosed in quotes.  A line is then output to
  501.           delimit the stdout of your program from that of the profiler,
  502.           it contains the full path and name of the program to be
  503.           executed.  If stdout has not been redirected the profiler
  504.           will pause with a message allowing you to cancel execution or
  505.           run the profile, optionally you may clear the screen prior to
  506.           running your program.
  507.  
  508.           After returning from your program, a line is output giving
  509.           the return code and the calculated time your program would
  510.           have taken if the profiler had not been used.  This time is
  511.           the basis for the percentage calculations made in the body of
  512.           the report.  The next line contains the start date, time, end
  513.           time and the percentage of the elapsed time spent within the
  514.           profiler.
  515.  
  516.           The body of the report starts on the next page.  In Appendix
  517.           A, example 1 is lines within functions, example 2 is a
  518.           functions only report.
  519.  
  520.           Whenever a new module is encountered in the .MAP file a line
  521.           is output with the module name.  When the beginning of a
  522.           function is identified a line is output with the name, the
  523.           percentage of time the function executed as compared to your
  524.           programs total time from page 1 and a graphic representation
  525.           of the percentage.  In addition, for a functions only report
  526.           the count column contains the number of times the function
  527.           was executed, for a lines within function report this count
  528.           appears on the first line within the function.
  529.  
  530.           The line number report has additional information.  The first
  531.           column contains the starting address of the line, the line
  532.           number, the number of times the line was executed, the time
  533.           taken by the line as a percentage of the programs' time, the
  534.           time taken by the line as a percentage of the functions' time
  535.           and a graphic representation of the percentages.
  536.  
  537.           Each column in the graph represents approximately 2.5%.  Four
  538.           characters are used within the graph, asterisks, periods,
  539.           equal signs and dashes.  The asterisks are used for function
  540.           lines only, no other characters appear on these graph lines.
  541.           Even though a report by lines is requested, if a function is
  542.           not executed only the function line will appear on the
  543.           report.  The period only appears in the first column of the
  544.           graph, it is used when a line was executed at least once but
  545.           the time was less than 2.5%.  The end of the equal signs
  546.           represents the lines' time compared to the total time.  The
  547.           end of the dashes represents the lines' time compared to the
  548.           functions' time.
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.                                                                 INPUT/OUTPUT - 7
  556.  
  557.  
  558.  
  559.           For the lines within functions report, the format of the
  560.           source file can affect the report.  The listing in Appendix A
  561.           contains some examples which will be referred to in the
  562.           following discussion.  The source for lines 33 and 34, and
  563.           line 39 are essentially the same and generate identical
  564.           machine instructions.  On the other hand, the report is
  565.           different for these two instruction sequences due to the map
  566.           output.  The compiler generates the initialization code of
  567.           the "for loop" and outputs the line address for the .MAP
  568.           file.  Since the calculation is contained on the same line
  569.           nothing is output to the .MAP file for it.  Therefore, line
  570.           39 reports that the line was executed only once and all the
  571.           time for the loop is included with line 39.  In the case of
  572.           lines 33 and 34, the compiler outputs the line 33 address for
  573.           the initialization code and the line 34 address for the
  574.           calculation which shows 19999 executions of the expression.
  575.           In version 2 of Turbo C other loop constructs (while, do) are
  576.           now generated similarly, so that lines 21 and 37 are now
  577.           reported in the same manner as line 39.
  578.  
  579.           All times for the last line of a function are reported with
  580.           the line which called the function.  Therefore for best
  581.           results, the closing bracket of a function should appear on a
  582.           separate line.  The count for the last line of a function is
  583.           correct.
  584.  
  585.           The difference in times between lines 21 and 39 indicate the
  586.           efficiencies of register variables.  In the main function two
  587.           dummy variables were allocated as registers so that the other
  588.           variables, which are used in line 21, could not be
  589.           automatically assigned by the compiler to registers.  In
  590.           test_func the variables for the loop were allocated to
  591.           registers.
  592.  
  593.           In version 2.0 of Turbo C the compiler outputs line numbers
  594.           to the .MAP file for floating point instructions.  Therefore,
  595.           these lines are now reported correctly.
  596.  
  597.           If you are using version 1.5 of Turbo C, lines 41 and 42
  598.           exhibit a problem when using floating point.  If the first
  599.           machine instruction to be generated on a line is for a
  600.           floating point operation the compiler does not output a line
  601.           number for the .MAP file.  Therefore, line 42 does not appear
  602.           in the report and all the time for line 42 is reported in
  603.           line 41.  If you need to see one or more floating point lines
  604.           separately the only option would be to precede each statement
  605.           with a non-floating point statement, such as an increment of
  606.           a dummy integer variable (better yet, upgrade to version 2,
  607.           it's worth it).
  608.             Example:  dummy++; r = a * b;  /* on one line */
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.                                                                 INPUT/OUTPUT - 8
  621.  
  622.  
  623.  
  624.                              MEMORY USAGE
  625.  
  626.  
  627.      Lines within functions
  628.  
  629.           "Memory required" =
  630.           16 * "number of lines mapped" +
  631.           2  * ("number of functions within the line map" +
  632.                 "value of -S option") +
  633.           13 * "number of modules within the line map" +
  634.           "your program requirements" + 39k
  635.  
  636.  
  637.      Functions only
  638.  
  639.           "Memory required" =
  640.           16 * "number of functions within the line map" * 2 +
  641.           2  * ("number of functions within the line map" +
  642.                 "value of -S option") +
  643.           13 * "number of modules within the line map" +
  644.           "your program requirements" + 39k
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.                                                                 MEMORY USAGE - 9
  686.  
  687.  
  688.  
  689.                             ERROR MESSAGES
  690.  
  691.  
  692.           Return
  693.           Code    Message
  694.  
  695.           35      DOS version must be 3.0 or later.
  696.  
  697.           36      Parameter invalid in response file.
  698.  
  699.           37      File not found (.exe and .map required).
  700.  
  701.           38      Invalid map file, no line numbers.
  702.                   In the chapter "INTRODUCTION" see section "Compiler
  703.                   and execution requirements".
  704.  
  705.           39      Insufficient memory.
  706.  
  707.           40      Logic.
  708.                   This message is accompanied by other information.  If
  709.                   it should occur please notify me, giving the full
  710.                   message displayed, details of your system and compile
  711.                   options used on the program being profiled.
  712.  
  713.           41      Not a Turbo C program.
  714.  
  715.           42      Invalid map file, no public values found.
  716.                   Refer to the section "Compiler and execution
  717.                   requirements".
  718.  
  719.           43      NOTE:  Timing inaccurate, see -S in documentation.
  720.                   Refer to the section "Profiler options".
  721.  
  722.           44      NOTE:  Timing inaccurate, see caveats in
  723.                   documentation.
  724.                   See the discussion on static functions under
  725.                   "Restrictions and caveats".
  726.  
  727.           99      Parameter display or error.
  728.  
  729.                   All return codes below 35 are identical to the errno
  730.                   values used by Turbo C.
  731.  
  732.  
  733.  
  734.  
  735.  
  736.  
  737.  
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.                                                              ERROR MESSAGES - 10
  751.  
  752.  
  753.  
  754.                                    APPENDIX A
  755.  
  756.  
  757.                              ---------------------------------
  758.                                    LISTING 1
  759.                              ---------------------------------
  760.  
  761.            1  #include <stdio.h>
  762.            2  #include <stdlib.h>
  763.            3
  764.            4
  765.            5
  766.            6
  767.            7  /*      Prototype Definitions      */
  768.            8  void test_func(void);
  769.            9  /* End Prototypes  */
  770.           10
  771.           11  #define LOOP_CNT 20000
  772.           12
  773.           13  main()
  774.           14  {
  775.           15  register int reg_si, reg_di; /* dummy variables to use up regs */
  776.           16  int a = 10;
  777.           17  int i = LOOP_CNT;
  778.           18
  779.           19    test_func();
  780.           20
  781.           21    while (--i) a = a * a / a;
  782.           22
  783.           23    printf("Proftest executed");
  784.           24    return (0);
  785.           25  }                  /*     end of main     */
  786.           26
  787.           27  void test_func(void)
  788.           28  {
  789.           29  register unsigned int i;
  790.           30  register unsigned int a = 10;
  791.           31  float b, c;
  792.           32
  793.           33    for (i = LOOP_CNT; --i;)
  794.           34      a = a * a / a;
  795.           35
  796.           36    i = LOOP_CNT;
  797.           37    while (--i) a = a * a / a;
  798.           38
  799.           39    for (i = LOOP_CNT; --i;) a = a * a / a;
  800.           40
  801.           41    for (i = 50, b = 10.0; i > 0; i--)
  802.           42      c = b * b / b;
  803.           43  }                /* end of test_func */
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.                                                                  APPENDIX A - 11
  816.  
  817.  
  818.  
  819.                             ----------------------------------
  820.                                    EXAMPLE 1
  821.                             ----------------------------------
  822.  
  823.                          Turbo C Profiler (TCPROF V1.5)                    1
  824.  
  825. PROFILER OPTIONS:
  826.   Minimum line count printed(-C) 0:  Lines per page(-L) 58
  827.   Internal stack size(-S) 10 default
  828.  
  829. Analyzing C:\C\PROFTEST.MAP
  830. 18 lines in 2 functions in 1 module will be profiled
  831.  
  832. Building profile table
  833. Memory available 437432 bytes
  834.  
  835. Parameters:  C:\C\PROFTEST.EXE
  836.  
  837. ***** STDOUT FOR C:\C\PROFTEST.EXE *****
  838. Proftest executed
  839.  
  840. *** End of Program Output  Return code 0  Time mm:ss 0:03 ***
  841. Start 9-25-1988 16:41:26.67  End 16:41:42.22  Profiler overhead 84%
  842.  
  843.    --------   Example 1 Page 1:   tcprof -L proftest >proftest.ex1   --------
  844.  
  845.  
  846.  
  847.  
  848.  
  849. PROFTEST.EXE             Turbo C Profiler (TCPROF V1.5)                    2
  850. Func/Addr   Line   Count      %Tot %Fun...1...2...3...4...5...6...7...8...9...
  851.  
  852. MODULE PROFTEST
  853.  
  854. main                           36      ***************
  855. 0000:01FA   13     1            0    0 .
  856. 0000:0202   16     1            0    0 .
  857. 0000:0207   17     1            0    0 .
  858. 0000:020C   19     1            0    0 .
  859. 0000:020F   21     1           36   99 ==============--------------------------
  860. 0000:0229   23     1            0    1 .
  861. 0000:0232   24     1            0    0 .
  862. 0000:0236   25     1            0    0 .
  863.  
  864. test_func                      64      *************************
  865. 0000:023C   27     1            0    0 .
  866. 0000:0244   30     1            0    0 .
  867. 0000:0247   33     1            0    0 .
  868. 0000:024C   34     19999       21   33 ========-----
  869. 0000:025D   36     1            0    0 .
  870. 0000:0260   37     1           18   28 =======----
  871. 0000:0273   39     1           18   28 =======----
  872. 0000:0289   41     1            0    0 .
  873. 0000:0299   42     50           7   11 ===-
  874. 0000:02B6   44     1            0    0 .
  875.  
  876.  
  877.  
  878.  
  879.  
  880.                                                                  APPENDIX A - 12
  881.  
  882.  
  883.  
  884. *** End of profile report for C:\C\PROFTEST.EXE ***
  885.  
  886.    --------   Example 1 Page 2:   tcprof -L proftest >proftest.ex1   --------
  887.  
  888.                        ----------------------------------
  889.                                    EXAMPLE 2
  890.                        ----------------------------------
  891.  
  892.                          Turbo C Profiler (TCPROF V1.5)                    1
  893.  
  894. PROFILER OPTIONS:
  895.   FUNCTIONS ONLY(-F):  Lines per page(-L) 58
  896.   Internal stack size(-S) 10 default
  897.  
  898. Analyzing C:\C\PROFTEST.MAP
  899. 2 functions in 1 module will be profiled
  900.  
  901. Building profile table
  902. Memory available 437656 bytes
  903.  
  904. Parameters:  C:\C\PROFTEST.EXE
  905.  
  906. ***** STDOUT FOR C:\C\PROFTEST.EXE *****
  907. Proftest executed
  908.  
  909. *** End of Program Output  Return code 0  Time mm:ss 0:03 ***
  910. Start 9-25-1988 16:42:58.56  End 16:43:02.08  Profiler overhead 12%
  911.  
  912.    -------   Example 2 Page 1:   tcprof -L -F proftest >proftest.ex2  -------
  913.  
  914. PROFTEST.EXE             Turbo C Profiler (TCPROF V1.5)                    2
  915. Func/Addr   Line   Count      %Tot %Fun...1...2...3...4...5...6...7...8...9...
  916.  
  917. MODULE PROFTEST
  918.  
  919. main               1           38      ***************
  920. test_func          1           62      *************************
  921.  
  922. *** End of profile report for C:\C\PROFTEST.EXE ***
  923.  
  924.    -------   Example 2 Page 2:   tcprof -L -F proftest >proftest.ex2  -------
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.                                                                  APPENDIX A - 13
  946.  
  947.  
  948.  
  949.                               APPENDIX B
  950.  
  951.  
  952.      Registered user information
  953.  
  954.           A registered users version of this program, TCPROFRU, is
  955.           available for $20.00 ($25.00 for 3 1/2" diskettes).  Please
  956.           use the order form at the end of this document.
  957.  
  958.           The registered user version has additional options which
  959.           allow you to tailor the amount of information gathered by the
  960.           program.  On larger programs this reduces the overhead of the
  961.           profile runs and the size of the report.
  962.  
  963.  
  964.      Registered user features
  965.  
  966.           -A[-]func-nm  Alter the treatment of the named function.
  967.  
  968.                         If the profiler is being run in the default
  969.                         mode of lines by function, each function named
  970.                         by this option will NOT have line numbers
  971.                         traced.  A single line, as for a functions only
  972.                         report, is output for each named function.
  973.  
  974.                         If the functions only option is "on" (-F) then
  975.                         the named functions will have line number
  976.                         tracing on.
  977.  
  978.                         For either case above, if a minus sign precedes
  979.                         the named function it will not be traced and
  980.                         all times for the function will be included in
  981.                         the lines or functions that call it.
  982.  
  983.                         Multiple A options may be used.  The function
  984.                         name is case sensitive.
  985.  
  986.                           Ex:  tcprofru -F -Afn1 -A-fn2 tstprg
  987.                         Functions only plus fn1 lines and no trace on
  988.                         fn2.
  989.  
  990.           -M[-]mod-nm   Alter the treatment of all functions in the
  991.                         named module.
  992.  
  993.                         Depending on the status of the F switch the
  994.                         treatment of all functions within the named
  995.                         module will be modified.  This is a shorthand
  996.                         method of altering(A[]) the treatment of all
  997.                         the functions in a module.
  998.  
  999.                         Multiple M options may be used.  The module
  1000.                         name is not case sensitive.
  1001.  
  1002.                           Ex:  tcprofru -Mmod1 -M-mod2 testprog
  1003.                         Profile functions only in mod1, no profile of
  1004.                         functions in mod2, all other functions are
  1005.                         profiled by line.
  1006.  
  1007.  
  1008.  
  1009.  
  1010.                                                                  APPENDIX B - 14
  1011.  
  1012.  
  1013.  
  1014.           -F[-][+]      Alter the treatment of all functions in the
  1015.                         program.
  1016.  
  1017.                         The -F- option causes all functions to be
  1018.                         skipped except those specified by A or M
  1019.                         options.  The functions included by a -A or -M
  1020.                         option are profiled by line unless the name is
  1021.                         preceded by a -, in which case a single line
  1022.                         per function is reported.  This is convenient
  1023.                         when only a few functions in a large program
  1024.                         needs to be profiled.
  1025.  
  1026.                         The -F+ option resets the default, profile by
  1027.                         line.  It would be used if a response file (-@
  1028.                         option) contains a -F option and you wish to
  1029.                         override it. The last -F option encountered on
  1030.                         the command line is the one in effect for all
  1031.                         functions.
  1032.  
  1033.                         The interaction between the -F, -M and -A
  1034.                         options result in 27 possibilities.  The table
  1035.                         below is taken from the help screen of
  1036.                         TCPROFRU.
  1037.  
  1038.           -F[-][+]     |     No or +     |       Yes       |      with -     |
  1039.           -M[-]module  |  N  |  Y  |  -  |  N  |  Y  |  -  |  N  |  Y  |  -  |
  1040.           -A[-]function|N Y -|N Y -|N Y -|N Y -|N Y -|N Y -|N Y -|N Y -|N Y -|
  1041.               resulting L F S F L S S L F F L S L F S S L F S L F L F S F L S
  1042.                 profile: L = lines; F = function; S = skip, add time to caller
  1043.  
  1044.                         The second, third and fourth columns are
  1045.                         interpreted as follows:  N means that the
  1046.                         option not used for a particular module or
  1047.                         function.  Y means that the option was used for
  1048.                         a particular module or function.  The - means
  1049.                         that a particular module or function was
  1050.                         preceded by a minus.
  1051.  
  1052.                           Ex: tcprofru -M-module1 -Amod1fn2
  1053.                         Refering to the preceding table:  The
  1054.                         "resulting profile" line gives the effect for a
  1055.                         particular function.  the effect on functions
  1056.                         mod1fn1 and mod1fn2 in module1 is:  No -F
  1057.                         option therefore, select -F column 1; -M-
  1058.                         specified for module1 therefore, select -M
  1059.                         column 3; for mod1fn1 -A was not specified
  1060.                         therefore, select -A column 7 which results in
  1061.                         this function not appearing in the report and
  1062.                         its time being added to the caller.  On the
  1063.                         other hand, mod1fn2 is specified by a -A option
  1064.                         which selects -A column 8 and results in each
  1065.                         line of the function being profiled.
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.                                                                  APPENDIX B - 15
  1076.  
  1077.  
  1078.  
  1079.                           Ex:  tcprofru -F- -Afn1 -M-mod2 tstprg
  1080.                         The -F- option turns off profiling of all
  1081.                         functions in the program.  The -A and -M
  1082.                         options then modify this action as follows:
  1083.                         Profile by lines function fn1, one line per
  1084.                         function will be profiled for the functions in
  1085.                         module mod2, all other function times are
  1086.                         included with the caller's.
  1087.  
  1088.  
  1089.           -PnnF&|T      Only print lines whose percentage exceeds nn.
  1090.  
  1091.                         F = Line's percentage of function:  T = Line's
  1092.                         percentage of total. If both are specified the
  1093.                         line is printed if either percentage exceeds
  1094.                         the nn value.  If both are to be the same
  1095.                         percentage it may be specified as P20FT.
  1096.  
  1097.                           Ex:  tcprofru -P50F -p10t tstprg
  1098.                         Only print lines, which are 50% or more of the
  1099.                         function or are 10% or more of the total.
  1100.  
  1101.           -I[-]         Include C source in the report.
  1102.  
  1103.                         This option interleaves the C source code with
  1104.                         the report.  For each C module encountered in
  1105.                         the .MAP file a standard DOS path search is
  1106.                         made.  If the source code is found it is
  1107.                         printed with the report.  The -I- option can be
  1108.                         used to override a -I specified in a response
  1109.                         file (-@ option).
  1110.  
  1111.           -@file-name   Merge the named file with the command line
  1112.                         options.
  1113.  
  1114.                         When the @ option is encountered on the command
  1115.                         line the file is opened and each line within
  1116.                         the file is treated as one profiler command
  1117.                         line parameter.  The response file cannot be
  1118.                         used to specify the program to be profiled or
  1119.                         it's options.  The options must be in the same
  1120.                         sequence as they would appear on the command
  1121.                         line.  An @ option may not be contained within
  1122.                         the file.  Multiple @ options may be used on
  1123.                         the command line.
  1124.  
  1125.                           Ex: tcprofru -@op.dat -Aadd_fn tstprg
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.                                                                  APPENDIX B - 16
  1141.  
  1142.  
  1143.  
  1144.                               APPENDIX C
  1145.  
  1146.  
  1147.      PROBLEM REPORT/SUGGESTIONS
  1148.  
  1149.                                                      TCPROF version 1.5
  1150.           From:  Name:             ___________________________________
  1151.  
  1152.                  Company:          ___________________________________
  1153.  
  1154.                  Address:          ___________________________________
  1155.  
  1156.                  City, State, Zip: ___________________________________
  1157.  
  1158.           Received program from: _____________________________________
  1159.  
  1160.           Hardware:          _________________________________________
  1161.  
  1162.           Operating system:  ________________________  version: ______
  1163.  
  1164.           Resident programs: _________________________________________
  1165.  
  1166.                             __________________________________________
  1167.  
  1168.           Error message (if problem report):
  1169.  
  1170.              _________________________________________________________
  1171.  
  1172.           Description of error or suggestions:
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.           If appropriate and available, printed output of the profile
  1190.           report and a listing of the program or a fragment
  1191.           illustrating the problem would be helpful.
  1192.  
  1193.           Mail to:
  1194.                               Mr. Andre Nancoz
  1195.                               349 Quincy Ave.
  1196.                               Bronx, NY 10465
  1197.  
  1198.  
  1199.  
  1200.  
  1201.      REGISTERED USER ORDER FORM
  1202.  
  1203.           Mail to:
  1204.                               Mr. Andre Nancoz
  1205.                               349 Quincy Ave.
  1206.                               Bronx, NY 10465
  1207.  
  1208.             ..........................................................
  1209.  
  1210.             Order for TC profiler registered users version (TCPROFRU):
  1211.  
  1212.           Name:             __________________________________________
  1213.  
  1214.           Company:          __________________________________________
  1215.  
  1216.           Address:          __________________________________________
  1217.  
  1218.           City, State, Zip: __________________________________________
  1219.  
  1220.  
  1221.           Received TCPROF program from:
  1222.  
  1223.             __________________________________________________________
  1224.  
  1225.  
  1226.           Hardware:          _________________________________________
  1227.  
  1228.  
  1229.           Operating system:  ________________________  version: ______
  1230.  
  1231.           Send:
  1232.  
  1233.              ___ copies of 5 1/4" DSDD at $20.00 each ________
  1234.  
  1235.              ___ copies of 3 1/2" DSDD at $25.00 each ________
  1236.  
  1237.                                      Total enclosed. $________
  1238.             Checks only.  U. S. funds.  NO COD.
  1239.