[edk2-platforms][PATCH 0/3] Introduce Ampere Mt. Jade support to edk2-platforms

[edk2-platforms][PATCH 0/3] Introduce Ampere Mt. Jade support to edk2-platforms

[Nhi Pham]

This short patch series introduces the support for Ampere Computing's
Arm64 hardware platforms, specifically the Mt. Jade platform based on
Ampere's Altra Family processor at this moment.

A public fork of EDK2 for supporting Mt. Jade is currently available at
https://github.com/AmpereComputing/edk2-platforms

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>

Nhi Pham (1):
  Maintainers.txt: Update for Ampere platforms

Phong Vo (2):
  Platform/Ampere: Add Readme.md
  Update Readme.md

 Maintainers.txt           |   6 +
 Platform/Ampere/Readme.md | 167 ++++++++++++++++++++
 Readme.md                 |   3 +
 3 files changed, 176 insertions(+)
 create mode 100644 Platform/Ampere/Readme.md

-- 
2.17.1

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

[Nhi Pham]

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:
+
+- Ubuntu 18.04 (x86)
+- CentOS 8.2 (x86)
+
+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/)
+
+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:
+
+```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
+```
+
+## 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
+   ```
+
+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

[edk2-platforms][PATCH 2/3] Update Readme.md

[Nhi Pham]

From: Phong Vo <phong@os.amperecomputing.com>

Update Readme.md with information about Ampere's Mt. Jade 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>
---
 Readme.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Readme.md b/Readme.md
index d896b2c5fcdf..d00600d35018 100644
--- a/Readme.md
+++ b/Readme.md
@@ -223,6 +223,9 @@ they will be documented with the platform.
 * [Overdrive](Platform/AMD/OverdriveBoard)
 * [Overdrive 1000](Platform/SoftIron/Overdrive1000Board)
 
+## [Ampere](Platform/Ampere/Readme.md)
+* [Mt. Jade](Platform/Ampere/JadePkg)
+
 ## [ARM](Platform/ARM/Readme.md)
 * [Juno](Platform/ARM/JunoPkg)
 * [SGI family](Platform/ARM/SgiPkg)
-- 
2.17.1

[edk2-platforms][PATCH 3/3] Maintainers.txt: Update for Ampere platforms

[Nhi Pham]

This change adds maintainers and reviewers for Ampere platforms.

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: Nhi Pham <nhi@os.amperecomputing.com>
---
 Maintainers.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Maintainers.txt b/Maintainers.txt
index da90c8a11452..4b21dc9805fb 100644
--- a/Maintainers.txt
+++ b/Maintainers.txt
@@ -91,6 +91,14 @@ F: Silicon/AMD/Styx/
 M: Ard Biesheuvel <ard.biesheuvel@arm.com>
 M: Leif Lindholm <leif@nuviainc.com>
 
+Ampere Computing
+F: Platform/Ampere
+F: Silicon/Ampere
+M: Nhi Pham <nhi@os.amperecomputing.com>
+M: Vu Nguyen <vunguyen@os.amperecomputing.com>
+R: Thang Nguyen <thang@os.amperecomputing.com>
+R: Chuong Tran <chuong@os.amperecomputing.com>
+
 ARM
 F: Platform/ARM/
 F: Silicon/ARM/
-- 
2.17.1

Re: [edk2-platforms][PATCH 0/3] Introduce Ampere Mt. Jade support to edk2-platforms

[Leif Lindholm]

On Thu, Dec 03, 2020 at 11:03:59 +0700, Nhi Pham wrote:
> This short patch series introduces the support for Ampere Computing's
> Arm64 hardware platforms,

Well, it doesn't really, does it?
It adds a Maintainers.txt entry, a Readme.md describing a fork
somewhere, and links that Readme into the top-level one.

I think it's great you've posted it here for people to see, but can
you clarify your intent somewhat?
Is this a precursor to a full upstreaming effort?

I don't see a point in merging just this, although I can (and will)
provide some feedback on the documentation.

Best Regards,

Leif

> specifically the Mt. Jade platform based on
> Ampere's Altra Family processor at this moment.
> 
> A public fork of EDK2 for supporting Mt. Jade is currently available at
> https://github.com/AmpereComputing/edk2-platforms
> 
> 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>
> 
> Nhi Pham (1):
>   Maintainers.txt: Update for Ampere platforms
> 
> Phong Vo (2):
>   Platform/Ampere: Add Readme.md
>   Update Readme.md
> 
>  Maintainers.txt           |   6 +
>  Platform/Ampere/Readme.md | 167 ++++++++++++++++++++
>  Readme.md                 |   3 +
>  3 files changed, 176 insertions(+)
>  create mode 100644 Platform/Ampere/Readme.md
> 
> -- 
> 2.17.1
> 

Re: [edk2-devel] [edk2-platforms][PATCH 0/3] Introduce Ampere Mt. Jade support to edk2-platforms

[Nhi Pham]

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

Hi Leif,

Please find my response inline.

On Thu, Dec 3, 2020 at 06:46 PM, Leif Lindholm wrote:

> 
> On Thu, Dec 03, 2020 at 11:03:59 +0700, Nhi Pham wrote:
> 
>> This short patch series introduces the support for Ampere Computing's
>> Arm64 hardware platforms,
> 
> Well, it doesn't really, does it?
> It adds a Maintainers.txt entry, a Readme.md describing a fork
> somewhere, and links that Readme into the top-level one.
> 
> I think it's great you've posted it here for people to see, but can
> you clarify your intent somewhat?
> Is this a precursor to a full upstreaming effort?

Yes, this patch series works as bootstrap that we will push all Mt. Jade code in one shot (about 35 commits) to the edk2-platforms for review after this is approved and merged. This series provides Maintainers and Reviewers in the Maintainer.txt who are responsible for giving code review feedback (Reviewed-by tag) if stewards can not review a large patch series.

Thanks,
Nhi

> 
> 
> I don't see a point in merging just this, although I can (and will)
> provide some feedback on the documentation.
> 
> Best Regards,
> 
> Leif
> 
> 
>> specifically the Mt. Jade platform based on
>> Ampere's Altra Family processor at this moment.
>> 
>> A public fork of EDK2 for supporting Mt. Jade is currently available at
>> https://github.com/AmpereComputing/edk2-platforms
>> 
>> 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>
>> 
>> Nhi Pham (1):
>> Maintainers.txt: Update for Ampere platforms
>> 
>> Phong Vo (2):
>> Platform/Ampere: Add Readme.md
>> Update Readme.md
>> 
>> Maintainers.txt | 6 +
>> Platform/Ampere/Readme.md | 167 ++++++++++++++++++++
>> Readme.md | 3 +
>> 3 files changed, 176 insertions(+)
>> create mode 100644 Platform/Ampere/Readme.md
>> 
>> --
>> 2.17.1
> 
>

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

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

[Leif Lindholm]

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
> 

Re: [edk2-devel] [edk2-platforms][PATCH 0/3] Introduce Ampere Mt. Jade support to edk2-platforms

[Leif Lindholm]

Hi Nhi,

On Thu, Dec 03, 2020 at 04:15:27 -0800, Nhi Pham via groups.io wrote:
> Hi Leif,
> 
> Please find my response inline.
> 
> On Thu, Dec 3, 2020 at 06:46 PM, Leif Lindholm wrote:
> 
> > 
> > On Thu, Dec 03, 2020 at 11:03:59 +0700, Nhi Pham wrote:
> > 
> >> This short patch series introduces the support for Ampere Computing's
> >> Arm64 hardware platforms,
> > 
> > Well, it doesn't really, does it?
> > It adds a Maintainers.txt entry, a Readme.md describing a fork
> > somewhere, and links that Readme into the top-level one.
> > 
> > I think it's great you've posted it here for people to see, but can
> > you clarify your intent somewhat?
> > Is this a precursor to a full upstreaming effort?
> 
> Yes, this patch series works as bootstrap that we will push all
> Mt. Jade code in one shot (about 35 commits) to the edk2-platforms
> for review after this is approved and merged. This series provides
> Maintainers and Reviewers in the Maintainer.txt who are responsible
> for giving code review feedback (Reviewed-by tag) if stewards can
> not review a large patch series.

Glad to hear it!

However, can we keep the Platform/Ampere/Readme.md aligned with what
is currentlt merged in edk2-platforms?
I have given some feedback on that file directly, but I think given
the above statement it would be more appropriate to start with a very
small document describing that upstreaming is in progress, and a link
to
https://github.com/AmpereComputing/edk2-platforms/blob/ampere/Platform/Ampere/Readme.md
.

Best Regards,

Leif

> 
> Thanks,
> Nhi
> 
> > 
> > 
> > I don't see a point in merging just this, although I can (and will)
> > provide some feedback on the documentation.
> > 
> > Best Regards,
> > 
> > Leif
> > 
> > 
> >> specifically the Mt. Jade platform based on
> >> Ampere's Altra Family processor at this moment.
> >> 
> >> A public fork of EDK2 for supporting Mt. Jade is currently available at
> >> https://github.com/AmpereComputing/edk2-platforms
> >> 
> >> 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>
> >> 
> >> Nhi Pham (1):
> >> Maintainers.txt: Update for Ampere platforms
> >> 
> >> Phong Vo (2):
> >> Platform/Ampere: Add Readme.md
> >> Update Readme.md
> >> 
> >> Maintainers.txt | 6 +
> >> Platform/Ampere/Readme.md | 167 ++++++++++++++++++++
> >> Readme.md | 3 +
> >> 3 files changed, 176 insertions(+)
> >> create mode 100644 Platform/Ampere/Readme.md
> >> 
> >> --
> >> 2.17.1
> > 
> >
> 
> 
> 
> 
> 

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

[Nhi Pham]

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

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

[Leif Lindholm]

Hi Nhi,

On Thu, Dec 03, 2020 at 07:44:39 -0800, Nhi Pham via groups.io wrote:
> >> +
> >> +```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?

Yes, that's an omission - ACPI hasn't seen as much churn recently as
it did for a while, but the underlying problems with iasl's lack of
backwards/forwards compatibility has not been resolved.

Would you be happy to do so?

/
    Leif

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

[Nhi Pham]

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

Hi Leif,


________________________________
From: Leif Lindholm <leif@nuviainc.com>
Sent: Friday, December 4, 2020 12:20 AM
To: devel@edk2.groups.io <devel@edk2.groups.io>; Nhi Pham OS <nhi@os.amperecomputing.com>
Subject: Re: [edk2-devel] [edk2-platforms][PATCH 1/3] Platform/Ampere: Add Readme.md

Hi Nhi,

On Thu, Dec 03, 2020 at 07:44:39 -0800, Nhi Pham via groups.io wrote:
> >> +
> >> +```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?

Yes, that's an omission - ACPI hasn't seen as much churn recently as
it did for a while, but the underlying problems with iasl's lack of
backwards/forwards compatibility has not been resolved.

Would you be happy to do so?

[Nhi] Yes, I would be willing to take a look at this as a different topic.  At this moment, it appears that only version 20200110 would work with our code,so we will need to state so specifically in our README.md.

/
    Leif


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