DDT


ABSTRACT:
	THE VERSION OF DDT PROVIDED BY DECUS HAS BEEN REWORKED
INTO SOMETHING A LITTLE CLOSER TO THE NEEDS OF THE SLSI GROUP.
THE OPERATOR INTERACTION HAS BEEN CHANGED; DDT NOW PROMPTS AND
A CARRIAGE RETURN IS REQUIRED AS A TYPE-IN TERMINATOR.  AN
AUTOMATIC, INVISIBLE START MODE HAS BEEN ADDED.  (THIS ALLOWS
USE OF THE DDT ERROR TRAP FUNCTIONS.)  THE CONDITIONAL
ASSEMBLY FEATURES FOR "NON-STANDARD" I/O AND OPERATING SYSTEMS
OTHER THAN RSX-11M SHOULD STILL WORK.  OUR VERSION IS CONFIG-
URED TO USE LUN 5 FOR OPERATOR COMMUNICATION (THE FORTRAN IV
PLUS DEFAULT UNDER RSX-11M) USING QIOW'S AND EVENT FLAGS 20.
AND 21.  THE REMAINDER OF THIS ABSTRACT DESCRIBES THE VERSION
RECEIVED FROM DECUS.
	A VERSION OF DDT, A POWERFUL SYMBOLIC DEBUGGER, IS
PROVIDED THAT MAY BE ASSEMBLED CONDITIONALLY TO RUN UNDER RSX11D
OR RSX11M,DOS-11, OR STAND-ALONE (INCLUDING WITH RT11).
	THIS IS REWORKED FROM THE STAND-ALONE ORIGINAL DDT-11 OF
STEVEN RUBIN OF CMU AND HAS SEVERAL ADDITIONAL
FEATURES PLUS CONDITIONALS FOR USE WITH A VARIETY OF DEC OPERATING
SYSTEMS.
	THE RSX VERSION MAY BE ASSEMBLED TO DO ALL ITS I/O THROUGH
THE NORMAL CONSOLE HANDLER, OR MAY BE BUILT WITH ACCESS TO THE
CONSOLE HARDWARE REGISTERS TO DO ITS OWN I/O INDEPENDENT OF THE
OPERATING SYSTEM. BOTH THE DOS-11 AND RSX-11 VERSIONS KNOW THE
START ADDRESS OF THE PROGRAMS THEY ARE LINKED WITH, AND MAY START
THEM WITH A SIMPLE <ALTMODE>G. CONSOLE DIALOGUE CLOSELY RESEMBLES
PDP-10 DDT.


	In the following, the dollar sign ($) refers to an ALTMODE
	or ESCAPE character (depending on your console), and not a
	dollar sign. It is used to conform to the usual TECO
	or RSX notation and for brevity.  <BS> refers to a 
	BACKSPACE.  <RO> refers to a RUBOUT or DELETE character,
	depending on your console.

	DDT/11 - Dynamic Debugging Technique on the PDP-11

RSX-11M I/O limitations have forced some changes in operator
interaction.  First, DDT now prompts.  The default prompt is
DDT> .  This can, however, be changed to any ASCII string of
seven or fewer characters, including the >.  (This should 
facilitate the simultaneous debugging of interacting tasks.)
The start of the ASCII prompt string is DDTPRS.  The number
of characters in the string is in DDTPRL.  Both of these
locations have been defined as globals (for disk patching) and
both are in the permanent DDT symbol table (for using DDT to
patch its own prompt).
Second, almost all DDT type-in now requires the use of a 
CARRIAGE RETURN as an input terminator.  This signals the
program that the type-in is complete.  The BACKSPACE, RUBOUT,
and LINEFEED commands are the only ones which do not require
the use of this terminator.
Each  command in DDT/11  is identical to the  PDP-10 version whenever
possible.   In some cases,  DDT/10 commands have been  omitted in the
interest  of saving core and  making good sense.  The  following is a
list of the DDT/11 commands:
<RO>	Kill current command (if any), terminate the type-in, and
	return to the DDT command level.  This is echoed as XXX.
	NOTE: if a <CR> is typed by itself (i.e., a terminator
	which marks the end of no type-in at all) it is processed
	as an <RO>.
 n/	Open word n.  Type contents in current mode
  /	Open word pointed to by last typed value
 n<BS>	Modify currently open word to be n.  Close word.  Does not 
	require a <CR> terminator
 n<LF>	Modify, close, open next word.  Does not require a <CR>
	terminator.
 n^	Modify, close, open previous word
 n<TAB>	Modify, close, open word pointed to by last typed address
 n\	Modify, close, examine word n
  \	Examine word pointed to by last typed value
n?	Type word n in RAD50 format.  (forces even address)
@	Types out location absolutely addressed by open location.
	(Same as TAB, and same as ODT convention on PDP-11.)
  $S	Change current mode to instruction type out
  $A	Addresses will be typed as absolute numbers
  $R	Addresses will be typed relative to symbols
  $C	Change current mode to numeric type out
 $nR	Change current radix for $C to n (n read in decimal)
  $T	Change current mode to ASCII text output
 $5T	Change current mode to Radix-50 text output
 $nO	Change current mode to n bit byte typeout
  $H	Change to halfword (byte) mode (reset by $5T and $S)
	Note that the initial modes are $S and $8R.  These can be
	temporarily changed by the above commands and will return
	to the permanent setting by a carriage return.  The settings
	can be permanently changed by using two altmodes before the
	mode setting command ($$T sets permanent ASCII mode)
 n[	Open location n, type as a numeric
 n]	Open location n, type as instruction
 n!	Open location n, do not type value
  ;	Retype currently open word
  =	Retype currently open word as number
 n=	Type value of n as a number
  _	Retype currently open word as instruction
 $_	Retype currently open word symbolically
  i$X	Execute instruction i (cannot execute branches or jumps)
  n$G	Start executing program at location n.  Default is to
	start executing at address in JOBSA (start of program)
  v$nB	Set breakpoint n at address v (n from 1 to 8 or can be omitted)
a,v$nB	Same as above but open address a at breakpoint
	If two altmodes are used, automatic proceeding is enabled.  The
	breakpoint will cause the message to be typed and the program
	resumed.  If you type a character, the automatic proceeding will stop.
  0$nB	Remove breakpoint n
   $B	Remove all breakpoints
   $P	Proceed from breakpoint
  n$P	Proceed from breakpoint n times (without halting)
	If two altmodes are used, the breakpoint will be proceeded from
	automatically.  WARNING: the automatic proceed cannot be
	stopped.  Another breakpoint must be set to stop the
	program, or it will "run away" until it exits.
  n$UW	Set offset limit to n (used when typing addresses)
   $1UT	Turn on single stepping (break at each instruction)
	NOTE: single stepping merely causes a breakpoint to always be
	generated for the next instruction.  The $P command is used
	to move to the next instruction.
  a$1UT	Turn on single stepping and open location a at each break
	If two altmodes are used, the single stepping will be done
	automatically.  WARNING: See the note on automatic proceeding
	above.
   $UT	Turn off single stepping
  a:	Make current location have symbolic name a
v<a:	Make symbolic name a have value v
  a$$K	Delete symbolic name a
  a$K	Delete symbolic name a from typeout only
   $D	Perform an $K on the last symbol coloned (:)
l<u$$Z	Zero memory from l to u ;location D.FILV (which is defined in
	DDT's permanent symbol table) contains the number filled in
  n$M	Set mask for searches (below) to n
l<u>s$W	Search core from l to u for word s.
l<u>s$E	Search core from l to u for effective address s.
l<u>s$N	Search core from l to u for word not equal to s.
 <CALL>	Soft restart at address 1004 (Graphics DDT only; not SLSI.)
   $UG	Turn on user display when in DDT (Graphics DDT only; not SLSI.)




Note that arguments can be any combination of the following:

	<Octal number>
	<Decimal number> .
	<Program symbol>
	" <Delimeter> <Two ASCII Characters> <Delimeter>
	"$ <Delimeter> <Three Radix-50 Characters> <Delimeter>
	<Instruction>

The operators +  (addition), - (subtraction), * (multiplication), and
' (division) are evaluated  from left to right unless parentheses are
included.  The space is treated like a plus except after instructions
where it is merely a  separator.   All input is  accepted in lower or
upper case and is folded (except for text.)

If you  are not  in DDT,  you can  re-enter with  a Meta-BREAK  on  a
graphics or  a restart  at DDT  (location typed  out initially).


The DDT permanent symbol tables contain all PDP-11 instruction
mnemonics.  The following are also pre-defined:

 R0-R5	are the user registers.  R1/ would open register 1.
 SP	is the user's stack pointer
 PC	is the user's program counter
 $I	is the user status
 $2I	is the status of DDT
 $M	is the mask for searches
 $Q	is the value at the current address
 $V	is the value at the current address with the bytes switched
 $nB	is the address of breakpoint n
 JOBSA	is the DDT location which contains the starting address of
	your program.  If you are running in RSX, your task name is
	dynamically entered at DDT startup into this table.  It will
	be an alias for JOBSA.
RSXEXT is the address of the RSX-11M or RSX-11D EXIT$S call.  To
	bail out, type RSXEXT$G
BYE	is another name for RSXEXT and has the same meaning.
DOS	is the address of the DOS exit call (DOS DDT ONLY).
DDTODD	is DDT odd address SST table entry (RSX DDT ONLY)
DDTIOT	is DDT IOT SST table entry
DDTTRP	is DDT SST table trap entry
DDTRES	is DDT SST table reserved instruction entry
DDTEMT	is DDT SST table non-RSX EMT entry
DDTMPR	is DDT SST table memory protect violation entry
NOTE: The appropriate trap vector will be disabled if its SST
	table entry location is set to 0.  The trap may also be
	set to a user routine by setting the appropriate table vector
	to the address of that routine.
$DSW	is the user's directive status word
D.FILV	is the number filled in by the $Z command (initially 0)
DDTPRS	is the start of the DDT prompt string (SLSI only)
DDTPRL	is the number of characters in the prompt string (7 or fewer).
D.INM1	is the typeout mode.  It can be used to suppress absolute
	addresses in search typeouts, allowing pseudo-assembly
	listings to be generated.
  .	represents the current location.  Thus .$1B puts
	breakpoint 1 at the currently opened location.
UP TO 160. USER SYMBOLS MAY BE ENTERED.


HANDY HINTS:
Remember, to start your program at its normal start address, type
$G.  To exit back to RSX-11, type BYE$G.  Due to the nature of
the terminal I/O, long pauses in the middle of command type-in are
discouraged.  DDT is in a wait state until the first character
is typed in response to the prompt.  It removes itself from
this state when the first reply character is echoed.  Pauses in the
middle of type-in may hang other users.  

TRAPS:
When DDT itself is executing, the ;ILG! trap may occur.  This
indicates a pathological error condition within DDT.  Crash reports
will be appreciated.
When  your program is  executing, the following  unexpected traps may
occur.  
;ODD!	Odd address or non-existent memory
;MPR!	Memory protection violation
;BPT!	Unexpected breakpoint encountered
;IOT!	IOT trap executed
;RES!	Reserved instruction attempted
;EMT!	Non-RSX EMT trap
;TRP!	Trap instruction executed
;FPP!	Floating-point processor trap
Once an MPR or RES trap has been executed, you may not give a
$P command.  It is, however, legal after the other traps.

TKB:
To use DDT, you must, of course, task build it in.  The following
discussion is for using the standard SLSI version, which is
[240,1]DDTLU5.OBJ .  This module must be in your input module list,
or, if ODL is being used, in your root.  The DA switch must be appended
to it ([240,1]DDTLU5/DA) and the DA switch must NOT appear anywhere
else in either your input or your output streams.  Several potentially
useful global symbols within DDT will appear on your load map.
DDTPRS and DDTPRL (see above) are the prompt string location and
character length.  These may be modified by ZAP.  D.LURK is a
switch which may be used to drive DDT in invisible automatic start
mode.  This switch is assembled as a 0.  It may be ZAPped to a non-0,
in which case DDT will suppress its initial typeout and execute
an automatic $G, starting the user task.  Since DDT has
been used (although invisibly), its traps will be set.

MODIFYING DDT
DDT has been designed for easy modification.  Conditional assembly
modules are invoked for different operating systems, terminals,
and I/O schemes.  [240,1] on MICRO II contains source for DDT as
well as its object module.  DDTASM.CMD is a command file to assemble
the standard SLSI version of DDT.  DDTPRE.MAC is a precursor
file which sets conditional assembly variables and the I/O
LUNs and event flags.  DDTAPP.MAC is the actual source for DDT.
If you wish to create a non-standard version, please copy these files
from [240,1] to some other UFD and change the names of any files you
modify.  Do NOT use DDTLU5 as the name of your object file.  The
confusion you save may be your own!
The APPLICON changes have been made for RSX11M.  Most of them are
conditionally assembled if the generated keyword RSX11M is defined.
The RSX-11D code has been left as untouched as possible.  Many of the
APPLICON changes were made to fit an RSX environment; I suspect
that any RSX-11D users might need them,too.  Any such users
would be well advised to look at the code assembled if RSX11M is defined
and change any code common to both RSX's to conditionally assemble if
$$RSX is defined.
Feedback from other users or potential users is welcome.  Please direct
this to:	Fred Isaacs	PHONE: 617-272-7070, x339
		SLSI Group
		Engineering Department
		Applicon, Inc.
		154 Middlesex Turnpike
		Burlington,
		MA	01803


The following additional documentation was received from DECUS
with the original, unmodified program.  Since we have had no need
to use any version other than the SLSI standard one, the other
conditional assembly options have not been tested.  However,
they should work.


	TO USE DDT, LINK YOUR PROGRAM WITH IT USING TKB (OR LINK-11
FOR THE DOS VERSION). DDT HAS THE ABILITY TO REMEMBER UP TO 160
SYMBOLS (MORE BY CHANGING THE .REPT 160. COUNT AT THE END OF DDT),
ALL OF WHICH MAY BE ENTERED FROM THE CONSOLE. DDT SHOULD BE
INCLUDED IN THE INPUT FILE LIST WITH THE /DA SWITCH FOR TKB
OR WITH THE /OD SWITCH WITH LINK-11.  THE TASK BUILD WITH DDT MAY BE
OF TWO TYPES, DEPENDING ON WHETHER THE CONDITIONAL ASSEMBLY PARAMETER
XTCOM IS DEFINED.
	TYPE 1 IS THE NORMAL RSX DDT, USING THE TT HANDLER TO DO I/O
AND USING LUN 6 FOR INPUT WITH EVENT FLAG 23. AND LUN 5 FOR OUTPUT, WITH
EVENT FLAG 22. YOU MUST HAVE AN ASSIGN DIRECTIVE AT TKB TIME TO ASSIGN
THESE LUNS TO TI: (OR WHEREVER...) OR DDT WILL NOT WORK. I/O IS VIA
QIO$ AND IS SO DONE THAT IT SHOULD WORK EVEN FOR RSX11M. AN <ALTMODE>G
(REPRESENTED HEREIN AS $G) WILL START THE TASK AT ITS NORMAL ADDRESS.
	TYPE 2 IS A DDT OBTAINED BY ASSEMBLING DDT WITH $$RSX AND XTCOM
DEFINED. IN THAT CASE, DDT MUST BE BUILT WITH A COMMON IN THE EXTERNAL PAGE
(I.E., WITH PAR=$$$EXT FOR RSX11D) AND THE SOURCE MUST HAVE THE DEFINITIONS
OF D.RCSR, D.RDB, D.TCSR, AND D.TDB SET UP AS THE ADDRESSES OF THE
TELETYPE (TERMINAL) DEVICE REGISTERS IN THE PLACE WHERE THEY APPEAR
IN DDT ADDRESS SPACE WHEN TASKBUILT. DDT WILL THEN DO ALL ITS I/O
THROUGH THAT COMMON IN NON-INTERRUPT MODE AND NOT REQUIRE THE
CONSOLE HANDLER. IT WILL HOWEVER BE IN CONTINUOUS EXECUTION THEN,
AND SO SUCH TASKS MUST BE BUILT TO RUN AT FAIRLY LOW PRIORITY
TO AVOID LOCKING OUT OTHER SYSTEM ACTIVITIES.
	TYPE 2 IS ESPECIALLY USEFUL FOR DEBUGGING DEVICE HANDLERS
OR THE EXECUTIVE.
	A FINAL NOTE: DDT DOES NOT PROMPT ANYTHING WHILE AWAITING INPUT.
JUST TYPE TO IT; IT WILL RESPOND. FURTHER, D.KSR SHOULD BE DEFINED (AS IT
PRESENTLY IS) IN THE SOURCE. THE OTHER CONDITIONALS ARE FROM STEVE
RUBIN'S ORIGINAL STAND-ALONE DDT AND ARE IRRELEVANT TO DOS, RSX, RT11,
OR NORMAL STAND-ALONE USE.

	TASK-BUILD EXAMPLES:
1. DDT WITH TT HANDLER

MCR>TKB
TKB>FOO=FOO,DDT/DA
TKB>/
ENTER OPTIONS:
TKB>TASK=...FOO
TKB>ASG=TI:5:6
TKB>//

2. DDT WITH EXTERNAL PAGE COMMON

MCR>TKB
TKB>FOO=FOO,DDT/DA
TKB>/
ENTER OPTIONS:
TKB>TASK=...FOO
TKB>PRI=5
TKB>LIBR=EXTPAG:RW
TKB>//

	LINK EXAMPLES (DOS-11 VERSION)
$R LINK

LINK V02-02C
#FOO<FOO,DDT/OD/E
#^C
.KI
$GE FOO
$OD
  DDT EXECUTION, RESTART= 122222



	DDT CONDITIONS
D.KSR	DEFINE ALWAYS; SETS TTY MODE I/O
TTYASR	DEFINE FOR DIRECT DDT CONTROL OF NON-CONSOLE TTY
$$DOS	DEFINE FOR DOS-11 DDT
$$RSX	DEFINE FOR ALL RSX DDT'S (11-M OR 11-D).
$RSXM	DEFINE IF RSX11M ON MACHINE WITHOUT RTT
$RSXMM	DEFINE IF RSX11M ON MACHINE WITH RTT
XTCOM	DEFINE WHERE DDT IS TO OPERATE DIRECTLY ON TTY HARDWARE.
	(OTHERWISE USES LUNS 5 AND 6, EVENT FLAGS 22 AND 23.)

