Debugging

Отладка

На этой странице описаны различные методы и шаги, необходимые для отладки ReactOS.

Вступление

Если вы хотите помочь в разработке ReactOS, вне зависимости от того, собираетесь ли вы участвовать в разработке исходного кода или хотите стать участником команды тестеров, вам необходимо знать, как правильно получить полезные протоколы отладки.

Полезные протоколы отладки являются основным источником информации, изучив которую разработчик может быстро и точно определить, что делает операционная система в тот момент, когда происходит сбой. Многие знают как получить стандартную отладочную информацию от операционной системы, но, по большей части, от нее мало пользы при поиске проблем, в особенности при поиске ошибок.

Цель этой статьи - не просто научить пользователей получать протокол отладки, а показать, каким образом можно сделать этот протокол максимально полезным и информативным: таким, чтобы на его основании можно было однозначно понять, что именно делает операционная система.

Доступные методы отладки

Существуют различные методики отладки ReactOS; некоторые из них требуют больше знаний, чем остальные. Список методов приведён ниже.

Отладка при помощи текстовых сообщений

Это самый простой способ получения отладочной информации из ReactOS.

Последовательный порт

Способ, в котором используется последовательный порт, является наиболее распространённым методом получения отладочных сообщений из ReactOS. Способ получения данных через последовательный порт зависит от того, запущен ReactOS в виртуальной машине или работает на реальном компьютере. Если вы собираетесь использовать виртуальную машину, вам может пригодится драйвер Com0com для соединения с виртуальным последовательным портом взамен использования именованного канала.

Виртуальные машины

Способы получения информации через последовательный порт рассмотрены на страницах, посвящённых отладке в конкретных виртуальных машинах:

• QEMU
• VirtualBox
• VMware

Реальный компьютер: Физический последовательный кабель

Если вы хотите получать отладочные данные от реального компьютера через последовательный порт, то вам потребуется соответствующий кабель. В этом случае вам понадобятся два компьютера (на одном вы будете тестировать ReactOS, а на другом получать отладочные сообщения). У компьютера, на котором будет производиться тестирование ReactOS должен иметься COM-порт. Обратите внимание, что адаптер последовательного порта для шины 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

Подключите кабель к первому последовательному порту обоих компьютеров.

Далее, используйте программу-терминал, такую, например, как PuTTY или Windows HyperTerminal на том компьютере, на котором вы хотите получать отладочные сообщения. Установите режим приёма данных с первого последовательного порта (COM1 [3F8/IRQ4]) и скорость данных 115200 бод.

После этого, загрузив ReactOS в режиме отладки ReactOS (Debug) на испытательном компьютере, вы будете получать отладочные сообщения. Если вы не получаете сообщений, проверьте свои аппаратные средства, а также конфигурацию freeldr.ini.

Возможно, что настройка последовательного порта покажется вам сложной, но дорогу осилит идущий! Просто запомните следующее:

• Продумайте, какое из соединений будет предназначено для передачи данных, а какое для приёма; уделите особое внимание выбору типа разъёма (гнездо или штекер). Кроме того, вы должны точно знать, к какому из последовательных портов (COM1 или COM2) вы подключаетесь на каждом компьютере.
• Для использования последовательного порта на PCI-карте вам возможно придётся настроить адрес последовательного порта, который будет использоваться ядром (дополнительную информацию можно найти чуть ниже).
• Убедитесь, что используете правильный тип нуль-модемного кабеля. Существует несколько способов изготовления таких кабелей, и не все из них совместимы.
• Используйте настолько короткие кабели, насколько это возможно.
• Для просмотра отладочных данных с удалённого компьютера, вам потребуется программа-терминал, например HyperTerminal или Minicom. Если во время работы программы вы не видите никаких данных в окне терминала, значит что-то не так.
• Команды GDB должны начинаться с $ и заканчиваться ;. По этим символам вы их и сможете опознать.
• Примечание: используйте эти настройки (в HyperTerminal)
  • Bits per second: 115200
  • Data bits: 8
  • Parity: None
  • Stop bits: 1
  • Flow control: Hardware
• Примечание: Некоторые старые версии BIOS могут не поддерживать скорость передачи данных 115200 бод, поэтому вам может потребоваться изменить её. Для этого вы можете снизить скорость передачи данных до 9600 бод отредактировав файл freeldr.ini на тестируемом компьютере, изменив параметр /BAUDRATE=9600. Разумеется, на принимающем компьютере вам также придётся установить скорость 9600 бод.

Запуск последовательного терминала в Linux

• Прежде всего вам потребуется установить терминальную программу cu, в системах, использующих пакеты в формате rpm, cu находится в пакете uucp-V.V.V.rpm.
  • на системах с yum выполните sudo yum -y install uucp
  • на системах с apt выполните sudo apt-get install uucp
• На некоторых дистрибутивах Linux необходимо также внести изменения в файл /etc/group: добавьте своего пользователя (а может и root) в группу dialout
• После этого запустите программу:

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

где:

• /dev/ttyS0 это имя вашего COM-порта, его вы можете найти изучив данные, выводимые по команде dmesg|grep tty.
• также, вместо --parity=none вы можете использовать ключи "-e -o"

Запуск последовательного терминала в FreeBSD

Программа cu предустановлена во FreeBSD.

Запустите в консоли:

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

где /dev/cuau0 имя вашего последовательного (COM) порта, узнать правильное имя COM-порта вы можете выполнив команду dmesg. Другие ключи:

• параметры "-e -o", заданные совместно, указывают на отсутствие контроля чётности
• -l /dev/Xdev задаёт имя COM-порта
• -t указывает на то, что соединение с хостом происходит по коммутируемой (dial-up) линии (не уверен в необходимости этого ключа).

Для сбора данных в файл из последовательного порта, запустите этот скрипт:

 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-$DATE.log, здесь $DATE будет заменено на время запуска скрипта. Вы можете заменить MyMachine1 на имя вашего компьютера.

Вывод текстовых отладочных сообщений в файл

Выберите в меню загрузки ReactOS (Log file). Отладочные сообщения будут сохраняться в файле debug.log. У этого способа имеются некоторые ограничения. Сообщения о критических системных сбоях не сохраняются в этот протокол отладки. Для того, чтобы отладочные данные выводились в другой файл, отредактируйте значение параметра /DEBUGPORT=FILE в freeldr.ini. Например:

 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 (Screen).

Или отредактируйте файл freeldr.ini таким образом, чтобы он содержал следующие строки:

[ReactOS_Debug]
BootType=ReactOS
SystemPath=multi(0)disk(0)rdisk(0)partition(1)\ReactOS
Options=/DEBUG /DEBUGPORT=SCREEN /SOS

Дополнительный параметр: Отладка протоколирования

Иногда возникает необходимость отладки протоколирующего отладчика, например, отладчика SCREEN, призводящего вывод протокола отладки на экран. Для этого существует возможность активизации более чем одного устройства вывода отладочных сообщений, задав использование этой возможности в командной строке ядра так: Отредактируйте freeldr.ini чтобы он содержал следующие строки:

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

Изменение скорости передачи данных

Если вам кажется, что скорость в 115200 бод слишком низка, и ваш последовательный порт поддерживает более высокую скорость передачи, как, например, виртуальный последовательный порт, то вы можете её изменить. Учтите, что некоторые версии BIOS на старых тестовых компьютерах могут некорректно работать на частоте 115200 бод. В этом случае используйте скорость 9600 бод.

1. Откройте файл freeldr.ini в корневой папке установки reactos.

2. Найдите секцию "[ReactOS_Debug]"

3. Измените настройки на что-то вроде "/BAUDRATE=921600" (исправно работает с hyperterminal и putty)

4. Сохраните файл.

5. Измените скорость передачи данных вашего терминала.

Изменение адреса последовательного порта

Отредактируйте параметр ядра /DEBUGPORT=COM. В этом может возникнуть необходимость если вы захотите воспользоваться картой адаптера последовательного порта для шин PCI/PCIe/PCMCIA/ExpressCard на реальном аппаратном обеспечении. Особенно это может пригодиться на ноутбуке без встроенного последовательного порта. Например:

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

Дополнительная информация: Chromium OS‎ Serial Debugging HOWTO, статья, посвящённая тому, как определить адрес порта ввода/вывода для установленной в системе карты расширения.

Примечание: В ReactOS (пока что!) не поддерживаются карты расширения для организации последовательного порта, производящие вывод в порт при помощи MMIO (большинство современных карт).

KDBG

Прочтите информацию о командах kdbg для получения дополнительной информации о встроенном отладчике ядра.

GDB

Для использования GDB в качестве отладчика ядра, прочтите сведения о GDB.

Необходимые элементы:

• GDB (входит в состав среды сборки ReactOS)
• QEMU

Запустите QEMU как обычно, но добавьте следующие параметры командной строки:

 -s -S

Если всё сделано правильно, то QEMU запустится в состоянии "ОСТАНОВЛЕНО", и позволит вам присоединиться при помощи GDB. Теперь пришло время как следует поработать с GDB.

• (Предполагается, что вы находитесь в режиме командной строки RosBE), введите “gdb” для запуска GDB.
• Введите “file ./output-i386/ntoskrnl/ntoskrnl.exe” чтобы указать GDB откуда необходимо загружать информацию о ядре.
• Введите “set disassembly-flavor intel” если вы предпочитаете синтакс Intel.
• Введите “target remote localhost:1234” для соединения GDB с QEMU.
• Введите “c” (сокращение от “continue“, т.е. “продолжить“) чтобы GDB дал указание QEMU начать/продолжить эмуляцию.
• Для того, чтобы самостоятельно приостановить выполнение кода, убедитесь, что окно GDB имеет фокус ввода и просто нажмите <CTRL>+<C>

WinDbg

Основная статья: WinDBG

Для работы WinDbg необходима перекомпиляция ReactOS в MSVC для обеспечения поддержки им pdb. Для программ, собранных в MSVC, это стандартный способ отладки. Если вы хотите использовать сборки, собранные в gcc, то сборку необходимо производить с параметром WINKD, имеющим значение TRUE (также вы можете воспользоваться CMake-GUI и отредактировать значение параметра после конфигурирования, а затем переконфигурировать вновь, помимо того, можно исправить значение по умолчанию в файле options.cmake). Ещё один способ заключается в подмене файлов ntoskrnl.exe и kdcom.dll их аналогами, собранными с параметром WINKD = TRUE. Помимо того, вы можете взять файл kdcom.dll из Windows 2003, который обладает чуть большей функциональностью, чем тот, что имеется в ReactOS на текущий момент, и заменить им его аналог из ReactOS.

Получение ещё большего количества данных

Чтобы получить большее количество отладочной информации, иногда необходимо включить режим вывода избыточной информации.

Включение режима вывода избыточной информации при компиляции

Стиль ReactOS

Почти все модули ReactOS используют встроенный отладочный функционал в "стиле ReactOS". Этот стиль характеризуется следующими особенностями:

• Уровень избыточной информации обычно задаётся в файле.
• Только 2 уровня сообщений:
  • всегда разрешено (DPRINT1)
  • разрешено, только если NDEBUG не задан (DPRINT)

Файлы, созданные в этом стиле, могут быть с лёгкостью опознаны по следующему коду:

#define NDEBUG
#include <debug.h>

Для включения полного избыточного режима просто закомментируйте строку "#define NDEBUG", и помните о необходимости её раскомментирования при отправке патчей.

Добавление своих отладочных сообщений

Убедитесь, что добавили debug.h

#include <debug.h>

И используйте DPRINT / DPRINT1, оба из них работают аналогично printf, но имеют несколько различные коды.

Стиль WINE

образец строки для включения каналов отладки в приложениях пользовательского режима, в файле:

boot/bootdata/hivesys.inf

 ; Отладочные каналы
 HKLM,"SYSTEM\CurrentControlSet\Control\Session Manager\Environment","DEBUGCHANNEL",0x00020000,"+ole,+rpc"

Включение режима избыточной информации во время работы

Простейшим способом включения режима избыточной отладочной информации в любом специфическом компоненте состоит в использовании переменной среды DEBUGCHANNEL. Например, чтобы получить все отладочные сообщения из MSI, просто выполните в командной строке:

 set DEBUGCHANNEL=+msi

Затем, запустите приложение, которое вы желаете проверить. Вы можете добавить отладочные сообщения отладки из нескольких компонентов, например:

 set DEBUGCHANNEL=+msi,+rpc,+ole

Полный список компонентов, которые можно отладить, вы можете найти здесь.

После закрытия CMD, режим избыточной отладочной информации отладки будет установлен в состояние по умолчанию.

<Здесь следует написать о том, как установить уровень избыточности сообщений, а также о том, как включить вывод отладочной информации от всех компонентов.>

Останов с переходом во встроенный отладчик ядра

Поиск ошибок происходит тогда, когда операционная система больше не может безопасно функционировать, и, чтобы избежать повреждения данных, она прерывает свою работу. Это обычно приводит к появлению "Синего экрана смерти", но, если на вашей системе активирован отладчик ядра, то вы перейдёте к просмотру состояния системы. По умолчанию, отладочные сборки ReactOS имеют встроенный отладчик ядра (kdbg). Финальные сборки НЕ имеют подобной функции и будут лишь отображать синий экран.

Существует два способа инициировать проверку ошибок, каждый из которых использует различные подходы:

Динамический

Если вы используете отладочную сборку, и хотите приостановить систему по какой-либо причине и войти в отладчик ядра, то можете инициировать проверку на ошибки просто нажав на клавиатуре: TAB+K

Помните, что хотя данные из KDbg выводятся через последовательный порт, но для ввода данных по умолчанию используется клавиатура.

Чтобы разрешить ввод данных через последовательный порт, запустите ReactOS выбрав в меню загрузки "ReactOS (RosDbg)" или добавьте команду /KDSERIAL в параметры загрузки в файле freeldr.ini.

Останов на исключительных ситуациях пользовательского режима

Для любого типа исключений, известных KDB вы можете задать условия, при которых должен произойти переход в KDB, они должны быть введены отдельно для первой и последней попытки. Возможными условиями являются: never, umode, kmode и always.

• never: при возникновении исключения переход в kdbg произведён не будет
• umode: переход в kdbg произойдёт только если исключение произошло в пользовательском режиме
• kmode: переход в kdbg произойдёт только если исключение произошло в режиме ядра
• always: переход в kdbg произойдёт при любом исключении

Чтобы изменить условие входа в KDB на always (значение по умолчанию "kmode"), войдите в отладчик и введите:

 set condition * first always

Наберите "cont" для продолжения нормального выполнения.

Статический

Этот способ полезен тогда, когда вы хотите прервать выполнение операционной системы по достижении ей определённой части кода, которую вы хотите отладить. Он особенно полезен, поскольку вы можете получить информацию обратной трассировки и увидеть, какой поток кода выполнялся перед инициализацией проверки ошибок.

Это делается при помощи команд KeBugCheck() или ASSERT() в коде.

Создание обратной трассировки

Для того, чтобы создать обратную трассировку, Вы должны вызвать KDBG.

Введя 'bt' и нажав клавишу ВВОД, вы увидите что-то вроде этого:

(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 покажет обратную трассировку прикреплённого в текущий момент потока, таким образом может возникнуть необходимость в использовании команды 'thread attach' ('подключиться к потоку'), пожалуйста обратитесь к руководству по kdbg для получения дополнительной информации.

Исследовав полученные данные более подробно, мы видим, что переход к проверке ошибок произошёл после того, как была обработана команда INT3, которая переключила нас на kdb. Следующая строка содержит Eip, это указатель команд, показывающий последний адрес, который был обработан перед остановкой системы.

Далее следуют фреймы. Это важная часть генерации данных обратной трассировки, фреймы содержат адреса всех функций, увеличивающиеся при проверке на ошибки. Это основная информация, которую разработчики должны понимать в потоке кода перед проверкой на ошибки.

Преобразование адресов

Иногда у вас будет возникать необходимость вручную преобразовывать адреса. Когда KDbg не включён и происходит проверка на ошибки, вам будут показаны данные трассировки стека, аналогичные приведенным ниже:

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

Как вы видите, во многом полученный результат аналогичен результату, получаемому при использовании команды 'bt' в kdbg. Проблема, однако, заключается в способе представления адресов. Так как эти адреса различны для каждой сборки, то эта информация будет бесполезна для того, кто попытается отследить, какие события произошли перед проверкой на ошибки.

Решением проблемы является преобразование адресов в имена функций, понимаемые человеком. Это делается при помощи программы, которая называется 'raddr2line' и является измененной версией Unix-программы 'addr2line'. Программа преобразует передаваемые ей адреса в имена файлов и номера строк. Для связывания адреса и удобной для человека информации она использует отладочную информацию из исполняемых файлов, и выводит данные в консоль. Эта информация может быть добавлена в приведённый выше протокол отладки совместно с адресами, что предоставит разработчикам детальную трассировку стека.

raddr2line включён в состав среды сборки Reactos (RosBE). Работает команда следующим образом :

 raddr2line <файл> <адрес>

Итак, берём нижний адрес в приведенной выше трассировке стека :

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)

здесь мы видим, что результатом преобразования адреса 0x85fa8 является строка 253 в файле ntoskrnl\ex\zw.S (будет отличаться при использовании вашей сборки)

Эта информация может теперь быть добавлена в приведённую выше трассировку стека следующим образом :

 <\SystemRoot\System32\NTOSKRNL.EXE: 29bb>    <введите здесь следующее>
 <\SystemRoot\System32\NTOSKRNL.EXE: 85fa8>   obj-i386\ntoskrnl\ex\zw.S:253 (ZwClearEvent)

Включение трассировки ядра

Обратитесь к этой статье для получения инструкций о том, как включить трассировку ядра.

Debug Page Heap (DPH)

Основанный на функциональности Windows Page Heap Verification, этот механизм полезен для более глубокой отладки проблем с кучей в пользовательском режиме (сбои в функциях ntdll:heap). Его можно включить избирательно для одного приложения или глобально (для всей системы).

Для включения DPH для конкретного приложения потребуется gflags.exe. Эта программа является составной частью нескольких пакетов, например Debugging Tools for Windows и Windows Support Tools. Убедитесь, что скачали 32-х битную версию пакета. GFlags.exe необходимо запустить в ReactOS со следующими параметрами: "gflags /p /enable application.exe /full" и приложение запустится. Отладка может быть отключена повторным запуском gflags с ключом /disable или перезагрузкой системы.

Для включения DPH для всей системы необходимо применить следующий патч к исходному коду ReactOS :

Index: lib/rtl/heap.c
===================================================================
--- lib/rtl/heap.c	(revision 62880)
+++ lib/rtl/heap.c	(working copy)
@@ -1231,6 +1231,7 @@
     NTSTATUS Status;
     ULONG MaxBlockSize; 
 
+RtlpPageHeapEnabled = TRUE;
     /* Check for a special heap */
     if (RtlpPageHeapEnabled && !Addr && !Lock)
     {
@@ -1251,6 +1252,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;

Как читать/отлаживать сообщения BugCheck

• Шестнадцатиричные значения параметра BugCheckCode определены в:

\include\reactos\mc\bugcodes.mc или в сгенерированной версии файла .h для i386: \obj-i386\include\reactos\bugcodes.h

• В некоторых сообщениях содержатся полезные инструкции.