X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2FREADME.x86;h=5d712445df5c6222106898713074eda5394cb5ed;hb=f85764cc1f6ab01ffc60dd78de9c4de4cff2b5ce;hp=5fab04491f3b04a43a8a1d37e476e5119a1f2e54;hpb=4e0114d9679173cfe8bfaffb8b4fb4bbf8cdaa10;p=u-boot diff --git a/doc/README.x86 b/doc/README.x86 index 5fab04491f..5d712445df 100644 --- a/doc/README.x86 +++ b/doc/README.x86 @@ -14,15 +14,16 @@ including supported boards, build instructions, todo list, etc. Status ------ U-Boot supports running as a coreboot [1] payload on x86. So far only Link -(Chromebook Pixel) has been tested, but it should work with minimal adjustments -on other x86 boards since coreboot deals with most of the low-level details. +(Chromebook Pixel) and QEMU [2] x86 targets have been tested, but it should +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 and Intel Crown Bay board -support running U-Boot 'bare metal'. +aka raw support or bare support. Currently Link, QEMU x86 targets and all +Intel boards support running U-Boot 'bare metal'. -As for loading 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. +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. Build Instructions ------------------ @@ -32,13 +33,30 @@ on other architectures, like below: $ make coreboot-x86_defconfig $ make all -Building ROM version of U-Boot (hereafter referred to as u-boot.rom) is a +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. + +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 uncommenting the following line in the main U-Boot Makefile: +on by enabling the ROM build: -# ALL-$(CONFIG_X86_RESET_VECTOR) += u-boot.rom +$ export BUILD_ROM=y + +This tells the Makefile to build u-boot.rom as a target. Link-specific instructions: @@ -58,10 +76,10 @@ Find the following files: * ./mainboard/google/link/descriptor.bin * ./mainboard/google/link/me.bin -* ./northbridge/intel/sandybridge/systemagent-ivybridge.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 [2]. +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: @@ -71,8 +89,8 @@ $ make all Intel Crown Bay specific instructions: -U-Boot support of Intel Crown Bay board [3] relies on a binary blob called -Firmware Support Package [4] to perform all the necessary initialization steps +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. @@ -88,17 +106,198 @@ in this FSP package too. Rename the first one to fsp.bin and second one to cmc.bin and put them in the board directory. -Now you can build U-Boot and obtaim u-boot.rom +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. + +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. + +Now you can build U-Boot and obtain u-boot.rom $ make crownbay_defconfig $ make all +Intel Minnowboard Max instructions: + +This uses as FSP as with Crown Bay, except it is for the Atom E3800 series. +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 + +Obtain the VGA RAM (Vga.dat at the time of writing) and put it into the same +directory: board/intel/minnowmax/vga.bin + +You still need two more binary blobs. The first comes from the original +firmware image available 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 + +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 + +$ 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 +700000 u-boot-dtb.bin CONFIG_SYS_TEXT_BASE +790000 vga.bin CONFIG_X86_OPTION_ROM_ADDR +7c0000 fsp.bin CONFIG_FSP_ADDR +7f8000 (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. + + +Intel Galileo instructions: + +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 + +QEMU x86 target instructions: + +To build u-boot.rom for QEMU x86 targets, just simply run + +$ make qemu-x86_defconfig +$ make all + +Note this default configuration will build a U-Boot for the QEMU x86 i440FX +board. To build a U-Boot against QEMU x86 Q35 board, you can change the build +configuration during the 'make menuconfig' process like below: + +Device Tree Control ---> + ... + (qemu-x86_q35) Default Device Tree for DT control + +Test with coreboot +------------------ +For testing U-Boot as the coreboot payload, there are things that need be paid +attention to. coreboot supports loading an ELF executable and a 32-bit plain +binary, as well as other supported payloads. With the default configuration, +U-Boot is set up to use a separate Device Tree Blob (dtb). As of today, the +generated u-boot-dtb.bin needs to be packaged by the cbfstool utility (a tool +provided by coreboot) manually as coreboot's 'make menuconfig' does not provide +this capability yet. The command is as follows: + +# 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 + +Make sure 0x1110000 matches CONFIG_SYS_TEXT_BASE and 0x1110015 matches the +symbol address of _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. + +To enable video you must enable these options in coreboot: + + - Set framebuffer graphics resolution (1280x1024 32k-color (1:5:5)) + - Keep VESA framebuffer + +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. + +Test with QEMU +-------------- +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: + +$ qemu-system-i386 -nographic -bios path/to/u-boot.rom + +This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU +also supports emulating an x86 board with Q35 and ICH9 based chipset, which is +also supported by U-Boot. To instantiate such a machine, call QEMU with: + +$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35 + +Note by default QEMU instantiated boards only have 128 MiB system memory. But +it is enough to have U-Boot boot and function correctly. You can increase the +system memory by pass '-m' parameter to QEMU if you want more memory: + +$ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 + +This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only +supports 3 GiB maximum system memory and reserves the last 1 GiB address space +for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m' +would be 3072. + +QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will +show QEMU's VGA console window. Note this will disable QEMU's serial output. +If you want to check both consoles, use '-serial stdio'. + CPU Microcode ------------- -Modern CPU usually requires a special bit stream called microcode [5] to be +Modern CPUs usually require a special bit stream called microcode [8] to be loaded on the processor after power up in order to function properly. U-Boot has already integrated these as hex dumps in the source tree. +SMP Support +----------- +On a multicore system, U-Boot is executed on the bootstrap processor (BSP). +Additional application processors (AP) can be brought up by U-Boot. In order to +have an SMP kernel to discover all of the available processors, U-Boot needs to +prepare configuration tables which contain the multi-CPUs information before +loading the OS kernel. Currently U-Boot supports generating two types of tables +for SMP, called Simple Firmware Interface (SFI) [9] and Multi-Processor (MP) +[10] tables. The writing of these two tables are controlled by two Kconfig +options GENERATE_SFI_TABLE and GENERATE_MP_TABLE. + Driver Model ------------ x86 has been converted to use driver model for serial and GPIO. @@ -106,13 +305,91 @@ x86 has been converted to use driver model for serial and GPIO. Device Tree ----------- x86 uses device tree to configure the board thus requires CONFIG_OF_CONTROL to -be turned on. Not every device on the board is configured via devie tree, but +be turned on. Not every device on the board is configured via device tree, but more and more devices will be added as time goes by. Check out the directory arch/x86/dts/ for these device tree source files. +Useful Commands +--------------- +In keeping with the U-Boot philosophy of providing functions to check and +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. +iod - Display I/O memory +iow - Write I/O memory +mtrr - List and set the Memory Type Range Registers (MTRR). These are used to + tell the CPU whether memory is cacheable and if so the cache write + mode to use. U-Boot sets up some reasonable values but you can + adjust then with this command. + +Development Flow +---------------- +These notes are for those who want to port U-Boot to a new x86 platform. + +Since x86 CPUs boot from SPI flash, a SPI flash emulator is a good investment. +The Dediprog em100 can be used on Linux. The em100 tool is available here: + + http://review.coreboot.org/p/em100.git + +On Minnowboard Max the following command line can be used: + + sudo em100 -s -p LOW -d u-boot.rom -c W25Q64DW -r + +A suitable clip for connecting over the SPI flash chip is here: + + http://www.dediprog.com/pd/programmer-accessories/EM-TC-8 + +This allows you to override the SPI flash contents for development purposes. +Typically you can write to the em100 in around 1200ms, considerably faster +than programming the real flash device each time. The only important +limitation of the em100 is that it only supports SPI bus speeds up to 20MHz. +This means that images must be set to boot with that speed. This is an +Intel-specific feature - e.g. tools/ifttool has an option to set the SPI +speed in the SPI descriptor region. + +If your chip/board uses an Intel Firmware Support Package (FSP) it is fairly +easy to fit it in. You can follow the Minnowboard Max implementation, for +example. Hopefully you will just need to create new files similar to those +in arch/x86/cpu/baytrail which provide Bay Trail support. + +If you are not using an FSP you have more freedom and more responsibility. +The ivybridge support works this way, although it still uses a ROM for +graphics and still has binary blobs containing Intel code. You should aim to +support all important peripherals on your platform including video and storage. +Use the device tree for configuration where possible. + +For the microcode you can create a suitable device tree file using the +microcode tool: + + ./tools/microcode-tool -d microcode.dat 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 + +These are written to arch/x86/dts/microcode/ by default. + +Note that it is possible to just add the micrcode for your CPU if you know its +model. U-Boot prints this information when it starts + + CPU: x86_64, vendor Intel, device 30673h + +so here we can use the M0130673322 file. + +If you platform can display POST codes on two little 7-segment displays on +the board, then you can use post_code() calls from C or assembler to monitor +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. + TODO List --------- -- MTRR support (for performance) - Audio - Chrome OS verified boot - SMI and ACPI support, to provide platform info and facilities to Linux @@ -120,7 +397,12 @@ TODO List References ---------- [1] http://www.coreboot.org -[2] http://www.coreboot.org/~stepan/pci8086,0166.rom -[3] http://www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-development-kit.html -[4] http://www.intel.com/fsp -[5] http://en.wikipedia.org/wiki/Microcode +[2] http://www.qemu.org +[3] http://www.coreboot.org/~stepan/pci8086,0166.rom +[4] http://www.intel.com/content/www/us/en/embedded/design-tools/evaluation-platforms/atom-e660-eg20t-development-kit.html +[5] http://www.intel.com/fsp +[6] http://www.intel.com/content/www/us/en/secure/intelligent-systems/privileged/e6xx-35-b1-cmc22211.html +[7] http://www.ami.com/products/bios-uefi-tools-and-utilities/bios-uefi-utilities/ +[8] http://en.wikipedia.org/wiki/Microcode +[9] http://simplefirmware.org +[10] http://www.intel.com/design/archives/processors/pro/docs/242016.htm