Attention

You are viewing an older version of the documentation. The latest version is v3.3.

Installing ECI-A¶

After building an image for either of the targets acrn-sos or acrn-zephyr-ehl, you are ready to deploy the ECI-A image on a target system.

To deploy the image on a target system, you need to do the following:

Create a bootable USB
Configure the target system BIOS
Boot and install the image

ECI-A: Create Bootable USB¶

The following steps are applicable to:

Open a terminal to the ECI directory. In Ubuntu*, you can right-click an empty space in the directory explorer and select Open in Terminal.
Insert a USB drive with at least 12GB capacity into the Linux build system.

Note: For best performance, use a USB 3.1 (or greater) device and port.

Warning

All data on the USB mass storage device will be erased!

At the terminal prompt, run the provided create_bootable_usb.sh script:
```
./create_bootable_usb.sh
```

If the message “Please run as root” appears, run the script again with sudo:
sudo ./create_bootable_usb.sh
If no ECI images have been built yet, the script will display the message: “No built images found”. Refer to acrn-sos or acrn-zephyr-ehl and build an ECI-A image. Then, run the create_bootable_usb.sh script.

The script will display a list of available ECI images. Enter an image name from the list. For example, enter acrn-sos.

If a mass storage device cannot be located, the script will display the message: “ERR: No removable mass storage devices found”. Insert a USB drive with at least 12GB capacity into the Linux build system and run the create_bootable_usb.sh script again.
The script will display a list of available removable mass storage devices.

Enter the name of a device from the displayed list. In this example, the device name displayed is sdc.

When the warning, Warning All data will be erased on <device> Proceed? y/[n], enter y to proceed. The target ECI image will be written to the removable mass storage device.¶
After the initial ECI image is written, the prompt Do you want to include an ECI image for ACRN hypervisor use? y/[n] is displayed.

If the prompt is not displayed, there are no ECI targets built that can be embedded. Refer to Building ECI Targets and build additional ECI targets. Then, run the create_bootable_usb.sh script again.

For acrn-zephyr-ehl, enter n at the prompt. Follow the section Boot & Install ECI-A to continue.

For acrn-sos, you have two options: Without embedding ECI image and Embedding ECI image for virtualization. Click the following tabs to learn more:
You can use the ECI-A image as-is, without embedding an ECI image for virtualization. Additional ECI images will not be included. Images can be added for virtualization after the ECI-A image is installed on the target system. To proceed with this option, enter n at the prompt.

After the script completes, you will have a USB drive that can install the ECI-A image. Eject the USB drive from the Linux build system. Follow the section Configure Target System BIOS to continue.
Additional ECI images can be embedded for virtualization. The script will prompt to select a VM profile or ECI image and perform the necessary operations to embed the ECI image. To proceed with this option, enter y at the prompt.

After choosing to include an ECI image for ACRN hypervisor use, the script will display the prompt: Do you want to use the VM profile tool to select a configuration? y/[n]. The VM profile tool is a menu-based interactive guide, which generates a VM profile that are used by automation scripts included in the acrn-sos image. It is recommended to use the VM profile tool to create a valid VM configuration for the desired target hardware platform.
To use the VM profile tool, enter y at the prompt, then follow the steps below:

The VM profile tool will prompt you to select an existing profile or create a new one. Selecting an existing profile will load the respective configuration. Choosing to create a new profile will start the configuration guide.

Note: Only the profiles and templates that match the target hardware platform selected during the ECI-A build process are displayed. This ensures that only configurations that are compatible with the target hardware platform are loaded into the image.

Use the arrow keys to move the selection and press the enter key to finalize the selection.

In this example, an existing profile is selected (see the following figure).

See also

For a comprehensive guide on creating a new profile, see the following section: VM profile tool

If you select an existing profile, the following prompt will appear. Select the Accept selection option to accept the selected profile or select Change selection to return to the previous menu to make another profile selection.

The script will perform a series of operations. These operations might take up to 30 minutes (or more) to complete depending on the read/write throughput of the hardware in use and the number of VMs defined in the profile.

After the script completes, you will have a bootable USB drive that can install the ECI-A image (and the embedded ECI image). Eject the USB drive from the Linux build system.

Depending on the target images selected in the VM profile, you might have to perform additional steps on the target system before the VMs are fully prepared. These additional steps typically include copying non-ECI images (that is, Windows or Ubuntu) to a specific location in the target system, with a specific name. In the above example, there is a Step 2, which instructs you to copy the “Linux” image for vm2 to the target filesystem at /var/lib/machines/images/vm2_linux.iso. The exact location and filename will vary depending on the situation.

Note: If the additional steps include copying an ECI image, it indicates that the ECI image has not yet been built. It is recommended that you refer to Building ECI Targets to build the missing ECI images. Then, refer to ECI-A: Create Bootable USB to allow the VM profile tool to automatically copy the required ECI images.

This completes the bootable USB creation. Follow the section Configure Target System BIOS to continue.
If you do not want to use the VM profile tool, enter n at the prompt.

The script will display a list of available ECI images. Enter an image name from the list. For example, enter base-poky.

The script will perform a series of operations. These operations might take up to 30 minutes (or more) to complete depending on the read/write throughput of the hardware in use. After the script completes, you will have a bootable USB drive that can install the target ECI image (and the embedded ECI image. Eject the USB drive from the Linux build system. Follow the section Configure Target System BIOS to continue.

Configure Target System BIOS¶

The following section is applicable to:

For ACRN hypervisor (acrn-sos build), certain BIOS settings need to be configured to boot properly. Do the following:

Boot the target system and access the BIOS (typically pressing the delete or F2 keys while booting will open the BIOS menu).
Select Restore Defaults or Load Defaults and then select Save & Exit.
Reboot the target system and open the BIOS again (as per Step 1).

Modify the BIOS configuration as listed in the following table.

Note

Not all configurations will be available depending on the platform and/or BIOS in use. In this case, modify as many configurations as possible.

Setting Name	Option	Setting Menu
Hyper-Threading	Disabled	Intel Advanced Menu ⟶ CPU Configuration
Intel (VMX) Virtualization	Enabled	Intel Advanced Menu ⟶ CPU Configuration
Intel(R) SpeedStep	Disabled	Intel Advanced Menu ⟶ Power & Performance ⟶ CPU - Power Management Control
Turbo Mode	Disabled	Intel Advanced Menu ⟶ Power & Performance ⟶ CPU - Power Management Control
C States	Disabled	Intel Advanced Menu ⟶ Power & Performance ⟶ CPU - Power Management Control
RC6 (Render Standby)	Disabled	Intel Advanced Menu ⟶ Power & Performance ⟶ GT - Power Management Control
VT-d	Enabled	Intel Advanced Menu ⟶ System Agent (SA) Configuration
Above 4GB MMIO BIOS assignment	Disabled	Intel Advanced Menu ⟶ System Agent (SA) Configuration
PM Support	Enabled	Intel Advanced Menu ⟶ System Agent (SA) Configuration ⟶ Graphics Configuration
DVMT Pre-Allocated	64M	Intel Advanced Menu ⟶ System Agent (SA) Configuration ⟶ Graphics Configuration

After modifying the BIOS configuration, save the configuration. Follow the section Boot & Install ECI-A to continue.

Boot & Install ECI-A¶

The following steps are applicable to:

Click the tab corresponding to the variant of ECI-A image being installed.

Insert the bootable USB drive created earlier (see section ECI-A: Create Bootable USB) into the target system.
Reboot the target system and access the BIOS (typically pressing the delete or F2 keys while booting will open the BIOS menu).
At the BIOS menu, navigate to the Save & Exit tab or open the Boot Manager Menu. On this page, you should see an entry with the prefix “UEFI …”. Select the entry that looks like: UEFI: <vendor>…, where <vendor> is the vendor of the USB drive.

Note: If the USB device does not appear in the boot menu, you might need to enable “Legacy USB Support” in BIOS. Configure the following BIOS setting, then reboot the system for the changes to take effect:

Setting Name

Option

Setting Menu

Legacy USB Support

Enabled

Intel Advanced Menu ⟶ USB Configuration ⟶ Legacy USB Support
The system will boot from the USB drive. A boot menu will appear with a few options. Choose the “install” option.
The system will begin the installation process. During the installation, you will be prompted to: Please select an install target or press n to exit. Enter an available install target (make sure that the target is correct). For example, enter sdb.
If you see the prompt: /dev/sdb# contains a ext4 file system … Proceed anyway? (y,N) , press y at the prompt.
After the installation is complete, remove the USB drive and press Enter on the keyboard to reboot the system.
Let the system boot completely. Select ACRN from the GRUB menu (this option will automatically be selected after 5 seconds).

Note

The Linux option in the GRUB menu boots the Linux kernel and Service OS without the ACRN hypervisor. This can be useful to help diagnose boot or hardware issues if using a custom platform (see: Compiling ACRN for different platforms).
A login prompt will eventually appear. Login with user root. At the terminal prompt, type: uname -a. Observe the build date to verify the image is correct.
Verify that ACRN hypervisor is active by using the command dmesg | grep ACRN The output should appear similar to the following:

# dmesg | grep ACRN
[    0.000000] Hypervisor detected: ACRN

Important

The acrn-zephyr-ehl target image is only compatible with Elkhart platforms booting SBL (SlimBootLoader).

Insert the bootable USB drive created earlier (see section ECI-A: Create Bootable USB) into the target system.
Connect an empty USB drive to the target system. ECI-A acrn-zephyr-ehl will be installed in this storage device.
Ensure a display and a serial/com port are connected to host PC. Power on the target system.
The system boot from the bootable USB drive. A boot menu will appear with a few options. Choose the “install” option.
The system will begin the installation process. During the installation, you will be prompted to: Please select an install target or press n to exit. Enter an available install target (make sure that the target is correct). For example, enter sdb.
If you see the prompt: /dev/sdb# contains a ext4 file system … Proceed anyway? (y,N) , press y at the prompt.
After the installation is complete, remove the bootable USB drive and press Enter on the keyboard to reboot the system.
Let the system boot completely. Select ACRN from the GRUB menu (this option will automatically be selected after 5 seconds). The ACRN hypervisor shell should appear on the serial console connected to host. At this point, the display may be disconnected since it will no longer be used.