book

Linux Device Drivers, 3rd Edition

by Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman

February 2005

Beginner to intermediate

636 pages

22h 51m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Jon’s IntroductionAlessandro’s IntroductionGreg’s IntroductionAudience for This BookOrganization of the MaterialBackground InformationOnline Version and LicenseConventions Used in This BookUsing Code ExamplesWe’d Like to Hear from YouSafari EnabledAcknowledgmentsJonAlessandroGreg
1.1. The Role of the Device Driver1.2. Splitting the Kernel1.2.1. Loadable Modules1.3. Classes of Devices and Modules1.4. Security Issues1.5. Version Numbering1.6. License Terms1.7. Joining the Kernel Development Community1.8. Overview of the Book
2.1. Setting Up Your Test System2.2. The Hello World Module2.3. Kernel Modules Versus Applications2.3.1. User Space and Kernel Space2.3.2. Concurrency in the Kernel2.3.3. The Current Process2.3.4. A Few Other Details2.4. Compiling and Loading2.4.1. Compiling Modules2.4.2. Loading and Unloading Modules2.4.3. Version Dependency2.4.4. Platform Dependency2.5. The Kernel Symbol Table2.6. Preliminaries2.7. Initialization and Shutdown2.7.1. The Cleanup Function2.7.2. Error Handling During Initialization2.7.3. Module-Loading Races2.8. Module Parameters2.9. Doing It in User Space2.10. Quick Reference
3.1. The Design of scull3.2. Major and Minor Numbers3.2.1. The Internal Representation of Device Numbers3.2.2. Allocating and Freeing Device Numbers3.2.3. Dynamic Allocation of Major Numbers3.3. Some Important Data Structures3.3.1. File Operations3.3.2. The file Structure3.3.3. The inode Structure3.4. Char Device Registration3.4.1. Device Registration in scull3.4.2. The Older Way3.5. open and release3.5.1. The open Method3.5.2. The release Method3.6. scull’s Memory Usage3.7. read and write3.7.1. The read Method3.7.2. The write Method3.7.3. readv and writev3.8. Playing with the New Devices3.9. Quick Reference
4.1. Debugging Support in the Kernel4.2. Debugging by Printing4.2.1. printk4.2.2. Redirecting Console Messages4.2.3. How Messages Get Logged4.2.4. Turning the Messages On and Off4.2.5. Rate Limiting4.2.6. Printing Device Numbers4.3. Debugging by Querying4.3.1. Using the /proc Filesystem4.3.1.1. Implementing files in /proc4.3.1.2. An older interface4.3.1.3. Creating your /proc file4.3.1.4. The seq_file interface4.3.2. The ioctl Method4.4. Debugging by Watching4.5. Debugging System Faults4.5.1. Oops Messages4.5.2. System Hangs4.6. Debuggers and Related Tools4.6.1. Using gdb4.6.2. The kdb Kernel Debugger4.6.3. The kgdb Patches4.6.4. The User-Mode Linux Port4.6.5. The Linux Trace Toolkit4.6.6. Dynamic Probes
5.1. Pitfalls in scull5.2. Concurrency and Its Management5.3. Semaphores and Mutexes5.3.1. The Linux Semaphore Implementation5.3.2. Using Semaphores in scull5.3.3. Reader/Writer Semaphores5.4. Completions5.5. Spinlocks5.5.1. Introduction to the Spinlock API5.5.2. Spinlocks and Atomic Context5.5.3. The Spinlock Functions5.5.4. Reader/Writer Spinlocks5.6. Locking Traps5.6.1. Ambiguous Rules5.6.2. Lock Ordering Rules5.6.3. Fine- Versus Coarse-Grained Locking5.7. Alternatives to Locking5.7.1. Lock-Free Algorithms5.7.2. Atomic Variables5.7.3. Bit Operations5.7.4. seqlocks5.7.5. Read-Copy-Update5.8. Quick Reference
6.1. ioctl6.1.1. Choosing the ioctl Commands6.1.2. The Return Value6.1.3. The Predefined Commands6.1.4. Using the ioctl Argument6.1.5. Capabilities and Restricted Operations6.1.6. The Implementation of the ioctl Commands6.1.7. Device Control Without ioctl6.2. Blocking I/O6.2.1. Introduction to Sleeping6.2.2. Simple Sleeping6.2.3. Blocking and Nonblocking Operations6.2.4. A Blocking I/O Example6.2.5. Advanced Sleeping6.2.5.1. How a process sleeps6.2.5.2. Manual sleeps6.2.5.3. Exclusive waits6.2.5.4. The details of waking up6.2.5.5. Ancient history: sleep_on6.2.6. Testing the Scullpipe Driver6.3. poll and select6.3.1. Interaction with read and write6.3.1.1. Reading data from the device6.3.1.2. Writing to the device6.3.1.3. Flushing pending output6.3.2. The Underlying Data Structure6.4. Asynchronous Notification6.4.1. The Driver’s Point of View6.5. Seeking a Device6.5.1. The llseek Implementation6.6. Access Control on a Device File6.6.1. Single-Open Devices6.6.2. Restricting Access to a Single User at a Time6.6.3. Blocking open as an Alternative to EBUSY6.6.4. Cloning the Device on open6.7. Quick Reference
7.1. Measuring Time Lapses7.1.1. Using the jiffies Counter7.1.2. Processor-Specific Registers7.2. Knowing the Current Time7.3. Delaying Execution7.3.1. Long Delays7.3.1.1. Busy waiting7.3.1.2. Yielding the processor7.3.1.3. Timeouts7.3.2. Short Delays7.4. Kernel Timers7.4.1. The Timer API7.4.2. The Implementation of Kernel Timers7.5. Tasklets7.6. Workqueues7.6.1. The Shared Queue7.7. Quick Reference7.7.1. Timekeeping7.7.2. Delays7.7.3. Kernel Timers7.7.4. Tasklets7.7.5. Workqueues

8.1. The Real Story of kmalloc8.1.1. The Flags Argument8.1.1.1. Memory zones8.1.2. The Size Argument8.2. Lookaside Caches8.2.1. A scull Based on the Slab Caches: scullc8.2.2. Memory Pools8.3. get_free_page and Friends8.3.1. A scull Using Whole Pages: scullp8.3.2. The alloc_pages Interface8.4. vmalloc and Friends8.4.1. A scull Using Virtual Addresses: scullv8.5. Per-CPU Variables8.6. Obtaining Large Buffers8.6.1. Acquiring a Dedicated Buffer at Boot Time8.7. Quick Reference
9.1. I/O Ports and I/O Memory9.1.1. I/O Registers and Conventional Memory9.2. Using I/O Ports9.2.1. I/O Port Allocation9.2.2. Manipulating I/O ports9.2.3. I/O Port Access from User Space9.2.4. String Operations9.2.5. Pausing I/O9.2.6. Platform Dependencies9.3. An I/O Port Example9.3.1. An Overview of the Parallel Port9.3.2. A Sample Driver9.4. Using I/O Memory9.4.1. I/O Memory Allocation and Mapping9.4.2. Accessing I/O Memory9.4.3. Ports as I/O Memory9.4.4. Reusing short for I/O Memory9.4.5. ISA Memory Below 1 MB9.4.6. isa_readb and Friends9.5. Quick Reference
10.1. Preparing the Parallel Port10.2. Installing an Interrupt Handler10.2.1. The /proc Interface10.2.2. Autodetecting the IRQ Number10.2.2.1. Kernel-assisted probing10.2.2.2. Do-it-yourself probing10.2.3. Fast and Slow Handlers10.2.3.1. The internals of interrupt handling on the x8610.3. Implementing a Handler10.3.1. Handler Arguments and Return Value10.3.2. Enabling and Disabling Interrupts10.3.2.1. Disabling a single interrupt10.3.2.2. Disabling all interrupts10.4. Top and Bottom Halves10.4.1. Tasklets10.4.2. Workqueues10.5. Interrupt Sharing10.5.1. Installing a Shared Handler10.5.2. Running the Handler10.5.3. The /proc Interface and Shared Interrupts10.6. Interrupt-Driven I/O10.6.1. A Write-Buffering Example10.7. Quick Reference
11.1. Use of Standard C Types11.2. Assigning an Explicit Size to Data Items11.3. Interface-Specific Types11.4. Other Portability Issues11.4.1. Time Intervals11.4.2. Page Size11.4.3. Byte Order11.4.4. Data Alignment11.4.5. Pointers and Error Values11.5. Linked Lists11.6. Quick Reference
12.1. The PCI Interface12.1.1. PCI Addressing12.1.2. Boot Time12.1.3. Configuration Registers and Initialization12.1.4. MODULE_DEVICE_TABLE12.1.5. Registering a PCI Driver12.1.6. Old-Style PCI Probing12.1.7. Enabling the PCI Device12.1.8. Accessing the Configuration Space12.1.9. Accessing the I/O and Memory Spaces12.1.10. PCI Interrupts12.1.11. Hardware Abstractions12.2. A Look Back: ISA12.2.1. Hardware Resources12.2.2. ISA Programming12.2.3. The Plug-and-Play Specification12.3. PC/104 and PC/104+12.4. Other PC Buses12.4.1. MCA12.4.2. EISA12.4.3. VLB12.5. SBus12.6. NuBus12.7. External Buses12.8. Quick Reference
13.1. USB Device Basics13.1.1. Endpoints13.1.2. Interfaces13.1.3. Configurations13.2. USB and Sysfs13.3. USB Urbs13.3.1. struct urb13.3.2. Creating and Destroying Urbs13.3.2.1. Interrupt urbs13.3.2.2. Bulk urbs13.3.2.3. Control urbs13.3.2.4. Isochronous urbs13.3.3. Submitting Urbs13.3.4. Completing Urbs: The Completion Callback Handler13.3.5. Canceling Urbs13.4. Writing a USB Driver13.4.1. What Devices Does the Driver Support?13.4.2. Registering a USB Driver13.4.3. probe and disconnect in Detail13.4.4. Submitting and Controlling a Urb13.5. USB Transfers Without Urbs13.5.1. usb_bulk_msg13.5.2. usb_control_msg13.5.3. Other USB Data Functions13.6. Quick Reference
14.1. Kobjects, Ksets, and Subsystems14.1.1. Kobject Basics14.1.1.1. Embedding kobjects14.1.1.2. Kobject initialization14.1.1.3. Reference count manipulation14.1.1.4. Release functions and kobject types14.1.2. Kobject Hierarchies, Ksets, and Subsystems14.1.2.1. Ksets14.1.2.2. Operations on ksets14.1.2.3. Subsystems14.2. Low-Level Sysfs Operations14.2.1. Default Attributes14.2.2. Nondefault Attributes14.2.3. Binary Attributes14.2.4. Symbolic Links14.3. Hotplug Event Generation14.3.1. Hotplug Operations14.4. Buses, Devices, and Drivers14.4.1. Buses14.4.1.1. Bus registration14.4.1.2. Bus methods14.4.1.3. Iterating over devices and drivers14.4.1.4. Bus attributes14.4.2. Devices14.4.2.1. Device registration14.4.2.2. Device attributes14.4.2.3. Device structure embedding14.4.3. Device Drivers14.4.3.1. Driver structure embedding14.5. Classes14.5.1. The class_simple Interface14.5.2. The Full Class Interface14.5.2.1. Managing classes14.5.2.2. Class devices14.5.2.3. Class interfaces14.6. Putting It All Together14.6.1. Add a Device14.6.2. Remove a Device14.6.3. Add a Driver14.6.4. Remove a Driver14.7. Hotplug14.7.1. Dynamic Devices14.7.2. The /sbin/hotplug Utility14.7.2.1. IEEE1394 (FireWire)14.7.2.2. Networking14.7.2.3. PCI14.7.2.4. Input14.7.2.5. USB14.7.2.6. SCSI14.7.2.7. Laptop docking stations14.7.2.8. S/390 and zSeries14.7.3. Using /sbin/hotplug14.7.3.1. Linux hotplug scripts14.7.3.2. udev14.8. Dealing with Firmware14.8.1. The Kernel Firmware Interface14.8.2. How It Works14.9. Quick Reference14.9.1. Kobjects14.9.2. Sysfs Operations14.9.3. Buses, Devices, and Drivers14.9.4. Classes14.9.5. Firmware
15.1. Memory Management in Linux15.1.1. Address Types15.1.2. Physical Addresses and Pages15.1.3. High and Low Memory15.1.4. The Memory Map and Struct Page15.1.5. Page Tables15.1.6. Virtual Memory Areas15.1.6.1. The vm_area_struct structure15.1.7. The Process Memory Map15.2. The mmap Device Operation15.2.1. Using remap_pfn_range15.2.2. A Simple Implementation15.2.3. Adding VMA Operations15.2.4. Mapping Memory with nopage15.2.5. Remapping Specific I/O Regions15.2.6. Remapping RAM15.2.6.1. Remapping RAM with the nopage method15.2.7. Remapping Kernel Virtual Addresses15.3. Performing Direct I/O15.3.1. Asynchronous I/O15.3.1.1. An asynchronous I/O example15.4. Direct Memory Access15.4.1. Overview of a DMA Data Transfer15.4.2. Allocating the DMA Buffer15.4.2.1. Do-it-yourself allocation15.4.3. Bus Addresses15.4.4. The Generic DMA Layer15.4.4.1. Dealing with difficult hardware15.4.4.2. DMA mappings15.4.4.3. Setting up coherent DMA mappings15.4.4.4. DMA pools15.4.4.5. Setting up streaming DMA mappings15.4.4.6. Single-page streaming mappings15.4.4.7. Scatter/gather mappings15.4.4.8. PCI double-address cycle mappings15.4.4.9. A simple PCI DMA example15.4.5. DMA for ISA Devices15.4.5.1. Registering DMA usage15.4.5.2. Talking to the DMA controller15.5. Quick Reference15.5.1. Introductory Material15.5.2. Implementing mmap15.5.3. Implementing Direct I/O15.5.4. Direct Memory Access
16.1. Registration16.1.1. Block Driver Registration16.1.2. Disk Registration16.1.2.1. Block device operations16.1.2.2. The gendisk structure16.1.3. Initialization in sbull16.1.4. A Note on Sector Sizes16.2. The Block Device Operations16.2.1. The open and release Methods16.2.2. Supporting Removable Media16.2.3. The ioctl Method16.3. Request Processing16.3.1. Introduction to the request Method16.3.2. A Simple request Method16.3.3. Request Queues16.3.3.1. Queue creation and deletion16.3.3.2. Queueing functions16.3.3.3. Queue control functions16.3.4. The Anatomy of a Request16.3.4.1. The bio structure16.3.4.2. Request structure fields16.3.4.3. Barrier requests16.3.4.4. Nonretryable requests16.3.5. Request Completion Functions16.3.5.1. Working with bios16.3.5.2. Block requests and DMA16.3.5.3. Doing without a request queue16.4. Some Other Details16.4.1. Command Pre-Preparation16.4.2. Tagged Command Queueing16.5. Quick Reference
17.1. How snull Is Designed17.1.1. Assigning IP Numbers17.1.2. The Physical Transport of Packets17.2. Connecting to the Kernel17.2.1. Device Registration17.2.2. Initializing Each Device17.2.3. Module Unloading17.3. The net_device Structure in Detail17.3.1. Global Information17.3.2. Hardware Information17.3.3. Interface Information17.3.4. The Device Methods17.3.5. Utility Fields17.4. Opening and Closing17.5. Packet Transmission17.5.1. Controlling Transmission Concurrency17.5.2. Transmission Timeouts17.5.3. Scatter/Gather I/O17.6. Packet Reception17.7. The Interrupt Handler17.8. Receive Interrupt Mitigation17.9. Changes in Link State17.10. The Socket Buffers17.10.1. The Important Fields17.10.2. Functions Acting on Socket Buffers17.11. MAC Address Resolution17.11.1. Using ARP with Ethernet17.11.2. Overriding ARP17.11.3. Non-Ethernet Headers17.12. Custom ioctl Commands17.13. Statistical Information17.14. Multicast17.14.1. Kernel Support for Multicasting17.14.2. A Typical Implementation17.15. A Few Other Details17.15.1. Media Independent Interface Support17.15.2. Ethtool Support17.15.3. Netpoll17.16. Quick Reference
18.1. A Small TTY Driver18.1.1. struct termios18.2. tty_driver Function Pointers18.2.1. open and close18.2.2. Flow of Data18.2.3. Other Buffering Functions18.2.4. No read Function?18.3. TTY Line Settings18.3.1. set_termios18.3.2. tiocmget and tiocmset18.4. ioctls18.5. proc and sysfs Handling of TTY Devices18.6. The tty_driver Structure in Detail18.7. The tty_operations Structure in Detail18.8. The tty_struct Structure in Detail18.9. Quick Reference
19.1. Books19.1.1. Linux Kernel19.1.2. Unix Design and Internals19.2. Web Sites

Content preview from Linux Device Drivers, 3rd Edition

Preface

This is, on the surface, a book about writing device drivers for the Linux system. That is a worthy goal, of course; the flow of new hardware products is not likely to slow down anytime soon, and somebody is going to have to make all those new gadgets work with Linux. But this book is also about how the Linux kernel works and how to adapt its workings to your needs or interests. Linux is an open system; with this book, we hope, it is more open and accessible to a larger community of developers.

This is the third edition of Linux Device Drivers. The kernel has changed greatly since this book was first published, and we have tried to evolve the text to match. This edition covers the 2.6.10 kernel as completely as we are able. We have, this time around, elected to omit the discussion of backward compatibility with previous kernel versions. The changes from 2.4 are simply too large, and the 2.4 interface remains well documented in the (freely available) second edition.

This edition contains quite a bit of new material relevant to the 2.6 kernel. The discussion of locking and concurrency has been expanded and moved into its own chapter. The Linux device model, which is new in 2.6, is covered in detail. There are new chapters on the USB bus and the serial driver subsystem; the chapter on PCI has also been enhanced. While the organization of the rest of the book resembles that of the earlier editions, every chapter has been thoroughly updated.

We hope you enjoy reading this book as ...