Sdílet prostřednictvím

Záznamník trasování za letu (IFR) pro protokolování trasování

Inflight Trace Recorder (IFR) je funkce trasování, která umožňuje zprostředkovateli trasování, jako je ovladač režimu jádra nebo ovladač UMDF, vytvořit sadu cyklických vyrovnávacích pamětí v paměti, kde jsou uchovávány nejnovější zprávy protokolu. Zprávy protokolu lze zobrazit pomocí ladicího programu.

IFR je založen na trasování softwaru WPP. Hlavní výhodou IFR oproti WPP je, že je zapnutá automaticky a nemusíte předem spouštět relace trasování.

platí pro:

  • Minimální operační systém: Windows 8 pro vývojáře ovladačů KMDF a WDM
  • Minimální operační systém: Windows 10 pro vývojáře ovladačů UMDF (2.15)

Jak povolit záznamník trasování za letu v aplikaci Visual Studio

Nejprve postupujte podle kroků v Přidání trasování softwaru WPP do ovladače systému Windows.

Dále na stránce vlastností projektu, v části Vlastnosti konfigurace - WPP Tracing - Funkce a možnosti maker - Povolit záznamník trasování za letu, vyberte Ano.

Pro pouze UMDF existuje jeden další krok: v části WPP Tracing-Function> and Macro Options-Preprocessor> Definitions, add WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Jak povolit Inflight Trace Recorder z příkazového řádku

Pokud soubor .vcxproj upravíte ručně, nastavte následující položky:

Pro ovladač KMDF nebo WDM:

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

Pro ovladač UMDF:

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

Jak nakonfigurovat parametry záznamníku trasování za letu

IFR můžete nakonfigurovat nastavením následujících volitelných položek registru pod klíčem parametru ovladače.

Použijte následující položky registru:

LogPages: REG_DWORD

Nastavte na počet stránek pro uložení výchozího protokolu. Výchozí hodnota je jedna.

VerboseOn: REG_DWORD

Výchozí nastavení nuly způsobí, že IFR zaznamená chyby, upozornění a informační události. Nastavte na hodnotu jedna, aby se do logu přidal podrobný výstup.

WppRecorder_UseTimeStamp: REG_DWORD (dostupné od sestavení WDK 22557)

Ovladače nastaví tuto položku na jednu pro přidání časových razítek do položek protokolu, které lze zobrazit pomocí !rcdrkd.rcdrlogdump nebo !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp: REG_DWORD (dostupné od sestavení WDK 22557)

Pokud chcete přesnější časová razítka, přidejte kromě WppRecorder_UseTimeStampWppRecorder_PreciseTimeStamp pomocí stejné syntaxe uvedené výše.

Příklady

V následujících příkladech přidejte řádky mezi počáteční a koncové komentáře, abyste nastavili počet stránek protokolu na dva a zapnuli časové razítko.

Pro ovladač v režimu 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

Pro ovladač 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

Odesílání trasovacích zpráv do výchozího protokolu

Postupujte podle pokynů v Přidání softwarového trasování WPP do ovladače systému Windows. Například:

  • Ve DriverEntry použijte funkci WPP_INIT_TRACING(DriverObject, RegistryPath).
  • V EvtDriverUnload zavolejte WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Nyní je ovladač volný pro volání funkce trasování podle potřeby. Příklad: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Další informace najdete v tématu WPP_INIT_TRACING a WPP_CLEANUP.

Odesílání trasovacích zpráv do vlastního protokolu

To platí jenom pro ovladače režimu jádra (KMDF nebo WDM).

Pro většinu ovladačů je jediný výchozí protokol dostatečně dobrý. Ale v některých scénářích je užitečné mít samostatné vyrovnávací paměti protokolu pro různé entity.

Například při psaní ovladače sběrnice můžete chtít, aby každé podřízené zařízení mělo vlastní vyrovnávací paměť. Ladicí program pak můžete použít k výpisu pouze protokolu pro konkrétní podřízené zařízení.

Chcete-li nastavit vlastní protokoly, musí ovladač obsahovat <WppRecorder.h>. Pak volejte následující rozhraní API:

Ovladač musí také definovat nové trasovací makro, které má jako první parametr popisovač protokolu. Příklad najdete v ukázkovém ovladači toustovače.

Přidání informací o časovém razítku do vlastního protokolu

Pokud ovladač volá WppRecorderLogCreate k vytvoření dalších popisovačů protokolu, je možné povolit časové razítka pro některé popisovače protokolu, ale ne pro jiné.

K tomu je potřeba přidat jeden řádek do kódu ovladače pro každý popisovač protokolu, který by měl používat časová razítka. Příklad kódu naleznete v tématu WppRecorderLogCreate.

Poznámka:

Tato funkce je dostupná od sestavení WDK 22557. Informace o cílení na konkrétní verzi najdete v tématu Sestavování ovladačů pro různé verze Windows.

Jak zobrazit trasovací zprávy v ladicím programu

Pro ovladače KMDF a UMDF použijte jako obvykle !wdfkd.wdflogdump . Vytiskne protokol IFR rozhraní i protokol IFR ovladače.

Pro ovladače WDM použijte !rcdrkd.rcdrloglist a !rcdrkd.rcdrlogdump.

  • Last updated on