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