Diving Deep into WinDbg's !analyze Extension: Your Go-To for Debugging Windows Drivers

When debugging Windows drivers and applications, time is of the essence. Quickly identifying the root cause of a crash or hang can save countless hours of frustration. That's where the !analyze extension in WinDbg, the Windows debugger, shines. This powerful tool provides a comprehensive analysis of exceptions and bug checks, helping developers pinpoint problems efficiently. This article provides an in-depth look at the !analyze extension, covering its parameters, usage, and benefits for both user-mode and kernel-mode debugging.

What is the !analyze Extension?

The !analyze extension is a WinDbg command that analyzes the current exception or bug check. It presents a detailed report, including the exception code, faulting address, call stack, and other relevant information. This information is invaluable for understanding the context of the error and identifying the source of the problem.

User-Mode Usage

In user mode, !analyze is primarily used to examine exceptions in applications. The basic syntax is:

!analyze [-v[0..99]] [-f | -hang] !analyze [-v[0..99]] -xml [-xmi] [-xcs] [-xmf OutputXmlFile] !analyze -c [-load KnownIssuesFile | -unload | -help ]

Here's a breakdown of common parameters:

• -v[0..99]: Controls the verbosity of the output. -v alone (or -v1) provides a good balance of information. -vv (or a higher number) displays all available details
• -f: Forces exception analysis, even if the debugger doesn't automatically detect an exception.
• -hang: Analyzes hung applications. This is particularly useful when an application becomes unresponsive. Before using -hang, switch to the thread that is suspected of hanging using the ~ command in WinDbg (e.g. ~1s to switch to thread 1).
• -xml: Generates the output in XML format. Useful for automated analysis or integration with other tools.
• -xmi: Adds module information to the XML output (requires -xml or -xmf).
• -xcs: Incorporates context and call stack frames into the XML output (requires -xml or -xmf).
• -xmf OutputXmlFile: Writes the XML output to the specified file. This can be helpful for archiving or sharing analysis results.
• -c: Continues execution when the debugger encounters a known issue defined in a KnownIssuesFile.
  • -load KnownIssuesFile: Loads the specified XML file containing known issues.
  • -unload: Unloads the current list of known issues.
  • -help: Displays help for the -c option.

Example:

To perform a verbose analysis of an exception in user mode, you would use:

!analyze -v

To analyze a hung application, you would first switch to the suspect thread and then use:

!analyze -hang

Kernel-Mode Usage

In kernel mode, !analyze is primarily used to investigate bug checks (BSODs). The syntax is similar to user mode with a few key differences.

!analyze [-v[0..99]] [-f | -hang] !analyze -show BugCheckCode [BugParameters] !analyze [-v[0..99]] -xml [-xmi] [-xcs] [-xmf OutputXmlFile] !analyze -c [-load KnownIssuesFile | -unload | -help ]

Important parameters include:

• All of the parameters described in User-Mode Usage apply to Kernel-Mode as well.
• -show BugCheckCode [BugParameters]: Displays information about a specific bug check code and its parameters. This allows retrieval of information about known bugs.
• -hang: In kernel mode, !analyze -hang investigates system locks and the DPC queue chain to identify potential deadlocks.

Example:

To display information about the bug check code 0x0000007E (SYSTEM_THREAD_EXCEPTION_NOT_HANDLED) with parameters 0xC0000005, 0x804F47A8, 0xF793A584, and 0xF793A27C, use:

!analyze -show 0x0000007E C0000005 804F47A8 F793A584 F793A27C

A simple invocation in Kernel-Mode after a crash, would look like this:

!analyze -v

This shows verbose output related to the bug check.

Interpreting the Output

The output of !analyze can be extensive, but it's organized into sections to facilitate analysis. Key sections include:

• Bug Check Analysis (Kernel Mode) / Exception Analysis (User Mode): Provides a summary of the error, including the bug check code or exception code, description, and probable cause.
• STACK_TEXT: Displays the call stack, showing the sequence of function calls that led to the error. This is crucial for identifying the code path that triggered the issue.
• MODULE_NAME: Identifies the module (DLL or executable) where the error occurred.
• IMAGE_NAME: Shows the full path to the image file.
• FAILURE_ID_HASH: This is a hash value related to the crash and can be used to search for known issues related to the specific failure signature.

Tips for Effective Usage

• Use Verbose Output: Start with !analyze -v to get a comprehensive overview. Increase the verbosity level (e.g., !analyze -v99) if you need more details. However, be mindful that increasing verbosity increases the output.
• Examine the Call Stack: The call stack is your roadmap to the error's origin. Pay close attention to function names and module names to identify potential problem areas.
• Leverage Symbol Files: Ensure that you have properly configured symbol files to get meaningful function names and source code context in the call stack. A symbol server simplifies this process.
• Consider -hang for unresponsive applications: When an application locks up, -hang can help you understand which threads are blocked and why.
• Explore Related Commands: Commands such as .bugcheck (in kernel mode), .exr, and .cxr can provide additional context.

UMDF Driver Analysis

For User-Mode Driver Framework (UMDF) version 2.15 and later, the !analyze extension can provide specific diagnostics for UMDF driver failures, including verifier errors and unhandled exceptions. When debugging UMDF driver crashes, !analyze attempts to identify the responsible driver, which helps speed up the debugging process.

Conclusion

The !analyze extension is a powerful and versatile tool for debugging Windows drivers and applications. By understanding its parameters, interpreting its output, and following best practices, developers can effectively diagnose and resolve a wide range of issues. Mastering !analyze is an essential skill for any Windows developer seeking to write robust and reliable code. Make sure to consult the official Microsoft documentation for the most comprehensive and up-to-date information. Remember to also review the essential guide "Using the !analyze extension" to see sample analysis outputs.