Joseph Kong - FreeBSD Device Drivers: A Guide for the Intrepid

Copyright 2012

All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher.

No Starch Press and the No Starch Press logo are registered trademarks of No Starch Press, Inc. Other product and company names mentioned herein may be the trademarks of their respective owners. Rather than use a trademark symbol with every occurrence of a trademarked name, we are using the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.

The information in this book is distributed on an As Is basis, without warranty. While every precaution has been taken in the preparation of this work, neither the author nor No Starch Press, Inc. shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in it.

While most portions of an operating system are maintained and developed by individuals who specialize in a given operating system, device drivers are unique: Theyre maintained by a much broader spectrum of developers. Some device driver authors have extensive experience with a particular operating system, while others have detailed knowledge of specific hardware components and are tasked with maintaining device drivers for those components across multiple systems. Too, device drivers are often somewhat self-contained, so that a developer can maintain a device driver while viewing other parts of the system as a black box.

Of course, that black box still has an interface, and each operating system provides its own set of interfaces to device drivers. Device drivers on all systems need to perform many common tasks, such as discovering devices, allocating resources for connected devices, and managing asynchronous events. However, each operating system has its own ways of dealing with these tasks, and each differs in the interfaces it provides for higher-level tasks. The key to writing a device driver that is both robust and efficient lies in understanding the specific details of the interfaces that the particular operating system provides.

FreeBSD Device Drivers is an excellent guide to the most commonly used FreeBSD device driver interfaces. Youll find coverage of lower-level interfaces, including attaching to eligible devices and managing device resources, as well as higher-level interfaces, such as interfacing with the network and storage stacks. In addition, the books coverage of several of the APIs available in the kernel environment, such as allocating memory, timers, and synchronization primitives, will be useful to anyone working with the FreeBSD kernel. This book is a welcome resource for FreeBSD device driver authors.

John Baldwin

Kernel Developer, FreeBSD

New York

March 20, 2012

Acknowledgments

No book is an island. You would not be holding this book in your hands without the help and support of a host of people to whom I am most grateful.

Foremost, thanks to Bill Pollock and the gang at No Starch Press for giving me the opportunity to write this book and for helping me along the way. Special thanks to Alison Law, Riley Hoffman, and Tyler Ortman for pulling things together. Alison, you deserve to be mentioned at least twice, if not more. Thanks for entering corrections multiple times and for keeping me on schedule (sort of). Thanks, too, to copyeditors Damon Larson and Megan Dunchak and to Jessica Miller for writing the back cover copy.

I couldnt have done this without John Baldwins excellent technical review. He patiently answered all of my (inane) questions and helped to improve my code. To my brother, Justin Kong, thank you for reviewing this book multiple times. You definitely deserve the Iron Man award. Thanks to Aharon Robbins for his review and to my friend Elizabeth C. Mitchell for drawing my diagrams (and for baking me brownies). And thanks to George Neville-Neil and Michael W. Lucas for your advice.

Thanks, Dad, for lending me your expertise on hardware and for lending me actual hardware, which made it possible for me to write this book. Thanks, Mom, for your love and support. I know you pray for me every day. Thanks also go to my friends for their support.

And last but not least, thanks to the open source software and FreeBSD communities for your willingness to share. Without you, Id be a lousy programmer, and Id have nothing to write about.

Introduction

Welcome to FreeBSD Device Drivers ! The goal of this book is to help you improve your understanding of device drivers under FreeBSD. By the time you finish this book, you should be able to build, configure, and manage your own FreeBSD device drivers.

This book covers FreeBSD version 8, the version recommended for production use as of this writing. Nonetheless, most of what youll learn will apply to earlier versions and should apply to later ones as well.

Who Is This Book For?

I wrote this book as a programmer, for programmers. As such, youll find a heavy focus on programming, not theory, and youll examine real device drivers (namely, ones that control hardware). Imagine trying to write a book without ever having read one. Inconceivable! The same thing goes for device drivers.

Prerequisites

To get the most out of this book, you should be familiar with the C programming language. You should also know something about operating system design; for example, the difference between a process and a thread.

If you lack the necessary background, I recommend reading the following three books prior to this one, or just keeping them around as references:

• The C Programming Language , by Brian W. Kernighan and Dennis M. Ritchie (Prentice Hall PTR, 1988)

• Expert C Programming , by Peter van der Linden (Prentice Hall, 1994)

• The Design and Implementation of the FreeBSD Operating System , by Marshall Kirk McKusick and George V. Neville-Neil (Addison-Wesley Professional, 2005)

Contents at a Glance

FreeBSD Device Drivers contains the following chapters.

Provides an overview and introduction to basic device driver programming concepts and terminology.

Describes FreeBSDs kernel memory management routines.

Teaches you how to communicate with and control your device drivers from user space.

Discusses the problems and solutions associated with multithreaded programming and concurrent execution.

Describes delaying code execution and asynchronous code execution, and explains why these tasks are needed.

Contains the first of several occasions where I walk you through a real-world device driver.

Covers the infrastructure used by FreeBSD to manage the hardware devices on the system. From here on, I deal exclusively with real hardware.