Windbg Commands Overview

As have introduced, windbg provides several categories commands, while I am going to categorize the commands from the operation perspective in this post, like memory management, execution control, register, etc...
Display and edit memory, using d* serial commands to display certain types data start from ......specific memory address.
For example, db 0x0700,0000 displays bytes values and ASCII characters start from 0x0700,0000. Except db, there are also dw,dW,dd,dq,dp,dps,da,du, ds,dS to display different types memory content. Please refer to the help documents of windbg for details.
You can use e* serial commands to modify memory. For example eb 0007,fed8 will edit 1 byte memory start from 0007,fed8:
............0:002> db 0007fed8 0007fed8
............0007fed8 1f .
............0:002> eb 0007fed8
............0007fed8 1f f1
............f1
............0007fed9 1f
............0:002> db 0007fed8 0007fed8
............0007fed8 f1
You can also use ew, ed, eq, ep to edit different kinds of memory. Notice that editing memory works on crash dumps but changes are not saved.

Windbg introduction (4) - Extension DLL

Usually debugger has 3 kinds of commands:

Normal Commands
…Directly executed by debugger
…Typical debugger operations
……Examples : dd 70003478, x ntdll!Nt*Port*, uf ntdll!ZwClose
!commands ( Debugger Extension DLL Commands)
…Executed by extension DLL
…Syntax is !ExtensionDLL.Command
……Omitting ExtensionDLLcauses debugger to use default debugger extension DLL
…Most debugger extensions have a “.help” command that lists the supported commands and their usage syntax
……link –dump –exports extension.dllalso shows list of commands
…WinDBG documentation also contains description of these commands
…Proprietary extension DLLs can be created using WinDBG SDK
……SDK is not installed by “Typical” debugger installation option
…Examples : !runaway, !rpcext.sizes, !uexts.help
.commands (Meta commands)
…Controls the debugger behavior (debugger settings)
…WinDBG and KD have same .command sets
…Example : .echotimestamps, .logappend logfile.txt


Generally, Debugger Extensions are Win32 DLLs that run in the WinDBG / KD environment, which call functions exported by the debugger engine. Interfaces (APIs) available for writing extension DLLs are: Managed Debugger Extension API (MDbgEng.dll); C++ Class framework library (EngExtCpp); COM based debugger engine interface; “C” function call based legacy debugger engine interface. Debugger interfaces use 64 bit addresses, and the same extension DLL works for both 32 bit and 64 bit targets.

Following are the functionalities exported by the debugger engine:
…Read and Write Memory
…Manipulate Breakpoints
…Control Execution
…Evaluate Expressions
…Query Symbol Table
…Query Type Information
…Enable Source Level Debugging.

Debugger Extension DLLs don’t need to be installed or registered, which can be copied in any directory in the debugger’s extension DLL search path. WinDBG/KD automatically picks the right version of the extension DLL corresponding to the target OS (nt4chk, nt4fre, w2kchk, w2kfre, winxp & winext directories). Pre-WinXP extension DLLs are OS version and type (checked or free) specific since the structure type information are hardcoded; Newer version of extension DLLS query structure type information from symbol table (.PDB file) at run time. DLLs in winxp directory support WinXP all subsequent versions of the OS.

Notice that debugger can load at the most 32 different extension DLLs. You can use following extension dll related commands:
…“!ExtensionDLL.help” can print out a list of commands supported by extension DLL
…“.chain” can print information on all currently loaded extension DLLs
…”.extpath” can set the extension DLL search path
…”.load” or “.loadby” can load a new extension DLL into the debugger
…”.unload” can unload an extension DLL from the debugger
…”.unloadall” can unload all extension DLLs from the debugger
…”.setdll” can change the default extension DLL for the debugger

Debugger has following user mode extension DLLs:
…exts.dll
……User and Kernel Mode Extension DLL
……Contains commands that can be used on both user mode and kernel mode targets
…uext.dll
……User Mode Debugger Extension
……Contains OS independent debugger extension commands
…logexts.dll
……Windows API Logging Extension
……Provides commands for runtime Win32 API Logging and Monitoring
…ntsdexts.dll
……User Mode Extension DLL
……Contains the OS dependent user mode debugger extension commands
…rpcexts.dll
……Remote Procedure Call Extension DLL
……Contains over 50 different RPC commands

Next session will introduce how to write a Debugger extension dll.

Windbg introduction (3) - Remote Debug

How to setup remote debug session using process server (DbgSrv.exe):

DbgSrv.exe is small application running on the same system as the target process. We can use it to attach to a target process or starts up a new process under control of debugger; can enable the process to be debugged remotely; does not require symbols or source code on target system.
Syntax:
DbgSrv –t tcp:port=<PortNumber>

For example, following command starts an dbgsrv process listening at TCP port 8000:
c:\Debugger\dbgsrv.exe -t tcp:port=8000

Detail usage:
Usage: dbgsrv -t [-sifeo ] [-x] [-c[s] ] [-pc ]
...transport: tcp npipe ssl spipe 1394 com
......for tcp use: port= <socket port #>
......for npipe use: pipe= <name of pipe>
......for 1394 use: channel= <channel #>
......for com use: port=<COM port>,baud=<baud rate>, channel=<channel #>
for ssl and spipe see the documentation

Example: dbgsrv -t npipe:pipe=foobar

Then run following command on host system to start an smart windbg client process:
Windbg –Q –premote tcp:server=<targetsystem>,port= <portnumber>

For example, following command will start windbg client, which starts a notepad.exe process under the control of dbgsrv process:
c:\debugger\Windbg -Q -premote tcp:server=localhost,port=8000 notepad.exe We can verify this by following command to list all of the current processes running on the system:
c:\debugger\tlist –t
-----------------------------
....
dbgsrv.exe (3308)
...notepad.exe (2220)
windbg.exe (1060) [tcp:server=localhost,port=8000] notepad.exe - WinDbg:6.8.0004.0 tlist.exe (2796)
--------------------------------
Apparently, notepad.exe (2220) is the child process of dbgsrv.exe (3308).

Now you can execute any commands on windbg client, which will be forwarded to dbgsrv.exe process and executed against the target process. For example: ‘g’ will run the target notepad.exe and you can type some text “ABCD” into the window.
Finally, at the end of your debugging, type ‘.endpsrv ’ will terminate DbgSrv.exe on the target system. Then, any command will fail since target process has been terminated.
For example:
0:002> .endpsrv
Server told to exit
Try to list all processes on the target system will fail:
0:002> .tlist
Unable to get process list, HRESULT 0x8001000A

Windbg Introduction (2) - Debug Type

The common used Debugger switches:
-Q: Suppresses prompt for saving workspace
-y: Path to symbols, symbol server
-srcpath: Source files directory path
-server: Creates a debugging server that remote debuggers can connect to
-remote: Creates a debugging client that attaches to a debugging sever
-g: Ignores initial breakpoint in target application
-z: Path to crash dump used for post-mortem debugging.
-p: Specifies the decimal process ID to be debugged. This is used to debug a process that is already running

Normally, as have posted in previous blog, there are 2 common types of debugging: live debugging and post-mortem debugging.

Live debugging usually needs SeDebugPrivilege user right , refer to http://support.microsoft.com/kb/131065/. Generally, there are 3 common used debugging scenarios:
1. User mode debugging – attach to a running process
2. User mode debugging – start an executable under debugger
3. User mode remote debugging – by TCP/IP or named pipe, which requires target process running under debugger or process server, AND remote debugger connect to the local debugger or process server through network.
Besides, debugger can attach and debug multiple processes simultaneously.

While post-mortem debugging is simple, just load the crash dump file and do debug (the crash dump either manually created when application hang or automatically created when application crash).

Also, if categorized by debugging mode, there are Invasive and Non-Invasive debugging.

Invasive debugging means debugger will attach to the target process and start a thread inside it. Debugger will interact with target process. OS send events like module loads and exceptions to debugger. Using ‘qd’ command to detach debugger from process and quit.

Non-Invasive debugging (opens a process), Debugger can access the Virtual Address of the target process, BUT cannot perform any execution control on target process, like bp, bu, g, p, t. Useful on WinNT4 and Win2000 where ‘qd’ is NOT supported.
You can use ‘.detach’ AND ‘.attach –v PID’ to switch from Invasive debugging to Non-Invasive debugging.

Windbg Introduction (1) - Start

从本篇博客开始给大家详细介绍Windows平台上常用的软件调试工具，包括Windbg, KD, NTSD, CDB。
从www.microsoft.com/whdc/ddk/debugging可以下载Debugger安装包，安装到本地目录， 比如C:\debugger\,注意不要安装到默认目录，因为默认安装目录(c:\program files\...)可能包含空格，会影响部分功能的正常使用。

在安装目录中可以发现如下可执行文件：Windbg,KD,NTSD,CDB. 其中，Windbg是带有图形界面的调试工具；CDB是基于控制台的调试器；而NTSD是NT符号化调试器(symbolic debugger),可以在后台运行；KD则是Windows的Kernel调试器。

这些调试器支持的CPU架构有X86,X64,IA64；支持Windows NT4SP3+,Win2000,WinXP,Win2003,Vista和Win2008；支持Native和Managed程序调试；支持运行调试器扩展命令。

调式的模式则分为两种： 实时调试--调试器Attach到一个目标运行进程进行调试；事后剖析(post-mortem)调试--目标进程的状态包含在一个Crash Dump中，可以装载并分析Dump，还可以装载任何可执行文件(.exe;.dll;.sys)到内存中。

调试器组件和架构：

其中，windbg.exe, cdb.exe, ntsd.exe是用于管理用户输入和输出的界面程序；dbgeng.dll是执行调试器的动作并为用户界面和扩展程序提供API的模块；dbghelp.dll则从.PDB文件中抽取符号信息表，符号信息是调试任何程序的基础。