3. UMDF PnP事件回调：IPnpCallbackHardware与IPnpCallbackSelfManagedIo

在UMDF驱动模型中，即插即用（PnP）与电源管理事件是驱动与内核交互的核心通道。本章聚焦于两个关键回调接口——IPnpCallbackHardware和IPnpCallbackSelfManagedIo，以及它们的核心方法OnPrepareHardware与OnReleaseHardware。理解这些回调的触发时机、职责边界和实现规范，是构建稳定DMA传输管道的前提。

3.1 接口职责与生命周期定位

UMDF框架将硬件生命周期划分为多个阶段，每个阶段由特定的回调接口负责。下表对比了IPnpCallbackHardware与IPnpCallbackSelfManagedIo的职责范围：

3.2 OnPrepareHardware：硬件资源就绪的入口

OnPrepareHardware是驱动接收硬件资源的第一个机会。当PnP管理器将设备分配到D0电源状态并完成资源仲裁后，框架调用此方法。驱动在此方法中必须完成以下工作：

1. 解析资源列表：从IResourceList中提取内存地址、中断向量、DMA通道。
2. 映射物理内存：调用IWDFDevice::CreateMemory或直接访问CM_PARTIAL_RESOURCE_DESCRIPTOR。
3. 创建DMA适配器：通过IWDFDmaAdapter::CreateDmaAdapter初始化DMA引擎。
4. 初始化硬件寄存器：设置设备控制寄存器、FIFO阈值等。

// OnPrepareHardware 典型实现骨架
HRESULT CMyDevice::OnPrepareHardware(
    _In_ IWDFDevice* pDevice,
    _In_ IResourceList* pResourcesRaw,
    _In_ IResourceList* pResourcesTranslated
    )
{
    HRESULT hr = S_OK;
    
    // 1. 遍历资源列表，查找内存资源
    ULONG count = pResourcesTranslated->GetCount();
    for (ULONG i = 0; i < count; i++)
    {
        PCM_PARTIAL_RESOURCE_DESCRIPTOR desc;
        pResourcesTranslated->GetDescriptor(i, &desc);
        
        if (desc->Type == CmResourceTypeMemory)
        {
            // 2. 映射BAR空间
            PHYSICAL_ADDRESS start = desc->u.Memory.Start;
            ULONG length = desc->u.Memory.Length;
            // 调用框架API映射到虚拟地址
            hr = pDevice->CreateMemory(/* ... */);
            BREAK_IF_FAILED(hr);
        }
    }
    
    // 3. 创建DMA适配器（如果设备支持总线主控DMA）
    if (SUCCEEDED(hr))
    {
        hr = CreateDmaAdapter(pDevice);
    }
    
    // 4. 初始化硬件寄存器
    if (SUCCEEDED(hr))
    {
        hr = InitializeHardwareRegisters();
    }
    
    return hr;
}

3.3 OnReleaseHardware：资源清理的保障

OnReleaseHardware是OnPrepareHardware的逆操作。当设备被移除、资源重新平衡或进入低功耗状态时，框架调用此方法。驱动必须在此释放所有在OnPrepareHardware中获取的资源：

• 取消DMA适配器：调用IWDFDmaAdapter::Delete释放DMA通道。
• 释放内存映射：框架自动管理大部分内存，但驱动分配的额外缓冲区需手动释放。
• 重置硬件状态：将设备寄存器恢复为安全默认值，防止后续驱动误操作。
• 清理软件状态：置空指针、释放引用计数。

// OnReleaseHardware 典型实现
HRESULT CMyDevice::OnReleaseHardware(
    _In_ IWDFDevice* pDevice,
    _In_ IResourceList* pResourcesTranslated
    )
{
    // 1. 停止所有正在进行的DMA传输（确保硬件空闲）
    AbortAllDmaTransfers();
    
    // 2. 释放DMA适配器
    if (m_pDmaAdapter)
    {
        m_pDmaAdapter->Delete();
        m_pDmaAdapter = NULL;
    }
    
    // 3. 释放公共缓冲区
    if (m_pCommonBuffer)
    {
        // 框架API释放
        m_pCommonBuffer->Release();
        m_pCommonBuffer = NULL;
    }
    
    // 4. 重置硬件寄存器（可选但推荐）
    ResetHardwareToSafeState();
    
    return S_OK;
}

3.4 IPnpCallbackSelfManagedIo：I/O生命周期的精细控制

与硬件资源回调不同，IPnpCallbackSelfManagedIo管理的是驱动自身的I/O处理状态。它提供了三个方法，对应设备I/O的三个状态转换：

// SelfManagedIo 回调实现示例
HRESULT CMyDevice::OnSelfManagedIoStart(
    _In_ IWDFDevice* pDevice
    )
{
    // 1. 启动I/O队列（框架开始分发请求）
    HRESULT hr = m_pIoQueue->Start();
    
    // 2. 使能硬件中断（如果设备使用中断）
    if (SUCCEEDED(hr))
    {
        EnableInterrupts();
    }
    
    // 3. 启动DMA传输引擎（例如：开始轮询描述符环）
    if (SUCCEEDED(hr))
    {
        hr = StartDmaEngine();
    }
    
    return hr;
}

HRESULT CMyDevice::OnSelfManagedIoStop(
    _In_ IWDFDevice* pDevice
    )
{
    // 1. 停止I/O队列（框架停止分发新请求）
    m_pIoQueue->Stop();
    
    // 2. 等待正在进行的DMA传输完成（带超时）
    WaitForPendingDmaComplete(5000); // 5秒超时
    
    // 3. 屏蔽中断
    DisableInterrupts();
    
    return S_OK;
}

3.5 回调协作流程与DMA集成

下图展示了PnP回调与DMA传输引擎的完整协作流程，从设备枚举到I/O运行：

3.6 回调实现避坑指南

基于实际项目经验，以下是PnP回调实现中最高频的五个错误及其解决方案：

3.7 小结：回调契约与DMA传输的绑定关系

本章的核心结论可以归纳为以下三点：

• 资源与逻辑分离：IPnpCallbackHardware负责硬件资源（内存、DMA适配器），IPnpCallbackSelfManagedIo负责I/O逻辑（传输启停）。两者通过OnPrepareHardware→OnSelfManagedIoStart的顺序耦合。
• DMA适配器的生命周期：创建于OnPrepareHardware，销毁于OnReleaseHardware。在OnSelfManagedIoStart/Stop中只控制传输状态，不重建适配器。
• 幂等与同步：所有回调必须幂等；Stop回调必须同步等待硬件完成，否则后续ReleaseHardware可能访问正在使用的资源。