Copyright Xerox Corporation 1979Inter-Office MemorandumToCommunication ProtocolsDateJune 30, 1978FromEd TaftLocationPalo AltoSubjectImplementation of Pup in TenexOrganizationPARC/CSLXEROX Filed on: [Maxc1]Tenex-Pup.pressThis is another revision of a memo with the same title dated October 18, 1975. The purpose of thisedition is to bring the documentation up-to-date (only minor changes have been made) and to re-issue it in Bravo and Press formats.BibliographyPup SpecificationsDescribes the Pup philosophy, basic packet format, and second-level Pup-based protocols(Echo, Rendezvous/Termination, BSP). File PupSpec.press.Naming and Addressing Conventions for PupFile PupName.press.The Pup Network Directory and the PUPNM JSYSDescribe conventions and facilities for naming and addressing Pup ports. FilePupDirectory.press.Pup Connection State DiagramPresents a model for implementation of the Rendezvous/Termination Protocol. FileRTPStates.press.Pup Telnet ProtocolDescribes a BSP-based protocol for performing character-oriented communication withdumb terminals. File Telnet.press.User Program InterfaceTenex user programs deal with Pup transmissions through the standard file system interface, in amanner similar to the Tenex Arpanet interface. That is, GTJFN is used to establish associationbetween a JFN and a network filename (which evaluates to the local and foreign ports to be used).OPENF causes the local port to be created and (optionally) communication to be established withthe foreign port. Data transfer operations come in two flavors: raw packet (new JSYSes calledPUPI and PUPO), and byte stream (BIN, BOUT, SIN, SOUT, etc). CLOSF causes the port to bereleased. And MTOPR is used for the remaining special device-dependent functions that don't seemto fit in anywhere else. &pX]g~qi cr]pX-r7Bp \r]p-r7Bp Vr]p-r 7BpOsp I% C"A BD[ @$ <2t 9Mu7p*-6C> 3^u)1p .u,-opN.O+ )u'pK% #u!p"1 ( t pP >! up=  N +u p u p/ | W *?/d Implementation of Pup in Tenex2Network FilenamesA network filename (for GTJFN) is in the form:PUP: . where all fields except the device name "PUP:" are optional.The local and foreign port specifications are as described in the memos Naming and AddressingConventions for Pup and The Pup Network Directory and the PUPNM JSYS. They each evaluate toan 8-bit network number, an 8-bit host number, and a 32-bit socket number (or a list of suchaddresses in the case of the foreign port). Any or all of these elements may be zero or unspecified,which causes the port to be wildcard and subject to special handling as described below.The local port specification must evaluate to a triple that satisfies thefollowing conditions:1.The network and host numbers, if both specified, must correspond to an actual Maxcconnection to some network. Ordinarily, user programs will leave these elementsunspecified.2.The socket number must be one accessible to the executing process.Tenex divides the set of all possible 32-bit local socket numbers into three ranges, distinguished bythe high-order 17 bits of the socket number, in a manner almost identical to the way in whichArpanet socket numbers are partitioned.Sockets whose high-order 17 bits are zero are designated system sockets, and are accessible only toprocesses with wheel or operator capability enabled. These are intended for use by system serverprocesses that listen on known, advertised sockets.Sockets whose high-order 17 bits are in the range 1 to 49999 (decimal) are designated user-relativesockets. These are accessible to processes whose connected directory number is equal to those high-order 17 bits.Sockets whose high-order 17 bits are in the range 50000 to 99999 (decimal) are available on a first-come-first-served basis to all processes.Sockets whose high-order 17 bits are 100000 (decimal) or greater are designated job-relative sockets.These are accessible to processes whose job number is equal to those high-order 17 bits minus100000 (decimal).The socket number in the local port specification, in conjunction with the socket type attribute (ifpresent), determines the actual local socket number to be used, in the following manner:1.If the local port specification is followed by "!A" (for "Absolute"), the 32-bit socket numberis completely determined by the socket number field of the local port specification. The useof "!A" is required to refer to a system socket, and may also be used to refer directly toother sockets that are accessible to the executing process.2.If the local port specification is followed by "!U", the high-order 17 bits are set equal to theprocess's connected directory number, hence making a user-relative socket. "!U" is thedefault if no socket type is specified.3.If the local port specification is followed by "!J", the high-order 17 bits are set equal to theprocess's job number plus 100000 (decimal), hence making a job-relative socket.4.If the socket number in the local port specification is zero or unspecified, the low-order 15bits are set to 8 times the JFN being assigned by GTJFN. fpXG bu _9p.\T1 Yo< Vupu p.u Upu,p Su p u pu p QP Pvup4 Mu p@ L  I'%-G( )CF C8B @Sb >L =I' :d9u p 8J 7Z3 4u Iu 2pup 1k .L -) *0up ('u p+ ' $- Au p "X  R>U!94; O`J E' `AO ] q8 R *?/[HImplementation of Pup in Tenex3The foreign port specification evaluates to one or more triples in which anyor all elements (including socket number) may be zero (wildcard). Tenex's handling of local socketnumbers is not performed on foreign socket numbers; i.e. all 32 bits of the foreign socket numberare determined by the user's foreign port specification.GTJFN, OPENFThe function of GTJFN for a network filename (as is the case for all other filenames) is simply toestablish an association between that filename and a JFN. GTJFN therefore checks only to see thatthe network filename is well-formed. Operations such as verifying access to the local socket,creating the local port, and exchanging messages with foreign hosts are performed by OPENF.At OPENF time, Tenex first checks that the specified local socket number is legally accessible to theexecuting process (error: OPNX13, "Illegal access"), and also ensures that it is currently unused.An error (OPNX9, "File busy") will result if the local socket number is equal to any other port'slocal socket number and the two ports have matching local network and host numbers. By"matching", we mean either that they are equal or that one or both of them are wildcard.A network file may be opened in either of two principal modes: raw packet mode (16 octal) andbyte stream mode (0 through 4).Raw Packet ModeIn raw packet mode, entire Pups are transferred to and from the user address space, including Pupheaders. Except for a small amount of checking and defaulting of fields in the Pup header, Tenexdoes no processing of the Pup. Acknowledgments, timeouts, duplicate message detection, flowcontrol, and similar functions are left entirely up to the user program to perform. Tenex willdiscard both incoming and outgoing Pups that exceed resource constraints or produce otheranomalies, with no error indication to the user process.Executing OPENF in raw packet mode merely causes the specified local port to be created. Nomessages are transmitted by OPENF. The OPENF may specify reading, writing, or both; typically,programs will open ports for both reading and writing.Data transfers to and from the user address space are performed by means of new JSYSes calledPUPI and PUPO, which transfer one complete Pup per command. At one time we contemplated usingDUMPI and DUMPO for raw packet I/O, but those JSYSes were found to be unsuitable for this operation due toexcessive overhead and non-interruptability. Packets are stored in user memory in standard PDP-10 form,which is to say two 16-bit bytes (or four 8-bit bytes) per word, left justified. Unused bits in PDP-10words are unspecified on input and ignored on output.Source address filtering and Pup Checksum generation and checking are optional. The userprogram is responsible for these operations if the options are not requested.The calling sequence for PUPI and PUPO is as follows:Accepts in1:B0:Never dismiss for I/O, give PUPX3 error instead.B1:Generate (PUPO) or check (PUPI) Pup Checksum, give PUPX5error if incorrect.B2:(PUPI only) Perform source address check, give PUPX7 error ifincorrect.RH:JFN2:LH:Length of Pup in 36-bit words.RH:Address of first word of Pup. fpXG bu p? `03 _:) ]8 Yu Vp@" Ul.4 S8& RbT O}:+ M>% LsZ JA Ii J F@u p Du p AFu >ap/2 <M ;WJ 9K 8MS 68 3L 2^#< 06 -C ,o;r! +Y )p= (()> &5 #E "9M T5o  !+ !#!  !:!  !  ! ! ?/]eLImplementation of Pup in Tenex4PUPI or PUPOReturns+1:Unsuccessful, error # in 1.+2:SuccessfulThe PUPI operation first waits for a Pup to be received whose Destination Port matches the localport (with fields corresponding to wildcard elements ignored). The Pup is then simply dropped intothe block specified by the user. If the Pup is too big to fit in the block, an error (PUPX1, "PUPI/Osize error") will be generated and the remainder of the Pup will be lost. Then, if B1 of 1 is set, thePup Checksum will be checked and the error return taken if it is incorrect (PUPX5, "PUPI:Checksum incorrect"). If B2 of 1 is set, the Source Port will be checked against the foreign portspecification for this network file, and the error return taken if it doesn't match (PUPX7, "PUPI:Source address incorrect").Similarly, PUPO first waits for Tenex to find some buffer space, then transmits the Pup. In the caseof PUPO, Tenex first performs some minimal processing of the Pup header. First, the Pup Lengthis checked for consistency with the actual size of the block given in the PUPO command (error:PUPX1, "PUPI/O size error"). Next, for any fields in the Source Port and Destination Port that arezero, Tenex substitutes the corresponding elements from the local and foreign port specifications, ifpossible. Nonzero fields of the Source Port and Destination Port are not touched. An error willoccur (PUPX2, "Pup address error") if the resulting Source Port is inconsistent with the local portspecification or designates a pair that does not refer to Maxc, or either the SourcePort or Destination Port contains any elements which are still zero. (Exception: some networkspermit broadcasting a packet to all hosts on that network by specifying a zero destination host.)The substitutions just described are performed as the Pup is copied from the user block to internalbuffers; i.e., PUPO does not modify user memory. It should also be noted that these substitutionswill invalidate a non-nil Pup Checksum. A program supplying a non-nil Pup Checksum musttherefore specify fully the Source Port and Destination Port (thereby preventing any substitution byTenex), and use these in computing the checksum. Alternatively, B1 of 1 may be set in the call toPUPO, causing Tenex to generate the Pup Checksum.For either PUPI or PUPO, if B0 of 1 is set, an immediate error return will be given if attemptingthe operation would cause the process to block for I/O (error: PUPX3, "PUPI/O not possiblenow"). For PUPI, this can be due to there being no buffered input Pups to read, while for PUPO itis due to there already being too many Pups buffered for output but not yet transmitted by Tenex.Finally, CLOSF first waits for any buffered outgoing packets to actually be transmitted, then merelydeletes the local port. Buffered incoming packets are lost, and any further Pups received by Tenexfor that port will be discarded without error indication.This exhausts the primitives required for raw packet mode communication.Byte Stream ModeByte stream mode operates in accordance with the Byte Stream Protocol (BSP), described in PupSpecifications.The general idea of byte stream mode is that the user program simply reads and writes streams ofpure data bytes, treating the network file as an ordinary sequential I/O medium. All BSP-specificoperations (such as acknowledgments and flow control) are performed entirely by Tenex.The byte stream primitives provided by Tenex are as follows:1.OPENF causes the establishment and initialization of a byte stream connection, andoptionally performs a rendezvous.2.BIN, BOUT, and higher-level sequential I/O operations cause pure, error-free byte streams fpXG(ib _9!\T! YoN Wc Ve7. Tc S[1( QA! PQ?# N KX Jb8' H<" GXZ E23 DNV BX AD-7 ?Q >:u pN ;UM 9J 8KI 67- 5A&< 31 0># /RH -H ,H&; )cF 'Q &Y9 #tH u p Ou Q p l U 02 bV }< ;! .At ?/]#TImplementation of Pup in Tenex5to be read and written.3.CLOSF causes the connection to be terminated in an orderly manner.4.A collection of MTOPR functions and other JSYSes are implemented for performing specialoperations peculiar to Pup and BSP.An important property of BSP connections is that they are bidirectional. Unfortunately, Tenex isnot capable of performing both sequential input and output independently over a single JFN. Aprogram desiring to do bidirectional sequential I/O through a single port must obtain two JFNs forthat port and open one for reading and the other for writing. Both JFNs must be opened by the same job,but may be opened by different forks of that job. The first OPENF performs the functions described belowwith respect to performing the rendezvous (if any) and establishing the connection, and the secondOPENF is effectively a no-op (but is nevertheless required before the second JFN may be used forI/O operations). Similarly, two CLOSFs are required to dissociate the two JFNs from the port (theconnection is actually closed by the CLOSF on the JFN opened for writing).The byte size specified by OPENF must be either 7 or 8 (error: SFBSX2, "Illegal byte size"). The7-bit byte size is provided for convenience in dealing with the usual Tenex 7-bit ASCII files;conversion between 7-bit characters and 8-bit Pup bytes is performed simply by adding a zero high-order bit on output and stripping off the high-order bit on input.The OPENF used to establish the byte stream connection may specify any of five modes, numbered0 through 4. These modes determine the operations to be performed by the OPENF and areindistinguishable thereafter. Of these five modes, four (modes 0 through 3) automatically implementspecial cases of the Rendezvous Protocol, while the fifth (mode 4) does not. In more detail, thevarious modes of OPENF operate as follows.Executing OPENF in mode 0 or 1 performs a rendezvous in which the local port takes on the roleof initiator. That is, after creating the local port (as for raw packet mode), OPENF transmits aRequest for Connection (RFC) to the foreign port, designating the same local port (the rendezvousport) as being the connection port as well. In mode 0 ("normal"), OPENF then waits until theanswering RFC arrives, changes the foreign port address for this connection to be the ConnectionPort designated by the answering RFC, sets the connection state to Open, and returns control to theuser program. In mode 1 ("immediate return"), the same operations are performed by Tenex as formode 0, but control returns to the user program immediately after the initiating RFC is transmitted.The connection state is RFC Outstanding until the answering RFC is received, at which point theconnection becomes Open. The user program may determine that this has happened by eitherpolling the connection state or arming the state-change interrupt.In modes 2 and 3, the local port takes on the role of listener. Executing OPENF does not send anRFC but rather puts the local port into a Listening state. In mode 2 ("normal"), OPENF thenwaits, while in mode 3 ("immediate return"), it returns immediately to the user program. When anRFC is received whose Source Port and Destination Port match the foreign and local portspecifications for this listening port (which will ordinarily have wildcard elements), Tenex substitutesthe actual values of the Destination Port and Connection Port fields (in the RFC) for the local andforeign port specifications of this port (respectively), sends the answering RFC to the foreignrendezvous port (from which the incoming RFC arose), and sets the state to Open as in the normalcase.Note that "normal" and "immediate return" modes differ only in whether or not the executingprocess waits while the protocol exchanges are taking place. In terms of internal events andmessages exchanged with the foreign host, there is no difference between the two modes. Tenextakes care of properly acknowledging all Pups received whether or not the user process is waiting forsuch acknowledgments.Wildcard elements in the foreign port specification are permitted only when Listening (modes 2 and3); their presence in other modes will result in an error (PUPX2, "Pup address error"). On theother hand, the local port specification may (and usually will) have wildcard network and host fpXGb _9B \T0'Z# Wa Ve^ Tb S[?r Qp9 PQb NP MGF KJ HP GX;# EK DNB Ai$: ?E >_?% <U ;U* 8pG 6up), 5f#4u 3p up; 2\` 0Bup /R R -d ,Hup$ *upB )>B &Y6upup $ up) #OF !%2 E26 O ;(7 ,up 1 L> 5( BW  [ 8 Su p= &9 Iu p- ?/]Implementation of Pup in Tenex6elements. For modes 0, 1, and 4, OPENF automatically sets these elements to appropriate values(usually based on the foreign port specification), and if the foreign port specification evaluates to alist of addresses, one of them is chosen at this time by Tenex. In modes 2 and 3, these fields are setfrom the Destination Port of the incoming RFC, as explained above. In any event, no port ispermitted to reach the Open state unless the local and foreign port addresses are completelydetermined.For all four modes just described, the rendezvous performed is a special case of the RendezvousProtocol in which the local rendezvous port and BSP connection port are the same. To permit otherforms of rendezvous, OPENF mode 4 is provided which creates a BSP connection port withoutperforming any rendezvous. When this option is used, the user program must supply the 32-bitConnection Identifier, right-justified in AC3. The local port is at once set to the Open state, andOPENF returns immediately.When using mode 4, it is the responsibility of the user program to perform the rendezvous itself. Itis intended that this be done by server programs (such as Telnet and FTP servers) that listen on asingle, widely-advertised rendezvous port, and pass each separate request for service off to a differentconnection port. This is most easily done in the following manner:1.Open the rendezvous port for I/O in raw packet mode, with the foreign port completelyunspecified.2.When an RFC arrives, open a new BSP connection port (using OPENF mode 4), with thefollowing parameters:a.Local network and host equal to the Destination Network and Destination Hostfields from the RFC;b.Local socket selected to be unique;c.Foreign port equal to the Connection Port in the RFC;d.Connection Identifier equal to the Pup Identifier of the RFC.3.Transmit (over the rendezvous port) an answering RFC containing the address of the BSPconnection port just created.Once a port has been opened successfully, all sequential I/O operations are possible (BIN, BOUT,SIN, SOUT, etc).Sequential output operations will wait only if necessary to obey flow control and bufferingconsiderations. Normally, output will be buffered and blocked into maximum-length Pups wherepossible, but MTOPR function 21 may be used to force buffered data to be transmitted immediately(see JSYS Manual). Ordinarily a maximum-length Pup contains 532 data bytes, but the Byte Stream Protocol permitsa receiver to specify a smaller maximum Pup length.Sequential input operations will wait if necessary for data to arrive. An end-of-file condition will besignalled (generating an EOF pseudo-interrupt if it is enabled) upon attempting to read past a Markor End packet. In the case of a Mark, the value of the Mark byte may be read by MTOPR 23, andSDSTS may be used to clear the end-of-file condition so as to allow reading the next logical file inthe byte stream.CLOSF will first wait for any buffered output data to be completely transmitted and acknowledged.It then transmits an End (or an End Reply if an End has already been received) and waits until the3-way End handshake has completed before returning to the user program. The port's statebecomes Closed, and the port is destroyed after all JFNs referencing it have been closed.If at any time an Abort is received, the connection will be terminated abnormally. If the userprogram was executing an OPENF or CLOSF at the time, the port is simply placed in the Closedstate and the JSYS error return is taken (error: OPNX21, "Rejected by foreign host" or IOX5, fpXG b!> `61 _52 ];! \ upA Z WH V upup TA S upO Qup4 up P M"M K'; Jup' Hup4 E5D) AD3?<-;U8p#552= /D.< +WE ) &? %hM #A "^r(5 3  Q=' Pup0 M"up> K HM G3up; ER D)up ADA ?D <u 9!p; 7u,p 45( 322+ 1J 0(24 .B - *96* (I '/A! %A "F !@a (: 6O Q@ K // b }E N s15 rU pD6 ?/]HkImplementation of Pup in Tenex8stream mode only).B6-11PSI channel for interrupt generated upon receipt of any packet for a portopened in raw packet mode. (This is handy for use in server processes thatlisten on several rendezvous ports at once.)B12-17State change PSI channel (byte stream mode only).Note that the indicated channel and the rest of the PSI system must also be initialized and enabledand activated in the usual manner (see JSYS Manual). All conditions are initially disarmed when aport is created.MTOPR function 25 generates an Abort and causes the connection to be terminated abnormally andthe port placed in the Closed state. The contents of AC3 are used as the Abort Code and AC4 (ifnonzero) is used as a string pointer to supply the Abort Text.MTOPR function 26 (legal only for a port in the Abort state) returns the Abort Code in AC3 anduses AC4 (if nonzero) as a string pointer to store the Abort Text.GDSTS may be used to obtain certain device-dependent information about Pup ports. The portstate and various status flags are returned in 2 (see below). If 3 is nonzero in the call, it is used asan address table pointer (in the same manner as the PUPNM JSYS) to return the foreign portaddress(es). That is, LH 3 is the length and RH 3 the address of a table in the user address spaceinto which GDSTS stores the foreign address(es). Two words are used for each address: the firstcontains the network number in the left half and the host number in the right, and the secondcontains the socket number right-justified. The number of words actually stored is then returned inLH 3.Selected status bits may be changed by use of SDSTS. For example, the Mark flag may be turnedoff to clear an end-of-file condition and allow further input.The following is the format of the port status word. Most bits are undefined for a port not open inBSP mode. Bits marked '*' are for internal use only and should not be relied upon (they maychange without notice).*B0Port is locked.*B1BSP processing request pending.*B2BSP input available.*B3BSP output possible.B4Mark encountered. Generates EOF interrupt (if armed). Must be cleared bySDSTS to permit further input.B5End encountered. Generates EOF interrupt (if armed).B6Timeout (no activity for 2 minutes, or protocol interaction failed to completewithin 2 minutes). Generates I/O Data Error interrupt. May be cleared bySDSTS.B7If set, generation and checking of Pup Checksums is suppressed. Initiallyclear, this bit may be set or cleared by SDSTS.B8Port is open for reading.B9Port is open for writing.B10Packets are to be discarded at random intervals by Tenex (this facility is fpXGb_9(!]5\/,YJ1 Ve>% T9) S[ PvC Nup; Ml> J!up) IB F#8 D=, C%5 AE @ H >'6 <X ;z 83up 7> 4+d 2": 1!.<+W(r%"6!#>5Y C&$OjJ/ 69 Z >/]/Implementation of Pup in Tenex9provided for the purpose of testing lost message detection and flow controlalgorithms, and is implemented for both Raw Packet and BSP ports). May beset or cleared by SDSTS.*B11Need to send Acknowledgment.*B12Received Acknowledgment.*B13Last Acknowledgment sent gave zero allocation.*B14Interrupt outstanding.*B15Port is or was listening.*B16BSP output queue non-empty.*B17BSP not possible in this state.B18-31Currently unused.B32-35Port state (see memo Pup Connection State Diagram).SIBE, SOBE, SOBF, DIBE, and DOBE are all implemented as described in the JSYS Manual.SIBE and SOBE return the number of buffered bytes for input and output respectively. Thenumber of "buffered input bytes" (for SIBE and DIBE) is defined to be the number of bytes thatcan be read without causing the process to block. Hence, it does not include bytes contained in anylater Pups that may have arrived out of sequence.The number of "buffered output bytes" (for SOBE and DOBE) is similarly defined to be thenumber of bytes that have been transmitted (or are potentially transmittable) but not yetcumulatively acknowledged. Bytes contained in packets that have been specifically acknowledgedout of sequence are therefore not considered to have been transmitted when making this count. ForSOBE, the count does not include bytes contained in the packet currently being assembled (if any).DOBE first forces transmission of any partially-filled Pup, then dismisses until all data has beencumulatively acknowledged. Note that completion of DOBE does not imply that the receiving process has actuallyseen the data, merely that it has been delivered successfully to the destination host.The privileged OPRFN JSYS is extended to include a few Pup-related operations, encoded bymeans of a SIXBIT name in AC1:PUPBGFEnables printing of internally detected Pup errors on the logging console ifAC2 is nonzero, and disables printing if zero.PUPROUSets the Pup routing table entry for network (AC2)-1 to the value in AC4masked by AC3 (i.e., only the bits corresponding to ones in AC3 arechanged). The routing table may be read from the PUPROU GETABtable.PUPDIRMaps in the highest version of PUP-NETWORK.DIRECTORY.Values of Pup SymbolsJSYS numbers:PUPIJSYS 441PUPOJSYS 442PUPNMJSYS 443Error codes: fpXGb ?`'#_\/YJVe.SPMJGEup B"(- @U ?K =9+ <1 9) N 7@ 6R 4E 3b 1Y 0 r+( .V +pE *d'I%.#$$!; 8" u p  /   ?/\"Implementation of Pup in Tenex10PUPX1602010PUPI/O: Block size errorPUPX2602011Pup address errorPUPX3602012PUPI/O: Operation not possible nowPUPX4602013(Not presently used)PUPX5602014PUPI: Checksum incorrectPUPX6602015PUPI/O: JFN not open in mode 16PUPX7602016PUPI: Source address incorrectPUPX8602017PUPI/O: JFN doesn't refer to device PUP:PUPNX1602030PUPNM: Name or address not foundPUPNX2602031PUPNM: Name ambiguousPUPNX3602032PUPNM: Syntax error or illegal addressPUPNX4602033PUPNM: Inconsistent values in name expressionATPX14602040ATPTY: JFNs don't refer to same deviceATPX15602041ATPTY: Pup JFNs don't refer to same local portATPX16602042ATPTY: Pup JFNs don't refer to BSP portATPX17602043ATPTY: Pup connection not openPort state codes:S.CLOS0ClosedS.RFCO1RFC OutS.LIST2ListeningS.OPEN3OpenS.ENDI4End InS.ENDO5End OutS.DALY6DallyS.ABOR7AbortPUP device type: 402Pup-Related GETAB TablesThe first four tables are parallel and are indexed by a "Pup port index".PUPLSKLocal socket numbers, right-justified. Zero denotes a free port and -1 a deletedport.PUPLNHLocal network/host numbers and BSP linkage. The network and host numbers ofthe local port address are in B0-7 and B8-15 respectively (zero means wildcard).The right half points to the BSP data block, if any (see below).PUPFPTForeign port address(es). If zero, the foreign port is completely wildcard. Ifnonzero, the LH is the negative of the number of words in the foreign port addresstable and the RH is a pointer to a block containing the address table (the addresstable begins in the second word of the block). The address table format is the sameas for the PUPNM and GDSTS JSYSes.PUPSTSPort status words (as returned by GDSTS).NVTPUPData for Pup network terminals (NVTs), indexed by (TTY # minus the TTY # ofthe first Pup NVT). Zero denotes a free NVT. An assigned NVT has the sign bitset and the Pup port index of the associated connection in the RH. The rest of theword is for internal use only.PUPPARPup parameter table, for miscellaneous constants. Indexed by item number, asfollows: fpXG?b"`"_""]"\ "Z"Y"W{"(T"S"Q"&P"-M""&K".J"'H" EB AD ? >: < ;0 9 8&  5A 1u .pI +Q*9 'T.% B$J@ !e6@[3:Q" l) &%<}9 1  G>/[TImplementation of Pup in Tenex110- # of Pup NVT's ,, TTY # of first Pup NVT.1Monitor address of Pup free storage region.2B0=1 if this Maxc system is a Gateway.PUPBUFPup free storage region, in which foreign port address tables and BSP data blocksare allocated. This GETAB table encompasses the entire region. Its monitoraddress is given by the second word of the PUPPAR table. Hence, to examine theblocks that the PUPLNH and PUPFPT tables point to (these pointers being monitoraddresses), one should subtract the starting address from the pointer to yield anindex into PUPBUF. Consult PUP.MAC for the format of the BSP data block(which is subject to change).PUPROUPup routing and address table, indexed by network number minus 1. B0 is set ifthe network is known to be inaccessible. B1 is set if it is possible to send"broadcast" packets on that net. B2-9 and B10-17 give, respectively, the networkand host numbers of a gateway to which packets for the given network are to berouted by Tenex (zero means that packets are to be routed directly to theirdestinations). The RH gives the local host address on that network (zero means thatMaxc is not connected to the network).PUPSTAPup statistics table (subject to change). At present, the only statistics recorded are abreakdown of where the Pup background process spends its time. Indexed by itemnumber, as follows:0Count of calls to release used output buffers.1Count of calls to assign new input buffers.2Count of calls to garbage-collect port table.3Count of calls to do BSP background processing.4Count of NVT input/output scans.5Count of Telnet protocol timeout checks.6Time spent releasing used output buffers.7Time spent assigning new input buffers.10Time spent garbage-collecting port table.11Time spent in BSP background processing.12Time spent in NVT input/output scans.13Time spent in Telnet protocol timeout checks.14Total time spent by the Pup background fork.PUPBGTHash table in which all PUPBUGs are recorded (whether or not they are alsoprinted on the logging terminal). Each word in the table is either zero (unused) orcontains the PC of the call to BUG(PUP,<...>) in RH and a count of occurrences inLH. The PUPBUG subsystem prints out the contents of this table.Telnet ProtocolTelnet is a higher-level protocol, entirely based upon the Byte Stream Protocol. We mention it inthis document only because server Telnet (network terminal) handling must be performed insideTenex.A Telnet connection is ordinarily established when a user process performs a rendezvous to theTelnet server on Maxc, which listens on socket 1. This socket is maintained by the PUPSRV program. Aftera BSP connection has been opened, it may be "attached" to a network terminal by means of theATPTY JSYS, described in the JSYS Manual. Thereafter, handling of byte streams in bothdirections is performed entirely by Tenex.When the connection is terminated (either normally or abnormally), Tenex destroys the assignedport, releases the network terminal, and detaches the controlled job (if any). fpXG?b+`+_& \/JZLY%OWOV,%T6S P,@N ?M"1KFJ+H&.G& D)9BGA>:.<+;0-9/8&6(5)3'2)0(/%--+, )5'Q&Q$r; t pT  P  )4* 3r0p O ; * 0K N d>/[UImplementation of Pup in Tenex12The Telnet protocol itself is described in the memo Pup Telnet Protocol. We describe here onlythose aspects of it that are peculiar to Tenex.When a Synch signal (Interrupt and Data Mark) is received, it causes the attached terminal inputbuffer to be cleared in addition to its normal effect of flushing the incoming byte stream.The Tenex CFOBF JSYS, when executed for a network terminal, generates a Synch and therebycauses the user's terminal output buffer to be cleared and all data already in the outgoing bytestream to be flushed.The DOBE JSYS, when executed for a network terminal, invokes the Telnet Timing Mark protocolso as to wait until all previous terminal output has been processed by the Telnet user.Upon receiving a terminal parameter command, the Tenex server Telnet sets the corresponding localparameter for that network terminal. The default terminal type is NVT (7), and the default linewidth and page length are 72 and 66 (decimal), respectively.ImplementationProcessing of Pups is performed by Tenex at three major levels. At the lowest level (input andoutput interrupt level), Pups received from NVIO are merely placed on the input queues for theappropriate ports, and Pups to be output are removed from the port output queues and passed toNVIO.At the second level lies the byte stream processor, which performs the work required to transform aqueue of raw input Pups into a queue of buffers containing a pure byte stream, and the reverse onoutput. The byte stream processor is implemented by an independent background Tenex processwhich runs on demand and which also performs various other tasks such as executing theRendezvous Protocol and handling I/O for network terminals.The highest level consists of the user program interface and related routines that are sequentiallyexecuted in response to JSYS calls. For ports open in byte stream mode, this level communicateswith the byte stream processor, whereas for ports open in raw packet mode, communication isdirectly with the interrupt-level Pup driver.Tenex/NVIO CommunicationTenex performs I/O to all networks through NVIO (or AltIO on Maxc2). NVIO's role is limited topassing packets between Maxc and the various networks, and providing a moderate amount ofbuffering. It has proven necessary for NVIO to have some knowledge of Pup format so as todistinguish between Pups and old-protocol MCA and Ethernet packets and to permit filtering ofobviously bad input packets at the lowest level. However, no logical processing is performed onPups by NVIO. Even forwarding of packets to other hosts (Maxc's gateway function) is performedby Tenex.For Pup input, Tenex passes NVIO the address of a maximum-length buffer in Maxc main memory.Upon receipt of a packet from any network, NVIO transfers that packet from its own buffers to theMaxc buffer. It then stores data in an overhead word in the buffer informing Tenex of the numberof Maxc words in the packet itself and the physical source address of the packet (network and host).Finally, NVIO generates a Maxc interrupt, and it is done with this packet.For Pup output, Tenex passes NVIO the address of a buffer containing a packet to be transmitted(with overhead word already set up). If NVIO has sufficient room to buffer the packet, it copies itand notifies Tenex that it has taken the packet. NVIO will discard any packets that it cannottransmit within a short timeout (e.g. due to repeated collisions on the Ethernet or an unresponsivedestination host on the MCA). fpXG? b3up `/ ]'9 \/5& YJD W:& V@ S[S QW N#> MlS K< GZt Dup+4 BupH Ak,2 ? =up1 ;|:' 9 P 8rH 6; 4"up  2L 0 N /y- *u (p<# &Y $J #xF !B nX  H /2  U u"B J  0/ a 1- |U  ?/[ZJImplementation of Pup in Tenex13With the introduction of Pup and packet-at-a-time transfers between Tenex and NVIO, we havetaken the opportunity to do away with the previous word-at-a-time protocol used for Arpanetcommunication. The word-at-a-time protocol was originally implemented in an attempt to emulate the BBN PDP-10/Imp interface so as to minimize changes to the Tenex Imp driver. In retrospect, this goal proved not to beworthwhile. NVIO can distinguish between Pup, Host-Host Protocol, and other types of packets bylooking at the link number of both incoming and outgoing Arpanet messages. In the case of Host-Host Protocol messages, NVIO can also take advantage of the variable byte size capability of theNova-Imp interface to perform reformatting that was formerly done at interrupt level by Tenex.Interrupt-Level Pup ProcessorPup input is initially enabled by the Pup background process, which allocates and locks into core aqueue of free, maximum-length Pup input buffers, and is responsible for maintaining a sufficientnumber of input buffers in this queue so that it never becomes empty (unless an excessive numberof input Pups have been buffered but not yet taken by user processes). The address of the firstbuffer is passed to NVIO to be filled with a Pup.When a Pup has been received and NVIO has triggered the Pup input completion interrupt inMaxc, the following operations are performed:1.The address fields in the Pup header are checked for reasonableness. Zero networknumbers are defaulted to their proper values (see the memo Naming and AddressingConventions for Pup).2.If the Pup Destination is not Maxc, the Pup is passed to the gateway processor (to bedescribed later) for immediate forwarding to another network/host.3.The Destination Socket number (only) is used to compute a hash probe into the local sockettable. The correct port is found by comparing the Pup Destination with the local portspecification of each port checked, ignoring wildcard elements. If no match is found, thePup is discarded. (Source address filtering is not performed at interrupt level.)4.If too many unprocessed Pups are already queued for the input port, the Pup is discarded.Otherwise, the buffer is linked to the end of the input buffer queue for that port, and isunlocked from core.5.If the "Pup Received" interrupt is enabled for that port, a PSI request is generated for theowning process. If the port is a BSP port, the Byte Stream processor is awoken. Actually, forports controlled by JFNs (as opposed to NVTs), the awakening of the Byte Stream processor is delayed for 100milliseconds so as to give the user fork an opportunity to do the BSP processing itself, assuming it is blockedfor I/O over that connection. This reduces process-switching overhead.6.The next free input buffer (if any) is taken from the free input buffer queue and passed toNVIO, and the interrupt is dismissed.Output Pups generated either from user level or by the byte stream processor are locked into coreand linked to the end of a single output buffer queue (the number of Pups and the amount ofstorage occupied by them are, however, maintained on a per-port basis). If Pup output is idle, anoutput interrupt is then manually initiated to start things moving.When the output interrupt routine is called, it first disposes of the buffer just output (if any), as willbe described shortly. A buffer is then removed from the front of the output queue, its address ispassed to NVIO, and the interrupt is dismissed.Pups generated by the byte stream processor may also be on a second queue called the BSP outputqueue (threaded through a separate cell in the buffer header). When Tenex receives an interruptsignalling that NVIO has finished with such a packet, the interrupt routine does nothing with thatbuffer, but rather leaves it for disposal or possible retransmission by the byte stream processor.However, if the buffer is not on the BSP output queue, it is immediately unlocked and placed on aqueue to be deallocated by the Pup background process. (The interrupt routine cannot perform the fpXG? b1* `O _r9# ])pr) \ pT Z V YN W{D Su PpM OX R ML LN` J1 G%4 F_- CzD A%u@pp ='up<B 9!,.7K 6L 4R 1B0(1up. +;!*9%+r(l'a &^G #p@"% 3!@ "up )11 C Q :/3 / Du KpG ] AG <% 7C ?/^Implementation of Pup in Tenex14deallocation itself because the storage allocation routines may reference nonresident storage).Routing of each Pup to the correct immediate destination network and host is accomplished bymeans of a routing table, which contains an entry for every accessible network. Directly-connectednetworks have their entries assembled in. Entries for other networks are initially empty(inaccessible) and are maintained by the PUPSRV program on the basis of its interactions with otherGateways using the Gateway Information Protocol.Pup Background ProcessA number of tasks are performed by the Pup background process, which is an asynchronous,independent Tenex process running as a fork under job zero. Included in these tasks are thefollowing:1.Global storage management, such as allocating and locking free input buffers, deallocatingused output buffers, and occasionally garbage collecting the socket number hash table.2.Network terminal handling. All network terminals are periodically scanned for service.Input data is retrieved via byte stream processor subroutines and packed into terminal inputbuffers, and terminal output is unpacked and given to the byte stream processor to transmit.3.Byte Stream and Rendezvous Protocol processing. Each port open in byte stream mode(including network terminal ports) has associated with it sufficient state to permit the (single)Pup background process to scan through all ports and perform any needed services for eachone. Hence we may describe these operations as if there were a separate process handlingeach byte stream.Input processing is performed whenever the port's input buffer queue is found to be non-empty.The byte stream processor dispatches on the Pup Type field of each Pup, disposes of it asappropriate, and continues until the input buffer queue is empty.When Data (and AData) Pups are processed, they are placed on a queue called the BSP inputqueue, ordered by the value of the Pup ID. Duplicate packets are discarded during this step. TheBSP input queue is divided into two segments: a "complete" segment at the front and an"incomplete" segment at the back. The "complete" portion constitutes an uninterrupted bytestream, which may immediately be read by a JSYS call or transferred to terminal input buffers. The"incomplete" portion (which, by definition, begins at the first gap in the byte stream) consists of alllater packets that may have been received out of sequence.The byte stream processor maintains a pointer to the boundary between the "complete" and"incomplete" portions of the BSP input queue, and updates it as gaps are filled in by newly-arrivingdata. It also maintains a "left window edge" which is the byte ID of the first packet in the queue,and a "right window edge" which is equal to the left window edge plus a constant determining themaximum number of bytes that may be buffered for a single port. The byte stream processor willdiscard received data packets whose Pup IDs lie outside this window.After processing all packets in the input buffer queue, the byte stream processor sends anAcknowledgment if an AData was encountered. The Acknowledgment packet is generated asfollows: The Pup ID is set equal to the byte sequence number corresponding to the first gap (i.e.the beginning of the "incomplete" segment of the BSP input queue), hence cumulativelyacknowledging all the "complete" data. The Number of Bytes field is set to the difference betweenthat and the right window edge. All Pups in the "incomplete" portion of the queue are thenspecifically acknowledged in the PosAck/NegAck Blocks field of the Ack packet. The current version ofthe software generates no PosAck/NegAck blocks in outgoing Acknowledgments, and ignores PosAck/NegAck blocks inincoming Acknowledgments.Output is handled in a similar fashion. Data generated by the outputting process is delivered to thebyte stream processor as a queue of Pups which we call the BSP output queue. This queue isthreaded through a different cell in the buffer header than is used for the output buffer queue fpXG? b_ _9D ] Y \/ > Z7, Y%0 Ulu Rp9 QK O} L"8K K H.1&F\E$5' B?/$@T ?5@=,-<+ 9FS 7P 6<A 3WPu 1p] 0M= .&5 -CF +J *9: 'T4$ %D $J V "` !@2- D ; Q,* G G !A ;' =; >r W:5  Yp-8 6up O;$ ?/]pImplementation of Pup in Tenex15referenced at interrupt level. The byte stream processor also maintains a "window" of Pup IDs thatmay be transmitted, based on information in received Ack packets.To transmit a packet, the byte stream processor stamps it with the current time and places it in theoutput buffer queue, but without removing it from the BSP output queue. Each time the bytestream processor services an outputting port, it (re)queues for output all packets lying within thewindow that have (a) not been transmitted previously, (b) timed out, or (c) had negativeacknowledgments received for them.The last retransmitted packet on the BSP output queue is send as an AData rather than a Data Pupif (a) the oldest unacknowledged packet on the queue is older than the "hold time" (currently 0.5second), or (b) allocation has fallen to less than 25% of its value in the most recently received Ack.When an Ack packet is received, all packets being positively acknowledged (either cumulatively orspecifically) are removed from the BSP output queue, and also from the Pup output buffer queue ifthey are already queued for retransmission. Buffers for which negative acknowledgments arereceived are marked for immediate retransmission. The window parameters are then updated withthe new information in the Ack, possibly permitting the user process to generate further output.Received Pups other than Data, AData, and Ack are passed to a subroutine implementing the finitestate machine described in the memo Pup Connection State Diagram.JSYS Call ProcessorThe JSYSes for the most part are very straightforward and may be implemented by anuncomplicated mapping from the user program interface specifications given earlier.The PUPI and PUPO operations for raw packet I/O simply remove packets from the input bufferqueue and append packets to the output buffer queue, respectively. No action by the Pupbackground process is required.For sequential input and output, packing and unpacking of the data is performed at JSYS level.The sequential input routine sets up a byte pointer to the first buffer in the BSP input queue and abyte count equal to the number of bytes in the Pup. The data thereafter is removed by the device-independent handlers for BIN, SIN, etc. When the packet is exhausted, the byte stream processor isawoken to do any necessary servicing (such as updating the window parameters), and the sequentialinput routine immediately proceeds to the next packet in the BSP input queue. If the "complete"portion of the queue becomes exhausted, the process blocks until it again becomes non-empty.The sequential output routine allocates a buffer capable of holding a maximum-length Pup, thensimply sets up the appropriate byte pointer and count. Actual packing of the data is done by thedevice-independent BOUT and SOUT handlers. When the buffer is full or must be forced out (byCLOSF, MTOPR 21, etc.), it is placed on the end of the BSP output queue and the byte streamprocessor is awoken. The process then blocks if the number of Pups or bytes on the BSP outputqueue exceeds the maximum permitted for one port.Byte stream processing is performed at JSYS level where possible so as to reduce the frequency ofwakeups of the Pup background process. To prevent anomalies due to race conditions, each porthas a lock associated with it, serving as a global interlock for BSP-related processing for that port.Gateway ProcessorMaxc may optionally be a Pup Gateway between the networks to which it is connected. This iscontrolled by the GATEWF assembly switch. At present, Maxc1 is a Gateway and Maxc2 is not.In order to minimize the overhead required to perform forwarding of packets from one network toanother, the gateway processor is immediately called at input interrupt level upon receipt of a packetwhose destination is not Maxc. Forwarding is accomplished by the following sequence ofoperations: fpXG? b9* `A ]%? \/up& Z'< Y% 5# W" TP S6*7 QC# NO MG8) K[ J=1- H3- E8( DN$up @u =pR <+S 9FN 7M 6< 3W> 16. 0Mb .J -Ca +Q *9@ 'TE % V $J> "> !@-1 1 F Q*4 a u .pD +r" p*5 ?7/ A 5 L ?/^]Implementation of Pup in Tenex161.The hop count in the Transport Control field is incremented, and the Pup is discarded if itreaches the value 8.2.If the Pup Checksum is non-nil, it is updated to account for the Transport Control field'shaving been changed. This change is made incrementally, so the updated checksum will becorrect only if the original checksum was correct. The gateway processor neither generatesnor checks Pup Checksums.3.The Pup is routed and linked to the end of the Pup output queue in the same manner as isdone for normal Pup output. fpXG? b,/` ]@\/)/Z7$Y% V@?T. Tt>/P TIMESROMAN  TIMESROMAN  TIMESROMANLOGO TIMESROMAN  TIMESROMAN    ! w, 6 @HOV^ g ~r | j/TENEX-PUP.bravoTaftSeptember 3, 1979 5:48 PM