HOWTO-Debug-Endian-Issues

Most desktop development machines being little-endian nowadays, proper endianness testing and debugging is becoming difficult.

The PS3, Wii and AmigaOS ports are some examples of systems running in big-endian mode and where endianness issues show up from time to time. Unfortunately, these ports are not very well suited for efficient iterative development and debugging. Apart from auditing the codebase for known non-portable code constructs, without a working test machine to replicate the issue and debug with, fixing these bugs can prove impossible.

Various solutions for working from a big-endian development environment exist, though:

1. Running a native, modern and powerful big-endian development system:
   • Examples include the Raptor Blackbird™ workstation. It is a powerful system which can run up-to-date Linux/BSD distributions, both in little-endian and big-endian modes.
   • Unfortunately, it's a pricey niche system, and there's no guarantee that big-endian OS options will be maintained for long.
   • NetBSD also allows running a Raspberry Pi in big-endian mode, but this hasn't been tested for ScummVM development yet.
2. Running a native, older big-endian development system:
   • Examples include buying an older G4 or G5 Apple PowerPC system, or an older SPARC64 Sun station. They can often be bought second-hand at very reasonable prices.
   • However, running a modern development environment on them in getting harder (but not impossible), because the big-endian desktop ecosystem receives less and less maintenance, so things often tend to break. G5 systems (in particular) also require careful maintenance and can be very power-hungry.
3. Emulating a big-endian development system from your regular development machine:
   • Any reasonably powerful desktop system should be able to emulate a big-endian architecture, thanks to QEMU.
   • The main drawback is that this currently requires running some older/unmaintained Linux distributions, and, as of late 2022, graphics acceleration support is missing. Since this is emulation (and not virtualization), there is also a noticeable (but usually tolerable) performance impact.

This howto focuses on the last option, since it is the most accessible one, and it's still a way of fixing the majority of endianness issues we encounter.

Linux big-endian PowerPC emulation with QEMU

The current reference VM is a pre-configured Debian 8.11 PowerPC system. It has been modified to feature an updated C++11 toolchain (GCC 5.5.0).

Some important notes:

• Security support updates have been discontinued for Debian 8 in late 2018. Older cryptographic ciphers and certificates (such as in TLS or SSH) in the base system may also cause various issues. For this reason, this VM should only be run on a local, trusted environment.
• 3D games will have a slow framerate, since QEMU only provides a limited, unaccelerated framebuffer for PPC.
• The bigger your host CPU clock rate, the better: a 4 GHz CPU will bring some improvement over a 3 GHz CPU, which is itself much better than a 2 GHz CPU, and so on. Note that QEMU emulation is mostly single-threaded, so having many CPU cores isn't really useful for this.

Starting the VM

The VM image is quite large, so ask the rest of the team for its URL.

Once you've downloaded and extracted the VM archive, you'll need to install QEMU for your system with your usual package manager (Windows builds are available here).

QEMU options

Then, create one of the following scripts in the same directory as the VM image.

run.bat for Windows:

"%ProgramFiles%\qemu\qemu-system-ppcw.exe" ^
-L pc-bios ^
-M mac99,via=pmu ^
-m 2048 ^
-g 1024x750x32 ^
-device ES1370 ^
-no-reboot ^
-boot c ^
-prom-env "boot-device=hd:,\yaboot" ^
-prom-env "boot-args=conf=hd:,\yaboot.conf" ^
-hda hda-debian8-scummvm-ppc.qcow2

run.sh for macOS and other Unix-like systems:

#!/bin/sh
qemu-system-ppc \
-L pc-bios \
-M mac99,via=pmu \
-m 2048 \
-g 1024x750x32 \
-device ES1370 \
-no-reboot \
-boot c \
-prom-env 'boot-device=hd:,\yaboot' \
-prom-env 'boot-args=conf=hd:,\yaboot.conf' \
-hda hda-debian8-scummvm-ppc.qcow2

Most options should be kept as-is, but you may want to tweak the following ones:

• -m 2048: the amount of memory given to the VM, in megabytes. Using more than 2 GiB is not possible in QEMU at the moment. Moreover, this is a 32-bit system and it wouldn't change the VM performance much.
• -g 1024x750x32: VM screen resolution and bit depth. You can try suiting it to your needs, but strange results may happen with some resolutions, and, since there's no graphics acceleration, making the window too big may worsen performance. Reducing the bit depth from 32 to 24 bits could help in some cases.
• -cdrom /path/to/host/game.iso: this is a quick way of sharing some game or development files from your host to the VM (it will then appear in its file manager). Other file-sharing options between the two systems are possible (see below).

Booting Debian ppc

Then, run that script. A QEMU window should appear, and a Linux system should boot. Wait until a full XFCE desktop appears (this may take a couple of minutes, depending on your host system performance).

Keyboard layout

The keyboard layout can be changed in Applications Menu > Settings > Keyboard > Layout, or with setxkbmap (see also https://wiki.debian.org/Keyboard), if necessary. Default credentials are scummvm / scummvm, since this is just a local development environment.

Building ScummVM in the Debian PPC VM

Open a terminal by clicking on Applications Menu > Terminal Emulator. The password for any sudo command is also scummvm.

If you need to shut down the VM at any point, click on Applications Menu > Log out > Shut Down, and make sure that the VM is completely halted before closing the QEMU window.

Don't expect the included web browser to be remotely useful for anything.

Build dependencies

For development purposes, you may want to install the following set of tools, if they are useful for your use case (note that Valgrind is quite large, though):

sudo apt-get install vim tmux ccache ddd valgrind

Compilers, GNU Make, GDB, Git and SDL development files are already installed in this image. The APT package manager is also pre-configured to use the older Debian 8 archive files. Some Debian 8 GPG keys have expired since then, though, so APT will print some security warnings.

Building

Cloning the repository and compiling ScummVM is done through the usual means, with some important points:

• Everything is going to be slower than your usual environment.
• Since QEMU emulation is single-threaded, there is no point is running make with any -j flag for parallel compilation.
• Some of the external libraries listed in the link above may be too old, or not been available at all in this old Debian release (e.g. libvpx). As of late 2024, the few missing librairies shouldn't cause an issue for the cases covered by big-endian debugging.
• It is highly suggested to only enable the engines and features that you need for your test, e.g. ./configure --disable-gold --disable-detection-full --disable-all-engines --enable-engine=tinsel --disable-lua --disable-tinygl --disable-cloud --disable-hq-scalers --disable-optimizations --enable-debug will save you a lot of time if you're only interested in testing the Tinsel engine.
• It is recommended to disable the use of the Gold linker (and revert to the default, older BFD linker) with the --disable-gold configure flag, because the version included in this old toolchain sometimes triggers internal errors.
• Some tools such as Valgrind become unbearably slow when emulated. --enable-asan is available, but its implementation is from 2015.
• The older 1.2 branch of SDL is used, since rendering is done through an unaccelerated framebuffer at the moment, and SDL1.2 is a better option than SDL2 for this case.

Testing

You can then run the resulting scummvm binary, while making sure that some ScummVM options such as Global Options > Paths > Extra Path are properly configured for development. Then, add your game, and see how it behaves on big-endian! Run gdb on it if necessary, make the appropriate code changes, and iterate with make until it works as expected.

Various options for a more convenient setup

Unmuting audio

If you can't hear any sound, make sure that your QEMU run script has the -device ES1370 option.

It's also possible that the emulated audio card is muted inside the Linux VM, for some reason. To fix this, start the Applications > Multimedia > Audio Mixer program and check that no main output is muted (you can also run the alsamixer program in the Terminal and type M and then Esc to unmute the main output).

Modern IDE integration

If you need a powerful and user-friendly IDE inside the VM, you won't have many options, because this is an old and limited Linux system. If you don't like console text editors, you're probably out of luck (unless you want to try sudo apt-get install codeblocks). One option could be to work from your usual IDE on your regular desktop, and share its files with the VM.

Sharing resources

The VM can access its host system via the 10.0.2.2 IP address (useful if you want to share files from the host to the VM with an NFS, SMB, HTTP, or FTP server).

If you just need to access the VM through SSH:

• add the -nic user,hostfwd=tcp::60022-:22 option to your qemu-system-ppc script
• inside the VM, install the OpenSSH server: sudo apt-get install openssh-server
• from your host, run: ssh -p 60022 scummvm@127.0.0.1. SSH access means that you can also rsync and so on.

Connecting through VNC is also possible, but it's probably not going to be a great experience.

Reclaiming some storage space

If you need a bit more storage space inside the VM, some big and unnecessary tools can be removed:

sudo apt-get remove --purge 'vlc.*' 'libreoffice.*' 'gimp.*' 'firefox.*' 'iceweasel.*'
sudo apt-get autoremove --purge

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 an 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.