If you've ever butted heads with UNIX serial ports, you've noticed that things often don't work just right. One reason is that most serial drivers are derived from a few ancestral sources, which have been hacked and kludged until they work--more or less. (Indeed, I've read two books on writing device drivers that start out by saying that the only practical way to write a terminal-like driver is by starting from someone else's driver.)

This is certainly the case with the serial driver that is part of FreeBSD, the UNIX-like operating system I run on my machine. That driver started out as the HP dca driver, was modified into the com.c driver, and was finally used to build the sio.c driver. It wouldn't surprise me at all to discover other transformations in there, too. The FreeBSD system is based on the 386BSD UNIX-like operating system developed by William Jolitz and described in a series of DDJ articles entitled "Porting UNIX to the 386" (January 1991--July 1992). FreeBSD is available from a number of sources, including Walnut Creek CD-ROM and the ftpmail server at gatekeeper.dec.com.

While the FreeBSD serial driver has several minor annoyances, its major defect is that your system can't dial in or out on the same serial line without manual intervention. After mulling over the options of further hacking the FreeBSD driver, waiting for developers to fix the problem, or porting an existing driver, I opted to write a new driver altogether. (This driver has since been ported to NetBSD, another 386BSD descendant.)

To successfully write a serial driver, you must have an understanding of concurrency and control flow in the device driver, the kernel interface, and the serial device itself. Good software-engineering practice dictates that the various parts of the driver be distinguished and separate; my driver has five sections: declarations, debugging and statistic facilities, hardware manipulation, state changes, and system-call interface.

In my serial driver, the declarations section contains type and variable declarations specific to the driver itself. In particular, the LINE_STATE enumeration describes the overall state of a line. One essential design decision was to describe the line-state concept using a scalar rather than a host of variables scattered through various data structures. By categorizing and characterizing the four primary states of a line before I began coding, I avoided most of the problems that beset other drivers. I'll discuss this further when I talk about the driver's open routine.

If you've ever written code that involved asynchronous events, you'll know just how difficult it can be to debug--bugs tend to depend on timing, so they are often very difficult to reproduce, much less track down. Ideally, you want a complete trace of the events that occurred just before the bug bit. In reality, such a trace requires that expensive hardware or CPU time be spent executing otherwise useless debugging code.

Each function entry, function exit, and significant driver action gets recorded in a circular buffer. This is moderately expensive in time, but a judicious use of inline assembly and functions in the debugging code keeps cost down. An external program takes a snapshot of the circular buffer, then interrupts and prints it out so that you can make sense of it. If the driver locks up the machine, the debugging code can be configured to record events on the console screen where, by no coincidence, the event codes result in distinguishable, readable characters on the screen.

Another useful item in this section is a "status print" routine. FreeBSD's kernel debugger, ddb, can call an arbitrary kernel function. At any time, you can break into the debugger and call this routine for a dump of most of a line's variables.

The hardware-manipulation section is the only part of the driver that knows the details of the hardware. Separating this part of the code let me implement a "virtual UART," which separates the bit-twiddling code from the primary driver logic. This also makes it relatively easy to support different sorts of hardware.

One difficulty of writing a serial device driver is that UNIX has a long interrupt latency. Consequently, serial drivers coded the "standard" way lose characters. One solution, "pseudo-dma," available in FreeBSD and used in my driver, replaces the standard interrupt-handler code with a much simpler one. Instead of establishing a normal UNIX execution thread with all the overhead that entails, the serial device's interrupt goes directly to the interrupt handler. Instead of calling standard UNIX functions to transfer data to and from the device (which is rather slow), data is transferred to and from the driver's control structures. The handler signals the UNIX kernel when it needs data or when it has data available; this functions much like an interrupt except that it is software generated. The "soft-interrupt" handler does the same work as a standard interrupt handler, except that instead of reading and writing to a device, it reads and writes to the driver's control structures.

The state-transition section moves data from here to there and keeps track of the state of the driver. Most of the tricky logic goes here. System calls eventually result in calls into this section, and the soft-interrupt handler is here. This part of the driver knows that it is dealing with a serial device but it relies on the hardware routines to do the actual device manipulation.

In many drivers, an attempt is made to propagate changes to driver variables throughout all the other variables that might be affected, This usually results in extremely complex code, full of incomprehensible conditionals--that never quite work right. In my driver, wherever this might be a problem, I use a different approach. I centralize the computation of the variable in a single routine, and then whenever anything might require a change to the variable, I call that routine. Instead of a computation from cause to effect that (hopefully!) considers exactly the effect that the change causes, I fully recompute the variable. The variable always has the right value, and if this is less efficient than the alternative, it isn't measurably so.

Having a state variable makes coding the open a snap. The heart of the open is of a single loop. On entry to the loop, the open wait count is incremented. The loop is only exited when the open is to fail with an error or succeed. In either case, the open wait count is decremented, because the open is not waiting anymore. Then, the open either returns an error or sets the appropriate open active flag and actually opens the line.

The loop is, conceptually, very simple. At the top of the loop, the line status is tested and the driver set to the appropriate state. Then a series of tests are performed. A given test says either that this open may not succeed, in which case the loop is exited with an error, or that this open is to succeed right now, in which case the loop is exited without an error. If all the tests fall through, the open goes to sleep and stays asleep until something relevant changes. When it wakes up, it goes right back up to the top of the loop, where it does all of the tests again.

Coding this loop was, in fact, my main reason for writing a new driver. Most drivers simply get this wrong. Typically, they use two loops, which test for different open conditions, both of which have to be true before the open may succeed. However, if you have two loops, there is either a sequence of events that causes the open to succeed when it shouldn't or a sequence that causes an open to deadlock, thus preventing the open from succeeding when it should.

About Ring Buffers

One problem facing driver developers is efficiently moving the data between the interrupt handlers and the rest of the driver. For small amounts of data, this isn't difficult; but the characters sent and received are a large amount of data that must be moved quickly. Functionally, you need a queue: characters placed in one end, where they sit until extracted from the other. One of the most time- and space-efficient ways to implement a queue is the "ring buffer," or circular queue.

A ring buffer is an array of elements with two pointers: "write" and "read." A character is added to the ring buffer by storing it at the write pointer, then advancing the write pointer. A character is removed from the ring buffer by loading it from the read pointer, then advancing that pointer. When the pointer advances past the end of the ring buffer, it is made to point to the start of the buffer.

There is a "gotcha" when writing ring-buffer code: When the ring buffer is empty, the read and write pointers are equal; the same is true when it is full. A full ring buffer must be distinguished from an empty one, so the ring buffer must not be allowed to become full.The solution I use involves having the read pointer trail one behind the actual read position. Instead of read and advance, I advance and read. As the write pointer is not allowed to advance past the read pointer, it can never actually reach the read position, so the buffer cannot become full.

Copyright © 1994, Dr. Dobb's Journal