共用方式為

如何撰寫第一個 USB 用戶端驅動程式 (KMDF)

  • 發行項

在本文中，您將使用 Microsoft Visual Studio 提供的 USB Kernel-Mode 驅動程式 範本，撰寫簡單的核心模式驅動程序架構， (KMDF) 型用戶端驅動程式。 建置並安裝客戶端驅動程序之後，您會在 裝置管理員 中檢視用戶端驅動程式，並在調試程式中檢視驅動程序輸出。

如需範本所產生原始程式碼的說明，請參閱 瞭解 USB 用戶端驅動程式的 KMDF 範本程式碼。

必要條件

若要開發、偵錯及安裝核心模式驅動程式，您需要兩部計算機：

  • 執行 Windows 7 或更新版本的 Windows 作業系統的主電腦。 主計算機是您開發環境，您可以在其中撰寫和偵錯驅動程式。
  • 執行 Windows Vista 或更新版本的 Windows 的目標電腦。 目標電腦具有您要偵錯的核心模式驅動程式。

開始之前，請確定您符合下列需求：

軟體需求

  • 主電腦裝載開發環境，並具有 Visual Studio。
  • 主電腦具有最新的 Windows 驅動程式套件 (WDK) 。 套件包含標頭、連結庫、工具、檔和偵錯工具，以及開發、建置和偵錯 KMDF 驅動程式所需的偵錯工具。 若要取得最新版本的 WDK，請參閱 下載 Windows 驅動程式套件 (WDK) 。
  • 主電腦有適用於 Windows 的最新版本偵錯工具。 您可以從 WDK 取得最新版本，也可以 下載並安裝適用於 Windows 的偵錯工具。
  • 您的目標電腦正在執行 Windows Vista 或更新版本的 Windows。
  • 您的主機和目標計算機已設定為核心偵錯。 如需詳細資訊，請參閱 在Visual Studio中設定網路連線。

硬體需求

取得您要撰寫用戶端驅動程式的 USB 裝置。 在大部分情況下，您會提供USB裝置及其硬體規格。 規格描述裝置功能和支援的廠商命令。 使用規格來判斷 USB 驅動程式的功能，以及相關的設計決策。

如果您不熟悉 USB 驅動程式開發，請使用 OSR USB FX2 學習套件來研究 WDK 隨附的 USB 範例。 您可以從 OSR Online 取得學習套件。 它包含 USB FX2 裝置，以及實作用戶端驅動程式所需的所有硬體規格。

您也可以取得 Microsoft USB 測試工具 (MUTT) 裝置。 MUTT 硬體可從 JJG 技術購買。 裝置未安裝韌體。 若要安裝韌體，請從 此網站 下載 MUTT 軟體套件，然後執行 MUTTUtil.exe。 如需詳細資訊，請參閱套件隨附的檔。

步驟 1：使用 Visual Studio USB 驅動程式範本產生 KMDF 驅動程式程式代碼

如需產生 KMDF 驅動程式程式代碼的指示，請參閱 根據範本撰寫 KMDF 驅動程式中的步驟。

針對 USB 特定程式代碼，請在 Visual Studio 中選取下列選項：

  1. 在 [ 新增專案] 對話框的頂端搜尋方塊中，輸入 USB。
  2. 在中間窗格中，選取 [核心模式驅動程式]、[USB (KMDF) ]。
  3. 選取 [下一步] 。
  4. 輸入專案名稱、選擇儲存位置，然後選取 [ 建立]。

下列螢幕快照顯示USB Kernel-Mode 驅動程式範本的 [新增專案] 對話方塊。

visual Studio 新項目選項。

visual Studio 新項目選項第二個畫面。

本文假設 Visual Studio 專案的名稱是 「MyUSBDriver_」。 其中包含下列檔案：

檔案 Description
Public.h 提供與 USB 裝置通訊的用戶端驅動程式和使用者應用程式共用的通用宣告。
<項目名稱>.inf 包含在目標電腦上安裝客戶端驅動程式所需的資訊。
Trace.h 宣告追蹤函式和宏。
Driver.h;Driver.c 宣告並定義驅動程序進入點和事件回呼例程。
Device.h;Device.c 宣告並定義準備硬體事件的事件回呼例程。
Queue.h;Queue.c 宣告並定義架構佇列物件所引發之事件的事件回呼例程。

步驟 2：修改 INF 檔案以新增裝置的相關信息

在建置驅動程式之前，您必須使用裝置的相關信息來修改範本 INF 檔案，特別是硬體識別符字串。

在 方案總管 的 [驅動程序檔案] 底下，按兩下 INF 檔案。

在 INF 檔案中，您可以提供資訊，例如製造商和提供者名稱、裝置安裝類別等等。 您必須提供的資訊之一是裝置的硬體識別碼。

若要提供硬體識別元字串：

  1. 將您的 USB 裝置連結至主電腦，並讓 Windows 列舉裝置。

  2. 開啟 裝置管理員 並開啟裝置的屬性。

  3. 在 [詳細數據] 索引標籤上，選取 [屬性] 底下的 [硬式標識符]。

    裝置的硬體識別碼會顯示在清單框中。 選取並按住 (或以滑鼠右鍵按兩下) ，然後複製硬體標識符字串。

  4. 以您的硬體識別碼字串取代下一行中的USB\VID_vvvv&PID_pppp。

    [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

步驟 3：建置 USB 用戶端驅動程式程式代碼

若要建置驅動程式：

  1. 在 Visual Studio 中開啟驅動程式專案或方案
  2. 選取並按住 (，或以滑鼠右鍵按兩下 ) 方案總管 中的解決方案，然後選取 [Configuration Manager]。
  3. 從 Configuration Manager 中，選取 [作用中方案組態] (，例如[偵錯] 或 [發行) ] 和 [作用中解決方案平臺] (，例如，對應至您感興趣的組建類型的 Win32) 。
  4. 從 [建置] 功能表中，選取 [建置解決方案]。

如需詳細資訊，請參閱 建置驅動程式。

步驟 4：設定計算機進行測試和偵錯

若要測試和偵錯驅動程式，您可以在主電腦上和目標計算機上的驅動程式上執行調試程式。 到目前為止，您已在主計算機上使用 Visual Studio 來建置驅動程式。 接下來，您需要設定目標計算機。 若要設定目標計算機，請遵循布建 計算機以進行驅動程式部署和測試中的指示。

步驟 5：啟用核心偵錯的追蹤

範本程式代碼包含數個追蹤訊息 (TraceEvents) ，可協助您追蹤函式呼叫。 原始程式碼中的所有函式都包含追蹤訊息，可標記例程的進入和結束。 針對錯誤，追蹤訊息包含錯誤碼和有意義的字串。 因為已啟用驅動程式專案的 WPP 追蹤，所以建置程式期間建立的 PDB 符號檔包含追蹤訊息格式設定指示。 如果您設定 WPP 追蹤的主電腦和目標電腦，驅動程式可以將追蹤訊息傳送至檔案或調試程式。

若要設定主電腦以進行 WPP 追蹤：

  1. 從 PDB 符號檔擷取追蹤訊息格式指示，以 (TMF) 檔案建立追蹤訊息格式。

    您可以使用 Tracepdb.exe 來建立TMF檔案。 此工具位於 WDK 的安裝資料夾>Windows Kits\10.0\bin\<architecture> 資料夾中。< 下列命令會建立驅動程序專案的TMF檔案。

    tracepdb -f <PDBFiles> -p <TMFDirectory>

    -f 選項會指定 PDB 符號檔的位置和名稱。 -p 選項會指定 Tracepdb 所建立之 TMF 檔案的位置。 如需詳細資訊，請參閱 Tracepdb 命令。

    在指定的位置，您會看到專案中每個 .c 檔案 (三個檔案) 。 它們會指定 GUID 檔名。

  2. 在除錯程式中，輸入下列命令：

    1. .load Wmitrace

      載入 Wmitrace.dll 延伸模組。

    2. 。鏈

      確認已載入調試程式擴充功能。

    3. ！wmitrace.searchpath +<TMF 檔案位置>

      將TMF檔案的位置新增至調試程式的搜尋路徑。

      輸出看起來會像這樣：

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

若要設定目標電腦進行 WPP 追蹤：

  1. 請確定您的目標電腦上有 Tracelog 工具。 此工具位於 WDK 的 install_folder>Windows Kits\8.0\Tools\<arch> 資料夾中。< 如需詳細資訊，請參閱 Tracelog 命令語法。

  2. 開啟 命令視窗 ，並以系統管理員身分執行。

  3. 輸入以下命令：

    tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

    此命令會啟動名為 MyTrace 的追蹤作業階段。

    guid 自變數會指定追蹤提供者的 GUID，這是客戶端驅動程式。 您可以在 Visual Studio Professional 2019 專案中從 Trace.h 取得 GUID。 另一個選項是輸入下列命令，並在 .guid 檔案中指定 GUID。 檔案包含連字元格式的 GUID：

    tracelog -start MyTrace -guid c：\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

    您可以輸入下列命令來停止追蹤工作階段：

    tracelog -stop MyTrace

步驟 6：在目標計算機上部署驅動程式

  1. 在 [方案總管] 視窗中，選取並按住 (或以滑鼠右鍵按兩下) *項目名稱>*<套件 ]，然後選擇 [屬性]。
  2. 在左窗格中，流覽至 [ 組態屬性 > 驅動程式安裝 > 部署]。
  3. 核取 [啟用部署]，然後核取 [匯入驅動程式存放區]。
  4. 針對 [遠端電腦名稱]，指定目標計算機的名稱。
  5. 選取 [安裝並驗證]。
  6. 選取 [確定]。
  7. 在 [ 偵 錯] 功能表上，選擇 [ 開始偵錯]，或在鍵盤上按 F5 。

注意

請勿在 [硬體標識符驅動程式更新] 底下指定裝置的硬體識別碼。 硬體標識碼只能在驅動程式的資訊 (INF) 檔案中指定。

如需在 Visual Studio 中將驅動程式部署至目標系統的詳細資訊，請參閱 將驅動程式部署至測試電腦。

您也可以使用 裝置管理員，在目標計算機上安裝驅動程式。 如果您要從命令提示字元安裝驅動程式，可以使用下列公用程式：

  • PnPUtil

    此工具隨附於 Windows。 它位於 Windows\System32 中。 您可以使用此公用程式將驅動程式新增至驅動程式存放區。

    C:\>pnputil /a m:\MyDriver_.inf
Microsoft PnP Utility

Processing inf : MyDriver_.inf
Driver package added successfully.
Published name : oem22.inf

    如需詳細資訊，請參閱 PnPUtil 範例。

  • DevCon Update

    此工具隨附於 WDK。 您可以使用它來安裝及更新驅動程式。

    devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6

步驟 7：在 裝置管理員 中檢視驅動程式

  1. 輸入下列命令以開啟 裝置管理員：

    devmgmt

  2. 確認 裝置管理員 顯示下列節點的節點：

    範例

    MyUSBDriver_Device

步驟 8：在調試程式中檢視輸出

Visual Studio 會先在 [ 輸出 ] 視窗中顯示進度。 然後它會開啟 調試程式即時運算視窗。 確認追蹤訊息出現在主電腦上的調試程式中。 輸出看起來應該像這樣，其中 「MyUSBDriver_」 是驅動程式模組的名稱：

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit