docs/aemfvp-a: add user guide for aemfvp-a

The aemfvp-a documents explain the steps to download, build the software
stacks and run these software stacks on the Armv-A Base AEM FVP.
Signed-off-by: Selvarasu Ganesan <selvarasu.ganesan@arm.com>
Change-Id: I81f548886901c2b03074283df1ec7d7558d26166

docs/aemfvp-a/busybox-boot.rst

+*********************************************
+Busybox boot on Armv-A Base AEM FVP platforms
+*********************************************
+
+.. contents::
+
+
+Overview of Busybox boot
+========================
+
+Busybox is a lightweight executable which packages lots of POSIX compliant UNIX
+utilities in a single file system. Busybox boot with Armv-A base design platform
+software stack demonstrates the integration of various software components on
+the software stack resulting in the ability to boot Linux Kernel on Armv-A
+Base AEM FVP.
+
+Booting to Busybox is especially helpful when porting the software stack for new
+platforms which are derivative of Armv-A base design platform as this can
+be quickly executed to ensure that the various software components are properly
+integrated and verify the basic functionality of various software components.
+
+This document describes how to build the Armv-A based design platform software
+stack and use it to boot up to Busybox on the Armv-A Base AEM FVP.
+
+
+Download the platform software
+==============================
+
+To obtain the required sources for the platform, follow the steps listed on the
+`user guide`_ page. Ensure that the platform software is downloaded before
+proceeding with the steps listed below. Also, note the host machine requirements
+listed on that page which is essential to build and execute the platform
+software stack.
+
+Skip this section if the required sources already have been downloaded.
+
+Build the platform software
+===========================
+
+This section describes the procedure to build the following software components
+for Busybox boot.
+
+        - Trusted firmware (TF-A)
+        - U-Boot
+        - UEFI
+        - GRUB
+        - Linux
+        - Busybox
+
+The disk image consists of two partitions. The first partition is an EFI system
+partition and contains GRUB and Kernel Image. The second partition is an ext3
+partition which contains the Busybox based rootfs. Examples of how to use the
+build command for Busybox boot are listed below.
+
+To build the software stack, the command to be used is
+
+::
+
+  ./build-scripts/aemfvp-a/build-test-busybox.sh -p <platform name> <command>
+
+Supported command line options are listed below
+
+* <platform name>
+
+  - ``aemfvp-a``
+
+* <command>
+
+  - Supported commands are
+
+    - ``clean``
+    - ``build``
+    - ``package``
+    - ``all`` (all of the three above)
+
+Note: On networks where the git port is blocked, the build procedure might not
+progress. Refer to the `troubleshooting guide`_ for possible ways to resolve
+this issue.
+
+Examples of the build command are
+
+- Command to clean, build and package the software stack required for Busybox
+  boot on Armv-A Base AEM FVP platform:
+
+  ::
+
+    ./build-scripts/aemfvp-a/build-test-busybox.sh -p aemfvp-a all
+
+- Command to perform an incremental build of the software components included in
+  the software stack for the Armv-A Base platform.
+
+  Note: this command should be followed by the ``package`` command to complete
+  the preparation of the FIP and the disk image.
+
+  ::
+
+    ./build-scripts/aemfvp-a/build-test-busybox.sh -p aemfvp-a build
+
+- Command to package the previously built software stack and prepare the FIP and
+  the disk image.
+
+  ::
+
+    ./build-scripts/aemfvp-a/build-test-busybox.sh -p aemfvp-a package
+
+Individual software component build (Optional)
+----------------------------------------------
+
+The user can use the following command if they want to rebuild individual
+software component. Each software component has a separate script to build that
+component. After the software components have been built they must be packaged a
+disk image using ``build-test-busybox.sh``.
+
+To rebuild individual software components, the command to be used is
+
+::
+
+  ./build-scripts/build-<component>.sh -p <platform name> -f <filesystem> <command>
+
+Supported command line options are listed below
+
+* <component>
+
+  - Supported components are
+
+    - ``arm-tf``
+    - ``uboot``
+    - ``uefi``
+    - ``grub``
+    - ``linux``
+    - ``busybox``
+
+* <platform name>
+
+  - ``aemfvp-a``
+
+* <filesystem>
+
+  - ``busybox``
+
+* <command>
+
+  - Supported commands are
+
+    - ``clean``
+    - ``build``
+
+To repackage the disk image, the command to be used is
+
+::
+
+  ./build-scripts/aemfvp-a/build-test-busybox.sh -p <platform name> package
+
+
+Boot up to Busybox
+==================
+
+After the build of the platform software stack for Busybox is complete, the
+following commands can be used to start the execution of the Armv-A Base AEM FVP
+model and boot the platform up to the Busybox prompt. Refer to the `user guide`_
+section ``Obtaining the Arm-A Base AEM FVP`` for information on downloading the
+Arm-A Base AEM FVP model. Examples of how to use the command are listed below.
+
+To boot up to the Busybox prompt, the commands to be used are
+
+- Set ``MODEL`` path before launching the model:
+
+  ::
+
+    export MODEL=<absolute path to the platform Armv-A AEM FVP binary>
+
+- Launch Busybox boot:
+
+  ::
+
+    ./model-scripts/aemfvp-a/boot.sh -p <platform name> -b <bootloader> -n [true|false]
+
+
+Supported command line options are listed below
+
+*  -p <platform name>
+
+   - ``aemfvp-a``
+
+*  -b <bootloader>
+
+   - Select bootloader to boot with Busybox.
+
+   - ``uefi`` (Default)
+   - ``u-boot``
+
+*  -n [true|false] (optional)
+
+   - Enable or disable network controller support on the platform.
+     If network ports have to be enabled, use 'true' as the option.
+     Default value is set to 'false'.
+
+Example commands for booting Busybox are listed below.
+
+- Command to start the execution of the Armv-A Base model to boot up to the
+  Busybox prompt using uefi:
+
+  ::
+
+    ./model-scripts/aemfvp-a/boot.sh -p aemfvp-a -b uefi
+
+- Command to start the execution of the Armv-A Base model to boot up to the
+  Busybox prompt using U-Boot:
+
+  ::
+
+    ./model-scripts/aemfvp-a/boot.sh -p aemfvp-a -b u-boot
+
+- Command to start the execution of the Armv-A Base model to boot up to the
+  Busybox prompt. The selection of the bootloader to be either UEFI or U-Boot
+  is based on command line parameters. The model supports networking allowing
+  the software running within the model to access the network.
+
+  ::
+
+    ./model-scripts/aemfvp-a/boot.sh -p aemfvp-a -b [uefi|u-boot] -n true
+
+  Note: If the user stops autoboot while booting with U-Boot with Busybox and
+  enters the U-Boot command line console, the user must run the following
+  commands to continue the boot process or exit from the U-Boot command line
+  console.
+
+  ::
+
+    run bootcmd
+
+  ::
+
+     Ctrl + ]
+     telnet> close
+
+When the script is executed, three terminal instances will be launched, one for
+the SCP and two for the AP (Application Processor). The SCP will not be used in
+booting of Armv-A Base AEM FVP. The AP will start booting Trusted Firmware-A,
+then UEFI/U-Boot, then BusyBox.
+
+To run terminal-only mode on hosts without graphics/display:
+
+::
+
+        env -u DISPLAY ./model-scripts/aemfvp-a/boot.sh -p <platform name> -b <bootloader>
+
+
+This launches FVP in the background and automatically connects to the
+interactive application console via telnet.
+
+To stop the model, exit telnet:
+
+::
+
+        Ctrl + ]
+        telnet> close
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
+
+.. _user guide: docs/aemfvp-a/user-guide.rst
+.. _troubleshooting guide: docs/aemfvp-a/troubleshooting-guide.rst

docs/aemfvp-a/change-log.rst

+**********
+Change Log
+**********
+
+This document contains a summary of the incremental changes, features,
+fixes and known issues in each release of the Armv-A Base AEM FVP platform stack.
+
+Version 21.09 (2021-R1 release)
+===============================
+Changed
+-------
+- Migration of build system from Yocto to BASH based scripting environment.
+- Migration of source code repository from `ARM linaro GIT`_ to `ARM Gitlab`_.
+- Migration of Kernel from 5.4 to 5.13.
+- Update Trusted Firmware-A to version 2.5.
+- Update U-boot to version 2021.4.
+- Migrate to the latest stable EDK2 version ``edk2-stable202108``.
+- Migrate to the latest EDK2-platforms commit ID ``46026ad759b718142e652618c399a1f68d4e3804``.
+- Changed the Armv-A Base AEM FVP model parameters to enable all the CPU cores.
+- Updated the Armv-A Base AEM FVP model parameters to enable network support.
+
+Features
+--------
+- (AARCH64) UEFI + Busybox boot supported with latest stable kernel version 5.13.
+- (AARCH64) U-Boot + Busybox boot supported with latest stable kernel version 5.13.
+- Linux distribution boot supported and the following distribution are verified
+  with Armv-A Base AEM FVP.
+
+        - Fedora-34-1.2
+        - Ubuntu-20.04.1
+        - Debian-11.0.0
+
+- Add changes for accessing Terminal-0 via Telnet if the Armv-A base AEM FVP
+  is running on a non-Xserver support.
+
+Platform Support
+----------------
+
+- This Software release is tested on Armv-A Base RevC AEM FVP and version is
+  [11.15.18 (Jul 14 2021)].
+
+Known issues or Limitations
+---------------------------
+- Ubuntu 20.04.1 installation may take longer compared to other distribution
+  installations on Armv-A Base AEM FVP.
+- The Armv-A Base AEM FVP model hangs when Linux reboot is triggered after the
+  model is booted with U-Boot and Busybox.
+
+Change logs for the previous releases
+=====================================
+- Refer to the `Old Change Log`_ for detailed information on software features
+  and changes for the previous releases.
+
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
+
+.. _ARM linaro GIT: https://git.linaro.org/landing-teams/working/arm
+.. _ARM Gitlab: https://gitlab.arm.com/arm-reference-solutions
+.. _Old Change Log: https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/tree/docs/basefvp/change-log.rst

docs/aemfvp-a/distro-boot.rst

+**********************************************************************
+Install and boot a Linux distribution on Armv-A Base AEM FVP Platforms
+**********************************************************************
+
+.. contents::
+
+
+Linux distribution boot
+=======================
+
+The Armv-A Base AEM FVP platform software stack supports the installation
+and boot of various Linux distributions such as Debian, Ubuntu, and Fedora. The
+distribution is installed on a SATA disk and since the installed image is
+persistent it can be used for multiple boots.
+
+
+Download the platform software
+==============================
+
+To obtain the required sources for the platform, follow the steps listed on the
+`user guide`_ page. Ensure that the platform software is downloaded before
+proceeding with the steps listed below. Also, note the host machine requirements
+listed on that page which is essential to build and execute the platform
+software stack.
+
+Skip this section if the required sources have been downloaded.
+
+Build the platform software
+===========================
+
+This section describes the procedure to build the platform firmware required to
+install and boot a Linux distribution on Armv-A Base AEM FVP platforms.
+
+To build the Armv-A Base AEM FVP software stack, the command to be used is
+
+::
+
+  ./build-scripts/build-test-uefi.sh -p <platform name> <command>
+
+Supported command line options are listed below
+
+* <platform name>
+
+  - ``aemfvp-a``
+
+* <command>
+
+  - ``clean``
+  - ``build``
+  - ``package``
+  - ``all`` (all of the three above)
+
+
+Examples of the build command are
+
+- Command to clean, build and package the Armv8-A Base AEM FVP software stack required for
+  the distribution installation/boot on the platform:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p aemfvp-a all
+
+- Command to remove the generated outputs (binaries) of the software stack for
+  the Armv8-A Base FVP platform:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p aemfvp-a clean
+
+- Command to perform an incremental build of the software components included in
+  the software stack for the Armv8-A Base platform:
+
+  Note: this command should be followed by the ``package`` command to
+  complete the preparation of the fip image.
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p aemfvp-a build
+
+- Command to package the previously built software stack and prepares the fip
+  image:
+
+  ::
+
+    ./build-scripts/build-test-uefi.sh -p aemfvp-a package
+
+
+Installing a Linux distribution
+===============================
+
+After the platform firmware build for the distribution install/boot is complete,
+a distribution can be installed into a SATA disk image. Before beginning the
+installation process, download the CD iso image of the required distribution
+version.
+
+The distribution installation images can be downloaded from the
+following locations (select an image built for aarch64 architecture):
+
+- `Fedora-34-1.2`_
+- `Ubuntu-20.04.1`_
+- `Debian-11.0.0`_
+
+Refer to the `user guide`_ section ``Obtaining the Arm-A Base AEM FVP``
+for information on downloading the Arm-A Base AEM FVP model.
+
+The commands used to begin the distribution installation are:
+
+- Set ``MODEL`` path before launching the model:
+
+  ::
+
+    export MODEL=<absolute path to the platform FVP binary>
+
+- Launch the installation:
+
+  ::
+
+    ./model-scripts/aemfvp-a/distro.sh -p <platform name> -i <abs_iso_image_path> -s <disk size> -n [true|false]
+
+Supported command line options are listed below
+
+*  -p <platform name>
+
+   - ``aemfvp-a``
+
+*  -i <abs_iso_image_path>
+
+   - Absolute path to the downloaded distribution installer disk image.
+
+*  -s <disk_size>
+
+   - Size of the SATA disk image (in GB) to be created. 12GB and above is
+     good enough for most use cases.
+
+*  -n [true|false] (optional)
+
+   - Enable or disable network controller support on the platform.
+     If network ports have to be enabled, use 'true' as the option.
+     Default value is set to 'false'.
+
+
+An example of a command to install the Fedora distribution is listed below.
+
+::
+
+  ./model-scripts/aemfvp-a/distro.sh -p aemfvp-a -i /absolute/path/to/Fedora-Server-dvd-aarch64-34-1.2.iso -s 16
+
+
+- This command creates a 16GB SATA disk image, boots the Armv8-A Base
+  software stack and starts the installation of Fedora distribution.
+
+- From here on, follow the instructions of the chosen distribution
+  installer. For more information about the installation procedure, refer
+  online installation manuals of the chosen distribution.
+
+- After the installation is completed, the disk image with a random name
+  "<number>.satadisk" will be created in satadisk/ folder.
+  Use this disk image for booting the installed distribution.
+
+
+Additional distribution specific instructions (if any)
+******************************************************
+
+- Debian Distribution installation:
+
+  - During installation, the installer will prompt the user with the message
+    'Load CD-ROM drivers from removable media' and display two options - Yes/No.
+    Select the option 'No'. This is followed by another prompt 'Manually select
+    a CD-ROM module and device?' and displays two options - Yes/No. Select the
+    option 'Yes'. This brings up the module list required for accessing CD-ROM
+    and lists two options - 'none' and 'cdrom'. Select the option 'none' and
+    enter ``/dev/vda``. The installation media on the virtio disk will be
+    detected and installation continues.
+
+
+Booting a Linux distribution
+============================
+
+Refer to the `user guide`_ section ``Obtaining the Arm-A Base AEM FVP``
+for information on downloading the Arm-A Base AEM FVP model.
+
+To boot the installed distribution, use the following commands:
+
+- Set ``MODEL`` path before launching the model:
+
+  ::
+
+    export MODEL=<absolute path to the platform FVP binary>
+
+- Start the distribution boot:
+
+  ::
+
+    ./model-scripts/aemfvp-a/distro.sh -p <platform name> -d <satadisk_path> -n [true|false]
+
+Supported command line options are listed below
+
+*  -p <platform name>
+
+   - ``aemfvp-a``
+
+*  -d <satadisk_path>
+
+   -  Absolute path to the installed distribution disk image created using the
+      instructions listed in the previous section.
+
+*  -n [true|false] (optional)
+
+   - Enable or disable network controller support on the platform.
+     If network ports have to be enabled, use 'true' as the option.
+     Default value is set to 'false'.
+
+Example commands to boot a Linux distribution are listed below.
+
+- Command to look for the available ``.satadisk`` image in the
+  ``satadisk/`` folder and boots with that image. If multiple
+  ``.satadisk`` images are found, it will list them all but won't boot:
+
+  ::
+
+    ./model-scripts/aemfvp-a/distro.sh -p aemfvp-a
+
+
+- Command to begin the distribution boot from the ``fedora.satadisk`` image:
+
+  ::
+
+    ./model-scripts/aemfvp-a/distro.sh -p aemfvp-a -d /absolute/path/to/fedora.satadisk
+
+When the script is executed, three terminal instances will be launched, one for
+the SCP and two for the AP (Application Processor). The SCP will not be used in
+booting of Armv-A Base AEM FVP. The AP will start booting Trusted Firmware-A,
+then UEFI, then Distribution.
+
+To run terminal-only mode on hosts without graphics/display:
+
+::
+
+        env -u DISPLAY ./model-scripts/aemfvp-a/distro.sh -p <platform name> -d <satadisk_path>
+
+
+This launches FVP in the background and automatically connects to the
+interactive application console via telnet.
+
+To stop the model, exit telnet:
+
+::
+
+        Ctrl + ]
+        telnet> close
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
+
+.. _user guide: docs/aemfvp-a/user-guide.rst
+.. _Fedora-34-1.2: https://alt.fedoraproject.org/alt
+.. _Ubuntu-20.04.1: https://old-releases.ubuntu.com/releases/focal
+.. _Debian-11.0.0: https://www.debian.org/distrib/netinst

docs/aemfvp-a/troubleshooting-guide.rst

+*********************
+Troubleshooting Guide
+*********************
+
+.. contents::
+
+Introduction
+============
+
+The documentation for Armv-A Base AEM FVP platform software typically
+suffices in most cases but there could be certain host development machine
+dependencies that could cause failures either during the build or execution
+stages. This page provides solutions for known issues that could affect the
+use of the platform software stack.
+
+
+Error while using repo command
+==============================
+
+The `repo init` or `repo sync` command fails with the below listed error
+message.
+
+::
+
+  File "<path-to-workspace>/.repo/repo/main.py", line 79
+  file=sys.stderr)
+      ^
+  SyntaxError: invalid syntax
+