WinDbg Tutorial

From ReactOS Wiki
Revision as of 14:44, 28 August 2015 by Hbelusca (talk | contribs)
Jump to: navigation, search

WinDbg Quick-Start Guide

This is work in progress and probably has a lot of rough edges. Feel free to phrase more clearly or explain in more detail (preferably by linking to the appropriate pages)



  1. Prepare ReactOS (Method 1)
    • build the kernel: nmake ntoskrnl
    • build kdcom.dll: nmake kdcom . You may prefer to use the one from Windows 2003.
    • build any other modules you want to work on. I prefer having at least ntdll, and kernel32. nmake ntdll kernel32
    • grab a trunk build. Usually the latest from - or build one yourself
    • if you can mount or otherwise access your target machine's file system, you can simply run first (and second, if you don't want to do any debugging there) stage setup, then replace the files on the target disk with the ones you built above
    • alternatively, replace the corresponding files in the ISO
  2. Prepare RectOS (Method 2): build the whole MSVC bootcd: nmake bootcd. Note that some things might not work with a MSVC bootcd.
  3. Now start WinDbg, and choose File->Kernel Debug (Ctrl+K)
  4. Set up WinDbg according to how your target outputs its debug messages:
    • to use a Pipe, check the Pipe option, set Port to \\.\Pipe\TheNameOfYourPipe
    • to use a com0com serial port, set Port to the name of the port, such as \\.\CNCA0
    • to use a physical serial port, set Baud Rate to 115200 and Port to the name of the port, such as \\.\COM1
  5. Boot up the target, and select the ReactOS (Debug) boot menu entry. Debug mode is default if you start 1st stage setup.
  6. Enjoy debugging with WinDbg. Some tips:
    • break in with Tab+K works, just like with kdbg. This is useful since ROS sometimes doesn't react to WinDbg's break-in
    • kernel breakpoints mostly work. In userspace they're not always too reliable. Adding __debugbreak(); in the source makes sure you'll break in
    • NOTE: Since revision 68841 deferred breakpoints work.
    • with an MSVC-built ntdll and an MSVC-built xxx.dll, you should get complete backtraces from the kernel back to xxx.dll
    • check out the WinDbg page for some useful commands. The help is also really good