Debugging/es

From ReactOS Wiki
Jump to: navigation, search

Template:Translate

Esta página describe diferentes métodos para depuración de ReactOS y los pasos necesarios para ello.


Introducción

Para ser capaz de ayudar en el desarrollo de ReactOS, tanto si participas en el desarrollo de su código fuente como si realizas testeos cruciales, vas a necesitar conocer como se generan logs útiles de depurado.

Los log de depurado resultan ser piezas esenciales de información que los desarrolladores necesitan para localizar e identificar exactamente lo que está haciendo el sistema operativo. Mucha gente sabe como obtener la salida de depurado por defecto del sistema operativo, pero esto en general no resulta particularmente útil para la localización de problemas, especialmente cuando se trata de errores.

Este artículo trata de aportar a los usuarios el conocimiento no solamente sobre como generar un log de depuración, sino como generar un útil log de depurado el cual puede ser utilizado directamente para averiguar lo que el sistema operativo está haciendo cuando se produce dicho error.

Métodos de depurado disponibles

Existen varios métodos para depurar ReactOS, algunos de los cuales requieren mayores conocimientos que otros. Son los listados debajo:

Depurando mediante mensajes de texto

Este es el método más sencillo para recibir la información de depurado de ReactOS.

Puerto Serie

El puerto serie es el método más común utilizado para la recepción de mensajes de depurado de ReactOS. El método utilizado para la recepción de datos por el puerto serie depende de como estés ejecutando ReactOS: en una máquina virtual o en un ordenador real.

Si pretendes utilizar una máquina virtual, entonces deberías considerar el uso de Com0com en lugar del named pipe para conectar con el puerto serie.

También puedes tratar de testear el puerto serie con Software de testeo RS232.

Máquinas virtuales

Sobre como manejar la salida serie desde máquinas virtuales podemos encontrar información específica en páginas de depurado:

Computadoras reales: cable serie físico

Si necesitas recibir las mensajes de depurado en computadoras reales utilizando el puerto serie, entonces también vas a necesitar un cable serie. Este método requiere dos computadoras (una en la cual se está testeando ReactOS y otra para la recepción de los mensajes de depurado). La computadora que realiza el test de ReactOS necesita tener por tanto un puerto serie. Ten en cuenta que un cable USB-serial no nos sirve, pero en cambio una tarjeta PCI de puertos serie debería funcionar.

El cable necesario para este método de depurado es un cable serie Null-Modem". Resulta relativamente sencillo encontrarlo en las tiendas de informática por menos de 10 dólares. Si no tienes uno, también puedes construirte uno:

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

Conecta el cable al primer puerto serie de ambos ordenadores.

A continuación utiliza una aplicación como PuTTY o HyperTerminal en el ordenador que recibe los mensajes de depurado.

Establece los valores para que escuche en el primer puerto serie (COM1 [3F8/IRQ4]) y con un ratio de baudios establecido a 115200.

Después de esto, arranca ReactOS (en modo Debug) en el ordenador a testear y deberías recibir mensajes de depurado. si esto no funciona, chequea tu hardware y la configuración del fichero.

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/ttyS4
cu: 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=Windows2003
SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOS
Options=/DEBUG /DEBUGPORT=SCREEN /SOS


Opción avanzada: Debugging the debug logger

Algunas veces las cosas salen mal y se hace necesario depurar el logger de debug, llamado SCREEN logger. Para hacer esto, es posible arrancar más de un logger especificándolo en la línea de mandatos del kernel tal como se indica a continuación:

Editar el fichero freeldr.ini para que contenga una entrada como la siguiente:

[ReactOS_Debug2]
BootType=Windows2003
SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOS
Options=/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 terminal's BAUD rate.

Changing the serial port address

Edit the kernel parameter /DEBUGPORT=COM. This could be necessary if you use a PCI, PCIe, PCMCIA, or ExpressCard serial card on real hardware. These cards are used with notebook computers without a 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 memory mapped I/O (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:

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 allows 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.
  • If you prefer Intel syntax then enter “set disassembly-flavor intel”.
  • 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 such as reconnect and break-in which do not work properly with ReactOS's own kdcom.

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.

The syntax of the DEBUGCHANNEL environment variable is:

DEBUGCHANNEL=[class]+xxx,[class]-yyy,...

For example:

DEBUGCHANNEL=+all,warn-heap

turns on all messages except warning heap messages.

The available message classes are: err, warn, fixme, trace.

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.

Sampling the Stack

If the system shows very high CPU usage or appears frozen, it may be possible to find the culprit by sampling the processor's call stack.

To obtain a simple sampling profile using the kernel debugger,

  • break into the debugger using TAB+K during a time of high CPU usage,
  • issue the bt command to print a stack backtrace (see #Generating a backtrace),
  • issue the cont command to continue execution,
  • repeat this process until you've obtained 3-5 backtraces, or the period of high CPU usage stops.

The backtrace samples obtained this way often show where processor time is being spent, and can pinpoint functions that have bugs or require optimization.

Please note that backtraces are of limited use if they have not been translated. When showing them to other people, be sure to translate the addresses, or include the exact binary files you used (or a link to the iso) to allow others to perform the translation.

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 hit RETURN, 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 the functionality of Windows Page Heap Verification, this mechanism is useful for more in-depth debugging of user mode 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 the packages Debugging Tools for Windows and Windows Support Tools. Be sure to download the 32-bit 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 rebooting.

To enable DPH system-wide, you need to apply the following patch to the 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;

When using WinDbg, you can also use the "!gflag +hpa" command, which will enable DPH for any processes started after the command was issued.

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
  • Some messages have useful instructions