Wdeb386 debugger

Microsoft Corporation

The Windows 95 Device Driver Kit

WDEB386 System Debugger

©Copyright 1996, 1998 Microsoft Corporation. All rights reserved.

Document Amendment HistoryRevision Date

Section Subject

980112.1 Chapter 3 Added Quick Reference information

980112.2 Chapter 3 Added IW, ID, OW, OD command descriptions

980113.1 (intro) Added Additional Resources list

980120.1 Chapter 1 Incorporated KB article Q163358 and expanded on use of debug binaries

980506.1 (all) Additions and enhancements including OSR21 debug binary info and additional dot command info

Additional Resources:

Knowledge Base (MSDN Library CD)

Title (Use the title as the search key when querying the MSDN Library CD)

Comments

Q58010, “WDEB386 Debugger’s Use of COM Port”

Using the /C: command-line switch

Q64123, “PRB: Encountering an INT01 with WDEB386”

Interpretation of debugger halting on an INT01

Q72379, “Tips on Using WDEB386” WINDOWS 3.x Info that applies to Windows 3.0/3.1 debugger only.

Q73333, “PRB: WDEB386 Does Not Find Driver Symbol Files”

WINDOWS 3.x Info that applies to Windows 3.0 / 3.1.

Q74605, “Advanced WDEB386 Features and Tips”

Information about breakpoints (bp / br), conditional execution (j) and the default command (z)

Q75252, “Tips on Installing WDEB386” WINDOWS 3.x Info that applies to Windows 3.0/3.1 debugger only.

Q76473, “PRB: No Output from VxD Debug_Out and Trace_Out Macros”

How to properly install WIN386.EXE

Q77987, “Debugging GP Faults with WDEB386”

WINDOWS 3.x Interpreting GP Faults with Windows version 3.0 / 3.1

Q85897, “WDEB386-Compatible Timing Card Available”

Third party timer card supporting the gs and gh commands

Q94671, “Categories and Keywords for All Knowledge Base Articles”

General KB search keywords

Q105275, “Using the ‘BR’ Command in WDEB386.EXE

More information about hardware breakpoints

Q114473 “Intel Privileged and Sensitive Instructions”

The Intel architecture defines "privileged" instructions and "sensitive" instructions.

Q118331, “How to Search for Windows DDK Articles by KBSubcategory”

Device Driver KB search keywords

Q121093 “Points to Remember When Writing a Debugger for Win32s”

This article is intended for developers of debugging tools for the Win32s environment. It covers the issues that should be to taken into consideration while writing debugging tools for the Win32s environment.

Q125868 “How to Display Debugging Messages in Windows 95”

This article is mainly applicable to using WDEB386 while developing Win16 code

Q141160 “How To Build Environment Required for Printer Drivers”

Printer driver debugging techniques

Q163358, “PRB: DDKDEBUG.BAT Copies Some Drivers to the Wrong Directory”

The DDKDEBUG batch file copies all debug binaries to the \windows\system\vmm32 path, but some of the binaries belong elsewhere. The contents of this KB article have been incorporated

into the document you are currently reading.

Q138983 “PATCH: MASM 6.11d Patch Available”

See the file README.TXT contained in this update for other information and installation instructions.

Q173168 “PATCH: MASM 6.12 Patch Available”

See the README.TXT contained in this update for other information and installation instructions.

Q177759 “PATCH: MASM 6.13 Patch Available”

Updates MASM 6.1x to accommodate new Pentium Pro, MMX and AMD 3D features.

Q175416 “HOWTO: Obtain a NDIS Trace on Win95 for an NDIS Driver”

NDIS debugging techniques

Q182539 “HOWTO: Debug NDIS WAN Miniports for MSDUN 1.2x”

This article shows you how to set tracing options to debug Network Driver Interface Specification (NDIS) wide area network (WAN) Miniports on Windows 95 with Microsoft Dial-Up Networking 1.2x. It also includes the address of the Web site you can visit to download debug binaries.

The Little Device Driver Writer Intro to writing Windows 95 and Windows NT hardware device drivers, including the I/O models, driver design and debugging strategies

The VxD Writer’s Resource Book, or VxD Writing as a Martial Art

An overview of virtual device driver (VxD) programming and a comprehensive reading list.

What's New in Windows 95 for VxD Writers? Explains the changes that VxD writers have to expect when porting VxDs to Windows 95.

Table of Contents

Table of Contents

CHAPTER 1. THE WINDOWS SYSTEM DEBUGGER .................................................................7

Setting up the Microsoft Windows System Debugger .........................................................................7How do I get started? .......................................................................................................................7How do I handle transmission speed issues without handshaking? ................................................7How do I change the COM port? .....................................................................................................7What is a null-modem serial cable? .................................................................................................8Can I use a Laplink V serial cable with WDEB386? .......................................................................8How do I disable handshaking on Windows 95? .............................................................................8How do I set up WDEB386? ............................................................................................................8How do I start up WDEB386? .........................................................................................................8Where can I find out about WDEB386 commands? ........................................................................9What do I do if I don't have another computer with a serial port? .................................................9I'm an NT developer. Can I use windbg for kernel debugging on Windows 95? ............................9What should I do if I can't get WDEB386 to work? ........................................................................9Can I use WDEB386 as a VxD? ......................................................................................................9How do I set up WDEB386 as a VxD? ..........................................................................................10How do I change the baud rate or COM port with the VxD version of WDEB386? ....................10

Preparing to Start ................................................................................................................................10Connecting the null-modem Serial Cable ..........................................................................................10Creating Symbol Files ........................................................................................................................11What are Debug Binaries....................................................................................................................11Installing Debug Environment ...........................................................................................................12Starting from the Command Line .......................................................................................................15Starting as a VxD ................................................................................................................................16

CHAPTER 2. USING THE SYSTEM DEBUGGER .......................................................................18

Breaking into the Debugger ...............................................................................................................18Determining the State of the Processor ..............................................................................................19Setting Breakpoints .............................................................................................................................20Using symbols with WDEB386..........................................................................................................22Setting the Default Command ............................................................................................................23If you stop in the debugger..................................................................................................................24

If you don't know why you stopped.................................................................................................24Hard-coded traps into the debugger...............................................................................................24If your code is at a fault...................................................................................................................24If Ln cs:eip gives you a name..........................................................................................................25

CHAPTER 3. REFERENCE ..............................................................................................................26

Command Quick Reference................................................................................................................26Command Syntax ................................................................................................................................34

Parameters ......................................................................................................................................34Binary and Unary Operators .........................................................................................................35Regular Expressions .......................................................................................................................36

Command Details................................................................................................................................38Dot Commands ...................................................................................................................................66

CHAPTER 4. OTHER TOOLS .........................................................................................................82

ADRC2VXD .......................................................................................................................................82DEVLIB ..............................................................................................................................................83

Table of Contents

EXE2BIN ............................................................................................................................................83HDR ....................................................................................................................................................83INFEDIT .............................................................................................................................................84SYMLIB .............................................................................................................................................84

错误！未定义样式。

Chapter 1. The Windows System Debugger

Microsoft Windows System Debugger (WDEB386.EXE) is used to test and debug Windows applications, dynamic-link libraries (DLLs), and virtual device drivers (VxDs) running with the Microsoft Windows operating system. You use System Debugger commands to inspect and manipulate memory and registers, control the execution of code, and perform other debugging operations. The chapter describes the debugger, explains how to start and use the debugger, and provides detailed information about the debugger commands.

Setting up the Microsoft Windows System Debugger This section is a list of frequently asked questions about setting up kernel debugging for Microsoft Windows 95. You'll find answers here about getting started with the System Debugger (WDEB386). Additional information can be found in the MSDN Library CD (check out the Additional Resources section, located at the beginning of this document).

How do I get started? You need a computer with a serial port, and you'll need to buy or make a null-modem cable. You only need a three-line null modem cable (transmit, receive, and ground). You don't need one with handshaking lines because WDEB386 doesn't use handshaking. You should also disable handshaking on your computer (Handshaking allows slower receivers to keep up with the amount of data being transmitted by telling the transmitter to stop sending data until it has a chance to catch up).

How do I handle transmission speed issues without handshaking? Because handshaking is disabled, it is possible that WDEB386 could send characters to the terminal faster than the terminal can display them. If you find that characters are dropped, you should increase the delay between lines (often a terminal drops characters while scrolling). Use the y CRDELAY=delay debugger command where "value" ranges from 0 (no delay) to FFFF (maximum delay). Increase the delay until your terminal stops dropping characters. You can also lower the speed of the connection. To do this, use the /c: command-line option with WDEB386 to set the baud rate.

How do I change the COM port? Use the /r: command-line option with WDEB386 to change the COM port. By default, WDEB386 uses COM1 at 19200 bits per second (bps).

Page 7


What is a null-modem serial cable? Typically with serial ports, you connect a computer to something like a modem. This is how serial ports are designed: you connect a computer, or Data Terminal Equipment (DTE), to a modem, or Data Communication Equipment (DCE). When you connect a computer to another computer, or DTE to DTE, you need a special cable called a null-modem cable. WDEB386 requires only the most basic null-modem cable, the three-line null-modem cable. The following illustration shows the null-modem cable's connectors. (The pin numbering would be backwards if you were looking at the computer's ports.)

5

789

12

6

345

789

12

6

34

The following table shows the pin numbers and names of the cable's three lines: Pin Name

Pin 2 Receive

Pin 3 Transmit

Pin 5 Ground

Can I use a Laplink V serial cable with WDEB386? Yes. The blue Laplink cable works fine. Remember to disable handshaking.

How do I disable handshaking on Windows 95? 1 Using your right mouse button, click My Computer, and then click Properties.

2 In the System Properties dialog box, click the Device Manager tab.

3 In the list of device types, double-click Ports (COM & LPT).

4 Double-click the name of the port the cable is connected to, usually Communications Port (COM2).

5 In the Communications Port Properties dialog box, click the Port Settings tab.

6 In the Flow Control list, click None.

7 Click OK.

How do I set up WDEB386? 1. Install the Windows 95 Device Driver Kit (DDK).

2. At the command prompt, go to the Debug subdirectory of the directory you installed the DDK in.

3. Follow the instructions in the section in this document titled “Installing Debug Environment”.

How do I start up WDEB386? The Ddkdebug batch file creates Runwdeb.bat in the System subdirectory of your Windows directory. Runwdeb.bat is a batch file that starts WDEB386. To use this batch file to start WDEB386, carry out the following procedure:

1. Click the Start button, and then click Shut Down.

Page 8


2. In the Shut Down Windows dialog box, click the option that enables you to restart the computer in MS-DOS mode, and then click Yes.

3. If you want to change the COM port or baud rate, edit runwdeb.bat. The /c: option determines the COM port, and the /r: option determines the baud rate.

4. At the command prompt, go to the System subdirectory of your Windows directory, type the following, and then press ENTER:

runwdeb.

Where can I find out about WDEB386 commands? See Chapter 3, Reference.

What do I do if I don't have another computer with a serial port? You can use screen swapping. This requires that you set the resolution of your computer to 640 x 480 with 16 colors and add the following line to the [386Enh] section of System.ini: debugvga=1

To start the debugger, press the F12 key.

I'm an NT developer. Can I use windbg for kernel debugging on Windows 95? No, you can use only WDEB386 or a third-party debugger such as SoftIce/W for kernel debugging.

What should I do if I can't get WDEB386 to work? • Make sure you are using the WDEB386 contained in the Windows 95 DDK (build 950). You

need this version to work with the retail version of Windows 95.

• Run Direct Cable Connection (DCC) to make sure your null-modem cable works. DCC is optionally installed with Windows 95. To see if it is installed, click the Start button, point to Accessories, and then look for Direct Cable Connection in the menu. If it is not there, use the Add/Remove Programs Control Panel to install it.

• Make sure handshaking is disabled on your computer.

• If the debugger stops responding partway through boot, this could be because you have a debugcom or debugbaud line in your system.ini file. These entries override the values provided on the wdeb386 command line.

• If the debugger is dropping characters or if you see garbage characters when doing large output, type y crdelay=8000 to slow down the delay between lines. The value of crdelay is a hex value from 0000 to FFFF. You may have to experiment with the crdelay value.

• If you are running out of memory with the debugger, use the command line option /L, which will have the effect of shrinking symbol files by a factor of three.

• Each symbol file uses an XMS handle. If you run out of handles, edit CONFIG.SYS to containdevice=himem.sys /NUMHANDLES=32.

Can I use WDEB386 as a VxD? Yes, and you'll save about 90K of conventional memory. You won't, however, be able to access symbols until after the Device_Init message is sent to your VxDs (during Windows 95 startup). So if

Page 9


you use the /b option with WDEB386 to break in VMM32 initialization, the debugger will have no knowledge of symbols until Device_Init is sent.

How do I set up WDEB386 as a VxD? The Ddkdebug.bat batch file creates a file called WDEBVXD.INS (the original file name is WDEBVXD.TMP) in the Debug subdirectory of the directory you installed the DDK in. You should insert the contents of this file into the [386Enh] section of System.ini. Make sure you comment out the following WDEB386 device lines from the [Enh386] section of System.ini when you restore the retail version of Windows 95: Device=WDEB386.EXEDevice=DEBUGCMD.VXD

For information about restoring the retail version of Windows 95, see "How do I set up WDEB386?"

How do I change the baud rate or COM port with the VxD version of WDEB386? To change the COM port, change the value in the debugcom= line in the [386Enh] section of System.ini. The following entry sets the COM port to COM2: debugcom=2

To change the baud rate, change the value in the debugbaud= line. The following entry sets the baud rate to 19,200: debugbaud=19200

Note that the values in System.ini will override prior WDEB386 command-line settings for the baud rate and COM port.

Preparing to Start You can start the System Debugger as an application from the real-mode command line or as a virtual device driver by specifying it in the SYSTEM.INI file. Before you start, however, you prepare for debugging by carrying out these steps:

• Connect a serial terminal or other computer by serial cable to a serial port on your debugging computer.

• Create symbol files for the applications, DLLs, and VxDs you intended to debug (see Creating Symbol Files below).

• Install the system debug environment if available (see Installing Debug Environment). These are debugging versions of the system DLLs and VxDs and their symbol files that can make debugging easier. These files are available in the Windows 95 Device Driver Development Kit.

Connecting the null-modem Serial Cable The debugger displays output and receives user input through a serial communication port of the computer on which it runs. To use the debugger, you must connect the null-modem cable from this serial port to either a serial terminal or the serial port of another computer. A three-wire null modem cable is the minimum cable requirement for this connection. Typically, users connect the cable to a second computer and use their favorite serial communications software to connect to the serial port and interact with the debugger. The Windows 95 operating system comes with the serial communication program Hyperterminal.

Page 10


Creating Symbol Files Symbol files provide the information the debugger needs to display functions, structures, variables, and absolute symbols by name rather than number. To prepare symbol files, perform the following steps: 1. Compile or assemble your source files, using the appropriate command-line option to generate

object files with line-number information. For more information about compiler and assembler options, see the documentation that accompanied your compiler and assembler.

2. Link the compiled code with the standard libraries (as needed), using the appropriate linker option to create a symbol map (.MAP) file that includes PUBLIC symbols. You may also want to use the linker option for display of line-number information. For more information about linker options, see the documentation that accompanied your linker.

3. Run the Microsoft Symbol File Generator (MAPSYM.EXE) to create a symbol file for symbolic debugging. MAPSYM converts the contents of your application's symbol map (.MAP) file into a form suitable for loading with the debugger; then MAPSYM copies the result to a symbol (.SYM) file.

Following is the command-line syntax for MAPSYM: mapsym [/l][/n] mapfilename /l Directs MAPSYM to display information on the screen about the conversion. The

information includes the names of groups defined in the application, the application start address, the number of segments, and the number of symbols per segment.

/n Directs MAPSYM to ignore line-number information in the map file. The resulting symbol file contains no line-number information.

mapfilename Specifies the filename for a symbol map file that was created during linking. If you do not give a filename extension, .MAP is assumed. If you do not give a full path, the current directory and drive are assumed. MAPSYM creates a new symbol file having the same name as the map file but with the .SYM extension.

In the following example, MAPSYM uses the symbol information in FILE.MAP to create FILE.SYM in the current directory on the current drive: mapsym /l file.map

Information about the conversion is sent to the screen. MAPSYM always places the new symbol file in the current directory on the current drive. MAPSYM can process up to 10,000 symbols for each segment in the application and up to 1024 segments. If you have many components to debug, you can combine multiple symbol files into a single file by using the Symbol File Librarian (SYMLIB.EXE). This creates a symbol library file and lets you add, remove, or replace .SYM files in it.

What are Debug Binaries

Debug binaries are Windows 95 kernel VxDs that are typically compiled with the DEBUG=1 statement contained in the corresponding makefile. Note the historic difference in nomenclature between Windows and Windows NT documentation:

Windows 3.x, Windows 9x Windows NT Meaning“Retail” “Free build” Normal retail code build“Debug binary” “Checked build” Debug code build

Page 11


You do not need to use the debug binaries in order to run and use the debugger. However, debug binaries are extremely helpful when troubleshooting your VxD:

• Debug binaries contain additional code that issues message(s) to the debugger terminal. These messages contain valuable informational info, warning info, and/or error info.

• Debug binaries frequently contain special debugger “dot command” handling code, not present in the retail drivers (See System Dot Commands). Dot commands are intended to reveal the contents of internal data structures unique to the driver that support the Dot command.

• Debug binaries perform additional verification of data and pointers (using ASSERT functions for example). For example, if a pointer is found to be null and it shouldn’t be, debug binaries may contain an INT1 or INT 3 breakpoint, causing the debugger to automatically halt at that point (see Breaking Into the Debugger).

• If symbol files are provided with the debug binary VxD, use them, to make it easier to navigate through the code.

Installing Debug Environment Do not depend on using the DDK’s DDKDEBUG.BAT batch file to copy debug binaries to their proper locations. Instead, copy debug binaries to the locations indicated in KB article Q163358 (reproduced below).

The DDKDEBUG.BAT file was originally intended to, among other things, allow the customer to copy debug binaries from the DDK to the windows environment. The user was to type ddkdebug set to install the debug binaries, and ddkdebug restore to remove them.

However, there is a bug in the ddkdebug.bat file, described in the following paragraphs.

NOTE:The KB Article, Q163358, “PRB: DDKDEBUG.BAT Copies Some Drivers to the Wrong Directory”, describes a problem in the DDKDEBUG.BAT file. A summary of this KB article follows:

If you use the \ddk\debug\ddkdebug.bat file to set the debug environment, it does not work correctly.

CAUSE=====

When you use the ddkdebug.bat file to set the debug environment, the batch file simply copies all the *.vxd files to the \windows\system\vmm32 directory. This directory is not the proper location for some of these drivers.

RESOLUTION==========

Here are the correct target locations to copy the debug drivers. If debugging Golden Windows 95, the debug binaries are located in the \ddk\debug directory. If debugging Windows 95 version OSR2 (“version “B”), see below for instructions on how to obtain the OSR2 debug binaries.

Driver file name Required target directory Comments

Page 12


bios.vxdconfigmg.vxdios.vxdvdd.vxdvdmad.vxdvflatd.vxdvkd.vxdvmcpd.vxd1

vmm.vxdvpicd.vxdvxdldr.vxd

\windows\system\vmm32 Replacements for components that were originally “bound” into vmm32.vxd.

cdtsd.vxdcdvsd.vxddisktsd.vxddiskvsd.vxdscsiport.pdr

\windows\system\iosubsys IOS layered hierarchy drivers

eisa.vxdisapnp.vxdlptenum.vxdndis.vxdpccard.vxdpci.vxd

\windows\system All other VxDs

debugcmd.tmp \windows\system\debugcmd.vxd Installed for additional debugger dot commands (see System Dot Commands, .P). Note that the file extension needs to be renamed from “.tmp” to “.vxd”.

Windows 95 Version OSR 2.1 (USB Support)

Driver file name Required target directory CommentsVMM.VXDVPICD.VXDVXDLDR.VXDNTKERN.VXD

\windows\system\vmm32 Replacements for components that were originally “bound” into vmm32.exe.

USBD.SYSOPENHCI.SYSUHCD.SYSUSBHUB.SYS

\windows\system32 WDM driver components

WIN.COM starts VMM32.VxD (formerly DOS386.EXE). During setup, many standalone VxDs are bound into one large file named VMM32.VxD. The number of VxDs bound can vary from machine to machine. This is done for quicker loading. However, there is still a separate, smaller VxD called VMM32.VxD, whose job is to load static system VxDs. The “bigger” VMM32.VxD contains it. The loader VMM32.VxD will first search for and load standalone VxDs located in the path \windows\system\vmm32. These VxDs replace VxDs by the same name that were bound into VMM32.VxD at setup time. Therefore, debug binary vxds that are placed into \windows\system\vmm32 will replace their (retail build) counterparts located in the bound VMM32.VxD. Within the registry or in SYSTEM.INI, an asterisk preceding a driver name (e.g. *VPICD, *VDMAD) indicates the driver is a “child” VxD located within VMM32.VxD. The driver replacement rules, just described, also apply to these child device references.

1 Supplied with OSR2 debug binaries only

Page 13


The Windows 95 path \windows\system\iosubsys contains I/O Supervisor (IOS) drivers. IOS is a layered hierarchy of drivers, implementing protected-mode 32 bit disk I/O. The drivers in this path are loaded by *IOS during its DEVICE_INIT phase.

The Windows 95 path \windows\system contains all other VxDs.

If you manually copy debug binary drivers, we recommend that you back up or rename any VxD’s that go by the same name in the target path, so you can restore the normal VxDs later.

The original debug binaries in the original Windows 95 DDK are intended for the use with the original (Golden) version of Windows 95. If debugging Windows 95 version b (OSR2), or version 2.1 (USB / WDM support) obtain the OSR2 or OSR21 debug binaries, located at the following Microsoft web site:

http://support.microsoft.com/support/ddk_hardware/winddk/tools/

Alternatively, go to the Microsoft Support site (http://support.microsoft.com/support) and search using the following keys:

1. My search is about: Device Drivers2. I want to search for: osr2 debug binaries

You can also use DDKDEBUG.BAT to remove the system debug environment and restore the original system files, by typing ddkdebug restore. However, the same problem regarding the ddkdebug set issue still needs to be addressed.

The RUNWDEB.WRF file contains command-line options for the debugger. This file along with RUNWDEB.BAT is copied to the WINDOWS\SYSTEM directory (provided that files with these names are not already present in that directory). Before you can use RUNWDEB.BAT, you may need to edit it to contain the correct debug settings. These settings are: /c: Number that represents the COM port to which debug terminal is attached. For example: /c:1

/r: Baud rate at which debug terminal will be operating. For example: /r:19200

You can add any other desired command line options to this file.

You will likely need to edit the RUNWDEB.WRF to add /s: options for the symbol files of the components you intended to debug. Remember that the symbol file(s) installed must match the corresponding binary, both in (Windows 95) version and the distinction between retail or debug versions.

Once you have completed editing these files and verifying settings, you can start the debugger by running RUNWDEB.BAT (with one optional WDEB386 command line parameter) from the WINDOWS\SYSTEM directory.

Debugging WDM Drivers

All WDM debugging under Windows 95/98 should be done with a standard Win95 system debugger such as WDEB386 or SoftIce. Debug output from WDM drivers such as a USB driver will not be displayed in real-time, unlike other Win95 debug components such as VxDs. Instead all WDM debug output is written to a debug log. To view this log you must use the debug interface of NTKERN.VXD. This is accomplished by breaking into the debugger and then typing ".NTKERN". You then type "D" to dump the NTKERN debug log. Note that the log is dumped in reverse order, meaning the first debug message displayed in the log is the one most recently logged. No debug

Page 14

http://support.microsoft.com/support

http://support.microsoft.com/support/ddk_hardware/winddk/tools/


binaries are required to use the debug log in NTKERN.VXD.

Starting from the Command Line You can start the debugger from the real-mode command line by using the WDEB386 command line. (You cannot start the debugger from the command line after WIN.COM has started. To get the real-mode command line, press the F8 key as Windows starts and choose the Command Prompt Only option.) The command line has this syntax: wdeb386 [/A] [/B] [/C:comport] [/D:"commands"] [/E] [/F:filename] [/H] [/I] [/L] [/N] [/T:hhhh] [/S:symfile] [/V[P]] [/X] winfile [parameters]

Following are the command-line options and parameters: /A Specifies that symbol files should not be automatically loaded.

/B Specifies that the debugger should stop just prior to VMM initialization, after all virtual devices have been loaded and the processor is running in protected mode. This option is useful if you want to install breakpoints early. Also, if you use the debugger’s .VMM s command at this stop point, you can turn on verbose device tracing which displays the name of each VxD before it is called, and OK when the VxD returns.

/C:comport Specifies a COM port for debugger output. You can specify "1", "2", "3", or "4" for comport. If this option is not specified, The debugger checks first for COM2. If COM2 is not found, the debugger then checks for COM1. If neither COM1 nor COM2 exists, the debugger checks for any other COM port in the read-only memory (ROM) data area (40:0).

/D:"commands" Carries out the debugger command line specified by the string enclosed in quotation marks. Spaces, semicolons (;), and other punctuation can be included in the command string. To use a single quote (') on the command line, use double quotation marks (") before and after the single quotation mark.

The commands specified in this option are carried out after symbols are loaded. This means you can set breakpoints in code even before the code has been loaded. Before a segment or module has been loaded or defined, breakpoints can be set on the logical address (a combination of map number and group number) until the segment or module is defined, at which point the breakpoint turns into a real breakpoint.

/E Specifies that the debugger should stop at real-mode entry.

/F: filename Specifies a file containing command-line options for the debugger. Maximum file size is 4K, and the input file cannot contain the /F option.

/H Specifies that the debugger should be loaded as a VxD.

/I Specifies that the debugger should be invisible to int 41.

/L Specifies that line numbers should not be included in the .SYM file. This can make a large difference in memory use, and may be required on a machine with 4 megabytes of RAM.

/N Sets the following options:

dislwr

codebytes

symaddrs

int3line

newvec

Page 15


newreg

newprompt

For information about these options, see the y command in Reference.

/R:dddd Sets the baud rate for the debugging terminal.

/S: symfile Specifies a symbol file to be loaded. This option can be repeated to load more than one symbol file. If the symbol files are not in your current directory, you must supply a full path, because the debugger does not use the PATH environment variable to locate any of the files supplied on the command line.

When memory is low, you can use more symbol files by running the Debugger in the Windows directory and specifying the full path of VMM32.VXD (such as \WINDOWS\SYSTEM\VMM32.VXD) instead of WIN.COM.

/T:hhhh Sets the port number for the timing card (The default number is 250h.). See MSDN Library CD: Q85897, “WDEB386-Compatible Timing Card Available”

/V Enables verbose mode, which displays messages indicating which segments are being loaded.

/VP Enables verbose mode, which displays messages indicating which segments are being loaded. This option displays the messages for applications only.

/X Causes symbols to be loaded into Extended Memory Specification (XMS) memory.

winfile Specifies the Windows application to run under debugger control. You will usually specify WIN.COM.

parameters Specifies any parameters to be passed to the application.

The length of the command line cannot exceed 128 characters. The following example shows a valid command line: wdeb386 /C:1 /R:9600 /F:RUNWDEB.WRF /V \windows\win.com

Starting as a VxD Running WDEB386 as a VxD requires approximately 90KB less of conventional memory than running it from the command line. Its only disadvantage is that loaded symbols aren't available until after SYS_CRITICAL_INIT. You can start the debugger as a virtual device driver by placing the following line in your CONFIG.SYS file: device=c:\windev\wdeb386.exe

You must specify the full path to the WDEB386.EXE file. You can specify any command-line options on the device line with (for example, you can load symbol files), or you can set options by adding one or more of the following debug settings to the [386Enh] section of SYSTEM.INI:

DebugCom=comport Sets the communications port that the debugger uses for input and output. The comport can be 1, 2, 3 or 4, as described for the /C command line option.

DebugBaud=baudrate Sets the baud rate for the communications port used by the debugger.

DebugCmd=parameters Lists the debugger commands to execute as the debugger starts. This is typically used to set command-line parameters. For example, use DebugCmd=y /n /b to enable new options and to initially break into debugger at SYS_CRITICAL_INIT. Multiple commands must be separated by semicolons (;).

DebugSym=symbol-files Specifies the symbol file or files to load.

Page 16


DebugSymCmd=cmds Lists the debugger commands to execute immediately after all symbols have been loaded. Multiple commands must be separated by semicolons (;).

BreakInDebugVxD=value Sets the behavior of the CTRL+C key when pressed on the debug terminal or the CTRL+ALT+SYSREQ key combination when pressed on the computer on which the debugger is running. If value is TRUE, pressing the key stops execution at the current instruction regardless of the privilege (ring) of the code. If FALSE, pressing the keys stops execution in ring 3 code only. The default setting if this entry is not given is TRUE.

If you have the Windows 95 Device Driver Development Kit, you can use the DDKDEBUG.BAT batch file to create a WDEBVXD.INS file that contains the statements that you need to add to the [386Enh] section of SYSTEM.INI. In particular, DDKDEBUG.BAT includes the DEBUGCMD.VXD file that provides additional debugging support. You may need to set the DebugCom and other options to appropriate values. When you no longer want to run the debugger as a VxD, insert a semicolon before the device=WDEB386.EXE (and device=DEBUGCMD.VXD if present) entry in the SYSTEM.INI file. Any debug options settings you added to the file do not need a semicolon; they will be ignored on subsequent loads of Windows 95.

Page 17


Chapter 2. Using the System Debugger

Throughout this document, there are many references to debugger dot commands (those commands that begin with a period, such as .VMM). Many of these dot commands only work when the supporting debug binary is installed. Refer to Chapter 3 for more information on how to install debug binaries, in order to make debug-VxD-specific dot commands available.

There are many situations in which the WDEB386 debugger is the best or even the only debugger you should use. For example, you might use WDEB386 to diagnose problems such as the following:

• Tracing through low-level code

• 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

• Developing and debugging virtual devices (VxDs)

This section gives information about how to use WDEB386 commands and features.

Breaking into the Debugger To execute debugging commands, you need to break into the debugger and have it display its command prompt. You can automatically break into the debugger as Windows starts by specifying /B option on the WDEB386 command line or in a y command with the DebugCmd setting in the SYSTEM.INI file. The debugger stops execution just after loading VxDs and just prior to initialization. Breaking in at Windows start time is useful if you want to setup breakpoints or use the “.VMM S” command to turn on verbose device tracing (which displays the name of each VxD before it is called, and OK when the VxD returns)To break into the debugger at any time interrupts are not disabled, press the CTRL+C key combination on the debugging terminal. Alternately, press the CTRL+ALT+SYSRQ key combination on the computer running the debugger. This stops execution at the next convenient location in ring 0 or ring 3 code. To break into the debugger when interrupts are disabled, you use hardware to generate a nonmaskable interrupt (NMI). This usually means having an external "STOP" button connected to a debugging card installed in computer running the debugger. Some machines may have the capability of connecting a front panel button to the NMI line on the machine bus. In any case, using NMI has the advantage of being able to break into a machine that has hung with interrupts disabled. (You can disable the breaking on nonmaskable interrupts by using the v2 command.)

You can have your application, DLL, or VxD break into the debugger by adding an int 1 or int 3 instruction or a call to the DebugBreak function to your code. The int 1 instruction produces an "Unexpected trace interrupt" message and stops on the instruction after the int 1. This message does not indicate an error condition and can be ignored. An int 3 will break directly on the int instruction and not produce the message. The int 3 is used in system components to stop execution on an error.

Page 18


Once an int instruction is hit, you can remove it by using the z (Zap) command. This command replaces the int instruction with a nop instruction. For programmers developing virtual device drivers (VxDs), the Debug_Out macro is available to send an ASCII string to the debug terminal and execute an int 1, which will break to the debugger. Once you have broken into the debugger, you can set additional breakpoints by using the bp or br command. For example, the following command sets a breakpoint at beginning of the function _MyEntryPoint: bp _MyEntryPoint

The system also breaks into the debugger if an application or DLL causes a general protection fault (GPF) by attempting to read or write memory with a bad selector, beyond a selector limit, or with a selector set to 0. The debugger receives control immediately if it traps interrupt vector 0Dh (the default setting). If you disable this trap (by using the vs command), Windows first displays a dialog box notifying the user of a problem. The user can click the Debug button to pass control to the debugger at the instruction that caused the fault.

Determining the State of the Processor Once control has been given to the debugger, the prompt character used will provide the protected mode status of the processor. The following list shows what prompt characters may be displayed and the meaning of each: > or >> The processor is in real mode (you should never see this when debugging Windows 9x)

# or ## The processor is in protected mode

- or -- The processor is in virtual 8086 (V86) mode

The mode the processor is in will be a good indication of what code is being executed. For example, if the prompt is a "#" (number sign), protected mode code is running. This can be a Windows-based application, DLL, or even the system itself. Stopping in ring 0 code may or may not be desirable. It is useful for VxD developers who need to examine and control execution of their VxDs, but it is not particularly useful for application or DLL developers.

If you are in V86 mode, then a DOS app, DOS device driver or DOS TSR has gone bad. Use the .DOSMGR commands to identify where you are. Do not use the LN command since it won’t provide correct V86 information.

If you are in protected mode, then the lower two bits of CS can be used to identify the ring of execution (zero indicates ring 0, 3 indicates ring 3).

CS Area CS Area0028 VxD code (ring 0) 013F Win32 flat code 0030 VxD data (ring 0) 0147 Win32 flat data 0048 debugger code 011F Krnl386 code

0137 Krnl386 data

The above selectors may be subject to changes in the future. Device driver developers generally debug VxD code, so the corresponding code selector value is usually 0028.

When in ring 0, the EIP should be of the form Cxxxxxxx. If it is not, some code jumped to an invalid address. Use ds esp to attempt to find out who did it.

A Win32 app’s EIP should be in the range of 0x00400000-0xBFFFFFFF.

Page 19


Regardless of the state of the processor, you can use the following command keys and the debugger prompt:

Key Action

CTRL+A Repeats the previous command.

CTRL+C Cancels the current command.

CTRL+S Freezes a System Debugger display.

CTRL+Q Restarts the display.

If the target system is executing code, CTRL+S and CTRL+Q are ignored.

Setting Breakpoints You can set breakpoints using the bp and br commands. With each breakpoint, you can specify breakpoint commands, a string of debugger commands that are executed when a breakpoint is hit. For example, the following command sets a breakpoint that stops execution in the function _MyEntryPoint and displays the registers and stack: bp _MyEntryPoint+346 "r;k"

Semicolons (;) separate commands from one another. All text is converted to uppercase except for text surrounded by single quotation marks ('). Two single quotation marks ('') or two double quotation marks ("") in a row act as an escape character and add one single quotation mark or one double quotation mark to the string. The maximum length of a breakpoint command is 80 characters. If the breakpoint has no breakpoint command string, WDEB386 executes the default (zd) command.

The conditional execution command (j) is very useful in breakpoint commands. This command executes the command list if the expression evaluates to TRUE (nonzero); otherwise, it continues to the next command in the command line (not including the ones in the command list parameter). If the command list contains more than one command, it must be enclosed in single or double quotation marks. Use a semicolon (;) to separate commands. No quotation marks are required if the command list contains zero or one command. The conditional execution command can be used in breakpoint commands to halt execution when an expression becomes true or in the default command.

Any operator, number, or symbol value can be used in the conditional expression. Always put a zero in front of a hexadecimal number that begins with a nonnumeric character. Doing so will prevent the debugger from treating the number as a symbol and searching all the loaded symbol files. For example, using 0f000 is faster than f000.

For example, the following command stops execution and display registers only if the variable _MyVar is equal to 3 when control enters the _MyEntryPoint function. Otherwise, it displays the current value and continues: bp _MyEntryPoint "j _MyVar == 3 r;'? "_MyVar=%x" _MyVar;g'"

Here are some additional breakpoint examples:

##bl0 d %c02e9ba0 [VKD_Set_Focus + 33]1 d %c012a57c [VKD_VM_Service_Phys]2 d W4 %c012c4f8 [VKD_8042_cmd_table + 1e8]3 e %c012ad8f [VKD_Chk_BIOS_Toggle_State + 21] "? 'BIOS %X',AL;G"4 e %c02ea32d [Hot_Key_Ended + ae] "? 'PriNot %x', DW 0C012BC2D;G"

Page 20


5 e %c012aaa4 [Update_Shift_State] "? '%X %X', DW 0C012BC2D, DW ESP;G"6 e %c012a8b1 [Queue_Output + 1] "J DI==8 R;G"7 e %c012a8b0 [Queue_Output] "J(AL==38 OR AL==0B8) '?''%X %X %X'',AL,DI,DW ESP;G';G"

Breakpoints zero and one are simple breakpoints; nothing much to say.

Breakpoint two is a write breakpoint, established via br w4 %0c012c4f8. This causes the debugger to halt whenever somebody (w)rites to the dword (4) at %c012c4f8. You can also set (r)ead and (e)xecute breakpoints. For read and write breakpoints, you also have to say the size of the object you want to break on, either 1, 2 or 4.

Breakpoint three is a simple command breakpoint. Whenever VKD_Chk_BIOS_Toggle_State+21 is hit, the command "? 'BIOS %X',AL;G" is executed. This command itself is in two parts. The first part is a ? command, which acts like printf. The print format is '%X' which means a hexadecimal value, and the argument is AL. So what the print command does is display the current value of the al register. The second command is G, which tells the debugger to resume execution after doing the requisite printing.

Breakpoint four is a minor extension of breakpoint three. Instead of printing AL, it prints DW 0C012BC2D. As noted above, the DW operator dereferences the dword at the specified location. So breakpoint four, when hit, displays the current dword value stored at address 0C012BC2D.

Breakpoint five is a minor extension of breakpoint four. A second value is printed, DW ESP. This displays the dword at the top of the stack, which is the address of the caller.

Breakpoint six is a simple conditional breakpoint. When the breakpoint is hit, the expression DI==8 is evaluated. If true, then R is executed (displaying registers); otherwise G is executed (resume execution). In other words, the breakpoint means Stop if DI==8.

Breakpoint seven combines all the tricks. The condition is (AL==38 OR AL==0B8). If the condition is met, then three values are printed, and execution continues. If the condition is not met, then execution continues without printing anything. Note first that quotation marks are used to enclose the commands to be executed if the condition is met. This needs to be done to protect the semicolon embedded within the command string from being interpreted as the end of the J command. Note second that the quotation marks that provide the print format are doubled, because they already live inside the quotation marks that are used to enclose the conditional command.

Debugger breakpoints can be “used” as markers by merely setting a (disabled) breakpoint at an address you will need to refer to frequently. For example:

## bp 12345678 ## bd0 &qquad;assuming that 12345678 was bp0 ## d br0+10 &qquad; dump at 12345688

If the code containing a breakpoint gets paged out to disk, you cannot remove that breakpoint until it is paged back in.

Page 21


Using symbols with WDEB386With WDEB386, all symbols are maintained into one single namespace. Symbols are explicitly manageed using w, wr, and wa. You can selectively enable and disable entire symbol files. When disabled, the debugger ignores all symbols that belong to a symbol file ("map").

The w command lists all the maps that are loaded, both enabled and disabled.The wr command disables a symbol file ("removes a map").The wa command enables a symbol file ("adds a map").For example, wr explorer will remove the explorer map from the debugger's symbol table. Keeping only the maps relevant to your project is important because the debugger's symbol table doesn't understand memory contexts.

As a shortcut, the asterisk means "all maps". So wr * disables all maps, and wa * re-enables them. Disabling all maps is useful if you want to discard all the symbolic information because the user is running with the wrong symbols.

Every symbol is mapped to a linear address, and that becomes its identity. In particular, the memory context and CPU mode are not factors in looking up a matching symbol. As a consequence, if you are running Win32 code, and you try to resolve an address that happens to match that of a Win16 driver or a DOS application, then you get symbols displayed that are irrelevant to the context of your code.

To search the active maps for symbols, you can us the ls (list symbols) or lse (list symbols by regular expression) commands. The argument is either a DOS-style (ls) or a UNIX-style (lse) pattern that will be looked up in all active maps. These are useful if you have the same symbol in multiple files and the debugger keeps picking the wrong one, and you choose not to go and disable all the maps that contain the bogus ones.

If you type a partial symbol name (at least five characters) and no perfect match is found, Wdeb386 will search for symbols that start with the characters you specify and present them in a list. You can then pick the one you really want and continue onwards.

If, in spite of everything, Wdeb386 can't find a symbol to match your address, it will search internal OS data structures, hoping to find something. If it has some Win16 address, it will walk the Win16 module list, checking to see if the selector is a code or data segment that belongs to any module in memory. If so, then it displays the address in the form MODULE!(n), where MODULE is the module name and n is the object number (1-based).

If the address lives in VxD space, then Wdeb386 will look at the list of in-memory VxDs and try to figure out which (if any) VxD contains the address. If found, the address is given in the form DDB(n)+zzzz, where DDB is the VxD DDB name, n is the object number, and zzzz is the offset within the object.

If the selector lives on the 16-bit global heap, but Wdeb386 can figure out which task allocated the memory, it will display the address in the form TASK!, where TASK! is the module name of the owner.If the address lives in the Win32 memory space, then Wdeb386 will look at the page table entries and figure out which module table entry the memory belongs to. It will then display the address in the form IMTEnnnn+zzzz, where nnnn is the module table entry index, and zzzz is the rva. If Wdeb386 can find the Win32 module table on its own, then it will do the conversion of the IMTE into a module name and display the result in the form MODULE.DLL+zzzz, where MODULE.DLL is the name of the module and zzzz is the rva.

Page 22


In summary:• MODULE!(n) Win16 module selector• TASK! Win16 global heap• IMTEnnnn+rva Win32 module• nnnnnnnn:DDB(n) VxD

If the symbol address is listed with an @-sign, it means that the module associated with the symbol is not in memory (or at least, is not in memory as far as Wdeb386 can determine). You can set a breakpoint on it. When the module finally gets loaded, Wdeb386 will instantiate the breakpoint.

Setting the Default Command The debugger runs the default command string when it reaches any breakpoint that you have set with the g (go), bp (Breakpoint), or br (Breakpoint Register) command. It also runs the default command when you run the p (program trace), t (trace), or zd command.

Initially, the default command string is set to the r (Register) command, but you can change it by using the zs (Set Default) command. If any errors occur (for example, if the command line is too long), the default command returns to the r command. The default command can be any sequence of debugger commands each separated by a semicolon (;). In the default command, j commands can be useful.

Here is the default command needed to continue execution each time the application or test program encounters an Interrupt 3:

zs "j (by cs:eip) == 0cc 'g'"

The following sample will trace until the doubleword at 137:00001234h is equal to 0EEDh (a primitive watchpoint). This operation must be started with a T, a P, or a ZD command so that the default command can be executed. If this operation is started by the G command, the default command will not execute unless execution is stopped on a go breakpoint or on a sticky breakpoint with no breakpoint command.

zs "j (dw 137:00001234) == 0eed 'r';t"zd

The following sample will perform a trace that displays each instruction until control is returned to code segment or selector 137h. Notice that PN displays only the disassembly line and not the register set, saving line space on the debugger's terminal screen.

zs "u cs:eip l1; j cs == 0137 'r';pn"zd

You can use the debugger default-command option to loop through a linked list (in this example, the next pointer is at offset 14), printing each packet on the list.

zs "?'%08.8x', eax; reax = dw (%(eax+14));zd"

It does destroy the contents of eax, but that can be restored. You can also replace the zd with a j eax != 0 'zd', and then it will stop at the end or some other condition to stop on. You need to set eax to the address of the first record and execute zd.

When finished, type zs "r" to restore the default-command to its normal value.

Page 23


If you stop in the debugger

If you don't know why you stoppedIf you do not see a reason why you stopped, the message may have been “lost in the noise”. Disassemble backwards from the current location and see if any of the addresses pushed onto the stack are strings.The following sample sessions indicate possible techniques to ferret out error message strings: ##u eip-0b L2 0028:........ push xxxxxxxx 0028:........ call dword ptr [__Debug_Out_Service (........)] ##da xxxxxxxx 0030:xxxxxxxx ... this is the error message...

##u eip-0a L2 0028:........ push xxxxxxxx 0028:........ call yyyyyyyy ##da xxxxxxxx 0030:xxxxxxxx ... this might be the error message...

##u eip-0d L3 0028:........ push xxxxxxxx 0028:........ call yyyyyyyy 0028:........ add esp, nn ##da xxxxxxxx 0030:xxxxxxxx ... this might be the error message...

Hard-coded traps into the debuggerDifferent components react to errors or assertion failure differently. Note that the following remarks are general principles; exceptions are not uncommon. Always cross-reference against the source code to be sure.

VMM32 uses int 3 for code coverage, int 1 for fatal errors, Debug_Out for assertion failures.

IOS uses int 3 for code coverage and Debug_Out for assertion failures. (Though it occasionally uses int 3 for assertion failures, too.)

If your code is at a fault

Disassemble near the faulting location to see if what you get is proper code or not. Don't forget that ASCII text may look deceptively valid. Another thing to check is whether ESP and EIP are very close to each other. If so, this suggests a stack-balancing problem (too many pushes or pops). Dump the stack back to find the last known sane location and start working forwards.

Type u cs:eip to see if what you get is proper code or not. If you see any of the following, then you do not have proper code:

• Any instruction of the form db xx.

Page 24


• Any instruction of the form lock xx.• Any instruction whose opcode begins with the letter f (floating point).• The same instruction repeated over and over, especially if it is one of the following:

add byte ptr [eax], aland byte ptr [edi], aladd byte ptr [bx+si], aland byte ptr [bx], al

• Anything else that obviously makes no sense.

If that quick test passes, then type db cs:eip-40 and check if you are in the middle of a data segment. One dead giveaway is that you see ASCII strings in the dump.

If Ln cs:eip gives you a nameThe command Ln cs:eip can supply you with the name of the module or routine. However, if you die very near the beginning of a routine, or if you see a message (in DEBUG) like 'Invalid mumble passed to ProcedureName', then the error is not in ProcedureName but rather in the caller. Dump the stack back to find the caller.

Page 25


Chapter 3. Reference

Command Quick ReferenceThe following is a quick reference list of System Debugger commands, ordered by Command Type:

Command Command Type Additional Arguments

Description

? print help menu? <expr> | [h|d|t|o|q|

b].<expr> display expression (h = hex, d or t = decimal, o or q = octal, b = binary)

? "printf string", <expr>, <expr>,

printf command

BC Breakpoint/Step [<bp list> | *] clear breakpoint(s)BD Breakpoint/Step [<bp list> | *] disable breakpoint(s)BE Breakpoint/Step [<bp list> | *] enable breakpoint(s)BL Breakpoint/Step list breakpoint(s)BP Breakpoint/Step [<bp>] [<addr>]

[<passcnt>] ["<bp cmds>"]

set a breakpoint

BR Breakpoint/Step [<bp>] E|W|R|1|2|4 [<addr>] [<passcnt>] ["<bp cmds>"]

set a Pentium processor debug register (hardware breakpoint).

C Register, Memory, Port <range> <addr> compare bytesD Register, Memory, Port [<range>] dump memoryDA Register, Memory, Port [<range>] dump asciiz stringDB Register, Memory, Port [<range>] dump memory in bytesDD Register, Memory, Port [<range>] dump memory in dwordsDG[A] 80386 Data Structure [<range>] dump GDT entriesDI[A] 80386 Data Structure [<range>] dump IDT entriesDL[A|P|S|H]

80386 Data Structure [<range>] dump LDT entries

DP[A|D] 80386 Data Structure [<range>] dump page directory/table entriesDT 80386 Data Structure [<addr>] dump TSSDW Register, Memory, Port [<range>] dump memory in wordsDX Miscellaneous dump contents of loadall bufferE Register, Memory, Port <addr> [<list>] enter memoryF Register, Memory, Port <range> <list> fill memoryG[S|H||T|Z]

Breakpoint/Step [=<addr> [<addr> ...]] go

H Miscellaneous <word> <word> hexaddI Register, Memory, Port <word> input a byte from portID Register, Memory, Port <word> input a dword from portIW Register, Memory, Port <word> input a word from portJ Breakpoint/Step <expr> [<cmds>] execute <cmds> if <expr> is true (non-

zero)K[V|S|B]

Disassemble / Stack Trace

[<SS:BPaddr>] [<CS:IPaddr>]

stack trace

Page 26


K[V|S|B]T

Disassemble / Stack Trace

[TDB] task stack trace

KA Disassemble / Stack Trace

<numargs> set number of stack dump arguments

LA Symbol, Symbol Map [<mapname>] list absolute symbols in active mapsLG Symbol, Symbol Map [<mapname>] list groups in active mapsLM Symbol, Symbol Map list linked and active mapsLN Symbol, Symbol Map [<addr>] list near symbolsLS Symbol, Symbol Map [<addr>] list symbols in groupLSE Symbol, Symbol Map <re> list symbols specified by regular

expressionM Register, Memory, Port <range> <addr> moveO Register, Memory, Port <word> <byte> output a byte to portOD Register, Memory, Port <word> <dword> output a dword to portOW Register, Memory, Port <word> <word> output a word to portP[N|T|Z]

Breakpoint/Step [=<addr>] [<word>] program step

R[T]|[<reg>]

Register, Memory, Port [[=] <word>] RegisterThe values used in the R cmd for changing the flags register are:FLAG SET CLEAROverFlow OV NVDirection DN(Decr.) UP(Incr)Interrupt EI(Enabled) DI(Disabled)Sign NG(Neg) PL(Plus)Zero ZR NZAux Carry AC NAParity PE (Even) PO(Odd)Carry CY NCNested Task NT (toggles)

S Register, Memory, Port <range> <list> searchT[A|C|N|S|X|Z]

Breakpoint/Step [=<addr>] [<word>] [<addr>]

trace

U Disassemble / Stack Trace

[<range>] unassemble

V Miscellaneous Display debugger version/dateV[1 | 3] Interrupt Vector specify rings to intercept a trap vectorV2 enable/disable NMI trapping in Ring 0VC[N|P|V|R|F]

Interrupt Vector <byte> ... stop intercepting trap vector

VL[N|P|V|R|F]

Interrupt Vector list trap vectors intercepted

VO [N|P|R|V]

Interrupt Vector lists interrupt vectors in the display format based on the newvec option.

VS[N|P|V|R|F]

Interrupt Vector <byte> ... intercept trap vector, ring 3 only

VT[N|P|V|R|F]

Interrupt Vector <byte> ... intercept trap vector, all rings

W Symbol, Symbol Map [<map name>] make named map activeWA Symbol, Symbol Map [<mapname> | *] add a map to the active listWR Symbol, Symbol Map [<mapname> | *] remove a map from the active listX Miscellaneous Dumps a listing of the current execution

environment (Bug report info).Y[?] Miscellaneous display/modify debugger optionsZ Breakpoint/Step zap the previous INT 1 or the current

Page 27


INT 3 with NOP'sZD Miscellaneous execute the default commandZL Miscellaneous list the default commandZS Miscellaneous set the default command

Dot commands

Dot commands are commands that are directed to the debugger entry point of a corresponding VxD. “System dot commands” are those commands that are always available. There are dot commands for several debug binary VxDs. The “Required debug binary .VxD” column indicates the debug binary that must be loaded to use the corresponding dot command(s). Many of the following debugger dot commands first require the installation of their corresponding debug binary VXD version. The following system dot commands are applicable to Windows 95 Version B (OSR2), but are generally the same for Golden Windows 95.

Command Additional Argument(s)

Required debug binary .VxD

Description

..<cmd> - Pass "cmd" directly to the VMM

.? (system) Prints help message

.<dev_name>

- Display device (VxD) specific info (if supported by the VxD)

.B <baud rate> [<port addr>]

(system) Set COM baud rate/port addr (1 = COM1, 2 = COM2)

..BIOS BIOS BIOS (space for help)? a Show all BIOS devnodese Dump recent BIOS eventsl Show List (Show every PCI devnode)s Show selected devnodey Select devnodez Select devnode by index

.CSP VMM Toggles catch stray pointer flag

.DF (system) Dumps the free list

.DG [handle | selector | arena(386)]

(system) Dumps the global heap

.DH [0 (from top) | -1 (from bottom)]

(system) Dumps the local heap

.DM (system) Dumps the Win16 module list

.DOSMGR - Dumps various data structures related to real-mode DOS. [1] Display SFTs[2] Display DPBs[3] Display MCBs (dump the real-mode memory map)[4] Display CDSs[5] Display PDBs (dump the real-mode process map)[6] Display DEVs[7] Display BDSs

Page 28


[8] Display INT 21h status

.DQ (system) Dumps the task queue

.DS (system) Dumps protected mode stack with labels. Dumps the VMM stack. Shows the stack pointer value, the DWORD contents and tries to display a code label that is near to each DWORD value. The label dump is sometimes useful for determining what chain of procedures have been executed to get to the current point, but it sometimes displays labels for DWORD values that really don't apply (i.e. 80000028 might display VMM_TEXT:DEBUG_ValidateLinear, when the value may really be from pushing the segment value 28, because pushing a segment value just decrements ESP and doesn't force a zero word for the high word.) So, this command can be useful, but requires some programmer interpretation to identify the correct stack trace.

.DU (system) Dumps the LRU list

.I? IOS Help menu for IOS commands

.IDCB <addr> IOS Dumps I/O Subsystem Device Control Block structure.

.IIOP <addr> IOS Dumps I/O Subsystem I/O Packet structure.

.IMED IOS Dumps I/O Subsystem Memory Element Descriptor structures.

.IDV DISKVSD & IOS

Display disk calldown/callup statistics

.ISAPNP ISAPNP Display current read data port, followed by information about each ISA bus card (if any).

.LQ VMM Displays the queue of messages queued with the macro Queue_Out.

.M (system) Dump assorted memory manager structures. Type '.M?' for a list of memory structures, and additional information.

.MEMCHECK - Display misc. memory layout

.NTKERN NTKERN OSR 2.1 & Windows 98 NT WDM (USB etc.) support. Typing this command supplies you with a menu, which includes the ability to dump its debug log (“D”). The debug log displays in LIFO order.

.P [?] DEBUGCMD Debugger tools when DEBUGCMD.VXD is installed (rename DEBUGCMD.TMP to DEBUGCMD.VXD, place it into \WINDOWS\SYSTEM, and load it by putting DEVICE=DEBUGCMD.VXD in the [386Enh] section of the SYSTEM.INI file):.p? Main help menu.p<cmd>? For more extensive help on a cmd.p lists threads in system.p <*/thread id> lists status of one thread.pf lists threads and their flags.ps <Thread handle/id> Dumps ring 0 stack with

labels.psx <Thread handle/id> Dumps 20 lines of ring0

stack and returns.pdev <Address> Finds nearest VXD name.plog <flags> Set scheduler query logging

flags

Page 29


.pmtx <Mutex Address> display mutex state

.psem <Semaphore Address> display semaphore state

.pthcb <Thread handle/id> display thread control block

.pprd Disables the logging of priority changes

.ppre Enables the logging of priority changes

.pprf <filter> Logs only boosts changing these bits

.pprl <Thread handle/id> Lists priority changes recorded

.pmax Show thread and VM maximum DOS386 stack usage

.PCI PCI PCI debug utility. Note that to use .PCI you must remove debugcmd.vxd from the system because its .P command prevents .PCI from being recognized.“Welcome to PCI's debugger”A show All; Show every PCI devnodesB show Busses; Show PCI bus structureC Config space; Toggle full/partial

config spaceD Enter dwdata; Enter data in config

space in dwordsE Enter data; Enter data in config spaceF FindIRQRoute; Help find the IRQ routingG Global info; Show global PCI infoI IDE Test; See if secondary IDE is

enabledL show List; Show every PCI devnodes

(short)Q Quit; Quit the debuggerR show Rom; Show ROM of selected devnodeS Show selected; Show selected devnodeT Trace CS; Trace config space accessY select devnode; Select DevNodeZ select devnode; Select DevNode by index

.R [#] - Displays the registers of the current thread. For example, if you used <ctrl c> to break into the system, this will show you the debugger’s <ctrl c> handler.

.REBOOT (system) reboots machine

.S [#] VMM Displays short logged exceptions starting at #, if specified.

.SL [#] VMM Displays long logged exceptions just #, if specified.

.T VMM Toggles the trace switch.

.VC [#] ------ (system) Displays the current VMs control block

.VDMAD VDMAD Virtual DMA Device State Dump

.VDD VDD Virtual Display Device State Dump. Also offers additional options:Select Option 1 - display VM register states 2 - display VM memory usage 3 - dump video page info 4 - display msg mode register state 5 - display planar mode register state 6 - read DAC 7 - display VM DAC states 8 - enable Queue_Outs 9 - enable MemC debug event

.VFLATD VFLATD Virtual Flat Video Buffer Device statistics and event

Page 30


log.VH [#] ------ (system) Displays a VMM linked list, given list handle.VKD VKD Virtual Keyboard Device

[0] - General info[1] - Hot Key info[2] - Per VM info[3] - Set VKD queue_outs[ESC] - Exit VKD debug query

.VL (system) Displays a list of all valid VM handles

.VM [#] ------ (system) Displays complete VM status

.VMM (system) Menu VMM state information:[A] System time[B] Display Critical Section info[C] Display blocked thread information[D] Reset dyna-link profile counts[E] I/O port trap information[F] Reset I/O profile counts[G] Turn procedure call trace logging on [H] V86 interrupt hook information[I] PM interrupt hook information[J] Reset PM and V86 interrupt profile counts[K] Display event lists[L] Display device list (all VxDs)[M] Display V86 break points[N] Display PM break points[O] Display interrupt profile[P] Reset interrupt profile counts[Q] Display GP fault profile[R] Reset GP fault profile counts[S] Toggle verbose device call trace[T] Dyna-link service profile information[U] Fault Hook information[V] Display time out queues[W] PM CLI/STI trace info[X] DPMI info

.VPICD - Virtual PIC Device status (status of hardware interrupts)[1] Global PIC information (ring 0)[2] Per-VM PIC information (virtualized VM state)[3] IRQ handler information (hardware interrupts and who is responsible for each)

.VR [#] ------ (system) Displays the registers of the current VM (both the current and alternate registers). Used to examine both V86 mode and protected mode portions of the VM.

.VS [#] ------ (system) Displays the current VM's virtual mode stack

.VXDLDR - Displays the list of dynamically loaded devices

.Y <expr> CONFIGMG Displays CONFIGMG (Plug & Play) structures:Welcome to CONFIGMG's debuggerA Arbitrators Show the list of arbitratorsB Block queue Prevent processing of eventsC Query remove Query removal at happy timed remove Removal at happy timee toggle Echo Set the echo to a specified levelf show Free Show free resourcesg enumerate Enumerate a devnodeh Reenable Appy Reenable checking of query removei Show Log Show procedural logsj test walks Test our walk proceduresk Show stack Show stack of procedure logsl show List Show devnode list

Page 31


m screen size Set screen sizen Nuke logs Nuke the procedure loggedp Problem List devnodes with problemsq Quit Quit the debuggerr show Range Show a Ranges Show tree Show the hardware treet toggle time Toggle the display of timeu Unblock queue Restart processing of eventsv View status View the global status of CONFIGMGw show all range Show all the rangelistsx eXclude Filter logging of procedure logsy force smthng Call some random HWProfile APIz Allow DLL call Allow the DLLs to be called

Where…

<range> = [<addr>] [<word>] | <addr> [L <word>]<addr> = [& | #][<word>:]<word> | %<dword> | %%<dword><list> = <byte> <byte> ... | "string"<binary ops> = : | * / MOD + . - << >> < > >= <= AND XOR OR && ||<unary ops> = &seg #sel %lin %%phy ! NOT SEG OFF BY WO DW POI PORT WPORT (OFF=offset, BY=byte, WO=word/16-bit near proc, DW=dword/32-bit proc, POI=16-bit FAR addr, PORT=I/O byte port, WPORT=I/O word port)

Regular expressions <re>:. any character, [] character class, [a-z], [^a], etc* match zero or more, # match zero or one, + match one or more Supported printf format characters are:

%% % %c character %[-][+][ ][0][width][.precision][p][n]d decimal %[-][0][width][.precision][p][n]u unsigned decimal %[-][#][0][width][.precision][p][n]x hex %[-][#][0][width][.precision][p][n]X hex %[-][0][width][.precision][p][n]o octal %[-][0][width][.precision][p][n]b binary %[-][width][.precision][a]s string %[-][width][.precision][a][p][n][L][H][N][Z]A address %[-][width][.precision][a][p][n][L][H][N][Z]S symbol %[-][width][.precision][a][p][n][L][H][N][Z]G group:symbol %[-][width][.precision][a][p][n][L][H][N][Z]M map:group:symbol %[-][width][.precision][a][p][n][L][H][N][Z]g group %[-][width][.precision][a][p][n][L][H][N][Z]m map a - pointer to a AddrS structure H - 16 bit offset L - 32 bit offset N - offset only Z - no address p - gets the previous symbol, address or offset n - gets the next symbol, address or offset

Prompts are: > real mode

Page 32


- or -- virtual 8086 mode # or ## protected mode

COMMON SELECTOR VALUES:

CS Area CS Area0028 VxD code (ring 0) 013F Win32 flat code 0030 VxD data (ring 0) 0147 Win32 flat data 0048 debugger code 011F Krnl386 code

0137 Krnl386 data

Page 33


Command Syntax Commands consist of command names and parameters. Names and parameters are not case-sensitive. If a syntax error occurs in a debugger command, the debugger redisplays the command line and indicates the error with a caret (^) and the word Error, as in the following example: A100 ^ Error

Parameters You can separate command parameters with delimiters (spaces or commas), but a delimiter is required only between two consecutive hexadecimal values. The following commands are equivalent: dCS:100 110d CS:100 110d,CS:100,110

Following are the parameters you can use with commands: addr Represents an address parameter in one of four forms. For more information about the operators

shown in the following address forms, see Binary and Unary Operators.

#1f:02C0 Protected-mode address (selector:offset)

%31020 Linear address

%%31020 Physical address

&0100:02FF Real-mode address (segment:offset)

Any of these specified address forms overrides the current address type.

byte Specifies a two-digit hexadecimal value.

cmds Specifies an optional set of debugger commands to be executed with the bp (Breakpoint) or j (Conditional) command.

count Specifies a count. Valid values depend on the command with which this parameter is being used.

dword Represents an eight-digit (4-byte) hexadecimal value. The DWORD data type is most commonly used as a physical address.

expr Represents a combination of parameters and operators that evaluates to an 8-bit, 16-bit, or 32-bit value. An expr parameter can be used as a value in any command. An expr parameter can combine any symbol, number, or address with any of the binary and unary operators.

flags Specifies one or more conditions. Valid conditions depend on the command with which this parameter is being used.

group-name

Specifies the name of a group that contains the map symbols you want to display.

list Specifies a series of byte values or a string. The list parameter must be the last parameter on the command line. Following is an example of the f (Fill) command with a list parameter:

fCS:100 42 45 52 54 41

map-name Specifies the name of a symbol map file.

name-chars

Specifies one or more characters.

number Specifies a numeric value. Valid values depend on the command with which this parameter is

Page 34


being used.

object Specifies a handle, a selector, or a heap address.

option Specifies an option. Valid options depend on the command with which this parameter is being used.

range Specifies the block of memory on which the command should operate. The range parameter can be two addresses (addr addr); or it can be one address and a length (addr L word, where word is the number of items on which the command should operate; 80h is the default value). Following are three valid examples:

CS:100 110

CS:100 L 10

CS:100

The limit for range is 10000h. To specify a word of 10000h using only four digits, use 0000h or 0h.

reg Specifies the name of a microprocessor register.

string Represents any number of characters enclosed in single quotation marks (') or double quotation marks ("). For quotation marks that must appear within string, you must use two sets of quotation marks. For example, the following strings are valid:

'This ''string'' is OK.'

\"This \"\"string\"\" is OK.\"

However, the following strings are not valid:

\"This \"string\" is not OK.\"

\"This 'string' is not OK.\"

The ASCII values of the characters in the string are used as a list of byte values.

word Specifies a four-digit (2-byte) hexadecimal value.

Binary and Unary Operators Following, in descending order of precedence, are the binary operators that can be used in commands: Operator Meaning

( ) Parentheses

: Address binder

* Multiplication

/ Integer division

MOD Modulus (remainder)

+ Addition

– Subtraction

> Greater-than relational operator

< Less-than relational operator

>= Greater-than/equal-to relational operator

<= Less-than/equal-to relational operator

Page 35


== Equal-to relational operator

!= Not-equal-to relational operator

AND Bitwise Boolean AND

XOR Bitwise Boolean exclusive OR

OR Bitwise Boolean OR

&& Logical AND

|| Logical OR

Following, in descending order of precedence, are the unary operators that can be used in commands: Operator Meaning

&(seg) Address of segment value

#(sel) Address of selector value

%%(phy) Address as a physical value

%(lin) Address as a linear value

– Two's complement

! Logical NOT operator

NOT One's complement

SEG Segment address of operand

OFF Address offset of operand

BY Low-order byte from given address

WO Low-order word from given address

DW Doubleword from given address

POI Pointer (4 bytes) from given address — this operator works only with 16:16 addresses

PORT 1 byte from given port

WPORT Word from given port

Regular Expressions The set of regular expressions that the debugger supports for matching symbols is similar to the set supported by UNIX grep. The debugger set includes a few enhancements. Following are the wildcards: Wildcard Description

. Matches any single character.

[ ] Defines a character class; matches a set or range of characters.

^ Negates a character class.

Following are the postfix operators: Operator Description

* Causes the previous wildcard or single character to match zero or more characters.

# Matches zero or one.

+ Plus sign, matches one or more.

Anywhere a symbol is accepted, a regular expression can be used. If there is more than one match, a list of matching symbols is displayed and you must select the proper symbol. The symbol match is not case-sensitive.

Page 36


The asterisk (*), number sign (#), and plus sign (+) are already math expression operators. To be recognized as a regular expression operator, each of these characters must be immediately preceded by an escape character — the backslash (\). The period (.), opening bracket ([), and closing bracket (]) do not require escape characters. Anything inside the brackets of a character class does not have to be escaped. Following are valid character classes: [a-z][;*+#]

Characters are escaped at two levels: in the expression evaluator and in the regular expression parser. A character special to the expression evaluator (*, #, +, or \) must be escaped to make it to the regular expression parser. If a character special to the regular expression parser must be escaped (for example, to match symbols with * or # in them), it must be escaped twice. If a backslash is needed in an expression, it must be double escaped. Following are sample regular expressions:

Regular expression Description

sym.\* Matches any symbols beginning with the string sym.

sym\* Matches sym alone and sym followed by any characters.

.\*sym.\* Matches any symbols containing the string sym.

sym[0–9] Matches sym0, sym1, sym2, and so on.

sym\\\* Matches sym*.

sym\\\\ Matches sym\.

sym\\\\.\* Matches any symbols beginning with the string sym\.

Page 37


Command DetailsThe following is a list of WDEB386’s commands.

? (Help) The ? command with no arguments displays a list of commands and syntax recognized by the debugger.

? (Evaluate Expression) ? [option.]expr? "string", expr, ...

The ? command evaluates an expression and displays the result. expr

Expression to evaluate. Can be a combination of numbers, addresses, and operators. Numbers are assumed to be hexadecimal. Addresses can be 32-bit physical addresses or protected-mode addresses (selector:offset). The number sign (#) operator overrides the current address type. Operators can be any listed in Binary and Unary Operators.

option Format in which to display the expression. Can be one of these:

h. Hexadecimal

d. Decimal

t. Decimal

o. Octal

q. Octal

y. Binary

By default, the command displays all formats: decimal, hexadecimal, octal, binary, ASCII, and Boolean.

string Formatting string. Can be a combination of text and zero or more of the following formatting descriptors and escape sequences:

%% Displays a percent sign (%).

%A Displays matching expr as an address.

%b Displays matching expr in binary format.

%c Displays matching expr as a character.

%d Displays matching expr in decimal format.

%G Evaluates matching expr as an address and displays the group and symbol associated with the address in group:symbol format.

%M Evaluates matching expr as an address and displays the map file, group and symbol associated

Page 38


with the address in map:group:symbol format.

%o Displays matching expr in octal format.

%S Evaluates matching expr as an address and displays the map file, group and symbol associated with the address.

%s Evaluates matching expr as an address and displays the string at that address.

%u Displays matching expr in unsigned decimal format.

%X Displays matching expr in hexadecimal format.

%x Displays matching expr in hexadecimal format

\a Inserts a bell (alert) character.

\b Inserts a backspace character.

\n Inserts a new line character.

\r Inserts a carriage return character.

\t Inserts a horizontal tab character.

One expression must be given for each formatting descriptor in the string. Multiple expressions can be separated with commas (,) or spaces.

Formatting descriptors can have these optional prefixes:

A [-][width][.precision][a][p][n][L][H][N]

b [-][0][width][.precision][p][n]

d [-][+][ ][0][width][.precision][p][n]

G [-][width][.precision][a][p][n][L][H][N]

M [-][width][.precision][a][p][n][L][H][N]

o [-][0][width][.precision][p][n]

s [-][width][.precision][a]

S [-][width][.precision][a][p][n][L][H][N]

u [-][0][width][.precision][p][n]

X [-][#][0][width][.precision][p][n]

x [-][#][0][width][.precision][p][n]

Specifying an asterisk (*) for the width or precision parameter causes the field width or precision, respectively, to be picked up from the next parameter. Decimal values can also be specified for the width and precision parameters. The prefix letters have these meanings:

a Address argument size

H Display 16-bit offset

L Display 32-bit offset

N Display offset only

p Get the previous symbol, symbol address, or offset

n Get the next symbol, symbol address, or offset

The following examples show simple commands and corresponding output: ? ds:esi013f:000001B3 %00098953 %%00098953

// display the value of the arithmetic expression 3*4: ? 3*4

Page 39


0Ch 12T 14Q 00001100Y '.' TRUE

bc (Breakpoint Clear) bc list | *

The bc command removes one or more defined breakpoints. list

Specifies any combination of integer values in the range 0 through 9. If you specify list, the debugger removes the specified breakpoints.

* Clears all breakpoints.

This example removes breakpoints 0, 4, and 8: bc 0 4 8

bd (Breakpoint Disable) bd list | *

The bd command temporarily disables one or more breakpoints. To restore breakpoints disabled by the bd command, use the be (Breakpoint Enable) command. list

Specifies any combination of integer values in the range 0 through 9. If you specify list, the debugger disables the specified breakpoints.

* Disables all breakpoints.

This example disables breakpoints 0, 4, and 8: bd 0 4 8

be (Breakpoint Enable) be list | *

The be command restores (enables) one or more breakpoints that have been temporarily disabled by a bd (Breakpoint Disable) command. list

Specifies any combination of integer values in the range 0 through 9. If you specify list, the debugger enables the specified breakpoints.

Page 40


* Enables all breakpoints.

This example enables breakpoints 0, 4, and 8: be 0 4 8

bl (Breakpoint List) bl

The bl command lists current information about all breakpoints created by the bp (Breakpoint) command. For each existing breakpoint, the command displays the breakpoint number, the enabled status ('e' for enabled, 'd' for disabled, 'I' for invalid), the breakpoint address, the number of passes remaining (if any), the initial number of passes in parentheses (if any), and debugger commands to be executed when the breakpoint is reached (if any). An invalid “I” breakpoint typically indicates the code has been paged out to disk; it may come back later. You can’t remove an invalid breakpoint until it pages back in.

The following example shows a typical list: 0 d %004010b5 [_MyTest] 4 (10) "db ds:edi"1 eI %0040110f [_MyWndProc@16 + 5a]

bp (Breakpoint) bp[number]addr [count] ["cmds"]

The bp command creates a software breakpoint at an address. When the application is running, software breakpoints stop execution and force the debugger to execute the default or optional command string. Unlike breakpoints created by the g (Go) command, software breakpoints remain in memory until you remove them with the bc (Breakpoint Clear) command or temporarily disable them with the bd (Breakpoint Disable) command.

number Specifies which breakpoint is being created. No space is allowed between the bp and number. If number is omitted, the first available breakpoint number is used. The debugger allows up to 10 software breakpoints (0 through 9). If you specify more than 10 breakpoints, the debugger returns the message: "Too Many Breakpoints."

addr Specifies any valid instruction address — the first byte of an operation code (opcode). The addr parameter is required for all new breakpoints.

count Specifies the number of times the breakpoint is to be ignored before being executed. It can be any 16-bit value.

Page 41


cmds Specifies an optional list of debugger commands to be executed in place of the default command when the breakpoint is reached. You must enclose optional commands in quotation marks and separate optional commands with semicolons (;).

This example creates a breakpoint at address CS:401000: bp 401000

This example creates breakpoint 8 at address given by the symbol _MyTest. When the breakpoint occurs, the debugger displays bytes at DS:SI: bp8 _MyTest "db DS:SI"

You cannot set a breakpoint on memory that is not in context (however, you can set a hardware execution breakpoint on the linear address; see the br command).

br (Breakpoint Register) br [number] flags [addr] [count] ["cmds"]

The Pentium processor contains four “hardware debug registers” that support hardware address breakpoints. Hardware debug registers allow the user to instruct the processor hardware to interrupt processor execution when specified addresses are read, written or executed. This is a very useful tool, for example, to find out what procedures are accessing or changing a specified memory variable.

The br command sets a Pentium debug register breakpoint, in order to “break” on data reads, writes and instruction execution. Up to four debug registers can be set and enabled at one time.

Hardware breakpoints take precedence over faults.

Since the four debug registers are global to the system, they should typically only be touched by a kernel mode debugger. See Knowledge Base Article Q137199, “ PRB: Debuggers Cannot Reliably Use Debug Register Breakpoints” for more information.

See also the following MSDN Library CD article: Q105275, “Using the ‘BR’ Command in WDEB386.EXE”.

number Specifies which breakpoint is being created. No space is allowed between the br command and the number parameter. If number is omitted, the first available breakpoint number is used.

flags Specifies the length and break conditions for the breakpoint. This parameter can be some combination of the following values:

1 Set 1-byte length (default value).

2 Set word length on word boundary.

4 Set doubleword length on doubleword boundary.

E Break on instruction execution only (1-byte length only).

W Break on writes only.

Page 42


R Break on reads and writes.

addrSpecifies the address to be watched.

count Specifies the number of times the breakpoint is to be ignored before being executed. It can be any 16-bit value.

cmds Specifies an optional list of debugger commands to be executed in place of the default command when the breakpoint is reached. You must enclose the group of optional commands in quotation marks and separate optional commands with semicolons (;).

c (Compare) c range addr

The c command compares one memory location with another memory location. If the two memory areas are identical, the debugger displays nothing and returns the debugger prompt. Differences, when they exist, are displayed in this form: addr1 byte1 byte2 addr2. range

Specifies the block of memory that is to be compared with a block of memory starting at addr.

addr Specifies the starting address of the second block of memory.

This example compares the bytes at addresses in the range 100h to 1FFh with the corresponding bytes at address from 300h to 3FFh: c100 1FF 300

This example compares the same block of memory as the previous example but specifies the range by using the L (length) option. c100 L 100 300

d (Display) d [range]

The d command displays the contents of memory at a given address or in a range of addresses. The d command displays one or more lines, depending on the range given. Each line displays the address of the first item displayed. The command always displays at least one value. The memory display is in the format defined by a previously executed da, db, dd, or dw command. Each subsequent d (typed without parameters) displays the bytes immediately following those last displayed. range

Specifies the block of memory to display. If you omit range, the d command displays the next

Page 43


byte of memory after the last one displayed. The d command must be separated by at least one space from any range value.

da (Display ASCII) da [range]

The da command displays as ASCII characters the values of the bytes at a given address or in a given range. The display includes all bytes up to the first zero byte. Nonprinting characters and characters having values greater than 127 are denoted by a period (.).

db (Display Bytes) db [range]

The db command displays the values of the bytes at a given address or in a given range. The display is in two portions: a hexadecimal display (each byte is shown in hexadecimal format) and an ASCII display (the bytes are shown as ASCII characters). A nonprinting character is denoted by a period (.) in the ASCII portion of the display. Each display line shows 16 bytes, with a hyphen between the eighth and ninth bytes. Each displayed line begins on a 16-byte boundary. range

Specifies the block of memory to display. If you omit range, 128 bytes are displayed beginning at the first address after the address displayed by the previous db command.

The following example displays 0Ah bytes of memory, beginning at the specified address: db CS:100 0A

This example displays lines in a format similar to the following: 04BA:00000100 54 4F 4D 20 53 . . . 45 52 TOM SAWYER

Each line of the display begins with an address, incremented by 10h from the address on the previous line.

dd (Display Doublewords) dd [range]

The dd command displays the hexadecimal values of the doublewords at the address specified or in the specified range of addresses. The dd command displays one or more lines, depending on the range given. Each line displays the address of the first doubleword in the line, followed by up to four hexadecimal doubleword values. The hexadecimal values are separated by spaces. The dd command displays values up to the end of the range or until the first 32 doublewords have been displayed. range

Specifies the block of memory to display. If you omit range, 32 doubleword values are displayed

Page 44


beginning at the first address after the address displayed by the previous dd command.

The following example displays the doubleword values from CS:100 to CS:110: dd CS:100 11004BA:0100 7473:2041 676E:6972 5405:0104 0A0D:786504BA:0110 0000:002E

No more than four values per line are displayed.

dg (Display GDT) dg[a] [range]

The dg command displays the specified range of entries in the global descriptor table (GDT). a

Displays all entries in the table, not just the valid ones. By default, only the valid GDT entries are displayed. If range specifies a local descriptor table (LDT) selector, the command displays the appropriate LDT entry.

range Specifies the range of entries to be displayed. If you omit range, the entire table is displayed.

The command displays the selector, descriptor type, base address, limit, privilege, and other descriptor flags.

di (Display IDT) di[a] [range]

The di command displays the specified range of entries in the interrupt descriptor table (IDT). a

Displays all entries in the table, not just the valid ones.


The command displays the interrupt number, the interrupt type, the interrupt address, privilege, and descriptor flags.

dl (Display LDT) dl[a | p | s | h] [range]

The dl command displays the specified range of entries in the local descriptor table (LDT). a

Displays all entries in the table, not just the valid ones. By default, only the valid LDT entries are displayed. If range specifies a global descriptor table (GDT) selector, it displays the appropriate

Page 45


GDT entry.

p Displays private segment selectors.

s Displays shared segment selectors.

h Displays huge segment selectors. To display the huge segment selectors, give the shadow selector followed by the maximum number of selectors reserved for that segment plus 1.


The command displays the selector, descriptor type, base address, limit, privilege, and other descriptor flags.

dp (Display Page Directory and Tables) dp[a|d] [range]

The dp command displays the page directory and page tables. Page tables are always skipped if the corresponding page directory entry is not present. Page directory entries appear with an asterisk next to the page frame. a

Displays all present page directory and page table entries; by default, page directory and page table entries that are zero are skipped.

d Displays only page directory entries. If a count is given as part of the optional range, it will be interpreted as a page directory entry count.

range Specifies the range of linear addresses for page tables.

The command displays the entry address, frame, and entry flags. Page directory entries are marked with an asterisk (*). Entry flags have the following meanings: A Accessed

c clean

CD Cache Disable

D Dirty

n Not-present

P Present

r Read-only

s Supervisor

U User

u Unaccessed

W writeable

WT Write Through

Page 46


dt (Display Task State Segment) dt [addr]

The dt command displays the current task state segment (TSS) or the selected TSS if you specify the optional address. More information about the TSS can be found in Intel’s “Pentium Processor User’s Manual, Volume 3” (1993). This command can be useful to view the register state at the time a double-fault occurs (dt 18:0).

addr Specifies the address of the TSS to display. If no addr is given, dt displays the current TSS pointed to by the TR register.

dw (Display Words) dw [range]

The dw command displays the hexadecimal values of the words at a given address or in a given range of addresses. The command displays one or more lines, depending on the range given. Each line displays the address of the first word in the line, followed by up to eight hexadecimal word values. The hexadecimal values are separated by spaces. The command displays values until the end of the range or until the first 64 words have been displayed. range

Specifies the range of addresses to display. If you omit range, 64 words are displayed beginning at the first address after the address displayed by the previous dw command.

The following example displays the word values from CS:100 to CS:110: dw CS:100 11004BA:0100 2041 7473 6972 676E 0104 5404 7865 0A0D04BA:0110 002E

dx (Display Loadall Buffer) dx

Displays the contents of the loadall buffer.

e (Enter) e addr [list]

Page 47


The e command enters byte values into memory at a specified address. You can specify the new values on the command line or let the debugger prompt you for values. addr

Specifies the address of the first byte to be entered.

list Specifies the byte values used for replacement. These values are inserted automatically. If an error occurs when you are using the list form of the command, no byte values are changed.

If the debugger prompts you, it displays the address and its contents and then waits for you to perform one of the following actions:

• Replace a byte value with a value you type. Type the value after the current value. If the byte you type is an invalid hexadecimal value or contains more than two digits, the system does not echo the illegal or extra character.

• Press the SPACEBAR to advance to the next byte. To change the value, type the new value after the current value. If, when you press the SPACEBAR, you move beyond an 8-byte boundary, the debugger starts a new display line with the address displayed at the beginning.

• Type a hyphen (-) to return to the preceding byte. If you decide to change a byte before the current position, typing the hyphen returns the current position to the previous byte. When you type the hyphen, a new line is started with its address and byte value displayed.

• Press ENTER to terminate the e command. You can press ENTER at any byte position.

The following example prompts you to change the value EB at CS:100: eCS:10004BA:0100 EB.

To step through the subsequent bytes without changing values, press the SPACEBAR. In the following example, the SPACEBAR is pressed three times: 04BA:0100 EB.41 10. 00. BC.

To return to a value at a previous address, type a hyphen, as shown in the following example: 04BA:0100 EB.41 10. 00. BC.-04BA:0102 00.-04BA:0101 10.

This example returns to the address CS:101.

f (Fill) f range list

The f command fills the addresses in a specified range with the values in the specified list. range

Specifies the block of memory to be filled. If range contains more bytes than the number of values in list, the debugger uses list repeatedly until all bytes in range are filled. If any of the memory in range is not valid (bad or nonexistent), an error occurs in all succeeding locations.

list Specifies the list of values to fill the given range. If list contains more values than the number of

Page 48


bytes in range, the debugger ignores the extra values in list.

The following example fills memory locations 04BA:100 through 04BA:1FF with the bytes specified, repeating the five values until it has filled all 100h bytes: f04BA:100 L 100 42 45 52 54 41

g (Go) g[s|h|t|z] [=addr [addr[...]] ]

The g command executes the application currently in memory. If you type the g command by itself, the current application runs as if it had been run outside the debugger. If you specify =addr, execution begins at the specified address. s

Shows the time, in microseconds, from when the system is started with gs until the next entry to the debugger. No attempt is made to calculate and remove debugger overhead from the measurement. Requires a timing card. See MSDN Library CD: Q85897, “WDEB386-Compatible Timing Card Available”.

h Displays the approximate debugger overhead in the s option. Requires a timing card.

t or z Allows trapped exceptions to resume at the original trap handler address without having to unhook the exception. Use these options instead of the vcp d; t; vsp d commands. Use gt when the debugger catches a fault, in order to continue (resume) execution.

=addr Specifies the address at which execution is to begin. The equal sign (=) is needed to distinguish the starting address from the breakpoint address.

addr Specifies one or more breakpoint addresses where execution is to halt. You can specify up to 10 breakpoints, but only at addresses containing the first byte of an operation code (opcode). If you attempt to set more than 10 breakpoints, an error message is displayed.

Specifying an optional breakpoint address causes execution to halt at the first address encountered, regardless of the position of the address in the list of addresses that halts execution or application branching. When execution of the application reaches a breakpoint, the default command string is executed.

The stack (SS:SP) must be valid and have 6 bytes available for this command. The g command uses an iret instruction to cause a jump to the application being tested. The stack is set, and the user flags, CS register, and IP register are pushed on the user stack. (If the user stack is not valid or is too small, the operating system may crash.) An interrupt code (0CCh) is placed at the specified breakpoint addresses.

When the debugger encounters an instruction with the breakpoint code, it restores all breakpoint addresses listed with the g command to their original instructions. If you do not halt execution at one of the breakpoints, the interrupt codes are not replaced with the original instructions.

The following example executes the application currently in memory until address 7550 in the CS

Page 49


selector is executed. The debugger then executes the default command string, removes the int 3 trap from this address, and restores the original instruction. When you resume execution, the original instruction is executed.

gCS:7550

The command g dw esp can be used to go back to the flat 32-bit calling procedure.The command g wo ss:sp can be used to go back to the 16-bit near calling procedure.The command g poi ss:sp can be used to go back to the 16-bit far calling procedure.

h (Hex) h word word

The h command performs hexadecimal arithmetic on the two specified parameters. The debugger adds, subtracts, and multiplies the two parameters; divides the second parameter by the first; and then displays the results on one line. The debugger does 32-bit multiplication and displays the result as doublewords. The debugger displays the result of division as a 16-bit quotient and a 16-bit remainder. word

Specifies a 16-bit word parameter.

i (Input) i word

The i command accepts and displays 1 byte (8 bits) from a specified port. word

Specifies the 16-bit port address.

The following example displays the byte at port address 2F8h: i2F8

id (Input) id word

The id command accepts and displays 1 doubleword (32 bits) from a specified port. word


The following example displays the doubleword at port address 2F8h: i2F8

Page 50


iw (Input) iw word

The iw command accepts and displays 1 word (16 bits) from a specified port. word


The following example displays the word at port address 2F8h: i2F8

j (Conditional) j expr [cmds-if-true][;cmds-if-false]

The j command executes selected commands based on whether the specified expression is TRUE or FALSE. The j command is useful in breakpoint commands to conditionally break execution when an expression becomes TRUE. expr

Evaluates to a Boolean TRUE or FALSE.

cmds-if-true Specifies a list of debugger commands to be executed when expr is TRUE. More than one command can be given, but the commands must be separated by semicolons and the complete list must be enclosed in single or double quotation marks.

cmds-if-false Specifies a list of debugger commands to be executed when expr is FALSE. The preceding semicolon is required. More than one command can be given, but the commands must be separated by semicolons and the complete list must be enclosed in single or double quotation marks.

The following example causes execution to continue if EAX equals zero when the breakpoint is reached: bp 167:1454 "J EAX == 0 G"

The following example displays the registers and continues execution when the byte pointed to by DS:SI +3 is equal to 40h; otherwise, it displays the descriptor table: bp 167:1462 "J BY (DS:SI+3) == 40 'R;G';DG DS"

k (Stack Trace) k[b|s|v] [addr] [addr]

This command displays the current (EBP-based) stack frame. Each line shows the name of a

Page 51


procedure, its arguments, and the address of the statement that called it. The command displays four 2-byte arguments by default. The ka command changes the number of arguments displayed by this command. b

Indicates the stack frame is 32 bits wide.

s Indicates the stack frame is 16 bits wide.

v Displays the verbose version of stack information — that is, information about stack location and frame pointer values for each frame.

addr Specifies an optional stack-frame address (SS:EBP) or an optional code address (CS:EIP).

Using the k command at the beginning of a function (before the function prolog has been executed) gives incorrect results. The command uses the BP register to compute the current backtrace, and this register is not correctly set for a function until its prolog has been executed.

ka (Stack Trace Arguments) ka count

The ka command sets the number of arguments displayed for all subsequent stack trace commands. The initial default value is 4. count

Specifies the number of arguments to be displayed. The count parameter must be in the range 0 through 1Fh.

kt (Stack Trace for Task) k[b|s|v]t [addr]

This command displays the stack frame of the current task or the task specified by the addr parameter. Each line shows the name of a procedure, its arguments, and the address of the statement that called it. The command displays four 2-byte arguments by default. The ka command changes the number of arguments displayed by this command. b

Indicates the stack frame is 32 bits wide.

s Indicates the stack frame is 16 bits wide.

v Displays the verbose version of stack information — that is, information about stack location and frame pointer values for each frame.

addr Specifies the segment address of the process descriptor block (PDB) for the task to be traced. To

Page 52


obtain the addr value, use the .dq (Dump Task Queue) command. If addr is not supplied, the kt command displays the stack frame of the current task.

la (List Absolute Symbols) la

The la command lists the absolute symbols in the active map.

lg (List Groups) lg

The lg command lists the address and the name of each group in the active map.

lm (List Maps) lm

The lm command lists the symbol files currently loaded and indicates which one is active. The last symbol file loaded is made active by default. Use the w (Change Map) command to change the active file.

ln (List Nearest Symbol) ln [addr]

The ln command lists the symbol nearest the specified address. The command lists the nearest symbol before and after the specified addr parameter. This command also shows line-number information if it is available in the symbol file.

addr

Specifies any valid instruction address. The default value is the current disassembly address.

The ln command without the addr parameter displays the nearest symbols before and after the current disassembly address.

Example: ln dw(esp) Lists the nearest symbol with respect to the caller (pushed address on stack)

Page 53


ls (List Symbols) ls group-name | name-chars | *

The ls command lists the symbols in the specified group or lists names that match the search specification in all groups. The search specification uses DOS-style semantics. The only valid wildcard is a single asterisk (*) as the last character on the command line; all other characters are ignored.

group-name Names the group that contains the symbols you want to list, for example ESDI_506.

name-chars Specifies the beginning characters of the symbols you want to list.

lse (List Symbols by Regular Expression) lse regular-expression

The lse command lists the symbols specified by the given regular expression. The search specification uses UNIX-style semantics.

regular-expression Can be a regular expression as described in Command Syntax.

m (Move) m range addr

The m command moves a block of memory from one memory location to another. If part of the destination block overlaps some of the source block, the move is always performed without loss of data. Addresses that could be overwritten are moved first. range

Specifies the block of memory to be moved.

addr Specifies the starting address at which the memory is to be relocated.

For moves from higher to lower addresses, the sequence of events is first to move the data at the block's lowest address and then to work toward the highest. For moves from lower to higher addresses, the sequence is first to move the data at the block's highest address and then to work toward the lowest. The following example first moves the data at address CS:110 to CS:510 and then moves the data at CS:10F to CS:50F, and so on, until the data at CS:100 is moved to CS:500: mCS:100 110 CS:500

Page 54


o (Output) o word byte

The o command writes a byte to a 16-bit port address. word

Specifies the 16-bit port address to be written to.

byte Specifies the 8-bit value to be written to the port.

The following example writes the byte value 4Fh to output port 2F8h: o 2F8 4F

od (Output) o word dword

The o command writes a dword to a 16-bit port address. word


dword Specifies the 32-bit value to be written to the port.

The following example writes the byte value 8000004Fh to output port 2F8h: o 2F8 8000004F

ow(Output) o word word

The o command writes a word to a 16-bit port address. word


word Specifies the 16-bit value to be written to the port.

The following example writes the word value 804Fh to output port 2F8h: o 2F8 804F

Page 55


p (Program Trace) p[n|t|z] [=addr][count]

The p command executes the instruction at a specified address and displays the current values of all the registers and flags (whatever the zd command has been set to). It then executes the default command string, if any. The p command is identical to the t (Trace Instructions) command, except that it automatically executes and returns from any calls or software interrupts it encounters. The t command always stops after executing into the call or interrupt, leaving execution control inside the called routine. n

Suppresses the register display so just the assembly line is displayed. The suppression results only if the default command, zd, is set to a normal setting, r.

t or z Allows trapped exceptions to resume at the original trap handler address without having to unhook the exception.

addr Specifies the starting address at which to begin execution. If you omit the optional addr parameter, execution begins at the instruction pointed to by the CS and IP registers. Use the equal sign (=) only if you specify addr.

count Specifies the number of instructions to execute before stopping and executing the default command string. The command executes the default command string for each instruction before executing the next.

The following example executes the instruction pointed to by the current CS and IP register values before it executes the default command string: p

The following example executes the instruction at address CS:120 before it executes the default command string: p=120

Program tracing through popf or popfd usually does not work.

r (Register) r[t][reg[=value]]

The r command displays the contents of one or more central processing unit (CPU) registers and allows the contents to be changed to new values. If you specify the reg parameter with the r command, the command displays the value of that register in hexadecimal format and prompts for a new value. If you specify a reg and a value, the command sets the register to the given value. t

Displays registers in terse format.

Page 56


reg Specifies the register to be displayed. If you specify f or msw for reg, the debugger displays the flags in a row at the beginning of a new line and prompts for one or more flag values. If you omit reg, the debugger displays the contents of all registers and flags along with the next executable instruction.

value Specifies the new value for the register. Can be a number or a combination of these flag values:

OV Overflow set

NV Overflow clear

DN Direction decrement

UP Direction increment

EI Interrupt enabled

DI Interrupt disabled

NG Sign negative

PL Sign positive

ZR Zero set

NZ Zero clear

AC Auxiliary carry set

NA Auxiliary carry clear

PE Parity even

PO Parity odd

CY Carry set

NC Carry clear

NT Nested task switch (on and off)

TS Sets the task switch bit. (MSW only)

EM Sets the emulation processor extension bit. (MSW only)

MP Sets the monitor processor extension bit. (MSW only)

PM Sets the protected-mode bit. (MSW only)

Flag values can be in any order. You do not have to leave spaces between these values.

If you type more than one value for a flag or enter an invalid flag name, the flags up to the error in the list are changed and those flags at and after the error are not changed. In addition, the debugger display the message: "Bad Flag."

Setting the protected-mode bit from within the debugger does not set the target system to run in protected mode. The debugger simulates the setting. To configure the target system to run in protected mode, you would have to set the PM bit in the MSW register and reset the target system to restart in protected mode.

See also the .r command.

Page 57


s (Search) s range list | "string"

The s command searches an address range for a specified list of bytes or an ASCII character string. You can include one or more bytes in list, but multiple bytes must be separated by a space or comma. When you search for more than one byte, the command returns the address of only the first byte in the string. When list contains only one byte, the debugger displays the addresses of all occurrences of the byte in range. range

Specifies the block of memory to be searched.

list Specifies one or more byte values to search for.

string Specifies an ASCII character string to be searched for. The string must be enclosed in quotation marks.

The following example searches for byte 41h in the address range CS:100 to CS:110: sCS:100 110 4104BA:010404BA:010D

t (Trace) t[a|c|n|s|x|z][=start_addr][count][addr]

The t command executes one or more instructions along with the default command string and then displays the decoded instruction. If you include the start_addr parameter, tracing starts at the specified address. Otherwise, the command steps through the next machine instruction and then executes the default command string. The t command uses the hardware trace mode of the Intel microprocessor. Consequently, you can also trace instructions stored in read-only memory (ROM).

a Indicates that an ending address is specified for the trace. Instructions are traced until the address in addr is reached.

c Suppresses all output and counts instructions traced. An ending address is required for this command. Instructions are traced until the address in addr is reached.

n Suppresses the register display so just the assembly line is displayed. This works only if the default command, zd, is set to r (the normal setting).

s Suppresses output; the instruction and count are displayed for each call and the return from that call.

Page 58


x Forces the debugger to trace regions of code known to be untraceable (_PGSwitchContext, for example).

z Allows original trap handler address to be traced into without having to unhook the exception. Use this option instead of vcp d; t; vsp d.

start_addr Specifies the instruction address at which to start tracing. The equal sign (=) is required.

count Specifies the number of instructions to execute and trace.

addr Specifies the instruction address at which to stop tracing.

The following command causes the debugger to execute 16 (10h) instructions beginning at 011A in the current selector: t=011A 10

The debugger executes and displays the results of the default command string for each instruction. The display is scrolled until the last instruction is executed. Press the CTRL+S key combination to stop the scrolling and CTRL+Q to resume.

This command does not trace into INTs (but will trace out), and tracing through popf or popfd usually does not work.

u (Disassemble) u [range]

The u command disassembles bytes and displays the source statements, with addresses and byte values that correspond to them. The display of disassembled code looks similar to a code listing for an assembled file. If you type the u command by itself, 20h bytes are disassembled at the first address after the one displayed by the previous u command. range

Specifies the block of memory in which instructions are to be disassembled. If no range is given, the command disassembles the next 20h bytes.

v (Version Number) v

The v command displays the current debugger version number and date.

Page 59


vc (Vector Clear) vc[n | p | r | v] number[,number [,...]]

The vc command clears the specified interrupt vector and reinstalls the previous interrupt vector. n

Removes the beep from traps that beep when encountered; does not clear the traps.

p Clears protected-mode vectors only.

r Clears real-mode vectors only.

v Clears virtual 8086 (V86) mode vectors only.

number Specifies the interrupt vector to clear.

For protected-mode games, type vcp 1 3 before running the app, and vtp 1 3 after exiting the app, to avoid “unexpected trace interrupt” errors. For DOS apps, use vcv 1 3 and vsv 1 3. To recover from the error message, first remove the vector, then type gt.

vl (Vector List) vl[n | p | r | v]

Lists the interrupt vectors that the debugger intercepts. Vectors that have been set with the vt command (as opposed to vs) are listed with an asterisk (*) following the vector number. n

Lists the traps that beep when encountered.

p Lists the protected-mode vectors only.

r Lists the real-mode vectors only.

v Lists the virtual 8086 (V86) mode vectors only.

vo (Vector List New) vo[n | p | r | v]

The vo command lists interrupt vectors in the display format based on the newvec option. For details,

Page 60


see the y command. n

Lists the traps that beep when encountered.

p Lists the protected-mode vectors only.

r Lists the real-mode vectors only.

v Lists the virtual 8086 (V86) mode vectors only.

vs (Vector Trap Non-Supervisor) vs[n | p | r | v] number[,number[,...]]

The vs command adds a new interrupt vector to the list of intercepted vectors. Vectors set by this command do not intercept interrupts that occur at ring 0. n

Beep when trap encountered.

p Set trap for protected-mode vectors only.

r Set trap for real-mode vectors only.

v Set trap for virtual 8086 (V86) mode vectors only.

number Specifies the interrupt vector to intercept.

vt (Vector Trap) vt[n | p | r | v] number[,number[,...]]

The vt command adds a new interrupt vector to the list of intercepted vectors. n

Beep when trap encountered.

p Set trap for protected-mode vectors only.

r Set trap for real-mode vectors only.

v Set trap for virtual 8086 (V86) mode vectors only.

number Specifies the interrupt vector to intercept.

Page 61


w (Change Map) w [map-name]

The w command changes the active map file. map-name

Specifies the name of the map file you want to make active. Use the lm (List Map) command to display a list of available map files.

If map-name is not specified, the loaded maps are displayed and the user is prompted to select a map by pressing its corresponding number.

wa (Activate Map) wa map-name

The wa command adds the specified map to the list of active maps. map-name

Specifies the map to add to the list of active maps.

wr (Deactivate Map) wr map-name

The wr command removes the specified map from the list of active maps. map-name

Specifies the map to remove from the list of active maps.

x (Dump Debug Report) x

Dumps a listing of the current execution environment.

Page 62


y (Debugger Options) y[? | option]

The y command changes the debugger configuration. The following list describes the available configuration options. All settings are toggles. ?

Displays a list of supported options.

option Following are the available configuration options:

/a Controls automatic symbol loading. If this option is set, Windows will not load symbols automatically.

/n Sets the following options, listed in more detail further below:

codebytes dislwr int3line newprompt newreg newvec symaddrs

/v Controls segment load notification messages. If this option is set, all segment load notifications will be displayed.

386env Controls the size of addresses, registers, and so on when displayed. When this option is on, addresses, registers, and so on are shown in 32-bit format; otherwise, they are shown in 16-bit format.

codebytes Causes code bytes to be displayed along with disassembled instructions.

crdelay = Implements a delay between lines emitted to the debug terminal. Specify the number of ASCII nulls between lines (0-FFFFH).

disaddr Causes addresses to be displayed with disassembled instructions.

disline Causes filenames and line numbers to be displayed with disassembled instructions.

dislwr Causes register and instruction names to be displayed in lowercase letters.

int3line Causes the filename and line number to be displayed with int 3 instructions.

newprompt Causes a double prompt when paging is enabled and a nesting level if the debugger is reentered.

newreg Changes the format of the register display to the newer format accommodating 32 bit registers.

newvec Controls the display format for the intercepted interrupt vectors.

regterse Controls the number of registers displayed by the r (Register) command. When regterse is on, only the first three lines are displayed (instead of the normal six lines plus disassembly line).

scrncols Sets the number of screen columns in the debug display. The default is 79 columns.

scrnlines Sets the number of screen lines in the debug display. The default is 24 lines.

skipint3s Causes the debugger to ignore inline int 3 instructions.

symaddrs Causes symbol values to be displayed with the symbols.

teftibase Sets the base port address for the timing card. . See MSDN Library CD: Q85897, “WDEB386-Compatible Timing Card Available”

Page 63


z (Zap) z

Replaces the instruction bytes of the current int 3 instruction or the previous int 1 instruction with nop instructions. This allows the user to avoid int 1 or int 3 instructions that were assembled into the executable file by breaking into the debugger more than once.

You can also z)ap debug_out‘s; they will be automatically converted to trace_out, so they stop trapping..

zd (Execute Default) zd

The zd command executes the default command string. The default command string is initially set to the r (Register) command by the debugger. The default command string is executed every time a breakpoint is encountered during execution of the application or whenever a p (Program Trace) or t (Trace) command is executed.

Use the zl command to display the default command string and the zs command to change the default command string.

zl (Display Default) zl

The zl command displays the default command string.

zs (Set Default) zs "string"

The zs command makes it possible for you to change the default command string. string

Specifies the new default command string. The string must be enclosed in single or double quotation marks. You must separate the debugger commands within the string with semicolons.

The following example changes the current default command string to an r (Display Register) command followed by a c (Compare Memory) command: zs "r;c100 L 100 300"

Page 64


The following example begins execution whenever an int 3 instruction is executed in your test application. This example executes a g (Go) command every time an int 3 instruction is executed. zs "j (by cs:ip) == cc 'g'"

You can use zs as follows to set up a watchpoint: zs "j (wo 40:1234) == 0eeed;t"

This command traces until the word at 40:1234 is not equal to 0EEED. This does not work if you are tracing through the mode switching code in MS-DOS or other sections of code that cannot be traced.

Page 65


Dot Commands

.<dev_name> (Dot Device)

.dev_name

Directs the VMM to send a Debug_Query message to the given virtual device. If the virtual device supports a debugging interface, it displays information about its operating state. dev_name

Can be the name of any virtual device.

Because virtual devices are not required to support the Debug_Query message, many do not produce debugging output. If a virtual device does generate output, it is typically device specific and not normally useful in a typical debugging situation. Examine the sample virtual devices to determine how to use the Trace_Out macro, and the In_Debug_Chr service to generate useful debugging information.

.? (Help)

.?

The .? command displays a list of external commands. These commands are part of debugger, but they are specific to the environment in which the debugger is running.

.b (Baud Rate)

.b number [addr]

The .b command sets the baud rate for the debugging port (COM2). number

Specifies the baud rate. It can be one of the following values: 150, 300, 600, 1200, 2400, 4800, 9600, or 19200. Because the default radix for the debugger is 16, you must type t after the number to indicate a decimal value.

addr Specifies 1 for COM1 or 2 for COM2; anything else is taken as a base port address. If there is no COM2, the debugger checks for COM1 and then for any other COM port address in the read-only memory (ROM) data area to use as the console.

The following example sets the baud rate to 1200: #.b 1200t

Page 66


..bios (BIOS Debug Binary Utility)The ..bios command displays the following menu:

BIOS (space for help)? a Show all BIOS devnodese Dump recent BIOS eventsl Show List (Show every PCI devnode)s Show selected devnodey Select devnodez Select devnode by index

.csp (VMM Debug Binary Utility)

The .csp command toggles the “catch stray pointer flag”.

.df (Display Free Memory)

.df

The .df command displays a list of the free global Win16 memory objects in the global heap. The list has the following form: address: size owner [chain] address

Specifies physical and heap addresses.

size Specifies the size of the object, in bytes.

owner Always specifies that the module is free.

chain Specifies the previous and next addresses in the list of least recently used (LRU) objects. The debugger displays the addresses only if the segment is movable and discardable.

.dg (Display Global Memory)

.dg [object]

The .dg command displays a list of the global memory objects in the global heap. The command displays information in much the same way as the HEAPWALK application.

Page 67


object Specifies the first object to be listed. The object parameter can be a handle, a selector, or a heap address.

The list has the following form: address: size segment-type owner [handle flags chain] address Specifies physical and heap addresses.


segment-type Specifies the type of object. The type can be any one of the following:

CODE Segment contains application code.

DATA Segment contains application data and possible stack and local heap data.

FREE Segment belongs to pool of free memory objects ready for allocation by an application.

PRIV Segment contains private data.

SENTINAL Segment marks the beginning or end of the global heap.

owner Specifies the module name of the application or library that allocated the memory object. The acronym PDB is used for memory objects that represent process descriptor blocks. These blocks contain execution information about applications.

handle Specifies the handle of the global memory object. If the debugger displays no handle, the segment is fixed.

flags Specifies either of the following:

D The segment is movable and discardable.

L The segment is locked. If the segment is locked, the lock count appears to the right of the flag.

If the debugger displays a handle but no flag, the segment is movable but not discardable.

chain Specifies the previous and next addresses in the list of least recently used (LRU) objects. Addresses are displayed only if the segment is movable and discardable (specified by the D flag).

.dh (Display Local Heap)

.dh

The .dh command displays a list of the local memory objects in the local heap (if any) belonging to the current data segment. The command uses the current value of the DS register to locate the data segment and check for a local heap. The list of memory objects has the following form: offset: size { BUSY | FREE } offset

Specifies the address offset from the beginning of the data segment to the local memory object.

Page 68



If BUSY is displayed, the object has been allocated and is currently in use. If FREE is displayed, the object is in the pool of free objects ready to be allocated by the application. A special memory object, SENTINAL, may also be displayed.

.dm (Display Modules)

.dm

The .dm command displays a list of the global Win16 modules in the global heap. The list has the following form: module-handle module-type module-name filename module-handle

Specifies the handle of the module.

module-type Specifies either a dynamic-link library (DLL) or the name of the application you are debugging.

module-name Specifies the name of the module.

filename Specifies the name of the file from which you loaded the application.

.dosmgr (Display Real Mode DOS structures)Dumps various data structures related to real-mode DOS. [1] Display SFTs[2] Display DPBs[3] Display MCBs (dump the real-mode memory map)[4] Display CDSs[5] Display PDBs (dump the real-mode process map)[6] Display DEVs[7] Display BDSs[8] Display INT 21h status

.dq (Display Task Queues)

.dq

The .dq command displays a list containing information about the various task queues supported by the system. The list has the following form: task-descriptor-block stack-segment:stack-pointer number-of-events priority internal-messaging-information module task-descriptor-block

Specifies the selector or segment address.

Page 69


The task descriptor block is identical to the process descriptor block (PDB).

stack-segment:stack-pointer Specifies the stack segment and pointer.

number-of-events Specifies the number of events waiting for the segment.

priority Specifies the priority of the segment.

internal-messaging-information Specifies information about internal messages.

module Specifies the module name.

.ds (Dump Stack)

.ds

Dumps the protected-mode stack and displays near code-segment labels (if available) next to each doubleword value from the stack. One important distinction that should be made is the difference between the k and the .ds commands. The k command will walk the Windows stack as long as the debugger is stopped in Windows-based application or dynamic-link library (DLL) code. However, if the debugger is tracing through ring 0 code, the k command will not produce any useful output. For this reason, the .ds command has been provided to display the ring 0 stack.

.du (Display Least Recently Used)

.du

The .du command displays a list of the least recently used (LRU) global memory objects in the global heap. The list has the following form: address: size segment-type owner [handle flags chain] address

Specifies physical and heap addresses.


segment-type Specifies the type of object. The type can be any one of the following:

CODE Segment contains application code.

DATA Segment contains application data and possible stack and local heap data.

FREE Segment belongs to pool of free memory objects ready for allocation by an application.

PRIV Segment contains private data.

SENTINAL Segment marks the beginning or end of the global heap.

Page 70


owner Specifies the module name of the application or library that allocated the memory object. The acronym PDB is used for memory objects that represent process descriptor blocks. These blocks contain execution information about applications.

handle Specifies the handle of the global memory object.

flags Specifies D, which means the segment is movable and discardable.

chain Specifies the previous and next addresses in the LRU list.

.i? (IOS Debug Binary Utility)Help menu for IOS commands:

.IDCB <addr> Dumps I/O Subsystem Device Control Block structure.

.IIOP <addr> Dumps I/O Subsystem I/O Packet structure.

.IMED Dumps I/O Subsystem Memory Element Descriptor structures.

.IDV (DISKVSD debug binary also required) Display disk calldown/callup statistics

.ISAPNP Display current read data port, followed by information about each ISA bus card (if any).

.lq (VMM Debug Binary Utility)Displays the queue of messages queued with the macro Queue_Out. Normally the queued messages are viewed with the ".S" command so it is possible to see the messages interspersed with the fault information to get a better idea of the execution sequence, but occasionally it is nice to be able to look at the messages quickly to determine if the desired one ever occurred. This list also displays the fault entry index of when each were logged, so it is possible to search for a desired message and then use the ".S" command and specify the identified index as a list starting point.

.m (Memory)

.m[struct][link] [expression [L count]]

Displays information about memory and memory objects. struct

Command option. Can be one of these letters.

a Display arena record.

c Display context descriptor

d Display page directory entry

e Toggle stopping in the debugger for memory manager errors (parameter validation errors as

Page 71


well as fatal errors).

f With no arguments, dump page fault log. With arguments, set to log faults in a specific range (syntax: .MF <address> L<lengh in bytes>).

fb Toggle stopping for each logged page fault.

ff Toggle logging page faults to debug terminal.

g Display pager descriptor

h [handle] Displays heap information for the given handle or global information if no handle is given. Displays heap information. This was originally intended for debugging the VMM's memory manager, but may be useful for looking at heap allocations that a device driver makes. This command accepts an optional parameter that specifies the heap allocation handle whose information should be dumped.

hs [handle] Dump statistics about a given heap.

hw Toggle paranoid VMM32 heap checking.

hx [handle] Check for corruption on given heap defaults to VMM32 fixed heap.

i Display Instance Data information. The first section lists which pages of V86 memory contain instance data. The second section lists the regions of instance data. A typical entry looks like:

VMAddr 00000413, Lead Byt 01, Algn Byt 29

This means that the instance region starts at 413h in V86 memory, that 1 byte exists before a DWORD boundary and 29h bytes exist after a DWORD boundary, for a total region length of 2Ah bytes. This command is useful for determining if a device has claimed instance data properly, or to just see what data is currently instanced.

l Display (physical) page table info for a given linear address

m [address [l page-count]]

Attempts to force memory present. The address defaults to last page faulted upon (contents of cr2 register).

n Force all unlocked memory not present

p Display ALL Linear addresses that map the given PhysAddr. This command requires a physical address, so page A0h would be address A0000.

r Display arena header

s Dumps global memory manager statistics such as how system memory is being used, what sort of pager is being used etc.

t Displays page table entry

u Toggles computing checksums for page-outs and page-ins

v Displays memory handle information for the memory handles that are allocated to the current VM. Originally used in debugging the VMM's memory manager. Also dumps out the list of routines that have used the global _Assign_Device_v86_Pages service.

w Dumps allocators of all committed pages.

x Displays all memory structures for an address.

y Displays valid physical memory ranges.

If no letter is given, the command displays all the structures associated with a given linear address.

Page 72


link Direction to walk structures if dumping more than one. Can be b to walk backward or f to walk forward. If link is not given, the default is to walk adjacent entries.

expression An expression identifying the structure to display. Can be a linear address, handle, array index, or other value as specified by the struct parameter.

count Number of structures to display if the specified structures are linked.

The default address for the .m and .mx commands is the contents of the cr2 register (the last page fault) and for the other commands it is the first structure in the list. For example, .m displays information about the page that most recently faulted. A word of caution about the .mm, .mhx, and .mhs commands. If you invoke these commands at the wrong time, you can crash your system. The only time it can be guaranteed safe is if you are currently executing ring 3 code. At other times we may be in the middle of another file system or memory manager operation.

.memcheckDisplay list of internal memory checking routines

.ntkern (NTKERN Debug Binary Utility)OSR 2.1 & Windows 98 NT WDM (USB etc.) support. Typing this command supplies you with a menu which includes the ability to dump its debug log (“D”). The debug log displays in LIFO order.

.p (DEBUGCMD Debug Binary Utility)Debugger tools when DEBUGCMD.VXD is installed (rename DEBUGCMD.TMP to DEBUGCMD.VXD, place it into \WINDOWS\SYSTEM, and load it by putting DEVICE=DEBUGCMD.VXD in the [386Enh] section of the SYSTEM.INI file):

.p? Main help menu

.p<cmd>? For more extensive help on a cmd

.p lists threads in system

.p <*/thread id> lists status of one thread

.pf lists threads and their flags

.ps <Thread handle/id> Dumps ring 0 stack with labels

.psx <Thread handle/id> Dumps 20 lines of ring0 stack and returns

.pdev <Address> Finds nearest VXD name

.plog <flags> Set scheduler query logging flags

.pmtx <Mutex Address> display mutex state

.psem <Semaphore Address> display semaphore state

.pthcb <Thread handle/id> display thread control block

.pprd Disables the logging of priority changes

.ppre Enables the logging of priority changes

.pprf <filter> Logs only boosts changing these bits

.pprl <Thread handle/id> Lists priority changes recorded

Page 73


.pmax Show thread and VM maximum DOS386 stack usage

.pci (PCI Debug Binary Utility)

Note that to use .PCI you must remove debugcmd.vxd from the system because its .P command prevents .PCI from being recognized.

“Welcome to PCI's debugger”

A show All; Show every PCI devnodeB show Busses; Show PCI bus structureC Config space; Toggle full/partial config spaceD Enter dwdata; Enter data in config space in dwordsE Enter data; Enter data in config spaceF FindIRQRoute; Help find the IRQ routingG Global info; Show global PCI infoI IDE Test; See if secondary IDE is enabledL show List; Show every PCI devnodes (short)Q Quit; Quit the debuggerR show Rom; Show ROM of selected devnodeS Show selected; Show selected devnodeT Trace CS; Trace config space accessY select devnode; Select DevNodeZ select devnode; Select DevNode by index

.r (Display Registers of Current Ring 3 Thread)

.r [#]

Displays the registers of the current ring 3 thread. For example, if you used <ctrl c> to break into the system, .r will show you the debugger’s <ctrl c> handler (corresponding to the current thread). To show the state of another thread, supply the thread’s ring0 thread ID as the parameter.

.reboot (System Restart)

.reboot

The .reboot command causes the target system to restart.

.s (VMM Debug Binary Utility)

.s [#] displays short logged exceptions starting at #, if specified.

Page 74


Displays a condensed version of logged exceptions (logging is enabled with the ".T" command described above). The ".S" command displays the log in brief format, most recent log entry first.

The first column is the log entry number.

The second column describes the reason for the log entry. If the log entry describes the beginning of a fault, it contains the fault number. If the log entry describes leaving ring 0 (for example, because faulthandling is complete), it contains the word "OUT".

The third column is the handle of the thread at the time of the fault.

The fourth column is the number of times the critical section was taken at the time the log entry was made.

The fifth column is "EI" if interrupts were enabled at the time the log entry was made; "DI" if interrupts were disabled.

The sixth column describes the processor mode at the time of the fault. It is "VMM" to indicate that the fault was encountered by a ring 0 component. It is "V86" to indicate that the fault was encounteredwhile in V86-mode. It is "PM" to indicate that the fault was encountered in ring 3 protected mode.

The seventh column is the address that caused the fault.

The remainder of the line contains auxiliary information related to the fault. If the fault was raised by a software interrupt or I/O port access, the faulting instruction is disassembled; in the case of a software interrupt, the value of the EAX register is also displayed following the disassembly. If the fault was caused by a callback or breakpoint, the address of the ring 0 handler for the callback or breakpoint is displayed.

Here follow some sample log entries with interpretation.

0000165A: OUT C1D9F08C 00 EI VMM C0011FDC

This is log entry number 0000165A. The system is leaving ring 0 ("OUT"). The current thread is C1D9F08C, the critical section is not taken ("00"), interrupts are enabled ("EI"), and the system is returning to interrupt code which happens also to be at ring 0 ("VMM"), at address C0011FDC.

00023131: 002A C359F08C 01 EI V86 FF03:5311 INT 2A 00008102

This is log entry number 000023131. The system is entering ring 0 due to software interrupt 002A. The current thread is C359F08C, the critical section is taken once ("01"), interrupts are enabled ("EI"), and the software interrupt was raised by V86-mode ("V86") at address FF03:5311. The faulting instruction was an "INT 2A", and the value of the EAX register was 00008102.

0002312B: 0006 C1D9F08C 00 DI V86 FEB7:1448 Hdl: C0087244:IFSMGR(01) + 86d

This is log entry number 00002312B. The system is entering ring 0 due to an invalid opcode (fault 0006). The current thread is C1D9F08C, the critical section is not taken ("00"), interrupts are disabled ("DI"),

Page 75


and the software interrupt was raised by V86-mode ("V86") at address FEB7:1448. The faulting instruction was a callback or breakpoint; the handler for the callback of breakpoint is IFSMGR(01) + 86d.

00023118: 0055 C1D9F08C 00 EI VMM C0011FDC

This is log entry number 000023118. The system is entering ring 0 due to an IRQ 5 (50+5). The current thread is C1D9F08C, the critical section is not taken ("00"), interrupts are disabled ("EI"), and the hardware interrupt was raised while the system was in ring 0 ("VMM") at address C0011FDC.

The ".SL" command described below displays a complete dump to each logged entry, but takes much more screen space, so this command is used more often to get a quick look at the sequence of faults, and the ".SL" command is used when a more in-depth view is necessary, or when it is necessary to know what other registers were at the time of the fault.

".S" accepts an optional parameter that is the fault entry index. If this parameter exists, then the log is searched for the specified entry. If the entry is found, then the list starts from that entry and proceeded backwards to the oldest entry; if the entry is not found then a warning message is displayed and the list starts from the most resent.

The macro Queue_Out queues messages to a separate circular queue. Each message is linked to the current fault entry index, so the ".S" can show the queued messages interspersed with the fault information. This allows fault handlers to show information about how they handled the fault so that the list displayed by the ".S" command is a fairly complete execution history, which is particularly useful when debugging devices that are trying to virtualize I/O so that they simulate actual hardware, such as the PIC, DMA and video.

".S" always disables logging before it displays anything, so no more logging will be performed until ".T" is invoked again.

.sl (VMM Debug Binary Utility)

.sl [#] displays long logged exceptions just #, if specified. ".SL" like ".S" (above) displays information about logged exceptions, enabled with the ".T" command. ".SL" displays all of the registers at the time the entry was logged and also shows the system time (the time VMM started) of the entry. ".S" shows a condensed view and is used more often because more faults can be viewed at the same time and because most of the registers are of little importance to the fault.

".SL" also disables logging before it displays anything, so no more logging will be performed until ".T" is invoked again

.t (VMM Debug Binary Utility)Toggles the trace switch. At start time the debugging VMM does not performing any fault logging,

Page 76


but when this command is invoked, then the message "start tracing" is displayed, at which point debugging code in the VMM starts logging each fault/exception that occurs. The logging includes the current registers, whether executing V86 client, PM client or VMM/VxD code, system time, fault #, etc. Both the fault entry into the VMM and the exit from the VMM are logged. The logged information can be viewed with the ".S" commands.

Invoking ".T" a second time displays the message "stop tracing", at which point the logging will stop, but any previously logged information can still be viewed. So, ".T" toggles the logging state between logging and not logging. Each time that logging is started, the current log is lost, so it is only possible to view the most recently logged session. The logging is done into a circular queue, so it will start overwriting at some point, but the queue is defined large enough to give a good view into the types of faults that are occurring.

This command is very useful for determining problems that are related to fault processing and sequencing, such as virtually handling I/O instructions being executed by the client. It is also useful for when the Windows/386 wants to blow-up; it may be possible to determine what happened just prior to the crash to find out what was at fault. It is often helpful to turn on procedure call tracing also. Refer to the ".VMM" command for details on call tracing. The debugging macro Queue_Out, logs messages into a separate circular queue. Each message is associated to a fault log item.

. v (Virtual Machine Commands)

.v[option]

Displays information about the current virtual machine (VM). option

Command option. Can be one of these option letters:

c Displays the standard fields from the current VM's control block (does not include device allocated fields.) This information is useful to determine the current state of the VM as the Windows/386 VMM sees it. It accepts the same optional parameter as ".VM".

h Displays the current VM's handle. Useful for determining which VM is currently executing. It is also possible to look at device allocated fields of the VM's control block, if the offset to the first field is known, by adding the offset to the handle when dumping memory.

m Displays the status of the current VM. Status information includes re-entry count, VM handle, critical section state, client registers, and top entries from the client's stack. This command is useful to see where the VM was/is trying to execute. It is then possible to set a break point at the client's CS:IP if it is necessary to step through a few instructions to determine what the client is trying to do. This command accepts an optional parameter that can be the VM handle or VM id of the VM whose status should be displayed.

r If Ring 0 code was executing at the time that the debugger took control, then is command displays the client registers of the current VM. If the client was executing, then the debugger is showing the current registers, and this command will just display a warning message. This command shows just the register display portion of the ".VM" command. It accepts the same optional parameter as ".VM".

s Displays the current VM's virtual mode stack if the debugger is running in protected mode.

l Displays a list of all valid VM handles. The list shows the assigned scheduler priority and the execution status of each VM.

Page 77


vdmad (VDMAD Debug Binary Utility)Virtual DMA Device State Dump.

.vdd (VDD Debug Binary Utility)VDD Virtual Display Device State Dump. Also offers additional options:Select Option 1 - display VM register states 2 - display VM memory usage 3 - dump video page info 4 - display msg mode register state 5 - display planar mode register state 6 - read DAC 7 - display VM DAC states 8 - enable Queue_Outs 9 - enable MemC debug event

.vflatd (VFLATD Debug Binary Utility)Virtual Flat Video Buffer Device statistics and event log.

.vkd (VKD Debug Binary Utility)

Virtual Keyboard Device[0] - General info[1] - Hot Key info[2] - Per VM info[3] - Set VKD queue_outs[ESC] - Exit VKD debug query

Page 78


.vmm (Display VMM Commands)

.vmm

Displays a menu of subcommands. Pressing a single key causes the corresponding command to be carried out.

Service Comments[A] System time Displays the current system time.[B] Display Critical Section info[C] Display blocked thread information[D] Reset dyna-link profile counts[E] I/O port trap information

Displays information about I/O emulation handling. The first section displays general information about the hash table used to dispatch trapped I/O instructions. The second section lists each I/O port trapped, number of times trapped, percentage of total number if I/O traps, current trapping state, hash function result, table index, offset from ideal table index, and handler routine name. This information is useful for determining which ports are trapped frequently and thus need to be tuned for speed.

[F] Reset I/O profile counts

Reset the trap counts on all I/O ports. Useful for isolating the profile information to a particular section of execution, such as reading from a floppy drive, etc.

[G] Turn procedure call trace logging on/off

Toggles the state of call tracing. When on, each debugging code created by the BeginProc macro performs a Queue_Out of the routine name each time it is entered. Thus when ".S" is invoked to dump a fault log, the log will be interspersed with messages stating each routine name as it is called and who called it, so it is possible to get a complete execution log.

[H] V86 interrupt hook information

Displays the V86 interrupt table; showing the current vector assignment and which VMM/device driver routines have hooked the interrupt, if any. This command gives a look at which interrupts are looked at by the different device drivers, etc.

[I] PM interrupt hook information

This command is similar to "G" above, but show the logical PM interrupt table. It shows current vector assignments and routine names that are hooked into the interrupt chains.

[J] Reset PM and V86 interrupt profile counts[K] Display event lists This command displays the list of current global events, and then of list

of local events for each VM.[L] Display device list This command displays the list of loaded devices along with the

information from each Device Descriptor Block. Type .VMM L={DDB}, where DDB is the name of the VxD, to list an explicit module.

[M] Display V86 break points

This command displays a list of all V86 break points that are currently allocated. This list shows that CS:IP of the break point, the Ring 0 callback address/label and the reference data.

[N] Display PM break This command displays a list of all PM break points that are currently

Page 79


points allocated. This list shows that CS:IP of the break point, the Ring 0 callback address/label and the reference data.

[O] Display interrupt profile

Profiles the activity (counts) of V86 Ints, PM Ints and VMM Ints

[P] Reset interrupt profile counts[Q] Display GP fault profile

Profiles General Protection Fault activity

[R] Reset GP fault profile counts[S] Toggle verbose device call trace

Turn on verbose device tracing to displays the name of each VxD before it is called, and OK when the VxD returns.

[T] Dyna-link service profile information

Displays a list of all services (in VMM and all devices) that shows the number of times the service has been called, the service number, routine address, and routine name. This information is a pseudo profile of which services are used frequently and thus should be tuned for speed.

[U] Fault Hook information

Displays all V86 fault hooks, PM fault hooks and VMM fault hooks.

[V] Display time out queues

Displays all the time out queues including the Async time out queue and Global time out queue.

[W] PM CLI/STI trace info[X] DPMI info

.VPICD (Virtual PIC Device Status)Status of hardware interrupts:[1] Global PIC information (ring 0)[2] Per-VM PIC information (virtualized VM state)[3] IRQ handler information (hardware interrupts and who is responsible for each)

.VXDLDR (List Loaded Dynamic VxDs)Displays the list of dynamically loaded VxDs.

.Y (CONFIGMG Debug Binary Utility)Displays CONFIGMG (Plug & Play) structures:

Welcome to CONFIGMG's debuggerA Arbitrators Show the list of arbitratorsB Block queue Prevent processing of eventsC Query remove Query removal at happy timed remove Removal at happy timee toggle Echo Set the echo to a specified level

Page 80


f show Free Show free resourcesg enumerate Enumerate a devnodeh Reenable Appy Reenable checking of query removei Show Log Show procedural logsj test walks Test our walk proceduresk Show stack Show stack of procedure logsl show List Show devnode listm screen size Set screen sizen Nuke logs Nuke the procedure loggedp Problem List devnodes with problemsq Quit Quit the debuggerr show Range Show a Ranges Show tree Show the hardware treet toggle time Toggle the display of timeu Unblock queue Restart processing of eventsv View status View the global status of CONFIGMGw show all range Show all the rangelistsx eXclude Filter logging of procedure logsy force smthng Call some random HWProfile API

z Allow DLL call Allow the DLLs to be called

Page 81


Chapter 4. Other Tools

The Device Driver Kit includes several tools: • ADRC2VXD Adds a resource to a VxD file.

• DEVLIB Manages W4 compressed VxD libraries.

• EXE2BIN Converts a small-model .EXE file to a .COM file.

• HDR Displays information about executable files.

• INFEDIT Edits .INF files.

• SYMLIB Manages symbol files (.SYM files).

ADRC2VXD The ADRC2VXD command allows you to append a resource onto a VxD file. You can use this command to add version information to your VxDs.

Syntax adrc2vxd vxdname resfilename

Parameters vxdname Specifies the VxD filename

resfilename Specifies the resource filename.

Examples The following example appends the resource version.res onto the VxD vtestd.vxd adrc2vxd vtestd.vxd version.res

Creating a version resource You can use the following template to create a version resource for your VxD file

/********************************************************************//* Version control data *//********************************************************************/#include <version.h>

#define VER_FILETYPE VFT_VXD#define VER_FILESUBTYPE DEVICE_ID#define VER_COMPANYNAME_STR "Company Name, Inc.\0"#define VER_FILEDESCRIPTION_STR "Sample VxD\0"#define VER_INTERNALNAME_STR "Sample\0"#define VER_LEGALCOPYRIGHT_YEARS "1993-1995\0"#define VER_ORIGINALFILENAME_STR "SAMPLE.VXD\0"

#include <common.ver>

In the example, DEVICE_ID is the VxD's Device ID or UNDEFINED_DEVICE_ID (defined in inc32\vmm.h) for dynaload VxDs. Use the resource compiler (rc.exe) to compile the above (the include files version.h and common.ver are in the inc16 include file subdirectory) and adrc2vxd to add it to your VxD.

Page 82


DEVLIB The command DEVLIB manages the new, compressed W4 format VxD libraries (like VMM32.VXD).

Syntax devlib [-c | -d | -p | -a] libname [ filename ]

Parameters -c Creates a VxD library.

-d Dumps (prints a table of contents) for the VxD library specified by libname. The library must be unpacked first. You can use the optional filename argument to extract a VxD in the library.

-p Pack (compresses) a VxD library.

-u Unpacks (uncompresses) a VxD library.

-a Appends the VxD filename to the library. The -a is optional.

libname Specifies the library name.

filename Specifies the VxD filename.

EXE2BIN Strips the .EXE header from an executable file. You can use EXE2BIN to create .COM files.

Syntax exe2bin filename

Parameters filename Specify the name of the file to strip.

Restrictions • The executable file must not contain a stack segment.

• The combined size of code and data must not exceed 64K

HDR Prints header information from executable files.

Syntax hdr [ options ] filename

Parameters -d Prints data relocation records.

-f Prepends the file name on every output line.

-h Prints the file header (default).

-m Print only memory segment table information.

-j[options] Prints specified tables.

d Prints debug table.

e Prints entry table.

f Prints extended attributes.

Page 83


i Prints import module table.

I Prints import procedure table.

r Prints resident name table.

R Prints resource table.

-p Prints file seek positions.

-R Same as -r, but also follows relocation chains.

-r Prints both text and data relocations.

-S Prints the file segment table with a header.

-s Prints the symbol table.

-T Prints the file type.

-t Prints the text relocation records.

-y Dumps DOS .SYM file.

-v Prints everything (verbose).

-? Prints usage summary.

filename Specifies the filename

INFEDIT The INFEDIT command is covered in the Device Installation section. See the document DEVINST.DOC for more information.

SYMLIB You can use SYMLIB to manage symbol libraries (.SYM files). With SYMLIB you can create new symbol files, add symbols, remove symbols, and update symbols.

Syntax symlib symlib1{+symlib2|-{symlib2|symbol}| symlib2|-+symlib2}

Parameters symlib1 Specifies the symbol library (.SYM file) to be created or modified.

symlib2 Specifies the symbol library (.SYM file) to be added to or updated in symlib1

symbol Specifies the symbol to be removed from symlib1

There should be no space between the '+' or '-' and the following argument.

Examples The following example adds vmm.sym to win386.sym. symlib win386.sym vmm.sym

or symlib win386.sym+vmm.sym

The following example updates the symbols in win386.sym with those in vmm.sym. symlib win386.sym-+vmm.sym

Page 84

Note


The following example deletes the symbol vmm from win386.sym. symlib win386.sym-vmm.sym

WDEB386 System Debugger Technique Report Microsoft® Windows® System Debugger (WDEB386.EXE) is used to test and debug Windows applications(Including ACPI), dynamic-link libraries (DLLs), and virtual device drivers (VxDs) running with the Microsoft Windows operating system. You use System Debugger commands to inspect and manipulate memory and registers, control the execution of code, and perform other debugging operations. How to Get StartedYou need a test computer and a debug terminal computer with a serial port, and you'll need a null-modem cable. To set up WDEB386 1. Install the Windows 98 Device Driver Kit (DDK). 2. At the command prompt, go to the Bin subdirectory of the directory you installed the DDK in.YOu will get wdeb386.exe and runwdeb.bat. 3. In test computer , Be sure that RUNWDEB.BAT and WDEB386.EXE are in the subdirectory c:\windows\system. 4. Edit RUNWDEB.BAT if necessary. The RUNWDEB.BAT file has been configured to support most environments. Depending on the

COM port you plan to send debugging data out to you may need to change the /C:1 portion of the command line to /C:2

reflect COM2. WDEB386 [/A] [/B] [/C:1|2|3|4] [/D:"commands"] [/E] {/F:filespec} [/L] [/N] [/R: dddd]

{/S:filespec} [/T:hhhh] [/V[P]] [/X] programspec [parameters] /A don't auto-load symbol files /B stop debugger during initialization /C specifies COM port for debugging terminal /D executes a debugger command line /E stops at real-mode entry /F command line response file /I makes debugger invisible to int 41 /H load wdeb386 as a vxd /L suppress line numbers from SYM file /N new debugger option defaults /R specifies the baud rate for debugging terminal /S specifies symbol files to be loaded /T specifies the TEFTI or STAT! card base in hex /V displays all segment load notifications /VP displays only windows segment load notifications /X load symbols in XMS memory

5. Update your AUTOEXEC.BAT file on the test computer to include the following lines: REM Goto End

cd\windows\system

Page 85


pause runwdeb :End This way if you want to disable the debugger through multiple boots you can take the

REM prefix off the Goto statement and avoid starting the debugger at all. The pause command makes last

minute changes much easier 6. To disable handshaking in debug terminal computer. a. Using your right mouse button, click My Computer, and then click Properties. b. In the System Properties dialog box, click the Device Manager tab. c. In the list of device types, double-click Ports (COM & LPT). d. Double-click the name of the port the cable is connected to, usually Communications

Port (COM2). f. In the Communications Port Properties dialog box, click the Port Settings tab. g. In the Flow Control list, click None. h. Click OK. 7. Then connect to the test computer via a null modem cable, and running a terminal program. 8. Reboot test computer, You should see the following print on the test system: Microsoft (R) Windows 4.0 Kernel Debugger Version 4.0.6 xx/xx/97 xx:xx:xx Copyright (C) Microsoft Corp. 1990-1997. All Rights Reserved

On the screen running the terminal program you should see:Kernel Debugger Version 4.0.6 02/24/97 23:52:11 [80386]

Note: Under terminal computer you can break into the Kernel debugger any time by pressing

Ctrl+C. If you are at the ## prompt (kernel debugger prompt) you can type in all command to get

debugger. About debug command , Please reference : MSDN Library\DDK Documentation\Windows 95 DDK\Windows 95

Documentation\Programmer's Guide\WDEB386 System Debuger\Refererce

Page 86

Documents

Wdeb386 debugger