Difference between revisions of "HOWTO-Debug-Endian-Issues"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Add first draft version of Debug-Endian-Issues HOWTO)
 
(Update second draft of HOWTO on Debugging Endian Issues.)
Line 1: Line 1:
As most desktop machines are now little-endian i.e. x86, debugging endian bugs is difficult.<br>
+
As most desktop machines are now Little-Endian i.e. x86, debugging endian bugs is becoming difficult.<br>
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.
+
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.
 
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 by using a virtual machine software package to emulate a machine with a different endian CPU to the host system.
+
This page details a solution to this.
  
== QEMU ==
+
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.
  
* [http://www.qemu.org Main Website]
+
Of the open source VM packages available, [https://www.virtualbox.org/ 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.
* [http://lassauge.free.fr/qemu/ Win32 Builds]
+
 
* [http://people.debian.org/~aurel32/qemu/powerpc/ Prebuild Debian PPC QEMU Images]
+
However, it is derived from [http://www.qemu.org 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: <pre>apt-get install qemu</pre>
 +
** Win32: Precompiled builds for Win32 are available from [http://lassauge.free.fr/qemu/ here].
 +
** OSX: This is packaged with an OSX GUI as the Q Emulator available from [http://www.kju-app.org/ here].
 +
** For all other systems, source code be downloaded from [http://www.qemu.org here]. Refer to your system and QEMU's documentation for help on compiling and installing this.
 +
* Configure QEMU to emulate a PPC machine.
 +
* Install a PPC Linux distribution onto the QEMU PPC VM.
 +
** [http://people.debian.org/~aurel32/qemu/powerpc/ Prebuild Debian PPC QEMU Images]
 +
* Install the ScummVM source code, required libraries and compile a debug build.
 +
* Install debugging tools.
  
 
== GXemul ==
 
== GXemul ==
  
 
* [http://gxemul.sourceforge.net/ Main Website]
 
* [http://gxemul.sourceforge.net/ Main Website]

Revision as of 05:00, 26 November 2012

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.
  • Install a PPC Linux distribution onto the QEMU PPC VM.
  • Install the ScummVM source code, required libraries and compile a debug build.
  • Install debugging tools.

GXemul