OPA - A PRIVILEGED TASK TO DISPLAY A SNAPSHOT MAP OF THE CURRENT CONTENTS
	OF POOL!!!! (for RSX-11M 3.2)

NOTE WELL:  This program is sufficiently valuable to all system managers/
programmers who have pool space problems that it is (to my mind) well worth
the risk of using.  However, it is necessary while this program is scanning
through pool to be on the system stack.  It has been made somewhat more
rugged than the 3.1 version submitted for San Diego DECUS, as it now catches
its own odd address or memory protect traps, and reports them rather than
causing a system crash.  It is, however, conceivable that it might corrupt
something in the EXEC, although rather less likely.  The biggest problem
from overuse is that some device drivers may require frequent access to
system state (i.e. forking) in order not to lose interrupts.  While this
task is collecting data, the EXEC cannot handle fork requests.  It does,
however, seem to work well on our 11/34 system, and has given us a
good deal of insight into what fragments and/or gobbles up pool.

	The program will identify about 95% of the data structures kept in
pool, in its current version.  Remaining known structures not identified are:
some AST control blocks (see version 3.2 CDA manual description of same to see
why I haven't yet tracked all of them down).
RECEIVE packets (certain tasks [notably TKTN, LOADER] have non-standard message
sizes, and without significant checking any attempt to map those packets along
with the standard ones would certainly cause difficulties).
FCB's for other than INDEXF.SYS (I have done the window blocks for files
which are open by tasks currently in memory, but didn't bother with the
associated FCB's since many are buffered in the ACP anyway.)
Buffers allocated by the half-duplex terminal driver for as-yet incomplete
unsolicited input, or completed messages for MCR from either terminal driver.
Offspring control blocks, which I have looked for but have not yet found
the linkages as suggested in the CDA manual.
OTHERS which I don't remember at the moment.
	The program output will appear on the invoking terminal, unless the
task is installed and the LUN reassigned to something like the lineprinter.

Output format:
1st line: # of fragments of pool
2nd line: total words of pool
next n lines: addresses and sizes of all free segments in pool
next line: total # words free in pool
Then the good part:
In this display, each ASCII character represents a minimum allocatable piece
of pool, i.e. 4 bytes.  Each line is 64(10) characters, corresponding to
400(8) bytes of pool.
Free area is shown by --------
Used but not identified is shown by ????????
<A> represents an attachment discriptor block
<An> is a specifed-ast control block, where n is the ast type code.
<M is a mount control block
<CP> is a checkpoint file control block
<TCB  -  ...MCR> is the task control block for task ...MCR, e.g.
<Cn> is a clock queue control block, where n is the type (see system data
structure definitions for types)
<Lx is a logical assignment control block.  The most interesting from the
point of pool fragmentation is <L/> which is a login assignment, which of course
will not move while the terminal is logged in.
<VCB  - DBn:> the volume control block for device DBn:
<FCB @DBn:> a file control block found for a file on DBn:
<WB=========> a window block for a file
<I DV: > an interrupt control block for device DV:
<DCB+UCB+SCB = DV:##> The data structures for a loadable driver with a loadable
database.  This may not be quite right if you have a 22-bit system with a DMA
device that does not say it is but still allocates space in the SCB for saving
the UNIBUS mapping register assignments.  There is a real example of such a
device (the VERSATEC DMA interface)!  It also will not handle data structures
which have oddball SCB lengths for other reasons.
<HEADER POOLFL###########> is of course a task header for task POOLFL.
Note that this is one of the significant pool fragmenters, particularly if
you get either MCR or an ACP checkpointed, since the header then will wind
up in the middle of pool somewhere when the task comes back in, and since the
task never exits (just stops) the header never goes back out.
<IO DVn:> is an I/O packet either currently in use or queued to device DVn:
Note that this does not include 'buffered I/O packets' used by the full-duplex
terminal driver.  Those appear (apparently) as AST packets but I haven't
tracked them down yet.
<PKT OPT> is a saved I/O size packet for QIO optimization.  These devils will
really fragment your pool, as they get allocated mostly when your system is
busy, then hang around later so it's hard to move/get rid of them, except of
course by turning off the optimization (we've had to do that to avoid pool
problems occurring on a regular basis).
( FCSRES) is a PCB for a permanent partition,
while (/POOLFL) is a subpartition control block, typically for the partition
control block for a running task in a system controlled partition. A sub
partition control block for a driver is (/ ZB:  )
<MCR LINE FOR ...RMD> is an example of a task invoked as an external MCR
function (i.e. JNK<cr> for a task called ...JNK) which hasn't gotten around
to doing a GMCR$.  This structure may stay until the task exits, so you
should remember to to a GMCR$ for any task which will be invoked as an external
MCR function and which will be active for awhile, even if it doesn't need to
get any information from the command line.

A sample output might look like:

FREE POOL FRAGMENTS=17.
TOTAL WORDS OF POOL=8940.
FREE SEGMENT LIST:
055064-055067 2.
055234-055237 2.
055430-055437 4.
.
.
.
070634-071753 296.
072004-071753 4178.
TOTAL FREE WORDS=4652.



POOL MAP:
053400:                                                              <A>
054000: <A>-<A><TCB = ...LOA><C0><C0>-<VCB=DB0:><FCB @DB0:>(/ TM:  )<M(/
054400:  VT:  )<HEADER F11ACP############><TCB = ...SLG>(/...PSZ)<A>---<
055000: A><WB==================================><CP>---(/ PL:  )--------
055400: -<DCB+UCB+SCB = TM:%%><A4>--<L/<TCB = ...PSZ>-------------<HEADE
.
.
.
071000: #############<A><A>????????<C2><C2><HEADER POOL  ###############
071400: ##><HEADER ...PSZ###########><IO LP0:>------<C2>----------------
072000: <MCR LINE FOR ...JNK>-------------------------------------------
072400: ------------------------------------------------<L/<L/<PKT OPT><
073000: PKT OPT>----------------------------------<PKT OPT>-------------
.
.
.
117000: -----------------( SHFPAR)<HEADER TKTN  ###########><TCB  -  TKT
117400: N  >( TKNPAR)<HEADER ...LDR###########><TCB  -  ...LDR>( LDRPAR)



Note that in general the stuff at the top of pool is put there by VMR, which
incidentally from this program I learned does a terrible job by not filling
any holes created by removing tasks, for example.

Comments and suggestion are welcome, but please don't complain if your system
crashes.  Hopefully I or others will get around to doing a few more data
structures,and there will be fewer areas labelled ????????.  Keep in mind
that it will never be possible to do all areas, since privileged tasks and
drivers may take blocks out of pool which are not referred to by any standard
data structures.  Also some structures are pointed to only by things in
the task headers, and if the task is checkpointed there is no way to find
them.  A good example is window blocks for files opened by various active
tasks.

	Jim Neeland
	Hughes Research Labs
	3011 Malibu Canyon Rd.
	Malibu, California 90265
	(213) 456-6411 ext. 333