Walter Oney - Programming the Microsoft Windows Driver Model

This electronic book was originally createdand still may be purchasedas a print book. For simplicity, the electronic version of this book has been modified as little as possible from its original form. For instance, there may be occasional references to sample files that come with the book. These files are available with the print version, but are not provided in this electronic edition.

Many of the graphics shown in this book are quite large. To improve the readability of the book, reduced versions of these graphics are shown in the text. To see a full-size version, click on the reduced graphic.

I'm indebted to many people who helped make this book a reality. Devon Musgrave, Robert Lyon, and the rest of the team at Microsoft Press performed yeoman service in turning a rugged WinWord manuscript into the polished work you're holding in your hands. I know that Ben Ryan, the Acquisitions Editor for this project, logs countless hours and frequent flyer miles searching for great authors and sizzling new books; well, better luck next time. Microsoft's Sandy Spinrad, in just one of his many aspects, ably assisted by locating technical information, hardware for testing, up-to-date releases, and much of the other research material on which I relied. Many members of the Windows 2000 and Windows 98 base teams reviewed this material and deserve personal mention, but they've requested anonymity; they and I know who they are, at least. My seminar students and the online community helped in many large and small ways by asking thought-provoking questions or sharing hard-won insights. Finally, I want to thank my wife, Marty, who's always there when the going gets tough.

Walter Oney
http://www.oneysoft.com

Walter Oney is a freelance software consultant based in Boston, Massachusetts. A member of the class of 1968, he holds S.B. and S.M. degrees in Electrical Engineering from the Massachusetts Institute of Technology. When not teaching programming seminars, he enjoys running, cycling, watching ballet, and playing the oboe.

Copyright 1999by Walter Oney

PUBLISHED BY
Microsoft Press
A Division of Microsoft Corporation
One Microsoft Way
Redmond, Washington 98052-6399

Copyright 1999 by Walter Oney

All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form or by any means without the written permission of the publisher.

Library of Congress Cataloging-in-Publication Data
Oney, Walter.
Programming the Microsoft Windows Driver Model
p. cm.
Includes index.
ISBN 0-7356-0588-2
1. Microsoft Windows NT device drivers (Computer programs)
2. Computer programming. I. Title
QA76.76.D49O54 1999
005.7'126--dc21 99-33878
CIP

Printed and bound in the United States of America.

1 2 3 4 5 6 7 8 9 QMQM 4 3 2 1 0 9

Distributed in Canada by Penguin Books Canada Limited.

A CIP catalogue record for this book is available from the British Library.

Microsoft Press books are available through booksellers and distributors worldwide. For further information about international editions, contact your local Microsoft Corporation office or contact Microsoft Press International directly at fax (425) 936-7329. Visit our Web site at mspress.microsoft.com.

Intel is a registered trademark of Intel Corporation. Microsoft, Microsoft Press, MSDN, Visual C++, Visual Studio, Win32, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Other product and company names mentioned herein may be the trademarks of their respective owners.

The example companies, organizations, products, people, and events depicted herein are fictitious. No association with any real company, organization, product, person, or event is intended or should be inferred.

Acquisitions Editor: Ben Ryan

Project Editor: Devon Musgrave

Technical Editor: Robert Lyon

Chapter 1

Souvenir shops in many of the cities I visit sell posters depicting the world from the localperspective. Landmarks and famous watering holes appear prominently in the foreground. Thebackground features the rest of the planet in progressively less detail, confirming that thenatives are less impressed by, say, the pyramids in Giza or the Great Wall of China than bysome busy downtown street corner. From the same sort of insular perspective, a MicrosoftWindows 2000 or Microsoft Windows 98 system consists of an operating system and a collection ofdevice drivers for whatever hardware the end user chooses to populate the system with from onemoment to the next. This book is all about the drivers and the nearby detail.

The Windows Driver Model (WDM) provides a framework for device drivers that operate in twooperating systemsWindows 98 and Windows 2000. Although to the end user these two systemsare very similar, they work very differently on the inside. In this section, I'll present abrief overview of the two systems.

Figure 1-1 is my perspective poster of the Windows 2000 operating system, wherein Iemphasize the features that are important to people who write device drivers. Software executeseither in user mode (untrusted and restricted to authorized activities only) or in kernel mode (fully trusted and able to do anything). A user-mode program that wants to,say, read some data from a device would call an application programming interface (API) such asReadFile. A subsystem module such as KERNEL32.DLL implements this API by invoking somesort of platform-dependent system service interface to reach a kernel-mode support routine. Inthe case of a call to ReadFile, the mechanism involves making a user-mode call to an entrypoint named NtReadFile in a system dynamic-link library (DLL) namedredundantly,I've always thoughtNTDLL.DLL. The user-mode NtReadFile function uses the systemservice interface to reach a kernel-mode routine that's also named NtReadFile.

Figure 1-1.The Windows 2000 architecture.

We often say that NtReadFile is part of a system component that we call the I/O Manager. Theterm I/O Manager is perhaps a little misleading because there isn't any singleexecutable module with that name. We need a name to use when discussing the "cloud"of operating system services that surrounds our own driver, though, and this name is the one weusually pick.

Many routines serve a purpose similar to NtReadFile. They operate in kernel mode to servicean application's request to interact with a device in some way. They all validate theirparameters, thereby ensuring that they don't inadvertently allow a security breach byperforming an operation or accessing some data that the user-mode program wouldn't havebeen able to perform or access by itself. They then create a data structure called an I/Orequest packet (IRP) that they pass to an entry point in some device driver. In the case of anoriginal ReadFile call, NtReadFile would create an IRP with a major function code ofIRP_MJ_READ (a constant in a DDK [Device Driver Kit] header file). Processing details at thispoint can differ, but a likely scenario is for a routine like NtReadFile to return to theuser-mode caller with an indication that the operation described by the IRP hasn't finishedyet. The user-mode program might continue about its business and then wait for the operation tofinish, or it might wait immediately. Either way, the device driver proceeds independently ofthe application to service the request.