本页面描述了不同的调试方法ReactOS和调试ReactOS所需的步骤。

能够帮助ReactOS发展,是否这是参与开发的源代码或参加重要的测试,你需要了解如何生成有用的调试日志。

有用的调试日志的信息至关重要,开发者需要快速精确定位和识别操作系统做什么。 很多人知道如何从操作系统默认调试输出,但这通常不是特别有用的定位问题,尤其是bug。

本文旨在给用户知识不仅在如何生成一个调试日志,但在如何生成一个有用的调试日志,可以直接用来评估操作系统做什么。

可用的调试方法

ReactOS调试方法有很多种,有些需要比别人更多的知识。 下面列出了这些。

调试通过短信

这是最简单的方法从ReactOS接收调试信息。

串行端口

串口是最常见的方法用于接收从ReactOS调试消息。 从串口接收数据使用的方法取决于你在虚拟机中运行ReactOS或一个真正的计算机。 如果您计划使用虚拟机,您可能需要考虑使用Com0com而不是命名管道与虚拟串行端口连接。

虚拟机

如何处理串行输出从VM虚拟机可以找到具体的调试页面:

  • QEMU

  • VirtualBox

  • VMware

真正的计算机:物理串行电缆

你 需要一个物理串行电缆如果你想接收调试消息从一个真正的计算机通过串行端口。 这种方法也需要两台电脑(一个你测试ReactOS,另一个用于接收调试消息)。 ReactOS测试计算机必须有一个串行端口。 注意,usb串口适配器是不合适的,但是PCI系列卡应该工作。

这种调试方法所需的电缆空调制解调器串行电缆。 你应该找到它在许多电脑商店不到10美元。 如果你没有准备好,你也可以构建一个:

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

将电缆连接到第一个串口的电脑。

然后使用一个终端应用程序腻子或Windows终端程序的计算机接收调试消息。 设置它听第一个串口(COM1[3 f8 / IRQ4])和波特率为115200。

在那之后,引导ReactOS(调试)在测试电脑上,你应该接收调试消息。 如果这不起作用,检查你的硬件和freeldr。 ini配置。

串行硬件可以是棘手的,但要持之以恒。 有一些事情要记住:

  • 计划连接终端设备和DCE,性别都有。 知道哪个串口(1或2)你在每台计算机连接。

  • 如果使用PCI系列卡片,它可能需要通过串行端口地址到内核(详情见下文)。

  • 得到合适的零调制解调器。 有一些方法可以使他们,并不是所有的都是相同的。

  • 尽可能使用短电缆。

  • 使用串行终端程序,如超级终端或小型计算机观察远程计算机。 如果你看不到数据你能认出,那是错误的。

  • GDB远程命令开始和结尾;美元。 你就可以认出他们来。

  • 注意:使用这些设置(在超级终端)

    • 每秒位数:115200

    • 数据位:8

    • 奇偶校验:没有

    • 停止位:1

    • 流控制:硬件

  • 注意:一些老的bios可能有115200波特率问题。 测试电脑上尝试而不是9600 freeldr通过编辑文件。 ini和使用参数/波特率= 9600。 当然你也必须改变波特率9600收到电脑。

如何开始在Linux上串行终端

  • 首先你需要安装终端程序,基于rpm的系统是在uucp-V.V.V.rpm包中。

    • 百胜基于系统运行:sudo yum - y uucp安装

    • 恰当的基于系统运行:sudo apt-get安装uucp

  • 有些Linux发行版需要下一个变化所属文件:添加用户(或者)集团dialout

  • 然后运行:

sudo cu -s 115200 --parity=none -l /dev/ttyS0

在这里

  • /dev/ttyS0是你的COM端口名称,你可以找到它的名字通过阅读dmesg | grep tty命令的输出。

  • “- e - o”键可以用来代替——平价=没有

故障排除

在“使用线”/“拒绝访问”错误:

user1~ # cu -s 115200 --parity=none -l /dev/ttyS4cu: open (/dev/ttyS4): Permission denied
cu: /dev/ttyS4: Line in use
user1~ #

确保你包括你user1dialout组。

串行终端通过FreeBSD

在FreeBSD预装。

运行在控制台:

sudo cu -s 115200 -e -o -t -l /dev/cuau0

这里/dev/cuau0是你的串口(COM)设备名称,找到正确的名称你的COM端口dmesg命令的输出。 和其他键:

  • “- e - o选项一起意味着无分区

  • - l /dev/Xdev指定COM设备名称

  • - t表示连接拨号线路连接到主机上(不确定是这个密钥需要)。

并收集日志输出到一个文件中发送,运行此脚本:

DATE=`date +"%F_%H%M%S"`screen -dmS ROSlogger script MyMachine1-ROS-debug-$DATE.log sudo cu -s 115200 -e -o -t -l /dev/cuau0

它将日志写入文件名为MyMachine1-ROS-debug至日期。 日志,这里美元日期将脚本的时候就开始了。 你可以改变这里MyMachine1您的机器的名字。

调试文本输出到文件

选择ReactOS(日志文件)在启动菜单。 将一个文件叫做调试消息debug.log。 这种方法有一定的局限性。 致命的系统错误信息不会出现在日志文件中。 将输出重定向到另一个文件,编辑在freeldr.ini内核参数/ com文件。 例如:

Options=/DEBUG /DEBUGPORT=FILE:\Device\Harddisk0\Partition1\debug.log /SOS

或者:

Options=/DEBUG /DEBUGPORT=FILE:\ArcName\multi(0)disk(0)fdisk(0)\debug.log /SOS

调试文本输出到屏幕上

选择ReactOS(屏幕)在启动菜单。

或编辑freeldr。 ini包含一个条目如下:

[ReactOS_Debug]BootType=Windows2003SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOSOptions=/DEBUG /DEBUGPORT=SCREEN /SOS


高级选项:调试调试日志记录器

有时事情出错了,就必要调试调试日志,说屏幕日志记录器。 要做到这一点,它是可能的 打开多个日志记录器,通过指定它内核命令行选项如下: 编辑freeldr。 ini包含一个条目如下:

[ReactOS_Debug2]BootType=Windows2003SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOSOptions=/DEBUG /DEBUGPORT=SCREEN /DEBUGPORT=COM1 /SOS

改变波特率

如果你认为115200是你太慢,串行连接支持更高的速度,像虚拟com端口一样,你可以改变它。 注意,一些bios与115200年旧的测试电脑可能有问题。 在这种情况下,使用9600。

1。 打开freeldr。 ini reactos安装的根文件夹。

2。 定位“[ReactOS_Debug]”一节

3所示。 设置更改为类似“/波特率= 921600”(使用超级终端测试和油灰)

4所示。 保存文件。

5。 改变你的终端波特率。

改变串行端口地址

编辑内核参数/ COM = COM。 这可能是必要的,如果您使用一个PCI /作为PCIe / PCMCIA / ExpressCard系列卡在真实硬件。 这通常是用于笔记本电脑没有内置串行端口。 例如:

Options=/DEBUG /DEBUGPORT=COM:0xCC00 /BAUDRATE=115200 /SOS

参见: 铬操作系统‎串行调试HOWTO如何确定插入的I / O地址扩展卡。

注意:Reactos(!)不支持MMIO-based(现代)串行扩展卡。

KDBG

看到kdbg命令参考关于内置的内核调试器的更多信息。

广东发展银行

作为一个内核调试器,使用GDB广东发展银行

所需物品:

像平时一样开始QEMU,但添加以下命令行参数:

-s -S

这样做的好处是,QEMU开始处于停止状态,并使用GDB允许您连接。 现在是时候让GDB。

  • (假设你在RosBE命令行),进入“gdb启动gdb。

  • 进入“文件/ output-i386 / ntoskrnl / ntoskrnl。。 exe”告诉GDB加载内核的信息。

  • 进入“设置disassembly-flavor英特尔”如果你喜欢英特尔语法。

  • 输入“目标远程localhost:1234”连接GDB QEMU。

  • “继续”进入“c”(),GDB指示QEMU启动/继续执行仿真。

  • 手动暂停执行,确保你的GDB窗口焦点,只需输入< CTRL > + < C >

WinDbg

主要文章: WinDBG

要 充分利用WinDBG,您需要编译reactos与MSVC pdb符号。 MSVC构建这是默认调试风格。 如果你想使用gcc构建,您需要编译WINKD选项设置为TRUE(可以使用CMake-GUI和编辑配置,然后重新配置后的价值,或者你可以编辑选项的 默认值。 cmake文件) 另一种可能性是取代ntoskrnl。 exe和kdcom。 dll WINKD = TRUE选项。 你也可以取代kdcom。 dll的一个Windows 2003,更多的功能,如连接和磨合,不与reactos的kdcom atm正常工作。

生成更多的输出

为了得到有意义的调试输出有时需要启用额外的冗长。

在编译时打开冗长

ReactOS风格

几乎所有ReactOS模块使用内置的“ReactOS风格”调试功能。 这种风格的特点是:

  • 冗长的水平通常是定义每个文件。

  • 只有2消息级别:

    • 总是启用(DPRINT1)

    • 只有NDEBUG没有定义时启用(DPRINT)

文件,按照这种风格可以很容易地发现这段代码:

 #define NDEBUG
 #include <debug.h>

启用完整冗长就注释掉“# define NDEBUG”,并记住取消时提交补丁。

添加自己的调试消息

你要确信你包括debug.h

 #include <debug.h>

和使用DPRINT / DPRINT1工作printf,但有一些不同的编码

葡萄酒的风格

样品线启用调试频道在usermode应用程序中,在文件:

启动/ bootdata / hivesys.inf

; Debug channels
HKLM,"SYSTEM\CurrentControlSet\Control\Session Manager\Environment","DEBUGCHANNEL",0x00020000,"+ole,+rpc"

在运行时打开冗长

打开调试冗长的最简单的方法在任何特定组件是使用DEBUGCHANNEL环境变量。 例如,要获取所有调试消息从MSI,只是在CMD运行:

set DEBUGCHANNEL=+msi

然后,运行这个程序你想测试。 您可以添加调试信息从多个组件,例如:

set DEBUGCHANNEL=+msi,+rpc,+ole

你可以找到一个debuggable组件的完整列表在这里

后关闭CMD,调试冗长会改变违约。

<描述如何设置冗长的细节水平,从所有组件打开调试。>

闯入内置的内核调试器

Bugchecks发生在操作系统不能操作安全,避免腐蚀数据,它停止操作。 通常这将抛出一个蓝色屏幕的死亡,但是如果你有激活内核调试器,它会将你带到这个提示给你探索系统状态的访问。 默认情况下ReactOS调试构建集成的内核调试器(kdbg启用)。 发布版本没有这个功能启用,只显示一个蓝色屏幕。

有两种方式迫使bugcheck,每一个使用一个不同的方法:

动态

如果你有一个调试版本,想停止系统对于任何给定的原因和进入内核调试器,您可以从键盘迫使bugcheck只需键入:选项卡+K


记住kdbg通过串口输出出去,但它默认接收从键盘输入。

允许输入通过串口与ReactOS开始启动选项”ReactOS(RosDbg) “或添加命令/ KDSERIAL freeldr。 ini引导选项。

打破在用户模式的例外

为每个类型的异常被KDB KDB应该进去的时候你可以设置条件分别为第一和最后的机会。 可能的设置条件从来没有,umode,kmode总是

  • 从来没有:kdbg不会进入时例外

  • umode:kdbg时将进入异常在usermode长大

  • kmode异常时输入:kdbg将在内核模式长大

  • 总是kdbg将进入每一个例外

改变条件进入KDB在所有例外“总是”(默认是“kmode”),进入调试器和类型:

set condition * first always

输入“租”继续正常执行。

静态

这是非常有用的,当你想要停止操作系统当它到达特定区域代码您可以调试。 这是特别有用,因为你可以立即返回跟踪看到代码流之前bugcheck被迫。

这是通过使用KeBugCheck()或断言()的代码。

生成回溯

为了生成一个回溯必须打入KDBG提示。

进入“电信”和打击返回,您应该会看到类似于下面的:

 (drivers\filesystems\vfat\rw.c:809) <\ReactOS\system32\kernel32.dll>
 Entered debugger on embedded INT3 at 0x0008:0x800935f2.
 kdb:> bt
 Eip:
 <ntoskrnl.exe:935f3 (lib\rtl\i386\debug_asm.S:31 (DbgBreakPoint@0))>
 Frames:
 <vfatfs.sys:97de (drivers/filesystems/vfat/misc.c:111 (VfatDispatchRequest))>
 <vfatfs.sys:9b25 (drivers/filesystems/vfat/misc.c:167 (VfatBuildRequest))>
 <ntoskrnl.exe:3ab23 (ntoskrnl/io/iomgr/irp.c:1088 (IofCallDriver))>
 <ntoskrnl.exe:36206 (ntoskrnl/io/iomgr/iofunc.c:686 (IoSynchronousPageWrite))>
 <ntoskrnl.exe:59daa (ntoskrnl/mm/section.c:6330 (MmspWriteDataSectionPages))>
 <ntoskrnl.exe:244c6 (ntoskrnl/ex/work.c:162 (ExpWorkerThreadEntryPoint))>
 <ntoskrnl.exe:70e90 (ntoskrnl/ps/thread.c:134 (PspSystemThreadStartup))>
 <ntoskrnl.exe:7b142 (ntoskrnl\ke\i386\ctxswitch.S:258 (KiThreadStartup@156))>
 kdb:>

bt命令将显示当前连接的线程的回溯,所以可能需要使用螺纹连接的命令,请参考kdbg手册获得更多细节。

这个更详细地检查,我们可以看到bugcheck发生通过INT3操作然后把我们变成kdb。 下一行向我们展示了Eip的指令指针,这表明之前的最后一个地址系统停止。

后从帧。 这是我们回溯生成的重要组成部分,它包含所有的函数地址bugcheck积聚。 这是crutial信息开发人员需要了解codeflow bugcheck之前。

翻译地址

偶尔,终有一天当你需要手动翻译地址。 当没有启用kdbg和bugcheck发生时,您将看到一个堆栈跟踪类似如下:

(subsystems\win32\csrss\win32csr\conio.c:1101) Console_Api Ctrl-C 
*** Fatal System Error: 0x00000001
                       (0x80079279,0x00000000,0x0000FFFF,0x00000000) 
<\SystemRoot\System32\NTOSKRNL.EXE: 29bb>
<\SystemRoot\System32\HAL.DLL: 4749>
<\SystemRoot\System32\NTOSKRNL.EXE: 54cb4>
<\SystemRoot\System32\NTOSKRNL.EXE: 582bf>
<\SystemRoot\System32\NTOSKRNL.EXE: 583fd>
<\SystemRoot\System32\NTOSKRNL.EXE: 89956>
<\SystemRoot\system32\drivers\videoprt.sys: 2417>
<\SystemRoot\system32\drivers\vbemp.sys: 17f5>
<\SystemRoot\system32\drivers\vbemp.sys: 19cf>
<\SystemRoot\system32\drivers\videoprt.sys: 1c48>
<\SystemRoot\System32\NTOSKRNL.EXE: 34c17>
<\SystemRoot\System32\NTOSKRNL.EXE: 21e0>
<\SystemRoot\System32\NTOSKRNL.EXE: 2908>
<\SystemRoot\System32\NTOSKRNL.EXE: 29bb>
<\SystemRoot\System32\NTOSKRNL.EXE: 85fa8>

正如你所看到的,这在很大程度上是一样的信息当kdbg发出“转基因”命令。 然而,这里的问题是,只有地址。 作为每个人的构建这些地址是不同的,这些信息是无用的对于那些试图跟随哪些事件发生在对bugcheck。

这里的解决方案是把地址翻译成人类可读的函数名。 这是通过一个工具叫“raddr2line”这是一个修改版本的Unix的addr2line工具。 这个工具会把地址给它翻译成文件名和行号。 它通过使用调试信息的可执行文件关联的地址和人类友好的信息输出到控制台。 此信息可以粘贴到上面的调试日志与地址为开发人员提供一个详细的堆栈跟踪。

raddr2line包含在Reactos构建环境。 调用它以下列方式:

raddr2line <file> <address>

所以在底部地址在上面的堆栈跟踪:

C:\Users\Ged\MyFiles\ReactOS\clean_source>raddr2line ntoskrnl.exe 85fa8

C:\Users\Ged\MyFiles\ReactOS\clean_source\output-i386\ntoskrnl\ntoskrnl.exe
obj-i386\ntoskrnl\ex\zw.S:253 (ZwClearEvent)

我们可以看到,地址转换为0 x85fa8是253行文件ntoskrnl \ \ zw交货。 (这将不同如果你试穿构建)

这个信息现在可以被添加到上面的堆栈跟踪如下:

<\SystemRoot\System32\NTOSKRNL.EXE: 29bb>    <enter next one here>
<\SystemRoot\System32\NTOSKRNL.EXE: 85fa8>   obj-i386\ntoskrnl\ex\zw.S:253 (ZwClearEvent)

启用内核跟踪

这篇文章说明如何启用内核跟踪。

页面调试堆(衰变时)

堆验证基于Windows的功能页面,这种机制对于更深入的调试非常有用usermode堆问题(崩溃ntdll:堆函数)。 它可以在每个应用程序启用或全局(整个系统)。

每个特定的应用程序启用衰变时,gflags。 exe是必要的。 这个程序是几包的一部分,即调试工具为Windows和Windows支持工具。 请确认你下载32位包。 GFlags。 从ReactOS exe必须执行以下语法:“gflags / p /启用应用程序。 exe /完整”之后,应用程序执行。 可以禁用调试运行gflags /禁用开关或重启。

使衰变时系统,您需要应用以下补丁ReactOS来源:

Index: lib/rtl/heap.c
===================================================================--- lib/rtl/heap.c	(revision 64030)+++ lib/rtl/heap.c	(working copy)@@ -1234,6 +1234,8 @@
     NTSTATUS Status;
     ULONG MaxBlockSize;
 +    RtlpPageHeapEnabled = TRUE;+
     /* Check for a special heap */
     if (RtlpPageHeapEnabled && !Addr && !Lock)
     {@@ -1254,6 +1256,8 @@
         Flags &= HEAP_CREATE_VALID_MASK;     } +    if (!Addr) Flags |= HEAP_FLAG_PAGE_ALLOCS;+
     /* TODO: Capture parameters, once we decide to use SEH */
     if (!Parameters) Parameters = &SafeParams;

特殊的池

特殊池的调试版本内核池和有助于检测超支(可选欠载运行很有用)以及使用后免费。

以下限制适用于使用特殊池:

  • 只有分配4088字节和较小的可以使用特殊的池。

  • 许多内存管理器结构依赖于居住在特定的内存区域,所以他们不能被放置在特殊的池。 除非特别试图解决一个毫米的问题,最好避免将任何毫米特殊池中分配。

  • 只有数量有限的页面的虚拟地址空间留给特别的游泳池,和每一个分配占两页。 因此你可能会耗尽页面很快如果你直接太多配置使用特殊池。 这将显示一个“特殊池:没有pt ! “调试打印和分配将回到常规池。 当启用特殊池分配,这已经发生在引导。

启用特殊池:

  • 使用特殊池一池标签,设置一个值MmSpecialPoolTag在ntoskrnl / mm / ARM3 / pool.c。 所有分配使用这个标签将被放置在特殊池只要pt是可用的。

  • 启用特殊池分配,设置MmSpecialPoolTag‘*’

  • 为一个以上的标签,使其集MmSpecialPoolTag任何exceept 0或1和修改MmUseSpecialPool在ntoskrnl / mm / ARM3 /特别。 c(如返回真正的多个标签)。

提示和技巧:

  • 你可以在任何时候改变MmSpecialPool标记的价值,唯一的限制是,它不能是0或1在引导,或特殊池永远不会被初始化。 示例WinDbg命令:ed nt ! MmSpecialPoolTag DCBA”

如何读/调试BugCheck消息吗

  • BugCheckCode参数中定义的十六进制值:

\include\reactos\mc\bugcodes.mc
 or, generated .h-version for i386: \obj-i386\include\reactos\bugcodes.h






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

Contents

1 Introduction

2 Available debugging methods

2.1.1 Serial Port

2.1.2 Debug text output to file

2.1.3 Debug text output to screen

2.1.4 Changing the BAUD rate

2.1.5 Changing the serial port address

2.1.1.1 Virtual machines

2.1.1.2 Real computer: Physical serial cable

2.1.1.3 How to start Serial terminal on Linux

2.1.1.4 Troubleshooting

2.1.1.5 Serial terminal through FreeBSD

2.1.3.1 Advanced option: Debugging the debug logger

2.1 Debugging through text messages

2.2 KDBG

2.3 GDB

2.4 WinDbg

3 Generating even more output

3.3.1 Dynamic

3.3.2 Static

3.3.1.1 Breaking on user mode Exceptions

3.1.1 ReactOS Style

3.1.2 WINE Style

3.1.1.1 Adding own debug messages

3.1 Turning on verbosity at compile time

3.2 Turning on verbosity at runtime

3.3 Breaking into the built-in kernel debugger

3.4 Generating a backtrace

3.5 Translating Addresses

3.6 Enabling Kernel Tracing

3.7 Debug Page Heap (DPH)

3.8 Special Pool

3.9 How to read/debug BugCheck messages

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

VirtualBox

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 ReactOS test computer must have a serial port. Note that a USB-serial adapter is unsuitable, but a PCI serial card should work.

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:

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 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.

Serial hardware can be tricky to get right, but be persistent. There are a few things to remember:

Plan which connections are DTE and which DCE, and which gender each has. Know which serial port (1 or 2) you're connecting on each computer.

If you use a PCI serial card, it could be necessary to pass the serial port adress to the kernel (for details see below).

Get the right kind of null modem. There are a few ways to make them and not all are the same.

Use shorter cables as much as possible.

Use a serial terminal program such as HyperTerminal or Minicom to observe the remote computer.  If you don't see data you can recognize, then something is wrong.

GDB remote commands start with $ and end with ;. You'll be able to recognize them that way.

Note: use these settings (In HyperTerminal)

Bits per second: 115200

Data bits: 8

Parity: None

Stop bits: 1

Flow control: Hardware

Note: Some older BIOSes may have problems with a baud rate 115200. Try instead 9600 on test computer by editing the file freeldr.ini and use parameter /BAUDRATE=9600. Of course you have to change the baudrate also to 9600 on receiving computer.

How to start Serial terminal on Linux

Firstly you need to have installed cu terminal program, for rpm-based systems cu is in uucp-V.V.V.rpm package.

on yum-based system run: sudo yum -y install uucp

on apt-based system run: sudo apt-get install uucp

Some Linux distributions require the next change in /etc/group file: add your user (or maybe root) to group dialout

Then run:

sudo cu -s 115200 --parity=none -l /dev/ttyS0

Here

/dev/ttyS0 is your COM port name, you could find its name by reading dmesg|grep tty command output.

also "-e -o" keys could be used instead of --parity=none

Troubleshooting

In case of "Line in use"/"Permission denied" error:

user1~ # cu -s 115200 --parity=none -l /dev/ttyS4cu: open (/dev/ttyS4): Permission denied
cu: /dev/ttyS4: Line in use
user1~ #

make sure you have included your user1 to dialout group.

Serial terminal through FreeBSD

cu goes preinstalled in FreeBSD.

Run in console:

sudo cu -s 115200 -e -o -t -l /dev/cuau0

here /dev/cuau0 is your serial port (COM) device name, find right name of your COM port in in the output of dmesg command. And for other keys:

"-e -o" options together mean no-parity

-l /dev/Xdev specifies COM device name

-t denotes connection is hardwired to a host on a dial-up line (not sure is this key really needed).

And to collect log output into a file for sending, run this script:

DATE=`date +"%F_%H%M%S"`screen -dmS ROSlogger script MyMachine1-ROS-debug-$DATE.log sudo cu -s 115200 -e -o -t -l /dev/cuau0

It will write log into file named MyMachine1-ROS-debug-$DATE.log, here $DATE will be the time when script was started. You could change here MyMachine1 to your machine name.

Debug text output to file

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. To redirect the output into another file, edit the kernel parameter /DEBUGPORT=FILE in freeldr.ini. For example:

Options=/DEBUG /DEBUGPORT=FILE:\Device\Harddisk0\Partition1\debug.log /SOS

Or:

Options=/DEBUG /DEBUGPORT=FILE:\ArcName\multi(0)disk(0)fdisk(0)\debug.log /SOS

Debug text output to screen

Choose ReactOS (Screen) in the boot menu.

Or edit freeldr.ini to contain an entry like the following:

[ReactOS_Debug]BootType=Windows2003SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOSOptions=/DEBUG /DEBUGPORT=SCREEN /SOS


Advanced option: Debugging the debug logger

Sometimes things go wrong and it becomes necessary to debug the debug logger, say SCREEN logger. To do this, it is possible to turn on more than one logger, by specifying it on kernel command line options like this: Edit freeldr.ini to contain an entry like the following:

[ReactOS_Debug2]BootType=Windows2003SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOSOptions=/DEBUG /DEBUGPORT=SCREEN /DEBUGPORT=COM1 /SOS

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. Note that some BIOSes on older test computer may have a problem with 115200. In that case, use 9600 instead.

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.

Changing the serial port address

Edit the kernel parameter /DEBUGPORT=COM. This could be necessary, if you use a PCI/PCIe/PCMCIA/ExpressCard serial card on real hardware. This is normally used for notebooks without built-in serial port. For example:

Options=/DEBUG /DEBUGPORT=COM:0xCC00 /BAUDRATE=115200 /SOS

See also: Chromium OS‎ Serial Debugging HOWTO on how to determine the I/O address of inserted extension card.

Note: Reactos does not (yet!) support MMIO-based (modern) serial extension cards.

KDBG

See 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 article: WinDBG

To take full advantage of WinDBG, you need to compile reactos with MSVC to get pdb symbols. For MSVC builds this is the default debugging style. If you want to use gcc builds, you need to compile with WINKD option set to TRUE (you can either use CMake-GUI and edit the value after configuring and then reconfigure, or you can edit the default value in the options.cmake file) Another possibility is to replace ntoskrnl.exe and kdcom.dll built with the WINKD = TRUE option. You can also replace kdcom.dll with the one from Windows 2003, which has a few more features, like reconnect and break-in, that don't work properly with reactos' own kdcom atm.

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 printf, but have some different codes.

WINE Style

sample line to enable debug channels in usermode applications, in file:

boot/bootdata/hivesys.inf

; Debug channels
HKLM,"SYSTEM\CurrentControlSet\Control\Session Manager\Environment","DEBUGCHANNEL",0x00020000,"+ole,+rpc"

Turning on verbosity at runtime

The easiest way to turn on debug verbosity on any particular component is to use DEBUGCHANNEL environment variable. For example, to get all debug messages from MSI, simply run in CMD:

set DEBUGCHANNEL=+msi

Then, run the app you wish to test. You can add debug messages from multiple components, for example:

set DEBUGCHANNEL=+msi,+rpc,+ole

You can find a complete list of the debuggable components here.

After closing down CMD, debug verbosity will change to default.

<Describe details on how to set verbosity level, turn on debug from all components.>

Breaking into the built-in kernel debugger

Bugchecks occur when the operating system can no longer operate safely and to avoid corrupting data, it halts operation. This will normally throw up a Blue Screen Of Death, but if you have the kernel debugger activated, it will drop you into the prompt giving you access to explore the system state. By default ReactOS debug builds have the integrated kernel debugger (kdbg) enabled. Release builds do NOT have this feature enabled and will only display a blue screen.

There are two ways for forcing a bugcheck, each one employing a different method:

Dynamic

If you have a debug build and want to halt the system for any given reason and break into the the kernel debugger, you can force a bugcheck from the keyboard by simply typing:TAB+K


Remember that kdbg output goes out through the serial port, but it receives input from the keyboard by default.

To allow input through the serial port as well start with ReactOS with the boot option "ReactOS (RosDbg)" or add the command /KDSERIAL to your freeldr.ini boot options.

Breaking on user mode Exceptions

For each type of exception known by KDB you can set the condition when KDB should be entered individually for first and last chance. The possible settings for the conditions are never, umode, kmode and always.

never: kdbg won't be entered when exceptions are raised

umode: kdbg will be entered when the exception was raised in usermode

kmode: kdbg will be entered when the exception was raised in kernel mode

always kdbg will be entered on every exception

To change the condition to enter KDB on all exceptions to "always" (default is "kmode"), enter the debugger and type:

set condition * first always

Type "cont" to continue normal execution.

Static

This is useful when you want to halt the operating system when it hits a particular area of code you might be debugging. This is especially useful as you can get an immediate back trace to see where the code flow came before the bugcheck was forced.

This is done by using KeBugCheck() or ASSERT() in the code.

Generating a backtrace

In order to generate a backtrace you must break into the KDBG prompt.

Enter 'bt' and hitRETURN, you should see something similar to the following:

(drivers\filesystems\vfat\rw.c:809) <\ReactOS\system32\kernel32.dll>
Entered debugger on embedded INT3 at 0x0008:0x800935f2.
kdb:> bt
Eip:
<ntoskrnl.exe:935f3 (lib\rtl\i386\debug_asm.S:31 (DbgBreakPoint@0))>
Frames:
<vfatfs.sys:97de (drivers/filesystems/vfat/misc.c:111 (VfatDispatchRequest))>
<vfatfs.sys:9b25 (drivers/filesystems/vfat/misc.c:167 (VfatBuildRequest))>
<ntoskrnl.exe:3ab23 (ntoskrnl/io/iomgr/irp.c:1088 (IofCallDriver))>
<ntoskrnl.exe:36206 (ntoskrnl/io/iomgr/iofunc.c:686 (IoSynchronousPageWrite))>
<ntoskrnl.exe:59daa (ntoskrnl/mm/section.c:6330 (MmspWriteDataSectionPages))>
<ntoskrnl.exe:244c6 (ntoskrnl/ex/work.c:162 (ExpWorkerThreadEntryPoint))>
<ntoskrnl.exe:70e90 (ntoskrnl/ps/thread.c:134 (PspSystemThreadStartup))>
<ntoskrnl.exe:7b142 (ntoskrnl\ke\i386\ctxswitch.S:258 (KiThreadStartup@156))>
kdb:>

The bt command will show a backtrace of the currently attached thread, so it may be necessary to use the 'thread attach' command, please refer to the kdbg manual for more details.

Examining this in more detail, we can see that the bugcheck occured via the INT3 operation which then dropped us into kdb. The next line shows us Eip which is the instruction pointer, and this points to the last address before the system halted.

Following on from that are the frames. This is the important part of generating our backtrace and it contains all the function addresses in the buildup to the bugcheck. This is the crutial information developers need to understand the codeflow before the bugcheck.

Translating Addresses

Occasionally, there will come a time when you will need to manually translate addresses. When kdbg is not enabled and a bugcheck occurs, you will be presented with a stack trace similar to the following:

(subsystems\win32\csrss\win32csr\conio.c:1101) Console_Api Ctrl-C
*** Fatal System Error: 0x00000001                       (0x80079279,0x00000000,0x0000FFFF,0x00000000)
<\SystemRoot\System32\NTOSKRNL.EXE: 29bb> <\SystemRoot\System32\HAL.DLL: 4749> <\SystemRoot\System32\NTOSKRNL.EXE: 54cb4> <\SystemRoot\System32\NTOSKRNL.EXE: 582bf> <\SystemRoot\System32\NTOSKRNL.EXE: 583fd> <\SystemRoot\System32\NTOSKRNL.EXE: 89956> <\SystemRoot\system32\drivers\videoprt.sys: 2417> <\SystemRoot\system32\drivers\vbemp.sys: 17f5> <\SystemRoot\system32\drivers\vbemp.sys: 19cf> <\SystemRoot\system32\drivers\videoprt.sys: 1c48> <\SystemRoot\System32\NTOSKRNL.EXE: 34c17> <\SystemRoot\System32\NTOSKRNL.EXE: 21e0> <\SystemRoot\System32\NTOSKRNL.EXE: 2908> <\SystemRoot\System32\NTOSKRNL.EXE: 29bb> <\SystemRoot\System32\NTOSKRNL.EXE: 85fa8>

As you can see, this is largely the same as the information presented when issuing a 'bt' command in kdbg. The problem here however, is that only the addresses are given. As these addresses are different for everyone's builds, this information is useless for anyone trying to follow what events occurred in the lead up towards to bugcheck.

The solution here is to translate the addresses into human readable function names. This is done via a tool named 'raddr2line' which is a modified version of the Unix tool 'addr2line'. This tool will translate the addresses given to it into file names and line numbers. It does this by using debug information in the executable files to associate the address with this human friendly info and outputs it into the console. This information can be pasted into the above debug log alongside the addresses providing the developers with a detailed stack trace.

raddr2line is included in the Reactos Build Environment. It is invoked in the following way :

raddr2line <file> <address>

So taking the bottom address in the above stack trace :

C:\Users\Ged\MyFiles\ReactOS\clean_source>raddr2line ntoskrnl.exe 85fa8

C:\Users\Ged\MyFiles\ReactOS\clean_source\output-i386\ntoskrnl\ntoskrnl.exe
obj-i386\ntoskrnl\ex\zw.S:253 (ZwClearEvent)

we can see here that the address translation for 0x85fa8 is line 253 in file ntoskrnl\ex\zw.S (this will differ if you try it on your build)

This information can now be added into the above stack trace as follows :

<\SystemRoot\System32\NTOSKRNL.EXE: 29bb>    <enter next one here>
<\SystemRoot\System32\NTOSKRNL.EXE: 85fa8>   obj-i386\ntoskrnl\ex\zw.S:253 (ZwClearEvent)

Enabling Kernel Tracing

Refer to this article for instructions on how to enable kernel tracing.

Debug Page Heap (DPH)

Based on functionality of Windows Page Heap Verification, this mechanism is useful for more in-depth debugging of usermode Heap issues (crashes in ntdll:heap functions). It can be enabled per-application or globally (for the whole system).

To enable DPH per particular application, gflags.exe is needed. This program is a part of few packages, namely Debugging Tools for Windows and Windows Support Tools. Please make sure you download 32bit package. GFlags.exe must be executed from ReactOS with the following syntax: "gflags /p /enable application.exe /full" and the application executed afterwards. Debug can be disabled by rerunning gflags with /disable switch or by reboot.

To enable DPH system-wide, you need to apply the following patch to ReactOS source :

Index: lib/rtl/heap.c
===================================================================--- lib/rtl/heap.c (revision 64030)+++ lib/rtl/heap.c (working copy)@@ -1234,6 +1234,8 @@
    NTSTATUS Status;
    ULONG MaxBlockSize;
 +    RtlpPageHeapEnabled = TRUE;+
    /* Check for a special heap */
    if (RtlpPageHeapEnabled && !Addr && !Lock)
    {@@ -1254,6 +1256,8 @@
        Flags &= HEAP_CREATE_VALID_MASK;     } +    if (!Addr) Flags |= HEAP_FLAG_PAGE_ALLOCS;+
    /* TODO: Capture parameters, once we decide to use SEH */
    if (!Parameters) Parameters = &SafeParams;

Special Pool

Special Pool is the debug version of the kernel pool and helps detect overruns (optionally underruns) as well as uses after free.

The following constraints apply to the use of Special Pool:

Only allocations of 4088 bytes and smaller can use special pool.

Many Memory Manager structures rely on residing in specific memory regions, so they cannot be placed in Special Pool. Unless specifically trying to solve an Mm issue it is best to avoid placing any Mm allocations in Special Pool.

There is only a limited number of pages in the virtual address space reserved for Special Pool, and every allocation occupies two pages. Hence you may run out of pages quickly if you direct too many allocations to use special pool. This will be indicated by a "Special pool: No PTEs left!" debug print, and the allocations will fall back to regular pool.  When enabling special pool on all allocations, this already happens at boot.

To enable Special Pool:

To use Special Pool for a single pool tag, set a value for MmSpecialPoolTag in ntoskrnl/mm/ARM3/pool.c. All allocations using this tag will be placed in Special Pool as long as PTEs are available.

To enable Special Pool for all allocations, set MmSpecialPoolTag to '*'.

To enable it for more than one tag, set MmSpecialPoolTag to anything exceept 0 or -1 and modify MmUseSpecialPool in ntoskrnl/mm/ARM3/special.c (e.g. to return TRUE for mutliple tags).

Tips & Tricks:

You can change the value of MmSpecialPool tag at any time — the only constraint is that it must not be 0 or -1 at boot, or Special Pool will never be initialized. Example WinDbg command: ed nt!MmSpecialPoolTag 'DCBA'

How to read/debug BugCheck messages

BugCheckCode parameter hex values are defined in:

\include\reactos\mc\bugcodes.mc
or, generated .h-version for i386: \obj-i386\include\reactos\bugcodes.h