13 Device Driver Configuration Files and File Fragments

Device driver configuration consists of the tasks necessary to incorporate device drivers into the kernel to make them available to system management and other utilities. There are two methods for configuring drivers into the kernel: static and dynamic. Digital recommends that you implement your driver products so that customers can statically or dynamically configure them into the kernel. Chapter 6 shows how to implement the /dev/none driver's configure interface and associated attributes table to cooperate with the cfgmgr framework so that a system manager can statically or dynamically configure it into the kernel. One of the tasks you must perform before configuring a device driver into the kernel is to create and include appropriate information in the driver configuration-related file fragments.

This chapter describes how some of the system management utilities use the files and file fragments you were introduced to in Chapter 12 and that are needed for or related to device driver configuration.

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 are not interested in learning about how the system management utilities deal with the driver-related file fragments, then skip to Chapter 14.

Specifically, the chapter discusses the following files and file fragments:

Target and GENERIC configuration files
/usr/sys/conf/.product.list and NAME.list files
files file fragment
sysconfigtab file fragment
BINARY.list file
name.kit file

13.1 Target and GENERIC Configuration Files

The /usr/sys/conf/NAME file (referred to as the target configuration file) is an ASCII text file that defines the components of the system. The target configuration file name, NAME, is usually the name of the system. By convention, the target configuration file name is capitalized. There can be more than one target configuration file defined in /usr/sys/conf, each with a capitalized name. As discussed in Chapter 12 and shown in Figure 12-3, EasyDriver Incorporated has one target configuration file called CONRAD. Customers, too, can have one or more target configuration files to represent different system configurations.

The Digital-supplied GENERIC configuration file is the configuration file for the all-encompassing generic kernel that is originally installed on the system. It contains all the possible software and hardware options that Digital supports. The GENERIC configuration file is used to build a kernel that represents all possible combinations of statically configured drivers that Digital supports. This kernel is booted during the operating system installation and is often referred to as the generic kernel. While running the generic kernel, the installation software determines which subset of all possible device drivers should be used to build a target kernel to match the hardware attached to the system being installed. The GENERIC kernel is also required for (tailored) kernels that customers generate.

13.2 The .product.list and NAME.list Files

The /usr/sys/conf/.product.list file stores information about device driver products that are installed on Digital UNIX systems. The NAME.list file is a copy of the .product.list file that is created when the doconfig program is run without the -c option. This is typically done in the subset control program. Device driver writers and kit developers do not supply either of these files; however, an understanding of the following topics related to these files can help during device driver kit development and testing:

Format of the NAME.list file
Relationship between NAME.list and /usr/sys/conf/.product.list

Note
If there are no products registered on your system, a /usr/sys/conf/.product.list file does not exist. In this case, a NAME.list file would not be created.

13.2.1 Format of the NAME.list File

In the device driver kits delivery process, the kreg utility sets up the .product.list and NAME.list files on the customer's system. Although third-party driver writers and kit developers do not supply these files, it is useful to understand the files' format. Figure 13-1 shows the format of such a file for EasyDriver Incorporated.

Figure 13-1: A NAME.list File for EasyDriver Incorporated

The figure shows that the NAME.list file has fields separated by colons (:), as follows:

Driver files path field
The driver files path field contains the path that points to the location of the files associated with the driver product, which in the figure is /usr/opt/ESA100. The value in the driver files path field must be unique.
Section 14.2.1.1 explains how to create a NAME.list file as part of the steps for statically configuring a single binary module to produce a /vmunix kernel. In this case, the only field you need is the driver files path field.
Subset ID field
The subset ID field contains the subset ID associated with the setld utility, which in the figure is EASYDRV200.
Date field
The date field contains the date when the product is ready for distribution. The date has the form yymmddhhmm, where yy represents the year, mm represents the month, hh represents the hour (24-hour time), and mm represents the minutes. For EasyDriver Incorporated, the date field translates to:
```
November 17, 1996 1:44 PM
```
Company name field
The company name field contains the company's name, which in the figure is abbreviated to EasyDriverInc.
Product name field
The product name field contains the name of the product, which in the figure is NONEdriver.
Product version field
The product version field contains the version number of the product, which in the figure is 1.0.
Note that the configuration software (namely, the config program) uses only the path field.

13.2.2 Relationship between NAME.list and .product.list Files

Figure 13-2 shows the relationship between the NAME.list and .product.list files during kit installation:

The system manager mounts the device driver kit and runs the setld utility.
The setld utility moves the contents of the kit to an appropriate destination directory, reads the device driver kit, and calls the subset control program (SCP) provided by the kit developer. The SCP contains path specifications for all of the files related to the driver product. For example, Figure 13-2 shows the path and one file associated with the /dev/none driver product.
The SCP calls the /sbin/kreg utility, which registers the statically configured product on the customer's system. This action makes the device driver product available to system management-related programs such as doconfig and config by creating an entry in the .product.list file.
As the figure shows, the SCP calls /sbin/kreg and supplies it with the driver path to where the files related to the /dev/none driver product are located. The /sbin/kreg utility registers the path along with other supporting information in the customer's .product.list file. The three dots following the driver path in the figure indicate that the supporting information is contained in other fields in the entry. The key piece of information for the driver writer and the kit developer is the location of the files associated with the driver product.

Figure 13-2: Comparison of .product.list File and NAME.list
The doconfig program, run by the system manager, reads the .product.list file and copies it to a file of the form NAME.list. (This occurs only if the system manager (or the subset control program) does not specify the -c option. If the system manager (or the subset control program) specifies the -c option, the doconfig program builds a kernel based on the contents of the file specified by the system manager. In this case, doconfig does not perform the copy operation.) 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.

The fields contained in the /usr/sys/conf/.product.list file are described in Section 13.2.1.

Customers can edit the NAME.list file to exclude a driver entry, thus removing the entry's associated functionality from the rebuilt (tailored) kernel. Otherwise, customers always get the driver products as they are specified in the /usr/sys/conf/.product.list file. Customers should never edit the /usr/sys/conf/.product.list file directly. Instead, customers make required changes by using the kreg utility or by editing the NAME.list file. Section 14.2.1.1 explains how to create a NAME.list file as part of the steps for statically configuring a single binary module into a /vmunix kernel.

13.3 The files File Fragment

A files file contains the following information about device drivers:

The location of the source code associated with the product drivers
Tags indicating when the product drivers are to be loaded into the kernel
Whether the source code or the binary form of the product drivers is supplied to the customer

This information is encapsulated into modules. A module is a collection of one or more objects linked together into a single entity. A module makes it possible to produce a single binary module (executable) that can be statically or dynamically configured into the kernel.

You can view the files file fragment as a ``mini'' files file. That is, it contains the exact same information as the files file. The files file fragment is the mechansm that third-party driver writers use to make the information about their device driver products available to customer's systems. Figure 13-3 shows the relationship between a files file fragment from EasyDriver Incorporated and a customer's files file. The files file fragment from EasyDriver Incorporated contains the modules for the /dev/none driver product. The customer's files file contains similar module entries for other device drivers. To have the doconfig program automatically generate the appropriate rules to build the drivers, the driver writer must specify the appropriate module information in the files file fragment.

Figure 13-3 shows that the config program (which is called from the doconfig program) run by the customer reads both files files and makes the information specified in them available to the system. The figure also shows that config does not append the information in the supplied files file fragment to the customer's files file, but rather creates a virtual files file of the entries contained in both files. It does not alter the supplied third-party files file fragment or the customer's files file.

This automated mechanism relieves the customer from having to make tedious and potentially error-prone changes to the files file. Driver writers must be particularly careful about choosing unique path and file names in this file.

Section 14.1.3 describes the syntaxes that you use to specify information in the files file fragment.

Figure 13-3: Comparison of files File Fragment and Customer's files File

13.4 The sysconfigtab File Fragment

The sysconfigtab file fragment contains device special file information, bus option data information, and physically contiguous memory usage information for statically and dynamically configured drivers. When the user installs a kernel kit, the sysconfigtab file fragment gets appended to the /etc/sysconfigtab database. Figure 13-4 shows the format associated with the fields in the sysconfigtab file fragment separated by colons (:). It also shows that the syntax for a sysconfigtab entry contains:

entry_name
Specifies the name of the device driver. The figure shows one sample driver entry called none.
Typically, each driver contains a separate sysconfigtab entry.
Comments
A number sign (#) at the beginning of a line indicates a comment. You can include comments at the beginning or the end of a driver sysconfigtab entry. The figure shows an example of a comment at the beginning of the entry for the /dev/none driver. Comments are not allowed within the body of the sysconfigtab entry.
Trailing blanks
Tabs are allowed at the beginning or end of lines and, as the figure shows, trailing blanks are allowed at the end of lines.
attribute_name and attribute_value
Specifies a valid sysconfigtab field. The figure shows that a valid sysconfigtab entry consists of a keyword that identifies the field, an equal sign (=) separator, and one or more values. The values can be strings (as in the figure) or valid keywords as described in Section 14.1.5.
Driver writers interested in learning about the other valid sysconfigtab keywords should see sysconfigtab in Reference Pages Section 4.
New lines
The figure also shows that a new line terminates an attribute name and value pair.

The following list describes restrictions associated with a sysconfigtab file fragment:

An individual sysconfigtab entry can be a maximum of 40960 bytes in length. The system ignores all bytes in excess of this limit.
An individual line (attribute) within a sysconfigtab entry cannot exceed 1548 bytes.
An individual sysconfigtab entry cannot consist of over 2048 lines (attributes).
At least one blank line is required between sysconfigtab entries.

Figure 13-4: Format of the sysconfigtab File Fragment

You can view the sysconfigtab file fragment as a ``mini'' sysconfigtab database, as shown in Figure 13-5. The figure shows the relationship between a sysconfigtab file fragment from EasyDriver Incorporated and a customer /etc/sysconfigtab database. The sysconfigtab file fragment from EasyDriver Incorporated contains device special file information: 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 reside. This file fragment can also contain bus option data information and physically contiguous memory usage information. The customer's /etc/sysconfigtab database contains not only these categories of information, but also additional ones that can represent other drivers. The driver writer at EasyDriver Incorporated specifies only those options related to the device driver product and needed by customers.

Furthermore, Figure 13-5 shows that the sysconfigdb utility appends the information contained in the sysconfigtab file fragment to the customer's /etc/sysconfigtab database.

Figure 13-5: Comparison of sysconfigtab File Fragment and sysconfigtab Database

This automated mechanism relieves the customer from having to make tedious and potentially error-prone changes to the /etc/sysconfigtab database.

Section 14.1.5 discusses the fields that driver writers use to populate the sysconfigtab file fragment.

13.5 The 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 14.1.4 explains how to create the BINARY.list file as part of the steps for producing the single binary module.

13.6 Single Binary Module and the Device Method File

A single binary module is the executable image of a device driver that can be statically or dynamically configured into the kernel. A single binary module has a file extension of .mod. To produce a single binary module, there is code you need to implement in the driver's configure interface. Section 6.6 describes how to write a configure interface so that your device driver can be statically or dynamically configured into the kernel. In addition, there are steps you follow when statically and dynamically configuring the driver (single binary module) into the kernel. Chapter 14 explains how to statically and dynamically configure drivers (single binary modules) into the kernel.

The device.mth utility is a tool that works with dynamically configured drivers. It creates and deletes the device special files associated with dynamically configured drivers. Contrast this with the kmknod utility, which creates and deletes device special files associated with statically configured drivers.

13.7 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. The following list provides examples of hardware needed during the initial installation and boot of the operating system:

Graphics controller
A graphics controller is the hardware interface between the computer and a graphics terminal.
Disk controller
A disk controller for the root file system is the hardware interface between the computer and a disk device. (Currently, disk devices are not supported as foreign devices.)
Network controller
A network controller (when booting from the network) is the hardware interface between the computer and a network device.

Before a system manager can make use of the peripheral devices associated with these controllers, the associated device drivers must be configured into the kernel. The problem is that during the initial installation and boot of the operating system there is no kernel and no device drivers available to handle potential kernel and user requests of these devices. (In other words, the GENERIC configuration file does not include these drivers.)

The name.kit file provides a way to configure device drivers into a kernel so that system managers can use devices that would otherwise not be available from the base Digital UNIX.

The name argument is usually based on the device name. For example, the NONE device's name.kit file would be called none.kit. The edgd device's name.kit file would be called edgd.kit. Because not all devices are needed prior to the operating system installation, it follows that not all drivers are needed at this time. Therefore, the name.kit file is optional. A name.kit file would not be supplied with the /dev/none and /dev/edgd driver products because they are not needed prior to the installation of the operating system.

The name.kit file would reside in the root directory or the driver's installation media. For example, if the /dev/none driver product was needed during the initial installation and boot of the operating system, it would reside in /usr/opt/ESA100. Figure 13-6 shows how the name.kit file works with the osfboot software during the installation of a peripheral device needed during the initial installation and boot of Digital UNIX.

The osfboot software is the Digital UNIX bootstrap program responsible for linking, reading, and booting a kernel. It is the osfboot software that prompts a user to specify a boot-link kernel on the console command line.

Figure 13-6: How osfboot Uses a name.kit File

As the figure shows, the driver kit contains a name.kit file called xx.kit. The xx.kit file contains the commands that instruct the osfboot software on how to build and configure a /vmunix kernel to include the single binary module xxdriver.mod. The figure shows that upon completion of this /vmunix kernel, the xxdriver.mod single binary module (the executable driver) is available to handle user and system requests of a specific hardware device during the initial installation and boot of the Digital UNIX operating system.