Debugging ReactOS

This page describes different methods of debugging ReactOS and the steps necessary to debug ReactOS.

= Introduction =

To be able to help ReactOS development, whether this be participating in the development of the source code or taking part in crucial testing, you are going to need knowledge of how to generate useful debug logs.

Useful debug logs are essential pieces of information which the developer needs to quickly pinpoint and identify exactly what the operating system is doing. Many people know how to get default debug output from the operating system, but this is generally not particularly useful for locating problems, especially bugs.

This article aims to give users knowledge not only on how to generate a debug log, but on how to generate a useful debug log which can be used directly to assess what the operating system is doing.

= Available debugging methods =

There are various methods to debug ReactOS, some require more knowledge than others. These are listed below.

== Debugging through text messages ==

This is the easiest method for receiving debug information from ReactOS.

=== Serial Port ===

The serial port is the most common method used for receiving debug messages from ReactOS.

The method used for receiving data from the serial port depends on whether you run ReactOS in a virtual machine or on a real computer.

If you plan to use virtual machine, you might want to consider using [[Com0com]] instead of named pipe for connecting with virtual serial port.

==== Virtual machines ====

How to handle serial output from virtual machines can be found on the VM specific debugging pages:

* [[QEMU#Grabbing_debug_messages|QEMU]]

* [[VirtualBox#Getting_debug_output|VirtualBox]]

* [[VMware#Getting_debug_output|VMware]]

==== Real computer: Physical serial cable ====

You will need a [[physical serial cable]] if you want to receive debug messages from a real computer through the serial port.

This method also requires two computers (one on which you test ReactOS and another one for receiving the debug messages).

The cable needed for this debugging method is a ''Null-Modem serial cable''. You should find it in many computer shops for less than 10 dollars.

If you don't have one ready, you can also build one like this:

DTE1_______________________________________________DTE 2

9pol 25pol (female)__________________________25pol 9pol (female)

5 7 ---GND---------------------GND------- 7 5

2 3 ---RxD--------. ,----------RxD------- 3 2

X

3 2 ---TxD--------' `----------TxD------- 2 3

7 4 ---RTS--------. ,----------RTS------- 4 7

X

8 5 ---CTS--------' `----------CTS------- 5 8

4 20 ---DTR--------. ,----------DTR------- 20 4

X

6 6 ---DSR--o-----' `-------o--DSR------- 6 6

| |

1 8 ---DCD--' `--DCD------- 8 1

Connect the cable to the first serial port of both computers.

Then use a Terminal application like [http://www.chiark.greenend.org.uk/~sgtatham/putty/ PuTTY] or Windows HyperTerminal on the computer for receiving the debug messages.

Set it up to listen to the first serial port (COM1 [3F8/IRQ4]) and a baud rate of 115200.

After that, boot ''ReactOS (Debug)'' on the test computer and you should receive debug messages. If this doesn't work, check your hardware and your freeldr.ini configuration.

=== Debug text output to file ===

(Since r43333.) Choose ''ReactOS (Log file)'' in the boot menu. The debug messages will go to a file called ''debug.log''.

This method has some limitations. Fatal system error messages will not appear in the log file.

=== Debug text output to screen ===

Edit freeldr.ini to contain an entry like the following:

<pre>

[ReactOS_Debug]

BootType=ReactOS

SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOS

Options=/DEBUG /DEBUGPORT=SCREEN /SOS

</pre>

=== Changing the BAUD rate ===

If you think that 115200 is way too slow and your serial connection supports higher speeds, like virtual com ports do, you can change it.

1. Open the freeldr.ini in the reactos installation's root folder.

2. Locate the "[ReactOS_Debug]" section

3. Change setting to something like "/BAUDRATE=921600" (tested to work with hyperterminal and putty)

4. Save file.

5. Change your terminals BAUD rate.

== KDBG ==

See [[kdbg|kdbg command reference]] for more information about the built-in kernel debugger.

== GDB ==

To use GDB as a kernel debugger, see [[GDB]].

Needed Items:

*GDB (included in ReactOS [[Build Environment]])

*[[QEMU]]

Start QEMU as you normally would, but add the following command line parameters:

-s -S

This is done so that QEMU starts in the STOPPED state, and allow you to connect using GDB.

Now it's time to get GDB off the ground.

* (Assuming you are in the RosBE command line), enter “gdb” to start GDB.

* Enter “file ./output-i386/ntoskrnl/ntoskrnl.exe” to tell GDB where to load information about the kernel.

* Enter “set disassembly-flavor intel” if you prefer Intel syntax.

* Enter “target remote localhost:1234” to connect GDB to QEMU.

* Enter “c” (for “continue“) to have GDB instruct QEMU to start/continue execution of the emulation.

* To manually pause execution, make sure your GDB window has focus and simply enter <CTRL>+<C>

== WinDbg ==

{{Main|WinDBG}}

WinDbg support is still limited. On the x86 build you need a Windows 2003 version of kdcom.dll to make it work. You also need to compile with WINKD=1 switch. On reactos64 builds it's the main debugging method and already works quite well with the current x64 version of kdcom.dll.

= Generating even more output =

In order to get meaningful debug output it is sometimes necessary to enable extra verbosity.

== Turning on verbosity at compile time ==

===ReactOS Style===

Nearly all ReactOS modules use the built in "ReactOS style" debugging functionality. This style is characterized by:

*Verbosity level is usually defined per file.

*Only 2 message levels:

**always enabled (DPRINT1)

**only enabled when NDEBUG is not defined (DPRINT)

Files that follow this style can easily be spotted by this code:

#define NDEBUG

#include <debug.h>

To enable full verbosity just comment out the "#define NDEBUG", and remember to uncomment it when submitting patches.

==== Adding own debug messages ====

Be sure that you included debug.h

#include <debug.h>

And use DPRINT / DPRINT1, both work like <tt>printf</tt>, but have some [[DPRINT codes|different codes]].