+# SPDX-License-Identifier: GPL-2.0+
#
# Copyright (C) 2014, Simon Glass <sjg@chromium.org>
# Copyright (C) 2014, Bin Meng <bmeng.cn@gmail.com>
-#
-# SPDX-License-Identifier: GPL-2.0+
-#
U-Boot on x86
=============
work with minimal adjustments on other x86 boards since coreboot deals with
most of the low-level details.
+U-Boot is a main bootloader on Intel Edison board.
+
U-Boot also supports booting directly from x86 reset vector, without coreboot.
In this case, known as bare mode, from the fact that it runs on the
'bare metal', U-Boot acts like a BIOS replacement. The following platforms
are supported:
- Bayley Bay CRB
+ - Cherry Hill CRB
- Congatec QEVAL 2.0 & conga-QA3/E3845
- Cougar Canyon 2 CRB
- Crown Bay CRB
- Link (Chromebook Pixel)
- Minnowboard MAX
- Samus (Chromebook Pixel 2015)
- - QEMU x86
+ - QEMU x86 (32-bit & 64-bit)
As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit
Linux kernel as part of a FIT image. It also supports a compressed zImage.
Building U-Boot as a coreboot payload is just like building U-Boot for targets
on other architectures, like below:
-$ make coreboot-x86_defconfig
+$ make coreboot_defconfig
$ make all
-Note this default configuration will build a U-Boot payload for the QEMU board.
-To build a coreboot payload against another board, you can change the build
-configuration during the 'make menuconfig' process.
-
-x86 architecture --->
- ...
- (qemu-x86) Board configuration file
- (qemu-x86_i440fx) Board Device Tree Source (dts) file
- (0x01920000) Board specific Cache-As-RAM (CAR) address
- (0x4000) Board specific Cache-As-RAM (CAR) size
-
-Change the 'Board configuration file' and 'Board Device Tree Source (dts) file'
-to point to a new board. You can also change the Cache-As-RAM (CAR) related
-settings here if the default values do not fit your new board.
-
Build Instructions for U-Boot as BIOS replacement (bare mode)
-------------------------------------------------------------
Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a
little bit tricky, as generally it requires several binary blobs which are not
shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build is
not turned on by default in the U-Boot source tree. Firstly, you need turn it
-on by enabling the ROM build:
-
-$ export BUILD_ROM=y
-
-This tells the Makefile to build u-boot.rom as a target.
-
----
-
-Chromebook Link specific instructions for bare mode:
-
-First, you need the following binary blobs:
-
-* descriptor.bin - Intel flash descriptor
-* me.bin - Intel Management Engine
-* mrc.bin - Memory Reference Code, which sets up SDRAM
-* video ROM - sets up the display
-
-You can get these binary blobs by:
-
-$ git clone http://review.coreboot.org/p/blobs.git
-$ cd blobs
-
-Find the following files:
-
-* ./mainboard/google/link/descriptor.bin
-* ./mainboard/google/link/me.bin
-* ./northbridge/intel/sandybridge/systemagent-r6.bin
-
-The 3rd one should be renamed to mrc.bin.
-As for the video ROM, you can get it here [3] and rename it to vga.bin.
-Make sure all these binary blobs are put in the board directory.
-
-Now you can build U-Boot and obtain u-boot.rom:
-
-$ make chromebook_link_defconfig
-$ make all
-
----
-
-Chromebook Samus (2015 Pixel) instructions for bare mode:
-
-First, you need the following binary blobs:
-
-* descriptor.bin - Intel flash descriptor
-* me.bin - Intel Management Engine
-* mrc.bin - Memory Reference Code, which sets up SDRAM
-* refcode.elf - Additional Reference code
-* vga.bin - video ROM, which sets up the display
-
-If you have a samus you can obtain them from your flash, for example, in
-developer mode on the Chromebook (use Ctrl-Alt-F2 to obtain a terminal and
-log in as 'root'):
-
- cd /tmp
- flashrom -w samus.bin
- scp samus.bin username@ip_address:/path/to/somewhere
-
-If not see the coreboot tree [4] where you can use:
-
- bash crosfirmware.sh samus
-
-to get the image. There is also an 'extract_blobs.sh' scripts that you can use
-on the 'coreboot-Google_Samus.*' file to short-circuit some of the below.
-
-Then 'ifdtool -x samus.bin' on your development machine will produce:
-
- flashregion_0_flashdescriptor.bin
- flashregion_1_bios.bin
- flashregion_2_intel_me.bin
-
-Rename flashregion_0_flashdescriptor.bin to descriptor.bin
-Rename flashregion_2_intel_me.bin to me.bin
-You can ignore flashregion_1_bios.bin - it is not used.
-
-To get the rest, use 'cbfstool samus.bin print':
-
-samus.bin: 8192 kB, bootblocksize 2864, romsize 8388608, offset 0x700000
-alignment: 64 bytes, architecture: x86
-
-Name Offset Type Size
-cmos_layout.bin 0x700000 cmos_layout 1164
-pci8086,0406.rom 0x7004c0 optionrom 65536
-spd.bin 0x710500 (unknown) 4096
-cpu_microcode_blob.bin 0x711540 microcode 70720
-fallback/romstage 0x722a00 stage 54210
-fallback/ramstage 0x72fe00 stage 96382
-config 0x7476c0 raw 6075
-fallback/vboot 0x748ec0 stage 15980
-fallback/refcode 0x74cd80 stage 75578
-fallback/payload 0x75f500 payload 62878
-u-boot.dtb 0x76eb00 (unknown) 5318
-(empty) 0x770000 null 196504
-mrc.bin 0x79ffc0 (unknown) 222876
-(empty) 0x7d66c0 null 167320
-
-You can extract what you need:
-
- cbfstool samus.bin extract -n pci8086,0406.rom -f vga.bin
- cbfstool samus.bin extract -n fallback/refcode -f refcode.rmod
- cbfstool samus.bin extract -n mrc.bin -f mrc.bin
- cbfstool samus.bin extract -n fallback/refcode -f refcode.bin -U
-
-Note that the -U flag is only supported by the latest cbfstool. It unpacks
-and decompresses the stage to produce a coreboot rmodule. This is a simple
-representation of an ELF file. You need the patch "Support decoding a stage
-with compression".
-
-Put all 5 files into board/google/chromebook_samus.
-
-Now you can build U-Boot and obtain u-boot.rom:
-
-$ make chromebook_link_defconfig
-$ make all
-
-If you are using em100, then this command will flash write -Boot:
-
- em100 -s -d filename.rom -c W25Q64CV -r
-
----
-
-Intel Crown Bay specific instructions for bare mode:
-
-U-Boot support of Intel Crown Bay board [4] relies on a binary blob called
-Firmware Support Package [5] to perform all the necessary initialization steps
-as documented in the BIOS Writer Guide, including initialization of the CPU,
-memory controller, chipset and certain bus interfaces.
-
-Download the Intel FSP for Atom E6xx series and Platform Controller Hub EG20T,
-install it on your host and locate the FSP binary blob. Note this platform
-also requires a Chipset Micro Code (CMC) state machine binary to be present in
-the SPI flash where u-boot.rom resides, and this CMC binary blob can be found
-in this FSP package too.
-
-* ./FSP/QUEENSBAY_FSP_GOLD_001_20-DECEMBER-2013.fd
-* ./Microcode/C0_22211.BIN
+on by enabling the ROM build either via an environment variable
-Rename the first one to fsp.bin and second one to cmc.bin and put them in the
-board directory.
+ $ export BUILD_ROM=y
-Note the FSP release version 001 has a bug which could cause random endless
-loop during the FspInit call. This bug was published by Intel although Intel
-did not describe any details. We need manually apply the patch to the FSP
-binary using any hex editor (eg: bvi). Go to the offset 0x1fcd8 of the FSP
-binary, change the following five bytes values from orginally E8 42 FF FF FF
-to B8 00 80 0B 00.
+or via configuration
-As for the video ROM, you need manually extract it from the Intel provided
-BIOS for Crown Bay here [6], using the AMI MMTool [7]. Check PCI option ROM
-ID 8086:4108, extract and save it as vga.bin in the board directory.
+ CONFIG_BUILD_ROM=y
-Now you can build U-Boot and obtain u-boot.rom
-
-$ make crownbay_defconfig
-$ make all
-
----
-
-Intel Cougar Canyon 2 specific instructions for bare mode:
-
-This uses Intel FSP for 3rd generation Intel Core and Intel Celeron processors
-with mobile Intel HM76 and QM77 chipsets platform. Download it from Intel FSP
-website and put the .fd file (CHIEFRIVER_FSP_GOLD_001_09-OCTOBER-2013.fd at the
-time of writing) in the board directory and rename it to fsp.bin.
-
-Now build U-Boot and obtain u-boot.rom
-
-$ make cougarcanyon2_defconfig
-$ make all
-
-The board has two 8MB SPI flashes mounted, which are called SPI-0 and SPI-1 in
-the board manual. The SPI-0 flash should have flash descriptor plus ME firmware
-and SPI-1 flash is used to store U-Boot. For convenience, the complete 8MB SPI-0
-flash image is included in the FSP package (named Rom00_8M_MB_PPT.bin). Program
-this image to the SPI-0 flash according to the board manual just once and we are
-all set. For programming U-Boot we just need to program SPI-1 flash.
-
----
-
-Intel Bay Trail based board instructions for bare mode:
-
-This uses as FSP as with Crown Bay, except it is for the Atom E3800 series.
-Two boards that use this configuration are Bayley Bay and Minnowboard MAX.
-Download this and get the .fd file (BAYTRAIL_FSP_GOLD_003_16-SEP-2014.fd at
-the time of writing). Put it in the corresponding board directory and rename
-it to fsp.bin.
-
-Obtain the VGA RAM (Vga.dat at the time of writing) and put it into the same
-board directory as vga.bin.
-
-You still need two more binary blobs. For Bayley Bay, they can be extracted
-from the sample SPI image provided in the FSP (SPI.bin at the time of writing).
-
- $ ./tools/ifdtool -x BayleyBay/SPI.bin
- $ cp flashregion_0_flashdescriptor.bin board/intel/bayleybay/descriptor.bin
- $ cp flashregion_2_intel_me.bin board/intel/bayleybay/me.bin
-
-For Minnowboard MAX, we can reuse the same ME firmware above, but for flash
-descriptor, we need get that somewhere else, as the one above does not seem to
-work, probably because it is not designed for the Minnowboard MAX. Now download
-the original firmware image for this board from:
-
-http://firmware.intel.com/sites/default/files/2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip
-
-Unzip it:
-
- $ unzip 2014-WW42.4-MinnowBoardMax.73-64-bit.bin_Release.zip
-
-Use ifdtool in the U-Boot tools directory to extract the images from that
-file, for example:
-
- $ ./tools/ifdtool -x MNW2MAX1.X64.0073.R02.1409160934.bin
-
-This will provide the descriptor file - copy this into the correct place:
-
- $ cp flashregion_0_flashdescriptor.bin board/intel/minnowmax/descriptor.bin
-
-Now you can build U-Boot and obtain u-boot.rom
-Note: below are examples/information for Minnowboard MAX.
-
-$ make minnowmax_defconfig
-$ make all
-
-Checksums are as follows (but note that newer versions will invalidate this):
-
-$ md5sum -b board/intel/minnowmax/*.bin
-ffda9a3b94df5b74323afb328d51e6b4 board/intel/minnowmax/descriptor.bin
-69f65b9a580246291d20d08cbef9d7c5 board/intel/minnowmax/fsp.bin
-894a97d371544ec21de9c3e8e1716c4b board/intel/minnowmax/me.bin
-a2588537da387da592a27219d56e9962 board/intel/minnowmax/vga.bin
-
-The ROM image is broken up into these parts:
-
-Offset Description Controlling config
-------------------------------------------------------------
-000000 descriptor.bin Hard-coded to 0 in ifdtool
-001000 me.bin Set by the descriptor
-500000 <spare>
-6ef000 Environment CONFIG_ENV_OFFSET
-6f0000 MRC cache CONFIG_ENABLE_MRC_CACHE
-700000 u-boot-dtb.bin CONFIG_SYS_TEXT_BASE
-790000 vga.bin CONFIG_VGA_BIOS_ADDR
-7c0000 fsp.bin CONFIG_FSP_ADDR
-7f8000 <spare> (depends on size of fsp.bin)
-7ff800 U-Boot 16-bit boot CONFIG_SYS_X86_START16
-
-Overall ROM image size is controlled by CONFIG_ROM_SIZE.
-
----
-
-Intel Galileo instructions for bare mode:
-
-Only one binary blob is needed for Remote Management Unit (RMU) within Intel
-Quark SoC. Not like FSP, U-Boot does not call into the binary. The binary is
-needed by the Quark SoC itself.
-
-You can get the binary blob from Quark Board Support Package from Intel website:
-
-* ./QuarkSocPkg/QuarkNorthCluster/Binary/QuarkMicrocode/RMU.bin
-
-Rename the file and put it to the board directory by:
-
- $ cp RMU.bin board/intel/galileo/rmu.bin
-
-Now you can build U-Boot and obtain u-boot.rom
-
-$ make galileo_defconfig
-$ make all
+Both tell the Makefile to build u-boot.rom as a target.
---
To build u-boot.rom for QEMU x86 targets, just simply run
-$ make qemu-x86_defconfig
+$ make qemu-x86_defconfig (for 32-bit)
+or
+$ make qemu-x86_64_defconfig (for 64-bit)
$ make all
Note this default configuration will build a U-Boot for the QEMU x86 i440FX
Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then,
'zboot' can be used to boot the kernel:
-=> zboot 02000000 - 04000000 1b1ab50
+=> zboot 01000000 - 04000000 1b1ab50
+
+To run 64-bit U-Boot, qemu-system-x86_64 should be used instead, e.g.:
+$ qemu-system-x86_64 -nographic -bios path/to/u-boot.rom
+
+A specific CPU can be specified via the '-cpu' parameter but please make
+sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely
+'-cpu pentium' won't work for obvious reasons that the processor only
+supports 32-bit.
+
+Note 64-bit support is very preliminary at this point. Lots of features
+are missing in the 64-bit world. One notable feature is the VGA console
+support which is currently missing, so that you must specify '-nographic'
+to get 64-bit U-Boot up and running.
CPU Microcode
-------------
You can also bake this behaviour into your build by hard-coding the
environment variables if you add this to minnowmax.h:
-#undef CONFIG_BOOTARGS
#undef CONFIG_BOOTCOMMAND
-
-#define CONFIG_BOOTARGS \
- "root=/dev/sda2 ro"
#define CONFIG_BOOTCOMMAND \
"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; " \
#undef CONFIG_EXTRA_ENV_SETTINGS
#define CONFIG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}"
+and change CONFIG_BOOTARGS value in configs/minnowmax_defconfig to:
+
+CONFIG_BOOTARGS="root=/dev/sda2 ro"
+
Test with SeaBIOS
-----------------
SeaBIOS [14] is an open source implementation of a 16-bit x86 BIOS. It can run
the compiler via "apt-get install iasl" if you are on Ubuntu or download
the source from [17] to compile one by yourself.
-Current ACPI support in U-Boot is not complete. More features will be added
-in the future. The status as of today is:
+Current ACPI support in U-Boot is basically complete. More optional features
+can be added in the future. The status as of today is:
* Support generating RSDT, XSDT, FACS, FADT, MADT, MCFG tables.
* Support one static DSDT table only, compiled by Intel ACPI compiler.
- * Support S0/S5, reboot and shutdown from OS.
+ * Support S0/S3/S4/S5, reboot and shutdown from OS.
* Support booting a pre-installed Ubuntu distribution via 'zboot' command.
* Support installing and booting Ubuntu 14.04 (or above) from U-Boot with
the help of SeaBIOS using legacy interface (non-UEFI mode).
of SeaBIOS using legacy interface (non-UEFI mode).
* Support ACPI interrupts with SCI only.
-Features not supported so far (to make it a complete ACPI solution):
- * S3 (Suspend to RAM), S4 (Suspend to Disk).
-
Features that are optional:
- * ACPI global NVS support. We may need it to simplify ASL code logic if
- utilizing NVS variables. Most likely we will need this sooner or later.
* Dynamic AML bytecodes insertion at run-time. We may need this to support
SSDT table generation and DSDT fix up.
* SMI support. Since U-Boot is a modern bootloader, we don't want to bring
those legacy stuff into U-Boot. ACPI spec allows a system that does not
support SMI (a legacy-free system).
-So far ACPI is enabled on BayTrail based boards. Testing was done by booting
+ACPI was initially enabled on BayTrail based boards. Testing was done by booting
a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and
Windows 8.1/10 to a SATA drive and booting from there is also tested. Most
devices seem to work correctly and the board can respond a reboot/shutdown
command from the OS.
+For other platform boards, ACPI support status can be checked by examining their
+board defconfig files to see if CONFIG_GENERATE_ACPI_TABLE is set to y.
+
+The S3 sleeping state is a low wake latency sleeping state defined by ACPI
+spec where all system context is lost except system memory. To test S3 resume
+with a Linux kernel, simply run "echo mem > /sys/power/state" and kernel will
+put the board to S3 state where the power is off. So when the power button is
+pressed again, U-Boot runs as it does in cold boot and detects the sleeping
+state via ACPI register to see if it is S3, if yes it means we are waking up.
+U-Boot is responsible for restoring the machine state as it is before sleep.
+When everything is done, U-Boot finds out the wakeup vector provided by OSes
+and jump there. To determine whether ACPI S3 resume is supported, check to
+see if CONFIG_HAVE_ACPI_RESUME is set for that specific board.
+
+Note for testing S3 resume with Windows, correct graphics driver must be
+installed for your platform, otherwise you won't find "Sleep" option in
+the "Power" submenu from the Windows start menu.
+
+EFI Support
+-----------
+U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI.
+This is enabled with CONFIG_EFI_STUB to boot from both 32-bit and 64-bit
+UEFI BIOS. U-Boot can also run as an EFI application, with CONFIG_EFI_APP.
+The CONFIG_EFI_LOADER option, where U-Boot provides an EFI environment to
+the kernel (i.e. replaces UEFI completely but provides the same EFI run-time
+services) is supported too. For example, we can even use 'bootefi' command
+to load a 'u-boot-payload.efi', see below test logs on QEMU.
+
+ => load ide 0 3000000 u-boot-payload.efi
+ 489787 bytes read in 138 ms (3.4 MiB/s)
+ => bootefi 3000000
+ Scanning disk ide.blk#0...
+ Found 2 disks
+ WARNING: booting without device tree
+ ## Starting EFI application at 03000000 ...
+ U-Boot EFI Payload
+
+
+ U-Boot 2018.07-rc2 (Jun 23 2018 - 17:12:58 +0800)
+
+ CPU: x86_64, vendor AMD, device 663h
+ DRAM: 2 GiB
+ MMC:
+ Video: 1024x768x32
+ Model: EFI x86 Payload
+ Net: e1000: 52:54:00:12:34:56
+
+ Warning: e1000#0 using MAC address from ROM
+ eth0: e1000#0
+ No controllers found
+ Hit any key to stop autoboot: 0
+
+See README.u-boot_on_efi and README.uefi for details of EFI support in U-Boot.
+
TODO List
---------
- Audio