home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / turbo_c / tcdebug.arc / TCDEBUG.DOC < prev    next >
Text File  |  1988-05-08  |  38KB  |  1,255 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                                             May 7, 1988
  9.  
  10.                              TCdebug Version 1.01
  11.  
  12.                     (C) Copyright 1987 by L. David Baldwin.  
  13.                              All Rights Reserved.
  14.  
  15.   Further copyright information given below
  16.  
  17.  
  18.   OVERVIEW
  19.  
  20.   TCdebug is an experimental source code debugger for use in debugging Turbo 
  21.   C (tm) Programs on the IBM-PC (tm).  Its goal is to allow source code 
  22.   debugging in all of Turbo C's memory models and with most of the possible 
  23.   compile and link options.  TCdebug allows you to:
  24.  
  25.        1.  View your source code (and, optionally, the assembly language 
  26.            code) while debugging.
  27.        2.  Trace the operation of your program by source code lines or by 
  28.            assembly language instructions.
  29.        3.  Insert breakpoints in your program by function name, by line 
  30.            number, or hexadecimal address.
  31.        4.  Examine (and change) simple global variables by symbolic name.  
  32.            Local variables may also be examined and changed, but require that 
  33.            the proper displacement on the stack be known. 
  34.        5.  Set up a Watch window to keep continuous tabs on a variable.
  35.        6.  Profile your program to find those portions which contribute most 
  36.            to the execution time.
  37.  
  38.   TCdebug is designed exclusively for debugging Turbo C programs.  It should 
  39.   not be used on programs generated by other compilers.
  40.  
  41.  
  42.   SYSTEM REQUIREMENTS
  43.  
  44.        1.  An IBM-PC, AT, or compatible.  Screen compatibility is a must.
  45.        2.  PC-DOS 2.0 or above.
  46.        3.  Approximately 135k more memory than would normally be required to 
  47.            run the program to be tested.
  48.  
  49.  
  50.   PREPARATION
  51.  
  52.   TCdebug requires that a Map file for your program be present to supply 
  53.   information on the program symbols and line number locations.  When 
  54.   compiling and linking with TC, the options can be set with O/C/C/L and 
  55.   O/L/M/P.  With TCC use -M and -y.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.                                       1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.   It is also highly desirable that the program to be tested be compiled with 
  75.   the 'standard stack frame' option on.  Using TC, set this option with 
  76.   O/C/C/S.  With TCC, use -k (The manual says -Y but that's apparently a 
  77.   typo).
  78.  
  79.   When starting a debugging session, the following files should be on the 
  80.   default drive:
  81.  
  82.     PROG.EXE    (or, optionally, .COM for the Tiny Model)
  83.     PROG.MAP    the map file
  84.  
  85.   Any C source files which will be accessed during the debugging session 
  86.   should also be on the default drive or on Paths specified in the DOS PATH.
  87.  
  88.  
  89.  
  90.   OPERATION
  91.  
  92.   TCdebug may be started by entering the filename of the program to be 
  93.   debugged and any parameters which it requires on the command line, as:
  94.  
  95.     TCdebug PROG <other stuff>
  96.  
  97.   Here, PROG is the name of the program to be tested with EXE being the 
  98.   default extension.  <other stuff> will be passed on to PROG as its command 
  99.   line when execution begins.  If TCdebug is called without parameters, a 
  100.   request will be made for them.
  101.  
  102.   When execution begins, TCdebug loads the Map file, the EXE file and reports 
  103.   some facts about the program.  Note should be made of whether pointers are 
  104.   regarded as Near or Far by default as this will be important when 
  105.   displaying pointers later.
  106.  
  107.   After "hitting any key", the program is executed to "main()" and the 
  108.   debugging screen appears.  The debugging screen is divided into two parts.  
  109.   The lower section is the command and data section.  The '*' is a prompt for 
  110.   one of the commands described later.  The top part of the screen displays 
  111.   the program source code text which at this point will be centered at the 
  112.   first statement in main().  Source code line numbers appear at the left 
  113.   with the current line (the one to be executed next) being highlighted.
  114.  
  115.   Dividing the two portions of the debugging screen is a line which shows the 
  116.   name of the source file presently displayed.
  117.  
  118.   Two keys which can be tried at this point are the F9 and F10 keys.  The 
  119.   F9 key toggles into and out of the assembly mode.  When in assembly mode, 
  120.   the assembly language instructions of the program are displayed with the 
  121.   source code lines interspersed.  The F10 key toggles between the debugger 
  122.   screen and the screen which receives program output.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                                       2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.   SPECIAL KEYS FOR VIEWING TEXT
  141.  
  142.   The following keys may be used to change the text being displayed:
  143.  
  144.        Pg Up
  145.        Pg Dn       Move the display up or down one page.
  146.  
  147.        ^Pg Up
  148.        ^Pg Dn      Move to the start or end of the current file.
  149.  
  150.        Up arrow
  151.        Down arrow  Scroll up or down one line.
  152.  
  153.        ^Left Arrow  (with Scroll Lock on)
  154.        ^Right Arrow (with Scroll Lock on)
  155.                    Scroll horizontally left and right.
  156.  
  157.        F9 key      Toggle in and out of assembly mode.
  158.  
  159.        F10 key     Toggle between the debug screen and the screen
  160.                    of the program under test.
  161.  
  162.        Alt-U       Move dividing line up one line.
  163.        Alt-D       Move dividing line down one line.
  164.  
  165.   Note that the toggling of the Scroll Lock key effects the action of some of 
  166.   the special keys.  The text display may also be changed using the View 
  167.   command described later.
  168.  
  169.  
  170.   COMMAND EDITOR
  171.  
  172.   Commands are entered at the '*' prompt.  When entering commands, the 
  173.   following keys may used to edit the command:  (They perform the same 
  174.   functions as they do in the Turbo C editor.)
  175.  
  176.        ^A,^S,^D,^F,^G,^T,^H,^V,^Y,LFARW,RTARW,^LFARW,^RTARW,
  177.        Ins, Del, Backspace
  178.  
  179.   The Insert mode (default) is indicated by a slightly fatter cursor.  The 
  180.   cursor is normal in the Overwrite mode.
  181.  
  182.   In addition, a stack of the last 6 commands (those having more than 3 
  183.   characters) is maintained.  The F3 key accesses the stored commands from 
  184.   the most recent to the oldest and the F5 key accesses them in the reverse 
  185.   order.  These old commands may be used as is or may be modified by editing 
  186.   them.
  187.  
  188.   Note that commands are not acted upon until the Enter key is hit.  (The 
  189.   cursor does not have to be at the line end to enter the command.)
  190.  
  191.  
  192.  
  193.  
  194.                                       3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.   COMMAND PARAMETERS
  207.  
  208.   TCdebug uses one or two letter commands.  The command is often followed by 
  209.   one or more parameters.  Parameters are delimited from the command and each 
  210.   other using spaces.  The one exception to this is the format parameter 
  211.   which is preceded by a comma.  The parameters which may be used are:
  212.  
  213.     <Symbol>
  214.        A C source code symbol representing a function name or variable as 
  215.        appropriate.  The leading underbar added by the compiler has been 
  216.        stripped off, so symbols are entered exactly as used in the source 
  217.        program.  Case is significant (unless the non case sensitive link 
  218.        option was selected).
  219.  
  220.        The special symbols, _AX, _AL, _BX, etc. may be used to refer to the 
  221.        hardware registers.
  222.  
  223.        A special symbol, rtn (or RTN), refers to the return address of the 
  224.        current function.  For this symbol to function reliably, the program 
  225.        should be compiled with the 'standard stack frame' option on.  
  226.        Currently, this symbol can only be accessed if the current CS:IP is on 
  227.        an exact source line number.
  228.  
  229.          Examples:
  230.            V rtn    Find out who called this function.
  231.            G RTN    Execute the remainder of this function, return to caller.
  232.  
  233.  
  234.     <Line Number>
  235.        Line numbers are entered as <filename>\<number> as:
  236.            myprog.c\345
  237.  
  238.        In most cases, the <filename> part can be dropped.  An entry of the 
  239.        form
  240.  
  241.            \345
  242.  
  243.        implies line number 345 in the currently displayed source file.  
  244.        (Currently, the '\' also may be dropped and a simple decimal entry will 
  245.        do.  However, the '\' may be required in future versions.)
  246.  
  247.     <Hexaddress>
  248.        Normal numerical entry in TCdebug is decimal with hex entries allowed 
  249.        by preceding them with '0x' or '$'.  However, numerical address 
  250.        entries must be entered in hex to distinguish them from line numbers.  
  251.        A <hexaddress> takes the following form:
  252.  
  253.            0x1234:0x1ABC
  254.            es:bx+2
  255.            SS:BP-0X5a
  256.  
  257.  
  258.  
  259.  
  260.                                       4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.        As indicated above, register names are allowed in address 
  273.        specifications.  The _current_ value in the register is used--the 
  274.        address does not change if the register value later changes.  The 
  275.        segment part of the <hexaddress> may be dropped as in:
  276.  
  277.            bp-0xA
  278.            0x123
  279.            bx
  280.  
  281.        If no segment is present in the entry, there is an implied segment.  
  282.        The rules for determining the implied segment are:
  283.  
  284.        1.  If the BP register is used, SS is implied.
  285.        2.  If BX,SI,DI are used (but not BP), DS is implied.
  286.        3.  If none of the above and a data entry is expected, DS is implied.
  287.        4.  If a code address is expected, the current CS is implied.
  288.  
  289.     <Format>
  290.        Format parameters are entered as one or two letters preceded by a 
  291.        comma.  Case is significant.  The purpose of the <format> parameter is 
  292.        to inform TCdebug of the size and type of a variable as this 
  293.        information is not available in the Map file.  <format> parameters 
  294.        correspond to those used in the C 'printf' function.  Currently 
  295.        supported are:
  296.  
  297.            c,s,i,d,u,x,X,o,p,g,G,li,ld,lx,lX,lo,Np,Fp,lg,lG
  298.  
  299.        For the p (pointer) format, the default pointer size for the selected 
  300.        memory model is used.  This size is indicated in the information 
  301.        presented at startup.  To override the default, use either N or F as 
  302.        appropriate.
  303.  
  304.        The c (character) format has been used as a catchall for byte size 
  305.        items.  Display is in quoted character form, decimal, and hex.  Change 
  306.        entries may be made using any of those forms.
  307.  
  308.  
  309.   COMMANDS
  310.  
  311.   G    (Go)
  312.  
  313.     Format:
  314.        G [<parameter> [<parameter..]]
  315.  
  316.     The Go command starts execution of the program under test.  Execution 
  317.     will continue until a breakpoint is reached or the program terminates.
  318.  
  319.     One or more breakpoints may be entered with the Go command.  These 
  320.     breakpoints are called temporary breakpoints as they are in effect only 
  321.     until the first stopping point is reached.  Any temporary breakpoint 
  322.     would then have to reentered with the next Go command if desired.
  323.  
  324.  
  325.  
  326.                                       5
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.     Examples:
  339.  
  340.        G   Start execution with no temporary breakpoints. (There might be 
  341.            some permanent breakpoints, however.)
  342.  
  343.        G \345 funct1 0x113
  344.            Start execution with temporary breakpoints at line number 345, at 
  345.            the start of function, funct1, and at address CS:0x113. In 
  346.            addition, there might be other permanent breakpoints in effect.
  347.  
  348.   T    (Trace)
  349.  
  350.     Format:
  351.        T   (or F7 key)
  352.  
  353.     In source code mode, execute the code on the current line.  Execution 
  354.     will stop at the next encountered line number.  If the current line 
  355.     contains a function call, the break will be at the start of the 
  356.     function.
  357.  
  358.     In assembly mode (assembly code is displayed), execute the next assembly 
  359.     language instruction.
  360.  
  361.  
  362.   N    (Next)
  363.  
  364.     Format:
  365.        N    (or F8 key)
  366.  
  367.     In either the source code or assembly mode, Next will execute the 
  368.     program, stopping at the next line number.
  369.  
  370.     The difference between the Trace and the Next command is that, if the 
  371.     current line contains a function call, Next will completely execute the 
  372.     function whereas Trace will Trace through the function.
  373.  
  374.  
  375.   P    (Permanent breakpoint)
  376.  
  377.     Format:
  378.        [-]P [<parameter>]  [<pass count>]
  379.  
  380.     The P command is used to specify permanent breakpoints.  Unlike temporary 
  381.     breakpoints, permanent breakpoints remain in effect until removed (using 
  382.     a '-' preceding the P command).  
  383.  
  384.     If no parameter is entered, the breakpoints in effect are listed.
  385.  
  386.     An optional pass count may be included when adding a breakpoint.  The 
  387.     pass count indicates how many times the breakpoint will be passed 
  388.     before the program is actually interrupted.
  389.  
  390.  
  391.  
  392.                                       6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.     Examples:
  405.  
  406.        P              List all permanent breakpoints.
  407.       -P              Delete all permanent breakpoints.
  408.        P moda.c\345   Install a breakpoint at line 345 in file moda.c.
  409.       -P funct1       Remove a breakpoint at function funct1.
  410.        P 0x34b 10     Install a breakpoint at CS:034B.  The break will
  411.                       occur at the 11th execution of the instruction.
  412.  
  413.  
  414.   BE, BC      (Conditional Breakpoints)
  415.  
  416.     Formats:
  417.        BE <parameter>, <format> <value>   (Break when Equal to value)
  418.        BC <parameter>, <format>           (Break when there is a Change)
  419.        B                                  (List conditional breakpoints)
  420.       -B  [<number>]                      (delete one or more conditionals)
  421.  
  422.     Conditional breakpoints allow TCdebug to interrupt program execution 
  423.     whenever it finds that a variable has changed or becomes equal to a 
  424.     specified value.  TCdebug checks each one of the conditional breakpoints 
  425.     whenever it regains control of the program.  Normally, when using 
  426.     conditional breakpoints, the GT (Go in Trace mode) command should be used 
  427.     to allow the variable checks to be made at each source line.
  428.  
  429.     String variables are compared over the first 10 characters.
  430.  
  431.     Examples:
  432.  
  433.        BC str,s        Break when the string variable, str, changes.
  434.        BE *np,i  39    Break when the integer pointed to by np equals 39.
  435.        -B2             Delete conditional breakpoint #2.       
  436.       
  437.  
  438.   GT   (Go in Trace mode)
  439.  
  440.     Format:
  441.        GT [<parameter> [<parameter..]]
  442.  
  443.     The GT command is a special version of the G (Go) command for use with 
  444.     conditional breakpoints.  Both commands have the same syntax.  When the 
  445.     GT command is used, the execution of the program is interrupted briefly 
  446.     at each source line so that the specified conditions can be checked.  
  447.  
  448.     Because of the extra overhead involved with the GT command, program 
  449.     execution is very much slower than with the G command.
  450.  
  451.     Example:
  452.        GT \334   
  453.            Start execution of the program stopping at the first occurrence of: 
  454.            line 334, reaching a permanent breakpoint, or one of the 
  455.            conditions specified by a conditional breakpoint.       
  456.  
  457.  
  458.                                       7
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.   V    (View text)
  473.  
  474.     Format:
  475.        V [<parameter>]
  476.  
  477.     The View command may be used to change the text being observed in the 
  478.     text window.  If no parameter is entered, the text will be centered 
  479.     around the current line.
  480.  
  481.     In assembly mode, code for which there is no source may be viewed by 
  482.     specifying a hex address with the V command.
  483.  
  484.     Examples:
  485.  
  486.        V initscreens   View text at function initscreens.
  487.        V \545          View text around line 545.
  488.        V 0x1234:0xABCD Display instructions at 1234:ABCD (Assembly mode)
  489.  
  490.  
  491.   VF   (View File)
  492.  
  493.     Format:
  494.        VF <filename>
  495.  
  496.     The View command is for viewing the program source files.  The VF 
  497.     command allows any ASCII file to be displayed.
  498.  
  499.  
  500.   E    (Examine/change variable) 
  501.  
  502.     Format:
  503.        E <symbol>|<hexaddress> , <format>
  504.  
  505.     The Examine/change command allows the the value of a simple variable to 
  506.     be displayed and optionally changed.  Global variables may be referred to 
  507.     symbolically.  Auto and static variables must be referred to by a 
  508.     <hexaddress>.  Pointers may be resolved using one or more '*'s preceding 
  509.     the symbol or address.  Single dimensioned arrays may be examined using 
  510.     the normal '[..]' to enclose the array index.  <format> indicates the 
  511.     type of display wanted.
  512.  
  513.     After a variable value is displayed in response to the Examine/change 
  514.     command, a new value may be optionally entered followed by the Enter key.  
  515.     The Enter key by itself is used if no new value is desired.
  516.  
  517.     String variables are displayed as a string within quotes.  When 
  518.     specifying a change to a string variable, the new string should be 
  519.     enclosed in double quotes.  A null string is specified by two quotes 
  520.     enclosing nothing.
  521.  
  522.  
  523.  
  524.                                       8
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.     Examples:
  538.  
  539.        E flt,g
  540.        E dble,lg
  541.        E *st,c
  542.        E es:bx,u
  543.        E bp-0x52, s
  544.        E s[22],c
  545.        E *pt[3],i   the 4th element of the integer array pointed to by pt.
  546.  
  547.     When referring to registers, note that there is a difference between the 
  548.     register symbols with underbars and those without the underbars, so that:
  549.  
  550.        E ds:bx,x  Examine/change the hex integer at the address ds:bx.
  551.        E bx,x     The same thing (DS is implied).
  552.        E _BX,x    Examine/change the BX register.
  553.  
  554.  
  555.   W    Watch variable
  556.  
  557.     Format:
  558.        W <symbol>|<hexaddress> , <format>
  559.     [-]W [<number>]
  560.  
  561.     The Watch command opens up a watch window so that the specified variable 
  562.     is displayed continuously.  The value displayed is updated whenever 
  563.     TCdebug regains control.  The syntax for watch variable entry is 
  564.     identical to that used with the Examine command.  
  565.  
  566.     When watch variables are displayed, they are given a number.  The number 
  567.     is useful for selectively deleting them using the -W command.
  568.  
  569.     Examples:
  570.        W var1, u    Watch the unsigned variable, var1
  571.        W *bp-4,c    Watch the char variable pointed to by SS:BP-4
  572.        W _AL,c      Watch the AL register
  573.       -W 1          Delete watch variable #1
  574.       -W            Delete all watch variables  
  575.  
  576.  
  577.   D    (Display Memory)
  578.  
  579.     Format:
  580.        D <symbol>|<hexaddress> , <format>
  581.       -D
  582.  
  583.     The Display command opens up a three line display window displaying 
  584.     memory contents at the address given by <parameter> in the format given 
  585.     by <format>.  This display window may be scrolled using the following 
  586.     keys when Scroll Lock is toggled on:
  587.  
  588.  
  589.  
  590.                                       9
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.        Up Arrow
  603.        Down Arrow    Move up or down one line (Scroll Lock on)
  604.  
  605.        Pg Up
  606.        Pg Dn         Move up or down two lines (Scroll Lock on)
  607.  
  608.     Examples:
  609.  
  610.        D ptrs,Fp   Display memory at ptrs in far pointer format.
  611.        D dbles,lG  Display memory at dbles in double format.
  612.        D *es:bx,s  Display memory as pointed to by es:bx in string or 
  613.                    character format.
  614.       -D           Close the display window.
  615.  
  616.  
  617.   DB   (Display Bytes)
  618.  
  619.     Format:
  620.        DB <symbol>|<hexaddress> [, <format>]
  621.       -DB
  622.  
  623.     The Display Bytes command produces the customary debug data display 
  624.     showing memory in both hex bytes and ASCII characters.  The display 
  625.     always starts on an even paragraph with the byte at the specified address 
  626.     highlighted.
  627.  
  628.     An optional <format> may be entered with the command so that the offset 
  629.     of subscripted variables may be determined, as:
  630.  
  631.        DB abc[1000],i
  632.  
  633.     will start the display at abc+2000.
  634.  
  635.  
  636.   X    (Translate symbols to addresses or addresses to symbols)
  637.  
  638.     Format:
  639.        X <symbol>
  640.        X <address>
  641.  
  642.     The X command allows the address associated with a symbol to be 
  643.     determined or vice versa.
  644.  
  645.  
  646.   R    (Register Display)
  647.  
  648.     Format:
  649.        R
  650.  
  651.     The Register display command displays the current machine register 
  652.     contents.  
  653.  
  654.  
  655.  
  656.                                      10
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.   RE   (Restart program under test)
  670.  
  671.     Format:
  672.        RE
  673.  
  674.     Reloads a fresh version of the test program and restarts it from the 
  675.     beginning.  Breakpoints and watch variables remain in effect.
  676.  
  677.  
  678.   WD   (Window Divide)
  679.  
  680.     Format:
  681.        WD [n]
  682.  
  683.     The Window Divide command allows the line dividing the screen to be moved 
  684.     up or down.  n is the desired line position.  If n is not entered, the 
  685.     line position is not changed but the screen is refreshed.
  686.  
  687.     The line dividing the screen may also be moved one line at a time using 
  688.     Alt-U (Up) or Alt-D (Down).
  689.  
  690.   TA   (Tab Size)
  691.  
  692.     Format
  693.        TA n
  694.  
  695.     Text displayed in the text window has tabs expanded to eight spaces by 
  696.     default.  The TAb command allows the expansion to be changed.
  697.  
  698.  
  699.   Q    (Quit)
  700.  
  701.     Format:
  702.        Q
  703.  
  704.     The Quit command ends debugging without running the program under test to 
  705.     completion.  However, the program's exit() routine is executed, so that 
  706.     files are closed, etc.  You will be asked if you wish to restart the 
  707.     program.  (Use F10 to check the program screen at this time if desired.)
  708.  
  709.  
  710.   DG   (DebuG)
  711.  
  712.     Format:
  713.        DG
  714.  
  715.     This command is used to enter an optional external assembly language 
  716.     debugger.  It is used mainly for debugging TCdebug.
  717.  
  718.  
  719.  
  720.  
  721.  
  722.                                      11
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.   HINTS
  735.  
  736.   When tracing in assembly mode and returning to source mode, it often 
  737.   happens that the current address may be between two source lines.  In these 
  738.   cases, the highlight bar will be on the line that is partially executed but 
  739.   will not extend over the line number.  If the current address is at the 
  740.   start of the line, the highlight will extend over the line number.
  741.  
  742.   It is possible to insert breakpoints in the source code using 
  743.   geninterrupt(3).  These breakpoints cannot be removed by TCdebug but may be 
  744.   useful for conditional breaks.  For instance:
  745.  
  746.     if (i==49) geninterrupt(3);
  747.  
  748.   If you mistakenly Trace into a function you wanted to skip using Next, use 
  749.   G rtn.  Actually, it's best to do a V rtn first to make sure that the 'rtn' 
  750.   symbol is working correctly.
  751.  
  752.   If, in the assembly mode, you trace into a library routine and can't find 
  753.   your way out, toggle out of assembly mode (F9).  Even if the source code 
  754.   screen is blank at this time, a single Trace will get you to the next line 
  755.   number.
  756.  
  757.   Avoid assembly tracing of the 8087 emulation code.
  758.  
  759.   Auto (stack) variables can be Examined or Watched by using the disassembly 
  760.   listing to determine their position on the stack relative to the BP 
  761.   register.  When doing this, be sure that the BP register is valid.  In 
  762.   particular, the BP register is not valid immediately on entry to the 
  763.   function.  One source line trace must be made (or several assembly 
  764.   instructions passed) before the BP register is correct.
  765.  
  766.   The Huge memory model has the same sort of problem with the DS register 
  767.   which changes between modules.  In this case, it only effects the 
  768.   disassembly listing.  The data symbols will not be correctly listed until 
  769.   the DS register has been setup.
  770.  
  771.  
  772.   PROFILER
  773.  
  774.   When a program runs slow, it's often due to a relatively small portion of 
  775.   code.  The trick is to determine which parts of the program contribute most 
  776.   to the execution time so that the programmer doesn't waste time refining 
  777.   the wrong code.  TCdebug's profiler provides a way to make that 
  778.   determination. 
  779.  
  780.   The profiler divides up a portion of the memory where the program resides 
  781.   into approximately 128 equal parts (or 'bins').  As the program executes, 
  782.   it is periodically interrupted using the PC's timer interrupt.  At each 
  783.   interrupt, TCdebug determines the address of the interrupted instruction 
  784.   and increments a count for the appropriate bin.  At the end of the run, the 
  785.  
  786.  
  787.  
  788.                                      12
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.   counts per bin then show the relative time of execution for that part of 
  801.   the code.
  802.  
  803.   PROFILER INSTRUCTIONS
  804.  
  805.   PS   (Profiler Setup)
  806.  
  807.     Format
  808.        PS
  809.  
  810.     The Profiler Setup command is used to specify which parts of memory are 
  811.     to be profiled and what the counting rate should be.  On issuing the PS 
  812.     command, the user is asked to answer the following:
  813.  
  814.        1. Starting segment or address (or 'PROGRAM')?
  815.        2. Ending segment or address?
  816.        3. Counts per second (40-4000)?
  817.  
  818.     The first two questions determine the memory address range where counts 
  819.     will be recorded.  This memory range is divided into approximately 128 
  820.     equal parts.  In some cases, there may fewer than 128 bins created since 
  821.     the bin sizes must all be equal and are sized in multiples of 16 bytes.  
  822.     When answering the first two questions, either an address (two hex 
  823.     numbers separated by a colon) or a segment (hex number without a colon) 
  824.     may be entered.
  825.  
  826.     An optional response to the first query is the word "PROGRAM".  If this 
  827.     entry is used, TCdebug will set the address limits to that actually used 
  828.     by the program code.
  829.  
  830.     The counting rate may be set between 40 and 4000 counts per second.  A 
  831.     rate of 1000 is appropriate in most cases.
  832.  
  833.     Note that the Profiler Setup command does not turn the profiler on.  The 
  834.     PO command must be used for that purpose.
  835.  
  836.   PO   (Profiler On/Off)
  837.  
  838.     Format
  839.        PO 0        (Turn profiler off)
  840.        PO 1        (Turn profiler on)
  841.        PO          (Request profiler status)
  842.  
  843.     When the appropriate point in the program is reached, the profiler is 
  844.     turned on.  Counting then commences with the next 'G' (Go) command and 
  845.     ceases when the debugger is reentered either at a breakpoint or when the 
  846.     program terminates.  The ability to turn the profiler on and off is 
  847.     useful to avoid timing unimportant events such as keyboard wait loops.
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.                                      13
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.   PR   (Profiler Reset)
  867.  
  868.     Format
  869.        PR
  870.  
  871.     The Profiler Reset command resets the counts to zero without changing the 
  872.     setup.
  873.  
  874.   PD   (Profiler Display)        
  875.  
  876.     Format
  877.        PD [<number>]       (Display profiler results on debugging screen)
  878.        PDP [<number>]      (Output profiler results to printer)
  879.  
  880.     The Profiler Display command outputs the profiler results in tabular form 
  881.     either to the screen or to the printer.  An optional percentage may be 
  882.     entered.  Bins with count percentages below the value entered will not be 
  883.     displayed.  If no percentage is entered, a default of 0.5% is used as the 
  884.     cutoff.  To see all the counts, enter PD 0 or PDP 0.
  885.  
  886.     Figure 1 shows the display from a profiling run.  The 'Total Count' of 
  887.     765 is the actual number of interruptions to the executing program, and 
  888.     'Total Count in Specified Interval' of 761 shows that almost all of the 
  889.     hits occurred in the memory interval specified in the setup (the 
  890.     "PROGRAM" option was used here).  The various column headings are:
  891.  
  892.        Block   
  893.            The bin number, 0..128.
  894.        Address Range
  895.            The segment and offset range corresponding to that block.  There 
  896.            are two 'Address Range' columns since it is possible to have a 
  897.            segment overlap within a block.
  898.        Program Loc
  899.            The first line number or symbol found in the block.  This helps 
  900.            locate the code for that block.
  901.        Count
  902.            The count recorded for that block.
  903.        % Intvl
  904.            The count as a percentage of the 'Count in Specified Interval'.
  905.        % Total
  906.            The count as a percentage of the 'Total Count'.
  907.  
  908.     The data shown in Figure 1 is a profile of the function that displays one 
  909.     screen of disassembly listing on an earlier version of TCdebug.  The 
  910.     profiler was turned on at the start of the routine (located between lines 
  911.     SCREEN.C\377 and 419) and a 'G RTN' issued to time one screenfull.  At 
  912.     1000 counts/sec, it took 0.76 seconds to change the screen.  One might 
  913.     expect that the disassembler (block 64) would be using most of the time  
  914.     but actually about 80% of the time is spent in blocks 13 and 14.  A 
  915.     further profile run narrowing in on that part of memory showed the 
  916.     problem to be the line number and symbol look up functions.  These are 
  917.  
  918.  
  919.  
  920.                                      14
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.     called for each line displayed to see if a source code line should be 
  933.     output.
  934.  
  935.   USING THE PROFILER
  936.  
  937.     Summarizing the profiler use:
  938.  
  939.     1. Use the PS command to set the address range and the counting rate.  
  940.        Often the best way to start is to examine all of memory using a 
  941.        starting segment of 0x0 and an ending segment of 0xFFFF.  While this 
  942.        won't yield any detail (each block is 8k), it will tell how much time 
  943.        is spent in the program, how much in DOS and how much in ROM bios.
  944.  
  945.     2. Set a breakpoint at the point profiling is to start and execute to 
  946.        that point.  Omit this step if the whole program is being timed.
  947.  
  948.     3. Turn the profiler on.
  949.  
  950.     4. Set a breakpoint where the profiling is to stop, execute the program 
  951.        to that point, and turn the profiler off.  Note that the program must 
  952.        be executed in real time (the G command)--the profiler does not 
  953.        operate in any of the trace modes.
  954.  
  955.     5. Display the results.
  956.  
  957.     6. Repeat the above steps narrowing in on the portions of memory where 
  958.        the action is to get more detail.
  959.  
  960.     A couple of caveats.  Because the profiler uses the timer interrupt, it 
  961.     won't work in sections of code where the interrupts are turned off.  If 
  962.     interrupts are turned off for a fairly long time, counts will tend to 
  963.     pile up at those instructions where the they're turned back on.  Also, 
  964.     the PC's timer is sped up considerably during profiling.  TCdebug 
  965.     attempts to keep the system clock operating normally, but this can't 
  966.     always be done exactly.  It's probably a good idea to check the system 
  967.     clock after a profiling session.
  968.  
  969.  
  970.   RESTRICTIONS, PROBLEMS, BUGS
  971.  
  972.   The following are current limits (somewhat arbitrarily set).  
  973.  
  974.     Permanent and temporary breakpoints are limited to 5 each.
  975.     Maximum file size for displayed files = 64k.
  976.     Maximum number of line numbers (only those with code count) = 3000.
  977.     Maximum number of program modules accommodated = 20.
  978.     Maximum number of symbols = 700.
  979.     Maximum number of watch variables = 4
  980.     Maximum number of conditional breakpoints = 3
  981.  
  982.   A simple screen swap is currently used.  This limits debugging to text only 
  983.   programs.  
  984.  
  985.  
  986.                                      15
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.   The map file for the Tiny memory model has some peculiarities in data 
  1000.   addresses which affect a number of library data symbols and one or two 
  1001.   source symbols.  The problem shows up in the assembly listing where the 
  1002.   affected symbols are not correctly displayed.
  1003.  
  1004.   The 8087 emulation code turns into a mess when disassembly is attempted.
  1005.  
  1006.   Currently, non default pointers cannot be resolved by the 'E' or 'W' 
  1007.   commands.  That is:
  1008.  
  1009.     E *st,c
  1010.  
  1011.   will always resolve st as a far pointer if the default is far.
  1012.  
  1013.   The map file generated by Turbo C does not correctly handle #include files 
  1014.   which generate code.  This shows up as incorrect line number information 
  1015.   for modules using such include files.  This problem does not apply to the 
  1016.   normal header include files as they don't generate code.
  1017.  
  1018.  
  1019.   COPYRIGHT
  1020.  
  1021.   Documentation and Program (C) Copyright 1987 by L. David Baldwin.  
  1022.   All Rights Reserved.
  1023.  
  1024.   TCdebug may be copied and distributed freely by individuals to friends and 
  1025.   acquaintances providing that no fee is charged and it is not part of a 
  1026.   package for which a charge is made.
  1027.  
  1028.   Please do not upload TCdebug to any bulletin board unless you are willing 
  1029.   to keep it updated and report back problems.
  1030.  
  1031.  
  1032.   TRADEMARKS
  1033.  
  1034.        IBM-PC is a trademark of International Business Machines 
  1035.        Corporation.
  1036.        Turbo C is a trademark of Borland International Inc.
  1037.  
  1038.  
  1039.  
  1040.   Please report all bugs, suggestions, and problems to Dave 
  1041.   Baldwin, CompuServe ID #76327,53.
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.                                      16
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.   APPENDIX A -- COMPILER OPTIONS
  1065.  
  1066.   As mentioned earlier, it is mandatory that the map file generation and line 
  1067.   number options be turned on.  The effect of some of the other compiler 
  1068.   options on debugging are discussed below.
  1069.  
  1070.   Standard Stack Frame
  1071.     This option is highly desirable as the BP register must be set up in 
  1072.     order for the 'rtn' symbol to work.  If this option is not used, any 
  1073.     function which has many auto variables will still have a standard stack 
  1074.     frame, so it is still possible to use 'rtn' in some cases.  The safest 
  1075.     method is to do a V rtn or X rtn first to see if the return address makes 
  1076.     sense before committing yourself to a G rtn.
  1077.  
  1078.   Register Optimization
  1079.     Borland suggests off.  The assembly language listing may be somewhat more 
  1080.     difficult to understand using this option.
  1081.  
  1082.   Jump Optimization
  1083.     Same as register optimization.
  1084.  
  1085.   80186/80286 Code Generation
  1086.     Off is best here.  The disassembler in TCdebug currently does not 
  1087.     understand the new instructions.
  1088.  
  1089.   Use Register Variables
  1090.     When this option is on, you may have to figure out which variables the 
  1091.     compiler decided to store in registers.  
  1092.  
  1093.   8087 vs Emulation
  1094.     If you have a choice, by all means select straight 8087.  The emulated 
  1095.     code does not disassemble in any meaningful way.
  1096.  
  1097.   Non Case Sensitive Link
  1098.     If this option is selected, symbols will appear in uppercase.  Symbol 
  1099.     entries may be made in either case.
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.                                      17
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.   APPENDIX B -- SOURCE CODE FORMATTING
  1131.  
  1132.   With modern compilers, line numbers often do not correspond to the code 
  1133.   generated in the manner that you might expect.  Layout of the source code 
  1134.   can help in this respect.  While you probably don't want to reformat all 
  1135.   your present code, you may want to change your formatting for code yet to 
  1136.   be written.
  1137.  
  1138.   The most obvious format change is to only have one source statement per 
  1139.   line.  With more than one statement on a line, line numbers can't be used 
  1140.   to set a breakpoint on the second statement and the Trace command will 
  1141.   trace multiple statements.
  1142.  
  1143.   Statements split between two lines do not cause much trouble.
  1144.  
  1145.   The 'else' in an 'if' statement causes a difficulty.  Consider the 
  1146.   following code:
  1147.  
  1148.   100  if (...)
  1149.   101     {..do something..}
  1150.   102  else {..do something else..}
  1151.   103
  1152.  
  1153.   To put a breakpoint on the ..do something else.. one might try a break on 
  1154.   line 102.  But the else here actually generates a jump instruction (to line 
  1155.   103) so ..do something else.. is inaccessible except by using a code 
  1156.   hexaddress.  A better format is:
  1157.  
  1158.   100  if (...)
  1159.   101     {..do something..}
  1160.   102  else 
  1161.   103     {..do something else..}
  1162.   104
  1163.  
  1164.   The 'for' statement also causes problems.  The decision code for the 'for' 
  1165.   statement is actually done at the bottom of the loop and often is included 
  1166.   as part of the next line where you would normally think the statement was 
  1167.   completed.  The best solution here is to add a blank line after the 'for' 
  1168.   statement loop.
  1169.  
  1170.   In short, it's best to use plenty of vertical spacing and blank lines.  
  1171.   Also take a peek at the assembly code to see what's going on.
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.                                      18
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.   128  Intervals of 28 Paragraphs (448 Bytes) Each
  1204.   Total Count = 765
  1205.   Total Count in Specified Interval = 761   ( 99.5%)
  1206.   Block Address Range   Address Range  Program Loc      Count  % Intvl  % Total
  1207.     13  327D:16C0-187F                 LOADSYM.C\53       127    16.7    16.6
  1208.     14  327D:1880-1A3F                 LOADSYM.C\104      483    63.5    63.1
  1209.     34  327D:3B80-3D3F                 BREAKS.C\785         1     0.1     0.1
  1210.     36  327D:3F00-40BF                 SCREEN.C\139         1     0.1     0.1
  1211.     37  327D:40C0-427F                 SCREEN.C\210        17     2.2     2.2
  1212.     40  327D:4600-47BF                 SCREEN.C\366         2     0.3     0.3
  1213.     41  327D:47C0-497F                 SCREEN.C\404         1     0.1     0.1
  1214.     52  327D:5B00-5CBF                 SCREEN.C\1056       15     2.0     2.0
  1215.     64  327D:7000-71BF                 UNASDB.C\868        74     9.7     9.7
  1216.     81  327D:8DC0-8F7F                 getcwd               1     0.1     0.1
  1217.     82  327D:8F80-913F                 intdos               2     0.3     0.3
  1218.     85  327D:94C0-967F                 _LoadProg            3     0.4     0.4
  1219.     86  327D:9680-983F                 ultoa               29     3.8     3.8
  1220.     99  327D:AD40-AEFF                 VPRINTER             2     0.3     0.3
  1221.    100  327D:AF00-B0BF                                      1     0.1     0.1
  1222.    101  327D:B0C0-B27F                 write                2     0.3     0.3
  1223.  
  1224.  
  1225.                                    Figure 1
  1226.                                Profiler Display
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.                                      19
  1251.  
  1252.  
  1253.  
  1254.  
  1255.