u-boot/doc/README.x86

5 # SPDX-License-Identifier:	GPL-2.0+
8 U-Boot on x86
11 This document describes the information about U-Boot running on x86 targets,
15 ------
16 U-Boot supports running as a coreboot [1] payload on x86. So far only Link
19 most of the low-level details.
21 U-Boot is a main bootloader on Intel Edison board.
23 U-Boot also supports booting directly from x86 reset vector, without coreboot.
25 'bare metal', U-Boot acts like a BIOS replacement. The following platforms
28    - Bayley Bay CRB
29    - Congatec QEVAL 2.0 & conga-QA3/E3845
30    - Cougar Canyon 2 CRB
31    - Crown Bay CRB
32    - Galileo
33    - Link (Chromebook Pixel)
34    - Minnowboard MAX
35    - Samus (Chromebook Pixel 2015)
36    - QEMU x86
38 As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
40 U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks
43 Build Instructions for U-Boot as coreboot payload
44 -------------------------------------------------
45 Building U-Boot as a coreboot payload is just like building U-Boot for targets
48 $ make coreboot-x86_defconfig
51 Note this default configuration will build a U-Boot payload for the QEMU board.
55 x86 architecture  --->
57 	(qemu-x86) Board configuration file
58 	(qemu-x86_i440fx) Board Device Tree Source (dts) file
59 	(0x01920000) Board specific Cache-As-RAM (CAR) address
60 	(0x4000) Board specific Cache-As-RAM (CAR) size
63 to point to a new board. You can also change the Cache-As-RAM (CAR) related
66 Build Instructions for U-Boot as main bootloader
67 ------------------------------------------------
71 Simple you can build U-Boot and obtain u-boot.bin
76 Build Instructions for U-Boot as BIOS replacement (bare mode)
77 -------------------------------------------------------------
78 Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
80 shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is
81 not turned on by default in the U-Boot source tree. Firstly, you need turn it
86 This tells the Makefile to build u-boot.rom as a target.
88 ---
94 * descriptor.bin - Intel flash descriptor
95 * me.bin - Intel Management Engine
96 * mrc.bin - Memory Reference Code, which sets up SDRAM
97 * video ROM - sets up the display
108 * ./northbridge/intel/sandybridge/systemagent-r6.bin
114 Now you can build U-Boot and obtain u-boot.rom:
119 ---
125 * descriptor.bin - Intel flash descriptor
126 * me.bin - Intel Management Engine
127 * mrc.bin - Memory Reference Code, which sets up SDRAM
128 * refcode.elf - Additional Reference code
129 * vga.bin - video ROM, which sets up the display
132 developer mode on the Chromebook (use Ctrl-Alt-F2 to obtain a terminal and
136    flashrom -w samus.bin
144 on the 'coreboot-Google_Samus.*' file to short-circuit some of the below.
146 Then 'ifdtool -x samus.bin' on your development machine will produce:
154 You can ignore flashregion_1_bios.bin - it is not used.
172 u-boot.dtb                     0x76eb00   (unknown)    5318
179    cbfstool samus.bin extract -n pci8086,0406.rom -f vga.bin
180    cbfstool samus.bin extract -n fallback/refcode -f refcode.rmod
181    cbfstool samus.bin extract -n mrc.bin -f mrc.bin
182    cbfstool samus.bin extract -n fallback/refcode -f refcode.bin -U
184 Note that the -U flag is only supported by the latest cbfstool. It unpacks
191 Now you can build U-Boot and obtain u-boot.rom:
196 If you are using em100, then this command will flash write -Boot:
198    em100 -s -d filename.rom -c W25Q64CV -r
200 ---
204 U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
212 the SPI flash where u-boot.rom resides, and this CMC binary blob can be found
215 * ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd
232 Now you can build U-Boot and obtain u-boot.rom
237 ---
243 website and put the .fd file (CHIEFRIVER_FSP_GOLD_001_09-OCTOBER-2013.fd at the
246 Now build U-Boot and obtain u-boot.rom
251 The board has two 8MB SPI flashes mounted, which are called SPI-0 and SPI-1 in
252 the board manual. The SPI-0 flash should have flash descriptor plus ME firmware
253 and SPI-1 flash is used to store U-Boot. For convenience, the complete 8MB SPI-0
255 this image to the SPI-0 flash according to the board manual just once and we are
256 all set. For programming U-Boot we just need to program SPI-1 flash.
258 ---
264 Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at
274    $ ./tools/ifdtool -x BayleyBay/SPI.bin
283 http://firmware.intel.com/sites/default/files/2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip
287    $ unzip 2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip
289 Use ifdtool in the U-Boot tools directory to extract the images from that
292    $ ./tools/ifdtool -x MNW2MAX1.X64.0073.R02.1409160934.bin
294 This will provide the descriptor file - copy this into the correct place:
298 Now you can build U-Boot and obtain u-boot.rom
306 $ md5sum -b board/intel/minnowmax/*.bin
315 ------------------------------------------------------------
316 000000   descriptor.bin      Hard-coded to 0 in ifdtool
321 700000   u-boot-dtb.bin      CONFIG_SYS_TEXT_BASE
325 7ff800   U-Boot 16-bit boot  CONFIG_SYS_X86_START16
333 ---
338 Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is
349 Now you can build U-Boot and obtain u-boot.rom
354 ---
358 To build u-boot.rom for QEMU x86 targets, just simply run
360 $ make qemu-x86_defconfig
363 Note this default configuration will build a U-Boot for the QEMU x86 i440FX
364 board. To build a U-Boot against QEMU x86 Q35 board, you can change the build
367 Device Tree Control  --->
369 	(qemu-x86_q35) Default Device Tree for DT control
372 ------------------
373 For testing U-Boot as the coreboot payload, there are things that need be paid
374 attention to. coreboot supports loading an ELF executable and a 32-bit plain
376 U-Boot is set up to use a separate Device Tree Blob (dtb). As of today, the
377 generated u-boot-dtb.bin needs to be packaged by the cbfstool utility (a tool
382 $ ./build/util/cbfstool/cbfstool build/coreboot.rom add-flat-binary \
383   -f u-boot-dtb.bin -n fallback/payload -c lzma -l 0x1110000 -e 0x1110000
388 If you want to use ELF as the coreboot payload, change U-Boot configuration to
393    - Set framebuffer graphics resolution (1280x1024 32k-color (1:5:5))
394    - Keep VESA framebuffer
408 ----------------------------
409 QEMU is a fancy emulator that can enable us to test U-Boot without access to
411 U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:
413 $ qemu-system-i386 -nographic -bios path/to/u-boot.rom
417 also supported by U-Boot. To instantiate such a machine, call QEMU with:
419 $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35
422 it is enough to have U-Boot boot and function correctly. You can increase the
423 system memory by pass '-m' parameter to QEMU if you want more memory:
425 $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024
427 This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only
429 for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m'
432 QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will
434 If you want to check both consoles, use '-serial stdio'.
436 Multicore is also supported by QEMU via '-smp n' where n is the number of cores
440 initrd, command-line arguments and more. U-Boot supports directly accessing
445 $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 -kernel /path/to/bzImage
446     -append 'root=/dev/ram console=ttyS0' -initrd /path/to/initrd -smp 8
448 Note: -initrd and -smp are both optional
450 Then start QEMU, in U-Boot command line use the following U-Boot command to
454 qfw - QEMU firmware interface
458     - list                             : print firmware(s) currently loaded
459     - cpus                             : print online cpu number
460     - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot
468 => zboot 01000000 - 04000000 1b1ab50
470 Updating U-Boot on Edison
471 -------------------------
473 patched U-Boot v2014.04. Though it supports DFU which we may be able to
476 1. Prepare u-boot.bin as described in chapter above. You still need one
477 more step (if and only if you have original U-Boot), i.e. run the
480 $ truncate -s %4096 u-boot.bin
482 2. Run your board and interrupt booting to U-Boot console. In the console
490 $ dfu-util -v -d 8087:0a99 --alt u-boot0 -D u-boot.bin
492 4. Return to U-Boot console and following hint. i.e. push Ctrl+C, and
498 -------------
500 loaded on the processor after power up in order to function properly. U-Boot
504 -----------
505 On a multicore system, U-Boot is executed on the bootstrap processor (BSP).
506 Additional application processors (AP) can be brought up by U-Boot. In order to
507 have an SMP kernel to discover all of the available processors, U-Boot needs to
508 prepare configuration tables which contain the multi-CPUs information before
509 loading the OS kernel. Currently U-Boot supports generating two types of tables
510 for SMP, called Simple Firmware Interface (SFI) [9] and Multi-Processor (MP)
515 ------------
517 keyboard, real-time clock, USB. Video is in progress.
520 -----------
527 ---------------
528 In keeping with the U-Boot philosophy of providing functions to check and
529 adjust internal settings, there are several x86-specific commands that may be
532 fsp  - Display information about Intel Firmware Support Package (FSP).
534 iod  - Display I/O memory
535 iow  - Write I/O memory
536 mtrr - List and set the Memory Type Range Registers (MTRR). These are used to
538 	 mode to use. U-Boot sets up some reasonable values but you can
542 --------------
543 As an example of how to set up your boot flow with U-Boot, here are
544 instructions for starting Ubuntu from U-Boot. These instructions have been
550 Note: It is possible to set up U-Boot to boot automatically using syslinux.
555 possible to make U-Boot start a USB start-up disk but for now let's assume
558 Use the U-Boot command line to find the UUID of the partition you want to
563 Partition Map for SCSI device 0  --   Partition Type: EFI
571 	type:	c12a7328-f81f-11d2-ba4b-00a0c93ec93b
572 	guid:	9d02e8e4-4d59-408f-a9b0-fd497bc9291c
575 	type:	0fc63daf-8483-4772-8e79-3d69d8477de4
576 	guid:	965c59ee-1822-4326-90d2-b02446050059
579 	type:	0657fd6d-a4ab-43c4-84e5-0933c84b4f4f
580 	guid:	2c4282bd-1e82-4bcf-a5ff-51dedbf39f17
633             3381262 System.map-3.13.0-32-generic
634             1162712 abi-3.13.0-32-generic
635              165611 config-3.13.0-32-generic
639             5798112 vmlinuz-3.13.0-32-generic
640              165762 config-3.13.0-58-generic
641             1165129 abi-3.13.0-58-generic
642             5823136 vmlinuz-3.13.0-58-generic
643            19215259 initrd.img-3.13.0-58-generic
644             3391763 System.map-3.13.0-58-generic
645             5825048 vmlinuz-3.13.0-58-generic.efi.signed
646            28304443 initrd.img-3.13.0-32-generic
650 self-extracting compressed file mixed with some 'setup' configuration data.
662 but normally this is not needed. The '-58' is used by Ubuntu. Each time they
667 The '.efi.signed' kernel is signed for EFI's secure boot. U-Boot has its own
668 secure boot mechanism - see [12] [13] and cannot read .efi files at present.
670 To boot Ubuntu from U-Boot the steps are as follows:
675    => setenv bootargs root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro
678 by its GUID, using '/dev/disk/by-partuuid/', a Linux path to a 'directory'
685    => ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic
693    => ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic
696 a variable for that. U-Boot sets 'filesize' to the size of the last file it
701 Type 'help zboot' if you want to see what the arguments are. U-Boot on x86 is
703 U-Boot:
709 …Linux kernel version 3.13.0-58-generic (buildd@allspice) #97-Ubuntu SMP Wed Jul 8 02:56:15 UTC 2015
714    Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro"
718 U-Boot prints out some bootstage timing. This is more useful if you put the
740 …-58-generic (buildd@allspice) (gcc version 4.8.2 (Ubuntu 4.8.2-19ubuntu1) ) #97-Ubuntu SMP Wed Jul…
741 …[    0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro co…
746    [    0.000000] RAMDISK: [mem 0x04000000-0x05253fff]
749    [    1.540111] Freeing initrd memory: 18768K (ffff880004000000 - ffff880005254000)
754    Begin: Running /scripts/local-premount ... done.
758    [    4.357243] scsi 1:0:0:0: Direct-Access     ATA      ADATA SP310      5.2  PQ: 0 ANSI: 5
759    [    4.366860] sd 1:0:0:0: [sda] 62533296 512-byte logical blocks: (32.0 GB/29.8 GiB)
765 Linux has found the three partitions (sda1-3). Mercifully it doesn't print out
776 displays the Ubuntu start-up screen) and a lot of 'Starting' messages:
784    setenv bootargs root=UUID=b2aaf743-0418-4d90-94cc-3e6108d7d968 ro
786 …xt2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; ext2load scsi 0:2 04000000 /boot/initrd…
792 You can also bake this behaviour into your build by hard-coding the
797 	"ext2load scsi 0:2 03000000 /boot/vmlinuz-3.13.0-58-generic; " \
798 	"ext2load scsi 0:2 04000000 /boot/initrd.img-3.13.0-58-generic; " \
809 -----------------
810 SeaBIOS [14] is an open source implementation of a 16-bit x86 BIOS. It can run
811 in an emulator or natively on x86 hardware with the use of U-Boot. With its
812 help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS.
814 As U-Boot, we have to manually create a table where SeaBIOS gets various system
818 To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on.
819 Booting SeaBIOS is done via U-Boot's bootelf command, like below:
827    SeaBIOS (version rel-1.9.0)
845 Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS
849    $ qemu-img create -f qcow2 disk.img 10G
852    $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512
855    $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512
858 SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally.
864 Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address
867 diff --git a/src/optionroms.c b/src/optionroms.c
869 --- a/src/optionroms.c
871 @@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources)
875 +    if (pci->bdf == pci_to_bdf(0, 2, 0))
886 ----------------
887 These notes are for those who want to port U-Boot to a new x86 platform.
896    sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r
900    http://www.dediprog.com/pd/programmer-accessories/EM-TC-8
907 Intel-specific feature - e.g. tools/ifttool has an option to set the SPI
924   ./tools/microcode-tool -d microcode.dat -m <model> create
928   ./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \
929 	-H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h \
930 	-m all create
935 model. U-Boot prints this information when it starts
941 If you platform can display POST codes on two little 7-segment displays on
948 During the U-Boot porting, one of the important steps is to write correct PIRQ
951 refer to U-Boot doc [15] for the device tree bindings of Intel interrupt router.
952 Here we have more details on the intel,pirq-routing property below.
954 	intel,pirq-routing = <
955 		PCI_BDF(0, 2, 0) INTA PIRQA
963 can get the interrupt pin either from datasheet or hardware via U-Boot shell.
965 up-to-date. Type 'pci header' plus the device's pci bus/device/function number
966 from U-Boot shell below.
979 chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This
984 allocation and assignment will be done by U-Boot automatically. Now you can
989 U-Boot then it will generate a device tree fragment with the interrupt
994 	{patsplit(device, bdf, "[0-9a-f]+"); \
999    PCI_BDF(0, 2, 0) INTA PIRQA
1000    PCI_BDF(0, 3, 0) INTA PIRQA
1004 -------------
1006 Quark-specific considerations:
1008 To port U-Boot to other boards based on the Intel Quark SoC, a few things need
1010 parameters. Quark MRC supports memory-down configuration only. All these MRC
1014 Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h.
1016 but by default they are held in reset after power on. In U-Boot, PCIe
1020 The two routines need implement a board-specific mechanism to assert/deassert
1030 U-Boot drivers. It will not resolve all build errors, but will perform common
1032 to U-Boot. This should go at the top of each file and list the coreboot
1042 -------------------
1044 industry-standard interfaces enabling OS-directed configuration, power
1049 For Windows, ACPI is a must-have firmware feature since Windows Vista.
1051 U-Boot. This requires Intel ACPI compiler to be installed on your host to
1053 the compiler via "apt-get install iasl" if you are on Ubuntu or download
1056 Current ACPI support in U-Boot is basically complete. More optional features
1062  * Support booting a pre-installed Ubuntu distribution via 'zboot' command.
1063  * Support installing and booting Ubuntu 14.04 (or above) from U-Boot with
1064    the help of SeaBIOS using legacy interface (non-UEFI mode).
1065  * Support installing and booting Windows 8.1/10 from U-Boot with the help
1066    of SeaBIOS using legacy interface (non-UEFI mode).
1067  * Support ACPI interrupts with SCI only.
1070  * Dynamic AML bytecodes insertion at run-time. We may need this to support
1072  * SMI support. Since U-Boot is a modern bootloader, we don't want to bring
1073    those legacy stuff into U-Boot. ACPI spec allows a system that does not
1074    support SMI (a legacy-free system).
1077 a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and
1089 pressed again, U-Boot runs as it does in cold boot and detects the sleeping
1091 U-Boot is responsible for restoring the machine state as it is before sleep.
1092 When everything is done, U-Boot finds out the wakeup vector provided by OSes
1101 -----------
1102 U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI.
1103 This is enabled with CONFIG_EFI_STUB. U-Boot can also run as an EFI
1104 application, with CONFIG_EFI_APP. The CONFIG_EFI_LOADER option, where U-Booot
1106 provides the same EFI run-time services) is not currently supported on x86.
1108 See README.efi for details of EFI support in U-Boot.
1110 64-bit Support
1111 --------------
1112 U-Boot supports booting a 64-bit kernel directly and is able to change to
1113 64-bit mode to do so. It also supports (with CONFIG_EFI_STUB) booting from
1114 both 32-bit and 64-bit UEFI. However, U-Boot itself is currently always built
1115 in 32-bit mode. Some access to the full memory range is provided with
1118 The development work to make U-Boot itself run in 64-bit mode has not yet
1119 been attempted. The best approach would likely be to build a 32-bit SPL
1120 image for U-Boot, with CONFIG_SPL_BUILD. This could then handle the early CPU
1121 init in 16-bit and 32-bit mode, running the FSP and any other binaries that
1122 are needed. Then it could change to 64-bit model and jump to U-Boot proper.
1124 Given U-Boot's extensive 64-bit support this has not been a high priority,
1128 ---------
1129 - Audio
1130 - Chrome OS verified boot
1131 - Building U-Boot to run in 64-bit mode
1134 ----------
1138 …/www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-develo…
1140 [6] http://www.intel.com/content/www/us/en/secure/intelligent-systems/privileged/e6xx-35-b1-cmc2221…
1141 [7] http://www.ami.com/products/bios-uefi-tools-and-utilities/bios-uefi-utilities/
1147 [13] http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf
1149 [15] doc/device-tree-bindings/misc/intel,irq-router.txt