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

["Nhi Pham" <nhi@os.amperecomputing.com>]

[-- Attachment #1: Type: text/plain, Size: 8836 bytes --]

Hi Leif,

Please find my responds inline.

On Thu, Dec 3, 2020 at 07:49 PM, Leif Lindholm wrote:

> 
> 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/

Thanks, will fix it.

> 
> 
>> +
>> +- 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
> 

Thanks Leif for the catch.  I'll update this to include our supported platforms as native compilation works, too.

> 
> 
>> +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.

We’ll update to clarify the use of Ampere’s custom toolchain as an option, for both cross compiling and native compiling.

> 
> 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

Thanks. Will fix.

> 
> 
>> +
>> +```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.

The top level README does not mention the IASL compiler. Do you think we should add it?

> 
> 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.

Thanks. Will fix.

> 
> 
> /
> 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
> 
>

[-- Attachment #2: Type: text/html, Size: 10144 bytes --]