.. # Copyright (c) 2022, Arm Limited. # # SPDX-License-Identifier: MIT ################################################### Armv8-R AArch64 Extras Layer (meta-armv8r64-extras) ################################################### ************************** Zephyr Sample Applications ************************** Recipes are provided to build three Zephyr sample applications (``zephyr-helloworld``, ``zephyr-synchronization`` and ``zephyr-philosophers``). These recipes use a common base include file (``zephyr-base.inc``), meaning that application recipes only need to define the path to their source code. There is also support for running Zephyr applications using the ``runfvp`` script from meta-arm. The applications are built using the `Zephyr SDK`_, which is pre-compiled and downloaded automatically, so the implementation is standalone and does not depend on meta-zephyr (https://git.yoctoproject.org/meta-zephyr). This means that the generated binary files are identical to those built by following the `guidelines`_ in the Zephyr documentation. .. _Zephyr SDK: https://github.com/zephyrproject-rtos/sdk-ng .. _guidelines: https://docs.zephyrproject.org/3.1.0/develop/getting_started/index.html ******************** Virtualization Stack ******************** The virtualization stack uses Xen as the Type-1 hypervisor to boot one or more domains independently. The meta-virtualization layer is used to provide Xen build support. The Xen MPU implementation only supports "dom0less" mode (for more details see the :ref:`Hypervisor (Xen)` section), so the meta-armv8r64-extras layer provides logic to build the required dom0less artifacts, which are shown in the diagram below. For more information on how U-Boot detects and uses these artifacts at runtime, see the U-Boot :ref:`Boot Sequence`. .. image:: /images/armv8r64-xen-stack.png :alt: Arm v8r64 Xen stack Domain Configuration ==================== The default domain configuration is provided in a bbclass. For more information, see :ref:`Customizing the Xen Domains`. Xen Configuration ================= Xen is configured through the bbappend file at :file:`v8r64/meta-armv8r64-extras/dynamic-layers/virtualization-layer/recipes-extended/xen`, which defines the branch and revision to build for the ``fvp-baser-aemv8r64`` machine and also includes a machine-specific config file. Linux Image Configuration ========================= In projects based on OE-core, the Linux image recipe is responsible for creating the disk image, including the root filesystem partition. The boot partition, which is part of the same disk image, is populated by extending ``IMAGE_CLASSES`` (see `Image Generation`_ below). No changes are made to the Linux kernel for the virtualization use case. Zephyr Application Configuration ================================ Zephyr requires some specific configuration when running as a Xen domain on the ``fvp-baser-aemv8r64`` machine. It is necessary to match the number of CPUs allocated, the DRAM address and the selected UART with the equivalent parameters in the domain configuration. This is achieved using Xen-specific overlay files (see :ref:`Customizing the Zephyr Configuration`). Device Tree Generation ====================== Xen domains in dom0less mode are configured using additions to the ``/chosen`` node in the device tree. To avoid modifying the firmware's device tree for the virtualization stack we instead dynamically generate a device tree overlay file which can be applied at runtime by U-Boot. Additionally, in order for Xen to access peripherals in dom0less mode, we must specify which peripherals to "pass through" to each domain using a domain-specific passthrough dtb file (see https://xenbits.xen.org/docs/unstable/misc/arm/passthrough.txt for more details). All these device trees are created from templates, substituting placeholders with values defined in the domain configuration. The passthrough device tree template to use for each domain is selected in the domain configuration. U-Boot Script Generation ======================== The boot script is partially dynamically generated in order to load the configured domain binaries and passthrough device trees to the configured memory addresses prior to booting Xen. Image Generation ================ The boot partition needs to be populated with the artifacts necessary to boot Xen and its domains so they can be loaded by U-Boot. This is achieved using a custom Wic image and a custom bbclass (``xen_image_dom0less``). This class can be added to ``IMAGE_CLASSES`` so that the desired Linux image recipe (e.g. ``core-image-minimal``) includes the necessary configuration to populate the boot partition. ********** Test Suite ********** The test cases in the test suite are implemented based on `bats`_ (Bash Automated Testing System) and include 2 categories: .. _bats: https://bats-core.readthedocs.io/en/stable/index.html * Network * SMP The test suite is added to Yocto `Ptest`_ (Package Test) framework and can be run with ``ptest-runner`` in the target machine. .. _Ptest: https://wiki.yoctoproject.org/wiki/Ptest The test suite can be added into the image by adding the following line in :file:`conf/local.conf`: .. code-block:: shell DISTRO_FEATURES:append = " refstack-tests"