Nadav's Blog

Memory Dumps @ The unmanaged domain

Download Source

---

Abstract
The focus of this article is to discuss an atonomus method of generating dump files w/o the need of any development tool installed.
Is starts by giving a high level explenation of what dump files are and what they are used for, then, it present few of the most common development tools used to generate dump files and discuss windows exception model, finally, a way of generating dump files w/o the need of any development tool is presented.

So what a Dump file is?
A dump file is the image of the process at a certain point in time, this process image can include various information such as the call stack & stack variables, loaded module list, and even an image of the raw memory used by the application. This valuable information can then be used to analyze the process state at the time the dump file was generated.

What is it used for?
In most cases ( but not only ) Dump files are used to identify the root of an exceptional condition causing the process to abnormally terminate ( a 2nd chance exception ), having a dump file generated just before the application has crashed will enable postmortem analysis of the process state when it has crashed, and thus, enables pin-pointing the root of the problem.

Using Microsoft Visual Studio to generate memory dumps
Microsoft Visual Studio enable generation of memory dumps while breaking the execution of a debugged process, this can be done through the Debug->Save Dump As menu item as illustrated in Figure 1 bellow

Two dump file types are support by the IDE, a 'minidump' that include stack trace information ( resulting small files ), and a 'minidump with heap' including the full memory image ( resulting large files ).

Using ADPlus @ debugging tools for windows to generate dump files
Debugging tools for windows is a light weight suite of tools for debugging applications, It is ideal for customer site problem resolution, and for scenarios where it is not possible to install heavy duty development environments such as Microsoft Visual Studio.
ADPlus ( also known as 'AutoDump+' ) is a light weight tool used to automatically generate Dump files, that is, upon abnormal process termination a Dump file will automatically be generated enabling postmortem analysis of the process state when it has crashed, it also support automatic dump generation upon deadlocks, Figure 2 bellow present sample ADPlus command line.

The above attach ADPlus to winword.exe and generates dump files at 'd:\dumps' upon winword.exe crash, click here for the full command line specification.

Analyzing Dump Files
Dump file analysis is the phase where postmortem takes place, Starting with Microsoft Visual Studio 10, it is possible to directly analyze dump files for unmanaged applications through the IDE, this is done through the “File->Open->’File…’” menu and then by selecting the dump file to analyze ( ‘*.dmp’, ‘*.mdmp’, ‘*.hdmp’ extensions ).
Once opened, Click the ‘Play’ Icon and the IDE will take you to the point where the application was breaking.
It is important to note that for Dump Analysis to properly work it is essential to keep the symbol files ( .pdb ) associated with the executable for which the dump was created, these should then be used during the analysis process.
Dump file analysis for managed applications is supported by debugging tools for windows and will be covered in a specialized Article.

Process termination due to Exceptional condition
A Process might be abnormally terminated due to an exceptional condition preventing normal process execution, such an exceptional condition is usually due to a programming error ( a SW bug ), A list describing common exceptions can be found here.
The operating system use Structured exceptions to indicate such exceptional behavior, the executing application will get the first chance to deal with the exception, and if not dealt with or if dealt with but not suppressed, the operating system will get the second chance to deal with it, having 1st and 2nd chance exceptions respectively, most of the time when 2nd chance exceptions are generated the operating system will terminate the application ( a crash ), exceptions are eg. debugger breakpoints ( DebugBreak() ) where once intercepted, the OS will open a dialog letting the programmer to choose if he wants to debug the application ( assuming a debugger is installed ) or supress the exception.

Automatically generating Dump files upon abnormal process termination
No more than few lines of code ar needed to be able to automatically generate dump files when the application is crashing, Figure 3 bellow demonstrate what is needed.

The above code snap uses Structured Exception handling to intercept 2nd chance exceptions, this is done by installing the Unhandled exception handler '__TopLevelExceptionHandler' ( using SetUnhandledExceptionFilter ) that intercept all 2nd chance exceptions.
Once an exception has been intercepted '__TopLevelExceptionHandler' is invoked and does the actual dump file generation.
The unhandled exception handler ( in our case '__TopLevelExceptionHandler' ) is executed on the context of the thread throwing the exception, thread stack is not collected while the hander is executed, this, might limit the exception handler implementation on stack overflow scenarios where there might not be enough space left on the stack to execute the handler functionality, for this, '__TopLevelExceptionHandler' create a separate thread where the actual ~dumping~ process will synchronously execute.
The actual dumping process is executed by the ‘__GenerateDumpFile’ method, in specific by using the MiniDumpWriteDump API.
By default the dump file will be generated at the directory of the executing process, the name of the file include the time, the exception code, and, the name of the process.
The code can easily be integrated in to any C++ application enabling automatic dump file generation, and, reducing the cost of customer site probelm interception.

Final words

I was trying to have the code provided with this article as clear & simple as possible, The generated dump files might take considerable disk space, integrating this code with any commercial product will req implementation of a dump file recycling mechanism.