User:Oldman/A layman's guide/How to get a debug log

This guide will show you how to get a debug log, using the Debug mode in real hardware and with a virtual machine using com0com (Windows) or tty0tty (unix), using the built in ReactOS debugger. The difference with the other debug modes is explained in Variations

reactos-bootcd = type of ISO (boot for installing, live for running OS without installing).

0.4.7 = The number of the next release. The number changes every time a release branch is created, so when the 0.4.7 was branched for release, the number on the daily/latest ISOs became 0.4.8. And when the 0.4.8 was branched for release, the number on the daily/latest ISOs became 0.4.9. Now the 0.4.9 is branched, the number on the daily/lastest ISOs are numbered 0.4.10.

For normal users, the ISOs built with gcc are the ones to go for. You may need a copy of MSVC to make full use of the msvc-win builds.

Stages of the installation of ReactOS

It may be helpful to understand the stages of the installation of ReactOS.

First stage:

When the installation CD (bootcd) is run, the bootloader asks you to press any key to install (real hardware)

The OS will first load itself into memory, then you are presented with the Language setup window, then 2 more windows, then Device settings window, then choose Hard drive partition window, then format window, then confirm format window. then choose directory window. then 2 more windows, then bootloader choice window. In the last window you are asked to remove media and press Enter. The computer now reboots.

Second stage:

The bootloader shows the Boot options choice window, then boots, loads device drivers, then shows the setup window, after that there are more configuration windows (when testing you can press Enter at all these windows), before it finally reboots.

Third stage:

It now boots up into desktop and displays the driver install wizard, if it finds any hardware without a driver.

NOTE:

Debug output only starts when the OS is loaded into memory, but just before it loads the drivers.

When installing (First stage), debug output is turned on by default and can only be captured through a null modem serial cable connect to a second computer (see also this section), but once ReactOS is installed (Second stage and normal usage), you will have a choice of how to record debug output, from the boot menu. See [1] in Screenshots section below.

Hardware requirements:

A test computer with a serial port.

A second computer with a serial port and Putty installed (or similar app).

Setting up Putty.

There are some vital settings in Putty, which need to be set, so that Putty can capture a debug log.
In putty go to Category and select Session, then set the following inputs to these values:
Serial line = COM1Speed = 115200Connection type = Serial

Back to Category and select Logging, in Session logging: check All session output. Note where Putty saves the log file and change if required; use the Browse button for the destination folder.

See in Screenshots[2] [3] below for visual information.

Save the above changes in putty, with a name of your choice, in Saved Sessions, then use the Save button. It can then be loaded the next time you use Putty, by using the Load button. Note: logging is started by using the Open button.

The ReactOS debugger

The ReactOS debugger has some commands that can be used from the command line; all of the commands are typed into the ReactOS test computer, but will be viewed in the terminal window (i.e putty) on the second computer. To enter a command, press the hotkey combination of Tab+k, which halts the system and gives you the command prompt which looks like this: kdb:> where you can then enter the command.

Commands:

Tab+k - this command halts the system so you can enter commands into the debugger.
bt - this command gives a backtrace; use it when ROS enters the debugger (see below).
cont - this is short for continue.
set condition * first always - this command tells ROS to enter the debugger on the first exception.

The following is an example of when ROS enters the debugger (see also in the [4] screenshot below):
Entered debugger on last-chance exception (Exception Code: 0xc0000001) (Unknown/User defined exception)kdb>

Getting a backtrace:

By looking in the Putty window, you will see when ROS enters the debugger, when that happens, you need to enter bt at the command prompt, like so:
kdb:> bt[4] and press enter on the keyboard.
You may see this
--- Press q to abort, any other key to continue ---[5]
If you do see it, then just press any key other than q, it may show again, just repeat until you are back at the command prompt of kdb:>

Getting a more detailed backtrace:

When you see debug info streaming into putty [Note], then press the hotkey combination of Tab+k on your keyboard, then type set condition * first always at the command prompt and press enter on the keyboard, then type cont[6] and press enter on the keyboard. Setting the condition to first always, will make ReactOS enter the debugger on every exception, which it will do many times, and each time you will have to type bt then cont.

Note: If you are testing an app, then it is better to wait until you are ready to run the app, before setting the condition to first always, else you could be overwhelmed with ReactOS entering the debugger.

No working keyboard!

Currently (Jan 2015) usb support is problematic, so your keyboard may not work! If you have found that your usb keyboard does not work with ReactOS, and ReactOS bsods at or before the first input window in the installation process, but after it is running in memory, you should still be able to get a debug log by using a livecd debug version (example: reactos-livecd-0.4.7-dev-575-g48b2714-x86-gcc-lin-rel.7z). The livecd versions currently default to Debug mode, so when it boots, it will output debug info to the serial port, but you will not be able to get a backtrace!

Advice:

Do not use Tab+k and bt to get a backtrace, when ReactOS does not automatically enter the debugger! If you think by doing so, you will get some more useful information for the dev's to work with (which I have done in the past), you will not, it is a waste of time, the backtrace is of no value!

Putty names the file putty.log, it would be a good idea to re-name it, because the next time that putty is run, it will over-write the file called "putty.log". I use something descriptive, in this format "app name - ReactOS revision number", for example "gimp-1.0.4 [0.4.7-dev-575-g48b2714]".

TIP:
If you find that when you use the test computer's keyboard to enter commands, nothing appears at the Command Prompt on the second (receiving) computer, then type the command on the second computer's keyboard, you then should see what you type appear at the Command Prompt.

Variations

RosDbg - This is only useful when ReactOS is compiled with a Microsoft compiler, which adds extra debugging code into ReactOS, which can output extra debug info. In use, the difference from Debug, is in the keyboard input, where you can only use Tab+k on the ReactOS test computer, all other keyboard input is via the logging computer's keyboard.

Screen - In this mode, debug information is written to the screen and you will have to take photos to be able to submit the information in a JIRA Issue. Any keyboard input is done on the ReactOS test computer keyboard. The instructions for Debug mode also apply to Screen mode.

Log file - This writes all debug output to a debug.log at C:\reactos\, on the ReactOS test computer's hard drive. Any keyboard input is done on the ReactOS test computer keyboard. You may, also need to use a Linux livecd to be able to recover the log file from the test computer.

Getting a debug log - Screenshots

[1] ReactOS boot options menu.

[2] PuTTY Configuration - Session

[3] PuTTY Configuration - Logging

[4] Ros in the debugger showing bt entered at the command prompt.

[5] You may see this after entering bt and after the debug info has stopped.

[6] The debugger has been entered manually and shows set condition * first always typed at the command prompt and cont.

[7] If you see this, type o as shown and press enter on your keyboard.

Getting debug information in the first stage of installing ReactOS without needing a serial port

To get debug information without a serial port and/or null modem cable in the first stage of the installation of ReactOS, you will need to run ReactOS in Debug to screen mode, by modifying a file called txtsetup.sif. There is no problem in the second stage of installation of reactOS, because there is a window which gives you a choice of modes that you can run in, you can then choose either Screen or Log File (which writes the debug log to C:\reactos).

Finding txtsetup.sif within the source code

If you compile your own source, then you will find txtsetup.sif in your source directory/folder, in \reactos\boot\bootdata\txtsetup.sif.
Example: E:\ReactOS_Development\Source\reactos\boot\bootdata\txtsetup.sif (see next image).

Modifying txtsetup.sif

Open txtsetup.sif in a text editor and scroll down to line 208 (132*) or thereabouts and find the section [SetupData]. (see image below) * older versions before 0.4.12-dev.

This shows the part of txtsetup.sif to alter, shown here in a text editor.

The altered version of txtsetup.sif

and comment out the line DbgOsLoadOptions = "/NOGUIBOOT /KDSERIAL /DEBUGPORT=COM1 /FIRSTCHANCE" by putting a semi-colon (;) at the front, then remove the semi-colon from the front of the line DbgOsLoadOptions = "/SOS /DEBUGPORT=SCREEN" as shown in the second image, just above, then save and compile.

Getting a debug log from VirtualBox

This section covers a simple VirtualBox setup using com0com or tty0tty as a virtual null modem cable to connect to Putty; all running on the same computer, no need for a real null modem cable and a second computer.

VirtualBox for Windows, Unix, can be down loaded from https://www.virtualbox.org/ (plus installation help, should you need it), it is also available for Unix through your package manager.

Note that for Unix, you will need to have the development package and the kernel source or header files installed.

Install VirtualBox for your operating system, then start it. You will first need to create a virtual machine to install ReactOS into; this is done by clicking on the blue New button. In the first setup window you will need to give it a name in Name:, then set it to Microsoft Windows in Type: and then set it to, either WindowsXP(32bit) or Windows 2003(32 bit) in Version:, then for a simple setup, you can accept all the defaults in all the other setup windows (I alter just one item, I select VHD (Virtual Hard Disk) in the last setup window). There is no need to install ReactOS into the virtual machine just yet, if you want to log the debug output from the start of an installation.

Note: You may find it helpful if you name the virtual machine with a descriptive name, such as 0.4.7-dev-582-g74cc915 or ReactOS-g74cc915 or ROS-0.4.6, especially if you intend doing some serious debugging and having several virtual machines with different versions of ReactOS installed.

In the setup window you will see CNCA0 and CNCB0 which are the newly created virtual ports [8] (If you should ever have the need to add more virtual ports, then the next pair will be CNCA1 and CNCB1). The CNCA0 is used in the Path/Address: in VirtualBox virtual machine serial configuration [10] in this format \\.\CNCA0 and the CNCB0 is used in the Serial line in the Putty serial configuration [11a] just as it is.

The com0com virtual ports process remains until you use the Remove button in the setup app, to remove them.

Unix - tty0tty

Unpack the package tty0tty-1.2tgz to a folder; my OS was able to unpack it to /tty0tty-1.2/, just by clicking on the package.

It requires compiling, so navigate to the directory /tty0tty-1.2/pts (cd /tty0tty-1.2/pts) and open a terminal window (right click - Window - Terminal here). At the command prompt type make and shortly you should have an executable file in the pts folder.
Then still within the pts folder/directory, type ./tty0tty at the command prompt to run [8b]. The output could be

(/dev/pts/1) <=> (/dev/pts/2)

or

(/dev/pts/2) <=> (/dev/pts/3)

it may vary. But whatever the left side is, such as /dev/pts/2 will be entered into the Path/Address: in the VirtualBox virtual machine's serial configuration [10] and whatever the right side is, such as /dev/pts/3 will be entered into the Serial line in the Putty Serial configuration, instead of the default com or tty [11b].

I end the tty0tty virtual ports process, by using the Ctrl - c combination, but I would expect it to terminate when the terminal window is closed.

There is another folder in the directory /tty0tty-1.2/module which also requires compiling. This will, when run, create several pairs of virtual ports, which remain until the OS is re-installed or upgraded. I have not used it or included it within this tutorial.

Testing com0com and tty0tty

To test if it works, configure one instance of putty with CNCA0 in Windows or /dev/pts/2 in Unix and another instance of putty with CNCB0 in Windows or /dev/pts/3 in Unix, then run both Windows Puttys or both Unix Puttys and type into each terminal window. If the input from each terminal window is shown in the other terminal window (what is typed into Putty No1 should display in Putty No2, also what is typed into Putty No2 should be displayed in Putty No1), then you have a working virtual null modem cable.

Now you can run your VirtualBox virtual machine and install ReactOS.

Note: When you run your virtual machine with an installed OS, then make sure that there is no bootable media in any of your external drives (floppy, USB or CD/DVD), else the VirtualBox virtual machine will boot it instead of the installed OS.

Screenshots

[8a] Setup window for com0com.

[8b] ‎Starting tty0tty.

[9] This is the main window in VirtualBox. It looks the same in both Unix and Windows. Use the New button to create a new virtual machine, the Settings button to add or alter settings (select the virtual machine first) and the Start button starts the selected virtual machine.

[10] This is the Serial port settings window in VirtualBox. In the Path/Address: it is \\.\CNCA0 for com0com in Windows and /dev/pts/2 for tty0tty in Unix. Depending on the version of VirtualBox, where you see Path/Address: you could see Port/File Path: instead.

[11a] Windows com0com Putty Serial configuration.

[11b] Unix tty0tty Putty Serial configuration.

Software crash reports

If some software that you are trying to use or are using, crashes, then you should find a crash report file on the Desktop. I would advise you to rename it as soon as possible, so that you know what software it is for and to prevent it from being over written.