+# 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
+ - Bayley Bay CRB
+ - Cherry Hill CRB
+ - Congatec QEVAL 2.0 & conga-QA3/E3845
- Cougar Canyon 2 CRB
- Crown Bay CRB
- Galileo
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 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 main bootloader
+------------------------------------------------
+
+Intel Edison instructions:
+
+Simple you can build U-Boot and obtain u-boot.bin
+
+$ make edison_defconfig
+$ make all
+
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:
+on by enabling the ROM build either via an environment variable
+
+ $ export BUILD_ROM=y
-$ export BUILD_ROM=y
+or via configuration
-This tells the Makefile to build u-boot.rom as a target.
+ CONFIG_BUILD_ROM=y
+
+Both tell the Makefile to build u-boot.rom as a target.
---
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.
+all set. For programming U-Boot we just need to program SPI-1 flash. Since the
+default u-boot.rom image for this board is set to 2MB, it should be programmed
+to the last 2MB of the 8MB chip, address range [600000, 7FFFFF].
---
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
+7b0000 vga.bin CONFIG_VGA_BIOS_ADDR
7c0000 fsp.bin CONFIG_FSP_ADDR
7f8000 <spare> (depends on size of fsp.bin)
-7fe000 Environment CONFIG_ENV_OFFSET
7ff800 U-Boot 16-bit boot CONFIG_SYS_X86_START16
Overall ROM image size is controlled by CONFIG_ROM_SIZE.
+Note that the debug version of the FSP is bigger in size. If this version
+is used, CONFIG_FSP_ADDR needs to be configured to 0xfffb0000 instead of
+the default value 0xfffc0000.
+
+---
+
+Intel Cherry Hill specific instructions for bare mode:
+
+This uses Intel FSP for Braswell platform. Download it from Intel FSP website,
+put the .fd file to the board directory and rename it to fsp.bin.
+
+Extract descriptor.bin and me.bin from the original BIOS on the board using
+ifdtool and put them to the board directory as well.
+
+Note the FSP package for Braswell does not ship a traditional legacy VGA BIOS
+image for the integrated graphics device. Instead a new binary called Video
+BIOS Table (VBT) is shipped. Put it to the board directory and rename it to
+vbt.bin if you want graphics support in U-Boot.
+
+Now you can build U-Boot and obtain u-boot.rom
+
+$ make cherryhill_defconfig
+$ make all
+
+An important note for programming u-boot.rom to the on-board SPI flash is that
+you need make sure the SPI flash's 'quad enable' bit in its status register
+matches the settings in the descriptor.bin, otherwise the board won't boot.
+
+For the on-board SPI flash MX25U6435F, this can be done by writing 0x40 to the
+status register by DediProg in: Config > Modify Status Register > Write Status
+Register(s) > Register1 Value(Hex). This is is a one-time change. Once set, it
+persists in SPI flash part regardless of the u-boot.rom image burned.
+
---
Intel Galileo instructions for bare mode:
- Set framebuffer graphics resolution (1280x1024 32k-color (1:5:5))
- Keep VESA framebuffer
+And include coreboot_fb.dtsi in your board's device tree source file, like:
+
+ /include/ "coreboot_fb.dtsi"
+
At present it seems that for Minnowboard Max, coreboot does not pass through
the video information correctly (it always says the resolution is 0x0). This
works correctly for link though.
+Note: coreboot framebuffer driver does not work on QEMU. The reason is unknown
+at this point. Patches are welcome if you figure out anything wrong.
+
Test with QEMU for bare mode
----------------------------
QEMU is a fancy emulator that can enable us to test U-Boot without access to
Multicore is also supported by QEMU via '-smp n' where n is the number of cores
to instantiate. Note, the maximum supported CPU number in QEMU is 255.
-The fw_cfg interface in QEMU also provides information about kernel data, initrd,
-command-line arguments and more. U-Boot supports directly accessing these informtion
-from fw_cfg interface, this saves the time of loading them from hard disk or
-network again, through emulated devices. To use it , simply providing them in
-QEMU command line:
+The fw_cfg interface in QEMU also provides information about kernel data,
+initrd, command-line arguments and more. U-Boot supports directly accessing
+these informtion from fw_cfg interface, which saves the time of loading them
+from hard disk or network again, through emulated devices. To use it , simply
+providing them in QEMU command line:
$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 -kernel /path/to/bzImage
-append 'root=/dev/ram console=ttyS0' -initrd /path/to/initrd -smp 8
Note: -initrd and -smp are both optional
-Then start QEMU, in U-Boot command line use the following U-Boot command to setup kernel:
+Then start QEMU, in U-Boot command line use the following U-Boot command to
+setup kernel:
=> qfw
qfw - QEMU firmware interface
=> qfw load
loading kernel to address 01000000 size 5d9d30 initrd 04000000 size 1b1ab50
-Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then, 'zboot'
-can be used to boot the kernel:
+Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then,
+'zboot' can be used to boot the kernel:
+
+=> zboot 01000000 - 04000000 1b1ab50
+
+Updating U-Boot on Edison
+-------------------------
+By default Intel Edison boards are shipped with preinstalled heavily
+patched U-Boot v2014.04. Though it supports DFU which we may be able to
+use.
+
+1. Prepare u-boot.bin as described in chapter above. You still need one
+more step (if and only if you have original U-Boot), i.e. run the
+following command:
+
+$ truncate -s %4096 u-boot.bin
+
+2. Run your board and interrupt booting to U-Boot console. In the console
+call:
+
+ => run do_force_flash_os
+
+3. Wait for few seconds, it will prepare environment variable and runs
+DFU. Run DFU command from the host system:
+
+$ dfu-util -v -d 8087:0a99 --alt u-boot0 -D u-boot.bin
-=> zboot 02000000 - 04000000 1b1ab50
+4. Return to U-Boot console and following hint. i.e. push Ctrl+C, and
+reset the board:
+
+ => reset
CPU Microcode
-------------
--------------
As an example of how to set up your boot flow with U-Boot, here are
instructions for starting Ubuntu from U-Boot. These instructions have been
-tested on Minnowboard MAX with a SATA driver but are equally applicable on
-other platforms and other media. There are really only four steps and its a
+tested on Minnowboard MAX with a SATA drive but are equally applicable on
+other platforms and other media. There are really only four steps and it's a
very simple script, but a more detailed explanation is provided here for
completeness.
It could also use the grub.cfg file (/efi/ubuntu/grub.cfg) to obtain the
GUID. If you figure these out, please post patches to this README.
-Firstly, you will need Ubunutu installed on an available disk. It should be
+Firstly, you will need Ubuntu installed on an available disk. It should be
possible to make U-Boot start a USB start-up disk but for now let's assume
that you used another boot loader to install Ubuntu.
Loading bzImage at address 100000 (5805728 bytes)
Magic signature found
Initial RAM disk at linear address 0x04000000, size 19215259 bytes
- Kernel command line: "console=ttyS0,115200 root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro"
+ Kernel command line: "root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro"
Starting kernel ...
240,329 ahci
1,422,704 vesa display
-Now the kernel actually starts:
+Now the kernel actually starts: (if you want to examine kernel boot up message
+on the serial console, append "console=ttyS0,115200" to the kernel command line)
[ 0.000000] Initializing cgroup subsys cpuset
[ 0.000000] Initializing cgroup subsys cpu
[ 0.000000] Initializing cgroup subsys cpuacct
[ 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)
- [ 0.000000] Command line: console=ttyS0,115200 root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro
+ [ 0.000000] Command line: root=/dev/disk/by-partuuid/965c59ee-1822-4326-90d2-b02446050059 ro console=ttyS0,115200
It continues for a long time. Along the way you will see it pick up your
ramdisk:
The \ is to tell the shell not to evaluate ${filesize} as part of the setenv
command.
-You will also need to add this to your board configuration file, e.g.
-include/configs/minnowmax.h:
-
- #define CONFIG_BOOTDELAY 2
-
-Now when you reset your board it wait a few seconds (in case you want to
-interrupt) and then should boot straight into Ubuntu.
-
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
This is also tested on Intel Crown Bay board with a PCIe graphics card, booting
SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally.
+If you are using Intel Integrated Graphics Device (IGD) as the primary display
+device on your board, SeaBIOS needs to be patched manually to get its VGA ROM
+loaded and run by SeaBIOS. SeaBIOS locates VGA ROM via the PCI expansion ROM
+register, but IGD device does not have its VGA ROM mapped by this register.
+Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address
+which is unknown to SeaBIOS. An example patch is needed for SeaBIOS below:
+
+diff --git a/src/optionroms.c b/src/optionroms.c
+index 65f7fe0..c7b6f5e 100644
+--- a/src/optionroms.c
++++ b/src/optionroms.c
+@@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources)
+ rom = deploy_romfile(file);
+ else if (RunPCIroms > 1 || (RunPCIroms == 1 && isvga))
+ rom = map_pcirom(pci);
++ if (pci->bdf == pci_to_bdf(0, 2, 0))
++ rom = (struct rom_header *)0xfff90000;
+ if (! rom)
+ // No ROM present.
+ return;
+
+Note: the patch above expects IGD device is at PCI b.d.f 0.2.0 and its VGA ROM
+is at 0xfff90000 which corresponds to CONFIG_VGA_BIOS_ADDR on Minnowboard MAX.
+Change these two accordingly if this is not the case on your board.
Development Flow
----------------
to U-Boot. This should go at the top of each file and list the coreboot
filename where the code originated.
+Debugging ACPI issues with Windows:
+
+Windows might cache system information and only detect ACPI changes if you
+modify the ACPI table versions. So tweak them liberally when debugging ACPI
+issues with Windows.
+
+ACPI Support Status
+-------------------
+Advanced Configuration and Power Interface (ACPI) [16] aims to establish
+industry-standard interfaces enabling OS-directed configuration, power
+management, and thermal management of mobile, desktop, and server platforms.
+
+Linux can boot without ACPI with "acpi=off" command line parameter, but
+with ACPI the kernel gains the capabilities to handle power management.
+For Windows, ACPI is a must-have firmware feature since Windows Vista.
+CONFIG_GENERATE_ACPI_TABLE is the config option to turn on ACPI support in
+U-Boot. This requires Intel ACPI compiler to be installed on your host to
+compile ACPI DSDT table written in ASL format to AML format. You can get
+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 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/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).
+ * Support installing and booting Windows 8.1/10 from U-Boot with the help
+ of SeaBIOS using legacy interface (non-UEFI mode).
+ * Support ACPI interrupts with SCI only.
+
+Features that are optional:
+ * 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).
+
+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.
+
+64-bit Support
+--------------
+U-Boot supports booting a 64-bit kernel directly and is able to change to
+64-bit mode to do so. However, U-Boot itself is currently always built
+in 32-bit mode. Some access to the full memory range is provided with
+arch_phys_memset().
+
+The development work to make U-Boot itself run in 64-bit mode has not yet
+been attempted. The best approach would likely be to build a 32-bit SPL
+image for U-Boot, with CONFIG_SPL_BUILD. This could then handle the early CPU
+init in 16-bit and 32-bit mode, running the FSP and any other binaries that
+are needed. Then it could change to 64-bit model and jump to U-Boot proper.
+
+Given U-Boot's extensive 64-bit support this has not been a high priority,
+but it would be a nice addition.
TODO List
---------
- Audio
- Chrome OS verified boot
-- SMI and ACPI support, to provide platform info and facilities to Linux
+- Building U-Boot to run in 64-bit mode
References
----------
[13] http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf
[14] http://www.seabios.org/SeaBIOS
[15] doc/device-tree-bindings/misc/intel,irq-router.txt
+[16] http://www.acpi.info
+[17] https://www.acpica.org/downloads
projects / u-boot / blobdiff