《Undocumented Windows 2000 Secrets》翻譯 --- 第三章（2）
第三章 編寫(xiě)內(nèi)核模式驅(qū)動(dòng)程序
翻譯： Kendiv
更新： Tuesday, February 08, 2005
作為補(bǔ)充這里給出 DrvInfo.h 的內(nèi)容：
// __________________________________________________________
//
// DrvInfo.h
// Driver Info Definitions V1.00
// 06-02-2000 Sven B. Schreiber
// sbs@orgon.com
// __________________________________________________________
#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ū)動(dòng)程序的 C 代碼中包含了幾乎所有 Kernel-mode Driver 都需要的基本代碼。我會(huì)盡量使該驅(qū)動(dòng)向?qū)в懈玫目啥ㄖ菩浴Ｄ憧梢宰杂傻母南驅(qū)峁┑哪０逦募?duì)于想保留原有代碼的人，下面的章節(jié)會(huì)為你提供該向?qū)У囊恍﹥?nèi)部細(xì)節(jié)的簡(jiǎn)要介紹。
該向?qū)傻尿?qū)動(dòng)模塊的進(jìn)入點(diǎn)是 DriverEntry() 。像所有的 Windows 2000 模塊的進(jìn)入點(diǎn)一樣，這個(gè)名字并不時(shí)必須的。你可以使用任何你喜歡的名稱(chēng)，但是你必須告訴鏈接器你所使用的進(jìn)入點(diǎn)名稱(chēng)，通過(guò)鏈接器的命令行選項(xiàng) /entry 可以做到這一點(diǎn)。對(duì)于前面提及的 TestDriver ，向?qū)б呀?jīng)很好的完成了這項(xiàng)工作。在 w2k_wiz.tp 模板或生成的 TestDrv.dsp 文件中，你會(huì)在鏈接器的命令行中找到 /entry:”DriverEntry@8” 這樣的字符串。 @8 后綴表示 DriverEntry() 接受 8 個(gè)字節(jié)的參數(shù)（這些參數(shù)位于棧中），這和 列表 3-1 提供的 DriverEntry() 的原型一致：兩個(gè)指針參數(shù)，每個(gè)占據(jù) 32 個(gè)位，共使用 64 個(gè)二進(jìn)制位，即 8 字節(jié)。
DriverEntry() 做的第一件事是調(diào)用 DriverInitialize() ，該函數(shù)將創(chuàng)建一個(gè)設(shè)備對(duì)象（ Device Object ）和該對(duì)象的一個(gè)符號(hào)鏈接（ Symbolic link ），在稍后你可能在用戶(hù)模式的程序中使用該符號(hào)鏈接來(lái)與設(shè)備通訊。要想找到 IoCreateDevice() 和 IoCreateSymbolicLink() 所使用的名字就有些許的困難，因?yàn)樗鼈兌际且蕾?lài) DrvzInfo.h （位于本書(shū)光盤(pán)的 srccommoninclude 目錄）中的宏定義。如果你想更多的了解這個(gè)技巧，請(qǐng)參考 TestDrv.h （前面的 列表 3-4 已列出）中的 PROGRAM IDENTIFICATION 一節(jié)，并跟蹤形如 DRV_* 的定義，它們以多種方式成組的出現(xiàn)在 DrvInfo.h 中。例如，一個(gè)完整的 VERSIONINFO 資源就是由多個(gè)小的宏構(gòu)成的。在別處，還定義了 DRV_DEVICE 和 DRV_LINK 常量，在這里，它們分別等價(jià)于 DeviceTestDrv 和 DosDeviceTestDrv 。注意，很多內(nèi)核 API 函數(shù)，如 IoCreateDevice() 和 IoCreateSymbolickLinke() 不接受一個(gè)以零結(jié)尾的字符串，僅支持一個(gè)特殊的結(jié)構(gòu)體 ---UNICODE_STRING ，該結(jié)構(gòu)在第二章已經(jīng)介紹過(guò)， 列表 3-5 再次給出了該結(jié)構(gòu)的定義。定義于 DrvInfo.h 中的宏 ----PRESET_UNICODE_STRING （應(yīng)用于 TestDrv.c 的 GLOBAL DATA Section ）從一個(gè)簡(jiǎn)單的 Unicode 字符串常量創(chuàng)建出一個(gè)靜態(tài)的 UNICODE_STRING 結(jié)構(gòu)。這是針對(duì) UNICODE_STRING 結(jié)構(gòu)的一個(gè)方便的速記符號(hào)。
在成功的創(chuàng)建完設(shè)備對(duì)象及其符號(hào)鏈接后， DriverInitialize() 將設(shè)備對(duì)象指針和設(shè)備上下文（ Device Context ）的指針保存在一個(gè)靜態(tài)全局變量中。 Device Context 是設(shè)備的一個(gè)私有結(jié)構(gòu)，該結(jié)構(gòu)可以有任意的大小和結(jié)構(gòu)。本書(shū)提供的驅(qū)動(dòng)程序骨架附帶了一個(gè)簡(jiǎn)單的 DEVICE_CONTEXT 結(jié)構(gòu)，該結(jié)構(gòu)定義于 TestDrv.h 中。該結(jié)構(gòu)僅包含分別指向設(shè)備和設(shè)備驅(qū)動(dòng)程序?qū)ο蟮膬蓚€(gè)指針。你可以擴(kuò)展該結(jié)構(gòu)來(lái)保存設(shè)備驅(qū)動(dòng)程序所特有的數(shù)據(jù)。系統(tǒng)針對(duì)驅(qū)動(dòng)程序接收到的每個(gè) I/O 請(qǐng)求包（ I/O Request Packet, IRP ）提供相應(yīng)的 Device Context 。
在 DriverInitialize() 成功完成并返回后， DriverEntry() 將建立一個(gè)重要的數(shù)組，該數(shù)組由系統(tǒng)傳入，并做為驅(qū)動(dòng)程序?qū)ο蠼Y(jié)構(gòu) ----pDriverObject 的一部分。該數(shù)組為驅(qū)動(dòng)程序期望的所有 IRP 提供空間，同時(shí) DriverEntry() 還為所有希望得到控制的 IRP 寫(xiě)入對(duì)應(yīng)的 CallBack 函數(shù)的指針。本書(shū)提供的驅(qū)動(dòng)程序骨架遵循此種設(shè)計(jì)，它保存了一個(gè) DriverDispatcher() 指針，并提供了可存放 28 個(gè) IRP 的空間，如 表 3-2 所示。稍后， DriverDispatcher() 將決定需要注意那些類(lèi)型的 IRP ，并針對(duì)所有不感興趣的 IRP 返回 STATUS_NOT_IMPLEMENTED 。需要注意的是， Windows NT 和 Windows 2000 的 IRP 處理例程數(shù)組的布局有一些微妙的差別。在 表 3-2 中，這種差別以黑體標(biāo)識(shí)出來(lái)。
譯注：
在 Windows NT 中，大多數(shù)的 I/O 請(qǐng)求都是用 I/O 請(qǐng)求包（ IRP ）來(lái)表示的。在多數(shù)情況下， I/O 請(qǐng)求包可以從一個(gè) I/O 系統(tǒng)組件轉(zhuǎn)移到另一組件。這種設(shè)計(jì)允許單個(gè)應(yīng)用程序線程并行的管理多個(gè) I/O 請(qǐng)求。 IRP 是一種數(shù)據(jù)結(jié)構(gòu)，包含描述一個(gè) I/O 請(qǐng)求的完整信息。
具體的細(xì)節(jié)，請(qǐng)參考《 Inside Windows 2000 》的第 9 章 I/O System
typedef struct _UNICODE_STRING
{
WORD Length;
WORD MaximumLength;
PWORD Buffer;
} UNICODE_STRING, *PUNICODE_STRING;
列表 3-5. 一個(gè)普遍存在的 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ù)組中的每個(gè) I/O 請(qǐng)求包的比較
在 IRP 數(shù)組建立好之后， DriverEntry() 將自己的 CallBack 函數(shù) ----DriverUnload() 寫(xiě)入驅(qū)動(dòng)程序?qū)ο蠼Y(jié)構(gòu)中，這將允許在運(yùn)行時(shí)卸載該驅(qū)動(dòng)程序。 DriverUnload() 函數(shù)只是簡(jiǎn)單的銷(xiāo)毀由 DriverInitialize() 創(chuàng)建的所有對(duì)象（即設(shè)備對(duì)象和其符號(hào)鏈接）。在此之后，就可安全的將驅(qū)動(dòng)程序從系統(tǒng)中移除。
每當(dāng)一個(gè)模塊要求驅(qū)動(dòng)程序做出相應(yīng)時(shí)，就會(huì)調(diào)用 DriverDispatcher() 函數(shù)。因?yàn)椋?qū)動(dòng)程序能夠處理多個(gè)設(shè)備， Dispatcher 首先檢查那個(gè)設(shè)備應(yīng)該響應(yīng)該請(qǐng)求。本書(shū)提供的驅(qū)動(dòng)程序骨架僅維護(hù)了一個(gè)設(shè)備，因此，僅需要在初始化時(shí)檢查從 IoCreateDevice() 接受到的設(shè)備對(duì)象指針是否一致。如果一致， DriverDispatcher() 將接收到的 IRP 向前傳遞，給之前的 DriverDispatcher() 函數(shù)，隨之傳遞的還有 DriverInitialize() 準(zhǔn)備好的 Device Context 。當(dāng)你擴(kuò)展該驅(qū)動(dòng)骨架以管理多個(gè)設(shè)備驅(qū)動(dòng)程序時(shí)，你可能需要為每個(gè)設(shè)備編寫(xiě)?yīng)毩⒌?IRP dispatcher 。 列表 3-3 中的 DeviceDispatcher() 函數(shù)只是一個(gè)示意性的實(shí)現(xiàn)，它僅能識(shí)別三種常見(jiàn)的請(qǐng)求： IRP_MJ_CREATE 、 IRP_MJ_CLEANUP 和 IRP_MJ_CLOSE ，并通過(guò)返回 STATUS_SUCCESS 來(lái)表示以處理該請(qǐng)求。這是使設(shè)備能夠正常打開(kāi)、關(guān)閉的最小實(shí)現(xiàn)方式，對(duì)于其他的請(qǐng)求都將返回一個(gè) STATUS_NOT_IMPLEMENTED 。
你可能想知道在 列表 3-3 的 DISCARDABLE FUNCTIONS 一節(jié)中出現(xiàn)的 #pragma alloc_text 的目的。 #pragma 指示符是將命令送往編譯器和鏈接器的有力手段。 alloc_text 命令表示將指定函數(shù)的代碼寫(xiě)入可執(zhí)行文件的非默認(rèn) section 中。默認(rèn)情況下，所有程序代碼都位于 .text section 。然而，指示符 #pragma alloc_text(INIT,DriverEntry) 將使 DriverEntry() 的代碼保存在一個(gè)新的 section----INIT 中。驅(qū)動(dòng)加載器可以識(shí)別這種指定的 section ，并在初始化之后丟掉該 section 。 DriverEntry() 和它的幫助函數(shù) DriverInitialize() 僅在驅(qū)動(dòng)程序啟動(dòng)時(shí)會(huì)被調(diào)用一次；因此，當(dāng)它們完成自己的工作后，就可安全的將它們從內(nèi)存中移除。
現(xiàn)在驅(qū)動(dòng)程序骨架就只剩下了資源腳本 ---TestDrv.rc ，如 列表 3-6 所示。該文件沒(méi)有太大價(jià)值，因?yàn)樗鼉H引用了來(lái)自 DrvInfo.h 的宏 ----DRV_RC_VERSION 以及向?qū)峁┑膸讉€(gè)數(shù)據(jù)項(xiàng)來(lái)創(chuàng)建一個(gè) VERSIONINFO 資源，另一個(gè)宏 ---DRV_RC_ICON 則等同于將 TestDrv.ico 加入 TesetDrv.sys 的 Resource Section 中的 ICON 聲明語(yǔ)句。
// 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ū)動(dòng)程序骨架的資源腳本
網(wǎng)公網(wǎng)安備