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

Linux Device Drivers, 3rd Edition
A Note Regarding Supplemental Files
Preface
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. An Introduction to Device Drivers
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. Building and Running Modules
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. Char Drivers
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. Debugging Techniques
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. Concurrency and Race Conditions
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. Advanced Char Driver Operations
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. Time, Delays, and Deferred Work
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. Allocating Memory
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. Communicating with Hardware
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. Interrupt Handling
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. Data Types in the Kernel
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. PCI Drivers
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. USB Drivers
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. The Linux Device Model
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. Memory Mapping and DMA
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. Block Drivers
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. Network Drivers
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. TTY Drivers
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. Bibliography
19.1. Books19.1.1. Linux Kernel19.1.2. Unix Design and Internals19.2. Web Sites
Index
About the Authors
Copyright

Content preview from Linux Device Drivers, 3rd Edition

Chapter 2. Building and Running Modules

It’s almost time to begin programming. This chapter introduces all the essential concepts about modules and kernel programming. In these few pages, we build and run a complete (if relatively useless) module, and look at some of the basic code shared by all modules. Developing such expertise is an essential foundation for any kind of modularized driver. To avoid throwing in too many concepts at once, this chapter talks only about modules, without referring to any specific device class.

All the kernel items (functions, variables, header files, and macros) that are introduced here are described in a reference section at the end of the chapter.

Setting Up Your Test System

Starting with this chapter, we present example modules to demonstrate programming concepts. (All of these examples are available on O’Reilly’s FTP site, as explained in Chapter 1.) Building, loading, and modifying these examples are a good way to improve your understanding of how drivers work and interact with the kernel.

The example modules should work with almost any 2.6.x kernel, including those provided by distribution vendors. However, we recommend that you obtain a “mainline” kernel directly from the kernel.org mirror network, and install it on your system. Vendor kernels can be heavily patched and divergent from the mainline; at times, vendor patches can change the kernel API as seen by device drivers. If you are writing a driver that must work on a particular distribution, ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Publisher Resources

ISBN: 0596005903Errata Page

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Linux Device Drivers, 3rd Edition

by Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman

Chapter 2. Building and Running Modules

Setting Up Your Test System

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.