Commit 2a4512a1 authored by David Boddie's avatar David Boddie

Merge branch 'link-indirectly-to-a-qemu-image' into 'master'

Update qemu instructions

See merge request !421
parents e62a3e52 a4aa3867
Pipeline #61282 passed with stages
in 1 minute and 25 seconds
......@@ -5,13 +5,15 @@ QEMU
An experimental QEMU image is available that includes:
- phosh: phone graphical shell
- Common apps: geary, epiphany, contacts, calls
- phone / network services: NetworkManager, ModemManager, ...
- Phosh: the phone graphical shell
- Common apps: Geary, Epiphany, Contacts, Calls, etc.
- Phone/network services: NetworkManager, ModemManager, etc.
Linux Environments
------------------
First, obtain a disk image for your workstation. The `most recent qcow2 image for x86_64`_ should be suitable for most users. If that is not available, follow these steps:
1. Go to the `Image Build`_ page on the CI server.
2. Find the most recent successful (green colored) `qemu-x86_64` build in the
......@@ -24,44 +26,42 @@ Linux Environments
(The `qcow2` image can also be built locally using `Librem5 image building
scripts`_.)
3. Install the software required to run it:
You need software to run the image. You can use any virtualization application that will create a VM from a **qcow2** file to run this image.
You can use any virtualization application that will create a VM from a
qcow2 to run this image.
GNOME Boxes
~~~~~~~~~~~
**GNOME Boxes**
On PureOS, `gnome-boxes` is already installed and can be used right away.
Create a new Box from archive selecting qemu-x86_64.qcow2
On PureOS, `gnome-boxes` is already installed and can be used right away. Create a new Box from archive selecting qemu-x86_64.qcow2
**Virt-manager**
On PureOS, you would need to install virt-manager::
Virt-manager
~~~~~~~~~~~~
$ sudo apt install virt-manager
On PureOS, you would need to install virt-manager::
Create a new virtual machine from your archive by selecting qemu-x86_64.qcow2
$ sudo apt install virt-manager
**Command Line**
You can also run the qcow2 image from the command line::
Create a new virtual machine from your archive by selecting qemu-x86_64.qcow2
$ sudo qemu-system-x86_64 -boot menu=on -drive file=qemu-x86_64.qcow2,format=qcow2 -vga virtio -display gtk -m 2G -enable-kvm
Using QEMU on the Command Line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It may be necessary to pass the ``-smp`` option (for example with ``-smp 6``) to improve performance. The ``-display`` option accepts different display types as its parameter -- experimenting with these may prove useful.
You can also run the qcow2 image from the command line::
If you would like to allow ssh connections from the host into the guest system, you may add ``-device e1000,netdev=net0 -netdev user,id=net0,hostfwd=tcp::5555-:22`` to the ``qemu-system-x86_64`` command above. Then, from another terminal window in the host, you can log in with this command::
$ sudo qemu-system-x86_64 -boot menu=on -drive file=qemu-x86_64.qcow2,format=qcow2 -vga virtio -display gtk -m 2G -enable-kvm
$ ssh -p 5555 purism@localhost
It may be necessary to pass the ``-smp`` option (for example with ``-smp 6``) to improve performance. The ``-display`` option accepts different display types as its parameter -- experimenting with these may prove useful.
See the `QEMU documentation`_ for more information.
If you would like to allow ssh connections from the host into the guest system, you may add ``-device e1000,netdev=net0 -netdev user,id=net0,hostfwd=tcp::5555-:22`` to the ``qemu-system-x86_64`` command above. Then, from another terminal window in the host, you can log in with this command::
4. Use the image (password is 123456):
$ ssh -p 5555 purism@localhost
.. image:: images/virt-manager.gif
:align: center
:alt: QEMU VM running phosh
See the `QEMU documentation`_ for more information.
Microsoft Windows
-----------------
First, obtain a disk image for your workstation. The `most recent img.xz image for x86_64`_ should be suitable for most users. If that is not available, follow these steps:
1. Go to the `Image Build`_ page on the CI server.
2. Find the most recent successful (green colored) `qemu-x86_64` build in the
......@@ -69,21 +69,22 @@ Microsoft Windows
page. Clicking on the link for that build will take you to a page containing
a suitable ``qemu-x86_64.img.xz`` image file.
Download the build artifact by right-clicking on the file called
Download the image to a suitable place:
1. Download the build artifact by right-clicking on the file called
``qemu-x86_64.img.xz`` and choosing "Save As".
3. Choose a folder on your computer with 4GB of free space.
2. Choose a folder on your computer with 4GB of free space.
4. After the download is complete, extract the file with 7zip or other untar program.
3. After the download is complete, extract the file with 7zip or other untar program.
5. Open an instance of PowerShell and navigate to the extracted file's folder.
4. Open an instance of PowerShell and navigate to the extracted file's folder.
6. The following command can be executed in PowerShell after modifying the path to the qemu
executable and the path to the downloaded qemu-x86-64.img file.::
5. The following command can be executed in PowerShell after modifying the path to the qemu executable and the path to the downloaded qemu-x86-64.img file.::
C:\Program Files\qemu\qemu-system-x86_64.exe -drive file=c:\downloads\qemu-x86_64.img,index=0,media=disk,format=raw -vga virtio -display sdl,gl=off -m 2G -L Bios -boot menu=on -rtc base=localtime,clock=host -parallel none -serial none -name PureOS -no-reboot
7. Note: You may also download and modify the following PowerShell script for your environment. The file
6. Note: You may also download and modify the following PowerShell script for your environment. The file
can executed on the command line, or by right-clicking launch-librem5.ps1 file from file explorer. The script is
fully commented to explain the command line variables that are used.
......@@ -112,6 +113,7 @@ Now your additional space on ``/dev/vda2`` is immediately ready for use without
Using workstation devices inside the VM
---------------------------------------
You might want to use your workstation's devices to test hardware-specific features within the VM, such as:
- testing the camera API or a camera app using your webcam
......@@ -121,9 +123,8 @@ In such case, you need to redirect the devices of the host machine (i.e. your wo
As an example, let's take a USB webcam. Once you have redirection properly configured, you can test it out by installing and running ``cheese`` within the VM.
Virtual Machine Manager
+++++++++++++++++++++++
~~~~~~~~~~~~~~~~~~~~~~~
#. Run ``virt-manager`` and open the entry for your librem5 VM
#. Click the "i" icon to show the virtual hardware details
......@@ -145,7 +146,8 @@ Virtual Machine Manager
#. You should now see the newly added device listed as 'USB <vendor ID>:<product ID>'
Command Line
++++++++++++
~~~~~~~~~~~~
If you're running the VM manually via the command line instead, you will need to pass the following additional arguments to qemu:
#. An emulated host controller of your choice (e.g. ``qemu-xhci``)
......@@ -162,11 +164,30 @@ To find the the information needed to redirect your device, run ``lsusb``. It wi
Then you can get the vendor ID and product ID from the line corresponding to your device.
Using the Image
---------------
The emulator should boot up to a lock screen. Swipe up to show the passcode entry screen, then log in using the passcode 123456.
.. |phosh-locked| image:: images/phosh-locked-icons.png
:scale: 50%
:alt: The initial lock screen
.. |phosh-passcode-entry| image:: images/phosh-locked-passcode-entry.png
:scale: 50%
:alt: Enter the passcode in the passcode entry screen
.. centered:: |phosh-locked| |phosh-passcode-entry|
You can now start exploring the phone software.
Resources
---------
- repo: https://source.puri.sm/Librem5/image-builder
.. _`most recent qcow2 image for x86_64`: https://developer.puri.sm/status/qcow2-status.html
.. _`most recent img.xz image for x86_64`: https://developer.puri.sm/status/img-status.html
.. _`Librem5 image building scripts`: https://source.puri.sm/Librem5/image-builder
.. _`last successful build`: https://arm01.puri.sm/job/Images/job/Image%20Build/lastSuccessfulBuild/artifact/
.. _`Image Build`: https://arm01.puri.sm/job/Images/job/Image%20Build/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment