blob: 8e0a3f36edfe29e8e956455a5b015b55db9a7242 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001# SPDX-License-Identifier: GPL-2.0+
Bin Meng5dad97e2014-12-17 15:50:48 +08002#
3# Copyright (C) 2014, Simon Glass <sjg@chromium.org>
4# Copyright (C) 2014, Bin Meng <bmeng.cn@gmail.com>
Bin Meng5dad97e2014-12-17 15:50:48 +08005
6U-Boot on x86
7=============
8
9This document describes the information about U-Boot running on x86 targets,
10including supported boards, build instructions, todo list, etc.
11
12Status
13------
14U-Boot supports running as a coreboot [1] payload on x86. So far only Link
Bin Meng1ae5b782015-05-07 21:34:12 +080015(Chromebook Pixel) and QEMU [2] x86 targets have been tested, but it should
16work with minimal adjustments on other x86 boards since coreboot deals with
17most of the low-level details.
Bin Meng5dad97e2014-12-17 15:50:48 +080018
Andy Shevchenko495f3772017-07-06 14:41:53 +030019U-Boot is a main bootloader on Intel Edison board.
20
Stoppa, Igor28a85362015-08-13 16:43:35 +030021U-Boot also supports booting directly from x86 reset vector, without coreboot.
22In this case, known as bare mode, from the fact that it runs on the
Simon Glassf21069f2016-03-11 22:07:33 -070023'bare metal', U-Boot acts like a BIOS replacement. The following platforms
24are supported:
25
Bin Mengeda995a2016-05-07 07:46:36 -070026 - Bayley Bay CRB
Bin Mengeb457872017-08-15 22:42:02 -070027 - Cherry Hill CRB
Bin Mengeda995a2016-05-07 07:46:36 -070028 - Congatec QEVAL 2.0 & conga-QA3/E3845
Simon Glassf21069f2016-03-11 22:07:33 -070029 - Cougar Canyon 2 CRB
30 - Crown Bay CRB
31 - Galileo
32 - Link (Chromebook Pixel)
33 - Minnowboard MAX
34 - Samus (Chromebook Pixel 2015)
Bin Meng6feb2ff2018-10-13 20:52:03 -070035 - QEMU x86 (32-bit & 64-bit)
Bin Meng5dad97e2014-12-17 15:50:48 +080036
Simon Glass3a1a18f2015-01-27 22:13:47 -070037As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
38Linux kernel as part of a FIT image. It also supports a compressed zImage.
Bin Meng3619e942015-10-07 20:19:20 -070039U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks
40for more details.
Bin Meng5dad97e2014-12-17 15:50:48 +080041
Stoppa, Igor28a85362015-08-13 16:43:35 +030042Build Instructions for U-Boot as coreboot payload
43-------------------------------------------------
Bin Meng5dad97e2014-12-17 15:50:48 +080044Building U-Boot as a coreboot payload is just like building U-Boot for targets
45on other architectures, like below:
46
Simon Glassd5032392018-04-12 14:04:40 -060047$ make coreboot_defconfig
Bin Meng5dad97e2014-12-17 15:50:48 +080048$ make all
49
Andy Shevchenko495f3772017-07-06 14:41:53 +030050Build Instructions for U-Boot as main bootloader
51------------------------------------------------
52
53Intel Edison instructions:
54
55Simple you can build U-Boot and obtain u-boot.bin
56
57$ make edison_defconfig
58$ make all
59
Stoppa, Igor28a85362015-08-13 16:43:35 +030060Build Instructions for U-Boot as BIOS replacement (bare mode)
61-------------------------------------------------------------
Simon Glass3a1a18f2015-01-27 22:13:47 -070062Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
Bin Meng5dad97e2014-12-17 15:50:48 +080063little bit tricky, as generally it requires several binary blobs which are not
64shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is
65not turned on by default in the U-Boot source tree. Firstly, you need turn it
Heinrich Schuchardt871aa412017-10-16 18:08:38 +000066on by enabling the ROM build either via an environment variable
Bin Meng5dad97e2014-12-17 15:50:48 +080067
Heinrich Schuchardt871aa412017-10-16 18:08:38 +000068 $ export BUILD_ROM=y
Simon Glasseea0f112015-01-27 22:13:32 -070069
Heinrich Schuchardt871aa412017-10-16 18:08:38 +000070or via configuration
71
72 CONFIG_BUILD_ROM=y
73
74Both tell the Makefile to build u-boot.rom as a target.
Bin Meng5dad97e2014-12-17 15:50:48 +080075
Stoppa, Igor28a85362015-08-13 16:43:35 +030076---
77
78Chromebook Link specific instructions for bare mode:
Bin Meng5dad97e2014-12-17 15:50:48 +080079
80First, you need the following binary blobs:
81
82* descriptor.bin - Intel flash descriptor
83* me.bin - Intel Management Engine
84* mrc.bin - Memory Reference Code, which sets up SDRAM
85* video ROM - sets up the display
86
87You can get these binary blobs by:
88
89$ git clone http://review.coreboot.org/p/blobs.git
90$ cd blobs
91
92Find the following files:
93
94* ./mainboard/google/link/descriptor.bin
95* ./mainboard/google/link/me.bin
Simon Glass8712af92015-04-19 22:05:37 -060096* ./northbridge/intel/sandybridge/systemagent-r6.bin
Bin Meng5dad97e2014-12-17 15:50:48 +080097
98The 3rd one should be renamed to mrc.bin.
Bin Meng786a08e2015-07-06 16:31:33 +080099As for the video ROM, you can get it here [3] and rename it to vga.bin.
Bin Meng5dad97e2014-12-17 15:50:48 +0800100Make sure all these binary blobs are put in the board directory.
101
102Now you can build U-Boot and obtain u-boot.rom:
103
104$ make chromebook_link_defconfig
105$ make all
106
Stoppa, Igor28a85362015-08-13 16:43:35 +0300107---
108
Simon Glass374e78e2016-03-16 07:44:43 -0600109Chromebook Samus (2015 Pixel) instructions for bare mode:
110
111First, you need the following binary blobs:
112
113* descriptor.bin - Intel flash descriptor
114* me.bin - Intel Management Engine
115* mrc.bin - Memory Reference Code, which sets up SDRAM
116* refcode.elf - Additional Reference code
117* vga.bin - video ROM, which sets up the display
118
119If you have a samus you can obtain them from your flash, for example, in
120developer mode on the Chromebook (use Ctrl-Alt-F2 to obtain a terminal and
121log in as 'root'):
122
123 cd /tmp
124 flashrom -w samus.bin
125 scp samus.bin username@ip_address:/path/to/somewhere
126
127If not see the coreboot tree [4] where you can use:
128
129 bash crosfirmware.sh samus
130
131to get the image. There is also an 'extract_blobs.sh' scripts that you can use
132on the 'coreboot-Google_Samus.*' file to short-circuit some of the below.
133
134Then 'ifdtool -x samus.bin' on your development machine will produce:
135
136 flashregion_0_flashdescriptor.bin
137 flashregion_1_bios.bin
138 flashregion_2_intel_me.bin
139
140Rename flashregion_0_flashdescriptor.bin to descriptor.bin
141Rename flashregion_2_intel_me.bin to me.bin
142You can ignore flashregion_1_bios.bin - it is not used.
143
144To get the rest, use 'cbfstool samus.bin print':
145
146samus.bin: 8192 kB, bootblocksize 2864, romsize 8388608, offset 0x700000
147alignment: 64 bytes, architecture: x86
148
149Name Offset Type Size
150cmos_layout.bin 0x700000 cmos_layout 1164
151pci8086,0406.rom 0x7004c0 optionrom 65536
152spd.bin 0x710500 (unknown) 4096
153cpu_microcode_blob.bin 0x711540 microcode 70720
154fallback/romstage 0x722a00 stage 54210
155fallback/ramstage 0x72fe00 stage 96382
156config 0x7476c0 raw 6075
157fallback/vboot 0x748ec0 stage 15980
158fallback/refcode 0x74cd80 stage 75578
159fallback/payload 0x75f500 payload 62878
160u-boot.dtb 0x76eb00 (unknown) 5318
161(empty) 0x770000 null 196504
162mrc.bin 0x79ffc0 (unknown) 222876
163(empty) 0x7d66c0 null 167320
164
165You can extract what you need:
166
167 cbfstool samus.bin extract -n pci8086,0406.rom -f vga.bin
168 cbfstool samus.bin extract -n fallback/refcode -f refcode.rmod
169 cbfstool samus.bin extract -n mrc.bin -f mrc.bin
170 cbfstool samus.bin extract -n fallback/refcode -f refcode.bin -U
171
172Note that the -U flag is only supported by the latest cbfstool. It unpacks
173and decompresses the stage to produce a coreboot rmodule. This is a simple
174representation of an ELF file. You need the patch "Support decoding a stage
175with compression".
176
177Put all 5 files into board/google/chromebook_samus.
178
179Now you can build U-Boot and obtain u-boot.rom:
180
181$ make chromebook_link_defconfig
182$ make all
183
184If you are using em100, then this command will flash write -Boot:
185
186 em100 -s -d filename.rom -c W25Q64CV -r
187
Simon Glassd4d25212019-05-02 10:52:16 -0600188Flash map for samus / broadwell:
189
190 fffff800 SYS_X86_START16
191 ffff0000 RESET_SEG_START
192 fffd8000 TPL_TEXT_BASE
193 fffa0000 X86_MRC_ADDR
194 fff90000 VGA_BIOS_ADDR
195 ffed0000 SYS_TEXT_BASE
196 ffea0000 X86_REFCODE_ADDR
197 ffe70000 SPL_TEXT_BASE
198 ffbf8000 CONFIG_ENV_OFFSET (environemnt offset)
199 ffbe0000 rw-mrc-cache (Memory-reference-code cache)
200 ffa00000 <spare>
201 ff801000 intel-me (address set by descriptor.bin)
202 ff800000 intel-descriptor
203
Simon Glass374e78e2016-03-16 07:44:43 -0600204---
205
Stoppa, Igor28a85362015-08-13 16:43:35 +0300206Intel Crown Bay specific instructions for bare mode:
Bin Meng5dad97e2014-12-17 15:50:48 +0800207
Bin Meng1ae5b782015-05-07 21:34:12 +0800208U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
209Firmware Support Package [5] to perform all the necessary initialization steps
Bin Meng5dad97e2014-12-17 15:50:48 +0800210as documented in the BIOS Writer Guide, including initialization of the CPU,
211memory controller, chipset and certain bus interfaces.
212
213Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T,
214install it on your host and locate the FSP binary blob. Note this platform
215also requires a Chipset Micro Code (CMC) state machine binary to be present in
216the SPI flash where u-boot.rom resides, and this CMC binary blob can be found
217in this FSP package too.
218
219* ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd
220* ./Microcode/C0_22211.BIN
221
222Rename the first one to fsp.bin and second one to cmc.bin and put them in the
223board directory.
224
Bin Meng83d97122015-03-05 11:21:03 +0800225Note the FSP release version 001 has a bug which could cause random endless
226loop during the FspInit call. This bug was published by Intel although Intel
227did not describe any details. We need manually apply the patch to the FSP
228binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP
229binary, change the following five bytes values from orginally E8 42 FF FF FF
230to B8 00 80 0B 00.
231
Bin Meng7aaff9b2015-07-06 16:31:35 +0800232As for the video ROM, you need manually extract it from the Intel provided
233BIOS for Crown Bay here [6], using the AMI MMTool [7]. Check PCI option ROM
234ID 8086:4108, extract and save it as vga.bin in the board directory.
235
Bin Meng617b8672015-01-06 22:14:24 +0800236Now you can build U-Boot and obtain u-boot.rom
Bin Meng5dad97e2014-12-17 15:50:48 +0800237
238$ make crownbay_defconfig
239$ make all
240
Stoppa, Igor28a85362015-08-13 16:43:35 +0300241---
242
Bin Menga2e3b052016-02-17 00:16:25 -0800243Intel Cougar Canyon 2 specific instructions for bare mode:
244
245This uses Intel FSP for 3rd generation Intel Core and Intel Celeron processors
246with mobile Intel HM76 and QM77 chipsets platform. Download it from Intel FSP
247website and put the .fd file (CHIEFRIVER_FSP_GOLD_001_09-OCTOBER-2013.fd at the
248time of writing) in the board directory and rename it to fsp.bin.
249
250Now build U-Boot and obtain u-boot.rom
251
252$ make cougarcanyon2_defconfig
253$ make all
254
255The board has two 8MB SPI flashes mounted, which are called SPI-0 and SPI-1 in
256the board manual. The SPI-0 flash should have flash descriptor plus ME firmware
257and SPI-1 flash is used to store U-Boot. For convenience, the complete 8MB SPI-0
258flash image is included in the FSP package (named Rom00_8M_MB_PPT.bin). Program
259this image to the SPI-0 flash according to the board manual just once and we are
Bin Mengfb05f0b2018-06-03 19:04:17 -0700260all set. For programming U-Boot we just need to program SPI-1 flash. Since the
261default u-boot.rom image for this board is set to 2MB, it should be programmed
262to the last 2MB of the 8MB chip, address range [600000, 7FFFFF].
Bin Menga2e3b052016-02-17 00:16:25 -0800263
264---
265
Bin Meng03bfc782016-02-17 00:47:04 -0800266Intel Bay Trail based board instructions for bare mode:
Simon Glass3a1a18f2015-01-27 22:13:47 -0700267
268This uses as FSP as with Crown Bay, except it is for the Atom E3800 series.
Bin Meng03bfc782016-02-17 00:47:04 -0800269Two boards that use this configuration are Bayley Bay and Minnowboard MAX.
Simon Glass3a1a18f2015-01-27 22:13:47 -0700270Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at
Bin Meng03bfc782016-02-17 00:47:04 -0800271the time of writing). Put it in the corresponding board directory and rename
272it to fsp.bin.
Simon Glass3a1a18f2015-01-27 22:13:47 -0700273
274Obtain the VGA RAM (Vga.dat at the time of writing) and put it into the same
Bin Meng03bfc782016-02-17 00:47:04 -0800275board directory as vga.bin.
Simon Glass3a1a18f2015-01-27 22:13:47 -0700276
Bin Meng03bfc782016-02-17 00:47:04 -0800277You still need two more binary blobs. For Bayley Bay, they can be extracted
278from the sample SPI image provided in the FSP (SPI.bin at the time of writing).
279
280 $ ./tools/ifdtool -x BayleyBay/SPI.bin
281 $ cp flashregion_0_flashdescriptor.bin board/intel/bayleybay/descriptor.bin
282 $ cp flashregion_2_intel_me.bin board/intel/bayleybay/me.bin
283
284For Minnowboard MAX, we can reuse the same ME firmware above, but for flash
285descriptor, we need get that somewhere else, as the one above does not seem to
286work, probably because it is not designed for the Minnowboard MAX. Now download
287the original firmware image for this board from:
Simon Glass68522482015-04-25 11:46:43 -0600288
289http://firmware.intel.com/sites/default/files/2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip
290
291Unzip it:
292
293 $ unzip 2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip
Simon Glass3a1a18f2015-01-27 22:13:47 -0700294
295Use ifdtool in the U-Boot tools directory to extract the images from that
296file, for example:
297
Simon Glass68522482015-04-25 11:46:43 -0600298 $ ./tools/ifdtool -x MNW2MAX1.X64.0073.R02.1409160934.bin
299
300This will provide the descriptor file - copy this into the correct place:
301
302 $ cp flashregion_0_flashdescriptor.bin board/intel/minnowmax/descriptor.bin
303
Simon Glass3a1a18f2015-01-27 22:13:47 -0700304Now you can build U-Boot and obtain u-boot.rom
Bin Meng03bfc782016-02-17 00:47:04 -0800305Note: below are examples/information for Minnowboard MAX.
Simon Glass3a1a18f2015-01-27 22:13:47 -0700306
307$ make minnowmax_defconfig
308$ make all
309
Simon Glassdf898672015-07-03 18:28:28 -0600310Checksums are as follows (but note that newer versions will invalidate this):
311
312$ md5sum -b board/intel/minnowmax/*.bin
313ffda9a3b94df5b74323afb328d51e6b4 board/intel/minnowmax/descriptor.bin
31469f65b9a580246291d20d08cbef9d7c5 board/intel/minnowmax/fsp.bin
315894a97d371544ec21de9c3e8e1716c4b board/intel/minnowmax/me.bin
316a2588537da387da592a27219d56e9962 board/intel/minnowmax/vga.bin
317
Simon Glass537ccba2015-07-03 18:28:24 -0600318The ROM image is broken up into these parts:
319
320Offset Description Controlling config
321------------------------------------------------------------
322000000 descriptor.bin Hard-coded to 0 in ifdtool
323001000 me.bin Set by the descriptor
324500000 <spare>
Bin Meng91fc5bf2016-05-11 07:44:55 -07003256ef000 Environment CONFIG_ENV_OFFSET
Bin Meng638a0582015-10-11 21:37:44 -07003266f0000 MRC cache CONFIG_ENABLE_MRC_CACHE
Simon Glass537ccba2015-07-03 18:28:24 -0600327700000 u-boot-dtb.bin CONFIG_SYS_TEXT_BASE
Bin Meng917d3562017-10-07 02:43:52 -07003287b0000 vga.bin CONFIG_VGA_BIOS_ADDR
Simon Glass537ccba2015-07-03 18:28:24 -06003297c0000 fsp.bin CONFIG_FSP_ADDR
3307f8000 <spare> (depends on size of fsp.bin)
Simon Glass537ccba2015-07-03 18:28:24 -06003317ff800 U-Boot 16-bit boot CONFIG_SYS_X86_START16
332
333Overall ROM image size is controlled by CONFIG_ROM_SIZE.
334
Stefan Roese5d98c5e2016-07-13 08:23:40 +0200335Note that the debug version of the FSP is bigger in size. If this version
336is used, CONFIG_FSP_ADDR needs to be configured to 0xfffb0000 instead of
337the default value 0xfffc0000.
338
Stoppa, Igor28a85362015-08-13 16:43:35 +0300339---
Simon Glass537ccba2015-07-03 18:28:24 -0600340
Bin Mengeb457872017-08-15 22:42:02 -0700341Intel Cherry Hill specific instructions for bare mode:
342
343This uses Intel FSP for Braswell platform. Download it from Intel FSP website,
344put the .fd file to the board directory and rename it to fsp.bin.
345
346Extract descriptor.bin and me.bin from the original BIOS on the board using
347ifdtool and put them to the board directory as well.
348
349Note the FSP package for Braswell does not ship a traditional legacy VGA BIOS
350image for the integrated graphics device. Instead a new binary called Video
351BIOS Table (VBT) is shipped. Put it to the board directory and rename it to
352vbt.bin if you want graphics support in U-Boot.
353
354Now you can build U-Boot and obtain u-boot.rom
355
356$ make cherryhill_defconfig
357$ make all
358
359An important note for programming u-boot.rom to the on-board SPI flash is that
360you need make sure the SPI flash's 'quad enable' bit in its status register
361matches the settings in the descriptor.bin, otherwise the board won't boot.
362
363For the on-board SPI flash MX25U6435F, this can be done by writing 0x40 to the
364status register by DediProg in: Config > Modify Status Register > Write Status
365Register(s) > Register1 Value(Hex). This is is a one-time change. Once set, it
366persists in SPI flash part regardless of the u-boot.rom image burned.
367
368---
369
Stoppa, Igor28a85362015-08-13 16:43:35 +0300370Intel Galileo instructions for bare mode:
Bin Meng67582c02015-02-04 16:26:14 +0800371
372Only one binary blob is needed for Remote Management Unit (RMU) within Intel
373Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is
374needed by the Quark SoC itself.
375
376You can get the binary blob from Quark Board Support Package from Intel website:
377
378* ./QuarkSocPkg/QuarkNorthCluster/Binary/QuarkMicrocode/RMU.bin
379
380Rename the file and put it to the board directory by:
381
382 $ cp RMU.bin board/intel/galileo/rmu.bin
383
384Now you can build U-Boot and obtain u-boot.rom
385
386$ make galileo_defconfig
387$ make all
Simon Glass3a1a18f2015-01-27 22:13:47 -0700388
Bin Meng03bfc782016-02-17 00:47:04 -0800389---
390
391QEMU x86 target instructions for bare mode:
Bin Meng1ae5b782015-05-07 21:34:12 +0800392
393To build u-boot.rom for QEMU x86 targets, just simply run
394
Bin Meng6feb2ff2018-10-13 20:52:03 -0700395$ make qemu-x86_defconfig (for 32-bit)
396or
397$ make qemu-x86_64_defconfig (for 64-bit)
Bin Meng1ae5b782015-05-07 21:34:12 +0800398$ make all
399
Bin Meng683b09d2015-06-03 09:20:04 +0800400Note this default configuration will build a U-Boot for the QEMU x86 i440FX
401board. To build a U-Boot against QEMU x86 Q35 board, you can change the build
402configuration during the 'make menuconfig' process like below:
403
404Device Tree Control --->
405 ...
406 (qemu-x86_q35) Default Device Tree for DT control
407
Bin Meng617b8672015-01-06 22:14:24 +0800408Test with coreboot
409------------------
410For testing U-Boot as the coreboot payload, there are things that need be paid
411attention to. coreboot supports loading an ELF executable and a 32-bit plain
412binary, as well as other supported payloads. With the default configuration,
413U-Boot is set up to use a separate Device Tree Blob (dtb). As of today, the
414generated u-boot-dtb.bin needs to be packaged by the cbfstool utility (a tool
415provided by coreboot) manually as coreboot's 'make menuconfig' does not provide
416this capability yet. The command is as follows:
417
418# in the coreboot root directory
419$ ./build/util/cbfstool/cbfstool build/coreboot.rom add-flat-binary \
Bin Meng330728d2015-08-13 00:29:07 -0700420 -f u-boot-dtb.bin -n fallback/payload -c lzma -l 0x1110000 -e 0x1110000
Bin Meng617b8672015-01-06 22:14:24 +0800421
Bin Meng330728d2015-08-13 00:29:07 -0700422Make sure 0x1110000 matches CONFIG_SYS_TEXT_BASE, which is the symbol address
423of _x86boot_start (in arch/x86/cpu/start.S).
Bin Meng617b8672015-01-06 22:14:24 +0800424
425If you want to use ELF as the coreboot payload, change U-Boot configuration to
Simon Glasseea0f112015-01-27 22:13:32 -0700426use CONFIG_OF_EMBED instead of CONFIG_OF_SEPARATE.
Bin Meng617b8672015-01-06 22:14:24 +0800427
Simon Glass3a1a18f2015-01-27 22:13:47 -0700428To enable video you must enable these options in coreboot:
429
430 - Set framebuffer graphics resolution (1280x1024 32k-color (1:5:5))
431 - Keep VESA framebuffer
432
433At present it seems that for Minnowboard Max, coreboot does not pass through
434the video information correctly (it always says the resolution is 0x0). This
435works correctly for link though.
436
Stoppa, Igor28a85362015-08-13 16:43:35 +0300437Test with QEMU for bare mode
438----------------------------
Bin Meng1ae5b782015-05-07 21:34:12 +0800439QEMU is a fancy emulator that can enable us to test U-Boot without access to
Bin Meng9c4f5412015-05-11 07:36:30 +0800440a real x86 board. Please make sure your QEMU version is 2.3.0 or above test
441U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:
Bin Meng1ae5b782015-05-07 21:34:12 +0800442
443$ qemu-system-i386 -nographic -bios path/to/u-boot.rom
444
445This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU
446also supports emulating an x86 board with Q35 and ICH9 based chipset, which is
447also supported by U-Boot. To instantiate such a machine, call QEMU with:
448
449$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35
450
451Note by default QEMU instantiated boards only have 128 MiB system memory. But
452it is enough to have U-Boot boot and function correctly. You can increase the
453system memory by pass '-m' parameter to QEMU if you want more memory:
454
455$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024
456
457This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only
458supports 3 GiB maximum system memory and reserves the last 1 GiB address space
459for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m'
460would be 3072.
Simon Glass3a1a18f2015-01-27 22:13:47 -0700461
Bin Meng9c4f5412015-05-11 07:36:30 +0800462QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will
463show QEMU's VGA console window. Note this will disable QEMU's serial output.
464If you want to check both consoles, use '-serial stdio'.
465
Bin Menga2eb65f2015-07-27 19:16:08 +0800466Multicore is also supported by QEMU via '-smp n' where n is the number of cores
Miao Yan5c2ed612016-01-07 01:32:06 -0800467to instantiate. Note, the maximum supported CPU number in QEMU is 255.
468
Bin Mengeda995a2016-05-07 07:46:36 -0700469The fw_cfg interface in QEMU also provides information about kernel data,
470initrd, command-line arguments and more. U-Boot supports directly accessing
471these informtion from fw_cfg interface, which saves the time of loading them
472from hard disk or network again, through emulated devices. To use it , simply
473providing them in QEMU command line:
Miao Yan5c2ed612016-01-07 01:32:06 -0800474
475$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 -kernel /path/to/bzImage
476 -append 'root=/dev/ram console=ttyS0' -initrd /path/to/initrd -smp 8
477
478Note: -initrd and -smp are both optional
479
Bin Mengeda995a2016-05-07 07:46:36 -0700480Then start QEMU, in U-Boot command line use the following U-Boot command to
481setup kernel:
Miao Yan5c2ed612016-01-07 01:32:06 -0800482
483 => qfw
484qfw - QEMU firmware interface
485
486Usage:
487qfw <command>
488 - list : print firmware(s) currently loaded
489 - cpus : print online cpu number
490 - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot
491
492=> qfw load
493loading kernel to address 01000000 size 5d9d30 initrd 04000000 size 1b1ab50
494
Bin Mengeda995a2016-05-07 07:46:36 -0700495Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then,
496'zboot' can be used to boot the kernel:
Miao Yan5c2ed612016-01-07 01:32:06 -0800497
Bin Meng10491c82016-10-09 04:14:14 -0700498=> zboot 01000000 - 04000000 1b1ab50
Bin Menga2eb65f2015-07-27 19:16:08 +0800499
Bin Meng6feb2ff2018-10-13 20:52:03 -0700500To run 64-bit U-Boot, qemu-system-x86_64 should be used instead, e.g.:
501$ qemu-system-x86_64 -nographic -bios path/to/u-boot.rom
502
503A specific CPU can be specified via the '-cpu' parameter but please make
504sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely
505'-cpu pentium' won't work for obvious reasons that the processor only
506supports 32-bit.
507
508Note 64-bit support is very preliminary at this point. Lots of features
509are missing in the 64-bit world. One notable feature is the VGA console
510support which is currently missing, so that you must specify '-nographic'
511to get 64-bit U-Boot up and running.
512
Andy Shevchenko495f3772017-07-06 14:41:53 +0300513Updating U-Boot on Edison
514-------------------------
515By default Intel Edison boards are shipped with preinstalled heavily
516patched U-Boot v2014.04. Though it supports DFU which we may be able to
517use.
518
5191. Prepare u-boot.bin as described in chapter above. You still need one
520more step (if and only if you have original U-Boot), i.e. run the
521following command:
522
523$ truncate -s %4096 u-boot.bin
524
5252. Run your board and interrupt booting to U-Boot console. In the console
526call:
527
528 => run do_force_flash_os
529
5303. Wait for few seconds, it will prepare environment variable and runs
531DFU. Run DFU command from the host system:
532
533$ dfu-util -v -d 8087:0a99 --alt u-boot0 -D u-boot.bin
534
5354. Return to U-Boot console and following hint. i.e. push Ctrl+C, and
536reset the board:
537
538 => reset
539
Bin Meng5dad97e2014-12-17 15:50:48 +0800540CPU Microcode
541-------------
Bin Meng7aaff9b2015-07-06 16:31:35 +0800542Modern CPUs usually require a special bit stream called microcode [8] to be
Bin Meng5dad97e2014-12-17 15:50:48 +0800543loaded on the processor after power up in order to function properly. U-Boot
544has already integrated these as hex dumps in the source tree.
545
Bin Meng1281a1f2015-06-23 12:18:53 +0800546SMP Support
547-----------
548On a multicore system, U-Boot is executed on the bootstrap processor (BSP).
549Additional application processors (AP) can be brought up by U-Boot. In order to
550have an SMP kernel to discover all of the available processors, U-Boot needs to
551prepare configuration tables which contain the multi-CPUs information before
552loading the OS kernel. Currently U-Boot supports generating two types of tables
Bin Meng7aaff9b2015-07-06 16:31:35 +0800553for SMP, called Simple Firmware Interface (SFI) [9] and Multi-Processor (MP)
554[10] tables. The writing of these two tables are controlled by two Kconfig
555options GENERATE_SFI_TABLE and GENERATE_MP_TABLE.
Bin Meng1281a1f2015-06-23 12:18:53 +0800556
Bin Meng5dad97e2014-12-17 15:50:48 +0800557Driver Model
558------------
Simon Glassf21069f2016-03-11 22:07:33 -0700559x86 has been converted to use driver model for serial, GPIO, SPI, SPI flash,
560keyboard, real-time clock, USB. Video is in progress.
Bin Meng5dad97e2014-12-17 15:50:48 +0800561
562Device Tree
563-----------
564x86 uses device tree to configure the board thus requires CONFIG_OF_CONTROL to
Bin Meng617b8672015-01-06 22:14:24 +0800565be turned on. Not every device on the board is configured via device tree, but
Bin Meng5dad97e2014-12-17 15:50:48 +0800566more and more devices will be added as time goes by. Check out the directory
567arch/x86/dts/ for these device tree source files.
568
Simon Glasscb3b2e62015-01-01 16:18:15 -0700569Useful Commands
570---------------
Simon Glasscb3b2e62015-01-01 16:18:15 -0700571In keeping with the U-Boot philosophy of providing functions to check and
572adjust internal settings, there are several x86-specific commands that may be
573useful:
574
Bin Meng62716eb2015-10-10 01:47:58 -0700575fsp - Display information about Intel Firmware Support Package (FSP).
576 This is only available on platforms which use FSP, mostly Atom.
Simon Glasscb3b2e62015-01-01 16:18:15 -0700577iod - Display I/O memory
578iow - Write I/O memory
579mtrr - List and set the Memory Type Range Registers (MTRR). These are used to
580 tell the CPU whether memory is cacheable and if so the cache write
581 mode to use. U-Boot sets up some reasonable values but you can
582 adjust then with this command.
583
Simon Glass7bea5272015-07-27 15:47:31 -0600584Booting Ubuntu
585--------------
586As an example of how to set up your boot flow with U-Boot, here are
587instructions for starting Ubuntu from U-Boot. These instructions have been
Bin Mengeda995a2016-05-07 07:46:36 -0700588tested on Minnowboard MAX with a SATA drive but are equally applicable on
589other platforms and other media. There are really only four steps and it's a
Simon Glass7bea5272015-07-27 15:47:31 -0600590very simple script, but a more detailed explanation is provided here for
591completeness.
592
593Note: It is possible to set up U-Boot to boot automatically using syslinux.
594It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the
595GUID. If you figure these out, please post patches to this README.
596
Bin Mengeda995a2016-05-07 07:46:36 -0700597Firstly, you will need Ubuntu installed on an available disk. It should be
Simon Glass7bea5272015-07-27 15:47:31 -0600598possible to make U-Boot start a USB start-up disk but for now let's assume
599that you used another boot loader to install Ubuntu.
600
601Use the U-Boot command line to find the UUID of the partition you want to
602boot. For example our disk is SCSI device 0:
603
604=> part list scsi 0
605
606Partition Map for SCSI device 0 -- Partition Type: EFI
607
608 Part Start LBA End LBA Name
609 Attributes
610 Type GUID
611 Partition GUID
612 1 0x00000800 0x001007ff ""
613 attrs: 0x0000000000000000
614 type: c12a7328-f81f-11d2-ba4b-00a0c93ec93b
615 guid: 9d02e8e4-4d59-408f-a9b0-fd497bc9291c
616 2 0x00100800 0x037d8fff ""
617 attrs: 0x0000000000000000
618 type: 0fc63daf-8483-4772-8e79-3d69d8477de4
619 guid: 965c59ee-1822-4326-90d2-b02446050059
620 3 0x037d9000 0x03ba27ff ""
621 attrs: 0x0000000000000000
622 type: 0657fd6d-a4ab-43c4-84e5-0933c84b4f4f
623 guid: 2c4282bd-1e82-4bcf-a5ff-51dedbf39f17
624 =>
625
626This shows that your SCSI disk has three partitions. The really long hex
627strings are called Globally Unique Identifiers (GUIDs). You can look up the
628'type' ones here [11]. On this disk the first partition is for EFI and is in
629VFAT format (DOS/Windows):
630
631 => fatls scsi 0:1
632 efi/
633
634 0 file(s), 1 dir(s)
635
636
637Partition 2 is 'Linux filesystem data' so that will be our root disk. It is
638in ext2 format:
639
640 => ext2ls scsi 0:2
641 <DIR> 4096 .
642 <DIR> 4096 ..
643 <DIR> 16384 lost+found
644 <DIR> 4096 boot
645 <DIR> 12288 etc
646 <DIR> 4096 media
647 <DIR> 4096 bin
648 <DIR> 4096 dev
649 <DIR> 4096 home
650 <DIR> 4096 lib
651 <DIR> 4096 lib64
652 <DIR> 4096 mnt
653 <DIR> 4096 opt
654 <DIR> 4096 proc
655 <DIR> 4096 root
656 <DIR> 4096 run
657 <DIR> 12288 sbin
658 <DIR> 4096 srv
659 <DIR> 4096 sys
660 <DIR> 4096 tmp
661 <DIR> 4096 usr
662 <DIR> 4096 var
663 <SYM> 33 initrd.img
664 <SYM> 30 vmlinuz
665 <DIR> 4096 cdrom
666 <SYM> 33 initrd.img.old
667 =>
668
669and if you look in the /boot directory you will see the kernel:
670
671 => ext2ls scsi 0:2 /boot
672 <DIR> 4096 .
673 <DIR> 4096 ..
674 <DIR> 4096 efi
675 <DIR> 4096 grub
676 3381262 System.map-3.13.0-32-generic
677 1162712 abi-3.13.0-32-generic
678 165611 config-3.13.0-32-generic
679 176500 memtest86+.bin
680 178176 memtest86+.elf
681 178680 memtest86+_multiboot.bin
682 5798112 vmlinuz-3.13.0-32-generic
683 165762 config-3.13.0-58-generic
684 1165129 abi-3.13.0-58-generic
685 5823136 vmlinuz-3.13.0-58-generic
686 19215259 initrd.img-3.13.0-58-generic
687 3391763 System.map-3.13.0-58-generic
688 5825048 vmlinuz-3.13.0-58-generic.efi.signed
689 28304443 initrd.img-3.13.0-32-generic
690 =>
691
692The 'vmlinuz' files contain a packaged Linux kernel. The format is a kind of
693self-extracting compressed file mixed with some 'setup' configuration data.
694Despite its size (uncompressed it is >10MB) this only includes a basic set of
695device drivers, enough to boot on most hardware types.
696
697The 'initrd' files contain a RAM disk. This is something that can be loaded
698into RAM and will appear to Linux like a disk. Ubuntu uses this to hold lots
699of drivers for whatever hardware you might have. It is loaded before the
700real root disk is accessed.
701
702The numbers after the end of each file are the version. Here it is Linux
703version 3.13. You can find the source code for this in the Linux tree with
704the tag v3.13. The '.0' allows for additional Linux releases to fix problems,
705but normally this is not needed. The '-58' is used by Ubuntu. Each time they
706release a new kernel they increment this number. New Ubuntu versions might
707include kernel patches to fix reported bugs. Stable kernels can exist for
708some years so this number can get quite high.
709
710The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own
711secure boot mechanism - see [12] [13] and cannot read .efi files at present.
712
713To boot Ubuntu from U-Boot the steps are as follows:
714
7151. Set up the boot arguments. Use the GUID for the partition you want to
716boot:
717
718 => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro
719
720Here root= tells Linux the location of its root disk. The disk is specified
721by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory'
722containing all the GUIDs Linux has found. When it starts up, there will be a
723file in that directory with this name in it. It is also possible to use a
724device name here, see later.
725
7262. Load the kernel. Since it is an ext2/4 filesystem we can do:
727
728 => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic
729
730The address 30000000 is arbitrary, but there seem to be problems with using
731small addresses (sometimes Linux cannot find the ramdisk). This is 48MB into
732the start of RAM (which is at 0 on x86).
733
7343. Load the ramdisk (to 64MB):
735
736 => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic
737
7384. Start up the kernel. We need to know the size of the ramdisk, but can use
739a variable for that. U-Boot sets 'filesize' to the size of the last file it
740loaded.
741
742 => zboot 03000000 0 04000000 ${filesize}
743
744Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is
745quite verbose when it boots a kernel. You should see these messages from
746U-Boot:
747
748 Valid Boot Flag
749 Setup Size = 0x00004400
750 Magic signature found
751 Using boot protocol version 2.0c
752 Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015
753 Building boot_params at 0x00090000
754 Loading bzImage at address 100000 (5805728 bytes)
755 Magic signature found
756 Initial RAM disk at linear address 0x04000000, size 19215259 bytes
Bin Mengeda995a2016-05-07 07:46:36 -0700757 Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro"
Simon Glass7bea5272015-07-27 15:47:31 -0600758
759 Starting kernel ...
760
761U-Boot prints out some bootstage timing. This is more useful if you put the
762above commands into a script since then it will be faster.
763
764 Timer summary in microseconds:
765 Mark Elapsed Stage
766 0 0 reset
767 241,535 241,535 board_init_r
768 2,421,611 2,180,076 id=64
769 2,421,790 179 id=65
770 2,428,215 6,425 main_loop
771 48,860,584 46,432,369 start_kernel
772
773 Accumulated time:
774 240,329 ahci
775 1,422,704 vesa display
776
Bin Mengeda995a2016-05-07 07:46:36 -0700777Now the kernel actually starts: (if you want to examine kernel boot up message
778on the serial console, append "console=ttyS0,115200" to the kernel command line)
Simon Glass7bea5272015-07-27 15:47:31 -0600779
780 [ 0.000000] Initializing cgroup subsys cpuset
781 [ 0.000000] Initializing cgroup subsys cpu
782 [ 0.000000] Initializing cgroup subsys cpuacct
783 [ 0.000000] Linux version 3.13.0-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015 (Ubuntu 3.13.0-58.97-generic 3.13.11-ckt22)
Bin Mengeda995a2016-05-07 07:46:36 -0700784 [ 0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200
Simon Glass7bea5272015-07-27 15:47:31 -0600785
786It continues for a long time. Along the way you will see it pick up your
787ramdisk:
788
789 [ 0.000000] RAMDISK: [mem 0x04000000-0x05253fff]
790...
791 [ 0.788540] Trying to unpack rootfs image as initramfs...
792 [ 1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000)
793...
794
795Later it actually starts using it:
796
797 Begin: Running /scripts/local-premount ... done.
798
799You should also see your boot disk turn up:
800
801 [ 4.357243] scsi 1:0:0:0: Direct-Access ATA ADATA SP310 5.2 PQ: 0 ANSI: 5
802 [ 4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB)
803 [ 4.375677] sd 1:0:0:0: Attached scsi generic sg0 type 0
804 [ 4.381859] sd 1:0:0:0: [sda] Write Protect is off
805 [ 4.387452] sd 1:0:0:0: [sda] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
806 [ 4.399535] sda: sda1 sda2 sda3
807
808Linux has found the three partitions (sda1-3). Mercifully it doesn't print out
809the GUIDs. In step 1 above we could have used:
810
811 setenv bootargs root=/dev/sda2 ro
812
813instead of the GUID. However if you add another drive to your board the
814numbering may change whereas the GUIDs will not. So if your boot partition
815becomes sdb2, it will still boot. For embedded systems where you just want to
816boot the first disk, you have that option.
817
818The last thing you will see on the console is mention of plymouth (which
819displays the Ubuntu start-up screen) and a lot of 'Starting' messages:
820
821 * Starting Mount filesystems on boot [ OK ]
822
823After a pause you should see a login screen on your display and you are done.
824
825If you want to put this in a script you can use something like this:
826
827 setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro
828 setenv boot zboot 03000000 0 04000000 \${filesize}
829 setenv bootcmd "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; run boot"
830 saveenv
831
832The \ is to tell the shell not to evaluate ${filesize} as part of the setenv
833command.
834
Simon Glass7bea5272015-07-27 15:47:31 -0600835You can also bake this behaviour into your build by hard-coding the
836environment variables if you add this to minnowmax.h:
837
Simon Glass7bea5272015-07-27 15:47:31 -0600838#undef CONFIG_BOOTCOMMAND
Simon Glass7bea5272015-07-27 15:47:31 -0600839#define CONFIG_BOOTCOMMAND \
840 "ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \
841 "ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \
842 "run boot"
843
844#undef CONFIG_EXTRA_ENV_SETTINGS
845#define CONFIG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}"
846
Sam Protsenko5abc1a42017-08-14 20:22:17 +0300847and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to:
848
849CONFIG_BOOTARGS="root=/dev/sda2 ro"
850
Bin Meng2e9ae222016-02-28 23:54:52 -0800851Test with SeaBIOS
852-----------------
853SeaBIOS [14] is an open source implementation of a 16-bit x86 BIOS. It can run
854in an emulator or natively on x86 hardware with the use of U-Boot. With its
855help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS.
856
857As U-Boot, we have to manually create a table where SeaBIOS gets various system
858information (eg: E820) from. The table unfortunately has to follow the coreboot
859table format as SeaBIOS currently supports booting as a coreboot payload.
860
861To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on.
862Booting SeaBIOS is done via U-Boot's bootelf command, like below:
863
864 => tftp bios.bin.elf;bootelf
865 Using e1000#0 device
866 TFTP from server 10.10.0.100; our IP address is 10.10.0.108
867 ...
868 Bytes transferred = 122124 (1dd0c hex)
869 ## Starting application at 0x000ff06e ...
870 SeaBIOS (version rel-1.9.0)
871 ...
872
873bios.bin.elf is the SeaBIOS image built from SeaBIOS source tree.
874Make sure it is built as follows:
875
876 $ make menuconfig
877
878Inside the "General Features" menu, select "Build for coreboot" as the
879"Build Target". Inside the "Debugging" menu, turn on "Serial port debugging"
880so that we can see something as soon as SeaBIOS boots. Leave other options
881as in their default state. Then,
882
883 $ make
884 ...
885 Total size: 121888 Fixed: 66496 Free: 9184 (used 93.0% of 128KiB rom)
886 Creating out/bios.bin.elf
887
888Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS
889to install/boot a Windows XP OS (below for example command to install Windows).
890
891 # Create a 10G disk.img as the virtual hard disk
892 $ qemu-img create -f qcow2 disk.img 10G
893
894 # Install a Windows XP OS from an ISO image 'winxp.iso'
895 $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512
896
897 # Boot a Windows XP OS installed on the virutal hard disk
898 $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512
899
900This is also tested on Intel Crown Bay board with a PCIe graphics card, booting
901SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally.
902
Bin Meng5a6a2c72016-05-11 07:45:06 -0700903If you are using Intel Integrated Graphics Device (IGD) as the primary display
904device on your board, SeaBIOS needs to be patched manually to get its VGA ROM
905loaded and run by SeaBIOS. SeaBIOS locates VGA ROM via the PCI expansion ROM
906register, but IGD device does not have its VGA ROM mapped by this register.
907Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address
908which is unknown to SeaBIOS. An example patch is needed for SeaBIOS below:
909
910diff --git a/src/optionroms.c b/src/optionroms.c
911index 65f7fe0..c7b6f5e 100644
912--- a/src/optionroms.c
913+++ b/src/optionroms.c
914@@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources)
915 rom = deploy_romfile(file);
916 else if (RunPCIroms > 1 || (RunPCIroms == 1 && isvga))
917 rom = map_pcirom(pci);
918+ if (pci->bdf == pci_to_bdf(0, 2, 0))
919+ rom = (struct rom_header *)0xfff90000;
920 if (! rom)
921 // No ROM present.
922 return;
923
924Note: the patch above expects IGD device is at PCI b.d.f 0.2.0 and its VGA ROM
925is at 0xfff90000 which corresponds to CONFIG_VGA_BIOS_ADDR on Minnowboard MAX.
926Change these two accordingly if this is not the case on your board.
Simon Glass7bea5272015-07-27 15:47:31 -0600927
Simon Glass00bdd952015-01-27 22:13:46 -0700928Development Flow
929----------------
Simon Glass00bdd952015-01-27 22:13:46 -0700930These notes are for those who want to port U-Boot to a new x86 platform.
931
932Since x86 CPUs boot from SPI flash, a SPI flash emulator is a good investment.
933The Dediprog em100 can be used on Linux. The em100 tool is available here:
934
935 http://review.coreboot.org/p/em100.git
936
937On Minnowboard Max the following command line can be used:
938
939 sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r
940
941A suitable clip for connecting over the SPI flash chip is here:
942
943 http://www.dediprog.com/pd/programmer-accessories/EM-TC-8
944
945This allows you to override the SPI flash contents for development purposes.
946Typically you can write to the em100 in around 1200ms, considerably faster
947than programming the real flash device each time. The only important
948limitation of the em100 is that it only supports SPI bus speeds up to 20MHz.
949This means that images must be set to boot with that speed. This is an
950Intel-specific feature - e.g. tools/ifttool has an option to set the SPI
951speed in the SPI descriptor region.
952
953If your chip/board uses an Intel Firmware Support Package (FSP) it is fairly
954easy to fit it in. You can follow the Minnowboard Max implementation, for
955example. Hopefully you will just need to create new files similar to those
956in arch/x86/cpu/baytrail which provide Bay Trail support.
957
958If you are not using an FSP you have more freedom and more responsibility.
959The ivybridge support works this way, although it still uses a ROM for
960graphics and still has binary blobs containing Intel code. You should aim to
961support all important peripherals on your platform including video and storage.
962Use the device tree for configuration where possible.
963
964For the microcode you can create a suitable device tree file using the
965microcode tool:
966
Simon Glass03e3c312015-08-15 14:37:48 -0600967 ./tools/microcode-tool -d microcode.dat -m <model> create
Simon Glass00bdd952015-01-27 22:13:46 -0700968
969or if you only have header files and not the full Intel microcode.dat database:
970
971 ./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \
972 -H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h \
Simon Glass03e3c312015-08-15 14:37:48 -0600973 -m all create
Simon Glass00bdd952015-01-27 22:13:46 -0700974
975These are written to arch/x86/dts/microcode/ by default.
976
977Note that it is possible to just add the micrcode for your CPU if you know its
978model. U-Boot prints this information when it starts
979
980 CPU: x86_64, vendor Intel, device 30673h
981
982so here we can use the M0130673322 file.
983
984If you platform can display POST codes on two little 7-segment displays on
985the board, then you can use post_code() calls from C or assembler to monitor
986boot progress. This can be good for debugging.
987
988If not, you can try to get serial working as early as possible. The early
Stefan Roesed5211972016-01-19 14:24:12 +0100989debug serial port may be useful here. See setup_internal_uart() for an example.
Simon Glass00bdd952015-01-27 22:13:46 -0700990
Bin Meng12c75102015-08-02 20:33:35 -0700991During the U-Boot porting, one of the important steps is to write correct PIRQ
992routing information in the board device tree. Without it, device drivers in the
993Linux kernel won't function correctly due to interrupt is not working. Please
Bin Meng2e9ae222016-02-28 23:54:52 -0800994refer to U-Boot doc [15] for the device tree bindings of Intel interrupt router.
Bin Meng12c75102015-08-02 20:33:35 -0700995Here we have more details on the intel,pirq-routing property below.
996
997 intel,pirq-routing = <
998 PCI_BDF(0, 2, 0) INTA PIRQA
999 ...
1000 >;
1001
1002As you see each entry has 3 cells. For the first one, we need describe all pci
1003devices mounted on the board. For SoC devices, normally there is a chapter on
1004the chipset datasheet which lists all the available PCI devices. For example on
1005Bay Trail, this is chapter 4.3 (PCI configuration space). For the second one, we
1006can get the interrupt pin either from datasheet or hardware via U-Boot shell.
1007The reliable source is the hardware as sometimes chipset datasheet is not 100%
1008up-to-date. Type 'pci header' plus the device's pci bus/device/function number
1009from U-Boot shell below.
1010
1011 => pci header 0.1e.1
1012 vendor ID = 0x8086
1013 device ID = 0x0f08
1014 ...
1015 interrupt line = 0x09
1016 interrupt pin = 0x04
1017 ...
1018
1019It shows this PCI device is using INTD pin as it reports 4 in the interrupt pin
1020register. Repeat this until you get interrupt pins for all the devices. The last
1021cell is the PIRQ line which a particular interrupt pin is mapped to. On Intel
1022chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This
1023can be changed by registers in LPC bridge. So far Intel FSP does not touch those
1024registers so we can write down the PIRQ according to the default mapping rule.
1025
1026Once we get the PIRQ routing information in the device tree, the interrupt
1027allocation and assignment will be done by U-Boot automatically. Now you can
1028enable CONFIG_GENERATE_PIRQ_TABLE for testing Linux kernel using i8259 PIC and
1029CONFIG_GENERATE_MP_TABLE for testing Linux kernel using local APIC and I/O APIC.
1030
Simon Glass590870e2015-08-13 10:36:17 -06001031This script might be useful. If you feed it the output of 'pci long' from
1032U-Boot then it will generate a device tree fragment with the interrupt
1033configuration for each device (note it needs gawk 4.0.0):
1034
1035 $ cat console_output |awk '/PCI/ {device=$4} /interrupt line/ {line=$4} \
1036 /interrupt pin/ {pin = $4; if (pin != "0x00" && pin != "0xff") \
1037 {patsplit(device, bdf, "[0-9a-f]+"); \
1038 printf "PCI_BDF(%d, %d, %d) INT%c PIRQ%c\n", strtonum("0x" bdf[1]), \
1039 strtonum("0x" bdf[2]), bdf[3], strtonum(pin) + 64, 64 + strtonum(pin)}}'
1040
1041Example output:
1042 PCI_BDF(0, 2, 0) INTA PIRQA
1043 PCI_BDF(0, 3, 0) INTA PIRQA
1044...
1045
Bin Meng448719c2015-09-09 23:20:29 -07001046Porting Hints
1047-------------
1048
1049Quark-specific considerations:
1050
1051To port U-Boot to other boards based on the Intel Quark SoC, a few things need
1052to be taken care of. The first important part is the Memory Reference Code (MRC)
1053parameters. Quark MRC supports memory-down configuration only. All these MRC
1054parameters are supplied via the board device tree. To get started, first copy
1055the MRC section of arch/x86/dts/galileo.dts to your board's device tree, then
1056change these values by consulting board manuals or your hardware vendor.
1057Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h.
1058The other tricky part is with PCIe. Quark SoC integrates two PCIe root ports,
1059but by default they are held in reset after power on. In U-Boot, PCIe
1060initialization is properly handled as per Quark's firmware writer guide.
1061In your board support codes, you need provide two routines to aid PCIe
1062initialization, which are board_assert_perst() and board_deassert_perst().
1063The two routines need implement a board-specific mechanism to assert/deassert
1064PCIe PERST# pin. Care must be taken that in those routines that any APIs that
1065may trigger PCI enumeration process are strictly forbidden, as any access to
1066PCIe root port's configuration registers will cause system hang while it is
1067held in reset. For more details, check how they are implemented by the Intel
1068Galileo board support codes in board/intel/galileo/galileo.c.
1069
Simon Glasse28fcb22016-03-06 19:28:17 -07001070coreboot:
1071
1072See scripts/coreboot.sed which can assist with porting coreboot code into
1073U-Boot drivers. It will not resolve all build errors, but will perform common
1074transformations. Remember to add attribution to coreboot for new files added
1075to U-Boot. This should go at the top of each file and list the coreboot
1076filename where the code originated.
1077
Bin Mengefd4be42016-05-11 07:45:12 -07001078Debugging ACPI issues with Windows:
1079
1080Windows might cache system information and only detect ACPI changes if you
1081modify the ACPI table versions. So tweak them liberally when debugging ACPI
1082issues with Windows.
1083
Bin Meng49d929b2016-05-07 07:46:37 -07001084ACPI Support Status
1085-------------------
1086Advanced Configuration and Power Interface (ACPI) [16] aims to establish
1087industry-standard interfaces enabling OS-directed configuration, power
1088management, and thermal management of mobile, desktop, and server platforms.
1089
1090Linux can boot without ACPI with "acpi=off" command line parameter, but
1091with ACPI the kernel gains the capabilities to handle power management.
1092For Windows, ACPI is a must-have firmware feature since Windows Vista.
1093CONFIG_GENERATE_ACPI_TABLE is the config option to turn on ACPI support in
1094U-Boot. This requires Intel ACPI compiler to be installed on your host to
1095compile ACPI DSDT table written in ASL format to AML format. You can get
1096the compiler via "apt-get install iasl" if you are on Ubuntu or download
1097the source from [17] to compile one by yourself.
1098
Bin Meng13c9d842017-04-21 07:24:49 -07001099Current ACPI support in U-Boot is basically complete. More optional features
1100can be added in the future. The status as of today is:
Bin Meng49d929b2016-05-07 07:46:37 -07001101
1102 * Support generating RSDT, XSDT, FACS, FADT, MADT, MCFG tables.
1103 * Support one static DSDT table only, compiled by Intel ACPI compiler.
Bin Meng13c9d842017-04-21 07:24:49 -07001104 * Support S0/S3/S4/S5, reboot and shutdown from OS.
Bin Meng49d929b2016-05-07 07:46:37 -07001105 * Support booting a pre-installed Ubuntu distribution via 'zboot' command.
Bin Meng206a3a42016-05-11 07:45:08 -07001106 * Support installing and booting Ubuntu 14.04 (or above) from U-Boot with
1107 the help of SeaBIOS using legacy interface (non-UEFI mode).
1108 * Support installing and booting Windows 8.1/10 from U-Boot with the help
1109 of SeaBIOS using legacy interface (non-UEFI mode).
Bin Meng49d929b2016-05-07 07:46:37 -07001110 * Support ACPI interrupts with SCI only.
1111
Bin Meng49d929b2016-05-07 07:46:37 -07001112Features that are optional:
Bin Meng49d929b2016-05-07 07:46:37 -07001113 * Dynamic AML bytecodes insertion at run-time. We may need this to support
1114 SSDT table generation and DSDT fix up.
1115 * SMI support. Since U-Boot is a modern bootloader, we don't want to bring
1116 those legacy stuff into U-Boot. ACPI spec allows a system that does not
1117 support SMI (a legacy-free system).
1118
Bin Menge6ddb6b2016-05-25 19:19:12 -07001119ACPI was initially enabled on BayTrail based boards. Testing was done by booting
Bin Meng206a3a42016-05-11 07:45:08 -07001120a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and
1121Windows 8.1/10 to a SATA drive and booting from there is also tested. Most
1122devices seem to work correctly and the board can respond a reboot/shutdown
1123command from the OS.
Simon Glasse28fcb22016-03-06 19:28:17 -07001124
Bin Menge6ddb6b2016-05-25 19:19:12 -07001125For other platform boards, ACPI support status can be checked by examining their
1126board defconfig files to see if CONFIG_GENERATE_ACPI_TABLE is set to y.
1127
Bin Meng13c9d842017-04-21 07:24:49 -07001128The S3 sleeping state is a low wake latency sleeping state defined by ACPI
1129spec where all system context is lost except system memory. To test S3 resume
1130with a Linux kernel, simply run "echo mem > /sys/power/state" and kernel will
1131put the board to S3 state where the power is off. So when the power button is
1132pressed again, U-Boot runs as it does in cold boot and detects the sleeping
1133state via ACPI register to see if it is S3, if yes it means we are waking up.
1134U-Boot is responsible for restoring the machine state as it is before sleep.
1135When everything is done, U-Boot finds out the wakeup vector provided by OSes
1136and jump there. To determine whether ACPI S3 resume is supported, check to
1137see if CONFIG_HAVE_ACPI_RESUME is set for that specific board.
1138
1139Note for testing S3 resume with Windows, correct graphics driver must be
1140installed for your platform, otherwise you won't find "Sleep" option in
1141the "Power" submenu from the Windows start menu.
1142
Simon Glass007adbc2016-07-17 01:23:45 -06001143EFI Support
1144-----------
1145U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI.
Bin Meng9efeb3f2018-06-12 08:36:13 -07001146This is enabled with CONFIG_EFI_STUB to boot from both 32-bit and 64-bit
1147UEFI BIOS. U-Boot can also run as an EFI application, with CONFIG_EFI_APP.
Bin Meng73149162018-06-27 20:38:05 -07001148The CONFIG_EFI_LOADER option, where U-Boot provides an EFI environment to
Bin Meng9efeb3f2018-06-12 08:36:13 -07001149the kernel (i.e. replaces UEFI completely but provides the same EFI run-time
Bin Meng73149162018-06-27 20:38:05 -07001150services) is supported too. For example, we can even use 'bootefi' command
1151to load a 'u-boot-payload.efi', see below test logs on QEMU.
1152
1153 => load ide 0 3000000 u-boot-payload.efi
1154 489787 bytes read in 138 ms (3.4 MiB/s)
1155 => bootefi 3000000
1156 Scanning disk ide.blk#0...
1157 Found 2 disks
1158 WARNING: booting without device tree
1159 ## Starting EFI application at 03000000 ...
1160 U-Boot EFI Payload
1161
1162
1163 U-Boot 2018.07-rc2 (Jun 23 2018 - 17:12:58 +0800)
1164
1165 CPU: x86_64, vendor AMD, device 663h
1166 DRAM: 2 GiB
1167 MMC:
1168 Video: 1024x768x32
1169 Model: EFI x86 Payload
1170 Net: e1000: 52:54:00:12:34:56
1171
1172 Warning: e1000#0 using MAC address from ROM
1173 eth0: e1000#0
1174 No controllers found
1175 Hit any key to stop autoboot: 0
Simon Glass007adbc2016-07-17 01:23:45 -06001176
Bin Meng9efeb3f2018-06-12 08:36:13 -07001177See README.u-boot_on_efi and README.uefi for details of EFI support in U-Boot.
Simon Glass007adbc2016-07-17 01:23:45 -06001178
Bin Meng5dad97e2014-12-17 15:50:48 +08001179TODO List
1180---------
Bin Meng5dad97e2014-12-17 15:50:48 +08001181- Audio
1182- Chrome OS verified boot
Bin Meng5dad97e2014-12-17 15:50:48 +08001183
1184References
1185----------
1186[1] http://www.coreboot.org
Bin Meng1ae5b782015-05-07 21:34:12 +08001187[2] http://www.qemu.org
1188[3] http://www.coreboot.org/~stepan/pci8086,0166.rom
1189[4] http://www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-development-kit.html
1190[5] http://www.intel.com/fsp
Bin Meng7aaff9b2015-07-06 16:31:35 +08001191[6] http://www.intel.com/content/www/us/en/secure/intelligent-systems/privileged/e6xx-35-b1-cmc22211.html
1192[7] http://www.ami.com/products/bios-uefi-tools-and-utilities/bios-uefi-utilities/
1193[8] http://en.wikipedia.org/wiki/Microcode
1194[9] http://simplefirmware.org
1195[10] http://www.intel.com/design/archives/processors/pro/docs/242016.htm
Simon Glass7bea5272015-07-27 15:47:31 -06001196[11] https://en.wikipedia.org/wiki/GUID_Partition_Table
1197[12] http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf
1198[13] http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf
Bin Meng2e9ae222016-02-28 23:54:52 -08001199[14] http://www.seabios.org/SeaBIOS
1200[15] doc/device-tree-bindings/misc/intel,irq-router.txt
Bin Meng49d929b2016-05-07 07:46:37 -07001201[16] http://www.acpi.info
1202[17] https://www.acpica.org/downloads