About This Book

This book discusses how to write TURBOchannel bus device drivers for Digital UNIX® systems.

Audience

This book is intended for systems engineers who:

Use standard library interfaces to develop programs in the C language
Know the Bourne or some other shell based on the UNIX operating system
Understand basic Digital UNIX concepts such as kernel, shell, process, configuration, and autoconfiguration
Understand how to use the Digital UNIX programming tools, compilers, and debuggers
Develop programs in an environment that involves dynamic memory allocation, linked list data structures, and multitasking
Understand the hardware device for which the driver is being written
Understand the basics of the CPU hardware architecture, including interrupts, direct memory access (DMA) operations, and I/O

This book assumes that you have a strong background in operating systems based on the UNIX operating system. It also assumes that you have a strong background in systems and C programming, and that you are familiar with topics presented in Writing Device Drivers: Tutorial. In addition, the book assumes that you have no source code licenses.

New and Changed Features

Although existing device drivers are binary compatible with the current version of Digital UNIX, you may want to take advantage of the single binary module technology. The following list summarizes the issues you need to consider when deciding whether to update device drivers written on previous versions of Digital UNIX to the current version of the Digital UNIX operating system.

Method for registering interrupt handlers
Method for registering block and character device driver interfaces
Use of the bus-specific option structure and structure snippet
Driver object files
Elimination of the stanza.static file fragment
Elimination of the stanza.loadable file fragment
Changes to the files file fragment
Elimination of the config.file file fragment
Method for configuring and unconfiguring controllers
Method for identifying bus, controller, and device information
Use of name_data.c files
Method for specifying device special file information
Use of device driver header file

For more information on these and other changes to device drivers, see Writing Device Drivers: Tutorial.

The following sections summarize the changes and additions made to this version of the book. Note that the chapter titled "Device Autoconfiguration on the TURBOchannel Bus" has been deleted.

Chapter 2: TURBOchannel Architecture

All new TURBOchannel device drivers should be dynamically registering interrupt handlers by using the ihandler_t and handler_intr_info data structures and by calling the handler interfaces. You no longer need to call the enable_option and disable_option interfaces. These interfaces will be retired in a future release of the Digital UNIX operating system. Thus, the section in this chapter that discussed the tc_enable_option, tc_disable_option, enable_option, and disable_option interfaces has been deleted.

Chapter 4: Data Structures That TURBOchannel Device Drivers Use

The following data structures are no longer discussed in this chapter:

tc_option
For previous versions of the operating system, you must understand the tc_option data structure, the tc_option structure array defined in tc_option_data.c, and the tc_option snippet structure. For this version of Digital UNIX, you no longer add entries to the tc_option structure array (for drivers that are statically configured into the kernel) or declare and initialize a tc_option structure snippet (for drivers that are dynamically configured into the kernel). For drivers that are statically configured into the kernel, this means you no longer directly edit the bus-specific structure option arrays or use the mkdata utility and associated bus-specific data files. You now use the TC_Option attribute field to populate a sysconfigtab file fragment. The information in the sysconfigtab file fragment gets appended to the /etc/sysconfigtab database. Thus, you do not need to understand the members of the tc_option structure. The section that discussed the tc_option structure has been deleted.
tc_intr_info
The tc_intr_info data structure is no longer discussed because you should be using the handler_intr_info data structure when registering a driver's interrupt handler.

Chapter 5: Kernel Interfaces That TURBOchannel Device Drivers Use

This chapter no longer discusses the enable_option and disable_option interfaces because they will be retired in a future release of the Digital UNIX operating system.

Chapter 7: TURBOchannel Device Driver Configuration

This chapter assumes that you are familiar with the third-party device driver kits delivery process, as described in Writing Device Drivers: Tutorial. For this version of Digital UNIX, you no longer add entries to the tc_option structure array (for drivers that are statically configured into the kernel) or declare and initialize a tc_option structure snippet (for drivers that are dynamically configured into the kernel). For drivers that are statically configured into the kernel, this means you no longer directly edit the bus-specific structure option arrays or use the mkdata utility and associated bus-specific data files. You now use the TC_Option attribute field to populate a sysconfigtab file fragment. The information in the sysconfigtab file fragment gets appended to the /etc/sysconfigtab database. Therefore, this chapter no longer discusses the tc_data file and the tc_option snippet structure. Instead, it discusses the syntax associated with the TC_Option attribute field. See the porting chapter in Writing Device Drivers: Tutorial for information on the differences between device drivers written for previous versions of Digital UNIX and device drivers written for the current version.

Appendix C: Summary Tables

Appendix C presents tables that summarize the header files, kernel interfaces, data structures, and other interfaces that device drivers use.

Scope of the Book

This book is directed towards users of the Digital UNIX operating system on computer systems that Digital Equipment Corporation has developed.
The book builds on the concepts and topics presented in Writing Device Drivers: Tutorial, the core book for developing device drivers on Digital UNIX. This book introduces driver writers to topics that are specific to the TURBOchannel bus and that are beyond the scope of the core tutorial. The book presents an example driver that operates on the TURBOchannel bus.

The book does not emphasize any specific types of device drivers. However, mastering the concepts and example presented in this book is useful preparation for writing a variety of device drivers that operate on the TURBOchannel bus.

Organization

The book contains the following chapters and appendixes.

Chapter 1 Review of Device Driver Concepts

Reviews general device driver concepts, which are discussed in detail in Writing Device Drivers: Tutorial.

Chapter 2 TURBOchannel Architecture

Discusses aspects of the TURBOchannel software architecture with which a device driver writer must be familiar.

Chapter 3 Structure of a TURBOchannel Device Driver

Describes the sections that make up a TURBOchannel device driver.

Chapter 4 Data Structures That TURBOchannel Device Drivers Use

Discusses the data structures developed for use with TURBOchannel device drivers.

Chapter 5 Kernel Interfaces That TURBOchannel Device Drivers Use

Discusses the kernel interfaces developed for use with TURBOchannel device drivers.

Chapter 6 TURBOchannel Device Driver Example

Describes how to code a character device driver for a device that operates on the TURBOchannel bus.

Chapter 7 TURBOchannel Device Driver Configuration

Discusses the TC_Option attribute field.

Appendix A TURBOchannel-Specific Reference Information

Describes, in reference-page style, the header file, data structures, kernel support interfaces, and device driver interfaces that are specific to the TURBOchannel bus.

Appendix B TURBOchannel Device Driver Source Listing

Contains the source code listing for the example driver presented in this book.

Appendix C Summary Tables

Presents tables that summarize the header files, kernel interfaces, data structures, and other interfaces that device drivers use.

Related Documentation

The printed version of the Digital UNIX documentation set is color coded to help specific audiences quickly find the books that meet their needs. (You can order the printed documentation from Digital.) This color coding is reinforced with the use of an icon on the spines of books. The following list describes this convention:

Audience Icon Color Code

General users G Blue

System and network administrators S Red

Programmers P Purple

Device driver writers D Orange

Reference page users R Green

Some books in the documentation set help meet the needs of several audiences. For example, the information in some system books is also used by programmers. Keep this in mind when searching for information on specific topics.

The Documentation Overview, Glossary, and Master Index provides information on all of the books in the Digital UNIX documentation set.

Writing device drivers is a complex task; driver writers require knowledge in a variety of areas. One way to acquire this knowledge is to have at least the following categories of documentation available:

Hardware documentation
Bus-specific device driver documentation
Operating system overview documentation
Programming tools documentation
Network programming documentation
System management documentation
Porting documentation
Kernel kit products documentation
Reference pages

The following sections list the documentation associated with each of these categories.

Hardware Documentation

You should have available the hardware manual associated with the device for which you are writing the device driver. You should also have access to the manual that describes the architecture associated with the CPU that the driver operates on, for example, the Alpha Architecture Reference Manual.

Bus-Specific Device Driver Documentation

The following documents provide information that pertains to writing device drivers for any bus architecture:

Writing Device Drivers: Tutorial
This manual provides information for systems engineers who write device drivers for hardware that runs the Digital UNIX operating system. Systems engineers can find information on driver concepts, device driver interfaces, kernel interfaces used by device drivers, kernel data structures, configuration of device drivers, and header files related to device drivers.
Writing Device Drivers: Advanced Topics
This manual provides information on topics that are beyond the scope of the core tutorial. Systems engineers can find information on such advanced topics as kernel threads and writing device drivers in a symmetric multiprocessing (SMP) environment. The manual also contains information about writing disk drivers.
Writing Device Drivers: Reference
This manual contains descriptions of the header files, kernel support interfaces, ioctl commands, global variables, data structures, device driver interfaces, and bus configuration interfaces associated with device drivers. The descriptions are formatted similarly to the Digital UNIX reference pages.

The following books provide information about writing device drivers for a specific bus that is beyond the scope of the core tutorial, advanced topics, and reference:

Writing EISA and ISA Bus Device Drivers
This manual provides information for systems engineers who write device drivers for the EISA/ISA bus. The manual describes EISA/ISA bus-specific topics, including EISA/ISA bus architecture and data structures that EISA/ISA bus device drivers use.
Writing PCI Bus Device Drivers
This manual provides information for systems engineers who write device drivers for the PCI bus. The manual describes PCI bus-specific topics, including PCI bus architecture and data structures that PCI bus device drivers use.
Writing Device Drivers for the SCSI/CAM Architecture Interfaces
This manual provides information for systems engineers who write device drivers for the SCSI/CAM Architecture interfaces.
The manual provides an overview of the Digital UNIX SCSI/CAM Architecture and describes User Agent routines, data structures, common and generic routines and macros, error handling and debugging routines.
The manual includes information on configuration and installation. Examples show how programmers can define SCSI/CAM device drivers and write to the SCSI/CAM special I/O interface supplied by Digital to process special SCSI I/O commands.
Writing VMEbus Device Drivers
This manual contains information systems engineers need to write device drivers that operate on the VMEbus. The manual describes VMEbus-specific topics, including VMEbus architecture and kernel interfaces that VMEbus device drivers use. A VMEbus device driver example illustrates the use of these kernel interfaces.

Operating System Overview Documentation

Refer to the Technical Overview for a technical introduction to the Digital UNIX operating system. This manual provides a technical overview of the Digital UNIX system, focusing on the networking subsystem, the file system, virtual memory, and the development environment. In addition, the manual lists all system limits.

This manual does not supersede the Software Product Description (SPD), which is the definitive description of the Digital UNIX system.

Programming Tools Documentation

To create your device drivers, you use a number of programming development tools and should have on hand the manuals that describe how to use these tools. The following manuals provide information related to programming tools used in the Digital UNIX operating system environment:

Kernel Debugging
This manual provides information about debugging kernels. The manual describes using the dbx, kdbx, and kdebug debuggers to find problems in kernel code. It also describes how to write a kdbx utility extension and how to create and analyze a crash dump file.
This manual is for system administrators responsible for modifying, rebuilding, and debugging the kernel configuration. It is also for system programmers who need to debug their kernel space programs.
Programming Support Tools
This manual describes several commands and utilities in the Digital UNIX system, including facilities for text manipulation, macro and program generation, and source file management.
The commands and utilities described in this manual are primarily for programmers, but some of them (such as grep, awk, sed, and the Source Code Control System (SCCS)) are useful for other users. This manual assumes that you are a moderately experienced user of UNIX systems.
Programmer's Guide
This manual describes the programming environment of the Digital UNIX operating system, with an emphasis on the C programming language.
This manual is for all programmers who use the Digital UNIX operating system to create or maintain programs in any supported language.

System Management Documentation

Refer to the System Administration manual for information about building a kernel and for general information on system administration. This manual describes how to configure, use, and maintain the Digital UNIX operating system. It includes information on general day-to-day activities and tasks, changing your system configuration, and locating and eliminating sources of trouble.

This manual is for the system administrators responsible for managing the operating system. It assumes a knowledge of operating system concepts, commands, and configurations.

Porting Documentation

Refer to the Digital UNIX Migration Guide for a discussion of the differences between the Digital UNIX and ULTRIX operating systems. This manual compares the Digital UNIX operating system to the ULTRIX operating system by describing the differences between the two systems.

This manual has three audiences, as follows:

General users can read this manual to determine the differences between using an ULTRIX system and using the Digital UNIX system.
System and network administrators can read this manual to determine the differences between ULTRIX and Digital UNIX system administration.
Programmers can read this manual to determine the differences between the ULTRIX programming environment and the Digital UNIX programming environment.

This manual assumes you are familiar with the ULTRIX operating system.

Reference Pages

The following reference pages are of interest to device driver writers:

Reference Pages Section 2
This section defines system calls (entries into the Digital UNIX kernel) that programmers use. The introduction to Section 2, intro(2), lists error numbers with brief descriptions of their meanings. The introduction also defines many of the terms used in this section. This section is for programmers.
Reference Pages Section 3
This section describes the routines available in Digital UNIX programming libraries, including the C library, Motif library, and X library. This section is for programmers. In printed format, this section is divided into six volumes.
Reference Pages Section 4
Section 4 describes the format of system files and how the files are used. The files described include assembler and link editor output, system accounting, and file system formats. This section is for programmers and system administrators. In printed format, this section is divided into two volumes.
Reference Pages Section 5
Section 5 contains miscellaneous information, including ASCII character codes, mail-addressing formats, text-formatting macros, and a description of the root file system. This section is for programmers and system administrators.
Reference Pages Section 7
Section 7 describes special files, related device driver functions, databases, and network support. This section is for programmers and system administrators.
Reference Pages Section 8 and 1m
This section describes commands for system operation and maintenance. It is for system administrators. In printed format, this section is divided into two volumes.

Reader's Comments

Digital welcomes any comments and suggestions you have on this and other Digital UNIX manuals.

You can send your comments in the following ways:

Fax: 603-881-0120 Attn: UEG Publications, ZK03-3/Y32
Internet electronic mail: readers_comment@zk3.dec.com
A Reader's Comment form is located on your system in the following location:
```
/usr/doc/readers_comment.txt
```
Mail:
Digital Equipment Corporation
UEG Publications Manager
ZK03-3/Y32
110 Spit Brook Road
Nashua, NH 03062-9987
A Reader's Comment form is located in the back of each printed manual. The form is postage paid if you mail it in the United States.

Please include the following information along with your comments:

The full title of the book and the order number. (The order number is printed on the title page of this book and on its back cover.)
The section numbers and page numbers of the information on which you are commenting.
The version of Digital UNIX that you are using.
If known, the type of processor that is running the Digital UNIX software.

The Digital UNIX Publications group cannot respond to system problems or technical support inquiries. Please address technical questions to your local system vendor or to the appropriate Digital technical support office. Information provided with the software media explains how to send problem reports to Digital.

Conventions

This book uses the following conventions:

.
.
.
A vertical ellipsis indicates that a portion of an example that would normally be present is not shown.

. . . In syntax definitions, a horizontal ellipsis indicates that the preceding item can be repeated one or more times.

filename In examples, syntax descriptions, and function definitions, this typeface indicates variable values.

buf In function definitions and syntax definitions used in driver configuration, this typeface is used to indicate names that you must type exactly as shown.

[ ] In formal parameter declarations in function definitions and in structure declarations, brackets indicate arrays. Brackets are also used to specify ranges for device minor numbers and device special files in file fragments. However, for the syntax definitions used in driver configuration, these brackets indicate items that are optional.

| Vertical bars separating items that appear in the syntax definitions used in driver configuration indicate that you choose one item from among those listed.

This book uses the word kernel ``interface'' instead of kernel ``routine'' or kernel ``macro.''

Chapter 1	Review of Device Driver Concepts
	Reviews general device driver concepts, which are discussed in detail in Writing Device Drivers: Tutorial.
Chapter 2	TURBOchannel Architecture
	Discusses aspects of the TURBOchannel software architecture with which a device driver writer must be familiar.
Chapter 3	Structure of a TURBOchannel Device Driver
	Describes the sections that make up a TURBOchannel device driver.
Chapter 4	Data Structures That TURBOchannel Device Drivers Use
	Discusses the data structures developed for use with TURBOchannel device drivers.
Chapter 5	Kernel Interfaces That TURBOchannel Device Drivers Use
	Discusses the kernel interfaces developed for use with TURBOchannel device drivers.
Chapter 6	TURBOchannel Device Driver Example
	Describes how to code a character device driver for a device that operates on the TURBOchannel bus.
Chapter 7	TURBOchannel Device Driver Configuration
	Discusses the `TC_Option` attribute field.
Appendix A	TURBOchannel-Specific Reference Information
	Describes, in reference-page style, the header file, data structures, kernel support interfaces, and device driver interfaces that are specific to the TURBOchannel bus.
Appendix B	TURBOchannel Device Driver Source Listing
	Contains the source code listing for the example driver presented in this book.
Appendix C	Summary Tables
	Presents tables that summarize the header files, kernel interfaces, data structures, and other interfaces that device drivers use.

Audience	Icon	Color Code
General users	G	Blue
System and network administrators	S	Red
Programmers	P	Purple
Device driver writers	D	Orange
Reference page users	R	Green

. . .	A vertical ellipsis indicates that a portion of an example that would normally be present is not shown.
. . .	In syntax definitions, a horizontal ellipsis indicates that the preceding item can be repeated one or more times.
`filename`	In examples, syntax descriptions, and function definitions, this typeface indicates variable values.
`buf`	In function definitions and syntax definitions used in driver configuration, this typeface is used to indicate names that you must type exactly as shown.
`[ ]`	In formal parameter declarations in function definitions and in structure declarations, brackets indicate arrays. Brackets are also used to specify ranges for device minor numbers and device special files in file fragments. However, for the syntax definitions used in driver configuration, these brackets indicate items that are optional.
\|	Vertical bars separating items that appear in the syntax definitions used in driver configuration indicate that you choose one item from among those listed.