1.. _using_zephyr_as_uos:
2.. _using_zephyr_as_user_vm:
3
4Run Zephyr as the User RTVM OS
5##############################
6
7This tutorial describes how to run Zephyr as the User VM on the ACRN hypervisor. We are using
8Kaby Lake-based Intel NUC (model NUC7i5DNHE) in this tutorial.
9Other :ref:`ACRN supported platforms <hardware>` should work as well.
10
11.. note::
12   This tutorial uses the (default) SDC scenario. If you use a different
13   scenario, you will need a serial port connection to your platform to see
14   Zephyr console output.
15
16Introduction to Zephyr
17**********************
18
19The Zephyr RTOS is a scalable real-time operating system supporting multiple hardware architectures,
20optimized for resource constrained devices, and built with safety and security in mind.
21
22Steps for Using Zephyr as User VM
23*********************************
24
25#. Build Zephyr
26
27   Follow the `Zephyr Getting Started Guide <https://docs.zephyrproject.org/latest/getting_started/>`_ to
28   set up the Zephyr development environment.
29
30   The build process for ACRN User VM target is similar to other boards. We will build the `Hello World
31   <https://docs.zephyrproject.org/latest/samples/hello_world/README.html>`_ sample for ACRN:
32
33   .. code-block:: none
34
35      $ cd samples/hello_world
36      $ west build -p auto -b acrn .
37
38   This will build the application ELF binary in ``samples/hello_world/build/zephyr/zephyr.elf``.
39
40#. Build grub2 bootloader image
41
42   We can build the grub2 bootloader for Zephyr using ``boards/x86/common/scripts/build_grub.sh``
43   found in the `Zephyr source code <https://github.com/zephyrproject-rtos/zephyr>`_.
44
45   .. code-block:: none
46
47      $ ./boards/x86/common/scripts/build_grub.sh x86_64
48
49   The EFI executable binary will be found at ``boards/x86/common/scripts/grub/bin/grub_x86_64.efi``.
50
51#. Preparing the boot device
52
53   .. code-block:: none
54
55      $ dd if=/dev/zero of=zephyr.img bs=1M count=35
56      $ mkfs.vfat -F 32 zephyr.img
57      $ sudo mount `sudo losetup -f -P --show zephyr.img` /mnt
58
59   Create the following directories.
60
61   .. code-block:: none
62
63      $ sudo mkdir -p /mnt/efi/boot
64      $ sudo mkdir -p /mnt/kernel
65
66   Copy ``zephyr.elf`` and ``grub_x86_64.efi``
67
68   .. code-block:: none
69
70      $ sudo cp boards/x86/common/scripts/grub/bin/grub_x86_64.efi /mnt/efi/boot/bootx64.efi
71      $ sudo cp samples/hello_world/build/zephyr/zephyr.elf /mnt/kernel
72
73   Create ``/mnt/efi/boot/grub.cfg`` containing the following:
74
75   .. code-block:: console
76
77      set default=0
78      set timeout=10
79
80      menuentry "Zephyr Kernel" {
81          multiboot /kernel/zephyr.elf
82      }
83
84   Unmount the loopback device:
85
86   .. code-block:: none
87
88      $ sudo umount /mnt
89
90   You now have a virtual disk image with a bootable Zephyr in ``zephyr.img``. If the Zephyr build system is not
91   the ACRN Service VM, then you will need to transfer this image to the
92   ACRN Service VM (via, e.g, a USB drive or network)
93
94#. Follow :ref:`gsg`
95   to boot "The ACRN Service OS" based on Ubnuntu OS (ACRN tag: v2.2)
96
97
98#. Boot Zephyr as User VM
99
100   On the ACRN Service VM, prepare a directory and populate it with Zephyr files.
101
102   .. code-block:: none
103
104      $ mkdir zephyr && cd zephyr
105      $ cp /usr/share/acrn/samples/nuc/launch_zephyr.sh .
106
107   You will also need to copy the ``zephyr.img`` created in the above section into directory ``zephyr``.
108
109   Run the ``launch_zephyr.sh`` script to launch Zephyr as User VM.
110
111   .. code-block:: none
112
113      $ sudo ./launch_zephyr.sh
114
115   Then Zephyr will boot automatically. You will see a console message from the hello_world sample application:
116
117   .. code-block:: console
118
119      Hello World! acrn
120