work with minimal adjustments on other x86 boards since coreboot deals with
most of the low-level details.
-U-Boot also supports booting directly from x86 reset vector without coreboot,
-aka raw support or bare support. Currently Link, QEMU x86 targets and all
-Intel boards support running U-Boot 'bare metal'.
+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
+ - 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.
+U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks
+for more details.
-Build Instructions
-------------------
+Build Instructions for U-Boot as coreboot payload
+-------------------------------------------------
Building U-Boot as a coreboot payload is just like building U-Boot for targets
on other architectures, like below:
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
This tells the Makefile to build u-boot.rom as a target.
-Link-specific instructions:
+---
+
+Chromebook Link specific instructions for bare mode:
First, you need the following binary blobs:
$ make chromebook_link_defconfig
$ make all
-Intel Crown Bay specific instructions:
+---
+
+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
$ make crownbay_defconfig
$ make all
-Intel Minnowboard Max instructions:
+---
+
+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 board directory:
-board/intel/minnowmax/fsp.bin
+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
-directory: board/intel/minnowmax/vga.bin
+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
-You still need two more binary blobs. The first comes from the original
-firmware image available from:
+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
$ cp flashregion_0_flashdescriptor.bin board/intel/minnowmax/descriptor.bin
-Then do the same with the sample SPI image provided in the FSP (SPI.bin at
-the time of writing) to obtain the last image. Note that this will also
-produce a flash descriptor file, but it does not seem to work, probably
-because it is not designed for the Minnowmax. That is why you need to get
-the flash descriptor from the original firmware as above.
-
- $ ./tools/ifdtool -x BayleyBay/SPI.bin
- $ cp flashregion_2_intel_me.bin board/intel/minnowmax/me.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
000000 descriptor.bin Hard-coded to 0 in ifdtool
001000 me.bin Set by the descriptor
500000 <spare>
+6f0000 MRC cache CONFIG_ENABLE_MRC_CACHE
700000 u-boot-dtb.bin CONFIG_SYS_TEXT_BASE
-790000 vga.bin CONFIG_X86_OPTION_ROM_ADDR
+790000 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
Overall ROM image size is controlled by CONFIG_ROM_SIZE.
+---
-Intel Galileo instructions:
+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
$ make galileo_defconfig
$ make all
-QEMU x86 target instructions:
+---
+
+QEMU x86 target instructions for bare mode:
To build u-boot.rom for QEMU x86 targets, just simply run
# in the coreboot root directory
$ ./build/util/cbfstool/cbfstool build/coreboot.rom add-flat-binary \
- -f u-boot-dtb.bin -n fallback/payload -c lzma -l 0x1110000 -e 0x1110015
+ -f u-boot-dtb.bin -n fallback/payload -c lzma -l 0x1110000 -e 0x1110000
-Make sure 0x1110000 matches CONFIG_SYS_TEXT_BASE and 0x1110015 matches the
-symbol address of _start (in arch/x86/cpu/start.S).
+Make sure 0x1110000 matches CONFIG_SYS_TEXT_BASE, which is the symbol address
+of _x86boot_start (in arch/x86/cpu/start.S).
If you want to use ELF as the coreboot payload, change U-Boot configuration to
use CONFIG_OF_EMBED instead of CONFIG_OF_SEPARATE.
the video information correctly (it always says the resolution is 0x0). This
works correctly for link though.
-Test with QEMU
---------------
+Test with QEMU for bare mode
+----------------------------
QEMU is a fancy emulator that can enable us to test U-Boot without access to
a real x86 board. Please make sure your QEMU version is 2.3.0 or above test
U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:
If you want to check both consoles, use '-serial stdio'.
Multicore is also supported by QEMU via '-smp n' where n is the number of cores
-to instantiate. Currently the default U-Boot built for QEMU supports 2 cores.
-In order to support more cores, you need add additional cpu nodes in the device
-tree and change CONFIG_MAX_CPUS accordingly.
+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:
+
+$ 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:
+
+ => qfw
+qfw - QEMU firmware interface
+
+Usage:
+qfw <command>
+ - list : print firmware(s) currently loaded
+ - cpus : print online cpu number
+ - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot
+
+=> 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:
+
+=> zboot 02000000 - 04000000 1b1ab50
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
-----------
adjust internal settings, there are several x86-specific commands that may be
useful:
-hob - Display information about Firmware Support Package (FSP) Hand-off
- Block. This is only available on platforms which use FSP, mostly
- Atom.
+fsp - Display information about Intel Firmware Support Package (FSP).
+ This is only available on platforms which use FSP, mostly Atom.
iod - Display I/O memory
iow - Write I/O memory
mtrr - List and set the Memory Type Range Registers (MTRR). These are used to
#undef CONFIG_EXTRA_ENV_SETTINGS
#define CONFIG_EXTRA_ENV_SETTINGS "boot=zboot 03000000 0 04000000 ${filesize}"
+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.
+
Development Flow
----------------
For the microcode you can create a suitable device tree file using the
microcode tool:
- ./tools/microcode-tool -d microcode.dat create <model>
+ ./tools/microcode-tool -d microcode.dat -m <model> create
or if you only have header files and not the full Intel microcode.dat database:
./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \
-H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h \
- create all
+ -m all create
These are written to arch/x86/dts/microcode/ by default.
boot progress. This can be good for debugging.
If not, you can try to get serial working as early as possible. The early
-debug serial port may be useful here. See setup_early_uart() for an example.
+debug serial port may be useful here. See setup_internal_uart() for an example.
+
+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 [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 = <
+ PCI_BDF(0, 2, 0) INTA PIRQA
+ ...
+ >;
+
+As you see each entry has 3 cells. For the first one, we need describe all pci
+devices mounted on the board. For SoC devices, normally there is a chapter on
+the chipset datasheet which lists all the available PCI devices. For example on
+Bay Trail, this is chapter 4.3 (PCI configuration space). For the second one, we
+can get the interrupt pin either from datasheet or hardware via U-Boot shell.
+The reliable source is the hardware as sometimes chipset datasheet is not 100%
+up-to-date. Type 'pci header' plus the device's pci bus/device/function number
+from U-Boot shell below.
+
+ => pci header 0.1e.1
+ vendor ID = 0x8086
+ device ID = 0x0f08
+ ...
+ interrupt line = 0x09
+ interrupt pin = 0x04
+ ...
+
+It shows this PCI device is using INTD pin as it reports 4 in the interrupt pin
+register. Repeat this until you get interrupt pins for all the devices. The last
+cell is the PIRQ line which a particular interrupt pin is mapped to. On Intel
+chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This
+can be changed by registers in LPC bridge. So far Intel FSP does not touch those
+registers so we can write down the PIRQ according to the default mapping rule.
+
+Once we get the PIRQ routing information in the device tree, the interrupt
+allocation and assignment will be done by U-Boot automatically. Now you can
+enable CONFIG_GENERATE_PIRQ_TABLE for testing Linux kernel using i8259 PIC and
+CONFIG_GENERATE_MP_TABLE for testing Linux kernel using local APIC and I/O APIC.
+
+This script might be useful. If you feed it the output of 'pci long' from
+U-Boot then it will generate a device tree fragment with the interrupt
+configuration for each device (note it needs gawk 4.0.0):
+
+ $ cat console_output |awk '/PCI/ {device=$4} /interrupt line/ {line=$4} \
+ /interrupt pin/ {pin = $4; if (pin != "0x00" && pin != "0xff") \
+ {patsplit(device, bdf, "[0-9a-f]+"); \
+ printf "PCI_BDF(%d, %d, %d) INT%c PIRQ%c\n", strtonum("0x" bdf[1]), \
+ strtonum("0x" bdf[2]), bdf[3], strtonum(pin) + 64, 64 + strtonum(pin)}}'
+
+Example output:
+ PCI_BDF(0, 2, 0) INTA PIRQA
+ PCI_BDF(0, 3, 0) INTA PIRQA
+...
+
+Porting Hints
+-------------
+
+Quark-specific considerations:
+
+To port U-Boot to other boards based on the Intel Quark SoC, a few things need
+to be taken care of. The first important part is the Memory Reference Code (MRC)
+parameters. Quark MRC supports memory-down configuration only. All these MRC
+parameters are supplied via the board device tree. To get started, first copy
+the MRC section of arch/x86/dts/galileo.dts to your board's device tree, then
+change these values by consulting board manuals or your hardware vendor.
+Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h.
+The other tricky part is with PCIe. Quark SoC integrates two PCIe root ports,
+but by default they are held in reset after power on. In U-Boot, PCIe
+initialization is properly handled as per Quark's firmware writer guide.
+In your board support codes, you need provide two routines to aid PCIe
+initialization, which are board_assert_perst() and board_deassert_perst().
+The two routines need implement a board-specific mechanism to assert/deassert
+PCIe PERST# pin. Care must be taken that in those routines that any APIs that
+may trigger PCI enumeration process are strictly forbidden, as any access to
+PCIe root port's configuration registers will cause system hang while it is
+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.
+
TODO List
---------
[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] http://www.seabios.org/SeaBIOS
+[15] doc/device-tree-bindings/misc/intel,irq-router.txt
projects / people / ms / u-boot.git / blobdiff