[PATCH edk2-platforms v1] Add build docs for Arm plats FVP and Juno

[PATCH edk2-platforms v1] Add build docs for Arm plats FVP and Juno

[jose.marinho]

Signed-off-by: Jose Marinho <jose.marinho@arm.com>

Cc: Sami Mujawar <sami.mujawar@arm.com>
Cc: Samer El-Haj-Mahmoud <samer.el-haj-mahmoud@arm.com>
---
 Platform/ARM/Readme.md | 315 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 315 insertions(+)
 create mode 100644 Platform/ARM/Readme.md

diff --git a/Platform/ARM/Readme.md b/Platform/ARM/Readme.md
new file mode 100644
index 0000000000..8c48bd0d7b
--- /dev/null
+++ b/Platform/ARM/Readme.md
@@ -0,0 +1,315 @@
+# Introduction
+
+These instructions explain how to get an edk2/edk2-platforms build running
+on the Arm Base FVP and a Juno. The Arm Base FVP is a software model provided by ARM (for free)
+, which models a Cortex A core with various peripherals. More information
+can be found [here](https://developer.arm.com/products/system-design/fixed-virtual-platforms).
+
+## Build environment setup on Linux or Windows
+
+### Initial steps
+
+The first step towards building an EDKII firmware image is to create a working directory.
+
+1. Launch a terminal window.
+2. Create a directory on your development machine (we willl name it 'source' in this example).
+3. Set the WORKSPACE environment variable to point to this directory.
+
+#### Example:
+In a Linux bash shell:
+```
+cd <Directory where you want to work>
+mkdir source
+cd source
+export WORKSPACE=$PWD
+```
+
+OR
+
+In a Windows command prompt:
+
+```
+cd <Directory where you want to work>
+mkdir source
+cd source
+set WORKSPACE=%CD%
+```
+
+### Cloning the source code repositories
+
+Note: To clone the repositories you need 'git' to be installed on your development PC (see Development Tools).
+
+In the terminal window, change directory to your workspace ('source') folder and run the following commands. Install Git if necessary.
+
+```
+git clone https://github.com/tianocore/edk2.git
+git clone https://github.com/tianocore/edk2-platforms.git
+git clone https://github.com/acpica/acpica.git
+```
+
+Then go to the edk2 folder and update the submodules.
+
+```
+cd edk2
+git submodule update --init
+cd ..
+```
+
+# Building firmware on a Linux host
+
+## Prerequisites
+
+- A 64-bit development machine.
+- Ubuntu 20.04 desktop.
+- At least 10GB of free disk space.
+
+Check the Ubuntu version by typing the following in the terminal window.
+
+```
+$ uname -srvmpio
+Linux 5.4.0-131-generic #147-Ubuntu SMP Fri Oct 14 17:07:22 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
+```
+
+### Development Tools
+
+The following tools must be installed on the development PC.
+
+
+| Sr. No.   | Tool                | Description                                                  | Install instructions                                     |
+|-----------|---------------------|--------------------------------------------------------------|----------------------------------------------------------|
+| 1         | Python 3            | Python interpreter                                           | $ sudo apt install python3 python3-distutils             |
+| 2         | Git                 | Git source control tool                                      | $ sudo apt install git                                   |
+| 3         | uuid-dev            | Required for including uuid/uuid.h                           | $ sudo apt install uuid-dev                              |
+| 4         | build-essential     | Installs make, gcc, g++, etc                                 | $ sudo apt install build-essential <br> $ make -v <br> GNU Make 4.2.1 <br> gcc --version <br> gcc (Ubuntu 9.4.0-1ubuntu1~20.04.1) 9.4.0 <br> $ g++ --version <br> g++ (Ubuntu 9.4.0-1ubuntu1\~20.04.1) 9.4.0 |
+| 5         | bison               | A parser generator required by acpica tools.                 | $ sudo apt install bison                                 |
+| 6         | flex                | A fast lexical analyzer generator required by acpica tools   | $ sudp apt get install flex                              |
+
+### Setting up the development tools
+
+Install the required development tools by running the following commands in the terminal window.
+
+```
+$ sudo apt install bison build-essential flex git uuid-dev
+ ```
+
+```
+$ sudo apt install python3 python3-distutils
+ ```
+
+### Arm cross compiler toolchain
+
+The Arm toolchain to cross compile from x86_64-linux to aarch64-elf is available [here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
+
+Select the latest toolchain to match the development PC architecture. Select the little-endian 'AArch64 ELF bare-metal target (aarch64-elf)' GCC cross compiler.
+
+Example: For a x86_64 development PC, download arm-gnu-toolchain-12.2.rel1-x86_64-aarch64-none-elf.tar.xz
+
+Create a directory called 'toolchain' under the workspace folder. For example source\toolchain and extract the toolchain to this directory.
+
+```
+$ mkdir $WORKSPACE/toolchain
+$ cd $WORKSPACE/toolchain
+$ wget https://armkeil.blob.core.windows.net/developer/Files/downloads/gnu/12.2.rel1/binrel/arm-gnu-toolchain-12.2.rel1-x86_64-aarch64-none-elf.tar.xz
+$ tar xf arm-gnu-toolchain-12.2.rel1-x86_64-aarch64-none-elf.tar.xz
+$ cd $WORKSPACE
+```
+
+### Build the acpica tools
+
+The acpica tools implement the latest iasl compiler. To build the acpica tools, run the following commands in the terminal window.
+
+```
+$ make -C $WORKSPACE/acpica
+```
+
+## Building EDKII firmware
+
+1. To build the firmware image, follow the steps below and run the commands in the terminal window.
+
+2. Set up the environment variables.
+
+```
+$ export GCC5_AARCH64_PREFIX=$WORKSPACE/toolchain/arm-gnu-toolchain-12.2.rel1-x86_64-aarch64-none-elf/bin/aarch64-none-elf-
+$ export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-platforms
+$ export IASL_PREFIX=$WORKSPACE/acpica/generate/unix/bin/
+$ export PYTHON_COMMAND=/usr/bin/python3
+```
+
+3. Configure the EDKII development environment by running the edk2setup bash script.
+```
+$ source edk2/edksetup.sh
+```
+
+4. Build the BaseTools.
+```
+$ make -C edk2/BaseTools
+```
+
+### Build the firmware for Arm FVP Base AEMv8A-AEMv8A Model platform
+
+Run the following command to build the firmware for FVP Base AEMv8A-AEMv8A platform.
+```
+$ build -a AARCH64 -t GCC5 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AArch64.dsc -b < DEBUG | RELEASE >
+```
+
+The firmware binaries can be found at the following location:
+```
+$WORKSPACE/Build/ArmVExpress-FVP-AArch64/<DEBUG|RELEASE>_GCC5/FV/FVP_AARCH64_EFI.fd
+```
+
+### Build the firmware for Arm Juno platform
+
+Run the following command to build the firmware for Arm Juno platform.
+```
+$ build -a AARCH64 -t GCC5 -p Platform/ARM/JunoPkg/ArmJuno.dsc -b < DEBUG | RELEASE >
+```
+
+The firmware binaries can be found at the following location:
+```
+$WORKSPACE/Build/ArmJuno/<DEBUG|RELEASE>_GCC5/FV/BL33_AP_UEFI.fd
+```
+
+# Building firmware on a Windows host using Windows Subsystem for Linux (WSL)
+
+The instructions for building the firmware using WSL are similar to that for a Linux host.
+The prerequisites for setting up the Windows Subsystem for Linux environment are listed below.
+
+## Prerequisites
+
+- A x64 development machine with Windows 10 (Version 21H2 - OS Build 19044.2486).
+- At least 10GB of free disk space.
+- Install the Windows Subsystem for Linux. Select Ubuntu 20.04 LTS from the Microsoft Store.
+
+Check the Ubuntu version by typing the following on the console.
+```
+$ uname -srvmpio
+Linux 4.4.0-19041-Microsoft #2311-Microsoft Tue Nov 08 17:09:00 PST 2022 x86_64 x86_64 x86_64 GNU/Linux
+```
+
+The remaining instructions for installing the development tools, configuring the development environment and building firmware are exactly the same as those for a Linux host.
+
+# Building firmware on a x64 Windows host
+
+#### Prerequisites
+
+- A 64-bit development machine
+- Windows 10 desktop (Version 21H2 - OS Build 19044.2486)
+- At least 10GB of free disk space.
+
+#### Development Tools
+
+The following tools must be installed on the development machine.
+
+| Sr. No.   | Tool                                         | Description                                                  | Install instructions                                     |
+|-----------|----------------------------------------------|--------------------------------------------------------------|----------------------------------------------------------|
+| 1         | Python 3                                     | Python interpreter                                           | Go [here](https://www.python.org/downloads/windows/) <br> <br> Choose the latest Python 3.X release. <br> <br> Download and run the Windows x86_64 MSI installer <br> <br> If needed, add the python executable to your path by executing the following command: <br> > set PATH=<Path_to_the_python_executable>;%PATH%  |
+| 2         | Git                                          | Git source control tool                                      | Go [here](https://git-scm.com/download/win) <br> <br> Download and run the 64-bit Git for Windows Setup |
+| 3         | ASL tools                                    | iasl compiler and other tools for the ASL language           | Go [here](https://www.acpica.org/downloads/binary-tools)  <br> <br> Download the iASL Compiler and Windows ACPI Tools <br> <br> Extract the content and place it at C:\ASL\ <br> <br> Check that the compiler is at the right place by executing: <br> > C:\ASL\iasl.exe -v |
+| 4         | Microsoft Visual Studio 2019 Professional    | Microsoft IDE and compiler toolchain.                        | Go [here](https://visualstudio.microsoft.com/downloads/) <br> <br> Download and install Visual Studio 2019 Professional |
+| 5         | echo tool                                    | Echo                                                         | See Workaround for echo command below. |
+
+
+## Setting up the development tools
+
+Install the required development tools listed above by running the appropriate installer applications.
+
+### Arm cross compiler toolchain
+The Arm toolchain Windows (i686-mingw32) hosted cross compilers are available [here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
+
+Select the latest toolchain for 'AArch64 bare-metal target (aarch64-none-elf)' GCC cross compiler.
+
+Example: Download arm-gnu-toolchain-12.2.rel1-mingw-w64-i686-aarch64-none-elf
+
+Create a directory called 'toolchain' under the workspace directory and extract the toolchain to this directory using the downloaded installer.
+
+The toolchain folder tree should look as below:
+
+```
+toolchain
++---arm-gnu-toolchain-12.2.rel1-mingw-w64-i686-aarch64-none-elf
+|   +---aarch64-none-elf
+|   +---bin
+|   +---include
+|   +---lib
+|   +---libexec
+|   +---share
+```
+
+### Workaround for the echo command
+
+EDKII needs a workaround related to the echo command. A script replacing the Windows echo executable must be created, with the name "echo.BAT?:
+
+- Create a file named "echo.BAT" in the folder of your choice.
+- Paste the following lines inside the file:
+
+```
+rem %~f0  echo.BAT  %*
+rem This file exists to overcome a problem in the EDKII build where
+rem build_rule.template invokes a command as:
+rem     "$(OBJCOPY)" $(OBJCOPY_FLAGS) ${dst}
+rem When OBJCOPY is set to echo, this results in the following error:
+rem     "echo" objcopy not needed for m:\...\PCD\Dxe\Pcd\DEBUG\PcdDxe.dll
+rem And CMD.EXE fails to find the DOS echo command because of the quotes
+@echo %*
+@goto :EOF
+```
+
+- Add the file to your PATH by executing:
+```
+> set PATH=<Path_to_the_echo_file>;%PATH%
+```
+
+## Building EDKII firmware
+
+1. To build the firmware image, follow the steps below and run the commands in the terminal window.
+2. Set up the environment variables.
+
+```
+ set GCC5_AARCH64_PREFIX=%WORKSPACE%\toolchain\arm-gnu-toolchain-12.2.rel1-mingw-w64-i686-aarch64-none-elf\bin\aarch64-none-elf-
+ set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-platforms
+ set EDK_TOOLS_PATH=%WORKSPACE%\edk2\BaseTools
+ set GCC_HOST_BIN=n
+```
+
+Select the python version you wish to use and set the PYTHON_COMMAND environment variable to your Python executable.
+
+Set the PYTHON_COMMAND to point to the Python3 executable.
+
+Check that your path is set up as it is stated in the development tools table above. It should give access to:
+
+- The make executable
+- The echo.BAT script
+
+3. Configure the EDKII development environment by running the edksetup.bat script.
+The Rebuild option can be skipped if the BaseTools have already been built.
+
+The ForceRebuild option can be used to do a clean build of the Base tools.
+```
+> call %WORKSPACE%\edk2\edksetup.bat [Rebuild | ForceRebuild]
+```
+
+### Build the firmware for Arm FVP Base AEMv8A-AEMv8A Model platform
+
+Run the following command to build the firmware for FVP Base AEMv8A-AEMv8A platform.
+
+```
+> build -a AARCH64 -t GCC5 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AArch64.dsc -b < DEBUG | RELEASE >
+```
+
+The firmware binaries can be found at the following location:
+```
+%WORKSPACE%\Build\ArmVExpress-FVP-AArch64\<DEBUG|RELEASE>_GCC5\FV\FVP_AARCH64_EFI.fd
+```
+
+### Build the firmware for Arm Juno platform
+
+Run the following command to build the firmware for Arm Juno platform.
+
+```
+> build -a AARCH64 -t GCC5 -p Platform\ARM\JunoPkg\ArmJuno.dsc -b < DEBUG | RELEASE >
+```
+The firmware binaries are at the following location:
+
+```
+%WORKSPACE%\Build\ArmJuno\<DEBUG|RELEASE>_GCC5\FV\BL33_AP_UEFI.fd
+```
-- 
2.25.1