Readme.md 11.8 KB
Newer Older
1
2
3
4
5
6
7
8
This branch holds all platforms actively maintained against the
[edk2](https://github.com/tianocore/edk2) master branch.

For generic information about the edk2-platforms repository, and the process
under which _stable_ and _devel_ branches can be added for individual platforms,
please see
[the introduction on the about branch](https://github.com/tianocore/edk2-platforms/blob/about/Readme.md).

9
10
11
12
The majority of the content in the EDK II open source project uses a
[BSD-2-Clause Plus Patent License](License.txt).  Additional details on EDK II
open source project code contributions can be found in the edk2 repository
[Readme.md](https://github.com/tianocore/edk2/blob/master/Readme.md).
13
14
15
16
The EDK II Platforms open source project contains the following components that
are covered by additional licenses:

- [`Silicon/RISC-V/ProcessorPkg/Library/RiscVOpensbiLib/opensbi`](https://github.com/riscv/opensbi/blob/master/COPYING.BSD)
17

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# INDEX
* [Overview](#overview)
* [How To Build (Linux Environment)](#how-to-build-linux-environment)
   * [Manual building](#manual-building)
   * [Using uefi-tools helper scripts](#using-uefi-tools-helper-scripts)
* [How To Build (Windows Environment)](#how-to-build-windows-environment)
* [Supported Platforms](#supported-platforms)
* [Maintainers](#maintainers)

# Overview

Platform description files can be found under `Platform/{Vendor}/{Platform}`.

Many platforms require additional image processing beyond the EDK2 build.
Any such steps should be documented (as a Readme.md), and any necessary helper
scripts be contained, under said platform directory.

Any contributions to this branch should be submitted via email to the
edk2-devel mailing list with a subject prefix of `[platforms]`. See
[Laszlo's excellent guide](https://github.com/tianocore/tianocore.github.io/wiki/Laszlo's-unkempt-git-guide-for-edk2-contributors-and-maintainers) for details
on how to do this successfully.

# How to build (Linux Environment)

## Prerequisites
The build tools themselves depend on Python (2) and libuuid. Most Linux systems
will come with a Python environment installed by default, but you usually need
to install uuid-dev (or uuid-devel, depending on distribution) manually.

## If cross compiling
If building EDK2 for a different archtecture than the build machine, you need to
obtain an appropriate cross-compiler. X64 (x86_64) compilers also support IA32,
but the reverse may not always be true.

Target architecture | Cross compilation prefix
--------------------|-------------------------
AARCH64             | aarch64-linux-gnu-
ARM                 | arm-linux-gnueabihf-
IA32                | i?86-linux-gnu-* _or_ x86_64-linux-gnu-
IPF                 | ia64-linux-gnu
X64                 | x86_64-linux-gnu-
59
RISCV64             | riscv64-unknown-elf-
60
61
62
63
64
65
66
67
68
69

\* i386, i486, i586 or i686

### GCC
Linaro provides GCC toolchains for
[aarch64-linux-gnu](https://releases.linaro.org/components/toolchain/binaries/latest/aarch64-linux-gnu/)
and [arm-linux-gnueabihf](https://releases.linaro.org/components/toolchain/binaries/latest/arm-linux-gnueabihf/)
compiled to run on x86_64/i686 Linux and i686 Windows. Some Linux distributions
provide their own packaged cross-toolchains.

70
71
72
73
74
### GCC for RISC-V
RISC-V open source community provides GCC toolchains for
[riscv64-unknown-elf](https://github.com/riscv/riscv-gnu-toolchain)
compiled to run on x86 Linux.

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
### clang
Clang does not require separate cross compilers, but it does need a
target-specific binutils. These are included with any prepackaged GCC toolchain
(see above), or can be installed or built separately.

## 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.
   ```
   $ export WORKSPACE=/work/git/tianocore
   $ mkdir -p $WORKSPACE
   $ cd $WORKSPACE
   ```

1. Into that folder, clone:
   1. [edk2](https://github.com/tianocore/edk2)
   1. [edk2-platforms](https://github.com/tianocore/edk2-platforms)
   1. [edk2-non-osi](https://github.com/tianocore/edk2-non-osi) (if building
      platforms that need it)
   ```
96
97
   $ git clone https://github.com/tianocore/edk2.git
   $ git submodule update --init
98
99
   ...
   $ git clone https://github.com/tianocore/edk2-platforms.git
Abner Chang's avatar
Abner Chang committed
100
   $ git submodule update --init
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
   ...
   $ git clone https://github.com/tianocore/edk2-non-osi.git
   ```

1. Set up a **PACKAGES_PATH** to point to the locations of these three
   repositories:

   `$ export PACKAGES_PATH=$PWD/edk2:$PWD/edk2-platforms:$PWD/edk2-non-osi`

## Manual building

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.)
1. 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.
TOOL_CHAIN_TAG    | `-t`         | Toolchain profile to use for building.

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`.

### Build a platform
The main build process _can_ run in parallel - so figure out how many threads we
have available.

```
$ getconf _NPROCESSORS_ONLN
8
```
OK, so we have 8 CPUs - let's tell the build to use a little more than that:
```
$ NUM_CPUS=$((`getconf _NPROCESSORS_ONLN` + 2))
```
For the toolchain tag, use GCC5 for gcc version 5 or later, GCC4x for
earlier versions, or CLANG35/CLANG38 as appropriate when building with clang.
```
$ build -n $NUM_CPUS -a AARCH64 -t GCC5 -p Platform/ARM/JunoPkg/ArmJuno.dsc
```
(Note that the description file gets resolved by the build command through
searching in all locations specified in **PACKAGES_PATH**.)

#### If cross-compiling
When cross-compiling, or building with a different version of the compiler than
the default `gcc` or `clang`(/binutils), we additionally need to inform the
build command which toolchain to use. We do this by setting the environment
variable `{TOOL_CHAIN_TAG}_{TARGET_ARCH}_PREFIX` - in the case above,
**GCC5_AARCH64_PREFIX**.

So, referring to the cross compiler toolchain table above, we should prepend the `build` command line with `GCC5_AARCH64_PREFIX=aarch64-linux-gnu-`.

## Using uefi-tools helper scripts
uefi-tools is a completely unofficial set of helper-scripts developed by Linaro.
They automate figuring out all of the manual options above, and store the paths
to platform description files in a separate configuration file. Additionally,
they simplify bulk-building large numbers of platforms.

The (best effort) intent is to keep this configuration up to date with all
platforms that exist in the edk2-platforms master branch.

The equivalent of the manual example above would be
```
$ git clone https://git.linaro.org/uefi/uefi-tools.git
...
$ ./uefi-tools/edk2-build.sh juno
...
------------------------------------------------------------
Christopher Co's avatar
Christopher Co committed
191
                         aarch64 Juno (AARCH64) RELEASE pass
192
------------------------------------------------------------
Christopher Co's avatar
Christopher Co committed
193
194
pass   1
fail   0
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
```
The build finishes with a summary of which platforms/targets were built, which
succeeded and which failed (and the total number of either).

Like the `build` command itself, `edk2-build.sh` it supports specifying multiple
targets on a single command line, but it also lets you specify multiple
platforms (or `all` for building all known platforms). So in order to build all
platforms described by the configuration file, for both DEBUG and RELEASE
targets:
```
$ ./uefi-tools/edk2-build.sh -b DEBUG -b RELEASE
```

# How To Build (Windows Environment)

(I genuinely have no idea. Please help!)


# Supported Platforms

These are the platforms currently supported by this tree - grouped by
Processor/SoC vendor, rather than platform vendor.

If there are any additional build steps beyond the generic ones listed above,
they will be documented with the platform.

## AMD
* [Cello](Platform/LeMaker/CelloBoard)
* [Overdrive](Platform/AMD/OverdriveBoard)
* [Overdrive 1000](Platform/SoftIron/Overdrive1000Board)

Phong Vo's avatar
Phong Vo committed
226
227
228
## [Ampere](Platform/Ampere/Readme.md)
* [Mt. Jade](Platform/Ampere/JadePkg)

Nariman Poushin's avatar
Nariman Poushin committed
229
## [ARM](Platform/ARM/Readme.md)
230
231
* [Juno](Platform/ARM/JunoPkg)
* [SGI family](Platform/ARM/SgiPkg)
232

233
234
235
## BeagleBoard
* [BeagleBoard](Platform/BeagleBoard/BeagleBoardPkg)

236
237
238
## Hisilicon
* [D03](Platform/Hisilicon/D03)
* [D05](Platform/Hisilicon/D05)
239
* [D06](Platform/Hisilicon/D06)
240
* [HiKey](Platform/Hisilicon/HiKey)
241
* [HiKey960](Platform/Hisilicon/HiKey960)
242

243
244
## Intel
### [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
250
251
252
253
254
255
256
257

For more information, see the
[EDK II Minimum Platform Specification](https://edk2-docs.gitbooks.io/edk-ii-minimum-platform-specification).
### Other Platforms
##### Intel® Quark SoC X1000 based platforms
* [Galileo](Platform/Intel/QuarkPlatformPkg)
##### Minnowboard Max/Turbot based on Intel Valleyview2 SoC
* [Minnowboard Max](Platform/Intel/Vlv2TbltDevicePkg)

258
## Marvell
259
260
261
262
* [Armada 70x0](Platform/Marvell/Armada70x0Db)
* [Armada 80x0](Platform/Marvell/Armada80x0Db)
* [CN913x](Platform/Marvell/Cn913xDb)
* [SolidRun Armada MacchiatoBin](Platform/SolidRun/Armada80x0McBin)
263

264
265
## Raspberry Pi
* [Pi 3](Platform/RaspberryPi/RPi3)
266
* [Pi 4](Platform/RaspberryPi/RPi4)
267

268
269
270
271
272
273
## RISC-V
### SiFive
* [Sifive U5 Series](Platform/SiFive/U5SeriesPkg) Refer to Platform/SiFive/U5Series/Readme.md on edk2-platform repository.
* [Freedom U500 VC707 FPGA](Platform/SiFive/U5SeriesPkg/FreedomU500VC707Board)
* [Freedom U540 HiFive Unleashed](Platform/SiFive/U5SeriesPkg/FreedomU540HiFiveUnleashedBoard)

274
275
276
## Socionext
* [SynQuacer](Platform/Socionext/DeveloperBox)

277
278
279
## NXP
* [LS1043aRdb](Platform/NXP/LS1043aRdbPkg)

280
281
282
## Qemu
* [SBSA](Platform/Qemu/SbsaQemu)

283
284
285
# Maintainers

See [Maintainers.txt](Maintainers.txt).
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317

# Submodules

Submodule in EDK II Platforms is allowed but submodule chain should be avoided
as possible as we can. Currently EDK II Platforms contains the following
submodules

- Silicon/RISC-V/ProcessorPkg/Library/RiscVOpensbiLib/opensbi

To get a full, buildable EDK II repository, use following steps of git command

```bash
  git clone https://github.com/tianocore/edk2-platforms.git
  cd edk2-platforms
  git submodule update --init
  cd ..
```

If there's update for submodules, use following git commands to get the latest
submodules code.

```bash
  cd edk2-platforms
  git pull
  git submodule update
```

Note: When cloning submodule repos, '--recursive' option is not recommended.
EDK II Platforms itself will not use any code/feature from submodules in above
submodules. So using '--recursive' adds a dependency on being able to reach
servers we do not actually want any code from, as well as needlessly
downloading code we will not use.