Skip to main content

Launching PolyOS Mobile with QEMU

PolyOS ❤️ QEMU, This guide will gracefully steer you toward launching PolyOS Mobile using the esteemed QEMU virtualization tool.

QEMU is a widely embraced open-source virtualization software that adeptly simulates the operation of operating systems and applications across distinct platforms. By harnessing the power of QEMU, you can conjure and oversee virtual machines, execute operating systems of varying hardware architectures, perform system snapshots, facilitate live migrations, and expedite the execution of virtualization tasks, making it a sagacious choice for inaugurating PolyOS Mobile.

Preface​

Prerequisites​

In the preliminary phase, to ensure the efficiency and gratifying user experience of PolyOS Mobile, ascertain your ability to allocate and satisfy the ensuing minimum requisites for your PolyOS Mobile virtual machine.

  1. CPU: 4 cores, 8 threads;
  2. Memory: 8 Gib of memory;
  3. Operating System:
    • Ubuntu 20.04, 22.04
    • Windows 10/11
note

During the composition of this article, the test environment utilized is a physical machine equipped with an i7-10700 CPU @ 2.90GHz, accompanied by 16 GiB of memory.

Launching PolyOS Mobile: Step by Step​

The majestic commencement of PolyOS Mobile on your computing apparatus merely necessitates 3 well-orchestrated steps:

  1. Installation of the QEMU renaissance distributed by the PolyOS community;
  2. The act of unraveling the image;
  3. The grand inauguration of PolyOS Mobile!

What follows is an elaborate elucidation of the meticulous steps to be undertaken on both Ubuntu and Windows platforms.

QEMU's Support Status​

AttributesUbuntuWindows
Graphics✅✅
Audio✅✅
Networing✅✅
Mouse✅✅
Keyboard✅✅
Camera✅🔲
Physical Key Emulation✅✅

Commencing on Ubuntu​

note

The contents of this section have undergone rigorous testing on Ubuntu 20.04 and are anticipated to function seamlessly on subsequent versions such as 21.04, 21.10, and 22.04. Please change /path/to into your local installation path in the following code cases.

QEMU Installation​

The esteemed PolyOS community extends pre-built QEMU packages for Ubuntu. Imbued with simplicity, the installation of PolyOS community-revitalized QEMU is facilitated through the dpkg package manager.

Engage the button below to acquire the PolyOS official site-endowed QEMU pre-built package.

Download QEMU

With the download secured, execute the subsequent command to sanctify QEMU's installation:

sudo dpkg -i /path/to/polyos-qemu-riscv64-7.1.0-1.x86_64.deb

The pantheon of QEMU will be enshrined within the hallowed halls of the /opt/qemu-7.1.0 directory.

caution

Prudent vigilance necessitates the assurance of the existence of a select set of dependencies:

sudo apt-get install libpixman-1-0 libepoxy0 libv4l-0 libpng16-16 \
                     libsdl2-2.0-0 libsdl2-image-2.0-0 libglib2.0-0 \
                     libasound2 libpulse0 osspd-alsa \
                     libusb-1.0-0 \
                     libncursesw5 \
                     libgtk-3-0 libgdk-pixbuf2.0-0 \
                     libx11-6

(Optional) Configuration of QEMU Environment​

An opulent choice presents itself: you may opt to ensconce /opt/qemu-7.1.0 within the realm of your environmental variables.

cat << EOF >> ~/.bashrc
export PATH=/opt/qemu-7.1.0/bin:$PATH
EOF
source ~/.bashrc

Unveiling the PolyOS Mobile Image​

Before the unshackling of the image of PolyOS Mobile, ensure that you possess the proper PolyOS Mobile image. Should the image be absent, navigate to Get PolyOS Mobile.

Commandeer the tar invocation to unfurl the visage of PolyOS Mobile:

tar -Jxvf /path/to/polyos-mobile-latest.img.tar.xz
info

Clarification of the Image Files:

  • updater.img: Image for system updates, encompassing scripts and binaries for system updates.
  • system.img: Immutable image of the initial system, featuring system libraries.
  • vendor.img: Directory of HDF driver platform files.
  • userdata.img: Image for the initial data partition, destined for mounting at /data.
  • kernel.img: Binary kernel image of PolyOS Mobile.
  • ramdisk.img: Image for the boot partition. This is a subset of the system image, mounted before the kernel mounts system.img, typically including binaries and initialization scripts.

Initiating PolyOS Mobile​

You have the option to elegantly initiate PolyOS Mobile by employing an initialization script that is conveniently nestled within the image file.

sh /path/to/qemu_riscv64_run_linux.sh

Initiating PolyOS Mobile on Windows​

note

The content of this section has undergone rigorous testing on Windows 10 22H1 and is expected to function seamlessly on subsequent build versions beyond 22H1, as well as Windows 11.

QEMU Installation​

The esteemed PolyOS community extends pre-built QEMU packages for the Windows realm. Please change /path/to into your local installation path in the following code cases.

You have the option to gracefully obtain the PolyOS community-endowed QEMU pre-built package by engaging the button below.

Download QEMU

Upon the package's acquisition, you are invited to partake in the ritual of a double-click on the .exe file, thus embarking upon an installation adorned with simplicity. QEMU, by default, shall find its abode within the hallowed halls of the C:\Program Files\PolyOS QEMU directory.

(Optional) Configuration of the QEMU Environment​

You have the option to bestow upon yourself an elevated computing experience by admitting C:\Program Files\PolyOS QEMU into the sacred realm of your environmental variables.

$env:Path = "C:\Porgram Files\PolyOS QEMU" + $env:Path
[Environment]::SetEnvironmentVariable("Path", $env:Path, "Machine")
tip

If the above code reports an error during execution, make sure you have run PowerShell as an administrator and re-execute the command.

Unveiling the PolyOS Mobile Image {#extract-images-on-windows} Before unfurling the image of PolyOS Mobile, kindly ensure that you possess the appropriate PolyOS Mobile image. Should this image be absent, it is recommended to navigate to Get PolyOS Mobile.

The unveiling of the PolyOS Mobile image can be achieved through the judicious invocation of the tar command:

tar -Jxvf /path/to/polyos-mobile-latest.img.tar.xz
info

In the event that your computing apparatus lacks the tar command, one is advised to obtain decompression support for tar files through the installation of 7-zip.

Initiating PolyOS Mobile​

You have the option to directly commence PolyOS Mobile by employing an initialization script, which is conveniently embedded within the image file.

/path/to/qemu_riscv64_run_windows.ps1
tip

If the above script reports an error during execution, it is possible that your system is preventing the script from running. Please make sure you have run PowerShell as an administrator, then type set-executionpolicy remotesigned to execute the policy change, then re-execute the script.

Launching PolyOS Mobile On Mac OS​

note

We tested on Mac OS 13.5.1 with M1 chip. It should also work on other version.

Install QEMU​

It's very simple to install qemu using homebrew.You can refer to thisLink for more information about homebrew.

brew install qemu

QEMU will be installed to brew default folder. Use the following command to check its path.

brew --prefix

Here we installed into path /opt/homebrew/Cellar/qemu/8.1.0_1/

(Optional)Configure QEMU Environment​

You can add /opt/homebrew/Cellar/qemu/8.1.0_1/ to your PATH environment。

cat << EOF >> ~/.bashrc
export PATH=/opt/homebrew/Cellar/qemu/8.1.0_1/bin:$PATH
EOF
source ~/.bashrc

Unveiling the PolyOS Mobile Image​

Before the unshackling of the image of PolyOS Mobile, ensure that you possess the proper PolyOS Mobile image. Should the image be absent, navigate to Get PolyOS Mobile.

Commandeer the tar invocation to unfurl the visage of PolyOS Mobile:

tar -Jxvf /path/to/polyos-mobile-latest.img.tar.xz
info

Clarification of the Image Files:

  • updater.img: Image for system updates, encompassing scripts and binaries for system updates.
  • system.img: Immutable image of the initial system, featuring system libraries.
  • vendor.img: Directory of HDF driver platform files.
  • userdata.img: Image for the initial data partition, destined for mounting at /data.
  • kernel.img: Binary kernel image of PolyOS Mobile.
  • ramdisk.img: Image for the boot partition. This is a subset of the system image, mounted before the kernel mounts system.img, typically including binaries and initialization scripts.

Start PolyOS Mobile​

You can use /opt/homebrew/Cellar/qemu/8.1.0_1/bin/qemu-system-riscv64 command to start PolyOS Mobile.

Copy the following script to a new file named qemu_riscv64_run_mac.sh。

You can change cpus and memory based on your Mac. This script is different with that for Linux.

cpus=4
memory="4096M"

image_path=$PWD

sudo /opt/homebrew/Cellar/qemu/8.1.0_1/bin/qemu-system-riscv64 \
    -name PolyOS-Mobile \
    -machine virt \
    -m ${memory} \
    -smp ${cpus} \
    -no-reboot \
    -netdev user,id=net0 \
    -device virtio-net-device,netdev=net0,mac=12:22:33:44:55:66 \
    -drive if=none,file=${image_path}/updater.img,format=raw,id=updater,index=3 \
    -device virtio-blk-device,drive=updater \
    -drive if=none,file=${image_path}/system.img,format=raw,id=system,index=2 \
    -device virtio-blk-device,drive=system \
    -drive if=none,file=${image_path}/vendor.img,format=raw,id=vendor,index=1 \
    -device virtio-blk-device,drive=vendor \
    -drive if=none,file=${image_path}/userdata.img,format=raw,id=userdata,index=0 \
    -device virtio-blk-device,drive=userdata \
    -append "loglevel=1 console=ttyS0,115200 init=init root=/dev/ram0 rw rootwait ohos.boot.hardware=riscv64_virt default_boot_device=10007000.virtio_mmio sn=8823456789 ohos.required_mount.system=/dev/block/vdb@/usr@ext4@ro,barrier=1@wait,required ohos.required_mount.vendor=/dev/block/vdc@/vendor@ext4@ro,barrier=1@wait,required ohos.required_mount.data=/dev/block/vdd@/data@ext4@nosuid,nodev,noatime,barrier=1,data=ordered,noauto_da_alloc@wait,reservedsize=104857600" \
    -kernel ${image_path}/Image \
    -initrd ${image_path}/ramdisk.img \
    -vga none \
    -vnc :9920 \
    -device virtio-gpu-pci,xres=486,yres=864,max_outputs=1,addr=08.0 \
    -monitor telnet:127.0.0.1:55556,server,nowait \
    -device virtio-mouse-pci \
    -device virtio-keyboard-pci \
    -device ac97 \
    -k en-us \
    -display cocoa
  
exit

Connecting​

Use telnet to connect to the emulator.

telnet 127.0.0.1 55556

With commend help you can see a list of useful commands.

We use info vnc command to find out the port number of vnc server.

(qemu) info vnc
default:
  Server: :::15820 (ipv6)
    Auth: none (Sub: none)
(qemu) info

Using a VNC Viewer, you will see the desktop UI after connecting. Check you ip using ifconfig to find out the emulator IP.

Troubleshooting​

Disabling the Camera​

The camera is activated through the registration of a new device within the QEMU simulator. To disable or enable the camera, you can locate the --device virtio-camera-device,v4ldev=/dev/video parameter within the startup configuration.

Camera Performance Issues​

The camera functionality imposes significant demands on system performance. It is advisable to temporarily allocate additional CPU resources for optimal performance.

Disabling Physical Button Emulation​

The emulation of physical buttons is achieved through the utilization of the GTK framework. To disable physical button emulation, you can replace the gtk option in the startup parameters with sdl.

-display gtk,gl=off
  => -display sdl,gl=off

High Mouse Latency​

High latency in mouse movement can lead to suboptimal fluidity. To mitigate this, consider reducing your computer's display resolution.

caution

When the resolution is excessively low, physical button emulation may cease to function, resulting in a black screen.

Affected resolutions: 360x720 and below.