여러 버전의 Windows용 WDF 드라이버 빌드

2025-03-25

WDF를 사용하면 항상 드라이버를 한 번 빌드하고 여러 버전의 Windows에서 결과 이진 파일을 사용할 수 있지만 Windows 10 버전 1803(Redstone 4) 이전에는 "이전 버전에서 빌드하고 최신 버전에서 실행"으로 제한되었습니다. Windows 10 버전 1803부터 WDF는 조건부 실행의 추가 혜택과 함께 "최신 빌드, 이전 버전에서 실행"을 추가합니다. 요약:

기존: 이전 버전의 프레임워크로 빌드된 바이너리는 주 버전이 일치할 경우, 최신 버전의 프레임워크가 포함된 Windows 버전에서도 실행됩니다. 예를 들어 KMDF 1.9(Windows 7)로 빌드된 드라이버는 Windows 8 시스템(KMDF 1.11)에서 실행됩니다. 이 예제에서 드라이버는 KMDF 1.9의 기능으로 제한됩니다.
추가된: Windows 10 버전 1803의 KMDF 버전 1.25 및 UMDF 버전 2.25부터 최신 프레임워크 버전을 사용하여 드라이버를 빌드할 수 있으며, 결과 드라이버 이진 파일은 이전 버전의 Windows에서 실행됩니다(최소 Windows 10 버전 1803). 또한 드라이버는 최신 프레임워크 버전에서만 사용할 수 있는 기능을 조건부로 사용할 수 있습니다.

즉, 드라이버는 항상 그렇듯이 이후 버전의 Windows에서 실행될 뿐만 아니라 이전 버전에서 Windows 10 버전 1803으로 다시 실행됩니다.

이 작업을 수행하는 단계는 Visual Studio에서 빌드 설정을 지정하고, API를 호출하기 전에 런타임 검사를 수행하거나 있거나 없을 수 있는 구조 또는 필드에 액세스하는 것입니다.

참고: 이 기능은 선택 사항이며 드라이버는 최신 WDF 기능이 없는 이전 버전의 Windows에서 로드 가능한 상태로 유지하면서 최신 WDF 기능을 사용하는 드라이버만 빌드하도록 설정해야 합니다.

부 버전(대상 버전) 또는 버전 부 버전(최소 필수)설정하지 않으면 버전 관리가 이전과 동일하게 유지됩니다.

필요한 최소값 지정

Visual Studio의 새 구성 설정은 다음과 같습니다.

KMDF 버전 하위 버전(최소 필요)
UMDF 버전 부 버전(최소 필요)

이 변경에 따라 두 기존 설정의 이름이 업데이트되었습니다.

KMDF 버전 마이너 ->KMDF 버전 마이너 (대상 버전)
UMDF 마이너 버전 ->UMDF 마이너 버전(대상 버전)

최소 필수 설정하지 않으면 Visual Studio는 대상 버전 이상용으로 빌드되며, 하향 지원을 제공하지 않습니다. 이전 버전의 몇몇 속성과 동작이 일치합니다.

필요한 최소 설정하면 다음 요구 사항이 적용됩니다.

25 <= 최소 필수 <= 대상 버전
구성 속성->드라이버 설정->일반에서 _NT_TARGET_VERSION를 RS4(0x0A000005) 이상으로 설정합니다.

기능이 있는지 확인

존재할 수도 있고 없을 수도 있는 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 속성에 대한 자세한 내용은 드라이버 프로젝트 대한드라이버 모델 설정 속성을 참조하세요.

다음을 통해 공유

여러 버전의 Windows용 WDF 드라이버 빌드

필요한 최소값 지정

기능이 있는지 확인

피드백

추가 리소스