共用方式為

教學課程：根據範本撰寫通用 Windows 驅動程式 （KMDF）

本主題描述如何使用 Kernel-Mode Driver Framework （KMDF） 撰寫 通用 Windows 驅動程式。 您將從 Microsoft Visual Studio 範本開始，然後在另一台電腦上部署及安裝驅動程式。

先決條件

  • 請遵循步驟來安裝 Windows 驅動程式套件 （WDK）。 當您安裝 WDK 時，會包含適用於 Windows 的 偵錯工具。

  • 安裝 Visual Studio 2022。 當您安裝 Visual Studio 2022 時，請選取具有 C++ 工作負載的 Desktop 開發，然後在 [個別元件] 底下 新增：

    • MSVC v143 - VS 2022 C++ ARM64/ARM64EC Spectre 漏洞緩解的函式庫（最新）
    • MSVC v143 - VS 2022 C++ x64/x86 Spectre 緩解函式庫（最新）
    • 使用最新的 v143 組建工具和 Spectre 風險降低功能的 C++ ATL（ARM64/ARM64EC）
    • 最新 v143 編譯工具 C++ ATL，配有 Spectre 風險降低功能（x86 & x64）
    • C++ MFC 使用適用於 Spectre 脆弱性緩解措施的最新 v143 編譯工具 (ARM64/ARM64EC)
    • 最新 v143 版建置工具的 C++ MFC，具有 Spectre 緩解措施（x86 & x64）
    • Windows 驅動程式套件

建立和建置驅動程式

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

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

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

    新項目對話框的螢幕快照，其中顯示已選取核心模式驅動程式。

    提示

    如果您在 Visual Studio 中找不到驅動程式專案範本，WDK Visual Studio 擴充功能並未正確安裝。 若要解決此問題，請啟動 Visual Studio Installer、選取 [修改]、在 [個別 元件] 索引卷標中新增 [Windows 驅動程式套件]，然後選取 [修改]。

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

    注意

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

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

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

    項目組態對話框的螢幕快照。

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

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

  7. 在 [方案總管] 視窗中，選取並按住 [KmdfDriver]，然後選擇 [[屬性]。 流覽至 [設定屬性] > [驅動程序設定] > [一般]，請注意，目標平臺 預設為 Universal。

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

    確認組建輸出包含：

    >    Driver is 'Universal'.

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

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

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

部署驅動程式

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

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

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

    提示

    當您依照步驟自動使用網路纜線佈建目標計算機時，請記下埠和密鑰。 您稍後會在偵錯步驟中使用它們。 在此範例中，我們將使用 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、test cert 和 .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。 請注意，硬體識別碼 Root\KmdfDriver位於 INF 文件中。

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

      devcon 安裝 kmdfdriver.inf root\kmdfdriver

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

      c：\tools\devcon 安裝 kmdfdriver.inf root\kmdfdriver

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

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

偵錯驅動程式

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

  1. 在主電腦上，以系統管理員身分開啟命令提示字元視窗。 變更為 WinDbg.exe 目錄。 我們將使用作為 Windows 套件安裝一部分的 Windows 驅動程式開發工具包（WDK）中安裝的 x64 版本 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. 若要讓目標計算機再次執行，請 從 [偵錯] 功能表選擇 [Go]，或按 “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）。

  • Last updated on