From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by mx.groups.io with SMTP id smtpd.web11.11726.1678187050466402859 for ; Tue, 07 Mar 2023 03:04:10 -0800 Authentication-Results: mx.groups.io; dkim=missing; spf=pass (domain: arm.com, ip: 217.140.110.172, mailfrom: jose.marinho@arm.com) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 51A6E113E; Tue, 7 Mar 2023 03:04:53 -0800 (PST) Received: from josmar02Desktop.cambridge.arm.com (josmar02Desktop.cambridge.arm.com [10.2.78.53]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 0591F3F5A1; Tue, 7 Mar 2023 03:04:08 -0800 (PST) From: jose.marinho@arm.com To: devel@edk2.groups.io Cc: nd@arm.com, Jose Marinho , Sami Mujawar , Samer El-Haj-Mahmoud Subject: [PATCH edk2-platforms v1] Add build docs for Arm plats FVP and Juno Date: Tue, 7 Mar 2023 11:03:42 +0000 Message-Id: <20230307110342.433330-1-jose.marinho@arm.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Signed-off-by: Jose Marinho Cc: Sami Mujawar Cc: Samer El-Haj-Mahmoud --- 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=0D +=0D +These instructions explain how to get an edk2/edk2-platforms build running= =0D +on the Arm Base FVP and a Juno. The Arm Base FVP is a software model provi= ded by ARM (for free)=0D +, which models a Cortex A core with various peripherals. More information= =0D +can be found [here](https://developer.arm.com/products/system-design/fixed= -virtual-platforms).=0D +=0D +## Build environment setup on Linux or Windows=0D +=0D +### Initial steps=0D +=0D +The first step towards building an EDKII firmware image is to create a wor= king directory.=0D +=0D +1. Launch a terminal window.=0D +2. Create a directory on your development machine (we willl name it 'sourc= e' in this example).=0D +3. Set the WORKSPACE environment variable to point to this directory.=0D +=0D +#### Example:=0D +In a Linux bash shell:=0D +```=0D +cd =0D +mkdir source=0D +cd source=0D +export WORKSPACE=3D$PWD=0D +```=0D +=0D +OR=0D +=0D +In a Windows command prompt:=0D +=0D +```=0D +cd =0D +mkdir source=0D +cd source=0D +set WORKSPACE=3D%CD%=0D +```=0D +=0D +### Cloning the source code repositories=0D +=0D +Note: To clone the repositories you need 'git' to be installed on your dev= elopment PC (see Development Tools).=0D +=0D +In the terminal window, change directory to your workspace ('source') fold= er and run the following commands. Install Git if necessary.=0D +=0D +```=0D +git clone https://github.com/tianocore/edk2.git=0D +git clone https://github.com/tianocore/edk2-platforms.git=0D +git clone https://github.com/acpica/acpica.git=0D +```=0D +=0D +Then go to the edk2 folder and update the submodules.=0D +=0D +```=0D +cd edk2=0D +git submodule update --init=0D +cd ..=0D +```=0D +=0D +# Building firmware on a Linux host=0D +=0D +## Prerequisites=0D +=0D +- A 64-bit development machine.=0D +- Ubuntu 20.04 desktop.=0D +- At least 10GB of free disk space.=0D +=0D +Check the Ubuntu version by typing the following in the terminal window.=0D +=0D +```=0D +$ uname -srvmpio=0D +Linux 5.4.0-131-generic #147-Ubuntu SMP Fri Oct 14 17:07:22 UTC 2022 x86_6= 4 x86_64 x86_64 GNU/Linux=0D +```=0D +=0D +### Development Tools=0D +=0D +The following tools must be installed on the development PC.=0D +=0D +=0D +| Sr. No. | Tool | Description = | Install instructions = |=0D +|-----------|---------------------|---------------------------------------= -----------------------|---------------------------------------------------= -------|=0D +| 1 | Python 3 | Python interpreter = | $ sudo apt install python3 python3-distutils = |=0D +| 2 | Git | Git source control tool = | $ sudo apt install git = |=0D +| 3 | uuid-dev | Required for including uuid/uuid.h = | $ sudo apt install uuid-dev = |=0D +| 4 | build-essential | Installs make, gcc, g++, etc = | $ sudo apt install build-essential
$ make -v =
GNU Make 4.2.1
gcc --version
gcc (Ubuntu 9.4.0-1ubuntu1~20.0= 4.1) 9.4.0
$ g++ --version
g++ (Ubuntu 9.4.0-1ubuntu1\~20.04.1) 9= .4.0 |=0D +| 5 | bison | A parser generator required by acpica = tools. | $ sudo apt install bison = |=0D +| 6 | flex | A fast lexical analyzer generator requ= ired by acpica tools | $ sudp apt get install flex = |=0D +=0D +### Setting up the development tools=0D +=0D +Install the required development tools by running the following commands i= n the terminal window.=0D +=0D +```=0D +$ sudo apt install bison build-essential flex git uuid-dev=0D + ```=0D +=0D +```=0D +$ sudo apt install python3 python3-distutils=0D + ```=0D +=0D +### Arm cross compiler toolchain=0D +=0D +The Arm toolchain to cross compile from x86_64-linux to aarch64-elf is ava= ilable [here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downl= oads).=0D +=0D +Select the latest toolchain to match the development PC architecture. Sele= ct the little-endian 'AArch64 ELF bare-metal target (aarch64-elf)' GCC cros= s compiler.=0D +=0D +Example: For a x86_64 development PC, download arm-gnu-toolchain-12.2.rel1= -x86_64-aarch64-none-elf.tar.xz=0D +=0D +Create a directory called 'toolchain' under the workspace folder. For exam= ple source\toolchain and extract the toolchain to this directory.=0D +=0D +```=0D +$ mkdir $WORKSPACE/toolchain=0D +$ cd $WORKSPACE/toolchain=0D +$ 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.x= z=0D +$ tar xf arm-gnu-toolchain-12.2.rel1-x86_64-aarch64-none-elf.tar.xz=0D +$ cd $WORKSPACE=0D +```=0D +=0D +### Build the acpica tools=0D +=0D +The acpica tools implement the latest iasl compiler. To build the acpica t= ools, run the following commands in the terminal window.=0D +=0D +```=0D +$ make -C $WORKSPACE/acpica=0D +```=0D +=0D +## Building EDKII firmware=0D +=0D +1. To build the firmware image, follow the steps below and run the command= s in the terminal window.=0D +=0D +2. Set up the environment variables.=0D +=0D +```=0D +$ export GCC5_AARCH64_PREFIX=3D$WORKSPACE/toolchain/arm-gnu-toolchain-12.2= .rel1-x86_64-aarch64-none-elf/bin/aarch64-none-elf-=0D +$ export PACKAGES_PATH=3D$WORKSPACE/edk2:$WORKSPACE/edk2-platforms=0D +$ export IASL_PREFIX=3D$WORKSPACE/acpica/generate/unix/bin/=0D +$ export PYTHON_COMMAND=3D/usr/bin/python3=0D +```=0D +=0D +3. Configure the EDKII development environment by running the edk2setup ba= sh script.=0D +```=0D +$ source edk2/edksetup.sh=0D +```=0D +=0D +4. Build the BaseTools.=0D +```=0D +$ make -C edk2/BaseTools=0D +```=0D +=0D +### Build the firmware for Arm FVP Base AEMv8A-AEMv8A Model platform=0D +=0D +Run the following command to build the firmware for FVP Base AEMv8A-AEMv8A= platform.=0D +```=0D +$ build -a AARCH64 -t GCC5 -p Platform/ARM/VExpressPkg/ArmVExpress-FVP-AAr= ch64.dsc -b < DEBUG | RELEASE >=0D +```=0D +=0D +The firmware binaries can be found at the following location:=0D +```=0D +$WORKSPACE/Build/ArmVExpress-FVP-AArch64/_GCC5/FV/FVP_AARCH= 64_EFI.fd=0D +```=0D +=0D +### Build the firmware for Arm Juno platform=0D +=0D +Run the following command to build the firmware for Arm Juno platform.=0D +```=0D +$ build -a AARCH64 -t GCC5 -p Platform/ARM/JunoPkg/ArmJuno.dsc -b < DEBUG = | RELEASE >=0D +```=0D +=0D +The firmware binaries can be found at the following location:=0D +```=0D +$WORKSPACE/Build/ArmJuno/_GCC5/FV/BL33_AP_UEFI.fd=0D +```=0D +=0D +# Building firmware on a Windows host using Windows Subsystem for Linux (W= SL)=0D +=0D +The instructions for building the firmware using WSL are similar to that f= or a Linux host.=0D +The prerequisites for setting up the Windows Subsystem for Linux environme= nt are listed below.=0D +=0D +## Prerequisites=0D +=0D +- A x64 development machine with Windows 10 (Version 21H2 - OS Build 19044= .2486).=0D +- At least 10GB of free disk space.=0D +- Install the Windows Subsystem for Linux. Select Ubuntu 20.04 LTS from th= e Microsoft Store.=0D +=0D +Check the Ubuntu version by typing the following on the console.=0D +```=0D +$ uname -srvmpio=0D +Linux 4.4.0-19041-Microsoft #2311-Microsoft Tue Nov 08 17:09:00 PST 2022 x= 86_64 x86_64 x86_64 GNU/Linux=0D +```=0D +=0D +The remaining instructions for installing the development tools, configuri= ng the development environment and building firmware are exactly the same a= s those for a Linux host.=0D +=0D +# Building firmware on a x64 Windows host=0D +=0D +#### Prerequisites=0D +=0D +- A 64-bit development machine=0D +- Windows 10 desktop (Version 21H2 - OS Build 19044.2486)=0D +- At least 10GB of free disk space.=0D +=0D +#### Development Tools=0D +=0D +The following tools must be installed on the development machine.=0D +=0D +| Sr. No. | Tool | Description = | Install instructions = |=0D +|-----------|----------------------------------------------|--------------= ------------------------------------------------|--------------------------= --------------------------------|=0D +| 1 | Python 3 | Python interp= reter | Go [here](https://www.pyt= hon.org/downloads/windows/)

Choose the latest Python 3.X release.=

Download and run the Windows x86_64 MSI installer

If n= eeded, add the python executable to your path by executing the following co= mmand:
> set PATH=3D;%PATH% |=0D +| 2 | Git | Git source co= ntrol tool | Go [here](https://git-scm= .com/download/win)

Download and run the 64-bit Git for Windows Se= tup |=0D +| 3 | ASL tools | iasl compiler= and other tools for the ASL language | Go [here](https://www.acp= ica.org/downloads/binary-tools)

Download the iASL Compiler and W= indows ACPI Tools

Extract the content and place it at C:\ASL\
Check that the compiler is at the right place by executing:
> C= :\ASL\iasl.exe -v |=0D +| 4 | Microsoft Visual Studio 2019 Professional | Microsoft IDE= and compiler toolchain. | Go [here](https://visuals= tudio.microsoft.com/downloads/)

Download and install Visual Studi= o 2019 Professional |=0D +| 5 | echo tool | Echo = | See Workaround for echo c= ommand below. |=0D +=0D +=0D +## Setting up the development tools=0D +=0D +Install the required development tools listed above by running the appropr= iate installer applications.=0D +=0D +### Arm cross compiler toolchain=0D +The Arm toolchain Windows (i686-mingw32) hosted cross compilers are availa= ble [here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-download= s).=0D +=0D +Select the latest toolchain for 'AArch64 bare-metal target (aarch64-none-e= lf)' GCC cross compiler.=0D +=0D +Example: Download arm-gnu-toolchain-12.2.rel1-mingw-w64-i686-aarch64-none-= elf=0D +=0D +Create a directory called 'toolchain' under the workspace directory and ex= tract the toolchain to this directory using the downloaded installer.=0D +=0D +The toolchain folder tree should look as below:=0D +=0D +```=0D +toolchain=0D ++---arm-gnu-toolchain-12.2.rel1-mingw-w64-i686-aarch64-none-elf=0D +| +---aarch64-none-elf=0D +| +---bin=0D +| +---include=0D +| +---lib=0D +| +---libexec=0D +| +---share=0D +```=0D +=0D +### Workaround for the echo command=0D +=0D +EDKII needs a workaround related to the echo command. A script replacing t= he Windows echo executable must be created, with the name "echo.BAT?:=0D +=0D +- Create a file named "echo.BAT" in the folder of your choice.=0D +- Paste the following lines inside the file:=0D +=0D +```=0D +rem %~f0 echo.BAT %*=0D +rem This file exists to overcome a problem in the EDKII build where=0D +rem build_rule.template invokes a command as:=0D +rem "$(OBJCOPY)" $(OBJCOPY_FLAGS) ${dst}=0D +rem When OBJCOPY is set to echo, this results in the following error:=0D +rem "echo" objcopy not needed for m:\...\PCD\Dxe\Pcd\DEBUG\PcdDxe.dll= =0D +rem And CMD.EXE fails to find the DOS echo command because of the quotes=0D +@echo %*=0D +@goto :EOF=0D +```=0D +=0D +- Add the file to your PATH by executing:=0D +```=0D +> set PATH=3D;%PATH%=0D +```=0D +=0D +## Building EDKII firmware=0D +=0D +1. To build the firmware image, follow the steps below and run the command= s in the terminal window.=0D +2. Set up the environment variables.=0D +=0D +```=0D + set GCC5_AARCH64_PREFIX=3D%WORKSPACE%\toolchain\arm-gnu-toolchain-12.2.re= l1-mingw-w64-i686-aarch64-none-elf\bin\aarch64-none-elf-=0D + set PACKAGES_PATH=3D%WORKSPACE%\edk2;%WORKSPACE%\edk2-platforms=0D + set EDK_TOOLS_PATH=3D%WORKSPACE%\edk2\BaseTools=0D + set GCC_HOST_BIN=3Dn=0D +```=0D +=0D +Select the python version you wish to use and set the PYTHON_COMMAND envir= onment variable to your Python executable.=0D +=0D +Set the PYTHON_COMMAND to point to the Python3 executable.=0D +=0D +Check that your path is set up as it is stated in the development tools ta= ble above. It should give access to:=0D +=0D +- The make executable=0D +- The echo.BAT script=0D +=0D +3. Configure the EDKII development environment by running the edksetup.bat= script.=0D +The Rebuild option can be skipped if the BaseTools have already been built= .=0D +=0D +The ForceRebuild option can be used to do a clean build of the Base tools.= =0D +```=0D +> call %WORKSPACE%\edk2\edksetup.bat [Rebuild | ForceRebuild]=0D +```=0D +=0D +### Build the firmware for Arm FVP Base AEMv8A-AEMv8A Model platform=0D +=0D +Run the following command to build the firmware for FVP Base AEMv8A-AEMv8A= platform.=0D +=0D +```=0D +> build -a AARCH64 -t GCC5 -p Platform\ARM\VExpressPkg\ArmVExpress-FVP-AAr= ch64.dsc -b < DEBUG | RELEASE >=0D +```=0D +=0D +The firmware binaries can be found at the following location:=0D +```=0D +%WORKSPACE%\Build\ArmVExpress-FVP-AArch64\_GCC5\FV\FVP_AARC= H64_EFI.fd=0D +```=0D +=0D +### Build the firmware for Arm Juno platform=0D +=0D +Run the following command to build the firmware for Arm Juno platform.=0D +=0D +```=0D +> build -a AARCH64 -t GCC5 -p Platform\ARM\JunoPkg\ArmJuno.dsc -b < DEBUG = | RELEASE >=0D +```=0D +The firmware binaries are at the following location:=0D +=0D +```=0D +%WORKSPACE%\Build\ArmJuno\_GCC5\FV\BL33_AP_UEFI.fd=0D +```=0D --=20 2.25.1