Introduction

Руководство разработчика Dolwin 0.10
Введение

Добро пожаловать в руководство по использованию исходного кода эмулятора Dolwin для разработки и отладки.

Внимание! Авторы не несут ответственности за порчу оборудования при использовании данного руководства. Руководство может быть использовано только в познавательных целях. Все торговые марки являются собственностью их уважаемых владельцев.

Данное руководство включает в себя :

  • полное описание структуры исходного кода и функций его API
  • устройство работы эмулятора и его особенности
  • краткое описание архитектуры Nintendo GAMECUBE
  • различные материалы, касающиеся устройства игр (game-hacking)
  • использование эмулятора в отладочных целях
  • советы по эмуляции GAMECUBE и процессора IBM PowerPC
Информационные ресурсы интернет (25 Nov 2004)

Домашний сайт эмулятора Dolwin

Разработка для GAMECUBE :

  • GCDEV
  • Linux on GAMECUBE
  • YAGCD - Yet Another GAMECUBE Documentation

Эмуляторы GAMECUBE :

  • Dolphin
  • GCUBE
  • Ninphin
  • WhineCube

Дополнительные ресурсы по теме :

  • Dextrose
  • Emulation 64
  • EmuHelp
  • Emu-Russia
  • EXEMU
  • MaxConsoles
  • NGEMU
Dolwin - Nintendo GameCube Emulator for Windows.
© 2002-2004, Dolwin Team.


Debug Manual

Руководство по отладке
Введение
Начиная с версии 0.08 в Dolwin интегрирован отладчик. Он представляет собой консольное окно с отладочной информацией и командной строкой. Разработчик может загружать программы для отладки и пошагового исполнения. Начиная с версии 0.10, отладчик может быть открыт/закрыт в любой момент, через меню : Development->Debug Console, или нажатием на Ctrl+D (предыдущие версии требовали отдельной компиляции, для поддержки отладчика).

Примечание для Beta : при закрытии отладчика, во время выполнения программы, эмулятор прекращает работу. Так что фактически, можно работать только с отладчиком, или без него. Должно быть исправлено в релизе 0.10.

Преимущества консоли перед GUI :

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

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

Отладчик поделен на несколько окон. Переключаться между окнами можно с помощью кнопок :

  • F1 - регистры (также происходит обновление всех регистров)
  • F2 - память
  • F3 - процессор
  • F4 - сообщения
Текущее окно помечено стрелочкой :

Окно регистров

Это окно предназначено для просмотра текущего состояния регистров CPU Gekko. По умолчанию показываются регистры общего назначения (GPR) и наиболее важные системные регистры (SPR).

Все числа в этом окне - с основанием 16 (HEX), поэтому C-префикс '0x' не используется.

Регистры R1-R31 используются CPU для целочисленных арифметических операций. При изменении значения этих регистров, они подсвечиваются зеленым цветом.

Регистр R1 обозначен как SP, R2 как SD2, и R13 как SD1, так как они неявным образом используются компилятором C. SP - указатель стека, SD1 и SD2 - указатели на данные, которые определены ключевым словом "static" в C.

Также в состав этого окна включен таймер CPU (регистр TBR). Этот регистр используется для определения текущего времени OS. Более подробно про таймеры GAMECUBE см. "Таймеры GAMECUBE и Dolphin OS", "Эмуляция DEC/TBR регистров PowerPC".

Также в состав окна регистров входят : регистры FPU, регистры FPU в режиме paired-single (PSR) и состояние MMU (Memory Mapping Unit). С помощью кнопки F6 можно циклически переключать эти под-окна :

Регистры FPR и PSR также подсвечиваются зеленым цветом, при изменении.
Примечание : в Dolphin OS, FPU всегда работает в режиме paired-single. Регистры FPR оставлены для совместимости с обычными программами PowerPC.

Советы при отладке :

  • По значению регистра MSR можно узнать, разрешены аппаратные прерывания или нет. Усановленный бит 16 (MSR[EE]) разрешает прохождение прерывания в CPU. Можете считать, что если пятая цифра MSR больше 8, то прерывания разрешены (например когда MSR = 0x00008030).
  • Регистр FPSCR не используется эмулятором, и зарезервирован для будующего. Все ошибки FPU (переполнение, потеря точности итд) игнорируются.
  • CR - регистр флагов для операций сравнения (cmp). В отличии от процессоров x86, у PPC 8 наборов флагов. Каждые четыре бита содержат результат последнего сравнения :
    8: a < b (LT - less than)
    4: a > b (GT - greater than)
    2: a = b (EQ - equal)
    1: значение бита XER[SO]
    Совсем несложно запомнить правило : "LGEX" (по первым буквам).
  • Можно примерно узнать, когда закончится цикл, по значению регистра CTR, который уменьшается с каждым шагом цикла: while (i--). Также можно узнать завершение цикла, когда в паре "зеленых" R1-R31 регистров - один "приближается" к другому: while (ptr1 != ptr2), ptr1++, или когда один из R-регистров постоянно увеличивает свое значение на 1: for (i=0; i<n; i++).
  • По значению регистра DEC иногда можно узнать - зависла игра, или нет. Регистр DEC уменьшает свое значение с частотой CPU_TIMER_CLOCK (40500000 hz). По достижении нуля возникает DEC-исключение (только если разрешены аппаратные прерывания, т.е. MSR[EE] = 1). Например игра X устанавливает значение DEC на 1 секунду (DEC = 0x0269FB20). Если по достижении DEC нуля (DEC = 0x00000000 -> 0xFFFFFFFF -> 0xFFFFFFFE ...), GX Plugin прекращает вывод графики, то вполне вероятно, что игра зависла (timing bug). Причиной может служить как неправильная эмуляция DEC-регистра, так и неаккуратное обращение с DEC самой игрой. Также такая ситуация может возникнуть при неправильных значениях настроек CPU Timing в Dolwin (Options->Settings->Emulator->CPU Timing).
  • При выключенном MMU (Options->Settings->Memory Mode->Simple translation) могут возникнуть ошибки обращения к памяти. Типичным признаком того, что программа использует MMU - отличное от нуля значение регистра SDR1.
    Примечание для Beta : эмуляция MMU не закончена. Рекомендуется использовать Simple translation.
Окно просмотра памяти

В этом окне показывается содержимое оперативной памяти GC (RAM). Используется эффективная адресация - чтобы узнать физический адрес текущей позиции, см. значение phys. В заголовке окна также указаны текущие указатели стека, и "static" данных (stack, sda1 и sda2).

Прокрутка окна вниз-вверх: Up, Down, Page Up, Page Down.

Для установки текущего адреса используется команда d.

Режим редактирования памяти
Чтобы перейти в режим редактирования памяти : F2->Enter.

В этом режиме можно изменять значение отдельных байтов. Измененные значения подсвечиваются сиреневым цветом. Ctrl+Enter: чтобы выйти и сохранить изменения, Esc: чтобы выйти без сохранения.

Кнопка Tab переключает курсор между редактированием байт и редактированием символов.

В общем этот режим аналогичен редактору памяти утилиты HIEW.
Окно процессора

В этом окне отображается загруженная программа. Желательно, чтобы у вас были навыки работы с ассемблером PowerPC, потому что все команды представлены именно на нём.

1. Эффективный адрес инструкции.
2. Код инструкции (в HEX).
3. Дизассемблированая инструкция. Все переходы (branch) подсвечиваются зеленым цветом. Стрелка указывает в какую сторону происходит переход.
4. Символьная информация для переходов. Показывает на какую функцию совершается переход. Символьная информация содержится в MAP-файлах. Более подробно см. "Символьная информация и MAP-файлы".

Для прокрутки содержимого окна используется курсор :

Кнопками Up, Down, Page Up, Page Down осуществляется перемещение курсора. Кнопками Enter/Esc можно перемещаться между вызовами (инструкция bl). Для этого нужно установить курсор на соответсвующий branch и нажать Enter.

Красным цветом подсвечиваются точки останова :

Синим цветом подсвечивается текущая инструкция CPU (PC) :

Для изменения позиции курсора используется команда u. Для установки курсора на текущую инструкцию используется команда .-точка.

Начиная с версии 0.10, отладчик поддерживает просмотр рекомпилированного PowerPC кода. Для этого нужно установить курсор на нужный адрес и нажать Ctrl+Enter. Примечание для Beta : на данный момент (25 Nov 2004) JIT Compiler не завершен, поэтому просмотр x86 JITC-кода полезен только для разработчиков.
Отладка программ
Для отладки программ используются следующие кнопки :
  • F9 - установить точку останова в позиции курсора
  • F10 - выполнить вызов (step-over)
  • F11 - пошаговое исполнение (trace)
  • F12 - пропустить инструкцию
  • F5 - выполнять программу до точки останова, или до повторного нажатия
Вывод сообщений

В этом окне выводятся отладочные сообщения (вызовы DBReport()). Можно блокировать вывод отдельных сообщений через меню Development->Log Output. В Dolwin приняты определенные соглашения на цвета и формат сообщений, придерживаться которых не требуется, но рекомендуется :

  • ЖЕЛТЫМ цветом выводятся сообщения о загрузке чего-либо (например файлов). Чаще всего эти сообщения выводятся во время инициализации эмулятора. Эти сообщения нельзя заблокировать.
  • ЦИАН используется для сообщений от железа GAMECUBE. Причем в начале каждого сообщения находится префикс соответствующего устройства :
    CP: GP Command Processor (FIFO)
    PE: Pixel Engine
    VI: Video Interface (TV)
    GP: Graphics Processor
    PI: Peripheral Interface (hardware interrupts)
    CPU: Central Processor
    MI: Memory Interface (protection)
    DSP: Digital Signal Processor HLE
    DI: DVD interface
    AR: Auxiliary (Audio) Memory (ARAM)
    AI: Audio Interface (DMA)
    AIS: Audio Interface (DVD Streaming)
    SI: Serial Interface (joypads)
    EXI: Expansion Interface
    MC: Memory Cards
  • ЗЕЛЕНЫМ цветом выводятся HLE-сообщения, а также сообщения Dolphin OS - OSReport().
  • КРАСНЫЙ цвет используется для ошибок. Эти сообщения нельзя заблокировать.

Для просмотра истории сообщений нужно нажать F4->Page Up. Чтобы сразу вернуться в командную строку можно нажать Esc, или начать ввод какой-либо команды - в этом случае переход в командную строку совершается автоматически из любого окна.
Примечание : размер буфера сообщений - приблизительно на 1000 строк. При переполнении буфера, происходит его очистка и вывод начинается заново.

Дополнительно сообщения можно сохранять в HTML-файле (см. команду log).
Примечание : вывод сообщений в log-файл значительно замедляет работу эмулятора.
Командная строка

Командная строка используется для ввода отладочных команд. Командная строка не поддерживает выделение текста, но есть возможность исправления неправильно введенных слов (Backspace, Ctrl+Left и Ctrl+Right). Набор слов, заключенных между парой кавычек считается за одно слово.

Ограничение на длину команды - не более 80 символов. Количество слов - не более 6 (включая саму команду).
Команды отладчика
Отладчик содержит встроенную справку по всем командам и кнопкам. Для вывода справки используется команда help.
Примечание для Beta : На данный момент (25 Nov 2004) команда help не завершена. Рекомендуется использовать только те команды, которые указаны в данном руководстве.

Отладочные команды в алфавитном порядке :

boot | boot <file> boot {n} Загрузить файл. Команда загружает указанный файл и начинает эмуляцию. Поддерживаемые форматы : BIN, DOL, ELF, GCM, GMP. В качестве параметра используется путь к файлу. Путь может быть как полным, так и относительным. Вариант команды boot с числовым параметром в {} скобках - позволяет загрузить файл из селектора (номер файла указан в окне статуса, например #1: c:\zelda.gcm). Примеры использования : boot pong.dol boot c:\zelda.gcm boot "c:\my gcms directory\mario.gcm" boot {5}
d | d <address> d <symbol> d <reg> [offset] Универсальная команда для изменения текущей позиции в окне просмотра памяти. В качестве параметра могут выступать: адрес, символьная метка или регистр со смещением. Смещение: 16-битное число со знаком (в DEC или HEX формате). Примеры использования : d 0x8023bc00 d OSSetCurrentContext d r5 d r9 -32 d r9 0x8034

Примечание для Beta : Планируется добавить больше команд.
Dolwin - Nintendo GameCube Emulator for Windows.
© 2002-2004, Dolwin Team.