1 Review of Device Driver Concepts

Before writing a driver for a TURBOchannel device, you must be familiar with driver concepts in general as well as specific tasks you need to perform to successfully code the driver. This book presumes you understand the following concepts:

Purpose of a device driver
Types of device drivers
Concept of the single binary module
When to call a device driver
Place of a device driver in Digital UNIX

The following sections review the tasks associated with writing device drivers. Writing Device Drivers: Tutorial discusses these tasks in detail.

1.1 Gathering Information

The first task in writing a device driver is to gather pertinent information about the host system and the device for which you are writing the driver. For example, you need to:

Specify information about the host system
Identify the standards used in writing the driver
Specify the characteristics and describe the usage of the device
Provide a description of the device registers
Identify support in writing the driver

1.2 Designing a Device Driver

After you gather information about the host system and the device, you are ready to design and develop the device driver. You need to specify the driver type and whether the driver you are writing will be statically or dynamically configured into the kernel. During the design of the driver, you also identify device driver entry points and describe the driver states.

1.3 Allocating Data Structures

Data structures are the mechanism used to pass information between the kernel and device driver interfaces. The following table summarizes data structures, which are described in Writing Device Drivers: Tutorial and Writing Device Drivers: Reference:

buf Describes arbitrary I/O.

bus Represents an instance of a bus entity to which other buses or controllers are logically attached.

cfg_attr_t Contains information for managing the loading and unloading of drivers.

cfg_subsys_attr_t Contains attribute information for drivers.

controller Contains members that store information about hardware resources and store data for communication between the kernel and the device driver.

controller_config Contains information needed to create a controller structure.

DEVGEOMST Stores disk device geometry.

devget Contains information about a device.

device Contains information that identifies the device. There is one device data structure for each device connected to the controller.

device_config Contains information needed to create a device structure.

device_info_t Is the top-level union that stores bus- and device-type information.

disklabel Stores disk device label information.

driver Defines driver entry points and other driver-specific information. You initialize this data structure in the device driver.

dsent Defines a device driver's entry points and other information.

handler_intr_info Contains interrupt handler information.

ihandler_t Contains information associated with device driver interrupt handling.

item_list Contains hardware platform-specific information.

lock Contains complex lock-specific information.

port Contains information about a port.

pt_tbl Stores a disk partition map.

sel_queue Defines a queue of select events.

sg_entry Contains bus address/byte count pairs.

slock Contains simple lock-specific information.

task Contains task-specific information.

thread Contains kernel threads-related information.

uio Describes I/O, either single vector or multiple vectors.

v1_bustype_info_t Stores bus information.

v1_device_info_t Is the top-level union that stores bus- and device-type information.

v1_devtype_info_t Stores device-type information.

v1_disk_dev_info_t Stores disk information.

v1_tape_dev_info_t Stores tape information.

When designing a device driver, you must decide on the technique you will use for allocating data structures. Generally, there are two techniques you can use: dynamic allocation and static allocation. Dynamic allocation is the recommended method for all new drivers; some existing drivers allocate data structures statically. If you know that the maximum number of devices is greater than five or that the driver uses numerous data structures, plan to use the dynamic allocation method.

1.4 Writing Portable Device Drivers

Whenever possible, design your device driver so that it can accommodate peripheral devices that operate on different bus architectures, different CPU architectures, and more than one CPU type within the same architecture. You need to consider the following issues to make your drivers portable across CPU architectures:

Control status register (CSR) access
Input/output (I/O) copy operation
Direct memory access (DMA) operation
64-bit versus 32-bit (of C compiler data types and bit sizes)

You need to consider the following issues to make your drivers portable across bus architectures:

Bus-specific header files
Bus-specific constant names
Bus-specific issues related to implementing the probe interface
Bus-specific issues related to implementing the slave interface
Bus-specific issues related to implementing the configure interface

You must consider these issues also if you have an ULTRIX device driver that you want to port to Digital UNIX. See Writing Device Drivers: Tutorial for a discussion of the additional tasks you need to perform to port an ULTRIX device driver to Digital UNIX. Also, see the porting chapter in Writing Device Drivers: Tutorial for a discussion of the issues associated with updating device drivers written for a previous version of Digital UNIX to the current version of the operating system. Although existing device drivers are binary compatible with the current version of Digital UNIX, you might want to make the changes suggested in the porting chapter of the tutorial.

Note
See Writing Device Drivers: Tutorial for information on the CSR I/O access interfaces read_io_port and write_io_port. These interfaces allow you to read from and write to a device's CSR addresses without directly accessing its device registers. Each of these interfaces takes an I/O handle that the bus configuration code passes to the driver's probe interface.
See Writing Device Drivers: Tutorial for information on the I/O copy operation interfaces io_copyin, io_copyio, io_copyout, and io_zero. These are generic interfaces that map to bus- and machine-specific interfaces that actually perform the I/O copy operations. Using these interfaces to perform copy operations makes the device driver more portable across different CPU architectures and different CPU types within the same architecture. Each of these interfaces takes an I/O handle that the bus configuration code passes to the driver's probe interface.

1.5 Reviewing the Device Driver Kits Delivery Process

When you are ready to write your driver, you may want to study the device driver kits delivery process and create an appropriate device driver development environment.

Writing Device Drivers: Tutorial describes the device driver kits delivery process and how to statically and dynamically configure drivers into the kernel. The tutorial discusses how to write device drivers for computer systems running Digital UNIX.

1.6 Identifying the Method for Registering Device Interrupt Handlers

For this version of Digital UNIX, Digital requires that you implement all new TURBOchannel bus device drivers to call the handler interfaces and reference the handler-specific data structures to register their device interrupt handlers. (See Writing Device Drivers: Tutorial for more information.)

`buf`	Describes arbitrary I/O.
`bus`	Represents an instance of a bus entity to which other buses or controllers are logically attached.
`cfg_attr_t`	Contains information for managing the loading and unloading of drivers.
`cfg_subsys_attr_t`	Contains attribute information for drivers.
`controller`	Contains members that store information about hardware resources and store data for communication between the kernel and the device driver.
`controller_config`	Contains information needed to create a `controller` structure.
`DEVGEOMST`	Stores disk device geometry.
`devget`	Contains information about a device.
`device`	Contains information that identifies the device. There is one `device` data structure for each device connected to the controller.
`device_config`	Contains information needed to create a `device` structure.
`device_info_t`	Is the top-level union that stores bus- and device-type information.
`disklabel`	Stores disk device label information.
`driver`	Defines driver entry points and other driver-specific information. You initialize this data structure in the device driver.
`dsent`	Defines a device driver's entry points and other information.
`handler_intr_info`	Contains interrupt handler information.
`ihandler_t`	Contains information associated with device driver interrupt handling.
`item_list`	Contains hardware platform-specific information.
`lock`	Contains complex lock-specific information.
`port`	Contains information about a port.
`pt_tbl`	Stores a disk partition map.
`sel_queue`	Defines a queue of select events.
`sg_entry`	Contains bus address/byte count pairs.
`slock`	Contains simple lock-specific information.
`task`	Contains task-specific information.
`thread`	Contains kernel threads-related information.
`uio`	Describes I/O, either single vector or multiple vectors.
`v1_bustype_info_t`	Stores bus information.
`v1_device_info_t`	Is the top-level union that stores bus- and device-type information.
`v1_devtype_info_t`	Stores device-type information.
`v1_disk_dev_info_t`	Stores disk information.
`v1_tape_dev_info_t`	Stores tape information.