Important

This is the latest documentation for the unstable development branch of Project ACRN (master).
Use the drop-down menu on the left to select documentation for a stable release such as v2.7.

Getting Started Guide for ACRN Hybrid Mode

ACRN hypervisor supports a hybrid scenario where the User VM (such as Zephyr or Ubuntu) runs in a pre-launched VM or in a post-launched VM that is launched by a Device Model in the Service VM.

../_images/ACRN-Hybrid.png

Figure 7 The Hybrid Scenario on the Intel NUC

The following guidelines describe how to set up the ACRN hypervisor hybrid scenario on the Intel NUC, as shown in Figure 7.

Note

All build operations are done directly on the target. Building the artifacts (ACRN hypervisor, kernel, tools and Zephyr) on a separate development machine can be done but is not described in this document.

Set-up base installation

Prepare the Zephyr image

Prepare the Zephyr kernel that you will run in VM0 later.

  • Follow step 1 from the Run Zephyr as the User VM instructions

    Note

    We only need the ELF binary Zephyr kernel, not the entire zephyr.img

  • Copy the zephyr/zephyr.elf to the /boot folder:

    sudo cp zephyr/zephyr.elf /boot
    

Set-up ACRN on your device

  • Follow the instructions in Getting Started Guide to build ACRN using the hybrid scenario. Here is the build command-line for the Intel NUC Kit NUC11TNBi5:

    make clean && make BOARD=nuc11tnbi5 SCENARIO=hybrid
    
  • Install the ACRN hypervisor and tools

    cd ~/acrn-hypervisor # Or wherever your sources are
    sudo make install
    sudo cp build/hypervisor/acrn.bin /boot
    sudo cp build/hypervisor/acpi/ACPI_VM0.bin /boot
    
  • Build and install the ACRN kernel

    cd ~/acrn-kernel # Or where your ACRN kernel sources are
    cp kernel_config_service_vm .config
    make olddefconfig
    make
    sudo make modules_install
    sudo cp arch/x86/boot/bzImage /boot/bzImage
    

Update Ubuntu GRUB

Perform the following to update Ubuntu GRUB so it can boot the hypervisor and load the kernel image:

  1. Append the following configuration in the /etc/grub.d/40_custom file:

    menuentry 'ACRN hypervisor Hybrid Scenario' --id ACRN_Hybrid --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-simple-e23c76ae-b06d-4a6e-ad42-46b8eedfd7d3' {
       recordfail
       load_video
       gfxmode $linux_gfx_mode
       insmod gzio
       insmod part_gpt
       insmod ext2
       echo 'Loading hypervisor Hybrid scenario ...'
       multiboot2 /boot/acrn.bin
       module2 /boot/zephyr.elf xxxxxx
       module2 /boot/bzImage yyyyyy
       module2 /boot/ACPI_VM0.bin ACPI_VM0
    
    }
    

    Note

    The module /boot/zephyr.elf is the VM0 (Zephyr) kernel file. The param xxxxxx is VM0’s kernel file tag and must exactly match the kern_mod of VM0, which is configured in the misc/config_tools/data/nuc11tnbi5/hybrid.xml file. The multiboot module /boot/bzImage is the Service VM kernel file. The param yyyyyy is the bzImage tag and must exactly match the kern_mod of VM1 in the misc/config_tools/data/nuc11tnbi5/hybrid.xml file. The kernel command-line arguments used to boot the Service VM are bootargs of VM1 in the misc/config_tools/data/nuc11tnbi5/hybrid.xml. The module /boot/ACPI_VM0.bin is the binary of ACPI tables for pre-launched VM0 (Zephyr). The parameter ACPI_VM0 is VM0’s ACPI tag and should not be modified.

  2. Correct example Grub configuration (with module2 image paths set):

    menuentry 'ACRN hypervisor Hybrid Scenario' --id ACRN_Hybrid --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-simple-e23c76ae-b06d-4a6e-ad42-46b8eedfd7d3' {
       recordfail
       load_video
       gfxmode $linux_gfx_mode
       insmod gzio
       insmod part_gpt
       insmod ext2
       echo 'Loading hypervisor Hybrid scenario ...'
       multiboot2 /boot/acrn.bin
       module2 /boot/zephyr.elf Zephyr_ElfImage
       module2 /boot/bzImage Linux_bzImage
       module2 /boot/ACPI_VM0.bin ACPI_VM0
    
    }
    
  3. Modify the /etc/default/grub file as follows to make the GRUB menu visible when booting:

    GRUB_DEFAULT=ACRN_Hybrid
    GRUB_TIMEOUT=5
    # GRUB_HIDDEN_TIMEOUT=0
    GRUB_HIDDEN_TIMEOUT_QUIET=false
    
  4. Update GRUB:

    $ sudo update-grub
    
  5. Reboot the Intel NUC. Select the ACRN hypervisor Hybrid Scenario entry to boot the ACRN hypervisor on the Intel NUC’s display. The GRUB loader will boot the hypervisor, and the hypervisor will start the VMs automatically.

Hybrid Scenario Startup Check

  1. Connect to the serial port as described in this Connecting to the serial port tutorial.

  2. Use these steps to verify that the hypervisor is properly running:

    1. Log in to the ACRN hypervisor shell from the serial console.

    2. Use the vm_list command to verify that the pre-launched VM and Service VM are launched successfully.

  3. Use these steps to verify all VMs are running properly:

    1. Use the vm_console 0 to switch to VM0 (Zephyr) console. It will display Hello world! acrn.

    2. Enter Ctrl + Space to return to the ACRN hypervisor shell.

    3. Use the vm_console 1 command to switch to the VM1 (Service VM) console.

    4. Verify that the VM1’s Service VM can boot and you can log in.

    5. ssh to VM1 and launch the post-launched VM2 using the ACRN Device Model launch script.

    6. Go to the Service VM console, and enter Ctrl + Space to return to the ACRN hypervisor shell.

    7. Use the vm_console 2 command to switch to the VM2 (User VM) console.

    8. Verify that VM2 can boot and you can log in.

Refer to the ACRN Shell Commands for more information about available commands.