Using Ubuntu as the Service OS¶

This document builds on the Getting Started Guides, 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 Getting started guide for Intel 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 and select the ubuntu-16.04.4-desktop-amd64.iso image.
Follow Ubuntu’s online instructions 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:
```
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.

Install the build tools and dependencies

Follow the instructions found in the Getting started guide for Intel NUC to install all the build tools and dependencies on your system.
Clone the Project ACRN code repository
```
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
Build and install ACRN

Here is the short version of how to build and install ACRN from source.
```
cd ~/acrn-hypervisor
make PLATFORM=uefi
sudo make install
```
For more details, please refer to the Getting Started Guides.
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.
1. Mount the EFI System Partition (ESP) and add the ACRN hypervisor and Service OS kernel to it (as root)
```
sudo umount /boot/efi
sudo lsblk
sudo mount /dev/sda1 /mnt
ls /mnt/EFI/ubuntu
```
  You should see the following output:
```
fw  fwupx64.efi  grub.cfg  grubx64.efi  MokManager.efi  shimx64.efi
```
2. Install the hypervisor (acrn.efi)
```
sudo mkdir /mnt/EFI/acrn/
sudo cp ~/acrn-hypervisor/build/hypervisor/acrn.efi /mnt/EFI/acrn
```
3. Configure the EFI firmware to boot the ACRN hypervisor by default
```
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 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.

Download and extract the Service OS kernel

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)

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.

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
```
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.)
```
#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:
```
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

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

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

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:

sudo chmod 777 /dev/acrn_vhm

One additional package is needed

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:
```
-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)

sudo /usr/share/acrn/samples/nuc/launch_uos.sh

Congratulations, you are now watching the User OS booting up!