通过

如何启用对 UMDF 驱动程序的调试

  • 项目

可以在开发期间使用以下配置来调试 User-Mode Driver Framework (UMDF) 驱动程序。 所有配置都涉及两台计算机，一个主机和一个目标。

  • 手动将驱动程序复制到目标。 对目标执行用户模式调试。 在此方案中，手动附加到目标上运行的驱动程序主机进程的实例。
  • 手动将驱动程序复制到目标，然后从主机执行内核模式调试。

建议在附加内核调试器的情况下执行所有 UMDF 驱动程序测试和开发。

最佳做法

建议在附加内核调试器的情况下执行所有 UMDF 驱动程序测试。

以下是建议的设置。 可以手动设置这些设置，也可以使用 WDK 中的 WDF 验证程序控制应用程序 (WDFVerifier.exe) 工具来查看或更改这些设置。

  • 在 WUDFHost.exe 上启用应用程序验证程序：

    AppVerif –enable Heaps Exceptions Handles Locks Memory TLS Leak –for WudfHost.exe

    如果发生异常，应用程序验证程序会将诊断消息发送到调试器并中断。

  • 如果使用内核模式调试会话，请设置 HostFailKdDebugBreak ，以便反射器在终止驱动程序主机进程之前会中断内核模式调试器。 默认情况下，从 Windows 8 开始启用此设置。

  • 通过将 UmdfHostProcessSharing 设置为 ProcessSharingDisabled 来禁用池。 有关信息，请参阅 在 INF 文件中指定 WDF 指令。

  • 默认情况下，当 UMDF 设备发生故障时，框架将尝试重启它最多五次。 可以通过将 DebugModeFlags 设置为 0x01 来关闭自动重启。 有关详细信息，请参阅 用于调试 WDF 驱动程序的注册表值。

  • 重新启动计算机。

  • 若要调试 UMDF 驱动程序问题，请查看 确定反射器终止主机进程的原因 和 调试 UMDF 驱动程序崩溃

使用 WinDbg 手动附加 (用户模式调试)

在目标计算机上，可以手动将 WinDbg 附加到承载驱动程序的 WUDFHost 实例。 附加时，会中断调试器，并且可以在驱动程序中设置断点。

由于驱动程序初始化发生在加载 WUDFHost 后不久，因此无法及时手动附加来调试初始化代码。 相反，可以设置注册表值，使主机进程在主机初始化或驱动程序加载时等待一定秒数。 此延迟使你有时间将 WinDbg 附加到 WUDFHost 进程的正确实例。

执行以下步骤：

  1. 在目标计算机上的注册表中，将 HostProcessDbgBreakOnStart 或 HostProcessDbgBreakOnDriverLoad 设置为一定秒数并重新启动。
  2. 在目标计算机上，以管理员身份打开 WinDbg。
  3. 在“ 文件 ”菜单上，选择“ 附加到进程”。 选择“ 按可执行文件”，找到命名的所有进程，WUDFHost.exe (可能没有任何) 。 如果有任何名为 WUDFHost.exe 的进程，请记下其进程标识符以供将来参考。
  4. 在“设备管理器”中，启用驱动程序。
  5. 重复步骤 2 并找到 WUDFHost.exe 的新实例。 如果未看到WUDFHost.exe的新实例，请单击“ 取消”，然后再次选择“ 附加到进程 ”。 找到 WUDFHost.exe 的新实例时，将其选中，然后单击“ 确定”。

如果 设备池 正在使用中，并且你设置了 HostProcessDbgBreakOnDriverLoad 注册表值，则可能会看到调试器因加载其他驱动程序而中断。 可以使用 UMDF 调试模式关闭设备池。

若要使用调试模式，请使用 Visual Studio 中的 F5 选项，或在注册表中设置 DebugModeFlags 和 DebugModeBinaries 值。

有关 UMDF 注册表值的详细信息，请参阅 用于调试 WDF 驱动程序的注册表值 (KMDF 和 UMDF) 。

使用 WinDbg 从主机远程调试 (内核模式调试)

从远程主机建立内核模式调试会话，然后将当前进程设置为托管驱动程序的 Wudfhost 实例。 如果要从远程内核调试器进行调试，可以将 HostProcessDbgBreakOnDriverStart 或 HostProcessDbgBreakOnDriverLoad 设置为0x80000000以指定不超时，但会中断内核调试器。

执行以下步骤：

  1. 禁用池。 打开 DebugModeFlags 并在 DebugModeBinaries 中列出驱动程序

  2. 如果驱动程序使用 UMDF 1.11 或更高版本，则默认情况下启用 HostFailKdDebugBreak 。 跳过此步骤。

    如果驱动程序使用 UMDF 1.9 或更早版本，请将 HostFailKdDebugBreak 设置为 1。

  3. 如果要调试与超时相关的问题，请关闭 HostProcessDbgBreakOnDriverStart 和 HostProcessDbgBreakOnDriverLoad。 (当 HostProcessDbgBreakOnDriverStart 或 HostProcessDbgBreakOnDriverLoad 不为零时，框架会禁用超时，以便在将用户模式调试器附加到主机进程时反射器不会终止主机。) 如果需要调试驱动程序初始化代码，而不是使用这两个值，请尝试在驱动程序加载之前在 WinDbg 中发出以下命令： sxe ld： 模块负载) 时MyDriver.dll(中断

  4. 如果进行了任何注册表更改，请重新启动。

  5. 根据上面所做的选择，当驱动程序在目标上加载或卸载时，远程内核调试器应中断。