Writing WinDbg Extensions

< BACK  NEXT >

[oR]

One of WinDbg's strengths is that its capabilities can be expanded by writing custom extension commands. This can be quite convenient, particularly for formatting the display of driver-specific data structures. This section explains the process of adding extension commands to WinDbg.

How WinDbg Extensions Work

A WinDbg extension is just a user-mode DLL that exports various commands in the form of DLL functions. The extension DLL also contains several support routines that perform initialization and version-checking operations.

The linkage between target system memory (whether crash file dump or a live target) is established with callback routines that the extension DLL uses to reference the debug target. This means the DLL has the same view of the target system's memory as WinDbg. In particular, extension commands cannot reference memory that was paged out at the time a crash or breakpoint occurs.

Initialization and Version-Checking Functions

To write an extension DLL for WinDbg (or NTSD or KD, for that matter), two DLL export functions are required for initialization. Optionally, a third version-checking function can be provided. These functions are described below.

WinDbgExtensionDllInit

WinDbg calls this function when the user loads the extension DLL. Its job is to save the address of the callback table so that other parts of the DLL can use it. This function (described in Table 17.3) is required.

Table 17.3. Function Prototype for WinDbgExtensionDllInit

VOID WinDbgExtensionDllInit
Parameter	Description
PWINDBG_EXTENSION_APIS	Address of table containing pointers to WinDbg
pExtensionApis	callback functions
USHORT MajorVersion	0xF for free build of Windows 2000
	0xC for checked build
USHORT MinorVersion	Build number of Windows 2000
Return value	- void -

ExtensionApiVersion

WinDbg calls this function when it attempts to load an extension DLL. Its purpose is to validate version compatibility between WinDbg and the extension. It does this by returning a pointer to the version structure associated with the extension DLL. This function (shown in Table 17.4) is required.

Table 17.4. Function Prototype for ExtensionApiVersion

LPEXT_API_VERSION ExtensionApiVersion
Parameter	Description
Void	None
Return value	Address of the DLL's EXT_API_VERSION structure

CheckVersion

Each time WinDbg executes a command in the DLL, it calls this function before calling the command routine. CheckVersion's job is to ensure that the version of the extension DLL is compatible with the version of Windows 2000 being debugged. If not, an error message should inform the user of the problem. The function (described in Table 17.5) is optional.

Table 17.5. Function Prototype for CheckVersion

VOID CheckVersion
Parameter	Description
Void	None
Return value	None

Writing Extension Commands

Each command in an extension DLL is implemented as a separate function. A macro, DECLARE_API, facilitates the declaration of each extension function.

 DECLARE_API( command_name ) {      //      // code goes here...      //      ... } 

DECLARE_API provides the function with the prototype shown in Table 17.6. The names of commands must be provided in complete lowercase; otherwise WinDbg cannot find them.

Table 17.6. Extension Command Function Prototypes

VOID command_name
Parameter	Description
IN HANDLE hCurrentProcess	Handle of current process on target
IN HANDLE hCurrentThread	Handle of current target thread
IN ULONG dwCurrentPc	Current value of program counter
IN ULONG dwProcessor	Number of current CPU
IN PCSTR args	Argument string passed to the command
Return value	void

The work that an extension command might perform is boundless. Any operation that makes debugging easier, such as formatting and displaying driver-specific data structures, is appropriate.

If an extension command takes (or could take) a long time to execute, or if considerable output is involved, it should periodically check to see if the WinDbg user has typed Ctrl-C. Otherwise, the user has no way to interrupt the command. One of the WinDbg helper functions described in the next section performs this check.

WinDbg Helper Functions

An extension DLL gains access to the system being debugged by invoking helper functions exported by WinDbg. These functions also provide access to the WinDbg command window for input and output. Table 17.7 contains a brief description of these helper functions.

Table 17.7. WinDbg Helper Functions Available to Extension DLLs

WinDbg Helper Functions
Function	Description
dprintf	Print formatted text in WinDbg command window
CheckControlC	See if WinDbg user has typed Ctrl-C
GetExpression	Convert a C expression into a DWORD value
GetSymbol	Locate name of symbol nearest a given address
Disassm	Generate string representation of machine instruction
StackTrace	Return stack-trace of current process
GetKDContext	Return current CPU number and count of CPUs
GetContext	Return CPU context of process being debugged
SetContext	Modify CPU context of process being debugged
ReadControlSpace	Get platform-specific CPU information
ReadMemory	Copy data from system virtual space into buffer
WriteMemory*	Copy data from buffer to system virtual space
ReadIoSpace*	Read I/O Port
WriteIoSpace*	Write I/O port
ReadIoSpaceEx*	Read I/O port on specific bus-type and number (Alpha only)
WriteIoSpaceEx*	Write I/O port on specific bus-type and number (Alpha only)
ReadPhysical	Copy data from physical memory into buffer
WritePhysical*	Copy data from buffer to specific physical addresses

The documentation for these helper functions is contained within the DDK help files. Look for the section entitled "Routines Called From Debugger Extensions."

Building and Using an Extension DLL

A WinDbg extension is just a user-mode DLL, and, therefore, Visual Studio is an appropriate vehicle for its construction. Interestingly, because a driver-specific extension relies on driver structures (and perhaps some DDK structures), some unusual #include statements appear. Otherwise, the build process is quite routine for an extension DLL.

To load and use an extension DLL with WinDbg, it must be loaded using the !load command. After that, the commands are directly accessible by preceding them with a bang (!), using the form !command. The !unload command allows the unloading of an extension DLL.

WinDbg allows up to 32 extension DLLs to be loaded simultaneously. When executing a !command, WinDbg searches DLLs starting with the most recently loaded. Thus, it is possible to override the functionality of an existing extension command.

< BACK  NEXT >