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 re-entrant device driver applicable to all architectures that conform to the Solaris 9^TM 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 on device drivers.

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.

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 and Events describes the set of interfaces used to read an update device node properties. It also contains information on events and name-value pairs.
Chapter 5, Driver 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 and Kernel Memory describes the set of interfaces that enable 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 enable 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, Drivers for Network Devices describes the Generic LAN driver (GLD), which is used for Solaris network drivers. GLD uses STREAMS technology, along with the Data Link Provider Interface (DLPI) for communicating with network protocol stacks.
Chapter 17, Compiling, Loading, Packaging, and Testing Drivers provides information on compiling and linking a driver, and for installing it in the system.
Chapter 18, Debugging gives hints, a simple mdb/kadb tutorial, and some hints on testing the driver.
Chapter 19, Recommended Coding Practices describes the recommended coding practices for writing drivers.
Appendix A, Hardware Overview discusses multi-platform hardware issues related to device drivers.
Appendix B, Summary of Solaris 9 DDI/DKI Services summarizes, by topic, the kernel functions that 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.

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 and other driver-related issues, the following books might be helpful.

From Sun Microsystems:

Application Packaging Developer's Guide, Sun Microsystems, 2000.
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.

From other sources:

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

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, Pentium III Xeon, and Pentium 4 processors, and compatible microprocessor chips made by AMD and Cyrix.

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.

Typographic Conventions

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	`#`