News :: Guest Column - Running GCW Zero applications with QEMU

Date: 2015-05-11, Author: Dmitry Smagin, Editors: Zear & Surkow
GCW Zero developer Dmitry Smagin has released pre-compiled binaries of OpenDingux for QEMU (short for Quick Emulator), a popular free and open-source multi-architecture emulator and hypervisor. In this article Dmitry explains how he managed to run OpenDingux, an operating system for the GCW Zero handheld, on top of the MIPS Malta board emulation in QEMU. It supports running native software for the GCW Zero on your PC, remote debugging via telnet, SSH and file transfers via FTP and SFTP. Lack of GPU emulation means software relying on GLES will not work.

Preamble

Strictly speaking this is not GCW Zero hardware emulation but rather emulation of the OpenDingux environment on top of different hardware that can run native applications for the GCW Zero.

The closest analogy would be running the same executable on the same operating system (on identical CPU architecture) but on different sets of hardware. Modern x86-based laptops may have different combinations of video, sound and network hardware with various degree of acceleration, but the same game executable runs on all its combinations.

In the same manner Raspberry Pi's debian-based operating system Raspbian is emulated on top of the ARM Versatile board in QEMU.

Features

It supports running native software for the GCW Zero on your PC, remote debugging via telnet, SSH and file transfers via FTP and SFTP.

Bugs and missing features

The biggest missing feature is the lack of GPU emulation (Vivante GC860), so there's no OpenGL ES, SDL2 or Love2D. Applications that rely on OpenGL ES or SDL2 will not run, because these libraries are omitted from the rootfs used in this package. Luckily, the majority of the applications still use software rendering.

Malta board uses the cirrusfb video driver which does not support vertical sync, nor double or triple buffering. Applications that rely on these features will still run fine, though frame rates may differ from what you expect to have on real hardware. Note that QEMU performs double-buffering itself which means you would hardly notice any tearing or flickering.

Moreover, there's no IPU (hardware up/downscaling), but it's not really needed. If an application requests a resolution that is different from 320x240, the cirrusfb video driver sets it as requested with no resizing. However, QEMU itself has its own resizing mechanism, so you can stretch your window to whatever size you desire thus simulating IPU behavior.

The other missing hardware include the analog joystick, g-sensor and rumble motor.

As for the network, there's no Wi-Fi (wlan) and ethernet via USB (usb0) but you have eth0 instead. Debugging could be done via serial port output which is redirected to console on Linux and to PuTTY or similar programs on Windows.

Another missing feature that should be named is the lack of MXU instructions which is an extension specific to Ingenic JZ47xx SoCs. QEMU emulates a generic MIPS 24Kc cpu which is mips32r2 with hardware float. Luckily for us, very few programs (if any) use MXU.

As for the sound, the AC97 audio driver strictly follows the rule to have a sample buffer of power of 2 (256, 512, 1024 etc) and if SDL (or any other library) requests an arbitrary size, it just returns an error. This is somewhat different from the GCW Zero, where the hardware doesn't apply such restrictions and SDL can use any sample buffer size. This concerns Minislug, for example, which tries to set up sound buffer of 1088 samples which works on a real device and fails in QEMU.

However, for true cross-platform compatibility all SDL applications must use a power of 2 for the sample buffer. Most applications follow the rule and still run fine.

Note that after boot the sound is muted. To enable it go to Settings -> Sound Mixer, unmute all channels and raise volume to the maximum.

Running QEMU

If you are on Windows, download QEMU from here and unpack to the desired location. If you are on Linux install QEMU from your distro repository. At the time of writing the last official version of QEMU is 2.2.0 but no harm is done if an earlier version is used, at least 1.3.1 is confirmed to work.

Unpack the provided archive to the same directory and click run-gcw0.bat for Windows or run-gcw0.sh for Linux (don't forget to make it executable with chmod +x run-gcw0.sh before running). After a short period of time you'll see gmenu2x running inside QEMU and you can begin testing some pre-installed games.

Key mapping

QEMU emulates a normal PS/2 keyboard and the GCW Zero keys are mapped as follows:

Arrow keys
D-PAD
Left Ctrl
A
Left Alt
B
SPACE
Y
Left Shift
X
Left Ctrl
A
TAB
Left Shoulder
Backspace
Right Shoulder
Escape
Select
Enter
Start

Please keep the key mappings in mind when developing, otherwise you'll happen to use some key that is unavailable on a real GCW Zero.

Network and adding more .OPK packages via SFTP

Note: if your host system is Windows, please refer to this article to properly set up PuTTY to catch serial output from QEMU. Without it you can pretty much do nothing.

On Linux just run run-gcw0.sh from the console and you'll see the kernel boot log directly appear in your console which should end with a command prompt.

Now you can enter commands and do various kinds of things that Linux can do. QEMU's network for the guest system is set to work in so-called user mode when guest and host systems are seen as one network entity to the outside world and interaction between them is limited. However, you can use SSH/SFTP/wget from guest to access remote servers and even your host machine (note: the latter only works for Linux, please contact me if you know how to do it for Windows).

Execute sftp your_host_user_name@10.0.2.2, enter your password and you are inside your host! Now you can browse the filesystem and download OPK files with the get filename command.

Note that connecting from host to guest is not possible with current QEMU settings. It is possible to set up a tun/tap interface and bridge but this is fairly complex and isn't part of this article.

More user-friendly way to add .OPK packages via virtual FAT disk

QEMU has an interesting feature to create virtual FAT disks using any host directory, but its contents should not exceed 512MB. All you have to do is create any directory, put any .OPKs there and edit either run-gcw0.bat or run-gcw0.sh and append the following option to the final line which calls QEMU with parameters:

-hdc fat:rw:your_dir_name

Then run QEMU, start DinguxCommander, browse to /media/QEMU VVFAT and copy all needed files to /media/data/apps.

The undoubtful advantage is that you don't have to use the command line console at all. Note that you have to be careful when writing anything to a virtual FAT partition. File system writes are asynchronous so files do not immediately appear in your host directory when the guest finishes writing. Just wait a little and files will appear.

Downloads

Pre-compiled OpenDingux package for QEMU can be downloaded here. It contains kernel and filesystem images with running scripts for both Windows and Linux platforms.

Note that you have to download and Install QEMU separately. Windows binaries can be downloaded here.

Questions & Answers