DD&T - Debugger Disassembler and Trace Utility [ ] [ ] [DD&T Graphic] [ ] [ ] TABLE OF CONTENTS General Information.....................................1 DD/CMD - Debugger Disassembler..........................2 DOS Program Trace Utility ..............................3 PTRACE - Program Trace Module ..........................3 STRACE - Statistical Trace Report.......................4 DD/CMD, PTRACE/CMD, and STRACE/CMD: Copyright 1984 by Richard N. Deglin, All rights reserved. DD&T is published by MISOSYS, Inc., Sterling VA 22170. LDOS and LS-DOS are trademarks of Logical Systems Inc. TRSDOS is a trademark of Tandy Corp. GENERAL INFORMATION This documentation covers the Model I/III version of DD&T which functions under the LDOS 5.1 operating system. It also covers the TRSDOS 6.x or LS-DOS 6.x version of DD&T called PRO-DD&T. The specific version of DD&T is noted on the diskette label supplied with this package. The D0&T package provides the assembler programmer with a major enhancement to the debugger supplied with your DOS. The Debugger Disassembler module is completely relocatable. Its interface to the DOS debugger is automatic. The TRACE utility can be used to help hone your programs to optimum efficiency. DD and TRACE together make DD&T a set of fine tools crafted to provide you with a rewarding assembler programming experience. DD&T - 1 DD&T - Debugger Disassembler and Trace Utility DD/CMD - Debugger Disassembler DD/CMD is an enhancement to the DOS system debugger which provides the added capability of an on-line disassembler during your program debugging sessions. Once invoked, it resides interfaced to the system's DEBUG module available at the touch of a button. DD is invoked via the command: ================================================= | | | Db (parameter) | | | | ON Loads the DD module into high memory | | and links into the system debugger. | | | | OFF Unlinks DD from the debugger and | | reclaims high memory if possible. | | | | Abbr: ON=YES or Y. OFF=NO or N | ================================================= The command "DD (ON)" or "DD" loads the DD high memory module and links itself into the system debugger. DD may be SYSGENed if you find it convenient to have the Debugger Disassembler available at each boot. The high memory module takes less than 1600 bytes of memory. A subsequent entry into the system debugger (normal or extended) activates the DD module. In the upper right hand corner of the debugger register display ("X" mode), DD will display a mnemonic disassembly of the 280 instruction which the current program counter (PC) points to. After a single-stepping debugger command ("I", "C", or "J") is executed, or a breakpoint is reached via use of the "G,nnnn" command, DD will update this instruction disassembly automatically. DD also provides for 280 disassembly directly from any memory location in your computer's 64 Kilobyte address space. The command "Z" will start the disassembly from the current program counter. The command "Znnnn" will start the disassembly from the hexadecimal address given in the command as "nnnn". The screen will clear, and 16 or 24 lines of disassembled instructions will be displayed, depending on whether you are operating version 5 or 6 of the DOS. You may continue the display with one or more additional screenfulls of disassembly by typing any keystroke; if you type "X", however, you will be returned to the prior debugger display screen ("X", or "S" mode). The DOS command "DD (OFF)" will unlink DD from the system debugger and attempt to reclaim high memory space. If DD is the first module found in protected high memory, the space will be reclaimed and the protected memory pointer (HIGH$) adjusted. If the DD module is not the first protected module, DD will unlink but the high memory allocation will remain. If the latter is the case, and you reload DD with the ON parameter, it will reuse the same high memory space as it previously occupied. DD&T - 2 DD&T - Debugger Disassembler and Trace Utility DOS Program Trace Utility The function of the TRACE utility is to simply show you where your program spends most of its time in execution. Programs may be coded so that they waste too much time in inefficiently written program routines. TRACE finds these program sections for you by means of the Statistical TRACE Report. You should compare your program listing against the TRACE report and analyze the routines where your program spends its time. Start tracing with a coarse address range. Once you identify major sections, you can narrow the trace to produce a more detailed snapshot of a given piece of code. Ask yourself if the section of code should normally be executed more frequently than other sections. If there is no reason for such frequent execution, look for another way to code the routine. By reducing these bottlenecks of inefficient routines, your programs will run faster. The DOS program trace utility is a package of two utilities designed to help you optimize the design and coding of an assembler application program. It consists of two utilities; PTRACE which records program activity by execution address ranges and, STRACE which compiles and displays the statistics of a series of PTRACE runs. PTRACE - Program Trace module PTRACE allows you to execute the target program in an environment which maintains a record of all program activity. Note that you cannot directly trace a library member. Your selected address range is divided evenly into 256 "buckets". PTRACE keeps a counter for each bucket. Two other buckets are used to track activity in areas above and below the selected range. Every time a system heartbeat interrupt occurs, PTRACE determines the program counter at the time of interrupt and updates the counter corresponding to the correct bucket. PTRACE is invoked via the command: ================================================= | | | PTRACE trace-file (START=X'nnnn',END=X'nnnn') | | | | trace-file The filespec to receive the trace | | data table generated during the | | target program's invocation. | | | | START The lower address range to obtain | | trace data. | | | | END The upper address range to obtain | | trace data. | | | | Abbr: START=S. END=E | ================================================= DD&T - 3 DD&T - Debugger Disassembler and Trace Utility The trace file is written out to disk when the trace terminates; i.e. when the target program exits to DOS Ready. START and END determine the address range; they must be greater than 255 bytes apart. The defaults are STAHT=X'0000' and END=X'FFFF' To keep interrupt overhead to a minimum, the range is rounded up to the next higher power-of-2; e.g 256, 512, 1024. The maximum range is all of memory, or 65536. If the table filespec [trace-file] is not entered on the DOS command line, PTRACE will prompt for it. In any case, PTRACE will prompt for the command line which will execute the target program. This is entered identically to the DOS command line which would be used to invoke the target program normally. PTRACE will load and execute the target program, trace its activity, and terminate by saving the bucket counters and associated range data as a Program Trace Table to a disk file, with default extension /PTT. \JVhile the trace is active, PTRACE will place a blinking asterisk (*) in the upper right corner of the video screen. Ten sample trace tables are included on this disk as T0/PTT through TS/PTT. STRACE - Statistical TRACE Report STRACE will report statistics computed from the data in one or more trace result files. In many cases, it will be desirable to repeat a PTRACE run several times. This depends on the range of the trace, how long the target program executes, and how fast your DOS computer is running (2 MHz or 4MHz, for instance). If a range is wide, the trace results will be coarser. If a target program run is short, fewer statistics will be gathered. If your computer is running fast, the fixed system interrupt interval will fall behind program activity. In any case, the more trace runs you make, the better the statistics will be. Use of a Job Control Language file to invoke PTRACE will ease this process. STRACE is invoked by the command: STRACE [trace-file-l] [trace-file-2] ... [trace-file-N] The file extension default of "/PTT" will be added to the file specification if you omit it. The report can be redirected to the printer by appending ">PR" to the command line, or to a file by appending ">report file" to the command line. The quotes are not entered. At least one trace file specification must be entered, but their order is not significant if more than one is present. If a consecutive series of "buckets" within the trace range all have a count of zero occurrences, they are squeezed together to form one "bucket" in the output listing. You cannot generate an STRACE report from trace tables with different address ranges. A sample trace report is included on this disk as TEST/RPT. DD&T - 4