Writing Device Drivers

Preface

Writing Device Drivers provides information on developing device drivers for character-oriented devices, block-oriented devices, and small computer system interface (SCSI) target devices. This book discusses the development of a dynamically loadable and unloadable, multithreaded reentrant device driver applicable to all architectures that conform to the Solaris^TM 8 DDI/DKI. A common driver programming approach is taken so that drivers can be written without concern for platform-specific issues, such as endianness and data ordering.

Who Should Use This Book

The audience for this book is UNIX® programmers familiar with UNIX device drivers. Several overview chapters at the beginning of the book provide background information for the detailed technical chapters that follow, but they are not intended as a general tutorial or text on device drivers.

How This Book Is Organized

This book is organized into the following chapters.

Chapter 1, Solaris Kernel and Device Tree provides an overview of the Solaris kernel and the manner in which it represents devices as nodes in a device tree.
Chapter 2, Overview of Solaris Device Drivers gives an outline of the kinds of device drivers and their basic structure. It points out the common data access routines and concludes with an illustrated roadmap of common driver entry points and structures.
Chapter 3, Multithreading describes the mechanisms of the Solaris multithreaded kernel that are of interest to driver writers.
Chapter 4, Properties describes the set of interfaces used to read an update device node properties.
Chapter 5, Autoconfiguration explains the support a driver must provide for autoconfiguration.
Chapter 6, Device Access -- Programmed I/O describes the interfaces and methodologies for drivers to use to access (read or write) device memory.
Chapter 7, Interrupt Handlers describes the interrupt handling mechanisms. These include registering, servicing, and removing interrupts.
Chapter 8, Direct Memory Access (DMA) describes direct memory access (DMA) and the DMA interfaces.
Chapter 9, Power Management explains the interfaces for Power Management^TM, a framework designed to regulate and reduce the power consumed by computer systems and devices.
Chapter 10, Drivers for Character Devices describes the structure and functions of a driver for a character-oriented device.
Chapter 11, Drivers for Block Devices describes the structure and functions of a driver for a block-oriented device.
Chapter 12, Mapping Device or Kernel Memory describes the set of interfaces that allow device drivers to manage access to memory, control the context of user processes accessing a device, and take advantage of large data transfers using new MMU hardware.
Chapter 13, Device Context Management describes the set of interfaces that allow device drivers to manage user access to devices.
Chapter 14, SCSI Target Drivers outlines the Sun Common SCSI Architecture and describes the additional requirements of SCSI target drivers.
Chapter 15, SCSI Host Bus Adapter Drivers explains how to write a SCSI Host Bus Adapter (HBA) driver using the Sun Common SCSI Architecture (SCSA).
Chapter 16, Compiling, Loading, Packaging, and Testing Drivers provides information on compiling and linking a driver, and for installing it in the system.
Chapter 17, Debugging gives coding suggestions, debugging hints, a simple mdb/kadb tutorial, and some hints on testing the driver.
Appendix A, Hardware Overview discusses multi-platform hardware issues related to device drivers.
Appendix B, Summary of Solaris 8 DDI/DKI Services summarizes, by topic, the kernel functions device driver can use.
Appendix C, Making a Device Driver 64-Bit Ready provides guidelines for updating a device driver to run in a 64-bit environment.
Appendix D, DDI Interfaces for Cluster-Aware Drivers provides information for creating cluster-aware drivers.
Appendix E, Hardened Drivers describes the concepts and techniques used to support hardened drivers.

Related Books and Papers

For detailed reference information about the device driver interfaces, see the man page sections 9, 9E (entry points), 9F (functions), and 9S (structures). For information on hardware issues and other driver-related issues, the following books might be helpful.

Application Packaging Developer's Guide, Sun Microsystems, 2000.
The SPARC Architecture Manual, Version 9. Prentice Hall, 1998. ISBN 0-13-099227-5.
The SPARC Architecture Manual, Version 8. Prentice Hall, 1994. ISBN 0-13-825001-4.
Pentium Pro Family Developer's Manual, Volumes 1-3. Intel Corporation, 1996. ISBN 1-55512-259-0 (Volume 1) , ISBN 1-55512-260-4 (Volume 2) , ISBN 1-55512-261-2 (Volume 3).
Open Boot PROM Toolkit User's Guide, Sun Microsystems Computer Company, 1996.
STREAMS Programming Guide. Sun Microsystems, 2000.
Multithreaded Programming Guide. Sun Microsystems, 2000.
Solaris 64-bit Developer's Guide. Sun Microsystems, 2000.
Solaris Modular Debugger Guide. Sun Microsystems, 2000.

Note -

In this document, the term "IA" refers to the Intel 32-bit processor architecture, which includes the Pentium, Pentium Pro, Pentium II, Pentium II Xeon, Celeron, Pentium III, and Pentium III Xeon processors, and compatible microprocessor chips made by AMD and Cyrix.

Note -

The Solaris operating environment runs on two types of hardware, or platforms--SPARC^TM and IA. The Solaris operating environment also runs on both 64-bit and 32-bit address spaces. The information in this document pertains to both platforms and address spaces unless called out in a special chapter, section, note, bullet, figure, table, example, or code example.

Ordering Sun Documents

Fatbrain.com, an Internet professional bookstore, stocks select product documentation from Sun Microsystems^TM, Inc.

For a list of documents and how to order them, visit the Sun Documentation Center on Fatbrain.com at http://www1.fatbrain.com/documentation/sun.

Accessing Sun Documentation Online

The docs.sun.com^SM Web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. The URL is http://docs.sun.com.

What Typographic Conventions Mean

The following table describes the typographic changes used in this book.

Table P-1 Typographic Conventions


Typeface or Symbol	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your `.login` file. Use `ls -a` to list all files. `machine_name% you have mail.`
`AaBbCc123`	What you type, contrasted with on-screen computer output	`machine_name%` `su` `Password:`
`AaBbCc123`	Command-line placeholder: replace with a real name or value	To delete a file, type `rm` `filename`.
AaBbCc123	Book titles, new words, or terms, or words to be emphasized.	Read Chapter 6 in User's Guide. These are called class options. You must be root to do this.

Shell Prompts in Command Examples

The following table shows the default system prompt and superuser prompt for the C shell, Bourne shell, and Korn shell.

Table P-2 Shell Prompts


Shell	Prompt
C shell prompt	`machine_name%`
C shell superuser prompt	`machine_name#`
Bourne shell and Korn shell prompt	`$`
Bourne shell and Korn shell superuser prompt	`#`
MDB prompt	`>`
SPARC PROM prompt	`ok`