Configuring a Kernel Debugger to Debug a Device Driver

ID: Q90081

The information in this article applies to:

Microsoft Win32 Device Driver Kit (DDK) for Windows NT, versions 3.1, 3.5, 3.51

SUMMARY

The following information is a supplement to the instructions for setting up a kernel debugger for the Win32 SDK for Windows NT. Setting up a debugger for use with a device driver properly is different than setting up a debugger for applications, so it may be less intuitive at first.

The system requires two machines, a host machine and a debug machine. The host machine is the system that is being developed for. The debug machine is where the debugger (I386KD or MIPSKD) is executed. The executing driver is on the host machine.

When debugging device drivers, it is important to note that the symbolic information for debugging is stored in the actual .SYS file, not in a separate .SYM file. On the debug machine, the .SYS file should be copied into a directory structure that is an exact copy of the host machines' directory structure. This is called a mirror. When you break in with the kernel debugger on the debug machine, the actual code that you are breaking into is on the host machine, not the debug machine. The kernel debugger examines the mirrored directory to get the symbols for the .SYS file where the break occurred.

Note that it is possible to break into the debugger by either hitting the SysRq key on the host machine, or by typing Ctrl-C on the debug machine, or by making a call to DbgBreakPoint in the driver. This call executes an INT 03 on an x86 machine, or equivalent instructions on a MIPS machine.

MORE INFORMATION

For the host machine, that only requirements are that the appropriate hardware is installed, that the driver is placed in <nt>\SYSTEM\DRIVERS, and that any necessary settings are made in the registry.

There are several steps in configuring the debug machine. First, mirror the host machine's directory structure on the debug machine. For example:

md c:\debug
md c:\debug\nt
md c:\debug\nt\system
md c:\debug\nt\system\drivers

copy NTOSKRNL.EXE c:\debug\nt\system.
copy HAL.DLL c:\debug\nt\system\drivers (optional)

Copy any appropriate drivers to c:\debug\nt\system\drivers. This includes the driver that is being debugged. Other appropriate drivers might be SCSIPORT.SYS, SCSIDISK.SYS, ATDISK.SYS, etc. When in doubt, put the driver in this directory, as it will not hurt anything.

Secondly, make a batch file called KD.BAT:


   @echo off
   REM CPU may be set to i386 or mips
   SET CPU=i386
   mode 80,500
   SET _NT_SYMBOL_PATH=c:\debug
   SET _NT_DEBUG_LOG_FILE_OPEN=%_NT_SYMBOL_PATH%\kd.log
   %CPU%kd -v %1 %_NT_SYMBOL_PATH%\nt\ntoskrnl.exe

Note that the batch file is set up so that the debugger can take an optional parameter (like -b for i386kd).

Execute KD.BAT on the debug machine.

Lastly, reboot the host machine.

Additional query words: 3.10 3.50


Keywords          : 
Version           : 
Platform          : 
Issue type        :

Last Reviewed: March 1, 1999