视频:使用 WDF 源代码调试驱动程序

本主题包含一个视频教程,演示如何在完全访问 WDF 源代码的情况下调试 Windows 驱动程序框架 (WDF) 驱动程序。 视频后面是视频中遵循的分步过程,方便参考。

WDF 源调试允许你自由单步执行框架代码,而无需下载 WDF 源代码。 调试器会自动从 GitHub 下载正确版本的 WDF。

例如,如果使用 WinDbg 在Windows 10计算机上调试 WDF 驱动程序,并且调试器因调用堆栈中的框架代码而中断,则可以双击“调用堆栈”视图中的 WDF 帧,WinDbg 会自动下载并打开匹配行处的相关 WDF 源文件。 然后,可以单步执行代码并设置断点。

此功能适用于运行 Windows 10、Technical Preview 内部版本 10041 或更高版本的公共版本的目标系统。 这些生成具有 MICROSOFT 公共符号服务器上提供的 KMDF (Wdf01000.sys) 和 UMDF (Wudfx02000.dll) 的专用源索引符号文件。 WDF 代码的源级调试仅在 WinDbg 中可用,在 Visual Studio 调试器中不可用。

快速启动

启动与目标计算机的 WinDbg 内核调试会话,并执行以下步骤:

  1. 使用 .symfix 设置默认符号路径。 这会将符号路径设置为指向 处 https://msdl.microsoft.com/download/symbols的符号服务器。

    kd> .symfix

  2. 使用 .srcfix 设置默认源路径。 这会将源路径设置为 srv*,该路径指示调试器从目标模块符号文件中指定的位置检索源文件。

    kd> .srcfix
    Source search path is: SRV*
    
  3. 使用 .reload 重新加载符号,并确认 UMDF) 的 Wdf01000.sys 符号 (或 Wudfx02000.dll 已编制源索引。 如下面的 !lmi 输出所示,Wdf01000.sys PDB 已编制源索引。 如果不是,请参阅下面的 WinDbg 设置部分。

    kd> .reload
    ...
    
    kd> !lmi wdf01000.sys
    Loaded Module Info: [wdf01000.sys] 
    ...
    Load Report: private symbols & lines, source indexed 
    C:\...\Wdf01000.pdb\...\Wdf01000.pdb
    
  4. 至此已完成全部设置! 单步执行 WDF 源代码的一种简单方法是在框架的 IRP 调度例程上设置断点,然后单步执行其余代码。 由于 Windows 系统具有许多内置 KMDF 驱动程序,因此 WDF 始终加载并运行,因此此断点将立即 (命中,而无需加载自己的驱动程序) 。

    kd> bp Wdf01000!FxDevice::DispatchWithLock
    kd> g
    Breakpoint 0 hit
    Wdf01000!FxDevice::DispatchWithLock:
    87131670 8bff mov edi,edi 
    

如果这不起作用,检查下面的 WinDbg 安装步骤。

WinDbg 安装程序

如果上述示例未按预期工作,则可能需要执行以下一个或多个说明。

启用源模式调试

确保在 源模式下启用调试 。 打开“调试”菜单并确认已选中“源模式”。

清除过时符号缓存

如果以前为同一 Windows 目标调试了 WDF 驱动程序,则可能使用的是未编制源索引的本地缓存 WDF 符号。 可以使用 !lmi 命令检查:

kd> !lmi Wdf01000.sys
Loaded Module Info: [wdf01000.sys]
...
Load Report: private symbols & lines, not source indexed
C:\...\Wdf01000.pdb\...\Wdf01000.pdb

根据上面的负载报告,Wdf01000.pdb 不是源索引。 这意味着本地 WinDbg 符号缓存已过时。 若要解决此问题,请从 WinDbg 中卸载 PDB,清除本地缓存, (路径可能因上面的 !lmi 输出) 而异,然后重新加载 PDB:

kd> .reload /u Wdf01000.sys

CMD> del
C:\...\Wdf01000.pdb\...\Wdf01000.pdb

kd> .reload Wdf01000.sys

现在运行 !lmi 以再次检查:PDB 应显示为已编制索引的源,并弹出源代码窗口。

kd> !lmi Wdf01000.sys
Loaded Module Info: [wdf01000.sys]
...
Load Report: private symbols & lines, source indexed
C:\...\Wdf01000.pdb\...\Wdf01000.pdb 

使用 WDF 源级调试不仅可用于实时调试和分析故障转储,还可以通过在 IRP 调度程序等核心函数上设置断点并浏览后续代码路径来了解有关框架内部的更多信息。