《Undocumented Windows 2000 Secrets》翻譯 --- 第三章（2）
第三章 編寫內核模式驅動程序
翻譯： Kendiv
更新： Tuesday, February 08, 2005
作為補充這里給出 DrvInfo.h 的內容：
// __________________________________________________________
//
// 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 給出的驅動程序的 C 代碼中包含了幾乎所有 Kernel-mode Driver 都需要的基本代碼。我會盡量使該驅動向導有更好的可定制性。你可以自由的更改向導提供的模板文件。對于想保留原有代碼的人，下面的章節會為你提供該向導的一些內部細節的簡要介紹。
該向導生成的驅動模塊的進入點是 DriverEntry() 。像所有的 Windows 2000 模塊的進入點一樣，這個名字并不時必須的。你可以使用任何你喜歡的名稱，但是你必須告訴鏈接器你所使用的進入點名稱，通過鏈接器的命令行選項 /entry 可以做到這一點。對于前面提及的 TestDriver ，向導已經很好的完成了這項工作。在 w2k_wiz.tp 模板或生成的 TestDrv.dsp 文件中，你會在鏈接器的命令行中找到 /entry:”DriverEntry@8” 這樣的字符串。 @8 后綴表示 DriverEntry() 接受 8 個字節的參數（這些參數位于棧中），這和 列表 3-1 提供的 DriverEntry() 的原型一致：兩個指針參數，每個占據 32 個位，共使用 64 個二進制位，即 8 字節。
DriverEntry() 做的第一件事是調用 DriverInitialize() ，該函數將創建一個設備對象（ Device Object ）和該對象的一個符號鏈接（ Symbolic link ），在稍后你可能在用戶模式的程序中使用該符號鏈接來與設備通訊。要想找到 IoCreateDevice() 和 IoCreateSymbolicLink() 所使用的名字就有些許的困難，因為它們都是依賴 DrvzInfo.h （位于本書光盤的 srccommoninclude 目錄）中的宏定義。如果你想更多的了解這個技巧，請參考 TestDrv.h （前面的 列表 3-4 已列出）中的 PROGRAM IDENTIFICATION 一節，并跟蹤形如 DRV_* 的定義，它們以多種方式成組的出現在 DrvInfo.h 中。例如，一個完整的 VERSIONINFO 資源就是由多個小的宏構成的。在別處，還定義了 DRV_DEVICE 和 DRV_LINK 常量，在這里，它們分別等價于 DeviceTestDrv 和 DosDeviceTestDrv 。注意，很多內核 API 函數，如 IoCreateDevice() 和 IoCreateSymbolickLinke() 不接受一個以零結尾的字符串，僅支持一個特殊的結構體 ---UNICODE_STRING ，該結構在第二章已經介紹過， 列表 3-5 再次給出了該結構的定義。定義于 DrvInfo.h 中的宏 ----PRESET_UNICODE_STRING （應用于 TestDrv.c 的 GLOBAL DATA Section ）從一個簡單的 Unicode 字符串常量創建出一個靜態的 UNICODE_STRING 結構。這是針對 UNICODE_STRING 結構的一個方便的速記符號。
在成功的創建完設備對象及其符號鏈接后， DriverInitialize() 將設備對象指針和設備上下文（ Device Context ）的指針保存在一個靜態全局變量中。 Device Context 是設備的一個私有結構，該結構可以有任意的大小和結構。本書提供的驅動程序骨架附帶了一個簡單的 DEVICE_CONTEXT 結構，該結構定義于 TestDrv.h 中。該結構僅包含分別指向設備和設備驅動程序對象的兩個指針。你可以擴展該結構來保存設備驅動程序所特有的數據。系統針對驅動程序接收到的每個 I/O 請求包（ I/O Request Packet, IRP ）提供相應的 Device Context 。
在 DriverInitialize() 成功完成并返回后， DriverEntry() 將建立一個重要的數組，該數組由系統傳入，并做為驅動程序對象結構 ----pDriverObject 的一部分。該數組為驅動程序期望的所有 IRP 提供空間，同時 DriverEntry() 還為所有希望得到控制的 IRP 寫入對應的 CallBack 函數的指針。本書提供的驅動程序骨架遵循此種設計，它保存了一個 DriverDispatcher() 指針，并提供了可存放 28 個 IRP 的空間，如 表 3-2 所示。稍后， DriverDispatcher() 將決定需要注意那些類型的 IRP ，并針對所有不感興趣的 IRP 返回 STATUS_NOT_IMPLEMENTED 。需要注意的是， Windows NT 和 Windows 2000 的 IRP 處理例程數組的布局有一些微妙的差別。在 表 3-2 中，這種差別以黑體標識出來。
譯注：
在 Windows NT 中，大多數的 I/O 請求都是用 I/O 請求包（ IRP ）來表示的。在多數情況下， I/O 請求包可以從一個 I/O 系統組件轉移到另一組件。這種設計允許單個應用程序線程并行的管理多個 I/O 請求。 IRP 是一種數據結構，包含描述一個 I/O 請求的完整信息。
具體的細節，請參考《 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 結構： 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. 數組中的每個 I/O 請求包的比較
在 IRP 數組建立好之后， DriverEntry() 將自己的 CallBack 函數 ----DriverUnload() 寫入驅動程序對象結構中，這將允許在運行時卸載該驅動程序。 DriverUnload() 函數只是簡單的銷毀由 DriverInitialize() 創建的所有對象（即設備對象和其符號鏈接）。在此之后，就可安全的將驅動程序從系統中移除。
每當一個模塊要求驅動程序做出相應時，就會調用 DriverDispatcher() 函數。因為，驅動程序能夠處理多個設備， Dispatcher 首先檢查那個設備應該響應該請求。本書提供的驅動程序骨架僅維護了一個設備，因此，僅需要在初始化時檢查從 IoCreateDevice() 接受到的設備對象指針是否一致。如果一致， DriverDispatcher() 將接收到的 IRP 向前傳遞，給之前的 DriverDispatcher() 函數，隨之傳遞的還有 DriverInitialize() 準備好的 Device Context 。當你擴展該驅動骨架以管理多個設備驅動程序時，你可能需要為每個設備編寫獨立的 IRP dispatcher 。 列表 3-3 中的 DeviceDispatcher() 函數只是一個示意性的實現，它僅能識別三種常見的請求： IRP_MJ_CREATE 、 IRP_MJ_CLEANUP 和 IRP_MJ_CLOSE ，并通過返回 STATUS_SUCCESS 來表示以處理該請求。這是使設備能夠正常打開、關閉的最小實現方式，對于其他的請求都將返回一個 STATUS_NOT_IMPLEMENTED 。
你可能想知道在 列表 3-3 的 DISCARDABLE FUNCTIONS 一節中出現的 #pragma alloc_text 的目的。 #pragma 指示符是將命令送往編譯器和鏈接器的有力手段。 alloc_text 命令表示將指定函數的代碼寫入可執行文件的非默認 section 中。默認情況下，所有程序代碼都位于 .text section 。然而，指示符 #pragma alloc_text(INIT,DriverEntry) 將使 DriverEntry() 的代碼保存在一個新的 section----INIT 中。驅動加載器可以識別這種指定的 section ，并在初始化之后丟掉該 section 。 DriverEntry() 和它的幫助函數 DriverInitialize() 僅在驅動程序啟動時會被調用一次；因此，當它們完成自己的工作后，就可安全的將它們從內存中移除。
現在驅動程序骨架就只剩下了資源腳本 ---TestDrv.rc ，如 列表 3-6 所示。該文件沒有太大價值，因為它僅引用了來自 DrvInfo.h 的宏 ----DRV_RC_VERSION 以及向導提供的幾個數據項來創建一個 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. 驅動程序骨架的資源腳本
網公網安備