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 7 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, SunOS Kernel and Device Tree,provides an overview of the SunOS^TM kernel and the manner in which it represents devices as nodes in a device tree.
Chapter 2, Hardware Overview discusses multiplatform hardware issues related to device drivers.
Chapter 3, Overview of SunOS 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 4, Multithreading describes the mechanisms of the SunOS multithreaded kernel that are of interest to driver writers.
Chapter 5, Autoconfiguration details the support a driver must provide for autoconfiguration.
Chapter 6, Interrupt Handlers describes the interrupt handling mechanisms. These include registering, servicing, and removing interrupts.
Chapter 7, DMA describes direct memory access (DMA) and the DMA interfaces.
Chapter 8, Power Management covers the interfaces for Power Management^TM, a framework designed to regulate and reduce the power consumed by computer systems and devices.
Chapter 9, Drivers for Character Devices describes the structure and functions of a driver for a character-oriented device.
Chapter 10, Drivers for Block Devices describes the structure and functions of a driver for a block-oriented device.
Chapter 11, 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 12, Device Context Management describes the set of interfaces that allow device drivers to manage user access to devices.
Chapter 13, SCSI Target Drivers outlines the Sun Common SCSI Architecture and describes the additional requirements of SCSI target drivers.
Chapter 14, SCSI Host Bus Adapter Drivers explains how to write a SCSI Host Bus Adapter (HBA) driver using the Sun Common SCSI Architecture (SCSA).
Chapter 15, Loading and Unloading Drivers provides information on compiling and linking a driver, and for installing it in the system.
Chapter 16, Debugging gives coding suggestions, debugging hints, a simple adb/kadb tutorial, and some hints on testing the driver.
Appendix A, Converting a SunOS 4.1 Device Driver to SunOS 5.7 gives hints on converting SunOS 4.1 drivers to SunOS 5.7.
Appendix B, Interface Transition List presents a list of DDI/DKI data access interface functions that have changed from Solaris 2.6 to Solaris 7. It also presents data access functions new to Solaris 7.
Appendix C, Summary of Solaris 7 DDI/DKI Services summarizes, by topic, the kernel functions device driver can use.
Appendix D, Sample Driver Source Code displays a list of sample drivers, and the location of the sample code in the DDK.
Appendix E, Driver Code Layout Structure presents header files and an outline of xx.c source code samples for a typical driver.
Appendix F, Making a Device Driver 64-Bit Ready provides guidelines for updating a device driver to run in a 64-bit environment.
Appendix G, Advanced Topics presents a collection of optional topics.

Related Books

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 may be helpful.

Writing PCMCIA Device Drivers, SunSoft, 1997.
Application Packaging Guide, SunSoft, 1996.
Streams Programming Guide, SunSoft, 1996.
Multithreading Programming Guide, SunSoft 1996.
SPARC Architecture Manual, Version 9, Sun Microsystems Computer Company, 1996.
80386 Programmer's Reference Manual, Intel Corporation, 1986. ISBN 1-55512-022-9.
i486 Microprocessor Hardware Reference Manual, Intel Corporation, 1990. ISBN 1-55512-112-8.
Pentium Processor User's Manual - Volume 3: Architecture and Programming Manual, Intel Corporation, 1993. ISBN 1-55512-195-0.
Open Boot PROM Toolkit User's Guide, Sun Microsystems Computer Company, 1996.
Dynamic Reconfiguration AnswerBook
PCI Special Internet Group Web Site: http://www.pcisig.com/contents.html
Advanced Configuration and Power Interface (ACPI) Web Site: http://www.teleport.com/~acpi

Ordering Sun Documents

The SunDocs^SM program provides more than 250 manuals from Sun Microsystems, Inc. If you live in the United States, Canada, Europe, or Japan, you can purchase documentation sets or individual manuals using this program.

For a list of documents and how to order them, see the catalog section of the SunExpress^TM Internet site at http://www.sun.com/sunexpress.

What Typographic Changes Mean

Table P-1 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	`di_add_intr()` registers a device interrupt with the system. `add_drv` adds a driver to the system.
`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	number is the number of the interrupt to register.
AaBbCc123	Book titles, new words or terms, or words to be emphasized	Read Chapter 6 in Writing Device Drivers. A mutual exclusion lock is....

Note -

The term "x86" refers to the Intel 8086 family of microprocessor chips, including the Pentium and Pentium Pro processors and compatible microprocessor chips made by AMD and Cyrix. In this document the term "x86" refers to the overall platform architecture, whereas "Intel Platform Edition" appears in the product name of x86 products.