第三章 編寫內(nèi)核模式驅(qū)動程序

翻譯： Kendiv

更新： Tuesday, February 08, 2005

作為補充這里給出 DrvInfo.h 的內(nèi)容：

// __________________________________________________________

//

// DrvInfo.h

// Driver Info Definitions V1.00

// 06-02-2000 Sven B. Schreiber

// [email protected]

// __________________________________________________________

#ifndef _DRVINFO_H_

#define _DRVINFO_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 Sven B. Schreiber 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

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

/*

05-26-2000 V1.00 Original version (SBS).

*/

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

// BASIC TYPES

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

typedef UCHAR BYTE, *PBYTE, **PPBYTE;

typedef USHORT Word, *PWORD, **PPWORD;

typedef ULONG DWORD, *PDWORD, **PPDWORD;

typedef unsigned __int64 QWORD, *PQWORD, **PPQWORD;

typedef int BOOL, *PBOOL, **PPBOOL;

typedef void **PPVOID;

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

#define BYTE_ sizeof (BYTE)

#define WORD_ sizeof (WORD)

#define DWORD_ sizeof (DWORD)

#define QWORD_ sizeof (QWORD)

#define BOOL_ sizeof (BOOL)

#define PVOID_ sizeof (PVOID)

#define HANDLE_ sizeof (HANDLE)

#define PHYSICAL_ADDRESS_ sizeof (PHYSICAL_ADDRESS)

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

// MacROS

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

#define _DRV_DEVICE(_name) Device ## _name

#define _DRV_LINK(_name) DosDevices ## _name

#define _DRV_PATH(_name) . ## _name

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

#define _CSTRING(_text) #_text

#define CSTRING(_text) _CSTRING (_text)

#define _USTRING(_text) L##_text

#define USTRING(_text) _USTRING (_text)

#define PRESET_UNICODE_STRING(_symbol,_buffer)

UNICODE_STRING _symbol =

{

sizeof (USTRING (_buffer)) - sizeof (WORD),

sizeof (USTRING (_buffer)),

USTRING (_buffer)

};

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

#if DRV_VERSION_LOW < 10

#define _DRV_V2(_a,_b) _a ## .0 ## _b

#define _DRV_V2X(_a,_b) V ## _a ## .0 ## _b

#else // #if DRV_VERSION_LOW < 10

#define _DRV_V2(_a,_b) _a ## . ## _b

#define _DRV_V2X(_a,_b) V ## _a ## . ## _b

#endif // #if DRV_VERSION_LOW < 10 #else

#define DRV_V2(_a,_b) _DRV_V2(_a,_b)

#define DRV_V2X(_a,_b) _DRV_V2X(_a,_b)

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

#define _DRV_V4(_a,_b,_c) _a ## . ## _b ## .0. ## _c

#define DRV_V4(_a,_b,_c) _DRV_V4(_a,_b,_c)

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

#define DRV_V DRV_V2X (DRV_VERSION_HIGH,

DRV_VERSION_LOW)

#define DRV_VERSION DRV_V2 (DRV_VERSION_HIGH,

DRV_VERSION_LOW)

#define DRV_VERSION_QUAD DRV_V4 (DRV_VERSION_HIGH,

DRV_VERSION_LOW,

DRV_BUILD)

#define DRV_VERSION_BINARY ((DRV_VERSION_HIGH * 100)

+ DRV_VERSION_LOW)

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

// DRIVER INFORMATION

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

#define DRV_ID DRV_PREFIX.DRV_MODULE

#define DRV_ID_VERSION DRV_ID.DRV_VERSION_HIGH

#define DRV_FILENAME DRV_MODULE.DRV_EXTENSION

#define DRV_CAPTION DRV_NAME DRV_V

#define DRV_COMMENT DRV_DATE DRV_AUTHOR

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

#define DRV_DEVICE _DRV_DEVICE (DRV_MODULE)

#define DRV_LINK _DRV_LINK (DRV_MODULE)

#define DRV_PATH _DRV_PATH (DRV_MODULE)

#define DRV_EXTENSION sys

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

#define DRV_CLASS DRV_MODULE.DRV_VERSION_QUAD

#define DRV_ICON DRV_MODULE.Icon

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

#define DRV_COPYRIGHT Copyright xA9 DRV_YEAR

#define DRV_COPYRIGHT_EX DRV_COPYRIGHT DRV_COMPANY

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

#define DRV_DATE_US DRV_MONTH-DRV_DAY-DRV_YEAR

#define DRV_DATE_GERMAN DRV_DAY.DRV_MONTH.DRV_YEAR

#define DRV_DATE DRV_DATE_US

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

// NT4 COMPATIBILITY

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

#ifndef IRP_MJ_QUERY_POWER

#define IRP_MJ_QUERY_POWER 0x16

#endif

#ifndef IRP_MJ_SET_POWER

#define IRP_MJ_SET_POWER 0x17

#endif

#ifndef IRP_MJ_PNP_POWER

#define IRP_MJ_PNP_POWER 0x1B

#endif

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

#ifdef _RC_PASS_

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

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

// HEADER FILES

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

#include <winver.h>

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

// VERSION INFO

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

#define DRV_RC_VERSION

VS_VERSION_INFO VERSIONINFO

FILEVERSION DRV_VERSION_HIGH, DRV_VERSION_LOW, 0, DRV_BUILD

PRODUCTVERSION DRV_VERSION_HIGH, DRV_VERSION_LOW, 0, DRV_BUILD

FILEFLAGSMASK VS_FFI_FILEFLAGSMASK

FILEFLAGS 0

FILEOS VOS_NT

FILETYPE VFT_DRV

FILESUBTYPE VFT2_UNKNOWN

{

BLOCK 'StringFileInfo'

{

BLOCK '040904B0'

{

VALUE 'OriginalFilename', CSTRING (DRV_FILENAME)

VALUE 'InternalName', CSTRING (DRV_MODULE)

VALUE 'ProductName', CSTRING (DRV_NAME)

VALUE 'FileDescription', CSTRING (DRV_CAPTION)

VALUE 'CompanyName', CSTRING (DRV_COMPANY)

VALUE 'ProductVersion', CSTRING (DRV_VERSION_QUAD)

VALUE 'FileVersion', CSTRING (DRV_VERSION_QUAD)

VALUE 'LegalCopyright', CSTRING (DRV_COPYRIGHT_EX)

VALUE 'Comments', CSTRING (DRV_COMMENT)

}

}

BLOCK 'VarFileInfo'

{

VALUE 'Translation', 0x0409, 0x04B0

}

}

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

// RESOURCES

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

#define DRV_RC_ICON DRV_ICON ICON DRV_MODULE.ico

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

#endif // #ifdef _RC_PASS_

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

#endif // #ifndef _DRVINFO_H_

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

// END OF FILE

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

列表 3-3 和 列表 3-4 給出的驅(qū)動程序的 C 代碼中包含了幾乎所有 Kernel-mode Driver 都需要的基本代碼。我會盡量使該驅(qū)動向?qū)в懈玫目啥ㄖ菩浴Ｄ憧梢宰杂傻母南驅(qū)峁┑哪０逦募τ谙氡Ａ粼写a的人，下面的章節(jié)會為你提供該向?qū)У囊恍﹥?nèi)部細節(jié)的簡要介紹。

該向?qū)傻尿?qū)動模塊的進入點是 DriverEntry() 。像所有的 Windows 2000 模塊的進入點一樣，這個名字并不時必須的。你可以使用任何你喜歡的名稱，但是你必須告訴鏈接器你所使用的進入點名稱，通過鏈接器的命令行選項 /entry 可以做到這一點。對于前面提及的 TestDriver ，向?qū)б呀?jīng)很好的完成了這項工作。在 w2k_wiz.tp 模板或生成的 TestDrv.dsp 文件中，你會在鏈接器的命令行中找到 /entry:”DriverEntry@8” 這樣的字符串。 @8 后綴表示 DriverEntry() 接受 8 個字節(jié)的參數(shù)（這些參數(shù)位于棧中），這和 列表 3-1 提供的 DriverEntry() 的原型一致：兩個指針參數(shù)，每個占據(jù) 32 個位，共使用 64 個二進制位，即 8 字節(jié)。

DriverEntry() 做的第一件事是調(diào)用 DriverInitialize() ，該函數(shù)將創(chuàng)建一個設(shè)備對象（ Device Object ）和該對象的一個符號鏈接（ Symbolic link ），在稍后你可能在用戶模式的程序中使用該符號鏈接來與設(shè)備通訊。要想找到 IoCreateDevice() 和 IoCreateSymbolicLink() 所使用的名字就有些許的困難，因為它們都是依賴 DrvzInfo.h （位于本書光盤的 srccommoninclude 目錄）中的宏定義。如果你想更多的了解這個技巧，請參考 TestDrv.h （前面的 列表 3-4 已列出）中的 PROGRAM IDENTIFICATION 一節(jié)，并跟蹤形如 DRV_* 的定義，它們以多種方式成組的出現(xiàn)在 DrvInfo.h 中。例如，一個完整的 VERSIONINFO 資源就是由多個小的宏構(gòu)成的。在別處，還定義了 DRV_DEVICE 和 DRV_LINK 常量，在這里，它們分別等價于 DeviceTestDrv 和 DosDeviceTestDrv 。注意，很多內(nèi)核 API 函數(shù)，如 IoCreateDevice() 和 IoCreateSymbolickLinke() 不接受一個以零結(jié)尾的字符串，僅支持一個特殊的結(jié)構(gòu)體 ---UNICODE_STRING ，該結(jié)構(gòu)在第二章已經(jīng)介紹過， 列表 3-5 再次給出了該結(jié)構(gòu)的定義。定義于 DrvInfo.h 中的宏 ----PRESET_UNICODE_STRING （應(yīng)用于 TestDrv.c 的 GLOBAL DATA Section ）從一個簡單的 Unicode 字符串常量創(chuàng)建出一個靜態(tài)的 UNICODE_STRING 結(jié)構(gòu)。這是針對 UNICODE_STRING 結(jié)構(gòu)的一個方便的速記符號。

在成功的創(chuàng)建完設(shè)備對象及其符號鏈接后， DriverInitialize() 將設(shè)備對象指針和設(shè)備上下文（ Device Context ）的指針保存在一個靜態(tài)全局變量中。 Device Context 是設(shè)備的一個私有結(jié)構(gòu)，該結(jié)構(gòu)可以有任意的大小和結(jié)構(gòu)。本書提供的驅(qū)動程序骨架附帶了一個簡單的 DEVICE_CONTEXT 結(jié)構(gòu)，該結(jié)構(gòu)定義于 TestDrv.h 中。該結(jié)構(gòu)僅包含分別指向設(shè)備和設(shè)備驅(qū)動程序?qū)ο蟮膬蓚€指針。你可以擴展該結(jié)構(gòu)來保存設(shè)備驅(qū)動程序所特有的數(shù)據(jù)。系統(tǒng)針對驅(qū)動程序接收到的每個 I/O 請求包（ I/O Request Packet, IRP ）提供相應(yīng)的 Device Context 。

在 DriverInitialize() 成功完成并返回后， DriverEntry() 將建立一個重要的數(shù)組，該數(shù)組由系統(tǒng)傳入，并做為驅(qū)動程序?qū)ο蠼Y(jié)構(gòu) ----pDriverObject 的一部分。該數(shù)組為驅(qū)動程序期望的所有 IRP 提供空間，同時 DriverEntry() 還為所有希望得到控制的 IRP 寫入對應(yīng)的 CallBack 函數(shù)的指針。本書提供的驅(qū)動程序骨架遵循此種設(shè)計，它保存了一個 DriverDispatcher() 指針，并提供了可存放 28 個 IRP 的空間，如 表 3-2 所示。稍后， DriverDispatcher() 將決定需要注意那些類型的 IRP ，并針對所有不感興趣的 IRP 返回 STATUS_NOT_IMPLEMENTED 。需要注意的是， Windows NT 和 Windows 2000 的 IRP 處理例程數(shù)組的布局有一些微妙的差別。在 表 3-2 中，這種差別以黑體標(biāo)識出來。

譯注：

在 Windows NT 中，大多數(shù)的 I/O 請求都是用 I/O 請求包（ IRP ）來表示的。在多數(shù)情況下， I/O 請求包可以從一個 I/O 系統(tǒng)組件轉(zhuǎn)移到另一組件。這種設(shè)計允許單個應(yīng)用程序線程并行的管理多個 I/O 請求。 IRP 是一種數(shù)據(jù)結(jié)構(gòu)，包含描述一個 I/O 請求的完整信息。

具體的細節(jié)，請參考《 Inside Windows 2000 》的第 9 章 I/O System

typedef struct _UNICODE_STRING

{

WORD Length;

WORD MaximumLength;

PWORD Buffer;

} UNICODE_STRING, *PUNICODE_STRING;

列表 3-5. 一個普遍存在的 Windows 2000 結(jié)構(gòu)： UNICODE_STRING

元素

Windows NT 4.0

Windows 2000

0x00

IRP_MJ_CREATE

IRP_MJ_CREATE

0x01

IRP_MJ_CREATE_NAMED_PIPE

IRP_MJ_CREATE_NAMED_PIPE

0x02

IRP_MJ_CLOSE

IRP_MJ_CLOSE

0x03

IRP_MJ_READ

IRP_MJ_READ

0x04

IRP_MJ_WRITE

IRP_MJ_WRITE

0x05

IRP_MJ_QUERY_INFORMATION

IRP_MJ_QUERY_INFORMATION

0x06

IRP_MJ_SET_INFORMATION

IRP_MJ_SET_INFORMATION

0x07

IRP_MJ_QUERY_EA

IRP_MJ_QUERY_EA

0x08

IRP_MJ_SET_EA

IRP_MJ_SET_EA

0x09

IRP_MJ_FLUSH_BUFFERS

IRP_MJ_FLUSH_BUFFERS

0x0A

IRP_MJ_QUERY_VOLUME_INFORMATION

IRP_MJ_QUERY_VOLUME_INFORAMTION

0x0B

IRP_MJ_SET_VOLUME_INFORMATION

IRP_MJ_SET_VOLUME_INFORMATION

0x0C

IRP_MJ_DirectorY_CONTROL

IRP_MJ_DIRECTORY_CONTROL

0x0D

IRP_MJ_FILE_SYSTEM_CONTROL

IRP_MJ_FILE_SYSTEM_CONTROL

0x0E

IRP_MJ_DEVICE_CONTROL

IRP_MJ_DEVICE_CONTROL

0x0F

IRP_MJ_INTERNAL_DEVICE_CONTROL

IRP_MJ_INTERNAL_DEVICE_CONTROL

0x10

IRP_MJ_SHUTDOWN

IRP_MJ_SHUTDOWN

0x11

IRP_MJ_LOCK_CONTROL

IRP_MJ_LOCK_CONTROL

0x12

IRP_MJ_CLEANUP

IRP_MJ_CLEANUP

0x13

IRP_MJ_CREATE_MAILSLOT

IRP_MJ_CREATE_MAILSLOT

0x14

IRP_MJ_QUERY_SECURITY

IRP_MJ_QUERY_SECURITY

0x15

IRP_MJ_SET_SECURITY

IRP_MJ_SET_SECURITY

0x16

IRP_MJ_QUERY_POWER

IRP_MJ_POWER

0x17

IRP_MJ_SET_POWER

IRP_MJ_SYSTEM_CONTROL

0x18

IRP_MJ_DEVICE_CHANGE

IRP_MJ_DEVICE_CHANGE

0x19

IRP_MJ_QUERY_QUOTA

IRP_MJ_QUERY_QUOTA

0x1A

IRP_MJ_SET_QUOTA

IRP_MJ_SET_QUOTA

0x1B

IRP_MJ_PNP_POWER

IRP_MJ_PNP

表 3-2. 數(shù)組中的每個 I/O 請求包的比較

在 IRP 數(shù)組建立好之后， DriverEntry() 將自己的 CallBack 函數(shù) ----DriverUnload() 寫入驅(qū)動程序?qū)ο蠼Y(jié)構(gòu)中，這將允許在運行時卸載該驅(qū)動程序。 DriverUnload() 函數(shù)只是簡單的銷毀由 DriverInitialize() 創(chuàng)建的所有對象（即設(shè)備對象和其符號鏈接）。在此之后，就可安全的將驅(qū)動程序從系統(tǒng)中移除。

每當(dāng)一個模塊要求驅(qū)動程序做出相應(yīng)時，就會調(diào)用 DriverDispatcher() 函數(shù)。因為，驅(qū)動程序能夠處理多個設(shè)備， Dispatcher 首先檢查那個設(shè)備應(yīng)該響應(yīng)該請求。本書提供的驅(qū)動程序骨架僅維護了一個設(shè)備，因此，僅需要在初始化時檢查從 IoCreateDevice() 接受到的設(shè)備對象指針是否一致。如果一致， DriverDispatcher() 將接收到的 IRP 向前傳遞，給之前的 DriverDispatcher() 函數(shù)，隨之傳遞的還有 DriverInitialize() 準(zhǔn)備好的 Device Context 。當(dāng)你擴展該驅(qū)動骨架以管理多個設(shè)備驅(qū)動程序時，你可能需要為每個設(shè)備編寫?yīng)毩⒌?IRP dispatcher 。 列表 3-3 中的 DeviceDispatcher() 函數(shù)只是一個示意性的實現(xiàn)，它僅能識別三種常見的請求： IRP_MJ_CREATE 、 IRP_MJ_CLEANUP 和 IRP_MJ_CLOSE ，并通過返回 STATUS_SUCCESS 來表示以處理該請求。這是使設(shè)備能夠正常打開、關(guān)閉的最小實現(xiàn)方式，對于其他的請求都將返回一個 STATUS_NOT_IMPLEMENTED 。

你可能想知道在 列表 3-3 的 DISCARDABLE FUNCTIONS 一節(jié)中出現(xiàn)的 #pragma alloc_text 的目的。 #pragma 指示符是將命令送往編譯器和鏈接器的有力手段。 alloc_text 命令表示將指定函數(shù)的代碼寫入可執(zhí)行文件的非默認 section 中。默認情況下，所有程序代碼都位于 .text section 。然而，指示符 #pragma alloc_text(INIT,DriverEntry) 將使 DriverEntry() 的代碼保存在一個新的 section----INIT 中。驅(qū)動加載器可以識別這種指定的 section ，并在初始化之后丟掉該 section 。 DriverEntry() 和它的幫助函數(shù) DriverInitialize() 僅在驅(qū)動程序啟動時會被調(diào)用一次；因此，當(dāng)它們完成自己的工作后，就可安全的將它們從內(nèi)存中移除。

現(xiàn)在驅(qū)動程序骨架就只剩下了資源腳本 ---TestDrv.rc ，如 列表 3-6 所示。該文件沒有太大價值，因為它僅引用了來自 DrvInfo.h 的宏 ----DRV_RC_VERSION 以及向?qū)峁┑膸讉€數(shù)據(jù)項來創(chuàng)建一個 VERSIONINFO 資源，另一個宏 ---DRV_RC_ICON 則等同于將 TestDrv.ico 加入 TesetDrv.sys 的 Resource Section 中的 ICON 聲明語句。

// TestDrv.rc

// 08-07-2000 <MyName>

// Copyright ?2000 <MyCompany>

#define _RC_PASS_

#define _TESTDRV_SYS_

#include 'TestDrv.h'

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

// STANDARD RESOURCES

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

DRV_RC_VERSION

DRV_RC_ICON

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

// END OF FILE

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

列表 3-6. 驅(qū)動程序骨架的資源腳本