Coding LiS Drivers
This document is concerned with the include files and compilation techniques for STREAMS drivers. It is not intended to be a tutorial on the subject of writing STREAMS drivers. Additional resources are available below for reference material.
Header Files
In your C language source file for a STREAMS driver, you should place the following line of code.
#include <sys/stream.h>
This line will include all of the additional header files and function prototypes needed to code a STREAMS driver.
If your STREAMS driver needs to decode the flush bits in M_FLUSH messages then also include the following.
#include <sys/stropts.h>
Compilation Options
When you compile your STREAMS driver, put the following compiler option on the gcc (cc) command line for each C language file that contains one or the other of the above include lines.
-I/usr/src/LiS/include -D__KERNEL__ -DLINUX
This directive assumes that you used standard installation procedures for LiS so that the name /usr/src/LiS is a symbolic link to the LiS installation directory. The -D's are necessary to give your driver the kernel's view of the header files and to get the Linux version in those cases where alternatives exist.
Driver Prefix
Choose a short prefix to put on the front of all your identifier names and routine names. For example, "xylo_". Thus, the main streamtab entry for your driver would be:
struct streamtab xylo_info = { &xylo_rinit, /* read queue */ &xylo_winit, /* write queue */ NULL, /* mux read queue */ NULL /* mux write queue */ };
The open routine would be called "xylo_open(....)" and so on.
The role of this prefix is to allow the LiS configuration process to build some tables that reference certain symbols within your driver. Just to take one example, the "prefixinfo" structure's name must be known to LiS so that it can build the queue structures that are passed to your driver at open time.
Driver Open Routine
It is important that you get the declaration of your driver open routine correct. There was a different prototype for the open routine in SVR 3 versus SVR 4. The Linux STREAMS package uses the SVR 4 style only. The prototype for your open routine should be as follows:
int xylo_open(queue_t *q, dev_t *dev, int oflag, int sflag, cred_t *cred_p);
These prototypes can be found in the DDI/DKI or consult the LiS include file include/sys/LiS/queue.h. Look for the definition of the structure qinit_t.
Driver Registration
Your driver will be automatically registered with the Linux kernel as a character mode special device driver. The LiS configuration process builds tables that allow LiS to perform this registration function on behalf of your driver. Thus, your STREAMS drivers should not contain any code to register itself as a Linux driver.
Information about writing STREAMS drivers and applications is available from other sites on the Internet. The following links may prove useful. Keep in mind that these links are to Unix documentation. Therefore, these documents cover many more kernel routines and services than appear in LiS.
Link |
Description |
|
This link goes to Amazon.com. Search for the string "unix streams". From there you can order a hard copy of the official "Unix System V Release 4: Programmer's Guide: Streams". This is the reference for LiS STREAMS. |
||
You will need to register (free) to view the documentation. This is official SVR4 documentation. It only covers user level, not driver level interfaces. Once you have registered, do a search on "STREAMS". There is also a DLPI specification available there. |
||
Documentation on Sun style STREAMS drivers. Very close to SVR4. Ignore information about multi-threaded drivers. The man pages for section 9 are especially helpful. |
||
Start by scrolling the left panel down to "Hardware and Driver Development". Man page lookups work well, also. Ignore information about multi-threaded drivers and execution context. |
||
Look for "SCO UnixWare Application Server Release 2" and then select man page section "3D". UW7 docs are easier to browse. |
||
Linux Journal #61, May 1999, LiS: Linux STREAMS by Fransisco Ballesteros, Denis Froschauer, David Grothe and Graham Wheeler. Not available online. Gives an overview of Linux STREAMS. |