1.. SPDX-License-Identifier: GPL-2.0+ 2.. Copyright (C) 2014, Simon Glass <sjg@chromium.org> 3.. Copyright (C) 2014, Bin Meng <bmeng.cn@gmail.com> 4 5x86 6=== 7 8This document describes the information about U-Boot running on x86 targets, 9including supported boards, build instructions, todo list, etc. 10 11Status 12------ 13U-Boot supports running as a `coreboot`_ payload on x86. So far only Link 14(Chromebook Pixel), Brya (Alder Lake Chromebook) and `QEMU`_ x86 targets have 15been tested, but it should work with minimal adjustments on other x86 boards 16since coreboot deals with most of the low-level details. 17 18U-Boot is a main bootloader on Intel Edison board. 19 20U-Boot also supports booting directly from x86 reset vector, without coreboot. 21In this case, known as bare mode, from the fact that it runs on the 22'bare metal', U-Boot acts like a BIOS replacement. The following platforms 23are supported: 24 25 - Bayley Bay CRB 26 - Cherry Hill CRB 27 - Congatec QEVAL 2.0 & conga-QA3/E3845 28 - Coral (Apollo Lake - Chromebook 2017) 29 - Cougar Canyon 2 CRB 30 - Crown Bay CRB 31 - Galileo 32 - Link (Ivy Bridge - Chromebook Pixel) 33 - Minnowboard MAX 34 - Samus (Broadwell - Chromebook Pixel 2015) 35 - Coral (Apollo Lake Chromebooks circa 2017) 36 - QEMU x86 (32-bit & 64-bit) 37 38As for loading an OS, U-Boot supports directly booting a 32-bit or 64-bit 39Linux kernel as part of a FIT image. It also supports a compressed zImage. 40U-Boot supports loading an x86 VxWorks kernel. Please check README.vxworks 41for more details. Finally, U-Boot can boot Linux distributions with a UEFI 42interface. 43 44Build Instructions for U-Boot as BIOS replacement (bare mode) 45------------------------------------------------------------- 46Building a ROM version of U-Boot (hereafter referred to as u-boot.rom) is a 47little bit tricky, as generally it requires several binary blobs which are not 48shipped in the U-Boot source tree. Due to this reason, the u-boot.rom build may 49print some warnings if required binary blobs (e.g.: FSP) are not present. 50 51CPU Microcode 52------------- 53Modern CPUs usually require a special bit stream called `microcode`_ to be 54loaded on the processor after power up in order to function properly. U-Boot 55has already integrated these as hex dumps in the source tree. 56 57SMP Support 58----------- 59On a multicore system, U-Boot is executed on the bootstrap processor (BSP). 60Additional application processors (AP) can be brought up by U-Boot. In order to 61have an SMP kernel to discover all of the available processors, U-Boot needs to 62prepare configuration tables which contain the multi-CPUs information before 63loading the OS kernel. Currently U-Boot supports generating two types of tables 64for SMP, called Simple Firmware Interface (`SFI`_) and Multi-Processor (`MP`_) 65tables. The writing of these two tables are controlled by two Kconfig 66options GENERATE_SFI_TABLE and GENERATE_MP_TABLE. 67 68Driver Model 69------------ 70x86 has been converted to use driver model for serial, GPIO, SPI, SPI flash, 71keyboard, real-time clock, USB. Video is in progress. 72 73Device Tree 74----------- 75x86 uses device tree to configure the board thus requires CONFIG_OF_CONTROL to 76be turned on. Not every device on the board is configured via device tree, but 77more and more devices will be added as time goes by. Check out the directory 78arch/x86/dts/ for these device tree source files. 79 80Useful Commands 81--------------- 82In keeping with the U-Boot philosophy of providing functions to check and 83adjust internal settings, there are several x86-specific commands that may be 84useful: 85 86fsp 87 Display information about Intel Firmware Support Package (FSP). 88 This is only available on platforms which use FSP, mostly Atom. 89iod 90 Display I/O memory 91iow 92 Write I/O memory 93mtrr 94 List and set the Memory Type Range Registers (MTRR). These are used to 95 tell the CPU whether memory is cacheable and if so the cache write 96 mode to use. U-Boot sets up some reasonable values but you can 97 adjust then with this command. 98 99Booting Ubuntu 100-------------- 101Typically U-Boot boots distributions automatically so long an `CONFIG_BOOTSTD`, 102`CONFIG_BOOTSTD_DEFAULTS` and `CONFIG_EFI_LOADER` are enabled. See 103:doc:`manual_boot` for how to do this manually. 104 105Test with SeaBIOS 106----------------- 107`SeaBIOS`_ is an open source implementation of a 16-bit x86 BIOS. It can run 108in an emulator or natively on x86 hardware with the use of U-Boot. With its 109help, we can boot some OSes that require 16-bit BIOS services like Windows/DOS. 110 111As U-Boot, we have to manually create a table where SeaBIOS gets various system 112information (eg: E820) from. The table unfortunately has to follow the coreboot 113table format as SeaBIOS currently supports booting as a coreboot payload. 114 115To support loading SeaBIOS, U-Boot should be built with CONFIG_SEABIOS on. 116Booting SeaBIOS is done via U-Boot's bootelf command, like below:: 117 118 => tftp bios.bin.elf;bootelf 119 Using e1000#0 device 120 TFTP from server 10.10.0.100; our IP address is 10.10.0.108 121 ... 122 Bytes transferred = 128748 (1f6ec hex) 123 ## Starting application at 0x000fd269 ... 124 SeaBIOS (version rel-1.14.0-0-g155821a) 125 ... 126 127bios.bin.elf is the SeaBIOS image built from SeaBIOS source tree. At the time 128being, SeaBIOS release 1.14.0 has been tested. To build the SeaBIOS image:: 129 130 $ echo -e 'CONFIG_COREBOOT=y\nCONFIG_COREBOOT_FLASH=n\nCONFIG_DEBUG_SERIAL=y\nCONFIG_DEBUG_COREBOOT=n' > .config 131 $ make olddefconfig 132 $ make 133 ... 134 Total size: 128512 Fixed: 69216 Free: 2560 (used 98.0% of 128KiB rom) 135 Creating out/bios.bin.elf 136 137Currently this is tested on QEMU x86 target with U-Boot chain-loading SeaBIOS 138to install/boot a Windows XP OS (below for example command to install Windows). 139 140.. code-block:: none 141 142 # Create a 10G disk.img as the virtual hard disk 143 $ qemu-img create -f qcow2 disk.img 10G 144 145 # Install a Windows XP OS from an ISO image 'winxp.iso' 146 $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -cdrom winxp.iso -smp 2 -m 512 147 148 # Boot a Windows XP OS installed on the virutal hard disk 149 $ qemu-system-i386 -serial stdio -bios u-boot.rom -hda disk.img -smp 2 -m 512 150 151This is also tested on Intel Crown Bay board with a PCIe graphics card, booting 152SeaBIOS then chain-loading a GRUB on a USB drive, then Linux kernel finally. 153 154If you are using Intel Integrated Graphics Device (IGD) as the primary display 155device on your board, SeaBIOS needs to be patched manually to get its VGA ROM 156loaded and run by SeaBIOS. SeaBIOS locates VGA ROM via the PCI expansion ROM 157register, but IGD device does not have its VGA ROM mapped by this register. 158Its VGA ROM is packaged as part of u-boot.rom at a configurable flash address 159which is unknown to SeaBIOS. An example patch is needed for SeaBIOS below: 160 161.. code-block:: none 162 163 diff --git a/src/optionroms.c b/src/optionroms.c 164 index 65f7fe0..c7b6f5e 100644 165 --- a/src/optionroms.c 166 +++ b/src/optionroms.c 167 @@ -324,6 +324,8 @@ init_pcirom(struct pci_device *pci, int isvga, u64 *sources) 168 rom = deploy_romfile(file); 169 else if (RunPCIroms > 1 || (RunPCIroms == 1 && isvga)) 170 rom = map_pcirom(pci); 171 + if (pci->bdf == pci_to_bdf(0, 2, 0)) 172 + rom = (struct rom_header *)0xfff90000; 173 if (! rom) 174 // No ROM present. 175 return; 176 177Note: the patch above expects IGD device is at PCI b.d.f 0.2.0 and its VGA ROM 178is at 0xfff90000 which corresponds to CONFIG_VGA_BIOS_ADDR on Minnowboard MAX. 179Change these two accordingly if this is not the case on your board. 180 181Development Flow 182---------------- 183These notes are for those who want to port U-Boot to a new x86 platform. 184 185Since x86 CPUs boot from SPI flash, a SPI flash emulator is a good investment. 186The Dediprog em100 can be used on Linux. 187 188The em100 tool is available here: http://review.coreboot.org/p/em100.git 189 190On Minnowboard Max the following command line can be used:: 191 192 sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r 193 194A suitable clip for connecting over the SPI flash chip is here: 195http://www.dediprog.com/pd/programmer-accessories/EM-TC-8. 196 197This allows you to override the SPI flash contents for development purposes. 198Typically you can write to the em100 in around 1200ms, considerably faster 199than programming the real flash device each time. The only important 200limitation of the em100 is that it only supports SPI bus speeds up to 20MHz. 201This means that images must be set to boot with that speed. This is an 202Intel-specific feature - e.g. tools/ifttool has an option to set the SPI 203speed in the SPI descriptor region. 204 205If your chip/board uses an Intel Firmware Support Package (FSP) it is fairly 206easy to fit it in. You can follow the Minnowboard Max implementation, for 207example. Hopefully you will just need to create new files similar to those 208in arch/x86/cpu/baytrail which provide Bay Trail support. 209 210If you are not using an FSP you have more freedom and more responsibility. 211The ivybridge support works this way, although it still uses a ROM for 212graphics and still has binary blobs containing Intel code. You should aim to 213support all important peripherals on your platform including video and storage. 214Use the device tree for configuration where possible. 215 216For the microcode you can create a suitable device tree file using the 217microcode tool:: 218 219 ./tools/microcode-tool -d microcode.dat -m <model> create 220 221or if you only have header files and not the full Intel microcode.dat database:: 222 223 ./tools/microcode-tool -H BAY_TRAIL_FSP_KIT/Microcode/M0130673322.h \ 224 -H BAY_TRAIL_FSP_KIT/Microcode/M0130679901.h -m all create 225 226These are written to arch/x86/dts/microcode/ by default. 227 228Note that it is possible to just add the micrcode for your CPU if you know its 229model. U-Boot prints this information when it starts:: 230 231 CPU: x86_64, vendor Intel, device 30673h 232 233so here we can use the M0130673322 file. 234 235If you platform can display POST codes on two little 7-segment displays on 236the board, then you can use post_code() calls from C or assembler to monitor 237boot progress. This can be good for debugging. 238 239If not, you can try to get serial working as early as possible. The early 240debug serial port may be useful here. See setup_internal_uart() for an example. 241 242During the U-Boot porting, one of the important steps is to write correct PIRQ 243routing information in the board device tree. Without it, device drivers in the 244Linux kernel won't function correctly due to interrupt is not working. Please 245refer to U-Boot `doc <doc/device-tree-bindings/misc/intel,irq-router.txt>`_ for 246the device tree bindings of Intel interrupt router. Here we have more details 247on the intel,pirq-routing property below. 248 249.. code-block:: none 250 251 intel,pirq-routing = < 252 PCI_BDF(0, 2, 0) INTA PIRQA 253 ... 254 >; 255 256As you see each entry has 3 cells. For the first one, we need describe all pci 257devices mounted on the board. For SoC devices, normally there is a chapter on 258the chipset datasheet which lists all the available PCI devices. For example on 259Bay Trail, this is chapter 4.3 (PCI configuration space). For the second one, we 260can get the interrupt pin either from datasheet or hardware via U-Boot shell. 261The reliable source is the hardware as sometimes chipset datasheet is not 100% 262up-to-date. Type 'pci header' plus the device's pci bus/device/function number 263from U-Boot shell below:: 264 265 => pci header 0.1e.1 266 vendor ID = 0x8086 267 device ID = 0x0f08 268 ... 269 interrupt line = 0x09 270 interrupt pin = 0x04 271 ... 272 273It shows this PCI device is using INTD pin as it reports 4 in the interrupt pin 274register. Repeat this until you get interrupt pins for all the devices. The last 275cell is the PIRQ line which a particular interrupt pin is mapped to. On Intel 276chipset, the power-up default mapping is INTA/B/C/D maps to PIRQA/B/C/D. This 277can be changed by registers in LPC bridge. So far Intel FSP does not touch those 278registers so we can write down the PIRQ according to the default mapping rule. 279 280Once we get the PIRQ routing information in the device tree, the interrupt 281allocation and assignment will be done by U-Boot automatically. Now you can 282enable CONFIG_GENERATE_PIRQ_TABLE for testing Linux kernel using i8259 PIC and 283CONFIG_GENERATE_MP_TABLE for testing Linux kernel using local APIC and I/O APIC. 284 285This script might be useful. If you feed it the output of 'pci long' from 286U-Boot then it will generate a device tree fragment with the interrupt 287configuration for each device (note it needs gawk 4.0.0):: 288 289 $ cat console_output |awk '/PCI/ {device=$4} /interrupt line/ {line=$4} \ 290 /interrupt pin/ {pin = $4; if (pin != "0x00" && pin != "0xff") \ 291 {patsplit(device, bdf, "[0-9a-f]+"); \ 292 printf "PCI_BDF(%d, %d, %d) INT%c PIRQ%c\n", strtonum("0x" bdf[1]), \ 293 strtonum("0x" bdf[2]), bdf[3], strtonum(pin) + 64, 64 + strtonum(pin)}}' 294 295Example output:: 296 297 PCI_BDF(0, 2, 0) INTA PIRQA 298 PCI_BDF(0, 3, 0) INTA PIRQA 299 ... 300 301Porting Hints 302------------- 303 304Quark-specific considerations 305^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 306 307To port U-Boot to other boards based on the Intel Quark SoC, a few things need 308to be taken care of. The first important part is the Memory Reference Code (MRC) 309parameters. Quark MRC supports memory-down configuration only. All these MRC 310parameters are supplied via the board device tree. To get started, first copy 311the MRC section of arch/x86/dts/galileo.dts to your board's device tree, then 312change these values by consulting board manuals or your hardware vendor. 313Available MRC parameter values are listed in include/dt-bindings/mrc/quark.h. 314The other tricky part is with PCIe. Quark SoC integrates two PCIe root ports, 315but by default they are held in reset after power on. In U-Boot, PCIe 316initialization is properly handled as per Quark's firmware writer guide. 317In your board support codes, you need provide two routines to aid PCIe 318initialization, which are board_assert_perst() and board_deassert_perst(). 319The two routines need implement a board-specific mechanism to assert/deassert 320PCIe PERST# pin. Care must be taken that in those routines that any APIs that 321may trigger PCI enumeration process are strictly forbidden, as any access to 322PCIe root port's configuration registers will cause system hang while it is 323held in reset. For more details, check how they are implemented by the Intel 324Galileo board support codes in board/intel/galileo/galileo.c. 325 326coreboot 327^^^^^^^^ 328 329See scripts/coreboot.sed which can assist with porting coreboot code into 330U-Boot drivers. It will not resolve all build errors, but will perform common 331transformations. Remember to add attribution to coreboot for new files added 332to U-Boot. This should go at the top of each file and list the coreboot 333filename where the code originated. 334 335Debugging ACPI issues with Windows 336^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 337 338Windows might cache system information and only detect ACPI changes if you 339modify the ACPI table versions. So tweak them liberally when debugging ACPI 340issues with Windows. 341 342ACPI Support Status 343------------------- 344Advanced Configuration and Power Interface (`ACPI`_) aims to establish 345industry-standard interfaces enabling OS-directed configuration, power 346management, and thermal management of mobile, desktop, and server platforms. 347 348Linux can boot without ACPI with "acpi=off" command line parameter, but 349with ACPI the kernel gains the capabilities to handle power management. 350For Windows, ACPI is a must-have firmware feature since Windows Vista. 351CONFIG_GENERATE_ACPI_TABLE is the config option to turn on ACPI support in 352U-Boot. This requires Intel ACPI compiler to be installed on your host to 353compile ACPI DSDT table written in ASL format to AML format. You can get 354the compiler via "apt-get install iasl" if you are on Ubuntu or download 355the source from https://www.acpica.org/downloads to compile one by yourself. 356 357Current ACPI support in U-Boot is basically complete. More optional features 358can be added in the future. The status as of today is: 359 360 * Support generating RSDT, XSDT, FACS, FADT, MADT, MCFG tables. 361 * Support one static DSDT table only, compiled by Intel ACPI compiler. 362 * Support S0/S3/S4/S5, reboot and shutdown from OS. 363 * Support booting a pre-installed Ubuntu distribution via 'zboot' command. 364 * Support installing and booting Ubuntu 14.04 (or above) from U-Boot with 365 the help of SeaBIOS using legacy interface (non-UEFI mode). 366 * Support installing and booting Windows 8.1/10 from U-Boot with the help 367 of SeaBIOS using legacy interface (non-UEFI mode). 368 * Support ACPI interrupts with SCI only. 369 370Features that are optional: 371 372 * Dynamic AML bytecodes insertion at run-time. We may need this to support 373 SSDT table generation and DSDT fix up. 374 * SMI support. Since U-Boot is a modern bootloader, we don't want to bring 375 those legacy stuff into U-Boot. ACPI spec allows a system that does not 376 support SMI (a legacy-free system). 377 378ACPI was initially enabled on BayTrail based boards. Testing was done by booting 379a pre-installed Ubuntu 14.04 from a SATA drive. Installing Ubuntu 14.04 and 380Windows 8.1/10 to a SATA drive and booting from there is also tested. Most 381devices seem to work correctly and the board can respond a reboot/shutdown 382command from the OS. 383 384For other platform boards, ACPI support status can be checked by examining their 385board defconfig files to see if CONFIG_GENERATE_ACPI_TABLE is set to y. 386 387The S3 sleeping state is a low wake latency sleeping state defined by ACPI 388spec where all system context is lost except system memory. To test S3 resume 389with a Linux kernel, simply run "echo mem > /sys/power/state" and kernel will 390put the board to S3 state where the power is off. So when the power button is 391pressed again, U-Boot runs as it does in cold boot and detects the sleeping 392state via ACPI register to see if it is S3, if yes it means we are waking up. 393U-Boot is responsible for restoring the machine state as it is before sleep. 394When everything is done, U-Boot finds out the wakeup vector provided by OSes 395and jump there. To determine whether ACPI S3 resume is supported, check to 396see if CONFIG_HAVE_ACPI_RESUME is set for that specific board. 397 398Note for testing S3 resume with Windows, correct graphics driver must be 399installed for your platform, otherwise you won't find "Sleep" option in 400the "Power" submenu from the Windows start menu. 401 402EFI Support 403----------- 404U-Boot supports booting as a 32-bit or 64-bit EFI payload, e.g. with UEFI. 405This is enabled with CONFIG_EFI_STUB to boot from both 32-bit and 64-bit 406UEFI BIOS. U-Boot can also run as an EFI application, with CONFIG_EFI_APP. 407The CONFIG_EFI_LOADER option, where U-Boot provides an EFI environment to 408the kernel (i.e. replaces UEFI completely but provides the same EFI run-time 409services) is supported too. For example, we can even use 'bootefi' command 410to load a 'u-boot-payload.efi', see below test logs on QEMU. 411 412.. code-block:: none 413 414 => load ide 0 3000000 u-boot-payload.efi 415 489787 bytes read in 138 ms (3.4 MiB/s) 416 => bootefi 3000000 417 Scanning disk ide.blk#0... 418 Found 2 disks 419 WARNING: booting without device tree 420 ## Starting EFI application at 03000000 ... 421 U-Boot EFI Payload 422 423 424 U-Boot 2018.07-rc2 (Jun 23 2018 - 17:12:58 +0800) 425 426 CPU: x86_64, vendor AMD, device 663h 427 DRAM: 2 GiB 428 MMC: 429 Video: 1024x768x32 430 Model: EFI x86 Payload 431 Net: e1000: 52:54:00:12:34:56 432 433 Warning: e1000#0 using MAC address from ROM 434 eth0: e1000#0 435 No controllers found 436 Hit any key to stop autoboot: 0 437 438See :doc:`../../develop/uefi/u-boot_on_efi` and :doc:`../../develop/uefi/uefi` 439for details of EFI support in U-Boot. 440 441Chain-loading 442------------- 443U-Boot can be chain-loaded from another bootloader, such as 444:doc:`../../board/coreboot/index` coreboot or 445:doc:`../../board/intel/slimbootloader`. Typically this is done by building for 446targets 'coreboot' or 'slimbootloader'. 447 448For example, at present we have a 'coreboot' target but this runs very 449different code from the bare-metal targets, such as coral. There is very little 450in common between them. 451 452It is useful to be able to boot the same U-Boot on a device, with or without a 453first-stage bootloader. For example, with chromebook_coral, it is helpful for 454testing to be able to boot the same U-Boot (complete with FSP) on bare metal 455and from coreboot. It allows checking of things like CPU speed, comparing 456registers, ACPI tables and the like. 457 458To do this you can use ll_boot_init() in appropriate places to skip init that 459has already been done by the previous stage. This works by setting a 460GD_FLG_NO_LL_INIT flag when U-Boot detects that it is running from another 461bootloader. 462 463With this feature, you can build a bare-metal target and boot it from 464coreboot, for example. 465 466Note that this is a development feature only. It is not intended for use in 467production environments. Also it is not currently part of the automated tests 468so may break in the future. 469 470SMBIOS tables 471------------- 472 473To generate SMBIOS tables in U-Boot, for use by the OS, enable the 474CONFIG_GENERATE_SMBIOS_TABLE option. The easiest way to provide the values to 475use is via the device tree. For details see 476:download:`smbios.txt <../../device-tree-bindings/sysinfo/smbios.txt>`. 477 478TODO List 479--------- 480- Audio 481- Chrome OS verified boot 482 483.. _coreboot: http://www.coreboot.org 484.. _QEMU: http://www.qemu.org 485.. _microcode: http://en.wikipedia.org/wiki/Microcode 486.. _SFI: http://simplefirmware.org 487.. _MP: http://www.intel.com/design/archives/processors/pro/docs/242016.htm 488.. _SeaBIOS: http://www.seabios.org/SeaBIOS 489.. _ACPI: http://www.acpi.info 490