Documentation for PCLSRing.

Makefile

@@ -30,7 +30,7 @@ DOC = info _info_ sysdoc sysnet syshst kshack _teco_ emacs emacs1 c kcc \
       chprog sail draw wl pc tj6 share _glpr_ _xgpr_ inquir mudman system \
       xfont maxout ucode moon acount alan channa fonts games graphs humor \
       kldcp libdoc lisp _mail_ midas quux scheme manual wp chess ms macdoc \
-      aplogo _klfe_ pdp11 chsncp cbf rug
+      aplogo _klfe_ pdp11 chsncp cbf rug bawden
 BIN = sys2 emacs _teco_ lisp liblsp alan inquir sail comlap c decsys \
       moon graphs draw datdrw fonts fonts1 fonts2 games macsym maint imlac \
       _www_ hqm

doc/sysdoc/pclsr.test

@@ -0,0 +1,88 @@
+06/07/87 21:26:03,4751;000000000000
+Date: Sun,  7 Jun 87 21:13:07 EDT
+From: Alan Bawden <ALAN at AI.AI.MIT.EDU>
+To:   DLW at SCRC-STONY-BROOK.ARPA
+cc:   ALAN at AI.AI.MIT.EDU, MOON at AI.AI.MIT.EDU, TK at AI.AI.MIT.EDU
+Re:   PCLSR test mode
+
+    Date: Sat, 6 Jun 87 17:33 EDT
+    From: Daniel L. Weinreb <DLW at Symbolics.COM>
+    Hi.  Have you ever used ITS's PCLSR test mode?
+
+Nope.  I've never written anything that warranted it.
+
+    I'm thinking about trying to implement something analogous, to help
+    people debug "transactions", which can abort and restart and so are
+    essentially subject to something much like PCLSRing.  How does the test
+    mode work, and is it useful?  Thanks.
+
+Its kind of a kludge actually.  
+
+I guess you remember that if you want a particular piece of code to be
+tested, you insert calls to this macro (PCLT) at points where you want to
+be PCLSRed from (typically right before you might go blocked).  Then PCLSR
+test mode lets you run the system call until it reaches one of the test
+points you have marked.
+
+There are three modes that control what happens each time the job being
+tested reaches one of the test points:
+
+1.  In "hold" mode, ITS PCLSR's the job and stops it as if the hacker had
+just typed a ^Z.  If the hacker P's the job, it will run to the exactly
+the same test point and then PCLSR and halt again.  Thus the hacker can
+test the same point over and over again.
+
+2.  In "advance" mode, each time the hacker P's the job it runs to the
+same test point as last time, and then sets a flag that causes the job to
+PCLSR and halt at the -next- test point, where and whenever that happens to
+occur.  Thus the hacker can test all of the test points in succession in a
+particular path through a system call.
+
+3.  "Advance but don't halt" mode is just like advance mode except that the
+job is not halted each time it is PCLSRed, it just keeps running and thus
+immediately starts the system call over.  This lets the hacker exercise a
+system call over and over, presumably waiting for a bug-check to trip.
+
+The kludge is how ITS decides you have reached "the same test point".  You
+can't just test the PC where the PCLT macro occured, because that might be
+in a subroutine that was called from several places.  So ITS crawls down
+the stack looking for likely return addresses to try and figure out the
+call-chain that got to the current routine.  (Its heuristic is that any
+word whose right half address a word in system code that immediately
+follows any PUSHJ P, is a return address.)  These return addresses are all
+hashed together, and the pair consisting of this hash and the PCLT's PC are
+used to distinguish one test point from another.
+
+(Actually you could hash the PCLT's PC in with the others, but keeping it
+separate means that you can -first- compare the current PCLT's PC with the
+one you are looking for, and if it doesn't match you don't have to bother
+with the slow hash computation.)
+
+Additionally, it is possible that a PCLT might occur in the middle of a
+loop so that neither its location, nor the call-chain, can be used to
+distinguish what the hacker might want to treat as separate test points.
+To cover this case there is a location (PCLIDX) whose contants are always
+hashed in with the return addresses.  By storing the loop-counter, or
+something else that varies each time around the loop, in PCLIDX, the hacker
+can cause these test points to be distinguished.  (This mechanism doesn't
+extend to nested loops, but it's only used in a single place.)
+
+Of course there are lots of ways you can imagine this hash test becoming
+confused (by extra gubbish on the stack that only -looks- like a return
+address and that happens to vary from call to call, or by routines that use
+other calling conventions, etc.), but I imagine that in practice the hacker
+doesn't get shafted all that often.
+
+Here is another hazard that can bite the hacker using this feature:  In
+advance mode, after ITS has found the previous test point and has set the
+flag that causes the next test point to trap, but before it actually gets
+there, it may happen that the job is PCLSR'd for some ordinary reason (like
+the job being swapped out).  Then the next time the job does any system
+call the -first- test point in that system call will trap.  This is
+probably sufficiently unlikely that its not worth fixing; if it ever
+happened to anyone, he would just grumble and start over.
+
+Is it usefull?  I don't really know.  It has never been used in my memory,
+but ITS hasn't changed all that much during that time.  I seem to recall
+Moon once remarking that he had never seen it used either, but I believe
+that TK once told me that it had flushed its share of bugs.