Interactive Debugging

< BACK  NEXT >

[oR]

Post mortem analysis is a necessary skill, but many driver problems are easier to diagnose while the driver is actively running. This section briefly describes how to debug driver code interactively.

Starting and Stopping a Debug Session

WinDbg is the primary tool for interactive debugging. To use it, two machines are needed: the target (machine under test) and the host (development machine running WinDbg). Appendix A describes the basics of making the connection between machines, but essentially a serial link is used to control and monitor activity on the target. Figure 17.3 shows the positioning of the host and target machines and files.

Figure 17.3. Interactive debugging using WinDbg.

The first secret to successful interactive debugging is to ensure that the necessary files are installed on the proper machines. The steps are outlined below.

1. Install the binary driver file (.SYS) on the target. The target does not need symbol files or source code.

2. The host requires symbol information for both the driver and the operating system of the target. For simplicity, it is a good idea to ensure that both target and host are running the same version (including service pack) of Windows 2000, but this is not strictly required.

3. On the host, launch WinDbg. Set up the symbols and source directory options to include a path to the appropriate information. Remember, the symbols and source information must match the target's binary file.

4. Select kernel mode debugging from the View menu under the Options Kernel Debugger tab of WinDbg.

5. Select the appropriate COM port and baud rate from this dialog box.

6. Choose the GO toolbar button, or type g in the command window. This places WinDbg into a mode where it waits to connect to the target.

7. Reboot the target machine with the kernel's debug client enabled. (Details are included in Appendix A.) As the system boots, a connection between host and target is established. Once connected, the command window of WinDbg displays considerable information.

The host is now in complete control of the target. The interactive version of a WinDbg session is a superset of the post mortem mode of crash dump analysis. Breakpoints can be established, even on top of code that has yet to be loaded into kernel memory.

To disconnect a debug session, perform the following steps:

1. Pause the target by typing Ctrl-C in the WinDbg command window. You can also press the SYSREQ key on the target.

2. Choose Edit, then Breakpoints, from the WinDbg menu and choose Clear All. It is important to clear breakpoints before breaking the connection between host and target.

3. From the Run menu, choose Go (or use the toolbar button) to release the target for continued execution.

4. From WinDbg, choose File, then Exit.

The target may still run sluggishly for a time after disconnecting from the host, but should recover shortly. This may be due to the fact that KdPrint and DbgPrint routines no longer have a connected debugger to which they can send output.

Setting Breakpoints

Setting breakpoints in live code is often the most attractive way to chase bugs in drivers. The technique is actually overblown in that stopping the system for a breakpoint is a remarkably invasive action. Frequently, intermediate or trace output judiciously placed in driver code yields superior results. However, there is comfort in the knowledge that this incredibly fast system has completely paused while the slow human takes time to sort things out and poke around.

To set a breakpoint with WinDbg, perform the following:

1. If the target machine is running, type Ctrl-C in the WinDbg command window to pause the target and regain control. Breakpoints cannot be set if the target is running.

2. From the File menu, choose Open. This allows any source code module to be opened within the host's WinDbg session.

3. Move the cursor onto a source code line where the desired breakpoint is to be set. If choosing a multiline C statement, choose a position that includes the statement's semicolon.

4. Click on the breakpoint button in the toolbar. (It resembles a raised hand.) If the driver is currently loaded into memory, the source code line turns red. Otherwise, the line is colored magenta.

5. Resume the target by clicking the Go button on the toolbar. Just prior to the source-code line executing, control is returned to the host and the breakpoint source code line turns green.

To remove a breakpoint, pause the target, select the source code line, and click on the breakpoint button. The Edit, Breakpoints menu item allows the removal of multiple breakpoints.

Setting Hard Breakpoints

Given WinDbg's interactive capabilities, there are not many reasons for putting hard breakpoints into driver code. When the need arises, the following two calls can be used:

 VOID DbgBreakPoint(); VOID KdBreakPoint(); 

KdBreakPoint is just a macro that wraps a conditional compilation directive around a call to DbgBreakPoint. The macro generates no call if the driver is built for release (free build).

Beware: Windows 2000 crashes with a KMODE_EXCEPTION_NOT_HANDLED STOP message if a driver encounters a hard-coded breakpoint and the kernel's debug client is not enabled. If a driver hits a breakpoint and there is no debugger connected to the serial line, the target hangs. Sometimes, this situation can be rectified by launching WinDbg on the host, after the fact.

Intermediate Output

Debugging code by sprinkling printf statements throughout has a long and honored tradition. The technique is sometimes called generating intermediate output. In fact, there is probably no bug that cannot be found by sufficient and proper use of intermediate output.

The technique lacks the glamour of breakpoint debugging, but is often better suited for chasing timing-sensitive bugs. The two routines to generate trace messages DbgPrint and KdPrint are described in Table 17.2. Both send a formatted string generated on the target to WinDbg on the host.

Table 17.2. DbgPrint and KdPrint Function Prototype

ULONG DbgPrint or KdPrint
Parameter	Description
PCHAR formatString	printf-like string to control format of remaining arguments
arguments	vararg list of arguments, printf style

Since KdPrint is actually a macro (defined in NTDDK.H), an extra set of parentheses is required in order to pass a variable-length list of arguments. The KdPrint macro becomes a no-op in retail (free) builds of a driver.

< BACK  NEXT >