WindowsWindows®® 2000 2000 DebuggingDebugging

André Vachon André Vachon Development LeadDevelopment LeadWindows DebuggersWindows DebuggersMicrosoft CorporationMicrosoft Corporation

AgendaAgenda DocumentationDocumentation SymbolsSymbols Dump FilesDump Files Debugger changesDebugger changes Debugger ExtensionsDebugger Extensions

DocumentationDocumentation Debugging is a knowledge Debugging is a knowledge

intensive taskintensive task The more you know, the more The more you know, the more

efficient you areefficient you are We have focused on providing much We have focused on providing much

better debugger documentationbetter debugger documentation Ships as part of the debugger packageShips as part of the debugger package

Will point you to debugger Will point you to debugger information all through the talkinformation all through the talk

DocumentationDocumentation Focused on the reference sectionsFocused on the reference sections

Documentation for all the parameters Documentation for all the parameters and commandsand commands

Unique command line interface for the Unique command line interface for the debuggersdebuggers

Future enhancementsFuture enhancements More debugger extensionsMore debugger extensions More “How To” sections for common More “How To” sections for common

debugging scenariosdebugging scenarios

SymbolsSymbols Symbol support in Windows debuggersSymbol support in Windows debuggers

exportsexports .dbg files.dbg files .pdb.pdb Mix of any symbol type since NT 4Mix of any symbol type since NT 4

Diagnosing bad symbolsDiagnosing bad symbols Symbol ServerSymbol Server

What Are .dbg Files ?What Are .dbg Files ? Only exist when compiling with VC 4 Only exist when compiling with VC 4

or VC 5or VC 5 Compiler and linker left extra debug Compiler and linker left extra debug

information in the imagesinformation in the images .dbg created to remove this extra info.dbg created to remove this extra info

Generated by internal tool from the .exe Generated by internal tool from the .exe or .dllor .dll

Contains basic debugging informationContains basic debugging information Contains pointer to the .pdb fileContains pointer to the .pdb file

What Are .pdb Files ?What Are .pdb Files ? Generated by the compiler and linkerGenerated by the compiler and linker Binary file with multiple “streams”Binary file with multiple “streams”

Each streams contains a certain type of Each streams contains a certain type of debugging informationdebugging information

Matched to the executable with Matched to the executable with unique identifiersunique identifiers Age and signatureAge and signature

Full .pdb FilesFull .pdb Files .pdb file as generated by the linker.pdb file as generated by the linker Has all data streamsHas all data streams

Types, locals, globals, statics, fpo, Types, locals, globals, statics, fpo, fixups, OMAP, source linesfixups, OMAP, source lines

Required to do full source Required to do full source level debugginglevel debugging

Files are very largeFiles are very large ntoskrnl.pdb is 8 MEGntoskrnl.pdb is 8 MEG

Not shipped outside MicrosoftNot shipped outside Microsoft

Public .pdb FilesPublic .pdb Files Generated by a tool from the full .pdbGenerated by a tool from the full .pdb Certain data streams are removedCertain data streams are removed

Types, locals, source linesTypes, locals, source lines All function names and data required All function names and data required

for stack traces are includedfor stack traces are included Globals, fpoGlobals, fpo

Files are much smallerFiles are much smaller Ntoskrnl.pdb is 1 MEGNtoskrnl.pdb is 1 MEG

Public .pdb files are shipped on the Public .pdb files are shipped on the support CDsupport CD

Type InformationType Information Type information is contained in one Type information is contained in one

of the .pdb streamsof the .pdb streams Full encoding of every type definition Full encoding of every type definition

used in a binaryused in a binary Every field name of every structureEvery field name of every structure

Debugger can query type definitionsDebugger can query type definitions Used for structure expansion Used for structure expansion

in debuggerin debugger

Other SymbolsOther Symbols Export SymbolsExport Symbols

Debugger can use public exports Debugger can use public exports as symbolsas symbols

Used when no symbol file can be foundUsed when no symbol file can be found Map filesMap files

Only used on Win9xOnly used on Win9x Not supported by kd\ntsd\WinDBGNot supported by kd\ntsd\WinDBG

Diagnosing Bad SymbolsDiagnosing Bad Symbols Debugger will give you a message Debugger will give you a message

when symbols are not foundwhen symbols are not found !sym noisy!sym noisy

More verbose symbol loadMore verbose symbol load !dh <image_base_address>!dh <image_base_address>

Dumps image headersDumps image headers Lm, lml, !driversLm, lml, !drivers

More commands to look at imagesMore commands to look at images Will add more documentation and Will add more documentation and

debugger commands for thisdebugger commands for this

Symbol ServerSymbol Server Symbol files can be indexed on Symbol files can be indexed on

a single machinea single machine Use unique identifiers from the images Use unique identifiers from the images

and symbol files to find the symbolsand symbol files to find the symbols New extension to the New extension to the

symbol handlersymbol handler Point to one location which contains Point to one location which contains

all your symbolsall your symbols We will ship tools to build We will ship tools to build

symbol serverssymbol servers More documentation to comeMore documentation to come

Dump FilesDump Files What are dump filesWhat are dump files Types of dump filesTypes of dump files

Kernel mode vs User modeKernel mode vs User mode Full dumps vs. Mini dumps.Full dumps vs. Mini dumps.

How to use dump filesHow to use dump files 32 bit vs 64 bit32 bit vs 64 bit

Kernel Dump FilesKernel Dump Files Three types of dump filesThree types of dump files

Full (All NT versions)Full (All NT versions) Summary (win2k)Summary (win2k) Mini (win2k)Mini (win2k)

Very useful to analyze software Very useful to analyze software failures off-linefailures off-line

Can not be used to analyze Can not be used to analyze hardware related problemshardware related problems

Full Kernel Dump FileFull Kernel Dump File In NT4, Win2k, WhistlerIn NT4, Win2k, Whistler Stores all the physical memory Stores all the physical memory

in the machinein the machine Dump is independent of virtual Dump is independent of virtual

addresses or processesaddresses or processes Data saved to the page fileData saved to the page file

Dump fails if page file is not Dump fails if page file is not large enoughlarge enough

Page file must be on boot drivePage file must be on boot drive Page file content is destroyedPage file content is destroyed

Can not restart OS from a kernel dump fileCan not restart OS from a kernel dump file

Full Kernel Dump FileFull Kernel Dump File AdvantagesAdvantages

Most complete dump availableMost complete dump available When debugged, paged-in portions of When debugged, paged-in portions of

user mode processes can be vieweduser mode processes can be viewed DisadvantagesDisadvantages

Can be very time consuming to createCan be very time consuming to create

Summary Kernel Dump FileSummary Kernel Dump File New in Windows 2000New in Windows 2000 Saves resident kernel pages onlySaves resident kernel pages only AdvantagesAdvantages

Quicker to generate at crash timeQuicker to generate at crash time Provide enough information to analyze Provide enough information to analyze

any kernel data structureany kernel data structure DisadvantagesDisadvantages

Can not look at any user mode stack Can not look at any user mode stack or data structuresor data structures

Mini Kernel Dump FilesMini Kernel Dump Files New in Windows 2000New in Windows 2000 64K in size64K in size Contains minimum amount of Contains minimum amount of

information to analyze a faultinformation to analyze a fault Context of the faulting threadContext of the faulting thread Stack of the faulting threadStack of the faulting thread Current thread and process Current thread and process

data structuresdata structures Kernel module listKernel module list A few key MM data structuresA few key MM data structures

Mini Kernel Dump FilesMini Kernel Dump Files AdvantagesAdvantages

Very quick to generateVery quick to generate Enabled by default by setup on Enabled by default by setup on

Windows 2000 ProfessionalWindows 2000 Professional Enough to pin-point simple failuresEnough to pin-point simple failures

DisadvantageDisadvantage Not enough information to do full Not enough information to do full

fault analysisfault analysis No Image sectionsNo Image sections

Requires debugger to load images Requires debugger to load images to get stack tracesto get stack traces

User Dump FilesUser Dump Files Two types of dump filesTwo types of dump files

Full (All NT version)Full (All NT version) Mini (whistler)Mini (whistler)

Full User Dump FileFull User Dump File Dump of the entire address space Dump of the entire address space

of the applicationof the application Generated automatically Generated automatically

by Dr.Watsonby Dr.Watson AdvantagesAdvantages

Lets you debug the fault off lineLets you debug the fault off line DisadvantagesDisadvantages

Can be very large and long Can be very large and long to generateto generate

Mini User Dump FileMini User Dump File Dump only contains basic Dump only contains basic

information about the crashinformation about the crash All threads, with associated context All threads, with associated context

and stackand stack List of modulesList of modules

AdvantagesAdvantages Small and quick to createSmall and quick to create

DisadvantagesDisadvantages Can only debug simple failures (AVs)Can only debug simple failures (AVs)

Using Dump FilesUsing Dump Files Debugger can load ANY type Debugger can load ANY type

of dump fileof dump file kd –z <dump_file> -y <sym_path>kd –z <dump_file> -y <sym_path>

All debugger commands and All debugger commands and extensions work identically extensions work identically to live debuggingto live debugging Some limitations based on information Some limitations based on information

available in the dumpavailable in the dump Minidump filesMinidump files

Must specify –i <image_path>Must specify –i <image_path> Limited data in the dump file restricts Limited data in the dump file restricts

which commands are validwhich commands are valid

Using Dump FilesUsing Dump Files AdvantagesAdvantages

Very simple to use with the debuggerVery simple to use with the debugger Very useful for off-line analysisVery useful for off-line analysis Can get dump files from customersCan get dump files from customers Can send dump files to other developersCan send dump files to other developers

DisadvantagesDisadvantages No adapter hardware state is availableNo adapter hardware state is available No access to live adapter registersNo access to live adapter registers Cannot execute codeCannot execute code Minidumps don’t have much informationMinidumps don’t have much information

32 Bit Vs. 64 Bit Dump Files32 Bit Vs. 64 Bit Dump Files Different file formatsDifferent file formats

Certain fields are extended to handle Certain fields are extended to handle 64 bit addresses64 bit addresses

64 bit dump files will get even 64 bit dump files will get even bigger, as address space of bigger, as address space of machine gets biggermachine gets bigger

The debugger just works with any The debugger just works with any dump filedump file

Debugger ChangesDebugger Changes Redesigned debugger internalsRedesigned debugger internals

Simple Debugger UISimple Debugger UI Command line - kd, cdb, ntsdCommand line - kd, cdb, ntsd Graphical - WinDBGGraphical - WinDBG

New debugger engineNew debugger engine Broader coverage of Windows OSesBroader coverage of Windows OSes Support for new transportsSupport for new transports Much better testingMuch better testing

Windows group will use same Windows group will use same debugger as external developersdebugger as external developers

Debugger ArchitectureDebugger ArchitectureThe debuggers have been split into:The debuggers have been split into: UIUI

Simple and replaceable front end that Simple and replaceable front end that manages user input and outputmanages user input and output

Debugger engineDebugger engine Handles all debugging activityHandles all debugging activity Exposes rich set of APIs to debugger Exposes rich set of APIs to debugger

UIs and extensionsUIs and extensions Symbol HandlerSymbol Handler

Used by engine to get symbolic infoUsed by engine to get symbolic info

HOST, TARGET, REMOTEHOST, TARGET, REMOTE HOST – Machine running the HOST – Machine running the

debugger directly connected debugger directly connected to the TARGETto the TARGET

TARGET -- Machine TARGET -- Machine being debuggedbeing debugged

REMOTE – Machine remotely REMOTE – Machine remotely running the debugger, connecting running the debugger, connecting to the HOSTto the HOST

HOSTHOST The debugger binaries are run on The debugger binaries are run on

the HOSTthe HOST WinDBG, kd, ntsd, debugger engineWinDBG, kd, ntsd, debugger engine

The debuggers binaries work and The debuggers binaries work and are tested on all versions of NT, are tested on all versions of NT, starting with NT 4starting with NT 4

Debugger could also run on Win9xDebugger could also run on Win9x Not tested yetNot tested yet We need to know if this is an issueWe need to know if this is an issue

Kd.exeKd.exe Kernel debuggerKernel debugger Simple command line UISimple command line UI

Takes all commands and sends them Takes all commands and sends them to the debugger engineto the debugger engine

Displays output from debugger engineDisplays output from debugger engine Merged i386kd, alphakd and ia64kd Merged i386kd, alphakd and ia64kd

into oneinto one

Cdb.exe And Ntsd.exeCdb.exe And Ntsd.exe User mode debuggerUser mode debugger Simple command line UISimple command line UI

Takes all commands and send them Takes all commands and send them to the debugger engineto the debugger engine

Displays output from debugger engineDisplays output from debugger engine Ntsd.exe is shipped in the OSNtsd.exe is shipped in the OS CDB.exe is only in the CDB.exe is only in the

debugger packagedebugger package

WinDBG.exeWinDBG.exe Simple Windows applicationSimple Windows application UI on top of the debugger engineUI on top of the debugger engine

Collection of dialogs to get Collection of dialogs to get configuration informationconfiguration information

A Set of windows to display A Set of windows to display information retrieved from the information retrieved from the debugger enginedebugger engine

WinDBG.exeWinDBG.exe WinDBG pre-release availableWinDBG pre-release available Download from our web site todayDownload from our web site today Debugger engine and command line Debugger engine and command line

100% functional100% functional Missing UI featuresMissing UI features

WorkspaceWorkspace More configuration optionsMore configuration options UI polishUI polish

Debugger EngineDebugger Engine Single DLL, with built in support Single DLL, with built in support

for:for: All versions of NT, starting with NT 4All versions of NT, starting with NT 4 32 bit and 64 bit32 bit and 64 bit User Mode and kernel modeUser Mode and kernel mode Live and Dump File debuggingLive and Dump File debugging RemotingRemoting Exposes full symbolic informationExposes full symbolic information

All these features are transparent All these features are transparent to the UIto the UI

User-Mode DebuggingUser-Mode Debugging For user-mode debugging:For user-mode debugging:

HOST machine == TARGET machineHOST machine == TARGET machine 32 and 64 bit versions of debugger32 and 64 bit versions of debugger

User-Mode Debug DemoUser-Mode Debug Demo Native IA64 debugging sessionNative IA64 debugging session

Kernel Debugging TARGETSKernel Debugging TARGETS TARGET does not use any extra TARGET does not use any extra

debugger binariesdebugger binaries Built-in to HAL and ntoskrnlBuilt-in to HAL and ntoskrnl

Multiple connection mediumsMultiple connection mediums COM portCOM port 1394 (Whistler)1394 (Whistler) Local debugging (Whistler)Local debugging (Whistler)

Kernel Debugging TARGETSKernel Debugging TARGETS Support any TARGET OS from NT4 Support any TARGET OS from NT4

to Whistlerto Whistler Detects version at runtimeDetects version at runtime

MP\UP, pro\svr\adv\dtc, NT4\Win2k\MP\UP, pro\svr\adv\dtc, NT4\Win2k\WhistlerWhistler

Support any TARGET architectureSupport any TARGET architecture Detects at runtime IA64, X86, etcDetects at runtime IA64, X86, etc

Remote DebuggingRemote Debugging Can connect remotely to a HOST Can connect remotely to a HOST

debug sessiondebug session REMOTE uses same binaries REMOTE uses same binaries

as the HOSTas the HOST WinDBG, kd, ntsdWinDBG, kd, ntsd

Support various protocols Support various protocols Named pipes, socketsNamed pipes, sockets

Multiple REMOTE debuggers can Multiple REMOTE debuggers can connect to the host debuggerconnect to the host debugger Must use the same protocolMust use the same protocol

Cannot remotely connect directly Cannot remotely connect directly to TARGETto TARGET

Remote Debugging DemoRemote Debugging Demo

HOST:HOST:X86, Win2K, kdX86, Win2K, kd

Serial Serial cablecable

TARGET:TARGET:IA64 WhistlerIA64 Whistler

REMOTE:REMOTE:X86, WhistlerX86, WhistlerWinDBGWinDBG

Named Named pipespipes

Type Information SupportType Information Support Requires full .pdbRequires full .pdb

Will work with symbol files for your Will work with symbol files for your drivers or applicationdrivers or application

Debugger engine has built-in Debugger engine has built-in support for type informationsupport for type information

New ‘dt’ debugger commandNew ‘dt’ debugger command New debugger interface to expose New debugger interface to expose

type information to the UItype information to the UI

Debugger ExtensionsDebugger Extensions Most important feature of the Most important feature of the

windows debuggerwindows debugger Lets you write specific code Lets you write specific code

to analyze faults or dump to analyze faults or dump data structuresdata structures

Windows DEV team could not debug Windows DEV team could not debug the OS without debugger extensionsthe OS without debugger extensions We have written 100’s of theseWe have written 100’s of these We ship a subset of them with We ship a subset of them with

the debuggerthe debugger !process, !thread, !vm, !pci, etc.!process, !thread, !vm, !pci, etc.

Old Debugger interfacesOld Debugger interfaces Exposed a subset of the Exposed a subset of the

debugger functionalitydebugger functionality Read and write memoryRead and write memory

Virtual, Physical, IO, MSR, PCIVirtual, Physical, IO, MSR, PCI Expression evaluationExpression evaluation Symbol lookupSymbol lookup

Incompatible between ntsd Incompatible between ntsd and WinDBGand WinDBG

New Debugger InterfacesNew Debugger Interfaces Debugger engine exposes the new Debugger engine exposes the new

debugger interfacedebugger interface Complete set of interfacesComplete set of interfaces Object based, yet still very simple Object based, yet still very simple

to useto use WinDBG is implemented using WinDBG is implemented using

these new interfacesthese new interfaces Could easily rewrite a UI to Could easily rewrite a UI to

replace WinDBG replace WinDBG Very simple extensions can be Very simple extensions can be

written to a subset of the interfaceswritten to a subset of the interfaces

New Debugger InterfacesNew Debugger Interfaces Read and write memoryRead and write memory BreakpointBreakpoint Execution controlExecution control Expression evaluatorExpression evaluator Full symbol and TYPE supportFull symbol and TYPE support Source code supportSource code support

Sample Debugger ExtensionSample Debugger Extension Tool to remotely connect to a debug Tool to remotely connect to a debug

session and retrieve the stack tracesession and retrieve the stack trace

Main(pszConnectString) {DebugConnect(pszCS,IID_D, &gDbg);gDbg->QueryInterface(IID_C, &gControl);gDbg->SetOutputCallbacks(&gOutCallback);gControl->Execute(“k”);

}

OutputCallback::Output(Mask, Text) {// handle output appropriately

}

32 bit vs. 64 bit extensions32 bit vs. 64 bit extensions All new interfaces use 64 bit addressesAll new interfaces use 64 bit addresses Debugger extensions should always Debugger extensions should always

use 64 bit addressesuse 64 bit addresses 32 bit addresses are SIGN-EXTENDED32 bit addresses are SIGN-EXTENDED

Must handle this correctly Must handle this correctly in extension DLLsin extension DLLs

Writing Debugger ExtensionsWriting Debugger Extensions New interfaces are not provided New interfaces are not provided

in the current debugger packagein the current debugger package Future release will have headers, libs, Future release will have headers, libs,

docs and samplesdocs and samples NT 4 and win2k extension interfaces NT 4 and win2k extension interfaces

can still be used todaycan still be used today

Write debugger extensions – Write debugger extensions – they will make debugging a lot they will make debugging a lot more easymore easy

Call To ActionCall To Action Try the new debugger !Try the new debugger !

http://www.microsoft.com/ddk/debugginghttp://www.microsoft.com/ddk/debugging Read the documentation. Learning more Read the documentation. Learning more

about the tools will make it easier to about the tools will make it easier to debug problems.debug problems.

For feedback (report bugs or missing For feedback (report bugs or missing featrures) windbgfb@microsoft.comfeatrures) windbgfb@microsoft.com

For support or help with the debugger For support or help with the debugger http://support.microsoft.com/support/ddkhttp://support.microsoft.com/support/ddk