..
 # Copyright (c) 2022, Arm Limited.
 #
 # SPDX-License-Identifier: MIT

######
Extend
######

This document provides the guides showing how to use extra features, customize
configurations in this software stack.

**************
Extra Features
**************

Networking
==========

The FVP is configured by default to use "user mode networking", which simulates
an IP router and DHCP server to avoid additional host dependencies and
networking configuration. Outbound connections work automatically, e.g. by
running::

  wget www.arm.com

Inbound connections require an explicit port mapping from the host. By default,
port ``8022`` on the host is mapped to port ``22`` on the FVP, so that the
following command will connect to an ssh server running on the FVP:

.. code-block:: shell

   ssh root@localhost -p 8022

To map other ports from host, add the parameter containing the port mapping in
the command as below:

.. code-block:: shell

   kas shell -k \
       v8r64/meta-armv8r64-extras/kas/virtualization.yml \
       -c "../layers/meta-arm/scripts/runfvp \
           --verbose --console -- --parameter \
           'bp.virtio_net.hostbridge.userNetPorts=8022=22,8080=80,5555=5555'"

.. note::

   User mode networking does not support ICMP, so ``ping`` will not work.

More details on this topic can be found at User mode networking [1]_.

File Sharing between Host and FVP
=================================

It is possible to share a directory between the host machine and the FVP using
the virtio P9 device component included in the kernel. To do so, create a
directory to be mounted from the host machine:

.. code-block:: shell

   mkdir /path/to/host-mount-dir


Then, add the following parameter containing the path to the directory when
launching the model:

.. code-block:: shell

   --parameter 'bp.virtiop9device.root_path=/path/to/host-mount-dir'


e.g. for the virtualization build:

.. code-block:: shell

   kas shell -k \
       v8r64/meta-armv8r64-extras/kas/virtualization.yml \
       -c "../layers/meta-arm/scripts/runfvp \
           --verbose --console -- --parameter \
           'bp.virtiop9device.root_path=/path/to/host-mount-dir'"


Once you are logged into the FVP, the host directory can be mounted in a
directory on the model using the following command:

.. code-block:: shell

   mount -t 9p -o trans=virtio,version=9p2000.L FM /path/to/fvp-mount-dir

***********************
Customize Configuration
***********************

.. _Customizing the Zephyr Configuration:

Customizing the Zephyr Configuration
====================================

The Zephyr repository contains two relevant board definitions,
``fvp_baser_aemv8r`` and ``fvp_baser_aemv8r_smp``, each of which provides a base
defconfig and device tree for the build. In the Yocto build, the board
definition is selected dynamically based on the number of CPUs required by the
application recipe.

The defconfig can be extended by adding one or more ``.conf`` files to
``SRC_URI`` (which are passed to the ``OVERLAY_CONFIG`` Zephyr configuration
flag).

.. note::

   The file extension for Zephyr config overlays (``.conf``) is different to the
   extension used by config fragments in other recipes (``.cfg``), despite the
   similar functionality.

The device tree can be modified by adding one or more ``.overlay`` files to
``SRC_URI`` (which are passed to the ``DTC_OVERLAY_FILE`` Zephyr configuration
flag). These overlays can modify, add or remove nodes in the board's device
tree.

For an example of these overlay files and how to apply them to the build, see
the modifications to run Zephyr applications on Xen at the path
:file:`v8r64/meta-armv8r64-extras/dynamic-layers/virtualization-layer/recipes-kernel/zephyr-kernel/`

The link Important Build System Variables [2]_ provides more information.

.. note::

   Zephyr's device tree overlays have a different syntax from U-Boot's device
   tree overlays.

.. _Customizing the Xen Domains:

Customizing the Xen Domains
===========================

The default configuration contains two pre-configured domains:
``XEN_DOM0LESS_DOM_LINUX`` and ``XEN_DOM0LESS_DOM_ZEPHYR``, with the BitBake
varflags set appropriately. These varflags define where to find the domain
binaries in the build configuration, where to load them in memory at runtime and
how to boot the domain. Note that no attempts are made to validate overlapping
memory regions, or even whether the defined addresses fit in the FVP RAM. For
information, see the notes in the file
:file:`v8r64/meta-armv8r64-extras/classes/xen_dom0less_config.bbclass`.

Currently, the default images that these two pre-configured domains run on are:
one Linux rootfs image (``core-image-minimal``) for ``XEN_DOM0LESS_DOM_LINUX``
and one Zephyr application (``zephyr-synchronization``) for
``XEN_DOM0LESS_DOM_ZEPHYR``.

The default Linux rootfs image can be configured using the variable
``XEN_DOM0LESS_LINUX_IMAGE`` and the default Zephyr application can be
configured using the variable ``XEN_DOM0LESS_ZEPHYR_APPLICATION``. For example,
to use ``core-image-base`` and ``zephyr-helloworld`` instead of the defaults,
run:

.. code-block:: shell

   XEN_DOM0LESS_LINUX_IMAGE="core-image-base" \
   XEN_DOM0LESS_ZEPHYR_APPLICATION="zephyr-helloworld" \
       kas build v8r64/meta-armv8r64-extras/kas/virtualization.yml


*********
Reference
*********

.. [1] https://developer.arm.com/documentation/100964/1118/Introduction-to-Fast-Models/User-mode-networking?lang=en

.. [2] https://docs.zephyrproject.org/3.1.0/develop/application/index.html#important-build-system-variables