PDP-10.its/doc/sysdoc/pclsr.test

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.