Internet Experiment Note 108 Internet User Queues William W. Plummer Bolt Beranek and Newman, Inc. 50 Moulton Street Cambridge MA 02138 19 June 1979 Internet User Queues William W. Plummer 19 June 1979 The Internet JSYSes provide a facility for user programs to send and receive Internet packets. This set of calls is parallel to the "IMP special queue" calls, which dealt only with the ARPANET. In order to use the Internet calls a program must first assign an Internet Queue using ASNIQ (JSYS 756). The arguments for this JSYS are a set of mask and value words that determine what messages may be sent and which of the incoming messages will be delivered to the owning job. A successful ASNIQ returns with a handle (a small number, short-hand for the queue), in T1 which can then be fed to SNDIN and RCVIN (SeND InterNet, ReCeiVe InterNet). The arguments for SNDIN are an Internet Queue Handle and a pointer to a buffer of data in the caller's space. Word-0 of this buffer is the size of the buffer, including this count word. Words 1 through 5 must have a Version 4 Internet Header (see last page). Various fields of the header are checked for legality, the source host word is filled in, the Internet header checksum inserted. Then a network interface is selected and a local leader for that network is constructed in the packet. The packet is then queued for output on that interface and SNDIN returns. Basically, users have no control over which interface is selected for packet output and no knowledge of which interface an incoming packet arrived on. This is analogous to the ARPANET where users have no control over which IMPs a message actually goes through. There is an exception when a system is equipped with a "Raw Packet Interface" (RPI) which is used to connect to a remote gateway or a encryption device (such as a BCR). Bit zero in T1 to ASNIQ will flag the queue as using the RPI rather than the normal interfaces. RCVIN takes the same arguments, an Internet Queue Handle and a buffer pointer. Normally, if no messages are already waiting on the queue, RCVIN waits. This wait can be defeated by turning on the "don't wait" control bit which forces an error return if no messages are waiting. When a message is available, it is delivered to the user- supplied buffer. The number of words filled is set into the left half of word-0 (the count word) of the buffer. Ordinarily this can be ignored, but if the message was too big for the buffer, this tells how much space would have been required. When finished, the queue handle can be released by using RELIQ. All handles owned by the job may be released by supplying -1 as the argument. - 1 - Internet User Queues William W. Plummer 19 June 1979 All Internet JSYS calls use only the left 32 bits of each word. This is true of both the ASNIQ argument block and of data buffers. Messages left waiting on an input queue for a long time (currently 30 seconds) will be deleted. Also, a queue cannot hold very many messages (32, today). Flooding an Internet input queue to a slow receiver will result in dropped messages. Messages addressed to the sending host will ordinarily be delivered without sending over any network at all and are reasonably fast. User programs have no control over which network a given message will be sent out over. This decision will be made by the host gateway module on the basis of routing information supplied to it by other Internet gateways. This means that all networks to which a host is connected must go down before Internet communications will be completely stifled, and even then, forks within a job will be able to communicate due to the local delivery mechanism. Programs using Internet messages must be aware that messages are not necessarily delivered in the order in which they were sent, some messages may be dropped and others duplicated. Some may traverse a broadcast network and be clobbered by other packets, lightning, flaky intermediate gateways, etc. Thus, some higher level protocol is needed in most cases. TCP is one example, but there are others (the "Datagram Protocol", XNET, etc.). If a particular protocol is implemented in the monitor (e.g., TCP) and that protocol module is turned on, no messages of that protocol type will be passed to users via Internet queues. Assigning a queue will still be possible, but no traffic will reach the user unless that protocol module is disabled. Not all Internet protocols have ports. If you are implementing one which does not, be sure that .IQPTM in the ASNIQ block contains a zero. If the protocol uses ports, they are expected to be in the first two 16-bit bytes following the Internet header, source port first and destination port second. The location of this word is found by adding the contents of the Internet data offset field to the address of the zeroth word of the Internet header. - 2 - Internet User Queues William W. Plummer 19 June 1979 An additional feature of the Internet Queue Mechanism is that it (optionally) provides an logical host capability. That is, incoming messages can be demultiplexed on the basis of bits in the Internet Destination Host field. Exactly which bits are considered logical host specifier bits depends on the naming conventions in force in the network (area) to which the host in question is connected. For ARPANET hosts, the middle 8-bit byte of the 24-bit Internet Host is considered to be the logical host specifier. ASNIQ takes a specification of what numbers are to be used in the logical host bits of the source address for packets which are sent and received. When a packet is sent, the logical host bits are obtained from the user's packet and combined with the Internet Host Identifier for the host being used, the result being inserted into the Source Host field of the packet. Incoming packets are accepted by the Internet Layer if they match the Internet Host Identifier (Name) when the logical host bits of the destination address have been set to zero. It is illegal to assign an Internet Queue such that the Logical host mask includes any bits which are not part of the logical host field. ASNIQ will give an error return in this case. - 3 - Internet User Queues William W. Plummer 19 June 1979 Assign Internet Queue JSYS ;T1/ Pointer to queue descriptor block ; (Bit-0: use Raw Packet Interface) ;T2/ (Unused, must be 0) ;T3/ (Unused, must be 0) ; ; ASNIQ (JSYS 756) ;Ret+1: Failed. Error code in T1. ;Ret+2: Success. Internet queue handle in T1. Format of a queue descriptor block: Word offset Name Contents 0 .IQPRV Internet protocol number in bit 24-31. Others should be 0. 1 .IQFHV Internet foreign host value word in bits 0-31. 2 .IQSHV Internet source host value word in bits 0-31. Used for logical host selection. 3 .IQPTV Internet port value word. Local port value in bits 0-15, foreign port in 16-31. 4 .IQPRM Mask word corresponding to .IQPRV. 5 .IQFHM Mask word corresponding to .IQFHV 6 .IQSHM Mask word corresponding to .IQSHV 7 .IQPTM Mask word corresponding to .IQPTV (Use 0 for portless protocols) The mask words specify those bit positions where an exact match is required. Thus, one can make .IQFHM contain 0 in order to talk to all Internet hosts. Or by making say the low 3 bits of the local port mask word be 0, one owns eight ports. Note that an error will result unless the current QDB differs in the masked in bits from all other Internet queues which are assigned at the instant the ASNIQ is issued. Possible errors: 600737,NTWZX1,NET WIZARD capability required 600740,ASNSX1,All Internet queues in use - 4 - Internet User Queues William W. Plummer 19 June 1979 600741,ASNSX2,Conflict with some other job (# in AC2) - 5 - Internet User Queues William W. Plummer 19 June 1979 Release Internet Queue JSYS ;T1/ An Internet Queue Handle or -1 for all ;T2/ (Not used. Must be 0) ;T3/ (Not used. Must be 0) ; ; RELIQ (JSYS 757) ;Ret+1: Failure. Error code in T1. ;Ret+2: Success. This JSYS releases ownership of an Internet queue so that other jobs can assign it. Note that neither the RESET JSYS nor the EXEC RESET command execute RELIQs. Thus, once the queue is assigned, it stays assigned until the job logs out. Possible errors: 600742,SQX1,Internet queue handle out of range 600743,SQX2,Internet queue not assigned - 6 - Internet User Queues William W. Plummer 19 June 1979 Send an Internet Message JSYS ;T1/ Internet Queue Handle ;T2/ Pointer to buffer containing message ;T3/ (Not used. Must be 0.) ; ; SNDIN (JSYS 754) ;Ret+1: Failure. Error code in T1. ;Ret+2: Success. The buffer must contain a word count in the right half of word-0, a valid Internet header in words 1 through 5, and possibly some data in words 6 and following. If port filtering is being used (.IQPTM was non-zero for ASNIQ), the ports must be located in the word following the Internet header. The address of this word is found by adding the address of word-1 in the buffer to the number in the Internet data offset field. The monitor fills in the source host field in the packet and also the Internet header checksum. The rest of the header is what is supplied by the user. Possible errors: 600742,SQX1,Internet queue handle out of range 600743,SQX2,Internet queue not assigned 600732,SNDIX1,Invalid message size 600733,SNDIX2,Insufficient system resources (No buffers available) 600735,SNDIX4,Invalid header value for this queue (Includes Internet Packet Length too big, Data offset too small, filtering on ports but packet length says packet does not contain a port word, and header does not fit the ASNIQ arguments). - 7 - Internet User Queues William W. Plummer 19 June 1979 Receive Internet Message JSYS ;T1/ Flags,,Internet Queue Handle ; Bit-0: On to cause fail return instead of waiting ;T2/ Pointer to buffer where message will be put ;T3/ (Not used. Must be 0.) ; ; RCVIN (JSYS 755) ;Ret+1: Failure. Error code in T1. ;Ret+2: Success. Each RCVIN gets one message from the named queue. These messages match the values in the queue descriptor block when masked by the mask words in the block. The number of words filled plus one (counting the count word) is placed in the left half of word-0 of the buffer. If the message was too big as determined by the Internet data length field, as much as will fit in the buffer is transferred and an error return given. No retry for the same message is possible. Possible errors: 600742,SQX1,Internet queue handle out of range 600743,SQX2,Internet queue not assigned 600732,SNDIX1,Invalid message size - 8 - Internet User Queues William W. Plummer 19 June 1979 ; The following structure definitions have been excerpted from ; the file INPAR.MAC which is used in building TENEX and TOPS20 ; monitors with Internet code. Those who are unfamiliar with the ; structure facility should refer to SYS:MACSYM.MAC. Basically, ; DEFSTR(Name,Location,Bit,Size) defines a structure called Name. ; This field is held in the word (possibly an index) at Location. ; The right-hand bit number is Bit and the field is Size bits wide. ; A typical reference to the data offset field might be: LOAD T1,PIDO,(PKT) ; where PKT is an index register which points at the zero-th word ; of the structure. ; Word offsets: .IPKVR==0 ; Word with version, type of service, etc .IPKSG==1 ; Word with segmentation info .IPKPR==2 ; Word with time to live, checksum, protocol .IPKSH==3 ; Word with source host .IPKDH==4 ; Word with destination host DEFSTR(PIVER,.IPKVR,3,4) ; PACKET.INTERNET.VERSION DEFSTR(PIDO,.IPKVR,7,4) ; PACKET.INTERNET.DATA-OFFSET DEFSTR(PITOS,.IPKVR,15,8) ; PACKET.INTERNET.TYPE-OF-SERVICE ; Overlays for the above: DEFSTR(PIPRI,.IPKVR,9,2) ; PACKET.INTERNET.PRIORITY DEFSTR(PISVD,.IPKVR,10,1) ; PACKET.INTERNET.STREAM-VS-DATAGRAM DEFSTR(PIREL,.IPKVR,12,2) ; PACKET.INTERNET.RELIABILITY DEFSTR(PISVR,.IPKVR,13,1) ; PACKET.INTERNET.SPEED-VS-RELIABILITY DEFSTR(PISPD,.IPKVR,15,2) ; PACKET.INTERNET.SPEED-OF-DELIVERY DEFSTR(PIPL,.IPKVR,31,16) ; PACKET.INTERNET.PACKET-LENGTH DEFSTR(PISID,.IPKSG,15,16) ; PACKET.INTERNET.SEGMENT-ID DEFSTR(PIFLG,.IPKSG,18,3) ; PACKET.INTERNET.FLAGS ; Overlays for the above: ; Unused bit DEFSTR(PIDF,.IPKSG,17,1) ; PACKET.INTERNET.DONT-FRAGMENT DEFSTR(PIMF,.IPKSG,18,1) ; PACKET.INTERNET.MULTIFRAGMENT DEFSTR(PIFO,.IPKSG,31,13) ; PACKET.INTERNET.FRAGMENT-OFFSET DEFSTR(PITTL,.IPKPR,7,8) ; PACKET.INTERNET.TIME-TO-LIVE DEFSTR(PIPRO,.IPKPR,15,8) ; PACKET.INTERNET.PROTOCOL DEFSTR(PICKS,.IPKPR,31,16) ; PACKET.INTERNET.HEADER-CHECKSUM DEFSTR(PISH,.IPKSH,31,32) ; PACKET.INTERNET.SOURCE-HOST ; Overlays for above: DEFSTR(PISHN,.IPKSH,7,8) ; PACKET.INTERNET.SOURCE.NET DEFSTR(PISHT,.IPKSH,31,24) ; PACKET.INTERNET.SOURCE.HOST DEFSTR(PIDH,.IPKDH,31,32) ; PACKET.INTERNET.DESTINATION-HOST ; Overlays for above: DEFSTR(PIDHN,.IPKDH,7,8) ; PACKET.INTERNET.DESTINATION.NET DEFSTR(PIDHT,.IPKDH,31,24) ; PACKET.INTERNET.DESTINATION.HOST - 9 - -------