Monday, October 20, 2008

Windows Kernel Debugging

Most Windows developers are familiar with the debugging functionality inside Microsoft Visual Studio and have few troubles stepping through code and using the watch windows. Visual Studio works great for the majority of applications which run in user mode on both local and remote machines. It also supports pure managed debugging,  where all the runtime details are hidden, simplifying debugging for .NET developers. Best of all, you don't need to leave the comfort of your IDE to attach a debugger and locate symbol files.

Microsoft also offers a number of stand-alone debuggers including CBD, NTSD, KD and WINDBG. These debuggers are included in the Windows SDK and you may also download them from the WHDC portal. Most user mode application developers will never want to use these stand alone debuggers because they expose a lot of information through a console interface. However, Visual Studio does not support kernel mode debugging and therefore has limited application for driver developers. This is where the stand-alone debuggers come into play.

If you'd like to learn more about debugging device drivers, the WHDC portal is great place to start. I'm not going to describe the inner workings of any particular debugger. However, I would like to describe how to setup a remote kernel debugging session using Firewire (IEEE 1394 interface) and KD. You can also debug using a serial or USB cable. For more details, I recommend  this MSDN article.

To start off, you will need a Firewire cable and two physical machines with 1394 host controllers. The first machine is your development box which will HOST the KD debugger. The second machine is the TARGET, which will run Windows in debug mode. This article assumes that you are using Windows Vista or later on the HOST machine and Windows Server 2003 or later on the TARGET machine.

  1. Connect the Firewire cable between you HOST and TARGET machines.
  2. Install KD on your HOST machine. Note that there are 64 bit versions of the debuggers.
  3. You also need to install the 1394 debugger driver. The first time you start a KD session over 1394, you will be prompted to install this driver so make sure you run as Administrator.
  4. Open an Administrator console and set the following environment variables:
    set _NT_DEBUG_BUS = 1394
    set _NT_DEBUG_1394_CHANNEL = 44
    REM if TARGET machine is Windows Server 2003 or later
    set _NT_DEBUG_1394_SYMLINK = instance
    REM else if TARGET machine is Windows XP or later
    set _NT_DEBUG_1394_SYMLINK = channel
  5. Change to the debugger install directory and run the following:
  6. Install the 1394 debugger driver if prompted
  7. KD will display a message saying "Waiting to reconnect"

At this point, your HOST machine is ready to go. Now you need to boot your TARGET machine into debug mode. You can do this a couple of different ways; the first using BCDEDIT and the second using MSCONFIG. I'll show you both.

To use BCDEDIT, open an Administrator console on the TARGET machine and type the following commands:

bcdedit /debug on
bcdedit /dbgsettings 1394 channel:44
shutdown -r

To use MSCONFIG, open the start menu and type msconfig in the search/run box. Browse to the Boot tab and choose Advanced Options. Check the Debug box, change the Port to 1394 and set the Channel to 44. Save the changes and reboot the machine.

If everything is configured correctly, you should see the KD session connect when the Windows splash screen is displayed as the TARGET machine reboots. If it doesn't work at first, try reconnecting the Firewire cable and press <ctrl>/<break> in the KD console.


No comments:

Post a Comment