.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<filename>
.sp
where <filename> 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<command tail>
.bp
where <command tail> 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 <command tail> are also copied to the default
command buffer at 0080H.  The length of the <command tail> 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<filename>
.sp
where <filename> 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<filename>
.br
.ti 8
W<filename>,s,f
.sp
The <filename> 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


