Debugger Extensions Tips
Windows Debugger Extension Tips.
Windows debugger is a powerful tool for diagnosing and examining drivers and applications in Windows. There is support for developers to create their own extensions within the debugger to assist them with common or even highly detailed analysis. The purpose of this blog is to show you how to get started and manage these extensions within Windows. The Windows debugger help file is your main resource but the three commands below are your starting point and should cover the majority of your needs.
.load DLLName
.chain
.unload DLLName
.Chain is the first command you will want to use. The command displays all the active extensions in the order that they will be searched. I use this when I know several extensions have overlapping features. So if I want to make sure the extension I want will be searched first as there is a known overlap or you want your custom extension to be the first extension the debugger sees then there are several ways to handle this. The way I like to handle this for a one time occurrence is to use the next command.
.Unload allows you to unload a debugger extension. Maybe you have an updated extension, you have overlapping features and you want to make sure your custom extension is hit. Use the .Unload command to unload the first extension that overlaps and run your command. You can also unload your extension and reload it thereby placing it at the top of the list
.Load allows you to load either your own custom or a third party extension. Extensions can do many tasks but they all have one main purpose and that is to make it easier to debug an issue. There is the .Loadby command but I prefer .Load as you can specify a specific path to the DLLName. From experience, I save my old extensions when replacing them with new ones. Sometimes, items are removed or changed in their behavior and it may be necessary to load an older extension and .load can do that for you.
To use the extensions you always have to start with a bang (!).
You can either pass or omit the debug extension name before the command you want to run (passing the name means you don't have to worry about the load order shown from .chain) Best practice is to put the debugger extensions in the extensions path (I usually put them in the \winext folder underneath the debugger install folder).
A gotcha - If you use .load and specify a path, then that path becomes the name the debugger uses for the extension. So if you later want to run !<extensionname>.command you have to use the same name you used originally. If you don't use a path it makes this much simpler.
Here is an example of loading an extension DLL by full path:
0: kd> .load c:\exts\myext.dll
Notice how .chain shows the name of the DLL includes the full path while the other ones do not.
0: kd> .chain
Extension DLL search Path:
C:\Program Files (x86)\Debugging Tools for Windows (x86)\WINXP;C:\Program Files (x86)\Debugging Tools for Windows (x86)\winext;C:\Program Files (x86)\Debugging Tools for Windows (x86)\winext\arcade;C:\Program Files (x86)\Debugging Tools for Windows (x86)\pri;C:\Program Files (x86)\Debugging Tools for Windows (x86);C:\Program Files (x86)\Debugging Tools for Windows;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\idmu\common;C:\Program Files (x86)\Debugging Tools for Windows (x86)\
Extension DLL chain:
c:\exts\myext.dll: image 1, 0, 0, 1, API 1.0.0, built Wed Jan 08 09:38:33 2010
[path: c:\exts\myext.dll]
dbghelp: image 6.11.0002.408, API 6.1.6, built Thu Apr 02 11:52:22 2010
[path: C:\Program Files (x86)\Debugging Tools for Windows (x86)\dbghelp.dll]
ext: image 6.11.0002.408, API 1.0.0, built Thu Apr 02 11:52:22 2010
[path: C:\Program Files (x86)\Debugging Tools for Windows (x86)\winext\ext.dll]
exts: image 6.11.0002.408, API 1.0.0, built Thu Apr 02 11:52:16 2010
[path: C:\Program Files (x86)\Debugging Tools for Windows (x86)\WINXP\exts.dll]
kext: image 6.11.0002.408, API 1.0.0, built Thu Apr 02 11:52:16 2010
[path: C:\Program Files (x86)\Debugging Tools for Windows (x86)\winext\kext.dll]
kdexts: image 6.1.7015.0, API 1.0.0, built Thu Apr 02 11:51:49 2010
[path: C:\Program Files (x86)\Debugging Tools for Windows (x86)\WINXP\kdexts.dll]
Now, if I try to run a command from my extension, you will see the different results.
First, running with no extension name means it will run the first extension dll in the chain which has that command
0: kd> !help
This is the help for my debugger extension
Next, trying to run !myext.help fails since that is not the name loaded.
0: kd> !myext.help
The call to LoadLibrary(labor) failed, Win32 error 0n2 "The system cannot find the file specified."
Please check your debugger configuration and/or network access.
If you use the full path, it works
0: kd> !c:\exts\myext.help
This is the help for my debugger extension.
Hope this introduction to extensions helps. The Windows debugger help file is a great resource for learning more about these features. You can also find more from MSDN website at https://msdn.microsoft.com/en-us/library/ff540551.aspx
Comments
- Anonymous
December 09, 2011
Wow this was great and resolved my issue. Found an extension was not loaded.Thanks Microsoft this is the best blog I've read in a month!!