1This branch holds all platforms actively maintained against the 2[edk2](https://github.com/tianocore/edk2) master branch. 3 4For generic information about the edk2-platforms repository, and the process 5under which _stable_ and _devel_ branches can be added for individual platforms, 6please see 7[the introduction on the about branch](https://github.com/tianocore/edk2-platforms/blob/about/Readme.md). 8 9The majority of the content in the EDK II open source project uses a 10[BSD-2-Clause Plus Patent License](License.txt). Additional details on EDK II 11open source project code contributions can be found in the edk2 repository 12[Readme.md](https://github.com/tianocore/edk2/blob/master/Readme.md). 13The EDK II Platforms open source project contains the following components that 14are covered by additional licenses: 15 16- [`Silicon/RISC-V/ProcessorPkg/Library/RiscVOpensbiLib/opensbi`](https://github.com/riscv/opensbi/blob/master/COPYING.BSD) 17 18# INDEX 19* [Overview](#overview) 20* [How To Build (Linux Environment)](#how-to-build-linux-environment) 21 * [Manual building](#manual-building) 22 * [Using uefi-tools helper scripts](#using-uefi-tools-helper-scripts) 23* [How To Build (Windows Environment)](#how-to-build-windows-environment) 24* [Supported Platforms](#supported-platforms) 25* [Maintainers](#maintainers) 26 27# Overview 28 29Platform description files can be found under `Platform/{Vendor}/{Platform}`. 30 31Many platforms require additional image processing beyond the EDK2 build. 32Any such steps should be documented (as a Readme.md), and any necessary helper 33scripts be contained, under said platform directory. 34 35Any contributions to this branch should be submitted via email to the 36edk2-devel mailing list with a subject prefix of `[platforms]`. See 37[Laszlo's excellent guide](https://github.com/tianocore/tianocore.github.io/wiki/Laszlo's-unkempt-git-guide-for-edk2-contributors-and-maintainers) for details 38on how to do this successfully. 39 40# How to build (Linux Environment) 41 42## Prerequisites 43The build tools themselves depend on Python (2) and libuuid. Most Linux systems 44will come with a Python environment installed by default, but you usually need 45to install uuid-dev (or uuid-devel, depending on distribution) manually. 46 47## If cross compiling 48If building EDK2 for a different archtecture than the build machine, you need to 49obtain an appropriate cross-compiler. X64 (x86_64) compilers also support IA32, 50but the reverse may not always be true. 51 52Target architecture | Cross compilation prefix 53--------------------|------------------------- 54AARCH64 | aarch64-linux-gnu- 55ARM | arm-linux-gnueabihf- 56IA32 | i?86-linux-gnu-* _or_ x86_64-linux-gnu- 57IPF | ia64-linux-gnu 58X64 | x86_64-linux-gnu- 59RISCV64 | riscv64-unknown-elf- 60 61\* i386, i486, i586 or i686 62 63### GCC 64Linaro provides GCC toolchains for 65[aarch64-linux-gnu](https://releases.linaro.org/components/toolchain/binaries/latest/aarch64-linux-gnu/) 66and [arm-linux-gnueabihf](https://releases.linaro.org/components/toolchain/binaries/latest/arm-linux-gnueabihf/) 67compiled to run on x86_64/i686 Linux and i686 Windows. Some Linux distributions 68provide their own packaged cross-toolchains. 69 70### GCC for RISC-V 71RISC-V open source community provides GCC toolchains for 72[riscv64-unknown-elf](https://github.com/riscv/riscv-gnu-toolchain) 73compiled to run on x86 Linux. 74 75### clang 76Clang does not require separate cross compilers, but it does need a 77target-specific binutils. These are included with any prepackaged GCC toolchain 78(see above), or can be installed or built separately. 79 80## Obtaining source code 811. Create a new folder (directory) on your local development machine 82 for use as your workspace. This example uses `/work/git/tianocore`, modify as 83 appropriate for your needs. 84 ``` 85 $ export WORKSPACE=/work/git/tianocore 86 $ mkdir -p $WORKSPACE 87 $ cd $WORKSPACE 88 ``` 89 901. Into that folder, clone: 91 1. [edk2](https://github.com/tianocore/edk2) 92 1. [edk2-platforms](https://github.com/tianocore/edk2-platforms) 93 1. [edk2-non-osi](https://github.com/tianocore/edk2-non-osi) (if building 94 platforms that need it) 95 ``` 96 $ git clone https://github.com/tianocore/edk2.git 97 $ git submodule update --init 98 ... 99 $ git clone https://github.com/tianocore/edk2-platforms.git 100 $ git submodule update --init 101 ... 102 $ git clone https://github.com/tianocore/edk2-non-osi.git 103 ``` 104 1051. Set up a **PACKAGES_PATH** to point to the locations of these three 106 repositories: 107 108 `$ export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms:$PWD/edk2-non-osi` 109 110## Manual building 111 1121. Set up the build environment (this will modify your environment variables) 113 114 `$ . edk2/edksetup.sh` 115 116 (This step _depends_ on **WORKSPACE** being set as per above.) 1171. Build BaseTools 118 119 `make -C edk2/BaseTools` 120 121 (BaseTools can currently not be built in parallel, so do not specify any `-j` 122 option, either on the command line or in a **MAKEFLAGS** environment 123 variable.) 124 125### Build options 126There are a number of options that can (or must) be specified at the point of 127building. Their default values are set in `edk2/Conf/target.txt`. If we are 128working only on a single platform, it makes sense to just update this file. 129 130target.txt option | command line | Description 131------------------|--------------|------------ 132ACTIVE_PLATFORM | `-p` | Description file (.dsc) of platform. 133TARGET | `-b` | One of DEBUG, RELEASE or NOOPT. 134TARGET_ARCH | `-a` | Architecture to build for. 135TOOL_CHAIN_TAG | `-t` | Toolchain profile to use for building. 136 137There is also MAX_CONCURRENT_THREAD_NUMBER (`-n`), roughly equivalent to 138`make -j`. 139 140When specified on command line, `-b` can be repeated multiple times in order to 141build multiple targets sequentially. 142 143After a successful build, the resulting images can be found in 144`Build/{Platform Name}/{TARGET}_{TOOL_CHAIN_TAG}/FV`. 145 146### Build a platform 147The main build process _can_ run in parallel - so figure out how many threads we 148have available. 149 150``` 151$ getconf _NPROCESSORS_ONLN 1528 153``` 154OK, so we have 8 CPUs - let's tell the build to use a little more than that: 155``` 156$ NUM_CPUS=$((`getconf _NPROCESSORS_ONLN` + 2)) 157``` 158For the toolchain tag, use GCC5 for gcc version 5 or later, GCC4x for 159earlier versions, or CLANG35/CLANG38 as appropriate when building with clang. 160``` 161$ build -n $NUM_CPUS -a AARCH64 -t GCC5 -p Platform/ARM/JunoPkg/ArmJuno.dsc 162``` 163(Note that the description file gets resolved by the build command through 164searching in all locations specified in **PACKAGES_PATH**.) 165 166#### If cross-compiling 167When cross-compiling, or building with a different version of the compiler than 168the default `gcc` or `clang`(/binutils), we additionally need to inform the 169build command which toolchain to use. We do this by setting the environment 170variable `{TOOL_CHAIN_TAG}_{TARGET_ARCH}_PREFIX` - in the case above, 171**GCC5_AARCH64_PREFIX**. 172 173So, referring to the cross compiler toolchain table above, we should prepend the `build` command line with `GCC5_AARCH64_PREFIX=aarch64-linux-gnu-`. 174 175## Using uefi-tools helper scripts 176uefi-tools is a completely unofficial set of helper-scripts developed by Linaro. 177They automate figuring out all of the manual options above, and store the paths 178to platform description files in a separate configuration file. Additionally, 179they simplify bulk-building large numbers of platforms. 180 181The (best effort) intent is to keep this configuration up to date with all 182platforms that exist in the edk2-platforms master branch. 183 184The equivalent of the manual example above would be 185``` 186$ git clone https://git.linaro.org/uefi/uefi-tools.git 187... 188$ ./uefi-tools/edk2-build.sh juno 189... 190------------------------------------------------------------ 191 aarch64 Juno (AARCH64) RELEASE pass 192------------------------------------------------------------ 193pass 1 194fail 0 195``` 196The build finishes with a summary of which platforms/targets were built, which 197succeeded and which failed (and the total number of either). 198 199Like the `build` command itself, `edk2-build.sh` it supports specifying multiple 200targets on a single command line, but it also lets you specify multiple 201platforms (or `all` for building all known platforms). So in order to build all 202platforms described by the configuration file, for both DEBUG and RELEASE 203targets: 204``` 205$ ./uefi-tools/edk2-build.sh -b DEBUG -b RELEASE 206``` 207 208# How To Build (Windows Environment) 209 210(I genuinely have no idea. Please help!) 211 212 213# Supported Platforms 214 215These are the platforms currently supported by this tree - grouped by 216Processor/SoC vendor, rather than platform vendor. 217 218If there are any additional build steps beyond the generic ones listed above, 219they will be documented with the platform. 220 221## AMD 222* [Cello](Platform/LeMaker/CelloBoard) 223* [Overdrive](Platform/AMD/OverdriveBoard) 224* [Overdrive 1000](Platform/SoftIron/Overdrive1000Board) 225 226## [Ampere](Platform/Ampere/Readme.md) 227* [Mt. Jade](Platform/Ampere/JadePkg) 228 229## [ARM](Platform/ARM/Readme.md) 230* [Juno](Platform/ARM/JunoPkg) 231* [SGI family](Platform/ARM/SgiPkg) 232 233## BeagleBoard 234* [BeagleBoard](Platform/BeagleBoard/BeagleBoardPkg) 235 236## Hisilicon 237* [D03](Platform/Hisilicon/D03) 238* [D05](Platform/Hisilicon/D05) 239* [D06](Platform/Hisilicon/D06) 240* [HiKey](Platform/Hisilicon/HiKey) 241* [HiKey960](Platform/Hisilicon/HiKey960) 242 243## Intel 244### [Minimum Platforms](Platform/Intel/Readme.md) 245* [Kaby Lake](Platform/Intel/KabylakeOpenBoardPkg) 246* [Simics](Platform/Intel/SimicsOpenBoardPkg) 247* [Whiskey Lake](Platform/Intel/WhiskeylakeOpenBoardPkg) 248* [Comet Lake](Platform/Intel/CometlakeOpenBoardPkg) 249 250For more information, see the 251[EDK II Minimum Platform Specification](https://edk2-docs.gitbooks.io/edk-ii-minimum-platform-specification). 252### Other Platforms 253##### Intel® Quark SoC X1000 based platforms 254* [Galileo](Platform/Intel/QuarkPlatformPkg) 255##### Minnowboard Max/Turbot based on Intel Valleyview2 SoC 256* [Minnowboard Max](Platform/Intel/Vlv2TbltDevicePkg) 257 258## Marvell 259* [Armada 70x0](Platform/Marvell/Armada70x0Db) 260* [Armada 80x0](Platform/Marvell/Armada80x0Db) 261* [CN913x](Platform/Marvell/Cn913xDb) 262* [SolidRun Armada MacchiatoBin](Platform/SolidRun/Armada80x0McBin) 263 264## Raspberry Pi 265* [Pi 3](Platform/RaspberryPi/RPi3) 266* [Pi 4](Platform/RaspberryPi/RPi4) 267 268## RISC-V 269### SiFive 270* [Sifive U5 Series](Platform/SiFive/U5SeriesPkg) Refer to Platform/SiFive/U5Series/Readme.md on edk2-platform repository. 271* [Freedom U500 VC707 FPGA](Platform/SiFive/U5SeriesPkg/FreedomU500VC707Board) 272* [Freedom U540 HiFive Unleashed](Platform/SiFive/U5SeriesPkg/FreedomU540HiFiveUnleashedBoard) 273 274## Socionext 275* [SynQuacer](Platform/Socionext/DeveloperBox) 276 277## NXP 278* [LS1043aRdb](Platform/NXP/LS1043aRdbPkg) 279 280## Qemu 281* [SBSA](Platform/Qemu/SbsaQemu) 282 283# Maintainers 284 285See [Maintainers.txt](Maintainers.txt). 286 287# Submodules 288 289Submodule in EDK II Platforms is allowed but submodule chain should be avoided 290as possible as we can. Currently EDK II Platforms contains the following 291submodules 292 293- Silicon/RISC-V/ProcessorPkg/Library/RiscVOpensbiLib/opensbi 294 295To get a full, buildable EDK II repository, use following steps of git command 296 297```bash 298 git clone https://github.com/tianocore/edk2-platforms.git 299 cd edk2-platforms 300 git submodule update --init 301 cd .. 302``` 303 304If there's update for submodules, use following git commands to get the latest 305submodules code. 306 307```bash 308 cd edk2-platforms 309 git pull 310 git submodule update 311``` 312 313Note: When cloning submodule repos, '--recursive' option is not recommended. 314EDK II Platforms itself will not use any code/feature from submodules in above 315submodules. So using '--recursive' adds a dependency on being able to reach 316servers we do not actually want any code from, as well as needlessly 317downloading code we will not use. 318