github.com/PDP-10.its
1
0
Fork 0
mirror of https://github.com/PDP-10/its.git synced 2026-01-25 11:47:10 +00:00
Code Issues Releases Wiki Activity

AI memo 261A: PEEK.

Browse Source
This commit is contained in:
Lars Brinkhoff
2018-08-14 08:36:51 +02:00
parent fc524e4d6b
commit 92aafbb040
1 changed files with 665 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

665
doc/wp/peek.261a17 Normal file
View File

@@ -0,0 +1,665 @@
.DEVICE XGP
.FONT 1 "FIX25"
.FONT 2 "MICR25"
.font 3 "fixu25"
.page frame 56 high 74 wide
.title area footing line 56
.title area heading lines 2 to 4
.area text line 5 to 54 char 4 to 74
.place text
.turn on "_{\%"
.tabs 12,24,36,48
.every footing ({page},,{page})
.portion titlepage
.group skip 5
.begin nofill
_MASSACHUSETTS INSTITUTE OF TECHNOLOGY
%2_A. I. Laboratory%1
.skip 3
Artificial Intelligence
Memo. No. 261AFebruary 1974
(Revised 261, May 1973)
.skip 7
%2_P E E K%1
_Donald E. Eastlake
.end
.skip 4
PEEK is a utility program designed to
operate under the ITS time sharing system. It enables a user
to monitor a variety of aspects of the time sharing system by
providing, to the user, various periodicly updated displays.
.skip 8
Work reported herein was conducted at the Artificial
Intelligence Laboratory, a Massachusetts Institute of Technology
research program supported in part by the Advanced Research Projects
Agency of the Department of Defense and monitored by the Office
of Naval Research under Contract Number N00014-70-A-0362-0005.
Reproduction of this document, in whole or in part, in permitted
for any purpose of the United States Government.
.next page
.portion main
.every heading (PEEK,,February 1974)
.macro s1(sh) begin nofill;indent 0;group skip 3;send contents 
.skip
sh  {page}
.
%2
_sh_%1
.skip
.end
.macro s2(sh) skip;send contents 
\sh  {page}
.
.once indent 0
sh
.
.indent 6
.s1 (1. Introduction)
PEEK is a utility program designed to operate under
the ITS time sharing system. It enables a user to monitor
a variety of aspects of the time sharing system
by providing periodicly updated display output or
periodic printed output to teletype or line printer.
Just what information is being presented to the user
is controlled by PEEK's information mode. The available modes
are listed in Section 3 below. Section 5 describes how PEEK
determines which device to output on. Section 2 describes, in
general, how the user can input commands to PEEK.
The first line of all pages output by PEEK is as
follows:
.once indent 0
ITS %2xxx%1 PEEK %2yyy%1 %2mm%1/%2dd%1/%2yy%1 %2hh%1:%2mm%1:%2ss%1 STIME=%2DD%1:%2HH%1:%2MM%1:%2SS%1
In this line %2xxx%1 is the version number of the system in use
and %2yyy%1 is the version number of the PEEK in use (so
bugs can be matched to exact version). At the time
this memo was released, PEEK 271 was the version in use. %2DD%1:%2HH%1:%2MM%1:%2SS%1
is the length of time that the particular ITS system running
has been up and %2mm%1/%2dd%1/%2yy%1 %2hh%1:%2mm%1:%2ss%1 is the current date and
time according to ITS.
For many modes (those with the mode letter just
after the sub-Section number followed by a colon
in Section 3) a standard
second line is output for any core or disk memory
error. This line lists the following three errors if any
have occured:
\1. Irrecoverable disk errors.
\2. Core memory parity errors.
\3. Core memory failures to respond (NXM).
The last line of all pages output to the 340 display by
PEEK is a list of mode command letters which can
be given by light penning them with effects identical to
typing them.
.s1(2. Command Formats)
PEEK is an unusual program in that it interprets all
characters typed at it immediately at the interrupt level. Commands
to PEEK are all single letters or control characters,
sometimes preceded by a numeric argument. The commands listed in
Sections 5 and 6 of this memo take effect immediately and do not
affect any number that PEEK may be accumulating from digits typed
at it.
The commands listed in Section 3 change PEEK's information
mode. They may or may not make use of a numeric argument but all
clear any number PEEK may have accumulated. These
commands normally start PEEK immediately displaying
the information requested.
PEEK interprets digits typed at it as forming an octal number.
.s1 (3. Information Modes Available)
Below are listed alphabeticly all the different information modes of
PEEK. Normally, the information specified by the current
information mode is output to the currently selected output
device (see Section 5). After PEEK has done this it
waits a while and then repeats. This waiting period
is fixed at ten seconds for some information modes that present
information that is not expected to change. For most modes, the
waiting time is initially ten seconds but can be changed by the
%2Z%1 command (see Section 6).
.s2 (3.1 %2A %3A%1RPA Network Sockets)
The active ARPA network sockets and pseudo-teletypes
in the system are listed by this mode. After a heading line, one line
of information is given for each socket with the following
information: (1) the socket's logical index number, (2)
the index, UNAME, and JNAME of the user associated with the socket, (3) the
local socket number and the state of the socket, (4) the
foreign host and socket number associated with the
socket, and (5) the outstanding message and bit allocations on
the socket.
If any pseudo-teletypes (STY) are in use, they are listed
below all the sockets under a different heading line. On
each line is listed the following: (1) the user index, UNAME,
and JNAME of the procedure that has the STY open as
a teletype, (2) the teletype number of the STY, and (3) the UNAME
of the job that has the other end of the STY open.
.s2 (3.2 %2C: %1Disk %3C%1hannels)
This mode lists the channels actually in use for the
transfer of information between disk files and procedures. After
an explanatory heading line, one line is displayed for each channel
with the following information: (1) the logical channel number,
(2) the index, UNAME, and JNAME of the user procedure that has the channel
open, (3) various status letters as listed in the next paragraph,
(4) a count of the number of words transferred, and (5) the
system name and two file names of the file.
The following are the disk transfer
status letters that can appear in the disk channels mode output:
\A\File address altered by .ACCESS or otherwise.
\B\Core transfer hung on active buffer.
\E\Transfer has reached EOF.
\F\Hung in directory full.
\L\Channel locked.
\M\Master directory read.
\P\PDUMP mode transfer.
\R\Read.
\T\Track Usage Table read.
\U\User directory read.
\W\Write.
\?\Parity error on read.
\*\Delete file when channel closed.
.s2 (3.3 %2D %3D%1isk Directory)
This mode displays the disk master file directory ("M.F.D.
(FILE)"), which lists the names of all the user directories, and
then lists the user directory (".FILE. (DIR)") for the current
default system name associated with PEEK. If output is to the
340 display, it may be possible to change this default system name by
light penning one of the names in the master directory display.
.s2 (3.4 %2G %1Swap/Schedule Variables)
This mode displays information very similar to mode %2N%1 with certain
additional data related to the ITS scheduler & swapping routines.
In particular, the interrupt request words in the per job information
are replaced by the number of page swap in requests and the total
run time used is replaced by the average recent load represented by
the job in page-milliseconds.
In addition, an extra line is displayed for each top level
job showing the average percent of machine time used and load in
page-milliseconds for the tree topped by that job (but note that
all disowned jobs are combined).
.s2 (3.5 %2H: %1Memory Grap%3h%1 Display)
This mode is only available on output to the 340 display.
It shows a graph of actual core memory usage. Horizontal position
represents absolute address and vertical position represents type
of use. Words are displayed on the left edge of the screen
describing the use shown to their right. An occurrence of a block
of memory at several vertical positions represents a shared
block. (See also mode %2M%1.)
.s2 (3.6 %2I %1Available %3I%1/O Devices)
The symbolic devices implemented in the
ITS system in use are listed by this mode. Output is repeated
after a ten second delay.
.s2 (3.7 %2L %1Console %3L%1ines)
This mode simply outputs the system supplied
directory for device TTY. Currently this contains a header
line, and, for each teletype line in use, its TTY number, the
UNAME and JNAME of the procedure actually connected
to the console, core of this procedure, total core
of that user, and user index. A final line lists free core and
swapped out pages.
.s2 (3.8 %2M: %3M%1emory Use List)
A display is provided by this
mode of all of the uses to which actual core memory is being put.
After an explanatory heading line, one line is shown for each
use in decreasing order by actual core memory occupied.
Each line begins with the type of use, either the
UNAME and JNAME of a procedure or a single descriptive
word such as "FREE" for unused actual memory
or "DSKBUF" for disk transfer buffers. A "*" is
displayed just after the names of a stopped job. After the type
of use, the total number of actual core blocks dedicated to that
use is listed, followed, for procedures, by the following:
(1) the number of the highest virtual page
slot in use in that procedure, (2) the number of its pages that are
shared with any other procedures, (3) the number of its pages that
are not in actual memory but have been swapped out, (4) the total
number of page slots in use by the procedure, and (5) the resources
in use by the procedure (see Section 4.1).
.s2 (3.9 %2N: %3N%1ormal Mode)
This is the initial and most commonly used information mode in
PEEK.
.s2 (3.9.1 The Top)
After the normal top of display lines (see Section 1), %2N%1
mode displays one line of special information in the form of
several variable names followed by their values. These names
are as follows:
\MEMFREE Number of blocks of unused actual core memory.
\USRHI Number of blocks of user variables currently
allocated in the system.
\RNABLU Number of runable users (including the
PEEK displaying it).
\TRUMM Total user memory blocks of
active users.
\AUSOPG Number of active user swapped out blocks (pages).
.s2 (3.9.2 The Middle)
After the special information listed in the Section above,
a heading line is displayed followed by one line of information per
job. The tree structure of jobs is shown by the indentation of
the first few items after the user index number on each line. Top
level console controlled, disowned, or system jobs
are leftmost. Under each appears its inferiors
with its immediate inferiors indented one space, its second level
inferiors indented two spaces and appearing after their immediate
superiors, etc.
The information appearing for each job is as follows: (1)
the user index, UNAME, JNAME, and current system name,
(2) the run status, teletype status, and resources seized (see
Section 4), (3) the number of blocks of memory in use by the job
and the number of such blocks that are swapped out,
(4) the average percent of available machine time used recently
by the job, (5) two words of possible pending interrupts for the
job, and (6) the total amount of actual run time that has
been used by the job. The preceding list applies to output
to the line printer or 340 display (see Section 5).
Other output is abbreviated by dropping some of the information.
In particular, the JNAME is dropped for top level
non-disowned jobs and the UNAME dropped for their
inferiors.
.s2 (3.9.3 The Bottom)
Space permitting, two lines of special information
are output at the bottom of the %2N%1 mode display. The first
is a line of totals which gives the total memory in use by all
listed jobs (no deduction is made for shared pages), the average
total percent of machine time used recently by listed
jobs, and the total amount of run time for all listed jobs.
The last line shows the total amount of run time for all
users that have logged out during the system run so far, the
amount of machine time used by jobs killed by users who are still
logged in, and the amount of run time for the null job.
.s2 (3.10 %2S %3S%1ingle Tree)
This mode outputs the same information in the
same format as the %2N%1 mode except that only procedures in a single
job tree are included. The %2S%1 command should be preceded by
the user index of a job in the tree to be displayed. If no argument
is given the tree containing the PEEK will be displayed.
.s2 (3.11 %2T %3T%1ranslation Table)
The from and to device, system name, file names, and
applicability of the system translation table entries are listed
by this mode.
.s2 (3.12 %2U: %1DEC Tape Channels)
This mode is similar to the %2C%1 mode for disk except that it
applies to the DEC tape drives. As well as listing information
for open channels, it lists various information for each drive. This
per drive information includes the directional motion status of
the drive, the tape block the system is trying to move it to, and
the current believed position of the
tape. Also listed for each drive is a directory pointer, the
UNAME of the user who last caused a directory to be read in
for that drive, and the UNAME of the user, if any, to whom
the drive is "assigned".
If the directory pointer for a drive is -1 it means that
the system is not retaining a directory for that drive and
the tape can be safely flapped by hand. Otherwise, the
directory pointer gives the location in memory of the tape's
directory. Even after a tape has been flapped and no directory
is being retained for it, this mode displays the UNAME of the
last job to cause a directory to be read in from that drive.
.s2 (3.13 %2V %1Single Procedure %3V%1ariables)
Many of the user variables for a single procedure can be
inspected with this mode. After showing the procedure's names, run
status, and resources, the octal values of a number of named variables
are displayed. Then, under a heading line, the contents
of the procedure's ACs, input-output channel words and input-output status words are
listed. For open channels, the device and mode symbol is also
shown.
.s2 (3.14 %2X: %1A/D and D/A Multiple%3x%1ors)
This mode outputs the digitalization of all the multiplexed
analog to digital input channels and the value being output to
each of the multiplexed digital to analog channels.
.s2 (3.15 %2Y %1DEC Tape Director%3y%1)
This mode simply outputs the system supplied
directory for a particular DEC tape. It should be preceded by
a drive number.
.s2 (3.16 %2% %1Scheduler History)
Users that have recently caused schedules by being
blocked are listed by this mode. Because the percent of overhead
time in its is related to the frequency of schedules, this mode may
be useful in finding the cause of excessively frequent schedules.
After a heading line, it lists procedures recently scheduled
in order of decreasing number of schedules. For each procedure
it gives (1) the user index, UNAME, & JNAME, (2)
the number of recent schedules, (3) the average run time per schedule,
(4) the percent of schedules caused by blocking caused by page faults,
(5) the most common PC when scheduled (with
an * in front if executive mode) and the number of schedules at
that particular PC.
.s2 (3.17 %2? %1Explanation Mode)
This mode outputs a list and brief explanation of PEEK's
commands. Output is repeated after a ten second delay.
.s1 (4. Special Output Field Formats)
.s2 (4.1 Resource Letters)
The following are the system resource letters used in modes
%2G%1, %2N%1, %2M%1,
%2S%1, and %2V%1 explained above:
\%36%1\The procedure has control of the PDP-6.
\%3B%1\The procedure has control of the IBM compatible magnetic
tape drive (MT0).
\%3C%1\The procedure is now using, or was the last to use, the
ITS core allocator.
\%3D%1\The procedure has control of the DEC 340 display (DIS).
\%3I%1\The procedure is in "IOT-user" mode (.IOTLSR). This letter
can be present for more than one procedure.
\%3L%1\The procedure has control of the line printer (LPT).
\%3M%1\The procedure has seized the master user facility (.MASTER).
\%3P%1\The procedure has control of the CalComp plotter (PLT).
\%3R%1\The procedure has control of the paper tape reader (PTR).
\%3S%1\The procedure has control of the Sylvania tablet (TAB).
\%3T%1\The procedure has control of the paper tape punch (PTP).
\%3V%1\The procedure has control of the vidisector (NVD).
\%3%%1\The procedure is in real time mode (.REALT).
.s2 (4.2 Process Run Status)
The following Sections explain
the procedure run status field output by
modes %2G%1, %2N%1, %2S%1, and %2V%1:
.group
.s2 (4.2.1 Prefix)
One of the following characters will appear at the beginning
of the status code:
\>\Swap blocked. This procedure is being blocked from running
by the swap scheduler to stop thrashing.
\_\Desired out. This procedure is not swap blocked but the
swap scheduler has decided to swap it out.
\*\PI in progress. This procedure is not swap blocked or
desired out but is processing a software interrupt.
\ \(Space) None of the above apply.
.apart
.s2 (4.2.2.1 Body If Stopped)
If a procedure is stopped, the body of its status field is a number
output in an unusual format. The first two octal digits of the number
are printed as an unsigned number, then an "!" is
output, then the rest of the number with leading zeros eliminated.
The resulting figure to the right of the "!" is the count of
transient reasons for the procedure to be stopped. If this count
is persistently non-zero, an internal system error has probably
occurred.
In the figure to the left of the "!", the top four bits have special
meaning. The 40 and 20 bits are used by the core allocator when it is
moving or modifying the core image of procedures. The 10 bit is the
most common and is the only bit directly controllable by user procedures to
start and stop other procedures. The 4 bit is used as a temporary
stop bit by some system calls. If the 40, 20, or 4 bits stay on
persistently, there is probably something wrong.
.s2 (4.2.2.2 Body If Hung)
A procedure can be hung (execution temporarily blocked) either due
to waiting for a page of its core image to be swapped in or due
to a wait for some condition in the execution of a system call.
In the case of a hung system call, PEEK simply displays the
name of the system call or, for an input-output transfer, the device
name and transfer type. If the procedure is blocked waiting for
a page to be swapped in, the word "PAGE" is displayed, unless
the page is needed to handle a software interrupt to the user in
which case "IPAGE" is displayed.
.s2 (4.2.2.3 Body If Running)
If a procedure is running in user mode, the word "RUN" is
displayed as the body of its status field. If it is executing a
system call, the same word is displayed as if it were hung in that
system call (see Section 4.2.2.2) except that a "+" is added in
front. There are several reasons, however, that a procedure can be
running in executive mode without haveing executed a normal system
call. For example, if the procedure has just executed an illegal
instruction, "XXX" will be displayed, and if it has
just executed a UUO that will be relected back to it as a user
UUO, the word "UUO" will be displayed.
.s2 (4.2.3 Suffix)
Under some circumstances, a system call being executed by a
procedure, say P1, will have to make sure that a
second procedure, P2, is temporarily not running in executive mode.
This may necessitate P1 waiting until P2 is interruptible if P2
is initially running in executive mode. If PEEK is run
during this waiting state, a ">" followed by the user
index of P2 will appear at the end of the status field for
P1 and a "<" followed by P1's index correspondingly after P2's
status. This situation is referred to as P1
PCLSRing (P-C-losering) P2.
This state should be extremely transient. If you see this suffix
display even once, you should suspect some problem.
.s2 (4.3 Process Teletype Status)
The teletype status field displayed for a procedure will be one of the
following five things:
\DISOWN\The procedure is disowned and can not have a
console associated with it.
\Tn\The procedure is immediately controlling and being controlled
by "teletype" number n.
\>\The procedure has assigned its teletype downward in its
procedure tree. The number should be displayed by one of its inferior
procedures.
\<\The procedure has had its console taken away by a higher level
procedure. The number should be displayed by some other procedure
in its procedure tree.
\?\There is no evidence of a console ever being directly associated
with the procedure. (It might be a newly created inferior.)
.s1 (5. I/O Control)
PEEK has four different modes of output (not to be confused
with the information modes listed in Section 3.) Two of these,
which provide the most verbose output, are intended for output to the
line printer and the 340 display. The remaining two modes are for
printing consoles (teletypes) and alpha-numeric display
consoles (Datapoints).
The exact information displayed for various information modes is
affected by this output mode. Especially for the more complex
information modes, like %2N%1, there is an abbreviated version of the
output for printing consoles, an intermediate one for alpha-numeric
displays, and a complete version for the line printer and 340
displays. In the descriptions of information modes, usually the
most complete output form was explained.
PEEK starts in either the printing or alpha-numeric display modes,
depending on the nature of the user's console, unless it finds that
the user's console is at a 340 screen or it can not open device TTY
for output. In either of these two cases it tries to use the 340
display output modes. (If the 340 display is not
tried, a flag is set that is cleared only
by ^Y which inhibits further attempts at using the 340.) The
following commands can be used to change PEEK's output mode:
\^B\This switches output to the line printer if it is
available. If it is not available, the output device
will be unchanged.
\^E\This command releases the line printer if PEEK
is using it. It then resets the output mode through the same procedure
as is used when PEEK is first started.
\^N\This command releases the 340 display, if PEEK
is using it, and then it sets a flag which inhibits any PEEK
attempt at using the 340. This flag is cleared only by
^Y. Finally, PEEK changes to type out or alpha-numeric
display mode.
\^Y\PEEK will try to seize the 340 display for output
on receipt of this command. If it succeeds, the output mode
will be set to the 340. Otherwise, output will revert to
the user's console. In either case, the flag mentioned under
^N above is cleared.
.s1 (6. Miscellaneous Commands)
The following are miscellaneous PEEK commands:
.skip 2
.begin preface 0
\%2P%1\This is the %3p%1roceed command.
\If PEEK is running under a HACTRN, this command
will return control of the user's console to HACTRN but leave
the PEEK running. If 340 display or line printer output
is selected, it will continue. If the PEEK is running
as a top level job, this command will cause it to logout.
\The %2P%1 command uses .VALUE to return the string ":PROCED "
to PEEK's superior procedure.
.skip
\%2Q%1\This is the %3q%1uit command.
\If PEEK is running under a HACTRN, this
command will destroy the PEEK it is typed at and return
control of the user's console to HACTRAN. If the PEEK
is running as a top level job, this command will cause
it to logout.
\The %2Q%1 command uses .VALUE to return the
string ":KILL " to PEEK's superior
procedure.
.skip
\%2Z%1\This is the do%3z%1e command.
\It takes a numeric argument and sets the standard
update delay to that number of seconds (see Section 3).
.skip
\ \(Space) This is a sort of null mode command. It does
not change PEEK's information mode but causes it to immediately
begin updating the current output.
.end
.next page
.nofill
.s1 (References)
See also the following AI memos:
\##238\ITS Status Report, D. Eastlake, et al
\##161A\ITS 1.5 Reference Manual, D. Eastlake, et al
\##147A\DDT Reference Manual, Eric Osman
.portion contents
.indent3_6
.preface 0
.every footing ()
.nofill
.skip 1
%2
Table of Contents%1
.skip 3
.receive