Dela via

Använda WPP Software Tracing i UMDF-drivrutiner

  • Artikel

WPP-programspårning möjliggör att du kan lägga till spårningsmeddelanden som hjälper dig att felsöka din drivrutin. Dessutom innehåller ramverkets händelseloggare hundratals spårningsmeddelanden som du kan visa.

Du kan visa spårningsmeddelanden med hjälp av TraceView eller Tracelog. Du kan också skicka spårningsmeddelanden till en kerneldebugger.

Lägga till spårningsmeddelanden i din drivrutin

Om du vill lägga till spårningsmeddelanden i din ramverksbaserade drivrutin måste du:

  • Lägg till ett #include-direktiv i var och en av drivrutins källfilerna som innehåller något av WPP-makrona. Det här direktivet måste identifiera en TMH-fil (trace message header). Filnamnet måste ha formatet <driver-source-file-name>.tmh.

    Om drivrutinen till exempel består av två källfiler som heter MyDriver1.c och MyDriver2.cmåste MyDriver1.c innehålla:

    #include "MyDriver1.tmh"

    och MyDriver2.c måste innehålla:

    #include "MyDriver2.tmh"

    När du skapar drivrutinen i Microsoft Visual Studio genererar WPP-förprocessorn .tmh-filerna.

  • Definiera ett WPP_CONTROL_GUIDS makro i en rubrikfil. Det här makrot definierar ett GUID och spårningsflaggor för din drivrutins spårningsmeddelanden. (För var och en av WDK:ns UMDF-baserade exempeldrivrutiner innehåller internal.h-huvudfilen det här makrot.)

  • Inkludera ett WPP_INIT_TRACING makro i din drivrutins DllMain-rutin. Det här makrot aktiverar spårning av programvara i drivrutinen. (För var och en av WDK:s UMDF-baserade exempeldrivrutiner innehåller rubrikfilen DllSup.h det här makrot.)

  • Inkludera ett WPP_CLEANUP makro i drivrutinens DllMain-rutin. Det här makrot inaktiverar spårning av programvara i drivrutinen. (För var och en av WDK:s UMDF-baserade exempeldrivrutiner innehåller rubrikfilen DllSup.h det här makrot.)

  • Använd DoTraceMessage makro, eller en anpassad version av makrot, i drivrutinen för att skapa spårningsmeddelanden. (För var och en av WDK:ns UMDF-baserade exempeldrivrutiner innehåller internal.h-huvudfilen ett anpassat makro.)

  • Öppna egenskapssidorna för drivrutinsprojektet. Högerklicka på drivrutinsprojektet i Solution Explorer och välj Egenskaper. I egenskapssidorna för drivrutinen väljer du Konfigurationsegenskaperoch sedan Wpp. Under menyn Allmänt anger du Kör WPP-spårning till Ja. Under menyn Filalternativ bör du även ange ramverkets WPP-mallfil, till exempel:

    {km-WdfDefault.tpl}*.tmh

Mer information om hur du lägger till spårningsmeddelanden i drivrutinen finns i Lägga till WPP-makron i en drivrutin.

Exempeldrivrutiner som använder spårning av WPP-programvara

Alla UMDF-baserade exempeldrivrutiner i WDK tillhandahåller filerna DllSup.h, Internal.h och Sources som aktiverar spårning av WPP-programvara. De flesta av dessa exempeldrivrutiner använder också ett anpassat makro för att skapa spårningsmeddelanden.

Visa drivrutins spårningsmeddelanden

Om du har lagt till spårningsmeddelanden i drivrutinen är drivrutinen en spårningsprovider. Du kan använda en spårningskontrollant, till exempel Tracelog, för att styra en spårningssession och skapa en spårningslogg. Du kan använda en spårningskonsument, till exempel Tracefmt, för att visa meddelandena.

Mer information om hur du använder programspårningsverktygen finns i Survey of Software Tracing Tools.

Visa UMDF-spårningsloggen

UMDF-loggfilen finns i %ProgramData%*\\Microsoft\\WDF.

Du kan visa UMDF-loggfilen med hjälp av antingen TraceView eller Tracelog. Båda verktygen kräver TMF-filer (trace message format) som formaterar spårningsloggens meddelanden. TMF-filerna är tillgängliga i WDK under underkatalogen \tools\tracing. (I TraceView visas UMDF som en namngiven provider med namnet "UMDF-Framework Trace" eller "Framework Trace", beroende på UMDF-versionen.)

WDF-kontrollanten kan du skicka spårningsmeddelanden till både UMDF-spårningsloggen och kernelfelsökaren. (Du bör inte skicka spårningsmeddelanden till kernelfelsökaren med hjälp av alternativet -kd i Tracelogeftersom Tracelog kan störa spårningsloggning i UMDF.)

Du kan också använda tillägget !wmitrace felsökningsprogram för att visa spårningsmeddelandena i felsökningsprogrammet:

  1. I WinDbg ansluter du till instansen av WUDFHost som är värd för drivrutinen. Mer information finns i Aktivera felsökning av en UMDF-drivrutin.

  2. Om drivrutinen använder version 1.11 eller senare och du använder kernelfelsökaren från Windows 8 eller senare kan du hoppa över det här steget. Om drivrutinen använder en tidigare version av UMDF än 1.11 använder du !wmitrace.tmffile eller !wmitrace.searchpath för att ange en plattformsspecifik spårningsmeddelandeformatfil (.tmf) eller en sökväg till en .tmf-fil. .tmf-filerna finns i plattformsspecifika underkataloger i WDK.

  3. Använd kommandot !wmitrace.logdump för att visa innehållet i spårningsbuffertarna:

    !wmitrace.logdump WudfTrace

Kontrollera spårningsmeddelanden

Du kan styra UMDF-spårningsmeddelanden med användargränssnittet som WDF-kontrollant tillhandahåller, eller genom att ändra registervärden. Du bör använda WDF-kontrollanten-gränssnittet när det är möjligt, eftersom registervärdena kan ändras i framtida versioner av UMDF. Dessutom bör du inte komma åt dessa värden i INF-filer eller din drivrutinskod.

För närvarande kan du ändra följande registervärden som finns under registernyckeln HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF:

  • Värdet LogEnable styr om UMDF skapar en spårningslogg för din drivrutin. Om det här värdet är inställt på 1 skapar UMDF en spårningslogg.

  • Värdet LogLevel styr mängden information som UMDF-spårningsmeddelanden innehåller. Standardvärdet för LogLevel är 3, vilket gör att UMDF-spårningsmeddelanden innehåller fel- och varningsmeddelanden. Ange det här värdet till 7 för att inkludera fel- och varningsmeddelanden, plus informationsmeddelanden som inte är fel. Ange den till 15 för att inkludera all spårningsinformation som UMDF kan tillhandahålla.

  • Värdet LogKd styr om UMDF skickar spårningsmeddelanden till kernelfelsökaren. Om LogKd- är inställt på 1 skickar UMDF sina spårningsmeddelanden till kernelfelsökaren.

  • Värdet LogFlushPeriodSeconds anger hur ofta spårningsmeddelanden skrivs till spårningsloggen på några sekunder.

  • Värdet LogMinidumpType innehåller flaggor som anger vilken typ av information som en minidumpfil ska innehålla om den skapas. Mer information om dessa flaggor finns i MINIDUMP_TYPE uppräkning.

Du kan hitta fler registervärden under registernyckeln HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF. Du bör inte ändra dessa värden.