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