PDP-10.its/doc/rug/rug.doc2

.XGP
.double
.fill

	Rug is a symbolic debugger which runs on the pdp11.
There are three basic output modes which affect how the
contents of a location get printed.
.nofill
$C causes the location contents to be printed as a number.
$S causes the location to be printed as a symbol.
$I causes the location to be printed as an instruction.
Also there are two minor mode changes:
$A inhibits the printing of symbols (like in an instruction).
$R reverses the action of $A.
.fill

	By typing two alt modes, the mode gets more permanently changed,
but can be changed back, of course by switching to a different mode.

	To open a location type / or \.
This opens it in word or byte mode respectively.
However if an odd location is opened, it will be in byte
mode even if / was typed.

	After a location is opened, a number can be placed into it numerically,
symbolically, or as an instruction. For instance if FOO is defined,all of the following are legal:
.nofill
100/  53 MOV @FOO+.(%2),(%3)+
100/  53 FOO+352-10
100/  53  6
.fill
	To open a register, type %5/ and %5 will be opened as expected
(or if it is a defined symbol
just type its name)

	When typing an instruction, type
the operation code followed by a space or tab. 
Extra tabs and spaces are ignored here.
Then type the next field. Follow it by a comma if
there is another field. Then type the other field.
When inputting a symbol, the arithmetic operations
are +, -, *, and ! for add, subtract multiply
and divide respectively.
Important note: when typing in
condition codes, type SE CZ, for example. in other words, type
SE(space) or CL(space), depending on whether you
wish to clear or set the flags, then follow it with all the
flags you wish to modify by the instruction.

	After a location is opened, carriage return will close it, placing
in it any value that might have been typed directly before the return,
unless some operations were performed, in which case it will not change
the contents.
 Line feed will open the next word or byte, depending
on whether the previous location were opened in word or byte mode.
if the previous location were opened in instruction mode, line feed
will open the next instruction. (it will skip over to the end of
a multiple lenth instruction.
 ^ will go to either one word or one byte ahead of the opened location. 
being in instuction mode does not change this.
 / opens the last memory location mentioned
(like JMP FOO,MOV BAR,FOO  or TSTB @FOO all open FOO)
 _ opens second last memory location mentioned
(MOV BAR,FOO opens BAR with an extra slash)
 tab (contrl i) opens the location which is the
value of the number in the location opened.

 < will return to the sequence interrupted by extra tabs

.center
breakpoints
To set a breakpoint, type FOO$B
This sets a breakpoint at location FOO.
To delete a breakpoint, type FOO$D.
To delete all breakpoints, type $D.

	To see which locations have breakpoints in them,
type .B/. This will contain either a random location within rug,
indicating that that breakpoint is not set, or a location which
would be where that breakpoint is.
If line feed is typed, you can see where B1 is.
If another line feed is typed, you can see where B2 is, etc.
up to B7. Or type .B+6 to examine breakpoint 6.
To examine the count number of each
breakpoint, type .C+n/ to examine the count of breakpoint n.
(The count is how many times you are to proceed through that
breakpoint before stopping.)



.center
running the program
.nofill
FOO$G starts it at location FOO
$P lets it proceed from where it left off
n$P causes it to stop after looping through the last breakpoint
n times.
.fill
The breakpoint repeat counts can be inpected and modified
by opening .B and typing 9 line feeds.
The repeat count for breakpoint 0 will then be typed.
The repeat counts for breakpoints 1 through 7 follow in sequence.
.center

single step mode
by typing ^N,  you can execute one more instruction.
Rug will type SS;adr, where adr is the address of the
next instruction to be executed.
To execute 5 instructions, type 5^N, etc.
Breakpoints are disabled in single instruction mode.
By typing 400^N, it is very likely you might skip a few
breakpoints.


 .S is a defined symbol which is the user status.
 .P is a defined symbol which is the user priority

.center
defining symbols
To define a symbol, type 100,FOO:
This defines FOO as location 100.
It is perfectly legal to redefine symbols.
All radix 50 chars are legal in a symbol.
Symbol names longer than 6 characters get automatically chopped.
Also, FOO: defines FOO as . (address of the open
location)

	To half kill an already defined symbol type FOO^k.
To unhalf kill a symbol you accidentally half killed, just
redefine it (type FOO,FOO)

	A string of numbers will be considered
as octal unless there is a decimal point somewhere in it
or it contains an 8 or 9.
.break

& causes radix 50 to be input (&abc is like typing the numeric
quantity which is abc in radix 50 packed with a on the left)
spaces are zero radix 50

.break
[ will type the two ascii bytes in the opened word
.break

.break
] performs a radix 50 mode unpack of the opened word.
.break

' causes the ascii value of the next character to be input
(mov ##'F,R2 is legal)
.break
" causes the next two char.'s ascii value to be packed into a word

.center
loading a file
	To load a file from the paper tape reader,
type $LP:. If it is on multiple tapes, the debugger
halts at the end of each tape and hitting "continue"
causes the next tape to be read.
Use RADIA;PUNCH BIN on the PDP10 to punch out a
debugger-loadable tape, which is an absolute loader
binary of the program which gets loaded directly onto
disk, followed by an absolute loader tape of the
symbol table which gets loaded directly into core.

	To load a file from the PDP10's disk, type $LT: <user;file name>,
where <user;file name> is the ITS file specification for the file to be
loaded.When it is done loading you'll be back
in the debugger.
	To load a program without first zeroing
core, type $^L instead of $L.
Symbols are always loaded with the program.

	To save the debugger on disk type $^D. To get it back type $^U.
To load a program of disk #<n>, type $L<n>:<file name>.  To save it (dump it)
type $Y<n>:<file name>.  If a file with the name <file name> exists already,
rug will type FILE EXISTS DELETE?.  If you then type Y, rug will delete the old
file, and dump core into a new file with <file name>.  If you type anything else,
the file is not dumped.
.center
zeroing core and initializing the symbol table.
	To zero all of core and initialize the symbol table, type $$Z. To just
reinitialize the symbol table, type $Z.
.center
interacting with programs
	Programs should leave locations 157000-160000 alone.
That is the resident portion of rug.
If a program is running and you wish to get to the debugger,
halt the program and start at location 157000.
Rug should swap the program out and itself in.
Proceed is disabled when the debugger is
started with the switches as opposed to trapping there.
(the program executes "3")
	Aside from the the 300 locations already mentioned, the program 
can use all 28k of core.
However, currently only up to 157500 (the
absolute loader) is swapped in and out.
Maximum symbol table size is about 2000 symbols
(logo is well under the limit.)
To find out how much symbol table room is used,
type "..B="
The mimumum allowed value of ..B is 10000.