Re: [edk2-platforms][PATCH 1/3] Platform/Ampere: Add Readme.md

["Leif Lindholm" <leif@nuviainc.com>]

On Thu, Dec 03, 2020 at 11:04:00 +0700, Nhi Pham wrote:
> From: Phong Vo <phong@os.amperecomputing.com>
> 
> Add initial version of Readme.md for Ampere platform
> 
> Cc: Leif Lindholm <leif@nuviainc.com>
> Cc: Michael D Kinney <michael.d.kinney@intel.com>
> Cc: Ard Biesheuvel <ard.biesheuvel@arm.com>
> Cc: Nate DeSimone <nathaniel.l.desimone@intel.com>
> 
> Signed-off-by: Phong Vo <phong@os.amperecomputing.com>
> ---
>  Platform/Ampere/Readme.md | 167 ++++++++++++++++++++
>  1 file changed, 167 insertions(+)
> 
> diff --git a/Platform/Ampere/Readme.md b/Platform/Ampere/Readme.md
> new file mode 100644
> index 000000000000..c93b35a62e84
> --- /dev/null
> +++ b/Platform/Ampere/Readme.md
> @@ -0,0 +1,167 @@
> +# Overview
> +
> +This document provides the guideline to build UEFI firmware for Ampere Computing's arm64 reference platforms.
> +
> +Platform code is located under Platform/Ampere/{Platform Name}Pkg.
> +
> +Silicon code is located under Silicon/Ampere/Ampere{SoC Name}Pkg.
> +
> +# How to build (Linux Environment)
> +
> +## Build machines
> +
> +The build instructions provided in this document are supported on the following operating systems:

s/are supported/have been verified/

> +
> +- Ubuntu 18.04 (x86)
> +- CentOS 8.2 (x86)

*sigh*
These platforms have 160-cores, support 8TB of DRAM, and you *still*
consider cross compilation from another architecture to be how to
build software for them?
https://www.youtube.com/embed/nqxbeEy8dMk?autoplay=1&playlist=nqxbeEy8dMk&loop=1

> +However, it does not mean this guideline is not applicable for other Ubuntu/CentOS versions,
> +or other Linux distributions. You may, at your own risk, try it on other Linux distributions
> +if all steps below are performed correctly.
> +
> +## Essential development tools
> +
> +The following is the list of tools needed for development: `bison, build-essential, bzip2, default-jre, flex
> +gawk, gpg, libc6:i386, libgcc1:i386, openssl, libssl-dev, m4, make, python, python3-distutils, tar, uuid-dev wget`
> +
> +They can be installed using standard OS distro's `apt-get` (for Ubuntu) or `yum` (for CentOS).
> +
> +## Toolchain
> +
> +### GCC for aarch64
> +
> +Ampere provides GCC toolchains
> +[aarch64-ampere-linux-gnu](https://cdn.amperecomputing.com/tools/compilers/cross/8.3.0/ampere-8.3.0-20191025-dynamic-nosysroot-crosstools.tar.xz)
> +
> +Linaro provides GCC toolchains for
> +[aarch64-linux-gnu](https://releases.linaro.org/components/toolchain/binaries/latest/aarch64-linux-gnu/)

Why on earth would you want custom toolchains?
Even *if* cross compiling, all of the relevant distributions have
packaged aarch64 cross compilers since LTS versions no longer
supported.

On the whole though, instructions for how to build a platform is
already documented in the top-level Readme.md. This file should
restrict itself to aspects that are specific to Ampere.

> +Throughout this document, Ampere toolchain is assumed to be installed at location /opt/toolchain/.
> +
> +When cross compiling, it is necessary to provide the appropriate compilation prefix depending on
> +whether Ampere toolchain or Linaro toolchain is used.
> +
> +Target architecture | Cross compilation prefix
> +--------------------|-------------------------
> +AARCH64             | aarch64-linux-gnu-  (Linaro toolchain)
> +AARCH64             | aarch64-ampere-linux-gnu- (Ampere toolchain)
> +
> +### Intel ASL+ Optimizing Compiler/Disassembler
> +
> +Download and install the ISAL compiler as follows:

IASL

> +
> +```bash
> +$ wget https://acpica.org/sites/acpica/files/acpica-unix2-20200110.tar.gz
> +$ tar xzf acpica-unix2-20200110.tar.gz
> +$ cd acpica-unix2-20200110
> +$ make && sudo make install
> +$ iasl -v
> +```

I could well believe a newer version of IASL than shipped with the
abovementioned Linux distros would be required. However, Instructions
for how to rebuild/install a newer acpica-tools would be better to
have in the top-level Readme.md.
Here, it would be more useful to document which is the minimum (and
worst case, maximum) version needed, and why.

> +
> +## Obtaining source code
> +
> +1. Create a new folder (directory) on your local development machine
> +for use as your workspace. This example uses `/work/git/tianocore`, modify as
> +appropriate for your needs.
> +
> +   ```bash
> +   $ export WORKSPACE=/work/git/tianocore
> +   $ mkdir -p $WORKSPACE
> +   $ cd $WORKSPACE
> +   ```
> +
> +2. Into that folder, clone:
> +
> +   ```bash
> +   $ git clone --recurse-submodules https://github.com/AmpereComputing/edk2.git
> +   $ git clone --recurse-submodules https://github.com/AmpereComputing/edk2-platforms.git
> +   ```

Not relevant for this repo.

/
    Leif

> +
> +Set up a PACKAGES_PATH to point to the locations of these three repositories:
> +`$ export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms`
> +
> +## Manual building
> +
> +### Additional environment setup
> +
> +```bash
> +$ export CROSS_COMPILER_PATH=/opt/toolchain/ampere-8.3.0-20191025-dynamic-nosysroot/bin
> +$ export PATH=${CROSS_COMPILER_PATH}:${PATH}
> +$ export CROSS_COMPILE=aarch64-ampere-linux-gnu-
> +$ export GCC5_AARCH64_PREFIX=${CROSS_COMPILE}
> +```
> +
> +1. Set up the build environment (this will modify your environment variables)
> +
> +   `$ . edk2/edksetup.sh`
> +
> +   (This step _depends_ on **WORKSPACE** being set as per above.)
> +
> +2. Build BaseTools
> +
> +   `make -C edk2/BaseTools`
> +
> +   (BaseTools can currently not be built in parallel, so do not specify any `-j`
> +   option, either on the command line or in a **MAKEFLAGS** environment
> +   variable.)
> +
> +### Build options
> +
> +There are a number of options that can (or must) be specified at the point of
> +building. Their default values are set in `edk2/Conf/target.txt`. If we are
> +working only on a single platform, it makes sense to just update this file.
> +
> +target.txt option | command line | Description
> +------------------|--------------|------------
> +ACTIVE_PLATFORM   | `-p`         | Description file (.dsc) of platform
> +TARGET            | `-b`         | One of DEBUG, RELEASE or NOOPT.
> +TARGET_ARCH       | `-a`         | Architecture to build for. In our case, use AARCH64.
> +TOOL_CHAIN_TAG    | `-t`         | Toolchain profile to use for building. In our case, use GCC5.
> +
> +There is also MAX_CONCURRENT_THREAD_NUMBER (`-n`), roughly equivalent to
> +`make -j`.
> +
> +When specified on command line, `-b` can be repeated multiple times in order to
> +build multiple targets sequentially.
> +
> +After a successful build, the resulting images can be found in
> +`Build/{Platform Name}/{TARGET}_{TOOL_CHAIN_TAG}/FV`.
> +
> +For example,
> +`Build/Jade/RELEASE_GCC5/FV`
> +
> +### Build a platform
> +
> +The main build process _can_ run in parallel - so figure out how many threads we
> +have available.
> +
> +```bash
> +$ getconf _NPROCESSORS_ONLN
> +8
> +```
> +
> +Set up the build to use a little more than that:
> +
> +```bash
> +$ NUM_CPUS=$((`getconf _NPROCESSORS_ONLN` + 2))
> +```
> +
> +Now build the UEFI image:
> +
> +```bash
> +$ cd edk2-platforms && build -a AARCH64 -t GCC5 -b RELEASE -D SECURE_BOOT_ENABLE -p Platform/Ampere/JadePkg/Jade.dsc
> +```
> +
> +(Note that the description file gets resolved by the build command through
> +searching in all locations specified in **PACKAGES_PATH**.)
> +
> +## Additional build tools
> +
> +Ampere provides additional tools and documentation for automating the manual process described above,
> +and for building a final Tianocore UEFI image that can be flashed on the target system.
> +
> +To use these tools, clone the following to the **WORKSPACE** location:
> +
> +```bash
> +$ git clone https://github.com/AmpereComputing/edk2-ampere-tools.git
> +```
> -- 
> 2.17.1
>