第三章 編寫內核模式驅動程序

翻譯： Kendiv

更新： Monday, February 07, 2005

在下一章中，我們會經常訪問那些僅在內核模式下才有效的系統資源。大量的示例代碼都被設計為內核驅動例程（ Kernel-mode driver routine ）。因此，需要有關開發此種軟件的基本知識。因為我不能假定所有讀者都有這方面的經驗，我會在此簡要地介紹一下內核模式驅動程序編程，不過這僅集中在如何使用驅動開發向導（在本書光盤上）。

本章還將討論 Windows 2000 服務控制管理器（ Service Control Manager ， SCM ）的基本知識，這包括 SCM 如何允許在運行時加載、控制和卸載驅動程序， resulting in wonderfully short change-build-test turnaround cycles 。本章的題目或許會讓人有些誤解，驅動一詞通常與控制硬件的底層軟件相關。事實上，很多內核程序員每天都在做這些事情。不過， Windows 2000 的驅動程序分層模式允許做比這更多的事情。內核驅動程序可以完成任意復雜的任務，若不考慮它們運行于更高的 CPU 特權級別上而且使用不同的開發接口，那它們很像用戶模式下的 DLL 。在此，我們將使用這種強大的開發技術來偵測 Windows 2000 的內部秘密，使用內核驅動程序就像駕駛從狹小的用戶模式飛往 Windows 2000 內核的太空飛船。

創建一個驅動程序的骨架

即使長時間開發 Win32 應用程序和庫的開發人員，在首次編寫內核驅動程序時，也會感覺像是一個絕對的初學者。這是因為，內核模式下的代碼運行在一個完全不同的操作系統環境中。 Win32 開發人員的工作僅局限在屬于 Windows 2000 Win32 子系統的幾個系統組件上。其他開發人員可能編寫 POSI 或 OS/2 應用程序， Windows 2000 的附加子系統為它們提供支持。感謝子系統這個概念， Windows 2000 就像一個變色龍 --- 它可通過這些子系統（前面提及的）導出不同的應用程序開發接口來模擬不同的操作系統。與此相反，內核模式的代碼可以看到“真實”的 Windows 2000 操作系統。它們使用的接口可以稱之為“最終邊界”。當然，這并不是說，內核模式完全擺脫了子系統。在第二章中，我們看到 win32k.sys 就是 Win32 GUI 和窗口管理器在內核模式下的分支，將它們放在內核是出于性能考慮。然而， win32k.sys 導出的 API 函數集合中只有一小部分出現在了 gdi32.dll 和 user32.dll 中，這也意味著只有這一小部分函數可以作為 Win32 API 函數來使用，因此， Win32K 決不只是 Win32 踏入內核世界的一腳，實際上，應把它看作是一個高性能的內核模式的圖形引擎。

Windows 2000 DDK （ Device Driver Kit ）

由于內核模式下的編程使用了不同的系統接口，在 Win32 編程中經常使用的頭文件和庫都將無法在內核模式下使用。針對 Win32 開發，微軟提供了 Platform Software Development Kit （ SDK ）。而與內核模式的驅動開發相關的是， Windows 2000 Device Driver Kit （ DDK ）。隨文檔一起， DDK 還提供了特殊的頭文件和導入庫，這些都是 Windows 2000 內核模塊必須的接口。安裝完 DDK 之后，接下來你應該打開 Visual C/C++ ，把 DDK 的路徑加入到編譯器和鏈接器的目錄列表中。在主菜單中選擇 Tools à Options ，然后單擊 DirectorIEs 。在目錄選擇下拉列表中選擇 Include files ，然后將 DDK 的適當路徑加入，如 圖 3-1 所示。默認情況下， DDK 將安裝到 NTDDK 目錄下， included 文件位于 NTDDKinc 子目錄中。需要注意的是，請將新添加的路徑置于原有路徑的上方，這樣就會使用新的頭文件或者庫。

圖 3-1 添加 DDK 頭文件路徑

圖 3-2 添加 DDK 導入庫路徑

在添加完 DDK 頭文件路徑后，用同樣的方法添加導入庫的路徑。 DDK 包含兩組導入庫，一組叫做 free （ release ） builds ，另一組叫做 checked （ debug ） builds 。其對應的目錄為： NTDDKlibfrei386 和 NTDDKlibchki386 ，參見 圖 3-2 。

DDK 開發環境與 Win32 模式有所不同，下面給出二者之間的一些明顯區別：

l 對于 Win32 程序員來說，主要的頭文件是 windows.h ，對于內核模式代碼來說，應使用 ntddk.h 替代之。

l 主進入點函數叫做 DirverEntry() ，而不再是 WinMain() 或 main() 。 列表 3-1 給出了它們的原型。

l 不能再使用一些常見的 Win32 數據類型，如 BYTE 、 Word 和 DWORD 。 DDK 使用 UCHAR 、 USHORT 、 ULONG 等。不過，很容易就能定義你自己喜歡的類型， 列表 3-2 給出了這樣的一個示例。

NTSTATUS DriverEntry ( PDRIVER_OBJECT pDriverObject,

PUNICODE_STRING pusRegistryPath);

列表 3-1 DriverEntry 函數的原型

typedef UCHAR BYTE, *PBYTE;

typedef USHORT WORD, *PWORD;

typedef ULONG DWORD, *PDWORD;

列表 3-2 定義常見的 Win32 數據類型

此外，還需要注意 Windows NT 4.0 和 Windows 2000 所使用的 DDK 之間的差別，有三點不同需要注意，如下：

l 默認情況下， Windows NT 4.0 DDK 的主目錄叫做 DDK ，而 Windows 2000 DDK 叫做 NTDDK

l 在 Windows NT 4.0 DDK 中，主要的頭文件 ntddk.h 位于主目錄之下。而在 Windows 2000 DDK 中，該文件被移到了 NTDDKDDK 子目錄下。

l 導入庫的路徑也發生了變化： libi386free 變成了 libfrei386 ， libi386checked 變成了 libchki386 。

我不知道微軟的這種改變有什么實際意義，不過為了生活，我們還是需要了解其變化 J 。

可定制的驅動程序向導

開發內核驅動程序的主要困難在于 Visual C/C++ 沒有提供此種類型的工程向導。幸運的是， MSDN 里有一系列不錯的關于 Windows NT 內核驅動開發的文章，是 Ruediger R.Asche. 在 1994 至 1995 年編寫的。其中的兩篇文章（ Asche 1995a ， 1995b ）詳細說明了如何在 Visual C/C++ 中加入自定義的驅動程序向導，這些文章給了我很大的幫助，盡管原始向導的輸出文件不能滿足我的所有需求，但這是一個很好的開始。我提供的內核驅動向導將基于 Ruediger Asche 的原始向導產生的輸出文件。

我提供的驅動向導的所有源代碼位于本書光盤的 srcw2k_wiz 目錄。通過閱讀這些代碼，你會發現它實際的標題“ SBS Windows 2000 Code Wizard ”。事實上，這是一個一般性的 Windows 2000 程序骨架生成器，該生成器可以產生多種類型的程序，包括 Win32 DLL 和應用程序。不過，光盤中的配置文件針對內核驅動開發做了一定的修改。基本上來說，我提供的向導是一個文件轉換器，它讀取一組文件，然后按照一些簡單的規則將它們進行轉換，最后將結果寫入另一組文件中。輸入文件是模板，輸出文件是 C 工程文件。通過修改模板文件，該向導可以變成一個 DLL 向導等等。必須提供 7 個模板文件（如果丟失了某一個，會產生錯誤）：

l 擴展名為 .tw 的文件是 workspace 模板，此種文件將會被保存為 Visual Studio 的工程文件 .dsw 。

l 擴展名為 .tp 的文件是工程模板，此種文件將被保存為 .dsp 文件。工程文件由于之關聯的 workspace 文件引用，工程文件還包含生成工程的所有配置選項。

l 擴展名為 .tc 、 .th 、 .tr 和 .td 的文件都是 C 代碼文件，這些文件最后會變成相應的 .c 、 .h 、 .rc 和 .def 文件。

l 擴展名為 .ti 的是 icon 文件，該文件會被直接保存為 .ico 文件。

這七個文件是一個新工程所必需的。 .def 文件以一種較老風格的方法從 DLL 中導出 API 函數，不過我更喜歡 __declspec(dllexport) 方式。因為驅動程序通常不導出函數，所以我省略了 .td 模板，導致的結果是，在開始時，向導會報告一個錯誤。我還省略了資源腳本和 icon 文件，不過經驗告訴我，最好提供它們。采用的轉換規則也非常簡單，僅包含一個很短的字符串替換列表。在掃描模板文件時，轉換器查找以 % 號開始的轉義符。當它找到后，會根據 % 后的字符來決定執行什么樣的動作。 表 3-1 列出了驗證過的轉義符。

表 3-1 中有幾處需參考配置文件 ---w2k_wiz.ini 。 示例 3-1 給出了其默認設置。在使用向導之前，你應該將光盤 srcw2k_wizrelease 目錄下的 w2k_wiz.exe 、 w2k_wiz.ini 和所有的 w2k_wiz.t* 模板文件復制到你的硬盤上，然后編輯配置文件，將對應內容改為你自己的設置。你還需要修改 Include 、 Free 和 Checked ，使其和你的 DDK 安裝相匹配。如果你使用 Visual C/C++ 6.0 ，可以不改變 Root 的值。如果不，則將其設為你存放工程文件的根目錄。如果以一個反斜線結尾，它將作為默認值。在 示例 3-1 中，其鍵值為： HKEY_CURRENT_USERSoftWareMicrosoftoDevStudio6.0Directories ，而 WorkspaceDir 用來存放基本的工作目錄。

鍵入 w2k_wiz MyDriver 來執行該向導，它會當前目錄下創建名為 MyDriver 的工程目錄，該目錄將存放向導生成的 MyDriver.dsw 、 MyDriver.dsp 、 MyDriver.c 、 MyDriver.h 、 MyDriver.rc 和 MyDriver.ico 文件。如果你指定了具體的路徑，則會在你指定的路徑下創建該目錄。另一個合法的命令選項是星號，如： w2k_wiz *MyDriver 。在此種情況下，向導不會在當前目錄下創建工程目錄，而是去查找 Visual C/C++ 維護的默認的工程根目錄，即 w2k_wiz.ini 中的 Root 所指向的位置。

w2k_wiz.ini

08-27-2000 Sven B. Schreiber

sbs@orgon.com

[Settings]

Text = <SBS Windows 2000 Code Wizard Project>

Company = <MyCompany>

Author = <MyName>

Email = <my@email>

Prefix = <MyPrefix>

Include = E:NTDDKinc

Free = E:NTDDKlibfrei386

Checked = E:NTDDKlibchki386

Root = HKEY_CURRENT_USERSoftwareMicrosoftDevStudio6.0DirectoriesWorkspaceDir

示例 3-1. 向導支持的自定義選項

運行驅動向導

現在，來試試這個驅動向導。 示例 3-2 給出了在 Windows 2000 控制臺下執行 w2k_wiz *TestDrv 后的輸出。這將在 Visual C/C++ 默認的工程根目錄下創建一個名為 TestDrv 的工程目錄。

顯然，除了將 .td 模板轉換為 .def 時出了錯，其余轉換都成功的完成了。因為該向導生成的驅動程序骨架不需要 .def 文件，所以不需要提供 .td 模板文件。現在，用 Visual C/C++ 打開一個新的 WorkSpace ，然后你會發現一個名為 TestDrv 的新目錄，該目錄中包含一個名為 TestDrv.dsw 的 WorkSpace 文件。該文件可以被正確的打開。接下來，你因該為生成項目選擇活動的配置信息。驅動向導生成的 .dsp 文件提供了如下兩個可用配置：

1. Win2k Kernel-mode Driver(debug)

2. Win2k Kernel-mode Driver(release)

默認情況下，將使用 debug 配置來生成項目，但是你可在任何時候從 Visual C/C++ 菜單 Build/Set Active Configuration 來選擇不同的項目配置。最后，你要將光盤中的 srccommonincludeDrvInfo.h 復制到你自己的頭文件目錄中。在打開 TestDrv.rc 時，應使用文本模式來打開（如 圖 3-3 所示），這是因為該文件使用了來自 DrvInfo.h 中的復雜的宏定義，這些宏會導致資源編輯器異常退出。這個錯誤從 Visual C/C++ 5.0 開始，在我印象中，一直沒有被改正過。和編輯器不同，資源編譯器（ Resource Compiler ）可以正常的處理這些宏。

圖 3-3. 以文本模式打開 TestDrv.c 、 TestDrv.h 和 TestDrv.rc

現在，已經為第一次編譯做好了所有準備。在示例 3-3 中，我通過選擇 Build/Rebuild 菜單來建立 Driver 的 Release 版，看起來一切都正常。順便說一下，頭兩行末尾的省略號表示我截斷了 Build 命令的輸出。

鏈接器會在 Debug 或 Release 目錄下創建了一個名為 TestDrv.sys 的可執行文件，這依賴于你的生成配置。 Test Driver 的 Release 版大小為 5.5KB ，其 Debug 版為 8KB 。你可以使用本書光盤中的 MFVDasm 或 PEView 來驗證 TestDrv.sys 是否包含有效的代碼和數據。

深入驅動程序的骨架

列表 3-3 展示了向導生成的 TestDrv.c 。與之相關的頭文件 TestDrv.h 在 列表 3-4 中。在 列表 3-3 中，請注意標題處的 <MyName> 和 <MyCompany> 標志。如果 w2k_wiz.ini 中的作者和公司名稱正確，那你自己的名字和相應的公司名稱將會替代它們。

// TestDrv.c

// 08-07-2000 <MyName>

// Copyright @2005 <MyCompany>

#define _TESTDRV_SYS_

#include <ntddk.h>

#include 'TestDrv.h'

// =================================================================

// DISCLAIMER

// =================================================================

/*

This software is provided 'as is' and any express or implied

warranties, including, but not limited to, the implied warranties of

merchantability and fitness for a particular purpose are disclaimed.

In no event shall the author <MyName> be liable for any

direct, indirect, incidental, special, exemplary, or consequential

damages (including, but not limited to, procurement of substitute

goods or services; loss of use, data, or profits; or business

interruption) however caused and on any theory of liability,

whether in contract, strict liability, or tort (including negligence

or otherwise) arising in any way out of the use of this software,

even if advised of the possibility of such damage.

*/

// =================================================================

// REVISION HISTORY

// =================================================================

/*

08-07-2000 V1.00 Original version.

*/

// =================================================================

// GLOBAL DATA

// =================================================================

PRESET_UNICODE_STRING (usDeviceName, CSTRING (DRV_DEVICE));

PRESET_UNICODE_STRING (usSymbolicLinkName, CSTRING (DRV_LINK ));

PDEVICE_OBJECT gpDeviceObject = NULL;

PDEVICE_CONTEXT gpDeviceContext = NULL;

// =================================================================

// DISCARDABLE FUNCTIONS

// =================================================================

NTSTATUS DriverInitialize (PDRIVER_OBJECT pDriverObject,

PUNICODE_STRING pusRegistryPath);

NTSTATUS DriverEntry (PDRIVER_OBJECT pDriverObject,

PUNICODE_STRING pusRegistryPath);

// -----------------------------------------------------------------

#ifdef ALLOC_PRAGMA

#pragma alloc_text (INIT, DriverInitialize)

#pragma alloc_text (INIT, DriverEntry)

#endif

// =================================================================

// DEVICE REQUEST HANDLER

// =================================================================

NTSTATUS DeviceDispatcher (PDEVICE_CONTEXT pDeviceContext,

PIRP pIrp)

{

PIO_STACK_LOCATION pisl;

DWORD dInfo = 0;

NTSTATUS ns = STATUS_NOT_IMPLEMENTED;

pisl = IoGetCurrentIrpStackLocation (pIrp);

switch (pisl->MajorFunction)

{

case IRP_MJ_CREATE:

case IRP_MJ_CLEANUP:

case IRP_MJ_CLOSE:

{

ns = STATUS_SUCCESS;

break;

}

}

pIrp->IoStatus.Status = ns;

pIrp->IoStatus.Information = dInfo;

IoCompleteRequest (pIrp, IO_NO_INCREMENT);

return ns;

}

// =================================================================

// DRIVER REQUEST HANDLER

// =================================================================

NTSTATUS DriverDispatcher (PDEVICE_OBJECT pDeviceObject,

PIRP pIrp)

{

return (pDeviceObject == gpDeviceObject

? DeviceDispatcher (gpDeviceContext, pIrp)

: STATUS_INVALID_PARAMETER_1);

}

// -----------------------------------------------------------------

void DriverUnload (PDRIVER_OBJECT pDriverObject)

{

IoDeleteSymbolicLink (&usSymbolicLinkName);

IoDeleteDevice (gpDeviceObject);

return;

}

// =================================================================

// DRIVER INITIALIZATION

// =================================================================

NTSTATUS DriverInitialize (PDRIVER_OBJECT pDriverObject,

PUNICODE_STRING pusRegistryPath)

{

PDEVICE_OBJECT pDeviceObject = NULL;

NTSTATUS ns = STATUS_DEVICE_CONFIGURATION_ERROR;

if ((ns = IoCreateDevice (pDriverObject, DEVICE_CONTEXT_,

&usDeviceName, FILE_DEVICE_CUSTOM,

0, FALSE, &pDeviceObject))

== STATUS_SUCCESS)

{

if ((ns = IoCreateSymbolicLink (&usSymbolicLinkName,

&usDeviceName))

== STATUS_SUCCESS)

{

gpDeviceObject = pDeviceObject;

gpDeviceContext = pDeviceObject->DeviceExtension;

gpDeviceContext->pDriverObject = pDriverObject;

gpDeviceContext->pDeviceObject = pDeviceObject;

}

else

{

IoDeleteDevice (pDeviceObject);

}

}

return ns;

}

// -----------------------------------------------------------------

NTSTATUS DriverEntry (PDRIVER_OBJECT pDriverObject,

PUNICODE_STRING pusRegistryPath)

{

PDRIVER_DISPATCH *ppdd;

NTSTATUS ns = STATUS_DEVICE_CONFIGURATION_ERROR;

if ((ns = DriverInitialize (pDriverObject, pusRegistryPath))

== STATUS_SUCCESS)

{

ppdd = pDriverObject->MajorFunction;

ppdd [IRP_MJ_CREATE ] =

ppdd [IRP_MJ_CREATE_NAMED_PIPE ] =

ppdd [IRP_MJ_CLOSE ] =

ppdd [IRP_MJ_READ ] =

ppdd [IRP_MJ_WRITE ] =

ppdd [IRP_MJ_QUERY_INFORMATION ] =

ppdd [IRP_MJ_SET_INFORMATION ] =

ppdd [IRP_MJ_QUERY_EA ] =

ppdd [IRP_MJ_SET_EA ] =

ppdd [IRP_MJ_FLUSH_BUFFERS ] =

ppdd [IRP_MJ_QUERY_VOLUME_INFORMATION] =

ppdd [IRP_MJ_SET_VOLUME_INFORMATION ] =

ppdd [IRP_MJ_DIRECTORY_CONTROL ] =

ppdd [IRP_MJ_FILE_SYSTEM_CONTROL ] =

ppdd [IRP_MJ_DEVICE_CONTROL ] =

ppdd [IRP_MJ_INTERNAL_DEVICE_CONTROL ] =

ppdd [IRP_MJ_SHUTDOWN ] =

ppdd [IRP_MJ_LOCK_CONTROL ] =

ppdd [IRP_MJ_CLEANUP ] =

ppdd [IRP_MJ_CREATE_MAILSLOT ] =

ppdd [IRP_MJ_QUERY_SECURITY ] =

ppdd [IRP_MJ_SET_SECURITY ] =

ppdd [IRP_MJ_POWER ] =

ppdd [IRP_MJ_SYSTEM_CONTROL ] =

ppdd [IRP_MJ_DEVICE_CHANGE ] =

ppdd [IRP_MJ_QUERY_QUOTA ] =

ppdd [IRP_MJ_SET_QUOTA ] =

ppdd [IRP_MJ_PNP ] = DriverDispatcher;

pDriverObject->DriverUnload = DriverUnload;

}

return ns;

}

// =================================================================

// END OF PROGRAM

// =================================================================

列表 3-3. 驅動程序骨架的源代碼

// TestDrv.h

// 08-07-2000 <MyName>

// Copyright @2005 <MyCompany>

// =================================================================

// PROGRAM IDENTIFICATION

// =================================================================

#define DRV_BUILD 1

#define DRV_VERSION_HIGH 1

#define DRV_VERSION_LOW 0

// -----------------------------------------------------------------

#define DRV_DAY 07

#define DRV_MONTH 02

#define DRV_YEAR 2005

// -----------------------------------------------------------------

// Customize these settings by editing the configuration file

// D:etc32w2k_wiz.ini

#define DRV_MODULE TestDrv

#define DRV_NAME <SBS Windows 2000 Code Wizard Project>

#define DRV_COMPANY <MyCompany>

#define DRV_AUTHOR <MyName>

#define DRV_EMAIL <my@email>

#define DRV_PREFIX <MyPrefix>

// =================================================================

// HEADER FILES

// =================================================================

#include 'drvinfo.h' // defines more DRV_* items

////////////////////////////////////////////////////////////////////

#ifndef _RC_PASS_

////////////////////////////////////////////////////////////////////

// =================================================================

// CONSTANTS

// =================================================================

#define FILE_DEVICE_CUSTOM 0x8000

// =================================================================

// STRUCTURES

// =================================================================

typedef struct _DEVICE_CONTEXT

{

PDRIVER_OBJECT pDriverObject;

PDEVICE_OBJECT pDeviceObject;

}

DEVICE_CONTEXT, *PDEVICE_CONTEXT, **PPDEVICE_CONTEXT;

#define DEVICE_CONTEXT_ sizeof (DEVICE_CONTEXT)

////////////////////////////////////////////////////////////////////

#endif // #ifndef _RC_PASS_

////////////////////////////////////////////////////////////////////

// =================================================================

// END OF FILE

// =================================================================

列表 3-4. 驅動程序骨架的頭文件