.bp odd .cs 5 .bp odd .he .mt 5 .mb 6 .pl 66 .ll 65 .po 10 .hm 2 .fm 2 .ft All Information Presented Here is Proprietary to Digital Research .he .tc 8 DDT-8000 .ce 2 =================== RE-WRITE USING DATA FROM THORN'S =============== =================== PORTABLE DEBUGGER WRITEUP =============== .sh Section 8 .sp .sh DDT-8000 .qs .sp 3 .he CP/M-8000 Programmer's Guide 8.1 DDT-8000 Operation .tc 8.1 DDT-8000 Operation .sh 8.1 DDT-8000 Operation .qs .ix DDT-8000 operation .pp DDT-8000\ \allows you to test and debug programs interactively in a CP/M-8000 environment. You should be familiar with the Z8000 Microprocessor, the assembler (AS68) and the CP/M-8000 operating system. .sp 2 .tc 8.1.1 Invoking DDT-8000 .sh 8.1.1 Invoking DDT-8000 .qs .pp Invoke DDT-8000 by entering one of the following commands: .sp .in 8 .nf DDT DDT filename .in 0 .fi .pp 5 The first command loads and executes DDT-8000. After displaying its sign-on message and the hyphen (-) prompt character. DDT-8000 is ready to accept commands. The second command invokes DDT-8000 and loads the file specified by filename. If the filetype is not specified, it defaults to the 8000 filetype. The second form of the command is equivalent to the sequence: .nf .sp .in 8 A>\c .sh DDT .qs .in 8 DDT-8000 .in 8 Copyright 1982, Digital Research .in 8 -Efilename .in 0 .sp .fi At this point, the program that was loaded is ready for execution. .sp 2 .tc 8.1.2 DDT-8000 Command Conventions .sh 8.1.2 DDT-8000 Command Conventions .qs .ix DDT-8000 command conventions .pp 5 When DDT-8000 is ready to accept a command, it prompts you with a hyphen (-). In response, you can type a command line or a CONTROL-C (^C) to end the debugging session (see Section 8.1.4). A command line can have as many as 64 characters, and must be terminated with a RETURN. While entering the command, use standard CP/M line-editing functions to correct typing errors. See Table 4-12. DDT-8000 does not process the command line until you enter a RETURN. .pp 5 The first nonblank character of each command line determines the command action. Table 8-1 summarizes DDT-8000 commands. They are defined individually in Section 8.2. .bp .ix DDT-8000 command summary .sh .ce Table 8-1. DDT-8000 Command Summary .sp .nf Command Action D display memory in hexadecimal and ASCII E load program for execution F fill memory block with a constant G begin execution with optional breakpoints H hexadecimal arithmetic I set up file control block and command tail L list memory using Z8000 mnemonics M move memory block R read disk file into memory S set memory to new values T trace program execution U untrace program monitoring V show memory layout of disk file read W write contents of memory block to disk X examine and modify CPU state .fi .sp .pp The command character may be followed by one or more arguments, which may be hexadecimal values, filenames, or other information, depending on the command. Some commands can operate on byte, word, or longword data. The letter W for word or a L for longword must be appended to the command character for commands that operate on multiple data lengths. Details for specific commands are provided with the command descriptions. Arguments are separated from each other by commas or spaces. .sp 2 .sh .tc 8.1.3 Specifying Address 8.1.3 Specifying Addresses .qs .pp Most DDT-8000 commands require one or more addresses as operands. All addresses are entered as hexadecimal numbers of up to eight hexadecimal digits (32 bits) .sp 2 .sh .tc 8.1.4 Terminating DDT-8000 8.1.4 Terminating DDT-8000 .qs .ix DDT-8000, terminating .ix terminating DDT-8000 .pp Terminate DDT-8000 by typing a ^\b|C in response to the hyphen prompt. This returns control to the CCP. .sp 2 .sh .tc 8.1.5 DDT-8000 Operation with Interrupts 8.1.5 DDT-8000 Operation with Interrupts .qs .pp DDT-8000 operates with interrupts enabled or disabled, and preserves the interrupt state of the program being executed under DDT-8000. When DDT-8000 has control of the CPU, either when it is initially invoked, or when it regains control from the program being tested, the condition of the interrupt mask is the same as it was when DDT-8000 was invoked, except for a few critical regions where interrupts are disabled. While the program being tested has control of the CPU, the user's CPU state, which can be displayed with the X command, determines the state of the interrupt mask. .pp Note that DDT-8000 uses the Trace and Illegal Instruction exceptions. Therefore, programs debugged under test should not use these. .sp 2 .he CP/M-8000 Programmer's Guide 8.2 DDT-8000 Commands .sh .tc 8.2 DDT-8000 Commands 8.2 DDT-8000 Commands .qs .mb 5 .fm 1 .ix DDT-8000 commands .pp This section defines DDT-8000 commands and their arguments. DDT-8000 commands give you control of program execution and allow you to display and modify system memory and the CPU state. .sp 2 .sh .tc 8.2.1 The D (Display) Command 8.2.1 The D (Display) Command .qs .ix D (Display) command (DDT-8000) .pp The D command displays the contents of memory as 8-bit, 16-bit, or 32-bit hexadecimal values and in ASCII. The forms are: .sp .nf .in 8 D Ds Ds,f DW DWs DWs,f DL DLS DLS,f .in 0 .fi .sp where s is the starting address, and f is the last address that DDT-8000 displays. .pp Memory is displayed on one or more lines. Each line shows the values of up to 16 memory locations. For the first three forms, the display line appears as follows: .mb 6 .fm 2 .sp .ti 8 aaaaaaaa bb bb ... bb cc ... cc .sp where aaaaaaaa is the address of the data being displayed. The bb's represent the contents of the memory locations in hexadecimal, and the c's represent the contents of memory in ASCII. Any nongraphic ASCII characters are represented by periods. .pp In response to the DS form of the D command, shown above, DDT-8000 displays 12 lines that start from the current address. Form Ds,f displays the memory block between locations s and f. Forms DW, DWs, and DWs,f are identical to D, Ds, and Ds,f except the contents of memory are displayed as 16-bit values, as shown below: .sp .ti 8 aaaaaaaa wwww wwww ... wwww cccc ... cc .pp Forms DL, DLs, and DLs,f are identical to D, Ds, and Ds,f except the contents of memory are displayed as 32-bit or longword values, as shown below: .sp .ti 8 aaaaaaaa llllllll llllllll ... llllllll cccccccc ... .pp During a display, the D command may be aborted by typing any character at the console. .sp 2 .sh .tc 8.2.2 The E (Load for Execution) Command 8.2.2 The E (Load for Execution) Command .qs .ix E (Load for Execution) command (DDT-8000) .pp The E command loads a file in memory so that a subsequent G, T or U command can begin program execution. The syntax for the E command is: .sp .ti 8 E .sp where is the name of the file to be loaded. If no file type is specified, the filetype 8000 is assumed. .pp An E command reuses memory used by any previous E command. Thus, only one file at a time can be loaded for execution. .pp When the load is complete, DDT-8000 displays the starting and ending addresses of each segment in the file loaded. Use the V command to display this information at a later time. .pp If the file does not exist or cannot be successfully loaded in the available memory, DDT-8000 displays an error message. See Appendix E for error messages returned by DDT-8000. .sp 2 .sh .tc 8.2.3 The F (Fill) Command 8.2.3 The F (Fill) Command .qs .ix F (Fill) command (DDT-8000) .pp The F command fills an area of memory with a byte, word, or longword constant. The forms are .sp .ti 8 Fs,f,b .ti 8 FWs,f,w .ti 8 FLs,f,l .sp where s is the starting address of the block to be filled, and f is the address of the final byte of the block within the segment specified in s. .pp In response to the first form, DDT-8000 stores the 8-bit value b in locations s through f. In the second form, the 16-bit value w is stored in locations s through f in standard form: the high 8 bits are first, followed by the low 8 bits. In the third form, the 32-bit value l is stored in locations s through f with the most significant byte first. .pp If s is greater than f, DDT-8000 responds with a question mark. Also, if b is greater than FF hexadecimal (255), w is greater than FFFF hexadecimal (65,535), or l is greater than FFFFFFFF hexadecimal (4,294,967,295), DDT-8000 responds with a question mark. DDT-8000 displays an error message if the value stored in memory cannot be read back successfully. This error indicates a faulty or nonexistent RAM location. .bp .sh .tc 8.2.4 The G (Go) Command 8.2.4 The G (Go) Command .qs .ix G (Go) command (DDT-8000) .pp The G command transfers control to the program being tested, and optionally sets one to ten breakpoints. The forms are .sp .nf .in 8 G G,b1,...b10 Gs Gs,b1,...b10 .in 0 .fi .sp where s is the address where program begins executing and b1 through b10 are addresses of breakpoints. .pp In the first two forms, no starting address is specified. DDT-8000 starts executing the program at the address specified by the program counter (PC). The first form transfers control to your program without setting any breakpoints. The second form sets breakpoints before passing control to your program. The next two forms are analogous to the first two except that the PC is first set to s. .ix program counter (PC) .pp Once control has been transferred to the program under test, it executes in real time until a breakpoint is encountered. At this point, DDT-8000 regains control, clears all breakpoints, and displays the CPU state in the same form as the X command. When a breakpoint returns control to DDT-8000, the instruction at the breakpoint address has not yet been executed. To set a breakpoint at the same address, you must specify a T or U command first. .sp 2 .sh .tc 8.2.5 The H (Hexadecimal Math) Command 8.2.5 The H (Hexadecimal Math) Command .qs .ix H (Hexadecimal Math) command (DDT-8000) .pp The H command computes the sum and difference of two 32-bit values. The form is: .sp .ti 8 Ha,b .sp where a and b are the values whose sum and difference DDT-8000 computes. DDT-8000 displays the sum (ssssssss) and the difference (dddddddd) truncated to 16 bits on the next line as shown below: .sp .ti 8 ssssssss dddddddd .sp 2 .sh .tc 8.2.6 The I (Input Command Tail) Command 8.2.6 The I (Input Command Tail) Command .qs .ix I (Input Command Tail) command (DDT-8000) .pp The I command prepares a file control block (FCB) and command tail buffer in DDT-8000's base page, and copies the information in the base page of the last file loaded with the E command. The form is .sp .ti 8 I .bp where is the character string which usually contains one or more filenames. The first filename is parsed into the default file control block at 005CH. The optional second filename, if specified, is parsed into the second default file control block beginning at 0038H. The characters in the are also copied to the default command buffer at 0080H. The length of the is stored at 0080H, followed by the character string terminated with a binary zero. .pp If a file has been loaded with the E command, DDT-8000 copies the file control block and command buffer from the base page of DDT-8000 to the base page of the program loaded. .sp 2 .sh .tc 8.2.7 The L (List) Command 8.2.7 The L (List) Command .qs .ix L (List) command (DDT-8000) .pp The L command lists the contents of memory in assembly language. The forms are .sp .ti 8 L .ti 8 Ls .ti 8 Ls,f .sp where s is the starting address, and f is the last address in the list. .pp The first form lists 12 lines of disassembled machine code from the current address. The second form sets the list address to s and then lists 12 lines of code. The last form lists disassembled code from s through f. In all three cases, the list address is set to the next unlisted location in preparation for a subsequent L command. When DDT-8000 regains control from a program being tested (see G, T and U commands), the list address is set to the address in the program counter (PC). .pp Long displays can be aborted by typing any key during the list process. Or, enter CONTROL-S (^\b|S) to halt the display temporarily. A CONTROL-Q (^\b|Q) restarts the display after ^\b|S halts it. .pp The syntax of the assembly language statements produced by the L command is described in the \c .ul Zilog 16-Bit Microprocessor User's Manual, \c .qu third edition, Z8000UM(AD3). .sp 2 .sh .tc 8.2.8 The M (Move) Command 8.2.8 The M (Move) Command .qs .ix M (Move) command (DDT-8000) .pp The M command moves a block of data values from one area of memory to another. The form is .sp .ti 8 Ms,f,d .sp where s is the starting address of the block to be moved, f is the address of the final byte to be moved, and d is the address of the first byte of the area to receive the data. Note that if d is between s and f, part of the block being moved will be overwritten before it is moved, because data is transferred starting from location s. .sp 2 .sh .tc 8.2.9 The R (Read) Command 8.2.9 The R (Read) Command .qs .ix R (Read) command (DDT-8000) .pp The R command reads a file to a contiguous block in memory. The format is .sp .ti 8 R .sp where is the name and type of the file to be read. .pp DDT-8000 read the file in memory and displays the starting and ending addresses of the block of memory occupied by the file. A Value (V) command can redisplay the information at a later time. The default display pointer (for subsequent Display (D) commands) is set to the start of the block occupied by the file. .sp 2 .sh .tc 8.2.10 The S (Set) Command 8.2.10 The S (Set) Command .qs .ix S (Set) command (DDT-8000) .pp The S command can change the contents of bytes, words, or longwords in memory. The forms are .sp .ti 8 Ss .ti 8 SWs .ti 8 SLs .sp where s is the address where the change is to occur. .pp DDT-8000 displays the memory address and its current contents on the following line. In response to the first form, the display is .sp .ti 8 aaaaaaaa bb .sp In response to the second form, the display is .sp .ti 8 aaaaaaaa wwww .sp In response to the third form, the display is .sp .ti 8 aaaaaaaa llllllll .sp where bb, wwww, and llllllll are the contents of memory in byte, word, and longword formats, respectively. .pp In response to one of the above displays, you can alter the memory location or leave it unchanged. If a valid hexadecimal value is entered, the contents of the byte, word, or longword in memory is replaced with the value entered. If no value is entered, the contents of memory are unaffected and the contents of the next address are displayed. In either case, DDT-8000 continues to display successive memory addresses and values until either a period or an invalid value is entered. .pp DDT-8000 displays an error message if the value stored in memory cannot be read back successfully. This error indicates a faulty or nonexistent RAM location. .sp 2 .sh .tc 8.2.11 The T (Trace) Command 8.2.11 The T (Trace) Command .qs .ix T (Trace) command (DDT-8000) .pp The T command traces program execution for 1 to 0FFFFFFFFH program steps. The forms are .ix program execution, tracing of .sp .nf .in 8 T Tn .in 0 .fi .sp where n is the number of instructions to execute before returning control to the console. .pp After DDT-8000 traces each instruction, it displays the current CPU state and the disassembled instruction in the same form as the X command display. .pp Control transfers to the program under test at the address indicated in the PC. If n is not specified, one instruction is executed. Otherwise, DDT-8000 executes n instructions and displays the CPU state before each step. You can abort a long trace before all the steps have been executed by typing any character at the console. .pp After a Trace (T) command, the list address used in the L command is set to the address of the next instruction to be executed. .pp Note that DDT-8000 does not trace through a BDOS interrupt instruction, since DDT-8000 itself makes BDOS calls and the BDOS is not reentrant. Instead, the entire sequence of instructions from the BDOS interrupt through the return from BDOS is treated as one traced instruction. .sp 2 .tc 8.2.12 The U (Untrace) Command .sh 8.2.12 The U (Untrace) Command .qs .ix U (Untrace) command (DDT-8000) .pp The U command is identical to the Trace (T) command except that the CPU state is displayed only after the last instruction is executed, rather than after every step. The forms are .sp .nf .in 8 U Un .in 0 .fi .sp where n is the number of instructions to execute before control returns to the console. You can abort the Untrace (U) command before all the steps have been executed by typing any key at the console. .sp 2 .ne 10 .sh .tc 8.2.13 The V (Value) Command 8.2.13 The V (Value) Command .qs .ix V (Value) command (DDT-8000) .pp The V command displays information about the last file loaded with the Load For Execution (E) or Read (R) commands. The form is .sp .ti 8 V .pp If the last file was loaded with the E command, the V command displays the starting address and length of each of the segments contained in the file, the base page pointer, and the initial stack pointer. The format of the display is .sp 2 .ti 3 Text base=00000500 data base=00000B72 bss base=00003FDA .ti 3 text length=00000672 data length=00003468 bss length=0000A1B0 .ti 3 base page address=00000400 initial stack pointer=000066D4 .sp 2 If no file has been loaded, DDT-8000 responds to the V command with a question mark (?). .sp 2 .sh .tc 8.2.14 The W (Write) Command 8.2.14 The W (Write) Command .qs .ix W (Write) command (DDT-8000) .pp The W command writes the contents of a contiguous block of memory to disk. The forms are .sp .ti 8 W .br .ti 8 W,s,f .sp The is the file specification of the disk file that receives the data. The letters s and f are the first and last addresses of the block to be written. If f does not specify the last address, DDT-8000 uses the same value that was used for s. .pp If the first form is used, DDT-8000 assumes the values for s and f from the last file read with a R command. If no file is read by an R command, DDT-8000 responds with a question mark (?). This form is useful for writing out files after patches have been installed, assuming the overall length of the file is unchanged. .pp If the file specified in the W command already exists on disk, DDT-8000 deletes the existing file before it writes the new file. .sp 2 .sh .tc 8.2.15 The X (Examine CPU State) Command 8.2.15 The X (Examine CPU State) Command .qs .ix X (Examine CPU State) command (DDT-8000) .ix CPU, state of .mb 5 .fm 1 .pp The X command displays the entire state of the CPU, including the program counter (PC), user stack pointer (usp), system stack pointer (ssp), status register (by field), all eight data registers, all eight address registers, and the disassembled instruction at the memory address currently in the PC. The forms are .sp 2 .nf .in 8 X Xr .in 0 .fi .sp 2 where r is one of the following registers: .mb 6 .fm 2 .sp 2 .ti 8 D0-D7, A0 to A7, PC, USP, or SSP .sp 2 .in 0 The first form displays the CPU state as follows: .sp 2 .ti 8 PC=00016000 USP=00001000 SSP=00002000 ST=FFFF=> (etc.) .ti 8 D 00001000 00000D01 ... 00000001 .ti 8 A 000B0A00 000A0010 ... 00000000 .ti 8 lea $16028,A0 .sp 2 The first line includes: .sp 2 .ti 8 PC Program Counter .ti 8 USP User Stack Pointer .ti 8 SSP System Stack Pointer .ti 8 ST Status Register .ix program counter .ix user stack pointer .ix system stack pointer .ix status register .sp 2 Following the Status Register contents on the first display line, the values of each bit in the status register are displayed. A sample is shown below: .sp 2 .ti 8 TR SUP IM=7 EXT NEG ZER OFL CRY .sp 2 This sample display includes: .sp 2 .nf TR Trace Bit SUP Supervisor Mode Bit IM=7 Interrupt Mask=7 EXT Extend NEG Negative ZER Zero OFL Overflow CRY Carry .fi .sp .pp The second form, Xr, allows you to change the value in the registers of the program being tested. The r denotes the register. DDT-8000 responds by displaying the current contents of the register, leaving the cursor on that line. If you type a RETURN, the value is not changed. If you type a new valid value and a RETURN, the register is changed to the new value. The contents of all registers except the Status Register can be changed. .sp 2 .he CP/M-8000 Programmer's Guide 8.3 Assembly Language Syntax .sh .tc 8.3 Assembly Language Syntax for A and L Commands 8.3 Assembly Language Syntax for the L Command .qs .ix L command (DDT-8000) .pp In general, the syntax of the assembly language statements used in the L command is standard Zilog Z8000 assembly language. Several minor exceptions are listed below. .sp .in 5 .ti -2 o DDT-8000 prints all numeric values in hexadecimal. .ti -2 o DDT-8000 uses lower-case mnemonics. .ti -2 o DDT-8000 assumes word operations unless a byte or longword specification is explicitly stated. .sp 2 .ce End of Section 8 .bp .he CP/M-8000 Programmer's Guide End of Section 8 .sp 50 .nx appa