PrefaceIt was thelate 1990s,and at IBM we were putting the Linuxkernel on a wristwatch.The target device was tiny,butthetaskwasturningouttobetough.TheMemoryTechnologyDevicessubsystemdidn'texist inthekernel,whichmeant that beforea filesystem could start lifeon the watch's flash memory,wehadto developthenecessary storagedriverfrom scratch.Interfacing thewatch'stouch screen with userapplicationswascomplicated because thekernel's input event driver interfacehadn't been conceived yet.GettingX Windows torun onthewatch'sLCDwasn'teasybecause it didn'tworkwell withframebufferdrivers.Of what useisawaterproof Linux wristwatch if you can't streamstock quotesfromyourbathtub?Bluetooth integration withLinux was several years away,and months were spent porting a proprietary Bluetooth stack to internet-enablethewatch.Powermanagementsupportwasgoodenoughonlytosqueezeafewhoursof juicefromthewatch'sbatteryhence we had work cut out on that front,too.Linux-Infrared was still unstable,so we hadto coax thestack before we could usean Infrared keyboard fordata entry.And wehad to compilethe compiler and cross-compileacompactapplication-setbecausetherewerenoaccepteddistributions intheconsumerelectronicsspace.Fast forward to the present: The baby penguin has grown into a healthy teenager. What took thousands of linesof code and ayear indevelopment back then can be accomplished in afew days withthe current kernels.But tobecomeaversatilekernel engineerwho can magically weavesolutions,you needto understand themyriadfeaturesandfacilitiesthatLinuxofferstodayAbouttheBookAmong the various subsystems residing in the kernel source tree, the drivers/ directory constitutes the singlelargest chunkand is several times bigger than theothers.With new and diversetechnologiesarriving in popularformfactors,thedevelopmentofnewdevicedriversinthekernelisacceleratingsteadily.Thelatestkernelssupportmorethan7odevicedriverfamilies.Thisbook isabout writing Linuxdevicedrivers.Itcoversthedesignand development of majordeviceclassessupported by the kernel, including those I missed during my Linux-on-Watch days. The discussion of each driverfamilystartsbylookingatthecorrespondingtechnology,movesontodevelopapracticalexample,andendsbylooking at relevantkernel sourcefiles.Beforeforaying into theworld of device drivers,however,thisbookintroducesyoutothekernelanddiscussestheimportantfeaturesof2.6Linux,emphasizingthoseportionsthatare of special interest to device driver writers.AudienceThis book is intended for the intermediate-level programmer eager to tweak the kernel to enable new devices.Youshouldhaveaworkingknowledgeof operatingsystemconcepts.Forexample,youshouldknowwhatasystem call is and why concurrency issues havetobe factored in while writingkernel code.The book assumesthatyouhavedownloaded Linuxonyoursystem,pokedthroughthekernelsources,andatleastskimmedthroughsomerelateddocumentation.AndyoushouldbeprettygoodinC.SummaryofChaptersThefirst4chaptersprepareyoutodigesttherestofthebook.Thenext16chaptersdiscussdriversfordifferentdevicefamilies.A chapter that describes devicedriver debugging techniques comes next.Thepenultimatechapterprovidesperspectiveonmaintenanceanddelivery.Weshutdown bywalkingthrougha checklistthatsummarizeshowtosetforthon yourwayto Linux-enablementwhenyougethold ofanewdevice.Chapter 1, "Introduction," starts our tryst with Linux. It hurries you through downloading the kernel sources,making trivial codechanges,and building a bootablekernel image
Preface It was the late 1990s, and at IBM we were putting the Linux kernel on a wristwatch. The target device was tiny, but the task was turning out to be tough. The Memory Technology Devices subsystem didn't exist in the kernel, which meant that before a filesystem could start life on the watch's flash memory, we had to develop the necessary storage driver from scratch. Interfacing the watch's touch screen with user applications was complicated because the kernel's input event driver interface hadn't been conceived yet. Getting X Windows to run on the watch's LCD wasn't easy because it didn't work well with frame buffer drivers. Of what use is a waterproof Linux wristwatch if you can't stream stock quotes from your bathtub? Bluetooth integration with Linux was several years away, and months were spent porting a proprietary Bluetooth stack to Internet-enable the watch. Power management support was good enough only to squeeze a few hours of juice from the watch's battery; hence we had work cut out on that front, too. Linux-Infrared was still unstable, so we had to coax the stack before we could use an Infrared keyboard for data entry. And we had to compile the compiler and crosscompile a compact application-set because there were no accepted distributions in the consumer electronics space. Fast forward to the present: The baby penguin has grown into a healthy teenager. What took thousands of lines of code and a year in development back then can be accomplished in a few days with the current kernels. But to become a versatile kernel engineer who can magically weave solutions, you need to understand the myriad features and facilities that Linux offers today. About the Book Among the various subsystems residing in the kernel source tree, the drivers/ directory constitutes the single largest chunk and is several times bigger than the others. With new and diverse technologies arriving in popular form factors, the development of new device drivers in the kernel is accelerating steadily. The latest kernels support more than 70 device driver families. This book is about writing Linux device drivers. It covers the design and development of major device classes supported by the kernel, including those I missed during my Linux-on-Watch days. The discussion of each driver family starts by looking at the corresponding technology, moves on to develop a practical example, and ends by looking at relevant kernel source files. Before foraying into the world of device drivers, however, this book introduces you to the kernel and discusses the important features of 2.6 Linux, emphasizing those portions that are of special interest to device driver writers. Audience This book is intended for the intermediate-level programmer eager to tweak the kernel to enable new devices. You should have a working knowledge of operating system concepts. For example, you should know what a system call is and why concurrency issues have to be factored in while writing kernel code. The book assumes that you have downloaded Linux on your system, poked through the kernel sources, and at least skimmed through some related documentation. And you should be pretty good in C. Summary of Chapters The first 4 chapters prepare you to digest the rest of the book. The next 16 chapters discuss drivers for different device families. A chapter that describes device driver debugging techniques comes next. The penultimate chapter provides perspective on maintenance and delivery. We shut down by walking through a checklist that summarizes how to set forth on your way to Linux-enablement when you get hold of a new device. Chapter 1, "Introduction," starts our tryst with Linux. It hurries you through downloading the kernel sources, making trivial code changes, and building a bootable kernel image
Chapter 2,"A Peek Inside the Kernel," takes a brisk look into the innards of the Linux kernel and teaches yousomemust-knowkernelconcepts.Itfirsttakesyouthroughthebootprocessandthendescribeskernelservicesparticularlyrelevanttodriverdevelopment,suchaskerneltimers,concurrencymanagement,and memoryallocation.Chapter 3,"Kernel Facilities,"examines severalkernel servicesthat areuseful components in thetoolbox ofdriverdevelopers.Thechapterstartsbylookingatkernelthreads,whichisawaytoimplementbackgroundtasks insidethekernel.Itthen moves ontohelper interfacessuchas linked lists,workqueues,completionfunctions,andnotifier chains.Thesehelperfacilities simplifyyourcode,weed out redundanciesfromthekernel,andhelplong-termmaintenanceChapter 4,"Laying the Groundwork,"builds thefoundation formastering the art of writing Linuxdevicedrivers.It introduces devicesand driversbygivingyoua bird's-eyeviewofthearchitectureof atypical PC-compatiblesystemandanembedded device.Itthenlooksat basicdriverconceptssuchas interrupthandlingandthekernel'sdevicemodel.Chapter 5,"Character Drivers,"looks at the architecture of character device drivers. Several conceptsintroduced inthis chapter,suchaspolling,asynchronousnotification,andI/ocontrol,arerelevanttosubsequent chapters,too,becausemanydevice classesdiscussedin therest ofthebook are"super"characterdevices.Chapter 6,"Serial Drivers,"explains thekernel layer that handles serial devices.Chapter7,"InputDrivers,"discussesthekernel'sinputsubsystemthatisresponsibleforservicingdevicessuchaskeyboards,mice,andtouch-screencontrollers.Chapter8,"TheInter-IntegratedCircuitProtocol,"dissectsdriversfordevicessuchasEEPROMsthatareconnected to a system's I2C bus or SMBus. This chapter also looks at other serial interfaces such as SPI bus and1-wire bus.Chapter 9,"PCMCIA and Compact Flash, delves into the PCMCIA subsystem. It teaches you to write drivers fordevices having a PCMCIA or Compact Flash form factor.Chapter 1o, "Peripheral Component Interconnect," looks at kernel support for PCI and its derivatives.Chapter11,"Universal Serial Bus,"explores USB architecture and explains how you can use the services of theLinux-USBsubsystemtowritedriversforUSBdevices.Chapter12,"VideoDrivers,"examinestheLinux-Videosubsystem.Itfindsouttheadvantagesofferedbytheframebuffer abstraction and teaches youto write frame buffer drivers.Chapter13,"AudioDrivers,"describestheLinux-Audioframeworkandexplainshowtoimplementaudiodrivers.Chapter 14, "Block Drivers,"focuses on drivers for storage devices such as hard disks. In this chapter, you alsolearnaboutthedifferentI/OschedulerssupportedbytheLinux-Blocksubsystem.Chapter 15, "Network Interface Cards," is devoted to network device drivers.You learn about kernel networkingdata structures and how to interface network drivers with protocol layers.Chapter 16,"Linux Without Wires," looks at driving different wireless technologies such as Bluetooth, Infrared,WiFi, and cellular communication.Chapter 17,"Memory TechnologyDevices,"discusses flash memory enablement on embedded devices.ThechapterendsbyexaminingdriversfortheFirmwareHubfoundonPCsystems.Chapter 18, "Embedding Linux," steps into the world of embedded Linux. It takes you through the mainfirmwarecomponentsofanembeddedsolutionsuchasbootloader,kernel,anddevicedrivers.Giventhesoaringpopularityof Linuxintheembedded space,it's morelikelythatyouwill usethedevicedriverskillsthatyou
Chapter 2, "A Peek Inside the Kernel," takes a brisk look into the innards of the Linux kernel and teaches you some must-know kernel concepts. It first takes you through the boot process and then describes kernel services particularly relevant to driver development, such as kernel timers, concurrency management, and memory allocation. Chapter 3, "Kernel Facilities," examines several kernel services that are useful components in the toolbox of driver developers. The chapter starts by looking at kernel threads, which is a way to implement background tasks inside the kernel. It then moves on to helper interfaces such as linked lists, work queues, completion functions, and notifier chains. These helper facilities simplify your code, weed out redundancies from the kernel, and help long-term maintenance. Chapter 4, "Laying the Groundwork," builds the foundation for mastering the art of writing Linux device drivers. It introduces devices and drivers by giving you a bird's-eye view of the architecture of a typical PC-compatible system and an embedded device. It then looks at basic driver concepts such as interrupt handling and the kernel's device model. Chapter 5, "Character Drivers," looks at the architecture of character device drivers. Several concepts introduced in this chapter, such as polling, asynchronous notification, and I/O control, are relevant to subsequent chapters, too, because many device classes discussed in the rest of the book are "super" character devices. Chapter 6, "Serial Drivers," explains the kernel layer that handles serial devices. Chapter 7, "Input Drivers," discusses the kernel's input subsystem that is responsible for servicing devices such as keyboards, mice, and touch-screen controllers. Chapter 8, "The Inter-Integrated Circuit Protocol," dissects drivers for devices such as EEPROMs that are connected to a system's I2C bus or SMBus. This chapter also looks at other serial interfaces such as SPI bus and 1-wire bus. Chapter 9, "PCMCIA and Compact Flash," delves into the PCMCIA subsystem. It teaches you to write drivers for devices having a PCMCIA or Compact Flash form factor. Chapter 10, "Peripheral Component Interconnect," looks at kernel support for PCI and its derivatives. Chapter 11, "Universal Serial Bus," explores USB architecture and explains how you can use the services of the Linux-USB subsystem to write drivers for USB devices. Chapter 12, "Video Drivers," examines the Linux-Video subsystem. It finds out the advantages offered by the frame buffer abstraction and teaches you to write frame buffer drivers. Chapter 13, "Audio Drivers," describes the Linux-Audio framework and explains how to implement audio drivers. Chapter 14, "Block Drivers," focuses on drivers for storage devices such as hard disks. In this chapter, you also learn about the different I/O schedulers supported by the Linux-Block subsystem. Chapter 15, "Network Interface Cards," is devoted to network device drivers. You learn about kernel networking data structures and how to interface network drivers with protocol layers. Chapter 16, "Linux Without Wires," looks at driving different wireless technologies such as Bluetooth, Infrared, WiFi, and cellular communication. Chapter 17, "Memory Technology Devices," discusses flash memory enablement on embedded devices. The chapter ends by examining drivers for the Firmware Hub found on PC systems. Chapter 18, "Embedding Linux," steps into the world of embedded Linux. It takes you through the main firmware components of an embedded solution such as bootloader, kernel, and device drivers. Given the soaring popularity of Linux in the embedded space, it's more likely that you will use the device driver skills that you
acquirefromthisbooktoenableembeddedsystems.Chapter19,"Drivers inUserSpace,"looksatdrivingdifferenttypesofdevicesfromuserspace.Somedevicedrivers, especially ones that are heavy on policy and light on performance requirements, are better off residingin userland.This chapteralso explains how the Linux process scheduler affects the response times of usermodedrivers.Chapter2o,"MoreDevicesandDrivers,"takesatourofapotpourriofdriverfamiliesnotcoveredthusfar,suchasErrorDetectionAndCorrection(EDAC),FireWire,andACPI.Chapter 21, "Debugging Device Drivers," teaches about different types of debuggers that you can use to debugkernel code.In this chapter,you also learn to use trace tools, kernel probes, crash-dump,and profilers.Whenyou develop a driver, be armed with the driver debugging skills that you learn in this chapter.Chapter22,"MaintenanceandDelivery,"providesperspectiveonthesoftwaredevelopment lifecycle.Chapter 23,"Shutting Down,"takesyouthrough a checklistofwork items when you embark on Linux-enablinganewdevice.ThebookendsbyponderingWhat next?Devicedrivers sometimesneedtoimplementcodesnippetsinassembly,soAppendixA,"LinuxAssembly,takes a look at thedifferent facets of assemblyprogramming on Linux.Some devicedrivers on x86-basedsystems depend directly or indirectly on the Bios, so Appendix B, "Linux and the BIos," teaches you how LinuxinteractswiththeBIoS.AppendixC,"SeqFiles,"describessegfiles,akernelhelperinterfaceintroducedinthe2.6kernel that device drivers canusetomonitorand trenddata points.Thebookisgenerallyorganizedaccordingtodeviceandbuscomplexity,coupled withpractical reasonsofdependencies between chapters.So,we start off withbasic deviceclasses suchas character,serial,and input.Next,welookatsimpleserialbusessuchasI2CandSMBus.ExternalI/ObusessuchasPCMCIA,PCI,andUSBfollow.Video,audio,block,andnetworkdevicesusuallyinterfacewiththeprocessorviatheseI/obuses,sowelookatthemsoonafter.Thenextportionsof thebook areorientedtoward embeddedLinuxand covertechnologiessuchaswirelessnetworkingandflashmemory.User-spacedriversarediscussedtowardtheendofthe book.Kernel VersionThisbook isgenerallyuptodateas of the2.6.23/2.6.24kernel versions.Most codelistings inthisbookhavebeen tested on a 2.6.23kernel.If youare using a later version, look at Linux websites such as lwn.net to learnabout the kernel changes since 2.6.23/24.BookWebsiteI've set up a website at elinuxdd.com to provide updates, errata, and other information related to this book.Conventions UsedSourcecode, function names,and shell commandsarewritten1ike this.Theshell promptused isbash>.Filename are written in italics, like this.Italics are also used to introduce new terms.Some chaptersmodifyoriginalkernel sourcefileswhile implementing codeexamples.To clearlypoint out thechanges, newly inserted code lines are prefixed with +, and any deleted code lines with -Sometimes,forsimplicity,thebookusesgenericreferences.Soifthetextpointsyoutothearch/your-arch/directory,it should betranslated,for example,to arch/x86/if youarecompiling thekernel forthex86architecture.Similarly,anymentionoftheinclude/asm-your-arch/directoryshouldbereadasinclude/asmarm/if youare,forinstance,buildingthekernel fortheARMarchitecture.The*symbol andXareoccasionallyusedaswildcardcharactersinfilenames.So,ifachapterasksyoutolookatinclude/linux/time*.h,lookatthe
acquire from this book to enable embedded systems. Chapter 19, "Drivers in User Space," looks at driving different types of devices from user space. Some device drivers, especially ones that are heavy on policy and light on performance requirements, are better off residing in user land. This chapter also explains how the Linux process scheduler affects the response times of user mode drivers. Chapter 20, "More Devices and Drivers," takes a tour of a potpourri of driver families not covered thus far, such as Error Detection And Correction (EDAC), FireWire, and ACPI. Chapter 21, "Debugging Device Drivers," teaches about different types of debuggers that you can use to debug kernel code. In this chapter, you also learn to use trace tools, kernel probes, crash-dump, and profilers. When you develop a driver, be armed with the driver debugging skills that you learn in this chapter. Chapter 22, "Maintenance and Delivery," provides perspective on the software development life cycle. Chapter 23, "Shutting Down," takes you through a checklist of work items when you embark on Linux-enabling a new device. The book ends by pondering What next? Device drivers sometimes need to implement code snippets in assembly, so Appendix A, "Linux Assembly," takes a look at the different facets of assembly programming on Linux. Some device drivers on x86-based systems depend directly or indirectly on the BIOS, so Appendix B, "Linux and the BIOS," teaches you how Linux interacts with the BIOS. Appendix C, "Seq Files," describes seq files, a kernel helper interface introduced in the 2.6 kernel that device drivers can use to monitor and trend data points. The book is generally organized according to device and bus complexity, coupled with practical reasons of dependencies between chapters. So, we start off with basic device classes such as character, serial, and input. Next, we look at simple serial buses such as I2C and SMBus. External I/O buses such as PCMCIA, PCI, and USB follow. Video, audio, block, and network devices usually interface with the processor via these I/O buses, so we look at them soon after. The next portions of the book are oriented toward embedded Linux and cover technologies such as wireless networking and flash memory. User-space drivers are discussed toward the end of the book. Kernel Version This book is generally up to date as of the 2.6.23/2.6.24 kernel versions. Most code listings in this book have been tested on a 2.6.23 kernel. If you are using a later version, look at Linux websites such as lwn.net to learn about the kernel changes since 2.6.23/24. Book Website I've set up a website at elinuxdd.com to provide updates, errata, and other information related to this book. Conventions Used Source code, function names, and shell commands are written like this. The shell prompt used is bash>. Filename are written in italics, like this. Italics are also used to introduce new terms. Some chapters modify original kernel source files while implementing code examples. To clearly point out the changes, newly inserted code lines are prefixed with +, and any deleted code lines with -. Sometimes, for simplicity, the book uses generic references. So if the text points you to the arch/your-arch/ directory, it should be translated, for example, to arch/x86/ if you are compiling the kernel for the x86 architecture. Similarly, any mention of the include/asm-your-arch/ directory should be read as include/asmarm/ if you are, for instance, building the kernel for the ARM architecture. The * symbol and X are occasionally used as wildcard characters in filenames. So, if a chapter asks you to look at include/linux/time*.h, look at the
header files, time.h, timer.h, times.h,and timex.h residing in the include/linux/ directory. If a section talksabout/dev/input/eventXor/sys/devices/platform/i8042/seriox/,Xistheinterfacenumberthatthekernelassigns toyourdevice in thecontext ofyoursystem configuration.Thesymbol is sometimes inserted between command orkernel output to attach explanations.Simple regular expressions are occasionally used to compactly list function prototypes. For example, the section"DirectMemoryAccess"inChapter1o,"PeripheralComponentInterconnect,"referstopci_[map/unmapldma_sync)_single()insteadofexplicitly citingpci_map_single(),pci_umap_single(),andpci_dma_sync_single().Several chapters refer you to user-space configuration files. For example, the section that describes the bootprocessopens/etc/rc.sysinit,andthechapterthat discussesBluetoothrefersto/etc/bluetooth/pin.The exactnames and locations of suchfilesmight,however,vary according to the Linuxdistribution youuse.一
header files, time.h, timer.h, times.h, and timex.h residing in the include/linux/ directory. If a section talks about /dev/input/eventX or /sys/devices/platform/i8042/serioX/, X is the interface number that the kernel assigns to your device in the context of your system configuration. The symbol is sometimes inserted between command or kernel output to attach explanations. Simple regular expressions are occasionally used to compactly list function prototypes. For example, the section "Direct Memory Access" in Chapter 10, "Peripheral Component Interconnect," refers to pci_[map|unmap|dma_sync]_single() instead of explicitly citing pci_map_single(), pci_umap_single(), and pci_dma_sync_single(). Several chapters refer you to user-space configuration files. For example, the section that describes the boot process opens /etc/rc.sysinit, and the chapter that discusses Bluetooth refers to /etc/bluetooth/pin. The exact names and locations of such files might, however, vary according to the Linux distribution you use
AcknowledgmentsFirst, I raise my hat to my editors at Prentice Hall: Debra Williams Cauley, Anne Goebel, and Keith Cline.Without their supporting work, this book would not have materialized. I thank Mark Taub for his interest in thisprojectand forinitiating it.Several sourceshavecontributedtomylearning inthepastdecade:themanyteammateswithwhomIworkedon Linux projects, the mighty kernel sources, mailing lists, and the Internet. All these have played a part inhelping me writethis book.Martin Streicher of Linux Magazine changed me from a full-time coder to a spare-time writer when he offeredmethemagazine's"Gearheads"kernel column.I gratefully acknowledgethemany lessons intechnical writingthat I've learned from himI owe a special debt of gratitude to my technical reviewers. Vamsi Krishna patiently read through each chapterofthemanuscript.Hisnumeroussuggestionshavemadethisabetterbook.JimLiebprovidedvaluablefeedbackonseveralchapters.ArnoldRobbinsreviewedthefirstfewchaptersandprovided insightful comments.Finally, I thank my parents and my wife for their love and support. And thanks to my baby daughter forconstantlyremindingmeto spend cyclesonthebookbyherwobblywalkthatbearsanuncannyresemblancetothat ofapenguin.VA
Acknowledgments First, I raise my hat to my editors at Prentice Hall: Debra Williams Cauley, Anne Goebel, and Keith Cline. Without their supporting work, this book would not have materialized. I thank Mark Taub for his interest in this project and for initiating it. Several sources have contributed to my learning in the past decade: the many teammates with whom I worked on Linux projects, the mighty kernel sources, mailing lists, and the Internet. All these have played a part in helping me write this book. Martin Streicher of Linux Magazine changed me from a full-time coder to a spare-time writer when he offered me the magazine's "Gearheads" kernel column. I gratefully acknowledge the many lessons in technical writing that I've learned from him. I owe a special debt of gratitude to my technical reviewers. Vamsi Krishna patiently read through each chapter of the manuscript. His numerous suggestions have made this a better book. Jim Lieb provided valuable feedback on several chapters. Arnold Robbins reviewed the first few chapters and provided insightful comments. Finally, I thank my parents and my wife for their love and support. And thanks to my baby daughter for constantly reminding me to spend cycles on the book by her wobbly walk that bears an uncanny resemblance to that of a penguin