IEN 150 W. Plummer BBN J. Postel ISI June 1980 TCP JSYS CALLING SEQUENCES This memo describes the TENEX and TOPS20 JSYSs for using TCP. There are a number of parameters that are common to this set of JSYSs and these are described first. These JSYSs use a Job Connection Number or "JCN" for connections in much the same way file manipulating JSYSs use a Job File Number or "JFN" for files. Typically a small number, the JCN is a handle on a connection, and is assigned by the OPEN JSYS. These JSYSs also use a Connection Block , either directly or implicitly by reference to an associated JCN. The Connection Block is a 3-word block: Word-0: 16-bit Local Port. Word-1: 8-bit Foreign Network and 24-bit Foreign Host. Word-2: 16-bit Foreign Port. These values are right justified in the 36-bit word. These JSYSs take flags in the left half of AC 1. Not all of these JSYSs look at all of the flags. The flag bits are: Bit-0: RH has JCN rather than pointer to connection block. Bit-1: Wait for the JSYS to complete. Bit-5: ForceSync -- cause SYN to be sent when OPEN executed. Bit-6: Persist -- keep resending SYN packet. Bit-7: Return statistics (STAT call only). Plummer & Postel [page 1] June 1980 TCP JSYS Calling Sequences The SEND and RECV JSYSs use data buffers which have control blocks and which may be chained together to form a ring of buffers. These control blocks are called Data Buffer Ring Elements. The Data Buffer Ring Element Format is: Word-0: Flags,,unused by TCP (typically a pointer to next buffer header) Word-1: 0,,Address of data buffer Word-2: Word/Byte count for this buffer Flags: Done: Cleared when TCP receives this buffer. Set when TCP has finished with it. Error: Buffer has an error associated with it. EOL: Send an end-of-letter with this buffer. Or, end-of-letter received with this buffer. WordMode: Buffer is formatted as 36-bit bytes. Off if buffer has four 8-bit bytes per word. (Not Implemented Yet, 36-bit mode not supported.) Flag Bit Assignments: Bit 0: Error Bit 1: Local Bit 2: Permanent Bits 3-7: Error Number Bits 8-11: Unused Bit 12: Done Bits 13-15: Unused Bit 16: EOL Bit 17: Word Mode The error numbers are listed under "Error Returns". [page 2] Plummer & Postel TCP JSYS Calling Sequences June 1980 The OPEN ans SEND JSYSs take a "Retransmission Parameters" word. This is controls the retransmission function. The right half is the initial retransmission Interval which is to be used. If the right half is 0, the initial Interval will be computed based on the measured round trip time. The left half of the parameters word has two 9-bit quantities, called the Numerator and the Denominator. In computing the next retransmission Interval from the previous one, the TCP multiplies the Interval by the Numerator and then divides by the Denominator. Interval = Interval * ( Numerator / Denominator ) Common retransmission functions are: SRI PR demo: Numerator=1, Denominator=1, Initial Interval=3. 3 seconds constant retransmission interval with no backoff. BBN (vanilla): Numerator=3, Denominator=2, Initial interval=0. Used in "average" conditions involving congested gateways and few dropped packets. 150% backoff from best guess initial interval. BBN (old): Numerator=4, Denominator=2, Initial interval=0. Same as above but 200% backoff. Quickly hits the 1 minute maximum interval and turns into slow, constant period retransmission. Plummer & Postel [page 3] June 1980 TCP JSYS Calling Sequences Error Returns When a JSYS does an error return (returns +1 instead of +2), AC 1 contains an error code. This code is an 8-bit number (right justified in the 36-bit word) composed as follows: Bit Assignments: Bit 28: Error Bit 29: Local Bit 30: Permanent Bits 31-35: Error Number The error numbers are: 0 Unknown Error 1 Argument Error in JSYS (no access, bad JCN, etc.) 3 Connection Not Open 4 Temporarily Out of Resources 6 Connection Already Exists 7 Connection Error or Rejected (No such TCB either here or there.) 9 Transmission Timeout 12 Connection Closed or Closing (Closed remotely.) 15 Bad Buffer Argument 17 Bad Argument to CHANL 20 Funny pointer to STAT (wraps around memory, etc) 21 Bad Transfer Size to STAT 29 Cannot change security level (SCSLV) 31 TCP Not Available The Error bit indicates if an error occured, for example error number 12 might not have the Error bit set in response to a CLOSE call. The Local bit indicates if the situation is local to this host or is due to the remote host. The Permanent Bit indicates if the situation is permanent, or temporary. [page 4] Plummer & Postel TCP JSYS Calling Sequences June 1980 OPEN (JSYS 742) 1/ Flags,,Pointer-to-Connection-Block 2/ Persistence in seconds 3/ Retransmission parameters OPEN R+1: failure, code in AC 1 R+2: OK, JCN (Job Connection Number) in AC 1 Flags: ForceSync: On to force synchronization without any data having been sent. Wait: Don't return until connection is opened. Persistent: Keep trying by sending SYN packets periodically. Plummer & Postel [page 5] June 1980 TCP JSYS Calling Sequences CLOSE (JSYS 743) 1/ Flags,,JCN-or-Pointer CLOSE R+1: failure, code in AC 1 R+2: OK, connection fully closed Flags: JCNSupplied: On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection Blk. Wait: Wait for close to happen in both directions. Note that if the wait bit is not set, the JCN will remain valid, allowing more RECVs to be done. ABORT may be used to release the handle when it has been discovered that the connection has terminated. [page 6] Plummer & Postel TCP JSYS Calling Sequences June 1980 SEND (JSYS 740) 1/ Flags,,JCN or Pointer-to-Connection-Block 2/ 0,,Pointer-to-Data-Ring 3/ Timeout in Seconds (0 for infinite) 4/ Retransmission parameters SEND R+1: failure, error code in AC 1 R+2: OK, JCN in AC 1 Flags: JCNSupplied: On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection Blk. Wait: Wait for close to happen in both directions. Plummer & Postel [page 7] June 1980 TCP JSYS Calling Sequences RECV (JSYS 741) 1/ Flags,,JCN or Pointer-to-Connection-Block 2/ 0,,Pointer-to-Data-Ring RECV R+1: failure, error code in AC 1 R+2: OK, JCN in AC 1 Flags: JCNSupplied: On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection Blk. Wait: Wait for close to happen in both directions. [page 8] Plummer & Postel TCP JSYS Calling Sequences June 1980 STAT (JSYS 745) 1/ Flags,,JCN or Pointer-to-Connection-Block 2/ -N,,Offset into TCB 3/ -M,,Address in user's space STAT R+1: failure, error code in AC 1 R+2: OK. Flags: JCNSupplied: On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection Blk. Returns statistics: This flag causes the TCP to dump words from the statistics area rather than a specific TCB. Thus, the JCN is irrelevant. The Source and Destination ACs are updated as if a TCB were being dumped. If successful min(M, N) words have been transferred from the TCB to the caller's space. The TCB offset identifies where the transfer starts and the Address in user space identifies the start of the destination area. Plummer & Postel [page 9] June 1980 TCP JSYS Calling Sequences CHANL (JSYS 746) 1/ Flags,,JCN or Pointer-to-Connection-Block 2/ Six 6-bit bytes (channel numbers) CHANL R+1: failure, error code in AC 1 R+2: OK. This fork will receive TCP PSIs Flags: JCNSupplied On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection Blk. Each of the 6-bit bytes may be 77 (octal) if no PSIs are desired for the corresponding event. Bits 0- 5: INTRP channel Bits 6-11: RECV buffer done Bits 12-17: SEND buffer done Bits 18-23: Error Bits 24-29: State change (open or close) Bits 30-35: EOL acknowledged (Not implemented) PSIs for the above may be dropped or be VERY tardy on heavily loaded systems. Some defensive programming is required to guard against these problems. See TCPTST.MAC which checks the buffer rings both when a "done" interrupt occurs and periodically. [page 10] Plummer & Postel TCP JSYS Calling Sequences June 1980 ABORT (JSYS 747) 1/ Flags,,JCN or Pointer-to-Connection-Block ABORT R+1: error, code in AC 1 R+2: OK, connection deleted Flags: JCNSupplied: On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection Blk. The local end of the connection is forgotten. An attempt to notify the remote end is made by sending a RST packet. Should this not be delivered, the other end will discover its half open connection the next time it attempts to use it. Plummer & Postel [page 11] June 1980 TCP JSYS Calling Sequences SCSLV (JSYS 744) 1/ Flags,,JCN or Pointer-to-Connection-Block 2/ 36 bit security value SCSLV R+1: failure, error code in AC 1 R+2: OK. The security value has been associated with the connection Flags: JCNSupplied On if RH of AC 1 has a JCN. Off if RH has Pointer-to-Connection Blk. The security value is not interpreted by the TCP (except to see that it matches). The number of bits of the security value actually used varries depending on the actual security procedure being in use. In all cases the rightmost bits of the word are used. [page 12] Plummer & Postel