.;
.;   Please use BONNER LAB RUNOFF on this document.
.;
.PAGE SIZE 58,70,10

.AUTOBREAK "-"
.NO AUTOHYPHENATE
.AUTOPARAGRAPH
.NO AUTOTITLE
.NO FLAGS
.STYLE HEADERS 6
.TAB STOPS +8,+8,+8,+8,+8,+8,+8
.TITLE DBG Assembly Level Debugger V1.8

.CHAPTER Introduction
.SUBTITLE Introduction

 DBG is a symbolic debugging tool for user mode programs running under
RSX-11M-PLUS (it won't work under M until sending the task region by reference
is allowed). It was written because DEC failed to include air sickness bags
with ODT. DBG has the following general features:

.LIST "o"
.LIST ELEMENT Symbolic instruction display.
.LIST ELEMENT Memory and register display and modification.
.LIST ELEMENT Program control via breakpoints, tracepoints, watchpoints
and single stepping.
.LIST ELEMENT Instruction profiling and history.
.LIST ELEMENT Ability to debug I/D space tasks.
.LIST ELEMENT Ability to accept commands from a command file, and write
commands and output to a log file.
.END LIST

 There are many desirable features which DBG does not provide, including:

.LIST
.LIST ELEMENT DBG is NOT a source language debugger.
.LIST ELEMENT DBG does NOT know the types of data objects.
.LIST ELEMENT DBG can NOT differentiate between I space and D space symbols
in an I/D space task.
.LIST ELEMENT DBG does NOT provide support for debugging overlaid programs.
.LIST ELEMENT DBG can NOT debug supervisor mode libraries.
.LIST ELEMENT DBG does NOT provide support for dealing with floating point
instructions and registers.
.LIST ELEMENT DBG does NOT provide a screen-oriented user interface.
.LIST ELEMENT DBG does NOT come with a known bug list. I'm sure there are
bugs here, but I don't know where they are.
.LIST ELEMENT DBG does NOT come with any guarantees, express or implied.
I have had good luck in using it, but I refuse any responsibility for the
results of any use, misuse, or abuse of this program.
.END LIST

.HEADER LEVEL 1 What DBG does

 To debug a program using DBG, the programmer includes an extra module in the
task image (DBGAID), and causes the task builder to create a symbol table file.
The programmer invokes the task in the normal manner, and then initiates DBG.
DBG prompts the programmer for commands and allows the programmer to examine
and modify memory and the CPU registers, and to control and profile task
execution.

 Breakpoints may be set in the task. Task execution will stop when a breakpoint
is reached; the instruction at that location will not yet have been executed.
Tracepoints are a lot like breakpoints, but they do not halt task execution.
You will simply be notified each time the task reaches the point in question.
Breakpoints and tracepoints are implemented by storing BPT instructions at the
specified points, so they can not be used on read only code (e.g. FCSRES).

 Watchpoints are used to detect erroneous data modifications. The target task
will be single stepped, and the watched location(s) will be examined after
every instruction. The task will be halted whenever the data changes. Only data
word watchpoints are provided (byte data is not supported). Because of the
implementation technique execution with watchpoints is very slow.

 When profiling is enabled a group of counters is created. Each counter
represents the execution of one or more instructions. The task is single
stepped, and every time an instruction that is represented by a counter is
executed that counter is incremented; this allows the measurement of the
instruction execution frequency within a task. The data acquired by profiling
can be used to aid in the optimization of program performance. A program
(PROFANAL.C) is provided to convert the instruction counter data to
instructions executed per module (areas separated by global symbols).

 When instruction history is enabled the task will be single stepped, and the
registers will be stored in the history buffer prior to the execution of each
instruction. The history buffer may be displayed as a list of instructions,
registers, or both.

.CHAPTER Expressions
.SUBTITLE Expressions

 DBG allows all addresses and numeric values to be expressions. A valid
expression may contain constants, symbols, and operators.

.HEADER LEVEL 1 Constants

 Constants may be numeric values, ASCII characters, or RAD50 characters.

.HEADER LEVEL 2 Numeric Constants

 Numeric constants may be in one of four radices: binary, octal, decimal, and
hexadecimal. By default, numeric constants are always processed in the current
default radix (initially octal, and controlled by the SET MODE command).
In addition, the default radix may be overridden through the use of the
temporary radix operators (^B, ^D, ^O, ^X), or by following a decimal value
with a period. The first digit of a hexadecimal constant must always be a
valid (decimal) digit, even if a temporary radix operator is used.

 The following examples assume the default radix is octal (default).

.LITERAL

   EXAMPLES:

	100	= 100 octal (64 decimal)
	100.	= 144 octal (100 decimal)
	^B100	= 4 octal (4 decimal)
	^X0D	= 15 octal (13 decimal)
	^XAF0	= Invalid (does not begin with 0-9)
.END LITERAL

.HEADER LEVEL 2 ASCII Constants

 ASCII constants may be either one or two characters long. Single ASCII
characters must be preceded by a single quote. Two characters following
a double quote will be packed into a 16-bit word; the first character
will be placed in the low byte.

.LITERAL

   EXAMPLES:

	'A	= 101 octal (65 decimal)
	"AA	= 40501 octal (16705 decimal)
	"AB	= 41101 octal (16961 decimal)
.END LITERAL

.HEADER LEVEL 2 RAD50 Constants

 RAD50 constants may be up to three characters long. The characters to be
converted to RAD50 must be preceded by a percent sign, or the RAD50 operator
(^R). If fewer than three characters are provided, the rightmost positions
in the word will be filled with RAD50 spaces (zeroes).

.LITERAL

   EXAMPLES:

	%ABC	= 3223 octal (1683 decimal)
	^RDEF	= 14716 octal (6606 decimal)
	%A	= 3100 octal (1600 decimal)
.END LITERAL

.HEADER LEVEL 1 Symbols

 Symbols are groups of characters which represent numeric values to DBG; they
may be created by the DEFINE and LOAD commands. Symbols may be composed of the
alphanumeric characters (A-Z and 0-9), the dollar sign ($) and period (.). A
symbol which begins with a digit will not be usable in expressions. Only the
first six characters in a symbol are significant. It is useful to note that all
C implementations (that I know of) for RSX convert an underscore (_) to a
period (.) for task building purposes.

.LITERAL

   EXAMPLES:

	ABC		OK
	$123		OK
	FILENAME	OK (but will be truncated to FILENA)
	E_ZT		Invalid (contains an underscore)
	1QZ		Not recommended (starts with digit)
.END LITERAL

 In addition, the following PDP-11 registers (and the directive status word)
may be referred to by name: R0, R1, R2, R3, R4, R5, SP, PC, PS, $DSW. These
special symbols refer to locations in the DBGAID module that contain the
register values.


.HEADER LEVEL 1 Operators

 DBG has several classes of operators: character, radix, monadic, and dyadic.
In addition, angle brackets (<>) may be used to enclose subexpressions, and
control the order of evaluation.

.HEADER LEVEL 2 Character Operators

 Character operators are used to convert characters to numeric values. The
single quote (') and double quote (") characters specify ASCII conversion, and
the percent sign (%) and RAD50 operator (^R) specify RAD50 conversion. For
examples of these operators see the sections on ASCII and RAD50 constants.

.HEADER LEVEL 2 Radix Operators

 Radix operators are used to temporarily control the conversion of digit
strings to numeric values. These operators cause the radix to be temporarily
set to binary (^B), octal (^O), decimal (^D) or hexadecimal (^X). These
operators are handled by the expression parser as monadic operators; they
normally apply only to the next digit string. If one of these operators is
used on a subexpression (i.e. one that is enclosed in angle brackets), then it
becomes the default radix for the subexpression. For examples of the use of
these operators, see the section on numeric constants.

.HEADER LEVEL 2 Monadic Operators

 Monadic operators take only a single argument. This argument may be a
constant, symbol, or subexpression enclosed in angle brackets. Monadic
operators are processed left to right before dyadic operators. The monadic
operators are the complementation operator (^C), the indirection operator (@),
and the negation operator (-).

 The complementation operator inverts all of the bits in its argument (it takes
the one's complement). The indirection operator fetches the data word specified
by its argument taken as an address. The negation operator produces the two's
complement of its argument.

.LITERAL

   EXAMPLES:

	^C<1>	= 177776 octal (65534 decimal)
	@R0	= contents of the word whose address is in
		  register R0.
	-1	= 177777 octal (65536 decimal)
.END LITERAL

.HEADER LEVEL 2 Dyadic Operators

 Dyadic operators take two arguments, which may be constants, symbols,
subexpressions, etc. These operators are evaluated from left to right. The
dyadic operators are add (+), subtract (-), multiply (*), divide (/), and (&),
and or (!).

.LITERAL

   EXAMPLES:

	1+2	= 4
	4-3	= 1
	5*6	= 36 octal (30 decimal)
	9./2	= 4 (note period after 9)
	5&6	= 4
	101!16	= 117 octal (79 decimal)
.END LITERAL

.CHAPTER Commands
.SUBTITLE Commands

 DBG has a number of commands, some of which are actually useful. All command
keywords and switches may be shortened as much as you like, but the result must
not be ambiguous (e.g. "EX" could represent "EXAMINE" or "EXIT"). You may exit
DBG by typing control-Z, EXIT, or QUIT. Any command line beginning with a
semicolon will be treated as a comment.

.HEADER LEVEL 1 CANCEL

 The CANCEL command is used to eliminate breakpoints, tracepoints, watchpoints,
and profile ranges. A keyword specifying the type of object to be eliminated
must be included following the command. If more than one object of a type is
to be eliminated then their addresses should be separated by commas with no
intervening blanks.

.LITERAL

   SYNTAX:

	CANCEL[/switches] keyword [address expression(s)]

   SWITCHES:

	/ALL	Specifies that all objects of the specified
		type are to be eliminated.

   KEYWORDS:

	BREAK	Eliminate the specified breakpoint.
	PROFILE	Eliminate all profile ranges.
	TRACE	Eliminate the specified tracepoint.
	WATCH	Eliminate the specified watchpoint.

   EXAMPLES:

	CANCEL BREAK T$RECV	Eliminate the breakpoint at
				location T$RECV

	CANCEL/ALL TRACE	Eliminate all tracepoints

	CANCEL PROFILE		Eliminate all profile ranges
.END LITERAL

.HEADER LEVEL 1 DEFINE

 The DEFINE command is used to define a symbol with a specified value. Both
the symbol name and value must be specified.

.LITERAL

   SYNTAX:

	DEFINE symbol=value

   EXAMPLES:

	DEFINE BIT9=512.	Define symbol BIT9 and give
				it the value 1000 octal.

	DEFINE NEXT=@PC		Define symbol NEXT and give
				it the value in the PC.
.END LITERAL

.HEADER LEVEL 1 DEPOSIT

 The DEPOSIT command is used to modify the target task memory and/or registers.
This command always defaults to depositing data words; it is not affected by
the mode settings. To deposit multiple data bytes or words in sequential memory
locations, separate them with commas. To deposit multiple instructions they
must be separated by semicolons. In I/D space tasks only instructions are
deposited into I space.

.LITERAL

   SYNTAX:

	DEPOSIT[/switch] address=value[,value...]

   SWITCHES:

	/BYTE		Deposit data bytes
	/INSTRUCTION	Deposit instructions
	/WORD		Deposit data words (default)

   EXAMPLES:

	DEPOSIT SYMLOW=64.	Deposits 100 octal in word
				SYMLOW

	DEP/BY TXT='H,'I	Deposits 'H and 'I in the
				two bytes at location TXT

	DEP/I @PC=MOV (R0)+,-(SP);SOB R1,@PC	Deposits a
						loop at @PC
.END LITERAL

.HEADER LEVEL 1 EVALUATE

 The EVALUATE command is used to evaluate an expression and display its value
in signed decimal, unsigned decimal, binary, octal, hexadecimal, RAD50, and
ASCII.

.LITERAL

   SYNTAX:

	EVALUATE expression

   EXAMPLE:

	EVAL 2*<3+6>
.END LITERAL

.HEADER LEVEL 1 EXAMINE

 The EXAMINE command is used to display target task memory or registers. This
command always remembers the last address range displayed, and will redisplay
it by default if no address range is specified. The data type and mode switches
are set for the current command only; the defaults are set by the SET MODE and
SET TYPE commands. An address range consists of two address expressions
separated by a colon; the lower address should be specified first. In I/D space
tasks I space can only be displayed as instructions; all other data types refer
to D space.

.LITERAL

   SYNTAX:

	EXAMINE[/switches] range[,range...]

   SWITCHES:

	/ADDRESS	Displays symbolic addresses
	/ASCII		Displays ASCII text
	/BINARY		Display in binary
	/BYTE		Displays byte data
	/DECIMAL	Display in decimal
	/HEXADECIMAL	Display in hexadecimal
	/INSTRUCTION	Displays instructions
	/LEADING	Display leading zeroes
	/NOLEADING	Don't display leading zeroes
	/NOSYMBOLIC	Don't display symbols
	/OCTAL		Display in octal
	/RAD50		Displays RAD50 characters
	/SIGNED		Display numbers as signed
	/SYMBOLIC	Display symbols
	/UNSIGNED	Display numbers as unsigned
	/WORD		Displays words

   EXAMPLES:

	EXAM/WORD R0:PS		Displays all registers
	EXAM @PC		'' next instruction
	EXAM @PC:@PC+20		'' next few instructions
	EXAM/ADDR @SP:@SP+100	'' stack symbolically
.END LITERAL

.HEADER LEVEL 1 EXIT

 The EXIT command terminates the debugging session. There are no parameters.
If a log file is open it will be closed before the command takes effect.

.HEADER LEVEL 1 GO

 The GO command initiates or resumes target task execution. If an address
expression is specified then the PC will be set to the specified address before
execution begins.

.LITERAL

   SYNTAX:

	GO [address]

   EXAMPLES:

	GO START	Resume execution at location START

	GO		Proceed with execution from @PC
.END LITERAL

.HEADER LEVEL 1 HELP

 The HELP command displays brief help on a variety of topics. Type HELP without
a topic to get a list of topics. HELP does not support subtopics.

.HEADER LEVEL 1 LOAD

 The LOAD command is used to add the symbols in a symbol table file produced
by TKB into the symbol table. The file name must be specified. If the device,
directory, and file type are not specified then they will default to the
current device (SY:), directory, and type .STB.

.LITERAL

   SYNTAX:

	LOAD filespec

   EXAMPLES:

	LOAD LB:[3,54]DBG	Load LB0:[3,54]DBG.STB

	LOAD PROGRAM		Load PROGRAM.STB
.END LITERAL

.HEADER LEVEL 1 QUIT

 This command is a synonym for the EXIT command.

.HEADER LEVEL 1 SET

 The set command is used to control many DBG parameters affecting program
execution and DBG output. The SET command must be followed by one or more
keywords indicating the parameters that are to be controlled. 

.HEADER LEVEL 2 SET BREAK

 SET BREAK is used to set one or more breakpoints. The addresses of the
instructions which are to be breakpointed must be specified. If multiple
breakpoints are set then their addresses should be separated by commas.

.LITERAL

   EXAMPLES:

	SET BREAK T$RECV	Breakpoint location T$RECV

	SET BREAK MAIN+20	Breakpoint location MAIN+20
.END LITERAL

.HEADER LEVEL 2 SET HISTORY

 SET HISTORY is used to control instruction and register traceback. The number
of instructions of traceback must be specified. The absolute maximum is 1820
instructions, but prior memory commitments may reduce this. Whenever HISTORY
is in effect all instructions will be single-stepped.

.LITERAL

   EXAMPLES:

	SET HISTORY 1820.	Set history to maximum.

	SET HISTORY 0		Turn off history.
.END LITERAL

.HEADER LEVEL 2 SET LOG

 SET LOG is used to set the name of the log file. The name of the log file must
be specified. The default filespec, parts of which will be used if the filespec
is not complete, is SY:DEBUG.LOG.

.LITERAL

   EXAMPLE:

	SET LOG EXAMPLE	   Sets the log file to EXAMPLE.LOG
.END LITERAL

.HEADER LEVEL 2 SET MODE

 The SET MODE command allows the user to control the formatting of numeric
values and other output, and the simulation of stepped instructions.

.HEADER LEVEL 3 SET MODE (NO)LEADING

 The command controls the display of leading zeroes on numeric values.
The initial setting is NOLEADING.

.LITERAL

   EXAMPLES:

	SET MODE LEADING	Display leading zeroes

	SET MODE NOLEADING	Don't display leading zeroes
.END LITERAL

.HEADER LEVEL 3 SET MODE radix

 This group of commands controls the default input radix, as well as the
output radix. The radix may be set to BINARY, DECIMAL, HEXADECIMAL, or OCTAL.
The initial setting is OCTAL.

.LITERAL

   EXAMPLE:

	SET MODE DECIMAL	Set radix to decimal
.END LITERAL

.HEADER LEVEL 3 SET MODE (NO)SIMULATE

 Single stepping is important to some of the things that DBG does, but stepping
with the trace trap is horrendously slow. For this reason, DBG provides a
module that simulates many common instructions at a faster rate than with the
trace trap. This module does not operate unless a SET MODE SIMULATE command is
issued, because it depends on the MFPS and MTPS instructions which are fully
implemented only on some of the newer PDP-11 CPUs (e.g. KDF11 and KDJ11s).
Please note that simulation could have strange effects on system behavior if
the MCR DEBUG command is used, or if the target task is aborted during
simulation.

.LITERAL

   EXAMPLES:

	SET MODE SIMULATE	Turns on simulation

	SET MODE NOSIMULATE	Turns off simulation
.END LITERAL

.HEADER LEVEL 3 SET MODE (NO)SINGLE

 This command controls the display of multiple data items on a single line
(as in EXAM/WORD). I find that I only use this mode as a switch on the EXAMINE
command. The initial setting is NOSINGLE.

.LITERAL

   EXAMPLE:

	SET MODE SINGLE		Display one item per line
.END LITERAL

.HEADER LEVEL 3 SET MODE (NO)SYMBOLIC

 This command controls the use of symbols in item addresses and disassembled
instruction operands (type ADDRESS is always displayed symbolically). The
initial setting is SYMBOLIC.

.LITERAL

   EXAMPLES:

	SET MODE SYMBOLIC	Display symbols

	SET MODE NOSYMBOLIC	Do not display symbols
.END LITERAL

.HEADER LEVEL 3 SET MODE (UN)SIGNED

 This command controls the display of values with the high bit set as
negative. The initial setting is UNSIGNED.

.LITERAL

   EXAMPLES:

	SET MODE SIGNED		Display values as signed

	SET MODE UNSIGNED 	Display values as unsigned
.END LITERAL

.HEADER LEVEL 2 SET OUTPUT

 The SET OUTPUT command allows the user to control terminal, log file, and
command file handling.

.HEADER LEVEL 3 SET OUTPUT (NO)ATTACH

 This command controls whether or not DBG's TI: will be attached during data
output (e.g. EXAMINE, SHOW). The initial setting is ATTACH.

.HEADER LEVEL 3 SET OUTPUT (NO)LOG

 This command controls whether or not commands and responses (except HELP
responses) will be sent to the log file. The initial setting is NOLOG.

.HEADER LEVEL 3 SET OUTPUT (NO)TERM

 This command controls whether or not commands and responses (except HELP
responses) will be sent to the terminal. The initial setting is TERM.

.HEADER LEVEL 3 SET OUTPUT (NO)VERIFY

 This command controls whether or not commands read from a command file are
sent to your terminal and the log file (subject to LOG and TERM). The initial
setting is NOVERIFY (i.e. commands read from a command file are executed
quietly).

.HEADER LEVEL 2 SET PROFILE

 The SET PROFILE command is used to control instruction profiling; specifically,
it is used to create a profile range. A profile range consists of a set of
counters which reflect execution within a specific address range. To create a
profile range an address range, and a compression factor, must be specified.

The address range specifies the minimum and maximum addresses which are to be
profiled. The compression factor specifies the number of instruction words to
be represented by each 32-bit counter. The default compression factor of one
provides the best possible profile resolution, but may consume too much memory.
Higher levels of compression reduce resolution, but also reduce memory
requirements.

.LITERAL

   EXAMPLES:

	SET PROF 0:20000	Profiles from 0 to 20000,
				1 word per counter

	SET PR 20002:40000 2	Profiles from 20002 to 40000
				2 words per counter
.END LITERAL

.HEADER LEVEL 2 SET TRACE

 SET TRACE is used to set one or more tracepoints. The addresses of the
instructions which are to be traced must be specified. If multiple tracepoints
are set then their addresses should be separated by commas.

.LITERAL

   EXAMPLES:

	SET TRACE LOOP		Trace location LOOP

	SET TRACE MAIN+20	Trace location MAIN+20
.END LITERAL

.HEADER LEVEL 2 SET TYPE

 SET TYPE controls the default type displayed by the EXAMINE command.
The type to be displayed must follow SET TYPE. The initial setting
is INSTRUCTION.

.LITERAL

   TYPES:

	ADDRESS		Displays symbolic addresses
	ASCII		Displays ASCII text
	BYTE		Displays byte data
	INSTRUCTION	Displays instructions
	RAD50		Displays RAD50 characters
	WORD		Displays words

   EXAMPLE:

	SET TYPE ADDR	Set the default type to ADDRESS
.END LITERAL

.HEADER LEVEL 2 SET WATCH

 SET WATCH is used to set one or more watchpoints. The addresses of the data
words which are to be watched must be specified. If multiple watchpoints are
set then their addresses should be separated by commas. 

.LITERAL

   EXAMPLES:

	SET WATCH ERRCOUNT	Watch the word at ERRCOU

	SET WATCH @SP+4		Watch the third word from
				the top of the stack

	SET WATCH R5		Watch R5
.END LITERAL

.HEADER LEVEL 1 SHOW

 The SHOW command is used to display various DBG parameters.

.HEADER LEVEL 2 SHOW BREAK

 SHOW BREAK will display the symbolic address of every breakpoint that is
currently set. If no breakpoints are set then nothing will be displayed.

.HEADER LEVEL 2 SHOW HISTORY

 SHOW HISTORY will display the size or contents of the history buffer. If no
switches are provided then the size will be displayed. The switches specify
what information should be displayed for each history entry. The optional count
parameter specifies how many of the most recent history entries should be
displayed.

.LITERAL

   SYNTAX:

	SHOW HISTORY[/switches] [count]

   SWITCHES:

	/INSTRUCTIONS	Displays instructions
	/REGISTERS	Displays registers

   EXAMPLES:

	SHOW HIST	Displays history buffer size
	SH HIST/I/R	'' entire history buffer
	SH HIST/R	'' all registers in buffer
	SH HIST/I 5	'' last 5 instructions
.END LITERAL

.HEADER LEVEL 2 SHOW MODE

 SHOW MODE will display the current mode settings. Note that some mode
parameters (e.g. LEADING, SIGNED, SIMULATE, SINGLE) are only displayed
when they are enabled (i.e. NOLEADING will never show up).

.HEADER LEVEL 2 SHOW OUTPUT

 SHOW OUTPUT will display the current output settings (i.e. those controlled
by the SET OUTPUT command).

.HEADER LEVEL 2 SHOW PROFILE

 SHOW PROFILE will display the profile ranges that have been defined. For each
range, the low and high addresses, and the compression factor, will be
displayed.

 SHOW PROFILE/COUNTERS will display all of the profile counters. Each line will
contain the symbolic address of the lowest word represented by the counter, and
the number of instructions executed in the words represented.

.HEADER LEVEL 2 SHOW SYMBOL

 SHOW SYMBOL will display the name and value of every symbol known to DBG. The
symbols will be displayed in value order. If no symbols have been defined then
nothing will be displayed.

.HEADER LEVEL 2 SHOW TRACE

 SHOW TRACE will display the symbolic address of every tracepoint that is
currently set. If no tracepoints are set then nothing will be displayed.

.HEADER LEVEL 2 SHOW TYPE

 SHOW TYPE will display the current default type for the EXAMINE command.

.HEADER LEVEL 2 SHOW WATCH

 SHOW WATCH will display the symbolic address of every watchpoint that is
currently set. If no watchpoints are set then nothing will be displayed.

.HEADER LEVEL 1 STEP

 The STEP command executes one or more instructions in the target task. If a
numeric value is provided then the number of instructions specified will be
executed. The step count is treated as an unsigned 16-bit value. If no count
is specified then one instruction will be executed.

.LITERAL

   SYNTAX:

	STEP [count]

   EXAMPLES:

	STEP 		Execute the next instruction

	STEP 3		Execute the next 3 instructions
.END LITERAL

.HEADER LEVEL 1 UNDEFINE

 The UNDEFINE command is used to delete one or more symbols from the symbol
table. The symbol name(s) must be specified. If more than one symbol is to
be deleted then the names should be separated with commas (no blanks).

.LITERAL

   SYNTAX:

	UNDEFINE symbol[,symbol...]

   EXAMPLE:

	UNDEF START	Remove START from the symbol table
.END LITERAL

.CHAPTER Installing DBG
.SUBTITLE Installing DBG

 All source code needed for DBG and DBGAID is provided. To assemble all of
the modules, install ...MAC and type "MAC @DBGASM". To generate listings,
use command file DBGASL instead of DBGASM.

 If your machine supports I/D space, then you may task build DBG by typing "TKB
@DBGBLD". Otherwise, you will have to task build DBG by typing "TKB @DBGOVLY"
(overlaid DBG). I/D space DBG is faster and has more space for symbols,
breakpoints, profile ranges, etc., so you should use it if possible. If your
system does not support fast mapping then you will have to edit out the "/FM"
switches in the task build files, and remove the definition of X$FMAP from
DBGPRE.MAC.

 Once you have assembled and task built DBG, you should copy DBGAID.OBJ to
LB:[1,1], and copy DBG.TSK to your LIBUIC (LB:[3,54]). If you intend to modify
DBG, then DBG.STB will be useful for debugging it.

.HEADER LEVEL 1 Conditional Assembly

 In some cases you may wish to modify DBGPRE.MAC (the source prefix file)
to change conditionally assembled support. The following conditional assembly
symbols are used:

.LITERAL

I$FIS	- Disassembly of FIS instructions
I$FPP	- Disassembly of FPP instructions
I$MTPS	- MFPS/MTPS support for simulation
M$PLUS	- Execution on RSX-11M-PLUS (default)
X$FMAP	- Fast mapping support
.END LITERAL

.HEADER LEVEL 1 Use of FCSRES

 Using FCSRES or FCSFSL with DBG will reduce the size of the task. If the
overlaid version is used, then this will also increase the virtual address
space available for symbols, etc. If your system does not support FCSRES
then you will have to remove the line specifying it in DBGOVLY.CMD.

.CHAPTER Task Building for use with DBG
.SUBTITLE Task Building for use with DBG

 In order for DBG to be used with a program, the DBGAID module must be linked
in as a debugging aid when the task is built. This module, which is normally
located in LB:[1,1], must always be placed in the root of an overlaid task.

.HEADER LEVEL 1 A Simple Example

 In the following example, DBGAID is linked with a task which consists of
a single module, TEST. The symbol table file produced will contain all global
symbols defined in TEST. These may be used to aid in debugging after being
loaded into the symbol table with a LOAD TEST command.

.LITERAL

	TKB TEST,,TEST=TEST,LB:[1,1]DBGAID/DA
.END LITERAL

.HEADER LEVEL 1 More About DBGAID

 The DBGAID module contains several locations which may be of interest to
advanced (i.e. desperate) users.

 Location $DBG$S (instruction space) may be patched to contain an RTI
instruction (octal 000002). This will cause DBGAID to begin task execution
immediately. If an error SST occurs (the MCR DEBUG command could also be used)
then DBGAID will attempt to communicate with the appropriate debugger task.
This allows a production task to be debugged if and when a problem is
discovered (without re-task building). DBG is built this way (see DBGBLD.CMD).

 Location $DBG$T (data space) contains the RAD50 name of the task which DBGAID
will communicate with. The first word (3 characters) of this value may be
patched during task building (or later) so that a name other than "DBGTxx" will
be used. This is especially useful for debugging more than one task from a
single terminal, or using DBG to debug itself (see DBGBLD.CMD). The second word
of this value is determined at startup from the TT: unit number of the target
task's TI: (e.g. a task running at TT13: will set this word to RAD50 "T13").

 Location $DBG$V (data space) contains the 8-word SST vector table. This table,
which is described in the Executive Reference Manual under the SVDB$ directive,
is used to vector the SSTs that DBG is interested in. Some language run time
systems, particularly DEC's Fortran OTS, use the TRAP instruction. Normally
DBGAID would receive this SST, but by changing the TRAP SST vector word
($DBG$V+14) to a zero you can allow Fortan to handle TRAPs in its own way. The
other SST vector words may be treated similarly, except that DBG will cease to
be useful if you zap the T-bit and BPT trap vector. Please note that your task
must never issue an SVDB$ directive (SVTK$ is OK).

 On RSX-11M-PLUS V3.0, DBGAID requires 562 bytes of instruction space, and 526
bytes of data space (1088 bytes total).

.CHAPTER Using DBG
.SUBTITLE Using DBG

.HEADER LEVEL 1 Getting Started

 DBG only seems to work right when it is installed as a utility (i.e. ...DBG),
so make sure that this is done prior to attempting to use it. After having
built your task with DBGAID, run it in the normal manner. Unless you have
patched DBGAID location $DBG$S, your program will not do anything much. Now
type DBG followed by the name of your task (if you leave off the task name, DBG
will prompt for it). If all is well, then DBG will come up with a message that
includes DBG's version and the name of the target task, and a prompt. If you
created a symbol table file, now is the time to LOAD it. The EXAMINE command
will let you look around (try "EXAM @PC" or "EXAM/W R0:PS"), and the GO and
STEP commands will let you begin to execute your task. Set a breakpoint with
SET BREAK (clear it with CANCEL BREAK). The HELP command just might.

.HEADER LEVEL 1 Target Task Priority

 If you must do a lot of stepping (e.g. profiling or using watchpoints) and
cannot use simulate mode then you should make sure that your target task runs
at a lower priority than DBG. This will result in much faster execution. This
is because of the way DBG and DBGAID use the Wait for Significant Event
directive while communicating. Organizing your task priorities in this manner
could also improve the speed of other operations.

.HEADER LEVEL 1 Directive Status

 The executive expects the directive status word ($DSW) to be at location 46.
DBGAID, however, would modify the target task directive status if it didn't
save it. For this reason you should always refer to $DSW by name for both
examination and modification. This will cause you to reference the target task
directive status that DBGAID has squirreled away, and which will be restored
before execution proceeds. If you "EVAL $DSW", you will notice it is not at
location 46 (it is stored right after the PS in DBGAID).

.HEADER LEVEL 1 MCR DEBUG

 The MCR DEBUG command is used to force a trace trap in a task which has a
debugging aid. DBG recognizes this condition, with the possible exception of
when the program is being stepped via the trace trap (try again if DBG doesn't
seem to notice).

 If you are stepping, and simulation mode is enabled, then the MCR DEBUG
command will not be recognized until an instruction that is not simulated is
encountered. This might take a little while. If this is a real problem for you,
then you should reduce the value of MAXSIM in DBGPRE.MAC.

.HEADER LEVEL 1 PROFANAL

 PROFANAL.C is a supplied C program that can help you to use the data from
instruction profiling. To use PROFANAL, compile and task build it, and run it
with the STDIN redirected to a file containing the output of the SHOW
PROFILE/COUNTERS command. You can create a file containing this information by
logging this information to a file (see SET OUTPUT LOG) and editing the log
file to remove everything but the results of this command. PROFANAL will add up
all counters between global symbols and display the sums, as well as a grand
total, on STDOUT. For many programs, this list represents the relative time
spent in each module, therefore it indicates which modules, if any, could
profit from optimization.

.HEADER LEVEL 1 SST Vectors

 As discussed in the section on DBGAID, DBGAID's debugging SST vectors begin
at location $DBG$V. If any vectors must be disabled (e.g. TRAP for use with
the Fortran OTS) they may be modified at run time. The target task must not
issue an SVDB$ directive.

.HEADER LEVEL 1 I/D Space Tasks

 DBG is perfectly happy debugging I/D space tasks. It doesn't know that you may
get confused because your data and instruction symbols will overmap the same
areas. Even if TKB indicated whether symbols are in I or D space, a lot of DBG
would have to change to take advantage of it (symbol storage, expression
handling, symbol selection, etc.).

.HEADER LEVEL 1 Programs with Overlays

 It is possible to debug programs with overlays using DBG, but I don't
recommend it.  Overlays make things nasty because DBG doesn't know where things
are anymore. You should make sure that no breakpoints are set in an overlay
area if another overlay might be loaded; otherwise DBG may modify your program
or data for you.

 It is useful to know that when you set a breakpoint on a global routine that
is actually in an overlay, DBG will set the breakpoint on the autoload vector
entry point (assuming you are not loading overlays yourself). From this point
you can step your way into the overlay...

.HEADER LEVEL 1 Programs with ASTs

 Debugging a program with ASTs can be complicated because of the multiple
execution streams through the task. DBGAID protects itself by disabling
AST recognition while it has control. Before DBGAID relinquishes control it
enables AST recognition only if it was enabled when DBGAID was entered.

 You can set a breakpoint within an AST routine and DBG should work as
expected. If you are single stepping the program at task level, an AST can
occur between the time the trace trap occurs and when DBGAID disables AST
recognition. When the AST routine is entered the PSW will not have the trace
bit set, so the AST routine will execute unimpeded. It may not be obvious that
this has occurred.

.HEADER LEVEL 1 Debugging a Task at Another Terminal

 It is sometimes necessary to run DBG on a different terminal from the target
tasks TI: (e.g. the target task attaches the terminal). This is most easily
handled by running the target task in the normal manner, and initiating DBG
execution via the MCR RUN command on another terminal and specifying the task
name as if DBG were running on the same terminal as the target task. This works
because DBGAID communicates with the DBG task using RCVD$ and SREF$ calls.

.LITERAL

   EXAMPLE:

	RUN $DBG/TASK=DBGT13
.END LITERAL

.HEADER LEVEL 1 Function Keys

 DBG is very nice with programmable function keys. Unfortunately, I didn't
implement them. I have a terminal which allows the user to program the function
keys inside the setup menus. I typically put in things like "STEP", "GO",
"EXAM/W R0:PS", etc. When I want to implement something that can't be done in
one command, I have the function key invoke a command file. A good example is
OVER.CMD (below, invoked as "@OVER").

.TEXT
.LITERAL

;
;   OVER.CMD "steps over" a subroutine call.
;   Note that this is not foolproof, but still useful.
;
SET BREAK @PC+4	! Set break at return point
GO		! Execute the subroutine
CAN BREAK @PC	! Clear the breakpoint
.END LITERAL
.END TEXT

.HEADER LEVEL 1 Serious Problems

 Because of the way DBGAID is implemented, it is possible to write a program
that is very difficult to debug. A program that modifies DBGAID's code and/or
data area(s) could cause you to tear your hair out. Assuming that the damage is
accidental, it may help to change the ordering of modules (changing DBGAID's
PSECT names could work), or to insert guard areas before and/or after DBGAID's
code and data areas, and set watchpoints on the guard areas. Understanding how
DBGAID works, along with some creative thinking, should get you through most
anything.

.CHAPTER Implementation
.SUBTITLE Implementation

 DBG is a non-privileged program, and operates on the target task by mapping an
address window to it. The DBGAID module facilitates the process by saving and
restoring task registers, and by sending mapping context information, and other
task areas, by reference. The DBGAID module is rather large because of its
internal data requirements, but it is smaller than ODT. An earlier version of
this program operated entirely by send and receive data calls, but I got fed up
with it because of the poor performance.

 DBG requires the extended instruction set (EIS). On KDF11 and KDJ11 processors
DBG can simulate instruction execution (the MFPS and MTPS instructions are
required); this is faster than stepping with the trace trap.

 DBG uses CSI, GCML, and FCS. DBGAID disables ASTs while it executes, and does
not use any LUNs or event flags. DBG uses fast mapping when it is available.
DBG and DBGAID use the following executive directives:

.LITERAL

	ALUN$				GTSK$S
	CRAW$				MAP$S
	DSAR$S				QIO$
	DTRG$				QIOW$
	ENAR$S				QIOW$S
	EXIT$S				RCVD$
	EXST$S				RREF$
	EXTK$S				SREF$S
	GIN$ (subfunction GI.TSK)	SVDB$
	GLUN$				SDAT$S
	GMCR$				WSIG$S
	GMCX$
.END LITERAL

 DBG is composed of the following files:

.LITERAL

ASSEMBLE.MAC	Assembles instructions for DEP/INS
CANCEL.MAC	CANCEL command
CONVERT.MAC	Numeric/symbolic conversion
DBGAID.MAC	DBG support module for target task
DBGPRE.MAC	DBG and DBGAID prefix file
DEBUG.MAC	DBG main program (many global variables)
DEFINE.MAC	DEFINE and UNDEFINE commands
DEPOSIT.MAC	DEPOSIT command
DISASM.MAC	Instruction disassembler
ERROR.MAC	Error message display and definition
EVALUATE.MAC	EVALUATE command
EXAMINE.MAC	EXAMINE command
EXECUTE.MAC	GO and STEP commands, associated stuff
EXPRESS.MAC	Expression parser
HELP.MAC	HELP command and text
INIT.MAC	One-time initialization
LOAD.MAC	LOAD command
MEMORY.MAC	Target task memory routines
MODTBL.MAC	Mode keyword table for SET and EXAMINE
OPCTBL.MAC	Opcode table for ASSEMBLE and DISASM
SET.MAC		SET command
SHOW.MAC	SHOW command
SIM11.MAC	PDP-11 instruction simulator
SYMBOL.MAC	Symbol handling routines
TSKCOM.MAC	Routines to talk to DBGAID
UTILITY.MAC	Utility routines (some bizarre)
PROFANAL.C	C program to analyze profile data
DBGASL.CMD	MAC command file to assemble DBG
DBGASM.CMD	Same as DBGASL but makes no listings
DBGBLD.CMD	Builds DBG for I/D space
DBGMAN.CMD	Produces DBG manual (via RUNOFF)
DBGOVLY.CMD	Builds overlaid DBG
DBGOVLY.ODL	Overlay description for DBGOVLY.CMD
DBGFRONT.RNO	Cover sheet for DBG manual (RUNOFF)
DBGMAN.RNO	DBG manual (RUNOFF)
DBG.DOC		Human readable DBG manual
.END LITERAL

.HEADER LEVEL 1 Parsing

 Parsing takes place at several levels within the debugger. Keywords are parsed
by recognizing them in keyword tables. Expressions are parsed by a recursive
descent expression parser. The following routines (modules) are useful for
parsing command lines.

.LITERAL

U$DCOD (UTILITY)    Looks up a keyword in a keyword table.
		    The keyword table is composed of KEYWRD
		    macro calls, and terminated by a zero.
U$FNXT (UTILITY)    Finds the next command line element.
U$FTRM (UTILITY)    Finds a command element terminator.
XPRESS (EXPRESS)    Evaluates an expression.
.END LITERAL

.HEADER LEVEL 1 User Output

.HEADER LEVEL 2 Output Formatting

 The following routines (modules) are provided to aid in the formatting of
output.

.LITERAL

C$ASCB (CONVERT)    Convert a byte to an ASCII character.
C$ASCI (CONVERT)    Convert a word to 2 ASCII characters.
C$NUMB (CONVERT)    Convert a byte to a numeric value.
C$NUM  (CONVERT)    Convert a word to a numeric value.
C$R50  (CONVERT)    Convert a RAD50 word to ASCII.
C$SYMB (CONVERT)    Convert a word value symbolically.
C$VALU (CONVERT)    Converts a word value according to the
		    default format (mode and symbol flags).
U$ADDR (UTILITY)    Buffer an address to start a data line.
U$RMTB (UTILITY)    Strip trailing blanks from a string.
.END LITERAL

.HEADER LEVEL 2 Error Output

 Routine ERROR (module ERROR) is used to output error messages. All of the
errors that can be displayed are in a table in this module. A single text
argument can be passed for inclusion at a user-defined point in an error
message.

.HEADER LEVEL 2 Terminal Output

 Routine LINOUT (module DEBUG) is used to output a line of text to the
terminal, and the log file if logging is enabled. Locating the data to be
presented in TRMBUF allows optimal data handling.

 Routines TRMATT and TRMDET (also module DEBUG) are used to attach and detach
the terminal for potentially long output sequences. This allows the use of
control O on the output.

.HEADER LEVEL 1 List Handling

 All lists managed by DBG are stored in value order. This simplifies many of
the list searching algorithms although it frequently increases search times.
The following lists are stored in this manner.

.LITERAL

BRKLST (DEBUG)	    Breakpoint list (elements are P.xxxx)
PROLST (DEBUG)	    Profile range list (elements are PR.xxx)
REGSYM (DEBUG)	    Register symbols (elements are S.xxxx)
SYMTBL (DEBUG)	    Symbol table list (elements are S.xxxx)
TRCLST (DEBUG)	    Tracepoint list (elements are P.xxxx)
WCHLST (DEBUG)	    Watchpoint list (elements are P.xxxx)
.END LITERAL

 The following routines are provided for managing symbol tables.

.LITERAL

S$DEFN (SYMBOL)     Define a symbol.
S$LNAM (SYMBOL)     Locate a symbol by name.
S$LVAL (SYMBOL)     Locate a symbol by value.
.END LITERAL