1.. _using_hybrid_mode_on_nuc:
2
3Getting Started Guide for ACRN Hybrid Mode
4##########################################
5
6ACRN hypervisor supports a hybrid scenario where the User VM (such as Zephyr
7or Ubuntu) runs in a pre-launched VM or in a post-launched VM that is
8launched by a Device Model in the Service VM.
9
10.. figure:: images/ACRN-Hybrid.png
11   :align: center
12   :width: 600px
13   :name: hybrid_scenario_on_Vecow
14
15   The Hybrid Scenario on the Vecow SPC-7100
16
17The following guidelines
18describe how to set up the ACRN hypervisor hybrid scenario on the Vecow SPC-7100,
19as shown in :numref:`hybrid_scenario_on_Vecow`.
20
21.. note::
22
23   All build operations are done directly on the target. Building the artifacts (ACRN hypervisor, kernel, tools and Zephyr)
24   on a separate development machine can be done but is not described in this document.
25
26.. contents::
27   :local:
28   :depth: 1
29
30.. rst-class:: numbered-step
31
32Set-up base installation
33************************
34
35- Use the `Vecow SPC-7100 <https://marketplace.intel.com/s/offering/a5b3b000000PReMAAW/vecow-spc7100-series-11th-gen-intel-core-i7i5i3-processor-ultracompact-f>`_.
36- Connect to the serial port as described in :ref:`Connecting to the serial port <connect_serial_port>`.
37- Install Ubuntu 20.04 on your SATA device or on the NVME disk of your
38  Intel Vecow.
39
40.. rst-class:: numbered-step
41
42Prepare the Zephyr image
43************************
44
45Prepare the Zephyr kernel that you will run in VM0 later.
46
47- Follow step 1 from the :ref:`using_zephyr_as_user_vm` instructions
48
49  .. note:: We only need the ELF binary Zephyr kernel, not the entire ``zephyr.img``
50
51- Copy the :file:`zephyr/zephyr.elf` to the ``/boot`` folder::
52
53   sudo cp zephyr/zephyr.elf /boot
54
55.. rst-class:: numbered-step
56
57Set-up ACRN on your device
58**************************
59
60- Follow the instructions in :Ref:`gsg` to build ACRN using the
61  ``hybrid`` scenario. Here is the build command-line for the `Vecow SPC-7100 <https://marketplace.intel.com/s/offering/a5b3b000000PReMAAW/vecow-spc7100-series-11th-gen-intel-core-i7i5i3-processor-ultracompact-f>`_::
62
63   make clean && make BOARD=tgl-vecow-spc-7100-Corei7 SCENARIO=hybrid
64
65- Install the ACRN hypervisor and tools
66
67  .. code-block:: none
68
69     cd ~/acrn-hypervisor # Or wherever your sources are
70     sudo make install
71     sudo cp build/hypervisor/acrn.bin /boot
72     sudo cp build/hypervisor/acpi/ACPI_VM0.bin /boot
73
74- Build and install the ACRN kernel
75
76  .. code-block:: none
77
78     cd ~/acrn-kernel # Or where your ACRN kernel sources are
79     cp kernel_config_service_vm .config
80     make olddefconfig
81     make
82     sudo make modules_install
83     sudo cp arch/x86/boot/bzImage /boot/bzImage
84
85.. rst-class:: numbered-step
86
87Update Ubuntu GRUB
88******************
89
90Perform the following to update Ubuntu GRUB so it can boot the hypervisor and load the kernel image:
91
92#. Append the following configuration in the ``/etc/grub.d/40_custom`` file:
93
94   .. code-block:: bash
95      :emphasize-lines: 10,11,12
96
97      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' {
98         recordfail
99         load_video
100         gfxmode $linux_gfx_mode
101         insmod gzio
102         insmod part_gpt
103         insmod ext2
104         echo 'Loading hypervisor Hybrid scenario ...'
105         multiboot2 /boot/acrn.bin
106         module2 /boot/zephyr.elf xxxxxx
107         module2 /boot/bzImage yyyyyy
108         module2 /boot/ACPI_VM0.bin ACPI_VM0
109
110      }
111
112
113   .. note:: The module ``/boot/zephyr.elf`` is the VM0 (Zephyr) kernel file.
114      The param ``xxxxxx`` is VM0's kernel file tag and must exactly match the
115      ``kern_mod`` of VM0, which is configured in the ``misc/config_tools/data/tgl-vecow-spc-7100-Corei7/hybrid.xml``
116      file. The multiboot module ``/boot/bzImage`` is the Service VM kernel
117      file. The param ``yyyyyy`` is the bzImage tag and must exactly match the
118      ``kern_mod`` of VM1 in the ``misc/config_tools/data/tgl-vecow-spc-7100-Corei7/hybrid.xml``
119      file. The kernel command-line arguments used to boot the Service VM are
120      ``bootargs`` of VM1 in the ``misc/config_tools/data/tgl-vecow-spc-7100-Corei7/hybrid.xml``.
121      The module ``/boot/ACPI_VM0.bin`` is the binary of ACPI tables for pre-launched VM0 (Zephyr).
122      The parameter ``ACPI_VM0`` is VM0's ACPI tag and should not be modified.
123
124#. Correct example Grub configuration (with ``module2`` image paths set):
125
126   .. code-block:: console
127      :emphasize-lines: 10,11,12
128
129      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' {
130         recordfail
131         load_video
132         gfxmode $linux_gfx_mode
133         insmod gzio
134         insmod part_gpt
135         insmod ext2
136         echo 'Loading hypervisor Hybrid scenario ...'
137         multiboot2 /boot/acrn.bin
138         module2 /boot/zephyr.elf Zephyr_ElfImage
139         module2 /boot/bzImage Linux_bzImage
140         module2 /boot/ACPI_VM0.bin ACPI_VM0
141
142      }
143
144#. Modify the ``/etc/default/grub`` file as follows to make the GRUB menu
145   visible when booting:
146
147   .. code-block:: bash
148
149      GRUB_DEFAULT=ACRN_Hybrid
150      GRUB_TIMEOUT=5
151      # GRUB_HIDDEN_TIMEOUT=0
152      GRUB_HIDDEN_TIMEOUT_QUIET=false
153
154#. Update GRUB::
155
156   $ sudo update-grub
157
158#. Reboot the Intel NUC. Select the **ACRN hypervisor Hybrid Scenario** entry to boot
159   the ACRN hypervisor on the Intel NUC's display. The GRUB loader will boot the
160   hypervisor, and the hypervisor will start the VMs automatically.
161
162.. rst-class:: numbered-step
163
164Hybrid Scenario Startup Check
165*****************************
166#. Connect to the serial port as described in this :ref:`Connecting to the
167   serial port <connect_serial_port>` tutorial.
168
169#. Use these steps to verify that the hypervisor is properly running:
170
171   a. Log in to the ACRN hypervisor shell from the serial console.
172   #. Use the vm_list command to verify that the pre-launched VM and Service VM are launched successfully.
173
174#. Use these steps to verify all VMs are running properly:
175
176   a. Use the ``vm_console 0`` to switch to VM0 (Zephyr) console. It will display ``Hello world! acrn``.
177   #. Enter :kbd:`Ctrl` + :kbd:`Space` to return to the ACRN hypervisor shell.
178   #. Use the ``vm_console 1`` command to switch to the VM1 (Service VM) console.
179   #. Verify that the VM1's Service VM can boot and you can log in.
180   #. ssh to VM1 and launch the post-launched VM2 using the ACRN Device Model launch script.
181   #. Go to the Service VM console, and enter :kbd:`Ctrl` + :kbd:`Space` to return to the ACRN hypervisor shell.
182   #. Use the ``vm_console 2`` command to switch to the VM2 (User VM) console.
183   #. Verify that VM2 can boot and you can log in.
184
185Refer to the :ref:`acrnshell` for more information about available commands.
186