다음을 통해 공유

추적 로깅을 위한 IFR(Inflight Trace Recorder)

  • 아티클

IFR(Inflight Trace Recorder) 은 커널 모드 드라이버 또는 UMDF 드라이버와 같은 추적 공급자가 최신 로그 메시지가 유지되는 메모리 내 순환 버퍼 집합을 만들 수 있는 추적 기능입니다. 로그 메시지는 디버거를 사용하여 볼 수 있습니다.

IFR은 WPP 소프트웨어 추적을 기반으로 빌드됩니다. WPP를 통해 IFR의 주요 이점은 자동으로 켜지고 추적 세션을 미리 시작할 필요가 없다는 것입니다.

적용 대상:

  • 최소 OS: KMDF 및 WDM 드라이버 개발자를 위한 Windows 8
  • 최소 OS: UMDF(2.15) 드라이버 개발자를 위한 Windows 10

Visual Studio에서 Inflight 추적 레코더를 사용하도록 설정하는 방법

먼저 Windows 드라이버에 WPP 소프트웨어 추적 추가의 단계를 수행합니다.

다음으로 프로젝트 속성 페이지의 구성 속성-WPP 추적 함수>> 및 매크로 옵션->실행 중 추적 레코더 사용에서예를 선택합니다.

마지막으로 UMDF의 경우 WPP 추적 함수 및 매크로 옵션->>전처리기 정의에서 를 추가WPP_MACRO_USE_KM_VERSION_FOR_UM=1합니다.

명령줄에서 Inflight 추적 레코더를 사용하도록 설정하는 방법

.vcxproj 파일을 수동으로 편집하는 경우 다음 항목을 설정합니다.

KMDF 또는 WDM 드라이버의 경우:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

UMDF 드라이버의 경우:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

Inflight 추적 레코더 매개 변수를 구성하는 방법

드라이버의 매개 변수 키 아래에 다음 선택적 레지스트리 항목을 설정하여 IFR을 구성할 수 있습니다.

다음 레지스트리 항목을 사용합니다.

LogPages: REG_DWORD

기본 로그를 저장할 페이지 수로 설정합니다. 기본값은 1개입니다.

VerboseOn: REG_DWORD

기본 설정이 0이면 IFR에서 오류, 경고 및 정보 이벤트를 기록합니다. 로그에 자세한 정보 표시 출력을 추가하려면 1로 설정합니다.

WppRecorder_UseTimeStamp: REG_DWORD (WDK 빌드 22557부터 사용 가능)

드라이버는 !rcdrkd.rcdrlogdump 또는 !wdfkd.wdflogdump를 사용하여 볼 수 있는 로그 항목에 타임스탬프를 추가하기 위해 이 항목을 하나로 설정합니다.

WppRecorder_PreciseTimeStamp: REG_DWORD (WDK 빌드 22557부터 사용 가능)

WppRecorder_UseTimeStamp 외에도 더 정확한 타임스탬프를 원하는 경우 위에 표시된 것과 동일한 구문을 사용하여 WppRecorder_PreciseTimeStamp 추가합니다.

예제

다음 예제에서는 시작 및 끝 주석 사이에 줄을 추가하여 로그 페이지 수를 2로 설정하고 타임스탬프를 켭니다.

커널 모드 드라이버의 경우:

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

UMDF 드라이버의 경우:

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

기본 로그에 추적 메시지를 보내는 방법

Windows 드라이버에 WPP 소프트웨어 추적 추가의 지침을 따릅니다. 예를 들면 다음과 같습니다.

  • DriverEntry에서 를 호출합니다WPP_INIT_TRACING(DriverObject, RegistryPath).
  • EvtDriverUnload에서 를 호출합니다WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

이제 드라이버는 필요에 따라 추적 함수를 자유롭게 호출할 수 있습니다. 예: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

자세한 내용은 WPP_INIT_TRACING 및 WPP_CLEANUP 참조하세요.

사용자 지정 로그에 추적 메시지를 보내는 방법

이는 커널 모드 드라이버(KMDF 또는 WDM)에만 적용됩니다.

대부분의 드라이버에서는 단일 기본 로그가 충분합니다. 그러나 일부 시나리오에서는 고유한 엔터티에 대해 별도의 로그 버퍼를 사용하는 것이 유용합니다.

예를 들어 버스 드라이버를 작성할 때 각 자식 디바이스에 자체 버퍼가 있어야 할 수 있습니다. 그런 다음 디버거를 사용하여 특정 자식 디바이스에 대한 로그만 덤프할 수 있습니다.

사용자 지정 로그를 설정하려면 드라이버에 가 포함되어 <WppRecorder.h>야 합니다. 그런 다음, 다음 API를 호출합니다.

또한 드라이버는 로그 핸들을 첫 번째 매개 변수로 사용하는 새 추적 매크로를 정의해야 합니다. 예제는 토스터 샘플 드라이버를 참조하세요.

사용자 지정 로그에 타임스탬프 정보를 추가하는 방법

드라이버가 WppRecorderLogCreate 를 호출하여 추가 로그 핸들을 만드는 경우 일부 로그 핸들에 대해 타임스탬프를 사용하도록 설정할 수 있지만 다른 로그 핸들에는 타임스탬프를 사용하도록 설정할 수 없습니다.

이렇게 하려면 타임스탬프를 사용해야 하는 각 로그 핸들의 드라이버 코드에 한 줄을 추가해야 합니다. 코드 예제는 WppRecorderLogCreate를 참조하세요.

참고

이 기능은 WDK 빌드 22557부터 사용할 수 있습니다. 특정 릴리스를 대상으로 하는 방법에 대한 자세한 내용은 다양한 버전의 Windows용 드라이버 빌드를 참조하세요.

디버거에서 추적 메시지를 보는 방법

KMDF 및 UMDF 드라이버의 경우 평소와 같이 !wdfkd.wdflogdump 를 사용합니다. 프레임워크 IFR 로그와 드라이버 IFR 로그를 모두 출력합니다.

WDM 드라이버의 경우 !rcdrkd.rcdrloglist 및 !rcdrkd.rcdrlogdump를 사용합니다.