PDP-10.its/doc/_info_/urug.manual

MICRORUG USER'S MANUAL

		M. Beeler, August 1973

Microrug is an octal debugger for the DEC GT-40 computer/display.
The user should be familiar with the PDP-11/05, which is the
minicomputer in the GT-40.

Microrug (URUG for short) occupies 1000 (octal) consecutive bytes of
memory, and uses the keyboard for input and the CRT display for output.
The information displayed is in four lines.  New information appears
on the bottom line, and when that line is completed, the lines are
scrolled upward; the previous top line is lost, and the new bottom
line is blank.  To help the user tell which line is which, a dot is
displayed at the left of the screen between the top and second lines.

URUG is used for three different functions:  examining (and depositing
into) memory locations, setting breakpoints, and starting up programs.
There are two versions of URUG, one which uses the JMP instruction
for breakpoints and one which uses BPT.  They are similar, so the JMP
version is described below, and then differences in the BPT version
are noted.

To examine a location, type its address in octal, and a space.  URUG
types the current contents of that location.  To change the contents,
type the desired contents and a space.  The new contents are deposited
in the location, and the display scrolled to present a fresh line for
more commands.

If no argument precedes the space, then nothing is deposited, and the
display is scrolled as usual.  (This also applies to typing a space
as the first character on a fresh line; no action is taken except to
scroll the display.)

If a mistake is made in typing a numeric argument (such as an address or
new contents), typing rubout resets URUG as if none of the argument
were typed.

If a linefeed is typed instead of a space, URUG takes the same action
but then also types the address and contents of the location after the
last location examined.

If you try to examine an odd-numbered location (i.e., the left byte of
a word), URUG acts as if you typed an address one less.

URUG's starting address, BEG, is the first location in URUG, often
assembled to be 37000.  When URUG is started, it saves general
registers R0 through R6, and restores them when  you ask it to start
up a program.  Thus, while URUG is running, 177700 through 177707
contain URUG's values and not those of the user's program.  The user's
general registers are referenced by typing R0 through R6 as addresses.
Since the locations actually examined are inside URUG, linefeed acts
strangely.  Specifically, user registers contents are stored in every
other word, so two linefeeds after R0 is the same as typing R1.
Examining non-existing locations (such as above 37776) causes a
timeout trap through location 4.  To avoid losing URUG's copy of the
user general registers, restart URUG at RESUME instead of BEG (that is,
40 bytes later).

A breakpoint consists of the instruction, JMP BEG, where BEG is the
starting address of URUG.  A breakpoint is set by typing B.  If no
argument is given, the breakpoint is placed at zero.

If a number precedes the B, that number is used as an address at which
to set the breakpoint.  Evenness of the B argument is not checked, so
trying to set a breakpoint at an odd address causes an odd address
error trap through location 4 (again, restart URUG at BEG+40).

When URUG is started (or restarted, at BEG+40), it checks whether any
breakpoint is set.  If not, it merely scrolls the display and waits
for commands.  If so, it restores the contents of the breakpoint
location (and following word), scrolls the display, and automatically
examines the breakpoint location to let you know it's just hit and
restored the breakpoint.

Typing B when the breakpoint (there is only one) is already set is the
same as restarting URUG at BEG+40; it restores the breakpoint contents,
etc.

Typing G, preceded by a number, restores the general registers to the
user's values, and transfers to the argument of the G.  G with no
argument transfers to the location last G'ed.  URUG's memory of what
this location is may be examined and modified as R7.

The G command, like B, does not check for evenness of its argument.
If you try to G to an odd address, the user values are already
restored to the machine's general registers, so it does not matter
whether you restart at BEG or BEG+40.

Two details of URUG are equivalent characters and typing too much.
Because of its simple type-in routines, carriage return and tab, as
well as various other control characters, have the same effect as
space.  Although R, B, and G are echoed as upper case, they must be
typed as lower case.  Except for these characters, and the ten digits
0 - 9, all characters = rubout.

If more than 24 (decimal) characters are typed, by URUG and/or the
user, before a scrolling occurs, then display commands will be
overwritten and URUG will probably have to be reloaded to be useful.
To be exact, URUG could still be used to replace the clobbered display
instructions at the very top of itself (as long as the garbaged
commands aren't making the PDP-11 trap).  22 characters will cause the
next command line to possibly be run-on, but this is temporary and
easily ignored.

If the user wants to resume his own display program before starting
up his PDP-11 program, the following sequence is suggested:
	R7	xxxxxx	USRBEG	(set G address)
	172000	xxxxxx	USRDPC	(start user's display program)
	G			(start user's PDP-11 program)
	BPT VERSION -- DIFFERENCES FROM JMP VERSION

The location RESUME, at which to start after time-out
and odd address traps, is BEG+34 instead of BEG+40.

A breakpoint in this version consists of the instruction, BPT.

It requires that:
(1) the user must have set up an appropriate BPT trap vector, namely:
	14 contains BEG+162 (=HITBRK), URUG's breakpoint handler
	16 contains 340, to set CPU priority to 7
(2) the user must have set up an appropriate stack pointer in R6,
    such that the BPT can push its 2 more words without trapping
(3) R6 must be so set up before any G command, since G'ing
    is done by pushing PS, PC, and executing an RTI

It has the advantages that:
(1) the breakpoint occupies only one word
(2) the BPT trap vector automatically protects URUG from interrupts
(3) the N, Z, V and C condition codes are preserved
    through a breakpoint-and-proceed sequence
(4) the user's processor status may be examined and modified
(5) URUG code saved allows automatic display restarting (see below)

In the BPT version, the saved PS may be examined and modified as R8.
While URUG is running, the user's PC and PS are popped off the stack
(into pseudo-R7 and R8), so examining R6 yields the user's R6 before
the BPT, and this may be modified without losing the PC or PS.
URUG does not use a stack, except for the breakpoint handler and
setting up the RTI for the G command.  (The JMP version of URUG
never uses a stack.)

The BPT version's G command also restarts the display before it starts
the user's program.  The address loaded into the Display Program
Counter may be examined and modified as R9.  It is initially that of
URUG's own display program.

Some thought has been given to making URUG position-independent.
It seems unlikely.  Instead, it is suggested that you re-assemble it
For whatever starting address you want.  It has assemble-time teletype
input to specify JMP or BPT version, as well as starting address.
A starting address not ending in zero may cause it to use a few more
than 1000 bytes.
	GT-40 BOOTSTRAP LOADER ("version S09, release R01")

The main point of this discussion is explaining what core locations
the loader clobbers.

The loader operates in two modes.  First, it echoes like a teletype,
sending each character from the keyboard to the PDP-10, and displaying
each character from the PDP-10 on the screen.

The loader (in both modes) starts its stack at 15770 and works down.
The echoing mode uses 2+2n stack words, where n is the number of
keyboard characters typed which have not yet been sent to the PDP-10.
Thus it uses at least 4 words, and if typing is not rapid, only 4.
This is fewer words than used in the loading mode, as discussed below.

The echoing mode also uses several locations in low core, mainly for
display words, but also for a power-fail vector.  Each character from
the PDP-10 is stored in a separate word with left byte = 0, starting
at location 32.  Thus, after receiving c characters from the PDP-10,
the following locations in low core will be clobbered:

       0 <= 160000	;DISPLAY JUMP
       2 <= 166756	;TO "DISPRG" IN LOADER

      24 <= 166010	;POWER FAIL PC = START+10
      26 <= 0		;POWER FAIL STATUS
      30 <= 0		;START OF DISPLAY LIST
      32 <= char1	;FIRST CHARACTER
      34 <= char2	;SECOND CHARACTER
     etc.
   30+2c <= char c	;c-th CHARACTER
   32+2c <= 160000	;DISPLAY JUMP
   34+2c <= 0		;To 0
   36+2c <= 160000	;DISPLAY JUMP
   40+2c <= 0		;To 0

   42+2c and following are not clobbered
The loading mode uses 8 stack words.  The stack pointer is initialized
to 15770 instead of 15770+2, so the first location on the stack, at
15770, is not clobbered.  The next lower 8 locations, 15750 through
15766 inclusive, are clobbered during loading.  Trying to load into
these locations will usually cause random data to be loaded, or else
transfer to random locations when a loader RTS PC pops loaded data
into the PC.

Both the echoing and the loading modes use three particular locations
as I/O character buffers:
	15772  (P10IC) is clobbered by characters read
	15774  is also clobbered by characters read
	15776  (P10OC) is used for characters to be sent to the
		PDP-10, and will contain 0 after loading

When the loader switches from echoing to loading mode, it turns off
the display and no longer references low core locations (except to
load data into them).  Thus, all the display words and the power-fail
vector can be overwritten by the loading mode.  The difficulty is if
one wishes to merge-load two or more programs.  If one of the programs
before the last one occupies these low core locations, then restarting
the bootstrap will clobber it.  There are two simple alternatives;
both involve telling the PDP-10 all the programs you want merged,
before any are loaded.  The PDP-10 can then either:
(1) concatenate all the programs and not give the
    "end of load" signal until all are loaded; or
(2) at the end of each program, give the "start up program" signal
    with address 166520 ("LOAD"), which simply restarts the loading
    mode.  After the last program it can give the "end of load" signal.

[Note on a GT-40 (PDP-11/05) quirk:  177700 through 177707 are R0
through R7 as far as the examine and deposit switches are concerned,
but	MOV Rm,@#17770n
always acts like n = 0 (i.e. deposits in R0 = 177700).  The data
also shows up in 177710, apparently a CPU temporary register.]
		 n = 0/1 = word/byte
		ee = offset, 0 - 77
		ff = offset, 0 - 377

	     0  HALT		1000ff  BPL
	     1  WAIT		1004ff  BMI
	     2  RTI		1010ff  BHI
	     3  BPT		1014ff  BLOS
	     4  IOT		1020ff  BVC
	     5  RESET		1024ff  BVS
             6  RTT		1030ff  BCC = BHIS
	     7 - 77  UUO	1034ff  BCS = BLO
	   1DD  JMP
	   20R  RTS
	   210 - 227  UUO
	   23m  SPL
	   240 - 277  CC's: 20 0/1 = clr/set
	   3DD  SWAB	  10 N
	   4ff  BR	   4 Z
	  10ff  BNE	   2 V
	  14ff  BEQ	   1 C
	  20ff  BGE
	  24ff  BLT	     104000
	  30ff  BGT	       to    EMT
	  34ff  BLE	     104377
	  4RDD  JSR
	n050DD  CLR(B)       104400
	n051DD  COM(B)         to    TRAP
	n052DD  INC(B)       104777
	n053DD  DEC(B)
	n054DD  NEG(B)
	n055DD  ADC(B)
	n056DD  SBC(B)
	n057DD  TST(B)
	n060DD  ROR(B)
	n061DD  ROL(B)
	n062DD  ASR(B)
	n063DD  ASL(B)
	  64mm  MARK         106400 - 106477  UUO
	  65SS  MFPI         1065SS  MFPD
	  66DD  MTPI         1066DD  MTPD
	  67DD  SXT          106700 - 107777  UUO
	  7000 - 7777  UUO
	n1SSDD  MOV(B)
	n2SSDD  CMP(B)
	n3SSDD  BIT(B)
	n4SSDD  BIC(B)
	n5SSDD  BIS(B)
	 6SSDD  ADD          16SSDD  SUB
	 70RSS  MUL
	 71RSS  DIV
	 72RSS  ASH
	 73RSS  ASHC         17xxxx  FPP's
	 74RDD  XOR
	 75000 - 76777  UUO
	 77Ree  SOB