From mboxrd@z Thu Jan 1 00:00:00 1970 Subject: Re: [edk2-devel] [edk2-platforms][PATCH 1/3] Platform/Ampere: Add Readme.md To: Leif Lindholm ,devel@edk2.groups.io From: "Nhi Pham" X-Originating-Location: Ho Chi Minh City, Ho Chi Minh, VN (42.119.193.214) X-Originating-Platform: Mac Chrome 87 User-Agent: GROUPS.IO Web Poster MIME-Version: 1.0 Date: Thu, 03 Dec 2020 07:44:39 -0800 References: <20201203124917.GR1664@vanye> In-Reply-To: <20201203124917.GR1664@vanye> Message-ID: <31782.1607010279980473846@groups.io> Content-Type: multipart/alternative; boundary="TGagCJWLGljCb7dEdFer" --TGagCJWLGljCb7dEdFer Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Hi Leif, Please find my responds inline. On Thu, Dec 3, 2020 at 07:49 PM, Leif Lindholm wrote: >=20 > On Thu, Dec 03, 2020 at 11:04:00 +0700, Nhi Pham wrote: >=20 >> From: Phong Vo >>=20 >> Add initial version of Readme.md for Ampere platform >>=20 >> Cc: Leif Lindholm >> Cc: Michael D Kinney >> Cc: Ard Biesheuvel >> Cc: Nate DeSimone >>=20 >> Signed-off-by: Phong Vo >> --- >> Platform/Ampere/Readme.md | 167 ++++++++++++++++++++ >> 1 file changed, 167 insertions(+) >>=20 >> 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: >=20 > s/are supported/have been verified/ Thanks, will fix it. >=20 >=20 >> + >> +- Ubuntu 18.04 (x86) >> +- CentOS 8.2 (x86) >=20 > *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=3D1&playlist=3DnqxbeE= y8dMk&loop=3D1 >=20 Thanks Leif for the catch.=C2=A0 I'll update this to include our supported= platforms as native compilation works, too. >=20 >=20 >> +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 oth= er >> 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/comp= ilers/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/ >> ) >=20 > 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=E2=80=99ll update to clarify the use of Ampere=E2=80=99s custom toolcha= in as an option, for both cross compiling and native compiling. >=20 > 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. >=20 >=20 >> +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: >=20 > IASL Thanks. Will fix. >=20 >=20 >> + >> +```bash >> +$ wget https://acpica.org/sites/acpica/files/acpica-unix2-20200110.tar= .gz >>=20 >> +$ tar xzf acpica-unix2-20200110.tar.gz >> +$ cd acpica-unix2-20200110 >> +$ make && sudo make install >> +$ iasl -v >> +``` >=20 > 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 s= hould add it? >=20 > Here, it would be more useful to document which is the minimum (and > worst case, maximum) version needed, and why. >=20 >=20 >> + >> +## 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=3D/work/git/tianocore >> + $ mkdir -p $WORKSPACE >> + $ cd $WORKSPACE >> + ``` >> + >> +2. Into that folder, clone: >> + >> + ```bash >> + $ git clone --recurse-submodules https://github.com/AmpereComputing/e= dk2.git >>=20 >> + $ git clone --recurse-submodules https://github.com/AmpereComputing/e= dk2-platforms.git >>=20 >> + ``` >=20 > Not relevant for this repo. Thanks. Will fix. >=20 >=20 > / > Leif >=20 >=20 >> + >> +Set up a PACKAGES_PATH to point to the locations of these three >> repositories: >> +`$ export PACKAGES_PATH=3D$PWD/edk2:$PWD/edk2-platforms` >> + >> +## Manual building >> + >> +### Additional environment setup >> + >> +```bash >> +$ export >> CROSS_COMPILER_PATH=3D/opt/toolchain/ampere-8.3.0-20191025-dynamic-nosy= sroot/bin >>=20 >> +$ export PATH=3D${CROSS_COMPILER_PATH}:${PATH} >> +$ export CROSS_COMPILE=3Daarch64-ampere-linux-gnu- >> +$ export GCC5_AARCH64_PREFIX=3D${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 w= e >> 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 AARCH= 64. >>=20 >> +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=3D$((`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 t= he >> 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 >=20 > --TGagCJWLGljCb7dEdFer Content-Type: text/html; charset="utf-8" Content-Transfer-Encoding: quoted-printable 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 L= indholm <leif@nuviainc.com>
Cc: Michael D Kinney <michael.d.k= inney@intel.com>
Cc: Ard Biesheuvel <ard.biesheuvel@arm.com><= br />Cc: Nate DeSimone <nathaniel.l.desimone@intel.com>

Si= gned-off-by: Phong Vo <phong@os.amperecomputing.com>
---
Pl= atform/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..c93b35= a62e84
--- /dev/null
+++ b/Platform/Ampere/Readme.md
@@ -0,0= +1,167 @@
+# Overview
+
+This document provides the guideli= ne 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)
+
+## B= uild 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?aut= oplay=3D1&playlist=3DnqxbeEy8dMk&loop=3D1
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 fo= r 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<= br />+
+The following is the list of tools needed for development: `bi= son, build-essential, bzip2, default-jre, flex
+gawk, gpg, libc6:i386,= libgcc1:i386, openssl, libssl-dev, m4, make, python, python3-distutils, ta= r, uuid-dev wget`
+
+They can be installed using standard OS dist= ro's `apt-get` (for Ubuntu) or `yum` (for CentOS).
+
+## Toolchai= n
+
+### GCC for aarch64
+
+Ampere provides GCC toolcha= ins
+[aarch64-ampere-linux-gnu](https://cdn.amperecompu= ting.com/tools/compilers/cross/8.3.0/ampere-8.3.0-20191025-dynamic-nosysroo= t-crosstools.tar.xz)
+
+Linaro provides GCC toolchains for+[aarch64-linux-gnu](https://releases.linaro.org/components/toolchain/binaries/latest/aarch= 64-linux-gnu/)
Why on earth would you want custom toolchains?
Even *if* cross compil= ing, all of the relevant distributions have
packaged aarch64 cross com= pilers since LTS versions no longer
supported.
We’ll update to clarify the use of Ampere’s custom toolchain a= s 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 i= nstalled 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.
+
+Targ= et architecture | Cross compilation prefix
+--------------------|-----= --------------------
+AARCH64 | aarch64-linux-gnu- (Linaro toolchain)<= br />+AARCH64 | aarch64-ampere-linux-gnu- (Ampere toolchain)
+
+#= ## Intel ASL+ Optimizing Compiler/Disassembler
+
+Download and in= stall 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-2020= 0110
+$ make && sudo make install
+$ iasl -v
+``` I could well believe a newer version of IASL than shipped with the
ab= ovementioned Linux distros would be required. However, Instructions
fo= r 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 s= hould 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
+appropr= iate for your needs.
+
+ ```bash
+ $ export WORKSPACE=3D/wor= k/git/tianocore
+ $ mkdir -p $WORKSPACE
+ $ cd $WORKSPACE
+ = ```
+
+2. Into that folder, clone:
+
+ ```bash
+ $= git clone --recurse-submodules https://github.com/AmpereCo= mputing/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 th= ese three repositories:
+`$ export PACKAGES_PATH=3D$PWD/edk2:$PWD/edk2= -platforms`
+
+## Manual building
+
+### Additional env= ironment setup
+
+```bash
+$ export CROSS_COMPILER_PATH=3D/o= pt/toolchain/ampere-8.3.0-20191025-dynamic-nosysroot/bin
+$ export PAT= H=3D${CROSS_COMPILER_PATH}:${PATH}
+$ export CROSS_COMPILE=3Daarch64-a= mpere-linux-gnu-
+$ export GCC5_AARCH64_PREFIX=3D${CROSS_COMPILE}
+```
+
+1. Set up the build environment (this will modify your e= nvironment variables)
+
+ `$ . edk2/edksetup.sh`
+
+ (T= his step _depends_ on **WORKSPACE** being set as per above.)
+
+2= . Build BaseTools
+
+ `make -C edk2/BaseTools`
+
+ (Bas= eTools can currently not be built in parallel, so do not specify any `-j`+ option, either on the command line or in a **MAKEFLAGS** environment<= br />+ variable.)
+
+### Build options
+
+There are a n= umber of options that can (or must) be specified at the point of
+buil= ding. 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 fi= le.
+
+target.txt option | command line | Description
+-----= -------------|--------------|------------
+ACTIVE_PLATFORM | `-p` | De= scription file (.dsc) of platform
+TARGET | `-b` | One of DEBUG, RELEA= SE or NOOPT.
+TARGET_ARCH | `-a` | Architecture to build for. In our c= ase, use AARCH64.
+TOOL_CHAIN_TAG | `-t` | Toolchain profile to use fo= r building. In our case, use GCC5.
+
+There is also MAX_CONCURREN= T_THREAD_NUMBER (`-n`), roughly equivalent to
+`make -j`.
+
= +When specified on command line, `-b` can be repeated multiple times in ord= er to
+build multiple targets sequentially.
+
+After a succe= ssful build, the resulting images can be found in
+`Build/{Platform Na= me}/{TARGET}_{TOOL_CHAIN_TAG}/FV`.
+
+For example,
+`Build/J= ade/RELEASE_GCC5/FV`
+
+### Build a platform
+
+The mai= n 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=3D$((`getconf _NPROCESSORS_ONLN= ` + 2))
+```
+
+Now build the UEFI image:
+
+```ba= sh
+$ 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 t= hrough
+searching in all locations specified in **PACKAGES_PATH**.)+
+## Additional build tools
+
+Ampere provides additiona= l tools and documentation for automating the manual process described above= ,
+and for building a final Tianocore UEFI image that can be flashed o= n the target system.
+
+To use these tools, clone the following t= o the **WORKSPACE** location:
+
+```bash
+$ git clone https://github.com/AmpereComputing/edk2-ampere-tools= .git
+```
--
2.17.1
--TGagCJWLGljCb7dEdFer--