.. # Copyright (c) 2022, Arm Limited. # # SPDX-License-Identifier: MIT ######### Reproduce ######### This document provides the instructions for setting up the build environment, checking out code, building, running and validating the key use cases. ***************** Environment Setup ***************** The following instructions have been tested on hosts running Ubuntu 20.04. Install the required packages for the build host: https://docs.yoctoproject.org/4.0.1/singleindex.html#required-packages-for-the-build-host Kas is a setup tool for bitbake based projects. The minimal supported version is ``3.0.2``, install it like so: .. code-block:: shell pip3 install --user --upgrade kas==3.0.2 For more details on kas, see https://kas.readthedocs.io/. To build the recipe for the FVP_Base_AEMv8R model itself, you also need to accept the EULA [1]_ by setting the following environment variable: .. code-block:: shell export FVP_BASE_R_ARM_EULA_ACCEPT="True" To fetch and build the ongoing development of this software stack, follow the instructions in the below sections of this document. .. note:: The host machine should have at least 50 GBytes of free disk space for the next steps to work correctly. ******** Download ******** Fetch the v8r64 repository into a build directory: .. code-block:: shell mkdir -p ~/fvp-baser-aemv8r64-build cd ~/fvp-baser-aemv8r64-build git clone https://gitlab.arm.com/automotive-and-industrial/v8r64 -b v4.0 ************* Build and Run ************* The software stack supports building and running three configurations: Baremetal Zephyr, Baremetal Linux and Virtualization, which are associated with the use cases described in :ref:`Use Cases Overview`. Instructions to build and run these three configurations are as below: Baremetal Zephyr ================ Build and run with the baremetal Zephyr configuration: .. code-block:: shell cd ~/fvp-baser-aemv8r64-build # Build kas build v8r64/meta-armv8r64-extras/kas/baremetal-zephyr.yml # Output images will be located at # build/tmp_baremetal-zephyr/deploy/images/fvp-baser-aemv8r64/ # Run kas shell -k v8r64/meta-armv8r64-extras/kas/baremetal-zephyr.yml \ -c "../layers/meta-arm/scripts/runfvp --verbose --console" To finish the FVP emulation, you need to close the telnet session: 1. Escape to telnet console with ``ctrl+]``. 2. Run ``quit`` to close the session. A different sample application can be selected using the Kas ``--target`` flag, e.g.: .. code-block:: shell kas build v8r64/meta-armv8r64-extras/kas/baremetal-zephyr.yml \ --target zephyr-helloworld There are 3 supported targets ``zephyr-helloworld``, ``zephyr-synchronization`` and ``zephyr-philosophers`` of which ``zephyr-synchronization`` is set as the default target. See the :ref:`Zephyr` section for more information. Baremetal Linux =============== Build and run with the baremetal Linux configuration: .. code-block:: shell cd ~/fvp-baser-aemv8r64-build # Build kas build v8r64/meta-armv8r64-extras/kas/baremetal-linux.yml # Output images will be located at # build/tmp_baremetal-linux/deploy/images/fvp-baser-aemv8r64/ # Run kas shell -k v8r64/meta-armv8r64-extras/kas/baremetal-linux.yml \ -c "../layers/meta-arm/scripts/runfvp --verbose --console" Virtualization ============== Build and run with the virtualization configuration: .. code-block:: shell cd ~/fvp-baser-aemv8r64-build # Build kas build v8r64/meta-armv8r64-extras/kas/virtualization.yml # Output images will be located at # build/tmp_virtualization/deploy/images/fvp-baser-aemv8r64/ # Run kas shell -k v8r64/meta-armv8r64-extras/kas/virtualization.yml \ -c "../layers/meta-arm/scripts/runfvp --verbose --console" # Check guest OS in another terminals after Xen started # Zephyr telnet localhost 5001 # Linux (login with root with empty password) telnet localhost 5002 .. note:: When running the ``runfvp`` command with the ``--verbose`` option enabled, you will see the following output: .. code-block:: shell terminal_0: Listening for serial connection on port 5000 terminal_1: Listening for serial connection on port 5001 terminal_2: Listening for serial connection on port 5002 terminal_3: Listening for serial connection on port 5003 Among them, port ``5000`` is assigned to the Xen hypervisor, ``5001`` to the Zephyr domain, ``5002`` to the Linux domain, and ``5003`` unused. If these ports are already occupied (for example, there is already a ``runfvp`` instance running), then the port number will automatically increase by 4, that is, ports ``5004`` ~ ``5007`` will be assigned. In this case, checking the output from the Zephyr and Linux domains requires using ports ``5005`` and ``5006``: .. code-block:: shell telnet localhost 5005 telnet localhost 5006 If any port(s) in ``5000`` ~ ``5003`` is (are) used by other programs, the FVP will try to find 4 available ports starting from ``5000``. Be sure to check the log of ``runfvp`` (with ``--verbose``) to determine the correct port numbers, then apply the determined port number to the ``telnet`` command. ******** Validate ******** Zephyr ====== For the Zephyr RTOS (both on baremetal and as a Xen domain), these three sample applications supported in this software stack are themselves test programs. The steps to build and run the sample applications are described in the `Build and Run`_ section above. After Zephyr starts, the sample application runs automatically, and you will see the following output (take ``zephyr-synchronization`` as an example): .. code-block:: shell *** Booting Zephyr OS build zephyr-v3.1.0 *** Secondary CPU core 1 (MPID:0x1) is up thread_a: Hello World from cpu 0 on fvp_baser_aemv8r! thread_b: Hello World from cpu 1 on fvp_baser_aemv8r! thread_a: Hello World from cpu 0 on fvp_baser_aemv8r! thread_b: Hello World from cpu 1 on fvp_baser_aemv8r! .. note:: For Zephyr running as a Xen domain, use command ``telnet localhost 5001`` in another terminal to check the output. Linux ===== For the Linux OS (both on baremetal and as a Xen domain), the software stack contains a test suite which is defined in kas configuration file :file:`meta-armv8r64-extras/kas/tests.yml`. It can be included into the target build to validate Linux's functionalities as below examples. To build image with the test suite and run the test suite, use the following commands: .. code-block:: shell # For Linux on baremetal # Build kas build v8r64/meta-armv8r64-extras/kas/baremetal-linux.yml:v8r64/meta-armv8r64-extras/kas/tests.yml # Run kas shell -k v8r64/meta-armv8r64-extras/kas/baremetal-linux.yml:v8r64/meta-armv8r64-extras/kas/tests.yml \ -c "../layers/meta-arm/scripts/runfvp --verbose --console" # Login with root account -or- # Remote login using ssh in another terminal ssh -p 8022 root@localhost # In FVP target root@fvp-baser-aemv8r64:~# ptest-runner basic-tests # For Linux running as a Xen domain # Build kas build v8r64/meta-armv8r64-extras/kas/virtualization.yml:v8r64/meta-armv8r64-extras/kas/tests.yml # Run kas shell -k v8r64/meta-armv8r64-extras/kas/virtualization.yml:v8r64/meta-armv8r64-extras/kas/tests.yml \ -c "../layers/meta-arm/scripts/runfvp --verbose --console" # Login with root account in another terminal telnet localhost 5002 # login: root -or- # Remote login using ssh in another terminal ssh -p 8022 root@localhost # In FVP target root@fvp-baser-aemv8r64:~# ptest-runner basic-tests .. note:: Similar to ports ``5000`` ~ ``5003``, if port ``8022`` is already occupied, it will also be automatically incremented to the next available port. Below is an example where you need to use port ``8023`` to execute the ``ssh`` command. .. code-block:: shell Warning: FVP_BaseR_AEMv8R: bp.virtio_net.hostbridge: Unable to bind to port '8022' Info: FVP_BaseR_AEMv8R: bp.virtio_net.hostbridge: ...binding to port 8023 instead An example of the running result of the test suite is as follows: .. code-block:: shell root@fvp-baser-aemv8r64:~# ptest-runner basic-tests START: ptest-runner 2022-06-14T04:11 BEGIN: /usr/lib/basic-tests/ptest 1..6 ok 1 physical network is present ok 2 physical network device got ip address ok 3 all CPU cores are up ok 4 SMP is enabled ok 5 SMP CPU hot plug ok 6 removing all cores and will fail when removing the last one DURATION: 7 END: /usr/lib/basic-tests/ptest 2022-06-14T04:11 STOP: ptest-runner TOTAL: 1 FAIL: 0 ********* Reference ********* .. [1] https://developer.arm.com/downloads/-/arm-ecosystem-fvps/eula