Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / c / library / dos / debug / tt_cdeb / ttcd.doc < prev next >

Wrap

Text File | 1987-11-14 | 99.5 KB | 3,103 lines

T T C D ------- (The Turbo C Debugger) --- ----- - -------- USERS GUIDE Version 1.5 (C) COPYRIGHT 1987 by SAYSoft, Inc. ALL RIGHTS RESERVED Created by Steve York COPYRIGHT NOTICE The Turbo C Debugger (TTCD) program and documentation is the copyrighted property of SAYSoft, Inc. You are granted a limited license to use the limited version of TTCD, and to copy it and distribute it, provided that the following conditions are met: 1) No fee may be charged for such copying or distribution. 2) TTCD may ONLY be distributed in its original, unmodified form. 3) TTCD may not be distributed, in whole or in part, as part of any commercial product or service without the express written permission of SAYSoft, Inc. USER LICENSE The limited version of TTCD along with this documentation may be freely copied to any person or organization in unmodified form. It may not be distributed in modified form, and may not be sold for profit. THE FULL VERSION OF TTCD (AND ITS DOCUMENTATION) MAY NOT BE DISTRIBUTED OR DUPLICATED IN ANY FORM EXCEPT FOR PERSONAL ARCHIVAL PURPOSES. DISCLAIMER SAYSoft, Inc. will not be liable for any damages or claims related in any way to the use of this product. SAYSoft, Inc. makes no warranties and specifically disclaims any implied warranties of this product. "Turbo C" and "Turbo Pascal" are trademarks and products of Borland International, Inc. The Limited Version of TTCD Since only a very small percentage of "Shareware" program users actually send the requested money to the program author I decided to try the "limited version" approach. Consequently, there are two versions of TTCD. A limited version, and a full version. ******************************************************************* IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT ******************************************************************* The limited version of TTCD is identical to the full version, except for the following limitations: o Only "small" model programs can be debugged. o It does not support programs that use CGA or EGA graphics. o Only 300 global symbols are allowed. ******************************************************************* Contributions for the use of TTCD will be appreciated, and should be sent to: SAYSoft, Inc. 14938 Kimberley Houston, TX 77079 If you would like to purchase the full version, please send $25.00 to the above address. Include sales tax if you are a Texas resident. With the full version, you will receive a printed and bound manual, a program serial number, and a telephone number for support. Registered full version TTCD users will be able to download upgrades, at no charge (except the cost of the phone call), as they become available. Table of Contents 1.0 About TTCD...............................................1 1.1 Background...........................................1 1.2 What is TTCD?........................................1 1.3 Files included with TTCD.............................2 1.4 Limitations of this version of TTCD..................2 1.5 TTCD and Different Turbo C Versions..................3 1.6 Future Directions of TTCD............................3 2.0 What is Required.........................................4 2.1 Hardware and software required.......................4 2.2 Compile and Link options and settings required.......4 2.2.1 Compile Options................................4 2.2.2 Link Options...................................5 2.3 Source code requirements.............................5 2.4 Related files........................................5 3.0 Executing TTCD...........................................7 3.1 The TTCD Command Line................................7 3.2 The TTCD Startup Screen..............................8 3.3 Getting Started......................................9 4.0 The TTCD Commands and Displays..........................10 4.1 The Status line.....................................10 4.2 The Main Menu.......................................10 4.2.1 reakpoints.................................11 4.2.1.1 <C>onditional...........................12 4.2.1.2 <D>isplay...............................12 4.2.1.3 <L>ine number...........................13 4.2.1.4 rocedure.............................13 4.2.1.5 <R>eset.................................13 4.2.2 <C>alc........................................13 4.2.3 <D>isplay.....................................14 4.2.3.1 <G>lobal symbol.........................14 4.2.3.2 <M>emory................................14 4.2.3.3 ublics...............................15 4.2.3.4 <R>egisters.............................15 4.2.3.5 <S>tack.................................15 4.2.3.6 Display 'Types'.........................16 4.2.3.7 Valid TTCD Addresses....................17 4.2.3.8 <D>isplay Command Examples..............18 4.2.4 <E>nter.......................................20 4.2.4.1 <R>egister..............................20 4.2.4.2 <M>emory................................20 4.2.5 <G>o..........................................21 4.2.5.1 <F>orever...............................22 4.2.5.2 <L>ine numbers..........................22 4.2.5.3 rocedure.............................22 4.2.6 <L>ist........................................22 4.2.7 <K>eep........................................22 4.2.7.1 <D>elete................................23 4.2.7.2 <G>lobal Symbol.........................23 4.2.7.3 <M>emory................................23 4.2.7.4 <R>egisters.............................23 4.2.8 <M>acros......................................24 iii Table of Contents 4.2.8.1 <D>isplay...............................24 4.2.8.2 <L>oad..................................24 4.2.8.3 <R>ecord................................24 4.2.8.4 <S>ave..................................25 4.2.9 <O>ptions.....................................25 4.2.9.1 <A>nimation Breakpoints.................25 4.2.9.2 <D>isplay...............................26 4.2.9.3 <F>lip screen on trace..................26 4.2.9.4 <S>now suppression......................26 4.2.10 <Q>uit.......................................26 4.2.11 rint......................................27 4.2.12 <S>creen.....................................27 4.2.13 <T>race......................................27 4.2.13.1 <A>nimate...............................27 4.2.13.2 <S>ingle step...........................28 4.2.13.3 roc step.............................28 4.2.13.4 Using <T>race..........................28 4.2.14 nassemble.................................29 4.3 The Repeat Count....................................30 4.4 Program Termination.................................31 5.0 Notes about Debugging with TTCD.........................32 5.1 Source Code Formatting..............................32 5.2 Mnemonic Differences................................32 5.3 Special Interrupts..................................33 5.4 Floating Point Emulation Deviations.................33 5.5 Floating Point Problems.............................33 5.6 Optimization Options................................34 5.7 The "#line" Directive...............................34 5.8 Memory Considerations...............................34 5.9 Interrupt Vector Trapping...........................35 5.10 Trapping Math Errors...............................35 6.0 Input responses to TTCD prompts.........................37 6.1 Input field editing.................................37 6.2 Case sensitivity....................................37 6.3 Input Radix Defaults................................38 6.4 Address Specification Defaults......................38 7.0 TTCD.MAC Format and Use.................................39 8.0 Known TTCD Bugs and Anomalies...........................40 9.0 Version Changes/Modification to TTCD....................41 iv 1.0 About TTCD 1.1 Background The Turbo C (tm) compiler is (for the most part) a very complete C compiler. It fully supports K & R definitions, has library routines supporting nearly all applicable UNIX "standard C library" calls, and supports most of the (proposed) ANSI C standard. Moreover, like the ubiquitous Turbo Pascal (tm) it has several useful (and high-powered) machine-/DOS-dependant language extensions and library routines. As an advanced C programmer, the first thing I did with Turbo C was to try to re-compile some of my previously written C programs with it. The C compiler that I have used for several years was not as close to the "UNIX type" compiler, and did not attempt to emulate the UNIX environment. I quickly discovered that one thing I really needed did not come with Turbo C. A tool that no C programmer should be without - a good debugger. I presume that the people at Borland expect Turbo C users to use the DOS "DEBUG" program, or some equivalent product. 1.2 What is TTCD? TTCD is a symbolic source-level debugger for programs written in Turbo C. TTCD allows debugging Turbo C programs via: o Normal execution to any specified line, procedure, or user- specified breakpoint(s). o Single-stepping through execution. o Program "animation". TTCD supports: o All Turbo C models except "Tiny". o Real-time examination/modification of variables, memory, and machine registers. o Variable-speed animation. o "Conditional" and "looping" breakpoints. o "Sticky" and "Non-sticky" breakpoints. o 8087 code, or floating point emulation. About TTCD Page 1 o Retaining variables, memory locations, or the machine registers on the screen. o Symbolic dis-assembly of program code. o Key-macros. o Programs that generate CGA and EGA graphics. o Multiple source-module programs. o 80186/80286 instructions. 1.3 Files included with TTCD The files included with this release of TTCD and their descriptions are: o TTCD.EXE - This is the TTCD program. o TTCD.DOC - Users guide for TTCD. o TTCD.TC - Sample Turbo C configuration file for use when compiling a program to be debugged with TTCD. o TTCD.MAC - This is a sample TTCD macro file. It contains useful definitions for function keys <F7> thru <F0>. Use the <M>acro <D>isplay command, or MAC2TEXT to display the recorded key strokes. o MAC2TEXT.C - This is the source code to a program that will convert the TTCD.MAC macro file to readable text. When compiled, this program will allow you to view TTCD macros that you have recorded and saved. o COND.H - This is an include file that will allow you to easily set up conditional breakpoints (of any complexity) at the source code level. 1.4 Limitations of this version of TTCD This version of TTCD has some limitations. They are: o "Tiny" model programs are not supported. o Programs that use VGA Graphics are not supported. o Maximum number of global symbols is 5000. o Maximum number of modules is 30. o Maximum number of lines per module is 65000. About TTCD Page 2 1.5 TTCD and Different Turbo C Versions I have Turbo C version 1.0 dated 6/3/87. All applicable Borland patches (TCP1.DIF thru TCP9.DIF) have been applied to it. TTCD was created with this version of Turbo C, and all my testing was done using programs compiled with this version of Turbo C. Patched or later versions may not have some of the problems discussed in section 5 of this users guide. I fully expect TTCD to be compatible with future versions of Turbo C unless radical changes are made in the product. If a new version of Turbo C is "TTCD incompatible", REGISTERED FULL VERSION TTCD USERS WILL BE ABLE TO DOWNLOAD TTCD UPGRADES AT NO CHARGE (except the cost of the phone call). For information about new versions of TTCD, or download availability call Pat at (713) 487-8379. 1.6 Future Directions of TTCD In future releases of TTCD, I plan to support the following: o Auto-configuration of global variable "types" for the <D>isplay and <E>nter commands. o Programs that generate VGA graphics (and possibly Hercules graphics). o Expanded memory use for graphics screen swapping and caching of source code. About TTCD Page 3 2.0 What is Required An understanding of how C utilizes memory is necessary for serious C program writing, and useful for debugging any C program. Also a knowledge of 8086 Assembler is recommended. 2.1 Hardware and software required A fixed disk is recommended, but not required. If a fixed disk is not available, the use of a RAM disk or disk cache will minimize the wait for source code to be displayed. The following hardware and software is required to make use of TTCD: o Version 1.0 (or greater) of Turbo C. o Approximately 128K bytes + the memory required by the target program. In addition, about 12K more memory is required if the "-C" command line option is used, and about 108K more if the "-E" command line option is used. See section 3.1 for explanations of these options. 2.2 Compile and Link options and settings required 2.2.1 Compile Options To debug a Turbo C program with TTCD, the program must be compiled with the following options set: o "Model": Any model except "Tiny". (NOTE: THE LIMITED VERSION OF TTCD WILL ONLY HANDLE "SMALL" MODEL PROGRAMS.) o "Calling convention": "C". o "Underbars": On. o The "Line numbers" option must be on for any modules that you intend to "step through" or set breakpoints in. The module that contains 'main()' must be compiled with line numbers on. The following option settings are recommended, but not required: o "Standard Stack Frame": On. o "Use Register variables": Off. What is Required Page 4 o "Register Optimization": Off. o "Jump Optimization": Off. All other compile options may be set as desired. 2.2.2 Link Options To debug a Turbo C program with TTCD, the program must be linked with the following options set: o A "Map" file must be produced with either the "Publics" or "Detailed" options on. Preferably the "Publics" option, as this is smaller, and faster to read. o The "Class names" must not be changed for code, data, or BSS. All other link options may be set as desired. 2.3 Source code requirements Any source modules that you intend to step through, or set breakpoints in must be compiled with the "Line numbers" option on. The default maximum number of modules compiled with line numbers is 10. This may be changed via command line options. See section 3.1. The source code for any module compiled with line numbers may be in any drive/directory when executing TTCD. If it is not found, you will be prompted for the new path, when entered, debugging will continue as usual. If prompted for a new path, you must enter some drive and/or path at this prompt, even to get to a source file in the current directory. 2.4 Related files In order to debug a Turbo C program, TTCD needs quite a bit of information about it. This information is obtained from the .MAP file produced by the linker. For instance, to debug a program named "HELLO.EXE", TTCD will also need "HELLO.MAP" (produced by the linker) and "HELLO.C", the program source code. If the program consists of multiple source code modules, these files should also be available to TTCD if compiled with line numbers. TTCD will read the .MAP and .EXE files and create a file with the extension ".DBG". The .DBG file is a relocatable program similar to an .EXE file, but it will not execute properly outside of TTCD. The .DBG file will be erased automatically, upon termination of TTCD. What is Required Page 5 NOTE: TTCD does not change the .EXE file. If the program works properly, it does not have to be re-compiled. Warning: If any of the source code modules are changed, and not re-compiled, the .EXE file (and consequently the .MAP and .DBG files) may not reflect the correct line number or procedure addresses. This could create quite a bit of confusion during the debugging process. What is Required Page 6 3.0 Executing TTCD 3.1 The TTCD Command Line The TTCD command line is as follows: TTCD [options] PROGRAM <program arguments & options> Where PROGRAM is the name of the .EXE file to debug (the "target" program). The extension need not be specified as it must be an .EXE file. The target program and its map file must be in the current directory, on the current drive. The TTCD options are as follows: -C (CGA Graphics option on) This option specifies that buffer space should be allocated for storage of a 16K "program screen". Note that the program is not automatically put in any graphics mode if this is specified. Screen modes are still controlled by the target program. This option causes TTCD to use about 12K more memory. THIS OPTION IS NOT AVAILABLE IN THE LIMITED VERSION OF TTCD. -E (EGA Graphics option on) This option specifies that buffer space should be allocated for storage of a 112K "program screen". This option causes TTCD to use about 108K more memory. Screen swapping is much slower when the target program is in any of the EGA graphics modes than when in the text or CGA modes. THIS OPTION IS NOT AVAILABLE IN THE LIMITED VERSION OF TTCD. -S### (Number of global symbols) This option specifies the size of the global symbol table. The default is 500 symbols (the limited version default is 300). This option is for use with programs that have more than 500 symbols. It may also be used to decrease the symbol table size if the debugger runs out of memory. THE LIMITED VERSION OF TTCD SUPPORTS A MAXIMUM OF 300 SYMBOLS. No white space is allowed between the 'S' and the digits. -M## (Number of modules with line numbers) This option specifies the size of the 'module table'. The default is 10 modules. This option is for use with programs that are broken into many small modules. Only the number of modules compiled with line numbers use module table space. Modules that are compiled without line numbers do not need to be included in the module count. No white space is allowed between the 'M' and the digits. Executing TTCD Page 7 -B## (Source file buffer size) This option specifies the size of the source file disk access buffer. The number specifies the buffer size in Kbytes. The minimum allowed is 4, and maximum allowed is 60. The default buffer size is 4K. The size of the disk buffer can greatly affect the speed of program animation. If the buffer size specified is larger than the largest source file, then program animation can always be done with no disk reads to display source code (within a single source module). A large buffer can slow down single step animation if the animation causes excessive alternation of source modules. Note that memory allocated for the disk buffer is taken from the available memory for the target program. No white space is allowed between the 'M' and the digits. 3.2 The TTCD Startup Screen When execution of TTCD starts, it will display status lines showing that it is reading the map file, and generating the ".DBG" file. When the program variables and tables are set up, some status information will be displayed. This should look similar to the following: TTCD Version 1.0 Created by Steve York. Copyright (c) 1987 by SAYSoft, Inc. Full version. Reading MCALC.MAP . . . Creating MCALC.DBG . . . Map contains: 279/500 global symbols 6/10 module definition(s) with line numbers 1534 lines total 24170 bytes free. Press <ESC> to abort, any other key to start. This tells us: o There are 279 global symbols in MCALC. This includes procedure names, global variables, procedure names linked in from libraries, and the overhead generated by Turbo C. The symbol table size is set to 500 symbols (default table size). Executing TTCD Page 8 o There are 6 program modules compiled with the 'line numbers' option on. The module table is set to 10 modules. o There are 1534 executable lines. This is only a sum of the lines in the modules compiled with line numbers. o There are about 24K bytes of data space left for MCALC to "grow", and still fit in TTCD with line numbers for all six modules. (Enough space for about 2000 more lines in modules compiled with line numbers.) TTCD is "small" model program itself. Consequently its own data space is limited to 64K. This is enough space for fairly large target programs. Programs of nearly any size can be debugged with TTCD if only selected modules are compiled with numbers. 3.3 Getting Started TTCD has several commands and menus, however, it is relatively straightforward to learn and use. To become acquainted with TTCD, it is a good idea to "step through" a working program before actually using it to debug a program with problems. For a simple example, "MAC2TEXT" can be used to "test drive" TTCD. MAC2TEXT.C is one of the files distributed with TTCD. Its purpose is to convert TTCD macros to readable text. For a more complete example, the "MCALC" program that comes with Turbo C can be used to "test drive" TTCD. In either case, compile all source code modules with the "line numbers" option on. Set all other compile and link options as described in section 2.2. When either MAC2TEXT.EXE or MCALC.EXE has been generated, enter (at the DOS prompt) the corresponding command: TTCD MAC2TEXT or TTCD MCALC If the target program has been compiled correctly, the TTCD startup screen will be displayed. This will resemble the example shown in section 3.2. Press any key (except <ESC>) to go to the TTCD main menu. At this point, try each of the commands described in section 4.2 to become familiar with them, and how they are used. Executing TTCD Page 9 4.0 The TTCD Commands and Displays Menus and prompts in TTCD are always on the top line of the screen. Menu options are selected by pressing the first letter of the command. The <ESC> key will always exit a menu with no action, and return to the Main menu. The second line of the screen is a status line. The rest of the screen is used to show source lines, variable, memory and register values, and other information. 4.1 The Status line The second line of the screen is the status line. It displays the current module name, procedure/function name, and source line number within that module. For instance, the top two lines of the screen may look like: <SPACE> - Menu 2 reakpoints <C>alc <D>isplay <E>... ========= Module: HELLO.C Proc: main() Line: 16 =====... The status line tells us: o We are in a source code module named "HELLO.C". o We are in procedure "main". o The next line to execute is source line number 16. The left end of the status line also shows other information. If a macro-recording is in progress, the leftmost column will have an 'R'. If the rint command is active, the second column will have a 'P'. If the repeat count value (see section 4.3) is greater than zero, its value is displayed near the left end. 4.2 The Main Menu The "Main menu" actually consists of three lines, only one of which is displayed at a time. The <SPACE> key changes the displayed line. The three lines are: <SPACE> - Menu 2 reakpoints <C>alc <D>isplay <E>nter <G>o <SPACE> - Menu 3 <K>eep <L>ist <M>acro <O>ptions rint <Q>uit <SPACE> - Menu 1 <S>creen <T>race nassemble Options are selected by pressing the letter in the angle-brackets. The space bar simply toggles the display of these three lines, any The TTCD Commands and Displays Page 10 option may be selected at any time whether that option is currently displayed at the top of the screen or not. Each of the options on the main menu is discussed below. 4.2.1 reakpoints A breakpoint is a place at which you wish to stop program execution and return to the debugger menu. TTCD has ten user-definable breakpoints. They are numbered 0 thru 9. These ten breakpoints are divided into two types. They are: o "Non-sticky" breakpoints - these are breakpoints that are automatically cleared anytime the debugger becomes active again. When the debugger menu returns, all non-sticky breakpoints are cleared. Breakpoints 0 thru 4 are non- sticky breakpoints. <M>acros are useful for repeatedly setting non-sticky breakpoints selectively. o "Sticky" breakpoints - these are breakpoints that are active until actually cleared, or until the debugger is exited. All sticky breakpoints will still be active when a <G>o or <A>nimate command is selected again. Breakpoints 5 thru 9 are sticky breakpoints. <M>acros are useful for "turning on" or "turning off" sets of sticky breakpoints selectively. Breakpoints are active during program <A>nimation if the "Animation Breakpoints" option is enabled. They are not active when tracing (see the <T>race command, section 4.2.13) through a program. If the "Animation Breakpoints" option is enabled, pressing <ESC> to terminate program animation will not clear the non-sticky breakpoints. The non-sticky breakpoints will be cleared if the animation is halted by reaching a breakpoint. When the reakpoint command is selected, the user will be asked for a breakpoint number. When a number key (<0> thru <9>) is pressed, the following menu will be displayed: <C>onditional <D>isplay <L>ine number rocedure <R>eset Each of these options is discussed below. All user-defined breakpoints have a loop count associated with them. The repeat count (see section 4.3) specifies the loop count of any break point. If no repeat count is entered, the loop count is initialized to 1, except for conditional breakpoints, which are initialized to 9999. A breakpoint with a loop count of 1 will trap program execution the first time it is encountered. The TTCD Commands and Displays Page 11 4.2.1.1 <C>onditional This option will allow you to set a condition for any breakpoint. Breakpoint conditions consist of non-compound statements of the form: <register> <relop> <value> or <symbol> <relop> <value> or <address> <relop> <value> Where: <register> is one of the registers listed in section 4.2.4.1. <address> is a global symbol name. Note the symbol must be a scaler here. If you need to compare the value of a structure or array member, its address must be specified. <address> is an address as specified in section 4.2.3.7. <relop> is one of the following: = != < <= > >= <value> is a numeric constant. If a symbol or an address is specified, you will be asked a value "type". Conditional types are a subset of the type discussed in section 4.2.3.6. The conditional types are as follows: <C>har <D>ouble <F>loat nt <L>ong nsigned These types are identical to their counterparts as discussed in section 4.2.3.6. When the condition and type are entered, you will be returned to the menu in 4.2.1 to complete the breakpoint setting. 4.2.1.2 <D>isplay This option will display all breakpoint settings. The breakpoint number specified is not used if this option is selected. The following is displayed for each active breakpoint: the breakpoint number (0 thru 9), its current loop count, condition (if any), and address. The following is a sample breakpoint display: Active Breakpoints: # Count Condition Address 1 1 None 5565:0176 -> Line: MOD1;5 6 1000 AX != 0x2 5565:031A -> Proc: display() The TTCD Commands and Displays Page 12 This shows two breakpoints set. Breakpoint #1 (non-sticky) is set to break the first time we reach line 5 of the module named "MOD1". Breakpoint #6 (sticky) will break when we get to the procedure "display()", and register AX is not equal to 2, or the 1000th time we get to "display()", which ever occurs first. 4.2.1.3 <L>ine number This option will allow you to set a breakpoint to any valid line number in any module compiled with line numbers. When selected, you will be asked the line number. If only a number is entered, the current module will be assumed. You may set a breakpoint at a certain line in another module by specifying the module name, a semicolon, and the desired line number. For example: If I entered "FILE1;23", a breakpoint would be set at line 23 in the module "FILE1.C". When entered, the specified breakpoint will be set to break before execution of that line. 4.2.1.4 rocedure This option will allow you to set a breakpoint to any valid procedure in any module compiled with line numbers. When selected, you will be asked the procedure name. When entered, the specified breakpoint will be set to break before execution of that procedure. 4.2.1.5 <R>eset This will clear the specified breakpoint. This would only be necessary for breakpoints 0 thru 4 if you set one then decide to remove it before execution. These breakpoints are cleared automatically anytime the debugger menu returns. 4.2.2 <C>alc The <C>alc command invokes a simple expression calculator. When selected, you will be asked to enter an expression. The expression may contain decimal and hexadecimal numbers (prefixed with "0x"), +, -, *, /, and unary minus. When a valid expression is entered, its value will be displayed. The resulting value is a signed long, and is printed both in decimal and hex. For example, the following may be entered at the expression prompt: 0x3a9 + 51 * 17 The normal mathematical hierarchy is adhered to (i.e. - multiplication performed before addition). After evaluating an expression, you may enter another expression to be evaluated, or press <ESC> to return to the menu. The TTCD Commands and Displays Page 13 The <C>alc command is also useful for converting numbers from hex to decimal and vice-versa. 4.2.3 <D>isplay The display command allows viewing of variables, memory, the current "frame storage area" (the stack, and local variables), or the machine registers. It may also be used to display the full list of public identifiers. When this option is chosen, the following menu will be displayed: <G>lobal symbol <M>emory ublics <R>egisters <S>tack Each of these options is discussed below. 4.2.3.1 <G>lobal symbol This option allows you to display the value of a public identifier (function or global variable) by name. When selected, you will be asked for the identifier name. If the identifier is a function name, its address will be displayed. If it is any other global symbol type, you will be asked for a 'type', as described in section 4.2.3.6. When entered, the variable value will be displayed. 4.2.3.2 <M>emory This option allows you to display any memory address as if it were the location of a C variable, of any type. When selected, you will be asked for an address (see section 4.2.3.7 for valid TTCD address specifications), and a 'type' as described in section 4.2.3.6. When entered, the value at the specified address will be displayed. NOTE: The value entered, is an address expression. Suppose we have the following assembler instruction: MOV AX,[BP+FFFE] And you wish to see what value will be moved into AX before this is executed. The <D>isplay <M>emory option may be used to see the value. Enter the address as: BP+FFFE not: [BP+FFFE] The former would display the value at 'BP+FFFE'. The latter would display the value of the address at 'BP+FFFE' - another level of The TTCD Commands and Displays Page 14 indirection. The latter is useful if the variable stored at 'BP+FFFE' is a pointer, and you wish to see the value of the object being pointed to. 4.2.3.3 ublics This option will display all global symbols, along with their addresses. When selected, all publics found in the ".MAP" file will be displayed, one screen at a time. Procedure names will be displayed with '()' following the name. 4.2.3.4 <R>egisters This option will display the machine register and flag values, with a format similar to the following: AX=0000 BX=049A CX=0000 DX=0014 SP=FFEC BP=FFF6 SI=003B DI=0454 DS=518C ES=518C SS=518C CS=5079 IP=0174 CF=0 SF=0 ZF=0 DF=0 OF=0 IF=1 PF=0 AF=0 4.2.3.5 <S>tack This option will display the memory in the current 'frame', and the 32 bytes above the current frame (where function parameters are). The current frame memory is the memory between [BP] and [SP]. When selected, the frame and parameter areas are displayed in a hex/ASCII dump format. This display might resemble the following: 0xA bytes local space: (BP=FF82 SP=FF78) [BP+FFF6] 01 00 00 00 00 00 00 00 24 40 ........$@ Parameter space: [BP+0000] DC FF 26 85 32 00 F8 1D 8C FF 32 2A 35 00 20 0E ..&.2.....2*5. . [BP+0010] 20 0E 4B 05 7B 22 8C 05 7B 22 4D 00 1E 27 73 03 .K.{"..{"M..'s. This display shows a hex dump of the 10 bytes of local storage that the current procedure has allocated on the stack. It also allows a simple way of displaying procedure parameters, and memory referenced to the BP register. For example, given the following assembler instructions: MOV AX,[BP+4] ADD AX,[BP+FFF6] MOV [BP+FFF8],AX Using the <D> <S> command, the action produced by these instructions is much easier to trace. Using the above hex dump, these instructions will move a 0x32 into register AX, add 1 to it, and store the result at BP+FFF8. The TTCD Commands and Displays Page 15 Note: Procedures that do not have any local storage may not set up a frame, and use the BP register as a frame pointer. The <D> <S> command may not show anything useful in this case. The "Standard Stack Frame" option can be used to force all procedures to set up a frame with BP as the frame pointer. The <ESC> key will stop the <D> <S> display if it scrolls off the screen. 4.2.3.6 Display 'Types' When the <D> <G> option or the <D> <M> option is selected, a display type must be specified. The display type menu consists of two lines, only one of which is displayed at a time. They are as follows: <SPACE> - Menu 2 <C>har <D>ouble <F>loat <H>ex nt <L>ong <SPACE> - Menu 1 <O>ffset <2>-ptr <4>-ptr <S>tring nsigned NOTE: The limited version of TTCD does not have the four-byte pointer option: <4>-ptr These specify the size and type of the item to be displayed, as follows: o <C>har - the byte at the specified address is displayed as a character, if printable. Also the hex value is displayed in parenthesis. o <D>ouble - the 8 bytes starting at the specified address are displayed as a 'double' floating point number. o <F>loat - the four bytes starting at the specified address are displayed as a floating point number. o <H>ex - memory starting at the specified address is dumped in a hex/ASCII format. o nt - the two bytes at the specified address are displayed as an integer. Also the hex value is displayed in parenthesis. o <L>ong - the four bytes starting at the specified address are displayed as a signed long integer. Also the hex value is displayed in parenthesis. The TTCD Commands and Displays Page 16 o <O>ffset - this option is used to specify the offset in a structure or array of the object whose value is to be displayed. When chosen, you will be asked to specify the offset value. After specifying an offset, another display type may be selected. The <O>ffset is always specified in bytes, not in units of data-item size. See section 4.2.3.8 for examples its use. o <2>-ptr - this tells TTCD that the value at the specified address is a 2-byte pointer to some data item. When selected, the user is left at the 'type' menu to specify what type the pointer points to. Another type may then be specified. The value of the object pointed to is then displayed. See section 4.2.3.8 for examples its use. o <4>-ptr - this tells TTCD that the value at the specified address is a 4-byte pointer to a data item. This command is the four-byte equivalent to the <2>-ptr option, and operates in a similar fashion. o <S>tring - memory starting at the specified address is displayed as a string. Non-printable and special characters are converted to their C equivalents. i.e. - a character 9 is displayed as '\t'. The string will be displayed with vertical bars (|) at each end of it so that leading/trailing white space may be seen. If the string is longer than 50 characters, it will be truncated, and displayed with an ellipses (. . .) following it. o nsigned - the two bytes at the specified address are displayed as an unsigned integer. Also the hex value is displayed in parenthesis. The <M>acro capabilities are very useful for displaying a variable value after repeated <T>race or <G>o commands. 4.2.3.7 Valid TTCD Addresses When TTCD prompts for a machine address, any of the following formats may be used: o offset o segment:offset o [offset] o segment:[offset] Where: Offset is a constant, a register, or a register +/- a constant. Segment is a constant, or a segment register. The TTCD Commands and Displays Page 17 NOTE: The address-decoding routine is 'dumb'. In an attempt to be as flexible and simple as possible, it performs basic syntax checking only. 4.2.3.8 <D>isplay Command Examples The <D>isplay command has the ability to display the value of any scaler, or string variable by global symbol name. This command can be very complicated due to pointer, array, and/or structure combinations. In order to use these capabilities, it is important to understand each of the display 'types'. The examples shown below should help clarify the <D>isplay 'types'. Note that all of the 'types' discussed in 4.2.3.6 apply to the <D>isplay <M>emory command as well as the <D>isplay <G>lobal command. Example 1: Lets suppose I have the following global declaration in a small model program: char *ptr={"Steve"}; I may display the value of the POINTER by pressing: <D> <G> ptr (<D>isplay <G>lobal "ptr" nteger) This will display (in decimal and hex) the memory location of where the string "Steve" is stored. The value of the OBJECT pointed to (the string "Steve") may be displayed by pressing: <D> <G> ptr <2> <S> (<D>isplay <G>lobal "ptr" <2>-ptr <S>tring) This tells TTCD to display the string pointed to by the 2-byte pointer "ptr". Example 2: Lets suppose I have the following declarations in a small model program: The TTCD Commands and Displays Page 18 #include <stdio.h> #include <alloc.h> char *my_equ={"26.34/2"}; /* Pointer to a string. */ struct my_struct { int type; /* 2 byte integer. */ double value; /* 8 byte double. */ char near *equation; /* 2 byte pointer. */ }; struct my_struct far *my_ptr; /* 4 byte pointer. */ main() { my_ptr=malloc(sizeof(struct my_struct)); my_ptr->type=1000; my_ptr->value=13.17; my_ptr->equation=malloc(strlen(my_equ)+1); strcpy(my_ptr->equation,my_equ); . . (Rest of program) . . } The value of any of the members of "my_ptr->my_struct" can be displayed using the <D>isplay <G>lobal command. The integer value "my_ptr->type" may be displayed by pressing: <D> <G> my_ptr <4> (<D>isplay <G>lobal "my_ptr" <4>-ptr nteger) The double precision value "my_ptr->value" may be displayed by pressing: <D> <G> my_ptr <4> <O> 2 <D> (<D>isplay <G>lobal "my_ptr" <4>-ptr <O>ffset "2" <D>ouble) The string "my_ptr->equation" may be displayed by pressing: <D> <G> my_ptr <4> <O> 10 <2> <S> (<D>isplay <G>lobal "my_ptr" <4>-ptr <O>ffset "10" <2>-ptr <S>tring) The fourth character of the string "my_ptr->equation" may be displayed by pressing: The TTCD Commands and Displays Page 19 <D> <G> my_ptr <4> <O> 10 <2> <O> 3 <C> (<D>isplay <G>lobal "my_ptr" <4>-ptr <O>ffset "10" <2>-ptr <O>ffset "3" <C>har) The TTCD key <M>acros can be very useful for repeatedly displaying variable values. 4.2.4 <E>nter The <E>nter command allows you to change register or memory values. When selected, the following menu will be displayed: <R>egister <M>emory Each of these options is discussed below. 4.2.4.1 <R>egister This option will allow you to change the value of a machine register. When selected, you will be asked the register name. The valid register names are: Byte: AL CL DL BL AH CH DH BH Word: AX CX DX BX SP BP SI DI Segment: ES CS SS DS When a register name is entered, you will be prompted for a value. The value must be specified by two or four hex digits. If a byte register is selected, and a word value is entered, only the lower byte will be set into the register. Warning: It is NOT a good idea to change any of the following registers unless you know exactly what you are doing: CS SS SP BP 4.2.4.2 <M>emory If this option is selected you will be asked for an address (see section 4.2.3.7 for address specifications). Next, you will be asked for a 'type'. The type-specification menu is as follows: <C>har <D>ouble <F>loat <H>ex nt <L>ong nsigned Each of these types is similar to its corresponding <D>isplay 'type', except that you will be asked for a value to put at the specified memory address. The only differences are: The TTCD Commands and Displays Page 20 o <C>har - when entering characters, multiple characters may be entered at one time. These characters will be put in memory starting at the specified address, continuing for as long as the input string (up to 50 characters). The C special characters may be used in the input. i.e. - '\t' will specify character number 9. This input routine allows input of any character via '\###'. Where '###' represents up to 3 hex digits. NOTE: Due to ambiguities, you should be very careful when specifying a character via '\###'. For instance: o "\felix" is 5 characters. They are: '\f' 'e' 'l' 'i' 'x'. The '\f' is taken as a formfeed character. o "\0felix" is 4 characters. They are: '\0fe' 'l' 'i' 'x'. The '\0fe' is taken as one character (0xfe). o "\00felix" is 5 characters. They are: '\0f' 'e' 'l' 'i' 'x'. The '\00f' is taken as one character (0xf). o "\000felix" is 6 characters. They are: '\0' 'f' 'e' 'l' 'i' 'x'. The '\000' is a null character. o <H>ex - multiple bytes may be entered via this option. The input string may be up to 50 characters long. These values will be put in memory starting at the specified address. Hex numbers may be separated by spaces, commas, or periods when more than one is specified. Any of the following are valid hex values: 0D0A0D0A d a d a 0D,0A,0D,0A 0D.0A.0D.0A 4.2.5 <G>o The <G>o command allows executing the program to a certain point. When selected, the following menu will be displayed: <F>orever <L>ine number rocedure Each of these options is discussed below. The TTCD Commands and Displays Page 21 4.2.5.1 <F>orever This option specifies that the <G>o command should execute until the end of the program or until a previously set reakpoint is reached. When the program ends execution or reaches a reakpoint, the debugger menu will return. 4.2.5.2 <L>ine numbers This option, when selected, will prompt you for a line number to stop at. The specified line may be in any module compiled with line numbers. It is specified similar to a reakpoint line number. See section 4.2.1.3 for an example. When execution reaches the specified line, the debugger menu will return. Note that not all source line numbers are valid line numbers to stop at, only source lines that caused code to be generated can be used to break at. If a "non-code" line number is specified, TTCD will use the next sequential line that does have code associated with it. 4.2.5.3 rocedure This option, when selected, will prompt you for a procedure name to stop at. When execution reaches the beginning of this procedure, the debugger menu will return. The procedure can be in any module compiled with the 'line numbers' option on. 4.2.6 <L>ist The <L>ist command allows viewing of the source file. When selected, you will be asked for a starting line number. When entered, five lines of the source code in the current module will be listed (unless a different repeat value is specified, see section 4.3). The next five lines (or repeat value number of lines) may be listed by pressing <SPACE>. Source code lines are truncated (not wrapped around) if they are too long to fit on one screen line. If the end of the current module source file is reached, a line stating '<End of file>' will be displayed. NOTE: Tab expansion is every 4th column, not every 8th. 4.2.7 <K>eep The <K>eep command allows you to retain register or variable values or memory contents on the screen. These will be updated each time The TTCD Commands and Displays Page 22 the debugger screen returns. When selected, the following menu will be displayed: <D>elete <G>lobal symbol <M>emory <R>egisters Each of these options will be discussed below. NOTE: In this version, the <K>eep <G>lobal command uses static addresses only. For instance, if you have a pointer to an integer, and you specify to <K>eep the integer pointed to, the current address (pointer value) will be the address always displayed by that keep command. If the pointer points to some other location in memory later, the integer at the original address will still be "kept" on the screen. In later releases of TTCD, I plan to address this. 4.2.7.1 <D>elete This option will allow you to remove a <K>eep variable. When selected, you will be asked the <K>eep number to remove. The first <K>eep currently displayed is number one, the second is number two, etc. When a number (1 thru 5) is entered, the corresponding <K>eep value will be removed. 4.2.7.2 <G>lobal Symbol This option will allow you to specify the <K>eep variable by name. When selected, you will be asked the symbol name. When entered, you will be asked a display "type" (see section 4.2.3.6). When the type is selected, the variable value will be added to the "keep" area at the bottom of the screen. 4.2.7.3 <M>emory This option will allow you to specify a memory location to <K>eep. When selected, you will be asked the address. When entered, you will be asked a display "type" (see section 4.2.3.6). When the type is selected, the memory contents will be added to the "keep" area at the bottom of the screen. 4.2.7.4 <R>egisters This option will allow you to <K>eep the general purpose registers on the screen. When selected, the registers contents will be added to the "keep" area at the bottom of the screen. The TTCD Commands and Displays Page 23 4.2.8 <M>acros When TTCD starts execution, it checks for the existence of a file named "TTCD.MAC". This is the file that TTCD key macros, and the color and option settings are stored in. If it is found in the current directory, or in the DOS path, it will be loaded automatically. The <M>acro command allows recording of any keystrokes entered into TTCD. When selected, the following menu will be displayed: <D>isplay <L>oad <R>ecord <S>ave Each option is discussed below. 4.2.8.1 <D>isplay This option will display the recorded key strokes for the ten function keys. 4.2.8.2 <L>oad This option causes all ten function key macros to be loaded from "TTCD.MAC". "TTCD.MAC" is created via the <M> <S> command, and must be in the current directory, or in a directory specified in the DOS path. This command may be used to re-load the "default" macros if any are changed during debugging. This command is not normally necessary since the macros stored in "TTCD.MAC" are automatically loaded at the beginning of execution. 4.2.8.3 <R>ecord This option allows you to record or change a macro. Macros may be assigned to any of the ten function keys. When selected, you will be asked to press the function key you wish to assign the macro to. When selected, an 'R' will appear in the left column of the status line, as shown below: <SPACE> - Menu 3 <K>eep <L>ist <M>acro <O>ptions ... R======= Module: HELLO.C Proc: main() Line: 10 === ... This is an indicator that a macro recording is in progress. All keys pressed, until the next <M>acro command, will be recorded for playback when the specified function key is pressed. The TTCD Commands and Displays Page 24 When recording macros: o Only the keys entered into the debugger will be recorded. Any keys entered into the target program will not be recorded. o Up to 99 key strokes may be recorded in one macro. o Function keys are ignored during macro recording. o Macros may not be nested or linked. o The "backward apostrophe" <`> key may be used to bypass a key when recording a macro. This is useful when recording part of a key sequence. For instance, lets suppose I wanted to make the <F1> start the single-step trace mode. The key required key sequence is: <M> <R> <F1> <ESC> <T> <S> <`> <ESC> <M> The key sequence actually recorded would be: <ESC> <T> <S> The second <ESC> key was not recorded, only used to get out of the trace mode in order to finish recording the macro. 4.2.8.4 <S>ave This option causes all ten function key macros, and the current configuration information to be saved in a file named "TTCD.MAC". The information recorded in "TTCD.MAC" will be re-loaded the next time TTCD is executed. 4.2.9 <O>ptions This command allows you to set TTCD parameters. When this command is selected, the following menu will be displayed: <A>nimation Brkpts <D>isplay <F>lip screen on trace <S>now suppression Each option is discussed below. 4.2.9.1 <A>nimation Breakpoints This option will allow you to enable or disable breakpoints during program <A>nimation. If enabled, the breakpoints will work similar to the way they function during execution via <G>o. If disabled, breakpoints will not stop program <A>nimation. Note that if The TTCD Commands and Displays Page 25 <A>nimation is terminated by pressing the <ESC> key, non-sticky breakpoints will not be cleared. 4.2.9.2 <D>isplay This option will display the current TTCD option settings and return to the main menu. 4.2.9.3 <F>lip screen on trace The "<F>lip screen on trace" option allows you to specify whether you want the target program screen replaced each time a statement is executed via <T>race. If it is set ON, the "program screen" and "debugger screen" will be swapped between each statement traced. If it is set to OFF, some target program screen I/O may be lost. When off, tracing and animation is much faster particularly if the target program is in a graphics mode. This option may also be toggled on or off while in the trace mode. 4.2.9.4 <S>now suppression The "<S>now suppression" option allows you to specify whether you want CGA "snow" suppressed each time the screen is flipped to or from the debugger screen. If this is set ON, you should not see any "glitching" when the screen is flipped. If this is set off, screen switching will be much faster in the text mode. Since screen snow does not occur when in any graphics mode, this option is only effective when the target program is in the text mode. Machines equipped with an EGA card should not have snow, regardless of the mode, however, many CGA cards have this problem. 4.2.10 <Q>uit This command allows you to exit TTCD. When this command is selected, the following menu will be displayed: <N>o <Y>es <R>estart Press <Y> to exit TTCD, <N> to resume debugging, or <R> to re-start execution of the target program. If the <R>estart option is selected, the program screen contents will be left as it is currently displayed. Selecting <Y> will cause the target program to immediately exit. Any "atexit" functions will not be executed, files will not be The TTCD Commands and Displays Page 26 flushed, etc. However, any memory allocated via standard calls (including allocmem()) should be freed properly. 4.2.11 rint This command allows a simple way to send debugging information to the printer. When selected, the "print option" will toggle. Its default state is off. When the print option is on, a 'P' will appear in the second column of the status line, and all debugging output will go to the printer as well as the screen. Debugging a program that is also printing may cause some confusion, but should work properly. 4.2.12 <S>creen This command will display the 'program screen'. When selected, the screen contents of the target program will be displayed. Press any key to return to the debugger screen. NOTE: If the program being debugged displays any CGA or EGA graphics, the '-C' or the '-E' debugger option must be specified to set aside enough memory for the screen contents. See section 3.1 for a description of command line options. 4.2.13 <T>race This command allows you to step through program execution. When selected, the following menu will be displayed: <A>nimate <S>ingle step roc step These commands are discussed below. 4.2.13.1 <A>nimate This option allows variable-speed continuous <S>ingle step or roc step tracing. When selected, you will be asked the speed. The fastest animation speed is 0, the slowest allowed is 50. When a number 0 thru 50 is entered, you will be returned to the <T>race menu. At this point, you may select <A>nimate again to change your speed, or select <S>ingle step or roc step to start execution. The <A>nimation Breakpoints option will allow you to enable or disable breakpoints during <A>nimation. See section 4.2.9.1. The TTCD Commands and Displays Page 27 4.2.13.2 <S>ingle step This option will allow you to execute one line of the target program at a time. When selected, the next source line to be executed will be displayed with an arrow pointing to it. Also, the following menu will be displayed: <A>nimate <SPACE> = <S>ingle step, roc step, <F>lip = ON Each time <SPACE> or <S> is pressed, the next statement will be executed, and the next line will be displayed with an arrow pointing to it. Press <A> to start animation (see section 4.2.13.1). Press to change the trace mode to roc tracing (see section 4.2.13.3). Press <F> to toggle the "Flip screen on trace" option (see section 4.2.9.3). Any other key will end the trace mode and return to the main menu. When the <S>ingle step mode reaches a function call, that function will be stepped through if it is in a module compiled with line numbers. NOTE: You may only single step through procedures that are in modules compiled with the 'line numbers' option on. 4.2.13.3 roc step This option will allow you to execute one line of the target program at a time. When selected, the next source line to be executed will be displayed with an arrow pointing to it. Also, the following menu will be displayed: <A>nimate <S>ingle step, <SPACE> = roc step, <F>lip = ON Each time <SPACE> or is pressed, the next statement will be executed, and the next line will be displayed with an arrow pointing to it. Press <A> to start animation (see section 4.2.13.1). Press <S> to change the trace mode to <S>ingle tracing (see section 4.2.13.2). Press <F> to toggle the "Flip screen on trace" option (see section 4.2.9.3). Any other key will end the trace mode and return to the main menu. roc tracing differs from <S>ingle step tracing in that procedures are not traced, but executed in one step. Even if a procedure is in a module compiled with line numbers, it will not be stepped through if its calling function is being roc traced. 4.2.13.4 Using <T>race Due to the way the trace mode must work, long delays may be caused with looping constructs on one line. For instance, if a section of code reads: The TTCD Commands and Displays Page 28 99 j=10000; 100 for(i=0;i<j;i++) array[i] = (array[i] >> 2) + array[i+1]; 101 printf("Loop completed %u iterations\n",j); Using the <A>, <S> or commands to trace through the statements above will work fine, however, line 100 may take several minutes to step through. One solution is to avoid single-line looping statements. The following is more readable anyway: 99 j=10000; 100 for(i=0;i<j;i++) 101 array[i]= (array[i] >> 2) + array[i+1]; 102 printf("Loop completed %u iterations\n",j); This may be stepped through also, but after seeing line 101 several times, you may be inclined to use the <G>o command instead of pressing <SPACE> 10,000 times. If you are fond of single-line looping constructs and do not wish to change your programming style, another solution is to <T>race up to the line, use the <G>o command to jump past it, and resume tracing with the following line. NOTE: When a C statement extends over multiple source lines, the <T>race command will only show the last line of the statement (with an arrow pointing to it). 4.2.14 nassemble This command allows you to un-assemble program code. When selected, you will be asked for a line number. When entered, a disassembly listing will be displayed for the code in the specified line. Pressing <SPACE> will display a disassembly listing of successive source lines, one at a time. Any other key will return to the main menu. The code at any address may be un-assembled by entering the address preceded by an 'a'. For instance, when prompted for the line number to start un-assembling at, if "a100" is entered, a disassembly listing will be displayed, starting CS:100. A starting segment may also be specified, such as "a6d00:0174". The instructions displayed by the nassemble command differ slightly from Intel/MASM assembler instructions, as discussed in section 5.2. One addition to the disassembled instructions is the appearance of global symbol names out to the right of some instructions. Any instruction containing an address corresponding to a global symbol location will have that symbol displayed following the instruction. The symbol will be enclosed in angle brackets. '<>'. For instance, an nassemble listing may resemble the following: The TTCD Commands and Displays Page 29 == 51 == 560D:00E1 E97B01 JMP 25F == 53 == 560D:00E4 B80100 MOV AX,1 560D:00E7 50 PUSH AX 560D:00E8 FF364E0D PUSH [0D4E] <currow> 560D:00EC FF36BF0D PUSH [0DBF] <curcol> 560D:00F0 9A0202C759 LCALL 59C7:0202 <deletecell()> 560D:00F5 83C406 ADD SP,6 == 54 == 560D:00F8 9A6B03C759 LCALL 59C7:036B <printfreemem()> == 55 == 560D:00FD 803E860000 CMP BYTE [0086],0 <autocalc> 560D:0102 7503 JNE 0107 560D:0104 E95801 JMP 25F This is a disassembly of lines 51 thru 55. Notice that line 52 is not listed. This is because no code was generated from this line of source code. Note that 'deletecell()' and 'printfreemem()' are procedures, while 'currow', 'curcol', and 'autocalc' are variables. Due to the way 8086 instructions may be indexed, it is possible for a global symbol to be displayed erroneously because its address matched a "displacement" value in an instruction. This should be rare, but it can happen. Warning: Any model that has 4-byte addresses, may not display some global symbol names. For instance, in the above section of code, lets suppose I was just looking at a disassembly of line 51, but was currently at line 347, the DS register may have a different value, and the address DS:0D4E would not correspond to the location of "currow". If this were the case, the "<currow>" symbol would not be displayed to the right of the instruction at 560D:00E8. The is also true for statements that have a "segment override", such as: MOV AX,ES:[0D4E] If ES did not have the value at dis-assembly time that it will have at execution time, the global symbol name will not be displayed. 4.3 The Repeat Count The "repeat count" is a number from 0 to 9999 entered at the main menu. It is used to specify "how many times" the next command does some action. The repeat count is used differently for different commands, and is a very powerful command option if used properly. The repeat count is displayed near the left end of the status line. The repeat count is used in conjunction with each command discussed below. The TTCD Commands and Displays Page 30 o reakpoints - A repeat count greater than 1 when a breakpoint is set will cause the breakpoint to be "ignored" N-1 times. The default is 1. For instance, if I press: <1> <5> <1> <L> 10 This will set a non-sticky breakpoint (number 1) to line 10, but the breakpoint will be dormant for 14 "passes" through line 10. On the 15th time line 10 is reached, the breakpoint will return control to the debugger. o <D>isplay - the repeat count determines the number items displayed. The default is 1. The repeat count is ignored if the display type is <H>ex or <S>tring. o <G>o - A repeat count greater than 1 when the <G>o command is selected will cause execution to "pass-through" the specified line or procedure N-1 times. The default is 1. For instance, if I press: <5> <3> <G> update_display The fifty-third time "update_display()" is called, control will return to the debugger main menu. o <L>ist - The repeat count determines the number of lines listed each time <SPACE> is pressed. The default is 5. o nassemble - The repeat count determines the number of lines un-assembled each time <SPACE> is pressed. The default is 1. 4.4 Program Termination When the target program ends execution (either normally, or abnormally), the message "Execution Terminated (return value=%d)" will be displayed. The "%d" will be replaced with the value returned by the program (i.e. - the number specified in the "exit()" command). NOTE: If there is not enough memory to execute the target program, the program termination message may be displayed erroneously. See section 5.8. The TTCD Commands and Displays Page 31 5.0 Notes about Debugging with TTCD 5.1 Source Code Formatting The format of C source code can cause the line numbers in the .MAP file to be seemingly incorrect. This can cause some confusion when trying to debug programs. Simple changes in the source code formatting style can minimize this problem. The following is a list of source-formatting considerations when writing programs: o One C statement per line line. A 'while' or 'for' construct is counted as a separate statement here. o Put 'else' statements on lines by themselves. o Looping constructs should have a blank line after the statements in the body of the loop, or have the close-brace on a line by itself. For instance: 15 for(i=0;i<100;i++) 16 *ptr++=0; 17 printf("Loop complete\n"); A blank line inserted before line 17 will make this portion of the code easier to trace. These are never necessary, but can make source-level debugging much easier to follow. 5.2 Mnemonic Differences Some of the instruction mnemonics displayed by the nassemble command will differ slightly from Intel/MASM mnemonics. These have been changed for reasons of clarity. For instance, a disassembly showing a RET instruction does not tell us if it is a 2-byte (near) or 4-byte (far) return. The major deviations from MASM/Intel mnemonics are with the JMP, CALL, and RET instructions. TTCD uses JMP, CALL, and RET instructions to refer to NEAR control transfers. LJMP, LCALL, and LRET are the respective FAR control transfers of these instructions. Also the format of indirect instructions has been simplified, as shown below. MASM TTCD CALL WORD PTR [100] CALL [100] CALL DWORD PTR [100] LCALL [100] JMP WORD PTR [100] JMP [100] JMP DWORD PTR [100] LJMP [100] Notes about Debugging with TTCD Page 32 In general the word "PTR" is not used, and data-size modifiers (such as "BYTE" or "WORD") are only used when required. 5.3 Special Interrupts Turbo C uses different interrupt vectors to handle floating point emulation than those specified in the Intel Technical Reference manuals. They are INT numbers: 0x35, 0x37, 0x38, 0x39, 0x3a, 0x3c and 0x3d. These interrupts are treated in a special manner. TTCD will attempt to decode a variable number of bytes following any of these INT instructions. If any incorrect decoding (due to some other use for any of these INT's) is encountered during tracing, TTCD will display incorrect un-assembly listings, and may lose control of the target program. 5.4 Floating Point Emulation Deviations As mentioned above, Turbo C code differs somewhat from Intel 8087 emulation specs. Because of this, I have had to handle some floating point emulation code by "seat of the pants" methods. If you should ever encounter an nassemble listing that has no mnemonic on a line, then I have missed an instruction type. PLEASE LET ME KNOW OF ANY SUCH OCCURRENCE. If you are a registered full version user, you will be able to download a fixed version, when available. 5.5 Floating Point Problems There seems to be a minor bug in Turbo C causing a problem with some line numbers in the .MAP file. It seems that any source line whose first assembler instruction is a floating point instruction (8087 or emulation code) will not have a line number entry in the .MAP file. For example, given the following source code: #include <stdio.h> #include <math.h> main() { float dbl1=1,dbl2=1; printf("Line 8\n"); dbl1=dbl1+dbl2; printf("Line 10\n"); exit(0); } Notes about Debugging with TTCD Page 33 Tracing through this program with the rint option on will print the following: 5 ->{ 6 -> float dbl1=1,dbl2=1; 8 -> printf("Line 8\n"); 10 -> printf("Line 10\n"); 12 -> exit(0); Execution terminated (return value=0) Notice that line 9 was not traced. This is due to the missing line number in the .MAP file. Also, line 9 cannot be specified for: reakpoint, <G>oto, or nassemble. A simple work-around is to put a "dummy" line of code in front of any such line (for debugging purposes), and use it as the target of a reakpoint, <G>oto, or nassemble. For instance, the following line of C will work nicely: _AL=1; 5.6 Optimization Options If the "Use register variables" option is on, it is possible for the <D> <G> command to show incorrect values. This is due to the compiler keeping some variable values temporarily in registers. The nassemble command can be used to check for this. Use the <D> <R> command to display register values. If the "Jump optimization" option is on, tracing through some statements may lead to a little confusion. This is particularly true of "switch" statements. It is best to leave this option off if you are new to TTCD. 5.7 The "#line" Directive The #line directive causes the compiler to re-map the line numbers put in an object file compiled with line numbers. If the #line directive is specified in a source module, that you intend to view in TTCD, the source lines displayed may not be correct lines corresponding to a location in the code segment. If at some point in the program TTCD thinks you are at a certain line, it may be displaying a different source code line on the screen because of a previous #line directive. 5.8 Memory Considerations Due to the way that child processes are loaded and executed, it is possible to not get an "out of memory" error message when the process-spawning routine really does run out of memory. Notes about Debugging with TTCD Page 34 In most cases, if there is not enough memory to execute the target program, an error message will be displayed, and TTCD will exit to DOS. It is possible for TTCD to display the message "Execution Terminated" when the target program did not attempt to run at all. This seems to happen if there is enough memory to load and relocate a load-module, but not enough memory to start execution of it (which requires setting up stack space, and the uninitialized data space). 5.9 Interrupt Vector Trapping In order to debug Turbo C programs that trap an interrupt vector (or otherwise modify the interrupt vector table), TTCD preserves the interrupt vector table. TTCD has not been tested extensively with programs that modify the interrupt vector table, but most "interrupt-trapping" programs should be able to used with it. There will probably be some difficulty in attempting to use TTCD to debug any program that traps a "timed" interrupt vector. Care should be taken if any interrupt vectors are set to point to procedures in the target program. TTCD will not be able to trace through the procedure unless trapped by a reakpoint, and then traced. Note that if the "interrupt" procedure transfers control to another point in the target program (via "longjmp"), TTCD may lose control of execution, unless you are tracing the interrupt procedure, or use a reakpoint. For instance, if a target program traps the <Ctrl><Break> vector, and then does a long jump to the program's main menu, it is a good idea to set a sticky breakpoint at the program's main menu. This will allow you to press <Ctrl><Break> while debugging your program, and TTCD will still maintain control of it. NOTE: TTCD uses interrupt vector number 3. If any target program changes this vector, TTCD will "lose control" of execution of it. 5.10 Trapping Math Errors TTCD will not trap, or control the trapping of math errors in any target program. In other words, if the target program traps math errors on its own, that routine will still trap math errors when executed under TTCD. If math errors are not trapped, the default action for Turbo C to generate is a one-line error message, then abort the program with a return value of 3. Notes about Debugging with TTCD Page 35 This is worth mentioning because, while tracing through a program, you may not see an error message flash by, only the TTCD message "Execution Terminated (return value=3)". If the "Flip screen on <T>race" option is on, any error message should be on the target program screen; otherwise, it may be overwritten by debugging information. Notes about Debugging with TTCD Page 36 6.0 Input responses to TTCD prompts 6.1 Input field editing Inputs to TTCD may be edited using the cursor keys. The following keys are used for input editing: <ENTER> Enter the displayed input into TTCD. The cursor does not have to be at the end of the input string when <ENTER> is pressed. <BackSpace> Move the cursor left in the input field, erasing characters as it goes. <Del> Delete the character under the cursor. <Home> Move the cursor to the beginning of the input field. <End> Move the cursor to the last character in the input field. <left arrow> Move the cursor left in the input field, but do not erase characters. <right arrow> Move the cursor right in the input field. <Ctrl><left arrow> Move the cursor left one word. <Ctrl><right arrow> Move the cursor right one word. <Ctrl><Home> Erase from the current cursor position to the beginning of the input field. <Ctrl><End> Erase from the current cursor position to the end of the input field. Many input prompts are pre-filled with expected values. If a value is displayed, you may: press the <ENTER> key to input it, use the editing keys to edit it, or just type the desired response, and it will be cleared automatically. 6.2 Case sensitivity Like the C language, all input responses to TTCD prompts are case sensitive. An exception to this is hex digits. When a hex number is entered, its digits may be upper or lower case. Any global symbol name entered in response to a TTCD prompt will not be found if the letters do not match exactly. Notes about Debugging with TTCD Page 37 6.3 Input Radix Defaults When TTCD prompt for a numeric input of some kind, it expects hex numbers in some cases, and decimal in others. To be specific, addresses or address offsets are expected in hexadecimal. Non- address values (i.e. - a conditional breakpoint comparison value, input to the <C>alculator, etc.) are expected to be decimal numbers. A hexadecimal number may be entered where a decimal number is expected, by prefixing the number with a "0x". (Just like in the "C" language.) 6.4 Address Specification Defaults All addresses entered into TTCD that do not contain a segment specification have an implied segment register. The default segment values are similar to those used when programming in assembler. These can always be overridden by specifying a segment value, or a segment register in the address expression. The implied segment values are as follows: CS - If the address is 'code' related. SS - If the address expression contains SP or BP. DS - All other addresses. Notes about Debugging with TTCD Page 38 7.0 TTCD.MAC Format and Use If there is a file named "TTCD.MAC" in the current directory, or the DOS path, it is loaded when TTCD begins execution. This file contains TTCD configuration information, and the key macros last saved (via the <M> <S> command). The format of TTCD.MAC is: Offset (byte) Use ------ --- 0 Color of non-highlighted menu characters. 1 Color of highlighted menu characters. 2 Status line color. 3 "Keep" information color. 4 Input prompt color. 5 Input response color. 6 Color of main debugging area. 7 Color of traced lines. 8-10 Reserved for future use. 11-13 Option Settings. 14-20 Reserved for future use. 20+ Extended key codes for each of the 10 macro keys. The first 8 bytes in TTCD.MAC are the attributes bytes for the specified screen areas. These may be changed with the DOS DEBUG program, or a hex file editor. TTCD Details and Nomenclature Page 39 8.0 Known TTCD Bugs and Anomalies At the time of this writing, there is one known bug in TTCD. As discussed in section 5.8, it is possible for the target program to abend with an error code of 3, when it did not really execute at all. Known TTCD Bugs and Anomalies Page 40 9.0 Version Changes/Modification to TTCD Version Enhancements/Modifications ------- ------------ ------------- 1.0 Beta test release 1.1 Added colors, enhanced screen handling and snow suppression. Corrected some dis-assembly bugs. 1.2 Added conditional breakpoints. Added <K>eep command. Made colors configurable. Enhanced key macros. Corrected more dis-assembly bugs. 1.3 Added Target program "animation". Added <V>iew command. Added <C>alc command. Added -B (File buffer size) command line option. Added full support for target program re-direction (thru DOS). Corrected some input error checking. 1.4 Added the ability to turn on breakpoints during program animation. Added an option to display the current <O>ption settings. Now uses the DOS path to find the configuration file "TTCD.MAC". Enhanced keyboard menu input. Now saves the configuration items in "TTCD.MAC". Version Changes/Modification to TTCD Page 41 1.5 Corrected to use the next line if a specified line number does not have any code associated with it. Added a <R>estart option to the <Q>uit menu. Now supports source code in other drives/directories. Now accepts a module name associated with a source code line number when specifying breakpoints or <G>o addresses. Corrected to clear non-sticky breakpoints after <A>nimation only if it was not aborted. Included "conditional breakpoint" macro include file "COND.H". Version Changes/Modification to TTCD Page 42