[an error occurred while processing this directive]

Deluge
A Simple Network Driver for L4

Ada Lim


Click here for errata and source code for this driver.

Introduction

Deluge is a basic implementation of the User Datagram Protocol as described in [RFC768, TCP/IP]. The IP interface it sits upon (which is hidden from the user) is somewhat broken; however it works sufficiently well for our purposes.

As [RFC768] says, ``this protocol provides a procedure for application programs to send messages to other programs with a minimum of protocol mechanism. The protocol is transaction oriented, and delivery and duplicate protection are not guaranteed. Applications requiring ordered reliable delivery of streams of data should use the Transmission Control Protocol (TCP).''

[RFC768] also dictates the desired protocol; we have tried to temper the semantics given with the semantics of the L4 serial driver[L4REF]. Thus, we have changed the receive operation to be analogous to the input function of the serial driver. The interface is summarised in ipdriver.h.

Unix Interface

UDP consists of datagrams (packets) sent from a port on one host to a port on another host. Host IP addresses can be stored in a 32-bit unsigned int; port numbers range from 0-65535 and can be stored in a 16-bit unsigned int. Good port numbers to use are in the 1024-4096 range; if you do netstat -a on a box you can see which ports are already in use. High port numbers can only be used by recompiling the stack on the U4600 (which currently supports up to 4096 only). Ports below 1024 are reserved for use by root.

UDP is unreliable: packets can get lost, or arrive out of order. In addition, you are not guaranteed to be able to send more than 512 bytes; thus, you should limit your packet size to 512 bytes or less, like a good protocol (eg DNS, TFTP, etc (-: ).

A simple example program (echo).

General principles of the driver interface

All messages are sent in either a short IPC or a long IPC with exactly one string dope:

All other fields in the register portion are described below.

In general, all control information is sent in the register portion of the IPC; the long portion consists of a single string dope referring to a buffer of a pre-agreed length. In the initial handshaking, both server and client specify the string dope length they are willing to accept. Currently, the server will accept outgoing packets of up to 1kb and its incoming packets can be up to 1kb in size. These limits can be changed at compile-time, however increasing them may reveal bugs.

Note: The driver expects the PCI to be little-endian. Make sure your clock driver is little-endian as well, or you'll have problems!

Creation of new receive ports

A bind request (which performs the same as a socket()/bind() in the traditional Berkeley interface) has four parameters in a short IPC:

  1. Request type (UDP_BIND),
  2. Local address (port number to bind to),
  3. Maximum message size (maximum incoming packet size),
  4. Handler thread (where the packets should be sent to).

The return IPC is identical, except that the from address now has the main interface's IP address in the top 32-bit word, and the ``maximum message size'' is the size of the string that the server will listen with.

Sending data

The short portion of the IPC contains the following:
  1. Request type (UDP_PACKET),
  2. Local address (port number to bind to; IP address section ignored),
  3. Message size (size of packet in octets),
  4. Remote address (high word: IP, low word: port).

The long portion is a single string; its length should be the length returned in the bind call.

Receiving data

The bind call registers a listener thread which should be prepared to receive long messages consisting of a single string (of the same length that it registered with). Upon receipt of a packet, the server will send a long IPC with a short timeout; if the receiver is not ready, the packet is dropped (silently).

The message is sent in the same format as described above (in sending data).

Note that the thread which sends the data received from the network is different from the thread to which bind requests and data packets are to be sent.

References

RFC768
Jon Postel. RFC 768: User Datagram Protocol. ISI, 1980.
TCP/IP
Richard Stevens. TCP/IP Illustrated, Volume 1. Addison-Wesley, Reading, MA, USA, 1994.
L4REF
Kevin Elphinstone, Gernot Heiser, Jochen Liedtke. L4 Reference Manual, MIPS R4x00. UNSW, 1997.

Last modified: 04 Sep 2002. [an error occurred while processing this directive]