<commit_before>.. xenvm:

ARMv8 Xen Virtual Machine Example
#################################

Overview
********

This board allows to run Zephyr as Xen guest on any ARMv8 board that supports
ARM Virtualization Extensions. This is example configuration, as almost any VM
configuration is unique in many aspects.

.. figure:: xen_project_logo.png
   :align: center
   :alt: XenVM

   Xen virtual Guest (Credit: Xen Project)

It provides minimal set of devices:

* ARM Generic timer
* GICv2/GICv3

Hardware
********
Supported Features
==================

The following hardware features are supported:

+--------------+-------------+----------------------+
| Interface    | Controller  | Driver/Component     |
+==============+=============+======================+
| GIC          | virtualized | interrupt controller |
+--------------+-------------+----------------------+
| ARM TIMER    | virtualized | system clock         |
+--------------+-------------+----------------------+

The kernel currently does not support other hardware features on this platform.

The default configuration using GICv2 can be found in the defconfig file:
    ``boards/arm64/xenvm/xenvm_defconfig``

The default configuration using GICv3 can be found in the defconfig file:
    ``boards/arm64/xenvm/xenvm_gicv3_defconfig``

Devices
========
System Clock
------------

This board configuration uses a system clock frequency of 8.32 MHz. This is the
default value, which should be corrected for user's actual hardware.

You can determine clock frequency of your ARM Generic Timer by inspecting Xen
boot log:

::

  (XEN) [    0.147541] Generic Timer IRQ: phys=30 hyp=26 virt=27 Freq: 8320 KHz

Interrupt Controller
--------------------

Depending on the version of the GIC on your hardware, you may choose one of the
following board configurations:

- ``xenvm_defconfig`` selects GICv2
- ``xenvm_gicv3_defconfig`` selects GICv3

CPU Core type
-------------

Default core in this configuration is Cortex A72. Depending on yours actual
hardware you might want to change this option in the same way as Interrupt
Controller configuration.

Known Problems or Limitations
==============================

Xen configures guests in runtime by providing device tree that describes guest
environment. On other hand, Zephyr uses static configuration that should be know
at build time. So there are chances, that Zephyr image created with default
configuration would not boot on your hardware. In this case you need to update
configuration by altering device tree and Kconfig options. This will be covered
in detail in next section.

Most of Xen-specific features are not supported at the moment. This includes:
* XenBus (under development)
* Xen grant tables (under development)
* Xen PV drivers

Now only following features are supported:
* Xen Enlighten memory page
* Xen event channels (currently only pre-defined - PV console, Xenbus)
* Xen PV console (2 versions: regular ring buffer based for DomU and consoleio for Dom0)<commit_msg>xenvm: doc: Update docs for Xen VM according to new evtchn functionality<commit_after>.. xenvm:

ARMv8 Xen Virtual Machine Example
#################################

Overview
********

This board allows to run Zephyr as Xen guest on any ARMv8 board that supports
ARM Virtualization Extensions. This is example configuration, as almost any VM
configuration is unique in many aspects.

.. figure:: xen_project_logo.png
   :align: center
   :alt: XenVM

   Xen virtual Guest (Credit: Xen Project)

It provides minimal set of devices:

* ARM Generic timer
* GICv2/GICv3

Hardware
********
Supported Features
==================

The following hardware features are supported:

+--------------+-------------+----------------------+
| Interface    | Controller  | Driver/Component     |
+==============+=============+======================+
| GIC          | virtualized | interrupt controller |
+--------------+-------------+----------------------+
| ARM TIMER    | virtualized | system clock         |
+--------------+-------------+----------------------+

The kernel currently does not support other hardware features on this platform.

The default configuration using GICv2 can be found in the defconfig file:
    ``boards/arm64/xenvm/xenvm_defconfig``

The default configuration using GICv3 can be found in the defconfig file:
    ``boards/arm64/xenvm/xenvm_gicv3_defconfig``

Devices
========
System Clock
------------

This board configuration uses a system clock frequency of 8.32 MHz. This is the
default value, which should be corrected for user's actual hardware.

You can determine clock frequency of your ARM Generic Timer by inspecting Xen
boot log:

::

  (XEN) [    0.147541] Generic Timer IRQ: phys=30 hyp=26 virt=27 Freq: 8320 KHz

Interrupt Controller
--------------------

Depending on the version of the GIC on your hardware, you may choose one of the
following board configurations:

- ``xenvm_defconfig`` selects GICv2
- ``xenvm_gicv3_defconfig`` selects GICv3

CPU Core type
-------------

Default core in this configuration is Cortex A72. Depending on yours actual
hardware you might want to change this option in the same way as Interrupt
Controller configuration.

Known Problems or Limitations
==============================

Xen configures guests in runtime by providing device tree that describes guest
environment. On other hand, Zephyr uses static configuration that should be know
at build time. So there are chances, that Zephyr image created with default
configuration would not boot on your hardware. In this case you need to update
configuration by altering device tree and Kconfig options. This will be covered
in detail in next section.

Most of Xen-specific features are not supported at the moment. This includes:
* XenBus (under development)
* Xen grant tables (under development)
* Xen PV drivers

Now only following features are supported:
* Xen Enlighten memory page
* Xen event channels
* Xen PV console (2 versions: regular ring buffer based for DomU and consoleio for Dom0)
{'fraction_non_alphanumeric': 0.15871696858899784, 'fraction_numerical': 0.012630879175668939, 'mean_word_length': 3.2832740213523133, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1056931', 'n_tokens_mistral': 1583, 'n_tokens_neox': 1451, 'n_words': 726}