12 Device Driver Kits Delivery Process

The device driver kits delivery process is the mechanism for developing, delivering, installing, and configuring device drivers on systems that run Digital UNIX. Customers use the setld utility to install the device driver product and then use a variety of system management utilities that automatically configure drivers into the kernel. This chapter provides an overview to the device driver kits delivery process, using as an example a fictitious device driver development company called EasyDriver Incorporated.

Figure 12-1 shows the tasks and groups of people involved in the device driver kits delivery process. The figure shows that the device driver kits delivery process involves at least three different audiences: the device driver writer, the kit developer, and the system manager (who, from the device driver writer's point of view, is the customer). In addition to showing the groups of people, Figure 12-1 also shows the tasks each group does to develop, deliver, install, and configure the device driver product:

Device driver development phase
In this phase, the device driver writer writes the driver, creates a driver development environment, produces the single binary module, statically and dynamically configures the single binary module (the driver) into the kernel, and tests the driver. After testing the driver, the device driver writer provides the driver product-related files and file fragments to the kit developer.
Device driver kit development phase
In this phase, the kit developer takes the driver product-related files and file fragments and prepares the device driver kit or kits and creates installation instructions, if needed. The kit developer also tests the installation procedure and ensures the driver statically and dynamically configures into the kernel and works with the appropriate utilities.
Device driver installation phase
In this phase, the customer loads the device driver kit, runs setld, and follows any installation instructions that the vendor supplies.

Figure 12-1: People and Tasks Associated With the Device Driver Kits Delivery Process

The following sections give an overview of these tasks. Because these tasks encompass more than one group of people, the following discussions explicitly identify the group typically associated with the specific tasks.

Chapter 13 describes how some of the system management utilities use the driver configuration-related files and file fragments. Chapter 14 describes the syntax associated with each of the file fragments as part of the steps to statically or dynamically configure device drivers (single binary modules) into the kernel. If you want to follow the steps for statically or dynamically configuring drivers (single binary modules) into the kernel without reading the background information provided in Chapter 12 and Chapter 13, then skip to Chapter 14.

Note
Device driver examples are stored in an optional software subset that the system manager must select when installing Digital UNIX. If the /usr/examples/devdriver directory does not appear on your system, check with your system manager. The system manager can use the setld utility to install this optional subset.
The device driver configuration information described in Part 4 of this book reflects the tools and methodology associated with Digital UNIX Version 4.0. Because the tools and methodology used to configure device drivers into the kernel can change from release to release, see the latest product documentation for the most current information related to device driver configuration.

12.1 Device Driver Development Phase

Figure 12-2 shows the tasks associated with the device driver development phase as practiced at EasyDriver Incorporated. You can choose to follow this model or devise an alternate one that matches your device driver development environment. The tasks that the driver writer at EasyDriver Incorporated performs during the device driver development phase are:

Write the device driver
Create the driver development environment
Create driver product-related files and file fragments
Produce the single binary module
Perform static configuration of the driver (single binary module)
Perform dynamic configuration of the driver (single binary module)
Test the driver
Provide driver product-related files and file fragments to the kit developer

The sections following Figure 12-2 provide an overview of the tasks associated with the device driver development phase.

Figure 12-2: Tasks for Device Driver Development Phase

12.1.1 Writing the Device Driver

The driver writer at EasyDriver Incorporated uses the techniques described in previous chapters of this book to write device drivers. The driver writer uses the guidelines presented in Section 2.1.2.1 for naming the device driver source file. For the /dev/none device driver product, the source file is called none.c. For the /dev/edgd device driver product, the source file is called edgd.c.

12.1.2 Creating the Device Driver Development Environment

The driver writer works with the kit developer to create a development environment. The driver writer for EasyDriver Incorporated works with the kit developer to create the driver development environment shown in Figure 12-3. This development environment consists of the directories and files associated with the driver product. (The .mod file will not appear in the directories until you actually produce it from the .c file.)

A directory structure, such as the one shown in Figure 12-3, helps the kit developer to prepare the kit and the driver writer to test the driver under conditions similar to those experienced by customers. Figure 12-3 contrasts the directories and files related to the system with the directories and files related to the driver kit development environment.

Figure 12-3: Driver Development Environment for EasyDriver Incorporated

The directories and files related to EasyDriver Incorporated's system are as follows.

/usr/sys/conf directory
This directory contains files that define the kernel configuration for the generic (all-encompassing) and target machine kernels. In the /usr/sys/conf directory for EasyDriver Incorporated, the generic kernel is called GENERIC and the target machine kernel is called CONRAD. This directory also contains the /usr/sys/conf/.product.list file and, optionally, a GENERIC.list or CONRAD.list file. Finally, it contains a BINARY.list file. Section 13.1 describes in more detail the GENERIC and target configuration files. Section 13.2 describes in more detail the /usr/sys/conf/.product.list file.

The directories and files related to EasyDriver Incorporated's driver development environment (identified in darker type in the figure) are as follows:

A /usr/opt directory
This directory contains subdirectories that represent each of the driver products that EasyDriver Incorporated developed. Figure 12-3 shows two such directories: ESA100 and ESB100.
Driver writers can follow the naming conventions described in the Guide to Preparing Product Kits book. The driver writer at EasyDriver Incorporated adheres to these conventions by specifying directory names based on 3-character product and version codes. Thus, the driver writer at EasyDriver Incorporated uses the product codes ESA and ESB to represent the directories that contain the files associated with the /dev/none and /dev/edgd drivers. The version code 100 indicates that this is Version 1.0 of the driver products.
A /usr/opt/ESA100 directory
This directory contains the files related to the /dev/none device driver product that EasyDriver Incorporated ships to its customers. These files include the following product-related file fragments: files and sysconfigtab. Section 13.3 describes in more detail the files file fragment. Section 13.4 describes in more detail the sysconfigtab file fragment. This directory also contains the driver header files, which have .h extensions; the driver source files, which have .c extensions; and the single binary modules, which have .mod extensions.
A /usr/opt/ESB100 directory
This directory contains the files related to the /dev/edgd device driver product that EasyDriver Incorporated ships to its customers. These files include the following product-related file fragments: files and sysconfigtab. Section 13.3 describes in more detail the files file fragment. Section 13.4 describes in more detail the sysconfigtab file fragment. This directory also contains the driver header files, which have .h extensions; the driver source files, which have .c extensions; and the single binary modules, which have .mod extensions.
A /subsys directory
This directory contains the single binary modules linked to the method files, which have .mth extensions. This directory typically contains the single binary modules for those subsystems that need to be configured before single user time. Section 13.6 describes in more detail the method files.
A /var/subsys directory
This directory contains files with .mod (single binary modules) and .mth (device method) extensions. You can use this directory or the /subsys directory to contain the files with .mod and .mth extensions. This directory typically contains the single binary modules for those subsystems that can be configured after single user time. Section 13.6 describes in more detail single binary modules and device method files.
A /sys/BINARY directory
This directory contains the single binary modules, which have .mod extensions. Section 13.6 describes in more detail the single binary module.

12.1.3 Creating Driver Product-Related Files and File Fragments

The driver writer creates the .c and .h files that contain the source code for the driver product. Section 2.1.2.1 provides guidelines for naming the driver product's .c and .h files. The driver writer at EasyDriver Incorporated adheres to the guidelines presented in Section 2.1.2.1 by naming the .c and .h files based on the product name. Thus, the source code for the /dev/none driver product is in the none.c and nonereg.h files. The source code for the /dev/edgd driver product is in the edgd.c and edgdreg.h files.

Prior to producing the single binary module, the driver writer at EasyDriver Incorporated supplies information in the following files:

files file fragment
The files file fragment is associated with drivers delivered in binary form. Drivers delivered in binary form can be statically or dynamically configured into the kernel. You specify a valid syntax for when the driver is to be loaded into the kernel, the location of the driver source code, and whether the driver sources are supplied. Section 13.3 describes how the config program uses the files file fragment and Section 14.1.3 describes the syntax for the files file fragment.
sysconfigtab file fragment
The sysconfigtab file fragment is associated with device drivers written to conform to the single binary module model. A driver written in this way can be statically or dynamically configured into the kernel. You use valid attributes for the driver's major number requirements, the names and minor numbers of the device special files, and the permissions and directory name where the device special files are created. Section 13.4 describes how the sysconfigdb utility uses a driver's sysconfigtab file fragment and Section 14.1.5 describes the attributes for the sysconfigtab file fragment.
NAME.list file
The NAME.list file is associated with drivers that are statically configured into the kernel. This file contains such information as where the files for the driver product are located. This file is not supplied on the device driver kit. However, it is useful for a driver writer to understand the purpose of this file because you will edit or create such a file as one of the steps described in Section 14.2.1.1 and Section 14.2.2.1. Section 13.2 describes the NAME.list file.
The NAME variable usually specifies the name of the target configuration file. For example, TIGRIS.list would be the name for the file that contains information about statically configured device drivers for the customer system described by the target configuration file called TIGRIS.
BINARY.list file
The BINARY.list file contains such information as where the files for the driver product are located. The purpose of the file is to identify the build rules associated with third-party device drivers built into the BINARY Makefile when the driver writer invokes the sourceconfig utility. This file is not supplied on the device driver kit. Section 13.5 describes the BINARY.list file. Section 14.1.6 explains how to run the sourceconfig program.

The single binary modules are the actual executables associated with the device driver. The syntax you specify in the files file fragment determines whether you want the driver to be statically or dynamically configured into the kernel.

To produce the method file (files with .mth extensions) for the driver product, the driver writer at EasyDriver Incorporated links the driver product to the device.mth file.

Another file that a driver writer might have to supply is the name.kit file. The name.kit file contains the information that certain hardware needs during the initial installation and boot of Digital UNIX. This hardware is referred to as a foreign device. Section 13.7 provides more information on the name.kit file.

12.1.4 Producing the Single Binary Module

After creating the appropriate files and file fragments, the driver writer at EasyDriver Incorporated produces the single binary module. Section 14.1 lists the steps for producting the single binary module.

12.1.5 Performing Static Configuration of the Driver

After producing the single binary module, the driver writer at EasyDriver Incorporated statically configures it (the single binary module) into the kernel. Section 14.2.1 lists the steps for statically configuring a driver (single binary module) in a /vmunix kernel. Section 14.2.2 lists the steps for statically configuring a driver (single binary module) in a boot-link kernel.

12.1.6 Performing Dynamic Configuration of the Driver

After producing the single binary module, the driver writer at EasyDriver Incorporated dynamically configures it (the single binary module) into the kernel. Section 14.3 lists the steps for dynamically configuring a driver (single binary module).

12.1.7 Testing the Device Driver Product

After statically and dynamically configuring the /dev/none device driver into the kernel, the driver writer at EasyDriver Incorporated tests the driver by using utilities that run on Digital UNIX. If the /dev/none driver does not work with these utilities, then the driver writer at EasyDriver Incorporated rewrites the driver and goes through the steps for producing the single binary module and statically and dynamically configuring the driver into the kernel. This sequence is repeated until the driver works with the appropriate utilities.

12.1.8 Providing Driver Product-Related Files and File Fragments to the Kit Developer

The driver writer provides the files and file fragments discussed in Section 12.1.3 and listed in Table 12-1 to the kit developer. These files and file fragments become the contents of the device driver kit and contain information necessary for system managers (customers) to statically or dynamically configure the driver product into their kernels. Table 12-1 summarizes the files and file fragments the driver writer needs to provide to the kit developer. The table has the following columns:

File
Contains the name of the file or file fragment.
Statically configured drivers (source)
A ``Yes'' appears in this column if the file or file fragment should be supplied with statically configured drivers supplied as source. Otherwise, a ``No'' appears.
Statically configured drivers (binary)
A ``Yes'' appears in this column if the file or file fragment should be supplied with statically configured drivers supplied as binary. Otherwise, a ``No'' appears.
Dynamically configured drivers (binary)
A ``Yes'' appears in this column if the file or file fragment should be supplied with dynamically configured drivers supplied as binary. Otherwise, a ``No'' appears.

Note
The device driver kit delivery process does not currently support shipping drivers as source and dynamically configuring them at the customer site. Therefore, the table omits a column for dynamically configured drivers (source).
The name.kit file is needed only if the driver must be available during the initial installation and boot of Digital UNIX. In other words, only device drivers that control foreign devices need this file. A foreign device is hardware used during the initial installation and boot of Digital UNIX.
A subset control program (SCP) is part of the device driver kit. However, the kit developer supplies the SCP. See the Guide to Preparing Product Kits for information on how to write an SCP.
Although name_data.c files are still supported, Digital recommends that you not use them in this and future releases.

Table 12-1: Contents of Device Driver Kit

File	Statically Configured Drivers (Source)	Statically Configured Drivers (Binary)	Dynamically Configured Drivers (Binary)
`files` file fragment	Yes	Yes	No
`sysconfigtab` file fragment	Yes	Yes	Yes
Driver headers (files with `.h` extensions)	Yes	No*	No
Driver sources (files with `.c` extensions)	Yes	No	No
Single binary modules (files with `.mod` extensions)	Yes	Yes	Yes
Device method (files with `.mth` extensions)	No	No	Yes
`name.kit` +	No	Yes	No
Subset control program	Yes	Yes	Yes
* But Yes if needed by data.c
+ Needed only by drivers that control foreign devices

12.2 Device Driver Kit Development Phase

Figure 12-4 shows the tasks associated with the device driver kit development phase as practiced at EasyDriver Incorporated. As the figure shows, the kit developer at EasyDriver Incorporated performs the following tasks during the device driver kit development phase:

Writes the subset control program (SCP)
Prepares the device driver kit

You can choose to follow this model or devise an alternate one that matches your device driver kit development environment. The sections following Figure 12-4 provide an overview of the tasks associated with the device driver kit development phase.

Figure 12-4: Tasks for Device Driver Kit Development Phase

12.2.1 Writing the SCP

As part of the kit development phase, the kit developer at EasyDriver Incorporated writes a subset control program (SCP) similar to the example provided in Guide to Preparing Product Kits. Your kit developers can use the example in Guide to Preparing Product Kits as the basis for writing their own SCPs.

12.2.2 Preparing the Device Driver Kit

The kit developer prepares the distribution medium, which in Figure 12-1 is a CD-ROM. The setld utility installs and manages Digital UNIX kernel products (including device drivers) kits and layered product kits. See the Guide to Preparing Product Kits book for a discussion of the media supported by Digital's kitting architecture.

The distribution medium, referred to as the device driver kit, consists of a hierarchical group of the files and directories provided by the device driver writer. It is the responsibility of the driver writer to work with the kit developer to determine how the files and directories are grouped within the hierarchy. The driver writer for EasyDriver Incorporated works with the kit developer to create the directory structure shown in Figure 12-3. In addition, the driver writer for EasyDriver Incorporated provides to the kit developer the files and file fragments listed in Table 12-1, which become the contents of the device driver kit.

The kit developer performs the appropriate tasks for preparing the device driver kit to be installed with the setld utility. The kit developer should refer to the Guide to Preparing Product Kits, which contains information about preparing software distribution kits that are compatible with the setld utility.

The Guide to Preparing Product Kits also provides an example SCP written by EasyDriver Incorporated.

If needed, the kit developer should also supply any installation instructions to accompany the device driver kit.

12.3 Device Driver Installation Phase

Digital UNIX provides tools that customers (and the system manager at EasyDriver Incorporated) use to automate the installation of device drivers. The automated mechanism:

Installs the device driver
Statically or dynamically configures device drivers into a kernel
Includes in the driver (at configuration time) site-specific tasks that are not currently handled by the config program

Figure 12-5 shows the tasks associated with the device driver kit installation phase as practiced at EasyDriver Incorporated. EasyDriver Incorporated expects its customers to follow these same steps. However, it is important to test the installation procedure prior to shipping the product to customers. You can choose to follow this model or devise an alternate one that matches your device driver kit installation environment. As the figure shows, the system manager at EasyDriver Incorporated performs the following tasks to install the kits for the /dev/none and /dev/edgd device driver products:

Loads the device driver kit onto a system
Runs the setld utility
Chooses from the prompt that the SCP displays to statically or dynamically configure the driver into the kernel

See the Guide to Preparing Product Kits for information related to installing device drivers that reside on a device driver kit.

Figure 12-5: Tasks for Device Driver Kit Installation Phase

12.4 System Management Tools

Table 12-2 summarizes the system management tools related to device driver configuration. See Reference Pages Section 8 and 1m for additional information on these system management tools.

Table 12-2: Summary of System Management Tools

Tool	Description
`doconfig`	Creates a new or modifies an existing target configuration file, copies `.product.list` to `NAME.list`, creates the device special file information for statically configured drivers, and builds a new Digital UNIX kernel. (The `doconfig` program calls `config`, which actually performs many of the tasks mentioned.)
`cfgmgr`	Works with `kloadsrv`, the kernel load server, to manage device drivers that are dynamically configured into the kernel.
`device.mth`	Works with driver products to produce the method file (files with `.mth` extensions).
`kmknod`	Uses the information from the driver's `sysconfigtab` file fragment and the driver's attribute table to dynamically create device special files at boot time for statically configured drivers.
`kreg`	Maintains the `/sys/conf/.product.list` system file, which registers device driver products that are statically configured into the kernel.
`sysconfig`	Configures a driver or handles a dynamically configured device driver. The `sysconfig` utility provides a user interface to the `cfgmgr` framework.
`osfboot`	Boots a Digital UNIX kernel. It contains support for boot link kernels that the `doconfig -b` command generates. The tool also supports dynamic booting and linking a kernel that contains foreign devices.
`sysconfigdb`	Maintains the `sysconfigtab` database. The driver entries in the `sysconfigtab` file fragment are appended to this database when the user installs a kernel kit.