Tips on Using WDEB386

This article was previously published under Q72379
This article has been archived. It is offered "as is" and will no longer be updated.
The WDEB386 debugger provided in the Windows Software Development Kit(SDK) has many invaluable features; however, it also has a number ofshortcomings. This article describes some of the things that WDEB386can and cannot do, and provides a few usage tips.

Reasons for Using WDEB386

The WDEB386 debugger was originally written as a Microsoft internal toolfor developing and debugging the enhanced mode layer of Windows. As such,it retains a number of the advanced features that are necessary to debug amultitasking, protected mode system. At the same time, the low-level natureof this debugging environment can be unwieldy and confusing in manysituations. However, there are many situations where this debugger isparticularly useful, or even totally necessary, to diagnose problems suchas the following:

  • Tracing through low-level code that CVW will not trace
  • Viewing virtual/linear/physical memory
  • Viewing advanced 386 processor data, such as the GDT, LDT, IDT, and all of the PMODE registers
  • Tracing hardware interrupt handlers
  • Tracing terminate-and-stay-resident (TSR) programs, or MS-DOS device drivers
  • Displaying the status of virtual machines (VMs)
  • Monitoring all interrupts and exceptions in enhanced mode
  • Developing and debugging virtual devices (VxDs) for enhanced mode
This is not an exhaustive list; however, it should serve to illustrate someof the situations where the WDEB386 debugger might typically be used.

Breaking into the Debugger on Startup

One command-line option that was not mentioned in Chapter 9 of the"Microsoft Windows Software Development Kit Tools" manual is the /Boption. Specifying /B on the WDEB386 command line instructs thedebugger to halt execution during Windows startup. This option doesnot guarantee that the debugger will halt execution on the very firstinstruction run. In fact, the debugger does not halt execution untilafter Windows has loaded VxDs, just prior to initialization.

Breaking into the Debugger in General

When WDEB386 is running, execution of the current instruction streamcan be halted with the CTRL+ALT+SYS RQ key combination. This will notstop execution at the precise location of the keyboard interrupt;execution will halt at a location in the virtual machine manager(VMM). The register contents of the interrupted virtual machine can beinspected using the .VM command (see below).

Alternatively, breakpoints can be set with the BP command, or withinterrupt instructions assembled directly into the code. Either an INT1 or INT 3 instruction can be used. The difference is that an INT 1will produce an "Unexpected trace interrupt" message and stop on theinstruction AFTER the INT 1. This message does not indicate an errorcondition and can be ignored. An INT 3 will break directly on the INTand not produce the message. Once a breakpoint instruction is hit, itcan be removed permanently with the "Z" command. This command replacesthe INT machine language with NOPs (No OPeration).

Also, if the necessary hardware is available, the nonmaskableinterrupt (NMI) can be used to break into the debugger. This usuallymeans having an external "STOP" button connected to a debugging cardinstalled in a slot of the development machine. Some machines may havethe capability of connecting a front panel button to the NMI line onthe machine bus. In any case, using NMI has the advantage of beingable to break into a machine that has "hung" with interrupts disabled.

For programmers developing virtual device drivers (VxDs), theDebug_Out macro is available to combine sending an ASCII string to thedebug terminal and executing an INT 1, which will break to thedebugger.

Using WDEB386 in Standard Mode

The WDEB386 debugger is provided mainly for enhanced mode debugging;however, it can also be used in standard mode on a 386 processor. Ingeneral, operation of the WDEB386 debugger in standard mode is thesame as in enhanced mode, except that a number of features areunavailable, particularly in Windows 3.0.

For example, the "/b" option to break on startup is only available inenhanced mode on Windows 3.0. It is available in standard mode on Windows3.1. Many of the "dot" commands (commands prefixed with a period) areprovided for enhanced mode and are not available in standard mode.

Determining the State of the Processor

Once control has been given to the debugger, the prompt character usedwill provide the protected mode status of the processor. The followinglist shows what prompt characters may be displayed and the meaning ofeach:
    Character  Meaning    ---------  -------       >       The processor is in real mode       #       The processor is in protected mode       -       The processor is in virtual 8086 mode				
The mode the processor is in will be a good indication of what code isbeing executed. For example, if the prompt is a "-" (hyphen), thecurrent instruction stream is somewhere in MS-DOS, the BIOS, or possiblyin a TSR or MS-DOS device driver. This is because the enhanced mode layerof Windows must switch the processor to V86 mode to run MS-DOS or BIOSfunctions. Alternatively, if the prompt is a "#" (number sign),protected mode code -- which could be a Windows-based application, DLL, oreven the enhanced mode layer -- is running.

One of the most important aspects of "knowing what is running" whenusing WDEB386 under Windows in enhanced mode is some awareness ofWIN386.EXE. This module consists of the VMM (virtual machine manager)and all VxDs (virtual devices). These components are oftencollectively referred to as the "enhanced mode layer," "ring zerocode," or just "WIN386." Under Windows 3.0 and 3.1, and Windows forWorkgroups, versions 3.0, 3.1, and 3.11, if the debugger prompt is a "#"and the value of the CS register is 0028h, it means the machine is stoppedin WIN386.

Stopping in WIN386 may or may not be desirable. For example, theability of WDEB386 to stop in WIN386 enables VxD developers to single-step through the VxD in question. However, an application or devicedriver programmer using WDEB386 because of its "protected modeawareness" may have no interest in what WIN386 is doing. In any case,recognizing the system component associated with the current executionstream is a crucial step in using WDEB386 effectively.

Using the Dot Commands

Probably the most interesting (and confusing) part about using WDEB386concerns the "dot" commands, which are commands preceded by a period.One of the causes of the confusion is that unless the debuggingversion of WIN386.EXE is installed, most of the dot commands areunavailable. For example, if the following message is displayed whileWindows is running in enhanced mode
Win386 not loaded, not debug version, or not responding
it most likely means that the retail version of WIN386.EXE isinstalled. For more information on installing the debugging version ofWIN386, query on the words:
prod(winddk) and wdeb386
Additionally, this message will always appear if WDEB386 is used whenWindows is in standard mode.

Dot Dump Commands

Conceptually, the dot commands are "external" commands, or commandsthat operate on data structures and operations specific to the Windowsenvironment. For example, the "D" (dump) command displays memorylocations as would be expected from a debugger, but the ".DG" commanddisplays Windows global heap information in much the same way as theHEAPWALK application.

Most of the .Dx commands do not require the debugging version ofWIN386.EXE, and are also available under standard mode. The remainderof the commands described in this article require both the debuggingversion of WIN386.EXE and enhanced mode operation. Once EVERYTHING isinstalled correctly, the ".?" help command should provide an onlinequick reference of the dot commands.

One important distinction that should be made is the differencebetween the "K" and the ".DS" commands. The "K" command will walk theWindows stack as long as the debugger is stopped in Windows-basedapplication or dynamic-link library (DLL) code. However, if thedebugger is tracing through WIN386 code, the "K" command will notproduce any useful output. For this reason, the ".DS" command has beenprovided to display the WIN386 stack. This is another demonstration ofthe importance of "knowing what is running," as mentioned previouslyin this article.

Dot VM Commands

WDEB386 was originally designed to debug the enhanced mode layer ofWindows; therefore, there may be situations in which the debugger isstopped in the middle of WIN386. For example, if execution is haltedusing CTRL+ALT+SYS RQ, the machine will not stop immediately at theinstruction that was running, but rather at a breakpoint in WIN386code. Thus, the general registers do not normally contain anythingthat will be of any use to a developer trying to debug a driver or anapplication.

However, the operating status of the current virtual machine can bedisplayed by using the .Vx commands. For example, ".VM" will displaythe status flags, register contents, current instruction, and aportion of the stack of the current VM. Typing ".VL" will produce alist of all of the VMs in the system. These commands can be used toget an overview of the application, DLL, MS-DOS, or BIOS execution state,as opposed to the state of WIN386.

Dot Memory Commands

The .Mx commands display advanced information on the state of memory.Many of the functions print internal WIN386 information in a morereadable format. Two commands that are immediately useful are ".ML"and ".MP". These commands convert addresses from linear to physical,and vice versa.

Dot Trace Commands

The ".T" and ".S" commands provide for keeping interrupt traceinformation. The trace entries describe what interrupts have occurred,the VM block address, and the interrupted instruction address. Thesecommands can be extremely helpful in tracking down problems (bugs)that do not produce immediate symptoms.

Dot Device Commands

WIN386 and WDEB386 provide the ability for an individual VxD todisplay information about its own operating state. In general, theuser can request this debugging information from a VxD by at the WDEB386 prompt, where "name" is the name of the VxD.For example, typing .VDMAD produces information about the state ofthe virtual DMA device.

Issuing a dot device command will cause VMM to send a "Debug_Query"message to the VxD. The VxD is not required to do anything in responseto this message, and in fact many VxDs do not produce any debuggingoutput. In general, output produced by VxDs in this manner is notdocumented, and is only provided as a means of debugging the VxD inquestion. VxD developers may want to take advantage of this mechanismto display important data structures that define the state of thevirtual device.

Dot Command Summary

The dot commands are summarized in Section 9.6 (page 9-48) of the"Microsoft Windows Software Development Kit Tools" manual. An onlinequick reference screen is available with the ".?" command.

Note: A number of the dot commands are not documented in the SDK toolsmanual. For example, the format of the dot device command isdescribed, but the actual output produced by specific virtual devicesis not given. There are a number of reasons for this:

  • The output produced by the dot commands usually is not produced by the WDEB386 debugger, but rather by components of WIN386. These components are being revised and updated more dynamically than the debugger, and so the information produced by these components is likely to change.
  • The output is often very specific information about the VxD itself, and would not normally be useful in a typical debugging situation.
wfw 3.00 3.10 3.11

Article ID: 72379 - Last Review: 01/05/2015 03:58:33 - Revision: 1.1

  • Microsoft Windows Device Development Kit (DDK) for Windows 3.0
  • Microsoft Windows Device Development Kit (DDK) for Windows 3.1
  • kbnosurvey kbarchive KB72379