HOWTO-Debug-Endian-Issues

As most desktop machines are now Little-Endian i.e. x86, debugging endian bugs is becoming difficult.
Since (as of Q4 2012) all common Big-Endian machines are not desktop systems e.g. Wii, getting run-time debug information from them is problematic and slow. The only solution available generally was to set up a legacy big-endian machine, which would generally also be very problematic and slow.

Apart from auditing the codebase for known non-portable code constructs as per Coding_Conventions#Endianess_issues, without a working test machine to replicate the issue and debug with, fixing these bugs can prove impossible.

This page details a solution to this.

The basic idea is to use an open source Virtual Machine (VM) software package to emulate a machine with a different endian CPU to the host system, install a Linux distribution for the emulated platform onto this, and then install the standard GCC toolchain and required libraries necessary to compile ScummVM from source, run and debug with gdb or valgrind as per normal Unix debugging.

Of the open source VM packages available, Oracle Virtualbox is probably the easiest to setup and configure. Unfortunately, this is only capable of emulating x86 and x86_64 machines, which are both little endian.

However, it is derived from QEMU, which is capable of emulating a far larger number of architectures, including PPC, which is probably the most common big-endian architecture.

Setting up a PPC (Big-Endian) VM using QEMU on a x86 (Little-Endian) host

• Install QEMU for your host operating system i.e. Win32, Linux, OSX
  • Linux: QEMU should be available via your distribution's package management libraries. Examples for standard distributions are as follows, but consult your distribution documentation for the exact method:
    • Debian:

      apt-get install qemu

  • Win32: Precompiled builds for Win32 are available from here.
  • OSX: This is packaged with an OSX GUI as the Q Emulator available from here.
  • For all other systems, source code be downloaded from here. Refer to your system and QEMU's documentation for help on compiling and installing this.
• Configure QEMU to emulate a PPC machine.
  • This should just be using the right binary i.e. qemu-system-ppc(.exe, .app), with some extra options to select an emulated sound device. Consult the QEMU documentation on your machine for full instructions.
  • QEMU may exit with an application crash/DLL error on Win32. This generally indicates bad parameter settings, rather than an executable/dependency problem.
  • For reference, the following Win32 batch file may be useful as a basis:
    

@ECHO OFF
SET SDL_VIDEODRIVER=directx
SET QEMU_AUDIO_DRV=dsound
SET SDL_AUDIODRIVER=dsound
SET QEMU_AUDIO_LOG_TO_MONITOR=1

START qemu-system-ppcw.exe ^
-name debianPPC ^
-L Bios -vga std -soundhw ac97 ^
-m 512M ^
-boot menu=on,splash=./bootsplash.bmp,splash-time=3000 ^
-rtc base=localtime,clock=host ^
-hda debian_squeeze_powerpc_desktop.qcow2 ^
-cdrom GAME.iso ^
-net nic,model=ne2k_pci -net user ^
-no-reboot

pause

• Install a PPC Linux distribution onto the QEMU PPC VM.
  • Prebuild Debian PPC QEMU Images
• Enable VM network access proxied via the host system.
  • QEMU should be providing a virtual ethernet network adapter to the VM, which will provide access to the internet via the host's internet connection. This can be checked by the normal methods such as ICMP ping. If this is not working, check on your host machine, then refer to the QEMU documentation for any missing configuration setting and to see if the hosted OS requires any device driver to allow this virtual device to work.
• Install the ScummVM source code, required libraries and compile a debug build.
• Within the VM, this now be done as per a normal Linux machine:
  • Getting ScummVM source tree:

    git clone git://github.com/scummvm/scummvm.git

    • Refer to Developer_Central#Getting_started here for more help.
  • Install any required libraries:

    apt-get install libsdl12dev

  • Compiling ScummVM:

    cd scummvm && ./configure && make clean && make

    • Refer to Compiling_ScummVM/GCC here for more help.
• Provide game data.
• Install debugging tools.

GXemul

• Main Website