ACX WDF 驱动程序生命周期管理

项目
05/15/2024

本主题提供了 ACX WDF 驱动程序生命周期管理和适当内存清理的摘要。有关 ACX 的一般概述，请参阅 ACX 音频类扩展概述。

注意

ACX 标头和库不包括在 WDK 10.0.22621.2428（2023 年 10 月 24 日发布）中，但在早期版本以及 WDK 的最新（25000 系列内部版本）预览体验预览版中可用。有关 WDK 预览版本的详细信息，请参阅安装 Windows 驱动程序工具包 (WDK) 的预览版本。

ACX WDF 初始化和启动

需要进行适当的 ACX 初始化，以便正确清理 ACX、WDF 和内存资源。关于此处总结的设备枚举主要阶段的更多详细信息，请参阅 ACX 设备枚举。

WDM Driver Entry
WDF 设备添加
WDF 准备硬件
WDF 设备 D0 条目
ACX 线路创建过程（ACX 引脚和 Jacks 对象与线路相关联）
ACX 流创建过程

ACX WDF 对象清理

本主题介绍按此顺序清理 ACX WDF 对象。

ACX 流关闭进程
ACX 线路删除过程
WDF 设备发布硬件
WDF 驱动程序卸载

有多种有效的方法可以创建和清理 WDF 和 ACX 对象，本主题介绍管理 ACX/WDF 对象的生存期的一些关键元素。

PnP Power 事件和对象销毁

PnP Power 事件可能导致对象创建和销毁。有关 PnP Power 事件的详细信息，请参阅 ACX 电源管理以及 WDF PnP 和电源管理回调序列。

WDF 对象引用生存期管理

WDF 使用引用计数来帮助跟踪对象的生存期。在清理回调函数中，可能适合取消引用对象引用。框架会调用此清理回调函数，以便驱动程序可以调用 WdfObjectDereference（如果以前为要删除的对象调用了 WdfObjectReference）。有关详细信息，请参阅 WdfObjectReference 和 WdfObjectDereference。

Surface 团队驱动程序开发最佳实践

有关内存和对象生命周期管理驱动程序代码中常见错误的说明，请参阅 Surface 团队驱动程序开发最佳实践中的这些部分。

ACX 流关闭进程

当客户端关闭流时，驱动程序需要工作才能关闭和清理与流关联的资源。有关详细信息，请参阅 ACX 流式处理 - 流关闭进程。请务必注意，驱动程序不清理支持流的资源，并且清理过程必须注意对客户端的影响。

ACX 线路删除过程

ACX 可以根据需要创建动态线路。这样，驱动程序会调用 WdfPdoInitAllocate 来分配 WDFDEVICE_INIT 结构。然后，驱动程序指定它想要接收的任何 PnP/power 回调，并创建设备。驱动程序会调用 AcxDeviceRemoveCircuitDevice 来从设备列表中删除音频设备。

有关详细信息，请参阅 ACX 线路中的 ACX 线路动态删除。

WDF 设备发布硬件

EVT_WDF_DEVICE_RELEASE_HARDWARE 回调函数用于在驱动程序的 EvtDeviceReleaseHardware 事件回调函数中执行设备不再可访问时所需的操作。

WDF 设备上下文清理

AudioCodec 示例中的这段代码显示了使用 WDF_OBJECT_ATTRIBUTES 结构来设置 EvtCleanupCallback。

    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(&attributes, CODEC_DEVICE_CONTEXT);
    attributes.EvtCleanupCallback = Codec_EvtDeviceContextCleanup;

给出 WdfDevice 的此示例回调清理设备上下文。

VOID
Codec_EvtDeviceContextCleanup(
    _In_ WDFOBJECT      WdfDevice
)

{
    WDFDEVICE               device;
    PCODEC_DEVICE_CONTEXT   devCtx;

    device = (WDFDEVICE)WdfDevice;
    devCtx = GetCodecDeviceContext(device);
    ASSERT(devCtx != nullptr);

    if (devCtx->Capture)
    {
        CodecC_CircuitCleanup(devCtx->Capture);
    }
}

WDF 驱动程序卸载

当卸载驱动程序时，它会释放所有剩余的资源。有关详细信息，请参阅发布驱动程序分配的资源。

驱动程序在调用 WdfDriverCreate 时注册 EvtDriverUnload 回调函数。 EvtDriverUnload 回调函数必须解除分配驱动程序 DriverEntry 例程分配的任何非特定于设备的系统资源。有关详细信息，请参阅 EVT_WDF_DRIVER_UNLOAD 回调函数。

AudioCodec 示例中的这段代码显示驱动程序卸载回调的结构。

EVT_WDF_DRIVER_UNLOAD               AudioCodecDriverUnload;

void AudioCodecDriverUnload(
    _In_ WDFDRIVER Driver
)
{
    PAGED_CODE();

    if (!Driver)
    {
        ASSERT(FALSE);
        return;
    }

    WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver));

// Here is where you would cleanup any allocated resources associated with the driver.

    return;
}