Building and flashing images on Intel systems with ACRN hypervisor¶

This document describes how to set up AutoSD to be the Service OS for the ACRN hypervisor. The process is based on the ACRN Getting Started Guide which uses distribution packages as a way to install the hypervisor and set up the bootloader. Packages for AutoSD are available in the @centos-automotive-sig/raptorlake-board-support Centos-stream+epel-next 9 copr repository.

The ACRN hypervisor needs to be built specifically for a given system with a configuration generated by its board inspector (acrn-board-inspector) and configurator (acrn-configurator) tools, so it is not possible to provide a pre-built acrn-hypervisor binary RPM package. Instead, the acrn-hypervisor packages need to be built after generating the desired configuration. This is done using distribution packaging files which are provided to build ACRN for AutoSD. This is a similar workflow to the one described in the ACRN Project Getting Started Guide. Additionally, ACRN assumes that the grub2 bootloader is used, which is different than the AutoSD default bootloader setup. Some tweaks are taken care of automatically by the packaging, but some changes still need to be made to change the AutoSD defaults before ACRN can boot on these systems.

Note

Not all Intel hardware can run the ACRN hypervisor, please check the ACRN Supported Hardware list for reference. This document targets Intel Raptor Lake, but may also be used as a reference to other supported hardware.

Workflow

Build a base AutoSD image and flash it to the target system.
Run the ACRN board inspector to collect information about the target system.
Run the ACRN configuration generator to produce the configuration files and launch scripts based on the target system and requirements.
Build the ACRN hypervisor binary, install it and run AutoSD as the ACRN Service OS.

Prerequisites

You have a local development system to build the base AutoSD image.
You have a target Intel system which supports ACRN.
You have a separate development system to run the acrn-configurator tool. Currently, the ACRN project only supports Debian-based systems to run acrn-configurator, but this does not impact the final system that runs AutoSD.

AutoSD base image build and flashing¶

These are the steps to build and flash a base image with AutoSD. Note that this image does not yet contain the ACRN hypervisor, that will be customized and installed in later steps.

Clone the sample-images repository:

$ git clone https://gitlab.com/CentOS/automotive/sample-images.git

Build the autosd-acrn-developer-regular x86_64 image.

To build AutoSD images, use the automotive-image-builder tool. See Installing the automotive-image-builder tool for installation instructions.

Note

This requires automotive-image-builder >= 1.1.0, which has not yet been released in the main repository at the time of this writing. Snapshot releases of automotive-image-buider are available in @centos-automotive-sig/automotive-image-builder-dev
```
$ cd sample-images
$ sudo automotive-image-builder build --target acrn \
    --mode package --export image \
    images/simple-developer.aib.yml autosd-acrn-developer-regular.x86_64.img
```
Alternatively, for more permissive ssh access:
```
$ sudo automotive-image-builder build --target acrn \
    --mode package --export image \
    --define 'ssh_permit_root_login=true' --define 'ssh_permit_password_auth=true' \
    images/simple-developer.aib.yml autosd-acrn-developer-regular.x86_64.img
```
Flash to the target system. The image can be flashed using any preferred method by the user (e.g. dd), and is hardware-specific.

Note

For a safe flashing process, one option is to boot a Live USB image on the target and use it to flash the local storage device with dd. A CentOS Stream 9 Live image can be used for this purpose: https://www.centos.org/download/#centos-stream

Note

Alternatively, if there is physical access to the internal hardware, the storage device can be removed and flashed using a separate host.
Log into the system, the default password for the default image is password

ACRN board inspector¶

Run the ACRN Board Inspector tool on the target system to collect system information for ACRN. The tool generates a XML file is used by the ACRN Configurator to determine which configuration options are possible, as well as which system resources are available.

This step assumes the target system is running a flashed autosd-acrn-developer-regular x86_64 image, which comes pre-installed with kernel-6.8.0-1000.acrn.el9 and acrn-board-inspector.

Run the acrn board inspector to create the XML, here named my_board.xml
```
# acrn-board-inspector my_board
```
Note

The rest of the instructions assume the name my_board. For initial testing, please do not change this.

ACRN configuration generation¶

Run the acrn-configurator tool to produce the ACRN configuration files and launch scripts. acrn-configurator takes my_board.xml from the previous step as input.

This step is done on the separate development system, not on the target system.

Important

Currently, this is still done on another Debian-based host with acrn-configurator installed.

Copy my_board.xml from the target system and run acrn-configurator to generate an ACRN scenario and launch scripts. The actual configuration depends on your desired configuration.
```
$ scp -v <target-system>:<path/to/my_board.xml> .
$ acrn-configurator
```
For an example configuration, which is considered as a reference for the rest of this document, please follow the steps after launching acrn-configurator in https://projectacrn.github.io/3.2/getting-started/getting-started.html#generate-a-scenario-configuration-file-and-launch-script

ACRN hypervisor build and installation¶

Build and install the customized acrn-hypervisor package, which contains the ACRN hypervisor binary. The build will take the configuration from the previous step as input. After the installation it will also perform final tweaks on the AutoSD base installation and start running AutoSD as the ACRN Service OS.

The remaining steps are all done on the target system.

Clone the acrn-hypervisor repository:

# dnf install -y git
# git clone https://gitlab.com/CentOS/automotive/src/acrn-hypervisor.git
# cd acrn-hypervisor

Copy launch_user_vm_id1.sh, my_board.board.xml and scenario.xml from the acrn-configurator output (from the MyConfiguration directory):
```
# scp -rv <development-system>:<path/to/MyConfiguration>/* .
```

Build the ACRN hypervisor RPMs for this configuration locally with rpmbuild:

# dnf install rpm-build rpmdevtools dnf-plugins-core epel-release
# dnf copr enable @centos-automotive-sig/raptorlake-board-support centos-stream+epel-next-9-x86_64
# dnf builddep acrn-hypervisor.spec
# spectool -g acrn-hypervisor.spec
# rpmbuild --define "_sourcedir $PWD" --define "_rpmdir $PWD/output" -ba acrn-hypervisor.spec

Note

The launch_user_vm_id1.sh, my_board.board.xml and scenario.xml sources from the previous step must be placed in the same directory as acrn-hypervisor.spec before building.

Then install the ACRN hypervisor RPMs:

# dnf install output/x86_64/*.rpm

Grub2 requires additional tweaks. Install the multiboot2 module and make it available at boot time:

# dnf install grub2-efi-x64-modules
# mkdir -p /boot/grub2/x86_64-efi/
# cp -vp /usr/lib/grub/x86_64-efi/{multiboot2,relocator}.mod /boot/grub2/x86_64-efi/

Grub2 on AutoSD and Fedora use BLS (BootLoaderSpec) by default, which is not compatible with ACRN grub config generation. Disable that for now and make sure the grub menu will appear and is not disabled by the HiddenGrubMenu feature.
```
# echo "GRUB_CMDLINE_LINUX=\"$(cat /etc/kernel/cmdline)\"" >> /etc/default/grub
# echo "GRUB_TIMEOUT=5" >> /etc/default/grub
# echo "GRUB_ENABLE_BLSCFG=false" >> /etc/default/grub
# grub2-editenv - unset menu_auto_hide
```
Make any more needed changes to /etc/default/grub (e.g. adjust cmdline if needed), then generate a full grub2 config again with:
```
# grub2-mkconfig -o /etc/grub2-efi.cfg
```

Reboot and select the appropriate entry on the console. The console should be taken by the ACRN:\> prompt, which can also be used to check the running VMs (if available).

…
 |*GNU/Linux with ACRN hypervisor, with Linux 6.8.0-1000.acrn.el9.x86_64 (ACRN 3.2)>|
…

ACRN:\>
ACRN:\>vm_list

VM_ID VM_NAME                          VM_STATE
===== ================================ ========
  0   ACRN_Service_VM                  Running

ssh back into the target system and check the detected hypervisor:
```
# dmesg | grep ACRN
[ 0.000000] Hypervisor detected: ACRN
```

Note

The autosd-acrn-developer-regular x86_64 image is a minimal image which does not come with a desktop pre-installed. The desktop graphics mode can easily be installed and enabled and set to boot by default with the commands below. This is an optional step.

# dnf groupinstall "Server with GUI"
# systemctl set-default graphical.target
# systemctl enable gdm
# reboot

ACRN Basic Post-Launched VM setup¶

Setup for testing a simple acrn post-launched VM.

Guest image used for a simple post launched VM test: https://download.fedoraproject.org/pub/fedora/linux/releases/40/Server/x86_64/iso/Fedora-Server-netinst-x86_64-40-1.14.iso (the console might be a bit garbled upon the guest boot; wait up to a couple of minutes for the guest boot to finish and hit Enter to find the prompt as it might be at the top of the terminal window).
For quick tests, launch_user_vm_id1.sh can be customized for a different image by editing the script and changing the virtio-blk line near the end of the script in the dm_params array.

For the systemd-networkd setup from acrn, the network may drop and the machine may get a different IP address.

# modprobe acrn
# echo acrn > /etc/modules-load.d/acrn.conf
# systemctl enable --now acrnd
# dnf install systemd-networkd
# systemctl enable --now systemd-networkd
# cp /usr/share/acrn/launch-scripts/my_board/MyConfiguration/launch_user_vm_id1.sh .
# chmod +x launch_user_vm_id1.sh
# ./launch_user_vm_id1.sh