From 196263051c88d1d9c257c1601ec6041354a92671 Mon Sep 17 00:00:00 2001 From: Lars Brinkhoff Date: Mon, 16 Jan 2017 18:10:42 +0100 Subject: [PATCH] Add most missing SYSDOC files. --- doc/info/netwrk.1 | 118 ++ doc/sysdoc/-read-.-this- | 1 + doc/sysdoc/chaord.57 | 2184 +++++++++++++++++++++++ doc/sysdoc/chaos.file | 760 ++++++++ doc/sysdoc/clo.100 | 169 ++ doc/sysdoc/devdoc.5 | 108 ++ doc/sysdoc/grphcs.21 | 638 +++++++ doc/sysdoc/intrup.108 | 562 ++++++ doc/sysdoc/itstty.41 | 3571 ++++++++++++++++++++++++++++++++++++++ doc/sysdoc/job.100 | 782 +++++++++ doc/sysdoc/locks.108 | 360 ++++ doc/sysdoc/magtap.101 | 206 +++ doc/sysdoc/ncp.100 | 841 +++++++++ doc/sysdoc/tv.100 | 310 ++++ doc/sysdoc/usets.119 | 1405 +++++++++++++++ doc/sysdoc/usr.102 | 823 +++++++++ 16 files changed, 12838 insertions(+) create mode 100755 doc/info/netwrk.1 create mode 100755 doc/sysdoc/-read-.-this- create mode 100755 doc/sysdoc/chaord.57 create mode 100755 doc/sysdoc/chaos.file create mode 100755 doc/sysdoc/clo.100 create mode 100755 doc/sysdoc/devdoc.5 create mode 100755 doc/sysdoc/grphcs.21 create mode 100755 doc/sysdoc/intrup.108 create mode 100755 doc/sysdoc/itstty.41 create mode 100755 doc/sysdoc/job.100 create mode 100755 doc/sysdoc/locks.108 create mode 100755 doc/sysdoc/magtap.101 create mode 100755 doc/sysdoc/ncp.100 create mode 100755 doc/sysdoc/tv.100 create mode 100755 doc/sysdoc/usets.119 create mode 100755 doc/sysdoc/usr.102 diff --git a/doc/info/netwrk.1 b/doc/info/netwrk.1 new file mode 100755 index 00000000..8a28fa27 --- /dev/null +++ b/doc/info/netwrk.1 @@ -0,0 +1,118 @@ +-*-Mode:Text-*- + +File: NETWRK Node: Top Up: (DIR) + +This file attempts to describe various computer networks of two types -- +those to which ITS systems are directly connected, and those which are of +interest to the ITS user community because they link up personal computers or +research institutions that are not accessible by the first kind of network. +There are two networks to which ITS machines are connected: the ARPANet and +the Chaosnet. These networks support file transfer, mail, remote login, and +other services -- they may appear to be quite similar to the user, but have +differing implementations. All the other networks documented herein are +mostly for mail and file transfer. + +* Menu: + +* ARPANet: (Internet) The Arpanet + +* Chaosnet: (CHAOS) The Chaosnet + +* User programs for either of the above + +* Internet: (Internet) The Internet + +* CSNET: (CSNET) The NSF CSnet. + +* PCNET: (MC:PCNET;PCNET INFO) Personal Computer Network + +Internet + +The Internet is a very large computer network that connects various +educational, military, and commericial establishments, all involved in some +way in computer science research. It is actually a ``catenet'' of many +computer networks that run a protocol, the Internet Protocol, to allow +packets to be sent from one host to another, possibly through several other +networks. An accompanying protocol called TCP provides a reliable byte +stream that programs can use, thus ignoring data errors and all the other +nitty-gritty details involved in getting a packet from here to there. + +The ARPANet is perhaps the most famous of the Internet networks. It +stretches from Massachusetts to Stanford. Before the days of Internet, it +ran a protocol called NCP, which, unfortunately, was beginning to show its +age. (The ARPANet is at least ten years old.) Because the net had ceased to +become a research project, turning into a heavily-used resource, it was +decided that it would be interesting, now that a long-haul network was shown +feasible, to try to connect various networks together. Then the hosts on +these networks, all differing in one characteristic or another, could talk to +each other without having to contact special hosts that would translate one +high-level protocol into another. IP came out of this desire. (In a false +start, all the internetwork issues were going to be resolved in the TCP +layer, but the details were wisely factored out.) So the ARPANet become +``just another'' network in the Internet, although it still carries most of +the long-distance traffic. + +When the switch from ARPAnet to Internet in software was made, it was a +cataclysm underneath, but the user could not notice much. Most of the +high-level protocols used in the NCP days were simply carried over: Telnet, +SUPDUP (where it was implemented), FTP, and SMTP. Some ITS user programs +contain commands to switch from TCP to NCP mode, though this is not usually +required. + +At MIT, Internet appears in a variety of ways. First, there is the ARPANet. +The second type of network to embrace IP was the LCS/Pronet Ring net. The +main users of these networks are the LCS VAXes and many of the Athena +machines. Thirdly, there are Ethernets at Tech Square who run IP, usually +along with Chaosnet. The users of this mode include some VAXes at the AI +Lab, and some LCS machines. And last, but not least, the Chaosnet can also +support Internet (after much heated discussion). A few Unix machines have +taken this option. + +As for the ITS machines, they all connect to the Internet through their +ARPANet IMPs. The Internet host tables can be found in SYSENG; HSTNIC > +ITS implements both server and user programs for FTP, TELNET, and SUPDUP. +The MLDEV is also supported. There is also an SMTP (mail) server. Sources +for various TCP-related programs can be found in the TCP; directory on MC. +For programmers, there is a quick rundown of the ITS TCP interface (and +documentation that applies to network system calls in general) in +TCP;TCPDOC > The network status can be checked with the PEEK program. + +CHAOS + +The Chaosnet was developed at the MIT AI lab as a local network to allows +Lisp Machines (CADRs, specifically) to access files on AI and MC. Its +success caused it to become the most widely used local network at MIT. The +following operation systems have support Chaosnet: LispM, ITS, Twenex, Tenex, +Unix, Multics, VMS, Seconds, MINITS, and MOS. The last three are used +mainly in terminal concentrators and bridges. Chaosnet has also been used at +Yale, TI, and many other Lisp Machine installations. The definitive Chaosnet +documentation can be found in AI Memo 628, ``Chaosnet,'' by David Moon. + +Chaosnet started out being supported by special Chaosnet hardware, but is now +mostly used with Ethernet II hardware. Leased serial lines and microwave +links have also been used to run Chaosnet. It is stressed that Chaosnet is +local network, but it has been used with some success transcontinentally. + +On ITS, most programs (except FINGER) will automatically chose to use the +Chaosnet. Here is a list of current user and server programs: + +Service Protocol User Server +-------------------------------------------------------------- +Remote Login TELNET :TELNET yes + SUPDUP :SUPDUP yes +File Access FILE :CFTP yes +Mail MAIL (COMSAT) yes + SMTP (COMSAT) yes +TTY send SEND :SEND yes + CONVERSE + +There are also the usual servers for HOSTAB, TIME, UPTIME, and STATUS. All +ITS machines offer a TCP server as well -- it allows Chaosnet hosts to +contact Internet hosts at a specified port number. There is also a GMSGS +server and a LIMERICK server. + +For contacting a host at an arbitary contact name, use + + :MOON;CHARFC host contact + +The K PEEK mode will show that status of the Chaosnet. diff --git a/doc/sysdoc/-read-.-this- b/doc/sysdoc/-read-.-this- new file mode 100755 index 00000000..a85e6a9d --- /dev/null +++ b/doc/sysdoc/-read-.-this- @@ -0,0 +1 @@ +This directory (SYSDOC) contains system documentation for ITS. diff --git a/doc/sysdoc/chaord.57 b/doc/sysdoc/chaord.57 new file mode 100755 index 00000000..a27a94b5 --- /dev/null +++ b/doc/sysdoc/chaord.57 @@ -0,0 +1,2184 @@ +;skip 1 +;list +;lftmar 350 +;kset 20fg + + CHAOS ORDER + + **** DRAFT **** +NOTES: +Work more on dynamic flow control, see end of that section. +Data grams seem to have a bug that the two parties can never + agree on whether they both agree that it really happened. Am I losing? +Flush cruft at end? +Add QES, which is the same as RFC but implies you expect ANS? Any point to it? +For ITS, a flavor of listening which queues RFCs coming in while index is busy, + or otherwise avoids that timing problem. +------- +This table of contents has not been kept up to date ******* + + Goals + Non-goals + Hardware Assumptions and Constraints + +User appearance + + Connections + Contact Names + ITS implementation + Lisp Machine implementation + +Network Control Program + + Packets + Hosts attached to more than one subnet + Subnet and Host numbers + Packet numbers + Indices + Routing + Operations + Table of packet field use vs opcode + Flow and Error Control + Dynamic Window-size Adjustment + Uniquization + Media Handlers + Buffers + ITS System Calls + +Comparison with LCSNET + Principle differences + High priority data packets, interrupts, and flushing + Data grams + Multiple messages per packet + Checksums in the packet + Host-independent user-level protocols + Very Small Hosts + +Transmission Media + + Ethernet + TEN11 Interface + DL10 & DTE20 + Asynchronous line + +Higher-Level Protocols + + Telnet + File Access + Mail + Locate-named-service + +>Goals + +High speed communication between processes running in various local machines. +By "high speed", I mean much faster than the Arpanet. +At least comparable to TU20 magtape (30000 characters/second), +about 10 times the speed of the Arpanet. +(30-50 kcps seems to be the measured preformance, with ITS, 10/2/78) + +No undetected errors in data transmission. + +Not to depend on a particular medium. (However, we are compromising +by picking a fixed packet size. The simplicity and efficiency are worth it.) + +Simple enough to put in small pdp11's. Also, simple to the user. + +As much power as the Arpanet but, hopefully, a lot less hair. + +Work well for both "telnet" and "file transfer." + +The initial implementation in ITS should have the "in-system" part as +small and simple as possible. This includes no per-host tables +in the NCP, which allows large nets and easy reconfiguration. +There is, of course, a host-name to address translation table +used by "user" programs. The NCP has to have a per-subnet table +which remembers where the bridge(s) to that subnet from +the local subnet are. + +The acknowledgement protocol must be designed not to limit +performance. + +Statistical flow control ((see below.)) + +Avoid bottlenecks such as the Arpanet "control link". Be immune +to transmission medium failures which cause deleted, duplicated, +or out-of-order packets. + + +>Non-goals + +Byte sizes other than 8 bits. (pdp10 binary transmission should +be part of a user-level file-transfer/ML-device protocol.) + +Compatibility with the Arpanet. + +Substituting for TEN11 interface functions such as running +the AI TV11 and XGP. + +Automatic routing will be deferred. Initially the routing +tables will be assembled into the programs. A host needs +one routing table for each subnet it is connected to +(or one for each network interface it possesses.) + + +>Hardware Assumptions and Constraints + +Transmission is physically in "packets" which have headers, rather +than in, e.g., continuous streams. + +The chaos net (ether) interface limits the physical length +of a packet to 4097 bits including overhead bits. The net result +is the maximum number of data bytes (excluding the header +defined by this protocol) in any packet is 488. This limitation +will be extended to the whole network (to keep things simple). +However some provision will be made for a possible network-wide +packet-size expansion, which has already been done once. + +All transmission media will be assumed to be highly-reliable +but not perfect; "perfect" reliability will be assured by having +the two ends of a connection use an acknowledgement protocol +which detects lost messages. Transmission media are required +to lose any messages that they don't deliver intact. (I.e. there +must be hardware checksums.) + +>User appearance + +The network allows user processes in various machines to +communicate with each other in various ways, for instance, +in imitation of a terminal, or in imitation of a disk file +system. These facilities are built on top of the basic +capability to send "packets" (a header plus some data in the +form of 8-bit bytes) through the network. The network undertakes +never to lose or garble any packets, except when the connection +is cut off entirely. + +This document defines the low-level, "in-system" part of the +protocol. On top of this, special programs (running in user-mode) +will implement the higher-level protocol that the general user +program sees. These protocols and programs won't be discussed +further in this document, but remember that the strange packet +formats and so forth are not seen by most user programs. + +>>Connections + +When two processes wish to communicate, they establish a +connection between them. This connection allows two streams +of packets to flow, one in each direction. [Explain why +connections should be bi-directional rather than uni-directional. +Basically that's what you always want, and it makes things simpler.] + +Connections are essentially the only facility provided by the network. +However, when first establishing the connection it is necessary +for the two processes to contact each other, and make each +other known to their respective operating systems. In addition, +it is often the case (in the usual user-server situation) that +one of the processes does not exist beforehand, but is to be created +and made to run a specified program. + +>>Contact Names + +The way we choose to implement contacting is to say that one process +is always a "user" and one process is always a "server". The server +has some "contact name" to which it "listens". The user requests its +operating system to connect it to a specified contact name at a +specified host. If a process at that host is listening to that +contact name, the two are connected. If no one is listening to that +contact name, the operating system must create a server process +which will load itself with the appropriate program and connect up. + +Discovering which host to connect to to obtain a given service +is an issue for higher-level protocols. It will not be dealt +with at all initially (that is, there will be a table of host +names and numbers and the user will have to enter the name.) + +Once the connection has been established, there is no more need for +the contact name, and it is discarded. Indeed, often the contact name +is simply the name of a network protocol (such as "telnet") and several +users may want to have connections to that service at the same time, +so contact names must be "reusable." (In the other common case, the +contact name will be a "gensym".) + +As far as the operating systems involved are concerned, contact names +are simply arbitrary ascii strings defined by user programs. It is +expected that the various higher-level protocols will define standard +contact names; for instance, to get the telnet protocol one would +connect to "telnet"; to get the file transfer protocol one would +connect to "file-transfer". If a machine receives a request to connect +to a contact name which no one is currently listening to, a server +process must be created and made to execute a program which decides, +from the contact name, what server program to load and execute, or else +to refuse the request for connection. + +Contact names have no relation to file names; they are simply +a device for introducing two processes to each other. If one was +using the network to transfer a file, one would first contact +the file transfer server at the appropriate host, then send a +packet containing the name of the file to be accessed. + + +>>ITS system calls + +Ordinary user programs will not access the network directly; they will +go indirectly through a job-device or sty-type program which will +use a higher-level protocol to make the network look like what the +user wants, the traditional things being a terminal and a disk +file system. + +Since these intermediate user-mode programs for using the network will +exist, there is no reason for the interface to the low level network +provided by the system to look at all like a standard device. Instead, +it will be designed solely for simplicity and ease of implementation, +and for a certain degree of efficiency. This interface will be +described after the interface between Network Control Programs in +different machines (the low-level protocol) is described. + +At some future time the intermediate programs might get moved into the +system for reasons of efficiency, but that should not be allowed to +complicate the initial implementation. + +As of October 1978, the opening and closing of connections is completely +device-dependent, as are "status"-type operations, however byte-string +I/O is supported in a fashion which is device-independent except when +errors occur, which is handy in several programs. Packet-level, +device-dependent I/O is also supported. + +The .INSRT-able file of routines NETWRK, will be augmented to handle +both the Chaos net and the Arpa net. + + +>>Lisp Machine implementation + +In the case of the Lisp Machine, the only distinction between user +programs and system programs is who maintains and documents them, +and how carefully. + +(More?) + +>Network Control Program + +This is the part of the operating system(s) that implements the network +(obviously). + +>>Packets + +The NCP's operate by exchanging packets. A packet consists of a +header containing control information, and zero or more 8-bit bytes of +data. Hardware restrictions of the Chaos net interface +restrict the maximum length of a packet to 253 16-bit words. In fact, +we will limit it to 252 words (to make packet buffers in pdp10's be 128 +words including two overhead words). Again for the convenience of +pdp10's, the header should be an even number of 16-bit words. + +In this section the packets will be described as they look to a pdp11. +They look the same inside a Lisp Machine, since the byte structure is the +same. Inside a pdp10, packets are stored with two 16-bit words +left-adjusted in each pdp10 word. Additionally, the bytes in the data +portion of the packet are swapped so as to put them in pdp10 standard +order. pdp11's that act as network interfaces for pdp10's will be required +to do this byte swapping since they're likely to have more time available +than the 10 to do it in, and can also do it faster, having a special +instruction for it. pdp10's that communicate directly to the network will +have hardware assistance for byte reshuffling in their interfaces. See the +transmission media section for how packets are encapsulated during +transmission through the various media. + +The header is 8 16-bit words and contains the following fields: + + ----------------------- + |opcode(8) | unused(8)| + ----------------------- + |fc(4) | nbytes(12) | + ----------------------- + | destination host # | + ----------------------- + | destination index | + ----------------------- + | source host # | + ----------------------- + | source index | + ----------------------- + | packet # | + ----------------------- + | ack packet # | + ----------------------- + + opcode - tells the receiver of the packet how to interpret + it. See the Operations section below. + This is 8 bits long. The 128 opcodes with high + order bit =0 are for NCP use. The 128 with high + order bit =1 are for user-program use. + + unused 8 bits reserved for future use. + + fc - forwarding count. 4 bits which count the number of times this + packet has been forwarded by bridges. Initially this field + is always generated as zero. Each bridge increments it; + if it overflows, there is assumed to be a loop + and the packet is discarded. + + nbytes - the number of 8-bit bytes of data in the data part. + The maximum value of nbytes is 488. The minimum is 0. + This is 12 bits long to allow for 4K-bit packets. + (Actually 12 bits is enough for up to 32K-bit packets.) + + destination host # + This is divided into two 8-bit fields. The high + byte specifies which subnet. The low byte specifies + which host on that subnet, and (on ethernet subnets) + is identical to the hardware host number. Neither + field may be zero in a valid host number. + + destination index - index for this connection assigned by the + destination host's NCP. + + source host # - see destination host #. + + source index - index for this connection assigned by the + source host's NCP. + + packet # - an ascending reference number used in error and + flow control (see below). + + ack packet # - used in error and flow control (see below.) + +>>Hosts attached to more than one subnet + +(This also applies to hosts with more than one interface to +the same subnet, if there ever are any.) + +Such hosts ought to act as bridges. That is, if a packet +is received which is not addressed to this host, it should +be sent back out, using this host's routing tables. The +forwarding count should be used to prevent infinite loops +in the event of inconsistent forwarding tables in two bridges. + +It is undesirable for a host to have more than one number. +So a host connected to multiple subnets should choose one +subnet as its "home", which is the address which is advertised +as that host. The host's other network connections are +un-named bridges. In some causes it may be preferable +not to pick a "home" subnet; instead, one invents a new +private subnet which only has that one host on it, +and all the host's network connections act as bridges +to that subnet (also to each other). + +The routing should be set up so that packets destined for such +a host from a subnet on which it has an interface choose that +interface as the bridge to that host, so that in fact data flows +the same way as if the host had more than one number and the +host-name to host-number lookup magically chose the right number. + + +>>Subnet and host numbers. + +Subnet numbers are arbitrary. Host numbers are assigned according to +position on the cable, as explained (elsewhere). + +These numbers may be found in the file SYSENG;HOSTS > + +The physical cable address of a host should include both its subnet number +and its host number (prior to October 1978 the subnet field of a physical +address was always 0). This allows the physical address to be used as +a unique machine identifier and makes it possible for a host to discover +its full 16-bit host address without prior knowledge. + +>>Packet numbers + +Each time the sending user puts another packet into the network, this +number is increased by one. (These numbers are independent for the +two directions of a connection.) The receiver uses these numbers to +get the packets into order and ensure that there are no duplications +nor omissions. The packet numbers are 16 bits and wrap around to zero +when they overflow. When the connection is first opened, an initial +value for the packet# is established. If it was 0, then the packet# +of the first data packet would be 1. + +Packet #'s should be compared modulo 2**16. On pdp11's, use + + CMP A,B + BMI (BMI rather than BLT or BLO) + +On pdp10's, use + + SUB A,B + TRNE A,100000 (rather than CAMGE A,B) + JRST + +On Lisp machines, use + + (AND (BITTEST 100000 (- A B)) + ) [rather than (AND (< A B) ...)] + +>>Indices + +Each connection has two indices assigned to it, one at each end. Each +index is an arbitrary 16-bit number assigned by the NCP at its end; usually +it is an index into that NCP's tables. Indices are required to be +non-zero. For maximum simplicity, all packets include both indices. The +receiver of a packet uses the destination index to find out who to give the +packet to. Generally the source index is used only for error checking, but +when a connection is first opened the source index has to be saved and used +as the destination index in future packets in the reverse direction. + +To prevent packets somehow left over from old connections from +interfering with new connections, we require that a certain time +elapse between successive connections between the same pair of hosts +with the same index numbers at each end, this time to be longer than +the maximum time a packet is reasonably expected to sit around in +the network somewhere (the maximum transit time through all bridges, etc.) +This requirement is implemented by making part of the index number be +a "uniquizer"; when a host reuses a slot in its tables, it increments +the uniquizer, so that the index number for that slot is not the same +as it was previously. Then if the uniquizer field is sufficiently wide, +and the rate of creation of connections (actually the rate of allocation +of indices) is sufficiently low, the requirement will be satisfied. +For the kind of network we're talking about, the time is a few tens of +seconds, and the uniquizer need only be a few bits wide. It is up +to each host how wide it makes the uniquizer, depending on how big +it wants its tables to be. It is best if table slots are also +allocated circularly, so that slots are reused at the minimum possible rate. + +The uniquizer also serves to "more or less" uniquely identify connections +so that duplicate copies of a Request For Connection (RFC) packet +can be identified and discarded. + +A user process's "capability" or "channel" to a connection, used by it +to ask the NCP to operate on that connection, simply contains the +appropriate index. + +Associated with each index the NCP has a "state", the host # and index +# of the other end of the connection, some read buffers and associated +variables, including a current packet #, and some write buffers and +associated variables, again including a current packet #. + +The "state" can be Closed (no connection or other activity currently +associated with this index), Open (this index has a connection to +another index at another machine), RFC-sent (requested another machine +for a connection, but no answer yet), Listen (listening for a request +for connection to a certain contact name), Broken (connection closed +abnormally by network or machine lossage), and RFC-received (waiting +for a server process to get going and pick up a request for connection +that came in). + + +>>Routing + +This section is a place-holder. Initially routing will be kludged with +a fixed table. Once the network is set up automatic routing will +be put in. + +The routing decision consists of looking at the destination subnet +field of a packet and deciding which interface (on a multi-interface +host) to transmit it on, i.e. what is the best route to that subnet. +In addition, if the destination is not on a subnet to which there +is a direct interface, one must determine what is the host number of +the bridge it should be sent to. + +It also involves recognizing packets which are destined to the +current host and receiving them. + + +The following is not yet implemented. It is an initial plan for routing. + +Gaetways will broadcast RUT packets periodically, perhaps once a minute. +The destination field is zero and the source field is the address of the +gateway on the net on which the packet is being broadcasted. The data field +contains a bunch of 16-bit words, divided into fields in the same way as +a host address. The subnet field of each word contains the number of a +subnet which this gateway is able to reach. The host field of each word +contains the hop count, which is 0 if the gateway is physically connected +to the specified (non-ether) subnet, 1 if the gateway is connected to +the specified (ether) subnet, or 1+ the hop count of the closer gateway +if this gateway indirects through another. The hop counts allow the gateways +to avoid loops when there are multiple paths; they may not need to be +looked at by non-gateway hosts. + +Each host maintains a routing table, with entries keyed by subnet number. +For subnets to which the host is physically connected, the entry points +to the host's physical interface. For subnets which the host knows how to +get to because it has been informed of a gateway via a RUT packet, the entry +contains the gateway's host address, the hop count, and the time that this +route was last confirmed by a RUT packet. If the NCP remembers only one +route to a given subnet, it wants to remember the one with the smallest +hop count unless that one is more than (say) 5 minutes old. If the NCP +remembers all the routes, it should stop using ones which are more than +(say) 5 minutes old. It is not clear that it should ever use one with +a hop count larger than the minimum. The reason for the time-out is to +avoid forever losing packets by sending to a gateway which has gone down. +If there are no gateways up and known about by the NCP which reach a given +host, it will look like that host is down. + +>>Operations + +This section tells what the values of the opcode field in a packet are, and +how an NCP responds to each one. + +1 RFC - Request for Connection + +This message is sent from user to server in order to open a +connection. The data contains the contact name. Actually, if +the data contains a space, the characters before the space are +the contact name and the characters after the space are "arguments". +This is done so that simple transactions can work (see below). + +The destination index is zero, because it is not known yet. The +responses are: + + OPN, if a server process is found or created that wishes + to accept the request and open up a connection. + + CLS, if the connection cannot be opened. The data field + contains an ascii explanation of why not. + + ANS, if a simple transaction is occuring. The data contains + the answer, and no connection is ever created. + + FWD, if there is no server process at this host, but there + might be a suitable one some place else. + +There may also be no response, if the RFC was lost in the network, or +the destination host is down, or the reply was lost in the network. + +To increase the reliability of establishment of connections, RFC's and +OPN's are retransmitted, just as data packets are, until a response is +elicited. CLS, ANS, and FWD cannot be retransmitted because we take +the position that retransmission is implemented by something associated +with a connection, and these packets are not sent by connections (and are +not acknowledged). OPN is sent by a connection, and RFC is sent by +a sort of embryonic connection which continues to exist while it awaits +an OPN or other reply. + +Since RFC is retransmitted, it is the responsibility of the NCP to detect +and discard duplicates. When an RFC is received, all existing connections +in the OPN or RFC-RECEIVED state, and all "pending" RFC's which are awaiting +servers to connect to them (if the NCP has such), should be checked to see +if they have the same source host and index number as the received RFC. +If so, the RFC is a duplicate and should be ignored. Note that connections +in the LOST, CLOSED, or BROKEN states should not be checked, since these +are not really connections as far as the foreign host is concerned, but simply +ghosts of connections left around to remember error status for their controlling +user programn. + +Since the response to RFC is not guaranteed, processes issueing RFC's +must have timeouts. In most implementations the normal host-down timeout +will suffice. + +[We should discuss why the special kludgery for control packets, rather +than using the regular connection mechanism to assure reliable transmission +of control packets, as the Arpanet does. Also a discussion of which control +operations inherently need reliability and which inherently don't, and +why that should be so.] + +The packet # field contains the first packet # that will be assigned +to data transmitted from the user process, minus one modulo 2**16. In +the simplest case, this can be zero, and the first packet sent will be +packet # 1. One might also imagine uniquizing the packet numbers +as an extra error check, but this should not be necessary, because +the indices are uniquized, and connections must be explicitly agreed +to by each end before data can flow. + + +2 OPN - Connection Open + +This is the positive acknowledgement to RFC. The source index field +conveys the acknowledger's connection index to the requester. The packet # +field contains the first packet # that will be assigned to data transmitted +from the server process, minus one modulo 2**16. The data portion of this +packet is the same as a STS packet (see below), and mainly serves to convey +the server's window-size to the user. The ack packet # field must contain +the usual value, i.e. the number that was sent in the packet # field of the RFC. +The receipt and ack in the OPN serve primarily to terminate retransmission of the RFC. + +When an OPN is received, a STS is sent in response, telling the server +the user's window-size. The exchange of an OPN and a STS also serves +as acknowledgement to each side that the other believes the connection +is open. No data packets may be committed to the network until after +this has occurred. If this rule was not followed, and packets happened +to get out of order, a data packet could arrive before the connection +was open and cause a LOS. + +To improve the reliability of establishment of connections, OPN's are +retransmitted, just as data packets are, until receipted (and +acknowledged) by STS. Because of this retransmission, the NCP must +detect and discard duplicate OPN's. If an OPN is received for a connection +which exists and is not in the RFC-SENT state, the OPN should be ignored +and no LOS should be sent. + +OPN's contain 16-bit data and are not byte-swapped. See below under opcode 300. + +3 CLS - Connection Closed + +CLS is the negative response to RFC. It indicates that no server was +listening to the contact name, and one couldn't be created, or for +some reason the server didn't feel like accepting this request for a +connection, or the destination NCP was unable to complete the +connection (e.g. connection table full.) The destination index will +be the source index of the RFC. The source index will be zero because +the NCP did not put this connection into its tables. The data bytes, +if there are any, contain an ascii explanation. + +CLS is also used to close a connection after it has been open for a while. +In the Arpanet, the NCP undertakes not to close the connection when the +user requests it, but waits until all data transfer has completed. This is +a source of extra complexity, since data transfer may be hung up, there +have to be timeouts, there have to be connections waiting to be closed +which aren't owned by any user, etc. It seems simpler to make CLS take +effect immediately, and let the user processes assure that data transfer +has been completed. Note that telnet-like applications don't need it, and +ftp-like applications have to have it separately from closing anyway. + +Since there is no error recovery or retransmission mechanism for CLS, +the use of CLS is necessarily optional. However, it is desirable to +send a CLS when possible to decrease user confusion. + +4 FWD - forward a request for connection + +This is a response to RFC which indicates that the desired service +is not available at the process contacted, but may be available at +a possibly-different contact name at a possibly-different host. The +data field contains the new contact name and the ack packet # field +contains the new host number. The issuer of the RFC should issue +another RFC to that address. + +5 ANS - answer to a simple transaction + +Simple transactions are transactions which consist of a single question +(request) and a single answer (response). They have no side effects, +so it is not necessary for either party to know whether the other party +thinks the transaction was completed or not. Simple transactions need +no flow control and no error control, other than a timeout by the user +side to detect lost messages. They are a simple, efficient way for +doing simple-minded things such as extracting information (such as the +time or a host name table) from a central server. + +A simple transaction is initiated by sending an RFC to a server which +happens to use simple transactions rather than full connections. The +data field of the RFC consists of the contact name of the server, +optionally followed by a space and arguments to the request. The +server responds by sending an ANS packet, whose data field is the +answer. The destination address of the ANS comes from the source +address of the RFC. The source address, packet #, and ack packet # +fields of the ANS are not used and should be zero. + +The difference between simple transactions (2 packets) and +full datagrams (4 packets) is that in the simple transaction the two +parties don't have to agree about whether or not the transaction +in fact took place, while in the full datagram they do, making +acknowledgement necessary. + +The server of a simple transaction should be prepared to process +the transaction multiple times without error. Simple transactions +should not have side effects which would be dangerous if repeated. + +200-377 DATA - Transmits Data + +The data portion of the packet is data being sent through the +connection. The packet # is a number that increments by one for each +data packet sent in this direction on this connection. This is used to +detect lost packets (which includes packets garbled in transmission and +packets lost in the statistical flow control scheme) and duplicated +packets (caused by lost or delayed acknowledges. The NCP undertakes to +deliver the packets to the destination process in the same order that +they came from the source process, with no duplications and no +omissions. Note that any opcode with the sign bit on is a data packet +as far as the NCP is concerned; if they wish, higher-level protocols +may use the opcode field to define various different kinds of data +packets. Thus, what is herein called a data packet may be a "control" +packet to a higher-level protocol. Normally, opcodes 200 and 300 +should be used. Opcodes 201-277 and 301-377 are to be used for special +purposes, as defined by higher-level protocols. + +Opcodes 300-377 are defined to be "16-bit data". Note that this does not +affect the byte count in the packet header; it is still a count of 8-bit +bytes. The sole effect of 16-bit data is to prevent byte-swapping when +communicating with pdp10's; pdp10's store the 2 8-bit bytes in a 16-bit +"word" in the reverse of the network standard order (defined by pdp11's +and Lisp machines). ((For purposes of 16-bit data, Interdata machines +are considered pdp10's.)) + +6 SNS - sense status + +This packet is a request for a STS packet to be returned. It is used for +"probing", see the section on flow and error control. + +Note that, to avoid a timing error, a SNS received by a connection in the +RFC-sent state should be ignored. This can happen if an OPN is transmitted +followed by a SNS and the packets get out of order. + +SNS should not be transmitted on a connection that is not in the Open state. + + +7 STS - report status + +STS is used for a variety of purposes. It is the vehicle to carry an +acknowledgement, when no data packet is being sent on which the +acknowledge could be piggy-backed. STS is used to set or change the +window size, to acknowledge opening of a connection, and to carry +receipts (see the flow control section.) In the future STS will (may) +be used to carry information used in automatic window-size adjustment. +Like most packets, the ack packet# field of STS carries an +acknowledgement, the number of the last packet given to the user +process. The first two bytes of the data field (low-order byte first) +carry a receipt, the number of the last packet guaranteed to be given +to the user process eventually. The next 2 data bytes carry the window +size (low-order byte first). Additional data bytes will be defined in +the future. + +STS's contain 16-bit data and are not byte-swapped. See above under opcode 300. + +10 RUT - routing information + +This packet type is reserved for the future, when automatic routing exists. + +RUT's contain 16-bit data and are not byte-swapped. See above under opcode 300. + +11 LOS - you are losing + +If a host receives a packet for a connection that does not exist (other +than RFC which isn't associated with a particular connection, LOS, and +CLS which is safe to ignore), it should return a LOS packet to the +source of the offending packet. The source of the LOS should be the +destination of the offending packet, and the packet# and ack packet# +fields should be copied. The data portion of a LOS contains an ascii +explanation of the problem. A host receiving a LOS should break the +connection specified by the destination index and inform the associated +process that something has gone wrong. It should make the LOS packet +available to that process so the explanation of the problem can be +read. + +The LOS packet isn't actually necessary, since if the supposed other +end of a connection refuses to cooperate (i.e. never sends any +packets), after a while the NCP will give up, close the connection, and +inform the user that the foreign host appears to be dead. + +For debugging, an echo feature is implemented as follows. If you send +a packet with a data opcode and source and destination indices of 0, +it will be sent back as a LOS packet. The data field will be destroyed +by the error explanation, but the packet # and ack packet # fields can +be used to remember any sequencing or checking information. + +12 LSN - listen (never transmitted through the net, see below) + +13 MNT - maintenance + +Normal NCPs will discard MNT packets, without generating a LOS. This packet +type is reserved for use by maintenance programs. + +>>Table of packet field use vs opcode + +The unused field is never used and must be zero, the forwarding count +field is always used in the same way, and the nbytes field is always +the length of the data. Fields marked "0" below are don't care +rather than must be zero, but zero is certainly recommended. The packet# +field of CLS, SNS, and STS would best be set the same as the packet# of +the next data packet to be sent (just as in RFC and OPN). + + Destination Source +Opcode Host Index Host Index Packet# Ack pk# Data +------ ---- ----- ---- ----- ------- ------- ---- + RFC usual 0 usual usual first - 1 0 contact name + + OPN usual usual usual usual first - 1 usual 0, window size + + CLS usual usual usual 0 0 0 reason + + ANS usual usual usual 0 0 0 answer + + FWD usual usual usual 0 0 new host contact name + + SNS usual usual usual usual 0 usual 0 + + STS usual usual usual usual 0 usual receipt#, window size + + LOS src h src i dst h dst i pk# ack pk # reason + + LSN 0 0 0 0 0 0 contact name + +Data usual usual usual usual usual usual data + + MNT completely nonstandard + + RUT completely nonstandard + +>>Flow and Error Control + +The NCPs conspire to ensure that data packets are sent from user to +user with no duplications, omissions, or changes of order. +Secondarily, the NCPs attempt to achieve a maximum rate of flow of +data, and a minimum of overhead and retransmission. + +The transmission medium is required to lose all damaged packets. Therefore +error control reduces to retransmission of lost packets, plus immunity to +duplicated and out-of-sequence packets. + +The following concepts must be explained: the window, acknowledgement, +receipt, retransmission, and probing. + +The window is the set of data packets "in the network" between the +sending process and the receiving process. Conceptually the window +slides along as transmission proceeds. When a packet is acknowledged, +that means that the window is to the right of that packet, since the +receiving process has gobbled that packet. The window has a fixed size +to limit the amount of buffer space that is used up if the sender sends +faster than the receiver receives. If the sending user process tries +to transmit more packets than the window size allows, it should be made +to wait until some packets have been acknowledged. The window is made +sufficiently large to regulate how often acknowledgements must be +returned. Note that the window includes only data packets, not +control packets. Control packets are to be processed immediately +when they are received, and do not take up buffer space. Separate +mechanisms are provided to deal with control packets being lost in +the network. + +No sender is actually required to pay any attention to the window size. +No receiver is actually required to set the window size to something +reasonable. However, those hosts that want to maximize performance +should do something about the window size. The size is initially set +during the RFC/OPN/STS dialogue, presumably according to the type of +protocol being used. An NCP may, if it chooses, dynamically adjust the +window size according to observed network behavior. (See dynamic +window-size adjustment section below.) + +An acknowledgement is a signal from a receiver to a sender that all +packets through packet number "n" have been given to the receiving +process, therefore the window should go from n+1 through n+window_size. +Note that acknowledgements can get out of order, so one should use +the maximum (mod 2^16) of all the acknowledgements ever received +as the start of the window. Since acknowledgements are so common, +there is a field (ack packet #) in the data packet which allows +an acknowledgement to be "piggy-backed" on another packet. + +A receipt is a signal from a receiver to a sender that all packets +through packet number "n" have been received successfully by the NCP +and are guaranteed to be delivered to the user process, therefore they +need not be retransmitted. Note that acknowledgement implies receipt. +The separate receipt mechanism is supplied so that useless +retransmissions can be limited, when the data have been received but +cannot be acknowledged because the receiving process is being slow +about reading them. The STS packet is used to send a +receipt. Receipts are optional. + +Retransmission is the process of sending all unreceipted data packets +in the sender's queue through the network to the receiver, except those +that were last sent very recently (within 1/30'th of a second in ITS.) +Retransmission occurs every 1/2 second, and when a STS packet is +received. The idea of retransmission is to keep sending a packet until +it has been proven to have successfully reached its destination (by +receipt or acknowledgement.) The reason retransmission occurs in +response to STS is so that a receiver may cause a faster retranmission +rate than twice a second, if it so desires. Since STS carries a +receipt, and very-recently-transmitted packets are not retransmitted, +this should never cause useless retransmission. + +A probe is the sending of a SNS packet, in the hope of eliciting +either a STS or a LOS, depending on whether the other side believes +in the connection. Probing is used periodically as a way of testing +that the connection is still open, and also serves as a way to get STS +packets retransmitted as a hedge against the loss of an acknowledgement, +which could otherwise stymie the connection. + +We probe every five seconds, on connections which have unacknowledged +packets outstanding (a non-empty window), and on connections which have +not received any packets for one minute. If a connection receives no +packets for 1 1/2 minutes, this means that at least 5 probes have been +ignored, and the connection is declared to be broken. + +The receiver generates STS packets under the following circumstances: +When a SNS is received (thus a response to a probe). When a duplicate +packet is received, so that further useless retransmission will be +prevented by the receipt. When the number of received but not +acknowledged packets is more than 1/3 the window size; evidently the +normal piggy-backed acknowledge mechanism is not working, so we +generate a STS to carry the acknowledge that will empty the window back +out, hopefully in time before transmission becomes clogged. When the +window size changes (to tell the other end of the change). + +When it is time to send a STS, we attempt to send one immediately. +If this fails (for instance, there might be no buffers available), +we keep trying to send one every half-second. + +The receiver can also generate "spontaneous" STS's, to stimulate +retransmission or to carry an acknowledge, to keep things moving on +fast devices with insufficient buffering, such as the Gould printer. +This provides a way for the receiver to speed up the retransmission +timeout in the sender, and to make sure that acknowledges are happening +often enough. For example, one might use a timer to generate a STS +every 1/10th of a second. + +Note that spontaneous STS's should not be generated until the connection +is fully open. This means that the server should not send STS until it +has gotten a STS back from its OPN. STS's other than spontaneous ones +have no such problem. + +>>Host Status + +All physical Chaosnet hosts, even gateways, are required to answer an +RFC with contact name STATUS and byte count 5 (no "arguments" allowed +in the data field of the packet) by returning an ANS packet whose data +field contains: the name of the host in ascii, an octal 200 (any byte +with the sign bit on terminates the name), and additional status and +metering information to be defined later, perhaps in a site-dependent +way. This makes it possible to write a program which determines the +status of all nodes in the network; the program could either be driven +by a host table or could try all possible host addresses; the NCP should +respond promptly to the STATUS RFC rather than starting up a program +to handle it, if starting up a program would take more than a second +or two. + +>>>Here is some narrative description of the NCP. + +Each receiver (each end of each connection is a receiver, and also a +sender; think of receivers and senders as little actors inside the NCP) +has a list of buffers containing packets which have been successfully +received and are waiting to be read by the user process, and two +packet# variables. One is the number of the last packet read by the +user process. The other is the number of the last packet which has +been acknowledged. If these two are not equal, the receiver needs to +send an acknowledgement "soon." + +The received-packet list needs to be kept sorted by packet number, and +the NCP has to make sure that the user process does not see duplicates +or omissions. If packets arrive out of order, the NCP has to sort them. +This means that the user process may not be able to read a packet even +though the receive list is non-empty, because the first packet in the +receive list is not the successor of the last packet read by the user +process. + +A good way to do this is to have two lists of received packets, each +of which is sorted. The first list contains those packets which +the user process may read; the first in the list is the successor +to the last packet read, and there are no gaps in the list. +The second list is the remaining packets, which the user may not +read until some other packet arrives to fill in the gap. Each +list needs a pointer to head and tail, and the packet number of +the next packet to be appended to the tail. + +It is not actually a requirement that an NCP support out-of-order +packets, rather than simply discarding them and hoping that they +will be retransmitted in order, but if it's not very hard to do +one might as well do it. + +Acknowledgements are sent by putting the last-received variable into +the "ack packet #" field of an outgoing packet on the opposite +direction of the appropriate connection, and copying the last-received +variable into the last-acknowledged variable. Where does the outgoing +packet come from? First of all, all outgoing data, SNS, and STS +packets automatically carry acknowledgement for the reverse direction +of their connection. So if an outgoing packet happens to be sent at a +time when an acknowledgement is necssary, that takes care of it. + +Secondly, if the number of outstanding unacknowledged packets is more +than 1/3 the window size, a STS should be generated and sent immediately +to acknowledge those packets before the sender fills up the window. + +Thirdly, the "soon" of four paragraphs back is implemented by a timeout +in the NCP. If an acknowledgement remains required for a certain amount +of time, a STS should be generated and sent to carry it. The appropriate +time interval is 1 second, I would guess. This timeout does not have +to be too exact, however. One could also not bother with this and let +the other end's probe timeout trigger the STS via a SNS. However, it +is desirable to send a receipt fairly soon after receiving a packet +to avoid useless retransmission. This could be done either by a timeout +or by sending a receipt when the packet is received for the second time. +[No known NCP has such a timeout. 10/2/78] + +The reason for having a timeout here, rather than just sending an +acknowledgement right away, is two-fold. It allows "batching" of +acknowledgements, where a single packet can be used to acknowledge +many packets, which halves the network traffic caused by bulk +data transfer. It also allows "piggy-backing" of acknowledgements +on data packets, which (for instance) decreases the network traffic +caused by remote-echoing telnet connections. + +When a receiver receives a data packet, it compares the packet # of +that packet with the last-received variable. If it is less or equal +(modulo 2^16), it is a duplicate of a packet already given to the user, +and should be discarded (or it is at least 30000 packets ahead of the +user, which is unlikely.) + +If it is greater, it is sorted into the received-packet list at the +appropriate position (if it has the same packet# as a packet already in +that list, it is a duplicate and is discarded.) It is NOT acknowledged +at this time; no packet is ever acknowledged until it has been given to +the user process ("end to end acknowledgement"). Since a packet on the +received packet list has not yet been acknowledged, it may be safely +discarded at any time if the operating system runs out of buffer space, +PROVIDED that it has not yet been receipted. +Also, if the receiving user process is not listening to the net, the +NCP cannot be swamped with arbitrary numbers of packets, since the +sending user process is not supposed to send more than window-size +packets past the last one the receiving user process read. +However, if receipts are being used, once a receipt has been sent for +a packet that packet may not be discarded. It is up to the individual +NCP which strategy it prefers to use. + +Note that the most likely cause of packet duplication is that an +acknowledge or a receipt was lost, so whenever a duplicate packet is +discarded, a STS packet should be sent back containing the current +receipt and acknowledge packet numbers. + +The sender has a list of packets which have been entrusted to it by the +user for transmission and one packet # variable, the number of the last +packet sent by the user. When the user next sends a packet, the sender +will increment this variable and set the packet# of the sent packet to +the result. The sender also sets the source and destination host +numbers and indices of the packet, sets the "ack packet #" to the +last-received variable of its corresponding receiver, sets the +receiver's last-acknowledged variable to that (clearing the receiver's +need-an-acknowledge flag), chooses a transmission medium by checking +the routing tables, and gives the packet to the transmission medium for +"immediate" transmission (perhaps it has to wait its turn in a queue.) +It also saves the packet on a list, in case retransmission is required. + +With each buffered packet the sender holds in trust, it remembers the time +that packet was last transmitted. From time to time "retransmission" +occurs. The sender gives one or more packets from its list to the +transmission medium. It always starts with the oldest, so as to keep +things in order, and sends the rest in order until it gets to one that was +transmitted too recently to do again. Retransmission is used to recover +from lost or damaged packets, lost or damaged acknowledgements, and packets +discarded by the receiver due to lack of buffering capacity. + +Each time a receiver receives a packet, it gives the "ack packet #" +from that packet to its corresponding sender. The sender discards any +packets with numbers less than or equal to that, since their successful +receipt has just been acknowledged, and advances the window. If a STS +packet is received, its receipt field is processed by discarding +packets, but the window is not advanced. + +>>Dynamic Window-size Adjustment + +This section has not been updated for receipts. Also, it is a bunch +of junk. Probably we can do without this stuff. + +Permit me to stress that this stuff is optional for small NCPs. + +The goals of flow control are: + 1. Error recovery. + 2. If the receiver is faster than the sender, avoid unnecessary + delays in transmission due to having to wait for an + acknowledge or having to wait for the sender process to wake up. + 3. If the sender is faster than the receiver, minimize + retransmissions due to receive buffer overflow. + 4. Minimize the number of otherwise-useless packets generated + to carry an acknowledgement or a window-size negotiation, + and minimize useless retransmissions. + +Consequences of the goals: + 1. All packets will be retransmitted until acknowledged. + 2. The sending NCP must buffer several packets, and packets + must be acknowledged in groups, not one-by-one. + 3. If the receiver is slow, something must force the sender + not to send packets too fast. + 4. The interval between retransmissions should not be too small. + It may be desirable for it to increase if the receiving + process is not listening for some reason. + +The window size is the maximum number of packets which may be in the +network at one time (for one direction of one connection). "In the +network" means output by the sending process and not yet input by +the receiving process. (These processes are the entities which +determine the rate, unless they are so fast that the network slows +them down.) + +The window size is not the number of packets acknowledged at a time; +for best operation the latter must be 1/2 to 1/3 of the former. +See below. + +If the sending process is slow (and determines the rate), things +are relatively simple. We just have to have a big enough window +size and frequent enough acknowledgement to cover for sending +process wakeup delays. + +If things are not limited by the sender, then + Window size + Flow rate = --------------- + Round trip time + + Round trip time = time to wake up sender process (multiplied + by the fraction of the time this + is necessary) + + time packet is sitting in sender buffers + before it is transmitted + + transit time through the net + + time packet is sitting in receiver buffers + before it is read; this is the maximum + of time to process previous packets + and time to wakeup sender process + + time until acknowledge is generated and sent + + transit time through the net + +The round trip time is the time between when packet N is output by the +sending process and when it is acknowledged, permitting the sending +process to output packet N+WS. + +The main variable components of the round trip time are the delay +before acknowledgement and the delay waiting in the receiver buffer for +packets to be processed. If these were zero, the round trip time would +consist of two process wakeups and two network transit times +(determined by the delay waiting for the cable and waiting for previous +packets from this host to be transmitted, the time needed to load and +unload the interface in the buffer, and the actual transmission time, +multiplied by the number of bridges in the path.) + +This ideal round trip time is probably on the order of 2 seconds. +The timeout for retransmission should be 2 to 3 times the round trip +time. The timeout for acknowledgement should be 1/3 to 1/2 the +round trip time. One could either measure the actual round trip time, +or use an estimate of say 3 seconds, a little higher than the ideal. +It would be a good idea to measure the round trip time in any case, +which is done by getting the elapsed time since transmission when +a packet is discarded due to its being acknowledged, and averaging +that. + +The receiver process should initially set the window size to the +maximum flow rate it wants to handle times the desirable round trip +time. + +Symptoms of improper window size: + +If the window-size is too large, the round trip time becomes +long due to packet processing delay in the receiver buffer. +(There will be many packets in the receiver buffer, and the +receiver will be processing them slowly.) The long round-trip +time will cause unnecessary retransmissions. Retransmissions +could also be caused by the NCP's discarding received packets +due to insufficient core to buffer them. + +If the window-size is too small, excessive process blocking +and waking up occurs. The receiver process often empties its +buffer and has to block until more packets arrive. The sender +process often fills up its buffer and has to block until +some of the buffered packets are acknowledged. A small window +size also causes acknowledgements to have to be sent more +frequently than necessary. Note that from the receiver's +point of view it is impossible to distinguish between the +window size being too small and the sending process being +too slow. + +Here is a scheme for dynamic adjustment of the window size: + +Note that window-size adjustments cannot take effect +(in the sense of fixing the symptoms) immediately, so it +is necessary to limit the rate at which the window size +is adjusted. + +When the receiver receives (and discards) a duplicate of a +packet it already has in its buffer, this indicates either +that an acknowledgement was lost or that the window size +is too large. Since packets are assumed not be lost very +often, we may as well assume the window size is too large +and send a WIN packet to decrease it. Another possibility +would be to have the sender detect the long round-trip +time and complain to the receiver, who could adjust the +window size. The receiver must not decrease the window +size again until all packets currently buffered have +been read and acknowledged, indicating that the sender +has had a chance to decrease the number of packets +buffered at its end. A reasonable amount to decrease +the window size by is 1/3 of its current value. + +When the sending process wants to output a packet, but the number of +packets already buffered is greater than or equal to the window size, +it should send a WTS, indicating that the problem is too small a window +size or too slow a receiver rather than too slow a sender. When the +receiving process wants to input a packet, but the buffer is empty, and +a flag is set indicating that a WTS has been received, it should send a +WIN packet adjusting the window size upward by 1/2 of its current value +(and clear the WTS-received flag). This is rate-limited by preventing +the sender from sending a second WTS until all the packets buffered at +the time the first WTS was sent have been acknowledged, indicating that +the receiver has had time to act on the first WTS. + +The variables required. For both the sending and receiving sides, a +packet number which has to be acknowledged before WTS or WIN can be +sent again, and a flag saying whether this number is operative. Also, +a WTS-received flag in the receiver. + +It is important to meter the performance of this mechanism and find out +whether it does anything and whether what it does is right. + +Consider the possibilities of changing this into a more symmetric and +negotiation-based scheme, where the sender always initiates window size +changing and the receiver either agrees or ignores the request. +Consider using elapsed time as an additional rate-limiter (have to use +the other thing, too, so idle connections don't keep changing window +size; this may be deleteable if it is always sender-initiated.) + +More notes on the subject of window-size too small. +This is identical to receiver too slow. The net flow rate +out of the sender is trying to be higher than that into +the receiver, so packets pile up in buffers at each end. +The round-trip becomes arbitrarily high to preserve the +equation and divide window size down enough to get the +flow rate. + +The situation where the window-size is too small and we want to do +something about it has to be distinguished from two other situations. +One, the receiver is accepting packets slowly but the sender is also +sending them slowly. We don't want to change the window-size, because +it doesn't matter since packets aren't piling up, and at any time they +might both decide to go fast. Two, the receiver's net flow rate is +high, but its response time is long (it's taking packets in bursts). +Here the round-trip time is still long, but making the window size +smaller would make things worse. + +The symptoms that distinguish the case where we want to make the +window-size smaller are: the round-trip time is long, the sender +buffer is full, and the number of packets acknowledged at a time is +small compared to the window size. Actually, the last two are sufficient, +since if the acknowledgement batch size is small, and we know it's +not the sender's fault, may as well decrease the window size +to save buffer space and decrease the round-trip time. + +>>Uniquization + +To avoid problems with packets left over from old connections +causing problems with new connections, we do two things. First of +all, packets are not accepted as input unless the source and +destination hosts and indices correspond to a known, existent +connection. By itself, this should be adequate, provided that +retransmission is only done by the originating host, not by intervening +gateways and bridges in the network. This is because we can safely +assume that when a host agrees to open a connection with a certain +index number at its end, it will give up on any previous connection +with the same index, therefore it won't retransmit any old packets +with that index once it has sent out a new RFC or OPN. The indications +are that our network will be "local" enough that indeed retransmission +will only be done by the original host. + +Problems could still occur if packets get out of order, so that an OPN +establishing a new connection gets ahead of a data packet for an old +connection with the same index. To protect against this, it is +necessary to assure that at least a few seconds elapse before an index +number is reused. This could be done either by remembering when an +index is last used, or by reserving part of the 16-bit index number as +a uniquization field, which is incremented each time an +otherwise-the-same index is reused. This field needs to big enough to +cover for the maximum delay of an old data packet with the same index, +and depends on the rate of creation of connections. Which method is +chosen is at the discretion of each local NCP. Another necessary +assumption is that when a system crashes and is reloaded (thus +forgetting any remembered information about which indices were in use +when and so forth) that the time to reload it is more than a few +seconds. + +Problems could occur not only with left over data packets, but also +with left over control packets. This isn't too much of a problem since +control packets are not retransmitted, but it could still happen that a +host gets faked out into thinking that it has a connection to another +host that the other host doesn't know about. In this case, it should +just look like the connection was opened and then either the other host +went down or the connection was broken by a LOS packet, since the other +host won't generate any data packets and won't accept any. + +>>Media handlers + +A host may be connected to more than one transmission medium. It has +service programs for each. + +When a packet is received that is not addressed to this host, the +forwarding count should be incremented. If it doesn't overflow, the +packet should be sent back out according to the routing tables, +otherwise it should be discarded. Normally it would not be useful to +send a packet back out on the same subnet it came in on, but we may as +well let the forwarding count catch this along with other loops. + +When a packet is received, if the opcode is RFC, it is handled +specially. The contact name is compared against those of all the +indices which are in the Listening state. If a match is found, that +index is put into the RFC-received state, its LSN packet is discarded, +and the RFC packet is put into its input list so that the server +process can see it. If no server is listening to that contact name, +the RFC packet is placed on the pending-RFC list, and (in the case of +ITS) a server process is created which will load itself with a suitable +program to open an index in "server" mode, gobble an RFC packet, look +at the contact name, and either reload itself with the appropriate +server program or send a CLS reply. + +When a non-RFC packet is received, the system must look for a receiver +index to handle it. If none is found, or the state is wrong, or the +source host and index don't match, a LOS should be sent unless the +received packet was a LOS. Otherwise, if the received packet is WIN, +WTS, or NOP, it is processed and discarded. Other packets are given to +the user; OPN, CLS, and LOS cause a state change but are also given to +the user as input. + +The transmitting side of a transmission medium handler has a queue of +packets to be transmitted. It should send them out, in order, as fast +as possible, except that if a receiving host has no buffer space (which +can be detected because its chaosnet interface will cause +"interference" on the ether), it should look down the list for another +host to send to. [No known NCP bothers to look for another +host to send to. 10/2/78] As long as packets to the same host are sent in the +order they are queued, everything will be all right. (Actually, this +normally shouldn't matter much.) In addition, when the packets are put +into the transmit queue, the destination host number has to be looked +up in a table to determine which transmission medium to use to get to +it and (in the case of ether) which physical host number to put in the +packet trailer for the hardware. + +>>Buffers + +In ITS, the buffering scheme will be as follows. There will be a pool of +128-word packet buffers available. When it runs out, more can be made. When +there are many free some can be flushed. 128-word buffers are made out of +1024-word pages (adding a new page type), rather than using the existing +128-word buffer mechanism, because there is a limited number of 128-word +buffers, and that mechanism is a little painful to use. There are likely +to be several hundred (?) packet buffers (say 12K of core) in use when +high-speed (e.g. mag-tape speed) file transfer is going on. + +Each packet buffer has a two-word header, and 126 words which can hold a +packet. Packet buffers can be on one (or sometimes two) of six lists: +The free list. The receive list, of which there are two for each +index, one for packets which the user may safely read and one for +out-of-order packets which are awaiting the arrival of an earlier +packet before the user may read them. The send list, of which there is +one for each index. The transmission list. The pending-RFC list. The +pending-LSN list. + +The free list contains packet buffers which are free. They are threaded +together through addresses in the first word. Zero ends the list. + +The transmission list contains packets which are to be transmitted out +on the network "immediately". At interrupt level packets are pulled +off of this list and sent. (There might be more than one transmission +list if a machine is connected to more than one physical medium.) +The transmission list is threaded through addresses in the left half +of the first word. Zero ends the list. After transmission -1 is stored +to indicate that the packet is not on the transmission list any more. +If the right half of the first word is -1, indicating that the packet +is not also on a send list, it is returned to free. + +Each send list contains packets for a particular connection which have +been entrusted to the system by the user to be sent, but have not yet +been acknowledged. They are threaded together through the right half +of the first word. The second word contains the time that the packet +was last transmitted (actually, the time that it was last put on the +transmission list.) + +Each receive list contains packets which have been received on a particular +connection and not yet read by the user. They are threaded together +by addresses in the first word, and the list ends with zero. The receive +lists must be kept sorted by packet number. + +The pending-RFC list contains request-for-connection packets which have +not yet been either accepted or rejected. They are threaded together +through the first word. When a server process finishes getting created +and loaded, it will take an RFC off the pending-RFC list and put it +on its own receive list. The second word of these packets contains +the time received so that the system can know when something has gone +wrong and they should be thrown away. + +The pending-LSN list contains LSN packets for all the listening users. +These packets are just used as a handy place to save the contact name +being listened to. They are threaded together through the first word. +The source-index field in the packet header can, of course, be used +to find which user this packet belongs to. + +>>ITS System Calls + +(Other systems would have similar calls, with appropriate +changes for their own ways of doing things.) + +OPEN + + Not allowed. (I said this wasn't a "standard" device!) + Instead use: + +CHAOSO + + arg 1 - receive channel number + arg 2 - transmit channel number + arg 3 - receive window size + + First, the two specified channels are closed. Then an index + is assigned to the user and the two channels are set up to + point to it. Two channels are used since in general ITS + channels are unidirectional, and to allow to the user to + handle receive and transmit interrupts differently. + + The created index is placed in the Closed state. To set up + a connection, IOT an RFC or LSN packet down the transmit + channel. + + +PKTIOT + arg 1 - channel number + arg 2 - address of a 126.-word block. + + Always transfers exactly one packet. + The format of the 126.-word block is: + 16 16 4 + ----------------------------------------- + | opcode | unused | fc | nbytes | 0 | + ----------------------------------------- + |destination host |destination index| 0 | + ----------------------------------------- + | source host | source index | 0 | + ----------------------------------------- + | packet # | ack packet # | 0 | + ----------------------------------------- + | data1 | data2 ... + + ... data487 | + ----------------------------------------- + + In the descriptions below, if an error is said to + occur that means IOC error 10. (channel in illegal mode) [3?] + is signalled. (Probably change this to an error return?) ******* + + In the case of an output PKTIOT, the user sets only + the opcode, nbytes, and data-n fields. When the + NCP copies the packet into a buffer in the system + it sets the other fields of the header to the + appropriate values. + + This is not completely true. When outputting an RFC, + the user sets the destination host field, and sets the + ack packet # to the receive window size desired. The user + also sets the window size when outputting an OPN. + + The NCP checks for the following special values + in the opcode field of a packet output by the user: + + RFC - error if the index is not in the Closed state. + The packet is transmitted (but not queued for + possible retransmission) and the index enters + the RFC-sent state. The user should do an input + PKTIOT which will wait for the OPN, CLS, FWD, or ANS reply + packet to arrive. The NCP also copies and saves + the user-specified host number and window size. + + LSN - error if the index is not in the Closed state. + It is put into the Listen state. The packet + is not transmitted, but it is saved so that + when an RFC comes in the system can compare + the contact names. (Note- LSN is a special + opcode which is never actually transmitted + through the net.) The pending-RFC list is searched + to see if an RFC with the same contact name has + been received. If so, it is given to this index + as if it was received just after the LSN was + sent out. + + OPN - error if the connection is not in the RFC-received + state. It is put into the Open state. The + packet is transmitted (but not queued for + retransmission, since until it is received + the other end does not know what index to + send acknowledgements to.) The system also + copies and remembers the window size. + + CLS - error if the connection is not in the Open + or the RFC-received state. It is put into + the Closed state and the packet is transmitted + (but not queued for retransmission). This packet + may optionally contain data bytes which are + an ascii excuse for the close. + + FWD - error if the connection is not in the RFC-received + state. The packet is transmitted, but not queued + for retransmission, and the connection is put into + the Closed state. + + ANS - error if the connection is not in the RFC-received + state. The packet is transmitted, but not queued + for retransmission, and the connection is put into + the Closed state. + + 200 or higher - This is a data packet. Error if the + connection is not in the Open state. A packet# + is assigned, the destination and source fields + are filled in, and the packet is transmitted and + queued for retransmission. + + Any other opcode causes an error. + + In the case of an input PKTIOT, the user will get an error + if the connection is in the Closed or Broken state, + except if it is in the Closed state and there are data + packets queued. This is so that the user can read the + CLS packet. Otherwise, it will hang until a packet + arrives, then return the packet into the user's + 126.-word block. + + The user should check the sign bit of the first word, + which will be set if this is a data packet. The + non-data packets which can get given to the user are + RFC, OPN, FWD, ANS, LOS, and CLS. (You shouldn't be + surprised if you get something else, though!) + + +IOT, SIOT + These can be used to do unit-mode 8-bit-byte transfers. + Control bit 1.4 means don't-hang, and applies to both input + and output. Only data packets with opcode 200 will be + transferred. Anything else on input causes the transfer + to stop, like an end-of-file. Use PKTIOT to find out what + the story is. (The correct way is to verify that there are + some packets in the input buffer, then do a SIOT, and if it + transfers 0 bytes then the first packet in the input buffer + must not be a data packet, so PKTIOT it in.) + + There can be input available to SIOT even when the state is + not %CSOPN (e.g. if the input buffer contains data and + a CLS packet.) In this case, you should first SIOT (if you + care to pick up the data) then PKTIOT. + +CLOSE + + Immediately closes the connection. All buffers and other + information associated with the index are discarded. Normally + the user should first IOT a CLS + packet containing an ascii explanation for why it is + closing. Note that any data previously written on the + connection but not yet received by the other end will be + lost. User programs should exchange "bye" commands of some + sort before closing if they care about losing data. It is + done this way to keep the NCP simple. + + +RESET + + Does nothing. + + +FORCE + + If there is a partially-filled output packet (created by IOT + or SIOT), it is transmitted. + +FLUSH + + On an output channel, does FORCE and then waits until + there are no queued output buffers. I.e., waits for + all output to be received and acknowledged by the foreign + host. This in fact waits for acknowledge, not just receipt. + + +RCHST + + val 1 SIXBIT/CHAOS/ + val 2 0 + val 3 0 + val 4 0 + val 5 -1 + + +RFNAME + + val 1 SIXBIT/CHAOS/ + val 2 0 + val 3 0 + val 4 0 + val 5 0 or 1 (i.e. .UAI or .UAO) + + +WHYINT + + val 1 - %WYCHA + val 2 - state + val 3 - number of packets queued (receive,,transmit) + val 4 - window size (receive,,transmit) + val 5 - input channel#,,output channel# (-1 if not open or I/O-pushed) + + LH(val 3) is the number of packets available to input IOT. + This is different from the number of received packets + if some are out of order. This is increased by 1 if + there is a partially-read buffer available to SIOT; + this packet is not available to PKTIOT. This is zero + if the connection is direct-connected to a STY. + + RH(val 3) is the number of packets which have been transmitted + by output IOT but which have not yet been received and + acknowledged by the foreign host. + + The state codes are: + + %CSCLS Closed + %CSLSN Listen + %CSRFC RFC-received + %CSRFS RFC-sent + %CSOPN Open + %CSLOS Broken by receipt of "LOS" packet. + %CSINC Broken by incomplete transmission (no acknowledge + for a long time) + + +NETBLK + + Similar to Arpanet NETBLK. + + +STYNET + + arg 1 - STY channel + arg 2 - Chaos channel to connect to, or + -1 to disconnect + arg 3 - Other Chaos channel (not actually used) + arg 4 - Output-reset character sequence, up to 3 8-bit + characters left-justified. + + This works the same as on the Arpanet. The specified STY + is connected to or disconnected from a Chaos net channel. + Data is transferred in and out by the system without the + need for intervention by the user program. If an unusual + condition occurs, the STY is disconnected from the Chaos + channel and the user is interrupted. It is illegal to do + I/O on any of the involved channels while they are connected. + + This call is provided for the benefit of the "Telnet" server. + + +CHAOSQ + + arg 1 - address of a 126.-word block (packet buffer) + + This is a special system call for use by the ATSIGN CHAOS + program, which is a daemon program that gets run when + an RFC is received that does not match up against an + existing LSN. + + The first packet on the pending-RFC queue is copied + into the packet buffer, then moved to the end of the + queue (so that the right thing happens when several + RFC's are pending at the same time.) + + The call fails if the pending-RFC queue is empty. + + The program should use the contact name in this + packet to choose a server program to execute. This + server program will then LSN to (presumably) the same + contact name, thus picking up the RFC. + +Interrupts + + IOC error interrupts occur if an attempt is made to IOT + when the connection is in an improper state, or to IOT + a packet with an illegal opcode. + + An I/O channel interrupt is signalled on the input channel + when the number of queued buffers changes from zero to + non-zero. + + An I/O channel interrupt is signalled on the output channel + when the number of queued buffers changes from greater or + equal to the window size, to less than the window size. + + An I/O channel interrupt is signalled on the input channel + when the connection state changes. + + Interrupts can be used for + + (1) detecting when input arrives. + (2) detecting when the system is willing to accept + output. + (3) detecting when the other end does a CLOSE. + (4) detecting when a requested connection + is accepted or rejected. + (5) detecting when a request for connection + comes into a listening server. + +>ITS packages + +Here document CHSDEF and NNETWK someday. Also the host table. + +>An NCP in English + +This section contains the salient routines and variables of the ITS +Chaos Network Control Program, in English. + +The following variables exist per-connection: + +CHSUSR the user who owns the connection, and his channel number for + it. This is used for reporting interrupts, and to keep track + of who owns what. + +CHSSTA the state. The following states exist: + Closed - this is the initial state + Listening - awaiting an RFC that matches the user's LSN. + RFC-received - entered from the Listening state when a matching + RFC arrives. + RFC-sent - entered from the closed state when an RFC is transmitted. + Open - entered from RFC-sent when an OPN is received, from RFC-received + when an OPN is sent. This is the "active" state. + Lost - entered when a LOS is received + Incomplete transmission - entered when probing produces no response. + + Some flags also exist: + Send STS as soon as possible + Connection is direct-connected to a STY. + +CHSIBF List of received packets, in order, which the user may read. + +CHSPBF List of out-of-order received packets. The user may not read these. + When the missing packets arrive, these are transferred to CHSIBF. + +CHSOBF List of transmitted packets which have not yet been receipted. This + list retains the packets for retransmission. Control packets do + not go on this list, only data packets. RFC's and OPN's DO go on this list. + +CHSNOS Number of output slots. This is the number of packets which the user + may output before the window fills and the user must wait. It is equal + to the window size minus the number of unacknowledged packets. + +CHSPKN The number of the last packet given to the user, and the number of + the last packet sent by the user. Used in assigning packet numbers, + checking order, and sending acknowledgements. + +CHSACK The numbers of the last packets acknowledged in each direction + of the connection. + +CHSNBF The number of packets in CHSIBF and the number of packets in CHSPBF. + Redundant information which is handy now and then. + +CHSITM The time (in 30ths of a second) that a packet was last received + from the network for this connection. Used in probing/incomplete-transmission. + +CHSWIN The two window sizes for the two directions of the connection. + +CHSLCL The local host and index numbers. + +CHSFRN The foreign host and index numbers. + +--- +When the user reads a packet, this algorithm is executed: +If the CHSIBF list is empty, then if the connection state is +not Open, give an error, otherwise await the arrival of a packet +into CHSIBF. Remove the first packet in CHSIBF and give it to +the user. If it is a data packet (opcode >= 200), "virtually +acknowledge" it as follows. Put its packet number into CHSPKN +as the last packet given to the user. Get the last packet number +acknowledged from CHSACK. If the difference of these is more than +1/3 the window size, send a STS. + +When the user outputs a packet, this algorithm is executed: +(what algorithm?) + +---------- Material after this point may be inoperative ---------- + +>Comparison with LCSnet + , and other blathering. + +>>Principle differences + +The LCSnet proposed protocol is called DSP. The Chaosnet protocol will +just be called chaos in this section. + +(1) DSP specifies things in terms of bytes where Chaosnet specifies +them in terms of packets. We choose packets to increase the simplicity +and efficiency of the scheme. DSP has to work in terms of bytes because +it allows packets to be reformatted en route, hence + +(2) DSP assumes that gateways can exist between networks with the same +protocols but different packet sizes. Therefore, the protocol has to +allow for the fact that packets may be reformatted en route. I happen +to believe that this situation is extremely unlikely to exist, and in +fact gateways between "different" networks will have to do much more +than just change the packet size. Therefore, it makes sense to make +the gateway worry about gateway issues, rather than have them permeate +the whole protocol. I believe that gateways will look more like +regular network ports than like transmission media; to get from a host +on the local net to a host on the arpa net, one will connect to the +arpa net gateway and ask it to open a connection from itself to the +host on the arpa net, then tie those connections together. A gateway +will perform not only packet reformatting, but protocol translation, +flow control on both sides, and maybe even character set translation. +There can also be entities called "bridges", which connect two networks +(or two separate segments of one network) with the same protocol. A bridge +simply forwards any packets it receives, but never alters the packets, +and never looks inside them except to find out where to forward them to. + +(3) A related difference is that DSP includes the arpa net, and TCP, +and by extension all the networks in the universe, in its port number +address space. Chaosnet would have you connect to a gateway, then +send the gateway the port number to connect to in the foreign +address space separately. Chaosnet does have to include all networks +reachable by bridges in its address space. + +(4) Chaosnet has an "opcode" field in the packet header, where DSP +does not. DSP acheives the same effect with various bits here and +there. It makes little difference unless user-level programs decide +to exploit the opcode field. + +(5) DSP and Chaosnet have quite different mechanisms for creating +connections. In DSP, one never creates a connection, exactly; +one simply starts sending to a port address. Local network note +#3 mumbles about how one discovers which port address to send to, +but I have not seen any specifics. In Chaosnet, the mechanism +for finding out where to send to and the mechanism for creating +a connection are intertwined; the excuse is that often the process +being connected to is created at the same time as the connection. + +(6) DSP uses unique, never-reused port IDs. Chaosnet does not. +The problem with unique, never-reused IDs is that I know of no +system that can implement them. Multics comes close, with the +aid of a special hardware clock. The clock is set from the +operator's watch when the system is powered on, and the mechanism +depends on the fact that the error in the operator's watch is +less then the time required to bring up the system after a power +failure. Small systems that cannot afford special hardware just +for this, and don't have permanent disk storage, would find it +very hard to generate unique IDs. + +Chaosnet prefers to rely on a scheme that doesn't require special +hardware, but nearly always works. By requiring a connection +to be opened before data packets can be sent through it, and by +some assumptions about the structure of the network, the problem +is eliminated. See the Flow and Error Control section for +further discussion. + +(7) DSP closes the two directions of a connection separately. Why? + +>>High priority data packets, interrupts, and flushing. + +The basic idea is to note that if you want to send a high priority +message, this means you want it out of order with respect to previously- +sent data on some connection. Therefore, high priority data should +be sent over an auxiliary connection. The per-connection overhead +is not prohibitively high, and this eliminates vast quantities of +hair from the innermost portion of the system. + +One advantage that DSP gains by having "high priority messages" +built into the system is that it also incorporates a standardized +way to "mark" a particular point in a data stream. However, this +is comparatively unimportant, particularly since I think high-priority +messages will probably never get used. The only place I've heard +them proposed to be used is with Telnet, but ordinary terminals +get along quite well without "out of band" signals when used with +reasonable operating system software. + +Interrupts and flushing of input are random crocks associated +with high priority messages. I don't propose to implement them either. + +>>Datagrams. (connections only used to pass a single packet.) + +These are easy. The guy who wishes to send a datagram does +OPEN, IOTs an RFC to the service to which the gram is to be +sent, and NETBLKs waiting for the connection to open up. He +then IOTs the data packet, FLUSHes waiting for it to get there, +then CLOSEs. + +The server OPENs and IOTs an OPN in response to the RFC. She +then IOTs in the datagram packet, CLOSEs, and goes off processing +the message. + +Four packets are transmitted, two in each direction. (An RFC, an OPN, +a DATA, and an ACKing NOP.) No need to send any CLS messages, since +each user process knows to do a CLOSE system call after one data +packet has been transmitted. It has been claimed that this is +the theoretical minimum if acknowledgement is required. The reason +is that the data packet must contain some unique id generated by +the RECEIVER to avoid duplicates, and it must be acknowledged, +so that's two packets in each direction, with no combining possible. + +Note that as [someone at] PARC has pointed out, for the important +case of side-effect-free transactions, a timeout can substitute +for acknowledgement, and only two packets are necessary. See ANS. + + +>>Why not multiple messages per packet? + +[1] Not needed for data. The division of the data stream into +packets is invisble to the real user, anyway. It's only used by +the "user-ring" portion of the network system software. + +[2] Extra complexity. Consider the hair involved with packed +control messages in the Arpanet. Because of the control link being +shared between multiple connections between the same pair of hosts, +this could save a little. I don't know of any NCP that does this; +furthermore, having that shared facility is a bad idea. The only +case in the Arpanet where packing two control messages into one +packet is useful is when opening a connection the receiver wants +to send STR and ALL both. In this protocol we just put the window +size in as part of the RFC and OPN messages. + +[3] There is an argument that having message boundaries separate +from packet boundaries is useful because gateways between different +networks may need to split up packets because the two networks +may have different maximum packet sizes. My feeling about this +is that the gateway is likely to have to do a good deal more than +that. It seems like too much to wish for that the two networks +should use exactly the same packet format, protocols, or even character +set; so the gateway rather than being a packet-reformatting device +is much more likely to look like a user program with two connections, +one on one network and one on the other, which passes data between +the connections with appropriate conversion. In particular, flow +control is likely to be host1 to gateway and host2 to gateway, +rather than host1 to host2. + + +>>Why not have a checksum in the packet? + +This network is likely to have a very diverse collection of machines +on it, which means it will be impossible to define a checksum which +can be computed efficiently in software on all machines. Now all +hardware links in the system ought to have whatever amount of +hardware checking is appropriate to them, but due to the efficiency +costs of a user-level end to end checksum, this should not be +a built-in requirement of the basic low-level protocol. Instead, +checksumming should be an optional feature which some higher-level +protocols (those that need it because the data being passed through +them is so vitally important that every possible effort must be made +to ensure its correctness) may implement. Checksumming should +be implemented at the user level in exactly the same way and for exactly +the same reasons as encryption should be implemented at the user level. + + +>>How about host-independent user-level protocols, where one just +connects to a service and doesn't have to know what host it's at today? + +Yeah, how about it? As far as I know, this protocol provides an +adequate base for constructing such a thing. Also I haven't +seen anything published on the subject. + + +>>Very small hosts. + +E.g. we'd like to put the Chess machine on the net. It has very little +memory, but not totally impotent microcode. A small host need only +support one connection, may ignore WIN, LOS, and CLS, may only have one packet +in transmission at a time, and may process receive packets one at a time +(ignoring any that come in until the first one has been fully processed). +It IS necessary to check that received DATA packets come in in the right order. + +RFC may be handled by remembering the other guy's host number and index, +and sending back a completely canned OPN. The contact name is ignored. +If a second user tries to connect while a first user is connected, +the first user gets bumped. Let them fight it out on some larger +machine (or the floor) for who will get to use the small machine. +Never originate any packet type other than DATA and that one OPN. + +Attaching ordinary terminals "directly" to the network is obviously +undesirable. + +>Transmission Media + +This section describes how packets are encapsulated for transmission +through various media, and what auxiliary hair is needed by each +medium. + + +>>Ethernet + +The messages transmitted through the ether (or CAIOS) net consist of +a packet followed by a three-word trailer: + + +----------------+ + | header | 8 words + +----------------+ + | data | 0-52 words + +----------------+ + | immediate dest | 1 word + +----------------+ + | immediate src | 1 word + +----------------+ + | CRC check word | 1 word + +----------------+ + +The three trailer words are looked at by the hardware; the last two +of them are supplied by the hardware. The reason this stuff is in +a trailer rather than a leader is that the caiosnet hardware actually +transmits the packet backwards. However, this is transparent to +the software. + +Bytes are sent two per word. The low-order byte is first (pdp11 standard). + + +>>TEN11 Interface + +[The following total hair has not been checked recently.] + +Since interrupts can't be sent through the TEN11 interface, the pdp10 can +only service the network at relatively-infrequent intervals, for instance +every 1/60'th of a second. Therefore it is necessary to have queues of +packet buffers in each direction. This provides high speed by allowing +several packets to be processed at a time. + +The speed and reliability of the TEN11 interface eliminates any need for +error checking. (ha ha) [ho ho] To decrease the load on the AI +pdp10, it is assumed that the pdp11's will be responsible for swapping the +bytes in the data portions of packets so that they will be in pdp10 +standard order. + +Even though the contents of packets will not be error-checked, the +pdp10 must check addresses to avoid being screwed by a losing pdp11. + +The form of a packet encapsulated for the TEN11 interface will then be + + |-----------------|-----------------|----| + | queue thread | 0=empty, 1=full | 0 | + |-----------------|-----------------|----| + | #bytes | opcode | unused | 0 | + |-----------------|-----------------|----| + |destination host |destination index| 0 | + |-----------------|-----------------|----| + | source host | source index | 0 | + |-----------------|-----------------|----| + | packet # | ack packet # | 0 | + |-----------------|-----------------|----| + | data 0 | data 1 | data 2 . . . | 0 | + | | 0 | + |-----------------|-----------------|----| + +for a total of 31 36-bit words, or 62 pdp11 words. + +The queue thread is the pdp11 address of the next packet-buffer in +a queue, or zero if this is the last. The empty/full indicator +says whether this buffer currently contains a packet, or not. + +The following is an attempt to express the algorithms of the +pdp10 and pdp11 in concise form. Hopefully they are self- +explanatory. + +Several queues of buffers need to exist in the pdp11. Only +two of these are known to the pdp10. + +TO10QF - first buffer queued for transmission to the 10. + +TO10QL - last buffer queued for transmission to the 10. + Exists so that buffers can be appended to the + list more quickly. + +TO10AC - first buffer in list of buffers actively being + gobbled by the 10. Set by 11, cleared by 10. + +TO10FR - copy of TO10AC. Used to free the buffers after + the 10 gobbles them. + +(come-from pdp11-packet-receivers + when (eq (destination-host ?packet) pdp10) + ;re-arrange 8-bit bytes for 10 + (swap-bytes (data-part packet)) + ;Add to to-10 queue + (set (thread packet) nil) ;nil=0 + (cond ((null TO10QF) + (setq TO10QF packet TO10QL packet)) + (t (set (thread TO10QL) packet) + (setq TO10QL packet))) + ;Try to activate to-10 queue + (cond ((null TO10FR) + (setq TO10FR TO10QF + TO10AC TO10QF + TO10QF nil + TO10QL nil))) +) + +(come-from pdp11-polling-loop + when (and (not (null TO10FR)) ;buffers were sent to 10 + (null TO10AC)) ;and 10 has finished gobbling + (mapcar 'make-buffer-free TO10FR) ;mapcar follows queue words + (setq TO10FR nil) ;OK to activate more buffers now + (cond ((not (null TO10QF)) ; more stuff waiting, activate it now + (setq TO10FR TO10QF + TO10AC TO10QF + TO10QF nil + TO10QL nil))) +) + +(come-from pdp10-clock-level + when (and (not (null TO10AC)) ;11 is sending buffers + (not web-buffers-locked)) + ;copy to user, process control message, or reject if buffers full + (mapcar 'process-input + TO10AC) + ;signal pdp11 that all packets have been gobbled + (setq TO10AC nil)) + + +FRBFLS - list of free buffers. cons-buffer gets from here, + make-buffer-free puts here. + +FM10AC - list of buffers into which pdp10 may place packets + set by 11 / cleared by 10. + +FM10GB - copy of FM10AC, used by 11 to process buffers after + 10 has placed packets into them. + +(come-from pdp11-polling-loop + when (and (null FM10GB) ;10 needs some buffers & + (not (null FRBFLS))) ; free buffers available + ;give the 10 a list of a suitable number of empty buffers + (repeat max-at-a-whack times + (and (null FRBFLS) (exitloop)) + (setq buffer (cons-buffer)) ;pull off free list + (set (full-indicator buffer) nil) ;contains no packet + (set (thread buffer) FM10GB) ;cons onto list + (setq FM10GB buffer)) + (setq FM10AC FM10GB) ;give buffer list to 10 +) + +(come-from pdp11-polling-loop + when (and (not (null FM10GB)) ;gave 10 some buffers + (null FM10AC)) ;which it has used + ;process packets sent from 10. + (mapcar + '(lambda (buffer) + (cond ((null (full-indicator buffer)) + (make-buffer-free buffer)) ;didn't get used + (t (swap-bytes buffer) + (send-to-destination buffer)))) + FM10GB) + (setq FM10GB nil)) ;no buffers active in 10 now + +(come-from pdp10-clock-level + when (and (not (null FM10AC)) ;buffer space avail + (not web-buffers-locked)) ;no M.P. interference + ;send as many packets as possible + (mapcar + '(lambda (buffer) + (cond ((needs-to-be-sent ?packet) ;find a sendable packet somewhere + (copy-into buffer packet) + (set (full-indicator buffer) t)))) + FM10AC) + ;signal pdp11 to gobble the packets + (setq FM10AC nil)) + + +To avoid the need for a gross number of exec pages in the pdp10, +the FM10AC and TO10AC words, and all the packet buffers, should +lie in a single 4K page. The best location for this page varies +from machine to machine. On dedicated 11's such as the AI TV11, +the MC console 11, etc. it should probably just be the first 4K +of memory. On the logo machine, it would probably be best to put +this page up in high memory where RUG won't mess with it. In the +case of the mini-robot system, I'm not sure. + +It would be best not to try to use this protocol with "general +purpose" machines, because of problems with finding the list +headers and packet buffers, problems with telling whether the +machine is running the right program, etc. It should be used +just as a way for the AI machine to get a path to the net. + +>>DL10 & DTE20 + +[Outline only] + +[Just use the pdp11 as a substitute for a direct chaosnet interface.] + +[Basically, the 11 says ready to transfer (in either direction), the 10 +sets up the pointers and says to transfer, and the 11 transfers the cruft. +To eliminate an extra level of buffering, on input transfers the 11 makes a +copy of the first 4 16-bit words of the header available to the 10 when it first +says "ready to transfer." The 10 uses these to decide where to copy the +packet into. It helps if you don't try to use a DL10 on a machine with a +cache.] + +>>Asynchronous line + +Packets are encapsulated by preceding them with start of text (202), +and following them with a 1-byte additive checksum and an end of text (203). +The 16-bit words are transmitted low order byte first. If the checksum +is wrong the receiver ignores the packet. The start and end characters are +just there to help in ignoring random noise on the line. If they don't +appear, the packet is ignored. The full 60-word packet is not transmitted; +the #bytes count is used to determine how many of the data bytes to +transmit; the receiver fills the remainder with zero (or garbage, at its +convenience.) + +This protocol is intended mainly for communication between the plasma +physics pdp11 in bldg. 38 and a pdp11 in 545, until the caiosnet +gets extended that far (or a longer-distance, lower-speed caiosnet +is extended to various machines off in that direction.) diff --git a/doc/sysdoc/chaos.file b/doc/sysdoc/chaos.file new file mode 100755 index 00000000..b960dd88 --- /dev/null +++ b/doc/sysdoc/chaos.file @@ -0,0 +1,760 @@ +-*- Mode:Text -*- + +Description of the CHAOS FILE protocol designed by HIC. + + The CHAOS FILE protocol is a protocol used to give access to the +file systems of remote hosts on the CHAOS net. Provided that the +foreign host has a CHAOS FILE server, one can read and write files, +delete, rename, etc. The protocol was originally designed to give LISP +machines access to the file systems of our PDP/10's, but is general +enough to support file transfer between 10's, and other purposes. + + We will describe the protocol from the point of view of the +user, i.e., the implementor of a user program communicating to a foreign +server. Hence, terms such as "receive", "send", "input", and "output" +are from a user's point of view, unless explicitly indicated. The first +step in using the protocol is to open what is called a CONTROL +connection to the server on the foreign host. A CONTROL connection is +simply a standard CHAOS net connection to the contact name "FILE" on the +foreign host. The CONTROL connection is used to send commands, and +receive responses and most error message. + + When reading or writing files, actual data is sent over separate +CHAOS net connections called DATA connections. DATA connections are +opened in conjunction with the foreign host, using commands on the +CONTROL connection. Hence, the CONTROL connection must be opened first. +We will present the details below; but here are some preliminary facts +about DATA connections. Like CONTROL connections, DATA connections are +bidirectional. Each half (send and receive) of a DATA connection is +used independently, so two file transfers may be active on a DATA +connection at the same time (but they must be in opposite directions). +There may be more than one DATA connection per CONTROL connection, but +each DATA connection is associated with a particular CONTROL connection. +This is because each CONTROL connection deals with a separate +incarnation of the server at the foreign host. We also note that DATA +connections are re-usable, i.e., can be used for many file transfers. +Simple programs might very well get by with a single DATA connection, +but it is possible to have several (the actual limit depends on +resources of the foreign host, and is 3 for ITS servers, and 8 for +TOPS-20 servers). + + The protocol is organized so that commands and responses have a +fairly uniform syntax. Further, each command (response) is sent +(received) in a single packet. Each command has a field for a unique +identifier, called the transaction id, or "tid" for short, which +identifies it. This is because the protocol permits asynchronous +processing of commands and responses, i.e., you can send a new command +without waiting for the response to the previous one. However, it is a +good idea to read the responses as they come in, so the server will not +block trying to send responses to you. The server is coded so that it +will not block if DATA connection packets back up. + + Let us now discuss the details of command and response packets. +We will discuss error processing later. Each command must be sent in a +separate packet on the CONTROL connection. The packet must have the +packet opcode for ASCII data (%CODAT = 200). When you are done with the +CONTROL connection and wish to disconnect from the foreign host, you +should send an EOF packet (%COEOF = 014) on the CONTROL connection. +This will cause the server to abort any transfers in progress, close all +DATA connections pertaining to this CONTROL connection, and close the +CONTROL connection. + + Responses to commands, successful or not, will come as data +packets (i.e., opcode %CODAT) on the CONTROL connection. The only other +kind of packet you should see on the CONTROL connection (unless there +are network problems) and asynchronous mark packets, which will be +discussed later. + + The contents of a command or response packet is simply the +sequence of ASCII bytes in the data portion of the packet. Fields are +generally separated by either spaces (040) or LISP machine newline +characters (NL = 215). We remark now that certain parts of the protocol +are oriented towards the LISP machine character set, which consists of +256 characters. This is in contrast to the 128 character set standard +on PDP/10's. The printing characters generally have the same +interpretation, though. Later we will explain the character set +translation features provided by the protocol in detail. + + Here is the format of command and response packets: + +command: tid [ fh ] cmd [ args ] +response: tid [ fh ] cmd [ results ] + + means a space character (040), and brackets surround +optional fields. Each field is a sequence of printing characters. Here +is the interpretation and format of the common fields: + +tid: Transaction identifier, used only to help the user program sort + out replies. Only the first 5 characters are significant; the + rest are discarded, and will not appear in a response. Tid's + may vary or be the same, as you wish. + +fh: File handle, used to identify a DATA connection, and a direction + (in/out). That is, each DATA connection has two file handles + associated with it, one for indicating input (transfer to you + from the foreign host), and one for output (transfer from you to + the foreign host). Like tid's, file handles are also unique + only in the first 5 characters. + +cmd: A command name. Only the first 5 characters are actually read + at the current time, but this should not be depended upon. The + full name of the command always appears in the response. + Command names must be presented in upper case. + + The "args" and "results" fields vary depending on the command, +and will be described with each command below. The response to a +particular command will have the same tid as the command, and also the +same file-handle (if relevant), and the same command name. The only +differences are that the tid and file handle in the response will be +truncated to 5 characters, and the command name will always appear in +full. + + Conventions used in the descriptions: + + Numbers we write (e.g., packet opcodes, ASCII codes, etc.) are +in octal, unless followed by a decimal point, in which case they are +decimal. Byte sizes are an exception to this rule: they are always in +decimal, even if not followed by a decimal point. + means an empty field in a packet. + means a sequence of ASCII characters that are all digits +(codes 060 through 071, i.e., '0' through '9'). Such numbers are always +expressed in decimal. These numbers are unsigned, but may have leading +zeroes. (The server may possibly send a negative to you, e.g., +the "-1" of the version field of an OPEN response, but you should never +send a negative to it.) + Some syntax was too long to be presented on a single line here; +we note that there is no CRLF or newline in the packet when we continue +syntax on a second line. That is, all characters in every command or +response are written down explicitly. + A reminder: the end of a command or response is not marked by a +special character, because the length field of the CHAOS net packet +determines where the data ends. + +------------------------------------------------------------------------ + + DATA-CONNECTION + args = ifh ofh + results = + + This is used to open a new DATA connection. The "ifh" and "ofh" +fields are the input and output file handles to associate with this data +connection. Each should be distinct from all other file handles of +other DATA connections pertaining to the same CONTROL. Since this +command does not pertain to any existing file handles, the file handle +field of the command must be omitted. As would be expected, the input +file handle is used to describe the receive half of the DATA connection +and the output file handle is use to describe the send half. + + When the server receives a valid (well-formed, etc.) +DATA-CONNECTION packet, it will attempt to open a new CHAOS net +connection to your host, using "ofh" (the output file handle you +supplied in the command packet) as the contact name. Hence, you should +listen for such a connection. The server will respond to the +DATA-CONNECTION command immediately, even though the new DATA connection +may not yet be open. Of course, you cannot use the connection until it +is open, but you will know that, because you had to open it. + +------------------------------------------------------------------------ + + UNDATA-CONNECTION + args = + results = + + This command is used to close a DATA connection when you are +finished with it. There is probably little occasion to use this, since +any DATA connections will be closed when the CONTROL connection is +closed, and a DATA connection can be re-used for multiple file +transfers. The DATA connection closed is the one whose input or output +file handle appears in the file handle field of the UNDATA-CONNECTION +command. UNDATA-CONNECTION implies a CLOSE on each file handle of the +DATA connection for which there is a file transfer in progress. + +------------------------------------------------------------------------ + + OPEN + args = [ options ] filename + options = option1 option2 ... optionN + results = version date len qfasl + realname + + This command is used to open a file for reading or writing at +the foreign host. The "filename" part is the filename to use at the +foreign host. It is always expressed in the foreign host's file name +syntax. The "options" field will be explained momentarily. If an input +file handle is given in the file handle field of the command, then the +file is to be opened for reading. If an output file handle is given, +then the file is to be opened for writing. In either case the file +handle serves to indicate not only the direction of transfer, but also +the DATA connection to be used for the transfer. A file handle must be +supplied, unless a PROBE is being done. PROBE will be explained below, +but breifly, it permits you to find out information about a file (i.e., +the "results" information of an OPEN response) without actually opening +it. + + The "options" field of the OPEN command consists of a number of +options (most of them are simple ASCII strings), always in upper case, +each preceded by a space (to separate them from the "OPEN" and from each +other). The options permit you to specify whether the transfer is to be +BINARY or CHARACTER, and a number of other things. Some options apply +only to BINARY transfers, and others (character set translations in +particular) only to CHARACTER transfers. Here is a list of the options +and their meaning. + + READ - Indicates that we will be reading a file. This is + redundant, and is checked for consistency (i.e., we must have + given OPEN an input file handle). + + WRITE - Analogous to READ. + + CHARACTER - Specifies that we will be transferring character + data as opposed to binary. This affects the mode in which the + server will open a file, as well as whether or not character set + translations are performed. CHARACTER is the default, so it + need never be specified. The check for QFASL files is not + performed (see below). + + BINARY - Specifies that we will be transferring binary data. A + check is made for QFASL files when reading (the result of the + test is supplied in the response to the OPEN; see below). The + default byte size is 16 bits (see the discussion of byte sizes + below). + + PROBE - This is used to check the existence of a file, and find + out information about it if it exists. The file is not actually + opened. This option is implied if no file handle is given in + the OPEN command. You should not supply a file handle when + doing a PROBE. The response packet will contain the same + information as a response to OPEN'ing the file for reading. + BINARY vs. CHARACTER makes a difference in a probe, as described + in the discussion of the response to OPEN. + +Options pertaining to BINARY transfers only: + + BYTE-SIZE - Specifies to use bytes with bits + each. The interpretation is explained below. + +Options pertaining to CHARACTER transfers only: + + RAW - Suppresses character set translation (see below). + + SUPER-IMAGE - Suppresses rubout quoting (this pertains to + character set translation, see below). + +Options specific to particular foriegn hosts: + + At present there are only two kinds of servers: ITS servers +(e.g., AI and MC) and TOPS-20 servers (e.g., XX, EE, and SPEECH). There +are two options that are specific to TOPS-20 servers (i.e., they do not +work for ITS servers, and should not be presented to them): + + TEMPORARY - TOPS-20 server only: says to use GJ%TMP in the + GTJFN. This is useful mainly when writing files, and indicates + that the foreign operating system is to treat the file as + temporary. See TOPS-20 documentation for more about the + implications of this option. + + DELETED - TOPS-20 server only: says to set GJ%DEL in the GTJFN. + This is useful mainly for READ'ing or in PROBE's, and indicates + that deleted files should be considered when looking for a file. + See TOPS-20 documentation for information about this. + +Details for ITS servers: + + A CHARACTER OPEN will be in .UAI (.UAO) mode when reading + (writing). Similarly, a BINARY OPEN will be in .UII (.UIO) + mode. An OPEN for writing always opens _LSPM_ OUTPUT in the + spcified directory, but does a RENMWO just before the CLOSE, to + the appropriate file names. The server takes care of the + traditional screws associated with the last word of text files, + i.e., you don't have to worry about it -- you will never see the + extra characters. + +Details for TOPS-20 servers: + + GTJFN's - When OPEN'ing for READ or PROBE, GJ%OLD is always set. + When OPEN'ing for WRITE, GJ%FOU and GJ%NEW will be set. These + are independent of the setting of GJ%DEL and GJ%TMP (see the + TEMPORARY and DELETED options, above). + + OPENF's - CHARACTER mode does a 7-bit OPENF, normal mode, with + line number checking off when reading. BINARY mode does a + 36-bit DUMP mode OPENF -- the server handles the packing and + unpacking of bytes within words. + +Open results: + + results = version date len qfasl + realname + + version = a , expressing the version number of the file. + On ITS server, this will be the numeric second name, or the + leading numeric characters of the second name. If the name has + no numerics, the field will be "-1". On TOPS-20 this will be + the generation number of the file. + + date = The creation date of the file, expressed in the form + "mm/dd/yy hh:mm:ss". (That is a real between the date and + the time.) + + len = ASCII digits for the length of the file in the byte size + being read. This will always be 0 when writing. + + qfasl = "T" if we are doing a BINARY READ, and the first word + of the file is "QFASL" in sixbit. "NIL" otherwise. This is + clearly oriented towards LISP machines! + + realname = the full name of the file, e.g., what RFNAME (on ITS) + or JFNS (on TOPS-20) will tell you, when asking for all the + usual fields (device, directory, first name, second name, + generation number). + +------------------------------------------------------------------------ + + CLOSE + args = + results = version date len + realname + + A file handle must be given, and a transfer must be active on +that handle. A synchronous mark will be sent or awaited accordingly, +and the file will be closed (but not the DATA connection). See the +discussion of data transfer protocol, below, for more details. + + The results are mostly as for OPEN. However, the "len" field is +computed differently. For ASCII input, it will be the number of +characters, as returned by FILLEN on ITS. On TOPS-20, it will be the +number of bytes in the file, if it was written using 7-bit bytes, +otherwise, 5 times the number of words. For binary input, it is the +number of words in the file times 2. For ASCII output, "len" is the +exact number of characters written, and for binary output, it is the +number of words times the number of bytes per word for the current byte +size. [This stuff may be buggy anyway.] + +------------------------------------------------------------------------ + + FILEPOS, args = + + This must have a file handle, and it must be an input file +handle. It requests the foreign host to reset its file access pointer +to byte of the file currently open, according to the current byte +size being used. As explained below, this sends a synchronous mark +before starting to send more data. FILEPOS is ILLEGAL for files being +written. + +------------------------------------------------------------------------ + + DELETE + args = or filename + results = + + If a file handle is given the file being read or written on the +specified DATA connection will be deleted after we close it (regardless +of direction). The file handle must refer to an open DATA connection, +and the direction must be correspond to the current transfer. This is +called a "delete while open", or DELEWO. In such a case, DELETE should +have no argument. + + If no file handle is given, then the optional argument must be +present, and specifies a file to be deleted immediately. + +------------------------------------------------------------------------ + + RENAME + args = filename1 [ filename2 ] + results = + + If a file handle is given, only the first filename should be +present, and the file will be renamed to filename1 sometime. This is +called a "rename while open", or RENMWO. On ITS, a RENMWO call is done +immediately. On TOPS-20, a GTJFN is done to filename1, and when we do a +CLOSE on the file handle, the CLOSF is done with CO%NRJ set, and then an +RNAMF is done to the previously obtained jfn. + + If no file handle is given, then both filenames must be present, +and the effect is to rename filename1 to be filename2. Don't forget +that on ITS renaming can only be done within a directory. The server +simply ignores the device and directory parts of filename2, so be +careful. On TOPS-20, renaming from one pack to another will fail. + +------------------------------------------------------------------------ + + CONTINUE + args = + results = + + This must have a file handle, and the indicated channel must be +in the asynchronously marked state. That is, an error of some kind +occurred. If the error might be recoverable, then CONTINUE will try to +resume from it. If the error is non-recoverable, you will get an error +response. See the discussion of marks below. + +------------------------------------------------------------------------ + + SET-BYTE-SIZE + args = nbs [ npos ] + results = + + This must have a file handle, which must refer to a file open in +BINARY mode. Both nbs and npos are 's. "nbs" is the new byte +size, and must be in the range 1 to 16. "npos" is the new position in +the file IN TERMS OF THE OLD BYTE SIZE. The npos part may be omitted +for output files, and is ignored if present (but the second MUST be +there). If npos is omitted for input files, it defaults to 0. This +command sends or awaits a synchronous mark. + +------------------------------------------------------------------------ + + LOGIN + args = userid [ password [ account ]] + results from ITS = uname hsname + persname + results from TOPS-20 = + + This command is for logging in at the foreign host. You must +log in before any OPEN commands will be accepted. Logging in to ITS is +simple: you just give the desired UNAME, which may even legally be +blank. On TOPS-20, the userid must correspond to a real directory +(RCUSR is used), and the password and account are passed to a LOGIN +jsys. For most of our TOPS-20's, userid = ANONYMOUS and password = +ANONYMOUS will give you a login of low privilege. If the first character +in the password is an asterisk, capabilities will be enabled. + +------------------------------------------------------------------------ + + DIRECTORY + args = options pathname + results = same as for OPEN + +The only option currently allowed is DELETED, which says to include deleted +files (TOPS20) or "*" files (ITS). + +The DIRECTORY command is like opening an input file. The possible responses +are the same as for OPEN, except that the affirmative response says DIRECTORY +rather than OPEN. + +The input file that you read consists of a series of records; first a +header and then the name and properties of each file that matches the +pathname, which may contain wildcards in system-dependent fashion. Each +record read consists of a pathname, , a set of properties separated by +, and an extra to separate it from the next record. Each property +consists of the name of the property, optionally followed by a space and +the value. (If no value is present, the property is a yes/no property and +the value is yes). The header record is in the same format; it has a blank +pathname and has the properties for the file system as a whole rather than +for a particular file. + +The properties are not documented here; consult the Lisp machine manual for +a list of the most useful ones. + +------------------------------------------------------------------------ + + COMPLETE + args = options default-pathname string + results = status new-string + +This does filename completion. String is a filename typed in by the user +amd default-pathname is the default name against which it is being typed. +The filename is completed according to the files present in the file system +and the possibly-expanded string is returned. + +Allowed options are DELETED, READ, WRITE, OLD, NEW-OK. DELETED means not +to ignore deleted files; this applies to Tenex and TOPS-20 only. READ +means the file is going to be read (this is the default). WRITE means the +file is going to be written, and affects version number defaulting. OLD +means an existent file is required (this is the default). NEW-OK means that +it is permissible for the string to complete to the name of a file that does +not exist. + +The returned status is NIL, OLD, or NEW. NIL means that an error occured, +OLD means that the string completed to the name of an existent file, NEW +means that the string completed to a legal filename which is not the name +of an existent file. + +------------------------------------------------------------------------ + + CHANGE-PROPERTIES + args = filename property-name new-value ... + results = + +This allows you to change one or more properties of a file. The properties which +are legal to change are those in the SETTABLE-PROPERTIES property of the header +record returned by the DIRECTORY command. The legal values for yes/no +properties are T and NIL. + +------------------------------------------------------------------------ + +About character set translations: + + As mentioned somewhere above, the protocol was originally +designed to provide access to PDP/10 file systems for LISP machines. +LISP machines support 8-bit characters, and hence have 256 characters in +their character set. This results in minor difficulties when conversing +with PDP/10's, which prefer 7-bit characters. Translations apply ONLY +to CHARACTER transfers, not BINARY transfers. Below is a table showing +the "normal" (i.e., default) correspondence between LISP machine and +PDP/10 characters. Some LISP machine characters expand to more than one +PDP/10 character. The notation "x in " means "for all +character codes x such that c1 <= x <= c2." + + LISP machine character PDP/10 character(s) + + x in <000, 007> x + x in <010, 012> 177 x + 013 013 + x in <014, 015> 177 x + x in <016, 176> x + 177 177 177 + x in <200, 207> 177 + x in <210, 212> + 213 177 013 + 214 014 + 215 015 012 + x in <216, 376> 177 + 377 no corresponding code + + This table may seem confusing at first, but there ARE some +general rules about it that should make it appear more sensible. First, +LISP machine characters in the range <000, 177> are generally +represented as themselves, and x in <200, 377> is generally represented +as 177 followed by . That is, 177 is used to quote LISP +machine characters with the high bit on. It was deemed that 177 is more +important than 377, so 177 177 means 177, and there is no way to +describe 377 with PDP/10 characters. On the LISP machine, the +formatting control characters appear shifted up by 200. This explains +why the preferred mode of expressing 210 (backspace) is 010, and 010 +turns into 177 010. The same reasoning applies to 211 (tab), 212 +(linefeed), 214 (formfeed), and 215 (newline). However, newline has an +added twist -- it is supposed to start at the beginning of a new line, +so it is deemed equivalent to 015 012 (CRLF) in PDP/10 characters. When +converting PDP/10 characters to LISP machine characters, an 015 always +turns into a 215; however, if it is followed by an 012, the 012 is +skipped. + + The above table applies in the case of NORMAL translation, i.e. +the default translation mode. Note that the server ASSUMES the user is +a LISP machine, and that all our servers are PDP/10's, so the labellings +"LISP machine" and "PDP/10" can be thought of as "user" and "server". + + The other translation modes available are: + + RAW - perform no translation (PDP/10 characters simply discard + the high order bit of LISP machine characters, and LISP machine + characters supplied by a server will always be in the range + <000, 177>. + + SUPER-IMAGE - This suppresses the use of rubout for quoting. + That is, each entry beginning with a 177 in the PDP/10 column of + the translation table presented above, has the 177 removed. The + PDP/10 character 015 always maps to the LISP machine character + 215, as in normal translation. Here is the corrected table: + + LISP machine character PDP/10 character(s) + + x in <000, 177> x + x in <200, 214> + 215 015 012 + x in <216, 376> + 377 no corresponding code + + User programs written for PDP/10's probably do not wish to have +any of the above translations performed, since they are using the PDP/10 +7-bit character set. Hence, RAW is probably what you want. It is also +the most efficient method of transferring ASCII data using the protocol. + +---------------------------------------------------------------- + +Data transfer and byte packing issues: + + Once a DATA connection has been established, and an OPEN has +succeeded, data transfer proceeds by sending/receiving packets on the +appropriate DATA connection. CHARACTER data is always in packets with +opcode %CODAT (200), and BINARY data in packets with opcode 300 octal. +Consider the data portion of a packet as a sequence of 8-bit bytes, in +the fashion usual for the CHAOS net. Then CHARACTER data is always +packed one character per packet byte. The organization is such that a +standard PDP/10 byte pointer of size 8-bits can be used to load or store +characters into a packet sequentially. (As usual, the low 4 bits of +each 36-bit word is ignored, and not even transmitted on the CHAOS net.) +There are no particular restrictions on the minimum or maximum sizes of +data packets, other than hardware or operating system limits. The +server will always send the largest packets it can. + + The situation with BINARY data is slightly more complicated. We +must consider the data portion of a packet as a sequence of 16-bit +bytes. Each 16-bit byte consists of two 8-bit bytes, with the first of +the two 8-bit bytes being the high-order half of the 16-bit byte. (This +corresponds to PDP/10 conventions, but is the opposite of PDP/11 +conventions regarding byte packing.) Each byte of binary data sent is +stored in one 16-bit byte in the packet. If the byte size is less than +16-bits, then the byte is right-justified within the 16-bits, with the +remaining high order bits set to unpredictable values. The organization +is such that loading or storing sequential bytes in a packet can be done +with a standard PDP/10 byte pointer of byte size 16 bits, and transfer +of the bytes so obtained to or from words of files can be done with a +byte pointer of the size in use for the transfer. + + Each packet of BINARY data should contain an integral number of +16-bit bytes, i.e., it should have an even nmber of 8-bit bytes. If it +does not, the odd byte is discarded. The server always sends binary +packets with an even number of 8-bit bytes. + + For transferring all 36 bits of a PDP/10 word to another 36 bit +machine, the byte size must divide 36. The most efficient value is 12, +since it is the largest divisor of 36 that is not greater than 16, which +is the largest byte size supported by the protocol. + +---------------------------------------------------------------- + +Protocol issues in data transfer: + + In addition to just data packets, some other kinds of +informative packets are sent or received on the DATA connection. + + EOF packets (opcode 014) are used to mark end of file when +reading or writing. That is, when you are writing a file and come to +the end of what you wish to write, you will send an EOF packet to tell +the server it has reached the end. Similarly, you will receive an EOF +packet at the end of a file when reading. EOF packets are always empty +(i.e., contain no data). There are additional details about closing a +file, however; read on. + + In addition to EOF packets, SYNCHRONOUS MARKS (opcode 201) are +used to separate groups of packets in the transfer, mainly for purposes +of matching up with FILEPOS and SET-BYTE-SIZE commands. You will +receive a synchronous mark on the DATA connection sometime after each +successful FILEPOS and SET-BYTE-SIZE command. These marks indicate the +place in the data stream where the command actually occurred. They are +necessary because the server may be several packets ahead of you in +sending data, and without the marks there would be no easy way to tell +where the previous information ended and the new information starts. A +synchronous mark is also sent in response to a CLOSE command when +reading, and expected after an EOF when writing. The mark after a CLOSE +when reading allows you to find the end of the data packets for that +transfer, if you decide to stop the transfer in the middle. The mark +after EOF when writing performs a similar function for the server if you +terminate the transfer in the middle. + + When writing, you should send a synchronous mark on the DATA +connection whenever you perform a successful SET-BYTE-SIZE command, and +also as part of a CLOSE, as described above. All other synchronous +marks are ones that you will receive. + +Examples: + +1) Reading a file. Assume you have a CONTROL connection and an idle +DATA connection. Send an OPEN command, and await the response. Then +start reading data packets from the data channel. The transfer will +continue unless you stop it. Suppose you have read all the file. Then +you will see an EOF packet. Send your CLOSE command, to order the file +closed, and await a SYNC mark on the DATA connection, indicating that +the close is in fact done, and the DATA connection can be re-used for +some other purpose. If you decide to quit in the middle, send a CLOSE +command, and get the response, and read packets from the DATA connection +until you see a SYNC mark. (This assumes that there would be no other +SYNC marks in transit because of, say, a previous FILEPOS command, etc. +If there were any of those, you will have to wait through the +appropriate number of SYNC marks.) + +2) Writing a file. Again assume you have established a CONTROL and DATA +connection. Send the OPEN command and await the reponse. Then start +writing packets on the DATA connection. Assuming there are no problems, +send an EOF. WAIT FOR THE EOF TO BE ACKNOWLEDGED BY THE SERVER. (That +is, a CHAOS net acknowledgement indicating that the server has actually +read the EOF packet.) Now send a SYNC mark on the DATA connection and a +CLOSE on the CONTROL connection (in either order). If you do not wait +for the EOF to be acknowledged, and you send a CLOSE anyway, the file +may be truncated because some data packets may not have been processed +by the server. + +---------------------------------------------------------------- + +Errors and Ansynchronous marks: + + ASYNCHRONOUS MARK packets (opcode 202) indicate error conditions +in the transfer, such as running out of disk space or allocation. Some +of these may be recoverable, some not. When reading, an asynchronous +mark will come in over the appropriate DATA connection. When writing, +it will come in on the CONTROL connection. (The DATA connection is not +used in this case because the receive half might be in use for another +transfer). Here is the format of an asynchronous mark packet: + + tid fh ERROR erc c message + +That is, it looks like a regular error response packet, except that it +has a different opcode (responses are data packets, opcode 200). The +tid should be ignored -- it will be somewhat random (whatever happens to +to be lying around). The file handle, fh, is useful when writing, to +see which DATA connection the error happened to. The "erc" part is a 3 +character error code (a table of them is presented below, subject to +change without notice). The single character "c" will be either "R" +(for recoverable) or "F" (for fatal). A recoverable error can be +restarted from by sending an appropriate CONTINUE command. A fatal +error cannot be recovered from, and an appropriate CLOSE should be +performed. The "message" part is an ASCII error message, possibly +obtained from the host operating system. + +Error codes: + +Flag codes: + C = command error (comes in data packet with cmd = "ERROR", on + the CONTROL connection). + F = fatal asynchronous error. + R = restartable asynchronous error. + +Flag Code Message, Causes, Possible Diagnosis + +C CCC - CHANNEL CANNOT CONTINUE + CONTINUE not possible. +C CNO - CHANNEL NOT OPEN + CLOSE on non-open channel. +C CRF - CANNOT RENAME OUTPUT FILE TO REAL NAMES + Final RENMWO for CLOSE on ITS failed. +F CSP - CANNOT SET POINTER + Response to this failure in FILEPOS or SET-BYTE-SIZE. +C FNF - message varies, depending on reason (FILE NOT FOUND). + Failing OPEN. +C IBS - ILLEGAL BYTE SIZE + Response to byte size not in range 1 - 16. +F IDO - ILLEGAL DATA OPCODE + Bad packet opcode in the range 200 - 377 (you should use + 200 for CHARACTER data, and 300 for BINARY) +C IFH - ILLEGAL FILE HANDLE FOR FILEPOS + Only input file handles are legal. +R IOC - message varies (INPUT OUTPUT CONDITION). + Generic code for possibly recoverable failures. This + will be sent in an ASYNC mark packet. +F IPO - ILLEGAL PACKET OPCODE + Received a packet with an illegal opcode, or a SYNC or + ASYNC mark when not expected. +C IRF - ILLEGAL REQUEST FORMAT + Generic response to ill-formed command. +C ISC - ILLEGAL CHANNEL FOR SET-BYTE-SIZE + SET-BYTE-SIZE may only be done on BINARY channels. +C NCN - NULL COMMAND NAME + Particular case of a bad command. +C NER - NOT ENOUGH RESOURCES + Possible causes are: no more I/O channels/jfns available + for new DATA connections, system failure to open a new + CHAOSnet channel, and inability to lookup a user's info + in LOGIN. +C NLI - NOT LOGGED IN + OPEN cannot be done until you are logged in. +C TMI - TOO MUCH INFORMATION + This happens if a response or error packet overflows. +C UFH - UNKNOWN FILE HANDLE + Particular case of an ill-formed command. +C UKC - UNKNOWN COMMAND + Particular case of an ill-formed command. +C UNK - USER NOT KNOWN + Bad LOGIN (TOPS-20 only). +C UOO - UNKNOWN OPEN OPTION + Obvious problem. +F xxx - ??? When a file system or other operating system call + fails, which is not covered in the above, then another code is + used. These are taken from a table for ITS, with the message + read from the ERR: device, and on TOPS-20, the letters are the + first letters of the first three words of the error message + returned by an ERSTR call. The only exception is code FNF, + special cased if the error is GJFX24 ("file not found") or OPNX2 + ("file does not exist") on TOPS-20. No other FNF's will come + from TOPS-20, even by "accidient" -- a special check is made. diff --git a/doc/sysdoc/clo.100 b/doc/sysdoc/clo.100 new file mode 100755 index 00000000..13b93333 --- /dev/null +++ b/doc/sysdoc/clo.100 @@ -0,0 +1,169 @@ +-*-Text-*- Alan 12/31/83 + +Here is what I know about the core link device(s). + +The core link device is a primitive mechanism for connecting two jobs +together with a uni-directional stream. The basic idea is very simple: +suppose job A opens CLO:FOO;BAR BAZ for input and job B opens +CLO:FOO;BAR BAZ for output, then by virtue of the fact that they used the +same name (FOO;BAR BAZ) they are connected together and anything job B +happens to output to its channel will be what job A reads from its channel. +For many simple hacks, that's all you really need to know about it! + +The core link device is not a random access device. Only the most basic +system calls are supported (like OPEN, IOT, SIOT, STATUS, RFNAME, and +CLOSE). There is no way for either job to cause the other to receive a +second word interrupt. For more advanced applications where a more +complicated interface is desired the JOB device can be used. See +.INFO.;ITS JOBONL (or .INFO.;ITS JOB). + +ITS keeps an I/O buffer for each core link, so the two jobs will not +actually be kept running in lock-step. The outputting job will wait when +it tries to output only if the buffer becomes full, and the inputting job +will wait when it tries to input only if the buffer becomes empty. The +buffer is about 100. words long. Because of this buffering it is not +necessary for both jobs to open their channels in identical modes, one job +can read (write) 36-bit words while the other is writing (reading) 7-bit +characters. [This should be contrasted with the JOB device, where ITS +cannot keep any internal state for the JOB/BOJ connection because of +PCLSRing considerations.] + +If the reading job closes its input channel, the writing job's output +channel acts like the NUL device. All output is simply discarded. If the +writing job closes its output channel, the reading job's input channel acts +like it has reached end of file (after it has read whatever remained in the +buffer of course). [Actually, in .UII mode if you IOT beyond end of file +it starts returning random 36-bit words. It should be fixed to generate an +IOC interrupt like other devices do at EOF in .UII mode. I guess it really +doesn't matter much since you don't open things in image mode unless you +know exactly what they are anyway...] + +There are actually 4 core link devices: CLO (Core Link Open), CLU (Core +Link Use), CLI (Core Link Interrupt), and CLA (Core Link Answer). The +differences between them all have to do with what happens when you open +them. In fact, after you have completed the process of opening a channel +with any of these devices, an RFNAME call on that channel will always +report that it is the CLO device, since from that point on they all behave +identically. + +In order match up jobs that desire to use the core link device, ITS +maintains a table called the "core link directory". At any given time the +core link directory contains a number of "core links". Each core link has +three names: an SNAME, a first name, and a second name (SNAME;NAME1 NAME2). + +When a job tries to open CLO:FOO;BAR BAZ, ITS searches the core link +directory for a core link named FOO;BAR BAZ. If no core link is found with +that name, then a new core link is created with that name and entered in +the directory. (If the core link directory gets full a %EFLDR error can be +returned at this point.) + +The CLU device behaves identically to the CLO device, except that if no +existing core link has the proper name then instead of creating a new one, +a file not found error is returned (%ENSFL). Thus you should use the CLU +device when you are certain that some other job has already created a core +link of a given name. + +Also potentially associated with each core link is a pair of jobs. One for +reading, and one for writing. After an appropriately named core link has +been located or created, ITS checks to see whether some other job already +has this core link open in the same direction. If so, a file locked error +is returned (%ENAFL), otherwise this job is recorded as the one reading or +writing the core link, and the channel is successfully opened. + +You can list the core link directory. Opening CLO:.FILE. (DIR) will +allow you to read a table like the following: + + SNAME NAME1 NAME2 ALAN A -> ALAN B + SPAZM FOOBAR 259 CLOSED-> ALAN A + QAZWSX FOOBAR 259 ALAN FOOBAR-> CLOSED + FOO BAR BAZ CLOSED-> CLOSED + +(Try typing CLO^F to DDT. Probably the core link directory will be empty, +so you won't seen anything interesting.) + +This table is interpreted as follows: + + SNAME NAME1 NAME2 ALAN A -> ALAN B + ^ ^ ^ ^ ^ ^ ^ + | | | | | | | UNAME and JNAME of + | | | | | +------+--- job reading from + | | | | | this core link. + | | | | | + | | | | | UNAME and JNAME of + | | | +------+---job writing into + | | | this core link. + | | | + | | | SNAME and first and + +------+------+---second names for + this core link. + +If no job is reading from the core link, the word CLOSED will appear after +the arrow instead of a UNAME/JNAME pair. Similarly if no job is writing +into the core link, CLOSED appears before the arrow. + +If you are trying to debug something that uses the core link device, a +listing of the core link directory is a valuable debugging aid. + +In the core link directory listing above, the core link named FOO;BAR BAZ +has neither an associated reading nor writing job. You might think that +such a core link would be worthless, but this is not necessarily the case! +Suppose that job A opens CLO:FOO;BAR BAZ for output intending to only +transmit 100. ascii characters through the link. Since 100. characters can +easily fit in the core link's buffer, job A can output all 100. characters +and close its channel before the reading job even gets as far as opening +its channel. Thus for a brief time the core link has no associated jobs. + +Unfortunately there is no way to guarantee that any job will ever open the +core link FOO;BAR BAZ for input to pick up those 100. characters. For this +reason ITS will garbage collect any core link that has not had any +associated jobs for several minutes (about 5 minutes). + +You can also delete core links from the core link directory yourself. Thus +from DDT you can type "^O CLO:FOO;BAR BAZ" to get rid of a garbage core +link. Normally there is no need to do this, since ITS will flush them +eventually anyway. [Indeed, it is a BAD idea to use this feature currently +because there is a bug such that instead of deleting the core link, you +sometimes cause it to become permanently locked down. Since there are a +finite number of core links (12. currently), if you do this often enough +you will render the core link device unusable.] + +A reasonable person might wonder what happens if some job tries to re-open +the core link FOO;BAR BAZ for output and write more characters into it. +Well, each core link actually acts as a SEQUENCE of files separated by +end-of-file markers. If a second job opens CLO:FOO;BAR BAZ and writes more +data into it, that data will be available to the SECOND job that opens that +core link for input. Thus if one job is in a loop opening the core link +named FOO;BAR BAZ, outputting a single character, and then closing it +again, and a second job is in a loop opening that core link, reading +characters until end of file, and then closing it again, then the second +job will see a sequence of single character length files. + +We haven't yet mentioned the CLI and CLA devices. These two devices enable +one job to interrupt another job indicating that it wishes to send a +message through a core link. This is how interactive messages work on ITS. + +The sending job opens the CLI device with first and second filenames equal +to the UNAME and JNAME of the job that it wishes to interrupt. For +example, a job might try to open CLI:CSTACY HACTRN (any SNAME supplied will +be ignored). ITS then checks to see that a job named CSTACY HACTRN really +does exist. If it does, ITS checks to see that that job has enabled the +%PICLI interrupt. If it is not the case that both conditions are met, the +open returns an illegal file name error (%EBDFN). If both conditions are +met, then we proceed as if we were opening CLO:_CLI_;CSTACY HACTRN. If +that succeeds, then we actually give the job CSTACY HACTRN the %PICLI +interrupt, and the open succeeds. + +The UNAME and JNAME of the sending job are now placed in the core link's +I/O buffer so that the receiving job will be able to read them out before +any additional data that the sender might wish to transmit. (Note that you +can only open the CLI device for output.) + +In order to handle the %PICLI interrupt the job CSTACY HACTRN opens CLA: +(any additional names supplied will be ignored). This is like opening +CLU:_CLI_;CSTACY HACTRN, except that it saves the interrupted job from +having to figure out its own name. The receiving job can now read the +UNAME and JNAME of its interrupter by inputting the first two 36-bit words +from the newly opened channel. + +The jobs are now talking through an ordinary core link named +_CLI_;CSTACY HACTRN. diff --git a/doc/sysdoc/devdoc.5 b/doc/sysdoc/devdoc.5 new file mode 100755 index 00000000..e7e8c0aa --- /dev/null +++ b/doc/sysdoc/devdoc.5 @@ -0,0 +1,108 @@ + +SUBTTL I/O DEVICE DISPATCH TABLES + +COMMENT | + This page tries to document the ITS I/O device dispatch tables and +dispatch environment. It is not completed yet. + +The tables use several different indices, which are: + opnidx - result of device name lookup in DEVTAB + ioidx - result of OPEN; has symbolic values. This is the index + stored in RH of IOCHNM (per-job channel table) + sidx - secondary index from DCHSTB(ioidx) + ridx - secondary index from RSTB(ioidx) + +The following system calls are dispatched through these tables. +There are 11 dispatch routines that each device must specify. +The format is "CALL [table name(index-used) -> device-routine]" +Unless otherwise noted, context for all routines has + U/ User index + R/ addr of IOCHNM word for specified channel +and the phrase "all ACs can be used" excludes P and U, of course. +and routines can hang (u.o.n.) + +OPEN [DEVADR(opnidx) -> devO] + "opnidx" is looked up from DEVTAB which holds the device names. + The device's OPEN routine is in the RH of DEVADR. + It must set up the user's IOCHNM word for the channel, + by setting the RH to the right "ioidx" and the LH to whatever + the device wants. + + Context: + A/ FN1 + B/ FN2 + C/ ,, + D/ + E/ + TT/ DEVADR word ,, + W/ "open" command (0= Normal R/W open, 1= Write-over mode, + 2= Make link, 4= Delete or rename) + SRN3(U),SRN4(U),SRN5(U) - args 4,5,6 (if present) + + Routine is JRST'd to, and must return via POPJ1 for success. + Errors should JRST to the appropriate OPNLnn label. + All ACs can be smashed. + +CLOSE [CLSTB(ioidx) -> devCLS] + The device's CLOSE routine is in the RH of CLSTB. + + Context: + A/ 0,, + B/ 0,, + C/ CLSTB entry, ,, + R/ addr of IOCHNM word + Called via PUSHJ, must return via POPJ (IOCHNM and IOCHST will + be cleared immediately after return). + Can smash all ACs including R. + Must NOT hang! + +IOT, SIOT [IOTTB(ioidx) -> devVarious] + These routines do I/O transfers. The main reason "ioidx" + has so many possible values (causing IOTTB to be large) is + because lots of devices specify different ioidx's for different + modes - input/output, block/unit, image/ascii, etc - in order + to speed up actual I/O transfers, which are probably the most + common device-related system calls. + + Context: + Boy is this complicated. + +STATUS [LH(DSTSTB(sidx)) -> devSTA] + Context: + R/ addr of IOCHNM word + Called by PUSHJ, must return by POPJ + Must return in RH(D) some device-dependent status stuff. + Calling routine (NSTATUS) fills in the LH from IOCHST. + Must not smash C,R! Probably should not smash other + stuff either, depending on what USRVAR/USET need. + +WHYINT [RH(DSTSTB(sidx)) -> devWHY] + +RCHST, RFNAME [LH(DRFNTB(sidx)) -> devRCH] + +RFPNTR [RH(DRFNTB(sidx)) -> devRFP] + +IOPUSH, IOPOP [LH(RSTB1(ridx)) -> devIOP] + +RESET [RH(RSTB1(ridx)) -> devRST] + Context: + R/ addr of IOCHNM wd + Called by JRST from NRESET/ARESET/AIOPP1, must return by POPJ. + Can clobber all ACs. Must not hang. + +FORCE [LH(DFRCTB(ridx)) -> devFRC] + Context: + A/ LH of IOCHNM word, in RH. + H/ IOCHNM word + R/ ,, + Called by JRST from NFORCE. Returns by POPJ1 for win, + POPJ if fail. Should not clobber context that FINISH routine + may need. + +FINISH [RH(DFRCTB(ridx)) -> devFIN] + Same as FORCE, except that FORCE is called first, thus + context is whatever FORCE leaves behind. This routine + must do the actual waiting for FORCE's actions to be + finished. + +| diff --git a/doc/sysdoc/grphcs.21 b/doc/sysdoc/grphcs.21 new file mode 100755 index 00000000..d6e033ce --- /dev/null +++ b/doc/sysdoc/grphcs.21 @@ -0,0 +1,638 @@ + This file was moved to MIT-MC from + MIT-AI by David C. Plummer on 6 June + 1981, and may be up to date. + + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + + +Network Working Group Richard Stallman +Request for Comments 746 MIT-AI +NIC 43976 17 March 1978 + + +The SUPDUP Graphics Extension + + ... extends SUPDUP to permit the display of drawings on the +screen of the terminal, as well as text. We refer constantly to the +documentation of the SUPDUP protocol, described by Crispin in RFC 734 +"SUPDUP Protocol". + + Since this extension has never been implemented, it presumably +has some problems. It is being published to ask for suggestions, and +to encourage someone to try to bring it up. + + The major accomplishments are these: + +* It is easy to do simple things. + +* Any program on the server host can at any time begin + outputting pictures. No special preparations are needed. + +* No additional network connections are needed. Graphics + commands go through the normal text output connection. + +* It has nothing really to do with the network. It is suitable + for use with locally connected intelligent display terminals + in a terminal-independent manner, by programs which need not + know whether they are being used locally or remotely. It can be + used as the universal means of expression of graphics output, for + whatever destination. Programs can be written to use it for + non-network terminals, with little loss of convenience, and + automatically be usable over the ARPA network. + +* Loss of output (due, perhaps, to a "silence" command typed + by the user) does not leave the user host confused. + +* The terminal does not need to be able to remember the + internal "semantic" structure of the picture being + displayed, but just the lines and points, or even just bits + in a bit matrix. + +* The server host need not be able to invoke arbitrary + terminal-dependent software to convert a standard language + into one that a terminal can use. Instead, a standard + language is defined which all programmable terminals can + interpret easily. Major differences between terminals are + catered to by conventions for including enough redundant + information in the output stream that all types of terminals + will have the necessary information available when it is + needed, even if they are not able to remember it in usable + form from one command to another. + + Those interested in network graphics should read about the +Multics Graphics System, whose fundamental purpose is the same, but +whose particular assumptions are very different (although it did +inspire a few of the features of this proposal). + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +SUPDUP Initial Negotiation: + + One new optional variable, the SMARTS variable, is defined. It +should follow the other variables sent by the SUPDUP user process to +the SUPDUP server process. Bits and fields in the left half-word of +this variable are given names starting with "%TQ". Bits and fields in +the right half are given names starting with "%TR". Not all of the +SMARTS variable has to do with the graphics protocol, but most of it +does. The %TQGRF bit should be 1 if the terminal supports graphics +output at all. + + +Invoking the Graphics Protocol: + + Graphics mode is entered by a %TDGRF (octal 231) code in the +output stream. Following characters in the range 0 - 177 are +interpreted according to the graphics protocol. Any character 200 or +larger (a %TD code) leaves graphics mode, and then has its normal +interpretation. Thus, if the server forgets that the terminal in +graphics mode, the terminal will not long remain confused. + + Once in graphics mode, the output stream should contain a +sequence of graphics protocol commands, each followed by its +arguments. A zero as a command is a no-op. To leave graphics mode +deliberately, it is best to use a %TDNOP. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Co-ordinates: + + Graphics mode uses a cursor position which is remembered from one +graphics command to the next while in graphics mode. The graphics +mode cursor is not the same one used by normal type-out: Graphics +protocol commands have no effect on the normal type-out cursor, and +normal type-out has no effect on the graphics mode cursor. In +addition, the graphics cursor's position is measured in dots rather +than in characters. The relationship between the two units (dots, and +characters) is recorded by the %TQHGT and %TQWID fields of the SMARTS +variable of the terminal, which contain the height and width in dots +of the box occupied by a character. The size of the screen in either +dimension is assumed to be the length of a character box times the +number of characters in that direction on the screen. If the screen +is actually bigger than that, the excess may or may not be part of +the visible area; the program will not know that it exists, in any +case. + + Each co-ordinate of the cursor position is a 14-bit signed +number, where zero is at the center of the screen (if the screen +dimension is an even number of dots, then the visible negative points +extend one unit farther than the positive ones, in proper two's +complement fashion). Excessively large values of the co-ordinates +will be off the screen, but are still meaningful. + + An alternate mode is defined, which some terminals may support, +in which virtual co-ordinates are used. The specified co-ordinates +are still 14-bit signed numbers, but instead of being in units of +physical dots on the terminal, it is assumed that +4000 octal is the +top of the screen or the right edge, while -4000 octal is the bottom +of the screen or the left edge. The terminal is responsible for +scaling these virtual co-ordinates into units of screen dots. Not all +terminals need have this capability; the %TQVIR bit in the SMARTS +variable indicates that it exists. To use virtual co-ordinates, the +server should send a %GOVIR; to use physical co-ordinates again, it +should send a %GOPHY. These should be repeated at intervals, such as +when graphics mode is entered, even though the terminal must attempt +to remember the state of the switch anyway. This repetition is so +that a loss of some output will not cause unbounded confusion. + + The virtual co-ordinates are based on a square. If the visible +area on the terminal is not a square, then the standard virtual range +should correspond to a square around the center of the screen, and the +rest of the visible area should correspond to virtual co-ordinates +just beyond the normally visible range. + + Graphics protocol commands take two types of cursor position +arguments, absolute ones and relative ones. Commands that take +address arguments generally have two forms, one for each type of +address. A relative address consists of two offsets, delta-X and +delta-Y, from the old cursor position. Each offset is a 7-bit two's +complement number occupying one character. An absolute address +consists of two co-ordinates, each 14 bits long, occupying two +characters, each of which conveys 7 bits. The X co-ordinate or offset +precedes the Y. Both types of address set the running cursor position +which will be used by the next address, if it is relative. It is +perfectly legitimate for parts of objects to go off the screen. What +happens to them is not terribly important, as long as it is not +disastrous, does not interfere with the reckoning of the cursor +position, and does not cause later objects, drawn after the cursor +moves back onto the screen, to be misdrawn. + + Whether a particular spot on the screen is specified with an +absolute or a relative address is of no consequence. The sequence in +which they are drawn is of no consequence. Each object is independent +of all others, and exists at the place which was specified, in one way +or other, by the command that created it. Relative addresses are +provided for the sake of data compression. They are not an attempt to +spare programs the need for the meagre intelligence required to +convert between absolute and relative addresses; more intelligence +than that will surely be required for other aspects of the graphics +protocol. Nor are relative addresses intended to cause several +objects to relocate together if one is "moved" or erased. Terminals +are not expected to remember any relation between objects once they +are drawn. Most will not be able to. + + Although the cursor position on entry to graphics mode remains +set from the last exit, it is wise to reinitialize it with a %GOMVA +command before any long transfer, to limit the effects of lost output. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Commands: + + Commands to draw an object always have counterparts which erase +the same object. On a bit matrix terminal, erasure and drawing are +almost identical operations. On a display list terminal, erasure +involves searching the display list for an object with the specified +characteristics and deleting it from the list. Thus, on such +terminals you can erase an object only if precisely that object was +drawn, and was specified the same way when drawn as when erased. +(presumably; a very hairy program might allow more). Any terminal +whose %TOERS bit is set must be able to erase to at least that extent. + + The commands to draw objects run from 100 to 137, while those to +erase run in a parallel sequence from 140 to 177. Other sorts of +operations have command codes below 100. Meanwhile, the 20 bit in the +command code says which type of addresses are used as arguments: if +the 20 bit is set, absolute addresses are used. Graphics commands are +given names starting with "%GO". + + Graphics often uses characters. The %GODCH command is followed +by a string of characters to be output, terminated by a zero. The +characters must be single-position printing characters. On most +terminals, this limits them to ASCII graphic characters. Terminals +with %TOSAI set in the TTYOPT variable allow all characters 0-177. +The characters are output at the current graphics cursor position (the +lower left hand corner of the first character's rectangle being placed +there), which is moved as the characters are drawn. The normal +type-out cursor is not relevant and its position is not changed. The +cursor position at which the characters are drawn may be in between +the lines and columns used for normal type-out. The %GOECH command is +similar to %GODCH but erases the characters specified in it. To clear +out a row of character positions on a bit matrix terminal without +having to respecify the text, a rectangle command may be used. + + +Example: + + The way to send a simple line drawing is this: + + %TDRST ;Reset all graphics modes. + %TDGRF ;Enter graphics. + %GOCLR ;Clear the screen. + %GOMVA xx yy ;Set cursor. + %GODLA xx yy ;Draw line from there. + << repeat last two commands for each line >> + %TDNOP ;Exit graphics. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Graphics Input: + + The %TRGIN bit in the right half of the SMARTS variable indicates +that the terminal can supply a graphic input in the form of a cursor +position on request. Sending a %GOGIN command to the terminal asks to +read the cursor position. It should be followed by an argument +character that will be included in the reply, and serve to associate +the reply with the particular request for input that elicited it. The +reply should have the form of a Top-Y character (code 4131), followed +by the reply code character as just described, followed by an absolute +cursor position. Since Top-Y is not normally meaningful as input, +%GOGIN replies can be distinguished reliably from keyboard input. +Unsolicited graphic input should be sent using a Top-X instead of a +Top-Y, so that the program can distinguish them. Instead of a reply +code, for which there is no need, the terminal should send an encoding +of the buttons pressed by the user on his input device, if it has more +than one. + + +Sets: + + Terminals may define the concept of a "set" of objects. There +are up to 200 different sets, each of which can contain arbitrarily +many objects. At any time, one set is selected; objects drawn become +part of that set, and objects erased are removed from it. Objects in +a set other than the selected one cannot be erased without switching +to the sets that contain them. A set can be made temporarily +invisible, as a whole, without being erased or its contents forgotten; +and it can then be made instantly visible again. Also, a whole set +can be moved. A set has at all times a point identified as its +"center", and all objects in it are actually remembered relative to +that center, which can be moved arbitrarily, thus moving all the +objects in the set at once. Before beginning to use a set, therefore, +one should "move" its center to some absolute location. Set center +motion can easily cause objects in the set to move off screen. When +this happens, it does not matter what happens temporarily to those +objects, but their "positions" must not be forgotten, so that undoing +the set center motion will restore them to visibility in their +previous positions. Sets are not easily implemented on bit matrix +terminals, which should therefore ignore all set operations (except, +for a degenerate interpretation in connection with blinking, if that +is implemented). The %TQSET bit in the SMARTS variable of the +terminal indicates that the terminal implements multiple sets of +objects. + + On a terminal which supports multiple sets, the %GOCLR command +should empty all sets and mark all sets "visible" (perform a %GOVIS on +each one). So should a %TDCLR SUPDUP command. Thus, any program +which starts by clearing the screen will not have to worry about +initializing the states of all sets. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Blinking: + + Some terminals have the ability to blink objects on the screen. +The command %GOBNK meaning make the current set blink. All objects in +it already begin blinking, and any new objects also blink. %GOVIS or +%TOINV cancels the effect of a %GOBNK, making the objects of the set +permanently visible or invisible. %TQBNK indicates that the terminal +supports blinking on the screen. + + However, there is a problem: some intelligent bit matrix +terminals may be able to implement blinking a few objects, if they are +told in advance, before the objects are drawn. They will be unable to +support arbitrary use of %GOBNK, however. + + The solution to the problem is a convention for the use of %TOBNK +which, together with degenerate definitions for set operations, makes +it possible to give commands which reliably work on any terminal which +supports blinking. + + On a terminal which sets %TQBNK but not %TQSET, %GOBNK is defined +to cause objects which are drawn after it to be drawn blinking. +%GOSET cancels this, so following objects will be drawn unblinking. +This is regardless of the argument to the %GOSET. + + Thus, the way for a program to work on all terminals with %TQBNK, +whether they know about sets or not, is: to write a bliniking +picture, select some set other than your normal one (set 1 will do), +do %GOBNK, output the picture, and reselect set 0. The picture will +blink, while you draw things in set 0. To draw more blinking objects, +you must reselect set 1 and do another %GOBNK. Simply reselecting set +1 will not work on terminals which don't really support sets, since +they don't remember that the blinking objects are "in set 1" and not +"in set 0". + + Erasing a blinking object should make it disappear, on any +terminal which implements blinking. On bit matrix terminals, blinking +MUST always be done by XORing, so that the non-blinking background +is not destroyed. + + %GOCLS, on a terminal which supports blinking but not sets, +should delete all blinking objects. Then, the convention for deleting +all blinking objects is to select set 1, do a %GOCLS, and reselect set +0. This has the desired effect on all terminals. This definition of +%GOCLS causes no trouble on non-set terminals, since %GOCLS would +otherwise be meaningless to them. + + To make blinking objects stop blinking but remain visible is +possible with a %GOVIS on a terminal which supports sets. But in +general the only way to do it is to delete them and redraw them as +permanent. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Rectangles and XOR Mode: + + Bit matrix terminals have their own operations that display list +terminals cannot duplicate. First of all, they have XOR mode, in +which objects drawn cancel existing objects when they overlap. In +this mode, drawing an object and erasing it are identical operations. +All %GOD.. commands act IDENTICALLY to the corresponding %GOE..'s. +XOR mode is entered with a %GOXOR and left with a %GOIOR. Display +list terminals will ignore both commands. For that reason, the +program should continue to distinguish draw commands from erase +commands even in XOR mode. %TQXOR indicates a terminal which +implements XOR mode. XOR mode, when set, remains set even if graphics +mode is left and re-entered. However, it is wise to re-specify it +from time to time, in case output is lost. + + Bit matrix terminals can also draw solid rectangles. They can +thus implement the commands %GODRR, %GODRA, %GOERR, and %GOERA. A +rectangle is specified by taking the current cursor position to be one +corner, and providing the address of the opposite corner. That can be +done with either a relative address or an absolute one. The %TQREC +bit indicates that the terminal implements rectangle commands. + + Of course, a sufficiently intelligent bit matrix terminal can +provide all the features of a display list terminal by remembering +display lists which are redundant with the bit matrix, and using them +to update the matrix when a %GOMSR or %GOVIS is done. However, most +bit matrix terminals are not expected to go to such lengths. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +How Several Process Can Draw On One Terminal Without Interfering With +Each Other: + + If we define "input-stream state" information to be whatever +information which can affect the action of any command, other than +what is contained in the command, then each of the several processes +must have its own set of input-stream state variables. + + This is accomplished by providing the %GOPSH command. The %GOPSH +command saves all such input-stream information, to be restored when +graphics mode is exited. If the processes can arrange to output +blocks of characters uninterruptibly, they can begin each block with a +%GOPSH followed by commands to initialize the input-stream state +information as they desire. Each block of graphics output should be +ended by a %TDNOP, leaving the terminal in its "normal" state for all +the other processes, and at the same time popping the what the %GOPSH +pushed. + + The input-stream state information consists of: + The cursor position + the state of XOR mode (default is OFF) + the selected set (default is 0) + the co-ordinate unit in use (physical dots, or virtual) + (default is physical) + whether output is going to the display screen or to a hardcopy + device (default is to the screen) + what portion of the screen is in use + (see "Using Only Part of the Screen") + (default is all) + + Each unit of input-stream status has a default value for the sake +of programs that do not know that the information exists; the +exception is the cursor position, since all programs must know that it +exists. A %TDINI or %TDRST command should set all of the variables to +their default values. + + The state of the current set (whether it is visible, and where +its center is) is not part of the input-stream state information, +since it would be hard to say what it would mean if it were. Besides, +the current set number is part of the input-stream state information, +so different processes can use different sets. The allocation of sets +to processes is the server host's own business. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Using Only Part of the Screen: + + It is sometimes desirable to use part of the screen for picture +and part for text. Then one may wish to clear the picture without +clearing the text. On display list terminals, %GOCLR should do this. +On bit matrix terminals, however, %GOCLR can't tell which bits were +set by graphics and which by text display. For their sake, the %GOLMT +command is provided. This command takes two cursor positions as +arguments, specifying a rectangle. It declares that graphics will be +limited to that rectangle, so %GOCLR should clear only that part of +the screen. %GOLMT need not do anything on a terminal which can +remember graphics output as distinct from text output and clear the +former selectively, although it would be a desirable feature to +process it even on those terminals. + + %GOLMT can be used to enable one of several processes which +divide up the screen among themselves to clear only the picture that +it has drawn, on a bit matrix terminal. By using both %GOLMT and +distinct sets, it is possible to deal successfully with almost any +terminal, since bit matrix terminals will implement %GOLMT and display +list terminals almost always implement sets. + + The %TDCLR command should clear the whole screen, including +graphics output, ignoring %GOLMT. + + +Errors: + + In general, errors in graphics commands should be ignored. + + Since the output and input streams are not synchronized unless +trouble is taken, there is no simple way to report an error well +enough for the program that caused it to identify just which command +was invalid. So it is better not to try. + + Errors which are not the fault of any individual command, such as +running out of memory for display lists, should also be ignored as +much as possible. This does NOT mean completely ignoring the commands +that cannot be followed; it means following them as much as possible: +moving the cursor, selecting sets, etc. as they specify, so that any +subsequent commands which can be executed are executed as intended. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Extensions: + + This protocol does not attempt to specify commands for dealing +with every imaginable feature which a picture-drawing device can have. +Additional features should be left until they are needed and well +understood, so that they can be done right. + + +Storage of Graphics Commands in Files: + + This can certainly be done. Since graphics commands are composed +exclusively of the ASCII characters 0 - 177, any file that can hold +ASCII text can hold the commands to draw a picture. This is less +useful than you might think, however. Any program for editing, in +whatever loose sense, a picture, will have its own internal data which +determine the relationships between the objects depicted, and control +the interpretation of the programs commands, and this data will all be +lost in the SUPDUP graphics commands for displaying the picture. +Thus, each such program will need to have its own format for storing +pictures in files, suitable for that program's internal data +structure. Inclusion of actual graphics commands in a file will be +useful only when the sole purpose of the file is to be displayed. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Note: the values of these commands are represented as 8.-bit octal +bytes. Arguments to the commands are in lower case inside angle +brackets. + +The Draw commands are: + +Value Name Arguments + + 101 %GODLR

+ Draw line relative, from the cursor to

. + 102 %GODPR

+ Draw point relative, at

. + 103 %GODRR

+ Draw rectangle relative, corners at

and at the + current cursor position. + 104 %GODCH <0> + Display the chars of starting at the current + graphics cursor position. + 121 %GODLA

+ Draw line absolute, from the cursor to

. + The same effect as %GODLR, but the arg is an absolute + address. + 122 %GODPA

+ Draw point absolute, at

. + 123 %GODRA

+ Draw rectangle absolute, corners at

and at the + current cursor position. + +The Erase commands are: + +Value Name Arguments + + 141 %GOELR

+ Erase line relative, from the cursor to

. + 142 %GOEPR

+ Erase point relative, at

. + 143 %GOERR

+ Erase rectangle relative, corners at

and at the + current cursor position. + 144 %GOECH <0> + Erase the chars of starting at the current + graphics cursor position. + 161 %GOELA

+ Erase line absolute, from the cursor to

. + 162 %GOEPA

+ Erase point absolute, at

. + 163 %GOERA

+ Erase rectangle absolute, corners at

and at the + current cursor position. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +The miscellaneous commands are: + +Value Name Arguments + + 001 %GOMVR

+ Move cursor to point

+ 021 %GOMVA

+ Move cursor to point

, absolute address. + 002 %GOXOR + Turn on XOR mode. Bit matrix terminals only. + 022 %GOIOR + Turn off XOR mode. + 003 %GOSET + Select set. is a 1-character set number, 0 - 177. + 004 %GOMSR

+ Move set origin to

. Display list terminals only. + 024 %GOMSA

+ Move set origin to

, absolute address. + 006 %GOINV + Make current set invisible. + 026 %GOVIS + Make current set visible. + 007 %GOBNK + Make current set blink. Canceled by %GOINV or %GOVIS. + 010 %GOCLR + Erase whole screen. + 030 %GOCLS + Erase entire current set (display list terminals). + 011 %GOPSH + Push all input-stream status information, to be + restored when graphics mode is exited. + 012 %GOVIR + Start using virtual co-ordinates + 032 %GOPHY + Resume giving co-ordinates in units of dots. + 013 %GOHRD + Divert output to output subdevice . + =0 reselects the main display screen. + 014 %GOGIN + Request graphics input (mouse, tablet, etc). + is the reply code to include in the answer. + 015 %GOLMT + Limits graphics to a subrectangle of the screen. + %GOCLR will clear only that area. This is for those + who would use the rest for text. + +NWG/RFC# 746 RMS 17-MAR-78 43976 +SUPDUP Graphics Extension + + +Bits in the SMARTS Variable Related to Graphics: + +Note: the values of these bits are represented as octal 36.-bit words, +with the left and right 18.-bit halfword separated by two commas as in +the normal PDP-10 convention. + +Name Value Description + +%TQGRF 000001,,0 terminal understands graphics protocol. + +%TQSET 000002,,0 terminal supports multiple sets. + +%TQREC 000004,,0 terminal implements rectangle commands. + +%TQXOR 000010,,0 terminal implements XOR mode. + +%TQBNK 000020,,0 terminal implements blinking. + +%TQVIR 000040,,0 terminal implements virtual co-ordinates. + +%TQWID 001700,,0 character width, in dots. + +%TQHGT 076000,,0 character height, in dots. + +%TRGIN 0,,400000 terminal can provide graphics input. + +%TRGHC 0,,200000 terminal has a hard-copy device to which output + can be diverted. + +;;;Local Modes: +;;;Mode:Text +;;;Auto Fill Mode:1 +;;;Fill Column:70 +;;;End: diff --git a/doc/sysdoc/intrup.108 b/doc/sysdoc/intrup.108 new file mode 100755 index 00000000..1cf0bba3 --- /dev/null +++ b/doc/sysdoc/intrup.108 @@ -0,0 +1,562 @@ +Overview of ITS User Interrupts + +When ITS wishes to signal a user program of the existence of an +unusual interesting condition or occurrence, it does so via +the "user interrupt" mechanism. This mechanism essentially +causes the user program to call an interrupt handling subroutine +in the middle of what it had been doing. The interrupt handler has +enough information to be able to return to the interrupted code +without any effects on it if desired, and to determine the cause +of the interrupt so as to take appropriate action. The program +can specify which interrupt conditions it wishes to handle, and +what their priority order should be; un-handled interrupts are +either ignored or fatal depending on the condition. Some interrupt +conditions represent errors in the execution of the job; some +indicate the occurrence of asynchronous events such as I/O operation +completion; some exist for debugging and are always fatal. + +The noun "interrupt" may mean either the event of interrupting +a program (causing it to call the handler), or a condition which +can cause a program to be interrupted. Also, the distinction +between an interrupt condition and the bit which is 1 when the +condition is present is often blurred. + +Unlike TENEX, ITS never gives the user an interrupt "in the middle +of a system call". The PC saved by an interrupt is always a user-mode PC. +This is a great advantage when it comes to having the interrupt handler +understand what the interrupted code was doing and fix it up. +System calls will either be finished or backed out of (to be redone) +when it is necessary for the job to be interrupted. To avoid having to +do a lot of work twice, all ITS system calls that take a long time to +complete are designed so that if restarted they will continue from +where they left off. They do this by updating their arguments to +indicate how much progress they have made, just like the BLT instruction. +Now you know why SIOT and block-mode IOT update their pointer and +byte count as they go. + +Section A describes how interrupts are signaled and enabled, etc. +Section B describes what is actually done to a job when it is + interrupted, if it uses the older simple interrupt mechanism. +Section C gives an example of an old-style interrupt handler. +Section D describes what is actually done to a job when it is + interrupted, if it uses the newer vectored interrupt mechanism. +Section E describes the individual interrupt conditions in the + first interrupt request word (.PIRQC). +Section F describes the individual interrupt conditions in the + second interrupt request word (.IFPIR). + +A. The ITS Interrupt Mechanism + +Each ITS job has two "interrupt request words", called .PIRQC +and .IFPIR, and readable with .SUSET. Each distinct interrupt +condition is assigned one of the bits in one of the words. +The interrupt is "pending" when the bit is 1. +.PIRQC is called the "first interrupt word" and interrupts in it +are "first word interrupts". .IFPIR is the "second interrupt word" +and its interrupts are "second word interrupts". + +Interrupt conditions are divided by the system into three severity classes. +Class 1 interrupts are always fatal. They are genarally conditions caused +by the user or the superior, for debugging purposes; for example, +breakpoints, ^Z typed, and single-instruction-proceed interrupts are +of class 1. Class 2 interrupts are fatal unless the program is set up +to handle the interrupt. Most error conditions are class 2; for example, +MPV (memory protect violation), ILOPR (illegal operation), IOCERR +(I/O channel error). All class 1 and 2 interrupts are first word +interrupts. Class 3 interrupts are never fatal unless the user +explicitly makes them so; either the program is eventually interrupted +or nothing happens. Most asynchronous conditions are class 3. + +When a job receives a fatal interrupt, that job is not interrupted +itself; instead, it is stopped, as if its superior had stopped it, +and an "inferior got a fatal interrupt" interrupt is signaled for the +superior. If a top level job receives a fatal interrupt, then it will +be stopped and detached (see the symbolic system call DETACH). + +Each interrupt word has a corresponding mask word: .MASK for .PIRQC, +and .MSK2 for .IFPIR. An interrupt is enabled if the appropriate bit in +the mask word is 1. A program will not receive an interrupt which is +disabled, but if the interrupt condition is in class 2 it +will be fatal if it is not enabled. Class 3 interrupts will not even +be signaled if they are disabled. Class 1 interrupts are not allowed +to be enabled, the idea being that the job which gets an always-fatal +interrupt is not allowed to handle the interrupt itself. + +Each interrupt word also has a defer word: .DF1 for .PIRQC, and +.DF2 for .IFPIR. If the appropriate bit in the defer word is set, +the interrupt is "deferred". For a class 2 interrupt, deferment has +the same effect as disablement: the interrupt becomes fatal. +For a class 1 interrupt, deferment has no effect. For a class 3 +interrupt, deferment differs from disablement in that a deferred +interrupt will still be signaled; it will then remain pending until +it is no longer deferred, when it will be given to the user. +The system makes it easy to defer a specified set of interrupts while +processing an interrupt. That is how different priorities of +interrupts may exist. + +Slightly obsolete but still useful is the variable .PICLR, which is +normally -1. If this variable is set to 0, all interrupts are deferred. +The actual values of the defer words are unaltered. .PICLR was +the original way to defer interrupts, before the defer words existed. +The older style of interrupt handling on ITS sets .PICLR to 0 while +an interrupt is being processed; thus, there is only one interrupt +priority level. + +To help eliminate timing errors, the six variables .PIRQC, .IFPIR, +.MASK, .MSK2, .DF1 and .DF2 have aliases which have the same value +when read, but when written either IORM or ANDCAM into the variable +instead of setting all the bits in it. These aliases are called +.IPIRQC, .IIFPIR, .IMASK, .IMSK2, .IDF1 and .IDF2 for IORM'ing, +and .APIRQC, .AIFPIR, .AMASK, .AMSK2, .ADF1 and .ADF2 for ANDCAM'ing. +Thus, depositing 20 in .APIRQC will clear the 20 bit in .PIRQC. + +Error-condition interrupts (MPV, ILOPR, IOCERR, WIRO, DTTY and some others) +usually abort the instruction that causes them. When this happens, +the old convention (still the default) is to leave the PC pointing +AFTER the aborted instruction. This is very bad since it is hard +for the user's interrupt handler to tell whether to decrement the PC. +The new convention, selected by setting bit %OPOPC in the LH of the +.OPTION variable to 1, is for the system to decrement the PC when +a fatal interrupt happens, so that if the interrupt handler fixes +the problem (e.g. creates the nonexistent page of core) and dismisses, +the instruction will be retried. All new programs should use the +new convention; it would be nice to flush the old one entirely. + +B. How Jobs Are Informed about Their Interrupts (Old Style) + +There are two ways for a program to receive interrupts from the +system: the old way, and the new way. The old scheme always stores +the PC in the same place, making recursive interrupts difficult. +It also makes all interrupts have the same priority level. +The new scheme pushes the interrupt information on a stack. It also +has the ability to decode the interrupts for the user, whereas with the +old mechanism the program must decode the interrupts. Nevertheless, +the old mechanism is not considered obsolete, since it is easier to use. + +Both mechanisms have the user's interrupt handler information pointed +to by location 42. More generally, the address of the interrupt pointer +is 2 plus the rh of the .40ADDR variable; since .40ADDR usually holds +40, the interrupt pointer usually lives in 42. + +The two mechanisms are selected by the %OPINT bit of the .OPTION +variable: the new mode is used if the bit is 1. + +In the old mode, 42 is expected to contain the address of the +interrupt handler itself. Let that address be called "TSINT" +(every program should use that label, for the sake of humans). +If TSINT is 0, or addresses nonexistent or pure storage, +when the system attempts to interrupt the job, an always-fatal +BADPI (%PIB42) interrupt is signaled and the program does not +receive the original interrupts. If the superior, handling the BADPI, +fixes up 42 and restarts the job, it will then be properly interrupted. + +When an interrupt happens, all the +pending enabled undeferred first word interrupts will be given to +the user at once if there are any; otherwise, all the pending +enabled undeferred second word interrupts will be given. The +interrupts which are given will be cleared in the request word. +Whichever interrupt request word is being given will be stored in TSINT. +If the interrupts being handled are second-word interrupts, the sign +of TSINT will be set. The PC is stored in TSINT+1. The job is then +started at TSINT+2, with all PC flags except user and user-i/o zeroed. +The job's .PICLR will be set to 0, preventing further interrupts while +the interrupt handler is running. Because more than one interrupt +may be given to the user at once, the interrupt routine should check +all of the interrupt bits, and after handling one interrupt should +return to check the remaining bits. + +The normal way for the interrupt handler +to exit is with the .DISMIS uuo, which should address a word containing +the desired new PC. .DISMIS jumps to that PC, restoring flags, and also +sets .PICLR to -1 to allow interrupts again. To restart the program +where it was interrupted, .DISMIS TSINT+1 should be used. The program +may desire to restore the saved PC flags but a different PC; in that +case, it should probably clear the byte-interrupt flag (%PCFPD) before +restoring the flags. + +C. An Example of an Old Style Interrupt Handler + +TSINT: +LOC 42 + TSINT ;this is the interrupt pointer. -> int handler. +LOC TSINT + 0 ;first word of handler gets the bits for the interrupts + 0 ;second gets the PC + EXCH A,TSINT + JUMPL A,TSINT2 ;sign of int word set => second word interrupts; + TLNE A,%PJRLT ;otherwise, they are first word interrupts. + PUSHJ P,TIMINT ;if we got an alarm clock int, handle that. + TRNE A,%PIMPV + PUSHJ P,MPVINT ;if we got an MPV, handle that. + TRNE A,%PIIOC + PUSHJ P,IOCINT ;if we got an IOCERR, handle that. +TSINTX: EXCH A,TSINT + .DISMIS TSINT+1 ;then restore the saved PC and zero .PICLR. + +TSINT2: TRNE A,1_TYIC + PUSHJ P,INPUTI ;handle characters typed on the tty (assuming + ;that tty input is open on channel TYIC) + TDNE A,INFBIT + PUSHJ P,INFINT ;handle interrupts from one of our inferiors, + ;assuming the inferior's .INTB variable was + ;read into INFBIT. + JRST TSINTX + +;if the program can't recover from MPV's well, it might do this: +MPVINT: + .DISMIS [RESTART] ;re-initialize the program. + +;if it wanted to create the referenced page, it might do this: +MPVINT: PUSH P,B + .SUSET [.RMPVA,,B] + LSH B,-10. ;get the referenced page's number. + .CALL [ SETZ ? 'CORBLK + MOVEI 400000 ? MOVEI -1 ? B ? SETZI 400001] + .VALUE ; ^ get a fresh page into page w/ number in B. + POP P,B + POPJ P, + +D. How Jobs Are Informed about Their Interrupts (New Style) + +When using the newer interrupt mechanism, the program must divide +the interrupts that it handles into some number of groups (there +may be as few as one interrupt in a group, or all the interrupts +may be in one group). The interrupts in a group are all handled +the same way; they have the same relative priority to all other +interrupts, and have the same handler address. For each group, +the user must specify to the system which interrupts are in it, +which interrupts are considered to have a lower priority than +those in the group, and where the handler for the group is located. +This is done with the "interrupt table", which should be 5n+1 words +long where n is the number of groups. The interrupt table should +be identified to the system by means of an AOBJN pointer in 42. + +The first word of the interrupt table should hold the address +of the interrupt stack (which may be an accumulator - P will work!). +The LH of this word specifies extra information to be pushed on +the interrupt stack at each interrupt, beyond the necessary minimum: + bits 3.5-3.1 # of ACs to push. 0 => don't push any ACs. + bits 3.7-4.1 # of first AC to push. + bit 4.9 1 => push the .JPC and .SUUOH variables, and the LSPCL + (an internal ITS variable), after the ACs if any. + +Then come five words for each interrupt group. Their meanings are: + wd 1 The 1st word interrupts that are in this group. + If a bit is set in this word, the corresponding interrupt is + in this group. + wd 2 The 2nd word interrupts which are in this group. + wd 3 The 1st word interrupts that are of priority less than or equal to + this group's. Give the bits for the appropriate interrupts. + When interrupts in this group happen, these bits will be + set in .DF1 to prevent the lower-priority interrupts from + happening. Note that it is not obligatory to include the + interrupts of the group itself in this word; if they are not + included, they will be able to interrupt recursively. That is + sometimes desirable for recoverable synchronous conditions. + wd 4 The 2nd word interrupts that are ofthe same or lower priority. + wd 5 The address of the handler for this group. + +Note that the priority-relation between interrupts, specified by the +second and third words of the groups in the interrupt table, need not +be even a partial order: it is permissible for interrupt A to defer +only B, B to defer only C, and C to defer only A, although not very +useful. Often, a synchronous interrupt is left incomparable with all +other interrupts - it defers only itself, or nothing. + +Synchronous interrupts should come before asynchronous ones +in the table. The only time an exception to that is safe is when +the asynchronous interrupt defers the synchronous one. The reason for +this rule is that when a synchronous interrupt and an asynchronous one +are signalled at the same time, if the asynchronous interrupt comes +earlier in the table it will happen first; if the synchronous one is +not then deferred, it will interrupt saving a PC pointing at the first +word of the asynchronous interrupt's handler - which is not the address +of the instruction that actually caused the synchronous interrupt. If +the synchronous interrupt's handler looks at the PC, as many do, it will +be confused. + +This is an example of an interrupt table (taken from DDT). + +TSINT: LOC 42 + -TSINTL,,TSINT +LOC TSINT + + P ;interrupt pdl pointer address. + %PIWRO ? 0 ? 0 ? 0 ? PURBR1 + ;pure-page violations don't inhibit anything. + ;DDT wants to type out ":UNPURE", and doesn't + ;like to type out with any interrupts inhibited. + %PITTY ? 0 ? %PITTY ? 0 ? TTYINT + ;Don't-have-tty interrupts defer themselves + ;so that they become fatal while one is being + ;processed. If DDT decides that the one + ;that happened should have been fatal, it + ;signals another by depositing in .IPIRQC, and + ;that one IS fatal since it is deferred. + %PIIOC\%PIILO\%PIMPV\%PIOOB ? 0 ? #%PITTY ? -1 ? TSIN0 + ;Error interrupts inhibit asynchronous ints for + ;safety's sake, and themselves so an error in + ;the handler will be fatal. + #%PIIOC#%PIILO#%PIMPV#%PIOOB#%PIWRO#%PICLI#%PITTY ? #<1_TYOC>#1_TYOBC + #%PIIOC#%PIILO#%PIMPV#%PIOOB#%PIWRO#%PICLI#%PITTY ? -1 ? TSIN0 + ;Miscellaneous interrupts have the same handler + ;as the errors - for historical reasons - but + ;don't defer the errors, so that DDT can recover + ;if an error happens in a miscellaneous int. + 0 ? 1_TYOC+1_TYOBC ? 0 ? 0 ? MORINT + ;Bottom-of-screen-on-terminal interrupts defer nothing, + ;so they can exit by simply jumping if they wish. + %PICLI ? 0 ? %PICLI ? 0 ? CLIBRK + ;Core-link interrupts (someone is :SEND'ing to me). +TSINTL==.-TSINT + +The algorithm for giving a set of interrupts is: +Look through the interrupt block one group at a time. +If a group is found that applies to any of the interupts that +are to be given, all the interrupts that it applies to and that are +to be given are pushed, together, onto the interrupt stack +at once. The words pushed are: + First, two words containing the interrupts being pushed. + The first word interrupt bits are pushed first. + Next, two words containing the old settings of .DF1 and .DF2. + The old .DF1 is pushed first. + Next, a word containing the PC before the interrupt. + Last, any AC's or debugging variables specified by the LH of + the first word of the interrupt table. These are pushed in the + order: AC's first, then .JPC, then .SUUOH, and finally LSPCL. +If pdl overflow is enabled, it will be detected properly when the +interrupt data is pushed. +After the necessary information has been saved and the interrupt pdl +updated, the defer words and the PC will be set as specified +in the the interrupt table. +At this point, if there still remain any pending enabled undeferred +interrupts, the whole process is repeated, scanning through all the +groups from the beginning. Note that giving one interrupt may cause +other previously undeferred interrupts to be deferred. It may also +set the pdl overflow interrupt, in which case that interrupt will +be given immediately if not deferred. + +If there are pending enabled undeferred interrupts not included +in any group, and they do not become deferred by the giving of other +interrupts, then they are considered immediately fatal. Thus, the +user can make a nonfatal interrupt be fatal by enabling it but not +including it in any group. + +The interrupt routine may conveniently +exit with the DISMIS Symbolic System Call. +The first arg, if not immediate, should point at the interrupt stack: + .CALL [SETZ ? 'DISMIS ? SETZ P] +The defer words and PC will be restored from the top 3 +words on the stack and 5 words will be popped. Stack overflow +will be detected. You may specify that extra things should be popped +using the control bit argument; bit 2.9 specifies that three words +should be discarded, while *100+ specifies that ACs through ++-1 should be popped. Thus, it is a win to give, as the control +bit argument (in the RH) whatever was put in the LH of the first word +of the interrupt table - that will cause the DISMIS to pop exactly +what interrupts push. + +If the first arg is immediate, clearly nothing can be popped: + .CALL [SETZ ? 'DISMIS ? SETZI 2+[DF1 ? DF2 ? PC] ] +In this case the control-bit argument is ignored. +If a second argument is given, it is used as the new PC +instead of what is found on the interrupt stack. +Similarly, optional third and fourth arguments specify the new +contents of the defer words, overriding what was saved on the stack. +Thus, if four arguments are given and the first is immediate, +the first argument is effectively ignored. + +E. The Interrupt Bits in the First Interrupt Word. + +The interrupt classes are: + [1] stops job and interrupts superior (fatal intr) + [2] stops job and interrupts superior unless enabled and undeferred + [3] does nothing unless enabled; waits if deferred. +Bits in the lh have two names: %PI... as a bit in the word, + and %PJ... shifted down by 18. bits. + +The following interrupts abort the instruction, and leave the PC pointing +before the instruction if %OPOPC is 1 (as is winning), or after it if +%OPOPC is 0: %PIMPV, %PIOOB, %PIIOC, %PIILO, %PJTTY, %PJWRO, %PJFET, %PJTRP. + +"(S)" indicates a synchronous interrupt; "(A)", an asynchronous one. +An interrupt is synchronous if its occurrence is always directly related +to the instruction that is being executed when it is signaled. + +;RH bits +%PICLI==400000 ;CLI interrupt [3] (A) + ;Some job opened the CLI device with filenames equal + ;to the uname and jname of this job. +%PIPDL==200000 ;PDL overflow [3] (S) +%PILTP==100000 ;340 or E&S light pen hit [3] (A) +%PIMAR==40000 ;MAR hit. [2] (S) + ;The MAR is a hardware feature that allows + ;references to a specific memory location to + ;be trapped. This is the interrupt that happens + ;when such a reference is detected. The guilty + ;instuction is usually not aborted; if it is, the + ;PC is SOS'ed regardless of the setting of %OPOPC. + ;See the .MARA and .MARPC variables. +%PIMPV==20000 ;MPV (memory protect violation) [2] (S) + ;The job referenced a non-existent memory location. + ;The address of that location (roundd down to + ;a page boundary on KA-10's) may be found in .MPVA. + ;The guilty instruction was aborted, and the PC was + ;left set according to %OPOPC. +%PICLK==10000 ;Slow (1/2 sec) clock [3] (A) +%PI1PR==4000 ;Single-instruction proceed [1] (S) + ;If a job is started with the one-proceed flag + ;(%PC1PR on KA-10's) set, after one instruction + ;is completed a %PI1PR interrupt will occur. + ;DDT's ^N command uses this feature. +%PIBRK==2000 ;.BREAK instruction executed. [1] (S) + ;.BREAK is used for DDT breakpoints, and for explicit + ;program requests to DDT. +%PIOOB==1000 ;Address out of bounds [2] (S) + ;This is an obscure condition that used to + ;happen on USR device IOT's, when an attempt + ;was made to refer to a nonexistent location in the + ;other job. Now this always causes an MPV. + ;The guilty instruction was aborted, and the PC was + ;left set according to %OPOPC. +%PIIOC==400 ;IOCERR (I/O channel error) [2] (S) + ;This indicates the failure of an I/O system + ;call. The channel that was being operated on is + ;in .BCHN, and its .IOS word should contain, in + ;bits 4.5 - 4.1, an error code. + ;The guilty instruction was aborted, and the PC was + ;left set according to %OPOPC. +%PIVAL==200 ;.VALUE instruction executed [1] (S) +%PIDWN==100 ;System-going-down status change [3] (A) + ;If the system changes its mind about whether + ;or when it is scheduled to go down, this interrupt + ;is signaled. +%PIILO==40 ;ILOPR, ILUUO (illegal operation) [2] (S) + ;This can be caused by a returnable uuo when the + ;program's 41 doesn't seem suitable for handling one + ;(see ITS UUOS). It can also be used to report + ;the failure of certain more archaic system calls. + ;The guilty instruction was aborted, and the PC was + ;left set according to %OPOPC. +%PIDIS==20 ;Display memory protect [2] (A) + ;The 340 or E&S display got an MPV. + ;This is now obsolete since the 340 and E&S + ;no longer work. +%PIARO==10 ;Arithmetic overflow [3] (S) + ;The PDP-10's built-in arithmetic overflow + ;condition was detected by the hardware. + ;In fact, overflow occurs so often + ;that enabling this interrupt causes the + ;machine to slow down considerably, + ;and it should be avoided. +%PIB42==4 ;BADPI (Bad location 42) [1] (S) + ;If in attempting to interrupt a job it turns out + ;to be necessary to refer to nonexistent memory + ;or write in read-only memory, this interrupt + ;is signaled, instead of MPV or WIRO. + ;This is so that the program will return to DDT + ;instead of mysteriously looping. +%PIC.Z==2 ;^Z or CALL typed on terminal [1] (A) +%PITYI==1 ;TTY input (obsolete) [3] (A) + +;LH bits +%PJRLT==200000 ;Real-time timer went off [3] (A) + ;These interrupts are controlled by the .REALT + ;uuo. See ITS UUOS. +%PJRUN==100000 ;Run-time timer went off [3] (A) + ;This interrupt is requested (in advance) + ;by setting .RTMR. +%PJNXI==40000 ;Non-existent IO register [2] (S) + ;A Job in User IOT mode referenced a non-existent IO + ;register on the KS10 Unibus. The PC is left pointing + ;before the guilty instruction. The address of the + ;non-existant register may be found in .MPVA. +%PJJST==20000 ;Job Status display request. [3] (A) + ;The sequence ^_J was typed on the + ;console owned by this process or some inferior. +%PJDCL==10000 ;Deferred call. [1] (S) + ;An attempt was made to read TTY input + ;and the next character was a deferred-call + ;character (^_D or Control-CALL). + ;This deferred-call character is never seen + ;by the program; it just causes the interrupt. + ;It differs from ordinary CALL or ^Z + ;in that it takes effect when the program + ;gets around to reading it, not immediately. +%PJATY==4000 ;TTY returned. [3] (A) + ;This interrupt happens when the TTY is + ;returned by the superior, after having + ;been taken away. TECO uses this to know + ;that it must redisplay the entire screen. +%PJTTY==2000 ;Don't have TTY [2] (S) + ;This results from an attempt to use the job's + ;console tty when the job does not own it, if + ;%TBINT is 1 and %TBWAT is 0. See ITS TTY. + ;The guilty instruction is aborted, and the PC is + ;left set according to %OPOPC. +%PJPAR==1000 ;Memory parity error [2] (A) + ;Programs are not intended to try to recover + ;from parity errors, on the assumption that they + ;are probably permanently screwed up. + ;This interrupt is asynchronous because it can + ;be caused by a parity error in another job + ;which destroys data in a page shared with this job. +%PJFOV==400 ;ARFOV (Floating overflow) [3] (S) + ;This is a non-aborting PDP-10 hardware condition. +%PJWRO==200 ;WIRO (Write in read-only page) [2] (S) + ;The guilty instruction was aborted, and the PC was + ;left set according to %OPOPC. The address of read + ;only location (rounded down to a page boundary on + ;KA-10's) may be found in .MPVA. +%PJFET==100 ;Fetched insn from impure page [2] (S) + ;On KA-10's, if bit %PCPUR of the PC flags is 1, + ;fetching an instruction from an impure page + ;will cause this interrupt. This is supposed to + ;facilitate catching jumps to randomness. + ;The guilty instruction is aborted, and the PC is + ;left set according to %OPOPC. +%PJTRP==40 ;SYSUUO (System uuo in trap mode) [2] (S) + ;A job whose .UTRAP variable was nonzero either + ;attempted to execute an instruction that trapped + ;to the system, or was about to be interrupted. + ;This feature is intended to be used by the superior + ;to provide a non-ITS environment for the inferior. + ;For that purpose, this interrupt should not be + ;enabled for the inferior, so that it will be fatal. + ;The guilty instruction was aborted, and the PC was + ;left set according to %OPOPC. +%PJDBG==2 ;System being debugged state change [3] (A) + ;When the system enters or leaves "debugging mode", + ;this interrupt is signaled. +%PJLOS==1 ;A .LOSE UUO or a LOSE system call [2] (S) + ;was executed. + +F. The Interrupt Bits in the Second Word + +The right half of the second word (.IFPIR) is used for I/O channel +interrupts that signal the arrival of or need for data. +They should not be confused with I/O channel error interrupts +or IOCERRors. Each channel has its own bit: 1.1 is for channel +0; 1.2, for channel 1; ... 2.7, for channel 17 . +They are all class 3, and their significance depends on the device +open on the channel. + +The left half of the second word (.IFPIR) is used for +"inferior got a fatal interrupt" interrupts. Each of a job's +inferiors is assigned its own interrupt bit from among the +bottom 8 bits of the left half. When an inferior job is created, +its interrupt bit should be read and remembered by reading the +.INTB variable with a .USET. Every time that inferior gets a fatal +interrupt, it will be stopped and the superior will receive an +interrupt on that inferior's bit in .IFPIR. The inferior may +be restarted by zeroing its .USTP variable, but if the fatal +interrupts remain and are still fatal the inferior will simply +stop and interrupt the superior again. "Inferior got a fatal +interrupt" interrupts are all class 3. + +The reason that inferiors interrupt through a special set of bits +instead of using I/O channel interrupts is that it makes it possible +to receive interrupts from all one's inferiors without having them +all open on I/O channels at all times. DDT normally keeps only +its current job open, and when it receives an interrupt from some +other job it opens that job temporarily. diff --git a/doc/sysdoc/itstty.41 b/doc/sysdoc/itstty.41 new file mode 100755 index 00000000..ee5254f2 --- /dev/null +++ b/doc/sysdoc/itstty.41 @@ -0,0 +1,3571 @@ +-*-TEXT-*- + +File: ITSTTY Node: Top Next: A Up: (DIR) + +This file describes just about all there is to know about using and +programming TTYs (abbreviation for "Teletypes", for which read "consoles") +on the ITS operating system. + +* Menu: + +* Special: A Characters specially interpreted when typed on the tty. +* Control: B "Control of the tty". +* Opening: C Opening tty channels. +* Input: D Input from terminals. +* Output: E Output to terminals. +* More: F **MORE** processing. +* Vars: G Per-tty/per-job variables. +* Perm: H Permanent and semipermanent tty information. +* STYs: I Pseudo-teletypes (STYs). +* Smart: J The intelligent terminal protocol. +* SofTTYs: K Software ttys and ITS output buffer codes. + + +This is the complete table of contents for this file: + +A. CHARACTERS SPECIALLY INTERPRETED WHEN TYPED ON THE TTY. + 1. INTERRUPTING THE PROGRAM - THE CALL FUNCTION. + a. Deferred CALL. + 2. ENTERING STRANGE CHARACTERS - THE ESCAPE FUNCTION. + a. Quoting the Characters Used for CALL and ESCAPE. + b. "^_". + c. Supplying Meta-Bits on Non-TV's. + 3. MODE SETTING USING ESCAPE. + a. "^_M" - Complement **MORE** Processing (%TSMOR). + b. "^_^" - Complement Scroll-mode (%TSROL). + c. "^_""" - Complement Use of SAIL Character Set (%TSSAI). + d. "^_U" - Complement conversion to upper case (%TOCLC) + 4. COMMUNICATE MODE. + a. Entering a Com Link. + b. Querying. + c. Leaving a Com Link. + d. When the System Prints "^_N". + e. Input and Output Overrides. + f. Slaving Another Terminal. + g. Telling the System How to Respond to "^_C" Requests. + 5. LIST OF ESCAPE CODES. + +B. "CONTROL OF THE TTY". + 1. WHAT DETERMINES WHO HAS THE TTY. + 2. .ATTY AND .DTTY. + 3. PERMISSION TO TYPE OUT. + 4. THE .TTY VARIABLE. + 5. THE .CNSL VARIABLE. + +C. OPENING TTY CHANNELS. + 1. OPENING "TTY". + 2. OPENING "Tnm". + 3. DEVICE-DEPENDENT BITS IN THE OPEN MODE. + a. Per-channel Bits. + b. Other Per-channel Bits on Input. + c. Other Per-channel Bits on Output. + d. First-time Bits on Output. + e. First-time Bits on Input. + +D. INPUT FROM TERMINALS. + 1. ECHO. + 2. MAIN-PROGRAM INPUT. + 3. ACTIVATION. + 4. INPUT INTERRUPTS. + 5. THROWING AWAY TYPE-IN. + 6. TESTING FOR THE AVAILABILITY OF INPUT. + 7. .STATUS ON TTY INPUT CHANNELS. + 8. THE CHARACTER SET + +E. OUTPUT TO TERMINALS. + 1. HOW TO CAUSE CHARACTERS TO BE OUTPUT. + 2. NORMAL OUTPUT (SEQUENTIAL ACCESS). + a. How the System Goes about Outputting. + 1: ASCII Graphic Characters. + 2: "^G". + 3: Carriage-return. + 4: Linefeed. + 5: Tab. + 6: Control-L (Formfeed). + 7: Altmode. + 8: Control-P. + 9: Backspace. + 10: Random Control Characters, and Rubout. + b. Continuation - the Result of Line-overflow. + c. Wraparound and Scrolling - the Results of Page-overflow. + 1: Scrolling. + 2: Wraparound. + 3. DISPLAY-MODE CHANNELS. ^P-CODES. + 4. THE ECHO AREA. + a. How the Echo Area Works. + b. Creating an Echo Area. + 5. READING THE CURSOR POSITION. + 6. SUPERIMAGE OUTPUT. + 7. RELEVANT TTYOPT BITS. + 8. THROWING AWAY TYPEOUT. + 9. WAITING FOR OUTPUT TO BE SENT TO THE TERMINAL. + 10. .STATUS ON TTY OUTPUT CHANNELS. + +F. **MORE** PROCESSING. + 1. WHEN **MORE** PROCESSING IS TRIGGERED. + 2. HOW **MORE** PROCESSING OPERATES. + a. Stupid Programs. + b. Smart Programs. + 3. PROGRAMMED INVOCATION OF **MORE** PROCESSING. + 4. INHIBITION OF **MORE** PROCESSING BY INPUT. + +G. PER-TTY/PER-JOB VARIABLES. + 1. THE VARIABLES. + a. the TTYST1 and TTYST2 variables. + b. The TTYSTS variable. + c. The Size of the Echo Area. + 2. SYMBOLIC SYSTEM CALLS. + a. TTYGET - read TTYST1, TTYST2, TTYSTS. + b. TTYSET - set TTYST1, TTYST2, TTYSTS. + c. SCML - Set Number of Command Lines. + +H. PERMANENT AND SEMIPERMANENT TTY INFORMATION. + 1. THE VARIABLES. + a. The Screen Size. + b. The TTYOPT variable. + c. The TCTYP variable. + d. The TTYTYP variable. + e. The TTYCOM variable. + f. The TTYROL variable or "Scroll Count". + g. The TTYSMT variable. + 2. SYSTEM CALLS. + a. RSSIZE. + b. CNSGET. + c. CNSSET. + d. TTYVAR. + +I. PSEUDO-TELETYPES (STY'S). + 1. OPENING STY'S. + 2. OUTPUT TO STY'S. + a. What happens when the buffer is empty. + b. Interrupts. + c. RESET on sty output channels. + d. STATUS on sty output channels. + 3. INPUT FROM STY'S. + a. What happens when the buffer is empty. + b. Interrupts. + c. .STATUS on sty input channels. + d. .RESET on sty input channels. + 4. CLOSING STY'S. + 5. CONTROLLING THE TTY ASSOCIATED WITH A STY. + 6. DIRECT CONNECTIONS TO NETWORK CHANNELS: STYNET. + 7. STYGET. + +J. THE INTELLIGENT TERMINAL PROTOCOL. + 1. ESCAPE SEQUENCES. + 2. ALLOCATION. + 3. OUTPUT-RESET. + +K. SOFTWARE TTYS AND ITS OUTPUT BUFFER CODES. + 1. ITS OUTPUT BUFFER CODES. + 2. HANDLING %TDORS. + 3. THE SCPOS SYSTEM CALL. + +File: ITSTTY, Node: A, Previous: Top, Up: Top, Next: B + +A. CHARACTERS SPECIALLY INTERPRETED WHEN TYPED ON THE TTY. + +Normally, characters type on terminal keyboards have effect only +by being read and acted on by user programs. There are, however, +a few important exceptions. + +* Menu: + +* Interrupting: A/1 Interrupting the program - the CALL function +* Strange: A/2 Entering strange characters - the ESCAPE function +* Mode Setting: A/3 Mode setting using ESACPE +* Communicate: A/4 Communicate mode +* Escape Codes: A/5 List of ESCAPE codes + +File: ITSTTY, Node: A/1, Previous: A, Up: A, Next: A/2 + + 1. INTERRUPTING THE PROGRAM - THE CALL FUNCTION. + +A function available on all terminals that are in use as +consoles is to stop the current program and interrupt its +superior. On TV's, this function is requested by hitting the +"CALL" key; on other terminals, which have no "CALL" key, the +character "^Z" is used. This makes the character "^Z" difficult +to type in as a normal characters on such terminals, requiring +quoting (*Note Quoting: A/2.). + +In detail, the CALL function gives the job which owns the tty +(*Note TTY-owning: B.) a fatal interrupt, causing its superior in the +tree to be interrupted. The superior will usually react by retrieving +the terminal from the job that had posessed it. Thus, CALL makes it +possible to regain control when the program that has the terminal is +out of control. + +When the terminal is in super-image input mode (%TSSII is 1), +the CALL function is disabled - attempts to use it merely +generate input to the program. Programs should not lightly enter +this mode. + + a. Deferred CALL + +If you want to return from a program to DDT after the program is +finished, if you use ordinary CALL you must not type it until then. +And since DDT will flush all input when it sees the CALL, you can't +type anything else until you have seen DDT respond. + +The "deferred CALL", which you can type as Control-CALL on a TV or as +^_D on any terminal, does about the same thing that ordinary CALL does +except that it does not take effect until the program tries to read +it. It thus acts like an "exit" command in all programs. DDT +distinguishes deferred CALLs from ordinary ones (deferred ones give the +program a %PIDCL interrupt instead of a %PIC.Z), and does not throw +away input. Thus, you can type the deferred CALL ahead, and also some +DDT commands to follow it. + +File: ITSTTY, Node: A/2, Previous: A/1, Up: A, Next: A/3 + + 2. ENTERING STRANGE CHARACTERS - THE ESCAPE FUNCTION. + +The ESCAPE function is requested by typing "BACK-NEXT" on TV's. +This character is available as "^_" (control-underscore) on most +terminals which have no "BACK-NEXT" key; on Lisp Machine keyboards it +is labeled SCROLL or MACRO. + +The character used for the ESCAPE function is hard to type in, just as +the character used for the CALL function is. However, it provides a +mechanism that solves those problems. Note that the ITS ESCAPE +terminal function should not be confused with the "ESCAPE" key on TV +keyboards, which escapes all the way to the PDP-11 which handles the TV's. + +In the following, "^_" will designate the ESCAPE function, unless +otherwise stated, regardless of whether it is actually obtained by +the character "^_". + +* Menu: + +* Quoting: A/2/a Quoting the chars used for CALL and ESCAPE +* ^_: A/2/b +* Meta-bits: A/2/c Supplying Meta-Bits on Non-TV's + +File: ITSTTY, Node: A/2/a, Previous: A/2, Up: A/2, Next: A/2/b + + a. Quoting the Characters Used for CALL and ESCAPE. + +One of the uses of the ESCAPE function is to enter characters +that are not on the keyboard or otherwise hard to type in. The +characters used for the CALL and ESCAPE functions may be entered +as normal input by preceding them with an ESCAPE, which "quotes" +them. For example, on a non-TV, typing "^_^_" causes a single +"^_" to be read by the program, to interrupt if the program has +enabled interrupts, etc., and "^_^Z" does the same thing for +"^Z". + +File: ITSTTY, Node: A/2/b, Previous: A/2/a, Up: A/2, Next: A/2/c + + b. "^_". + +If the terminal's keyboard is missing a character, that +character may be entered by typing ESCAPE followed by the octal +numerical code for the character. The number may have any number +of digits, and is terminated by the first non-digit. If that +non-digit is a space, it is discarded; otherwise, it is taken +normally as input. The character entered as digits will be echoed +(if echoing of that character is turned on). Thus, "^_001 " +inputs a "^A" and echoes as "^_001^A", and "^_1q" enters "^Aq" +and echoes as "^_1^Aq". + +File: ITSTTY, Node: A/2/c, Previous: A/2/b, Up: A/2, Next: A/3 + + c. Supplying Meta-Bits on Non-TV's. + +It is possible to enter characters in the TV character set that are not in +ASCII, using the ESCAPE function followed by ^B, ^C, ^D, or ^F, followed by +the basic ASCII character. ^B means "set the CONTROL bit"; ^C, the META +bit; ^F, the SUPER bit; ^D, the TOP bit. Any combination of those four +characters should be followed by the basic ASCII character with which those +bits will be OR'ed. To specify one of those four control characters, or +^Q, as the basic ASCII character, quote it with ^Q. For example, "^_^B^C1" +specifies CONTROL-META-1. "^_^BA" is CONTROL-A, which has the code 301, +and is not the same as ^A (code 001). The TOP bit is useful for programs +(such as TECO) which distinuish SAIL graphics characters from CONTROL +characters. TECO treats an ASCII ^K as an alias for CONTROL-K, but ^_^D^K +(TOP-^K) is believed to be the SAIL character Uparrow. + +The reason that ^B and ^C stand for CONTROL and META is that +they correspond to the SAIL characters Alpha and Beta, which +are traditionally used for this purpose. + + +File: ITSTTY, Node: A/3, Previous: A/2, Up: A, Next: A/4 + + 3. MODE SETTING USING ESCAPE. + +Most of the switches that are associated with each terminal are +intended to be set or cleared by means of the TCTYP program. +However, there are two switches for which each job that can use the +terminal has its own setting. The TCTYP program may be used to set the +default values of the switches, which are used to initialize new jobs. +ESCAPE codes are provided for complementing the switch associated with +the job that the terminal belongs to at the moment. + + a. "^_M" - Complement **MORE** Processing (%TSMOR). + +When **MORE** processing is enabled, the system causes output to +pause at the bottom of the screen, until a space is typed. + + b. "^_^" - Complement Scroll-mode (%TSROL). + +When a terminal is in scroll mode, linefeeding past the bottom +of the screen causes everything on the screen to move up, +instead of wrapping around to write at the top of the screen. + + c. "^_""" - Complement Use of SAIL Character Set (%TSSAI). + +When %TSSAI is set, ascii mode and echo mode output of +non-formatting control characters will send the character +unmodified, assuming it to be a graphic character. Thus, "^B" +will echo as an alpha, etc., on terminals that can handle the +SAIL character set. + + d. "^_U" - Complement conversion to upper case (%TOCLC) + +When %TOCLC is set, characters typed at the terminal are converted +to uppercase. + +File: ITSTTY, Node: A/4, Previous: A/3, Up: A, Next: A/5 + + 4. COMMUNICATE MODE. + +It is possible for a group of terminals to be put in a "com +link". When that is done, anything typed on any one of the +terminals echoes on all of them. Normally, what is typed on a +terminal that is in a com link is ignored except for that +echoing, however the user may cause it to be treated as normal +input (see "^_I"). Also, programs are usually prohibited from +typing out while the tty is in a com link, but that may be +changed by the user (see "^_O"). It is also possible to cause +one of the terminals in a com link to supply input for and view +the output from another (see "^_S" and "^_E"). + +* Menu: + +* Entering: A/4/a Entering a COM link +* Querying: A/4/b +* Leaving: A/4/c Leaving a COM link +* ^_N: A/4/d When the system prints "^_N" +* Overrides: A/4/e Input and output overrides. "^_I" and "^_O". +* Slaving: A/4/f Slaving another terminal. "^_S" and "^_E". +* Respond: A/4/g Telling the system how to respond to "^_C" requests + +File: ITSTTY, Node: A/4/a, Previous: A/4, Up: A/4, Next: A/4/b + + a. Entering a Com Link. + +From any terminal, a com link with any other terminal may be +requested by means of "^_C", which should be followed by the +number of the terminal to be linked to, or by the uname of the +user logged in on that terminal. The name or number is terminated +by the first space or CR, except that any number of spaces or +CR's may follow right after the "C" and will be ignored. + +It is allowed for either the terminal on which "^_C" is typed or +the terminal to which a link is requested to be in a com link +already; in either case, if the request succeeds both of the +terminals and all the other terminals that had been linked to +either of them will form one com link. If there is no terminal +with the specified number, or no one is logged in with the +specified uname, the "^_C" will have no effect, and a "?" will +be typed. The same thing will happen if the specified terminal +is already in a com link with the requesting terminal. If the +specified terminal is in the middle of typing in an ESCAPE code, +or has characters unprocessed in its input buffer, the "^_C" +fails, typing "Busy". When that happens, it is reasonable to +try again in a few seconds. If the specified terminal's user +has ordered it ro refuse com links, with "^_R" +(it is in "refuse mode"), then "Refused" will be typed, and the +request will fail. If these conditions for "^_C" are met, the +request is basically acceptible, and what happens to it depends +on whether the specified terminal is in "accept mode" (the usual +case) or in "query mode". In accept mode, the two terminals will +be linked right away. If the target terminal is already in a com +link, a list of the terminals in that com link will be typed out +and the user will be asked whether he wants to "break in". An +answer other than "Y" or "y" will abort the request. In query +mode, the specified terminal must be asked whether the link +should be made - that process will be described later. + +Assuming that the specified terminal is in accept mode, and that +if necessary the user has decided to break in, then, the link +will be created, and the requesting terminal will be informed +that the request has succeeded by a "OK". "F" will be typed in +addition if the specified terminal is free. The "OK" tells the +requesting user that he is linked to the specified terminal, but +he may also be linked without knowing to other terminals already +linked to the specified terminal. Also, the other terminals in +the link at this point know nothing. Therefore, messages are +typed on the terminals as follows: on the specified terminal and +all terminals linked to it, the message "LINK FROM " will be typed, where the includes +the requesting terminal and all terminals linked to it, and a +terminal is referred to by its uname if it is a logged in +console, and as "Tnn" otherwise. Also, if there are other +terminals already linked to the requesting terminal, the message +"LINK TO " will be typed, naming the specified terminal +and any other terminals linked to it. Also, if the specified +terminal is already linked to others, the message +"LINK TO " naming only those others, and not the specified +terminal, will appear on the requesting terminal. The result of +all of those messages is that each terminal that ends up in the +new com link is informed of all the other terminals that it is +becoming linked to. + +File: ITSTTY, Node: A/4/b, Previous: A/4/a, Up: A/4, Next: A/4/c + + b. Querying. + +When the specified terminal is in query mode (*Note ^_Q: A/4/g.), +"QUERYING" is typed on the requesting terminal, and the "LINK FROM ..." +message is typed on the specified terminal only (NOT on the +terminals linked to it already), followed by "QUERYING", which +informs its user that he is being queried. He need not +pay immediate attention to the query, and his commands will +continue to go to his program. When he wishes to respond, +he may do "^_Y" to accept the link, "^_Z" to to refuse it, +"^_Q" to list the people querying, or "^_C" to a specific +user querying him. Such a "^_C" will always succeed +immediately, even if the target is in refuse mode or query mode, +as long as he is querying the "^_C"'er. This is how to +accept some but not all of several simultaneous queries. +When a query is accepted or rejected, "OK" or "REFUSED" will be +typed on the requesting terminal. Until that happens, +the requesting terminal may not do anything but "^_N" to give up +waiting, aborting the request, or ^G, which echoes on the terminal +being queried, to attract its user's attention. If "^_N" is +used to abort the request, the queried terminal is not informed. +If the request is accepted, "OK", the "LINK TO ..." messages and +the remaining "LINK FROM ..." messages are typed as they would +have been for accept mode. + +File: ITSTTY, Node: A/4/c, Previous: A/4/b, Up: A/4, Next: A/4/d + + c. Leaving a Com Link. + +Any terminal may be removed from a com link by typing "^_N" on it. +Also, any terminal in a com link may remove any of the other +terminals from that link by typing "^_K" followed by the uname or +number of the terminal to be unlinked (using the same syntax as +"^_C"). If there is only one terminal left in the com link, the link +is destroyed, and that terminal also returns to normal. Otherwise +the terminals remaining in the link continue to be linked, and +"BYE FROM " is typed on each of them. + +File: ITSTTY, Node: A/4/d, Previous: A/4/c, Up: A/4, Next: A/4/e + + d. When the System Prints "^_N". + +Whenever a terminal enters a com link, or makes a "^_C" request, +it is said to enter "com mode". That causes input not to be passed +to the program, and prevents programs from typing out (but see "^_I" +and "^_O"). This state persists until the terminal is no longer in +com mode. Therefore, the system informs the user that the terminal +has left com mode by typing "^_N" on the terminal, unless the +terminal has left com mode because the user has just typed "^_N" +on it (the idea is that if a "^_N" has just echoed there is no need +to supply another). + +File: ITSTTY, Node: A/4/e, Previous: A/4/d, Up: A/4, Next: A/4/f + + e. Input and Output Overrides. + +Normally, on a terminal in com mode input is not passed to the +program and programs may not type out (.IOT's hang). That can be +explicitly changed with "^_I" and "^_O". "^_O" complements the +%TCOCO switch which, if on, allows programs to output to the terminal +even when it is in com mode. %TCOCO is initialized to 0 whenever +a terminal is initialized (when it starts to be used after being +free for a while). DDT turns %TCOCO on temporarily when printing +unsolicited messages such as "ITS GOING DOWN". %TCOCO can be set +with :TCTYP OCO and cleared with :TCTYP NO OCO. +"^_I" complements the %TCICO switch which, if on, causes input to +be passed to the program even when in com mode, and also allows +programs to type out (just like %TCOCO). %TCICO is initialized +to 0 at the same time as %TCOCO, and may also be set with :TCTYP. +Note that when the switch is off all characters echo regardless of +what the program has requested, but when the switch is on, characters +echo or not just as they would when not in com mode, according to +the program's setting of the TTYST1 and TTYST2 variables. + +File: ITSTTY, Node: A/4/f, Previous: A/4/e, Up: A/4, Next: A/4/g + + f. Slaving Another Terminal. + +In any com link at any time one terminal may be slaved. That means +that those other terminals that wish to may supply input to the +program using the slaved terminal, and see the output typed on it. +(Actually, it isn't too hard to cause there to be two slaved +terminals in a link). Any terminal that is slaved will always see +program output, regardless of the setting of the "^_O" switch. +The "^_I" switch functions normally on slaved terminals. +Any terminal may explicitly slave any other terminal +linked to it, by means of "^_S", which has the same syntax as "^_C". +This automatically unslaves all terminals in the link other than +the one requested to be slaved. +Each terminal has a switch that determines whether input typed on +it should be sent to the slaved terminal in the link, if there is +one. This switch is complemented by "^_E", and initialized off when +com mode is entered. If there are exactly two terminals in the link, +typing "^_E" on one automatically does a "^_S" to the other. +Otherwise, both the "^_E" and the "^_S" must be done to get any +effect. If a terminal's "^_I" switch and its "^_E" switch are both +set, input from it will be fed to both its own programs and those of +the slaved terminal. That is, the two switches are independent. +Similarly, the "^_O" switch does not interact with the "^_E" switch. + +File: ITSTTY, Node: A/4/g, Previous: A/4/f, Up: A/4, Next: A/5 + + g. Telling the System How to Respond to "^_C" Requests. + +Any terminal may be in any one of three modes: accept mode, refuse +mode, and query mode. Accept mode is the default, and causes "^_C" +requests to succeed; refuse mode causes them to fail; query mode +causes them to query as described in section b. Accept mode may be +entered by typing "^_A"; refuse mode, by "^_R"; query mode, by "^_Q". +In addition, "^_A" accepts all pending queries, and "^_R" refuses them. +The program TCTYP also has the capability of changing the mode, using +the CNSSET system call. The information is stored in the bits %TCRFS +and %TCQRY in the TTYCOM variable (*Note Combits: H/1/e.). + +File: ITSTTY, Node: A/5, Previous: A/4, Up: A + + 5. LIST OF ESCAPE CODES. + +In most cases, the escape code name is also the name of a footnote +leading to a node containing more details on the specific code. + +^_^Z Program receives "^Z". No quitting action, etc. +^_^_ " " "^_". No special action +^_" Complement %TSSAI for the job which has the tty. + That flag, if 1, says that the SAIL character set should be + used for echo mode and ascii mode output. *Note ": E/2/a. +^_ + Enter the character whose ASCII code is . + *Note nnn: A/2/b. +^_A Set "accept mode". *Note A: A/4/g. +^_B Cause typeout to pause. *Note B: F/1. +^_C Communicate with another terminal. *Note C: A/4/a. +^_D Deferred Call. *Note D: A/1/a. +^_E Start or stop sending input to a slaved terminal. + *Note E: A/4/f. +^_I Complement the input override flag (%TCICO). *Note I: A/4/e. +^_J Give a %PIJST interrupt to the job that has the tty, or the closest + superior that has the interrupt enabled. +^_K Take some other terminal out of com link. *Note K: A/4/c. +^_L Clears the screen (echoes "^PC"). +^_M Complement **MORE** processing for job that has the tty. + *Note M: F/2. +^_N Leave com link or quit waiting for answer to query. + *Note N: A/4/c. +^_O Complement the output override flag (%TCOCO). *Note O: A/4/e. +^_Q Set "query mode" (%TCQRY). *Note Q: A/4/g. +^_R Set "refuse mode" (%TCRFS). *Note R: A/4/g. +^_S Slave a specified terminal. *Note S: A/4/f. +^_U Complement conversion of to upper case (%TOCLC). + *Note U: A/3/d. +^_Y Say yes to a query. *Note Y: A/4/b. +^_Z Say no to a query. *Note Z: A/4/b. +^_^ Complement scroll mode for job that has the tty. + *Note ^: A/3/b. +^_^U Clear input for this TTY. This completely flushes what + is in the input buffer and is useful for getting rid of + unwanted typeahead. + + +File: ITSTTY, Node: B, Previous: A, Up: Top, Next: C + +B. "CONTROL OF THE TTY". + +A terminal that is a console may be used by any of the jobs in +its tree, but not all at once. At any time, the terminal belongs +to a particular job, and for the most part only that job can use it. +Also, all input and output interrupts go to that job only. If +any other job in the tree tries to use the tty for anything except +to type out, it will not +succeed (it may wait until it is allowed to use the tty, it may +get an interrupt, or its system call may simply fail, depending +on what the job is doing and on the setting of some bits in .TTY, +described below). Permission to type out is controlled by a +separate mechanism. + +The job that is allowed to use the tty is said to "have control +of the tty", or to "have the tty". The .ATTY and .DTTY UUO's +allow control of the tty to be passed between the jobs in a +tree. + +* Menu: + +* Who Has: B/1 What determines who has the TTY +* ATTY: B/2 .ATTY and .DTTY +* Permission: B/3 Permission to type out +* .TTY: B/4 The .TTY variable +* .CNSL: B/5 The .CNSL variable + +File: ITSTTY, Node: B/1, Previous: B, Up: B, Next: B/2 + + 1. WHAT DETERMINES WHO HAS THE TTY. + +Each job has a variable - called .TTY, readable with a .SUSET or +.USET - that says, among other things, whether it wishes to retain +the tty or to pass it on to a particular one of its inferiors. +Each job can alter that setting at any time. The instantaneous +values of the .TTY variables of all the jobs in a tree determine +which of them has the tty, as follows: If the top level job wishes +to retain the tty, then it owns the tty; otherwise, if the one +inferior which it wishes to pass the tty on to wishes to retain +the tty, then that job owns the tty; otherwise the job that job +wishes to pass the tty on to has its chance, etc. In other words, +at any instant the tty is as far down as it can get before being +blocked from further descent by a job that wishes to retain it. + +File: ITSTTY, Node: B/2, Previous: B/1, Up: B, Next: B/3 + + 2. .ATTY AND .DTTY. + +.DTTY is used when a job decides that it wishes to retain the +tty. It skips if it succeeds; it fails if the job was already in +the state of wishing to retain the tty, +If the tty had actually belonged to some (possibly +indirect) inferior, it will belong after the .DTTY to the job +that executed it. + +The ATTY operation puts the job in the state of wishing to pass +control of the tty to one of its direct inferiors. This is known +as an "ATTY'ing state". If a job which is in an ATTY'ing state +is allowed ownership of the TTY by its superiors (ie, they too are +in ATTY'ing states pointing down to this job), then ownership +passes yet another level to the ATTY'd inferior. +Whenever an ATTY is done, the %TSATY bit will be set to 1 in TTYSTS, +and the inferior receiving the tty will be given a %PIATY +interrupt if it is enabled. + +The ATTY operation can be done with either the .ATTY UUO or the ATTY +symbolic system call. .ATTY , specifies the inferior open on +channel . The ATTY symbolic system call takes one argument, +a job spec, to specify the inferior to ATTY to. + +ATTY'ing is illegal for the job which has the tty, when the %TSLCZ +bit is set (meaning that the last char typed on the tty was "^Z"). +This is a half-hearted attempt to make it possible to "^Z" up +several levels past programs that are trying to prevent that. +Since super-image input mode now exists, such an attempt is futile. +This "feature" can probably be flushed if anyone wishes. + +The "P" command causes DDT to do an .ATTY, among other things. +"^P" does not. DDT does a .DTTY when an "P"'ed job returns to DDT. + +A job need not have the tty to do an .ATTY or .DTTY. In fact, they +are the only operations on ttys that work as well without the tty +as with it. + +File: ITSTTY, Node: B/3, Previous: B/2, Up: B, Next: B/4 + + 3. PERMISSION TO TYPE OUT. + +The job that owns the TTY, and the job at the top of the tree, +can always type out on the TTY. Those jobs can also grant +permission to some of their inferiors, which can in turn grant +it to their inferiors, and so on. Such indirect permission +is controlled by two bits in the .TTY variable of each job. +One bit, %TBOUT, is set by the superior to 1 to grant permission, or +to 0 to deny it, to the job whose %TBOUT bit it is. The other, +%TBINF, if set to 0, denies all inferiors permission to type out +without forgetting the states of their %TBOUT's. A job inherits +type-out permission from its superior only if its own %TBOUT and the +superior's %TBINF are both 1. A job has type-out permission iff a +chain of inheritance reaches up from it to the top of the tree or to +the job which owns the TTY. + +The DDT command ^P works by means of this feature. + +File: ITSTTY, Node: B/4, Previous: B/3, Up: B, Next: B/5 + + 4. THE .TTY VARIABLE. + +This variable is actually called TTYTBL in the system. +"%TB" and "$TB" identify bits and fields in the TTYTBL variable, +which contains the information on the status of a job +with respect to its console tty (if any). Note that it is not +necessary for a job to belong to a tree that has a tty for these +bits to make sense. The $TBECL field is actually a shadow location +for a per-tty/per-job variable; it only contains real information +when the job does NOT have the tty. + +Most of the fields are set only by the system, but %TBNVR and +%TBINT are user options, settable by .SUSET or .USET. They +decide what the job will do when it tries to use the tty, but +doesn't have it. + +%TBNOT==400000 ;4.9 1 iff the job does not have the tty. +%TBNVR==200000 ;4.8 1 => opens of TTY: should fail when + ;the job does not have the tty. +%TBINT==100000 ;4.7 1 => all attempts to use the tty when + ;the job doesn't have the tty, should cause class 2 + ;interrupts on bit 4.2 (%PJTTY) of the first interrupt word. + ;0 => such attempts wait until the job gets the tty. +%TBWAT==040000 ;4.6 1 => override the settings of %TBNVR and + ;%TBINT, and always wait for the TTY. This bit can + ;be set only by the job's superior, and means "you + ;are supposed to have the TTY, even though for a + ;short interval you may not really have it". +%TBDTY==010000 ;4.4 1 iff job doesn't have tty, but wishes + ;to retain it. Set by .DTTY, cleared by .ATTY. +%TBOUT==004000 ;4.3 1 => this job can inherit type-out permission + ;from its superior (can be altered only by superior). +%TBINF==002000 ;4.2 1 => inferiors are allowed to inherit type-out + ;permission from this job. +$TBECL==220600 ;3.1 - 3.6 the job's setting of the number of + ;lines in the echo area, if the job doesn't have + ;the tty. +RH: ;If the job has the tty, this is the tty number. + ;If the job is in an .ATTY'ed state, this has the + ;internal user index of the inferior the tty + ;should be passed on to. + ;Otherwise, 0. + +File: ITSTTY, Node: B/5, Previous: B/4, Up: B + + 5. THE .CNSL VARIABLE. + +If a program needs to know the number of its tree's tty (or of +some other job's tree's tty), it can get that information +without actually possessing the tty by reading the .CNSL +user variable. That variable contains the number of the +tree's tty if there is one; -1 for a job scheduled as part +of the system; -2 for a job scheduled as a disowned job. +for a job device or its inferior, .CNSL will be the same as +for the creator of the job device. + +File: ITSTTY, Node: C, Previous: B, Up: Top, Next: D + +C. OPENING TTY CHANNELS. + +Terminals may be opened for I-O using either device TTY: or device +Tnm:. TTY should be used by a job in a console-controlled tree to +open the console. Tnm should be used to open a terminal "as a +device" - that is, to open a tty that is not the console of the +job doing the opening. + +* Menu: + +* Opening: C/1 Opening "TTY:" and "Tmn:" +* Bits: C/3 Device-dependent bits in the OPEN mode + +File: ITSTTY, Node: C/1, Previous: C, Up: C, Next: C/3 + + 1. OPENING "TTY". + +Device TTY may only be successfully opened by a job in a console- +-controlled tree which is in posession of the tty. If a job which +does not meet that criterion tries to open the tty, the open may +hang, fail, or generate a fatal interrupt, depending on the setting +of the %TBNVR and %TBINT bits of the job (*Note NoTTY: B/3.). +What such an open will definitely not do is succeed. + + 2. OPENING "Tnm". + +Opening device Tnm is the way for a program to make use of a tty +other than its console (in fact, it need not have a console). +"nm" should be replaced by the two-digit octal number of the terminal +to be used. In order for the opening of device Tnm to succeed, +the specified terminal must not be in use by any other job. +An attempt to open by number a tty which happens to be the console +of the job doing the open will succeed iff the job has the tty at +the time. This is to make it possible to specify one's own tty when +asked to specify a tty by number. + +File: ITSTTY, Node: C/3, Previous: C/1, Up: C, Next: D + + 3. DEVICE-DEPENDENT BITS IN THE OPEN MODE. + +Many of the bits in the mode specified in a .OPEN have special +meanings for devices TTY and Tnm. Some of them affect only the +channel being opened; others merely initialize some of the per-tty/ +per-job information, but those bits are +effective only if the terminal is not open in the same direction on +any other channel (those bits exist for historical reasons only, +since the variables they set may be set explicitly at any time +using the TTYSET and SCML symbolic system calls (*Note vars: G.)). + +The per-channel bits which have names are used only to initialize +the IOCHNM word of the channel - thus, mode bit 4.6 (%TIECH) is +copied into bit 4.6 of the IOCHNM word. Various I-O operations +examine the IOCHNM word to decide what to do. With symbolic system +call IOT's, the user may temporarily alter the settings of those +bits, so the values supplied in the open are merely the defaults +for the channel. + +The per-channel bits that are not named are +interpreted by the OPEN routine, and act by setting some of the +named bits, as described below. They exist for historical reasons. +(that does not include bits 3.1 and 3.2, which are special). + +* Menu: + +* Bits: C/3/a Per-channel bits +* Other: C/3/b Other Per-channel bits on input and output +* First: C/3/d First-time bits on output and input + +File: ITSTTY, Node: C/3/a, Previous: C/3, Up: C/3, Next: C/3/b + + a. Per-channel Bits. + +3.1 1 => output; 0 => input. Affects the interpretation of the + other bits. +3.2 1 => block mode; 0 => unit mode. In block mode, each + character is treated as in unit mode, except that on output, + "^C" is ignored, and on input, "^C" typed in will act like + end-of-file (that is, the .IOT will return with the last + word padded out with "^C"'s and the pointer not fully + counted out). "^C" also terminates SIOT's on unit input + channels, but it is not ignored by output SIOT's. + +File: ITSTTY, Node: C/3/b, Previous: C/3/a, Up: C/3, Next: C/3/d + + b. Other Per-channel Bits on Input. + +%TIECH==40000 ;1 => can read even if char needs pi echoing. +%TIPEK==20000 ;1 => don't remove char from buffer. +%TIACT==4000 ;1 => don't wait for activation character. +%TIINT==2000 ;1 => can read a char even if it is supposed to interrupt & hasn't yet. +%TINWT==1000 ;1 => do not wait for input. If no input is available, + ;unit mode IOT's return -1; unit mode SIOT's and block mode + ;IOT's return without filling up the space available to them. +%TIFUL==400 ;1 => use the full TV character set if possible. + ;suppresses the conversion, which is normally + ;performed on TV's, from the TV character set + ;to ascii. See ITS TV. + + + c. Other Per-channel Bits on Output. + +3.4 1 => turn on %TJECH, %TJPP2, and %TJMOR. +3.5 1 => turn on %TJDIS. +3.6 1 => turn on %TJSIO. +%TJECH==40000 ;1 => echo mode output (all chars output the + ;way they would be echoed) +%TJCTN==20000 ;1 => don't do line-continuation. +%TJSTP==10000 ;1 => this channel is hung in **more**. + ;this bit is unusual in that the system changes it +%TJDIS==4000 ;1 => recognize "^P" as an escape for display commands +%TJSIO==2000 ;1 => superimage output, no padding or cursor control. +%TJMOR==1000 ;1 => don't do **MORE** processing. +%TJPP2==400 ;1 => output in the echo area if there is one. + +File: ITSTTY, Node: C/3/d, Previous: C/3/b, Up: C/3 + + d. First-time Bits on Output. + +3.3 1 => image mode (set all %TGIMG bits in TTYST1 and TTYST2) + If you think you want to do this, you probably + really want to use %TJSIO. + + e. First-time Bits on Input. + +3.3 1 => image mode (clear all %TGPIE and %TGMPE bits in TTYST1, TTYST2). + It is UNWISE TO USE THIS FEATURE, because it will prevent the + user from translating TTY: to a file of commands for your + program. You should use a TTYGET and TTYSET to change these + bits, and you should not complain if they fail. +3.4 1 => "DDT" (clear %TGPIE and %TGMPE bits for CR, LF and TAB) +3.6 1 => want 3 lines in echo area. + (that is, the OPEN should do a SCML with argument 3. + *Note SCML: E/4.). + +File: ITSTTY, Node: D, Previous: C, Up: Top, Next: E + +D. INPUT FROM TERMINALS. + +Characters typed on a terminal, aside from those that invoke the +CALL and ESCAPE functions, go into an input buffer from which +they may eventually be read by the program (if the buffer is +full, they are discarded, and a "^G" is output). Before being +read, they may be echoed (and usually will be). A character may +also cause an input interrupt - this allows specific characters +to signal a program to perform some action immediately, at any +time, without waiting for the program to get around to looking +for input. + +If %TOALT is set, and %TSALT is not, characters 175 and 176 will +be turned into 33 (this is "standardization of altmodes"). + +* Menu: + +* Echo: D/1 Echo +* MP Input: D/2 Main-program input. +* Activation: D/3 Activation. +* Interrupts: D/4 Input interrupts. +* Throw: D/5 Throwing away type-in. +* Avail: D/6 Testing for the availability of input. +* .STATUS: D/7 .STATUS on tty input channels. +* Char Set: D/8 The character set + +File: ITSTTY, Node: D/1, Previous: D, Up: D, Next: D/2 + + 1. ECHO. + +"Echoing" is the act of typing out whatever the user types in. +Its purpose is to give the user positive verification of his +type-in. On ITS, echoing works by taking the typed-in characters +and outputting them in echo mode, in the echo area if there is +one (that is, outputting with %TIECH and %TIPP2 set). There are +two types of echoing: PI echoing, and MP (main program) echoing. +PI echoing happens as soon as possible after the character is +typed in. MP echoing happens when the character is read in by +the program. Each program may specify which characters ought to +be PI echoed, and which ought to be MP echoed, using the +per-tty/per-job variables TTYST1 and TTYST2 (specifically, the +%TGPIE and %TGMPE bits, of each of which there is one for each +group). It is permitted to specify that a character not be echoed +at all, or that it be echoed in both ways (PI and MP). Most +programs specify that all characters be PI echoed, and none MP +echoed; DDT choses to have LF and TAB not echoed at all; some +programs such as TELNET and PDP11 in certain modes turn off all +echoing. MP echoing is not used much if at all, and is not +clearly useful, so it may be flushed in the future, although if +an important use is found it will stay. Therefore, new programs +should avoid using MP echo if possible. If use of it is +very desirable, please :BUG ITS the application. + +Normally, a character cannot be read in until any necessary +echoing has taken place. However, if reading is done with the +%TIECH bit set, any echoing (of the characters thus read) not +yet performed will be skipped entirely. This does not guarantee +that such characters will not be PI echoed; it just means that +the system will not regard the PI echoing as essential, and will +forgo it rather than wait for it. MP echoing will certainly not +be done for characters read with %TIECH set. Extra bits will be +returned with such characters saying what kinds of echoing were +appropriate but were not yet done, to enable the program to echo +the character itself if that is right. The bits are +%TXPIE=200000 saying PI echo was desired, and %TXMPE=400000 +saying MP echo was desired. + +The bit %TSNOE in the TTYSTS variable (*Note TTYSTS: G/1/b.), when set +to 1, causes echoing to be deferred; that is, echoing will not be +performed while the bit is set, but the system still remembers what +echoing is pending, and will again start doing it when %TSNOE becomes +0. However, if a character with pending echoing is read in while +%TSNOE is 1, the pending echoing will of necessity be forgotten. When +%TSNOE is 1, the system acts as if %TIECH were 1 on all input IOT's +from that tty, since otherwise such IOT's wuld simply wait forever. +In particular, the %TXPIE and %TXMPE bits in the character read will +tell the user what sorts of echoing were still pending. + + +File: ITSTTY, Node: D/2, Previous: D/1, Up: D, Next: D/3 + + 2. MAIN-PROGRAM INPUT. + +Characters are read from the tty using the .IOT UUO or the +symbolic system calls IOT or SIOT. +.IOT has slightly less overhead, but the symbolic system calls +allow the channel's characteristics to be temporarily altered. + +Unit mode IOT's read a single character and return it. SIOT's and +block mode IOT's try to read enough characters to fill the block +supplied, but the character "^C" will cause them to return what +has been read so far, with pointers and counts not fully advanced. +SIOT and block mode IOT input from ttys is relatively useless; +it is provided for the sake of device-independence. Programs +should normally read from the tty in unit mode. + +IOT'ing on the job's console cannot actually be done unless the +job has control of the console (*Note Owner: B.). If it does not, +either the IOT will wait until the job gets the tty, or a class 2 +interrupt will result, depending on the %TBINT and %TBWAT +bits in .TTY (*Note NoTTY: B/3.). +Also, on any tty, IOT's will wait until either the tty is +not in a com link, or the tty is slaved, or %TCICO is set +(*Note Com: A/4/e.). + +Input IOT's executed when the input buffer is empty will +normally wait until input is available (*Note Wait: D/3.). However, +if %TINWT is set, the IOT will not wait at all. Instead, unit mode +IOT's will immediately return -1; SIOT's and block mode IOT's +will return with the supplied block not completely filled +and the pointer and count advanced to point to the first +unfilled character or word. + +When an IOT attempts to read a character, if PI echoing is +necessary for the character and has not been performed, the IOT +waits until it has been (unless %TIECH is set, or %TSNOE is +set). Also, if the character is supposed to cause an input +interrupt, the IOT waits until the character has been processed +at interrupt level with .ITYIC (unless %TIINT is set or .PICLR +holds 0 preventing interrupts from occurring). In that case, the +interrupt will normally occur as soon as the IOT hangs up, and +if the interrupt routine dismisses normally, the IOT will then +be able to read the character. + +When any necessary PI echoing or interrupting is finished, the +IOT performs MP echoing if necessary and not yet done (unless +%TIECH is set, or %TSNOE is set). The character is then removed +from the input buffer and returned to the user (but if %TIPEK is +set, the character is left in the input buffer, so that the next +IOT will re-read it). If echoing that normally +would have been required before the IOT could return has been +omitted because of %TIECH or %TSNOE, the following extra bits +will be returned along with the character read (in unit mode +only): %TXPIE = 200000 meaning that PI echo would have been +done, and %TXMPE = 400000 meaning that MP echoing would have +been done. + +It is at this point, when the character is about to be returned +to the user, that conversion from the TV character set to ascii +is done unless the %TIFUL bit is set. This conversion happens on +all terminals but it has no effect on characters which are +already ascii,as all characters are if the terminal is not a TV. + +The way symbolic system call IOT's and SIOT's change the settings +of the per-channel bits is with the control-bit argument, which is +XOR'ed into the IOCHNM word at the beginning and end of the IOT. +Thus, if %TIACT is normally 0, and it is desired to read one +character with %TIACT set to 1, the following call may be used: + .CALL [ SETZ + 'IOT,, + 1000,,TYIC ;CHANNEL. + AC ;CHARACTER READ GOES IN AC. + 405000,,%TIACT] ;IMMEDIATE CONTROL-BIT ARGUMENT. + .VALUE + ... ;CHARACTER NOW IN AC. +Note that the IOT does not change the settings permanently; to +do that, the channel must be reopened. The specified bits are +changed only for the duration of the IOT that specifies them. + + +File: ITSTTY, Node: D/3, Previous: D/2, Up: D, Next: D/4 + + 3. ACTIVATION. + +An input IOT will, for an unclever program, unhang as soon as there +is any character to be read in. However, it may be known that a +particular program never needs to respond to type-in until a character +from some small set (such as CR and rubout; for TECO, altmode, +rubout and "^C") has been typed in. Such programs may lighten the +scheduling and swapping load on the system by saying that other +characters should not be "activation characters". Then an IOT will +usually not unhang unless at least one activation character +has been typed in. Note that no lossage will occur if a character +that need not activate does so. Also, some other conditions cause +activation. + +The set of activation characters is specified using the %TGACT bits +in the TTYST1 and TTYST2 variables. Initially, all of them are 1, +meaning that all characters should activate. + +A program may be able to get away with a small set of activation +characters except in a few special circumstances (for example, +TECO needs to be able to respond immediately to a "?" typed as +the first character when a command string is expected, but most of +the time a "?" requires no immediate response). The +program may then specify that small set for activation, and when +the unusual circumstances arise, it can do input in a special +way that does not wait for activation, either by IOT'ing with the +%TIACT bit set to 1, or by setting %TSACT to 1 before each character +is read. Both of those bits mean "activate on any character". Note +that %TSACT is cleared after each character, so setting it only +affects the next attempt to do input. %TIACT may be set temporarily +using a symbolic system call IOT. + + +File: ITSTTY, Node: D/4, Previous: D/3, Up: D, Next: D/5 + + 4. INPUT INTERRUPTS. + +A program may enable an interrupt to occur whenever a character +is typed in. In the simplest case, any character will cause an +interrupt, but the program may prevent uninteresting characters +from interrupting by clearing their %TGINT bits in TTYST1 and +TTYST2. There are two kinds of interrupts that may be enabled. +If the tty is a console, bit 1.1 (%PITYI) in the first interrupt +word may be enabled. This bit is obsolete and should be avoided. +For any tty, whether console or device, an interrupt may be enabled +on one of the input channels - in which case an interrupt will be +signaled on one and only one of the enabled channels. Both kinds +of interrupt are class 3. + +Most programs normally read their input at main program level, +and want only a few characters to be processed at interrupt level. +Such programs need to be able to examine the character which caused +the interrupt. IOT'ing it will not do, for other non-interrupting +characters may have been typed in before the interrupt character, +and not read yet at main program level. ITS provides a special +mechanism for doing this: .ITYIC, which reads the next +not-yet-.ITYIC'ed interrupt character. The program should execute +.ITYIC for each tty input interrupt to see what character caused it. +The calling sequence is: + MOVEI AC,CHANNEL + .ITYIC AC, + JRST GIVEUP ;PRETEND THIS INTERRUPT HADN'T HAPPENED. + ... ;CHARACTER NOW IN AC. +The .ITYIC will skip if it succeeds; it can fail if the channel +number is bad or does not have a tty open, if the tty is the job's +console but does not belong to this job at the moment, or because +no interrupt character is available. It can also cause a class 2 +interrupt if the %TBINT bit is set and the job does not have the +tty. + +.ITYIC is actually a special case of the WHYINT generic system call. +Doing a WHYINT on a TTY input channel will return %WYTYI as the first +value and the character which caused the interrupt as the second. +WHYINT was invented by generalizing .ITYIC to other sorts of devices. +Thus, .ITYIC is actually semi-obsolete, but everyone still uses it. + +The program should ignore any interrupt caused by a character +that isn't supposed to interrupt (due to timing screws and +moving the tty from one job to another that can happen). It +should also ignore an interrupt if the .ITYIC doesn't skip +(that can happen if DDT took the tty away and flushed the input +between the interrupting and the .ITYIC'ing). + +If the interrupt routine decides that it needs to examine the +next character also, it can set %TSINT to 1. That will cause the +following character to interrupt even if it normally wouldn't +(TECO uses this to distinguish a solitary altmode from a pair of +altmodes at interrupt level). This feature will work regardless +of whether that "following" character has already been typed in. + +.ITYIC'ing does not eliminate the need to IOT the character - it +is specifically designed not to interfere with the expected later +IOT'ing of the character. If the interrupt character is supposed +to have no effect except for the interrupt, then it must be +ignored explicitly when IOT'ed. Alternatively, the character can +be flushed explicitly from the input stream by using the TTYFLS +symbolic system call (see ITS .CALLS). + +It is not necessary for the interrupt handler to keep .ITYIC'ing +until no more characters are available, because a separate +interrupt will occur for each character that should cause one. + +An alternative to .ITYIC'ing at interrupt level and IOT'ing at +main program level, is IOT'ing at interrupt level. This works +reasonably as long as it is convenient for the program (for +example, PEEK does this). The program can even IOT the characters +at interrupt level and keep its own buffers for its main program +level if it wishes to. If the characters are +IOT'ed when they interrupt, there is no need to .ITYIC them. +However, all characters must be set to cause interrupts, or the +interrupts might get one off from the IOT's. + +File: ITSTTY, Node: D/5, Previous: D/4, Up: D, Next: D/6 + + 5. THROWING AWAY TYPE-IN. + +If a .RESET UUO or a RESET symbolic system call is done on a +tty input channel, any input in the input buffer will be thrown +away. If any of the characters being discarded has not echoed, +or has not interrupted, then it never will. + + +File: ITSTTY, Node: D/6, Previous: D/5, Up: D, Next: D/7 + + 6. TESTING FOR THE AVAILABILITY OF INPUT. + +A program may find out how much input is available using the UUO +.LISTEN or the symbolic system call LISTEN. Both wait for the +output buffer to empty, and then return the number of characters +in the input buffer (To check for input without waiting for output +to finish, use .STATUS - see below). +.LISTEN AC, applies only to the job's console, +and returns its value in AC. If the job has no console, or doesn't +have its console at the moment, 0 is returned. +The symbolic LISTEN call takes a tty +channel as an argument and returns a value in the usual way. +The call will fail if the channel number is bad, if the channel does +not have a tty open, or if the tty is the job's console but the +job doesn't own it at the moment. It will skip iff it succeeds. + .CALL [ SETZ + 'LISTEN + 1000,,CHANNEL + 402000,,FOO] ;PUTS # CHARS. IN FOO. + JRST NOTTY ;I WAS ^P'D BY DDT. + ... ;FOO NOW SET UP. + + +File: ITSTTY, Node: D/7, Previous: D/6, Up: D, Next: D/8 + + 7. .STATUS ON TTY INPUT CHANNELS. + +A .STATUS or symbolic system call STATUS executed on a tty +channel returns either 1 or 2 as the device type code - 2 if the +tty is a display with selective erase (%TOERS is set); 1, otherwise. +Bit 2.1 will be 1 iff the tty's input buffer is full; bit 2.2 will +be 1 iff the buffer is empty. Thus, .STATUS on an +input channel is a way of testing for the availability of input +without waiting for the output buffer to empty out. Bit 2.4 will be +1 if the job currently owns its console. Bit 2.5 will be 1 iff the +number of characters available for IOT'ing is different from the +number available for interrupt level processing (I am not sure why +this bit exists). Bit 2.8 will be 1 iff the terminal is located +next to the 340 display or one of its slaves (it will always be +0 except on the AI KA-10 machine). Bit 2.9 will be 1 iff the terminal +is "local" - that is, near the machine itself (only local ttys +are allowed to use the LPT directly, for example). + +File: ITSTTY, Node: D/8, Previous: D/7, Up: D + + 8. THE CHARACTER SET + +This section describes the 12-bit input character set. Terminals +with the %TOFCI TTYOPT bit set can generate all of these. Other +terminals can only generate the ascii subset. + +An input character consists of 7 bit of ascii character and 4 modifier +bits. Note that the ascii codes from 0-37, if generated by a +non-%TOFCI terminal, are control characters, but if generated +by a %TOFCI terminal are either special keys (like RETURN) +or are "SAIL" printing characters in which case they appear in +combination with %TXTOP. TECO ORDER has more information on this. + +The modifier bits are: + + %TXTOP Indicates that the TOP key was held down (usually). + Can also indicate some special characters (see below). + %TXCTL Indicates that the CTRL key was held down. + %TXMTA Indicates that the META key was held down. + %TXSUP Indicates that the SUPER key was held down. + (This used to mean that the SHIFT key was held down.) + +Numerically, %TXTOP=4000, %TXCTL=200, %TXMTA=400, and %TXSUP=1000. +%TXASC=177 is a mask for the 7-bit ascii basic character. + +Note that the TOP key also modifies the ascii character +code, but CTRL and META are simply added in. + +Some special keys are indicated by %TXTOP plus the ascii code for +a capital letter. These can also be combined with %TXCTL, %TXMTA and %TXSUP. + + %TXTOP+A ESCAPE. Note that the ESCAPE key is used to send commands + to the terminal controller (see ITS TV), so it cannot + be sent to the system except with CTRL or META. + %TXTOP+B BREAK. Recommended as the character for "getting out of" + programs where CALL is not what you want. + %TXTOP+C CLEAR. + %TXTOP+D circle-minus. An unassigned printing character key. + %TXTOP+E circle-plus. An unassigned printing character key. + %TXTOP+F delta. An unassigned printing character key. (shift circle-minus) + %TXTOP+G del. An unassigned printing character key. (shift circle-plus) + %TXTOP+H Help key (top H). Recommended for getting help. + This code is unusual in that it is passed to the + program as %TXTOP+H even when %TIFUL is not set. + %TXTOP+Z Internal code for deferred call. + +Other special keys, which generate codes in the ascii controls region +and without %TXTOP, are: + + 10 Backspace + 11 Tab + 12 Line + 13 VT + 14 Form (recommended for clear and redisplay the screen) + 15 Return (recommended for end of line) + 37 Back-next (used for input escape, *Note Escape: A.) + 33 Altmode + 177 Rubout (recommended for character deletion) + +Some of these have printed representations on output. Backspace, Tab, +Line, and Return are format effectors. Altmode is a printing character. + +File: ITSTTY, Node: E, Previous: D, Up: Top, Next: F + +E. OUTPUT TO TERMINALS. + +The most basic forms of I-O are oriented toward stream-like devices. +In fact, the ideal terminal is no longer a stream-like device but a +random-access device - a display. Ordinarily, access proceeds +sequentially using a pointer called the cursor. For more interesting +operations, a set of display commands are provided to move the cursor +or erase sections of the screen in ways independent of the hardware +characteristics of the particular display in use, as long as the +display has the ability to perform the specified function at all. +There are also bits in the TTYOPT variable, which may be read with the +CNSGET symbolic system call, that give information on which functions +the particular terminal can perform. + +* Menu: + +* Output: E/1 How to cause characters to be output. +* Normal: E/2 Normal output (sequential access). +* Display: E/3 Display-mode channels. ^P-codes. +* Echo: E/4 The echo area. +* Cursorpos: E/5 Reading the cursor position. +* Super: E/6 Superimage output. +* TTYOPT: E/7 Relevant TTYOPT bits. +* Flush: E/8 Throwing away typeout. +* Waiting: E/9 Waiting for output to be sent to the terminal. +* .STATUS: E/10 .STATUS on tty output channels. + +File: ITSTTY, Node: E/1, Previous: E, Up: E, Next: E/2 + + 1. HOW TO CAUSE CHARACTERS TO BE OUTPUT + +User programs output characters by means of the .IOT UUO or the +symbolic system calls IOT or SIOT. .IOT is pretty much equivalent to +symbolic IOT, but has slightly less overhead and is less flexible. +Display commands, which are several characters long, are output +by outputting in order the characters that compose them. +Unit mode channels may be used to output single characters with +IOT, or to output packed strings of characters with SIOT. +Since SIOT is much more efficient, commonly used programs or programs +doing much tty output should use it when possible. + +Block mode is semi-obsolete. On a block mode channel, IOT outputs +a block of words, containing 5 characters each. The character "^C" +is totally ignored, making it possible to output other than a +multiple of five characters. Block mode IOT's have no advantage over +SIOT's on unit mode channels. + +The symbolic system calls IOT and SIOT allow the respecification of +the values of several per-channel mode bits (all those given names +starting with "%TJ" - *Note Bits: C/3/c.). Unit mode IOT is somewhat +slower than the .IOT UUO, but the same is not true for SIOT and block +mode IOT. + +From now on, all three ways of outputting a character will be referred +as IOT'ing, since their differences have all been described above. + +If the terminal is in a com link, output IOT's will hang up, unless +%TCOCO (see "^_O") or %TCLFT (see "^_E") is set. If the tty is the job's +console, the IOT will not do its work unless the job has the +tty; otherwise it may wait or it may interrupt (*Note NoTTY: B/3.). + +File: ITSTTY, Node: E/2, Previous: E/1, Up: E, Next: E/3 + + 2. NORMAL OUTPUT (SEQUENTIAL ACCESS). + +The way terminal output works when display commands are not in use +is that each ordinary character is printed where the cursor points, +and advances the cursor over the positions that it occupies. +Formatting characters such as CR, LF, TAB and BS act by moving the +cursor in the appropriate way (that is, they are really display +commands). + +* Menu: + +* How: E/2/a How the System Goes about Outputting. +* Contin: E/2/b Continuation - the Result of Line-overflow. +* Wrap: E/2/c Wraparound and Scrolling - the Results of Page-overflow + +File: ITSTTY, Node: E/2/a, Previous: E/2, Up: E/2, Next: E/2/b + + a. How the System Goes about Outputting. + +The way the system outputs any particular character to the tty +depends in general on the following factors: whether the relevant +%TGIMG bit in the TTYST1 +or TTYST2 variable says that the character should be output in image +mode (this is the only way those bits have an effect), whether +the channel specifies output in echo mode, whether the terminal +can print the SAIL character set, and sometimes on random TTYSTS +bits. + +Note that we are thinking of flushing the %TGIMG bits in TTYST1 and +TTYST2. If that is done, all output will be done "in ASCII mode". If +you want the effects described below for image mode, you should +probably open a channel in superimage mode and use it at such times. + +* Menu: + +* Ascii: E/2/a/1 ASCII Graphic Characters. +* ^G: E/2/a/2 "^G". +* CR: E/2/a/3 Carriage-return. +* LF: E/2/a/4 Linefeed. +* Tab: E/2/a/5 Tab. +* ^L: E/2/a/6 Control-L (Formfeed). +* Altmode: E/2/a/7 Altmode. +* ^P: E/2/a/8 Control-P, the escape code. +* BS: E/2/a/9 Backspace. +* Random: E/2/a/10 Random Control Characters, and Rubout. + +File: ITSTTY, Node: E/2/a/1, Previous: E/2/a, Up: E/2/a, Next: E/2/a/2 + + 1: ASCII Graphic Characters. + +These characters are simply sent to the terminal. The system +assumes that they will occupy one printing position, and move +the terminal's hardware cursor one place to the right. + + +File: ITSTTY, Node: E/2/a/2, Previous: E/2/a/1, Up: E/2/a, Next: E/2/a/3 + + 2: "^G". + +"^G" is assumed to make a noise or other temporary indication, +occupy no space on the screen, and not move the cursor. + + +File: ITSTTY, Node: E/2/a/3, Previous: E/2/a/2, Up: E/2/a, Next: E/2/a/4 + + 3: Carriage-return. + +If the channel specifies echo mode, a "CRLF" will be done. +That is, the results will be the as if a CR and a LF had +been output in image mode. +Otherwise, if the TTYST2 variable specifies that CR is output +in ascii mode, a "CRLF" will be done just the same, except +that a bit will be set so that if the next character output +to the tty is a LF, it will be ignored. Thus, in ascii mode, +a CR without a LF is the same as a CR with one LF. +If CR is output in image mode, it moves the cursor to the +beginning of the line it was on. The line is not cleared. +However, this feature will eventually be flushed, so you should not +use it. Instead, simply output ^PH^H to do a "stray CR". In fact, +you can output all your CR's this way. For CR's which are not stray, +this will not cause any trouble, and for those which are stray, it +will cause the desired overprinting. + +File: ITSTTY, Node: E/2/a/4, Previous: E/2/a/3, Up: E/2/a, Next: E/2/a/5 + + 4: Linefeed. + +If a LF follows a CR that was output in ascii mode and not +in echo mode, the LF is ignored. Otherwise, the LF is output +in one standard way regardless of the settings of the several +variables (but it is best to have TTYST2 specify ascii mode +just in case image mode for LF ever means something). +The action of LF is normally to move the cursor down one line. +The horizontal cursor position is not changed by a LF. On +displays with selective erase (%TOERS is set) LF clears the +line it moves down to. The entire line is cleared even if +the horizontal position is not zero. +The bottom of the screen poses special problems for LF. +If the LF reaches the lowest line on the screen, it may +trigger **MORE** processing. If it starts from the bottom line +of the screen, it needs to wrap around or scroll (*Note Wrap: E/2/c.). + +File: ITSTTY, Node: E/2/a/5, Previous: E/2/a/4, Up: E/2/a, Next: E/2/a/6 + + 5: Tab. + +If the channel specifies echo mode or TTYST2 specifies ascii +mode, the tab causes the cursor to be moved rightward up to +the next multiple of eight spaces from the left margin, or +to the right margin if that comes first. If continuation is +not suppressed and the cursor starts out at the continuation +column, continuation will be done and then the tab will be +handled (note that when continuation is in effect, the right +margin is the continuation column). +If output is not in ascii mode or echo mode, a tab character +is sent to the tty, and assumed not to move the cursor. + +File: ITSTTY, Node: E/2/a/6, Previous: E/2/a/5, Up: E/2/a, Next: E/2/a/7 + + 6: Control-L (Formfeed). + +In echo mode, "^L" will normally echo as a clear screen +("^PC"). However, on printing ttys (ttys whose %TOMVU is off) +or if the program has set %TSCLE (Control-L Echo) "^L" will +echo like other random control characters (*Note Ctl: E/2/a/10.). +Not in echo mode, "^L" is treated like other random +control characters. + +File: ITSTTY, Node: E/2/a/7, Previous: E/2/a/6, Up: E/2/a, Next: E/2/a/8 + + 7: Altmode. + +If the TTYST2 variable says that altmode should be output in +ascii mode, or if the channel specifies echo mode, then +normally a dollar-sign will be sent, but if the %TOSAI bit in +the TTYOPT variable, which means "ASCII mode should use the +SAIL character set" is on, an altmode will be sent (it comes +out as a diamond on the screen). In either case the cursor +moves one position. +If output is in image mode and not in echo mode, an altmode +will be sent to the terminal. It will be assumed not to move +the cursor unless %TOSAI is set, meaning "the terminal +understands the SAIL character set", in which case it will +be assumed to move the cursor one space right. + +File: ITSTTY, Node: E/2/a/8, Previous: E/2/a/7, Up: E/2/a, Next: E/2/a/9 + + 8: Control-P. + +"^P" is output like most other control characters (*Note Ctl: E/2/a/10.). +However, on a channel open in display mode, "^P" serves as +an escape prefix for display commands. In order to output +a "^P" using such a channel, the display command "^PP" must +be used. + +File: ITSTTY, Node: E/2/a/9, Previous: E/2/a/8, Up: E/2/a, Next: E/2/a/10 + + 9: Backspace. + +In echo mode on a terminal which can't backspace, "^H" echoes +as uparrow-H. +Otherwise, if in column 0, backspace does nothing. +Otherwise, on an IMLAC, backspace sends a backspace, and +assumes the cursor moves back one position. On other types +of terminals, backspace simply moves the cursor back one +position. + +File: ITSTTY, Node: E/2/a/10, Previous: E/2/a/9, Up: E/2/a + + 10: Random Control Characters, and Rubout. + +If TTYST1 specifies ascii mode for these characters, or +the channel specifies echo mode, then a control character +will be sent as an uparrow followed by the appropriate +graphic character (thus, "^A" as "^" followed by "A"), +unless %TSSAI is set, in which case the control character +itself will be sent, and the system will expect it to be +a graphic that moves the cursor one position. +If %TSSAI is 0 but %TOSAI is set, then a SAIL uparrow will +be used instead of a "^" when typing the "^A". +If not in ascii mode or echo mode, the control character +itself will be sent, and the system will expect it not to +move the cursor, unless %TOSAI is set, in which case it +will be expected to move the cursor one space right. +Note that this is just like the treatment of altmode +except for the details of the conversion in the case +of ascii or echo mode with %TSSAI not set. + +File: ITSTTY, Node: E/2/b, Previous: E/2/a, Up: E/2, Next: E/2/c + + b. Continuation - the Result of Line-overflow. + +When typeout attempts to go past the right margin, the +system inserts a "!" and a CRLF to make sure that output +is not lost. The last printing position on each line is +normally reserved for the "!" printed when continuation +is done, and the line size of the terminal as specified +in or returned by system calls does not count that column. +The act of continuation takes place when an attempt is made +to output a character and the cursor is pointing at the +reserved continuation column; the "!" and CRLF are output, +followed by the character that provoked the continuation +(which will be in the next line). +Continuation may be suppressed by opening a channel with the +%TICTN bit set; then characters output on that channel will +never provoke continuation no matter where the cursor points. +The continuation column is available for use by the program. + +The display codes ^PX and ^PB "understand" continuation to some +extent. See their descriptions. + +File: ITSTTY, Node: E/2/c, Previous: E/2/b, Up: E/2 + + c. Wraparound and Scrolling - the Results of Page-overflow. + +When an attempt is made to linefeed past the bottom line of +the screen, either the cursor wraps around or the screen scrolls +up. Which one happens depends on whether the terminal is in +scroll mode, as determined by the setting of %TSROL. That bit +is stored per-tty/per-job, and may be set by the program with +TTYSET, and complemented by the user with "^_^". Its value +is initialized from %TOROL in each job separately. %TOROL is +initialized whenever a tty begins to be used. The initial +value is 0 except on the dynamod machine. %TOROL may be set +with a CNSSET, or by the TCTYP program. + +The echo area cursor never causes scrolling. Whenever it reaches +the bottom of the screen it wraps around to the top of the echo +area, regardless of the setting of %TSROL. + +* Menu: + +* Scrolling: E/2/c/1 +* Wraparound: E/2/c/2 + +File: ITSTTY, Node: E/2/c/1, Previous: E/2/c, Up: E/2/c, Next: E/2/c/2 + + 1: Scrolling. + +Scrolling moves the contents of the screen up several lines +(the number depends on the type of terminal) and then linefeeds +normally. Only some types of terminals can scroll; others will +always wrap around even if scroll mode is on. + +File: ITSTTY, Node: E/2/c/2, Previous: E/2/c/1, Up: E/2/c + + 2: Wraparound. + +On displays that can erase selectively, wraparound simply +puts the cursor on the top line, clearing it. +On Tektronix-like displays (those which can't erase selectively), +wrapaound clears the screen, since it can't clear only the +top line. Because this is necessary, **MORE** processing is +less likely to be suppressed on such terminals. +Wraparound does take place on printing ttys, but it is +indistinguishable from ordinary linefeed. + +File: ITSTTY, Node: E/3, Previous: E/2, Up: E, Next: E/4 + + 3. DISPLAY-MODE CHANNELS. ^P-CODES. + +It would be impossible to output a display command using a channel +which simply printed any character sent out on it. If it is desired +to make use of display commands, a channel may be opened in display +mode. That causes the character "^P" to be an escape character when +output on that channel. When a "^P" is output on a display-mode +channel, it has no effect except for setting bits causing the next +character output on that channel to be interpreted as a display code. +The display codes are: + +A Advance to a fresh line. If at beginning of line do nothing, + else act like a CRLF. +B move Backward. Decrements the horizontal position. + If the horizontal position is 0, it is set to the horizontal + screen size minus two, and the vertical position is decreased + by one. Thus, it moves back over one character position even + if there was a line continuation in the way. +C Clear screen. The cursor goes to the upper left corner and + the whole screen is cleared. On a printing tty (%TOMVU is 0) + a CRLF is output, since "clearing the screen" is undefined. + If "^PC" is output to the echo area, only the echo area is + cleared, and only the echo area cursor is moved. +D move Down. The vertical position is incremented. If it becomes + equal to the vertical screen size, it is set to 0. +E clear to Eof. The remainder of the current line, and all lower + lines, are erased. The cursor doesn't move. +F move Forward. The horizontal position is incremented. At the + end of the line it wraps around to the beginning of the + next line. +H set Horizontal position. Takes one argument: the following + character should be the desired horizontal position setting + plus 8. The vertical position is not changed. An attempt to + set the position beyond a margin will position it at the + margin. +I Outputs a one-position printing character in image mode. Takes one + argument: the numeric ASCII code of the desired character. +K Kill (erase) the character the cursor points at. The cursor + does not move. The position erased is the one that would be + written in next by ordinary output. +L clear Line. The current line, starting with the position that + the cursor points at, is erased. The cursor does not move. +M (More) hang up until a character is read in. *Note More: F/3. +N (No home-up) similar, but don't home up after the character is + read. +P output "^P". Useful if it is desired to output "^P" in image + mode with a display-mode channel, or if the terminal handles + the SAIL character set. +Q output "^C". Similar to "^PP". This is needed only for block + mode IOT's. With SIOT, it is not needed since "^C" isn't special. +R Restore cursor position. The cursor is set to the most + recently saved value. +S Save cursor position. Remembers the current cursor position + for use with "^PR". There is no stack for saved cursor + positions; only the most recent saved position is remembered. +T go to Top of screen (home up). The cursor is positioned at the + upper left corner of the screen. +U move Up. The vertical position is decremented. If it was 0, + it becomes equal to the vertical size minus one. +V set Vertical position. Takes the following character as an + argument - it should be 8 plus the desired vertical position. + An attempt to set the cursor beyond the top or bottom margin + will position it as far as allowed in the desired direction. + Similarly, "^PV" will not move the echo area cursor outside + the echo area. Note that vertical positions in the echo area + are to be specified relative to the top of the echo area. +X backspace and erase one character ("^PB" followed by "^PK"). + If done at column zero, it clears the last TWO characters on + the previous line (assuming that one of them was the + character you intended to erase, and the other was an "!" + indicating a continuation). +Z home down. The cursor is positioned at the lower left corner. +[ insert line. The current line and all lines below it are + pushed down one slot. A blank line appears at the current + position. The cursor does not move. Works only on terminals + which have %TOLID set (^P\ also). +\ delete line. The current line disappears, and all teh lines + below it move up by one position. The bottom line becomes + blank. The cursor does not move. +] obsolete - same as "^PL". +^ insert character. All the characters after the cursor move + right one position. The last one moves off the right margin + and disappears. A space appears at the cursor, which does not + move. Works only on terminals which have %TOCID set. +_ delete character. The character at the cursor disappears, and + all the rest of the characters on the line move left one + position. A space appears at the end of the line. The cursor + does not move. + +File: ITSTTY, Node: E/4, Previous: E/3, Up: E, Next: E/5 + + 4. THE ECHO AREA. + +Normally there is only one cursor, used by all output, including +echoing, and visible always on the screen. However, the program may +create an "echo area", which means that there will be two cursors: +one acting just like the normal one, and used for most program +output; the other, restricted to a few lines at the bottom of the +screen, and used for all echoing (and by program output that +specifically requests it). +The terminal will show whichever cursor was used most recently. + +The normal cursor is known as the "main-program cursor"; the other, as +the "echo area cursor". + +* Menu: + +* How: E/4/a How the Echo Area Works. +* Creating: E/4/b Creating an Echo Area. + +File: ITSTTY, Node: E/4/a, Previous: E/4, Up: E/4, Next: E/4/b + + a. How the Echo Area Works. + +One of the per-tty/per-job variables in the system is the size of the +echo area. This variable is 0 iff there is no echo area; this is the +usual case, and all output (including echo) uses the main program +cursor. If the variable isn't 0, it must be positive and less than the +screen height; that many lines at the bottom of the screen become the +echo area. Ordinary output using the main program cursor is not +affected by the existence of the echo area, but output done with the +%TIPP2 bit set (and this includes all system echoing), will use the +echo area cursor. This cursor is restricted to the echo area; ^P-codes +and wraparound for this cursor act as if the top of the screen were +really located at the top of the echo area (the ^P-codes mention how +they treat the echoing cursor if that is special). Scrolling never +happens to the echo area cursor. **MORE** processing can happen, +just as with the main program cursor, and completely independently, +but all system echoing is done with %TIMOR set to prevent that. + +File: ITSTTY, Node: E/4/b, Previous: E/4/a, Up: E/4 + + b. Creating an Echo Area. + +When a job is created it has no echo area on its console. When a tty +in use as a device is first opened, it has no echo area. The size of +the echo area may be changed (and, in particular, an echo area may be +created or destroyed) with the SCML symbolic system call, described +in section G.3.c. Also, one of the first-time-only bits in the mode +of the tty input OPEN allows creation of a 3-line echo area. + +File: ITSTTY, Node: E/5, Previous: E/4, Up: E, Next: E/6 + + 5. READING THE CURSOR POSITION. + +The symbolic system call RCPOS returns to the program the values +of the cursor positions of both the main-program area and the +echo area. Each cursor position is returned as a single word +consisting of the vertical position in the left half and the +horizontal position in the right half. The first value is the +main program area cursor; the second, the echo area cursor. The +echo area cursor position is returned relative to the top of the +echo area. *Note TTY Spec: G/2. for a description of the options +for the first argument and the reasons why the call can fail. +RCPOS does not require ownership of the terminal, just output +permission (*Note Permit: B/3.). For example: + .CALL [ SETZ + SIXBIT/RCPOS/ + 1000,,CHANNEL + 2000,,MPPOS ;MP ARE POSITION GOES IN MPPOS. + 402000,,ECHPOS] ;ECHO AREA POSITION GOES IN + ;ECHPOS. + .VALUE ;CALL FAILED. + ... ;CALL SUCCEEDED. + +File: ITSTTY, Node: E/6, Previous: E/5, Up: E, Next: E/7 + + 6. SUPERIMAGE OUTPUT. + +When %TISIO is 1, output is done in superimage mode. That means that +no padding will be done, and the system will not do cursor positioning +or attempt to keep track of where the cursor is; every character +IOT'ed will be sent without change. In addition, ITS output buffer +display commands may be sent directly, rather than via ^P-codes +(*Note SUPDUP: K/1). This mode is useful when output is +being done to a strange device that is connected to the system via a +tty line (for example, a logo music box or a PDP11 running the +absolute loader), and when the output has already been put into the +correct form for the particular type of tty (for example, the TELNET +program has a mode that assumes that the foreign host has handled +such things). It is also useful for programs which do +cursor-position updating, line continuation, etc., themselves, +and want to save time by stopping ITS from doing them. + +To be efficient, use SIOT. Block mode IOT will ignore +"^C", which may be embarrassing. + +If the characters output in superimage mode will move the cursor, +the SCPOS system call must be used to tell ITS about it. +*Note SCPOS: K/3. + +File: ITSTTY, Node: E/7, Previous: E/6, Up: E, Next: E/8 + + 7. RELEVANT TTYOPT BITS. + +%TOERS says that the tty can erase selectively. If this bit is not +set, "^PL", and "^PE" cannot be used. "^PX" and "^PK" will work +anyway, if %TOOVR is off, since then ITS knows it can use a space +to erase a single character. + +%TOMVU says that the tty can move its cursor up. If this bit is not +set, the tty is a printing terminal. Any attempt to erase will have no +effect. Horizontal and downward cursor motion will work but not upward +motion. For the sake of those programs that wish to know about +displays only to the extent of clearing the screen on them every so +often, "^PC" on a printing terminal comes out as a CRLF. + +%TOOVR says that the tty can overstrike characters successfully. The +effect of attempted overstriking on a terminal that can't handle it is +undefined, but on a datapoints what will happen is that only the last +character printed in a given position will be visible. Note that +outputting a space character will erase iff the terminal cannot +overstrike. Space should be output only when attempted overstriking is +generally desired - for example, when copying out of a file. If +erasing is specifically desired, "^PK" should be used (or "^PK^PF" = +move forward, erasing). If it is specifically desired not to erase, +"^PF" should be used. For "printing terminals" (or rather, terminals +on which no cursor motion characters except ASCII format effectors +are known) which lack %TOOVR, some cursor motion optimizations are not +done (for example, moving backward can be done only by backspacing, +since CR'ing and spacing forward might erase something useful). + +%TOMVB, if 0, means that the terminal can't backspace. This is true +only of teletypes. The system will simulate a backspace with a CR and +spaces, but, since that is so slow, backspace should be avoided on such +terminals. For that reason, it echoes as uparrow-H rather than as a +backspace. + +%TOSAI, if 1, says that control characters sent to the terminal will +be one-position graphic characters. The system will assume that +control characters output in image mode move the cursor one space +right. Also, altmode will be output as itself, rather than as a +dollarsign, even in ascii or echo mode (but the same is not true of +random control characters, which check %TSSAI). + +%TORAW, if 1, says that the various cursor motion characters (space, +tab, CR, LF, and BS) should be output to the terminal in the same +order the program gave them to the system, and in the same way, if +possible. This bit does not effect the padding done to CR, LF and TAB, +and will not prevent the system from simulating BS and TAB on tty's +that require such simulation. It will prevent the system from combining +several cursor motion characters to produce their effect more +efficiently; for example, CR's at the beginning of the line will +be ignored when %TORAW is 0, but when it is 1, they will cause CR to +be sent. Also, CR followed by spaces will always be output in that +manner even if backspacing would be faster. +This bit is normally set by the TELNET server except when the foreign +host is a tip, for the sake +of terminals that don't even always handle CR and LF correctly, but +do manage to handle the sequence CR-LF correctly, etc. + +File: ITSTTY, Node: E/8, Previous: E/7, Up: E, Next: E/9 + + 8. THROWING AWAY TYPEOUT. + +Many programs have interrupt characters for requesting that some +output be discarded. Normally they set flags telling the program not +to output anything. But on slow terminals the text already in the +output buffer will take an annoyingly long time to come out. For +that reason, the .RESET UUO and the RESET symbolic system call when +used on slow terminals (those for which %TPORS is 1) throw away the +text in the output buffer. On fast terminals that is not done. + +On all terminals, an output RESET restores the state of several bits +associated with the channel it is given on to normal. For example, +if the RESET took place after an interrupt out from the middle of +typing out a ^P-code, the RESET will cause the next output character +to be treated normally rather than as a display code. If the channel +had been hung in a **MORE** (*Note More: F/2/a.) it will be unhung. + +File: ITSTTY, Node: E/9, Previous: E/8, Up: E, Next: E/10 + + 9. WAITING FOR OUTPUT TO BE SENT TO THE TERMINAL. + +The symbolic system call FINISH may be used to wait until +the output buffer is empty, meaning that all characters +output by the program have actually been sent to the terminal. +The call's only argument is a tty output channel number: + .CALL [ SETZ + SIXBIT/FINISH/ + 401000,,CHTTYO] + .LOSE %LSFIL ;CALL FAILS?? +FINISH does not require ownership of the terminal; just output +permission (*Note Permit: B/3.). + +File: ITSTTY, Node: E/10, Previous: E/9, Up: E + + 10. .STATUS ON TTY OUTPUT CHANNELS. + +The information returned as the STATUS of an output channel resembles +that returned for an input channel except that bits 2.1 and 2.2 refer +to the output buffer rather than the input buffer, and bits 2.5, 2.8 +and 2.9 are not returned with any information. *Note In-status: D/7. + +File: ITSTTY, Node: F, Previous: E, Up: Top, Next: G + +F. **MORE** PROCESSING. + +This feature, when enabled, causes typeout to pause at certain +times (for example, at the bottom of the screen). +Certain events (such as reaching the last line on the screen) +trigger a **MORE** by setting the %TFEOP bit. Once that has +happened, the next attempt to output a character will cause +the program to be interrupted if it is clever, or cause the +system to wait for the user to order typeout to proceed if the +program is not clever. + +* Menu: + +* When: F/1 When **MORE** processing is triggered. +* How: F/2 How **MORE** processing operates. +* Programmed: F/3 Programmed invocation of **MORE** processing. +* Inhibition: F/4 Inhibition of **MORE** processing by input. + +File: ITSTTY, Node: F/1, Previous: F, Up: F, Next: F/2 + + 1. WHEN **MORE** PROCESSING IS TRIGGERED. + +The main occasion for triggering is .IOT'ing a LF that reaches +the last line of the screen. However, triggering has complicated +conditions: it will not happen if %TSMOR is set (%TSMOR's meaning +is "disable **MORE** processing, and this is how it functions); +in scroll mode triggering may not occur until the results of the +previous triggering have scrolled to the top of the screen, or a +home-up ("^PT" or "^PC") has happened. Note that printing terminals +usually have the screen height set to 200000,, , but wrap around +at line 118., so linefeed will never trigger. However, if the +screen height of a printing terminal is set to a small value, +**MORE** processing will take place. + +The user may trigger a **MORE** whenever he wishes to stop output +temporarily, by typing "^_B". %TSMOR does not +inhibit this, and scroll mode does not affect it. + +File: ITSTTY, Node: F/2, Previous: F/1, Up: F, Next: F/3 + + 2. HOW **MORE** PROCESSING OPERATES. + +Once one of the events described above has triggered it, **MORE** +processing will happen at the next attempt to .IOT a character +out to the terminal, except for output done with %TIMOR set to 1. +The details differ depending on how clever the program wishes to be. + +* Menu: + +* Stupid: F/2/a Stupid Programs. +* Smart: F/2/b Smart Programs. + +File: ITSTTY, Node: F/2/a, Previous: F/2, Up: F/2, Next: F/2/b + + a. Stupid Programs. + +If the tty channel being used for the output IOT that caused +**MORE** processing to occur, is not enabled to interrupt, +("**MORE**-interrupts are not enabled"), the +system assumes that the program is not clever, and tries to +handle the condition itself, telling the user that there is +more output, and waiting for his command to go ahead and print it. +Before handling the +.IOT'ed character, "**MORE**" is typed out, and the system reads a +character from the ordinary input stream. Output will resume, +starting with the character whose .IOT'ing was put off to do the +**MORE**, as soon as a character is available to be read. The input +character will not be thrown away, however, unless it is a space +(that is, if it is not a space, it will remain for the program to +read eventually). The system will supply a home-up so that output +will resume on the top line of the screen (which, on an Tektronix or +other display without selective erase, requires clearing the screen). + +While the system is waiting for an input character, it is actually +hung in the .IOT on the output channel. The terminal's variables are +not in abnormal state, except for that channel, and .RESET will return +the channel to normal. Thus, if the character typed in response to the +"**MORE**" is an interrupt character, the interrupt will happen +normally, and if it is dismissed without side-effect, the system will +continue waiting for a character to tell it to proceed. But if the +interrupt character tells the program to .RESET its output and await a +new command, that will do the right thing. Also, when a program is +"hung in a **MORE**", if the TTY is taken away by its superior and +then given back, its state will be unchanged, although the superior +will have had no trouble outputting to it (and might even have done +**MORE** processing). + +File: ITSTTY, Node: F/2/b, Previous: F/2/a, Up: F/2 + + b. Smart Programs. + +If the TTY output channel being used for output when **MORE** +processing becomes necessary is enabled for interrupts, the +system will signal an interrupt on it, and wipe its hands +of the matter. It is up to the program to pause, or whatever +is desired. It is a convention that smart programs that +provide the user with the ability to "flush" the rest of +the typeout should type "--MORE--" instead of "**MORE**". +One algorithm for handling **MORE** interrupts might be: +optionally set %TSNOE, type out "--MORE--", do a FLUSH to wait +for the "--MORE--" to come out, then read a character with +%TIPEK and %TIACT set. At this point, depending on the character, +the routine may gobble it by IOT'ing it again without %TIPEK. +Then, the routine may either flush by typing out a message such +as "flushed", clearing %TSNOE if it was set, re-enabling interrupts +and returning to a restart point, or it may proceed by clearing %TSNOE +and dismissing the interrupt. The purpose of using %TSNOE here +is to prevent the character typed at the "--MORE--" from echoing +in case it is to cause flushing but not be gobbled - the idea is +that it will echo LATER, when it is re-used as normal input. + +Programs which handle **MORE**-interrupts should not .IOT a control +character expecting it to be printed as an uparrow and a printing +character, because that will lose if a **MORE**-interrupt comes +between the two. + +File: ITSTTY, Node: F/3, Previous: F/2, Up: F, Next: F/4 + + 3. PROGRAMMED INVOCATION OF **MORE** PROCESSING. + +The two display commands "^PM" and "^PN" cause the channel they are +output on to enter the same state that a channel is in after the +system has typed "**MORE**" through it - namely, waiting for a +character to be read in before outputting any more. Those commands are +not affected by enabling of **MORE**-interrupts - that is, these +commands issued by even a clever program will enter the state the is +normally entered only for stupid programs. "^PN" is unusual in that +after the character has been read in, only a linefeed will be done, +instead of a home-up. + +File: ITSTTY, Node: F/4, Previous: F/3, Up: F + + 4. INHIBITION OF **MORE** PROCESSING BY INPUT. + +When the program waits for input, triggering of **MORE** processing +is inhibited for a while. This is so that a program which is giving +short replies to commands typed in will not do **MORE**'ing, which in +those circumstances would probably be a nuisance. The details of the +inhibition vary; in scroll mode triggering is inhibited until the +place the cursor was when the program waited for input scrolls to the +top of the screen; otherwise, inhibition takes place the very next +time the bottom is reached, but only if the waiting occurred in the +bottom 5 lines of the screen. In any case, if a home-up (or +clear-screen) intervenes, there is no inhibition. +It is not the typing of input or the reading of input that inhibits, +but the waiting for input, for the following reasons: if typing ahead +inhibited triggering, it would be impossible to type ahead to a +**MORE**; if reading typed-ahead input inhibited triggering, it would +be possible to lose by typing ahead commands that produced a +surprisingly large amount of input. + +File: ITSTTY, Node: G, Previous: F, Up: Top, Next: H + +G. PER-TTY/PER-JOB VARIABLES. + +Some of the variables which exist for a tty are intended to +describe the tty to the system or user; others are intended as +program-settable options. Of those, there are some that are +per-channel, and others that are not, either for historical +reasons, because they are too large to fit in the space that +each channel has for variables, or because they are used by +the input interrupt routine (at input interrupt time it is not +known which channel will be used to read the character). +These variables are maintained per-tty/per-job, which means +that for a tty in use as a device, there is one setting of the +variables, under the control of the job that has the tty open, +but for a tty that is a console, each job in the tree controlled +by the tty may set the variables independently. The values +actually in effect at any time are those set by the program which +has the tty at that time. The .ATTY and .DTTY UUO's that transfer +the tty from one job to another in the tree automatically save +the values set by the job that is losing control of the tty, and +restore the per-tty/per-job variables from the last settings made +by the job that is gaining control of the tty. When a job does +not have the tty, its settings may be examined with the .TTY, +.TTST, .TTS1 and .TTS2 .USET variables. + +The variables for a tty which is in use as a device are +initialized when the tty is opened. Each job's copies of the +variables for its console tty are initialized when the job is +created. That latter initialization simply copies the job's +superior's settings of the variables, except for the %TSMOR, +%TSROL and %TSSAI bits, which are copied from the appropriate +TTYOPT bits. The size of the echo area is always initialized to +0 for each new job or tty. Note that the first input tty open +and the first output tty open will, between them, re-initialize +all of TTYST1 and TTYST2. + +There exist symbolic system calls for reading and setting these +variables. As usual, the calls to read them may be done to any +tty, specified by number, while the calls to set them require a +channel, and thus may be done only to a tty under the control of +the job. Some of these variables are set by the first-time bits +in the open-mode for tty opens. + +* Menu: + +* Variables: G/1 The variables. +* Calls: G/2 Symbolic system calls. + +File: ITSTTY, Node: G/1, Previous: G, Up: G, Next: G/2 + + 1. THE VARIABLES. + +* Menu: + +* ST1&2: G/1/a The TTYST1 and TTYST2 variables. +* STS: G/1/b The TTYSTS variable. +* Size: G/1/c The Size of the Echo Area. + +File: ITSTTY, Node: G/1/a, Previous: G/1, Up: G/1, Next: G/1/b + + a. the TTYST1 and TTYST2 variables. + +These variables contain the information on which characters +should be echoed, and how; on which characters should activate +(cause an .IOT to unhang), and which should interrupt (all this +is used at input interrupt time). Also, they contain the +information on which characters are to be output in image mode. +A job that does not possess its console has its TTYST1 and TTYST2 +settings for the console kept in the .USET variables .TTS1 and .TTS2. + +These words are divided into 6-bit bytes, one for each character +group. All of the options for the characters in any group are +located in the byte for that group, as follows: +%TGINT==1 ;1 => characters in this group should interrupt. + ;*Note Int: D/4. +%TGACT==2 ;1 => characters in this group should activate. + ;*Note Act: D/3. +%TGSPC==4 ;1 => perform special hack. The meaning of this bit + ;depends on which character-group is in question. + ;Right now it is defined only for group 1 (letters) + ;and means "convert lower case to upper case). +%TGIMG==10 ;1 => output the characters of this group in image mode. + ;*Note Image: E/2. for the consequences of setting this bit. + ;It is likely that this feature will be flushed soon, + ;since it cannot be made to work right with the $$^P + ;feature that allows several jobs to type out at once +%TGPIE==20 ;1 => echo these characters at interrupt level. + ;*Note Echo: D/1. +%TGMPE==40 ;1 => echo them at main program level + ;(that is, when they are .IOT'ed in). *Note Echo: D/1. + +The characters are divided into groups based on the ascii code. +TV characters are assigned to groups by converting them to ascii +(thus, the meta bit is ignored, and the control bit is ignored +except with letters, which are converted into ascii control characters). +The groups of characters are: +Group 0: "^@" - "^F", "^K", "^L", "^N" - "^R", "^T" - "^Z", "^\" - "^^". + (in otherwords, random control characters). +Group 1: Letters (both upper and lower case). +Group 2: Digits. +Group 3: !"#$%&',.:;?@\`|~ (random graphics). +Group 4: *+-/=^_ (operators) +Group 5: <>[](){} (brackets). +Group 6: "^G" "^S" (most commonly used interrupt chars). +Group 7: LF, TAB. +Group 10: Altmode. +Group 11: CR. +Group 12: Rubout. +Group 13: Space and BS. + +File: ITSTTY, Node: G/1/b, Previous: G/1/a, Up: G/1, Next: G/1/c + + b. The TTYSTS variable. + +This variable contains many historical relics, as well as information +used to control interrupt level actions, and to signal the user program. +The prefix "%TS" is used for bits in the TTYSTS variable. When a job +does not possess its console, its TTYSTS setting for the console may +be found in its .TTST variable. + +%TSFRE==400000 ;4.9 1 => tty is free (not in use as device or console) +%TSCLE==200000 ;4.8 1 => "^L" output in echo mode should always come + ;out as uparrow-L. (Normally, "^L" echoes as a clear + ;screen on displays). +%TSHDX==100000 ;4.7 same as %TOHDX. This is vestigial. +%TSFCO==040000 ;4.6 1 => use the full 12-bit TV character set for + ;output and echoing. The control bit outputs as "^A" + ;or "alpha", the meta bit outputs as "^B" or "beta", and + ;the super bit outputs as "^F" or "epsilon". + ;Also, the top bit is used to distinguish ASCII control + ;characters from Sail graphic characters. The main value + ;of this feature is for its effect on echoing. +%TSALT==020000 ;4.5 1 => don't standardize altmodes. +%TSROL==010000 ;4.4 1 => scroll mode is in effect. + ;Complemented by "^_"""". +%TSSAI==004000 ;4.3 1 => echo and ascii output should use SAIL chars. + ;Complemented by "^_^". +%TSACT==002000 ;4.2 1 => next input IOT shouldn't wait for an + ;activation character to have been typed in. +%TSNEA==001000 ;4.1 => Don't echo in echo area; echo in M.P. area. +%TSINT==000400 ;3.9 1 => next input character should interrupt even + ;if its %TGINT bit doesn't say it should. +%TSMOR==000200 ;3.8 1 => inhibit **MORE** processing. + ;Complemented by "^_M". +%TSATY==000100 ;3.7 this bit is set whenever an .ATTY executed by a + ;superior gives the tty to the job. It is what TECO + ;uses to know that it should clear the screen before + ;the next display. + ;3.6-3.5 unused. +%TSNOE==000010 ;3.4 1 => defer echoing (*Note Echo: D/1.). +%TSLCZ==000004 ;3.3 1 => the last character typed in was "^Z". + ;If this bit is 1, .ATTY fails (*Note ATTY: B/2.). +%TSSII==000002 ;3.2 1 => superimage input. The special treatment of + ;"^Z" and "^_" is suppressed. +%TSCNS==000001 ;3.1 1 => the tty is a console (not a device). + +RH: ;the user-index of the job that owns the tty, or -1 + ;if the tty is free. The actual system variable has + ;the user-index in its internal form but TTYGET + ;returns it in external form (=internal form + ;divided by LUBLK). + + +File: ITSTTY, Node: G/1/c, Previous: G/1/b, Up: G/1 + + c. The Size of the Echo Area. + +The vertical size of the echo area is a per-tty/per-job +variable. *Note Echo area: E/4. + +File: ITSTTY, Node: G/2, Previous: G/1, Up: G + + 2. SYMBOLIC SYSTEM CALLS. + +These system calls all take, as the first argument, a tty-specifier +which tells the system which tty's variables are to be read or written. +The tty specifier should either be a channel number, on which a tty +or pseudoteletype should be open (in the latter case, the variables +of the tty which is the alter ego of the sty will be accessed), or be +400000 plus the number of the desired tty (this option is allowed only +for calls that do not alter the variables. It enables a program to +read the variables of a tty which is in use by a different job). + +An invalid tty specifier will cause the call to fail with an +open-failure code such as "NO SUCH DEVICE" or "BAD CHANNEL NUMBER". + +If the job specifies its console, but it doesn't possess the console +at the time, the call will wait until the tty is given back by the +superiors. + +* Menu: + +* Get: G/2/a TTYGET - read TTYST1, TTYST2, TTYSTS. +* Set: G/2/b TTYSET - set TTYST1, TTYST2, TTYSTS. +* SCML: G/2/c SCML - Set Number of Command Lines. + +File: ITSTTY, Node: G/2/a, Previous: G/2, Up: G/2, Next: G/2/b + + a. TTYGET - read TTYST1, TTYST2, TTYSTS. + +The TTYGET symbolic system call takes one argument, which specifies +the tty whose variables are to be read, and returns up to five +values, which are the TTYST1, TTYST2, TTYSTS, TTYTYP and TCTYP +variables of that tty, as set by the job which has control of that +tty at the time the system call is executed. The argument should be +as described above. + +Actually, the right half of the third value returned is the user +index in its external form, rather than its system-internal form, +which is what the right half of the TTYSTS variable in the system +really holds (The internal form is the external form times LUBLK, +a symbol defined in the timesharing system. The external form is +more useful to user programs - all interfaces with the system +expect the external form, .USET of .UIND returns it, etc.). + +As an example, suppose TTYNUM contains the number of a tty whose +variables are to be read. The following code will read the TTYST1, +TTYST2 and TTYSTS respectively into ST1, ST2, and STS: + MOVE A,TTYNUM + .CALL [ SETZ + 'TTYGET + 1000,,400000(A) ;Immediate arg = 400000+ + 2000,,ST1 ;1st value returned in ST1. + 2000,,ST2 + 402000,,STS] ;Sign bit marks end of call. + JRST TRANSL ;User must have translated TTY to a file. + ... ;ST1, ST2, STS now set up. + +Note that the TTYGET call can fail quite legitimately, if the +user translates device TTY: to a file of commands for the program. +Therefore, you should not naively put a .VALUE or a .LOSE after +a TTYGET, but instead write code to assume that a command file +is being used and do the "appropriate" thing. + +File: ITSTTY, Node: G/2/b, Previous: G/2/a, Up: G/2, Next: G/2/c + + b. TTYSET - set TTYST1, TTYST2, TTYSTS. + +The TTYSET symbolic system call takes either three or four +arguments. The first specifies the tty (TTYSET, like the other +calls that alter tty variables, do not allow a tty to be specified +by number). The second and third arguments are used to set the +TTYST1 and TTYST2 variables. The fourth, if present, sets the +TTYSTS variable (if there are only three arguments, the TTYSTS +variables is not changed). The bits %TSFRE, %TSHDX, %TSLCZ and +%TSCNS, as well as the right half of TTYSTS, cannot be changed. +If the %TSINT (the next character should interrupt whatever it is) +bit is turned on, and there is a character in the input buffer +already following the last one that has been .ITYIC'ed, that +character will be made into an interrupt character if it wasn't +already one. +For example, if the desired values of the variables are contained +in ST1, ST1+1, and STS, the variables may be set as follows +(This isn't the simplest way; it is meant to illustrate the +flexibility of the symbolic system call): + MOVEI A,ST1 + .CALL [ SETZ + 'TTYSET + 1000,,TYIC ;Immediate arg = tty channel. + (A) ;Set TTYST1 from ST1 + 1(A) ;Set TTYST2 from ST1+1 + 400000,,STS] ;Set TTYSTS from STS + JRST TRANSL ;User must have translated TTY to a file. + ... ;Variables now set. + +Most of the time, when TTYSET is used, only a few of the bits +are intended to be changed. Rather than giving the TTYSET +constant arguments, which is tantamount to making baseless +assumptions about the meanings of the other bits, you should +read in the current values with a TTYGET, change only the bits +you want to change, and then write out the result. + + +File: ITSTTY, Node: G/2/c, Previous: G/2/b, Up: G/2 + + c. SCML - Set Number of Command Lines. + +SCML takes two arguments: a tty channel number, and the desired +size of the echo area. For example, to have 4 echo lines: + .CALL [ SETZ + SIXBIT/SCML/ ;Note 'SCML is right-justified, and won't do. + 1000,,TYIC ;Immediate arg = tty channel + 401000,,4] ;Immediate arg = <# command lines>. + JRST TRANSL ;User must have translated TTY to a file. + ... ;Echo area now set up. + +Before attempting to do a SCML, you should verify that the +terminal being used is a display and not a printing terminal. +You should also check for the possibility that TTY was translated +to a file. + +File: ITSTTY, Node: H, Previous: G, Up: Top, Next: I + +H. PERMANENT AND SEMIPERMANENT TTY INFORMATION. + +The permanent information on a tty describes the characteristics +of the particular type of terminal in use and the line it is connected +to. The semipermanent information consists of several user-settable +bits controlling system options; they are all reinitialized whenever +a free tty begins to be used. Also, when a TV or a tty on a dialup line +is freed, the permanent information is reinitialized. When an STY is +opened after being free its alter ego is similarly reinitialized. + +* Menu: + +* Variables: H/1 The variables. +* Calls: H/2 System calls. + +File: ITSTTY, Node: H/1, Previous: H, Up: H, Next: H/2 + + 1. THE VARIABLES. + +* Menu: + +* Size: H/1/a The Screen Size. +* TTYOPT: H/1/b The TTYOPT variable. +* TCTYP: H/1/c The TCTYP variable. +* TTYTYP: H/1/d The TTYTYP variable. +* TTYCOM: H/1/e The TTYCOM Variable. +* TTYROL: H/1/f The TTYROL variable or "Scroll Count". +* TTYSMT: H/1/g The TTYSMT variable. Says what sort of + CPU the terminal is, and to what extent + it supports graphics. + +File: ITSTTY, Node: H/1/a, Previous: H/1, Up: H/1, Next: H/1/b + + a. The Screen Size. + +The horizontal screen size is the number of character positions on a +line, not including the column normally used for "!"'s produced by +line continuation. The vertical screen size is the number of lines +on the screen. For printing ttys on which **MORE** processing should +never be done, it is 200000,, . If the screen height on a printing +tty is set to a small value (less than 118.), **MORE** processing will +be done if enabled (this is for the sake of terminals which are +physically displays, but which are being operated as printing terminals +because ITS does not know how to send display operations to them). + +Programs which make their output depend on the screen size will be +totally screwed when the user detaches and reattaches on a different +terminal, unless they are specially hacked to recover. Such programs +should either enable the %PIATY interrupt, or test %TSATY in the +TTYSTS variable regularly, since if the user switches terminal type +for any reason those conditions will certainly be signaled. When the +interrupt happens or %TSATY is seen, the program should read the +screen size and TTYOPT once again from the system and take appropriate +actions if they have changed. + +In the system, the horizontal size plus 1 is stored in the TCMXH +variable, and the vertical size is stored in the TCMXV variable. + +File: ITSTTY, Node: H/1/b, Previous: H/1/a, Up: H/1, Next: H/1/c + + b. The TTYOPT variable. + +This variable holds the rest of the information on the particular +tty in use: what capabilities it has, and what special treatment it +needs. Also it holds several user options: %TOMOR, %TOROL, %TOSA1 +and %TOCLC. Programs that base their actions on the value of the +value of the TTYOPT variable should provide for the possibility that +the user changes his terminal type. They should either test %TSATY in +the TTYSTS variable frequently, or enable %PIATY interrupts. When the +chosen condition is detected, the program should the re-examine the +value of TTYOPT. + +"%TO" signifies a bit in the left half of TTYOPT. "%TP" signifies a +bit in the right half; "$TP", a byte pointer to a field. + +%TOALT==200000 ;4.8 => Standardize altmodes. +%TOCLC==100000 ;4.7 => Convert lower case to upper on input. +%TOERS==40000 ;4.6 => This tty can erase selectively +%TOHDX==20000 ;4.5 => This tty is half-duplex. +%TOMVB==10000 ;4.4 => This tty can handle backspaces directly. +%TOSAI==4000 ;4.3 => This tty can handle the SAIL character + ;set, if given control characters in image mode. +%TOSA1==2000 ;4.2 => use the SAIL character set for echo and + ;ascii mode output (actually just init %TSSAI of + ;new jobs). +%TOOVR==1000 ;4.1 => This tty can overprint successfully. +%TOMVU==400 ;3.9 => This tty can move its cursor upward + ;(that is, it is a display). +%TOMOR==200 ;3.8 => do **MORE** processing on this tty + ;(actually just used to init %TSMOR for new jobs). +%TOROL==100 ;3.7 similarly, used to init %TSROL for new jobs. +%TORAW==40 ;3.6 => don't optimize cursor motion (*Note Out: E/7.). +%TOLWR==20 ;3.5 => this tty has lower case keyboard. + ;(Doesn't affect system actions - exists to + ;tell user programs what to do). +%TOFCI==10 ;3.4 => this tty's keyboard has full TV character set. +%TOIML==4 ;3.3 => this tty acts like an imlac +%TOLID==2 ;3.2 => this tty can insert/delete lines. +%TOCID==1 ;3.1 => thus tty can insert/delete characters. +$TPPLF==170300 ;3-bit field saying how to pad LF. + ;0 - don't. 1 - memowreck, 2741 (2 pad chars.). 2 - more. + ;If a terminet, tells the baud rate. +$TPPCR==140300 ;3-bit field saying how to pad CR. + ;7 - unused. 6 - memowreck. 5 - 2741. 4 - execuport. + ;0 - don't. 1 - normal. 2 - double. + ;On datapoints, number of padding characters desired + ;before each string of cursor motion commands. +$TPPTB==110300 ;3 bit field saying how much padding needed after tab. + ;0 => tabs not allowed; else 1 +<# padding chars needed> + ;On displays: 0 don't use tabs, 1 use tabs, + ;2 use VT52-style absolute positioning. +%TPMTA==400 ;1.9 => treat bit 1.8 of input characters as the meta bit. + ;This is for terminals such as Telerays which have Edit keys. +%TPPRN==200 ;1.8 => interchange ( with [, and ) with ], on input. +%TPTEL==100 ;1.7 => Treat CRLF input as CR for TELNET protocol. +%TPCBS==40 ;1.6 => intelligent terminal protocol in use. + ; *Note ITP: J. +%TP11T==20 ;1.5 => PDP-11 TV tty. Reflects %TY11T. + ;not settable by user. +%TPORS==10 ;1.4 => output reset on this tty should really do something. +%TPRSC==4 ;1.3 => this terminal implements %TDRSU and %TDRSD. + ;These are commands usable in superimage output + ;which perform region scrolling. *Note RSC: K/1. + +File: ITSTTY, Node: H/1/c, Previous: H/1/b, Up: H/1, Next: H/1/d + + c. The TCTYP variable. + +It tells the system what type of display codes the terminal actually +needs. The system takes the display commands that are output by +programs and converts them into whatever will accomplish the desired +result on the particular type of tty in use, according to the setting +of the TCTYP variable. User programs should try to avoid looking at +this variable; use TTYOPT instead. + +The possible values are: + +%TNPRT==0 ;printing terminal. +%TNDP==1 ;good datapoint. +%TNODP==2 ;"bad" datapoint or "loser". +%TNIML==3 ;IMLAC. +%TNTEK==4 ;Tektronix 4000 series. +%TNTV==5 ;PDP-11 TV. +%TNMEM==6 ;Memowreck. +%TNSFW==7 ;"software" terminal that expects internal ITS + ;display commands ("SUPDUP" codes). + ; *Note SUPDUP: I/3/e. +%TNTRM==10 ;Terminet. +%TNESC==11 ;Display using ASCII standard display codes. +%TNDTM==12 ;A Datamedia 2500. +%TNRAY==13 ;Teleray 1061 +%TNHDS==14 ;Concept-100 +%TNH19==15 ;H19 +%TNAAA==16 ;Ann Arbor Ambassador + +File: ITSTTY, Node: H/1/d, Previous: H/1/c, Up: H/1, Next: H/1/e + + d. The TTYTYP variable. + +This variable contains the information on the line the tty is +connected to, as opposed to the tty itself. Most of the fields in +the TTYTYP table cannot be set with a system call. The exceptions +are the input and output speed codes, which can be as the +ISPEED and OSPEED variables with TTYVAR. + +"%TT" signifies a bit in the left half of TTYTYP; "$TT", a byte +pointer to a field. "%TY" signifies a bit in the right half. + +%TTLCL==400000 ;BIT 4.9 ONE => LOCAL TTY +%TT340==200000 ;BIT 4.8 ONE => CONSOLE NEXT TO 340 OR A 340 SLAVE +%TT3HP==100000 ;BIT 4.7 HIGH PRIORITY ON 340 +%TTPAR==004000 ;BIT 4.3 TTY needs to have parity sent. +%TTDDI==002000 ;BIT 4.2 DONT DING ON EXCESS INPUT +%TTIBM==001000 ;BIT 4.1 DATEL LINE +$TTISP==260400 ;3.8-3.5 INPUT SPEED CODE +$TTOSP==220400 ;3.4-3.1 OUTPUT SPEED CODE +%TYDPK==400000 ;BIT 2.9 => this tty is on a datapoint controller line. +%TYSTY==200000 ;BIT 2.8 => this tty is the alter ego of an STY. +%TYNVA==100000 ;BIT 2.7 => this tty is a NOVA tty (They no longer exist) +%TYMTY==040000 ;BIT 2.6 => this tty is on a Morton controller line. +%TYDIL==020000 ;BIT 2.5 => this tty is on a dial-up line. +%TY11T==010000 ;BIT 2.4 => this tty is a PDP-11 TV. +%TYDL== 004000 ;BIT 2.3 => this tty is on a DC76 line. +%TYOTY==002000 ;BIT 2.2 => this tty is a KA-10 console tty. +%TYETY==001000 ;BIT 2.1 => this tty is a DTE-20 tty. +%TYNTY==000400 ;BIT 1.9 => this tty is a TK-10 tty. +%TYMDM==000200 ;BIT 1.8 => this tty is on a dial-up line with modem control. +%TYKST==000100 ;BIT 1.7 => this tty is a KS-10 console tty. +%TYDZT==000040 ;BIT 1.6 => this tty is a DZ-11 tty on a KS-10. +%TYRLM==000020 ;BIT 1.5 => this tty is a connected to the ROLM data switch. + +The meanings of the possible 4-bit speed codes are: + 0 = unknown 6 = 1800 baud 13 = 40K baud + 1 = 600 baud 7 = 2400 baud 14 = 50K baud + 2 = 110 baud 10 = 4800 baud 15 = 80K baud + 3 = 150 baud 11 = 9600 baud 16 unused + 4 = 300 baud 12 = 25K baud 17 unused + 5 = 1200 baud + +File: ITSTTY, Node: H/1/e, Previous: H/1/d, Up: H/1, Next: H/1/f + + e. The TTYCOM Variable. + +This variable contains the com link status of the tty, +some user options associated with com links, and internal +system flags. The following bits may be set with a CNSSET: +%TCICO, %TCOCO, %TCRFS, %TCQRY. + + ;4.9 => tty in communicate mode +%TCLFT==200000 ;4.8 => Local Feed Through (set if my program receiving his chars) +%TCRFT==100000 ;4.7 => Remote Feed Through (set if his program receiving my chars) + ;All characters typed on ttys with %TCRFT are given to all ttys + ;with %TCLFT. ^_S and ^_E control these bits. +%TCICO==40000 ;4.6 => Input Communicate Override (allows program to read and + ;type out, even if the tty is in com mode. +%TCOCO==20000 ;4.5 => Output Communicate Override (allows program to type out + ;even if the tty is in com mode. + ;4.4-4.3 => message receipt switch + ;00 => accept +%TCRFS==10000 ;10 => refuse +%TCQRY==4000 ;01 => interrogate +%TCMTR==2000 ;4.2 => tty's motor is off & must be turned + ;on before any other output is done + ;(only terminets have their motors shut off by ITS). +%TCECH==1000 ;4.1 => the last output to this tty was PI echoing + ;(used to prevent output RESET from throwing away echo). +%TCDET==200 ;3.8 console's tree detached by top level interrupt. + ;Set by NDETAC as signal to SYSCFM (console-free-msg typer) +%TCDNG==100 ;3.7 => type bell on this tty (because input buffer full). +%TCCBK==40 ;3.6 => reading args for a ^_K on this tty. +%TCCBS==20 ;3.5 => reading args for a ^_S on this tty. +%TCFPD==10 ;3.4 => First part of an output code sequence is done. +%TCTPN==4 ;3.3 type ^_N on leaving com mode (unless user explicitly types ^_N) +%TCPAD==2 ;3.2 0 => padding necessary on datapoint. +%TCHNG==1 ;3.1 line seems not to be interrupting for output, + ;so don't try to wait for output to get out. + +The right half is -1 for a tty that is not in a com link. +For ttys in com links, the RH's are the links in a cirular +list of all the ttys in the com loop. Each RH is the number +of the next tty in the loop. The order of the ttys in the +circular list has no significance. + +File: ITSTTY, Node: H/1/f, Previous: H/1/e, Up: H/1, Next: H/1/g + + f. The TTYROL variable or "Scroll Count". + +The TTYROL variable contains the number of lines that the screen +shifts up when, in scroll mode, an attempt is made to type past the +bottom of the screen. On most terminals, this is 1. On terminals that +can't scroll, it should be 0. On printing terminals (and inferior +displays that ITS thinks are printing terminals) it should be 1. + +File: ITSTTY, Node: H/1/g, Previous: H/1/f, Up: H/1 + + g. The TTYSMT or "SMARTS" variable. + +The TTYSMT variable is used to describe smart terminals. +It contains information on three things: + + What sort of CPU the terminal has (in case you want to load + a program into it), and + + To what extent (if at all) the terminal supports the ITS + local-editing and line-saving protocols, and + + To what extent (if at all) the terminal supports the ITS + terminal-independent graphics protocol. + *Note Graphics: (SYSDOC;GRPHCS)*. + +%TQ signifies a bit or field in the left half of TTYSMT, and %TR +signifies a bit or field in the right half. + +%TQMCH==700000 ;4.7-4.9 CPU type. 0 => unknown or uninteresting. + ;1 => PDP11. 2 => IMLAC PDS4. 3 => IMLAC PDS1. + +;These bits are for local-editing and line-saving (See SUPDUP doc) +%TRLED==100000 ;2.7 Terminal supports the local-editing protocol. +%TRLSV==034000 ;2.3-2.5 nonzero means terminal can save about 4**n lines. + +;These bits record what timezone the terminal is physically in. +%TRTIM==003700 ;2.2-1.7 signed offset from GMT minus 20. A value of zero + ; means don't know, don't care, or user program hasn't + ; implemented it yet. + +;The remainder of TTYSMT pertains to the graphics protocol. +;If %TQGRF is 0, it should all be 0. +%TQGRF==1 ;3.1 Terminal understands the graphics protocol. + ;the old name for this was %TQGPH +%TQHGT==76000 ;4.2-4.6 Character height in dots. +%TQWID==1700 ;3.7-4.1 Character width in dots. + +;The remaining bits and fields in TTYSMT indicate which optional +;features of the graphics protocol are supported. +%TQSET==2 ;3.2 Terminal implements multiple sets. +%TQREC==4 ;3.3 Terminal implements the rectangle commands. +%TQXOR==10 ;3.4 Terminal implements XOR mode. +%TQBNK==20 ;3.5 Terminal implements blinking. +%TQVIR==40 ;3.6 Terminal implements virtual coordinates. + +%TRGIN==400000 ;2.9 Terminal provides graphic input. +%TRGHC==200000 ;2.8 Terminal provides has graphic hardcopy. +%TRSCN==040000 ;2.6 Terminal implements scan-line output. + +File: ITSTTY, Node: H/2, Previous: H/1, Up: H + + 2. SYSTEM CALLS. + +* Menu: + +* RSSIZE: H/2/a RSSIZE. +* CNSGET: H/2/b CNSGET. +* CNSSET: H/2/c CNSSET. +* TTYVAR: H/2/d TTYVAR. + +File: ITSTTY, Node: H/2/a, Previous: H/2, Up: H/2, Next: H/2/b + + a. RSSIZE. + +The symbolic system call RSSIZE returns the horizontal and +vertical screen size of a tty. It takes one argument, like +the argument to TTYGET, and returns two values: the vertical +size and the horizontal size. + +File: ITSTTY, Node: H/2/b, Previous: H/2/a, Up: H/2, Next: H/2/c + + b. CNSGET. + +This symbolic system call takes one argument specifying the tty +(like TTYGET's argument) and returns seven values: +the vertical screen size, +the horizontal screen size, +the TCTYP variable, +the TTYCOM variable, +the TTYOPT variable, +the TTYTYP variable, +the TTYSMT variable. + +Note that the CNSGET call can fail quite legitimately, if the +user translates device TTY: to a file of commands for the program. +Therefore, you should not naively put a .VALUE or a .LOSE after +a CNSGET, but instead write code to assume that a command file +is being used and do the "appropriate" thing. + +File: ITSTTY, Node: H/2/c, Previous: H/2/b, Up: H/2, Next: H/2/d + + c. CNSSET. + +This symbolic system call is used to set the permanent and +semipermanent variables. It takes six arguments. The first is +a tty channel; the next five are the new values of +the vertical screen size, +the horizontal screen size, +the TCTYP variable, +the TTYCOM variable, +the TTYOPT variable. +If the second, third or fourth argument is negative, the +corresponding variable will not be altered. Fewer than six +arguments may be given, in which case variables corresponding +to arguments not given will not be changed. The system will +make sure that the variables are not given inconsistent values, +and will not allow some bits in TTYCOM to be changed. + +You should always make sure that a CNSSET does not change bits +or variables that you do not specifically want to change. Do +this by 1) specifying -1's for the screen sizes and TCTYP if +you are not changing them, or 2) reading in the old setting s +with a CNSGET, altering specific bits or variables, and then +writing the altered settings out. + +File: ITSTTY, Node: H/2/d, Previous: H/2/c, Up: H/2 + + d. TTYVAR. + +The TTYVAR symbolic system call allows you to read and/or write +any of the permanent or semipermanent variables. See the entry +for TTYVAR in the ITS .CALLS file for information on the several +ways of using it. + +Variables may be specified by sixbit names and read, written, or +modified (increased, decreased, bits set, cleared, or complemented). +Of course, some fields of some variables may not be changed; attempts +to change them will be ignored. The variable names now allowed are +HEIGHT, IDLTIM, ISPEED, OSPEED, SMARTS, TCTYP, TTYCOM, TTYOPT, TTYROL, +TTYSMT, TTYTYP, and WIDTH. Many of them have been described under +semipermenent variables. Here are the rest: + + ISPEED and OSPEED are the input and output speeds of the terminal. +They refer to the input and output speed codes stored in the TTYTYP +variable. However, they are not speed codes; they are the speeds, +in bauds. Also, you are allowed to set the ISPEED and OSPEED +variables, while you are not allowed to set the whole TTYTYP variable. + + IDLTIM (not at all permanent) is the length of time since the last +input character was typed on the tty, in 30'ths of a second. + + Note that the TTYVAR call can fail quite legitimately, if the +user translates device TTY: to a file of commands for the program. +Therefore, you should not naively put a .VALUE or a .LOSE after +a TTYVAR, but instead write code to assume that a command file +is being used and do the "appropriate" thing. + +File: ITSTTY, Node: I, Previous: H, Up: Top, Next: J + +I. PSEUDO-TELETYPES (STY'S). + +Pseudo-teletypes are a facility that allows programs to do the +things that users do with terminals - type in on them, and observe +what is typed out on them. A sty is a device which is analogous to +a user's physical terminal. Outputting to a sty device is like +typing on a physical terminal's keyboard. Reading from a sty is +analogous to a physical terminal's gobbling down of output. Thus, +outputting a "^Z" to a sty just opened would load a DDT. DDT's +initial typeout "xx ITS.nnn. DDT.nnn." etc. would then be available +as input from the sty. + +The system contains many tty devices. A physical terminal that is +online is the end of a pipeline whose other end is one of the tty +devices. A sty device is also one end of a pipeline whose other end +is one of the tty devices. Each sty device has a particular tty +device permanently associated with it; the sty's are distinguished +by number, as are tty's, and the number of the tty associated with +a sty equals the sty number plus the value of the symbol NFSTTY. + +Since the most common use of stys is for network TELNET servers, +a special feature called "direct connection" exists for tying +a sty to a pair of network channels, so that all input from the +net is fed to the sty and all input from the sty is fed to the net, +without having to run the actual server program. + +* Menu: + +* Opening: I/1 Opening STYs. +* Output: I/2 Output to STYs. +* Input: I/3 Input from STYs. +* Closing: I/4 Closing STYs. +* Controlling: I/5 Controlling the tty associated with a STY. +* Direct: I/6 Direct connections to network channels: STYNET. +* STYGET: I/7 STYGET. + +File: ITSTTY, Node: I/1, Previous: I, Up: I, Next: I/2 + + 1. OPENING STY'S. + +There are two ways to open a sty: opening the STY device, and +opening a Snm device, where nm is the number of the desired sty. +Opening STY is a convenient way of obtaining any sty that is free. +If STY is not open, opening it causes the system to find a sty +which is free and whose associated tty is also free, and open it. +Opening STY when STY is already open on another channel will use the +same sty as before. Thus, a program that wishes to use one sty can +avoid the trouble of finding a free sty and remembering its number +by using device STY throughout. For more complicated applications, +any sty may be opened by number (Open device S00 to get sty number +0). However, a sty that is open in another job may not be opened. + +When a sty is opened that was not already open, the tty on the +other end of the pipeline is put into a standard state - the one +that would result from doing :TCTYP PRINTING on that tty. Also, an +input RESET and an output RESET are done, clearing all buffers. + +Sty opens recognize two special mode bits. Bit 3.3 ("image mode") +on an input open is copied into the associated tty's %TOHDX bit, +so if the sty is opened for input in image mode, +characters output to the sty will not be read back in as echo. +Bit 3.4, if 1 in either an input or an output open, causes the +sty to operate in "don't hang" mode in that direction. +*Note NH Out: I/2/a. *Note NH In: I/3/a. +Bit 3.5, on input, says that %TDORS should +be provided when tty output is reset, even if the tty is +not a software tty (*Note TDORS: K/2.). This makes +it possible for the sty handling job to tell when tty output +has been thrown away. + +These modes are not remembered separately for each channel; +each open sets the modes for all channels in that direction. + +File: ITSTTY, Node: I/2, Previous: I/1, Up: I, Next: I/3 + + 2. OUTPUT TO STY'S. + +IOT'ing a character to a sty output channel is like typing the +character into the tty on the other end of the pipeline. The +characters "^Z" and "^_" are special just as they are on physical +terminals. Characters sent to a sty may be echoed, just as +characters typed on a physical terminal may be (of course, the tty +may be made half-duplex, in which case there will be no echoing. +When the sty is opened for input, it is there is an option to make +the tty half-duplex). The characters output need not be ascii - +any character in the 12-bit TV character set may be output to +the tty, which will treat it the way a TV would. + +* Menu: + +* Empty: I/2/a What happens when the buffer is empty. +* Interrupts: I/2/b Interrupts. +* Reset: I/2/c RESET on sty output channels. +* Status: I/2/d STATUS on sty output channels. + +File: ITSTTY, Node: I/2/a, Previous: I/2, Up: I/2, Next: I/2/b + + a. What happens when the buffer is empty. + +An attempt to output to a sty channel open in normal output +mode when the tty input buffer has no room in it will wait until +there is room. This is unlike the treatment of physical +terminals, which unfortunately cannot be told to wait. + +If the channel is open in "don't hang" mode, then the character +will be thrown away, and "^G" echoed, just as on a physical +terminal. This mode is good for programs that simulate special +types of terminals for the user. + +File: ITSTTY, Node: I/2/b, Previous: I/2/a, Up: I/2, Next: I/2/c + + b. Interrupts. + +If a sty output channel is enabled to interrupt, an interrupt will +happen whenever a job attempts to read from the associated tty and +its input buffer (the sty's output buffer!) is empty. + +File: ITSTTY, Node: I/2/c, Previous: I/2/b, Up: I/2, Next: I/2/d + + c. RESET on sty output channels. + +A .RESET UUO or a RESET symbolic system call done on a sty output +channel is like a RESET on an input channel; of the associated tty; +all characters waiting in the input buffer of the tty are thrown +away. If they have not echoed already they will not; if they have +not interrupted already they will not. + +File: ITSTTY, Node: I/2/d, Previous: I/2/c, Up: I/2 + + d. STATUS on sty output channels. + +A .STATUS UUO or STATUS symbolic system call done on a sty output +channel will return the device code 25, and will set bit 2.2 or bit +2.1 if the tty's input buffer is empty or almost full, respectively. + +File: ITSTTY, Node: I/3, Previous: I/2, Up: I, Next: I/4 + + 3. INPUT FROM STY'S. + +Characters read in by a sty are like characters received by a +physical terminal's printer. The sty input effectively comes out of +the tty output buffer. The sty will read the exact same sequence of +characters that a physical terminal would receive with the same +settings of the various tty variables. This includes padding and +cursor motion characters according to the setting of the tty's +TTYOPT variable, but the initial setting given to the tty when the +sty is first opened causes padding not to be done. + +* Menu: + +* Empty: I/3/a What happens when the buffer is empty. +* Interrupts: I/3/b Interrupts. +* Status: I/3/c .STATUS on sty input channels. +* Reset: I/3/d .RESET on sty input channels. + +File: ITSTTY, Node: I/3/a, Previous: I/3, Up: I/3, Next: I/3/b + + a. What happens when the buffer is empty. + +There are two modes of input from sty's, distinguished by what +happens when the tty has no characters to output. The normal mode +waits for output from the tty to be available. The other mode, +"don't hang" mode, returns immediately when there is no input, +giving an indication of that fact. "Don't hang" unit mode IOT's +return -1 instead of an input character. +SIOT's return with the pointer and count not completely advanced. +Block mode IOT's have a kludgerous scheme and should be avoided. +"Don't hang" mode is selected by opening an input +channel with the 20 bit in the open-mode set to 1. + +File: ITSTTY, Node: I/3/b, Previous: I/3/a, Up: I/3, Next: I/3/c + + b. Interrupts. + +A sty input channel may be enabled to interrupt. It will do so +whenever input (tty output) is available. In normal mode, it is +expected that the interrupt routine will read one character; if when +the interrupt is dismissed more are available another interrupt will +occur. In "don't hang" mode, the interrupt routine should continue +reading until it reads a -1, indicating that no more input is +available at the moment. + +File: ITSTTY, Node: I/3/c, Previous: I/3/b, Up: I/3, Next: I/3/d + + c. .STATUS on sty input channels. + +A .STATUS UUO or STATUS symbolic system call on a sty input channel +returns bit 2.1 as 1 iff the tty's output buffer is full, and 2.2 as +1 iff it is empty. + +File: ITSTTY, Node: I/3/d, Previous: I/3/c, Up: I/3 + + d. .RESET on sty input channels. + +A .RESET UUO or RESET symbolic system call on a sty input channel +is approximately the same as a .RESET on an output channelof the +associated tty - namely, it throws away what is in the tty's output +buffer. However, RESET on a tty output channel also initializes some +bits associated with that particular channel, while sty input reset +doesn't change the settings of those bits for any of the tty output +channels. Also, tty output reset may not actually discard the buffer +if the tty's %TPORS bit is 0, or if the buffer contains PI-echoed +characters, but sty input reset will always clear out the buffer +even in those circumstances. An input RESET is part of the process +of initializing a sty for use, performed when the sty is opened +after being free. + +File: ITSTTY, Node: I/4, Previous: I/3, Up: I, Next: I/5 + + 4. CLOSING STY'S. + +When a sty channel is closed, but the sty is still open on some +other channel, nothing special happens - if the channel were +reopened, nothing would have changed. In particular, nothing is done +to the state of the associated tty or to characters sitting in its +buffers. + +When a sty is closed on the only channel it is open on (this +happens when the only channel it is open on is reopened), if the +associated tty is in use as a tree-controlling console, the tree +will be logged out. If the tty is in use as a device its status will +not be changed. + +File: ITSTTY, Node: I/5, Previous: I/4, Up: I, Next: I/6 + + 5. CONTROLLING THE TTY ASSOCIATED WITH A STY. + +Any of the special symbolic system calls for tty's, except for +LISTEN, may be given a sty channel instead of a tty channel as its +first argument, in which case the function will be performed for the +tty associated with the specified sty. The calls that are most +useful in this mode are TTYGET, CNSGET and CNSSET. TTYGET returns +the TTYSTS variable, which tells whether the tty is in use (%TSFRE), +by what job (the R.H.), and whether as a console or as a device +(%TSCNS) (*Note TTYSTS: G/1/b. for a description of the TTYSTS variable and the +values of those two bits). CNSGET returns the information that ITS +uses in deciding exactly how to treat the tty. CNSSET sets that +information. Programs that use sty's will often want to do a CNSSET +to the sty as soon as it has been opened. For example, the 340D +program does a CNSSET to the sty it uses, setting it to be a +datapoint with a peculiar screen size. This causes ITS to send +datapoint cursor motion codes to the tty. The 340D program reads +them from the sty and simulates their effect in the display that it +maintains on the 340. The TTYCOM variable may be examined with a +CNSGET, and the com-mode status of the tty may be altered by +outputting the appropriate ^_ codes to the STY. + +Any symbolic system call that requires a job-spec as an argument may +be given a sty channel, which will signify whatever job has the +associated tty in its possession. + +File: ITSTTY, Node: I/6, Previous: I/5, Up: I, Next: I/7 + + 6. DIRECT CONNECTIONS TO NETWORK CHANNELS: STYNET. + +It is possible with this call to connect a sty to a pair +of network channels, one open for input, and one open for output. +When the direct connection is established, anything received by +the net input socket will be fed automatically as output to the +sty, and any type-out that the sty receives from its TTY will be +fed automatically to the net output channel. The transfer of +data is handled by the system at clock level, eliminating +the need for the program to wake up at each character. + +The STYNET call returns immediately, without actually +transferring any data. Once established, the direct connection will last until +broken explicitly by the user (with another STYNET), or until an escape condition +is detected by the system. Escape conditions include receipt +of a TELNET control character on the net input channel, and +either net channel's getting into an abnormal state (other +than %NSOPN, %NSINP, or %NSCLI) - in general, things which +the system expects that the user program will want to take +action on. When the system detects an escape condition it will +break the direct connection and notify the user program with +an interrupt on the net input channel. +While the connection lasts, interrupts on the net channels +due to arriving data are intercepted by the system, so +an interrupt implies that the connection has been broken. + +Only one input and one output net channel can be connected to +a sty, and only one sty can be connected to any net channel. +Both sides of a sty are connected and disconnected at once. +A job can connect a sty if it has the sty open in either direction +(but it will generally want to have both directions open). + +When a %TDORS comes out of the sty, indicating that the TTY's +output buffer has been cleared, this is indicated to the net +output channel by means of a network interrupt, and the +string of up to 3 characters specified as the fourth argument +to the STYNET call. If the tty is a software tty and uses the +intelligent terminal protocol, then output RESETs will also block +the TTY at main program level. The sty-operating program will +not be informed of this, so it is up to the program at the other +end of the network connection to send back a ^\^P to turn output +back on. + +If you use STYNET with the official TELNET protocol, you must +turn on the %TPTEL bit in the sty TTY's TTYOPT variable, to +cause the sequence CR-LF received from the net +to be turned into just a CR. + +The arguments to a STYNET call are as follows: + +arg 1 sty channel (either direction). +arg 2 -1 to disconnect the sty from its network channels + (in which case args 3 and 4 are unnecessary), + or Net input channel (to connect sty output to). +arg 3 Net output channel (to connect sty input to). +arg 4 Characters to send out on net + when an output .RESET is done on the sty's TTY. + Up to 3 8-bit characters, left-justified. + +File: ITSTTY, Node: I/7, Previous: I/6, Up: I + + 7. STYGET. + +Sty handling programs that wish to take an active interest in +managing the lives of the programs attached to the sty's alter ego +may use the STYGET symbolic system call to get information on +what those jobs are doing. STYGET takes one argument - a tty spec - +and returns the following five values: + +1) The RH is 0 if the sty is free; otherwise, it is the job number + the job that owns the sty. The LH bits %SSHNG and %SSOHG + if set indicate that input and output, respectively, are in + don't hang mode. + This value contains garbage if the tty is not associated with a sty. +2) -1 if the tty is free; otherwise, the job number of the job + that owns the tty. +3) -1 if the tty is not a console; otherwise, the RH contains the + job number of the top level job in the tty's tree and the LH + is nonzero iff the tree is logging out. +4) Gives information on whether a job is hung trying to use the tty: + Bit 1.1 if 1 => the job owning the tty is waiting for input. + Bit 4.9 if 1 => that job is waiting for output buffer room. +5) Indicates the status of the tty's buffers: + Bit 4.9 if 1 => input is available. + Bit 4.8 if 1 => output buffer space is available. +6) Is the tty's TTYSTA word, which contains these bits: + Bit 4.9 (%TACFM) 1 => tty has had a "console-free" + message printed, and has not been in use since. + Bit 4.8 (%TAC.Z) 1 => tty is being ^Z'd, but the + tree has not been created yet. %TACFM will + be 0. If %TACFM is 0 and %TAC.Z is also 0, + the tty is in the process of being freed. + Bit 4.7 (%TANJS) 1 => the ^Z attempt in progress + on this tty is being ignored, because all + the job slots in the system are in use. + Bits 4.6-4.3 (%TANEC) Number of following chars to inhibit echo and + ints for. This is used for the arg chars that follow Top-E, Top-S, + Top-Y, etc. + + +File: ITSTTY, Node: J, Previous: I, Up: Top, Next: K + +J. THE INTELLIGENT TERMINAL PROTOCOL. + +The %TPCBS bit in the RH of TTYOPT turns on the intelligent terminal +protocol. This gives the terminal some extra control over things +through the use of escape sequences introduced by 034 (control +backslash). These escape sequences are handled at a "lower level" +than everything described above, and the characters composing them +are not echoed. The idea is not that the user should produce the +escape sequences by typing the characters, but that the terminal +should send them of its own accord when necessary, invisibly to +the user. For example, when the user types a ^\, the terminal +should send ^\^\, which is how to cause the intelligent terminal +protocol to pass the user's ^\ up to higher levels. + +* Menu: + +* Escape: J/1 Escape sequences. +* Alloc: J/2 Allocation. +* Reset: J/3 Output-reset. + +File: ITSTTY, Node: J/1, Previous: J, Up: J, Next: J/2 + + 1. ESCAPE SEQUENCES. + +(The spaces that appear inside the escape sequences are just +for readability; they should not actually be sent) + +The escape sequences are: + +^\ where is in {@, A, B, ..., _} and is + any character inputs the character (&27)*200+. + That is, supplies the 4 meta-bits for . The + meta bits are (in their ultimate positions): + + %TXTOP 4000 "TOP" + %TXSUP 1000 "SUPER" (Used to mean "SHIFT".) + %TXMTA 400 "META" + %TXCTL 200 "CONTROL" + + The bits should appear in shifted right 5; thus, + "C" = 103 will set %TXCTL and %TXMTA. + + Note that %TXCTL and %TXMTA are used with the + uncontrollified character, while %TXTOP is used + with the code for a SAIL-graphic < 40, not with + the letter which appears on that key on a TV keyboard. + Thus, 32 is the code for CALL, while %TXTOP+32 is the + code for the harmless SAIL graphic character NOT-EQUAL + and %TXCTL+132 is the code for CONTROL-Z. + %TXCTL+32 is CONTROL-CALL, and %TXCTL+%TXTOP+32 + is CONTROL-NOT-EQUAL. + %TXTOP+132 is meaningless, because %TXTOP makes sense + only with basic 7-bit codes that are less than 40. + +(In the following, # represents a number between 0 and 177 +(octal) which is simply transmitted as a character.) + +^\ ^A # increments the allocation by # characters. + +^\ ^Z zeros the allocation. + +^\ ^I sets the allocation to infinity. + +^\ ^S stops output at main program level. + +^\ ^R restarts output at main program level. + +^\ ^P # # sets the cursor position. The first # is the vertical + position (zero at the top of the screen.) The second # + is the horizontal position (0 at the left margin.) + Output is then restarted at main program level. + +^\ ^\ inputs a ^\. This is what to send when the user types + ^\ on the keyboard (unless the full character set is + being hacked in which case one would probably use + either "^\ A \" to input a control-backslash, or + "^\ P ^\" to input a less-than-or-equal). + +^\ ^C signals that the screen has been "messed up". + This gives a %PIATY interrupt to the running program, + just as if its superior had taken the terminal away and + presumably messed up the screen. Some programs (including + TECO) will respond to this by redisplaying everything. + +File: ITSTTY, Node: J/2, Previous: J/1, Up: J, Next: J/3 + + 2. ALLOCATION. + +To provide for intelligent terminals which sometimes can't +process characters as fast as ITS can send them, there is an +output allocation mechanism. The output allocation is the +number of characters which can be sent to the terminal without +overloading it. After this number has been sent, ITS will cease +outputting at interrupt level (but IOT'ing of output may +continue if the output buffer is not full). Transmission will +resume as soon as the terminal increases the allocation above +zero with a ^\ ^A # or a ^\ I. + +The initial default value of the allocation is infinity; +thus output normally never stops. When the terminal wishes to +begin to use the allocation feature, it should do ^\ ^Z to +initialize the allocation to zero. Then it should do one or more +^\ ^A #'s to tell ITS how much buffer space it has (more than one +is needed if the terminal wants to say it can buffer more than +177 characters). When characters arrive from ITS, the terminal +need not do anything, since ITS will decrement the allocation +automatically; but, when the terminal processes the characters +from its buffer, it must tell ITS that the buffer space is free +once more by sending a ^\ ^A #. For example, the terminal might +send ^\ ^A ^X once for each 24. characters it removes from its +buffer. If the terminal has reason to suspect that it and ITS +have gotten out of phase in remembering the allocation, it can +always reinitialize without fear using ^\ ^Z ^\ ^A . + +To stop using the allocation feature, just do ^\ ^I. + +File: ITSTTY, Node: J/3, Previous: J/2, Up: J + + 3. OUTPUT-RESET. + +If the TTY is a software-tty (*Note Soft: K.), uses the +intelligent terminal protocol (has %TPCBS on in TTYOPT), and +does output-resets (has %TPORS on in TTYOPT), then .RESET on +an output channel to that tty is handled specially. Any characters +in ITS's output buffer are thrown away, a %TDORS character is +sent to the terminal, and output is blocked at main program +level. The terminal should then throw away any characters in +its buffer. If the terminal is connected to ITS through a network +each node in the path should throw away the contents of its +output buffer and pass on the %TDORS. + +When the %TDORS gets to the terminal, it should determine +where the output that wasn't thrown away left the cursor +and send back a ^\ ^P # #, which sets the ITS cursor to this +position and restarts output. + +File: ITSTTY, Node: K, Previous: J, Up: Top + +K. SOFTWARE TTYS AND ITS OUTPUT BUFFER CODES. + +When a tty's TCTYP variable is set to %TNSFW, ITS sends +the contents of the tty output buffer directly to the +terminal, instead of translating it into one of the codes +used by any of the normal types of terminals. This can +be very convenient for new types of intelligent terminals, +and for sty-handling programs that must actually understand +the data read from the sty. The data output to a software +tty includes printing characters, and ITS display commands +as are found in the tty output buffer. Not having to +convert them into a different code at interrupt level saves +time; in addition, the display commands encode a superset of +the capabilities all real terminals supported by ITS, and +therefore more convenient than the code of any actual terminal. + +* Menu: + +* Codes: K/1 ITS output buffer codes. +* TDORS: K/2 Handling %TDORS. +* SCPOS: K/3 The SCPOS system call. + +File: ITSTTY, Node: K/1, Previous: K, Up: K, Next: K/2 + + 1. ITS OUTPUT BUFFER CODES. + +The internal ITS output buffer codes are 8 bits long. +Sty handlers should read them in unit mode only. To read +more than one at a time, use SIOT with 8-bit bytes. +Real terminals are assumed to be able to receive only +7-bit characters; for them, codes 0 - 176 are sent as +is; codes above 176 have 176 subtracted from them and +are escaped by a 177. 200-codes that have following arguments +which can reasonably be zero (%TDMOV, %TDMV0, %TDMV1) +have 1 added to each argument, so that 0 need not be sent. + +Note that not all 200-codes are meaningful on all types +of terminals. Programs outputting them in superimage mode +must be careful to use codes that work on the terminal +they have. + + 0 - 177 Characters, to be output as is. + Normally, only single-spacing graphic characters + will be sent this way. Other characters will + appear if programs output them in image mode. +%TDMOV=200 Move cursor. followed by 4 bytes of arguments: + first, the old vertical and horizontal positions + (these are probably not needed by the sty + handling program); next, the desired vertical + and horizontal positions. + Should not be used on "raw" ttys (%TORAW set), + though it will work. +%TDMV1==201 Should never be encountered. If it is, it is + followed by 2 bytes of args - the desired + vertical and horizontal positions. + Should not be used on "raw" ttys (%TORAW set). +%TDEOF==202 Clear rest of line and rest of page. + Does not move the cursor. + Does nothing on terminals that aren't selectively + erasable, even if they are displays. +%TDEOL==203 Clear rest of line +%TDDLF==204 Clear out character after cursor, without moving cursor. +%TDMTF==205 Turn off motor (should not come out except on terminets). +%TDMTN==206 Turn on motor (" "). +%TDCRL==207 Move cursor to beginning of next line, + and clear that line. If done when the cursor is on + the bottom line, it causes the terminal to scroll + its whole screen up. The TTYROL variable tells ITS + how many lines the terminal WILL scroll. +%TDNOP==210 No-op. +%TDBS==211 Backspace - used only on tty's with %TORAW set. +%TDLF==212 Linefeed - ("). +%TDRCR==213 Carriage return - ("). +%TDORS==214 Output reset. Put in the buffer when a tty + output reset is done, to inform the sty handling + program or the terminal. Should never be sent by + a program explicitly. +%TDQOT==215 Quote the next character so that it is output to the + terminal without being interpreted by ITS. +%TDFS==216 Move cursor forward one column. + This is identical to an appropriate %TDMOV command, and + exists to increase the efficiency of utilisation of + space in the output buffer. +%TDMV0==217 Move cursor, followed by 2 args: the desired + vertical and horizontal positions. + Should not be used on "raw" ttys (%TORAW set). +%TDCLR==220 Clear the screen, and move the cursor to the top left. + On printing terminals, it does nothing. +%TDBEL==221 Produce a sound on the terminal, or otherwise try + to attract the user's attention, without permanently + altering the contents of the screen. +%TDINI==222 Sent at system start-up to all terminals, + to tell them to reset themselves. +%TDILP==223 Insert Line Positions. Followed by a byte containing + the number of lines to insert. The current line and + all lines below it are pushed down on the screen that + many positions. Lines pushed off the bottom of the + screen are lost. Blank lines appear at the cursor to + replace the lines shifted downward. The cursor does + not move. + This code and the following one should be used only + on terminals which have %TOLID set, and only with the + cursor at the beginning of a line. +%TDDLP==224 Delete Line Positions. Followed by a byte containing + the number of positions to delete. That many lines, + starting with the current line, disappear. The lines + below them are shofted up to take their places. Blank + lines are shifted in as necessary at the bottom of the + screen. The cursor does not move. +%TDICP==225 Insert Character Positions. Followed by a byte + containing the number of spaces to insert. All of the + characters on the current line from the cursor to the + end move that many positions to the right. The last + few move off the right margin and disappear. The + terminal is not expected to know anything about + continuation lines. Spaces are shifted in at the + cursor to replace the characters that are moving + right. + This code and the following one should be used only + on terminals which have %TOCID set. +%TDDCP==226 Delete Character Positions. Followed by a byte + containing the number of character positions to + delete. All of the characters to the right of the + cursor move that many positions left, except for the + first few, which disappear rather than move past the + cursor. Spaces appear at the right margin to replace + them. +%TDBOW==227 Turns on inverse video mode for characters which are + output subsequently. The terminal should use some + sort of alternate display mode to emphasize them. +%TDRST==230 Turns off inverse video mode. If any other similar + modes are created, %TDRST will turn them off too. +%TDGRF==231 This is supposed to be for graphics, but it is not + implemented by anything. +%TDRSU==232 Region scroll upwards. +%TDRSD==233 Region scroll downwards. These two commands can be used + if the %TPRSC bit is on in TTYOPT. The %TDRSU/%TDRSD + command is followed by two parameter characters. The + first is the number of lines in the region to be scrolled; + the second is the number of lines by which the text is + to be scrolled. A region of the screen, which starts at + the line containing the cursor and proceeds downward for + the specified number of lines, is shifted by the specified + amount. %TDRSU shifts text upwards, bringing in blank lines + at the bottom of the region. %TDRSD shifts text downwards, + bringing in blank lines at the top of the region. The + cursor is not moved. If either parameter is 0 the command + should be ignored. If the size of the region is larger + than the size of the screen below the cursor, the region + should end at the bottom of the screen. If the number of + lines to scroll by is not less than the size of the region, + the region should be cleared. + +File: ITSTTY, Node: K/2, Previous: K/1, Up: K, Next: K/3 + + 2. HANDLING %TDORS. + +%TDORS is output to a software tty when an output RESET was +done on the tty, discarding some number of output characters. +For a normal terminal, ITS keeps track of the cursor position +at interrupt level; a RESET knows that the interrupt level +value is the correct one. For software terminals, ITS does +not remember an interrupt-level cursor position, so it is +up to the terminal (or sty-handler) to inform ITS of the +actual cursor position after each RESET. RESET turns on +the "hold output" bit for the tty, to make sure that +nothing happens to confuse the matter until that is done. +Actual terminals should use the ^\ ^P # # command of the +Intelligent Terminal Protocol (*Note ITP: J/3.). Sty +handlers should use the SCPOS system call (*Note SCPOS: K/3.). + +%TDORS will be sent to sty ttys even if they are not +software ttys, if %SSORS is set for the sty. That will +be so if the sty was opened for input with bit 20 +set in the open mode. In this case, SCPOS need not be +done, since the system knows the cursor position. +If the program does something with the %TDORS that +changes the cursor position, however, it should +do an SCPOS to inform ITS of the fact. Unlike the +case of software ttys and intelligent-terminal +protocol ttys, output will not be hung up until +this SCPOS is received. + +File: ITSTTY, Node: K/3, Previous: K/2, Up: K + + 3. THE SCPOS SYSTEM CALL. + +The SCPOS system call is used for telling ITS that a tty's +cursor is actually located at a given spot. IT DOES NOT +MOVE THE CURSOR. To move the cursor, ^P-codes or ITS +output buffer codes must be output. + +SCPOS must be used after any event in which ITS does not +understand how the cursor is moving. Luckily, there are +only two. A program which has done super-image output +must SCPOS if the output moves the cursor at all; +a sty-handler using a software tty must SCPOS after +an output RESET. Physical software ttys must do the +equivalent of an SCPOS after output RESETs, but they use +the Intelligent Terminal Protocol instead. + +The first argument to an SCPOS system call should be a tty specifier +(*Note TTY spec: G/2.). +The next two arguments should be the corrected vertical and +horizontal positions. +The third argument is optional, and if present sets the TTOALC +variable of the tty. A third argument of -1 is the way to clear +the hold-output bit after an output reset. + +SCPOS does not require ownership of the terminal; just output +permission (*Note Permit: B/3.). + +Tag Table: +File: ITSTTY Node: Top³8 +File: ITSTTY, Node: Aµ209 +File: ITSTTY, Node: A/1µ783 +File: ITSTTY, Node: A/1/a¶879 +File: ITSTTY, Node: A/2·719 +File: ITSTTY, Node: A/2/a¸631 +File: ITSTTY, Node: A/2/b¹220 +File: ITSTTY, Node: A/2/c¹852 +File: ITSTTY, Node: A/3±1045 +File: ITSTTY, Node: A/4±2512 +File: ITSTTY, Node: A/4/a±3567 +File: ITSTTY, Node: A/4/b±7111 +File: ITSTTY, Node: A/4/c±8543 +File: ITSTTY, Node: A/4/d±9171 +File: ITSTTY, Node: A/4/e±9847 +File: ITSTTY, Node: A/4/f²1071 +File: ITSTTY, Node: A/4/g²2535 +File: ITSTTY, Node: A/5²3286 +File: ITSTTY, Node: B²4887 +File: ITSTTY, Node: B/1²6017 +File: ITSTTY, Node: B/2²6913 +File: ITSTTY, Node: B/3²8783 +File: ITSTTY, Node: B/4²9753 +File: ITSTTY, Node: B/5³1853 +File: ITSTTY, Node: C³2391 +File: ITSTTY, Node: C/1³2882 +File: ITSTTY, Node: C/3³3947 +File: ITSTTY, Node: C/3/a³5386 +File: ITSTTY, Node: C/3/b³5981 +File: ITSTTY, Node: C/3/d³7382 +File: ITSTTY, Node: D³8148 +File: ITSTTY, Node: D/1³9205 +File: ITSTTY, Node: D/2´2157 +File: ITSTTY, Node: D/3´6093 +File: ITSTTY, Node: D/4´7874 +File: ITSTTY, Node: D/5µ2007 +File: ITSTTY, Node: D/6µ2344 +File: ITSTTY, Node: D/7µ3370 +File: ITSTTY, Node: D/8µ4443 +File: ITSTTY, Node: Eµ7111 +File: ITSTTY, Node: E/1µ8393 +File: ITSTTY, Node: E/2¶0094 +File: ITSTTY, Node: E/2/a¶0749 +File: ITSTTY, Node: E/2/a/1¶1944 +File: ITSTTY, Node: E/2/a/2¶2245 +File: ITSTTY, Node: E/2/a/3¶2467 +File: ITSTTY, Node: E/2/a/4¶3456 +File: ITSTTY, Node: E/2/a/5¶4395 +File: ITSTTY, Node: E/2/a/6¶5078 +File: ITSTTY, Node: E/2/a/7¶5516 +File: ITSTTY, Node: E/2/a/8¶6293 +File: ITSTTY, Node: E/2/a/9¶6663 +File: ITSTTY, Node: E/2/a/10¶7087 +File: ITSTTY, Node: E/2/b¶8083 +File: ITSTTY, Node: E/2/c¶9177 +File: ITSTTY, Node: E/2/c/1·0146 +File: ITSTTY, Node: E/2/c/2·0486 +File: ITSTTY, Node: E/3·1015 +File: ITSTTY, Node: E/4·5836 +File: ITSTTY, Node: E/4/a·6612 +File: ITSTTY, Node: E/4/b·7759 +File: ITSTTY, Node: E/5·8265 +File: ITSTTY, Node: E/6·9269 +File: ITSTTY, Node: E/7¸0518 +File: ITSTTY, Node: E/8¸3878 +File: ITSTTY, Node: E/9¸4869 +File: ITSTTY, Node: E/10¸5413 +File: ITSTTY, Node: F¸5791 +File: ITSTTY, Node: F/1¸6575 +File: ITSTTY, Node: F/2¸7551 +File: ITSTTY, Node: F/2/a¸8009 +File: ITSTTY, Node: F/2/b¸9958 +File: ITSTTY, Node: F/3¹1464 +File: ITSTTY, Node: F/4¹2155 +File: ITSTTY, Node: G¹3306 +File: ITSTTY, Node: G/1¹5754 +File: ITSTTY, Node: G/1/a¹5983 +File: ITSTTY, Node: G/1/b¹8395 +File: ITSTTY, Node: G/1/c±00841 +File: ITSTTY, Node: G/2±01029 +File: ITSTTY, Node: G/2/a±02128 +File: ITSTTY, Node: G/2/b±03852 +File: ITSTTY, Node: G/2/c±05628 +File: ITSTTY, Node: H±06320 +File: ITSTTY, Node: H/1±07001 +File: ITSTTY, Node: H/1/a±07472 +File: ITSTTY, Node: H/1/b±08916 +File: ITSTTY, Node: H/1/c±11981 +File: ITSTTY, Node: H/1/d±12930 +File: ITSTTY, Node: H/1/e±14851 +File: ITSTTY, Node: H/1/f±17022 +File: ITSTTY, Node: H/1/g±17487 +File: ITSTTY, Node: H/2±18935 +File: ITSTTY, Node: H/2/a±19126 +File: ITSTTY, Node: H/2/b±19430 +File: ITSTTY, Node: H/2/c±20089 +File: ITSTTY, Node: H/2/d±21194 +File: ITSTTY, Node: I±22741 +File: ITSTTY, Node: I/1±24472 +File: ITSTTY, Node: I/2±26344 +File: ITSTTY, Node: I/2/a±27269 +File: ITSTTY, Node: I/2/b±27858 +File: ITSTTY, Node: I/2/c±28145 +File: ITSTTY, Node: I/2/d±28569 +File: ITSTTY, Node: I/3±28875 +File: ITSTTY, Node: I/3/a±29684 +File: ITSTTY, Node: I/3/b±30410 +File: ITSTTY, Node: I/3/c±30935 +File: ITSTTY, Node: I/3/d±31209 +File: ITSTTY, Node: I/4±32076 +File: ITSTTY, Node: I/5±32726 +File: ITSTTY, Node: I/6±34279 +File: ITSTTY, Node: I/7±37305 +File: ITSTTY, Node: J±39088 +File: ITSTTY, Node: J/1±40013 +File: ITSTTY, Node: J/2±42507 +File: ITSTTY, Node: J/3±44143 +File: ITSTTY, Node: K±45038 +File: ITSTTY, Node: K/1±46035 +File: ITSTTY, Node: K/2±51091 +File: ITSTTY, Node: K/3±52503 + End Tag Table: + +Don't delete this page. diff --git a/doc/sysdoc/job.100 b/doc/sysdoc/job.100 new file mode 100755 index 00000000..2942c1df --- /dev/null +++ b/doc/sysdoc/job.100 @@ -0,0 +1,782 @@ +PROGRAMMING TECHNOLOGY DIVISION DOCUMENT SYS.xx.yy + + +IDENTIFICATIONî______________ + + The JOB/BOJ Device: A Mechanism for Implementing + Non-standard Devices + + Marc S. Seriff, Jack Haverty, Richard Stallman (MIT-AI) + + September 18, 1974 + + +INTRODUCTIONî____________ + + It is occasionally desirable to extend the ITS system to allow + +for the use of non-standard I/O devices. A very desirable feature + +would be to allow user-level programs to make use of the newly defined + +devices with out modification of the user-level programs. For this + +reason the JOB/BOJ device was implemented. + + When a job (call it the user) attempts an OPEN for a file whose + +name is "JOB: <-dir>-; <-fn1>- <-fn2>-", the system creates a + +new job, called the BOJ device handler, or BDH (this is a terrible + +name; it USES the BOJ device and HANDLES the JOB device), and attempts + +to load the file "DSK: <-dir>-; <-fn1>- <-fn2>-" into that job. + +If the load fails, the OPEN will fail. If this load succeeds, the + +OPEN, as well as all further I/O operations on the user's JOB channel + +will be referred to the BDH for execution. At that point, it will be + +up to the BDH to decide whether or not the open should fail. In order + +to get a handle on information about the user's open, The BDH opens + +one or more channels to the "BOJ" device. The system will insure that + +the BDH's BOJ channel is logically linked to the user's JOB channel. + +The following diagram illustrates what happens: + PTDD 2 SYS.xx.yy + + + + __________ _________ + | | | | + | User |------v__________------>| BDH | + |__________| | | ---XO--- | | |_________| + | | Sys|tem | | + ____| |_____|_____| |____ + |v | |v + The JOB channel | The BOJ channel + | + |v + System mediates + + + Once the BDH has successfully opened the BOJ channel, it will be + +notified (via an I/O channel interrupt) every time the user attempts + +an I/O operation on the JOB channel. The BDH may then examine the + +data that is made available to it about the I/O operation and may + +simulate the operation for the user. In this way, BDHs can be written + +to give anything the appearance of a disk, tape or other specific type + +of I/O device. + +USING THE JOB DEVICEî_____ ___ ___ ______ + + Programs that use the JOB device should not be required to make + +special provisions. A BDH should, in general, be written so that the + +non-standard device will behave exactly like some standard device. In + +other words, a user program may open a JOB device using a standard + +open and may then execute any legal I/O operation. + + A file name with something other than "JOB" for a device code can + +be made to act like a JOB device in one of two ways. The first way + +should be used for devices that are not generally applicable or are + +expected to be used only for a short time. To use this method simply + +use translates (using MONIT, DDT or directly via system calls) to + +inform the system which file should be used as a BDH. For instance, + +if we translate all file names of the form "XXX:" into the file name + PTDD 3 SYS.xx.yy + + +"JOB:ABC;TS RUNXXX", then the system will use the file "DSK:ABC;TS + +RUNXXX" as the BDH for any file name whose device code is "XXX". + + The other method is much simpler and is designed for non-standard + +devices that are to be made available to the entire user community. + +When an OPEN is attempted on a device whose name the system does not + +recognize, the system will examine the "DEVICE;" directory for a file + +whose first name is "JOBDEV" and whose second name is the unrecognized + +device name. If such a file exists, then the contents of that file + +will be loaded by the system and used as the BDH for the user's OPEN. + +USING THE BOJ DEVICE - THE BOJ DEVICE HANDLERî_____ ___ ___ ______ _ ___ ___ ______ _______ + + The BDH is the workhorse in the JOB/BOJ device scheme. It is + +required to interpret all of the user's I/O operations. It must do + +everything to make the non-standard device that it represents appear + +standard. The system provides five .CALLs to give the BDH some of the + +required communcation with the user. + + The first thing that the BDH should do when he is loaded and + +started by the system is to execute an OPEN on the BOJ device. This + +establishs a logical link between the user and the BDH. The BDH may + +enable a channel interrupt on the BOJ channel, in order to be informed + +whenever the user attempts an I/O operation. + + It should be noted that the ITS system allows for the possibility + +of a full duplex connection between the user and the BDH (i.e. a + +channel in each direction). If a user attempts an open for reading + +and an open for writing on the same device, then the system will + +present both opens to the same activation of the BDH. Should this be + +undesirable for a particular BDH, that BDH should use an open mode + +with the 3.4 bit set (10 in the left half) each time it attempts to + +open the BOJ device. + PTDD 4 SYS.xx.yy + + +JOBCAL SYSTEM CALLî______ ______ ____ + + The first .CALL that will be discussed is the JOBCAL. This call + +enables the BDH to find out what I/O operation the user has attempted + +to execute. It has the following calling sequence: + + .CALL JOBCAL + ... ; Error return + ... ; Success return + +JOBCAL: SETZ + SIXBIT/JOBCAL/ + [<-BOJ channel number>-] + 2000,,<-opcode>- + SETZ [-<-n>-,,<-data>-] + + +This .CALL, as well as the other three discussed below, will fail to + +skip if any of the following conditions hold: + + 1. <-BOJ channel number>- is an illegal channel number. + + 2. <-BOJ channel number>- is not open on the BOJ device. + + 3. the user job does not exist or as has closed his channel. + + 4. the user job is no longer attempting to execute the I/O + operation. + + <-opcode>- should be an address into which information about + +the I/O operation requested will be placed. This word contains three + +sections. The right half of the word contains an integer indicating + +which operation was attempted. The following table indicates what the + +various integers mean: + PTDD 5 SYS.xx.yy + + + + CODE OPERATIONî ____ _________ + + 0 OPEN + + 1 IOT (transfer) + + 2 STATUS (currently unused) + + 3 RESET + + 4 RCHST (complete status) + + 5 ACCESS + + 6 FDELE (for delete or rename while not open) + + 7 FDELE (for rename while open) + + 8 CALL (see below) + +It is up to the BDH to insure that these I/O operations perform as + +they would for standard ITS devices. + + The top three bits (4.9-4.7) of the op-code word contain the mode + +in which user is attempting to open his channel. This is only + +meaningful for op-code 0, OPEN. If either of the next two bits (4.6 + +and 4.5) are non-zero, then the user is requesting that a channel be + +closed. As was mentioned above, the system allows the connection + +between user and BDH to be full dumplex. If the 4.6 bit of the opcode + +is set, then the user is requesting that his input channel be closed, + +while the 4.5 bit requests a close of the user's output channel. It + +is possible to get an opcode in which both bits are set. In the case + +the BDH should perform the obvious task of closing both channels. + + Most I/O operations require more information than just the name + +of the operation. The third argument to JOBCAL tells the system where + +any additional information that is available should be placed. + +<-n>- is the largest number of words that the BDH is willing to + PTDD 6 SYS.xx.yy + + +accept (it should normally be 12). <-data>- is the address where + +the first word of the information should be placed. What information + +is placed in this buffer is determined by the I/O operation being + +attempted. + + If the op-code (in the right half of the op-code word) is less + +than 8, then five words will be written into the buffer (beginning at + +<-data>-) in response to the JOBCAL. The meanings of the words are + +given in the following table: + PTDD 7 SYS.xx.yy + + + +WORD OPERATIONS MEANINGî____ __________ _______ + + 1 IOT (1) Meaningful only for block IOTs. + This word will contain the user's + IOT pointer. The left half of this + word will be the negative of the + number of words that the user wants. + + 1 ACCESS (5) The address within the virtual file + that is open from (or to) which the + next IOT should be done. The first + word of the virtual file is word + zero. + + 1 FDELE (6 or 7) Zero implies delete requested. + Non-zero means that a rename is + requested. This word is the name + (in sixbit) to be used as the new + first file name. + + 2 OPEN (0) or FDELE (6) First name of the file that the user + is attempting to open, rename or + delete. + + 3 OPEN (0) or FDELE (6) Second name of the file that the + user is attempting to open, rename + or delete. + + 4 OPEN (0) or FDELE (6) Name of directory to be used for + open, rename or delete. + + 5 OPEN (0) or FDELE (6) Name of device to be used for open, + rename or delete. + + 6 OPEN (0) The full 18 bit open mode (right + justified). + + 6 FDELE (6 or 7) Zero implies delete. Non-zero means + that a rename is requested. This + word is the name (in sixbit) to be + used as the new second file name. + + If the op-code returned by JOBCAL is 8, then the user has + +attempted some I/O operation not recognized by the systems JOB/BOJ + +device code (this does not mean that the operation is illegal). Inî ___ + +this case, more information is written into the BDH's buffer (up to + +twelve words). The first of the data words will be the SIXBIT name of + PTDD 8 SYS.xx.yy + + +the operation being performed. (This will normally be the name of the + +.CALL executed by the user - see Appendix 1 for a list of + +possiblities.) The second word will contain all of the flags that the + +user has set using the "flag" feature of the .CALL UUO. The third + +word will be an integer indicating how many input (to the system) + +arguments the user supplied in his .CALL. It should be noted that if + +this integer is larger than <-n>-+3, then some information will be + +lost. The values of the input arguments will appear in the remainder + +of the words in the buffer. Remember that, in almost all cases, the + +first of the input arguments will be the user's channel number. + +JOBRET SYSTEM CALLî______ ______ ____ + + Once the BDH has interpreted the user's request for execution of + +an I/O operation, the BDH must have some way of responding to the + +user. This is provided with the JOBRET .CALL. This .CALL serves + +three purposes: + + 1. to unblock the user who is waiting for completion of his + I/O request (possibly causing the request to skip) + + 2. to set lossage codes in the user's status words (e.g. for + failed opens). + + 3. to return information requested by the user's I/O + operation. + +The format of this CALL is as follows: + + .CALL JOBRET + ... ; error return + ... ; success return + +JOBRET: SETZ + SIXBIT /JOBRET/ + [<-BOJ channel number>-] + [<-return>-] + SETZ [-<-n>-,,<-data>-] + + +where <-return>- satisfies requirements 1 and 2 above. If + PTDD 9 SYS.xx.yy + + +<-return>- is zero, then the user's I/O call will not skip or set + +status bits. If <-return>- is of the form <-i>-,,<-j>- , then + +<-i>- will be placed in the "open-loss" field of the status word for + +the user's channel and the user's I/O call will skip <-j>- times. A + +list of all currently recognized open loss codes can be found in + +Appendix 2. + + If the user's I/O call requested data, then the BDH can supply + +this data by supplying the third argument to the JOBRET call. The + +system will use the <-n>- words beginning at location <-data>- as + +the values for the return arguments in the user's call. + +SETIOC AND JOBINT -- INTERRUPT SYSTEM CALLSî______ ___ ______ __ _________ ______ _____ + + There are two interrupt oriented functions that the BDH must + +perform and there are CALLs available to perform them. The first is + +to notify the user when he has done something catastrophic. The user + +should be notified of his error by causing the system to awaken him + +with an I/O channel error. This done with the SETIOC call, as + +follows: + + .CALL SETIOC + ... ; error return (standard reasons + + illegal IOCERR code) + ... ; success return + +SETIOC: SETZ + SIXBIT/SETIOC/ + [<-BOJ channel number>-] + SETZ [<-IOCERR code>-] + + +where <-IOCERR code>- is an integer identifying the reason for the + +error. This integer should be chosen from the list that can be found + +in Appendix 2. Since BDHs are written to handle non-standard devices, + +these error codes will quite often not apply. Simply choose the code + +that comes closest. + PTDD 10 SYS.xx.yy + + + Occassionally, the BDH must notify the user of a non-catastrophic + +situation (e.g. the arrival of data). The JOBINT call allows the BDH + +to give the user a second-word I/O channel interrupt, as follows: + + .CALL JOBINT + ... ; error return + ... ; success return + +JOBINT: SETZ + SIXBIT /JOBINT/ + SETZ [<-BOJ channel number>-] + + +JOBSTS SYSTEM CALLî______ ______ ____ + + Finally, the BDH must have some way to notify the system what the + +status of the pseudo-device is. For this purpose, the JOBSTS call is + +available. Its calling sequence is as follows: + + .CALL JOBSTS + ... ; error return + ... ; success return + +JOBSTS: SETZ + SIXBIT /JOBSTS/ + [<-BOJ channel number>-] + SETZ [<-new status>-] + + +The right half of <-new status>- will be given to anyone requesting + +the status of the user's channel until another JOBSTS is done. It + +should be remembered that the low order six bits (1.1-1.6) should + +contain the device code of the pseudo-device. Unless, you know what + +you are doing, this should always be 22 octal. + +DATA TRANSFERS - HOW TO IOTî____ _________ _ ___ __ ___ + + Since the main purposes of I/O devices is transfer of + +information, let us look at how the BDH manages to respond to the + +user's IOTs. The method for doing this is very simply. If we think + +back to the diagram presented early in this memo, we will remember + PTDD 11 SYS.xx.yy + + +that the BOJ and JOB channels (i.e. the channels belonging to the BDH + +and the user, respectively) are logically connected. The full meaning + +of this now becomes clear. If the JOB channel is open for input and + +the BOJ channel is open for output, then anything that BDH outputs on + +the BOJ channel will be available to the user as input on the JOB + +channel. (For this reason, the BDH must insure that he opens the BOJî ____ + +channel in the opposite direction from the user's JOB channel even if + +this requires opening the BOJ channel a second time in the correct + +mode.) + + There are two features of which the BDH implementer should be + +aware when writing the I/O sections of the BDH. Let us assume for the + +discussion here, that the user has the JOB channel open for reading + +and that the BDH has the BOJ channel open for writing. Let us also + +assume that the user is currently hung attempting to read 100 words on + +his JOB channel. + + First it should be noted that the BDH does not have to respond toî ___ + +this request with a single transfer of 100 words. The system will act + +as an mediator between different transfer sizes. The BDH can respond + +to the user's request for 100 words in several ways: + + 1. He can send all 100 words in small pieces (e.g. 10 + + transfers of 10 words each. + + 2. He can send all 100 words in a single transfer. + + 3. He can send more than 100 words. In this case, the BDH + + will remain hung in his IOT until the user has read all of + + the data that the BDH is attempting to send. (If this is + + undesirable, set the 3.5 in the BOJ open mode. This will + + cause BOJ IOTs to unhang whenever the user's IOT is + PTDD 12 SYS.xx.yy + + + satisfied. When that happens, the BOJ IOT pointer will + + have been counted out only partially; the RH will point to + + the first word not transfered) + + 4. He may send less than 100 words. In this case, the BDH + + must manually awaken the user as described below. + +The user, who is hung awaiting his 100 words, will stay hung until he + +has received all 100 words. Suppose, however, that the BDH only + +wishes to send 50 words (e.g. the last 50 words of the virtual file). + +To do this, he can send the 50 words normally, but must then use the + +JOBRET call (described above) to awaken the user. JOBRET should be + +called with the BOJ channel number as the first argument, zero as the + +second argument and no third argument. Secondly, the BDH implementer + +must be aware that the ITS system guarantees that IOTs to a channel + +open in block mode, will never generate an I/O channel error. In + +other words, the following algorithm should be followed: + + 1. If the user requests n words and there are n words or more + + left in the "file", give him n words. + + 2. If the user requests n words and there are only m words + + (n>m), give him m words and manually awaken him (using + + JOBRET). + + 3. If the user requests n words and there are no words left, + + then give him nothing and manually awaken him (using + + JOBRET). + +HINTS TO BDH IMPLEMENTERSî_____ __ ___ ____________ + + The following hints should ease the task of BDH implementers a + +little. It is hoped that anyone who attempts to a BDH implementation + +will add his harshly acquired knowledge to this section of this memo. + PTDD 13 SYS.xx.yy + + +1. Remember that the BDH is essentially a disowned job and should + + attempt to log out after a close has been requested. + +2. Be very leery of logging out for any reason other than a requested + + CLOSE. In particular: + + a. if a JOBCAL fails, only log out if a request for OPEN has not + + yet been received. + + b. when you generate an I/O channel error for the user, only log + + out if the error is irrecoverable. Remember that he can + + correct an access beyond end-of-file by doing an access before + + attempting another IOT. + + c. if he requests an I/O operation that you do not recognize, + + generate a "mode not available" error (via JOBRET) and wait + + for his next request. + + d. if you decide, for your own reasons, to make the initial open + + fail, you should log out. + +THE OJB DEVICE -- AN AID FOR DEBUGGING THE BDHî___ ___ ______ __ __ ___ ___ _________ ___ ___ + + One of the problems with debugging BDH programs is that when the + +JOB device is used, it is loaded into a newly created job. That job is + +not inferior to any DDT, and there is no way to put breakpoints in it + +before it starts. The OJB device makes it possible to run the BDH + +program under DDT. + + The OJB device acts just like the JOB device except during the + +initial open. When the JOB device would be creating and loading a new + +job, the OJB device is looking for an existing job whose UNAME and + +JNAME are the same as the filenames specified in the open. If such a + +job is found, it is connected to the job opening the OJB device + +through a standard JOB-BOJ pipeline. If such a job does not exist, + PTDD 14 SYS.xx.yy + + +the open of the OJB device fails. In order to protect innocent jobs + +from being hacked in this matter, the job opened on the OJB device is + +required to have set its OPTOJB bit (this is bit 4.2 in the .OPTION + +varisble, settable with .SUSET). Also, it must not already be a BDH, + +for the system cannot consider one job to be a BDH through two + +connections at once. If either of those conditions is not met, the + +OJB open WAITS until they are. + + To remove a possible timing screw, a BOJ device open by a job + +that is not a BDH, which usually fails, will wait instead for the job + +to become a BDH if the job's OPTOJB bit is set. + + The procedure for using the OJB device for debugging is: + + + 1. create a job to use for the BDH (call it J, in this example). + + 2. run (in another job) the program which would normally open + +the JOB device, but tell it (perhaps by means of a translation) to use + +the OJB device instead. This program's function is to issue system + +calls so that the BDH's responses to them can be tested. + + Since the OPTOJB bit of job J is now 0, when this program reaches + +the OJB open it will hang. + + 3. ^Z that program, and ^P it. it will go back to hanging in the + +open of the OJB device. + + 4. switch to job J, load in the BDH program. This RESET's the + +job so that if it had been a BDH before, it will not be one now. + + 5. turn on the OPTOJB bit by depositing from DDT in .OPTION. + +The conditions for a successful OJB open by job JJ have now been met, + +so that job will make some headway, turning job J into a BDH and + +waiting for job J to issue a JOBRET. + PTDD 15 SYS.xx.yy + + + 6. it is now possible to start running job J, with breakpoints + +as desired, to step through the code for handling the initial open. + +It is unlikely, but theoretically possible, for J to execute its BOJ + +open before JJ gets around to turning J into a BDH. In this case, J + +will wait for JJ to do so. + + 7. if it becomes necessary to try again after discovering a bug, + +go back to step 2. The OJB open will hang up this time not because + +the OPTOJB bit is off (since it is still 1) but because J is already a + +BDH. Loading J in step 4 will make J cease to be a BDH but also turn + +off the OPTOJB bit, so JJ will still be waiting. + + 8. it is possible for job JJ to be "PCLSR'ed" or backed up out + +of its open while job J is being traced through the handling of the + +initial open. For example, job JJ might receive a real-time + +interrupt. If that happens, J will cease to be a BDH. This will not + +interfere with the tracing of J until the next BOJ device system call + +is executed; that call will probably fail. It is impossible to + +continue after such an occurrence, so the jobs must be restarted by + +returning to step 2. Of course, if there are no breakpoints before + +the first JOBRET, this is very unlikely to happen. + + 9. if the initial open has been handled successfully, to go on + +to debug handling of other system calls, simply tell JJ to execute + +them with J stopped while JJ is being told, then ^Z^P JJ and go back + +to J. + + 10. the usual .LOGOUT in the BDH program will be a no-op when the + +program is run as an inferior in this manner, so it should be followed + +by a .VALUE. + \ No newline at end of file diff --git a/doc/sysdoc/locks.108 b/doc/sysdoc/locks.108 new file mode 100755 index 00000000..992e683f --- /dev/null +++ b/doc/sysdoc/locks.108 @@ -0,0 +1,360 @@ + -*- Text -*- + + + This file contains documentation for both the LOCK device, + and the locked switch list and critical routine features. + + + +THE LOCK DEVICE. [ In ITS version 1630 and later ] + +The LOCK device provides a simple and foolproof technique for interlocking +between jobs. While not as efficient as using an AOSE-style switch in +shared memory, the LOCK device is much easier to use and is suitable for +use in those situations where a lock is only rarely seized, and is only +held for brief periods of time. + +Locks are identified using a single SIXBIT word as a lock name. (Actually, +and non-zero 36-bit word can be used.) A job can lock the FOO lock by +opening "LOCK:FOO" for output. The LOCK device ignores any second filename +or directory name you might supply. The lock will be released when the +channel is closed. As long as the job keeps the lock channel open, any +other attempts to lock the same lock result in a %ENAFL (FILE LOCKED) +error. + +When opening the LOCK device, bit 1.4 indicates that the opener wishes to +hang waiting for the lock, rather than receiving a %ENAFL error. + +It is also possible to receive a %EFLDV (DEVICE FULL) error when opening +the LOCK device if the table of currently held locks that ITS maintains +overflows. + +Here is the registry of all lock names. Any program that uses the LOCK +device should register the name of the locks it uses here. + + Name Purpose + ------ ------ + NUTMEG This lock is used in an example later + on in this file. + + MBXxxx The set of locks whose names start with the + characters "MBX" are used by COMSAT and GMSGS to + coordinate access to mailboxes. The algorithm for + computing the lock for the mailbox named + SNAME;NAME1 NAME2 is: + + MOVE A,NAME1 + ROT A,1 + ADD A,NAME2 + ROT A,1 + ADD A,SNAME + IDIVI A,777773 ; Largest prime < 1,,0 + HRLI B,(SIXBIT /MBX/) ; Result in B = A + 1 + + + + +THE LOCKED SWITCH LIST AND CRITICAL ROUTINE FEATURES. + +There is an obvious technique for interlocking between jobs on +the PDP-10 - namely, the use of AOSE - which has been unusable +under ITS simply because a job might be killed while it had a +switch locked, thus causing the switch to remain locked forever. +These implemented features allow that problem, and the similar +problem of system crashes while a switch in a permanent data +base is locked, to be solved without any loss of efficiency. + +The locked switch list feature allows a program to maintain a +list of switches which it has locked, so that ITS can unlock +them when the job is killed (or logs out, or is gunned) +or is reset (for example, $l'd by DDT). The critical routine +feature allows the program to cause ITS to perform certain +actions if the job is killed or reset with the PC in a specified range. + +These features do not prevent bugs in the programs accessing +a switch from causing the switch not to be unlocked. They make +possible successful interlocking but do not guarantee it. + + +A. THE DEFINITIONS OF THE FEATURES. + +These features are all activated by setting the %OPLOK bit in +the .OPTION USET-variable to 1 (This bit is 1000,,). If that is +not done, words 43 and 44 are not in any way special. Also, the +addresses used do not have to be 43 and 44; that is merely their +default values. The actual adresses used are relative to the +contents of the .40ADDR USET-variable, which initially contains +40 . If .40ADDR were set to 1000, locations 1003 and 1004 would +used. Of course, all system actions that normally use locations +40, 41 and 42 would use 1000, 1001 and 1002. + + 1. THE LOCKED SWITCH LIST. + +When the %OPLOK bit is 1, location 43 is taken to be the pointer +to the job's locked switch list. The list pointer +should either be 0, meaning the list is empty, or the address of +the first two-word switch block. The format of a switch block is +as follows: + + 1st word: the switch, or, if the indirect bit is set in + the second word, the address of the switch + (multiple indirection is not allowed). + 2nd word: the RH holds the address of the next switch + block, or 0 (this is the CDR of the list). + the LH holds the instruction to be executed to + unlock the switch. The index field is ignored. + The instruction must either be an AOS or SOS + with 0 in the AC field, a logical instruction + (such as SETAM, IORM, SETOM, ANDCAM), a halfword + instruction, a MOVEM, MOVNM, MOVSM, MOVMM, + ADDM or SUBM. The AC will never be modified + even if the instruction + says to do so. If the LH is 0, the instruction + SETOM is used, as the most common choice. + +When the job is killed or reset, if the locked switch list is +not null, the system looks at the first switch block, unlocks +the switch by executing the unlock instruction with the switch +word as its memory argument, and the copying the RH of the +second word of the switch block into 43 to remove the block +from the list (this makes sure that no switch is ever unlocked +twice due to PCLSR'ing). +This procedure is repeated until 43 contains 0, +thus unlocking all the switches in the list. Obviously since the +job's pages are about to be discarded this action will have no +consequence unless the switches are in pages shared with other +jobs. + +If in the process of unlocking the switches +the system tries to read from a nonexistent page or write in a +pure page, it gives up entirely, ignoring the rest of the +locked switch list, and also the critical routine table. Also +if the end of the list is not reached after 512. switch blocks +have been unlocked, the system gives up. + + 2. THE CRITICAL ROUTINE TABLE. + +When the %OPLOK bit is 1, location 44 is considered to be an +AOBJN pointer to a table of critical sections of code, which are +involved in the manipulation of switches or the locked switch +list. The table should be a vector of two-word entries, one for +each critical section of code. The first word of each entry +should give the boundaries of the critical section: the left +half should have the the address of the first instruction of the +critical section; the right half, the address of the first +instruction after the critical section. The second word of the +entry should have an unlock instruction, subject to the same +restrictions as for locked switch list unlock instructions, +the only difference being that the address field of the +instruction is taken from the RH of the word, as one would expect, +whereas in unlock instructions in switch blocks the address of +the switch block is used, and the RH of the word is the CDR. +Examples will make all this clear. + +If the job is killed or reset while the PC is in the range +specified by a critical routine table entry, the switch +specified by the entry will be unlocked by executing the unlock +instruction. It is possible +for the ranges specified by two entries to overlap; to make sure +that no entry is processed more than once, the system updates 44 +as it processes each entry. + +As with the switch list unlocking, the system abandons the whole +thing if it needs to read or write in a page that won't allow it. + + 3. FATAL INTERRUPTS IN TOP-LEVEL JOBS WITH LOCKED LOCKS. + +When the %OPLKF bit in a job's .OPTION variable is set to 1, and if the job +is the top-level job of a non-disowned tree, then if that job ever receives +a fatal interrupt its locks will be unlocked by the system job as part of +the process of detaching it. Thus fatal interrupts in network servers, +toplevel DDTs, system demons, etc. that happen while those jobs have shared +databases locked, will not keep other jobs blocked waiting for someone to +gun down the corpse. + +The reason you might not want to set %OPLKF is that after a jobs locks are +unlocked, it will not in general work to proceed the job. Such a detached +corpse will only be good for autopsy, not revival. + + +B. USING THE FEATURES FOR SWITCHES IN A SHARED PAGE. + +In this section it is assumed that the page is not part of a +disk file, and will not survive through a system crash. That +means that it is not necessary to worry about unlocking switches +that are locked at the time of a system crash. + + 1. LOCKING AN AOSE-STYLE SWITCH. + +The proper routine to use for locking a switch follows: +The address of the two-word switch block is assumed to be in A. + +LOCK: AOSE (A) ;LOCK THE SWITCH, OR WAIT TILL WE CAN. + .HANG +LOCK1: MOVE B,43 ;PUT THE SWITCH ON THE + HRLI B,(SETOM) + MOVEM B,1(A) ;LOCKED SWITCH LIST + MOVEM A,43 +LOCK2: POPJ P, + +This routine will set up the switch as a switch block, and make +43 point to it. The contents of the switch block will be: + + 0 ;This word is the switch itself! + SETOM + ;The SETOM is the unlock instruction. + ;The RH has nothing to do with the SETOM; + ;it points to the next block of the list. + +Note that the HRLI instruction is superfluous, because 0 in the +left half of the second word of the block is the same as (SETOM). + +The three instructions starting at LOCK1 are critical because +the switch has been locked but is not on the locked switch list. +Therefore, an entry in the critical routine table of the form + + LOCK1,,LOCK2 + SETOM @A + +is needed, in case the job is killed while executing there. + + + 2. UNLOCKING AN AOSE-STYLE SWITCH. + +The correct way to unlock a switch follows: +(assuming that A points to the switch block and that +the switch block is the first item on the locked switch list). + +UNLOCK: HRRZ B,1(A) ;REMOVE THE SWITCH FROM THE + MOVEM B,43 ;LOCKED SWITCH LIST. +UNLOC1: SETOM (A) ;THEN UNLOCK THE SWITCH. +UNLOC2: POPJ P, + +The instruction at UNLOC1 is critical because the switch is +locked but not on the locked switch list. Therefore, an entry +is needed in the critical routine table as follows: + + UNLOC1,,UNLOC2 + SETOM @A + +Note that the switch must be removed from the list before +unlocking. That is because if the switch is locked but not on +the list, the critical routine table may be used to unlock it, +but if the switch is on the list but not locked, it will be set +to -1 if the job is killed, and that could cause problems if +some other job had locked the switch. + + +C. HANDLING SWITCHES IN DISK FILES. + +The extra problem here is to make sure that if the system crashes, the next +time the data base is accessed after the system is reloaded all the +switches will be reinitialized. This may be done by using the time and +date that the system was started to distinguish different incarnations of +it. + +The technique uses a variable INITDN, stored in the database, and a LOCK +device lock named "NUTMEG". Whenever a program accesses the database for +the first time, it must check INITDN. If INITDN does not equal the time +the system was started, the database requires initialization. If a job +detects that the database requires initialization, it seizes the NUTMEG +lock, checks to see that initialization really is required, performs the +initialization, updates INITDN, and releases the lock. + +The skeleton of the necessary routine is as follows, assuming that the file +has already been opened and its pages mapped into core with a CORBLK system +call, and INITDN is the address of the variable and SWIT1, SWIT2, etc. are +the addresses of switches. + +INIT: .CALL [ SETZ ? SIXBIT /RQDATE/ + MOVEM A ; Ignore 1st value + SETZM A] ; 2nd value is time of system startup. + .LOSE 1000 + JUMPL A,[MOVEI A,300. ; System doesn't know time, + .SLEEP A, ; Sleep 10. sec and hope it + JRST INIT] ; finds out the time. + CAMN A,INITDN ; Init needed? + POPJ P, ; No => No need for the lock, just return. + .CALL [ SETZ ? SIXBIT /OPEN/ + MOVSI 10\.UAO ; 1.4 => Hang waiting for initialization lock + MOVEI CH + MOVE [SIXBIT /LOCK/] + SETZ [SIXBIT /NUTMEG/]] ; Registered, database specific lock + .LOSE + CAMN A,INITDN ; Init needed? + JRST INIT1 ; No => someone else did it, unlock and return. + SETOM SWIT1 ; Start setting switches to unlocked + SETOM SWIT2 ; state. These insns should address + SETOM SWIT3 ; locations in the mapped file pages. + ;; etc. + SETOM SWIT9 + MOVEM A,INITDN ; Mark init complete. +INIT1: .CLOSE CH, + POPJ P, + +Note that the first CAMN A,INITDN can be omitted, and the algorithm is +still correct, but the second CAMN A,INITDN can -not- be safely omitted. + + +D. REFERENCE COUNTS. + +Sometimes it is desirable to keep a count of the number of jobs +looking at a data base. When the count is AOS'd, an entry must +be put on the locked switch list to cause it to be SOS'd if the +job is killed. For example, assuming that A points to the count +and B points to an available two word block of memory: + +LOOK: AOS (A) +LOOK1: MOVEM A,(B) + MOVSI C,(SOS @) + HRR C,43 + MOVEM C,1(B) ;SET UP UNLOCK INSN & CDR POINTER. + MOVEM B,43 ;PUT THE BLOCK ON THE LIST. +LOOK2: POPJ P, + +The critical code table entry needed is: + + LOOK1,,LOOK2 + SOS @A + +When finished looking, the count must be SOS'd, and removed from +the list. The following routine will work, assuming only that +the block at the front of the list was put on by the LOOK routine +above: + +UNLOOK: MOVE B,43 + HRRZ A,(B) ;GET ADDRESS OF THE COUNT VARIABLE TO BE SOS'D . + HRRZ B,1(B) ;GET CDR POINTER. +UNLOO1: MOVEM B,43 ;REMOVE BLOCK FROM LIST. +UNLOO2: SOS (A) ;DECREMENT THE COUNT. + POPJ P, + +The critical code table entry needed is: + + UNLOO1,,UNLOO2 + SOS @A + + +E. THE .HANG INSTRUCTION. + +The .HANG UUO is to make it easy for programs to wait for various +conditions, such as locks becoming unlocked. It should be used the way a +JRST .-1 would be used in a stand-alone program. .HANG is documented +completely in .INFO.;ITS UUOS. + + +F. THE UNLOCK SYSTEM CALL. + +The UNLOCK system call can be used to unlock the switches of a specified +job. Usually this is used by a job to unlock its own switches, but it can +be used on the switches of any job that the executing job is allowed to +write. + +Usual case: + + .CALL [ SETZ ? SIXBIT /UNLOCK/ + SETZI %JSELF ] ; Unlock all my switches + .LOSE %LSSYS + +(Note that this has nothing to do with the LOCK device. In particular it +will -not- close LOCK device channels.) diff --git a/doc/sysdoc/magtap.101 b/doc/sysdoc/magtap.101 new file mode 100755 index 00000000..264176ed --- /dev/null +++ b/doc/sysdoc/magtap.101 @@ -0,0 +1,206 @@ +MAG TAPE SPECS +Copied from memo from S.Cutler 2/23/72 +THIS MEMO CONTAINS MANY LOWER-CASE CHARS + +Bits in left half word of .OPEN call: +3.1=1,,0 + 0=> Input + 1=> Output + +3.2=2,,0 + 0=> Unit + 1=> Block + +3.3=4,,0 + 0=> ASCII + 1=> Image + +3.4=10,,0 + 0=> Ignore record gaps,treat them as part of the hardware + 1=> "Chunk mode." [does not appear to be implemented any more] + If output then write an EOR gap after each .IOT. + If input, if user defined block IOT pointer is big enough + one record is read. See .IOT for details. Must be + opened in block mode. + +3.5=20,,0 + 0=> Skip to EOF on last close on read + 1=> Don't " " " " " " " + +3.6=40,,0 + 0=> Odd parity + 1=> Even parity + +3.7,8=300,,0 + 00=> default (800 or 1600 BPI depending on drive type) + 01=> 800 BPI (used to be 200 BPI) + 10=> 1600 BPI (used to be 556 BPI) + 11=> 6250 BPI (used to be 800 BPI) + +3.9=400,,0 Only meaningful for 9 track tapes + 0=> Core dump mode, 36 bit words, any density allowed. + 1=> IBM Character Mode, 32 bit words, doesn't allow 200/556 BPI + +4.1,2,3=7000,,0 + 0=> 2000=1024. words per record + 1=> 1000=512. WPR + 2=> 400=256. WPR + 3=> 200=128. WPR + 4=> 100=64. WPR + 5=> 40=32. WPR + 6=> 20=16. WPR + 7=> 10=8. WPR + +Open error if: + 1) Open for writing and + a) Open for reading on another channel + b) Tape write locked (i.e. no ring) + c) IBM mode and less than 800 BPI + 2) Open for reading and already open for writing on another + channel + 3) Transport not on line + 4) Chunk mode and not block mode + + +.IOT CHNM,LOC +------------- + +For standard .OPEN, this works as a standard .IOT. If open +in chunk mode input [not implemented any more], loc has + + loc/ -count,,loc2 + +where count is a number greater than the possible number of words to +be written into core. The .IOT causes words to be read into core +starting at loc2. For each word read, the count in decreased by one. +An IOC error occurs if the count is too small to contain the +record. + +On chunk mode output, an EOR gap is written after each .IOT, +and the tape is written after each .IOT instead of waiting for +system buffers to fill or the channel closed. [not implemented any more] + + + + +.CLOSE CHNM, +------------ + +Closes the channel, releases the transport if not open on another +channel. Writes out all buffers in the system and writes 2 EOF +marks if open for writing, and backs up over second one. + + + + +.STATUS CHNM,LOC +---------------- + +1.1-1.6=> physical device code (15) + +1.7-1.9 mode open in + +2.1=> System buffering capacity empty (i.e. 0=> data read from + tape and not yet transferred to user by a .IOT or data + .IOTed from the user to the system but not actually + written onto tape or user core image.) + +2.2=> System buffering capacity full (i.e. no core in which to + allocate buffers for reading from tape. Also too many + buffers resident in system but not yet written onto either + tape or users core image.) + +2.3=> 1=> Beginning of tape + +2.4=> 1=> End of tape + +2.5=> 1=> 9 track, 0=> 7 track + +2.6=> 1=>IBM mode, 0=> core dump mode + +2.7=> Transport idle (no pending command) + +2.8=> EOF (last thing seen was a tape mark) + +Left half standard. + + + + +.RCHST AC, +---------- + +AC/ CHNM,,LOC + +LOC: 0) 0,,(SIXBIT /MTn/) + 1) 0 + 2) 0 + 3) 0 + 4) -1 + + + + +.MTAPE AC, +---------- + +AC/ CHNM,,COMAND + +COMAND/ COUNT,,FUNCTION + +Right half of COMAND + 0=> Hang until all tape motions finish + 1=> Rewind + 2=> Rewind and unload (also shreds tape leader) + 3=> Write EOR. Writes out current system buffers even if + less than record size and writes an EOR gap. + 4=> Write 3 inches of blank tape + 5=> Write EOF. (Two EOF's are written automatically + after a close on a channel open for writing.) + 6=> Space forward COUNT records. COUNT=0 implies 1 + record. COUNT negative implies space reverse. Stops + at EOF or BOT. + 7=> Space forward +- COUNT files. (Stops at BOT or + logical EOT.) + 8.=> Space forward to logical EOT, back up over second + EOF. + 9.=> Stop and reset the tape system. + 10.=> Set write record size to COUNT words. + 11.=> Read into AC write record size or size of last record + gobbled by an input IOT. + +Skips if successful. + +Rewind and space only if open for reading. + +Write EOR, 3 inch, EOF writing only. + +Stop and hang for both read and write. + + + + +Transport State Notes +--------- ----- ----- + +A transport turned off or off line is equivalent to not being there. + +Tape can not be written unless the write enable ring is in the hub +of the tape. + +A transport can be opened by an arbitrary number of channels in +different modes, but can not be opened by more than one user, or in +both input and output. The device dependent bits (3.4-4.9) must be +the same for all channels with the exception of chunk mode. + + +The logical end of tape (EOT) is located after two EOF's in a +row. A close on a channel open for writing writes two EOF's and +then backspaces over one of them. The .MTAPE command to go to +the end of the tape also backspaces over the second EOF. + +If the physical end of tape mark is reached while writing a record, +the record is finished being output (there is always room for a few +records after the reflective strip) and an IOC error is raised +saying End of Tape. + \ No newline at end of file diff --git a/doc/sysdoc/ncp.100 b/doc/sysdoc/ncp.100 new file mode 100755 index 00000000..b910d4c1 --- /dev/null +++ b/doc/sysdoc/ncp.100 @@ -0,0 +1,841 @@ +Warning- don't believe everything in this file! + + + ITS NCP INTERFACE + +CALL: .OPEN + + FUNCTION: OPEN channel to Network + + ARGUMENT TEMPLATE: + 1. Channel number in AC field of .OPEN instruction + 2. 4 word block addressed by @ E (X) field of + .OPEN instruction + 4 word block has this form: + + _________________________________________________ + | | | + | MODE BITS | SIXBIT /NET/ | + |_______________________|_______________________| + | | + | LOCAL SOCKET | + |_______________________________________________| + | | + | FOREIGN SOCKET | + |_______________________________________________| + | | + | FOREIGN HOST | + |_______________________________________________| + + + MODE BITS + + |--------- don't buffer more + | output than allocation + | + | |----- 0-200 words + | | 1-2000 words + | | +____________________________________________________________________________ +| | | | | |out|big|by- lis gen|im- | +| | SIZE OF BYTE | | |ctl|buf| te ten sok|age blk out| +|___________|___________|___________|___|___|___|___|___|___|_#_|___|___|___| + | | | | |_____| +BYTE SIZE IF | 0-"NORMAL" | | | | +MODE=44 __| 1-8 BIT BYTE SIZE _______| | | +(BYTE & IMAGE) IF ASCII | | STANDARD + USE BYTE FIELD | | ITS + IF IMAGE | | MODES + | | ______________ + 0-"NORMAL" | | | | + 1-LISTEN ON ___________| | | 0XX ASCII | + LOCAL SOCKET | | 1XX IMAGE | + | | X0X UNIT | + 0-USE LOCAL | | X1X BLOCK | + SOCKET FIELD | | XX0 INPUT | + 1-GENERATE _______________| | XX1 OUTPUT | + "UNIQUE" SOCKET |____________| + # (USE .RCHST + TO FIND OUT + RESULT) + + + + LOCAL SOCKET + 32 bit socket # for local identification + + FOREIGN SOCKET + 32 bit socket # determined by foreign host + system + + FOREIGN HOST + 8 bit socket # specifying computer system + with which to contact + + + RETURNS: None + + SKIPS: No Skip If Fails + + FAILURE RETURNS: + Indicated in LH of .STATUS value (low order 6 bits + in LH) + i.e. .STATUS ch, ac + LDB ac, [220600,,ac] + + CODE____ + + 2 "WRONG DIRECTION" + (gender of socket wrong for mode) + + 6 "DEVICE FULL" + (socket table full) + + 7 "DEVICE NOT READY" + (NCP not up, or IMP not up) + + 13 "FILE ALREADY EXISTS" + (socket already open by you on another channel) + + 22 "CONTRADICTORY OPEN" + (byte size mismatched) + + 23 "FILE LOCKED" + (socket number not part of your allocated + "unique" group of 8 allocated to your job) + + 41 "OTHER END OF PIPELINE GONE OR NOT OPEN" + (HOST dead or non-existant see NETHST call) + + + SIDE EFFECTS: + + + + EXAMPLES: + ;to listen .OPEN ch, listen + JRST fail + . + . + + Listen: 20,,'NET + 1 ;waiting socket + 0 ;socket determined when + matching RFC received + 0 ;host determined when + matching RFC received + + + :to get "unique socket" + .OPEN ch, unique + JRST fail + + :Unique 10,,'NET + 0 ;determined by system + 1305 ;foreign socket + 6 ;foreign host + + +Equivalent: + + .CALL OPEN + + arg 1 mode,,channel number + arg 2 SIXBIT/NET/ + arg 3 local socket + arg 4 foreign socket + arg 5 host number + + +CALL: .RCHST + + FUNCTION: Read extended STatus of network CHannel + + ARGUMENT TEMPLATE: AC/ channel,, + + + RETURNS: + WORD _________________________________ + | | | + 0 | | 'NET | + |_______________|_______________| + | | + 1 | LOCAL SOCKET | + |_______________________________| + | | + 2 | FOREIGN SOCKET | + |_______________________________| + | | | BYTE | | + 3 | I | (reserved)| SIZE | HOST | + |___|___________|_______|_______| + | | | + 4 | IMP DOWN | STATE | + |_______________|_______________| + | | | + 5 | (reserved) | CLS | + |_______________|_______________| + | | | + 6 | (reserved) | #BITS | + |_______________|_______________| + + + INTERRUPT + 4.9 bit of word 3 + set by receipt over network of INR/INS + control message (see protocol) + cleared by .RESET + causes interrupt on channel + + BYTE SIZE + 9 bit field + byte size of connection (bits 2.9 - 2.1) + + HOST + 9 bit field (8 used by Network foreign host #) + + IMP DOWN + time in 1/30 sec. until IMP going down + (if planned) + -1 not going down + 0 down + +n planned to go down in n/30 sec. + (see also NETIMP call) + + + STATE + %NSCLS 0 connection closed + %NSLSN 1 listening for RFC + %NSRFC 2 RFC in to listen + %NSRCL 3 CLS received after RFC + %NSRFS 4 RFC sent + %NSOPN 5 open + %NSRFN 6 RFNM wait on output + %NSCLW 7 CLS sent, waiting for matching CLS + %NSCLI 10 CLS received data available to input + %NSINP 11 input available + + + REASON FOR CLS (state 0) + %NCNTO 0 never opened connection (not .OPEN) + %NCUSR 1 CLS by user (.CLOSE) + %NCFRN 2 CLS by foreign host + %NCRST 3 RST (reset) from foreign host (dead) + %NCDED 4 host dead (see also NETHST call) + %NCINC 5 incomplete transmission (see NETHST) + %NCBYT 6 byte size mismatch + %NCNCP 7 local NCP went down, breaking connection + %NCRFS 10 connection refused by foreign host + + + SKIPS: No skip + + FAILURE RETURNS: None + + + SIDE EFFECTS: None + + + EXAMPLE: + MOVE ac, [ch,,blk] + .RCHST ac, + . + . + + BLK: BLOCK 7 + +Equivalent: + + .CALL RCHST + + arg 1 network channel number + + val 1 'NET,,0 + val 2 local socket number + val 3 foreign socket number + val 4 4.9 interrupt received + 2.1-2.9 byte size + 1.1-1.9 host number + val 5 LH IMP Down time/reason + RH Socket state (%NSxxx) + val 6 Open mode + val 7 RH Close reason (%NCxxx) + val 8 RH Number of bits____ available + (input data available or output buffer room) + + +.CALL WHYINT + + arg 1 network channel number + + val 1 %WYNET + val 2 Socket state (%NSxxx) + val 3 Number of bytes_____ available + (input data available or output buffer room) + val 4 Close reason (%NSxxx) + +This call is usually used to respond to a second-word interrupt +from a network channel. + + + +CALL: .STATUS + + FUNCTION: Reads status of Network channel + + ARGUMENT TEMPLATE: + Channel number in AC field of .STATUS instruction + + RETURNS: Status of word in location addressed by + @ E (X) fields of .STATUS instruction + + SKIPS: No skip + + + FAILURE RETURNS: None + + SIDE EFFECTS: None + + EXAMPLE: + .STATUS ch, statwd + Statwd: BLOCK 1 + + + FORMAT OF STATUS WORD + + _________________________________ + | | | + | ERROR CODE | SS0026 | + |_______________|_______________| + + + ERROR CODE + if IOC (I/O channel error) or OPEN failure, + codes will be stored here. + + SS + state (byte 140600), same as that given for + .RCHST -- see list of states + + 26 + code for Network device + + +Equivalent: + + .CALL STATUS + + arg 1 channel number + + val 1 status word as above + + + +CALL: .NETACC + + FUNCTION: NETwork ACcepts Connection (after LISTEN type + .OPEN) + (to REJECT, do a .CLOSE) + + ARGUMENT TEMPLATE: + Channel number in AC field of .NETACC instruction + + RETURNS: Nothing + + SKIPS: Skips on success + + FAILURE RETURNS: + Not skip --not in state 2 (RFC received to LISTEN) + + SIDE EFFECTS: Sends matching RFC (and "allocate" if input) + + EXAMPLE: + .NETACC ch, + JRST error + + + + + +CALL: .NETS + + FUNCTION: NET Send buffer now + (Buffer is normally sent when "full" or after + 1/2 second of first activity) + + ARGUMENT TEMPLATE: + Channel number in AC field .NETS of instruction + + RETURNS: Nothing + + SKIPS: No skip + + FAILURE RETURNS: + IOC (I/O channel error) + Code 1, if not SEND (write) channel + + SIDE EFFECTS: Buffer is queued to be sent immediately + + EXAMPLE: + .NETS ch, + + +CALL: .CALL FORCE + + arg 1 channel number + + Equivalent to .NETS (see above) + + +CALL: .CALL FLUSH + + arg 1 channel number + + Does FORCE then waits for all buffered data to be sent + and for the final RFNM to come back. + + +CALL: .CLOSE + + FUNCTION: CLOSEs channel and returns immediately + + ARGUMENT TEMPLATE: + Channel number in AC field of .CLOSE instruction + + RETURNS: None + + SKIPS: No skip + + FAILURE RETURNS: None + + EXAMPLE: + .CLOSE ch, + + +Equivalent: + + .CALL CLOSE + + arg 1 channel number + + +CALL: .CALL NETBLK + + FUNCTION: Hang until connection is not in specified + state or until time out + + ARGUMENT TEMPLATE: + Standard .CALL arguments + 1. channel number + 2. state -- returns when not in this state + 3. (optional) time -- number of 30ths of second + to wait or -- (time since system up) in 30ths + of second + + RETURNS: 1. (optional) state -- new state + 2. (optional) time -- time left after state + change + + SKIPS: Skips on success + + FAILURE RETURNS: + Not skip and + OPEN code 14 -- channel number not <20 + -- channel not Network device + + SIDE EFFECTS: None + + EXAMPLE: + .CALL netblk + JRST error + . + . + + Netblk: SETZ + SIXBIT /NETBLK/ + channel + state + time + 2000,,newstate + 402000,,timeleft + + Channel: ch + + State: <-wait for this state to be left>- + + Time: <-30ths of second to wait>- + + Newstate: BLOCK 1 + + Timeleft: BLOCK 1 + + + The time argument is clobbered in the same way that + .SLEEP clobbers its AC; unless it is immediate. In that + case, the time out will be restarted if the job is pclsred. + + +CALL: .RESET + + FUNCTION: Used to RESET interrupt bit + (INR/INS from Network) + + ARGUMENT TEMPLATE: + Channel number in AC field of .RESET instruction + + RETURNS: Nothing + + SKIPS: No skip + + FAILURE RETURNS: None + + SIDE EFFECTS: Clears the Network interrupt bit (see .RCHST, + bit 4.9 of word 3) + + EXAMPLE: + .RESET ch, + +Equivalent: + + .CALL RESET + + arg 1 channel number + + + +CALL: .NETINT + + FUNCTION: Sends Network INR/INS control message for + link corresponding to channel. (TELNET protocol also + demands a "data mark" to be inserted in the stream) + + ARGUMENT TEMPLATE: + Channel number in AC field of .NETINT instruction + + RETURNS: Nothing + + SKIPS: Skip if success + No skip if Network down or not a Network + channel + + FAILURE RETURNS: + I/O Channel error Interrupt, NET went down + Code 1 + + SIDE EFFECTS: Sends NET INR/INS control message + + EXAMPLE: + .NETINT ch, + JRST fail + + + + +CALL: .GETSYS areas + NCPHTB + NCPPQ + NCPSM + + FUNCTION: Get socket map + host table + pending queue + + ARGUMENT TEMPLATE: + Name of first of 2 consecutive accumulators in AC + field of .GETSYS instruction + + ac/ -<-length>-,,<-address>- ;CPTR to block to store + + ac+1/ SIXBIT/<-name>-/ ;sixbit name of area + desired + + + RETURNS: Block of desired information + + SKIPS: Skips on success + + FAILURE RETURNS: + No skip -- area name not known in system -- not + enough memory + (ac+1 zeroes) + (ac gets <-lng,,> for number of words needed) + + SIDE EFFECTS: None + + EXAMPLE 1: + ;This can be used to find out how much storage is + needed for a .GETSYS block + + HRROI ac,temp + MOVE ac+1, [SIXBIT/NCPSM/] + .GETSYS ac, + HLRES ac ;here ac contains + lng,,temp + MOVNS ac ;now ac contains + number of words + needed + CALL FREE (ac) + + + EXAMPLE 2: + MOVE ac, [-lng,,blk] + MOVE ac+1 [SIXBIT /NCPSM/] + or NCPHTB or NCPPQ + .GETSYS ac, + JRST error + . + . + + BLK: BLOCK lng + + + +NCPHTB area + + Length -- 400 (8) words (256(10)) + + Format -- one word per host number + (word(i) is data for host.number (i)) + + Each word has info packed -- + + |1| | 2 | 9 | 18 + ______________________________________________ + |R| | | | | | + |F| | | | | | + |N|unused|RST| CTL TIME|00| HOST DEAD STATUS | + |M| | | | | | + |_|______|___|_________|__|__________________| + + + RFNM 0-control link open + 1-waiting for RFNM on control link + + RST 0-host down or not tried + 1-sent RST to see if up + 2-got RRP, connections may be opened + + CTL TIME 9 + Last time (1/30 sec module 2 ) + message sent to this host on control link (0) + + HOST DEAD STATUS + Last HOST DEAD STATUS from this host's IMP + (See RFC 611) + +(If data for a single host is desired, use the NETHST call) + + HOST DEAD STATUS in right half + + Bits 20-31 (byte pointer [041400,,x]) + give the time of the Host's coming back up, + bit-coded as follows: + + + Bits 20-22 (byte pointer [150300,,x] + the day of the week the Host is coming back up + Monday is day 0 and Sunday is day 6 + + Bits 23-27 (byte pointer [100500,,x]) + the hour of the day, from hour 0 to hour 23, + that the Host is coming back up + + Bits 28-31 (byte pointer [040400,,x]) + the five minute interval, from 0 to 11, in the + hour that the Host is coming back up + + + All three of the above are specified in Universal Time + (i.e., G.M.T.). The Host may indicate that it will be + coming back up more than a week away by setting bits 20-31 + all to ones (7777). Setting all bits 20-30 to one and bit + 31 to zero (20-31 = 7776) means it is unknown when the Host + is coming back up. + + Bits 32-35 have the follwing meanings: + + Value Meaning + ----- ------- + + 0 The destination Host is not communicating with the + network -- the destination IMP has no information + about the cause. Note that this is the message most + likely to occur if the destination IMP has gone down + since the destination Host went down. + + 1 The destination Host is not communicating with the + network -- it took its ready-line down without saying + why. + + 2 The destination Host is not communicating with the + network -- the Host was tardy in taking traffic from + the network and the network had to declare the Host + down. + + 3 The destination Host does not exist to the knowledge + of the NCC. + + 4 Currently unused. + + 5 The destination Host is down for scheduled P.M. + + 6 The destination Host is down for scheduled hardware + work. + + 7 The destination Host is down for scheduled software + work. + + 8 The destination Host is down for emergency restart. + + 9 The destination Host is down because of power outage. + + 10 The destination Host is stopped at a software + breakpoint. + + 11 The destination Host is down because of a hardware + failure. + + 12-15 Currently Unused. + + When the value of this 4-bit field is 0,1,2, or 3, bits 20-31 +will have the "unknown" indication. + NCPPQ area -- pending queue of RFC's + + Length -- variable 3+4*n where n is currently 40 (8) but + may change + + Format -- + word 0 -- relocation word, tells location in system + core where first slot begins + + word 1 -- pointer to first queue entry + + word 2 thru 4*n+1 -- 4 word slot for queue or -1 if + last one on queue + (0) -- pointer to next one (must un-relocate, + using word 0 + (1) -- local socket number + (2) -- foreign socket number + (3) -- sign bit 0 = STR 1 = RTS + low order 8 bits (byte pointer [001000,,X]) + link number if RTS + byte size if STR + next 8 bits (byte pointer [101000,,x]) + foreign Host number + + +Example of unrelocating for the NCPPQ area. + ;Let ac,ac+1 and b be accumulators + + MOVE ac, [-lng,,blk] + MOVE ac+1, [SIXBIT /NCPPQ/] + GETSYS ac, + JRST error + MOVEI ac, blk + MOVN b,(ac) ;-system address + loop: ADD ac,b ;ac now points to + ;first queue entry + + ;0(ac) is next pointer word + ;1(ac) is local socket word + ;2(ac) is foreign socket word + ;3(ac) is Host -- lind/byte word + + MOVE ac,0(ac) ;get next + JUMPGE ac,loop ;loop if not last one + + NCPSM area + + Length -- 1+13.*20. = 261(10) or 405(8) + there are 13 (or more) blocks each of length + IMPSTL (an assebly parameter, currintly 20(n)) + + Format -- + word 0 -- contains IMPSTL, the number of words + in each block + word 1 -- begins first block -- the blocks are: + +IMSOC1: REPEAT IMPSTL,0 ; 0 => FREE + ; 4.9 = 1 => SOCKET IN USE + ; 4.8 = 1 => CHNL TRYING TO BE CLOSED + ; 3.1-4.7 MASK FOR INTERRUPT BIT (LSH 1 CHNL#) + ; RH = USER INDEX +IMSOC2: BLOCK IMPSTL ; 1.1-4.5 = LOCAL SOCKET NUMBER + ; 4.6-4.9 0 (MAKES COMPARISONS EASIER) +IMSOC3: BLOCK IMPSTL ; 1.1-4.5 = FOREIGN SOCKET NUMBER + ; 4.6-4.9 = 0 +IMSOC4: BLOCK IMPSTL ; RH = SOCKET STATE + ; 3.1-3.8 = LINK NUMBER + ; 3.9-4.7 = FOREIGN HOST NUMBER + ; 4.8 = SET BY RCV CLS - MAKES MATCH USING IMSCHD FAIL + ; 4.9 = SEND THIS BUFFER NOW +IMSOC5: BLOCK IMPSTL ; 1.1-1.8 = CONNECTION BYTE SIZE + ; 2.1-2.9 = CLOSE REASON + ; 3.1-3.8 = USER BYTE SIZE + ; 3.9 => ASCII MODE - 7 BIT + ; 4.1 => ASCII MODE - 8 BIT + ; 4.2 => 1 BIT BYTES + ; 4.3 => NET INTERRUPT (INR/INS) RECEIVED + ; 4.4 => HAVE BEGUN CLOSE TIMEOUT + ; 4.5 => CLOSED WHILE IN RFNM WAIT, EXPECT ANOTHER RFNM + ; 4.9 => TRANSFER IN 32 BIT MODE +IMSOC6: BLOCK IMPSTL ; RH => BUFFER ADDRESS + ; 4.9 => LOCKED BY CORE JOB + ; 4.8 => ACTIVE AT PI LEVEL + ; 4.7 => INPUT OCCURRED WHILE BUFFER LOCKED + ; 3.1-3.8 => IOBFT INDEX, OR 377 IF BIG BUFFER +IMSOC7: BLOCK IMPSTL ; BIT ALLOCATION +IMSOC8: BLOCK IMPSTL ; MESSAGE ALLOCATION +IMSC7I: BLOCK IMPSTL ; AMOUNT TO INCREASE BIT ALLOCATION BY IN NEXT ALL MSG +IMSC8I: BLOCK IMPSTL ; AMOUNT TO INCREASE MESSAGE ALLOCATION BY " " " " +IMSOCT: BLOCK IMPSTL ; TIME WHEN FIRST MESS PUT INTO BUF + ; (DURING INPUT HAS NUMBER OF DATA BYTES LEFT IN MSG) + ; (DURING CLOSE HAS TIME TIMEOUT STARTED) +IMSMPP: BLOCK IMPSTL ; MAIN PROGRAM POINTER, ILDB OR IDPB FOR NEXT BYTE +IMSMPC: BLOCK IMPSTL ; MAIN PROGRAM COUNTER, FOR OUTPUT HAS ROOM LEFT + ; IN BUFFER IN BYTES. FOR INPUT HAS TOTAL NUMBER + ; OF DATA BYTES IN THE BUFFER. +IMSPIP: BLOCK IMPSTL ; INTERRUPT LEVEL POINTER. FOR OUTPUT ILDB GETS + ; FIRST BYTE OF NEXT MESSAGE OUT. FOR INPUT RH + ; HAS ADDRESS OF HEADER WORD OF NEXT MESSAGE IN. +IMSBFE: BLOCK IMPSTL ; BYTE POINTER TO LAST BYTE IN BUFFER. + +CALL: .IOT + + FUNCTION: Transfer data in or out over Network + + ARGUMENT TEMPLATE: + Channel number in AC field of .IOT in struction + <-word>- or pointer to block + + RETURNS: None (unit output mode) + Datum (unit input mode) + Updated pointer (block mode) + + SKIPS: No skip + + FAILURE RETURNS: + I/O Channel error INTERRUPT + Code 1 -- Network went down + Code 8 -- Attempted output mode IOT when not in + State 5 (open) or State 6 (RFNM wait) + Or attempted input IOT when in bad state + or when closed other than by foreign host. + End of file is sensed when input is done from + a socket closed by the foreign host. In unit + image mode this gives I/O channel error code 2. + + SIDE EFFECTS: + Output -- data buffered to be sent + Input -- data copied from buffer ALLOCATE sent if + buffer empty (enough) + + EXAMPLE: .IOT ch, foo + + +In image block mode, one byte per word is transferred, +right-justified. + +In ascii block mode, five bytes per word are transferred, +or four bytes per word (8-bit) if mode bit 1.6 was on in +the OPEN. + diff --git a/doc/sysdoc/tv.100 b/doc/sysdoc/tv.100 new file mode 100755 index 00000000..26231921 --- /dev/null +++ b/doc/sysdoc/tv.100 @@ -0,0 +1,310 @@ + A slightly revised TV-11 program is up and running. +There are the following features/changes: + +SHIFT and SHIFT-LOCK no longer XOR. The general reaction + was against that feature, so it was removed. + +[ESC]D Buzzes the ninth-floor door for three seconds and + then flashes your screen. It works for free consoles + as well. + +[ESC]Q Generates a hardcopy, as before, but the timeout is + sixteen seconds, avoiding garbage output. + +[ESC]L Clears your screen. + NOTE: This is the same command as [ESC]I, which + is retained for old times' sake for the + moment, but will be garbage-collected + soon. +_______________________________________________________________ + +A. THE WHO-LINE. + +The who-line is a line that appears at the bottom of the screen +on a TV terminal, describing the status of either the system as +a whole, or a particular job. In the former case, it is said +that the system who-line is being displayed; in the latter, the +user who-line. The information is updated every 5 seconds. The +who-line may be turned on or off, and various modes may be +selected, under either user or program control. + + 1. WHAT APPEARS IN THE WHO-LINE. + + a. The User Who-line. + +The user who-line begins with system status information: +the version number of ITS, the time of day and the date. +Then comes information on the job that is selected for who-line +display: the job number, the uname, jname and sname, +a "status" that says what the job is doing, +the percentage of the system's time that the job is running, +its total run time so far, and its core size in K. +An example of a user who-line is: + +12/31/74 21:21:30 20 RMS NT .INFO. TTY 5% 0:03:09.2 24K RANDOM CRUFT + + ^time. ^uname. ^sname. ^% runtime. ^core size. +^date. ^job #. ^jname. ^status. ^job runtime. ^user-specified stuff. + + 1: The Who-line Status. + +STOP means that the job has been stopped (presumably by its + superior). This will be the case for jobs that have + been ^Z'd. +RUN for jobs that are running in user mode - that is, + neither stopped nor executing a system call. +PAGE means that the job is waiting to swap a page in. + + means that the job is executing an IOT (or SIOT) on that device. + Appended to the name of the device may be the following + characters: + I input. + O output. + B block mode. + S string mode. + For example, DSKBI means block mode input from the disk. + + (for example, "OPEN", "CLOSE"). + means that the job is executing the system call named. + +If the job is currently executing a system call (which implies +that the status is not RUN or STOP), a "+" will +appear in front of the status if the job is actually running, as +opposed to waiting (for buffer space, etc). +Thus, "DSKBI" indicates that the job is waiting for a disk +transfer to take place, while "+DSKBI" indicates that it is +copying information out of a system disk buffer. + +The user-specified part of the who-line is controlled by the +.WHO1, .WHO2 and .WHO3 variables of the job described by the +who-line. Those variables exist so that the program running can +show whatever internal status information it thinks the user might +want to know - what page of input is being processed, for example. +See the description of those variables in ITS USETS for details of +how to use them in a program. + + + b. The System Who-line. + +The items in the system who-line are as follows: + +ITS XXX MM/DD/YY HH:MM:SS USERS RNBL/TJOB SWAPB PAGEW RCORE/UCORE FCORE + +XXX ITS version # +MM/DD/YY today's date +HH:MM:SS time of day +USERS number of users logged in +RNBL number of runnable jobs +TJOB total number of ITS jobs +SWAPB number of swap blocked jobs +PAGEW number of jobs waiting for pages +RCORE number of pages belonging to runnable jobs +UCORE total number of pages in the system. +FCORE number of user pages there is room for + in real core at one time. + +In addition, if ITS is being debugged, the system who-line +will mention that fact. + + + 2. USER CONTROL OF WHO-LINES. + +Currently, who-line control uses the [ESC]W command, interpreted +directly by the PDP11. When a command is given, it is not really +processed until the next time the who-lines are updated. The +issuing of a command triggers such updating immediately, even +if the normal time for updating has not arrived, but there may +be a delay nevertheless. In that case, a second command given +before the updating is done will overwrite the first. + + The options are: + +[ESC]W turns off the who-line. +[ESC]1W selects the user who-line, migrating with the + ownership of the tty. That is, each time the + who-line is updated, it will describe whichever + job has the tty at that moment. + This is the default status. +[ESC]2W freezes the who-line on whatever job was last + shown. If you are about to ^Z - ^P a job but + wish the who-line to continue to show that job + instead of following the tty to its superior, + this is the thing to do. The who-line remains + frozen until the next time it is explicitly + changed. If the job selected disappears, strange + things may be displayed. +[ESC]3W moves the who-line to a different job with + the same uname as the one previously shown. + Repeated use of this command will cycle through + all the jobs with your uname. The who-line is + left frozen on whichever job is reached. +[ESC]4W moves similarly but in the other direction. That + is, it will move back to the job that [ESC]3W + left. +[ESC]5W selects the system who-line. + +[ESC]U selects the user wholine, for job number . + The job need not be part of your tree. + + + 3. PROGRAM CONTROL OF WHO-LINES. + + a. The Variables. + +Two variables, WHMODE and WHJOB, contain the information +about which mode of who-line display is selected. +WHMODE is interpreted as follows: + +-1 no who-line display. +0 user who-line, migrating with tty. +1 user who-line, frozen on a particular job + whose job number is in WHJOB. +4 system who-line. + +(2 and 3 are transitory states that occur while [ESC]3W or +[ESC]4W is waiting to be processed. [ESC]W actually works +by putting its argument plus 1 into WHMODE). + + b. System Calls. + +The WHOLIN symbolic system call is used for reading and +writing the two variables WHMODE and WHJOB. Its first +argument specifies the tty to be used. The second and third +arguments are optional; if present, they will be used to set +WHMODE and WHJOB. In any case, two values are available: +the previous values of WHMODE and WHJOB. +If only one argument is given, the tty may be specified by +number, since it is not being modified. If two or three args +are given, the tty must be specified by a channel. +If the tty specified is not a TV, the call will fail with a +"wrong type device" error. + +For example, to put the old values in FOO and FOO1, and +freeze the who-line on the job whose number is in BAR1: + + .CALL [ SETZ + 'WHOLIN + 1000,,TYIC ;IMMEDIATE TTY CHANNEL ARGUMENT. + 1000,,1 ;NEW WHMODE = FREEZE ON JOB. + BAR1 ;JOB TO LOOK AT. + 2000,,FOO ;STORE OLD WHMODE. + 402000,,FOO1] ;STORE OLD WHJOB. + .VALUE + ... + + c. Use of the TCTYP Program. + +The TCTYP program when asked to describe a tty fully, or when +a tty's WHMODE is not -1, will print out "WHOLINE=" followed by +one plus the value of WHMODE (in other words, the argument to +[ESC]W needed to put the tty in the state it is in). The command +"WHOLINE" is also available; it takes an argument and acts like +[ESC]W, except that 1) it may be put in init files and valret +strings, while [ESC]W cannot, and 2) giving the WHOLINE command +an argument of 3 or 4 does not produce useful results. + +Thus, if you like having a who-line, +:TCTYP WHOLINE 1 +in your init file will give you one automatically. + + +B. FEATURES FOR PROCESSING WHAT IS ON A TV SCREEN. + +What is sent to an ordinary terminal is unknowable to the +system unless specially remembered. That is not true +of TV terminals. Some standard facilities for processing +the contents of TV screens appear below. Of course, any +program may examine TV screens simply by mapping their +pages. + + 1. THE HARD COPY PRINTER. + +There exists a device for making a printed reproduction of +whatever appears on a TV screen. To use it, type [ESC]Q, +which causes one copy to be made immediately. If the device +is in use, the screen will flash and no action will be taken. +The process lasts 16 seconds; nothing prevents the screen from +changing during that period, and if such a thing happens the +results will be interesting. When the copy is finished, the +screen will flash. Thus [ESC]Q always flashes the screen, +but faster if you're losing. If an infix argument is given as +for [ESC]S (see below), then the specified video input is copied. +This command can be used even on non-logged-in keyboards. + + 2. RECORDINGS. + +The system program RECORD will make an ascii file out of +whatever is on the TV screen. To use it, just type +RECORD^K at DDT. The file is called RECORD > +and goes on your default directory (the MSNAME). + +Other more sophisticated programs for handling TV bit maps +may be found documented in AI:.INFO.;TVXGP INFO. + + 3. SPYING. + +When using a TV terminal, it is possible to spy on any other +TV terminal. This operates by routing a different video memory +through the video switch to your screen. Doing this does not +affect your programs in any way - their output continues to +be placed in your own video buffer and will be visible when +you stop spying. Also, spying does not affect the handling +of input in any way. +These commands can be used even on free keyboards. +[ESC]S on free keyboards, and [ESC]F on keyboards that are in use, +will time out after 40 seconds and an automatic [ESC]S will be done +to make the screen show its default picture once again. +Any character typed will make that happen prematurely. + +The commands are: + +[ESC]S begins spying. The number should be the number + of the terminal to spy on; thus, [ESC]64S spies + on TTY T64. If the specified tty is not in use, + the command is a no-op. + may also be 200 plus the number of a video buffer. + This makes it possible to spy on a screen that nobody + is currently using. + may also be a video switch input number, + for those of you who are hardware hackers. + +[ESC]S stops spying. You are again viewing your own + video buffer. + +[ESC]F spies on the video buffer used for logged-out consoles + (this is the one with the useful information from + the NAME dragon). + +C. OTHER TV FEATURES. + + 1. COMPLEMENTING THE SCREEN. + +The last PDP-10 word of every display memory is used to hold +various information on how the contents of the memory should +be modified on their way to the screen. The 200000 bit of the +word controls complementation of the screen; if the bit is +on the screen appears black on white. This bit may be complemented +by the user with the command [ESC]C. Programs may, of course, +change the bit easily by accessing the display pages. + + 2. CLEARING THE SCREEN COMPLETELY. + +[ESC]L is guaranteed to clear every bit of the display memory, +and also reset the scroll-register (don't worry if you don't +understand that). ^L usually does a good enough job, so this +command is hardly ever necessary. If ^L doesn't clear the +screen (because a program has turned it off), ^_L will clear it. + + 3. THE REPEAT KEY. + +[ESC]R is the "repeat key"; it causes the previous input +character to be sent to the PDP-10 8 times a second, forever, +or until a character is typed on the keyboard (escape commands +not included). The character that stops the repeat will be +ignored as input, unless it is CALL. + +[ESC]R, where is an OCTAL number, will repeat the +previous input character times (or until stopped by +the typing of a character). can't be more that 177 (octal). + + 4. \ No newline at end of file diff --git a/doc/sysdoc/usets.119 b/doc/sysdoc/usets.119 new file mode 100755 index 00000000..fca6b96e --- /dev/null +++ b/doc/sysdoc/usets.119 @@ -0,0 +1,1405 @@ +ITS USETS: + +This file attempts to maintain up-to-date documentation on +all user variables hacked by .USET/.SUSET. Those wonderful +souls who update the information in any way (additions, +deletions, corrections) should describe their +modifications in a brief note to INFO-ITS@AI so +that interested parties can correct their copies or +conceptions without needing to print or read the +entire file again. For example: + + :QMAIL INFO-ITS@AI I added more details to the .FOO user var ^C + +If you want to be put on the INFO-ITS mailing list, +just say so in a message to it. +------------------------------------------------- +Each job running under ITS has a large number of variables +associated with it maintained by the system. In order to +examine and set these variables, the .USET and .SUSET +uuo's are provided. The .USET uuo allows the specification +of the job whose variables are to be accessed. The .SUSET +uuo always accesses the variables of the job which executes it +(SUSET = Self USET). + +The .USET uuo is used like this: .USET CHNL,SPEC +and the .SUSET uuo like this: .SUSET SPEC +The ac field CHNL of the USET must be the number of +an input/output channel for which a job is open, +as either the USR, JOB, or BOJ device. +The .USET may modify the variables only +if it has modification rights to the job (the job +is a JOB device, or is a direct inferior). + +The contents of the effective address SPEC are of this form: + 4.9 0 = read variable, 1 = set variable. + 4.8 Block mode (see below). + 4.7-3.1 Number of user variable to access. + 2.9-2.1 Address of a location within the caller which + is to receive the value of the variable, or which + contains the new value for the variable. +If bit 4.8 is 1, then the word at location SPEC is really +an AOBJN pointer to a block of specifications. This is +useful for getting several variables at a time easily. +The AOBJN pointer is updated as the operation progresses, +and so must be in a writable area. Block mode may not be nested. +If an illegal specification is given to .USET or .SUSET, +the job will receive an illegal operation word 1 interrupt +(bit 1.6 of the .PIRQC user variable). + +The variables are described in this document by the names which +DDT knows for them; the first character of each name is a ".". +If you open up a location by using one of these names, DDT +treats it specially and actually accesses the corresponding +variable and not a location in the job's core. + +When writing .USET's and .SUSET's in MIDAS code, +one may use the symbols defined by MIDAS for accessing them. +These are the same as the names known to DDT, except that +the "." is followed by "R" for reading or "S" for setting. + +If you open a location containing a SPEC, try typing +.R$?? if it is positive, or .S$?? if it is negative; this will +use bit typeout mode to print out the spec as it might have been +assembled; for example, 400001,,500 .S$?? gives .SVAL,,500 . + +Examples: + +To read your own runtime in 4-microsecond ticks into FOO: + + .SUSET [.RRUNT,,FOO] + +To set your word 1 interrupt mask: + + .SUSET [.SMASK,,[%PIDWN\%PIPDL]] + ;enable "pdl overflow" and "sys going down" interrupts + +To read your input/output status word for channel 13 into FOO: + + .SUSET [.RIOS+13,,FOO] + +To start a job (your immediate inferior!) open on channel + USRC at its location QUUX, with its option + bits indicating your readiness to supply JCL: + + .USET USRC,[.SOPTION,,[%OPCMD,,]] + .USET USRC,[.SUPC,,[QUUX]] + .USET USRC,[.SUSTP,,[0]] + +Another way to do the same thing is: + + MOVE AC,[-3,,USBLOK] + .USET USRC,AC + . . . +USBLOK: .SOPTION,,[%OPCMD,,] + .SUPC,,[QUUX] + .SUSTP,,[0] + +FORM OF DESCRIPTIONS: + +The descriptions of the various variables accessible by +.USET and .SUSET are in the following form: + + + + + +The descriptor contains four characters "wx yz". +The first two ("wx") refer to the access for .USET; +the last two ("yz") to the access for .SUSET. +In each case these characters are chosen from these sets: + -- May neither read nor set. + +- May read but not set. + +* May read and set. + +? May read, may sometimes set (please read on...) +That is, + means may read, * may set, - denies access, +while ? says that things are more complicated. + +.40ADDR +* +* "40" address + + The right half: + + Initially 40 octal. Whenever the system + references locations "40" through "44" specifically, + (e.g. giving the user interrupts, or returning uuo's 50-77), + the system really references the 5-word block that + .40ADDR points to. Thus, if .40ADDR is set to 500, the + system expects location 502 to contain the address of + the interrupt routine. This is especially useful to + distinguish system-returned uuo's (0 and 50-77) from + standard user-mode uuo's (1-37); the latter always + trap through location 40, while the former trap + through .40ADDR. + The various words accessed through .40ADDR are + as follows (indexed by "normal" location #): + 40 System places a uuo here when it wants + to give it to the user. + 41 Should contain the address of the uuo handler. + If .40ADDR is not indeed 40, this + may be a different uuo handler from the + one which handles uuo's 1-37. + If .40ADDR is actually 40, then unless + 41's index and indirect fileds are 0 and its + opcode is either 0 or JSR, all system-returned + UUOs will cause ILOPR interrupts instead. + This is to protect programs that want their + hardware user-UUOs to be handled by a PUSHJ + from being clobbered when they accidentally + execute a meaningless UUO. + 42 If the job's %OPINT bit in its + .OPTION variable (q.v.) is 0, then + this is a JSR to the user's old-style + interrupt handler. The three words addressed + by the JSR are, in order, the word in + which the interrupt bits are placed, the + return address for the interrupt, and the + first instruction of the handler. + If the %OPINT bit is 1, then this + is an AOBJN pointer to a vector of + 5-word blocks describing the various + interrupt handlers and their priorities. + See ITS INTRUP for details. + 43 If the job's %OPLOK bit is set in + its .OPTION variable, then this is + the pointer to the list of switches + to be reset if the job is killed. + 44 If the job's %OPLOK bit is set, + this is an AOBJN pointer to a block + of critical code region descriptors. + See ITS LOCKS for details. + + The left half: + + Initially 20 octal. This is the address of a block of + 20 octal words which a job's superior may use to hack + that job. For compatibility, if LH(.40ADDR) is zero, + the default of 20 will be assumed. + +.ADF1 +* +* ANDCAM into .DF1 + + Like .DF1 (q.v.) when reading. + Performs ANDCAM into .DF1 when writing. + + +.ADF2 +* +* ANDCAM into .DF2 + + Like .DF2 (q.v.) when reading. + Performs ANDCAM into .DF2 when writing. + + +.AIFPIR +* +* ANDCAM into .IFPIR + + Like .IFPIR (q.v.) when reading. + Performs ANDCAM into .IFPIR when writing. + + +.AMASK +* +* ANDCAM into .MASK + + Like .MASK (q.v.) when reading. + Performs ANDCAM into .MASK when writing. + + +.AMSK2 +* +* ANDCAM into .MSK2 + + Like .MSK2 (q.v.) when reading. + Performs ANDCAM into .MSK2 when writing. + + +.APIRQC +* +* ANDCAM into .PIRQ + + Like .PIRQC (q.v.) when reading. + Performs ANDCAM into .PIRQC when writing. + +.APRC +- +- APR CONO + + 4.9 Procedure is in a disowned tree. + 4.7 (BUMRTL) Tree will be gunned if hasn't run for an hour + (meaningful only in top level job). Cleared by reowning or + attaching. See the DETACH and DISOWN system calls. + 4.6 Core request pending for this job. + 4.5 User disabled, waiting to be flushed by SYS job. + The SYS job will delete the job tree eventually. + 4.4-4.1 .BCHN user variable (q.v.). + 3.9 In process of deleting or logging out this job. + Bit 4.5 will probably be set eventually. + 3.5-3.1 Must be zero. + 2.9-1.1 CONO'ed to APR whenever job is about + to be run. Initially 447. Modified by + altering the .MASK user variable. + + +.BCHN +* +* bad channel number + + Initially 0. + Number of channel most recently in error. + Typically after reading this variable one does a + .STATUS or a STATUS symbolic system call + to get the status word for the channel. This word + can then be fed to the ERR device. + .BCHN is actually part of the .APRC variable. + See also the .IOS variable. + + +.CNSL +- +- console tty number + + If the job is in a console-controlled tree, this + variable contains the console's number, even if + the job doesn't own the console. If the job is + in a non-console-controlled tree, .CNSL is -1 + if the job is scheduled as part of the system, + -2 if the job is scheduled as a disowned job; + for a job-device-handler job, .CNSL is the same + as it is for the job it is serving. + + +.DF1 +* +* defer bits, word 1 + + Initially 0. + Defer bits for word 1 interrupts (see .PIRQC + and .MASK). If an interrupt bit is set in both + .PIRQC and .MASK, but is also set in .DF1, + it is temporarily deferred. + + +.DF2 +* +* defer bits, word 2 + + Initially 0. + Defer bits for word 2 interrupts (see .IFPIR + and .MSK2). If an interrupt bit is set in both + .IFPIR and .MSK2, but is also set in .DF2, + it is temporarily deferred. + +.EBO1 +- +- KL-10 Ebox counter + + This is the low-order word of the KL-10 Ebox counter + value for the job. It contains garbage on KA-10's. + Its location is .EBOX+1, for convenience. + + +.EBOX +- +- KL-10 Ebox counter + + This is the high-order word of the KL-10 Ebox counter + value for the job. It contains garbage on KA-10's. + + +.FLS +- -- flush instruction + + Initially 0. + The instruction which is blocking the running of + the job. Zero if user not blocked (user can run + if .USTP is also zero). + (The scheduler tests a job for runnability by first + checking the .USTP variable, and if it is zero, + then executing the flush instruction. The job is + runnable iff the flush instruction skips.) + + +.FTL1 +- +- Fatal interrupt first word + + After a fatal interrupt, this variable contains the + .PIRQC bits which caused the error. At any other time + it contains garbage. + +.FTL2 +- +- Fatal interrupt second word + + After a fatal interrupt, this variable contains the + .IFPIR bits which caused the error. At any other time + it contains garbage. + + +.HSNAME +* +* Home System Name + + This is a word of sixbit like .SNAME (q.v.). It + is initialized to be the same as the UNAME on creation + of a not-logged-in tree, and when a job is created + as an inferior or as a job device, it's .HSNAME is + copied from that of it's creator. The LOGIN system call + sets it to be the same as the UNAME, although this should + be changed to be the XUNAME. + + This is not used by ITS for anything, but is intended to + associate a directory with a specific XUNAME for the sake + of init and mail files of people without a directory of + the same name as their XUNAME. DDT will soon initialize + it by looking up information in the INQUIR database for + the particular user. + +.IDF1 +* +* IORM into .DF1 + + Like .DF1 (q.v.) when reading. + Performs IORM into .DF1 when writing. + +.IDF2 +* +* IORM into .DF2 + + Like .DF2 (q.v.) when reading. + Performs IORM into .DF2 when writing. + + +.IFPIR +* +* inferior procedure and i/o requests (?) + + Initially 0. + This variable contains bits for pending word 2 interrupts. + + Bit 3.n is the interrupt bit for the n'th job directly + inferior to the specified job (see the .INTB user variable). + These therefore occupy bits 3.8-3.1. + An inferior interrupt bit is set if an a class 1 + or untrapped class 2 interrupt occurs in the inferior, + or if the inferior is using new-style interrupts + (see ITS INTRUP, and the %OPINT bit of the .OPTION + user variable) and any unhandled interrupt occurs. + Performing a .UCLOSE on an inferior clears the + inferior interrupt bit in the .IFPIR variable + of the job performing the .UCLOSE. + + Bit 1.n is the interrupt bit for input/output + channel n-1 (actually, these occupy bits 2.7-1.1). + Thus bit 1.1 = channel 0, 1.2 = channel 1, + 1.3 = channel 2, . . ., bit 2.7 = channel 17. + When an input/output interrupt is detected, the + system call WHYINT shoud be used to discover the + cause (see ITS .CALLS). + + The following devices can cause channel interrupts: + + TTY Input: A character was typed which according + to the job's TTYST1 and TTYST2 variables + (see ITS TTY) should be treated as an interrupt + character. If the tty is opened for input + on more than one channel, only one channel, + if any, receives the interrupt. + Output: The **MORE** condition has occurred. + See ITS TTY. + STY Input: Input is pending (i.e. the corresponding TTY + has attempted output). If the STY is open + for input on more than one channel, only + one channel, if any, receives the interrupt. + See ITS TTY. + Output: The STY's alter ego is waiting for input, + or at least was (it isn't guaranteed not to + stop waiting and do something else). + STK Input is available. Interrupts occur on all enabled channels. + USR A foreign job open on the channel has been killed. + If the job went away while the channel was pushed + on the I/O pdl, this interrupt will occur when the + channel is popped. See the .UCLOSE, .IOPUSH, and + .IOPOP uuo's. + If the job is the PDP-6, the PDP-6 has requested an interrupt. + JOB Various conditions, some programmable. See ITS JOB. + BOJ Various conditions, some programmable. See ITS JOB. + NET One of the following conditions has occurred: + The IMP has gone down. + RFC received. + After RFC sent, the connection is now open. + Input available. + Connection closed. + Net interrupt received (INR or INS). + MSP Message has been sent. + +.IIFPIR +* +* IORM into .IFPIR + + Like .IFPIR (q.v.) when reading. + Performs IORM into .IFPIR when writing. + + +.IMASK +* +* IORM into .MASK + + Like .MASK (q.v.) when reading. + Performs IORM into .MASK when writing. + + +.IMSK2 +* +* IORM into .MSK2 + + Like .MSK2 (q.v.) when reading. + Performs IORM into .MSK2 when writing. + + +.INTB +- +- interrupt bit + + Gets the interrupt bit for the procedure. This is + the word 2 interrupt bit which the procedure's + superior will see when the procedure interrupts + its superior. This variable will therefore have + exactly one of bits 3.1-3.8 set, and no others. + If the procedure is top level (has no superior), + then this variable is negative. + + +.IOC + +- +- input/output channel + + The variable .IOC+ is the input/output channel + word for channel , for n between 0 and 17 octal. + Normally zero for a closed channel. + + +.IOP + +- +- input/output pdl + + The input/output pdl is a pdl of two-word entries + used by the .IOPUSH, .IOPOP, and .IOPDL uuo's. + The first word of each pair is the .IOC word for + the stacked channel, and the second is the .IOS word. + In addition, bits 4.9-4.6 of the .IOS word of each + pair contain the channel number which the channel was + pushed from (this is used by the .IOPDL uuo). + The pdl has eight entries; thus should be between + 0 and 17 (0 is the .IOC word for the least recently + pushed entry, etc.). + +.IOS + +- +- input/output status + + The variable .IOS+ is the input/output status + word for channel , for between 0 and 17 octal. + Normally zero for a closed channel. + This word contains various bits describing the status + of the channel. The left half is a set of error + codes if non-zero; the .IOS word can be given to + the ERR device to obtain an ascii message for + the error. The right half contains various bits + describing the state of the device. (Internally to + ITS, the right half contains an access pointer; + the right half bits supplied for .IOS are the + same as those generated by the .STATUS uuo or + the STATUS symbolic system call.) + + The various bits in the .IOS word are as follows: + 4.9-4.6 Always zero (see the .IOP variable). + 4.5-4.1 If non-zero, the number of a non-display + input/output error (see table below). + 3.9-3.7 If non-zero, the number of an IDS interpreted + display input/output error (see table below). + 3.6-3.1 If non-zero, the number of a standard error. + Set primarily by failing .OPEN's and + .FDELE's. These are the same as the error + codes returned by failing .CALL's (see + table below). + 2.9-2.3 Device dependent. + 2.2 Buffering capacity empty. + 2.1 Buffering capacity full. + 1.9-1.7 Mode in which device was opened. + 1.9 0 = ascii, 1 = image. + 1.8 0 = unit, 1 = block. + 1.7 0 = input, 1 = output. + 1.6-1.1 ITS internal physical device code + (see table below). + + The error messages indicated by bits 4.5-4.1 are: + 1 DEVICE HUNG OR REPORTING NON-DATA ERROR + 2 END OF FILE + 3 NON-RECOVERABLE DATA ERROR + 4 NON-EXISTENT SUB-DEVICE + 5 OVER IOPOP + 6 OVER IOPUSH + 7 USR OP CHNL DOES NOT HAVE USR OPEN + 10 CHNL NOT OPEN + 11 DEVICE FULL (or directory full) + 12 CHNL IN ILLEGAL MODE ON IOT + 13 ILLEGAL CHR AFTER CNTRL P ON TTY DISPLAY + 14 DIRECTORY FULL + 15 DIRECTORY'S ALLOCATION EXHAUSTED + + The error messages indicated by bits 3.9-3.7 are: + 1 IDS ILLEGAL SCOPE MODE + 2 IDS SCOPE HUNG + 3 MORE THAN 1K SCOPE BUFFER + 4 IDS MEM PROTECT + 5 IDS ILLEGAL SCOPE OP + 6 IDS MEM PROTECT ON PDL PNTR + 7 IDS ILLEGAL PARAMETER SET + + The error messages indicated by bits 3.6-3.1 are: + 1 NO SUCH DEVICE + 2 WRONG DIRECTION + 3 TOO MANY TRANSLATIONS + 4 FILE NOT FOUND + 5 DIRECTORY FULL + 6 DEVICE FULL + 7 DEVICE NOT READY + 10 DEVICE NOT AVAILABLE + 11 ILLEGAL FILE NAME + 12 MODE NOT AVAILABLE + 13 FILE ALREADY EXISTS + 14 BAD CHANNEL NUMBER + 15 TOO MANY ARGUMENTS (CALL) + 16 PACK NOT MOUNTED + 17 DIRECTORY NOT AVAIL + 20 NON-EXISTENT DIRECTORY NAME + 21 LOCAL DEVICE ONLY + 22 SELF-CONTRADICTORY OPEN + 23 FILE LOCKED + 24 M.F.D. FULL + 25 DEVICE NOT ASSIGNABLE TO THIS PROCESSOR + 26 DEVICE WRITE-LOCKED + 27 LINK DEPTH EXCEEDED + 30 TOO FEW ARGUMENTS (CALL) + 31 CAN'T MODIFY JOB + 32 CAN'T GET THAT ACCESS TO PAGE + 33 MEANINGLESS ARGS + 34 WRONG TYPE DEVICE + 35 NO SUCH JOB + 36 VALID CLEAR OR STORED SET + 37 NO CORE AVAILABLE + 40 NOT TOP LEVEL + 41 OTHER END OF PIPELINE GONE OR NOT OPEN + 42 JOB GONE OR GOING AWAY + 43 ILLEGAL SYSTEM CALL NAME + 44 CHANNEL NOT OPEN + 45 INPUT BUFFER EMPTY OR OUTPUT BUFFER FULL + 46 UNRECOGNIZABLE FILE (LOAD) + 47 LINK TO NON-EXISTENT FILE + + The physical device codes from bits 1.6-1.1 are as + follows. Note that, as a half-hearted rule, bit 1.6 + indicates that file names are significant, and bit 1.5 + indicates a software-implemented device. + This list is subject to additions and deletions! + CODE SYMBOL DEVICE DESCRIPTION + 0 TTY Console input. + 1 SNTTY TTY Printing console output. + 2 SNTDS TTY Display console output. + 3 SNLPD LPT Data Products line printer. + 4 SNVID VID Vidisector ??? + 5 SNBAT Vidisector ??? + 6 SNPLT PLT Calcomp plotter. + 7 SNPTP PTP Paper tape punch. + 10 SNIMPX IMX Input multiplexor. + 11 SNOMPX OMX Output multiplexor. + 12 SNPTR PTR Paper tape reader. + 13 SN340 DIS DEC 340 display, Ascii output. + 14 SN340I IDS Interpreted 340 display. ??? + 15 SNMTC MTn Magnetic tape. + 16 SNCOD COD Morse code device. + 17 SNTAB TAB Tablet. ??? + 21 SNNUL NUL Source of zeroes, or output sink. + 22 SNJOB JOB Job device. + 23 SNBOJ BOJ Inverse of JOB. + 24 SNSPY SPY Spy on another console. + 25 SNSTY STY Pseudo-teletype. + 26 SNNET NET ARPAnet (NCP). + 27 SNLPV LPT Vogue line printer (yech!) + 30 SNSTK STK Stanford keyboard. + 31 SNMSP MSP (DM) Interprocess message protocol. + 32 SNCHA CHAOS CHAOS net. + 33 SNTCP TCP TCP Internet. + 34 SNTRAP TRAP Trap "device" + 35 SNIPQ IPQ Internet IP Queue. + 41 SNUTC UTn Microtape (DECtape). + 43 SN2311 DSK 2311 disk drives or equivalent. + 60 SNFUSR USR A foreign (not immediately inferior) procedure. + 61 SNUSR USR An immediately inferior procedure. + 62 SNCLK CLx Various core link devices (x  {AIOU}) + 63 SNDIR --- File directory or ERR device. + 64 SNPDP USR The PDP-6. + 65 SNDIRH DIRHNG Directory hang "device" + 66 SNLCK LOCK Lock "device" + +.IPIRQC +* +* IORM into .PIRQC + + Like .PIRQC (q.v.) when reading. + Performs IORM into .PIRQC when writing. + + +.JNAME +* +? job name + + The name of the job as a word of sixbit characters. + The uname-jname pair must be unique to a job + (there are some exceptions involving system-created + jobs or jobs not logged in). + The uname and jname are used as file names when + creating or subsequently opening the job on the USR + device. See also the .UNAME user variable. + The .JNAME variable may be set by a .SUSET only in a + top-level job, and then only if the job has no + inferiors. + Attempting to set a jname to zero causes an + illegal operation interrupt (bit 1.6 of the .PIRQC + user variable). So does attempting to set it such that + the uname-jname pair would no longer be unique. + So does attempting to illegally set one's own jname. + + +.JPC +* +* jump program counter + + The PC as of the most recent jump instruction, + i.e. an instruction which changed the PC by other + than 1 or 2. This is actually a register in the + paging box when running. + + +.MARA +* +* MAR (memory address register) address + + Initially 0. + The address for the MAR register in the paging box, + which gives a %PIMAR interrupt when the specified operation + is performed on the specified address. + 3.3 0 = exec mode, 1 = user mode. + This is forced to 1 when set with + .SUSET or .USET; exec mode is for very + obscure system hacks only. + 3.2-3.1 0 Never interrupt. + 1 Interrupt on instruction fetch. + 2 Interrupt on write. + 3 Interrupt on any reference. + 2.9-2.1 Address for MAR. + The MAR does not work well on accumulators. + See also the .PIRQC user variable, bit %PIMAR; + and ITS INTRUP and ITS USR. + +.MARPC +* +* MAR program counter + + The PC as of the instruction that most recently + tripped the MAR interrupt, if any. In addition, + the indirect bit will be set if that instruction + completed successfully (was not aborted by the MAR + hit). See the .MARA user variable. + + +.MASK +* +* word 1 interrupt mask + + Initially 0. + This is a mask for word 1 interrupts which indicates + which interrupts the job is prepared to handle. + If a class 2 or class 3 word 1 interrupt tries to + occur, but the corresponding bit in .MASK is not + set, then the interrupt is converted to class 1 or + ignored, respectively. The bits in .MASK directly + correspond to those in .PIRQC (q.v.). Bits for class + 1 interrupts are AND'ed out before setting the .MASK + variable. + + +.MBO1 +- +- KL-10 Mbox counter + + This is the low-order word of the KL-10 Mbox counter + value for the job. On KA-10's, it holds garbage. + Its location is .MBOX+1, for convenience. + + +.MBOX +- +- KL-10 Mbox counter + + This is the high-order word of the KL-10 Mbox counter + value for the job. On KA-10's, it holds garbage. + + +.MEMT +* +* memory top + + This variable contains 1 plus the highest legal + address in the job (the accessible word with the + largest address). Setting this variables is like + performing an equivalent .CORE uuo (q.v.): + .SUSET [.SMEMT,,[FOO]] + is like doing: + .CORE _12 + + +.MPVA +- +- memory protect violation address + + The address which the last instruction to cause a memory protection + violation (or a write into read only memory violation) attempted to + reference, on KA-10's rounded down to a page boundary. Thus an + attempt to reference the non-existent location 317435 would cause + .MPVA to be set to 316000 octal on a KA-10, or 317435 on a KL-10. + + On the KS-10, .MPVA also holds the non-existant IO register address + after a %PINXI. + + See also the .PIRQC variable. + +.MSK2 +* +* word 2 interrupt mask + + Initially 0. + This is a mask for word 2 interrupts which indicates + which interrupts the job is prepared to handle. + If a class 2 or class 3 word 2 interrupt tries to + occur, but the corresponding bit in .MSK2 is not + set, then the interrupt is converted to class 1 or + ignored, respectively. The bits in .MSK2 directly + correspond to those in .IFPIR (q.v.). + + +.OPC +- +- old program counter + + The PC just before the last instruction was executed. + This corresponds to a register in the paging box. + It doesn't exist on KL-10's. + +.OPTION +* +* option bits + + Initially 0. + The bits in this word correspond to various options + as follows: + 4.9 %OPTRP Same as the .UTRP user variable. See ITS UUO. + 4.8 %OPDET ** This bit is OBSOLETE and NO LONGER EXISTS ** + It is documented for historical purposes only. + Nowadays, fatal interrupts always cause top-level + jobs to be detached. Once upon a time, top-level + jobs with consoles would be reloaded instead of + detached, unless they had set %OPDET=1. + See the DETACH and RELOAD symbolic system calls. + 4.7 %OPDEC Uuo's 40, 41, and 47 (that is, + .IOT, .OPEN, and .ACCESS) + should trap to the user as uuos + via the .40ADDR user variable (q.v.). + This is useful for programs which wish to + interpret DEC TOPS-10 UUO's, since those are the + only ones which conflict with ITS UUOs. + Luckily, those ITS UUOs are not essential since + there are symbolic system calls to do the same things. + 4.6 %OPCMD Superior claims it has JCL which + it will cheerfully supply in response to + the appropriate .BREAK 12, command. + 4.5 %OPBRK Superior claims to handle all .BREAK's. + 4.4 %OPDDT Superior claims to be DDT. + 4.3 %OPINT Job desires new-style (vectored + and stacked) interrupts. See also the + .40ADDR variable. See ITS INTRUP for + information on old- and new-style + interrupts. + 4.2 %OPOJB Other jobs may open this job + as the OJB device, thereby turning it + into a JOB device. See ITS JOB. + 4.1 %OPLOK Job desires the switch locking + and unlocking synchronization feature. + See also the .40ADDR variable. + See ITS LOCKS for information on locks. + 3.9 %OPLIV The job tree of which this is the + top-level job is permitted to survive a + system shutdown -- it should take care + of logging itself out. See the .SHUTDN uuo. + Meaningful only for top-level jobs. + Primarily useful for system demons which need to + survive system death (e.g. the statistics + demon PFTHMG DRAGON). + 3.8 %OPOPC Job desires that instruction-aborting interrupts + such as MPV leave the PC pointing before the + instruction that lost, instead of the old + convention of leaving it pointing after. + The new convention is far better and all new + programs should use it. + 3.7 %OPLSP Superior claims to be MacLisp. + 3.6 %OPLKF Unlock locks on fatal interrupt. When a + non-disowned top-level job receives a fatal + interrupt, if it has set this bit, its locks will + be unlocked by the system job as part of the + process of detaching it. See the %OPLOK bit and + ITS LOCKS. + +.PAGAHEAD +* +* page-ahead control + + Normally zero, this word is set nonzero to enable + sequential paging through a part of the address space + specified by .PAGRANGE. The right half of .PAGAHEAD is + the page-ahead interval width and the left half is the page-behind + distance. Each time a page in the designated range is + touched for the first time, the next few pages, forming the + page-ahead interval begin to swap in, and a page a certain + distance behind (specified by the page-behind distance) is + swapped out or marked for swap out in the near future. The + precise treatment depends on how loaded the system is. + + Exactly one of the page-ahead interval width and the + page-behind distance should be negative. The page-behind + distance should be negative, if memory is being used from low + addresses to high ones. The page-ahead width should be + negative if moving from high addresses to low ones. + + Example: -2,,4 means on first reference to page n, start + reading in pages n+1 through n+4 and possibly swap out page n-2. + Page n-1 is not affected until page n+1 is touched. A + page-behind distance of 2 means that two consecutive pages are + always available. + +.PAGRANGE +* +* page-ahead range + + Normally zero, this word is made nonzero together with .PAGAHEAD + to enable the sequential paging feature. The two halves of + .PAGRANGE are page numbers which specify the region of the + address space in which sequential paging should go on. + The left half specifies the first page in the sequentially + paged region, and the right half specifies the first page + after the end of that region. + +.PICLR +* +* priority interrupt clear + + Initially -1. + If non-zero, the job may take interrupts. If zero, + interupts are deferred. This variable is cleared + when an old-style interrupt occurs (but not by new-style + interupts!), and is set to -1 by the .DISMISS uuo + and the DISMIS symbolic system call. Attempts + to set this variable will convert the value to -1 or 0 + depending on bit 4.9. + + +.PIRQC +* +* priority interrupt request cruft (?) + + This word contains bits for pending word 1 interrupts. + Setting bits in this causes the corresponding interrupts + to attempt to take place, subject to .MASK, .DF1, + .PICLR (q.v.), and the %OPINT bit of the .OPTION user + variable (see ITS INTRUP). + + Interrupts are of three classes: + 1 Very serious. The job is stopped and its + superior interrupted. + 2 Semi-serious. The job may request to handle + such an interrupt by setting the corresponding + bit in .MASK (q.v.); otherwise it is treated + as a class 1 interrupt. + 3 Trivial. The job receives the interrupt if it + has requested to handle it; otherwise the + interrupt condition is ignored. (Under the + new-style interrupt scheme, a class 3 interrupt + may become a class 1 interrupt.) + See also the .IFPIR variable for word 2 interrupts. + + The interrupt bits and their classes are as follows. + The character * denotes a class 1 interrupt, and + a + class 2 interrupt. + 4.9 Must be zero. + %PIRLT 4.8 Clock break (see the .REALT uuo). + %PIRUN 4.7 Run time interrupt (see the .RTMR user variable). + %PINXI 4.6 + Non-Existent IO register + A Job in User IOT mode referenced a non-existent IO + register on the KS10 Unibus. The PC is left + pointing before the guilty instruction. The address + of the non-existant register may be found in .MPVA. + %PIJST 4.5 Job Status display request. + The sequence ^_J was typed on the console owned + by this process or some inferior. + %PIDCL 4.4 * A defered call was typed while the job had the TTY. + %PIATY 4.3 The tty was given back to the job by + its superior. Indicates that the screen has + probably been written on and its contents + have changed unpredictably. + %PITTY 4.2 + Attempt to use tty when not possessing it. + %PIPAR 4.1 + Parity error. + %PIFOV 3.9 Arithmetic floating overflow. + %PIWRO 3.8 + Attempt to write into read only memory. + See the .MPVA user variable. + %PIFET 3.7 + Pure page trap (attempt to fetch an instruction from + writable memory when bit 4.2 of the PC set). + This feature doesn't exist on KL-10's, instead + this interrupt is signalled for "Illegal entry + to concealed mode" which you probably can't make + happen. (See the KI10 Processor Reference Manual.) + See bit 4.2 of the .UPC user variable. + %PITRP 3.6 * System uuo to user trap (see the .UTRP user variable). + 3.5 Arm tip break 3 (OBSOLETE). + 3.4 Arm tip break 2 (OBSOLETE). + 3.3 Arm tip break 1 (OBSOLETE). + %PIDBG 3.2 System being debugged. + Occurs when someone uses the .SETLOC or .IFSET uuo + to alter SYSDBG and the new contents are non-zero + and the old contents non-negative. + (See also the SSTATU symbolic system call.) + %PILOS 3.1 + A .LOSE UUO or LOSE system call was executed + (their purpose is to signal the superior). + %PICLI 2.9 CLI device interrupt. + %PIPDL 2.8 Pdl overflow. + %PILTP 2.7 Light pen interrupt on 340. + Program stop or hit stop on E&S display. + %PIMAR 2.6 + MAR interrupt. + (See the .MARA and .MARPC user variables.) + %PIMPV 2.5 + Memory protection violation (attempt to reference + a page not in the job's page map). + (See the .MPVA user variable.) + %PICLK 2.4 Slow clock interrupt (every .5 second). + %PI1PR 2.3 * Single intruction proceed interrupt. + Used by DDT for ^N commands. + %PIBRK 2.2 * Breakpoint interrupt (.BREAK uuo executed). + %PIOOB 2.1 + Illegal user address. (OBSOLETE) + %PIIOC 1.9 + Input/output channel error. + (See the .BCHN and .IOS user variables.) + %PIVAL 1.8 * Value interrupt (.VALUE uuo executed). + %PIDWN 1.7 System going down or being revived. + (See the .SHUTDN, .REVIVE, and .DIETIME uuo's, + and the SSTATU symbolic call.) + %PIILO 1.6 + Illegal instruction operation. + %PIDIS 1.5 + Display memory protection violation (340 or E&S). + %PIARO 1.4 Arithmetic overflow. + %PIB42 1.3 * Bad location 42. + (See the .40ADDR user variable, and ITS INTRUP.) + %PIC.Z 1.2 * ^Z typed when this job had the TTY. + %PITYI 1.1 Character enabled for interrupt was typed on TTY. + (Semi-obsolete; see the .IFPIR user variable, + and ITS TTY.) + +.PMAP + +- +- page map word + + This is the page map word for page of the job, + for between 0 and 377 octal (256.K = 400 1K pages). + The map word read has this form: + 4.9 %CBWRT Page is writable. + 4.8 %CBRED Page exists (if this bit is zero, then the + whole word is zero). + 4.7 ??? Page is in core (as opposed to swapped out). + 4.6 %CBPUB Page is public (any job can write into it + which wants to). + 4.2 %CBLOK Page is locked in core + (inhibited from swapout) + 3.9 %CBSLO Page is in slow memory + (Doesn't work; Moon says it never will) + 3.8-3.1 Number of times the page is shared. + (See the CORTYP symbolic system call, + right half of value 4.) + 2.9-2.1 Absolute page number, or page number in next + sharer in the circular list of sharers. + (See CORTYP, value 3.) + 1.9-1.1 0 Page is absolute. + 777 Page is not shared. + Next sharer in circular list of sharers + is the job with user index . + + +.RTMR +* +* runtime timer + + Initially -1. + If non-negative, the amount of run time remaining until the job + will receive a word 1 runtime interrupt. (See bit %PIRUN of the + .PIRQC variable.) The time is measured in slightly different units + on different CPUs. On the KA in 4.069 microsecond units, on the KL + in 4 microsecond units, and on the KS in 3.9 microsecond units. + + +.RUNT +- +- run time + + Initially 0. + This is the run time used so far by the job, + measured in units of 4 microseconds. + +.SERVER +* +* server job + + Initially -1. + This is the user index of a job that has been given special + permission to modify this job, or -1 if there is no such job. + + This can be used to implement various oddball client/server + protocols between jobs. The client job will request some service + from the server job and will set his .SERVER variable to the server's + user index to allow the service to be performed. + + If the server job is killed, all of the client jobs will have their + .SERVER variables set back to -1. + + Although it is safe to set .SERVER to -1 using .SUSET or .USET, + there can be timing errors if a client loads his .SERVER variable + by simply writing the server's user index into it. Specifically, + during the time the server's user index is sitting in the client's + memory, the server job might be killed and another job started with + the same user index. This can be guarded against by handling + interrupts on the USR: channel, but this is clumsy. A better + method is to use the SSERVE system call. (See .INFO.;ITS .CALLS) + +.SNAME +* +* system name + + This is a word of six sixbit characters which is + the default "directory name" for various input/output + operations. It is initially the same as the job's + .UNAME (q.v.). It can be overridden by supplying the + directory name explicitly to a symbolic system call. + The other uuo's such as .OPEN and .FDELE always use .SNAME. + +.SUPPRO +- +- superior + + This is -1 if the job is top-level, or the user index + of the job's superior. See .UIND. + + +.SV40 +- +- saved 40 + + The contents of absolute location 40 (i.e., the last + uuo that trapped to the system for this job). + See also the .UUOH user variable. + Note that only uuo's 40-47 are really used for + communication with the system. All other uuo's are + handed back to the executing job via its .40ADDR + user variable (q.v.). + + +.TR1INS +? +? Trap 1 instruction. + + This is the instruction to be executed when arithmetic + overflow occurs. Op-code 0 is special, and uses + its E.A. as interrupt bits to turn on in the RH of .PIRQC. + The default contents of .TR1INS are simply %PIARO to + set the overflow interrupt. On the KA-10, writing the + variable doesn't change it. + + +.TR2INS +? +? Trap 2 instruction. + + This is the instruction to be executed when pdl + overflow occurs. Op-code 0 is special, and uses + its E.A. as interrupt bits to turn on in the RH of .PIRQC. + The default contents of .TR2INS are simply %PIPDL to + set the pdl overflow interrupt. On the KA-10, writing the + variable doesn't change it. + + +.TTST +- +- saved TTYSTS + + In a job which does not have the TTY, this variable + holds the saved contents of TTYSTS (what would be in + TTYSTS if the job were given a TTY). This is primarily + useful for examining from DDT. + See ITS TTY for a description of the contents of TTYSTS. + See also the TTYGET and TTYSET symbolic system calls. + + +.TTS1 +- +- saved TTYST1 + + Like .TTST, but for the TTYST1 variable instead of the + TTYSTS variable. + + +.TTS2 +- +- saved TTYST2 + + Like .TTST, but for the TTYST2 variable rather than the + TTYSTS variable. + +.TTY +* +* random TTY variable + + This variable indicates the status of the job with + respect to the console controlling its job tree. + The %TBNVR, %TBINT, %TBWAT, %TBOUT, %TBINF, %TBOIG, and %TBIIN bits + are settable. %TBWAT may be set only by the superior. + 4.9 %TBNOT Does not have TTY now. + 4.8 %TBNVR If 1, an OPEN on the tty will fail + rather than hanging, unless %TBWAT is on. + 4.7 %TBINT An attempt to use the console without owning + it will cause a %PITTY interrupt (LH of + the .PIRQC user variable), unless + %TBWAT is set to 1. + In particular an OPEN on the tty + will interrupt instead of failing or + hanging. + 4.6 %TBWAT If 1, overrides the setting of %TBINT + and %TBNVR, and makes the system act + as if they were 0. Settable only with + .USET. DDT sets this bit when $P'ing a + job, so that even if the job loses the tty + momentarily it will not get upset. + 4.4 %TBDTY If the TTY was taken from the job, + then when it gets it back, this bit says + that the TTY should stay with the job + and not be passed down to an inferior. + 4.3 %TBOUT Allow this job to type out, even if it + doesn't have the TTY. Some operations, + and all input will still require the job + to have the TTY. Not effective unless + the superior enables it by setting %TBINF + in the superior's .TTY var. + 4.2 %TBINF Enable this job's inferiors to take + advantage of their %TBOUT's. + 4.1 %TBOIG Ignore output. Overrides %TBWAT, %TBINT. + 3.9 %TBIIN Interrupt on attempt to do input. Overrides + %TBWAT. + 3.6-3.1 $TBECL Number if echo lines, if the job + doesn't currently have the TTY. + 2.9-1.1 If the job has the TTY, this is the TTY number. + If it doesn't, and doesn't want it, this is the + (internal) user number of the immediately + inferior job to give the TTY to. + +.TVCREG +* +* TV console register + + Initially -1. + This variable is placed in the console register + when the job is run if it is non-negative. + It controls which video buffer memory is used + when writing into the job's tty's TV buffer + (see the CORBLK symbolic system call). + The format of the console register is as follows: + 4.9-4.2 ALU function, used when writing into TV memory: + VALUE SYMBOL FUNCTION + 0 CSETC SETCAM + 1 CNOR ANDCBM + 2 CANDC ANDCAM + 3 CSETZ SETZM + 4 CNAND ORCBM + 5 CCOMP SETCMM + 6 CXOR XORM + 7 CANCSD ANDCMM + 10 CORCSD ORCAM + 11 CEQV EQVM + 12 CSAME SETMM/MOVES/JFCL + 13 CAND ANDM + 14 CSETO SETOM + 15 CORSCD ORCMM + 16 CIOR IORM + 17 CSET SETAM/MOVEM + Note that those symbols are not predefined in MIDAS. + 4.1-3.3 Video buffer number (video switch input number). + See the VIDSW symbolic system call. + + +.UIND +- +- user index + + The unique number assigned to the job by the system + when the job was created. These numbers typically + are between 0 and 77 octal or so (the exact maximum value + is a function of the particular incarnation of the + system). When a job is killed, its user index is + freed for re-use. + Most symbolic system calls which require a job + to be specified will accept 400000+the user index + in lieu of a channel with the job open on it if the + call is only to examine the job and not to modify it. + The .GUN and DETACH commands require a user index. + Jobs 0 and 1 are special in that they always stand for + the system itself and for the CORE job, respectively. + (The CORE job manages core allocation for the system.) + This may have various implications depending on context; + for example, when sharing a page with a job via the + CORBLK symbolic system call, sharing with + job 0 means sharing with an absolute page, and "sharing" + with job 1 means getting a fresh page. + +.UNAME +- +? user name + + A word of sixbit characters which is the user + name of the job. All jobs in a given job + tree must all have the same user name. Furthermore, + a console-controlled tree may not log in if another + console-controlled tree is logged in under the same + uname. When a new console-controlled tree is created + by typing ^Z on a free console, the uname of the newly + created top-level job of the tree is set to "___nnn", + where "nnn" is the user index of the newly-created + job. A non-disowned non-console controlled job is also given + such a uname initially. This may subsequently be changed to + something more reasonable by using the LOGIN symbolic + system call. + The uname of a newly created inferior job is initialized + to the uname of its creator. + If a disowned job tree is re-owned, the unames of all the + jobs in the re-owned job tree are set to the uname of the + re-owning job tree. + The .UNAME user variable may be set only with a .SUSET, and + only by a top level job which has no direct inferiors; + furthermore, attempting to set the uname to zero or the left + half to -1 causes an illegal operation interrupt (bit 1.6 of + the .PIRQC user variable), as does attempting to make the + uname-jname pair of the job non-unique. + See also the .JNAME user variable. + +.UPC +* +- user program counter + + The PC for the job. This word, of course, + contains the PC flags in the left half; + a job may set these flags for itself only by + using JRST 2,@[]. + On KA's, the flags in the left half are as follows: + (- = .USET may not set; % = peculiar to ITS) + %PCARO==400000 Overflow. + %PCCR0==200000 Carry 0. + %PCCR1==100000 Carry 1. + %PCFOV==40000 Floating overflow. + %PCFPD==20000 First part of instruction already done. + %PCUSR==10000 - User mode. + %PCUIO==4000 - User I/O. + %PCPUR==2000 % Pure. Instructions may only be fetched from + read-only memory. See bit 3.7 of the .PIRQC user + variable. This feature is not available on + all machines -- beware! + %PCSPC==1000 - Unused. (A PDP6 feature) + %PC1PR==400 % One proceed. An interrupt will occur at the end + of the next instruction. See bit 2.3 of the .PIRQC + user variable. Used by DDT for ^N commands. + %PCX17==200 % AI KA-10 computer only. Index-off-the-PC hack. + When this bit is set, an index field of 17 means + index off the PC instead of ac 17. + %PCFXU==100 Floating underflow. + %PCDIV==40 No divide. + 3.5-3.1 Always zero. May not be set non-zero. + + On KL's the flags are as follows (note the "|" at the front + of lines that differ significantly from those for KA's): + +| %PSPCP==400000 "Previous Context Public" - this applies only + in exec mode; in user mode this bit is the same + as in KA (%PCARO, Arithmetic overflow). + %PSCR0==200000 Carry 0. + %PSCR1==100000 Carry 1. + %PSFOV==40000 Floating overflow. + %PSFPD==20000 First part of instruction already done. + %PSUSR==10000 - User mode. + %PSUIO==4000 - User I/O. +| %PSPUB==2000 "Public Mode" - not used in ITS +| %PSINH==1000 Inhibits MAR-breaks and trap3 (one-proceed trap) +| for one instruction. +| %PSTR2==400 Set by pdl overflow; causes the "trap 2 instruction" +| to be executed. That instruction is kept in .TR2INS +| %PSTR1==200 Set by arithmetic overflow; causes the +| "trap 1 instruction" in .TR1INS to be executed. +| Both %PSTR1 and %PSTR2 set generates a one-proceed +| trap. +| %PS1PR==160 % %PSINH+%PSTR2+%PSTR1. Setting those bits +| causes a single instruction proceed. + %PSFXU==100 Floating underflow. + %PSDIV==40 No divide. + 3.5-3.1 Always zero. May not be set non-zero. + + The user mode (4.4) is always set to 1. + The user I/O bit (4000, bit 4.3) is set according + to whether the job is in .IOTLSR mode. + + If the .UPC user variable for one job is read by another while + the first is running, an exec mode PC may be seen (bit 4.4 = 0); + this reflects the fact that the job is in the middle + of a system call or something. The .UUOH user variable + should then be examined (this is precisely what DDT does + for the evaluation of .). + +.USTP +* -- user stop bits + + Initially <100000,,>. + If this variable is non-zero, the job is being blocked + from running for one reason or another. If zero, the + .FLS variable controls whether the job may run. + The form of the .USTP variable is as follows: + 4.9 BCSTOP Job is being moved in core. + 4.8 BUCSTP Core job is stopping this job + in order to get more core for another job. + 4.7 BUSRC User control bit. Only this + bit may be modified, and only by the + procedure's superior. Any attempt to + set the .USTP variable non-zero + will set this bit; any attempt to set it + to zero will clear this bit. + 4.6 BSSTP Set while superior is altering the page + map for the job. (Not directly settable + by superior.) + 2.9-1.1 Count of transient reasons for stopping the job. + If non-zero, inhibits relocation of the job by + the core job. + PEEK displays this variable by printing the high six bits + in octal, then a "!", then the rest in octal. This is + why one normally sees "10!0" for a stopped job. + + +.UTRP +* -- user trap switch + + When non-zero, this switch specifies that all uuo's + which trap to the system should, instead of performing + their usual actions, should cause a word 1 class 1 + interrupt to the job executing the uuo. This allows + simulators, etc., to trap all uuo's executed by a job. + An attempt to set this variable will use only bit 1.1. + + This is the same as the %OPTRP bit of the .OPTION user variable. + + +.UUOH +- +- system uuo PC + + The program counter as of the last uuo which trapped + to absolute location 40 (not location 40 in the job, + nor the location specified by .40ADDR!) + See also the variable .SV40. + + +.VAL +* +* value or error code of job + + .VALUE instructions set this word to the contents + of the memory location they address. That is useless. + More importantly, .LOSE instructions, and the LOSE + system call, set .VAL to ,,, so that the superior can decode the + error. + +.WHO1 +* +* user who-line control word + + This variable controls the printing of .WHO2 and .WHO3 + at the end of the TV who-line (see ITS TV). + 4.9 If 1, suppress the who-line entirely when focused + on this job. + 4.8 Suppress space between halves of .WHO2. + 4.7-4.5 Mode for printing left half of .WHO2: + 0 Do not print. + 1 Date in packed form: + 4.9-4.3 Year (mod 100.). + 4.2-3.8 Month. + 3.7-3.3 Day. + 3.2-3.1 Unused. + See the RQDATE symbolic system call, but + note that here the date is shifted. + 2 Time in fortieths of a second, printed in tenths + in the form HH:MM:SS.T. + 3 Time in half-seconds, printed in the form HH:MM:SS. + 4 Octal halfword. + 5 Decimal halfword (no . is supplied). + 6 Three sixbit characters. + 7 Unused. + 4.4-4.2 Mode for printing right half of .WHO2. + 4.1 Print 3.9-3.3 twice (doubled character). + 3.9-3.3 If non-zero, character to print after left half of .WHO2. + 3.2 If 1, suppress the space between .WHO2 and .WHO3 printout. + 3.1 If 1, suppress the space between halves of .WHO3. + 2.9-2.7 Mode for printing left half of .WHO3. + 2.6-2.4 Mode for printing right half of .WHO3. + 2.3 Print 2.2-1.5 twice. + 2.2-1.5 If non-zero, character to print after left half of .WHO3. + 1.4-1.1 Unused. + That is, if the who-line is printed at all, what appears + at the end is these characters: + AAAAXX-BBBB=CCCCYY+DDDD + where: AAAA is the result of printing the left half of .WHO2. + BBBB right half of .WHO2. + CCCC left half of .WHO3. + DDDD right half of .WHO3. + XX one or two characters specified by .WHO1 4.1-3.3. + YY one or two characters specified by .WHO1 2.3-1.5. + - space, unless .WHO1 4.8 is 1. + = space, unless .WHO1 3.2 is 1. + + space, unless .WHO1 3.1 is 1. + Note that the specifications fall neatly into 8-bit bytes + (for the convenience of the PDP-11); hence it is easiest + to specify this word using .BYTE 8 in MIDAS. + Example: + .SUSET [.SWHO1,,[ .BYTE 8 ? 166 ? 0 ? 144 ? 200+", ]] + causes .WHO2 to appear as a word of sixbit, and .WHO3 to + appear as octal halfword typeout in mmm,,nnn format. + + +.WHO2 +* +* first user who-line variable + + See .WHO1 for details. + + +.WHO3 +* +* second user who-line variable + + See .WHO1 for details. + +.XJNAME +* +* "intended" job name. + + This variable holds what the job's name was "intended" + to be, by its creator. Why might the job's name not + actually be what it was intended to be? Perhaps because + that name was already in use by some other job, and the + creator had to find a second choice. For example, when + :NEW T in DDT creates a job named T0 because there was + already a job named T, the job T0's .XJNAME will be "T". + In any case, when using the common technique of having + several programs be links to one file, which figures + out what name it was invoked under and behaves + accordingly, the .XJNAME is the right place to look to + find out what behavior the invoker desires. + + When a job is first created, its .XJNAME is the same as it's .JNAME. + + +.XUNAME +* +* "real" user name. + + This variable holds what says who you really are, + as opposed to what you are logged in as. + It should be a word of sixbit, just like .UNAME. + For example, if you are logged in as FOO1 then + your XUNAME will probably be FOO, because that's + what DDT will normally set it to. However, though + the .UNAME may change because of reowning or attaching, + the .XUNAME will ot change iunless requested specifically. + However, the user may alter DDT's .XUNAME by depositing in + ..XUNAME, which works by informing DDT and having DDT + tell ITS. + Whenever an inferior is created, its .XUNAME is initialized + from its superior's. diff --git a/doc/sysdoc/usr.102 b/doc/sysdoc/usr.102 new file mode 100755 index 00000000..68b1f2b1 --- /dev/null +++ b/doc/sysdoc/usr.102 @@ -0,0 +1,823 @@ +JOBS IN ITS + + +@. ABSTRACT. + +In ITS, a "job" is an entity that consists mainly of memory to hold +a program, registers to run it with, and I/O channels for it to do +I/O on through the system. Whenever a program is +running, it must be running "in" some job. Jobs are structured +into trees; the root of a tree is a "top-level" job, and for any +job, the job one step closer to the root is the first job's superior; +the first job is one of its inferiors. Normally, each user has +one tree of jobs, but he may also have a few other secondary trees. + +Jobs may read anything associated with any job, but usually may write +only their direct inferiors. + +TABLE OF CONTENTS + +A. OVERVIEW OF JOBS. + +B. CREATING AND DELETING INFERIORS, AND OTHER METHODS OF CHANGING THE + 0. OPENING THE USR: DEVICE - A BASIC TOOL. + 1. CREATION + 2. DELETION + 3. DISOWNING + 4. REOWNING + 5. DETACHING + 6. ATTACHING + 7. LOGGING IN + 8. LOGGING OUT AND GUNNING + +C. CONTROL OF INFERIORS. + 1. READING AND WRITING + 2. SHARING MEMORY BETWEEN JOBS + 3. LOADING + a. Resetting + 4. DUMPING + a. Pure dumping + b. Impure dumping + 5. STARTING AND STOPPING + 6. HANDLING INTERRUPTS + 7. DEBUGGING CONTROLS. + 8. TTY PASSING + +D. SYSTEM JOBS AND WHAT THEY DO + 1. THE SYSTEM JOB. + 2. THE CORE JOB. + 3. DEMON JOBS. + +A. OVERVIEW OF JOBS. + +Each ITS job has an address space, the slots of which may be filled +with various types of memory, perhaps shared with other jobs; its own +set of accumulators (copied temporarily into the real ones when the +job is running); a program counter (PC); sixteen I/O channels, each of +which may be used to handle a device or file; system "user variables" +with which the program in the job may communicate with the system; +and other variables used by the system in scheduling +or swapping the job, or as temporaries for system call routines. + +The word "user" has two meanings on ITS: one is the human or other being +using a terminal; the other is an individual "user job". In specific +contexts either "job" or "user" sounds better for their common meaning. +A "program", however, is a more abstract entity; the same program may +be running in several jobs (but using different files, etc. in each). + +Each job is identified by two names, the UNAME and the JNAME, each of +which is up to six SIXBIT characters, left justified in a PDP-10 word. +They are available in the .UNAME and .JNAME user variables of the job. +These two names uniquely identify the job. +All the jobs in a tree must have the same uname. Two trees may have +the same uname; that usually means that they really correspond to the +same user. + +Each job is also uniquely identified by its "job number" (or +"user number"), which is a small positive number. This number +is the usual way to specify a job in a system call. A job may find +out its own number by reading its .UIND user variable; its superior's +is in its own .SUPPRO user variable. The term "user index" +may mean, loosely, the job number, but more strictly it means the +job number times LUBLK, the length of the system's per-job data block +(the "user variable block"). Supported communications paths +between the user and the system use the job number, not the user index +itself, even if the term "user index" is used. + +A job has several "user variables" which are really variables in the +system that pertain to it, and are readable by that job or others +using the .USET and .SUSET UUO's (see ITS UUOS). Each user variable +has a name, which starts with ".". User variables can be opened in +DDT just like memory locations, although what DDT does to access them +is a .USET. Some user variables, such as .UIND, .SUPPRO, .UNAME and +.JNAME mentioned above, exist solely to be read by programs. Others +also allow the program to tell the system how to treat it; examples +are .OPTION, which contains bits that enable various system features, +and .MASK, which is used to enable user interrupts (see ITS INTRUP). +A complete list of user variables and what they contain is in the +file ITS USETS. + +When a user connects to ITS by typing ^Z or CALL on a terminal, he is +supplied with a single top-level job using that terminal, running the +program "DDT" (on DM, "MONIT" is used instead). The jname of that +job is always "HACTRN" (pronounced "hack-tran"), +and the job is called "a HACTRN". The uname +will be three backarrows followed by three digits, identifying the tree +as non-logged-in. "Logging in" is nothing other than altering the uname +of the hactrn to a more meaningful name. It makes little direct +difference. +DDT and MONIT both provide facilities for creating other jobs for the +user, loading programs into them, and running them. There are no user +commands per se for controlling jobs built into ITS; instead, the +user gives commands to DDT or MONIT telling them to execute the system +calls to control his other jobs. + +The two main types of job trees are the console-controlled trees and +the non-console-controlled (or "disconsolate") trees. A console +controlled tree has one terminal which is "in use as a console" by +the whole tree. All the jobs in the tree can refer to that terminal as +device TTY:. The number of that terminal can be found in the .CNSL +variable of any job of the tree. +At any time, only one of the jobs in the tree has +permission to do I/O to the console; that job is said to "own" +the console. Ownership is transferred by means of .ATTY and .DTTY +UUO's executed by jobs in the tree (see ITS TTY). If ^Z (or CALL on +TV's) is typed on a console, the job that owns it gets a fatal +interrupt. The jobs may also have other terminals open "as devices", +but those can be in use only by a single job, not the whole tree. +The console-controlled trees are usually the ones with hactrn's at the +top. + +Disconsolate trees do not have any console, but in all other respects +bahave just like console-controlled trees. They may or may not be +"disowned". If they are, they get worse treatment from the scheduler +and swapper, and also may be more conveniently "reowned" (made into a +subtree of another tree - see below). Usually only system demons and +job-device handlers are disconsolate non-disowned trees. +Job-devices will have a .CNSL equal to that of the tree of the +job using the job-device. Other disconsolate jobs will have a .CNSL +of -1 if they are scheduled as part of the system, or -2 if scheduled +as disowned jobs. + +Jobs often refer to each other using a device, the "USR" device. A job +may be opened on the USR device by specifying its uname and jname as the +opened filenames. It is then possible to examine or deposit the job's +memory or user variables, etc. This is why DDT, when it starts up, +mentions its uname and jname by saying "USR: ". +The USR device should not be confused +with the JOB device, which is a mechanism for creating software devices +which enables the system calls that manipulate the device to be +simulated and handled by a user program, the job-device handler program +(See ITS JOBDEV). + +The remainder of this file is devoted to desribing the ITS system calls +with which jobs may create, delete, sense and control other jobs. + +B. CREATING AND DELETING INFERIORS, AND OTHER METHODS OF CHANGING THE + TREE STRUCTURE OF JOBS. + + 0. OPENING THE USR: DEVICE - A BASIC TOOL. + +Unfortunately, many different things are done by opening the +USR device in different ways in different situations. They +include creation of inferiors, reowning disowned jobs, selection +of existing jobs (inferiors or not), and testing for the existence +of a job. Opening USR is the ONLY way to do those things. What's +more, a job's memory cannot be read or written without having a USR +channel open in the appropriate direction, and a job's user variables +cannot be read or written without at least one USR channel open in +either direction. Thus, opening USR: is very important. It is intended +that this mechanism will be made more rational in the future. + +This section will describe what opening the USR device will do, +organised by how it is done. Later sections will say what +to do to achieve a specific goal. + +By convention, "USRI" and "USRO" are the canonical names in MIDAS +programs for the I/O channels used for opening the USR device for +input and output, respectively. Their use in an inferior-handling +program is a sort of comment. + +A USR: open always specifies two filenames. Normally they are +the uname and jname of the job to be opened. However, 0 may +be used as the first filename to specify your own uname. +If the second filename is 0, then the first is not really a +name but a job spec; this crock makes it possible to open a +job known only by its number. + +A USR: open must also ask for either block mode or unit mode. +Right now SIOT on unit mode USR channels is not as efficient as +IOT on block mode channels, so it is usually better to open in +block mode. In any case, this choice is orthogonal to everything +else. + +All USR: opens should specify image mode. Ascii mode doesn't now +exist for the USR device, and if you ask for it you will get image +mode instead, so for compatibility with the future you should ask +for image mode. + +There are four things specified in each USR open that affect the +actions taken in important ways. They are the two filenames, +the direction, and the device-dependent bit 1.4 of the open-mode, +known here (and inside ITS) as UBPFJ. + +If UBPFJ is set, the open may be for reading only, and will fail with +code 4 if the job specified by the uname and jname does not exist. +If the job does exist, it will be opened as a "foreign job", which +means that the opening job may not modify it at all using the +channel opened in this way. Also, the process of opening the job +with UBPFJ is guaranteed not to alter it. This style of open is +good for asking whether a job exists with particular names. + +Without UBPFJ, if the open is for writing, then +if a job with the specified uname and jname exists and is the + inferior of the job doing the open, it will be opened for + writing, with no special side effects. +If a job with the specified names exists and can be reowned + (it is a top-level disowned job), it will be reowned, and + opened for writing. Reowning may change its uname or jname, + so whenever an open might reown a job the program should + read back the uname and jname of the opened job just in case. +If no job with the specified names exists, then an attempt is + made to create an inferior by that name. If the specified + uname isn't the same as yours, that is impossible, and the open + fails with code 20. If you already have the maximum number of + inferiors, it fails with code 5. If there are no job slots available, + it fails with code 6. If the attempt succeeds, the new inferior + is opened for writing. +Otherwise (a job with the specified names exists, but isn't + an inferior of the running job already and can't be made one + by reowning it), the open fails with code 12. +Note that if an open for writing succeeds, you know the job that +is open is your inferior (thought it might not have been so before). + +An open for reading, without UBPFJ, is like an open for writing +except that when the job exists but isn't an inferior and can't +be reowned, it will be opened as a foreign job (as if UBPFJ were 1). + +To understand these possibilities better, think of the FOO$J command in +DDT, which means, essentially, "open the job named FOO". That command +will reselect a job named FOO if there is one; if not, it will create +one. If there is a job named FOO that isn't a direct inferior of DDT, +it will be selected, but will be unwriteable (DDT will type a "#"). If +there is a disowned job named FOO, it will be reowned (made into an +inferior of DDT), and DDT will type ":$REOWNED$"). + +There is no easy way to tell after the fact what has happened when +an open without UBPFJ has succeeded. You know you have an inferior, +if an open for writing succeeds, +but whether it is new, reowned or old is forgotten. If you care, +you should find out in advance what is going to happen by doing +an open with UBPFJ set. If it fails, you will get a newly created +inferior. If it succeeds, look at the .APRC and .SUPPRO user variables. +If both are negative, you have a top-level disowned job which +would be reowned. If .SUPPRO equals your .UIND variable, the +job is your inferior already. Otherwise, an open for writing +would fail, and an open for reading would open it as a foreign job. + +Some information is still available after an open. +The job's .UPC variable will be nonzero iff the job has ever run +(because the user-mode bit, %PCUSR, will be 1). +If the job has been run, then it certainly wasn't just created. +Also, if the job's uname or jname was changed by the open, then +it must have been reowned. + + 1. CREATION + +In order to create an inferior, one must choose a jname for it. +Its uname will have to be the same as its creator's, and together +the uname and jname must be unique among all jobs in existence. +An attempt to create an inferior looks just like an attempt to +open an existing job, so if the would-be creator is mistaken about +the uniqueness of the jname it may get confused (a way out of this +problem is described later). + +Given a jname which isn't in use, an inferior of that name may be +created by simply opening the USR device with the uname and jname +as filenames, as in section 0. You should open a channel in each +direction (call the input channel USRI and the output channel USRO). +If you are unwilling to try to live with a foreign job, do the +output open first. + +One way to make sure of getting a newly created job is to check +in advance that the names are not in use, by opening them with +UBPFJ (see section 0) before actually trying to create the job. +If the test open succeeds, close the channel again and +pick a new jname. + +The new inferior will have 1K of zeroed unshared core, +and will not be running (its .USTP will be nonzero). + +Then, if you wish to handle interrupts from the inferior, +read the inferior's interrupt bit, which may be found in +the inferior's .INTB variable, and remember it somewhere. +That is the bit .IFPIR on which YOU will be interrupted, +if the inferior gets a fatal interrupt. + + 2. DELETION + +Inferiors do not need to remain open to continue to exist. Simply +closing the channels one is open on does not delete it; it is +merely hard to refer to until it is opened again. This is so +that it is possible to have many inferiors without tying up many +I/O channels. When it IS desired to delete an inferior, the +.UCLOSE uuo should be used: + + .UCLOSE , + +This uuo kills the inferior open on . All the channels +it is open on are closed. The uuo does not skip. +If a foreign job instead of an inferior is open, all the channels +in this job that it is open on are closed, but it is not killed. +If there isn't a job open on the specified channel, an ILOPR +interrupt happens. + + 3. DISOWNING + +Disowning an inferior causes it to continue to exist, but no longer +as your inferior. This can be useful for two reasons: +1) you wish to log out but want the inferior to remain, or +2) you want the job to become someone else's inferior. + +Disowning is done with the DISOWN system call, as follows: + + .CALL [ SETZ ? 'DISOWN + 401000,,] + .VALUE + +It fails if the specified job isn't an inferior of the executing one. +If it succeeds, the specified job and its inferiors become +a separate disowned tree, of which the specified job is the top. +All channels on which the running job had that job open are closed. +See the DISOWN symbolic system call for more details and features. + + 4. REOWNING + +A top-level disowned job may be "reowned" (made one's inferior) +by opening it with bit 1.4 of the mode set to 0. The uname of +every job in the reowned tree will be changed to equal that of +the reowning job, if necessary. If as a result the uname/jname +pair of one of the reowned jobs is no longer unique, the jname +will be altered until the uname/jname pair is unique. + +Another way to reown a job is to use the REOWN symbolic system +call. The job to be reowned should already be open on an I/O +channel as a foreign user; the REOWN will cause it to be open +as an inferior instead on the same channel. An example is: + + .CALL [ SETZ ? SIXBIT/REOWN/ ? 401000,,USRI] + .VALUE + +In DDT, selecting a job that may be reowned will always reown it. +DDT will type ":$REOWNED$" when that happens. If the uname or +jname changes, DDT will type the new names. + + 5. DETACHING + +An entire tree may be made disowned, have its console taken +away from it, or both, with the DETACH system call. The goal might +be to free the console for other use, or to make the tree into +a subtree of another tree by reowning it. + + 6. ATTACHING + +Attaching is the operation of connecting a terminal to a tree +as the tree's console. The simplest kind of attachment takes +a free console and a disowned tree and connects them. A top-level +console-controlled job may also attach one of its inferiors to +its console; this has the same effect as if it were to disown +the inferior, detach itself, and then attach the erstwhile inferior +to the now free console, except that it happens more smoothly. +DDT's :ATTACH command uses the second flavor of ATTACH. See the +ATTACH system call for more details. + + 7. LOGGING IN + +When the system creates a top-level job (such as a HACTRN), its uname +will be three "_"'s followed by three unique digits. The job may +change its uname to one that gives more information to humans by +"logging in", which simply sets the uname. The job must not have any +inferiors at the time; the new uname must not start with "___" and +must not be in use. A logged-in job may not log in again, but it may +change its uname with a .SUSET of .UNAME. +Logging in is done with the LOGIN symbolic system call, as follows: + + .CALL [ SETZ ? SIXBIT/LOGIN/ + SETZ []] + .VALUE + +The system call takes an optional third argument which now should be +used only by network server telnet jobs. For them, its hould be the +sixbit string "HSTnnn", where nnn is the octal number of the foreign +host. + + 8. LOGGING OUT AND GUNNING + +A top-level job may delete itself, and all its inferiors, by "loggin +out". This is done with the .LOGOUT UUO, as follows: + + .LOGOUT + +The UUO returns only if it fails (the job isn't top level); it does not +skip. Programs that do not normally run in top-level jobs might +nevertheless be run in disowned jobs sometimes, so they should always +try to log out before requesting another command string or trying to ask +DDT to kill them. + +A job may force any top-level job to log out by "gunning" it, using the +.GUN UUO. The user index of the job to be gunned must be known. The +way to do it is: + + MOVEI AC, + .GUN AC, + JRST LOSE ;FAILED - JOB DIDN'T EXIST OR WASN'T TOP LEVEL. + ... ;SUCCEEDED. + +Gunning should go on only between consenting adults. + +C. CONTROL OF INFERIORS. + +Jobs can control their inferiors by means of several special-purpose +system calls. The more specific of them are documented below under +their uses. One more general one is .USET, which allows the inferior's +"user variables" to be read or set. For example, when section C.5. +speaks of "setting the job's .USTP variable", a .USET is meant. The +way to set the .FOO variable with a .USET is this: + .USET ,[.SFOO,,[]] +Thus, .USET ,[.SUSTP,,[0]] will stop the job open on channel +. + .USET ,[.RFOO,,TEMP] will read the value of the .FOO +variable into TEMP. +For a complete description of the available .USET variables, and more +features of .USET, see the file ITS .USETS. + + 1. READING AND WRITING + +Reading or writing the contents of another job requires having the job +open on a USR device channel. It is done by .IOT'ing on that channel; +thus, reading requires an input channel and output requires an output +channel. Selection of the region to read or write is done by setting +the channel's access pointer with .ACCESS. At the moment, SIOT on unit +mode USR channels is not very efficient, so it is best to open a job in +block mode. That requires one extra instruction when transferring a +single word, which is a slight cost when compared with the ease of +transferring several words. +Note that ascii mode does not exist for the USR device - all channels +should be opened in image mode. + +For example, to read the word at 500 into A, do + + .ACCESS USRI,[500] + HRROI B,A + .IOT USRI,B + +assuming that USRI is the USR input channel. This clobbers B. +To write A into the word at 500, do + + .ACCESS USRO,[500] + HRROI B,A + .IOT USRO,B + +assuming that USRO is the USR output channel. This clobbers B. + +If a non-existent location in another job is read or written +with an IOT, an MPV interrupt results. The .MPVA variable +of the job doing the reading will point at the non-existent +page of the other job. (Actually, in ITS before version 1017, +when a non-existent page is written, the system may give an MPV, +or may do a .CORE on the inferior so that it has enough core +to make the IOT succeed. ITS version 1017 and up will +always MPV). + + 2. SHARING MEMORY BETWEEN JOBS + +Another way to refer to the core of other jobs is to share +memory with them. The slots of a job's page map should be +understood to be pointers to pages; one page may be pointed +to independently by several slots in several jobs' page maps. +The CORBLK call can be used to copy other jobs' pointers to pages +into one's own job, resulting in shared memory. Of course, +the memory will not have the same address in both slots +unless that is specificaly arranged for. +Unfortunately, other jobs' accumulators cannot be referred to +via memory sharing, since they are not stored anywhere in +the job's memory even when the job isn't running. + + 3. LOADING + +Loading a binary file into a job is not actually a fundamental +operation, since it could be done by a program that understood +the format of the binary file and deposited in appropriate +locations in the job being loaded. However, for convenience' +sake, the LOAD system call exists for loading a binary file +into an inferior, or into the running job itself. Both types +of ITS binary files may be loaded with LOAD; it is not necessary +to know which type of file is being loaded. Unfortunately, this +call works only for disk files. For other devices, the program +must do it the hard way. Code may be copied from DDT for that +purpose. + +The LOAD system call takes two arguments: the job to be loaded, +and the file to load. The first is expressed by a job spec; the +second, by a channel number. For example, + + .CALL [ SETZ ? SIXBIT /LOAD/ + 1000,,-1 ;into myself + 401000,,DISKC] ;the file open on DISKC + .VALUE + +The LOAD will leave the disk channel set up to read the file's +start instruction, which is a jump to the starting address, or +zero if there is no starting address. After that word in the +file should come the symbol table and another copy of the start +instruction; see DDT ORDER for their format. + +Loading a PDUMP file (pure file) inserts pages into the job +as specified by the file. It does not alter the pages of the +job that the file has no data for. It also does not alter the +accumulators, even if page 0 is loaded. Loading an SBLK file +(impure file) alters only the words of the job that the file +specifies data for. The other words are NOT cleared. If data +are specified in a nonexistent page, fresh memory will be +put there, and also in all nonexistent pages below it in the +address space! Thus, if an impure dump is made of a job containing +nonzero data only at address 100000, the resulting file when +loaded will create core up through address 101777, even though +only the last page of that is actually being loaded. This +unfortunately cannot be changed, but often causes trouble. For +that reason (and many others), it is hoped that there will be +a new, more versatile binary format some day. + + a. Resetting + +Loading per se modifies only the locations that the binary file +specifies data for. It does NOT clear the rest of core. If you +want to do that, chances are that you really want to RESET the +inferior. To do that, use the .RESET UUO or the RESET symbolic system +call on an I/O channel with the inferior open. + +RESETting a job deletes all of its core, provides it with a single +page of unshared writeable core, closes all the job's channels, +kills all of its inferiors, and re-initializes most of the job's +system variables. Most notably not cleared out are the job's +translation lists for filenames. + + 4. DUMPING + a. Pure dumping + b. Impure dumping + 5. STARTING AND STOPPING + +An inferior may be started (caused to run) by setting its .USTP +variable to zero. It will continue with whatever PC it has. +To set the PC, store the desired new PC in the .UPC variable. + +An inferior may be stopped by setting the .USTP variable to +nonzero. The exact value deposited in .USTP will be forgotten +since it corresponds only to a single bit of real storage. +This is how the system stops a job which gets a fatal interrupt. + +DDT has another way of stopping a job, which it uses in executing +the ^X command: it turns on bit %PIC.Z of the job's .PIRQC, causing +a fatal ^Z-typed interrupt in that job. +This not only makes the system set the job's .USTP, but causes +DDT's interrupt handler to find out about the stoppage of the +job and be properly faked out. + + 6. HANDLING INTERRUPTS + +Every job has the ability to enable interrupts on several conditions +(see ITS INTRUP). Among those conditions is the occurrence of a fatal +error interrupt in an inferior. This is the mechanism that enables +a job to "return to DDT" deliberately - it simply causes a fatal +interrupt in itself. This is also how DDT knows when an illegal +instruction is executed by an inferior. + +Whenever a job acquires an inferior (by creation or reowning), one +of the job's interrupt bits is assigned to that inferior. Each +inferior has its own interrupt bit. There are exactly eight +interrupt bits which can be used for that purpose, which is why a +job can have at most eight inferiors at a time. Those eight are +all located in the left half of the .IFPIR variable. + +The superior should find out which interrupt bit was assigned by reading +the inferior's .INTB variable, in which that bit alone will be 1. + +See ITS INTRUP for more details. + +The two system calls .VALUE and .BREAK exist solely so that a job can +cause a fatal interrupt to signal its superior. DDT has standard +interpretations for those instructions; see .INFO.;DDT ORDER. + + 7. DEBUGGING CONTROLS. + +These features exist to facilitate debugging. They work currently on +KA-10's only, though they will be extended to KL-10's eventually. +They are generally used and controlled only by the superior of the +job on which they are acting, to which they are generally transparent. + + a: One-proceed. + +If appropriate bits in a job's PC are set, that job will be +able to execute one more instruction and then will get a fatal +%PI1PR interrupt. This feature is used by DDT's "single step" +command (^N). Which bits to use depends on the processor type: +for KA's, %PC1PR is the right bit (it is an 18 bit quantity, to +be OR'ed into the flags); for KL's, %PS1PR is right. On any +machine, the symbol OIPBIT will be defined in the ITS symbol +table as either %PC1PR,, or %PS1PR,, , whichever is appropriate. + + b: Address-stop (MAR). + +The MAR feature makes it possible to trap all references to a +particular address. When the specified location is referred to +("the MAR is hit"), the inferior will get a fatal %PIMAR +interrupt, which may or may not allow the instruction that +tripped the MAR to finish. The MAR is turned off when it is +hit and must be turned on again explicitly or it will stay +off forever. + +The MAR is controlled by the .MARA user variable. Its RH +contains the address to be traced. Its LH contains the control +code, which is 0 to turn the MAR off, 1 to trap instruction +fetches only, 2 to trap writes only, and 3 to trap all +references. There is also a variable .MARPC which, after +the MAR is hit, contains the address of the instruction that +hit it. In addition, the indirect bit will be set on KA's +if the instruction that hit the MAR was completed (on KL's, +the instruction is always aborted). +On KL's, after a MAR, the job's PC (.UPC) will have %PSINH +set, which will inhibit MAR hitting for one instruction +when the job is continued. +The job's PC in .UPC should NOT be used to locate the +instruction that hit the MAR, since if the instruction was +not aborted and was a jump, the PC will be the address +jumped to. Even if it wasn't a jump, it might have skipped. + + c: .JPC - Last Jump Address. + +The user variable .JPC always contains the address of the last +jump instruction executed in the job. It can be used, for +example, to trace a job backward from the point of failure by +putting in a breakpoint, examining the .JPC when the breakpoint +is hit, and running the program again with the breakpoint now +located at the previous jump, etc. Unfortunately, subroutine +calls (including user-trapping UUOs) alter the JPC, even though +the information is redundant for them, but returnable UUO's and +interrupts do not. For that reason, after a returnable UUO +or interrupt a program should always read .JPC before jumping +anywhere, for debugging purposes. The canonical names UUOJPC +and INTJPC exist for the locations .JPC is saved in. Also, +error-handling uuos used by the program should be returnable +uuos rather than direct user-trapping uuos, so that the JPC +will be meaningful. The vectored interrupt mechanism has the +ability to store .JPC automatically on each interrupt (see +ITS INTRUP). + + 8. TTY PASSING + +For now, see under .ATTY and .DTTY in ITS TTY. + +D. SYSTEM JOBS AND WHAT THEY DO + +There are two jobs built into the system, that run in exec mode +and perform housekeeping tasks; they are the system job and +the core job. There are also various "demon" jobs that exist +at times which, though receiving no special treatment from the +system, may be regarded as part of it in that they provide a +system-wide service. + + 1. THE SYSTEM JOB. + +This job, whose full name is SYS SYS, provides a great many +independent services; it is really a timesharing system for +many trusting processes, each of which is controlled by a +single bit in the system variable SUPCOR. Setting the bit for +a process causes the process to run, and clear the bit. The +process should never run for very long, or it may tie up the +system by making the services of the other processes +unobtainable. If a process wishes to run continually, it does +so by setting its bit in SUPCOP. SUPCOP is or'ed into SUPCOR +every second, so a process whose bit in SUPCOP is set will be +run again that often. The process is always started the same +way, but it can of course have state variables. + +The reasons why a given activity may involve the system job are +1) it may wish to print a message on the system log terminal, or +2) it may need to run in a job (eg, do system calls), but not be +associated with any one job, or +3) it may need to be able to hang up for short periods of time, +but the need to do it may be noticed at a time when that is +impossible, or +4) it needs to be done once every two minutes or every two hours. +The routines for those "very slow" and "super slow" clocks are in +the system job. + +Re-initialising the connection to the IMP is an example of reasons 1 +and 2. Typing "console free" messages is an example of reason 3 - it +involves doing I/O to the terminal, but it isn't done until the last +stage of killing a tree, when waiting of any sort would allow PCLSR'ing, +which would leave things in a screwed-up state. An example of reason 4 +is the detection of core-link files which have not been used for more +than 2 minutes. + +A complete list of the system job's functions follows: + + a: Allocating or Deallocating Memory for Job Slots. + +Most of the memory occupied by the system is marked as belonging to +the system job. For that reason, the way more is allocated for user +variable blocks is by having the system job do a .CORE UUO. This is +somewhat of a historical crock. Creating a job does not require such +allocation if there are free slots in the memory already allocated. +However, it may need to. For that reason, if the system job is hung +up, often jobs cannot be created. + + b: Printing Various Messages on All Terminals. + +Sometimes, messages such as "ITS GOING DOWN IN ..." or "ITS BEING +DEBUGGED" are printed on all the terminals in the world. It is the +system job that prints them on terminals which are free. Consoles have +them printed by DDT, however. + + c: Checksumming the Constant Areas of the System. + +The system job is always checksumming parts of the system and comparing +the checksums with those previously calculated. This mechanism causes +the clobberage of a word in the code of the system to be detected. If +only a single word in an area is clobbered, which word it is and the +original contents can be detarmined. In any case, a message is printed +on the system log terminal when clobberage is found. + + d: Determining the Date and Time. + + e: Detaching Trees. + +When a top-level job is halted by a fatal interrupt, it is the system +job which executes the DETACH system call to detach it. Similarly, it +is the system job which detaches trees controlled by TV terminals when +the TV system crashes, and trees controlled by dialup lines whose +connections are broken (only when the hardware can detect that). + + f: Depositing in the System. + +When a job deposits in the system using .SETLOC or .IFSET, the system +job is informed so that it can update its checksums and avoid a system +clobbered" message. It also makes the change. + +This used to be a great screw, in that if the system job were hung, it +could not be fixed by depositing in the system. Now, .SETLOC will do +the work itself without calling the system job, if the system job +appears to be hung. + + g: Printing "Console-free" Messages. + +When a terminal ceases to be in use, the system job is signalled to look +at all terminals and print console-free messages on all those which have +recently stopped being in use. + + h: Logging Out. + +The final stages of killing a job must be run by some other job. When a +top-level job is being killed, it does some of the work itself (kills +its inferiors and closes its channels). That is to make sure the +system job never hangs up trying to do it. The rest of the work is +then done by the system job, which can afford to wait for short peiods +of time when the job is almost killed. + + i: Reinitialising the NCP. + +When the connection to the ARPA network goes down, the system job gives +interrupts to all the jobs using the network, and also checks every so +often whether the network is useable again. + + j: Printing of Various Messages on the System Log Terminal. + +Events which cause messages on the log terminal include logging in, +logging out, writing on a directory whose name starts with "SYS", +garbage-collecting a disk directory, creating a disk directory, +gunning, parity errors, NXM errors. + + l: Spooling the LPT. + +On the AI KA-10 and the ML KA-10, the system job checks periodically for +spooled files and prints them. + + m: Starting Other Demons. + +On DM, the system job checks for any domon programs which have been +signaled. If there are any, it loads them into newly created jobs +and starts them. + + n: Reinitialising the TV System, or Noticeing that it is Down. + + 2. THE CORE JOB. + +This job, whose full name is CORE JOB, allocates core to jobs that +request it, and also frees up memory for use as user variable blocks, +which have to be allocated consecutively, by relocating the old +contents. Before there was pageing, the core job used to do shuffling. + + 3. DEMON JOBS. + + a: The Comsat. + +This demon, always named after some spacecraft or rocket, is responsible +for handling mail. Requests to send mail are placed in the .MAIL. +directory, and are eventually processed by the demon. The demon is +necessary because it may not be possible to send mail to other machines +right away, and in any case the user should not have to wait the time +it takes. It also provides other services such as forwarding. + + b: NAMDRG. + +This demon maintains the list of logged in users which appears on all +free TV consoles. It also updates a file saying when every user +logged out last. It exists on the AI KA-10 only. + + c: PFTHMG DRAGON. + +This demon updates the logout times file and keeps track of each user's +total CPU time. This demon originated on the ML KA-10, but has run on all +ITS machines at one time or another. + + \ No newline at end of file