News :: Guest Column - Running GCW Zero applications with QEMU
Date: 2015-05-11, Author: Dmitry Smagin, Editors: Zear & SurkowGCW 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.
Running gmenu2x in QEMU.
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.
System Info overview.
Note that sound is disabled after boot and you have to raise the volume manually in Alsa mixer.
FreeDoom running in QEMU.
WetSpot 2 running in QEMU.
Key mapping
QEMU emulates a normal PS/2 keyboard and the GCW Zero keys are mapped as follows:
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.
How the network is seen by Network Settings
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
- Q: What operating systems does QEMU support?A: Windows, Linux, MacOS X or anything that can run QEMU images. Only Windows and Linux are properly tested though.
- Q: So, is this a GCW Zero emulator?A: No, QEMU does not emulate the CPU of GCW Zero (Ingenic JZ4770 SoC) or any other of its hardware components. It simply allows you to run the GCW Zero software on a different, emulated MIPS platform (general MIPS 24Kc cpu on Malta board). It is thus not comparable to the real hardware and should never be used for any performance testing of GCW Zero software.
- Q: Who is this package addressed to?A: This could be useful mostly for testers and developers who would like to taste the things before they acquire the real device, and for those curious ones who would like to see what OpenDingux for GCW Zero looks like.
- Q: With so many differences with a real GCW Zero is this still useful?A: Well, there are many situations when the real handheld is not available but you have to develop or test something and compiling for x86 is not an option. E.g. when your host is Windows and your application uses some linux-specific features that MinGW or Cygwin can't handle. Or, when you are testing the behavior of your application in OpenDingux environment (using correct paths etc). Or, when you are developing an emulator with a MIPS dynarec and that obviously can't be compiled for other architectures.
- Q: Hey, how it's done? Can I create my own OpenDingux images for QEMU?A: Everything is explained step by step in a more technical article here.
- Q: My OPK doesn't start in emulator but it works on real GCW Zero! Why so?A: Most probably you have found another incompatibility. Contact the author and perhaps things could be fixed in the future.
- Q: Hey, I noticed System Info shows only 256MB of RAM, can I have more?A: Well, no, at least for now. Despite the fact that Malta board supports up to 2Gb of RAM, the current kernel lacks proper highmem support for this board. That's why the maximum amount of ram is limited to 256 Megabytes which should be enough for most applications.