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

아티클
04/06/2023

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

기능이 있는지 확인

존재할 수도 있고 없을 수도 있는 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 드라이버 빌드

필요한 최소값 지정

기능이 있는지 확인

피드백

추가 리소스