Inflight Trace Recorder (IFR) a nyomkövetések naplózásához

Az Inflight Trace Recorder (IFR) egy nyomkövetési funkció, amely lehetővé teszi, hogy egy nyomkövetési szolgáltató ( például kernel módú illesztőprogram vagy UMDF-illesztőprogram) memóriabeli körkörös puffereket hozzon létre, ahol a legújabb naplóüzenetek megmaradnak. A naplóüzenetek hibakeresővel tekinthetők meg.

Az IFR a WPP-szoftverkövetésre épül. Az IFR elsődleges előnye a WPP-vel szemben, hogy automatikusan aktiválódik, és nem szükséges előre elindítani a nyomkövetési munkameneteket.

A következőkre vonatkozik:

  • Minimális operációs rendszer: Windows 8 KMDF- és WDM-illesztőprogram-fejlesztőknek
  • Minimális operációs rendszer: Windows 10 UMDF (2.15) illesztőprogram-fejlesztőknek

Az Inflight Trace Recorder engedélyezése a Visual Studióban

Először kövesse a WPP-szoftverkövetés Windows-illesztőprogramhoz való hozzáadásának lépéseit.

Ezután a Project tulajdonságlapján, a Configuration Properties-WPP> Tracing-Function> and Macro Options-Enable> Inflight Trace Recorder területen válassza az Igen lehetőséget.

Végül csak az UMDF esetében van még egy lépés: a WPP nyomkövetési – Funkció és Makróbeállítások – Előfeldolgozási definíciók területen adja hozzá WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Az Inflight Trace Recorder engedélyezése a parancssorból

Ha manuálisan szerkessze a .vcxproj fájlt, állítsa be a következő bejegyzéseket:

KMDF- vagy WDM-illesztő esetén:

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

UMDF-illesztőprogram esetén:

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

Inflight Trace Recorder-paraméterek konfigurálása

Az IFR konfigurálásához állítsa be a következő választható beállításjegyzék-bejegyzéseket az illesztőprogram paraméterkulcsa alatt.

Használja a következő beállításjegyzék-bejegyzéseket:

LogPages: REG_DWORD

Állítsa be az alapértelmezett napló tárolásához használt oldalak számát. Az alapértelmezett érték az egyik.

VerboseOn: REG_DWORD

A nulla alapértelmezett beállítása miatt az IFR naplózza a hibákat, figyelmeztetéseket és tájékoztató eseményeket. Állítsa be az egyiket, hogy részletes kimenetet adjon a naplóhoz.

WppRecorder_UseTimeStamp: REG_DWORD (a WDK 22557-es buildjében érhető el)

Az illesztőprogramok ezt a bejegyzést úgy állítják be, hogy időbélyegeket adjanak a naplóbejegyzésekhez, amelyek ezután megtekinthetők a !rcdrkd.rcdrlogdump vagy a !wdfkd.wdflogdump használatával.

WppRecorder_PreciseTimeStamp: REG_DWORD (a WDK 22557-es buildjében érhető el)

Ha pontosabb időbélyegeket szeretne, a WppRecorder_UseTimeStamp mellett adjon hozzá WppRecorder_PreciseTimeStamp a fent látható szintaxissal.

Példák

Az alábbi példákban adja hozzá a kezdő és a záró megjegyzés közötti sorokat a naplólapok számának két értékre történő beállításához és az időbélyegek bekapcsolásához.

Kernel módú illesztőprogram esetén:

[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-illesztőprogram esetén:

[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

Nyomkövetési üzenetek küldése az alapértelmezett naplóba

Kövesse a WPP-szoftverkövetés Windows-illesztőprogramhoz való hozzáadására vonatkozó utasításokat. Például:

  • A DriverEntry-ben hívja meg a WPP_INIT_TRACING(DriverObject, RegistryPath) függvényt.
  • Az EvtDriverUnload eseményben hívja meg a WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)) függvényt.

Most az illesztőprogram igény szerint hívhatja meg a nyomkövetési függvényt. Például: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

További információ: WPP_INIT_TRACING és WPP_CLEANUP.

Nyomkövetési üzenetek küldése egyéni naplóba

Ez csak a kernel módú illesztőprogramokra (KMDF vagy WDM) vonatkozik.

Az illesztőprogramok többsége számára az egyetlen alapértelmezett napló elég jó. Bizonyos esetekben azonban hasznos, ha különálló naplópufferekkel rendelkezik a különböző entitásokhoz.

Például egy buszvezető írásakor előfordulhat, hogy minden gyermekeszköznek saját pufferrel kell rendelkeznie. Ezután használhatja a hibakeresőt, hogy kimentsük csak az adott al-eszköz naplóját.

Egyéni naplók beállításához az illesztőnek tartalmaznia kell a(z) <WppRecorder.h> elemet. Ezután hívja meg a következő API-kat:

Az illesztőnek egy új nyomkövetési makrót is definiálnia kell, amely az első paraméterként a naplókezelőt használja. Például lásd a Kenyérpirító mintaillesztőprogramját.

Időbélyegadatok hozzáadása egyéni naplókhoz

Ha az illesztőprogram meghívja a WppRecorderLogCreate-ot , hogy hozzon létre további naplóleírókat, engedélyezheti az időbélyegeket egyes naplóleírókhoz, másokhoz azonban nem.

Ehhez egyetlen sort kell hozzáadnia az illesztőkódhoz minden olyan naplóleíróhoz, amely időbélyegeket használ. Példakód: WppRecorderLogCreate.

Megjegyzés:

Ez a funkció a WDK 22557-es buildjében érhető el. Egy adott kiadás megcélzásával kapcsolatos információkért lásd: Illesztőprogramok készítése a Windows különböző verzióihoz.

Nyomkövetési üzenetek megtekintése a hibakeresőben

KMDF- és UMDF-illesztőprogramok esetén a szokásos módon használja a !wdfkd.wdflogdump parancsot. A keretrendszer IFR-naplója és az illesztőprogram IFR-naplója is ki lesz nyomtatva.

WDM-illesztőprogramok esetén használja a !rcdrkd.rcdrloglist és a !rcdrkd.rcdrlogdump parancsot.

  • Last updated on