建置適用於多個 Windows 版本的 WDF 驅動程式
WDF 一律可讓您建置驅動程式一次,並在多個 Windows 版本上使用產生的二進位檔,但在 Windows 10 版本 1803(Redstone 4)之前,這僅限於「在較舊版本上建置,在較新的版本上執行」。從 Windows 10 版本 1803 開始,WDF 會新增「以較新版本為基礎建置,在較舊版本上執行」,並具有條件式執行的額外優點。 總結:
- #B0 現有的 #A1:使用舊版架構所建置的二進位檔可在包含較新架構版本的 Windows 上執行,但前提是主要版本相符。 例如,使用 KMDF 1.9 (Windows 7) 建置的驅動程式會在 Windows 8 系統上執行 (KMDF 1.11)。 在此範例中,驅動程式受限於 KMDF 1.9 的功能。
- #B0 新增 #A1:從 Windows 10 1803 版開始的 KMDF 1.25 版和 UMDF 2.25 版起,您可以使用較新的架構版本建置驅動程式,並使產生的驅動程式二進位檔可在較早版本的 Windows 上執行(至少在 Windows 10 1803 版)。 此外,驅動程式可以有條件地使用只能在較新的架構版本中使用的功能。
這表示您的驅動程式不僅會在未來的 Windows 版本上執行,因為它一如既往,也會在舊版上執行,回到 Windows 10 版本 1803。
執行此動作有兩個步驟:在 Visual Studio 中指定組建設定,並在叫用 API 或存取可能不存在的結構或字段之前執行運行時間檢查。
#B0 附註 #A1:此功能是選擇性的,驅動程式應該只啟用它來建置使用最新 WDF 功能的驅動程式,同時在沒有最新 WDF 功能的舊版 Windows 上仍可載入。
如果您未設定 次要版本(目標版本) 或 次要版本(最低必要),版本控制將維持與之前相同。
Visual Studio 中的新組態設定如下:
- KMDF 次要版本(最低要求)
- UMDF 次要版本號(最低需求)
根據這項變更,已更新兩個現有設定的名稱:
- KMDF 次版本 - KMDF 次版本(目標版本)
- UMDF 次要版本 - UMDF 次要版本(目標版本)
如果您未設定最低需求,Visual Studio 會建置目標版本及更高版本,而不會提供向下支援。 這與舊次要版本屬性的行為相符。
如果您設定最低需求,下列要求將適用:
- 25 #B0 = 最低必要 #B1 = 目標版本
- 在「#B0 組態屬性-#A1 驅動程式設定-#A2 一般」中,將
_NT_TARGET_VERSION
設定為0x0A000005
(RS4)或更新版本。
在每次使用可能不存在的 API、結構或成員之前,您必須呼叫下列其中一個巨集,這些巨集定義於 WdfFuncEnum.h:
BOOLEAN
WDF_IS_FUNCTION_AVAILABLE (
FunctionName
);
BOOLEAN
WDF_IS_STRUCTURE_AVAILABLE (
StructName
);
BOOLEAN
WDF_IS_FIELD_AVAILABLE (
StructName,
FieldName
);
請考慮下列範例。 當 WDF v29 發行時,它會新增一個新的 API:WdfSomeNewFeature。 如果您將 目標版本 設為 29,最低必要 為 25,則產生的驅動程式會在 25 到 29 的任何架構版本上載入,只要主要版本未變更,就會呼叫 25 版 API,如同以前的做法,並在每次呼叫任何 v29 API 之前進行以下檢查:
if (WDF_IS_FUNCTION_AVAILABLE(WdfSomeNewFeature)) {
WdfSomeNewFeature();
}
如果您沒有執行條件式檢查,您可能會看到下列內容:
- 如果 API 傳回 NTSTATUS,呼叫會傳回失敗碼。
- 如果 API 傳回 NTSTATUS 以外的任何值:
- KMDF:系統偵錯檢查。
- UMDF:WudfHost 進程因 DriverStop 錯誤而當機。
- 如果已啟用驅動程式驗證器,驅動程式也會當機。 這有助於識別測試環境中的問題。
- 無提示記憶體損毀(存取結構或欄位時)。
驅動程式當機包含失敗的驅動程式名稱、架構名稱和失敗的 API 索引。 您可以查閱 WdfFuncEnum.h 中的 WDFFUNCENUM 值來擷取 API 的名稱。
如需 WDF 中 Visual Studio 屬性的詳細資訊,請參閱「驅動程式專案的驅動程式模型設定屬性」。