kolibrios-fun/programs/develop/koldbg/readme.txt

Введение.

koldbg представляет собой интерактивный отладчик для операционной системы KolibriOS. Автор программы - Евгений Гречников (Diamond). Данная документация описывает возможности отладчика и работу с ним. Если у вас есть какие-либо вопросы по работе с программой или нужны какие-то возможности отладчика, которых ещё нет, обращайтесь на форум board.kolibrios.org в соответствующую тему - http://board.kolibrios.org/viewtopic.php?f=45&t=358, или по адресу автора - mailto:diamondz@land.ru.

Общее описание.

В каждый момент времени koldbg может отлаживать только одну программу. Назовём такую программу загруженной для отладки. Если никакая программа не загружена, абсолютное большинство действий по отладке недоступно.

koldbg управляется командной строкой, вводимой с клавиатуры. Командная строка изображается в нижней части окна отладчика. Обрабатываются стандартные клавиши ввода Backspace, Delete, Home, End, стрелки влево/вправо, стрелки вверх/вниз (прокручивание истории команд). Команды нечувствительны к регистру символов. В качестве разделителя используется произвольное ненулевое число пробелов.

В любой момент отладчик можно завершить командой "quit" (без аргументов). Впрочем, можно и просто нажать на кнопку закрытия в правом верхнем углу окна.

Запуск отладчика без параметров командной строки приводит к тому, что никакая программа не загружена. Также koldbg можно запускать с командной
строкой, в этом случае он попытается загрузить программу с именем, указанным как первый аргумент командной строки, и параметрами, указанными как
последующие (если они есть).

Если никакая программа не загружена, то можно загрузить программу командой load:
load <полное имя исполняемого файла> [<аргументы>]
Например:
load /sys/example
LOAD   /sys/aclock w200 h200
 LoaD  /hd0/1/menuetos/dosbox/dosbox
Всё, что стоит после первого пробела после имени исполняемого файла, дословно передаётся программе в качестве командной строки.
Команда load сообщает о результате в окне сообщений (немного выше окна командной строки). Если программу удалось загрузить, то об этом появится соответствующее сообщение; если не удалось, то в сообщении будет указана причина ошибки. Наиболее вероятная - "file not found", если неправильно указано имя файла.

Отладчик может загружать файлы с информацией об именах в программе (метки, глобальные переменные) - текстовые файлы, каждая строка которых имеет вид 0x<hex_значение_адреса> <имя> (строки, не имеющие такой вид, игнорируются). Такой файл может быть создан вручную или сгенерирован автоматически при компиляции исходника fasm'ом.
Явная загрузка осуществляется командой load-symbols:
load-symbols <полное имя файла символов>
Кроме того, при выполнении команды load отладчик проверяет наличие файла с таким же именем, как загружаемый бинарник, и расширением .dbg (/sys/example.dbg для первого из примеров выше), и если такой есть, загружает его автоматически (выдавая сообщение "Symbols loaded", если всё в
порядке).

Может случиться так, что загруженная программа упакована. Общий принцип упаковки программ следующий: сначала исходный файл пакуется (каким-нибудь алгоритмом сжатия), потом приписывается небольшой по размеру код, который получает управление при запуске программы, распаковывает в памяти исходный код, после чего передаёт ему управление. Если программа упакована, то её "настоящий" код не виден и для отладки нужно предварительно пройти код распаковщика. koldbg определяет большинство существующих упаковщиков (mxp, mxp_lzo, mxp_nrv, mtappack) и в этом случае предлагает автоматически пройти до "настоящего" кода. Рекомендуется согласиться (нажать 'y' или <Enter>), но можно и отказаться. При отказе и в случае, когда программа упакована чем-то неизвестным, можно использовать команду "unpack" (без аргументов). Вызывайте её только в случае,
когда вы уверены, что программа упакована и что управление ещё не дошло до основного кода! [Начиная с версии Kolibri 0.6.5.0, весь этот абзац уже неактуален, поскольку приложения можно упаковывать как и любые двоичные файлы kpack'ом и при этом код распаковщика находится в ядре и распаковка прозрачна для отладки.]

Загруженную программу можно прибить командой "terminate" (без аргументов). Команда "detach" (без аргументов) отключается от программы, после чего программа продолжает выполняться нормально, как если бы отладчика не было. После обеих этих команд программа перестаёт быть отлаживаемой.

Можно заново загрузить программу для отладки командой "reload" (без аргументов). Если уже есть загруженная программа, то она прибивается и
запускается (с самого начала) новый экземпляр (с той же командной строкой), в этом случае команда аналогична командам:
terminate
load <last program name> <last program arguments>
В противном случае заново загружается программа, которую отлаживали последней (в текущем сеансе работы с koldbg) (с той же командной строкой), т.е. почти то же самое, что и load <last program name> <last program arguments>, но команда reload в обоих случаях короче и удобнее; кроме того, load считает, что загружается новая программа, и переводит окно данных (см. ниже) на нулевой адрес, а reload сохраняет текущий адрес.

Всегда доступна команда "help", которую можно сокращать до "h".
Все команды разбиты на группы.
help без аргументов показывает список групп команд.
help с указанием группы выводит список команд этой группы с краткими
комментариями.
help с указанием команды выводит информацию о заданной команде.
Например:
help
help control
h LoaD

Окно отладчика состоит из следующих элементов, перечисляемых сверху вниз:
- строка состояния. При наличии загруженной программы показывает ее имя и состояние ("Running"/"Paused"), при отсутствии сообщает "No program loaded".
- окно регистров - показывает значения регистров общего назначения, регистра eip, регистра флагов и регистров FPU/MMX. Регистр флагов отображается двумя способами: полное hex-значение и состояния отдельных флагов: CF,PF,AF,ZF,SF,DF,OF: если флаг сброшен, то изображается маленькая буква, если установлен, то заглавная. Регистры, изменившиеся с предыдущего момента, подсвечиваются оранжевым.
- окно данных (окно дампа) - показывает содержимое памяти загруженной программы
- окно кода (окно дизассемблера) - показывает код программы в виде дизассемблированных инструкций
- окно сообщений
- окно командной строки

В окне дампа можно просматривать данные, начиная с любого адреса, для этого есть команда:
d <выражение>
Команда d без аргументов пролистывает окно дампа вниз. То же самое относится к окну кода и команде u <выражение> или просто u.
Например:
d esi - показывает данные, находящиеся по адресу esi (например, полезна перед выполнением инструкции rep movsb)
d esp - показывает стек
u eip - дизассемблирует инструкции, начиная с текущей

Выражения в koldbg могут включать
- шестнадцатеричные константы
- имена всех регистров общего назначения (8 32-битных, 8 16-битных и 8 8-битных) и регистра eip; значения 16- и 8-битных регистров расширяются
  нулями до 32 бит
- четыре арифметические операции +,-,*,/ (со стандартными приоритетами) и скобки
- [если есть информация о символах] имена, загруженные из dbg-файла
Все вычисления производятся по модулю 2^32.
Примеры выражений:
eax
eip+2
ecx-esi-1F
al+AH*bl
ax + 2* bH*(eip+a73)
3*esi*di/EAX
Команда
? <выражение> вычисляет значение указанного выражения.

Значения регистров загруженной программы можно изменять командой r, имеющей две абсолютно эквивалентные формы:
r <регистр> <выражение>
r <регистр>=<выражение>
(в обоих случаях можно расставлять пробелы по вкусу). В качестве регистра можно указывать любой из вышеупомянутых - 24 регистра общего назначения и eip.


Допустим, команда load успешно загрузила программу для отладки. Сразу после загрузки программа приостановлена и не выполняется.
Нажатие F7 (аналог командной строки - команда "s") делает один шаг в загруженной программе, после чего управление возвращается отладчику, который показывает новое содержимое регистров и памяти. Системный вызов int 40h (а также инструкции sysenter и syscall) при этом считается одним шагом.
Нажатие F8 (аналог командной строки - команда "p") также делает шаг в загруженной программе, но при этом вызовы процедур, строковые операции с
префиксом rep/repz/repnz и циклы loop выполняются как один шаг.
Команды пошагового выполнения используются, как правило, на отдельных участках программы, когда нужно, например, регулярно отслеживать значения регистров и/или каких-то переменных в памяти.
Команда g <выражение> возобновляет выполнение программы и ждёт, пока управление дойдёт до eip=соответствующему адресу, и в этот момент приостанавливает программу. Команда "g" без аргументов просто возобновляет выполнение программы.

Приостановить выполнение программы можно командой "stop" (без аргументов).

Обычно требуется, чтобы программа нормально выполнялась, но при наступлении определённых условий программа приостанавалась и управление получал отладчик. Соответствующие условия называются точками останова, breakpoint(s), в просторечии - бряками. Простейший тип точек останова - на конкретный адрес, т.е. прерывать выполнение при eip=<заданное значение>. Такие точки останова устанавливаются командой:
bp <выражение>
Замечание. Если есть только одна такая точка останова, удобнее вместо неё использовать команду "g" с аргументом.

Другой тип точек останова - по обращению к заданному участку памяти. Таких точек останова может быть не больше четырёх (поскольку используются
аппаратные возможности процессоров x86, где допускаются только 4 таких точки).
bpm <выражение> - брякается на любой доступ к байту по указанному адресу
bpm w <выражение> - брякается на запись байта по указанному адресу
bpmb/bpmw/bpmd <выражение> - брякаются на доступ к соответственно байту, слову и двойному слову по указанному адресу. bpm и bpmb - синонимы. При использовании bpmw/bpmd адрес должен быть выровнен соответственно на границу слова (т.е. быть чётным) или на границу двойного слова (т.е. делиться на 4).
bpmb,bpmw,bpmd w <выражение> - аналогично для бряка на запись.

Список установленных точек останова можно просмотреть командой "bl", информацию о конкретной точке останова можно получить с помощью "bl <номер>". Ненужные точки останова удаляются командой "bc <номер>", временно ненужные можно запретить командой "bd <номер>", когда они станут снова нужны, используйте команду "be <номер>".

Замечания.

1. При отладке собственных программ можно вставлять в код инструкции int3 (обратите внимание на отсутствие пробела!). Такая инструкция вызывает исключение при нормальном запуске, что приведёт к завершению процесса, но при работе под отладчиком просто активизируется отладчик (с сообщением "int3 command at xxx"). Это позволяет не думать о том, какие адреса использовать в командах g и/или bp. Можно также генерировать файл с информацией о символах и загружать его, тогда не только нет нужды самостоятельно вычислять адреса для "g" и "bp", но и "u","d","?" будут понимать указание имени метки/переменной.
2. Весь вывод и весь ввод ориентирован на 16-ричную систему счисления.
3. Когда программа выполняется, окна регистров и данных показывают информацию, относящуюся к моменту до возобновления; установка значений регистров в этом режиме невозможна. Впрочем, команда "d" в этом режиме показывает информацию, верную в момент выдачи команды.