KS10 microcode.

Plus assorted KS10-related documents.

doc/kshack/-read-.-this-

@@ -0,0 +1,14 @@
+
+This directory contains KS10 specific files for ITS.  It contains:
+The microcode assembler, microcode source files, etc.
+KSDEFS and other KS10-specific documentation and definition files.
+The new salvager NSALV.
+KSFEDR, the 8080 front-end filesystem manipulation program.
+MTBOOT, the KS10 boot tape writing program.
+The MINI36 server, used by NSALV to retrieve files over Chaosnet.
+Etc.
+
+The KSHACK directory on MC no longer contains the canonical versions of
+these files.  The KSHACK directory on AI is now the official KS10 hacking
+directory.  -Alan 12/30/85
+

doc/kshack/1proc.bugs

@@ -0,0 +1,2 @@
+Some floating-point instructions clear all bits in FLG,
+they will have to be fixed to only clear some LH bits.

doc/kshack/ainote.8

@@ -0,0 +1,182 @@
+-*- Text -*-				This is the file AI:KSHACK;AINOTE >
+
+
+                           WHAT TO DO IF AI CRASHES
+
+*******************************************************************************
+* Before following these directions, please try to find a system hacker to    *
+* take a look at the corpse first.					      *
+*									      *
+* If you do -anything- about a crashed ITS, leave an explanation in the log   *
+* book next to the system console.  Include the date and time, your name,     *
+* what the problem was, what you did, and anything else relevant.  And please *
+* make it legible; three lines of random scrawls can't help the hackers fix   *
+* the problem.								      *
+*******************************************************************************
+
+                               THE SIMPLEST CASE
+In the most common sort of crash, AI will type a bug message and go to Exec
+DDT.  For example:
+    PI LEVEL 7 BUGHALT.  FIND A WIZARD OR CONSIDER TAKING A CRASH DUMP.
+    THE SYSTEM HAS CRASHED AND CANNOT BE REVIVED WITHOUT EXPERT ATTENTION.
+    IF YOU CAN'T FIND HELP, RELOAD THE SYSTEM.
+    YOU ARE NOW IN DDT.
+    BUGPC/   CAIA PCLSR+3   $Q-1/   PUSHJ P,BUGNIL
+
+If the message says that the bug is "proceedable", you can try typing:
+    $P
+to revive the system.  If this works, be glad you don't have to read the rest
+of this notice; however, you should still leave a note in the log book.
+
+                               LESS THAN SIMPLE
+If the system cannot be revived, it must be reloaded.  To reload, you must get
+to DSKDMP.  Type:
+    $U
+to leave Exec DDT and start DSKDMP.  When DSKDMP starts up it announces itself
+by saying:
+     DSKDMP
+If DSKDMP has something to complain about, it will type a error message; its
+error messages are explained on the summary of DSKDMP commands taped to AI.  If
+you don't understand (or like) what DSKDMP is telling you, stop; let someone
+who does understand check it out.
+
+                                  CRASH DUMPS
+Before reloading, you may want to take a crash dump.  Crash dumps are
+recommended if anything unusual was happening before the system crashed, or if
+the remains look funny.  To take a crash dump, get into DSKDMP and type:
+    D$CRASH;<fn1> <fn2><cr>
+where <fn1> <fn2> is somehow descriptive of the problem; AI will linefeed when
+the crash has been dumped.  You can list the CRASH directory by typing:
+    U$CRASH;
+to see what filenames are already used.  If you take a crash dump, send mail to
+Bug-ITS giving the filename you used.
+
+                                 RELOADING ITS
+Look at AI's "Very Small Bulletin Board" envelope on the front of the system
+console.  The punch card in front will list which version of ITS is supposed to
+be running.  If, for instance, it says "NITS", then to reload AI, type:
+    .;NITS<cr>
+This will cause DSKDMP to find the file DSK:.;@ NITS, load it into core, and
+start it in Exec DDT -- thus, you will be talking to Exec DDT again, which will
+linefeed to indicate it's ready for you.
+
+Now check for any special instructions someone might have left about patching
+ITS before starting it.  Typically, a patch will appear as a few cryptic
+commands scrawled on a scrap of paper stuffed into the VSBB in front on the
+punch cards, which must be typed to Exec DDT before you proceed further.  If
+you find such instructions, but can't figure out what they mean, stop now.
+
+To start ITS, type:
+    $G
+to Exec DDT.  ITS starts by running the Salvager over the filesystem, which
+causes the disk to make noise -- don't worry, that's supposed to happen -- and
+prints a series of messages to indicate its progress.  If the Salvager finds
+anything terribly wrong with the filesystem, it will refuse to let you bring
+the system back up.  If this happens, give up and find a hacker.
+
+Next, ITS pokes around to see if there are any surprising holes in its memory.
+If it finds any, it will ask if they are OK.  If there is a note in the VSBB
+predicting the holes exactly, answer affirmatively; otherwise it is time to
+find a system hacker.
+
+Now ITS checks whether it knows the time.  If it doesn't, it tries to find the
+current time from other machines on the local network.  This may not work; if
+it doesn't, AI will print an attention-getting message (including feeps) as it
+comes up.  In this case, you must log in and run the PDSET program.
+
+                                 RUNNING PDSET
+If ITS tells you to run PDSET, you might as well does this from the system
+console.  So type:
+    
+and after AI greets you, type:
+    :PDSET<cr>
+to run the PDSET program.  PDSET starts by warning you that what it does is
+potentially dangerous.  To set the date and time type:
+    yymmddD
+    hhmmssT
+    !.
+where "yymmdd" is the date ("850520" for May 20, 1985) and "hhmmss" is the time
+in 24-hour time ("145900" for 2:59 PM).  At the instant you type the ".", PDSET
+will set the time to what you specified.
+
+To leave PDSET type:
+    Q
+and then log out:
+    $$U
+
+                                  IF AI HALTS
+If the processor halts, the 8080 front-end will print a halt code and a PC.
+These will look something like:
+    %HLTD/000001  PC/704000,,071101
+Write these numbers in the log book.  Also, if you take a crash dump, mention
+these numbers in the mail you send to Bug-ITS.
+
+You should now be talking to the 8080 front-end.  To check this, type a
+linefeed or two; you should see the prompt:
+    KS10> 
+Now type:
+    ST 777700<cr>
+and the 8080 will try to start DSKDMP.  If this works, DSKDMP will announce
+itself, and you should go back to the middle of "Less Than Simple" and proceed
+from there.
+
+If DSKDMP does not start up, cold boot the machine.
+
+                                 COLD BOOTING
+Push the white "BOOT" switch on the front of AI.  This should initialize
+everything, and load and start DSKDMP.  DSKDMP will announce itself by typing:
+     DSKDMP
+If nothing happens, make sure that some loser hasn't set the white "LOCK"
+switch, also be sure that the "WRITE PROTECT" switch on the disk isn't set.
+Now go back to "Reloading ITS" and proceed from there.
+
+                 ITS IS CLEARLY BROKEN, BUT IT'S STILL RUNNING
+Are you sure?  Make sure it is really the case that nobody is getting any work
+done.  Check people on both network terminals and hardwired lines.  If you are
+certain, then type:
+    
+to get the attention of the 8080 front-end.  It should prompt you with:
+    KS10> 
+(if it doesn't, make sure the white "LOCK" switch hasn't accidently been set).
+Type:
+    SH<cr>
+to make the 8080 ask ITS to stop and go to Exec DDT.  If this works, AI will
+print a PI LEVEL 7 BUG message; go back to "Less Than Simple" and proceed from
+there.
+
+If ITS ignores the 8080's request, type "" again and this time follow it 
+with:
+    HA<cr> 
+This should force the processor to halt, so go back to "If AI Halts" and
+proceed from there.  If this does not work, cold boot the machine.
+
+                                  CALLING DEC
+If you determine that the machine needs to be serviced by DEC, call them at
+895-5711.  Tell them we have "2020 system number 84019009N" and describe the
+problem.  If they claim they can't find the system in their records, be
+insistent; the field service people can find the machine even if the phone
+answering people can't.  They will ask for the name and phone number of someone
+to contact; it doesn't matter whose you give them -- the field service people
+know MIT well enough that they don't need those.
+
+                               BRINGING AI DOWN
+You should only bring AI down with good reason, e.g. the machine room is over
+80, or it's time for PM.  First, log in:
+    <your uname here>$U
+(for instance, "DEC$U" if you're here to run PM.)  Then run
+    :LOCK
+It will prompt
+    _
+type
+    nDOWN
+where "n" is an integer not less than five; this will make AI bring itself down
+in "n" minutes (LOCK sees numbers in octal only).  This interval must be at
+least five minutes to give people a chance to clean up.  LOCK will ask you for
+a message explaining why you're bringing AI down; type in a short explanation
+and include your UNAME (so the users know who to blame) and end with
+    
+Then
+    Q
+to get out of LOCK and
+    $$U
+to log out.  Then just wait.

doc/kshack/consol.24

@@ -0,0 +1,134 @@
+-*- Text -*-				This is the file AI:KSHACK;CONSOL >
+
+
+                          Useful Console Commands
+
+
+Talking to the 8080:
+
+		Start talking to the 8080
+		Stops whatever the 8080 is doing
+		Stop talking to the 8080
+
+
+Multiple commands can be given on a command line separated by commas.  If
+the RP command is the last command in the line, then the line will be
+repeated.  It stops when you type any character.  An argument to RP causes
+it to repeat the command roughly that many times.  Useful are: "PM,RP",
+"SI,RP", "EN,RP".
+
+
+Booting the machine:
+
+BT		BooT
+		Resets the machine and boots from disk.
+		Normally this loads and starts DSKDMP.
+
+MT		MagTape boot
+		Resets the machine and boots from magtape.
+
+DS		Disk Select
+		Selects which disk drive to boot from.
+
+MS		Magtape Select
+		Selects which tape drive to boot from.
+
+
+Debugging PDP-10 code:
+
+ST pc		STart
+		DDT starts at 774000.
+		DSKDMP starts at 777700.
+
+SH		SHutdown  (Stop! Hold!)
+		Like raising switch 0 on a machine that has one.
+
+HA		HAlt
+
+CO		COntinue
+
+SI		Single Instruction
+
+LA addr		Load Address
+
+DM data		Deposit Memory
+
+DN data		Deposit Next
+
+EM [addr]	Examine Memory
+
+EN		Examine Next
+
+EX inst		EXecute instruction
+
+ZM		Zero Memory
+		This is VERY slow.  It starts with low addresses, so ZM
+		followed by  is good enough to clear most memory that
+		you care about.
+
+
+Debugging microcode:
+
+SM [upc]	Start Microcode
+		0 (the default) is the normal starting address.  1 just
+		writes a halt status block. 
+
+MR		Master Reset
+		Resets everything (whatever that is).
+
+CH		Clock Halt
+		Stops the microcode in its tracks.
+
+CS		Clock Start
+		Start the microcode up again.
+
+CP [steps]	Clock Pulse
+		Single steps the microcode one or many steps.
+
+EJ		Examine Jumps
+		Prints current upc and how the next upc is being computed.
+
+PM		Pulse Machine
+		Like "CP,EJ".
+
+TR upc		TRace
+		Like "PM,RP" except it stops when the current upc gets to
+		the specified value.  Also uses twice as much paper.
+
+TE [state]	Timer Enable
+		"TE 0" turns the timer off.  Makes it possible to single
+		step the microcode with paging enabled without looping
+		taking timer interrupts.  "TE 1" turns the timer on.  Just
+		"TE" tells you what its state is.
+
+CE [state]	Cache Enable
+		Turns the cache on and off.
+
+TP [state]	Traps & Paging
+		Turns traps and paging on and off.
+
+
+Halt Status Block:
+
+[ Note that the DEC microcode wants to write the halt status block 
+  starting at 376000. ]
+
+500:	MAG		506:	BRX	       514:	PI
+501:	PC		507:	ONE	       515:	XWD1
+502:	HR		510:	EBR	       516:	T0
+503:	AR		511:	UBR	       517:	T1
+504:	ARX		512:	MASK	       520:	VMA
+505:	BR		513:	FLG
+
+It does -not- work to start the machine and read the halt status block
+using DDT, you have to read it using the 8080.
+
+
+Halt Codes:
+
+     0:	Power Up			   102:	Bad Interrupt Table Pointer
+     1:	Halt Instruction		  1000:	Bad BWRITE Function
+     2:	Halted by 8080			  1004:	Bad NICOND Dispatch
+   100:	I/O Page Fail			  1005:	Failed Multiply Self-test
+   101:	Bad Interrupt Instruction	777777:	Halted after "SM 1" command
+