Getting Started Guide for the Intel NUC

The Intel® NUC is the primary tested platform for ACRN development, and its setup is described below.

Hardware Setup

The Intel Apollo Lake NUC (APL) and the Intel Kaby Lake NUC (KBL), described in Supported Hardware, are currently supported for ACRN development.

Note that we can enable the serial console on the KBL (NUC7i7DN), but this is not supported on the APL (NUC6CAYH).

Connecting to the serial port

If you do not need a serial console, ignore this section.

Neither the APL nor the KBL NUCs contain an external serial port interface. However, the KBL NUC has a serial port header you can expose with a serial DB9 header cable. You can build this cable yourself; refer to the KBL NUC product specification as shown below:

../_images/KBL-serial-port-header.png

Figure 21 KBL serial port header details

Or you can purchase such a cable.

You’ll also need an RS232 DB9 female to USB cable, or an RS232 DB9 female/female (NULL modem) cross-over cable to connect to your host system.

Note that If you want to use the RS232 DB9 female/female cable, choose the cross-over type rather than straight-through type.

Firmware update on the NUC

You may need to update to the latest UEFI firmware for the NUC hardware. Follow these BIOS Update Instructions for downloading and flashing an updated BIOS for the NUC.

Software Setup

Set up a Clear Linux Operating System

We begin by installing Clear Linux as the development OS on the NUC. The Clear Linux release includes an acrn.nuc6cayh.sdc.efi hypervisor application that will be added to the EFI partition (by the quick setup script or manually, as described below).

Note

Refer to the ACRN Release Notes for the Clear Linux OS version number tested with a specific ACRN release. Adjust the instruction below to reference the appropriate version number of Clear Linux OS (we use version 31080 as an example).

  1. Download the compressed Clear Linux OS installer image from https://download.clearlinux.org/releases/31080/clear/clear-31080-live-server.iso.xz and follow the Clear Linux OS Installation Guide as a starting point for installing the Clear Linux OS onto your platform. Follow the recommended options for choosing an Advanced options installation type, and using the platform’s storage as the target device for installation (overwriting the existing data).

    When setting up Clear Linux on your NUC:

    1. Launch the Clear Linux OS installer boot menu.

    2. With Clear Linux OS highlighted, select Enter.

    3. Log in with your root account and new password.

    4. Run the installer using the following command:

      $ clr-installer
      
    5. From the Main menu, select Configure Installation Media and set Destructive Installation to your desired hard disk.

    6. Select Telemetry to set Tab to highlight your choice.

    7. Press A to show the Advanced options.

    8. Select Select additional bundles and add bundles for desktop-autostart, editors, network-basic, and user-basic.

    9. Select Manager User to add an administrative user clear and password.

    10. Select Install.

    11. Select Confirm Install in the Confirm Installation window to start the installation.

  2. After installation is complete, boot into Clear Linux OS, log in as clear (using the password you set earlier).

  3. The instructions below provide details for setting up the ACRN Hypervisor, Service OS, and Guest OS. Along with the manual step details, We also provide an automated script that does all these steps for you, so you can skip these manual steps. See the quick-setup-guide section below to use the automated setup script.

Use the script to set up ACRN automatically

We provide an acrn_quick_setup.sh script in the ACRN GitHub repo to quickly and automatically set up the SOS and UOS and generate a customized script for launching the UOS.

This script requires the Clear Linux version number you’d like to set up for the ACRN SOS and UOS. The specified version must be greater than or equal to the Clear Linux version currently installed on the NUC. You can see your current Clear Linux version with this command:

$ cat /etc/os-release

The following instructions use Clear Linux version 31080. Specify the Clear Linux version you want to use.

Follow these steps:

  1. Install and log in to Clear Linux.

  2. Open a terminal.

  3. Download the acrn_quick_setup.sh script to set up the SOS. (If you don’t need a proxy to get the script, skip the export command.)

    $ export https_proxy=https://myproxy.mycompany.com:port
    $ cd ~
    $ wget https://raw.githubusercontent.com/projectacrn/acrn-hypervisor/master/doc/getting-started/acrn_quick_setup.sh
    
    $ sudo sh acrn_quick_setup.sh -s 31080
    Password:
    Upgrading SOS...
    Disable auto update...
    Running systemctl to disable updates
    Clear Linux version 31080 is already installed. Continuing to setup SOS...
    Adding the service-os, kernel-iot-lts2018 and systemd-networkd-autostart bundles...
    Loading required manifests...
    Downloading packs (104.41 MB) for:
     - kernel-iot-lts2018-sos
     - iasimage
     - service-os
     - kernel-iot-lts2018
     - systemd-networkd-autostart
            ...100%
    Finishing packs extraction...
    No extra files need to be downloaded
    Installing bundle(s) files...
            ...100%
    Calling post-update helper scripts
    none
    Successfully installed 3 bundles
    Add /mnt/EFI/acrn folder
    Copy /usr/lib/acrn/acrn.nuc6cayh.sdc.efi to /mnt/EFI/acrn/acrn.efi
    Check ACRN efi boot event
    Clean all ACRN efi boot event
    Check linux bootloader event
    Clean all Linux bootloader event
    Add new ACRN efi boot event
    Getting latest Service OS kernel version: org.clearlinux.iot-lts2018-sos.4.19.73-92
    Add default (5 seconds) boot wait time.
    New timeout value is: 5
    Set org.clearlinux.iot-lts2018-sos.4.19.73-92 as default boot kernel.
    Service OS setup done!
    Rebooting Service OS to take effects.
    Rebooting.
    

    Note

    This script is using /dev/sda1 as the default EFI System Partition ESP). If the ESP is different based on your hardware, you can specify it using the -e option. For example, to set up the SOS on an NVMe SSD, you could specify:

    sudo sh acrn_quick_setup.sh -s 31080 -e /dev/nvme0n1p1

    If you don’t need to reboot automatically after setting up the SOS, you can specify the -d parameter (don’t reboot).

  4. After the system reboots, log in as the clear user. Verify that the SOS booted successfully by checking the dmesg log:

    $ sudo dmesg | grep ACRN
    Password:
    [    0.000000] Hypervisor detected: ACRN
    [    1.252840] ACRNTrace: Initialized acrn trace module with 4 cpu
    [    1.253291] ACRN HVLog: Failed to init last hvlog devs, errno -19
    [    1.253292] ACRN HVLog: Initialized hvlog module with 4 cpu
    
  5. Continue by setting up a Guest OS using the acrn_quick_setup.sh script with the -u option (and the same Clear Linux version number):

    $ sudo sh acrn_quick_setup.sh -u 31080
    Password:
    Upgrading UOS...
    Downloading UOS image: https://download.clearlinux.org/releases/31080/clear/clear-31080-kvm.img.xz
      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
     14  248M   14 35.4M    0     0   851k      0  0:04:57  0:00:42  0:04:15  293k
    

    After the download is complete, you’ll get this output.

    Unxz UOS image: clear-31080-kvm.img.xz
    Get UOS image: clear-31080-kvm.img
    Upgrade UOS done...
    Now you can run this command to start UOS...
    $ sudo /root/launch_uos_31080.sh
    
  6. Launch the UOS using the customized launch_uos script (with sudo):

    $ sudo /root/launch_uos_31080.sh
    Password:
    
    cpu1 online=0
    cpu2 online=0
    cpu3 online=0
    passed gvt-g optargs low_gm 64, high_gm 448, fence 8
    SW_LOAD: get ovmf path /usr/share/acrn/bios/OVMF.fd, size 0x200000
    pm by vuart node-index = 0
    logger: name=console, level=4
    logger: name=kmsg, level=3
    logger: name=disk, level=5
    vm_create: vm1
    VHM api version 1.0
    vm_setup_memory: size=0x80000000
    open hugetlbfs file /run/hugepage/acrn/huge_lv1/vm1/D279543825D611E8864ECB7A18B34643
    open hugetlbfs file /run/hugepage/acrn/huge_lv2/vm1/D279543825D611E8864ECB7A18B34643
    level 0 free/need pages:1/1 page size:0x200000
    level 1 free/need pages:2/2 page size:0x40000000
    
    try to setup hugepage with:
            level 0 - lowmem 0x0, biosmem 0x200000, highmem 0x0
            level 1 - lowmem 0x80000000, biosmem 0x0, highmem 0x0
    total_size 0x180000000
    
    mmap ptr 0x0x7f792ace5000 -> baseaddr 0x0x7f7940000000
    mmap 0x80000000@0x7f7940000000
    touch 2 pages with pagesz 0x40000000
    mmap 0x200000@0x7f7a3fe00000
    touch 1 pages with pagesz 0x200000
    ...
    [    1.414873] Run /usr/lib/systemd/systemd-bootchart as init process
    [    1.521343] systemd[1]: systemd 242 running in system mode. (+PAM +AUDIT -SELINUX +IMA -APPARMOR -SMACK -SYSVINIT +UTMP +LIBCRYPTSETUP +GCRYPT +GNUTLS +ACL +XZ +LZ4 +SECCOMP +BLKID +ELFUTILS +KMOD -IDN2 -IDN -PCRE2 default-hierarchy=legacy)
    [    1.531173] systemd[1]: Detected virtualization acrn.
    [    1.533287] systemd[1]: Detected architecture x86-64.
    [    1.542775] systemd[1]: Failed to bump fs.file-max, ignoring: Invalid argument
    [    1.681326] systemd[1]: File /usr/lib/systemd/system/systemd-journald.service:12 configures an IP firewall (IPAddressDeny=any), but the local system does not support BPF/cgroup based firewalling.
    [    1.689540] systemd[1]: Proceeding WITHOUT firewalling in effect! (This warning is only shown for the first loaded unit using IP firewalling.)
    [    1.734816] [drm] Cannot find any crtc or sizes
    [    1.860168] systemd[1]: Set up automount Arbitrary Executable File Formats File System Automount Point.
    [    1.870434] systemd[1]: Listening on udev Kernel Socket.
    [    1.875555] systemd[1]: Created slice system-serial\x2dgetty.slice.
    [    1.878446] systemd[1]: Started Dispatch Password Requests to Console Directory Watch.
    [    2.075891] random: systemd-random-: uninitialized urandom read (512 bytes read)
    [    2.239775] [drm] Cannot find any crtc or sizes
    [    3.011537] systemd-journald[133]: Received request to flush runtime journal from PID 1
    [    3.386326] i8042: PNP: PS/2 Controller [PNP0303:KBD,PNP0f13:MOU] at 0x60,0x64 irq 1,12
    [    3.429277] i8042: Warning: Keylock active
    [    3.556872] serio: i8042 KBD port at 0x60,0x64 irq 1
    [    3.610010] serio: i8042 AUX port at 0x60,0x64 irq 12
    [    3.658689] Adding 33788k swap on /dev/vda2.  Priority:-2 extents:1 across:33788k
    [    4.034712] random: dbus-daemon: uninitialized urandom read (12 bytes read)
    [    4.101122] random: tallow: uninitialized urandom read (4 bytes read)
    [    4.119713] random: dbus-daemon: uninitialized urandom read (12 bytes read)
    [    4.223296] virtio_net virtio1 enp0s4: renamed from eth0
    [    4.342645] input: AT Translated Set 2 keyboard as /devices/platform/i8042/serio0/input/input1
    [    4.560662] IPv6: ADDRCONF(NETDEV_UP): enp0s4: link is not ready
    Unhandled ps2 mouse command 0xe1
                                    [    4.725622] IPv6: ADDRCONF(NETDEV_CHANGE): enp0s4: link becomes ready
    [    5.114339] input: PS/2 Generic Mouse as /devices/platform/i8042/serio1/input/input3
    
    clr-a632ec84744d4e02974fe1891130002e login:
    
  7. Log in as root. Specify the new password. Verify that you are running in the UOS by checking the kernel release version or seeing if acrn devices are visible:

    # uname -r
    4.19.73-92.iot-lts2018
    # ls /dev/acrn*
    ls: cannot access '/dev/acrn*': No such file or directory
    

    The UOS does not have /dev/acrn* devices. If you are in the SOS, you will see results such as these:

    $ uname -r
    4.19.73-92.iot-lts2018-sos
    $ ls /dev/acrn*
    /dev/acrn_hvlog_cur_0   /dev/acrn_hvlog_cur_2  /dev/acrn_trace_0  /dev/acrn_trace_2  /dev/acrn_vhm
    /dev/acrn_hvlog_cur_1   /dev/acrn_hvlog_cur_3  /dev/acrn_trace_1  /dev/acrn_trace_3
    

You have successfully set up Clear Linux at the Service and User OS and started up a UOS VM.

Manually Set Up ACRN

Instead of using the quick setup script, you can also set up ACRN, SOS, and UOS manually. Follow these steps:

  1. Install Clear Linux on the NUC, log in as the clear user, and open a terminal window.

  2. Disable the auto-update feature. Clear Linux OS is set to automatically update itself. We recommend that you disable this feature to have more control over when updates happen. Use this command:

    $ sudo swupd autoupdate --disable
    

    Note

    When enabled, the Clear Linux OS installer automatically checks for updates and installs the latest version available on your system. To use a specific version (such as 31080), enter the following command after the installation is complete:

    sudo swupd repair --picky -V 31080

  3. If you have an older version of Clear Linux OS already installed on your hardware, use this command to upgrade the Clear Linux OS to version 31080 (or newer):

    $ sudo swupd update -V 31080     # or newer version
    
  4. Use the sudo swupd bundle-add command to add these Clear Linux OS bundles:

    $ sudo swupd bundle-add service-os systemd-networkd-autostart
    
    Bundle Description
    service-os Adds the acrn hypervisor, acrn devicemodel, and Service OS kernel
    systemd-networkd-autostart Enables systemd-networkd as the default network manager

Add the ACRN hypervisor to the EFI Partition

In order to boot the ACRN SOS on the platform, you must add it to the EFI partition. Follow these steps:

  1. Mount the EFI partition and verify you have the following files:

    $ sudo ls -1 /boot/EFI/org.clearlinux
    bootloaderx64.efi
    freestanding-00-intel-ucode.cpio
    freestanding-i915-firmware.cpio.xz
    kernel-org.clearlinux.iot-lts2018-sos.4.19.73-92
    kernel-org.clearlinux.native.5.3.1-838
    loaderx64.efi
    

    Note

    On the Clear Linux OS, the EFI System Partition (e.g. /dev/sda1) is mounted under /boot by default. The Clear Linux project releases updates often, sometimes twice a day, so make note of the specific kernel versions (iot-lts2018) listed on your system, as you will need them later.

    The EFI System Partition (ESP) may be different based on your hardware. It will typically be something like /dev/mmcblk0p1 on platforms that have an on-board eMMC or /dev/nvme0n1p1 if your system has a non-volatile storage media attached via a PCI Express (PCIe) bus (NVMe).

  2. Add the acrn.nuc6cayh.sdc.efi hypervisor application (included in the Clear Linux OS release) to the EFI partition. Use these commands:

    $ sudo mkdir /boot/EFI/acrn
    $ sudo cp /usr/lib/acrn/acrn.nuc6cayh.sdc.efi /boot/EFI/acrn/acrn.efi
    
  3. Configure the EFI firmware to boot the ACRN hypervisor by default.

    The ACRN hypervisor (acrn.efi) is an EFI executable that’s loaded directly by the platform EFI firmware. It then loads the Service OS bootloader. Use the efibootmgr utility to configure the EFI firmware and add a new entry that loads the ACRN hypervisor.

    $ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN"
    

    Note

    Be aware that a Clear Linux OS update that includes a kernel upgrade will reset the boot option changes you just made. A Clear Linux OS update could happen automatically (if you have not disabled it as described above), if you later install a new bundle to your system, or simply if you decide to trigger an update manually. Whenever that happens, double-check the platform boot order using efibootmgr -v and modify it if needed.

    The ACRN hypervisor (acrn.efi) accepts two command-line parameters that tweak its behavior:

    1. bootloader=: this sets the EFI executable to be loaded once the hypervisor is up and running. This is typically the bootloader of the Service OS. The default value is to use the Clear Linux OS bootloader, i.e.: \EFI\org.clearlinux\bootloaderx64.efi.

    2. uart=: this tells the hypervisor where the serial port (UART) is found or whether it should be disabled. There are three forms for this parameter:

      1. uart=disabled: this disables the serial port completely.
      2. uart=bdf@<BDF value>: this sets the PCI serial port based on its BDF. For example, use bdf@0:18.1 for a BDF of 0:18.1 ttyS1.
      3. uart=port@<port address>: this sets the serial port address.

      Note

      uart=port@<port address> is required if you want to enable the serial console. Run dmesg |grep ttyS0 to get port address from the output, and then add the uart parameter into the efibootmgr command.

    Here is a more complete example of how to configure the EFI firmware to load the ACRN hypervisor and set these parameters:

    $ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \
          -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=disabled"
    

    Here is an example of how to enable a serial console for the KBL NUC:

    $ sudo efibootmgr -c -l "\EFI\acrn\acrn.efi" -d /dev/sda -p 1 -L "ACRN NUC Hypervisor" \
          -u "bootloader=\EFI\org.clearlinux\bootloaderx64.efi uart=port@0x3f8"
    
  4. Add a timeout period for the Systemd-Boot to wait; otherwise, it will not present the boot menu and will always boot the base Clear Linux OS:

    $ sudo clr-boot-manager set-timeout 5
    $ sudo clr-boot-manager update
    
  5. Set the kernel-iot-lts2018 kernel as the default kernel:

    $ sudo clr-boot-manager list-kernels
    * org.clearlinux.native.5.3.1-838
      org.clearlinux.iot-lts2018-sos.4.19.73-92
    

    Set the default kernel from org.clearlinux.native.5.3.1-838 to org.clearlinux.iot-lts2018-sos.4.19.73-92:

    $ sudo clr-boot-manager set-kernel org.clearlinux.iot-lts2018-sos.4.19.73-92
    $ sudo clr-boot-manager list-kernels
      org.clearlinux.native.5.3.1-838
    * org.clearlinux.iot-lts2018-sos.4.19.73-92
    
  6. Reboot and wait until the boot menu is displayed, as shown below:

    Code Block 1 ACRN Service OS Boot Menu
    Clear Linux OS (Clear-linux-iot-lts2018-sos-4.19.73-92)
    Clear Linux OS (Clear-linux-native.5.3.1-838)
    Reboot Into Firmware Interface
    
  7. After booting up the ACRN hypervisor, the Service OS launches automatically by default, and the Clear Linux OS desktop show with the clear user (or you can login remotely with an “ssh” client). If there is any issue which makes the GNOME desktop not successfully display,, then the system will go to the shell console.

  8. From the ssh client, log in as the clear user. Use the password you set previously when you installed the Clear Linux OS.

  9. After rebooting the system, check that the ACRN hypervisor is running properly with:

$ sudo dmesg | grep ACRN
[    0.000000] Hypervisor detected: ACRN
[    1.253093] ACRNTrace: Initialized acrn trace module with 4 cpu
[    1.253535] ACRN HVLog: Failed to init last hvlog devs, errno -19
[    1.253536] ACRN HVLog: Initialized hvlog module with 4 cpu

If you see log information similar to this, the ACRN hypervisor is running properly and you can start deploying a User OS. If not, verify the EFI boot options, and SOS kernel settings are correct (as described above).

ACRN Network Bridge

The ACRN bridge has been set up as a part of systemd services for device communication. The default bridge creates acrn_br0 which is the bridge and tap0 as an initial setup. The files can be found in /usr/lib/systemd/network. No additional setup is needed since systemd-networkd is automatically enabled after a system restart.

Set up Reference UOS

  1. On your platform, download the pre-built reference Clear Linux OS UOS image version 31080 (or newer) into your (root) home directory:

    $ cd ~
    $ mkdir uos
    $ cd uos
    $ curl https://download.clearlinux.org/releases/31080/clear/clear-31080-kvm.img.xz -o uos.img.xz
    
    Note that if you want to use or try out a newer version of Clear Linux OS as the UOS, download the latest from http://download.clearlinux.org/image/. Make sure to adjust the steps described below accordingly (image file name and kernel modules version).
    
  2. Uncompress it:

    $ unxz uos.img.xz
    
  3. Deploy the UOS kernel modules to the UOS virtual disk image (note that you’ll need to use the same iot-lts2018 image version number noted in Step 1 above):

    $ sudo losetup -f -P --show uos.img
    $ sudo mount /dev/loop0p3 /mnt
    $ sudo mount /dev/loop0p1 /mnt/boot
    $ sudo swupd bundle-add --path=/mnt kernel-iot-lts2018
    $ uos_kernel_conf=`ls -t /mnt/boot/loader/entries/ | grep Clear-linux-iot-lts2018 | head -n1`
    $ uos_kernel=${uos_kernel_conf%.conf}
    $ sudo echo "default $uos_kernel" > /mnt/boot/loader/loader.conf
    $ sudo umount /mnt/boot
    $ sudo umount /mnt
    $ sync
    
  4. Edit and run the launch_uos.sh script to launch the UOS.

    A sample launch_uos.sh is included in the Clear Linux OS release, and is also available in the acrn-hypervisor/devicemodel GitHub repo (in the samples folder) as shown here:

    By default, the script is located in the /usr/share/acrn/samples/nuc/ directory. You can run it to launch the User OS:

    $ cd /usr/share/acrn/samples/nuc/
    $ sudo ./launch_uos.sh
    
  5. You have successfully booted the ACRN hypervisor, SOS, and UOS:

    ../_images/gsg-successful-boot.png

    Figure 23 Successful boot