blob: 145f13922b53b0261f58913623c46ed92783c618 [file] [log] [blame]
.. _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!