OpenMoko under QEMU

From Openmoko

Revision as of 10:59, 17 April 2007 by Jserv (Talk | contribs)

Jump to: navigation, search

QEMU can basically be used in three ways to run OpenMoko. Depending on the purpose that you are going to use the emulator for, you should decide on the target platform.

  • PC - OpenMoko can be built to run on regular i386 hardware, 32- or 64-bit and this is probably the fastest way to get OpenMoko running if you want to get an impression of how it looks. In this scenario QEMU would only serve for isolating your OpenMoko installation from your normal system, or, if you're not on a UNIX system, QEMU provides a non-intrusive way to get Linux up quickly. More information can be found in the FAQ and here.
  • Integrator/CP - this is the default ARM-based machine that QEMU knows about. This target is used with MACHINE="qemuarm" and it is sufficient to run the original OpenMoko rootfs image, although it doesn't emulate any of the Neo1973 Hardware except the CPU. Read more in the FAQ.
  • Neo1973 - the QEMU tree available from OpenMoko repositories is also capable of emulating most of the actual Neo1973 hardware, although not all of it at this moment. It is a work-in-progress and when it's more mature it is going to be submitted for merging to the main QEMU development tree.

Contents

Neo1973 emulation

This target will (obviously) run original OpenMoko rootfs images, but then it should also be able to run the original u-boot and kernel images, the same ones that a real Neo1973 uses. Among other differences you will notice between this approach and the Integrator/CP target is you also get correct screen resolution, some (fake) battery readings, and other goodness. Currently missing parts of the emulator are: GSM modem, AGPS and Bluetooth, as well as the USB slave functionality - these things will still be worked on, as well as general usability. Even with these things missing, QEMU should provide substantial help in debugging kernel and u-boot issues to developers.

What QEMU can *not* be used for, and probably no other emulator can, is speed measures and getting the general feel of OpenMoko performance. Code running in qemu runs with the maximum speed your host computer can provide with an overhead of translating target code to host code, and this overhead is not uniform across different instructions. This means that even if your virtual Neo reports near 100 BogoMIPS (which is the speed of a real Neo), different actions performed in the emulator will not run with the same speed. On most PCs you will notice the virtual Neo running faster than a real one (Audio related operations may be one of the exceptions).

What hardware is supported

Rough status for each of the components that need emulation, following the outline of Neo1973 Hardware page.

Hardware Status Usage notes
S3C2410A Processor
ARM920T core Works Already in mainline QEMU.
Basic guts Work This includes GPIO interface, DMA, Interrupt Controller, Timers, NAND controller, MMC/SD host, I2C and IIS interfaces, Memory & Clock & Power management controllers, RAM.
Serial ports Work Use the "-serial" switch (maybe be specified multiple times) to tell QEMU where serial input/output should go to. GSM module will be connected on UART0.
RTC Works On start QEMU will load it with current time/date - the Neo1973 kernel doesn't use it for time/date source currently.
SPI Works The guest kernel can drive it using either the SPI interface or raw GPIO bitbanging.
LCD Works The virtual LCD will display as in QEMU window iff "-nographic" is not specified.
ADC Works Mouse events in QEMU window generate what would be touchscreen events on a Neo1973 and are passed to the guest OS through the on-chip ADC.
OHCI USB Works This part is in mainline QEMU. Use the "-usb" switch to enable the controller and "usb_add" in QEMU monitor to attach new virtual or physical USB devices.
Slave USB To Do Possibly Linux's dummy HCD in conjunction with gadget filesystem API can be make the virtual Neo appear as a real one connected to your computer. Otherwise different host functions (usbtty, usbnet) could be emulated.
Watchdog To Do This is one of the less important on-chip peripherals in S3C2410. It is however used by Linux for rebooting the board.
I2C bus peripherals
PCF50606 Works (Aka PMU) Fakes the battery charge level (set at 88%), POWER button, etc. Also contains and RTC, also unused by Linux.
LM4857 Works
WM8753L Works The CODEC is also connect to the CPU's IIS port. Basic audio functionality is supported - see QEMU documentation on getting audio input/output from the emulator. Volume control has no effects.
Other peripherals
NAND Flash Works However, some pieces are not confirmed to be completely compatible with the real hardware because of lack thereof. Use "-mtdblock flashimagefilenamehere" switch to point QEMU to your flash image. The file should be at least 69206016 bytes big.
JBT6K74-AS(PI) Works (Aka LCM) Wired to the SPI channel 1
Buttons Work Enter is the AUX button, Space is the POWER button. Wired to on-chip GPIO and PCF50606.
SD card Works This part is already in mainline QEMU. Use the "-sd cardimagegoeshere" switch to point QEMU to the card image. The regular QEMU monitor commands for removable media can also be used. The card works, however the on-chip host controller gave block length errors on heavy I/O despite working as described in specification. I suspect the kernel driver. DMA operation is not tested.
Bluetooth To Do Will require implementing the Delta DBFM chip and connecting it to USB. The ROM will likely be replaced with code to translate communication directly to TCP/UDP networking (like Slirp). A real bluetooth dongle can also be attached to the emulator (see USB documentation in QEMU).
GSM In Progress A fake modem will be connected to UART0 with as much functionality as possible (basic AT commands understanding, fake GPRS connections and SMS send/receive). This way all parts of the phone subsystem (CALYPSO, TWL3014, TRF6151) will not have to be emulated. There is a possibility to wire a real GSM modem to QEMU's serial port.
AGPS To Do There are obvious difficulties emulating the chip, but hopefully it can be made to present the guest OS with some fixed coordinates later when more is known about the chip. Again a real chip could be connected to QEMU's serial port.

How to get it running

Using MokoMakefile

This is the recommended way since you won't need to deal with the compiling and flashing processes yourself. See MokoMakefile for details.

Building the environment manually

To obtain the latest source code for the emulator, you will want to do something like the following:

$ svn checkout https://svn.openmoko.org/trunk/src/host/qemu-neo1973
$ cd qemu-neo1973

Now, we're going to configure and build the emulator:

$ ./configure --target-list=arm-softmmu  # GCC 3.x will be required
$ make

See other available options for the configure script by appending "--help". Now you have should have a working emulator under the name "arm-softmmu/qemu-system-arm". To run OpenMoko you will also need to somehow install OpenMoko on your virtual phone, which is totally clean of any software at this moment. There are several block devices to choose from, the best option is probably to do exactly what the Neo1973 manufacturer does before it ships the device to the final user. This process is described in Bootloader, Kernel, NAND bad blocks and Devirginator but you don't need to know all the details. Two scripts are provided to generate a firmware for your phone, as realistic as possible. First, run

$ openmoko/download.sh

which will look up the list of latest available OpenMoko snapshot builds from buildhost.openmoko.org and choose the most recent u-boot, Kernel, and root filesystem images, and download the images (unless they are already found in the openmoko/ directory). These binaries will be used by the next command:

$ openmoko/flash.sh

which runs the emulator, loads u-boot into it and then uses u-boot's capability to program the Flash memory to install all the necessary parts of the system into the virtual Flash. It will also set up all the bootloading process including a boot menu, splash, u-boot environment and some default kernel parameters. If everything goes OK, the script should print a command which you can use to start using the emulator.

QEMU has *tons* of commandline switches and things that can be configured. You can look them up in QEMU user docs. You will probably want to use the "-snapshot" switch, among other ones.

Requirements

The QEMU tree has only been tested on GNU/Linux. To get graphical and/or audio output from the emulator you will need SDL installed on your computer. To enable audio, see the available switches to the ./configure script. All of the requirements listed in QEMU documentation apply.

QEMU and GNU debugger

QEMU lets you debug operating system kernels and bootloaders like you debug all other programs. To do this you will need a debugger that speaks the GDB remote debugging protocol - GDB is the obvious choice. Some cross toolchains come with GDB already set up. Otherwise building cross-GDB yourself is quick and easy (compared to building binutils and cross-gcc).

To debug u-boot, load the file "u-boot" into gdb (not "u-boot.bin") that is produced by "make" when building u-boot. To debug a Linux kernel, load the file "vmlinux" from the main source directory into gdb. These files are in ELF format and contain all the symbol information and are not stripped of debugging data until you run "strip" on them, unlike "u-boot.bin" and "Image"/"zImage"/"uImage". Next, tell QEMU to enable the gdbserver by appending the "-s" switch or issuing "gdbserver" in the monitor. Use the command
(gdb) target remote localhost:1234
to make a connection to the emulator. From there you should be able to use all the usual GDB commands, including stepping instructions, setting breakpoints, watchpoints, inspecting stack, variables, registers and more. If gdb is running in the same directory from which it grabbed the ELF executable, the "edit" command should work so you can jump right to the source line which is executing.

Pre-built binaries

Win32 binaries shipped with firmware could be downloaded: openmoko-emulator-win32-bin-20070416.zip. Tested on Windows XP. Screenshot: OpenMoko emulator running on Windows XP

Personal tools

QEMU can basically be used in three ways to run OpenMoko. Depending on the purpose that you are going to use the emulator for, you should decide on the target platform.

  • PC - OpenMoko can be built to run on regular i386 hardware, 32- or 64-bit and this is probably the fastest way to get OpenMoko running if you want to get an impression of how it looks. In this scenario QEMU would only serve for isolating your OpenMoko installation from your normal system, or, if you're not on a UNIX system, QEMU provides a non-intrusive way to get Linux up quickly. More information can be found in the FAQ and here.
  • Integrator/CP - this is the default ARM-based machine that QEMU knows about. This target is used with MACHINE="qemuarm" and it is sufficient to run the original OpenMoko rootfs image, although it doesn't emulate any of the Neo1973 Hardware except the CPU. Read more in the FAQ.
  • Neo1973 - the QEMU tree available from OpenMoko repositories is also capable of emulating most of the actual Neo1973 hardware, although not all of it at this moment. It is a work-in-progress and when it's more mature it is going to be submitted for merging to the main QEMU development tree.

Neo1973 emulation

This target will (obviously) run original OpenMoko rootfs images, but then it should also be able to run the original u-boot and kernel images, the same ones that a real Neo1973 uses. Among other differences you will notice between this approach and the Integrator/CP target is you also get correct screen resolution, some (fake) battery readings, and other goodness. Currently missing parts of the emulator are: GSM modem, AGPS and Bluetooth, as well as the USB slave functionality - these things will still be worked on, as well as general usability. Even with these things missing, QEMU should provide substantial help in debugging kernel and u-boot issues to developers.

What QEMU can *not* be used for, and probably no other emulator can, is speed measures and getting the general feel of OpenMoko performance. Code running in qemu runs with the maximum speed your host computer can provide with an overhead of translating target code to host code, and this overhead is not uniform across different instructions. This means that even if your virtual Neo reports near 100 BogoMIPS (which is the speed of a real Neo), different actions performed in the emulator will not run with the same speed. On most PCs you will notice the virtual Neo running faster than a real one (Audio related operations may be one of the exceptions).

What hardware is supported

Rough status for each of the components that need emulation, following the outline of Neo1973 Hardware page.

Hardware Status Usage notes
S3C2410A Processor
ARM920T core Works Already in mainline QEMU.
Basic guts Work This includes GPIO interface, DMA, Interrupt Controller, Timers, NAND controller, MMC/SD host, I2C and IIS interfaces, Memory & Clock & Power management controllers, RAM.
Serial ports Work Use the "-serial" switch (maybe be specified multiple times) to tell QEMU where serial input/output should go to. GSM module will be connected on UART0.
RTC Works On start QEMU will load it with current time/date - the Neo1973 kernel doesn't use it for time/date source currently.
SPI Works The guest kernel can drive it using either the SPI interface or raw GPIO bitbanging.
LCD Works The virtual LCD will display as in QEMU window iff "-nographic" is not specified.
ADC Works Mouse events in QEMU window generate what would be touchscreen events on a Neo1973 and are passed to the guest OS through the on-chip ADC.
OHCI USB Works This part is in mainline QEMU. Use the "-usb" switch to enable the controller and "usb_add" in QEMU monitor to attach new virtual or physical USB devices.
Slave USB To Do Possibly Linux's dummy HCD in conjunction with gadget filesystem API can be make the virtual Neo appear as a real one connected to your computer. Otherwise different host functions (usbtty, usbnet) could be emulated.
Watchdog To Do This is one of the less important on-chip peripherals in S3C2410. It is however used by Linux for rebooting the board.
I2C bus peripherals
PCF50606 Works (Aka PMU) Fakes the battery charge level (set at 88%), POWER button, etc. Also contains and RTC, also unused by Linux.
LM4857 Works
WM8753L Works The CODEC is also connect to the CPU's IIS port. Basic audio functionality is supported - see QEMU documentation on getting audio input/output from the emulator. Volume control has no effects.
Other peripherals
NAND Flash Works However, some pieces are not confirmed to be completely compatible with the real hardware because of lack thereof. Use "-mtdblock flashimagefilenamehere" switch to point QEMU to your flash image. The file should be at least 69206016 bytes big.
JBT6K74-AS(PI) Works (Aka LCM) Wired to the SPI channel 1
Buttons Work Enter is the AUX button, Space is the POWER button. Wired to on-chip GPIO and PCF50606.
SD card Works This part is already in mainline QEMU. Use the "-sd cardimagegoeshere" switch to point QEMU to the card image. The regular QEMU monitor commands for removable media can also be used. The card works, however the on-chip host controller gave block length errors on heavy I/O despite working as described in specification. I suspect the kernel driver. DMA operation is not tested.
Bluetooth To Do Will require implementing the Delta DBFM chip and connecting it to USB. The ROM will likely be replaced with code to translate communication directly to TCP/UDP networking (like Slirp). A real bluetooth dongle can also be attached to the emulator (see USB documentation in QEMU).
GSM In Progress A fake modem will be connected to UART0 with as much functionality as possible (basic AT commands understanding, fake GPRS connections and SMS send/receive). This way all parts of the phone subsystem (CALYPSO, TWL3014, TRF6151) will not have to be emulated. There is a possibility to wire a real GSM modem to QEMU's serial port.
AGPS To Do There are obvious difficulties emulating the chip, but hopefully it can be made to present the guest OS with some fixed coordinates later when more is known about the chip. Again a real chip could be connected to QEMU's serial port.

How to get it running

Using MokoMakefile

This is the recommended way since you won't need to deal with the compiling and flashing processes yourself. See MokoMakefile for details.

Building the environment manually

To obtain the latest source code for the emulator, you will want to do something like the following:

$ svn checkout https://svn.openmoko.org/trunk/src/host/qemu-neo1973
$ cd qemu-neo1973

Now, we're going to configure and build the emulator:

$ ./configure --target-list=arm-softmmu  # GCC 3.x will be required
$ make

See other available options for the configure script by appending "--help". Now you have should have a working emulator under the name "arm-softmmu/qemu-system-arm". To run OpenMoko you will also need to somehow install OpenMoko on your virtual phone, which is totally clean of any software at this moment. There are several block devices to choose from, the best option is probably to do exactly what the Neo1973 manufacturer does before it ships the device to the final user. This process is described in Bootloader, Kernel, NAND bad blocks and Devirginator but you don't need to know all the details. Two scripts are provided to generate a firmware for your phone, as realistic as possible. First, run

$ openmoko/download.sh

which will look up the list of latest available OpenMoko snapshot builds from buildhost.openmoko.org and choose the most recent u-boot, Kernel, and root filesystem images, and download the images (unless they are already found in the openmoko/ directory). These binaries will be used by the next command:

$ openmoko/flash.sh

which runs the emulator, loads u-boot into it and then uses u-boot's capability to program the Flash memory to install all the necessary parts of the system into the virtual Flash. It will also set up all the bootloading process including a boot menu, splash, u-boot environment and some default kernel parameters. If everything goes OK, the script should print a command which you can use to start using the emulator.

QEMU has *tons* of commandline switches and things that can be configured. You can look them up in QEMU user docs. You will probably want to use the "-snapshot" switch, among other ones.

Requirements

The QEMU tree has only been tested on GNU/Linux. To get graphical and/or audio output from the emulator you will need SDL installed on your computer. To enable audio, see the available switches to the ./configure script. All of the requirements listed in QEMU documentation apply.

QEMU and GNU debugger

QEMU lets you debug operating system kernels and bootloaders like you debug all other programs. To do this you will need a debugger that speaks the GDB remote debugging protocol - GDB is the obvious choice. Some cross toolchains come with GDB already set up. Otherwise building cross-GDB yourself is quick and easy (compared to building binutils and cross-gcc).

To debug u-boot, load the file "u-boot" into gdb (not "u-boot.bin") that is produced by "make" when building u-boot. To debug a Linux kernel, load the file "vmlinux" from the main source directory into gdb. These files are in ELF format and contain all the symbol information and are not stripped of debugging data until you run "strip" on them, unlike "u-boot.bin" and "Image"/"zImage"/"uImage". Next, tell QEMU to enable the gdbserver by appending the "-s" switch or issuing "gdbserver" in the monitor. Use the command
(gdb) target remote localhost:1234
to make a connection to the emulator. From there you should be able to use all the usual GDB commands, including stepping instructions, setting breakpoints, watchpoints, inspecting stack, variables, registers and more. If gdb is running in the same directory from which it grabbed the ELF executable, the "edit" command should work so you can jump right to the source line which is executing.

Pre-built binaries

Win32 binaries shipped with firmware could be downloaded: openmoko-emulator-win32-bin-20070416.zip. Tested on Windows XP. Screenshot: OpenMoko emulator running on Windows XP