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. Currently Link, QEMU x86
-targets and all Intel boards support running U-Boot 'bare metal'.
+'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
+ - Galileo
+ - Link (Chromebook Pixel)
+ - Minnowboard MAX
+ - Samus (Chromebook Pixel 2015)
+ - QEMU x86
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.
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
+
+or via configuration
-$ export BUILD_ROM=y
+ CONFIG_BUILD_ROM=y
-This tells the Makefile to build u-boot.rom as a target.
+Both tell the Makefile to build u-boot.rom as a target.
---
---
+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
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.
-=> zboot 02000000 - 04000000 1b1ab50
+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
+
+4. Return to U-Boot console and following hint. i.e. push Ctrl+C, and
+reset the board:
+
+ => reset
CPU Microcode
-------------
Driver Model
------------
-x86 has been converted to use driver model for serial and GPIO.
+x86 has been converted to use driver model for serial, GPIO, SPI, SPI flash,
+keyboard, real-time clock, USB. Video is in progress.
Device Tree
-----------
--------------
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
+in an emulator or natively on x86 hardware with the use of U-Boot. With its
+help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS.
+
+As U-Boot, we have to manually create a table where SeaBIOS gets various system
+information (eg: E820) from. The table unfortunately has to follow the coreboot
+table format as SeaBIOS currently supports booting as a coreboot payload.
+
+To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on.
+Booting SeaBIOS is done via U-Boot's bootelf command, like below:
+
+ => tftp bios.bin.elf;bootelf
+ Using e1000#0 device
+ TFTP from server 10.10.0.100; our IP address is 10.10.0.108
+ ...
+ Bytes transferred = 122124 (1dd0c hex)
+ ## Starting application at 0x000ff06e ...
+ SeaBIOS (version rel-1.9.0)
+ ...
+
+bios.bin.elf is the SeaBIOS image built from SeaBIOS source tree.
+Make sure it is built as follows:
+
+ $ make menuconfig
+
+Inside the "General Features" menu, select "Build for coreboot" as the
+"Build Target". Inside the "Debugging" menu, turn on "Serial port debugging"
+so that we can see something as soon as SeaBIOS boots. Leave other options
+as in their default state. Then,
+
+ $ make
+ ...
+ Total size: 121888 Fixed: 66496 Free: 9184 (used 93.0% of 128KiB rom)
+ Creating out/bios.bin.elf
+
+Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS
+to install/boot a Windows XP OS (below for example command to install Windows).
+
+ # Create a 10G disk.img as the virtual hard disk
+ $ qemu-img create -f qcow2 disk.img 10G
+
+ # Install a Windows XP OS from an ISO image 'winxp.iso'
+ $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512
+
+ # Boot a Windows XP OS installed on the virutal hard disk
+ $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512
+
+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
----------------
During the U-Boot porting, one of the important steps is to write correct PIRQ
routing information in the board device tree. Without it, device drivers in the
Linux kernel won't function correctly due to interrupt is not working. Please
-refer to U-Boot doc [14] for the device tree bindings of Intel interrupt router.
+refer to U-Boot doc [15] for the device tree bindings of Intel interrupt router.
Here we have more details on the intel,pirq-routing property below.
intel,pirq-routing = <
held in reset. For more details, check how they are implemented by the Intel
Galileo board support codes in board/intel/galileo/galileo.c.
+coreboot:
+
+See scripts/coreboot.sed which can assist with porting coreboot code into
+U-Boot drivers. It will not resolve all build errors, but will perform common
+transformations. Remember to add attribution to coreboot for new files added
+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. U-Boot can also run as an EFI
+application, with CONFIG_EFI_APP. The CONFIG_EFI_LOADER option, where U-Booot
+provides an EFI environment to the kernel (i.e. replaces UEFI completely but
+provides the same EFI run-time services) is not currently supported on x86.
+
+See README.efi 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. It also supports (with CONFIG_EFI_STUB) booting from
+both 32-bit and 64-bit UEFI. 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
----------
[11] https://en.wikipedia.org/wiki/GUID_Partition_Table
[12] http://events.linuxfoundation.org/sites/events/files/slides/chromeos_and_diy_vboot_0.pdf
[13] http://events.linuxfoundation.org/sites/events/files/slides/elce-2014.pdf
-[14] doc/device-tree-bindings/misc/intel,irq-router.txt
+[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 / people / ms / u-boot.git / blobdiff