14 Building a Device Driver

Chapter 12 presents an overview of the device driver kits delivery process. The overview includes summary descriptions of the tasks performed during the device driver development phase, the device driver kit development phase, and the device driver installation phase. This chapter discusses in more detail how to build a device driver so that you can test it with the appropriate utilities prior to creating the device driver kit. Building a device driver involves the following tasks that driver writers perform during the device driver development phase:

Produce the single binary module
Statically configure a single binary module (the driver product)
Dynamically configure a single binary module (the driver product)

The device driver writers at EasyDriver Incorporated need to statically and dynamically configure their driver products (single binary modules) into the kernel in order to test them with the appropriate Digital UNIX utilities.

The following sections describe the steps associated with each of these tasks.

Note
The steps described in the following sections assume that you are superuser and that you are running the /genvmunix kernel.

14.1 Producing the Single Binary Module

Before you can statically or dynamically configure a device driver into the kernel, you must produce the single binary module. 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 the single binary module associated with a device driver product, you perform the following steps:

Step 1: Create a directory to contain driver product files
Step 2: Copy driver product files
Step 3: Create a files file fragment
Step 4: Create a BINARY.list file
Step 5: Create a sysconfigtab file fragment
Step 6: Run the sourceconfig program
Step 7: Run the make program
Step 8: Create a kernel configuration development area
Step 9: Run the sysconfigdb utility

The following sections discuss each of these steps, using as an example the driver build environment practiced at EasyDriver Incorporated.

14.1.1 Step 1: Create a Directory to Contain Driver Product Files

Use the mkdir command to create a directory to contain the driver product files:

# mkdir /usr/sys/io/ESA100 [1]

Shows that the driver writer at EasyDriver Incorporated creates the directory called /usr/sys/io/ESA100 to contain the files related to the /dev/none driver product. Note that the driver writer at EasyDriver Incorporated performs the work at the superuser prompt.
When you create your directory, replace ESA100 with a product directory that reflects a name specific to your company. [Return to example]

14.1.2 Step 2: Copy Driver Product Files

Use the cp command to copy the driver product files to the directory you created in Section 14.1.1 (Step 1):

# cd /usr/sys/io/ESA100 [1]

# cp /usr/sys/mydevelopment/none.c . [2]

# cp /usr/sys/mydevelopment/nonereg.h . [3]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/io/ESA100 directory.
You should change to the directory where you will copy the files for your driver product. [Return to example]
Shows that the driver writer at EasyDriver Incorporated copies the none.c file (the source file for the /dev/none driver product) to the /usr/sys/io/ESA100 directory. The /usr/sys/mydevelopment directory is where the driver writer initially created the none.c file.
You should copy the source file associated with your driver product to the directory you specified in Section 14.1.1 (Step 1).
You should have implemented the device driver's configure interface to follow the single binary module model (that is, your driver handles static and dynamic configuration). Chapter 6 describes how to implement a configure interface that follows the single binary module model. [Return to example]
Shows that the driver writer at EasyDriver Incorporated copies the nonereg.h file (the device register header file for the /dev/none driver product) to the /usr/sys/io/ESA100 directory. The /usr/sys/mydevelopment directory is where the driver writer initially created the nonereg.h file.
You should copy the device register header file (and any other header or source files) associated with your driver product to the directory you specified in Section 14.1.1 (Step 1). [Return to example]

14.1.3 Step 3: Create a files File Fragment

Use an editor such as vi to create a files file fragment:

# pwd [1]
/usr/sys/io/ESA100

# vi files [2]

Shows that the driver writer at EasyDriver Incorporated uses the pwd command to make sure the working directory is the one created in Section 14.1.1 (Step 1). The pwd command displays /usr/sys/io/ESA100, the directory created in Step 1.
You should also check that you are in the directory that you created in Section 14.1.1 (Step 1). [Return to example]
Shows that the driver writer at EasyDriver Incorporated uses the vi editor to create the files file fragment.
You can use vi or another editor to create your files file fragment. [Return to example]

The following example shows the contents of the files file fragment that the driver writer at EasyDriver Incorporated creates:

# This is the files file fragment for the /dev/none driver
# used to produce the single binary module.
#
MODULE/STATIC/none       standard Binary [1]

io/ESA100/none.c         module   none [2]

Shows the files file fragment syntax typically specified to produce a single binary module.
- MODULE
  The keyword that identifies a module. A module is a collection of one or more objects. In the case of device drivers, these objects are the source files (with .c extensions) that make up the driver.
  These objects are linked together to produce a single binary module. The module mechanism achieves the goal of producing a single binary module that represents the executable for device drivers that can be statically or dynamically configured into the kernel.
- STATIC
  The keyword that indicates this module is to be statically configured into the kernel. A module with this keyword is a group-linked object. A group-linked object has a configure interface and a filled-in cfg_subsys_attr_t structure.
  For example, the /dev/none driver product's configure interface is called none_configure and its filled-in cfg_subsys_attr_t structure is called none_attributes. Section 6.3 shows how to set up the cfg_subsys_attr_t structure for the /dev/none driver.
- none
  The name of the module, which in this case is the driver name. The driver writer at EasyDriver Incorporated specifies the name none for the /dev/none driver product. Replace the name none with the name of your device driver product.
  This name is a string that matches the string you specified for the entry_name item in the /etc/sysconfigtab database. Typically, third-party driver writers specify the driver name (followed by a colon) in the sysconfigtab file fragment, which gets appended to the /etc/sysconfigtab database during the driver product installation.
- standard
  The standard keyword indicates that the module will be included in every kernel. Note that the sourceconfig program ignores the standard keyword.
- Binary
  The Binary keyword causes the sourceconfig program to generate the build rules in the BINARY Makefile. When this Makefile is run to build the driver module, the single binary module (a file with a .mod extension) is placed in the /usr/sys/BINARY directory. A soft link is created in the directory that contains the driver product files (for EasyDriver Incorporated, the /usr/sys/io/ESA100 directory) that points to the .mod file (for EasyDriver Incorporated, the none.mod file) that resides in the /usr/sys/BINARY directory.
[Return to example]
Gives the path and source file name or names that make up the driver product. The driver writer at EasyDriver Incorporated specifies io/ESA100/none.c as the path and source file name. The driver writer at EasyDriver Incorporated also specifies the MODULE keyword followed by the token that represents the driver name, none.
Replace the path and source file name with the path and source file name associated with your driver product. Also replace the token following the module keyword with the token that represents the name of your driver product. [Return to example]

14.1.4 Step 4: Create a BINARY.list File

Use an editor such as vi to create a BINARY.list file:

# cd /usr/sys/conf [1]
# vi BINARY.list [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/conf directory.
You should also change to the /usr/sys/conf directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated uses the vi editor to create the BINARY.list file.
You can use vi or another editor to create your BINARY.list file. [Return to example]

The following example shows the contents of the BINARY.list file that the driver writer at EasyDriver Incorporated creates:

/usr/sys/io/ESA100: [1]

Shows the typical contents of a BINARY.list file. The contents is the directory path where you placed the driver product-related files. You created this directory in Section 14.1.1 (Step 1). For EasyDriver Incorporated, this directory is:
/usr/sys/io/ESA100:
Replace the path and source file name with the path and source file name associated with your driver product. You must follow the path and source file name with a colon (:), as shown in the example. [Return to example]

14.1.5 Step 5: Create a sysconfigtab File Fragment

Use an editor such as vi to create a sysconfigtab file fragment:

# cd /usr/sys/io/ESA100 [1]

# vi sysconfigtab [2]

Shows that the driver writer at EasyDriver Incorporated changes to the directory created in Section 14.1.1 (Step 1).
You should also change to the directory that you created in Section 14.1.1 (Step 1). [Return to example]
Shows that the driver writer at EasyDriver Incorporated uses the vi editor to create the sysconfigtab file fragment.
You can use vi or another editor to create your sysconfigtab file fragment. [Return to example]

The following example shows the possible contents of the sysconfigtab file fragment that the driver writer at EasyDriver Incorporated creates:

none:
  Module_Config_Name = none [1]
  Device_Dir = /dev [2]
  Device_Char_Major = ANY [3]
  Device_Char_Minor = 0 [4]
  Device_Char_Files = none [5]
  Device_User = root [6]
  Device_Group = 0 [7]
  Device_Mode = 666 [8]
  Device_Major_Req = Same [9]
  TC_Option = Modname - 'NONE    ', Driver_Name - none, Type - C,
              Adpt_Config - N [10]

Shows that the driver writer at EasyDriver Incorporated assigns the driver product name none to the Module_Config_Name field.
This name is a string that matches the string you specified for the entry_name item in the /etc/sysconfigtab database. Typically, third-party driver writers specify the driver name (followed by a colon) in the sysconfigtab file fragment, which gets appended to the /etc/sysconfigtab database during the driver product installation. See Figure 13-4 for a description of the entry_name item.
You should specify the Module_Config_Name field with the name of your driver product. [Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the directory /dev to the Device_Dir field. This directory is where the device special files for the /dev/none driver will be located.
You should specify the Device_Dir field with the /dev specification for your driver product or replace it with some other directory specification. [Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the value ANY to the Device_Char_Major field. This field indicates that the device special files associated with the driver product will be created and will be assigned a major number.
The device special files for the driver product have an associated major number. You obtained this major number by calling the devsw_add interface. Section 6.6.5.2 discusses how to reserve a major number by calling the devsw_add interface. Use the value ANY to indicate that the device special files will be created and that the associated major number was reserved when the driver's configure interface calls the devsw_add interface. [Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the value zero (0) to the Device_Char_Minor field. This field identifies the minor number for the character device controlled by the /dev/none driver. Use a single value as the minor number for the character device controlled by your driver product. Or, specify the minor number as follows:
- One device minor number, for example:
  Device_Char_Minor = 1
  To specify a single device minor number, simply specify the number. The device minor number must be a positive integer that cannot exceed 99999. A maximum of 512 device special files can be created for a device major number, unless a driver is both a block and character device. In this case, the maximum is 1024 device special files (512 for the block and 512 for the character drivers).
- More than one device minor number, for example:
  Device_Char_Minor = 0,1,2,3
  To specify more than one device minor number, specify the numbers separated by commas. Each device minor number must be greater than the one previously specified.
- A range of device minor numbers, for example:
  Device_Char_Minor = [0-10]
  To specify a range of device minor numbers, enclose the range within brackets ([]) and separate the beginning and ending values with a dash (-). The following rules apply to numbers specified in a range:
  - The ending number must be greater than the beginning number, as in the example. Thus, [10-0] is an invalid range specification.
  - The numbers specified in the range must be greater than the value zero (0). Thus, [-1-10] is also an invalid range specification because the first number is less than the value zero (0).
  - The largest allowable number in the range is 99999.
  - A maximum of 512 device special files can be created for any device major number. Thus, [0-511] and [1000-1500] are valid range specifications while [0-600] is invalid.
- More than one range of device minor numbers, for example:
  Device_Char_Minor = [0-10],[21-30]
  To specify more than one range of device minor numbers, enclose the first range within brackets ([]) and separate the range with a dash (-). Follow the first range with a comma (,). Specify the second range in the same manner as the first and omit the comma (unless there are additional ranges).
  The values you specify for block devices are the same except that you use the Device_Block_Minor field instead of Device_Char_Minor.
[Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the value none to the Device_Char_Files field. This field identifies the device special file name associated with the minor number for the character device controlled by the /dev/none driver. Use a single value as the device special file name associated with the device minor number for the character device controlled by your driver product; or, specify the device special file name as follows:
- One device special file name, for example:
  Device_Char_Files = rrz1
  To specify a single file name, simply specify the name.
- More than one device special file name, for example:
  Device_Char_Files = rrz1,rrz2,rrz3
  To specify more than one file name, specify the names separated by commas.
- A range of device special file names, for example:
  Device_Char_Files = rrz1[1-10]
  To specify a range of file names, enclose the range within brackets ([]) and separate the beginning and ending names with a dash (-). The following rules apply to letters specified in a range:
  - Both letters must be either lowercase or uppercase. Thus, [a-h] or [A-H] are valid range specifications while [A-h] and [a-H] are invalid.
  - Only one letter is allowed in the range specification, as in the example. Thus, [aa-hh] is not a valid range specification.
  - The ending letter must be greater than the beginning letter. Thus, [z-a] is not a valid range specification.
- More than one range of device special file names, for example:
  Device_Char_Files = rrz1[a-h],rrz2[i-t]
  To specify more than one range of file names, enclose the first range within brackets ([]) and separate the range with a dash (-). Follow the first range with a comma (,). Specify the second range in the same manner as the first and omit the comma (unless there are additional ranges).
  The values you specify for block devices are the same except that you use the Device_Block_Files field instead of Device_Char_Files. In addition, you specify the device name as a block device, for example rz0 and rz1 instead of rrz0 and rrz1.
  The Device_Char_Files field must be paired with corresponding minor numbers specified in the Device_Char_Minor field. (For block devices, the Device_Block_Files field must be paired with corresponding minor numbers specified in the Device_Block_Minor field.) The ranges for each must represent an equal number of file-to-minor number associations. The following example shows a correct match:
  Device_Char_Files = rrz0[a-h]
  Device_Char_Minor = [0-7]
  The following shows an invalid match:
  Device_Char_Files = rrz0[a-c]
  Device_Char_Minor = [0-7]
  The following shows a match that uses more than one range. Note that the gap in the minor numbers is valid.
  Device_Char_Files = rrz0[a-h],rrz1[a-h],rrz2[a-h],rrt5[a-h]
  Device_Char_Minor = [0-7],[8-15],[16-23],[40-47]
  The number of files must equal the number of minor numbers, just as in a single range specification. In addition, the maximum number of devices is 512. Thus, the following range specifications are invalid:
  Device_Char_Files = rrz0[0-300],rrz1[301-600]
  Device_Char_Minor = [0-300],[301-600]
  If you violate any of the previously discussed rules, none of the device special files will be created.
[Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the value root to the Device_User field. This field identifies the user that owns the device special files associated with the /dev/none driver.
Use the value root as the user name or specify something else for your driver product. [Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the value zero (0) to the Device_Group field. This field identifies the group that owns the device special files associated with the /dev/none driver.
Use the value zero (0) as the group user or specify something else for your driver product. [Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the value 666 to the Device_Mode field. This field identifies the protection mode for the device special files associated with the /dev/none driver.
Use the value 666 as the protection mode or specify another octal number for your driver product. [Return to example]
Shows that the driver writer at EasyDriver Incorporated assigns the value Same to the Device_Major_Req field. This field specifies requirements that relate to major number assignment.
Use the value Same for your driver product. [Return to example]
The option data for a bus contains bus-specific information. For example, the option data associated with the TURBOchannel bus includes the module name and the driver name. The option data for the EISA bus includes the board ID and the driver name. The driver writer at EasyDriver Incorporated assigns the option data associated with the TURBOchannel bus. For example purposes, the /dev/none driver operates on the TURBOchannel bus. Assign the option data associated with the bus your driver operates on, using the following fields: EISA_Option, ISA_Option, PCI_Option, or TC_Option. If your driver operates on multiple buses, then you would specify the appropriate keywords. For example, if your driver operates on the EISA, ISA, and PCI buses you would specify the EISA_Option, ISA_Option, and PCI_Option keywords.
See the bus-specific books for descriptions of the values associated with these option data fields.
Drivers operating on the VMEbus use the VBA_Option keyword.
One characteristic to note for the TC_Option field is that the information must be specified on one line (that is, there should be no carriage returns separating the information). For complete explanations of the information associated with the TC_Option keyword, see Writing TURBOchannel Device Drivers. [Return to example]

If your device driver calls the contig_malloc interface to allocate physically contiguous memory and you have implemented the driver to be dynamically configured into the kernel, you need to specify the CMA_Option field in your sysconfigtab file fragment. The contig_malloc interface cooperates with the cma_dd subsystem to ensure that a dynamically configured driver's request for physically contiguous memory is granted. The call to contig_malloc is the same for statically or dynamically configured drivers. However, in the case of dynamically configured drivers, it is the cma_dd subsystem that causes the physically contiguous memory to be allocated. The reason for this is that the contig_malloc interface does not work when the system reaches single-user mode.

The CMA_Option field provides the information that the Digital-provided cma_dd subsystem needs. The cma_dd subsystem allocates physically contiguous memory on behalf of a device driver that is dynamically configured into the kernel.

Each CMA_Option entry causes the cma_dd subsystem to generate (by calling the contig_malloc interface) a contiguous block of memory. The cma_dd subsystem reserves this memory in a saved memory pool. When specifying information with the CMA_Option field, you use five parameters that map to the five arguments associated with contig_malloc. You must make sure that the values passed to the call to contig_malloc match the values specified with the paramaters associated with the CMA_Option field.

A device driver later calls the contig_free interface to release the physically contiguous memory and cause the cma_dd subsystem to return the memory resource to the save memory pool. This memory resource is then available for reallocation by a dynamically configured driver upon subsequent reload requests.

The following sysconfigtab file fragment shows how to specify the CMA_Option for a /dev/xx driver.

xx:

.
.
.

CMA_Option = Size - 0x10000, Alignment - 0x10000, Addrlimit - 0,
             Type - 0x1f, Flag - 1 [1]

.
.
.

You specify the CMA_Option field. One characteristic to note for the CMA_Option field is that the information must be specified on one line (that is, there should be no carriage returns separating the information). The following list describes the five parameters:

Size
This parameter maps to the size argument of the contig_malloc interface. The parameter specifies the size of the memory (in bytes) to allocate.
In the example, the size is 0x10000.
Alignment
This parameter maps to the alignment argument of the contig_malloc interface. The parameter specifies the alignment of the memory to be allocated. For example, for a 256-byte alignment you should pass the value 256. A zero (0) value means there is no alignment requirement.
In the example, the alignment is 0x10000.
Addrlimit
This parameter maps to the addrlimit argument of the contig_malloc interface. The parameter specifies that the address of all the allocated memory should be less than or equal to this address. A zero (0) value means that there is no address limit requirement.
In the example, the address limit is the value zero (0).
Type
This parameter maps to the type argument of the contig_malloc interface. The parameter specifies the purpose for which the memory is being allocated (or freed). The memory type constants are defined in the file /usr/sys/include/sys/malloc.h. Examples of memory type constants are M_DEVBUF (device driver memory), M_KTABLE (kernel table memory), M_RTABLE (routing tables memory), and so forth.
In the example, the type is 0x1f. You should reference the /usr/sys/include/sys/malloc.h file to determine the hexadecimal value to be defined in the Type parameter.

Flag

This parameter maps to the flag argument of the contig_malloc interface. The parameter specifies one of the following flags defined in /usr/sys/include/sys/malloc.h:

Value Meaning

M_ZERO Signifies that contig_malloc should zero the allocated memory.

M_WAITOK Signifies that contig_malloc can block.

M_NOWAIT Signifies that contig_malloc cannot block.

In the example, the flag is the value 1. You should reference the /usr/sys/include/sys/malloc.h file to determine the hexadecimal value to be defined in the Flag parameter.

[Return to example]

The example sysconfigtab file fragment discussed in this section uses a subset of the available fields. Table 14-1 describes all of the possible fields along with a short description.

Table 14-1: The sysconfigtab File Fragment Fields

Field	Meaning
`Device_Dir`	The `Device_Dir` field is optional. It specifies a valid directory specification for the location of the device special files. This directory is typically `/dev` for both block and character devices. If you do not specify a directory for this field, it defaults to `/dev` for both block and character devices.
`Device_Subdir`	The `Device_Subdir` field is optional. It is appended to the directory specified or defaulted to in the `Device_Dir` field. The `Device_Subdir` field specifies a single directory location for the placement of the device special files associated with both character and block drivers. If you do not specify a directory for this field, the system places the device special files in the directory specified or defaulted to in the `Device_Dir` field. If the device special files for both block and character drivers should not reside in a single directory, use the `Device_Block_Subdir` and `Device_Char_Subdir` fields.
`Device_Block_Subdir`	The `Device_Block_Subdir` field is optional. It specifies a subdirectory for the directory specified in `Device_Dir`. The `Device_Block_Subdir` field overrides any directory specification you made in the `Device_Subdir` field for device special files associated with block device drivers. The system uses this directory to place the device special files for block drivers to keep them separate from the device special files for character drivers. If you do not specify a directory for this field, the system places the device special files in the directory specified or defaulted to in the `Device_Dir` field and the `Device_Subdir` field, if specified. If the device special files for block device drivers reside in the same directory as the device special files for character drivers, use the `Device_Subdir` field.
`Device_Char_Subdir`	The `Device_Char_Subdir` field is optional. It specifies a subdirectory for the directory specified in `Device_Dir`. The `Device_Char_Subdir` field overrides any directory specification you made in the `Device_Subdir` field for device special files associated with character device drivers. The system uses this directory to place the device special files for character drivers to keep them separate from the device special files for block drivers. If you do not specify a directory for this field, the system places the device special files in the directory specified or defaulted to in the `Device_Dir` field and the `Device_Subdir` field, if specified. If the device special files for character device drivers reside in the same directory as the device special files for block drivers, use the `Device_Subdir` field.
`Device_Major_Req`	The `Device_Major_Req` field is required. It specifies the requirements that relate to major number assignment. Specify the value `Same`.
`Device_Block_Major`	The `Device_Block_Major` field is required only if the driver is a block device driver. It specifies that the device special files associated with the driver will be created and will be assigned a major number. Specify the value `ANY`.
`Device_Block_Minor`	The `Device_Block_Minor` field is optional. It specifies the minor numbers used to create the device special files for the driver. You must pair each minor number with a file name specified in the `Device_Block_Files` field.
`Device_Block_Files`	The `Device_Block_Files` field is optional. It specifies the device special files to be created. You must pair each device special file name with a minor number specified in the `Device_Block_Minor` field. If a driver is both a block and character driver, specify device special files in both the `Device_Block_Files` and `Device_Char_Files` fields.
`Device_Char_Major`	The `Device_Char_Major` field is required only if the driver is a character driver. It specifies that the device special files associated with the driver will be created and will be assigned a major number. Specify the value `ANY`.
`Device_Char_Minor`	The `Device_Char_Minor` field is optional. It specifies the minor numbers used to create the device special files for the driver. You must pair each minor number with a file name specified in the `Device_Char_Files` field.
`Device_Char_Files`	The `Device_Char_Files` field is optional. It specifies the device special files to be created. You must pair each device special file name with a minor number specified in the `Device_Char_Minor` field. If a driver is both a block and character driver, specify device special files in both the `Device_Block_Files` and `Device_Char_Files` fields.
`Device_User`	The `Device_User` field is optional. It specifies the user ID (UID) that owns the device special files for block and character devices. You can specify a decimal number or a string of alphabetic characters. The default is the value zero (0).
`Device_Group`	The `Device_Group` field is optional. It specifies the group ID (GID) to which the device special files associated with the block and character devices belong. You can specify a decimal number or a string of alphabetic characters. The default is the value zero (0).
`Device_Mode`	The `Device_Mode` field is optional. It specifies the protection mode for the device special files. You must specify an octal number. The default is the octal number 0664.
`Module_Config_Name`	The `Module_Config_Name` field specifies the driver name. You should set this field to the same name that was specified for the `entry_name` field in the `sysconfigtab` file fragment. See Figure 14-5 for a description of the `entry_name` field that appears in the `sysconfigtab` file fragment.
`CMA_Option`	The `CMA_Option` field provides the information that the Digital-provided `cma_dd` subsystem needs. The `cma_dd` subsystem allocates physically contiguous memory on behalf of a device driver that is dynamically configured into the kernel.
`EISA_Option`	The `EISA_Option` field specifies the option data associated with the EISA bus. See Writing EISA and ISA Bus Device Drivers for a description of the values that you can specify with this field.
`ISA_Option`	The `ISA_Option` field specifies the option data associated with the ISA bus. See Writing EISA and ISA Bus Device Drivers for a description of the values that you can specify with this field.
`PCI_Option`	The `PCI_Option` field specifies the option data associated with the PCI bus. See Writing PCI Bus Device Drivers for a description of the values that you can specify with this field.
`TC_Option`	The `TC_Option` field specifies the option data associated with the TURBOchannel bus. See Writing TURBOchannel Device Drivers for a description of the values that you can specify with this field.
`VBA_Option`	The `VBA_Option` field specifies the option data associated with the VMEbus. See Writing VMEbus Device Drivers for a description of the values that you can specify with this field.

14.1.6 Step 6: Run the sourceconfig Program

Run the sourceconfig program from the /usr/sys/conf directory:

# cd /usr/sys/conf [1]
# ./sourceconfig BINARY [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/conf directory before running the sourceconfig program.
You should also change to this directory prior to running the sourceconfig program. [Return to example]
Shows that the driver writer at EasyDriver Incorporated invokes the sourceconfig program followed by the BINARY configuration file name. This generates a new Makefile in the /usr/sys/BINARY directory. This Makefile contains the information necessary to compile the single binary module or modules defined in the BINARY.list file and the files file fragment. Section 14.1.4 (Step 4) tells you how to create a BINARY.list file in the /usr/sys/conf directory. Section 14.1.3 (Step 3) tells you how to create a files file fragment in the working directory for your product. For example, the driver writer at EasyDriver Incorporated created the files file fragment in the /usr/sys/io/ESA100 directory.
Your files file fragment resides in the directory that you created in Section 14.1.1 (Step 1). [Return to example]

14.1.7 Step 7: Run the make Program

Run the make program from the /usr/sys/BINARY directory:

# cd /usr/sys/BINARY [1]

# make none.mod [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/BINARY directory before running the make program.
You should also change to this directory prior to running the make program. [Return to example]
Shows that the driver writer at EasyDriver Incorporated invokes the make program followed by the name of the device driver product followed by the .mod extension. This step creates the single binary module in the /usr/sys/BINARY directory. In the example, none.mod is the single binary module for the /dev/none driver product, created in the /usr/sys/BINARY directory. This step also creates a link from the /usr/sys/BINARY directory to the directory you created in Section 14.1.1 (Step 1).
You should invoke the make program as in the example except replace none with the name of your driver product. Invoke the make program for each driver product you want to compile. The appropriate links get created as described in the previous paragraph. [Return to example]

14.1.8 Step 8: Create a Kernel Configuration Development Area

Use an editor such as vi to create a sysconfigtab file fragment:

Run the doconfig program from the /usr/sys/conf directory to create a kernel configuration development area:

# cd /usr/sys/conf [1]
# doconfig [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/conf directory.
You should also change to this directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated invokes the doconfig program.
You should invoke the doconfig program. [Return to example]

Enter the name of the target configuration file at the following prompt:

*** KERNEL CONFIGURATION AND BUILD PROCEDURE ***
Enter a name for the kernel configuration file. [CONRAD]: EASYDRV

For purposes of testing your device driver, enter a new name for the target configuration file. For example, the driver writer at EasyDriver Incorporated enters the target configuration file name EASYDRV. Giving the doconfig program a new target configuration file name allows your existing target configuration file to remain on the system. You can then use the new target configuration file to configure a system that contains the device driver that you are testing.

Select the option from the menu that indicates you are adding no new kernel options.

Indicate that you do not want to edit the target configuration file in response to the following prompt:

Do you want to edit the configuration file? (y/n) [n] no

14.1.9 Step 9: Run the sysconfigdb Utility

Run the sysconfigdb utility to configure the single binary module's attributes:

# cd /usr/sys/io/ESA100 [1]
# sysconfigdb -a -f sysconfigtab none [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/io/ESA100 directory.
You should change to the directory that you created in Section 14.1.1 (Step 1). [Return to example]
Shows that the driver writer at EasyDriver Incorporated invokes the sysconfigdb utility with the following flags:
- The -a flag
  Specifies that sysconfigdb add the device driver entry to the /etc/sysconfigtab database.
- The -f flag
  Specifies the flag that precedes the sysconfigtab file fragment whose device driver entry is to be added to the /etc/sysconfigtab database. This flag is used with the -a flag.
- The device driver name
  The driver writer at EasyDriver Incorporated specifies the name of the driver product, none.
  You should replace none with the name of your driver product.
[Return to example]

14.2 Statically Configuring a Single Binary Module

After creating a single binary module of the device driver product, you can statically configure it into the kernel as follows:

Statically configure a single binary module into a /vmunix kernel
Statically configure a single binary module into a /sysconfigtab boot-link kernel

The following sections describe the steps for each of these tasks.

14.2.1 Statically Configuring a Single Binary Module into a /vmunix Kernel

To statically configure a single binary module into a /vmunix kernel, you perform the following steps:

Step 1: Edit or create the NAME.list file
Step 2: Run the doconfig program
Step 3: Copy /vmunix (the new kernel) to the root directory
Step 4: Shut down and boot the system

The following sections discuss each of these steps.

14.2.1.1 Step 1: Edit or Create the NAME.list File

Section 14.1.8 (Step 8) instructs you to create a kernel configuration development area. If your system has a /usr/sys/conf/.product.list file, then the system creates a NAME.list file. Use an editor such as vi to edit or create a NAME.list file in the /usr/sys/conf directory:

# cd /usr/sys/conf [1]
# vi EASYDRV.list [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/conf directory.
You should also change to this directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated uses the vi editor to create a NAME.list file called EASYDRV.list.
You can use vi or another editor to create the NAME.list file. You replace NAME with the name you specified for the target configuration file in Section 14.1.8 (Step 8). [Return to example]

The following example shows the contents of the EASYDRV.list file the driver writer at EasyDriver Incorporated creates:

/usr/sys/io/ESA100:

The contents of the NAME.list file is the directory you created in Section 14.1.1 (Step 1).

The contents of your NAME.list file should be the directory you created in Section 14.1.1 (Step 1). You must follow the path and file name with a colon (:), as shown in the example.

14.2.1.2 Step 2: Run the doconfig Program

Run the doconfig program from the /usr/sys/conf directory to rebuild the kernel. You previously created this kernel (and associated configuration development area) in Section 14.1.8 (Step 8).

# cd /usr/sys/conf [1]
# doconfig -c EASYDRV [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/conf directory.
You should also change to this directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated invokes the doconfig program with the -c option followed by the target configuration file name, EASYDRV.
You should invoke doconfig with the -c option and replace EASYDRV with the name of your target configuration file. [Return to example]

Enter the name of the target configuration file at the following prompt:

*** KERNEL CONFIGURATION AND BUILD PROCEDURE ***
Enter a name for the kernel configuration file. [CONRAD]: EASYDRV

For purposes of testing your device driver, enter a new name for the target configuration file. For example, the driver writer at EasyDriver Incorporated enters the target configuration file name EASYDRV. Giving the doconfig program a new target configuration file name allows your existing target configuration file to remain on the system. You can then use the existing target configuration file to configure a system that omits the device driver you are testing.

Select the option from the Kernel Option Selection menu that indicates you are adding no new kernel options.

Indicate that you do not want to edit the target configuration file in response to the following prompt:

Do you want to edit the configuration file? (y/n) [n] no

14.2.1.3 Step 3: Copy the New Kernel to the Root Directory

Copy the new /vmunix kernel into the / (root) directory:

# cd / [1]
# cp /usr/sys/EASYDRV/vmunix /vmunix.none [2]

Shows that the driver writer at EasyDriver Incorporated changes to the / (root) directory.
You should also change to the / (root) directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated copies the new /vmunix kernel to the root directory. Note that the driver writer specifies the name vmunix.none as the name for the new kernel. This is typically done when testing the driver.
You should perform a similar copy operation, replacing EASYDRV with the target configuration file name you specified in Section 14.2.1.2 (Step 3). Also replace the name none in vmunix.none with some other appropriate name. [Return to example]

14.2.1.4 Step 4: Shut Down and Boot the System

Shut down and boot the system:

# shutdown -h now [1]
>>> boot -fi "vmunix.none" [2]

Shows that the driver writer at EasyDriver Incorporated specifies the shutdown command with the -h option to shut down the system.
You should perform a similar shutdown procedure. [Return to example]
Shows that the driver writer at EasyDriver Incorporated specifies the boot command followed by the fi options and the name of the new kernel. This was the kernel copied to the root directory in Section 14.2.1.3 (Step 4).
You should also specify the boot command in the same manner, replacing vmunix.none with the name you specified in Section 14.2.1.3 (Step 4).
The device driver product (single binary module) is now part of this new kernel. You can now test it with the appropriate utilities. [Return to example]

14.2.2 Statically Configuring a Single Binary Module into a /sysconfigtab Boot-Link Kernel

Typically, only device driver writers testing foreign devices and Digital-internal systems engineers testing new hardware platforms in the boot path before creating kits perform the steps in this section. The boot-link kernel should not be used for system use because it is an installation technology. Assume that the /dev/edgd driver controls a foreign device.

Note
The steps in this section assume that the driver writer at EasyDriver Incorporated created a single binary module for the /dev/edgd driver product. The steps in this section will make references to the steps for creating a single binary module for the /dev/edgd driver product. However, the actual details and examples are not provided.

To statically configure a single binary module into a boot-link kernel (the /sysconfigtab text file), you perform the following steps:

Step 1: Edit or create the NAME.list file
Step 2: Run the doconfig program
Step 3: Copy the sysconfigtab file (the new boot-link kernel) to the root directory
Step 4: Copy the none.mod, NAME.mod, and EXTRAS.mod files
Step 5: Shut down and boot the boot-link kernel

The following sections discuss each of these steps.

14.2.2.1 Step 1: Edit or Create the NAME.list File

# cd /usr/sys/conf [1]
# vi EDBTLNK.list [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/conf directory.
You should also change to this directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated uses the vi editor to create a NAME.list file called EDBTLNK.list.
You can use vi or another editor to create the NAME.list file. You replace NAME with the name you will specify for the target configuration file in Section 14.2.1.2 (Step 3). [Return to example]

The following example shows the contents of the EDBTLNK.list file the driver writer at EasyDriver Incorporated creates:

/usr/sys/io/ESB100:

The contents of the NAME.list file is the directory created in Section 14.1.1 (Step 1).

The contents of your NAME.list file should be the directory you created in Section 14.1.1 (Step 1). You must follow the path and file name with a colon (:), as shown in the example.

14.2.2.2 Step 2: Run the doconfig Program

Run the doconfig program from the /usr/sys/conf directory to rebuild the kernel. You previously created this kernel (and associated configuration development area) in Section 14.1.8 (Step 8). In this case, you use the -b option:

# cd /usr/sys/conf [1]
# doconfig -b EDBTLNK [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /usr/sys/conf directory.
You should also change to this directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated invokes the doconfig program with the -b option followed by the target configuration file name, EDBTLNK.
You should invoke doconfig with the -b option and replace EDBTLNK with the name of your target configuration file. [Return to example]

Enter the name of the configuration file at the following prompt:

*** KERNEL CONFIGURATION AND BUILD PROCEDURE ***
Enter a name for the kernel configuration file. [CONRAD]: EASYDRV

For purposes of testing your device driver, enter a new name for the target configuration file, such as EASYDRV. Giving the doconfig program a new target configuration file name allows your existing target configuration file to remain on the system. You can then use the existing target configuration file to configure a system that omits the device driver you are testing.

Select the option from the Kernel Option Selection menu that indicates you are adding no new kernel options.

Indicate that you want to edit the target configuration file in response to the following prompt:

Do you want to edit the configuration file? (y/n) [n] no

14.2.2.3 Step 3: Copy the sysconfigtab File

Copy /sysconfigtab (the new boot-link kernel) into the / (root) directory:

# cd / [1]
# cp /usr/sys/EDBTLNK/sysconfigtab /vmunix.edgd.sysconfigtab [2]

Shows that the driver writer at EasyDriver Incorporated changes to the / (root) directory.
You should also change to the / (root) directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated copies /sysconfigtab (the new boot-link kernel) to the root directory.
You should perform a similar copy operation, replacing EDBTLNK and vmunix.edgd.sysconfigtab with names appropriate to your development environment. [Return to example]

14.2.2.4 Step 4: Copy the none.mod, NAME.mod, and EXTRAS.mod Files

Copy the single binary module (the driver product with the .mod file extension), the NAME.mod file, and the EXTRAS.mod file to the /sys/BINARY directory. The EXTRAS.mod file contains object files (files with .o file extensions).

# cd /sys/BINARY [1]
# cp /usr/sys/io/ESB100/none.mod . [2]
# cp /usr/sys/EDBTLNK/EXTRAS.mod . [3]
# cp /usr/sys/EDBTLNK/EDBTLNK.mod . [4]

Shows that the driver writer at EasyDriver Incorporated changes to the /sys/BINARY directory.
You should also change to the /sys/BINARY directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated copies the none.mod file to the /sys/BINARY directory. Note that the directory specification is for the directory created in Section 14.1.1 (Step 1).
You should perform a similar copy operation, replacing none.mod with the name you specified in Section 14.1.1 (Step 1). [Return to example]
Shows that the driver writer at EasyDriver Incorporated copies the EXTRAS.mod file to the /sys/BINARY directory. Note that the directory specification is for the directory created in Section 14.2.2.2 (Step 2).
You should perform a similar copy operation, replacing none.mod with the name you specified in Section 14.2.2.2 (Step 2). [Return to example]
Shows that the driver writer at EasyDriver Incorporated copies the EDBTLNK.mod file to the /sys/BINARY directory.
You should perform a similar copy operation, replacing EDBTLNK with the name you specified in Section 14.2.2.2 (Step 2). [Return to example]

14.2.2.5 Step 5: Shut Down and Boot the Boot-Link Kernel

Shut down and reboot the system:

# shutdown -h now [1]
>>> boot -fi "vmunix.edgd.sysconfigtab" [2]

Shows that the driver writer at EasyDriver Incorporated specifies the shutdown command with the -h option to shut down the system.
You should perform a similar shutdown procedure. [Return to example]
Shows that the driver writer at EasyDriver Incorporated specifies the boot command followed by the fi flags and the name of the new boot-link kernel. This was the kernel copied to the root directory in Section 14.2.2.3 (Step 3).
You should also specify the boot command in the same manner, replacing vmunix.edgd.sysconfigtab with the name you specified in Section 14.2.2.3 (Step 3).
The device driver product (single binary module) is now part of this new boot-link kernel. You can now test it with the appropriate utilities. [Return to example]

14.3 Dynamically Configuring a Single Binary Module

To dynamically configure a single binary module into a /sysconfigtab kernel, you perform the following steps:

Step 1: Link to the single binary module
Step 2: Link to the method file
Step 3: Run the sysconfig utility

The following sections discuss each of these steps.

Note
The steps in this section assume that the driver writer at EasyDriver Incorporated created a single binary module for the /dev/none driver product. The steps in this section will make references to the steps for creating a single binary module for the /dev/none driver product. These steps were described in Section 14.1.1 (Step 1) through Section 14.1.7 (Step 9).

14.3.1 Step 1: Link to the Single Binary Module

Run the ln command to link the single binary module attributes:

# cd /var/subsys [1]
# ln -s /usr/sys/BINARY/none.mod none.mod [2]

Shows that the driver writer at EasyDriver Incorporated changes to the /var/subsys directory.
You should also change to the /var/subsys directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated creates a symbolic link. The source of the link is /usr/sys/BINARY/none.mod and the destination is none.mod.
You should also create a symbolic link by replacing none with the name of your driver product. [Return to example]

14.3.2 Step 2: Link to the Method File

Run the ln command to link to the method file:

# pwd [1]
/var/subsys
# ln -s /subsys/device.mth none.mth [2]

Shows that the driver writer at EasyDriver Incorporated uses the pwd command to make sure the working directory is /var/subsys. The pwd command displays /var/subsys, the directory changed to in Section 14.3.1 (Step 2).
You should also check that you are in the /var/subsys directory. [Return to example]
Shows that the driver writer at EasyDriver Incorporated creates a symbolic link. The source of the link is /subsys/device.mth and the destination is none.mth.
You should also create a symbolic link by replacing none with the name of your driver product. [Return to example]

14.3.3 Step 3: Run the sysconfig Utility

Use the sysconfig utility to load the single binary module:

# sysconfig -c none [1]

Shows that the driver writer at EasyDriver Incorporated uses the sysconfig utility to load the single binary module. The -c option configures the single binary module into the kernel and creates the device special files.
You should also use the sysconfig utility and the -c option to load the single binary module. Replace none with the product name for your driver. [Return to example]

When you dynamically configure a single binary module into a kernel, you have access to debug information related to the configuration of the driver. The following are valid debug attributes: EISA_Developer_Debug (EISA bus), ISA_Developer_Debug (ISA bus), PCI_Developer_Debug (PCI bus), and TC_Developer_Debug (TURBOchannel bus). To enable a debug attribute (and thus have debug messages displayed on the console terminal), you run the sysconfig utility with the -r option as follows. Note that there should be no spaces before and after the equals (=) sign.

# sysconfig -r pci PCI_Developer_Debug=1

To disable a debug attribute (and thus have no debug messages displayed on the console terminal), you run the sysconfig utility with the -r option as follows. Note that there should be no spaces before and after the equals (=) sign.

# sysconfig -r pci PCI_Developer_Debug=0

Value	Meaning
`M_ZERO`	Signifies that `contig_malloc` should zero the allocated memory.
`M_WAITOK`	Signifies that `contig_malloc` can block.
`M_NOWAIT`	Signifies that `contig_malloc` cannot block.