ACD-Protokollierung und -Debugging
Dieses Thema enthält Informationen zum Protokollieren, Nachverfolgen und Debuggen der ACX-Audioklassenerweiterungen.
ACX-Treiberprotokollierung
Die Softwareablaufverfolgung für Treiber basiert in der Regel auf der Ereignisablaufverfolgung für Windows (Event Tracing for Windows, ETW), einer Einrichtung auf Kernelebene, die Ablaufverfolgungsmeldungen für Kernelmodus- und Benutzermodusprozesse protokolliert. Da ACX-Treiber WDF-Treiber sind, stehen alle WDF-Protokollierungs- und Ereignisfunktionen für ACX-Treiberentwickler zur Verfügung.
WPP
Da die Verwendung von ETW etwas kompliziert sein kann, nutzen die meisten Treiberentwickler den Windows Software Trace Preprocessor (WPP), der den Prozess der Instrumentierung eines Treibers für die ETW-Ablaufverfolgung vereinfacht und verbessert.
ACX verwendet WPP-Protokolle für die Ablaufverfolgung und das Debuggen. Weitere Informationen finden Sie unter Verwenden der WPP-Softwareablaufverfolgung in KMDF-Treibern und Hinzufügen der WPP-Softwareablaufverfolgung zu einem Windows-Treiber.
In-Flight-Recorder (IFR)
In-Flight-Recorder (IFR) wird unterstützt und kann über WDFKD, RCDRKD oder mit der ACXKD-Debuggererweiterung angezeigt werden, wenn sie verfügbar ist. Allgemeine Informationen zum Arbeiten mit IFR-Protokollen finden Sie unter Verwendung des Inflight Trace Recorders (IFR) in KMDF- und UMDF 2-Treibern und Video: Zugreifen auf Treiber IFR-Protokolle ohne Debugger
ACX protokolliert wichtige Ereignisse mithilfe anderer ETW-Anbieter, um die Visualisierung dieser speziellen Ereignisse zu vereinfachen.
Hinzufügen der Protokollierung zu Ihrem Treiber
Es wird dringend empfohlen, dass Treiber von Drittanbietern auch WPP- und ETW-Ereignisse verwenden.
Dieser Beispielcode zeigt die Überprüfung eines Rückgabewerts und das Protokollieren eines geeigneten Fehlers.
//
// The driver uses this DDI to delete the circuits from the current device.
//
status = AcxDeviceRemoveCircuit(Device, devCtx->Speaker);
if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speaker circuit, continuing with ReleaseHardware, %!STATUS!", status); }
status = AcxDeviceRemoveCircuit(Device, devCtx->MicArray);
if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove micarray circuit, continuing with ReleaseHardware, %!STATUS!", status); }
status = AcxDeviceRemoveCircuit(Device, devCtx->SpeakerHp);
if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove speakerHp circuit, continuing with ReleaseHardware, %!STATUS!", status); }
status = AcxDeviceRemoveCircuit(Device, devCtx->MicrophoneHp);
if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove microphoneHp circuit, continuing with ReleaseHardware, %!STATUS!", status); }
status = AcxDeviceRemoveCircuit(Device, devCtx->HDMI);
if (!NT_SUCCESS(status)) { DrvLogError(g_AudioDspLog, FLAG_INIT, L"Failed to remove HDMI circuit, continuing with ReleaseHardware, %!STATUS!", status); }
Die empfohlene Version des Toaster-Treiberbeispielcodes enthält Beispiele für die WMI-Ablaufverfolgung sowie den wiederverwendbaren Ablaufverfolgungscode. Weitere Informationen zum Toaster-Beispiel finden Sie unter Toaster-Beispieltreiber.
Empfehlungen für die ACX-Treiberprotokollierung
Um die Zuverlässigkeit Ihres ACX-Treibers zu verbessern, sollten Sie die folgenden Verhaltensweisen für die Protokollierung berücksichtigen.
- Unerwartete Rückgabewerte aus Datenstrompuffer-E/A oder einer anderen normalen Signalverarbeitungsaktivität.
- Unerwartete Energiezustände oder Energiezustandsübergänge.
- Fehler im Zusammenhang mit Anrufen, die während Updates oder einer erneuten Installation getätigt wurden.
- Andere Verhaltensweisen, die möglicherweise den Fehler „Keine Audiodaten“ auslösen, könnten für die Protokollierung berücksichtigt werden.
Verwenden der WMI-Debuggererweiterungen für die Ablaufverfolgung
Um Ablaufverfolgungsereignisse im Debugger anzuzeigen, verwenden Sie die WMI-Erweiterung Wmitrace.dll. Sie enthält eine Bibliothek mit Funktionen, die zum Steuern und Anzeigen der WMI-Ereignisablaufverfolgung entwickelt wurden. Weitere Informationen finden Sie unter WMI-Ablaufverfolgungserweiterungen (Wmitrace.dll).
ACX-Treiberdebugging
ACX-Treiber sind WDF-Treiber, daher gelten die für WDF-Treiber beschriebenen Debugtechniken für ACX-Treiber. Informationen zum Debuggen von WDF-Treibern finden Sie in den folgenden Themen.
Allgemeine Informationen zu den Tools zum Debuggen
Tools zum Debuggen unter Windows (WinDbg, KD, CDB, NTSD)
KMDF: Debuggen
Diese Anleitung verwendet den herkömmlichen Sysvad-Audiotreiber, zeigt aber einige Techniken, die auch für ACX-Treiber hilfreich sein können. Debuggen von Treibern: Schritt-für-Schritt-Übung (Sysvad-Kernelmodus)
Exemplarische Vorgehensweisen als Videos
- Video: Debuggen des Treibers mit WDF-Quellcode
- Videoreihe: Debuggen von Kernelmodustreibern für Treiberframework
Erweiterungsbibliothek des ACX-Kerneldebuggers (AcxKd.dll)
Um das Debuggen zu erleichtern, verfügt ACX über eine zusätzliche Kernel-Debugger-Erweiterungsbibliothek (AcxKd.dll). Diese Bibliothek unterstützt Entwickler beim Nachverfolgen des Problems auf Einzel-Stack- und Multi-Stack-Audiopfaden. Mit der kd-Erweiterung können Entwickler ACX-Strukturen durchsuchen.
Hinweis
Diese Debugger-Erweiterung befindet sich in der Entwicklung. Sobald sie verfügbar ist, werden wir Sie hier informieren.