DCON DOCUMENTATION
==================
ver 1.1
updated
08/27/81 by "R"
--"Who was that Masked Man?"
--"Didn't he write Sex & the Single Guy?"
--"Naw, he was one of the President's Men".
--------------------------
Version 1.1 update:
Several bugs have been repaired in version 1.1, along with
the addition of a couple of new features, and some minor changes
in display formatting.
1) An index register initialization error has been corrected.
Under certain circumstances, this caused a random write
into (usually) low memory when the program was first loaded.
2) A bug in the expression analyzer has been corrected. This
caused an error whenever a quoted character was used within
an expression. For example, the command: H'A' under 1.0
would cause an error message. The 'A' will now be inter-
preted as its correct hex value.
3) An error in the relocation logic caused DCON to relocate
itself 2K lower in memory than necessary. This has been
corrected, resulting in an additional 2K of memory space
for debugging programs.
4) A CPU ID test is made before the program begins relocating.
If it is determined that the CPU is not a Z80, an error
message is printed, and control returns to CP/M.
5) A new load option has been added to enable the user to specify
the execution address of DCON. This is done by appending a
specifier option of the form ":=
" to the command
line (this must be the last item on the command line). If
is omitted, DCON will relocate to just below the
CCP. Examples:
A>DCON :=5000 ;relocate DCON to 5000, no other args
A>DCON MYPROG := ;load MYPROG, reloc to just under CCP
A>DCON FOO.COM FOO.SYM :=7D00 ;load FOO.COM and FOO.SYM,
;reloc DCON to 7D00H
In no case will ":=" be interpreted as a file to load. Also,
must be be on a page boundary, or the message:
++ Reloc Ignored ++
will be printed, and DCON will load as if no relocation
had been specified.
DCON will acknowledge the relocation by printing a "*" char-
acter in the sign-on after its name.
NOTE: DCON is not designed to operate above the TPA. Un-
predictable operation may result if DCON is loaded outside
the TPA.
--------------------------
Documentation for version 1.0:
DCON is a new debugger for the CP/M series of operating systems. This
document is an attempt to explain DCON's operation, and differences that
exist between it and SID and ZSID (DCON's mother and father, respectively).
For proper understanding of this document, you'll need a copy of the SID
User's Manual; this document explains only the added features and commands.
A) Overview
===========
DCON is a direct descendent of SID and ZSID, two debuggers for the 8080/Z80
family, from Digital Research. DCON's powers are a superset of those debuggers.
It's command set retains upward compatibility with these debuggers with a
few exceptions, detailed under "Upgraded Features".
DCON's extended features include a more powerful expression evaluator, a
"search" facility with wildcards, a "verify" command, Z80 instructions,
settable display modes, I/O port access, CP/M2 "USER" support, and more
powerful use of previously available facilites.
Note that DCON is NOT public domain! Much of the code is proprietary to
Digital Research. Hence, DCON should only be distributed to LEGAL owners
of SID and ZSID.
B) Upgraded Features
====================
The following features of SID and ZSID have been extended/changed:
1) The "/" symbolic operator (for "qualified symbols") has been
changed to "%" in order to accomodate the use of "/" as the
division operator in mathematical expressions.
2) The "D" command format retains the structure of that used with
SID (16 bytes of hex dump followed by 16 ascii characters).
ZSID's rather clumsy "ascii-under-the-hex" format has been
eliminated.
3) The assembler/disassembler module is compatible with neither
(see next section).
4) A bug that existed in ZSID through at least version 1.4 has
been corrected. Specifically, this bug caused improper operation
when tracing relative jumps (sign bit of the argument byte was
improperly added to the program counter).
5) The stack-reference operator has been changed from the circumflex
character ("^") to the dollar sign ("$") in order to accomodate
the input radix specifier. (The stack operator was an undocumented
feature of SID 1.4 -- see under "Expression Evaluator")
6) The "List Symbols" command ("H" with no arguments) now places
four symbols on a line.
7) The "M" (move memory) command has been extended to allow over-
lapping areas of memory to be moved.
8) The "S" command will now "back up"; if you enter a "-" character
(must be on the line by itself), the "S" pointer will be decremented
and the previous location will be opened.
B) Z80 operation
================
The debugger has been upgraded to allow interpretation of Z80 opcodes.
The format used for the assembler/disassembler module is that used by
the TDL/XITAN/CDL/PASM series of assemblers, with one change:the index
regesters are referenced by "[+offset]" rather than the
"offset()" used by these assemblers. For example, loading reg.
B from index register "X" offset by 6 would be "MOV B,[IX+06]" rather
than "MOV B,6(X)", as it would be with the TDL series assemblers. Note
that the leading zero in the offset constant is required.
All Z80 instructions are understood by the trace commands, "T" and "U".
Further, the Z80 registers are displayed in a two-line format, with the
8080 subset on the first line. This is similar to ZSID's display, except
that the second line (Z80-specific registers only) can be disabled under
command control (see under "New Commands").
I may someday add a ZILOG format assembler/disassembler module.
C) Expression evaluator
=======================
The expression evaluator has been significantly upgraded to allow
new operations:
1) The multiplication ("*") and division ("/") operators
are now allowed in any expression. Their precedence
is one level higher than addition and subtraction.
2) The precedence of operations may be changed by using
parentheses. For example, 2*3+4 will evaluate to 10,
whereas 2*(3+4) will result in 14.
3) The indirect-word operator "@" has been extended to
include the entire expression to the right of the op-
erator; this operator formerly had effect only on sym-
bols. For example, if location 5 contains a jump to
0DC06H, the command "D6" will display memory from loc.
6 onward, where "D@6" will display starting at DC06H.
4) The indirect-byte operator has been similarly extended.
5) The radix may be specified ahead of a numeric constant
using the "^" operator. For example, "^H40"
can be used to specify hexadecimal 40, "^D40" will spec-
ify decimal 40, and "^B0101" specifies binary 0101 (dec-
imal 5). Note that the "#" prefix is retained as a
decimal specifer. Also, if no modifier is present,
hex is assumed.
6) The stack may be referenced within an expression with
the "$" symbol, which will retrieve stack items one level
deep for each occurence of the symbol. For example, sup-
pose the stack contains the following: 0D30H, 7206H,
6903H. Then "D$" will display starting at 0D30H, "G$$+1"
will transfer control to location 7207H, and "H$$$" will
display 6903H. This was an undocumented feature of SID
version 1.4 (the symbol was "^").
D) New Commands
===============
The following new commands have been added:
1) QUERY ("Q"): this is used to "query" I/O ports. The formats are:
a. QIp - query inport port p, where p is any expression
evaluating to 255 or less.
b. QI - query the last input port accessed with the "QI"
command. DCON's response is "pp=vv", where "pp"
is the port number referenced. This is to remind
you of the last port number accessed. Note that
if no port has been previously accessed, port #0
is assumed.
c. QOp,v - send the value "v" out to port # p
2) VERIFY ("V"): used to compare memory blocks. The format is
Vs,e,d
where s is the source address, e is the end of the source block,
and d is the destination block to be compared to the source.
If the two blocks match exactly, DCON will simply return to
command level. Otherwise a list of the diffences will be printed.
3) SEARCH ("Y"): used to search for a string of up to 16 bytes/chars.
The formats used are:
YBs,e - set "s" as the search lower boundary, and "e"
as the upper. Only this area will be searched.
These value are initially set to include the entire
TPA.
Y - specifies the string to search for. This
can be a quoted string, as "Yfoobar". It can also
be made up of an expression list; for example,
YC3,04,02,'B',#213,^B010101101. Strings and expr-
essions can be intermixed. The "?" character can
be used to specify a wild-card (matches anything).
Note that lower-to-upper case translation is
suppressed within quoted strings.
YW - as above, except expressions are interp-
reted as word values (quoted strings are still
considered bytes.
Y - Find next occurence of previous search string.
In general, Y will find the first occurence of the
search string, and display the matched string for a length of 16
bytes using the format of the "D" command. To find subsequent
occurences, use more "Y" commands without arguments. When no reply
is given, the search area contains no more occurences of the string.
A subsequent "Y" will reset the search parameters to the beginning
of the search area (i.e., the search will start over).
The special forms "-Y" and "-Y" will suppress
printing of the ascii equivalent of the found search string.
The search string is not modified by the "YB" form.
Some examples should illustrate the power of the search command:
-- Y300,.TOPMEM sets search area to start at 300H and end at
the value of the symbol .TOPMEM.
-- YCD,?,?,"ZOT",CD,?,?,C3 will search for any call instruction
(CD) followed by the string "ZOT", followed by another call
instruction, followed by a jump instruction.
-- YW.IFMAP,CD03,.GETCH,"bop",0FD3 will search for the WORDS
.IFMAP, hex CD03, symbol .GETCH, string "bop", hex 0FD3.
-- YDB,?,E6,?,C2 will search for an input routine of the form
IN , ANI , jump not-zero.
4) NEXT (N): the N command allows convenient re-display of the
loaded program/symbol parameters, "NEXT PC END".
5) VERSION (Z): displays the DCON version number
6) Extended commands: there are (currently) two "extended" commands,
prefixed by the letter "E".
a. USER ("EU"): changes/queries the CP/M 2.x user number.
(not available under CPM 1.4 and 1.3). The format is
EUn where n is the DECIMAL CONSTANT to set the user
number to. If n is omitted, the current user number will
be displayed.
b. MODE ("EM"): there are (currently) two display modes
supported - register display and trace display.
The register display is normally two lines of registers,
with the 8080 subset on the first line, the Z80 primes and
index registers on the second line, followed by the PC
and disassembled instruction. The command "EMR" can be
used to toggle between this format and an abbreviated
format consisting of only the 8080 register subset and
the PC with disassembled instruction.
Trace mode refers to WHEN the registers are displayed
during tracing. The default condition for tracing is
1) display the registers
2) trace the instruction
3) print *PC
4) return to DCON command level
The disadvantage of this is that you can never see the
instruction that's about to be traced without using the
"L" (list) command. By using the command, "EMT", you
can toggle between this "normal" mode, and a mode where
the following sequence occurs:
1) trace the instruction
2) print *PC
3) display updated registers.
4) return to DCON command level
In this way, you always see the instruction that's about
to be executed, rather than one that has already been
executed.
"EM" without arguments displays the current modes.
Note also that these modes may be set up as defaults by
patching the byte at location 204H as follows:
X X X X X X X X
7 6 5 4 3 2 1 0
\ / | |
\ / | |
unused | .--> 0= full reg display
bits | 1= 8080 subset only
|
.----> 0= display before tracing
1= display after tracing
then re-saving the program (length is 39 CP/M pages,
so use SAVE 39 DCON.COM
In practice, I've found that the new trace mode takes some
getting used to, but after my initial "break-in" period, I
never use the old mode.
E) Miscellaneous Notes
======================
A couple of undocumented (and relatively useless) options to commands
existed under SID and ZSID version 1.4, and have been retained in DCON
for no particular reason.
1) -L removes the assembler/disassembler module from the program.
This is not reflected in the location at BDOS+1. This also
happens whenever the assembler/disassembler module is overlaid
with a user program.
2) -D suppresses the ascii portion of "D" lines.
F) Commants, Suggestion, Bug Fixes
====-=============================
Comments and suggestions from remote CP/M operators and other SID/ZSID
users/owners are welcomed. I must, however, maintain my anonymity.
Therefore, please address all comments to "BUG-DCON" on the Clearinghouse
system (I'm not the Sysop there, but I do check in there frequently).
Include this name in both the "TO" field and the "SUBJECT" field, so I
can find it easily.
"R"
08/18/81
.
Include this name in both the "TO" field and the "SUBJECT" field, so I
can find it easily.
"R"
08/18/81