Preface

Writing Device Drivers provides information on developing drivers for character-oriented devices, block-oriented devices, network devices, SCSI target and HBA devices, and USB devices for the Solaris^TM Operating System (Solaris OS). This book discusses how to develop multithreaded reentrant device drivers for all architectures that conform to the Solaris OS DDI/DKI (Device Driver Interface, Driver-Kernel Interface). A common driver programming approach is described that enables drivers to be written without concern for platform-specific issues such as endianness and data ordering.

Additional topics include hardening Solaris drivers; power management; driver autoconfiguration; programmed I/O; Direct Memory Access (DMA); device context management; compilation, installation, and testing drivers; debugging drivers; and porting Solaris drivers to a 64-bit environment.

Note –

This Solaris release supports systems that use the SPARC® and x86 families of processor architectures: UltraSPARC®, SPARC64, AMD64, Pentium, and Xeon EM64T. For supported systems, see the Solaris OS Hardware Compatibility Lists at http://www.sun.com/bigadmin/hcl/. This document cites any implementation differences between the platform types.

Who Should Use This Book

This book is written for UNIX® programmers who are familiar with UNIX device drivers. Overview information is provided, but the book is not intended to serve as a general tutorial on device drivers.

Note –

The Solaris operating system (Solaris OS) runs on both SPARC and x86 architectures. The Solaris OS also runs on both 64-bit and 32-bit address spaces. The information in this document applies to all platforms and address spaces unless specifically noted.

How This Book Is Organized

This book is organized into the following chapters:

Chapter 1, Overview of Solaris Device Drivers provides an introduction to device drivers and associated entry points on the Solaris platform. The entry points for each device driver type are presented in tables.
Chapter 2, Solaris Kernel and Device Tree provides an overview of the Solaris kernel with an explanation of how devices are represented as nodes in a device tree.
Chapter 3, Multithreading describes the aspects of the Solaris multithreaded kernel that are relevant for device driver developers.
Chapter 4, Properties describes the set of interfaces for using device properties.
Chapter 5, Managing Events and Queueing Tasks describes how device drivers log events and how to use task queues to perform a task at a later time.
Chapter 6, Driver Autoconfiguration explains the support that a driver must provide for autoconfiguration.
Chapter 7, Device Access: Programmed I/O describes the interfaces and methodologies for drivers to read or write to device memory.
Chapter 8, Interrupt Handlers describes the mechanisms for handling interrupts. These mechanisms include registering, servicing, and removing interrupts.
Chapter 9, Direct Memory Access (DMA) describes direct memory access (DMA) and the DMA interfaces.
Chapter 10, Mapping Device and Kernel Memory describes interfaces for managing device and kernel memory.
Chapter 11, Device Context Management describes the set of interfaces that enable device drivers to manage user access to devices.
Chapter 12, Power Management explains the interfaces for Power Management^TM, a framework for managing power consumption.
Chapter 13, Hardening Solaris Drivers describes how to integrate fault management capabilities into I/O device drivers, how to incorporate defensive programming practices, and how to use the driver hardening test harness.
Chapter 14, Layered Driver Interface (LDI) describes the LDI, which enables kernel modules to access other devices in the system.
Chapter 15, Drivers for Character Devices describes drivers for character-oriented devices.
Chapter 16, Drivers for Block Devices describes drivers for a block-oriented devices.
Chapter 17, SCSI Target Drivers outlines the Sun Common SCSI Architecture (SCSA) and the requirements for SCSI target drivers.
Chapter 18, SCSI Host Bus Adapter Drivers explains how to apply SCSA to SCSI Host Bus Adapter (HBA) drivers.
Chapter 19, Drivers for Network Devices describes the Generic LAN driver (GLD), a Solaris network driver that uses STREAMS technology and the Data Link Provider Interface (DLPI).
Chapter 20, USB Drivers describes how to write a client USB device driver using the USBA 2.0 framework.
Chapter 21, Compiling, Loading, Packaging, and Testing Drivers provides information on compiling, linking, and installing a driver.
Chapter 22, Debugging, Testing, and Tuning Device Drivers describes techniques for debugging, testing, and tuning drivers.
Chapter 23, Recommended Coding Practices describes the recommended coding practices for writing drivers.
Appendix A, Hardware Overview discusses multi-platform hardware issues for device drivers.
Appendix B, Summary of Solaris DDI/DKI Services provides tables of kernel functions for device drivers. Deprecated functions are indicated as well.
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, Console Frame Buffer Drivers describes how to add the necessary interfaces to a frame buffer driver to enable the driver to interact with the Solaris kernel terminal emulator.

Related Books and Papers

For detailed reference information about the device driver interfaces, see the section 9 man pages. Section 9E, Intro(9E), describes DDI/DKI (Device Driver Interface, Driver-Kernel Interface) driver entry points. Section 9F, Intro(9F), describes DDI/DKI kernel functions. Sections 9P and 9S, Intro(9S), describe DDI/DKI properties and data structures.

For information on hardware and other driver-related issues, see the following books from Sun Microsystems:

Device Driver Tutorial. Sun Microsystems, Inc., 2008.
Application Packaging Developer’s Guide. Sun Microsystems, Inc., 2005.
Open Boot PROM Toolkit User's Guide. Sun Microsystems, Inc., 1996.
STREAMS Programming Guide. Sun Microsystems, Inc., 2005.
Multithreaded Programming Guide. Sun Microsystems, Inc., 2008.
Solaris 64-bit Developer’s Guide. Sun Microsystems, Inc., 2005.
Solaris Modular Debugger Guide. Sun Microsystems, Inc., 2007.
Solaris Dynamic Tracing Guide. Sun Microsystems, Inc., 2005.
DTrace User Guide. Sun Microsystems, Inc., 2006.

The following books from other sources might also be useful:

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. Volume 1, ISBN 1-55512-259-0; Volume 2, ISBN 1-55512-260-4; Volume 3, ISBN 1-55512-261-2.

Documentation, Support, and Training

The Sun web site provides information about the following additional resources:

Typographic Conventions

The following table describes the typographic conventions that are used in this book.

Table P–1 Typographic Conventions


Typeface	Meaning	Example
`AaBbCc123`	The names of commands, files, and directories, and onscreen computer output	Edit your `.login` file. Use `ls -a` to list all files. `machine_name% you have mail.`
`AaBbCc123`	What you type, contrasted with onscreen computer output	`machine_name%` `su` `Password:`
`aabbcc123`	Placeholder: replace with a real name or value	The command to remove a file is `rm` `filename`.
AaBbCc123	Book titles, new terms, and terms to be emphasized	Read Chapter 6 in the User's Guide. A cache is a copy that is stored locally. Do not save the file. Note: Some emphasized items appear bold online.

Shell Prompts in Command Examples

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

Table P–2 Shell Prompts


Shell	Prompt
C shell	`machine_name%`
C shell for superuser	`machine_name#`
Bourne shell and Korn shell	`$`
Bourne shell and Korn shell for superuser	`#`