《Undocumented Windows 2000 Secrets》翻譯 --- 第三章（2）
第三章 編寫內(nèi)核模式驅(qū)動程序
翻譯： 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ū)動程序的 C 代碼中包含了幾乎所有 Kernel-mode Driver 都需要的基本代碼。我會盡量使該驅(qū)動向?qū)в懈玫目啥ㄖ菩浴Ｄ憧梢宰杂傻母南驅(qū)峁┑哪０逦募?。對于想保留原有代碼的人，下面的章節(jié)會為你提供該向?qū)У囊恍﹥?nèi)部細(xì)節(jié)的簡要介紹。
該向?qū)傻尿?qū)動模塊的進(jìn)入點(diǎn)是 DriverEntry() 。像所有的 Windows 2000 模塊的進(jìn)入點(diǎn)一樣，這個名字并不時必須的。你可以使用任何你喜歡的名稱，但是你必須告訴鏈接器你所使用的進(jìn)入點(diǎn)名稱，通過鏈接器的命令行選項(xiàng) /entry 可以做到這一點(diǎn)。對于前面提及的 TestDriver ，向?qū)б呀?jīng)很好的完成了這項(xiàng)工作。在 w2k_wiz.tp 模板或生成的 TestDrv.dsp 文件中，你會在鏈接器的命令行中找到 /entry:”DriverEntry@8” 這樣的字符串。 @8 后綴表示 DriverEntry() 接受 8 個字節(jié)的參數(shù)（這些參數(shù)位于棧中），這和 列表 3-1 提供的 DriverEntry() 的原型一致：兩個指針參數(shù)，每個占據(jù) 32 個位，共使用 64 個二進(jìn)制位，即 8 字節(jié)。
DriverEntry() 做的第一件事是調(diào)用 DriverInitialize() ，該函數(shù)將創(chuàng)建一個設(shè)備對象（ Device Object ）和該對象的一個符號鏈接（ Symbolic link ），在稍后你可能在用戶模式的程序中使用該符號鏈接來與設(shè)備通訊。要想找到 IoCreateDevice() 和 IoCreateSymbolicLink() 所使用的名字就有些許的困難，因?yàn)樗鼈兌际且蕾?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ū)ο蟮膬蓚€指針。你可以擴(kuò)展該結(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è)計(jì)，它保存了一個 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è)計(jì)允許單個應(yīng)用程序線程并行的管理多個 I/O 請求。 IRP 是一種數(shù)據(jù)結(jié)構(gòu)，包含描述一個 I/O 請求的完整信息。
具體的細(xì)節(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)中，這將允許在運(yùn)行時卸載該驅(qū)動程序。 DriverUnload() 函數(shù)只是簡單的銷毀由 DriverInitialize() 創(chuàng)建的所有對象（即設(shè)備對象和其符號鏈接）。在此之后，就可安全的將驅(qū)動程序從系統(tǒng)中移除。
每當(dāng)一個模塊要求驅(qū)動程序做出相應(yīng)時，就會調(diào)用 DriverDispatcher() 函數(shù)。因?yàn)?，?qū)動程序能夠處理多個設(shè)備， Dispatcher 首先檢查那個設(shè)備應(yīng)該響應(yīng)該請求。本書提供的驅(qū)動程序骨架僅維護(hù)了一個設(shè)備，因此，僅需要在初始化時檢查從 IoCreateDevice() 接受到的設(shè)備對象指針是否一致。如果一致， DriverDispatcher() 將接收到的 IRP 向前傳遞，給之前的 DriverDispatcher() 函數(shù)，隨之傳遞的還有 DriverInitialize() 準(zhǔn)備好的 Device Context 。當(dāng)你擴(kuò)展該驅(qū)動骨架以管理多個設(shè)備驅(qū)動程序時，你可能需要為每個設(shè)備編寫?yīng)毩⒌?IRP dispatcher 。 列表 3-3 中的 DeviceDispatcher() 函數(shù)只是一個示意性的實(shí)現(xiàn)，它僅能識別三種常見的請求： IRP_MJ_CREATE 、 IRP_MJ_CLEANUP 和 IRP_MJ_CLOSE ，并通過返回 STATUS_SUCCESS 來表示以處理該請求。這是使設(shè)備能夠正常打開、關(guān)閉的最小實(shí)現(xiàn)方式，對于其他的請求都將返回一個 STATUS_NOT_IMPLEMENTED 。
你可能想知道在 列表 3-3 的 DISCARDABLE FUNCTIONS 一節(jié)中出現(xiàn)的 #pragma alloc_text 的目的。 #pragma 指示符是將命令送往編譯器和鏈接器的有力手段。 alloc_text 命令表示將指定函數(shù)的代碼寫入可執(zhí)行文件的非默認(rèn) section 中。默認(rèn)情況下，所有程序代碼都位于 .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 所示。該文件沒有太大價值，因?yàn)樗鼉H引用了來自 DrvInfo.h 的宏 ----DRV_RC_VERSION 以及向?qū)峁┑膸讉€數(shù)據(jù)項(xiàng)來創(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ū)動程序骨架的資源腳本
網(wǎng)公網(wǎng)安備