Udostępnij przez

Używanie funkcji śledzenia oprogramowania WPP w sterownikach UMDF

Oprogramowanie do śledzenia WPP umożliwia dodawanie komunikatów śledzenia, które ułatwiają debugowanie sterownika. Ponadto rejestrator zdarzeń platformy udostępnia setki komunikatów śledzenia, które można wyświetlić.

Komunikaty śledzenia można wyświetlać przy użyciu TraceView lub Tracelog. Możesz również wysyłać komunikaty śledzenia do debugera jądra.

Dodawanie komunikatów śledzenia do sterownika

Aby dodać komunikaty śledzenia do sterownika opartego na strukturze, musisz:

  • Dodaj dyrektywę #include do każdego pliku źródłowego sterownika zawierającego dowolne makra programu WPP. Ta dyrektywa musi identyfikować plik nagłówka komunikatów śledzenia (TMH) . Nazwa pliku musi mieć format <driver-source-file-name.tmh>.

    Jeśli na przykład sterownik składa się z dwóch plików źródłowych o nazwie MyDriver1.c i MyDriver2.c, MyDriver1.c musi zawierać:

    #include "MyDriver1.tmh"

    i MyDriver2.c musi zawierać

    #include "MyDriver2.tmh"

    Podczas tworzenia sterownika w programie Microsoft Visual Studio preprocesor WPP generuje pliki tmh.

  • Zdefiniuj makro WPP_CONTROL_GUIDS w pliku nagłówkowym. To makro definiuje identyfikator GUID oraz flagi i do śledzenia komunikatów sterownika. (Dla każdego przykładowego sterownika opartego na UMDF z zestawu WDK, plik nagłówka Internal.h zawiera to makro.)

  • Uwzględnij makro WPP_INIT_TRACING w procedurze DllMain sterownika. To makro aktywuje śledzenie działania oprogramowania w sterowniku. (Dla każdego z przykładowych sterowników UMDF zestawu WDK plik nagłówkowy DllSup.h zawiera to makro).

  • Uwzględnij makro WPP_CLEANUP w procedurze DllMain sterownika. Makro to dezaktywuje śledzenie oprogramowania w twoim sterowniku. (Dla każdego z przykładowych sterowników UMDF zestawu WDK plik nagłówkowy DllSup.h zawiera to makro).

  • Użyj makra DoTraceMessage lub dostosowanej wersji makra w swoim sterowniku, aby utworzyć komunikaty śledzenia. Plik nagłówka Internal.h dla każdego z przykładowych sterowników UMDF zestawu WDK zawiera spersonalizowane makro.

  • Otwórz strony właściwości dla projektu sterownika. Kliknij prawym przyciskiem na projekcie sterownika w Eksploratorze rozwiązań i wybierz pozycję Właściwości. Na stronach właściwości sterownika wybierz pozycję Właściwości konfiguracji, a następnie pozycję Wpp. W menu Ogólne ustaw opcję Uruchom śledzenie WPP jako Tak. W menu Opcje plików należy również określić plik szablonu frameworka WPP, na przykład:

    {km-WdfDefault.tpl}*.tmh

Aby uzyskać więcej informacji na temat dodawania komunikatów diagnostycznych do sterownika, zobacz Dodawanie makr WPP do sterownika.

Przykładowe sterowniki korzystające z śledzenia oprogramowania WPP

Wszystkie przykładowe sterowniki oparte na funkcji UMDF w zestawie WDK udostępniają pliki DllSup.h, Internal.h i Sources, które umożliwiają śledzenie oprogramowania WPP. Większość z tych przykładowych sterowników używa również dostosowanego makra do tworzenia komunikatów śledzenia.

Wyświetlanie komunikatów diagnostyki sterownika

Jeśli do sterownika dodano komunikaty śledzenia, sterownik jest dostawcą śledzenia. Kontroler śledzenia, taki jak Tracelog, umożliwia kontrolowanie sesji śledzenia i tworzenie dziennika śledzenia. Aby wyświetlić komunikaty, możesz użyć konsumenta śledzenia, takiego jak Tracefmt.

Aby uzyskać więcej informacji na temat używania narzędzi do śledzenia oprogramowania, zobacz Survey of Software Tracing Tools (Ankieta dotycząca narzędzi do śledzenia oprogramowania).

Wyświetlanie dziennika śledzenia UMDF

Plik dziennika UMDF znajduje się w folderze %ProgramData%*\\Microsoft\\WDF.

Plik dziennika UMDF można wyświetlić przy użyciu elementu TraceView lub Tracelog. Oba narzędzia wymagają plików formatu komunikatów śledzenia (TMF), które formatują komunikaty dziennika śledzenia. Pliki TMF są dostępne w zestawie narzędzi WDK w podkatalogu \tools\tracing. (W usłudze TraceView UMDF pojawia się jako nazwany dostawca o nazwie "UMDF-Framework Trace" albo "Framework Trace", w zależności od wersji UMDF).

WDF weryfikator pozwala na wysyłanie komunikatów śledzenia zarówno do dziennika śledzenia UMDF, jak i debugera jądra. (Nie należy wysyłać komunikatów śledzenia do debugera jądra przy użyciu opcji -kd w usłudze Tracelog, ponieważ usługa Tracelog może zakłócać rejestrowanie śledzenia w ramach funkcji UMDF).

Możesz również użyć rozszerzenia debugera !wmitrace , aby wyświetlić komunikaty śledzenia w debugerze:

  1. W systemie WinDbg połącz się z instancją WUDFHost, która obsługuje sterownik. Aby uzyskać więcej informacji, zobacz Jak włączyć debugowanie sterownika UMDF.

  2. Jeśli sterownik używa wersji 1.11 lub nowszej i korzystasz z debugera jądra z systemu Windows 8 lub nowszego, możesz pominąć ten krok. Jeśli sterownik używa wersji UMDF starszej niż 1.11, użyj pliku !wmitrace.tmffile lub !wmitrace.searchpath , aby określić plik komunikatu śledzenia specyficznego dla platformy (.tmf) lub ścieżkę do pliku tmf. Pliki .tmf znajdują się w podkatalogach specyficznych dla platformy w zestawie WDK.

  3. Użyj polecenia !wmitrace.logdump, aby wyświetlić zawartość buforów śledzenia.

    !wmitrace.logdump WudfTrace

Kontrolowanie komunikatów śledzenia

Możesz kontrolować komunikaty śledzenia UMDF za pomocą interfejsu użytkownika, który udostępnia WDF Verifier, lub modyfikując wartości rejestru. W miarę możliwości należy użyć interfejsu WDF Verifier , ponieważ wartości rejestru mogą ulec zmianie w przyszłych wersjach funkcji UMDF. Ponadto nie należy uzyskiwać dostępu do tych wartości w plikach INF ani kodzie sterownika.

Obecnie można zmodyfikować następujące wartości rejestru znajdujące się w kluczu rejestru HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF :

  • Wartość LogEnable określa, czy usługa UMDF tworzy dziennik śledzenia dla sterownika. Jeśli ta wartość jest ustawiona na 1, funkcja UMDF tworzy dziennik śledzenia.

  • Wartość LogLevel steruje ilością informacji, które zawierają komunikaty śledzenia UMDF. Wartość domyślna elementu LogLevel to 3, co powoduje, że komunikaty śledzenia UMDF zawierają komunikaty o błędach i ostrzeżeniach. Ustaw tę wartość na 7, aby uwzględnić komunikaty o błędach i ostrzeżeniach oraz komunikaty informacyjne niezwiązane z błędami. Ustaw wartość 15, aby uwzględnić wszystkie informacje śledzenia, które mogą być zapewniane przez usługę UMDF.

  • Wartość LogKd określa, czy usługa UMDF wysyła komunikaty śledzenia do debugera jądra. Jeśli wartość LogKd jest ustawiona na 1, funkcja UMDF wysyła komunikaty śledzenia do debugera jądra.

  • Wartość LogFlushPeriodSeconds określa częstotliwość zapisywania komunikatów śledzenia w dzienniku śledzenia w sekundach.

  • Wartość LogMinidumpType zawiera flagi określające typ informacji, które będą zawierać plik mini-zrzutu, jeśli zostanie utworzony. Aby uzyskać więcej informacji na temat tych flag, zobacz wyliczenie MINIDUMP_TYPE .

Więcej wartości rejestru można znaleźć w kluczu rejestru HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF . Nie należy modyfikować tych wartości.

  • Last updated on