Linux STREAMS

Authors

Linux STREAMS, termed LiS, is an SVR4 compatible STREAMS executive which runs in the Linux Kernel as a loadable module. It is the product of a joint effort among the following authors.

Francisco J. Ballesteros nemo@gsyc.inf.uc3m.es

Denis Froschauer Denis.Froschauer@hol.fr

David Grothe dave@gcom.com

Graham Wheeler gram@cdsec.com

David Grothe is the only remaining active supporter of LiS, so please direct questions to him rather than to the others. Francisco Ballesteros still maintains an LiS mailing list. You can mail to the group by addressing email to linux-streams@gsyc.inf.uc3m.es. You can view all the LiS discussion traffic at the following web site [http://www.gsyc.inf.uc3m.es/~majordomo/linux-streams/].

Features and General Description

LiS adds UNIX SVR4 STREAMS capability to the Linux operating system. It follows the SVR4 STREAMS specification rather closely. There are a few esoteric ioctls not implemented, but these have to do with the SVR4 implementation of STREAMS based pipes.

The calling sequence for STREAMS driver open routines follows the SVR4 convention. All SVR4 provided STREAMS queue and message routines are implemented. There is an implementation of a UNIX compatible timeout routine and a cmn_err routine.

LiS adds the system calls getpmsg, putpmsg and poll to the Linux kernel. To open a STREAM file a user program performs a normal file open to a character device special file, conventionally located in the /dev directory. Normal read and write functions can be performed on STREAMS files. STREAMS files can also appear in select lists. Likewise, the STREAMS implementation of poll allows for non-STREAMS files to appear in a poll list.

LiS also implements the SVR4 clone driver.

STREAMS pushable modules are implemented in LiS. They can be pushed onto a STREAMS file using the I_PUSH ioctl.

STREAMS multiplexors are fully implemented in LiS. The I_LINK, I_PLINK, I_UNLINK and I_PUNLINK ioctls are all implemented.

Some simple STREAMS drivers are included in the distribution. A few of them are small drivers that are essential to the operation of LiS itself. Others are small drivers used to test LiS. One driver of particular note acts in a dual capacity as an interface driver under IP which then communicates downstream to any DLPI capable STREAMS driver. In other words, it allows the adapting of DLPI drivers as IP interface drivers.

LiS comes with a configuration utility program. This program interprets a file containing an ASCII description of each STREAMS driver that is to be linked into LiS. The configuration program arranges for Linux driver registrations to be performed on behalf of the STREAMS drivers. It also generates a program that can be run at boot time to make all of the device nodes on behalf of STREAMS drivers. The configuration program assists in the definition of clone devices. The STREAMS configuration program is run automatically as a part of building the LiS loadable module.

LiS also provides a utility program, "streams", which displays statistics on the STREAMS subsystem. This same program can be used to set bits in an LiS debug mask, a very useful feature for debugging STREAMS drivers.

At present, LiS does not manage interrupts for STREAMS drivers. We expect to put this feature in at some future time. It is part of our plan to ensure single threaded execution of STREAMS drivers, even in SMP kernels.

There is also no TLI interface at the present time, and no STREAMS interface to TTY drivers (no ldterm).

The current version of LiS will run on kernel versions 2.0.24 through 2.0.33.

LiS Debugging

The LiS streams utility program allows you to set bits in the LiS debug mask while the system is running. The debug bits mostly lead to causing LiS to print out information about the execution of STREAMS. A sampling of the debug features is as follows.

• Print a message at each STREAMS file open or close.
• Print information about each read or write involving a STREAMS file.
• Print information about each getpmsg or putpmsg.
• Print out information about each STREAMS ioctl.
• Print information about each I_LINK and I_UNLINK.
• Print information about poll system calls.
• Trace messages as they are passed from one STREAMS driver to the next.
• Implement careful checking of structures (highly recommended setting).
• Print information at each memory or message allocation or free.

In addition, the streams utility can cause LiS to print out an area by area summary of all allocated memory under its control. This is extremely useful for finding cases of memory that has been left allocated by a driver. In LiS all allocated memory is tagged with file name and line number of the caller of the memory allocator. This information is printed out when LiS prints out its memory summary.

Also, the LiS allocator places guard words at the end of each allocated area so that it can detect "off by one" writing off the end of allocated memory.

Installation

The LiS source code is placed into your kernel source code tree at the location /usr/src/linux/drivers/streams, where the "streams" directory is new. The menuconfig system of Linux is modified to add the STREAMS option to the configuration menus. A small placeholder patch is applied to the kernel source itself to reserve the system calls that LiS needs and to export some kernel routines needed by LiS.

LiS itself is compiled as a loadable module. It is run with an insmod command. The directory /usr/src/linux/drivers/streams/pkg is a location in which binary STREAMS drivers can be added to the LiS module. Because LiS itself is licensed under the GNU General Library Public License, this allows proprietary drivers to be linked with LiS and the whole thing loaded as a module into the kernel.

The directory /usr/src/linux/drivers/streams/LiS/util contains the utility programs that come with the package.

The directory /usr/src/linux/drivers/streams/LiS/include contains the STREAMS oriented include files. When developing either STREAMS drivers or STREAMS application code you should put a "-I" to this directory on your compiler command line. Once you have done that then the only include file that a driver will likely need is <sys/stream.h> and the only include files that an application will likely need are <sys/stropts.h> and <sys/poll.h>.

The directory /usr/src/linux/drivers/streams/LiS/head contains all of the C language code that implements the kernel resident portion of LiS. This directory contains a sub-directory named "user" in which you can compile a user level test version of LiS. This allows you to perform some driver testing in user space before trying your driver in the kernel.

The directory /usr/src/linux/drivers/streams/LiS/drivers/str contains some ancillary STREAMS drivers that come with LiS. Two of those drivers, clone and runq, are required for the correct operation of LiS. Others such as loop and minimux are there for STREAMS testing purposes. LiS includes a program in the util directory called strtst. This program exercises the various features of STREAMS will full debugging turned on and produces a log file of the results. It can be run against the fully installed LiS in the kernel or it can be run with LiS compiled for user mode execution.

Also in this same directory is the ip_strm_mod driver. This driver acts as two drivers. One is a standard Linux driver written to act as an interface driver below IP. The other is a STREAMS multiplexor, under which DLPI drivers may be I_LINKed. The driver maps back and forth between the two IP interfacing protocols. This allows DLPI MAC drivers to be ported from UNIX and be used to interface to Linux's TCP/IP.

To install LiS, download the zipped tar archive, unpack it into a directory somewhere (/usr/src/LiS is a suggestion) and follow the instructions in the README file. We have developed some installation scripts that make installing LiS fairly straightforward.

The runq driver is used to run the service procedures for STREAMS drivers. As a part of the installation process you will be asked to put a line of the form "cat /dev/runq" into one of your rc files. The runq driver never returns from its open routine. It sleeps there and wakes up whenever the STREAMS service procedures need to be run. It calls the routine in LiS which executes all of the scheduled service procedures. Thus, the accumulated CPU time for the cat runq process is the amount of time spent running service procedures.

Kernel Debugging

Gcom also provides a kernel patch, called gdbstub, which allows you to use two Linux machines in a debugging environment in such a way that you can use one machine to debug the kernel of the other.

You compile your experimental kernel on a development system (machine #1) and then copy it over to your test system (machine #2) for execution (run LILO). The two machines are connected by a serial line connected to their com ports. A kernel patch in machine #2 causes all kernel faults plus breakpoint instructions to funnel into a piece of code which uses the com port to communicate with machine #1. Meanwhile, machine #1 is running GNU's GDB on the kernel. It is placed into remote mode. The debugger on machine #1 "gets control" whenever the kernel on machine #2 faults or hits a breakpoint. You can display source code, structures, modify memory, single step, in short, you can perform all of the debugging functions that you can do on your user level programs -- but you are actually debugging the kernel.

To use this feature you must compile your test kernel with the options "-g -O2". The README that comes with the gdbstub patch describes how to do all of this.

All trademarks belong to their owners. Use on this World Wide Web site does not constitute a challenge to ownership.

©1998, Gcom, Inc.
Updated April 28, 1998.