QEMUx86 Emulator for Linux

Version added 28-Jun-2018| Modified 15-Oct-2018

webOS Open Source Edition (OSE) provides an emulator that enables you to test the webOS OSE application and platform on a virtual environment. With the emulator, you can test major features of webOS OSE on your PC without a physical device such as Raspberry Pi.

The emulator is based on the open source QEMU project. Currently, the emulator only supports the x86 (x86_64) machine architecture and Linux Ubuntu operating system as a host. For more information on system requirements and features of the emulator, refer to the Release Notes.

To use the emulator, you must take the following steps:

Building the webOS OSE Image for QEMUx86

First thing to do is to build the disk image of webOS OSE for QEMUx86. The image will be created as webos-image-qemux86.vmdk.

Prerequisites

Make sure that your system meets the Build System Requirements.

Upgrade all the installed packages to the latest version.

$ sudo apt-get update
$ sudo apt-get upgrade

If Git is not installed, install the package with an -f option to correct a possible broken dependencies.

$ sudo apt-get -f install git

Building the Image

To build the webOS OSE image for QEMUx86, run the following commands one by one. Note that qemux86 is used as a parameter to the mcf command.

$ git clone https://github.com/webosose/build-webos.git
$ cd build-webos
$ sudo scripts/prerequisites.sh
$ ./mcf -p 0 -b 0 qemux86
$ source oe-init-build-env
$ bitbake webos-image

After the build is successfully completed, the resulting image will be created at BUILD/deploy/images/qemux86/webos-image-qemux86.vmdk.

Preparing the Emulator Package

Basically, you can use the pre-built emulator package. However, depending on the version of your Ubuntu or required libraries, you may have trouble running the pre-built emulator package. In that case, you should build a custom emulator package.

Using the Pre-built Emulator Package

To use the pre-built emulator package, download or clone the pre-built emulator package from the GitHub repository.

To clone the pre-built emulator package, enter the following:

$ git clone https://github.com/webosose-emulator/prebuilt-emulator.git

If you have downloaded the package as zip, unzip the package to the location of your choice.

Building a Custom Emulator Package

To build a custom emulator package, you need to build virglrenderer and QEMU, and copy the results to the pre-built emulator package.

Building virglrenderer

virglrenderer is a library that allows graphics rendering by using the host GPU.

Before you begin, upgrade all the installed packages to the latest version and install the dependency packages.

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get -f install git libtool libdrm-dev libepoxy-dev libgbm-dev libegl1-mesa-dev libgtk-3-dev autoconf

To build virglrenderer, run the following commands one by one.

$ git clone git://anongit.freedesktop.org/virglrenderer
$ cd virglrenderer
$ git checkout virglrenderer-0.6.0
$ ./autogen.sh
$ ./configure --with-glx
$ make && sudo make install

Building QEMU

Before you begin, make sure that the virglrenderer package has been built successfully.

After that, upgrade all the installed packages to the latest version and install the dependency packages.

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get -f install libsdl2-dev libpixman-1-dev

To build QEMU, run the following commands one by one.

$ git clone https://github.com/webosose-emulator/qemu.git
$ cd qemu
$ ./configure --target-list=i386-softmmu --enable-sdl --with-sdlabi=2.0 --audio-drv-list=alsa,pa
$ make

Copying the Results to Pre-built Emulator

As the last step, copy the build results to the pre-built emulator package. Note that you must specify a different target directory depending on whether the host operating system is 64-bit or 32-bit.

If you have not cloned or downloaded the package in the previous steps, clone the prebuilt-emulator repository first.

$ git clone https://github.com/webosose-emulator/prebuilt-emulator.git

On 64-bit Ubuntu

Copy the virglrenderer library.

$ cp /usr/local/lib/libvirglrenderer.so* prebuilt-emulator/lib/x86_64

Copy the qemu library.

$ cp <qemu directory path>/i386-softmmu/qemu-system-i386 prebuilt-emulator/bin/x86_64
$ cp -rf pc-bios prebuilt-emulator/bin

On 32-bit Ubuntu

Copy the virglrenderer library.

cp /usr/local/lib/libvirglrenderer.so* prebuilt-emulator/lib/x86

Copy the qemu library.

cp <qemu directory path>/i386-softmmu/qemu-system-i386 prebuilt-emulator/bin/x86
cp -rf pc-bios prebuilt-emulator/bin

Running the Emulator

To run the emulator, refer to the steps below.

Step 1. Establish an environment for running the emulator.

Make sure you have completed the following:

Step 2. Create a JSON configuration file.

By default, the emulator package includes a template for configuration file, webos-config-sample.json. You can create your own configuration file, webos-config.json, from the template by modifying the option values according to your environment.

Create a configuration file from the template, and edit the file.

$ cd <pre-built emulator directory path>
$ mv webos-config-sample.json webos-config.json
$ vi webos-config.json

Change the option values to the ones suitable for your environment. Especially, "vmdk_file_path" must be set to the file path of the built .vmdk image. For example, if build-webos is under your home directory, the path should be set to ~/build-webos/BUILD/deploy/images/qemux86/webos-image-qemux86.vmdk.

For detailed description of all the options in the JSON file, refer to the README file inside the package.

Step 3. Run the emulator.

Use the run script (emulator) to launch the emulator.

$ ./emulator webos-config.json

In case of Ubuntu 18.04, you need to launch the script with sudo command, because of KVM permission.

Connecting to the Emulator

On the host machine, you can connect to the emulator from the shell or from the web browser.

Connecting from the Shell

To connect to the emulator on a Linux shell, use the command below. The port number should match the value set in the portforwarding.SSH option (default: 6622) of JSON configuration file.

$ ssh -p <PortNumber> -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null root@localhost

Connecting from the Web Browser

To connect to the emulator using Web Inspector, connect to "localhost:<PortNumber>" on a web browser (for example, Chrome). The port number should match the value set in the portforwarding.inspector option (default: 9998) of JSON configuration file.

Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.