************************************************ Armv-A Base AEM FVP platform software user guide ************************************************ .. contents:: Introduction ============ The Armv-A Base AEM FVP (Fixed Virtual Platform) is an evolution of the base platform, enhanced to support the exploration of system level virtualization. It is an Architecture Envelope Model (AEM) which incorporates two AEM clusters, each of which can be configured with up to four cores. This document is a user guide on how to set up, build and run the software stack on the Armv-A Base AEM FVP (Fixed Virtual Platform). Host prerequisites for a validated build environment ==================================================== - Ubuntu Linux 18.04 LTS - Minimum of 50 GB free storage space. - Commands provided in this guide are executed from a ``bash`` shell environment. Packages -------- To ensure that all the required packages are installed, run: :: sudo apt-get update sudo apt-get install make autoconf autopoint bc bison build-essential curl \ device-tree-compiler dosfstools flex gettext-base git libssl-dev m4 \ mtools parted pkg-config python python3-distutils rsync unzip uuid-dev \ wget acpica-tools fuseext2 iasl To ensure that all the required packages for FVP are installed, run: :: sudo apt-get install telnet xterm Repo ---- Follow the instructions provided in the `repo README file`_ to install the ``repo tool``. NOTE: The repo tool which gets installed using apt-get command sometimes return errors, in such a case it's recommended to install repo using the ``curl`` method. The ``repo`` tool uses ``git`` to download the source code. It should be configured before using the ``repo`` tool. :: git config --global user.name "Your Name" git config --global user.email "you@example.com" Downloading the software stack ============================== The manifest files, which contain the location of all the git repositories of Armv-A Base AEM FVP platform software stack, are available `here`_. This section explains the procedure to sync the software stack. - Create a new empty folder :: mkdir cd - For fetching the latest *stable* software stack, use the following commands to sync: :: repo init \ -u https://git.gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest.git \ -m pinned-aemfvp-a.xml \ -b refs/tags/AEMFVP-A-2021.09.20 --depth=1 repo sync Note: The repo tool requires at least Python 3.6 to be installed on the development machine. On machines where python3 is not used as default, the repo init command will fail to complete. Refer to the `troubleshooting guide`_ for resolving this issue. Note: To fetch the entire commit history that is being downloaded, remove ``--depth=1`` from the repo init command. This will increase the time taken to download the platform software stack. Verify prerequisites ==================== Run the following command to verify all the required prerequisites to build the software stack: :: sudo ./build-scripts/check_dep.sh Note: This command checks and notifies to the user if the host machine is missing any required packages to build the software stack. The user has to install the missing packages. Obtaining the Armv-A Base AEM FVP ================================= The latest version of the Armv-A Base AEM FVP model can be downloaded from `Arm Ecosystem FVPs`_ and select ``Armv-A Base RevC AEM FVP``. Follow the instructions of the installer and set up the FVP. The installer, by default, selects the home directory to install the FVP. To opt for a different directory than the one selected by the installer, provide an absolute path to that directory when prompted for during the FVP installation process. Enable network on Armv-A Base AEM FVP ===================================== The Armv-A Base AEM FVP supports virtual ethernet interface to allow networking support, used for the software executed by the Armv-A Base AEM FVP. If support for networking is required, the host TAP interface has to be set up before the Armv-A Base AEM FVP is launched. To set up the TAP interface, execute the following commands on the host machine. - Install libvirt-bin :: sudo apt-get install libvirt-bin Note: The above command creates the network interface ``virbr0`` with the IP address ``192.168.122.1``. This can be checked with the command ``ifconfig``. If the interface is not created, run the following command to restart the libvirt daemon. :: sudo systemctl restart libvirt-bin.service - Create a tap interface named 'tap0' :: sudo ip tuntap add dev tap0 mode tap user $(whoami) sudo ifconfig tap0 0.0.0.0 promisc up sudo brctl addif virbr0 tap0 Supported features ================== Armv-A Base AEM FVP software stack supports the following features. - `Busybox Boot`_. - `Distribution Boot`_. Follow the links above for detailed information about the build and execute steps for each of the supported features. Software Components =================== The following software components are involved in the Armv-A Base AEM FVP booting. #. Trusted Firmware-A (TF-A) #. U-Boot #. UEFI #. GRUB #. Linux #. Root Filesystem (Busybox or Distribution) Trusted Firmware-A ------------------ Based on `Trusted Firmware-A`_. +----------------+----------------------------------------------------------+ | Build script | /build-scripts/build-arm-tf.sh | +----------------+----------------------------------------------------------+ | Checkout path | /arm-tf | +----------------+----------------------------------------------------------+ | Output | /output/aemfvp-a/aemfvp-a/tf-bl1.bin | | | /output/aemfvp-a/aemfvp-a/tf-bl2.bin | | | /output/aemfvp-a/aemfvp-a/tf-b31.bin | +----------------+----------------------------------------------------------+ U-Boot ------ Based on `U-Boot`_. +----------------+---------------------------------------------------------+ | Build script | /build-scripts/build-uboot.sh | +----------------+---------------------------------------------------------+ | Checkout path | /u-boot | +----------------+---------------------------------------------------------+ | Output | /output/aemfvp-a/aemfvp-a/uboot.bin | +----------------+---------------------------------------------------------+ UEFI ---- Based on `edk2`_ and `edk2-platforms`_ +----------------+-------------------------------------------------------+ | Build script | /build-scripts/build-uefi.sh | +----------------+-------------------------------------------------------+ | Checkout path | /uefi/edk2 | | | /uefi/edk2/edk2-platforms | +----------------+-------------------------------------------------------+ | Output | /output/aemfvp-a/aemfvp-a/uefi.bin| +----------------+-------------------------------------------------------+ GRUB ---- Based on `GRUB`_. +----------------+-------------------------------------------------------+ | Build script | /build-scripts/build-grub.sh | +----------------+-------------------------------------------------------+ | Checkout path | /grub | +----------------+-------------------------------------------------------+ | Output | /grub/output/grubaa64.efi | +----------------+-------------------------------------------------------+ Linux ----- Based on `Linux`_. +----------------+-------------------------------------------------------+ | Build script | /build-scripts/build-linux.sh | +----------------+-------------------------------------------------------+ | Checkout path | /linux | +----------------+-------------------------------------------------------+ | Output | /output/aemfvp-a/aemfvp-a/Image | +----------------+-------------------------------------------------------+ Root Filesystem (Busybox) ------------------------- The `Busybox`_ provides the minimal Rootfs. +----------------+---------------------------------------------------------------------------+ | Build script | /build-scripts/build-busybox.sh | +----------------+---------------------------------------------------------------------------+ | Checkout path | /busybox | +----------------+---------------------------------------------------------------------------+ | Output | /busybox/out/arm64/_install/ | +----------------+---------------------------------------------------------------------------+ Root Filesystem (Distribution) ------------------------------ This environment provides the base firmware (TF-A and UEFI) to boot the distribution on Armv-A Base AEM FVP and does not have a separate script to create the installable distribution images. The installable distribution images are fetched from the corresponding repository. The GRUB, Linux, and Rootfs are parts of the installable distribution images. Report security vulnerabilities =============================== For reporting security vulnerabilities, please refer `Vulnerability reporting`_ page. Release Tags ============ The table below lists the release tags for the Armv-A Base AEM FVP software stack and the corresponding Armv-A Base AEM FVP version that is recommended to be used along with the listed release tag. The summary of the software feature and changes introduced in each release is listed in `change log`_. +-----------------------+------------------------------+ | Release Tag | Armv-A Base AEM FVP Version | +=======================+==============================+ | AEMFVP-A-2021.09.20 | 11.15.18 | +-----------------------+------------------------------+ -------------- *Copyright (c) 2021, Arm Limited. All rights reserved.* .. _Arm Ecosystem FVPs: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models .. _Busybox Boot: docs/aemfvp-a/busybox-boot.rst .. _Distribution Boot: docs/aemfvp-a/distro-boot.rst .. _change log: docs/aemfvp-a/change-log.rst .. _repo README file: https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md .. _troubleshooting guide: docs/aemfvp-a/troubleshooting-guide.rst .. _here: https://gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest .. _Trusted Firmware-A: https://git.trustedfirmware.org/TF-A/trusted-firmware-a .. _U-Boot: https://git.denx.de/u-boot .. _edk2: https://github.com/tianocore/edk2 .. _edk2-platforms: https://github.com/tianocore/edk2-platforms .. _GRUB: https://www.gnu.org/software/grub/grub-download.html .. _Linux: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git .. _busybox: https://github.com/mirror/busybox .. _Vulnerability reporting: docs/aemfvp-a/vulnerability-reporting.rst