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 illumos^TM Operating System (illumos). This book discusses how to develop multithreaded reentrant device drivers for all architectures that conform to the illumos 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 illumos drivers; power management; driver autoconfiguration; programmed I/O; Direct Memory Access (DMA); device context management; compilation, installation, and testing drivers; debugging drivers; and porting illumos drivers to a 64-bit environment.

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

What's New

SX build 96: Rewrote the description of the sleep-flag flag on page 86.

SX build 88: Added the strnlen function to Utility Functions. Added the ddi_periodic_add and ddi_periodic_delete functions to Time-Related Functions.

Who Should Use This Book

This book is written for UNIX^TM 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.

The illumos operating system (illumos) runs on both SPARC and x86 architectures. illumos 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

• Overview of illumos Device Drivers provides an introduction to device drivers and associated entry points on the illumos platform. The entry points for each device driver type are presented in tables.

• illumos Kernel and Device Tree provides an overview of the illumos kernel with an explanation of how devices are represented as nodes in a device tree.

• Multithreading describes the aspects of the illumos multithreaded kernel that are relevant for device driver developers.

• Properties describes the set of interfaces for using device properties.

• 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.

• Driver Autoconfiguration explains the support that a driver must provide for autoconfiguration.

• Device Access: Programmed I/O describes the interfaces and methodologies for drivers to read or write to device memory.

• Interrupt Handlers describes the mechanisms for handling interrupts. These mechanisms include registering, servicing, and removing interrupts.

• Direct Memory Access (DMA) describes direct memory access (DMA) and the DMA interfaces.

• Mapping Device and Kernel Memory describes interfaces for managing device and kernel memory.

• Device Context Management describes the set of interfaces that enable device drivers to manage user access to devices.

• Power Management explains the interfaces for Power Management^TM, a framework for managing power consumption.

• Hardening illumos 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.

• Layered Driver Interface (LDI) describes the LDI, which enables kernel modules to access other devices in the system.

• Drivers for Character Devices describes drivers for character-oriented devices.

• Drivers for Block Devices describes drivers for a block-oriented devices.

• SCSI Target Drivers outlines the Sun Common SCSI Architecture (SCSA) and the requirements for SCSI target drivers.

• SCSI Host Bus Adapter Drivers explains how to apply SCSA to SCSI Host Bus Adapter (HBA) drivers.

• Drivers for Network Devices describes the Generic LAN driver (GLD), an illumos network driver that uses STREAMS technology and the Data Link Provider Interface (DLPI).

• USB Drivers describes how to write a client USB device driver using the USBA 2.0 framework.

• Compiling, Loading, Packaging, and Testing Drivers provides information on compiling, linking, and installing a driver.

• Debugging, Testing, and Tuning Device Drivers describes techniques for debugging, testing, and tuning drivers.

• Recommended Coding Practices describes the recommended coding practices for writing drivers.

• Hardware Overview discusses multi-platform hardware issues for device drivers.

• Summary of illumos DDI/DKI Services provides tables of kernel functions for device drivers. Deprecated functions are indicated as well.

• Making a Device Driver 64-Bit Ready provides guidelines for updating a device driver to run in a 64-bit environment.

• Console Frame Buffer Drivers describes how to add the necessary interfaces to a frame buffer driver to enable the driver to interact with the illumos 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.

• 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.

• Modular Debugger Guide. Sun Microsystems, Inc., 2008.

• Dynamic Tracing Guide. Sun Microsystems, Inc., 2007.

• DTrace User Guide. Sun Microsystems, Inc., 2006.

• 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.

Typographic Conventions

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

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.