mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-06-24 14:33:38 +00:00
Documentation: tutorial on how to use Ubuntu as the SOS
Add a tutorial explaining how to use Ubuntu as the Service OS running on ACRN and providing all the device sharing services (devicemodel) and tools to manage virtual machines. Signed-off-by: Geoffroy Van Cutsem <geoffroy.vancutsem@intel.com> Signed-off-by: Ailin Yang <ailin.yang@intel.com>
This commit is contained in:
Geoffroy Van Cutsem
Jack Ren
parent
bf5088eff4
commit
dc135bd501
272
doc/tutorials/using_ubuntu_as_sos.rst
Normal file
272
doc/tutorials/using_ubuntu_as_sos.rst
Normal file
@ -0,0 +1,272 @@
|
||||
.. _Ubuntu Service OS:
|
||||
|
||||
Using Ubuntu as the Service OS
|
||||
##############################
|
||||
|
||||
This document builds on the :ref:`getting_started`, and explains how to use
|
||||
Ubuntu instead of using `Clear Linux`_ as the Service OS with the ACRN
|
||||
hypervisor. (Note that different OSes can be used for the Service and User OS.)
|
||||
In the following instructions we'll build on material in the
|
||||
:ref:`getting-started-apl-nuc`.
|
||||
|
||||
Install Ubuntu (natively)
|
||||
*************************
|
||||
|
||||
Ubuntu 16.04.4 LTS was used throughout this document, other versions such as
|
||||
18.04 may work too.
|
||||
|
||||
* Download Ubuntu 16.04 from the `Ubuntu 16.04.4 LTS (Xenial Xerus) page
|
||||
<https://www.ubuntu.com/download/desktop>`_ and select the `ubuntu-16.04.4-desktop-amd64.iso
|
||||
<http://releases.ubuntu.com/16.04/ubuntu-16.04.4-desktop-amd64.iso>`_ image.
|
||||
|
||||
* Follow Ubuntu's `online instructions <https://tutorials.ubuntu.com/tutorial/tutorial-install-ubuntu-desktop?_ga=2.114179015.1954550575.1530817291-1278304647.1523530035>`_
|
||||
to install it on your device.
|
||||
|
||||
.. note::
|
||||
Configure your device's proxy settings to have full internet access.
|
||||
|
||||
* While not strictly required, enabling SSH gives the user a very useful
|
||||
mechanism for accessing the Service OS remotely or when running one or more
|
||||
User OS (UOS). Follow these steps to enable it on the Ubuntu SOS:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo apt-get install openssh-server
|
||||
sudo service ssh status
|
||||
sudo service ssh start
|
||||
|
||||
Install ACRN
|
||||
************
|
||||
|
||||
ACRN components are distributed in source form, so you'll need to download
|
||||
the source code, build it, and install it on your device.
|
||||
|
||||
1. Install the build tools and dependencies
|
||||
|
||||
Follow the instructions found in the :ref:`getting-started-apl-nuc` to
|
||||
install all the build tools and dependencies on your system.
|
||||
|
||||
#. Clone the `Project ACRN <https://github.com/projectacrn/acrn-hypervisor>`_
|
||||
code repository
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd ~
|
||||
git clone https://github.com/projectacrn/acrn-hypervisor
|
||||
git checkout <known-good-tag/release>
|
||||
|
||||
.. note::
|
||||
We clone the git repository below but it is also possible to download the
|
||||
tarball for any specific tag or release from the `Project ACRN Github
|
||||
release page <https://github.com/projectacrn/acrn-hypervisor/releases>`_
|
||||
|
||||
#. Build and install ACRN
|
||||
|
||||
Here is the short version of how to build and install ACRN from source.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd ~/acrn-hypervisor
|
||||
make PLATFORM=uefi
|
||||
sudo make install
|
||||
|
||||
For more details, please refer to the :ref:`getting_started`.
|
||||
|
||||
#. Install the hypervisor
|
||||
|
||||
The ACRN devicemodel and tools were installed as part of the previous step.
|
||||
However, ``make install`` does not install the hypervisor (``acrn.efi``) on
|
||||
your EFI System Partition (ESP), nor does it configure your EFI firmware to
|
||||
boot it automatically. Follow the steps below to perform these operations
|
||||
and complete the ACRN installation.
|
||||
|
||||
#. Mount the EFI System Partition (ESP) and add the ACRN hypervisor and
|
||||
Service OS kernel to it (as ``root``)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo umount /boot/efi
|
||||
sudo lsblk
|
||||
sudo mount /dev/sda1 /mnt
|
||||
ls /mnt/EFI/ubuntu
|
||||
|
||||
You should see the following output:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
fw fwupx64.efi grub.cfg grubx64.efi MokManager.efi shimx64.efi
|
||||
|
||||
#. Install the hypervisor (``acrn.efi``)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo mkdir /mnt/EFI/acrn/
|
||||
sudo cp ~/acrn-hypervisor/build/hypervisor/acrn.efi /mnt/EFI/acrn
|
||||
|
||||
#. Configure the EFI firmware to boot the ACRN hypervisor by default
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 \
|
||||
-L "ACRN Hypervisor" -u "bootloader=\EFI\ubuntu\grubx64.efi"
|
||||
# Verify that the "ACRN Hypervisor" will be booted first
|
||||
sudo efibootmgr -v
|
||||
|
||||
You can change the boot order at any time using ``efibootmgr
|
||||
-o XXX,XXX,XXX``
|
||||
|
||||
.. note::
|
||||
By default, the “ACRN Hypervisor” you have just added should be
|
||||
the first one to boot. Verify this by using ``efibootmgr -v`` or
|
||||
by entering the EFI firmware at boot (using :kbd:`F10`)
|
||||
|
||||
Install the Service OS kernel
|
||||
*****************************
|
||||
|
||||
You can download latest Service OS kernel from
|
||||
`<https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/>`_
|
||||
(**We need to update the URL to one that is known to work, and matches the
|
||||
tag/release we use above!!!**). We will extract it and install it in the next
|
||||
few steps.
|
||||
|
||||
a. Download and extract the Service OS kernel
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
mkdir ~/kernel-build
|
||||
cd ~/kernel-build
|
||||
wget https://download.clearlinux.org/releases/current/clear/x86_64/os/Packages/linux-pk414-sos-4.14.41-39.x86_64.rpm
|
||||
sudo apt-get install rpm2cpio
|
||||
rpm2cpio linux-pk414-sos-4.14.41-39.x86_64.rpm | cpio -idmv
|
||||
|
||||
#. Install the SOS kernel and its drivers (modules)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo cp -r ~/kernel-build/usr/lib/modules/4.14.41-39.pk414-sos/ /lib/modules/
|
||||
sudo cp ~/kernel-build/usr/lib/kernel/org.clearlinux.pk414-sos.4.14.41-39 /boot/acrn/
|
||||
|
||||
#. Configure Grub to load the Service OS kernel
|
||||
|
||||
* Modify the ``/etc/grub.d/40_custom`` file to create a new Grub entry that
|
||||
will boot the SOS kernel.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuentry 'ACRN ubuntu SOS' {
|
||||
recordfail
|
||||
load_video
|
||||
insmod gzio
|
||||
insmod part_gpt
|
||||
insmod ext4
|
||||
linux /boot/acrn/org.clearlinux.pk414-sos.4.14.41-39 pci_devices_ignore=(0:18:1) maxcpus=1 console=tty0 console=ttyS0
|
||||
i915.nuclear_pageflip=1 root=PARTUUID=<ID of rootfs partition> rw rootwait ignore_loglevel no_timer_check consoleblank=0
|
||||
i915.tsd_init=7 i915.tsd_delay=2000 i915.avail_planes_per_pipe=0x00000F i915.domain_plane_owners=0x011111110000
|
||||
i915.enable_guc_loading=0 i915.enable_guc_submission=0 i915.enable_preemption=1 i915.context_priority_mode=2
|
||||
i915.enable_gvt=1 hvlog=2M@0x1FE00000
|
||||
}
|
||||
|
||||
.. note::
|
||||
You need to adjust this to use your partition UUID (``PARTUUID``) for
|
||||
the ``root=`` parameter (or use the device node directly).
|
||||
|
||||
.. note::
|
||||
You will also need to adjust the kernel name if you used a different
|
||||
RPM file as the source of your Service OS kernel.
|
||||
|
||||
* Update Grub on your system
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo update-grub
|
||||
|
||||
At this point, you need to modify ``/boot/grub/grub.cfg`` file manually to
|
||||
enable the timeout so that the system has an opportunity to show you the
|
||||
grub menu. (Without this the grub choice menu won't display.)
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
#set timeout_style=hidden
|
||||
set timeout = 10
|
||||
|
||||
#. Reboot the system
|
||||
|
||||
Reboot system. You should see the Grub menu with the new “ACRN ubuntu SOS”
|
||||
entry. Select it and proceed to booting the platform. The system will start
|
||||
the Ubuntu Desktop and you can now log in (as before).
|
||||
|
||||
To check if the hypervisor is effectively running, check ``dmesg``. The
|
||||
typical output of a successful installation will look like this:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
dmesg | grep ACRN
|
||||
[ 0.000000] Hypervisor detected: ACRN
|
||||
[ 0.862942] ACRN HVLog: acrn_hvlog_init
|
||||
|
||||
Prepare the User OS (UOS)
|
||||
*************************
|
||||
|
||||
We are using a User OS based on `Clear Linux`_.
|
||||
|
||||
* Download the Clear Linux image from `<https://download.clearlinux.org>`_
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cd ~
|
||||
wget https://download.clearlinux.org/releases/22780/clear/clear-22780-kvm.img.xz
|
||||
unxz clear-22780-kvm.img.xz
|
||||
|
||||
* Download the Production Kenrel (PK) kernel
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
wget https://download.clearlinux.org/releases/22780/clear/x86_64/os/Packages/linux-pk414-standard-4.14.47-44.x86_64.rpm
|
||||
rpm2cpio linux-pk414-standard-4.14.47-44.x86_64.rpm | cpio -idmv
|
||||
|
||||
* Update the UOS kernel modules
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo losetup -f -P --show /root/clear-22789-kvm.img
|
||||
sudo mount /dev/loop0p3 /mnt
|
||||
sudo cp -r /root/usr/lib/modules/4.14.47-44.pk414-standard /mnt/lib/modules/
|
||||
sudo cp -r /root/usr/lib/kernel /lib/modules/
|
||||
sudo umount /mnt
|
||||
sync
|
||||
|
||||
If you encounter a permission issue, follow these steps:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo chmod 777 /dev/acrn_vhm
|
||||
|
||||
* One additional package is needed
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo apt-get instal iasl
|
||||
sudo cp /usr/bin/iasl /usr/sbin/iasl
|
||||
|
||||
* Adjust ``launch_uos.sh``
|
||||
|
||||
You need to adjust the ``/usr/share/acrn/samples/nuc/launch_uos.sh`` script
|
||||
to match your installation. These are the couple of lines you need to modify:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
-s 3,virtio-blk,/root/clear-22780-kvm.img
|
||||
-k /lib/modules/kernel/org.clearlinux.pk414-standard.4.14.47-44
|
||||
|
||||
Start the User OS (UOS)
|
||||
***********************
|
||||
|
||||
You are now all set to start the User OS (UOS)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo /usr/share/acrn/samples/nuc/launch_uos.sh
|
||||
|
||||
**Congratulations**, you are now watching the User OS booting up!
|
||||
|
||||
.. _Clear Linux: https://clearlinux.org
|
||||
Loading…
Reference in New Issue
Block a user