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.
  • The full method here is to create a blank QCOW2 disk image file with the qemu-tools and then use this as the main emulated hard disk via the "-hda" option, then add a Linux PPC CDROM ISO image using the "-cdrom" option, start QEMU and do the distribution installation procedure as normal.
  • However, Debian Linux Squeeze for PPC is suggested as prebuilt disk images are available here. Squeeze is preferred over Wheezy for this.
• Enable VM network access proxied via the host system.
  • By default, QEMU should be providing a virtual ethernet network adapter to the VM, which will provide access to the internet via the host's connection. This can be checked by the normal methods such as ICMP ping within the VM OS. 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 any OS updates to the VM.
  • Especially when using the prebuilt images, OS system updates should be done via the normal method to ensure up to date system libraries are installed.
    • Debian:

      apt-get update

• Install the ScummVM source code, required libraries and compile a debug build.
• Within the VM, this can now be done as per a normal Linux build. For further information, check our GCC compilation instructions page
  • Getting ScummVM source tree:

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

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

    apt-get install libsdl12dev

  • Compiling ScummVM:

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

    • Refer to here for more help.
• Provide game data to the VM.
  • Though QEMU can provide access to host directories as emulated FAT formatted drives by this option:

     -drive file=fat:ro:some-directory

    , this only supports FAT-16 and is thus limited to 2GB maximum. It is suggested to use the

     -cdrom 

    option with a ISO image instead. CD swapping is not possible, but it is fairly easy to create a ISO image from a set of files in the same way as prior to writing a CD.
  • Transferring data to the host VM by normal network file transfer is also possible i.e. SSH from the VM to host or another machine, HTTP download, etc.
• Install debugging tools.

  • apt-get install gdb

  • apt-get install valgrind

    • Note: Valgrind is currently broken on Debian Squeeze PPC. If you want to install this, you will need to add the apt repositories for "Wheezy" and install the updated version from there.
• Debugging can then be done as per a normal native Linux machine, though patience may be required as the VM will be much slower than a native machine.

A preinstalled standard desktop Debian Squeeze PPC QEMU hard disk image in qcow2 format can be provided by the ScummVM development team, but since this is over 5GB, this is currently only provided on request, rather than on the download site.

Debugging for Other Architectures

The instructions above should be valid for emulation and debugging of other uncommon machine architectures e.g. MIPS, provided that QEMU supports that architecture e.g. use qemu-system-mips, rather than ppc, and a Linux distribution or other Unix is available for that architecture as a installation CD ISO image.

However, there are a few architectures which QEMU does not support, notably SH. However, there is another general purpose CPU/machine emulator called GXemul which does support this and some other more esoteric platforms. This is less supported than QEMU, but this procedure should be possible with some modifications. Any notes on this would be gratefully received by the team.