ACX 日志记录和调试

项目
06/27/2024

本主题提供有关 ACX 音频类扩展的日志记录、跟踪和调试的信息。

ACX 驱动程序日志记录

驱动程序的软件跟踪通常基于 Windows 事件跟踪 (ETW)，这是一个内核级别工具，用于记录内核模式进程和用户模式进程的跟踪消息。由于 ACX 驱动程序是 WDF 驱动程序，因此所有 WDF 日志记录和事件功能都可供 ACX 驱动程序开发人员使用。

WPP

由于 ETW 的使用可能有些复杂，因此大多数驱动程序开发人员都使用 Windows 软件跟踪预处理器 (WPP)，这可简化并增强检测 ETW 跟踪驱动程序的过程。

ACX 使用 WPP 日志进行跟踪和调试。有关详细信息，请参阅在 KMDF 驱动程序中使用 WPP 软件跟踪和将 WPP 软件跟踪添加到 Windows 驱动程序。

即时记录器 (IFR)

即时记录器 (IFR) 受支持，可通过 WDFKD、RCDRKD 或 ACXKD 调试器扩展进行查看（可用时）。有关使用 IFR 日志的一般信息，请参阅在 KMDF 和 UMDF 2 驱动程序中使用即时跟踪记录器 (IFR) 和视频：在没有调试器的情况下访问驱动程序 IFR 日志

ACX 使用其他 ETW 提供程序记录关键事件，以简化这些特殊事件的可视化。

将日志记录添加到驱动程序

强烈建议第 3 方驱动程序也使用 WPP 和 ETW 事件。

此示例代码演示如何检查返回值和记录适当的错误。


    //
    // 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); }

Toaster 驱动程序示例代码的特色版本提供了 WMI 跟踪和可重用跟踪代码的示例。有关 Toaster 示例的详细信息，请参阅 Toaster 示例驱动程序。

ACX 驱动程序日志记录建议

若要提高 ACX 驱动程序的可靠性，请考虑以下日志记录行为。

来自流缓冲区 IO 或其他常规信号处理活动的意外返回值。
意外电源状态或电源状态转换。
与更新或重新安装期间进行的调用相关的错误。
可能会考虑可能会导致“无音频”的其他行为进行日志记录。

使用 WMI 跟踪调试器扩展

若要查看调试器中的跟踪事件，请使用 WMI 扩展 Wmitrace.dll。其中包含一个用于控制和查看 WMI 事件跟踪的函数库。有关详细信息，请参阅 WMI 跟踪扩展 (Wmitrace.dll)。

ACX 驱动程序调试

ACX 驱动程序是 WDF 驱动程序，因此为 WDF 驱动程序描述的调试技术适用于 ACX 驱动程序。有关调试 WDF 驱动程序的信息，请参阅以下主题。

有关调试工具的常规信息

Windows 调试工具（WinDbg、KD、CDB、NTSD）

KMDF 调试

Wdfkd.dll 中的调试程序扩展摘要
本演练使用传统的 Sysvad 音频驱动程序，但阐释了一些可能对 ACX 驱动程序有所帮助的技术。调试驱动程序 - 分步实验室（Sysvad 内核模式）

视频演练

ACX 内核调试器扩展库 (AcxKd.dll)

为了帮助调试，ACX 具有配套内核调试器扩展库 (AcxKd.dll)。此库可帮助开发人员跟踪单栈和多栈音频路径的问题。利用 kd 扩展，开发人员可查看 ACX 结构内部。

注意

此调试器扩展正在开发中，可用时将在此处提供信息。

另请参阅

ACX 音频类扩展概述

ACX 对象摘要

通过