Building Coreboot for Protectli Platforms
Total Page:16
File Type:pdf, Size:1020Kb
Building coreboot for Protectli platforms Step-by-step guide 3MDEB CONTACT ul. Burgaska 9D/10 Piotr Król, 3mdeb CEO 80-287 Gdańsk, Poland +48 880 673 344 TAX ID: PL2530164147 [email protected] Website About Us Introduction This document describes how to build a coreboot image for Protectli platforms using the upstream coreboot repository. Although coreboot is an open-source firmware framework, building firmware for x86 architecture is currently impossible without certain blobs. These blobs consists of: CPU microcode (automatically included during build process) Intel Firmware Support Package - silicon initialization code in binary form require to initialize modern Intel CPU. May be automatically included in coreboot image or an explicitly selected blob file. VGA option ROM - a binary required for BIOS graphics output to display logo or boot menu Preparing environment In order to build coreboot image a Linux operating system is preferred. Additionally a docker container will be used in the build process to ensure all the libraries and utilities have correct versions, the appropriate toolchain is present and the build will proceed without errors. Install Docker for the Linux distribution you are using. You may refer to https://docs.docker.com/engine/install/ for installation process. The build process is also possible on Windows 10 machine. However it requires Pro version to have correct Docker support and it has not been thoroughly validated. If you are experienced enough, you may try Windows. Install git: sudo apt-get install git # or sudo yum install git # or sudo dnf install git . Clone the coreboot repository with its submodules: git clone --recurse-submodules https://review.coreboot.org/coreboot.git . Enter the container and mount the directory with coreboot source code inside the container: docker run --rm -it -v $PWD/coreboot:/home/coreboot/coreboot \ -w /home/coreboot/coreboot coreboot/coreboot-sdk:1.52 /bin/bash -v $PWD/coreboot:/home/coreboot/coreboot mounts the coreboot directory as /home/coreboot/coreboot inside container. -w /home/coreboot/coreboot automatically changes the working directory to the mounted coreboot source. coreboot/coreboot-sdk:1.52 indicates the name of the container to use. If it is not locally present it will be pulled from dockerhub (it may take a while). /bin/bash tells to enter terminal inside the container. The terminal should switch to something similar like coreboot@0a222d9455c8:~/coreboot$. Now the environment is ready Configuring the coreboot If you have set up the environment correctly it is time to select the platform and desired configuration. To do that, follow steps below. Open configuration menu to select platform and options inside container (in my example it is FW4B): coreboot@0a222d9455c8:~/coreboot$ make menuconfig A coreboot configuration menu should display: Go to Mainboard submenu, choose vendor Protectli select the platform you need: Do not touch other settings, otherwise the built image will not be appropriate for flashing on the platform. You may navigate through the menu using key arrows on the keyboard. To enter a submenu press ENTER. To select/deselect an option press SPACE. You may go back to previous menu with ESC. To display a help for given option press "?" (Shift + /). Now let's have a quick look at Chipset submenu (entered from the main menu). For FW2B and FW4B platform there is nothing particular to do. I will just briefly explain few options. Perform MP Initalization by FSP - this option tells coreboot to leave CPU cores initialization to Intel FSP. Typically we leave this option disabled, because we want to have MP initialization under open-source control. Enable SOC debug interface - this option may enable debugging the CPU via Intel DCI or DBC. It is a debugging method over USB 3.0. It requires Intel System Studio to utilize the debug interface. Additionally this option poses a security threat so it should be used by developers for debugging problems with silicon. Leave disabled. Enable VMX for virtualization - enables the virtualization extensions (Intel VT-x). Typically we leave this option as enabled Include CPU microcode in CBFS - this option is very important. By default it tells the coreboot build system to include the microcode update binary from Intel microcode repository submodule. Without microcode update the platform will not boot. If you wish you may include own microcode binary, but be sure that the binary matches the processor on the platform. For the safety better leave this option as is, i.e. Generate from tree. Validate Intel descriptor - this option enables Intel flash descriptor validation. Use with cause as it may make you platform unbootable. Add Intel descriptor.bin file - this option allows to integrate the Intel flash descriptor into the final image. Not needed to deploy coreboot on a platform. Requires extraction of original descriptor from the original platform firmware image. This option also opens a way to include Intel ME firmware to final image. As this is for more advanced users we leave these options as disabled. Protect flash regions - this option allows to select the flash protection, for example to lock the Intel ME region in the image When FW6 is selected as a platform few additional options may appear: Enable Hyperthreading - enables Hyperthreading technology (1 core may have 2 threads) Board can contain Skylake/Kaby Lake - this option tells coreboot build system to include more microcode updates in case platform (or its variants have different CPU series). Leave the default choice. Enable Software Guard Extensions (SGX) if available - as name indicates, it enables Intel SGX secure enclaves Next submenu is Device. Here we can configure the graphics. For FW2B/FW4B in order to have BIOS graphics output to select the boot device one must include an VGA option ROM. In order to do this select: Add a VGA BIOS image and provide the path to the VGA option ROM. The path is relative to coreboot root directory. The blob can be downloaded from 3mdeb cloud: FW2B/FW4B VGA option ROM FW6 VGA option ROM In case of the FW2B and FW4B the VGA PCI device ID should be set to 8086,22b0 so it matches the graphics device identification on the platform. For FW6A it must be 8086,5906 and for FW6B/FW6C 8086,5916. Be sure to use the correct option ROM for the platform and the correct device identification. Additionally there is certain trick for FW2B/FW4B that has to be made to avoid build failure. coreboot expects another VGA option ROM for different stepping of the graphics device. So copy the downloaded vgabios.bin with: cp vgabios.bin vgabios_c0.bin. When VGA BIOS image addition is enabled the field Graphics initialzation will change to None. Since the payload will use the option ROM to initialize graphics, coreboot doesn't need to do it. An alternative option to initialize graphics on FW6 platform is an open-source graphics initialization library called libgfxinit. It can be selected in Graphics initialzation option as Use libgfxinit. The VGA option ROM will no longer be required in such case (although libgfxinit has some limitations). With libgfxinit one should set the desired framebuffer mode. So got Display submenu and change the Framebuffer mode: Legacy VGA text mode will simply give basic text output on the screen from BIOS. Displaying images like logo will be impossible. Linear "high-resolution" framebuffer will enable the graphical mode to display images in BIOS. When Linear framebuffer is enabled one may select the maximum resolution for the graphical display. More about it a little bit later. Another important submenu is the Generic drivers. Enter this submenu from the main menu. The example view of Generic drivers submenu when FW2B/FW4B is selected: Typically there is nothing to do here, but pay attention to the following options: Add Intel FSP binary to flash image - this must be always selected to include FSP blob that initializes the CPU. Otherwise the platform will not boot. Intel FSP binary location in CBFS - this is the location where FSP will be placed in coreboot image. Leave the default value, otherwise FSP will not be executed correctly and the platform will not boot. Use FSP binary from 3rdparty/fsp repo - this option tells coreboot to automatically include FSP binary for the right CPU during build process. Unless you want to use different FSP binary which is appropriate for your platform, leave it enabled. The right FSP binary will be take from official Intel FSP repository mirror. Enable protection on MRC setting - this option will protect the memory training results from overwriting during firmware updates. It may be useful, because these settings allow the platform to boot much faster and avoid retraining (which is time-consuming). The example view of Generic drivers submenu when FW6 is selected: Typically there is nothing to do here, but pay attention to the following options: Use binaries of the Intel FSP repository on GitHub - this option tells coreboot to automatically include FSP binary for the right CPU during build process. Unless you want to use different FSP binary which is appropriate for your platform, leave it enabled. The right FSP binary will be take from official Intel FSP repository mirror. If the option is deselected another options to include different FSP binary will appear, but it is out of scope. Enable protection on MRC setting - this option will protect the memory training results from overwriting during firmware updates. It may be useful, because these settings allow the platform to boot much faster and avoid retraining (which is time-consuming). Another important submenu is Console it controls the debugging output from coreboot. Enter this submenu from main menu. The only one important option worth attention is Default console log level. It controls the verbosity of coreboot booting process.