Commit 35be53fa authored by Selvarasu Ganesan's avatar Selvarasu Ganesan Committed by Deepak Pandey
Browse files

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's avatarSelvarasu Ganesan <selvarasu.ganesan@arm.com>
Change-Id: I81f548886901c2b03074283df1ec7d7558d26166
parent 0537883d
*********************************************
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
**********
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
**********************************************************************
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
*********************
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)
^