boards/x86/acrn/doc/index.rst

.. _acrn:

ACRN UOS (User Operating System)
#################################

Overview
********

This board configuration defines an ACRN User OS execution environment for
running Zephyr RTOS applications.

ACRN is a flexible, lightweight reference hypervisor, built with real-time
and safety-criticality in mind, optimized to streamline embedded development
through an open source platform. Check out the `Introduction to Project ACRN
<https://projectacrn.github.io/latest/introduction/>`_ for more information.

This baseline configuration can be used as a starting point for creating
custom ACRN UOS configurations. It currently supports the following devices:

* I/O APIC
* local APIC timer
* NS16550 UARTs

Serial Ports
------------

The serial ports are assumed present at traditional ``COM1:`` and ``COM2:``
I/O-space addresses (based at ``0x3f8`` and ``0x2f8``, respectively). Only
polled operation is supported in this baseline configuration, as IRQ
assignments under ACRN are configurable (and frequently non-standard).
Interrupt-driven and MMIO operation are also possible.

Building and Running
********************

This details the process for building the :ref:`hello_world` sample and
running it as an ACRN User OS.

On the Zephyr Build System
--------------------------

#. The build process for the ACRN UOS target is similar to other boards. We
   will build the :ref:`hello_world` sample for ACRN with:

   .. zephyr-app-commands::
      :zephyr-app: samples/hello_world
      :board: acrn
      :goals: build
      :tool: all

   This will build the application ELF binary in
   ``samples/hello_world/build/zephyr/zephyr.elf``.

#. Build GRUB2 boot loader image

   We can build the GRUB2 bootloader for Zephyr using
   ``boards/x86/common/scripts/build_grub.sh``:

   .. code-block:: none

      $ ./boards/x86/common/scripts/build_grub.sh x86_64

   The EFI executable will be found at
   ``boards/x86/common/scripts/grub/bin/grub_x86_64.efi``.

#. Preparing the boot device

   .. code-block:: none

      $ dd if=/dev/zero of=zephyr.img bs=1M count=35
      $ mkfs.vfat -F 32 zephyr.img
      $ LOOP_DEV=`sudo losetup -f -P --show zephyr.img`
      $ sudo mount $LOOP_DEV /mnt
      $ sudo mkdir -p /mnt/efi/boot
      $ sudo cp boards/x86/common/scripts/grub/bin/grub_x86_64.efi /mnt/efi/boot/bootx64.efi
      $ sudo mkdir -p /mnt/kernel
      $ sudo cp samples/hello_world/build/zephyr/zephyr.elf /mnt/kernel

   Create ``/mnt/efi/boot/grub.cfg`` containing the following:

   .. code-block:: console

     set default=0
     set timeout=10

     menuentry "Zephyr Kernel" {
         multiboot /kernel/zephyr.elf
     }

   And then unmount the image file:

   .. code-block:: console

      $ sudo umount /mnt

   You now have a virtual disk image with a bootable Zephyr in ``zephyr.img``.
   If the Zephyr build system is not the ACRN SOS, then you will need to
   transfer this image to the ACRN SOS (via, e.g., a USB stick or network).

On the ACRN SOS
---------------

#. If you are not already using the ACRN SOS, follow `Getting started guide
   for Intel NUC
   <https://projectacrn.github.io/latest/getting-started/apl-nuc.html>`_ to
   install and boot "The ACRN Service OS".

#. Boot Zephyr as User OS

   On the ACRN SOS, prepare a directory and populate it with Zephyr files.

   .. code-block:: none

      $ mkdir zephyr
      $ cd zephyr
      $ cp /usr/share/acrn/samples/nuc/launch_zephyr.sh .
      $ cp /usr/share/acrn/bios/OVMF.fd .

   You will also need to copy the ``zephyr.img`` created in the first
   section into this directory. Then run ``launch_zephyr.sh`` script
   to launch the Zephyr as a UOS.

   .. code-block:: none

      $ sudo ./launch_zephyr.sh

   Then Zephyr will boot up automatically. You will see the banner:

   .. code-block:: console

      Hello World! acrn

   Which indicates that Zephyr is running successfully under ACRN!