Udostępnij przez

Inflight Trace Recorder (IFR) do rejestrowania śladów

pl-PL: Inflight Trace Recorder (IFR) to funkcja śledzenia, która umożliwia dostawcy śledzenia, takiemu jak sterownik trybu jądra lub sterownik UMDF, do utworzenia zestawu cyklicznych buforów w pamięci, w których są zachowywane najnowsze komunikaty dziennika. Komunikaty dziennika można wyświetlać przy użyciu debugera.

IFR jest oparty na śledzeniu oprogramowania WPP. Główną zaletą IFR w porównaniu do WPP jest to, że jest on włączony automatycznie i nie trzeba rozpoczynać sesji śledzenia z wyprzedzeniem.

Dotyczy:

  • Minimalny system operacyjny: System Windows 8 dla deweloperów sterowników KMDF i WDM
  • Minimalny system operacyjny: Windows 10 dla deweloperów sterowników UMDF (2.15)

Jak włączyć narzędzie Inflight Trace Recorder w programie Visual Studio

Najpierw wykonaj kroki opisane w temacie Dodawanie funkcji śledzenia oprogramowania WPP do sterownika systemu Windows.

Następnie na stronie właściwości projektu, w obszarze Właściwości konfiguracji->WPP Tracing->Funkcja i Opcje Makr->Włącz rejestrator śledzenia inflight, wybierz pozycję Tak.

Na koniec, tylko dla UMDF, istnieje jeden dodatkowy krok: w obszarze Śledzenie WPP->Funkcje i Opcje Makra->Definicje preprocesora, dodaj WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Jak włączyć narzędzie Inflight Trace Recorder z poziomu wiersza polecenia

Jeśli ręcznie edytujesz plik .vcxproj, ustaw następujące wpisy:

W przypadku sterownika KMDF lub WDM:

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

W przypadku sterownika UMDF:

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

Jak skonfigurować parametry rejestratora śledzenia w locie

IfR można skonfigurować, ustawiając następujące opcjonalne wpisy rejestru w kluczu parametru sterownika.

Użyj następujących wpisów rejestru:

LogPages: REG_DWORD

Ustaw wartość na liczbę stron do przechowywania dziennika domyślnego. Wartość domyślna to jeden.

VerboseOn: REG_DWORD

Domyślne ustawienie zera powoduje, że IFR rejestruje błędy, ostrzeżenia i zdarzenia informacyjne. Ustaw na jeden, aby dodać szczegółowe dane wyjściowe do dziennika.

WppRecorder_UseTimeStamp: REG_DWORD (dostępne począwszy od kompilacji WDK 22557)

Sterowniki ustawiają ten wpis na jeden, aby dodać znaczniki czasu do wpisów dziennika, które są następnie widoczne przy użyciu !rcdrkd.rcdrlogdump lub !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp: REG_DWORD (dostępne począwszy od kompilacji WDK 22557)

Jeśli chcesz uzyskać bardziej precyzyjne znaczniki czasu, oprócz WppRecorder_UseTimeStamp, dodaj WppRecorder_PreciseTimeStamp przy użyciu tej samej składni pokazanej powyżej.

Przykłady

W poniższych przykładach dodaj wiersze między komentarzami początkowymi i końcowymi, aby ustawić liczbę stron dziennika na dwie i włączyć znaczniki czasu.

W przypadku sterownika trybu jądra:

[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

W przypadku sterownika 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

Jak wysyłać komunikaty śledzenia do dziennika domyślnego

Postępuj zgodnie z instrukcjami w temacie Dodawanie śledzenia oprogramowania WPP do sterownika systemu Windows. Przykład:

Teraz sterownik może wywołać funkcję śledzenia zgodnie z potrzebami. Przykład: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Aby uzyskać więcej informacji, zobacz WPP_INIT_TRACING i WPP_CLEANUP.

Jak wysyłać komunikaty śledzenia do niestandardowego dziennika

Dotyczy to tylko sterowników trybu jądra (KMDF lub WDM).

W przypadku większości sterowników pojedynczy dziennik domyślny jest wystarczająco dobry. Jednak w niektórych scenariuszach warto mieć oddzielne dziennika dla odrębnych jednostek.

Na przykład, pisząc sterownik magistrali, możesz chcieć, aby każde urządzenie podrzędne miało swój własny bufor. Następnie możesz użyć debugera, aby wygenerować tylko dziennik dla określonego urządzenia podrzędnego.

Aby skonfigurować dzienniki niestandardowe, sterownik musi zawierać element <WppRecorder.h>. Następnie wywołaj następujące interfejsy API:

Sterownik musi również zdefiniować nowe makro śledzenia, które przyjmuje uchwyt dziennika jako pierwszy parametr. Aby zapoznać się z przykładem, zobacz Przykładowy sterownik tostera.

** Jak dodać informacje dotyczące znacznika czasu do dziennika niestandardowego

Jeśli sterownik wywołuje funkcję WppRecorderLogCreate aby utworzyć dodatkowe uchwyty dziennika, można włączyć znaczniki czasu dla niektórych uchwytów dziennika, ale nie dla innych.

Aby to zrobić, należy dodać pojedynczy wiersz do kodu sterownika dla każdego uchwytu dziennika, który powinien używać znaczników czasu. Aby zapoznać się z przykładem kodu, zobacz WppRecorderLogCreate.

Uwaga / Notatka

Ta funkcja jest dostępna od wersji 22557 zestawu WDK. Aby uzyskać informacje na temat celowania w określoną wersję, zobacz Kompilowanie sterowników dla różnych wersji systemu Windows.

Jak wyświetlać komunikaty śledzenia w debugerze

W przypadku sterowników KMDF i UMDF użyj !wdfkd.wdflogdump jak zwykle. Zostanie wyświetlony zarówno dziennik IFR struktury, jak i dziennik IFR sterownika.

W przypadku sterowników WDM użyj !rcdrkd.rcdrloglist oraz !rcdrkd.rcdrlogdump.

  • Last updated on