共用方式為

根據範本撰寫通用 Windows 驅動程式 (KMDF)

  • 發行項

本主題描述如何使用 Kernel-Mode Driver Framework (KMDF) 撰寫 通用 Windows 驅動程式 。 您將從 Microsoft Visual Studio 範本開始，然後在不同的電腦上部署並安裝驅動程式。

繼續之前，您必須遵循 下載 Windows 驅動程式套件 (WDK) 中列出的安裝步驟。

當您安裝 WDK 時，會包含適用於 Windows 的偵錯工具。

建立和建置驅動程式

  1. 開啟 Microsoft Visual Studio。 在 [ 檔案] 功能表上，選擇 [ 新增 > 專案]。

  2. 在 [ 建立新專案 ] 對話框中，選取左下拉式清單中的 [C++ ]、選擇中間下拉式清單中的 [Windows ]，然後在右下拉式清單中選擇 [ 驅動程式 ]。

  3. 從項目類型清單中選取 [核心模式驅動程式] (KMDF) 。 選取 [下一步] 。

    [新增專案] 對話框的螢幕快照，其中顯示已選取的核心模式驅動程式。

  4. 在 [ 設定新專案 ] 對話框中，於 [ 項目名稱 ] 字段中輸入 “KmdfDriver”。

    注意

    當您建立新的 KMDF 或 UMDF 驅動程式時，您必須選取具有 32 個字元或更少字元的驅動程式名稱。 此長度限制定義於 wdfglobals.h 中。  

  5. 在 [ 位置] 欄位中，輸入您要在其中建立新項目的目錄。

  6. 勾選 [將方案和專案放在相同的目錄中 ]，然後選取 [ 建立]。

    專案組態對話框的螢幕快照。

    Visual Studio 會建立一個專案和方案。 您可以在 [方案總管] 視窗中查看這些檔案。 (如果看不到 方案總管 視窗，請從 [檢視] 功能表選擇 [方案總管]。) 解決方案有名為 KmdfDriver 的驅動程序專案。 若要查看驅動程式原始程式碼，請開啟 [原始程序檔] 底下的任何檔案。 Driver.c 和 Device.c 是很好的起點。

    顯示驅動程式項目中檔案的方案總管螢幕快照。

  7. 在 [方案總管] 視窗中，選取並按住 (，或以滑鼠右鍵按兩下 [) KmdfDriver]，然後選擇 [屬性]。 流覽至 [ 組態屬性 > 驅動程式設定 > ][一般]，並注意 [目標平臺 ] 預設為 [通用]。

  8. 若要建置驅動程式，請從 [建置] 功能表選擇 [建置方案]。 Microsoft Visual Studio 會在 [ 輸出 ] 視窗中顯示建置進度。 (如果看不到 [輸出] 視窗，請從 [檢視] 功能表選擇 [輸出]。)

    確認組建輸出包含：

    >    Driver is 'Universal'.

    當您確認已成功建置解決方案時，您可以關閉 Visual Studio。

  9. 若要查看內建驅動程式，請在 檔案總管 中移至您的 KmdfDriver 資料夾，然後移至 x64\Debug\KmdfDriver。 目錄包含下列檔案：

    • KmdfDriver.sys -- 核心模式驅動程序檔案
    • KmdfDriver.inf -- 安裝驅動程式時 Windows 使用的資訊檔案

部署驅動程式

一般而言，當您測試和偵錯驅動程式時，調試程式和驅動程式會在不同的計算機上執行。 執行調試程式的計算機稱為 主計算機，而執行驅動程式的計算機稱為 目標計算機。 目標計算機也稱為 測試計算機。 如需偵錯驅動程式的詳細資訊，請參閱 偵錯 Windows 工具。

到目前為止，您已使用 Visual Studio 在主電腦上建置驅動程式。 現在您需要設定目標計算機。

  1. 請遵循佈建 電腦以進行驅動程式部署和測試中的指示， (WDK 10) 。

    提示

    當您依照步驟使用網路纜線自動佈建目標計算機時，請記下埠和密鑰。 您稍後會在偵錯步驟中使用它們。 在此範例中，我們將使用 50000 作為埠，並使用 1.2.3.4 作為密鑰。

    在實際的驅動程序偵錯案例中，我們建議使用 KDNET 產生的密鑰。 如需如何使用 KDNET 產生隨機金鑰的詳細資訊，請參閱 偵錯驅動程式 - 逐步實驗室 (Sysvad 核心模式) 主題。

  2. 在主計算機上，在 Visual Studio 中開啟您的方案。 您可以在 KmdfDriver 資料夾中按兩下方案檔案KmdfDriver.sln。

  3. 在 [方案總管] 視窗中，選取並按住 (或以滑鼠右鍵按兩下 KmdfDriver 項目) ，然後選擇 [屬性]。

  4. 在 [ KmdfDriver 套件屬性頁 ] 視窗的左窗格中，移至 [ 組態屬性 > 驅動程序安裝 > 部署]。

  5. 在 部署之前，請檢查移除先前的驅動程式版本。

  6. 針對 [遠端電腦名稱]，選取您為測試和偵錯設定的計算機名稱。 在此練習中，我們使用名為 MyTestComputer 的計算機。

  7. 選取 [硬體標識符驅動程式更新]，然後輸入驅動程式的硬體識別碼。 在此練習中，硬體標識碼為 Root\KmdfDriver。 選取 [確定]。

    kmdfdriver 套件屬性頁視窗的螢幕快照，其中顯示已選取的部署驅動程式安裝

    注意

    在此練習中，硬體標識碼不會識別實際的硬體片段。 它會識別一個虛構的裝置，該 裝置會在裝置樹狀結構 中指定為根節點的子系。 針對實際硬體，請勿選取 [硬體標識符驅動程式更新] ;請改為選取 [安裝並驗證]。 您會在驅動程式的資訊中看到硬體識別碼， (INF) 檔案。 在 [方案總管] 視窗中，移至 [KmdfDriver > 驅動程序檔案]，然後按兩下 [KmdfDriver.inf]。 硬體標識碼位於 [Standard.NT$ARCH$]。

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. 在 [ 建置] 功能表上，選擇 [部署解決方案]。 Visual Studio 會自動將安裝及執行驅動程式所需的檔案複製到目標計算機。 這可能需要一兩分鐘。

    當您部署驅動程式時，驅動程式檔案會複製到測試計算機上的 %Systemdrive%\drivertest\drivers資料夾。 如果在部署期間發生錯誤，您可以檢查檔案是否複製到測試計算機。 確認 .inf、.cat、測試憑證和 .sys 檔案，以及任何其他必要檔案都存在於 %systemdrive%\drivertest\drivers 資料夾中。

    如需部署驅動程式的詳細資訊，請參閱 將驅動程式部署至測試計算機。

安裝驅動程式

將 KMDF 驅動程式部署至目標電腦後，現在您將安裝驅動程式。 當您先前使用 [自動 ] 選項布建目標計算機時，Visual Studio 會設定目標計算機，以在布建過程中執行測試已簽署的驅動程式。 現在，您只需要使用 DevCon 工具來安裝驅動程式。

  1. 在主計算機上，流覽至 WDK 安裝中的 [工具] 資料夾，並找出 DevCon 工具。 例如，查看下列資料夾：

    C：\Program Files (x86) \Windows Kits\10\Tools\x64\devcon.exe

    將 DevCon 工具複製到遠端電腦。

  2. 在目標電腦上，流覽至包含驅動程式檔案的資料夾，然後執行DevCon工具，以安裝驅動程式。

    1. 以下是您將用來安裝驅動程式之 devcon 工具的一般語法：

      devcon 安裝 <INF 檔案><硬體識別碼>

      安裝此驅動程式所需的 INF 檔案為 KmdfDriver.inf。 INF 檔案包含用來安裝驅動程式二進位檔的硬體識別碼， KmdfDriver.sys。 回想一下，位於 INF 檔案中的硬體識別碼是 Root\KmdfDriver。

    2. 以系統管理員身分開啟命令提示字元視窗。 瀏覽至您的驅動程式套件資料夾，然後輸入下列命令：

      devcon install kmdfdriver.inf root\kmdfdriver

      如果您收到無法辨識 devcon 的錯誤訊息，請嘗試將路徑新增至 devcon 工具。 例如，如果您將其複製到目標計算機上名為 C：\Tools 的資料夾，請嘗試使用下列命令：

      c：\tools\devcon install kmdfdriver.inf root\kmdfdriver

      隨即會出現對話框，指出測試驅動程式是未簽署的驅動程式。 選取 [繼續安裝此驅動程式 ]。

      驅動程式安裝警告的螢幕快照。

偵錯驅動程式

既然您已在目標電腦上安裝 KMDF 驅動程式，您將會從主電腦遠端連結調試程式。

  1. 在主電腦上，以系統管理員身分開啟命令提示字元視窗。 變更為 WinDbg.exe 目錄。 我們將使用 Windows 驅動程式套件 (WDK) 安裝作為 Windows 套件安裝一部分的 x64version WinDbg.exe。 以下是 WinDbg.exe 的預設路徑：

    C：\Program Files (x86) \Windows Kits\10\Debuggers\x64

  2. 使用下列命令啟動 WinDbg 以連線到目標電腦上的核心偵錯會話。 埠和金鑰的值應該與您用來佈建目標電腦的值相同。 我們將針對埠使用 50000 ，而 1.2.3.4 用於索引鍵，也就是我們在部署步驟期間所使用的值。 k 旗標表示這是核心偵錯會話。

    WinDbg -k net：port=50000，key=1.2.3.4

  3. 在 [ 偵錯] 功能表上，選擇 [ 中斷]。 主電腦上的調試程式會中斷至目標計算機。 在 [ 調試程式命令 ] 視窗中，您可以看到核心偵錯命令提示字元： kd>。

  4. 此時，您可以在 kd> 提示字元中輸入命令，以實驗調試程式。 例如，您可以嘗試下列命令：

  5. 若要讓目標計算機再次執行，請從 [偵錯] 功能表選擇 [移至]，或按 “g”，然後按 [enter]。

  6. 若要停止偵錯會話，請選擇 [偵錯] 功能表中的 [中斷鏈接偵錯]。

    重要

    請務必使用 「go」 命令讓目標計算機在結束調試程式之前再次執行，或者目標計算機仍不會回應滑鼠和鍵盤輸入，因為它仍在與調試程式交談。

如需驅動程式偵錯程式的詳細逐步解說，請參閱 偵錯通用驅動程式 - 逐步執行實驗室 (Echo Kernel-Mode) 。

如需遠端偵錯的詳細資訊，請參閱 使用 WinDbg 進行遠端偵錯。

使用驅動程式模組架構 (DMF)

驅動程式模組架構 (DMF) 是 WDF 的延伸模組，可為 WDF 驅動程式開發人員啟用額外的功能。 它可協助開發人員更快速地撰寫任何類型的 WDF 驅動程式。

DMF 做為架構，允許建立稱為 DMF 模組的 WDF 物件。 這些 DMF 模組的程式代碼可以在不同的驅動程式之間共用。 此外，DMF 會組合我們針對驅動程式開發的 DMF 模組連結庫，而且感覺會對其他驅動程式開發人員提供價值。

DMF 不會取代 WDF。 DMF 是搭配 WDF 使用的第二個架構。 利用 DMF 的開發人員仍會使用 WDF 及其所有基本類型來撰寫設備驅動器。

如需詳細資訊，請參閱 驅動程式模組架構 (DMF) 。