From 92aafbb0400552e2f60e28fd0cb9d344966fcd50 Mon Sep 17 00:00:00 2001 From: Lars Brinkhoff Date: Tue, 14 Aug 2018 08:36:51 +0200 Subject: [PATCH] AI memo 261A: PEEK. --- doc/wp/peek.261a17 | 665 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 665 insertions(+) create mode 100644 doc/wp/peek.261a17 diff --git a/doc/wp/peek.261a17 b/doc/wp/peek.261a17 new file mode 100644 index 00000000..2f8a241f --- /dev/null +++ b/doc/wp/peek.261a17 @@ -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 +  \ No newline at end of file