ITS TCP user interface documentation ============================================================================ Contents: 1 Contents, intro 2 List of affected ITS calls - name, internal dispatch points, general summary of changes 2 - General device I/O 3 - Unusual calls 4 - New calls 5 Mapping from TCP document (RFC-793) to ITS This file is intended to eventually specify all details of ITS system calls that pertain to TCP/IP. As a useful service, info about the old-style NET/NCP and CHAOSnet calls is also included. There are some places with details of the internal implementation, where it might affect how the user interface is designed. CALLNAME [internal dispatch info] Indices 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: DCHSTB(ioidx) ridx: RSTB(ioidx) OPEN [DEVADR(opnidx)] NET: NETO - sets ioidx = NETDUI, NETDUO, NETDBI, NETDBO TCP: TCPO - sets ioidx = TCPDUI, TCPDUO, TCPDBI, TCPDBO CHA: none, uses CHAOSO; sets ioidx = CHAIDN, CHAODN Actually for TCP we will probably have to use a TCPOPN call rather than further distorting the standard OPEN. However, I would like to find some elegant way of continuing to use OPEN. CLOSE [CLSTB(ioidx)] NET: NETCLS TCP: TCPCLS CHA: CHACLS See full description for the CLOSE syscal. Basically acts like NET/NCP rather than CHAOS. Note control bit which will cause immediate abort of the TCP connection (sends RST). IOT, SIOT [IOTTB(ioidx) -> device I/O rtns] NET: NETI, NETW, NETBI, NETBO (corresponding to ioidx) TCP: TCPI, TCPW, TCPBI, TCPBO CHA: CHAUI, CHAUO TCPBI and TCPBO (block mode I/O) is not actually legal. The entries were just thrown in to emulate NET. Maybe they can still be used for something. Note Image mode is a no-no too. Note that because TCP allows overlap of data segments, it might be possible to always retain a copy of the last 3 bytes sent, so as to allow aligning stuff on word boundaries (either for transmitting or for copying from user buffer). STATUS [LH(DTSTB(sidx))] NET: STANET TCP: TCPSTA CHA: popj Only new thing to STATUS is the new TCP device code, and the new TCP status bits in 2.9-2.4. WHYINT [RH(DTSTB(sidx))] NET: NETWHY TCP: TCPWHY CHA: CHAWHY New code %WYTCP and a new set of returned values. Should return TCP-URGENT value (# bytes to go, 0 if none). Note that an interrupt can be generated by receipt of a TCP-URGENT message. RFNAME [LH(DRFNTB(sidx))] NET: NETRCH TCP: TCPRCH CHA: popj Similar to WHYINT. Should return TCP-URGENT value (# bytes to go) RFPNTR [RH(DRFNTB(sidx))] NET: OPNL34 TCP: TCPRFP CHA: OPNL34 TCP will just return OPNL34 too. IOPUSH, IOPOP [LH(RSTBI(ridx))] NET: NETIOP TCP: TCPIOP CHA: CHAIOP No user perceptible difference. RESET [RH(RSTBI(ridx))] NET: NETRS TCP: TCPRS CHA: popj For TCP, what should this do?? Probably nothing. Could reset TCP-URGENT value, but seems like there might be a race condition danger here (which exists for NCP too anyway) FORCE [LH(DFRCTB(ridx))] NET: NETFRC TCP: TCPFRC CHA: CHAFRC For TCP, will immediately queue any buffered output for sending, and set the TCP-PUSH flag for this data. If for some reason it becomes useful to force a send without the TCP-PUSH flag, a control bit could be defined to disable it. FINISH [RH(DFRCTB(ridx))] NET: NETFIN TCP: TCPFIN CHA: CHAFIN For TCP, do a FORCE and wait for ACK of all data. Always implies a TCP-PUSH. Oddities: RCHST (obsoleted by RFNAME, RFPNTR, WHYINT) Non-I/O Network related calls: NETAC(ch) - accept NCP connection .NETAC ch, NET: ANETAC NETBLK(ch,state,time) - Block on network chan state NET: ANETBL CHA: CHANBK ; Goes here first if chaosnet exists NETHST(host) - Arpanet host status ANETHS NETIMP() - Read or set Arpanet IMP status ANETIM NETINT(ch) - Send network interrupt (NCP: INR/INS) .NETINT ch, NNETINT .NETS ch, same as FORCE STYNET(sty,neti,neto,rstr) - Hook STY to net chans NSTYNT STLGET(tty) - Not directly involved with net, but may want to have this call return true host address later. Chaosnet only: CHAOSO(ch1,ch2,winsiz) CHAOSO CHAOSQ(bufadr) CHAOSQ PKTIOT(ch,bufadr) PKTIOT New network related calls: TCPOPN - special OPEN like CHAOSO for opening TCP connections. NETRFC(netspec,arg) NETRFC Returns pending RFC value for specified network. Can refuse them. IPQ only: IPKIOT(ch,bufadr,cnt) NIPKIO Mapping from TCP specification (RFC-793) to ITS: Connection states: Note that states are somewhat confusing since ITS wants to treat input and output a bit differently. Some of this could probably be cleared up by providing separate indications of input-availability or output-waiting, which would also indicate whether input or output was still allowed. RFC-793 states: CLOSED Closed LISTEN Waiting for SYN SYN-SENT SYN sent, waiting for matching SYN SYN-RCVD SYN rcvd/sent, waiting for ACK of SYN ESTAB Open, input available FIN-WAIT1 Sent FIN, wait for ACK or FIN FIN-WAIT2 Sent FIN, rcvd ACK, wait for FIN. CLOSING Sent FIN, rcvd FIN, wait for ACK. TIME-WAIT Wait for our last ACK to reach remote site. CLOSE-UWAIT Rcvd FIN, sent ACK, wait for user close LAST-ACK User closed from -UWAIT, sent FIN, wait for ACK ITS I/O Channel states: %NSxxx ITS/TCP RFC793 DESCRIPTION 0 CLS %NTCLS CLOSED Closed 1 LSN %NTLSN LISTEN Waiting for SYN to arrive 2 RFC %NTSYR SYN-RCVD Rcvd SYN, waiting for ACK of our SYN 4 RFS %NTSYN SYN-SENT Sent SYN, waiting for matching SYN 5 OPN %NTOPN ESTAB Open, idle (can do I/O) 6 RFN %NTWRT ESTAB O: Output blocked temporarily (but open) 11 INP %NTINP ESTAB I: Input available 10 CLI %NTCLI CLOSE-WAIT I: Input avail, it's the last batch or CLOSING 3?RCL? %NTCLU CLOSE-WAIT I: No more input available, remote site FINed, but output is still open waiting for user to close it. 7 CLW %NTCLX LAST-ACK No more input, can't output, awaiting or FIN-WAIT1 various finalizations before closing. or FIN-WAIT2 or CLOSING or TIME-WAIT This page documents how the user-invoked calls in RFC 793 can be emulated using ITS system calls. ------------------------------------------------------------------------- OPEN(local port, fgn port, active/passive [,timeout] [,precedence] [,security/compartment] [,options]) Returns local connection name (LCN) Use new TCPOPN system call to set up input/output TCP channels. Timeout, precedence, security/compartment, and options cannot be set. ------------------------------------------------------------------------- SEND(LCN, bufadr, cnt, PUSH, URGENT [,timeout]) Use IOT/SIOT on output TCP channel. There is no user-specified timeout; ITS uses an internal timeout (approx 1 minute) which is the same for all connections. A user-specified value could be an additional argument to IOT/SIOT as well as to TCPOPN. PUSH can be done with FORCE/FINISH. There could also be an IOT/SIOT control bit, although this is somewhat redundant since ITS always sets PUSH anyway for all outgoing segments. There is no way to set URGENT. This could be an IOT/SIOT control bit. Unfortunately NETINT cannot be used to set this since zero-length segments can't be used with URGENT; the remote process won't see a signal unless it comes with data that hasn't yet been read by the process. Ditto PUSH for that matter. Note: doing output-reset on a directly-connected STY (i.e. hooked up via STYNET and sending %TDORS) will send a string of up to 3 bytes with the URGENT flag set. ------------------------------------------------------------------------- RECV(LCN, bufadr, cnt) Returns cnt, urgent, push Use IOT/SIOT on input TCP channel. PUSH and URGENT are currently ignored. They could perhaps be read via status calls; URGENT could generate an interrupt condition similar to the way the old NCP INS stuff worked. ------------------------------------------------------------------------- CLOSE(LCN) Use CLOSE on both TCP channels. ------------------------------------------------------------------------- STATUS(LCN) Use the various calls like STATUS, RFNAME, WHYINT. ------------------------------------------------------------------------- ABORT(LCN) There is currently no way to send an RST for a connection. The user program can simply close both TCP channels, since this returns immediately, and let the system worry about graceful cleanup. It would be possible to provide a control bit for CLOSE which, when used on either TCP channel, would mean to abort the connection and send a RST. ------------------------------------------------------------------------- Remaining notes on various stuff: * Problem with CLOSE for TCP connections: A CLOSE on the output channel will cause an automatic FORCE, and a FIN segment will be sent to the remote host indicating "no more data to send". However, the input channel will remain open, and data can continue to be read from it. A CLOSE on the input channel will cause any further input received to be thrown away by ITS. Output can continue to be sent. Return from this call is immediate; it will not hang. Note that, like NCP, this does not allow the user to determine whether the last stuff successfully reached the destination or not. When this is desirable, a FINISH should be done prior to the CLOSE. !!!***> Possible alternate actions: - Hold up input (don't ACK it) - Close both channels - Abort (send RST) Note must pay attention to "default" action without control bits, which happens during job killing, IOPOPing, and the like. !!!***> ADD THIS FEATURE?? A CLOSE with the "abort" control bit set will cause immediate abort of the TCP connection (sends RST), and closes both input and output channels regardless of which was furnished. IOT/SIOT: Must document don't-hang mode for .INFO.;ITS .CALLS. UAI, UAO ; Only modes currently allowed, for SIOT. UII, UIO ; The rest are undefined; could be used for BAI, BAO ; other stuff, if any ideas turn up. BII, BIO Must define control bits for: - URGENT - looks like this is the place to put it. - PUSH? or just use FORCE for this? If new ctl bit added, should probably be a device-independent FORCE. NETWORK RELATED CALLS: CLOSE (general) FINISH (dev dep) FORCE (dev dep) IOPOP (general) IOPUSH (general) IOT (general) IPKIOT (IP datagram I/O - not documented yet) NETAC (NCP only) NETBLK (NCP/TCP/CHA) NETHST (Arpanet hosts only) NETIMP (May not work) NETINT (NCP only) OPEN (dev dep) RESET (dev dep) RFNAME (dev dep results) RFPNTR (general - no net meaning tho) SIOT (general) STATUS (dev dep results) STYNET (NCP/TCP/CHA) TCPOPN (TCP channel open) WHYINT (dev dep results)