1.. xenvm:
2
3ARMv8 Xen Virtual Machine Example
4#################################
5
6Overview
7********
8
9This board allows to run Zephyr as Xen guest on any ARMv8 board that supports
10ARM Virtualization Extensions. This is example configuration, as almost any VM
11configuration is unique in many aspects.
12
13It provides minimal set of devices:
14
15* ARM Generic timer
16* GICv2/GICv3
17
18Hardware
19********
20Supported Features
21==================
22
23The following hardware features are supported:
24
25+--------------+-------------+----------------------+
26| Interface    | Controller  | Driver/Component     |
27+==============+=============+======================+
28| GIC          | virtualized | interrupt controller |
29+--------------+-------------+----------------------+
30| ARM TIMER    | virtualized | system clock         |
31+--------------+-------------+----------------------+
32
33The kernel currently does not support other hardware features on this platform.
34
35The default configuration for this board can be found in these files:
36
37- :zephyr_file:`boards/xen/xenvm/Kconfig.defconfig`
38- :zephyr_file:`boards/xen/xenvm/xenvm_defconfig`
39
40Devices
41========
42System Clock
43------------
44
45This board configuration uses a system clock frequency of 8.32 MHz. This is the
46default value, which should be corrected for user's actual hardware.
47
48You can determine clock frequency of your ARM Generic Timer by inspecting Xen
49boot log:
50
51::
52
53  (XEN) [    0.147541] Generic Timer IRQ: phys=30 hyp=26 virt=27 Freq: 8320 KHz
54
55Interrupt Controller
56--------------------
57
58Depending on the version of the GIC on your hardware, you may choose one of the
59following board configuration variants:
60
61- ``xenvm`` selects GICv2
62- ``xenvm//gicv3`` selects GICv3
63
64CPU Core type
65-------------
66
67Default core in this configuration is Cortex A72. Depending on yours actual
68hardware you might want to change this option in the same way as Interrupt
69Controller configuration.
70
71Known Problems or Limitations
72==============================
73
74Xen configures guests in runtime by providing device tree that describes guest
75environment. On other hand, Zephyr uses static configuration that should be know
76at build time. So there are chances, that Zephyr image created with default
77configuration would not boot on your hardware. In this case you need to update
78configuration by altering device tree and Kconfig options. This will be covered
79in detail in next section.
80
81Most of Xen-specific features are not supported at the moment. This includes:
82
83* XenBus (under development)
84* Xen PV drivers
85
86Now only following features are supported:
87
88* Xen Enlighten memory page
89* Xen event channels
90* Xen PV console (2 versions: regular ring buffer based for DomU and consoleio for Dom0)
91* Xen early console_io interface (mainly for debug purposes - requires debug version of Xen)
92* Xen grant tables (granting access for own grants and map/unmap foreign grants)
93
94Building and Running
95********************
96
97Use this configuration to run basic Zephyr applications and kernel tests as Xen
98guest, for example, with the :zephyr:code-sample:`synchronization` sample:
99
100- if your hardware is based on GICv2:
101
102.. code-block::
103
104   $ west build -b xenvm samples/synchronization
105
106- if your hardware is based on GICv3:
107
108.. code-block::
109
110   $ west build -b xenvm//gicv3 samples/synchronization
111
112This will build an image with the synchronization sample app. Next, you need to
113create guest configuration file :code:`zephyr.conf`. There is example:
114
115.. code-block::
116
117   kernel="zephyr.bin"
118   name="zephyr"
119   vcpus=1
120   memory=16
121   gic_version="v2"
122   on_crash="preserve"
123
124When using ``xenvm//gicv3`` configuration, you need to remove the ``gic_version``
125parameter or set it to ``"v3"``.
126
127You need to upload both :code:`zephyr.bin` and :code:`zephyr.conf` to your Dom0
128and then you can run Zephyr by issuing
129
130.. code-block::
131
132   $ xl create zephyr.conf
133
134Next you need to attach to PV console:
135
136.. code-block::
137
138   $ xl console zephyr
139
140Also this can be performed via single command:
141
142.. code-block::
143
144   $ xl create -c zephyr.conf
145
146You will see Zephyr output:
147
148.. code-block:: console
149
150   *** Booting Zephyr OS build zephyr-v2.4.0-1137-g5803ee1e8183  ***
151   thread_a: Hello World from cpu 0 on xenvm!
152   thread_b: Hello World from cpu 0 on xenvm!
153   thread_a: Hello World from cpu 0 on xenvm!
154   thread_b: Hello World from cpu 0 on xenvm!
155   thread_a: Hello World from cpu 0 on xenvm!
156
157Exit xen virtual console by pressing :kbd:`CTRL+]`
158
159Updating configuration
160**********************
161
162As was said earlier, Xen describes hardware using device tree and expects that
163guest will parse device tree in runtime. On other hand, Zephyr supports only
164static, build time configuration. While provided configuration should work on
165almost any ARMv8 host running in aarch64 mode, there is no guarantee, that Xen
166will not change some values (like RAM base address) in the future.
167
168Also, frequency of system timer is board specific and should be updated when running
169Zephyr xenvm image on new hardware.
170
171One can make Xen to dump generated DTB by using :code:`LIBXL_DEBUG_DUMP_DTB`
172environment variable, like so:
173
174.. code-block::
175
176   $ LIBXL_DEBUG_DUMP_DTB=domu-libxl.dtb xl create zephyr.conf
177
178Then, generated "domu-libxl.dtb" file can be de-compiled using "dtc" tool.
179
180Use information from de-compiled DTB file to update all related entries in
181provided "xenvm.dts" file. If memory layout is also changed, you may need to
182update :code:`CONFIG_SRAM_BASE_ADDRESS` as well.
183
184References
185**********
186
187`Xen ARM with Virtualization Extensions <https://wiki.xenproject.org/wiki/Xen_ARM_with_Virtualization_Extensions>`_
188
189`xl.conf (guest configuration file) manual <https://xenbits.xen.org/docs/unstable/man/xl.cfg.5.html>`_
190