Include Files
Every file in the operating system source code includes header files con-taining declarations of global data structures. The source code for device drivers need not be contained in a single file, and programmers should subdi-vide the driver among several files if it is large. Even if the driver is contained in a single file, programmers should follow convention and declare the driver data structures in new driver-specific header (" .h ,,) files. The definition of the data structures (the place in the source code where the compiler allocates memory storage) should be of the form extern, in a ".c" file, usually the driver source file. The only data structures that should be defined outside the driver are those that are configuration-dependent; that is, if the driver needs to allocate storage for each subdevice, a method is needed to allocate based on the number configured. For UNIX System V /386, the file Space.c is used to allocate configuration-dependent data for use by the device driver.
For instance, if a system is configured for 4 trace devices, the file Space.c will include a line
and the include file for the trace driver will contain the declaration of the trace structure. The configuration process that ID executes will set TLUNITS equal to 4 based on the unit parameter (field 3) of the System file. The driver source code file should "include" the new header files. Driver file names conventionally contain the device name as part of their names.
As an example, consider a driver for a new networking device called nnet.
Assume the driver consists of two ".c" files, nnet.c and nnetprot.c, and one header file, nnet.h. The names suggest that the files are associated with the new nnet device and that the nnetprot.c file contains a protocol for the device. The header file may contain a declaration such as
3·16 ISDG
struct nnet { char char
int lIDJlOrt;
int lID_chan;
Struct lID_queue } ;
and the ".c" files should contain the line
#include "sys/nnet.h"
General System Data Structures
Driver programmers must not change standard system header files, such as the proc file, the user file, or the inode file. Since the drivers are a separate part of the system, it is unacceptable to introduce new data structures and new "hooks" into standard system data structures to accommodate a private driver. In addition, changing system data structures could cause user-level programs to work incorrectly if they rely on the system data structure. For example, changes to the process table usually require recompilation of the ps command. Driver programmers should likewise refrain from tampering with kernel source files.
Usually driver source code must contain some standard "include" files to allow the driver access to system utilities and data structures commonly used to return information to the kernel. The list below defines a few of the more commonly used include files:
1. /usr/include/sys/types.h - basic system data types
2. /usr/include/sys/param.h - fundamental system parameters 3. /usr/include/sys/dir.h - directory structure definition 4. /usr/include/sys/user.h - the user structure definition
The driver must include dir.h and user.h if the error field u.u_error is set in the driver or if the fields u.u_base or u.u_count are used (see the section "Read and Write"). The error field gives error
DEVICE DRIVERS 3·17
information to the kernel, and the information later returns to the user program. The introduction to Section 2 of the Programmer's Reference Manual describes the values the field may take. If the driver includes user.h, it must first include dir.h because of interdependencies between the two header files.
5. /usr/inc1ude/sys/signal.h -definition of system signals
If the driver sends signals to user processes, it must include this file.
6. /usr/inc1ude/sys/conf.h -definition of device switch tables This file is needed if the driver uses line disciplines (see the section
"Use of line Disciplines").
7. /usr/inc1ude/sys/file.h -definition of file structure
This file is needed if the driver uses control flags such as "no delay"
(FNDELAY).
8. /usr/inc1ude/sys/buf.h -definition of the buf (system buffer) struc-ture
This file is needed if the driver uses the system buffer pool (see the section "Buffer Pool").
9. /usr/inc1ude/sys/tty.h - definition of the clist structure
This file is needed if the driver uses clists (see the section "Clists").
Driver-Specific Data Structures
Naming Conventions
The names of driver data structures and variables should have the driver name in the prefix to ease program readability and debugging and to avoid conflict with other variables in the system with the same name. For example, in Appendix C, the trace driver contains the variable tr_cnt and the data structure tr_data. Both names are private to the trace driver, and the prefix
"tr_" identifies them as belonging to the trace driver.
3-18 ISDG
Unit Numbers
As mentioned above, drivers frequently "drive" several hardware units, as a terminal driver may "drive" many terminals. Each terminal has a unit number corresponding to the minor number of the device file. Drivers typi-cally contain a data structure that contains a flag field to record the device status, such as open, sleeping waiting for data to drain, etc. Except for the inclusion of a flag field, the contents of the data structure are
device-dependent, so no recommendation can be given here. However, there should be one entry per unit, defined in the driver file and declared in the header file.
A sample declaration of the data structure for the fake device nnet was defined above. Each nnet device should have one of these data structures.