Windows ® 2000 Debugging André Vachon Development Lead Windows Debuggers Microsoft Corporation

Agenda  Documentation  Symbols  Dump Files  Debugger changes  Debugger Extensions

Documentation  Debugging is a knowledge intensive task  The more you know, the more efficient you are  We have focused on providing much better debugger documentation  Ships as part of the debugger package  Will point you to debugger information all through the talk

Documentation  Focused on the reference sections  Documentation for all the parameters and commands  Unique command line interface for the debuggers  Future enhancements  More debugger extensions  More “How To” sections for common debugging scenarios

Symbols  Symbol support in Windows debuggers  exports .dbg files .pdb  Mix of any symbol type since NT 4  Diagnosing bad symbols  Symbol Server

What Are.dbg Files ?  Only exist when compiling with VC 4 or VC 5  Compiler and linker left extra debug information in the images .dbg created to remove this extra info  Generated by internal tool from the.exe or.dll  Contains basic debugging information  Contains pointer to the.pdb file

What Are.pdb Files ?  Generated by the compiler and linker  Binary file with multiple “streams”  Each streams contains a certain type of debugging information  Matched to the executable with unique identifiers  Age and signature

Full.pdb Files .pdb file as generated by the linker  Has all data streams  Types, locals, globals, statics, fpo, fixups, OMAP, source lines  Required to do full source level debugging  Files are very large  ntoskrnl.pdb is 8 MEG  Not shipped outside Microsoft

Public.pdb Files  Generated by a tool from the full.pdb  Certain data streams are removed  Types, locals, source lines  All function names and data required for stack traces are included  Globals, fpo  Files are much smaller  Ntoskrnl.pdb is 1 MEG  Public.pdb files are shipped on the support CD

Type Information  Type information is contained in one of the.pdb streams  Full encoding of every type definition used in a binary  Every field name of every structure  Debugger can query type definitions  Used for structure expansion in debugger

Other Symbols  Export Symbols  Debugger can use public exports as symbols  Used when no symbol file can be found  Map files  Only used on Win9x  Not supported by kd\ntsd\WinDBG

Diagnosing Bad Symbols  Debugger will give you a message when symbols are not found  !sym noisy  More verbose symbol load  !dh  !dh  Dumps image headers  Lm, lml, !drivers  More commands to look at images  Will add more documentation and debugger commands for this

Symbol Server  Symbol files can be indexed on a single machine  Use unique identifiers from the images and symbol files to find the symbols  New extension to the symbol handler  Point to one location which contains all your symbols  We will ship tools to build symbol servers  More documentation to come

Dump Files  What are dump files  Types of dump files  Kernel mode vs User mode  Full dumps vs. Mini dumps.  How to use dump files  32 bit vs 64 bit

Kernel Dump Files  Three types of dump files  Full (All NT versions)  Summary (win2k)  Mini (win2k)  Very useful to analyze software failures off-line  Can not be used to analyze hardware related problems

Full Kernel Dump File  In NT4, Win2k, Whistler  Stores all the physical memory in the machine  Dump is independent of virtual addresses or processes  Data saved to the page file  Dump fails if page file is not large enough  Page file must be on boot drive  Page file content is destroyed Can not restart OS from a kernel dump file Can not restart OS from a kernel dump file

Full Kernel Dump File  Advantages  Most complete dump available  When debugged, paged-in portions of user mode processes can be viewed  Disadvantages  Can be very time consuming to create

Summary Kernel Dump File  New in Windows 2000  Saves resident kernel pages only  Advantages  Quicker to generate at crash time  Provide enough information to analyze any kernel data structure  Disadvantages  Can not look at any user mode stack or data structures

Mini Kernel Dump Files  New in Windows 2000  64K in size  Contains minimum amount of information to analyze a fault  Context of the faulting thread  Stack of the faulting thread  Current thread and process data structures  Kernel module list  A few key MM data structures

Mini Kernel Dump Files  Advantages  Very quick to generate  Enabled by default by setup on Windows 2000 Professional  Enough to pin-point simple failures  Disadvantage  Not enough information to do full fault analysis  No Image sections Requires debugger to load images to get stack traces Requires debugger to load images to get stack traces

User Dump Files  Two types of dump files  Full (All NT version)  Mini (whistler)

Full User Dump File  Dump of the entire address space of the application  Generated automatically by Dr.Watson  Advantages  Lets you debug the fault off line  Disadvantages  Can be very large and long to generate

Mini User Dump File  Dump only contains basic information about the crash  All threads, with associated context and stack  List of modules  Advantages  Small and quick to create  Disadvantages  Can only debug simple failures (AVs)

Using Dump Files  Debugger can load ANY type of dump file  kd –z -y  kd –z -y  All debugger commands and extensions work identically to live debugging  Some limitations based on information available in the dump  Minidump files  Must specify –i  Must specify –i  Limited data in the dump file restricts which commands are valid

Using Dump Files  Advantages  Very simple to use with the debugger  Very useful for off-line analysis  Can get dump files from customers  Can send dump files to other developers  Disadvantages  No adapter hardware state is available  No access to live adapter registers  Cannot execute code  Minidumps don’t have much information

32 Bit Vs. 64 Bit Dump Files  Different file formats  Certain fields are extended to handle 64 bit addresses  64 bit dump files will get even bigger, as address space of machine gets bigger  The debugger just works with any dump file

Debugger Changes  Redesigned debugger internals  Simple Debugger UI Command line - kd, cdb, ntsd Command line - kd, cdb, ntsd Graphical - WinDBG Graphical - WinDBG  New debugger engine  Broader coverage of Windows OSes  Support for new transports  Much better testing  Windows group will use same debugger as external developers

Debugger Architecture The debuggers have been split into:  UI  Simple and replaceable front end that manages user input and output  Debugger engine  Handles all debugging activity  Exposes rich set of APIs to debugger UIs and extensions  Symbol Handler  Used by engine to get symbolic info

HOST, TARGET, REMOTE  HOST – Machine running the debugger directly connected to the TARGET  TARGET -- Machine being debugged  REMOTE – Machine remotely running the debugger, connecting to the HOST

HOST  The debugger binaries are run on the HOST  WinDBG, kd, ntsd, debugger engine  The debuggers binaries work and are tested on all versions of NT, starting with NT 4  Debugger could also run on Win9x  Not tested yet  We need to know if this is an issue

Kd.exe  Kernel debugger  Simple command line UI  Takes all commands and sends them to the debugger engine  Displays output from debugger engine  Merged i386kd, alphakd and ia64kd into one

Cdb.exe And Ntsd.exe  User mode debugger  Simple command line UI  Takes all commands and send them to the debugger engine  Displays output from debugger engine  Ntsd.exe is shipped in the OS  CDB.exe is only in the debugger package

WinDBG.exe  Simple Windows application  UI on top of the debugger engine  Collection of dialogs to get configuration information  A Set of windows to display information retrieved from the debugger engine

WinDBG.exe  WinDBG pre-release available  Download from our web site today  Debugger engine and command line 100% functional  Missing UI features  Workspace  More configuration options  UI polish

Debugger Engine  Single DLL, with built in support for:  All versions of NT, starting with NT 4  32 bit and 64 bit  User Mode and kernel mode  Live and Dump File debugging  Remoting  Exposes full symbolic information  All these features are transparent to the UI

User-Mode Debugging  For user-mode debugging:  HOST machine == TARGET machine  32 and 64 bit versions of debugger

User-Mode Debug Demo  Native IA64 debugging session

Kernel Debugging TARGETS  TARGET does not use any extra debugger binaries  Built-in to HAL and ntoskrnl  Multiple connection mediums  COM port  1394 (Whistler)  Local debugging (Whistler)

Kernel Debugging TARGETS  Support any TARGET OS from NT4 to Whistler  Detects version at runtime MP\UP, pro\svr\adv\dtc, NT4\Win2k\Whistler MP\UP, pro\svr\adv\dtc, NT4\Win2k\Whistler  Support any TARGET architecture  Detects at runtime IA64, X86, etc

Remote Debugging  Can connect remotely to a HOST debug session  REMOTE uses same binaries as the HOST  WinDBG, kd, ntsd  Support various protocols  Named pipes, sockets  Multiple REMOTE debuggers can connect to the host debugger  Must use the same protocol  Cannot remotely connect directly to TARGET

Remote Debugging Demo HOST: X86, Win2K, kd Serial cable TARGET: IA64 Whistler REMOTE: X86, Whistler WinDBG Named pipes

Remote Debugging Demo HOST: X86, Win2K, kd Serial cable TARGET: IA64 Whistler REMOTE: X86, Whistler WinDBG Named pipes

Type Information Support  Requires full.pdb  Will work with symbol files for your drivers or application  Debugger engine has built-in support for type information  New ‘dt’ debugger command  New debugger interface to expose type information to the UI

Debugger Extensions  Most important feature of the windows debugger  Lets you write specific code to analyze faults or dump data structures  Windows DEV team could not debug the OS without debugger extensions  We have written 100’s of these  We ship a subset of them with the debugger  !process, !thread, !vm, !pci, etc.

Old Debugger interfaces  Exposed a subset of the debugger functionality  Read and write memory Virtual, Physical, IO, MSR, PCI Virtual, Physical, IO, MSR, PCI  Expression evaluation  Symbol lookup  Incompatible between ntsd and WinDBG

New Debugger Interfaces  Debugger engine exposes the new debugger interface  Complete set of interfaces  Object based, yet still very simple to use  WinDBG is implemented using these new interfaces  Could easily rewrite a UI to replace WinDBG  Very simple extensions can be written to a subset of the interfaces

New Debugger Interfaces  Read and write memory  Breakpoint  Execution control  Expression evaluator  Full symbol and TYPE support  Source code support

Sample Debugger Extension  Tool to remotely connect to a debug session 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 extensions  All new interfaces use 64 bit addresses  Debugger extensions should always use 64 bit addresses  32 bit addresses are SIGN-EXTENDED  Must handle this correctly in extension DLLs

Writing Debugger Extensions  New interfaces are not provided in the current debugger package  Future release will have headers, libs, docs and samples  NT 4 and win2k extension interfaces can still be used today  Write debugger extensions – they will make debugging a lot more easy

Call To Action  Try the new debugger !   Read the documentation. Learning more about the tools will make it easier to debug problems.  For feedback (report bugs or missing featrures)  For support or help with the debugger