Documentation/tutorial/part1.md

   1 Tutorial, part 1: Starting from scratch
   2 ===========================================
   3
   4 This tutorial will guide you through the process of setting up a working
   5 coreboot toolchain. In same cases you will find specific instructions for Debian (apt-get),
   6 Fedora (dnf) and Arch Linux (pacman) based package management systems. Use the
   7 instructions according to your system.
   8
   9 Download, configure, and build coreboot
  10 ---------------------------------------
  11
  12 ### Step 1 - Install tools and libraries needed for coreboot
  13     $ sudo apt-get install -y bison build-essential curl flex git gnat libncurses5-dev m4 zlib1g-dev
  14     $ sudo pacman -S base-devel curl git gcc-ada ncurses zlib
  15     $ sudo dnf install git make gcc-gnat flex bison xz bzip2 gcc g++ ncurses-devel wget zlib-devel
  16
  17 ### Step 2 - Download coreboot source tree
  18     $ git clone https://review.coreboot.org/coreboot
  19     $ cd coreboot
  20
  21 ### Step 3 - Build the coreboot toolchain
  22 Please note that this can take a significant amount of time. Use `CPUS=` to
  23 specify number of `make` jobs to run in parallel.
  24
  25 This will list toolchain options and supported architectures:
  26
  27     $ make help_toolchain
  28
  29 Here are some examples:
  30
  31     $ make crossgcc-i386 CPUS=$(nproc)       # build i386 toolchain
  32     $ make crossgcc-aarch64 CPUS=$(nproc)    # build Aarch64 toolchain
  33     $ make crossgcc-riscv CPUS=$(nproc)      # build RISC-V toolchain
  34
  35 Note that the i386 toolchain is currently used for all x86 platforms, including
  36 x86_64.
  37
  38 Also note that you can possibly use your system toolchain, but the results are
  39 not reproducible, and may have issues, so this is not recommended.  See step 5
  40 to use your system toolchain.
  41
  42 ### Step 4 - Build the payload - coreinfo
  43     $ make -C payloads/coreinfo olddefconfig
  44     $ make -C payloads/coreinfo
  45
  46 ### Step 5 - Configure the build
  47
  48 ##### Configure your mainboard
  49     $ make menuconfig
  50        select 'Mainboard' menu
  51        Beside 'Mainboard vendor' should be '(Emulation)'
  52        Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4'
  53        select < Exit >
  54 These should be the default selections, so if anything else was set, run
  55 `make distclean` to remove your old config file and start over.
  56
  57 ##### Optionally use your system toolchain (Again, not recommended)
  58        select 'General Setup' menu
  59        select 'Allow building with any toolchain'
  60        select < Exit >
  61
  62 ##### Select the payload
  63        select 'Payload' menu
  64        select 'Add a Payload'
  65        choose 'An Elf executable payload'
  66        select 'Payload path and filename'
  67        enter 'payloads/coreinfo/build/coreinfo.elf'
  68        select < Exit >
  69        select < Exit >
  70        select < Yes >
  71
  72 ##### Check your configuration (optional step):
  73
  74     $ make savedefconfig
  75     $ cat defconfig
  76
  77 There should only be two lines (or 3 if you're using the system toolchain):
  78
  79     CONFIG_PAYLOAD_ELF=y
  80     CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf"
  81
  82 ### Step 6 - build coreboot
  83     $ make
  84
  85 At the end of the build, you should see:
  86
  87     Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4)
  88
  89 This means your build was successful. The output from the build is in the build
  90 directory. build/coreboot.rom is the full rom file.
  91
  92 Test the image using QEMU
  93 -------------------------
  94
  95 ### Step 7 - Install QEMU
  96     $ sudo apt-get install -y qemu
  97     $ sudo pacman -S qemu
  98     $ sudo dnf install qemu
  99
 100 ### Step 8 - Run QEMU
 101 Start QEMU, and point it to the ROM you just built:
 102
 103     $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio
 104
 105 You should see the serial output of coreboot in the original console window, and
 106 a new window will appear running the coreinfo payload.
 107
 108 Summary
 109 -------
 110
 111 ### Step 1 summary - Install tools and libraries needed for coreboot
 112 Depending on your distribution you have installed the minimum additional
 113 software requirements to continue with downloading and building coreboot.
 114 Not every distribution has the tools, that would be required,
 115 installed by default. In the following we shortly introduce the purpose of the
 116 installed packages:
 117
 118 * `build-essential` or `base-devel` are the basic tools for building software.
 119 * `git` is needed to download coreboot from the coreboot git repository.
 120 * `libncurses5-dev` or `ncurses` is needed to build the menu for 'make menuconfig'
 121 * `m4, bison, curl, flex, zlib1g-dev, gcc, gnat` and `g++` or `clang`
 122 are needed to build the coreboot toolchain. `gcc` and `gnat` have to be
 123 of the same version.
 124
 125 If you started with a different distribution or package management system you
 126 might need to install other packages. Most likely they are named slightly
 127 different. If that is the case for you, we'd like to encourage you to contribute
 128 to the project and submit a pull request with an update for this documentation
 129 for your system.
 130
 131 ### Step 2 summary - Download coreboot source tree
 132 This will download a 'read-only' copy of the coreboot tree. This just means
 133 that if you made changes to the coreboot tree, you couldn't immediately
 134 contribute them back to the community. To pull a copy of coreboot that would
 135 allow you to contribute back, you would first need to sign up for an account on
 136 gerrit.
 137
 138 ### Step 3 summary - Build the coreboot toolchain.
 139 This builds one of the coreboot cross-compiler toolchains for X86 platforms.
 140 Because of the variability of compilers and the other required tools between
 141 the various operating systems that coreboot can be built on, coreboot supplies
 142 and uses its own cross-compiler toolchain to build the binaries that end up as
 143 part of the coreboot ROM. The toolchain provided by the operating system (the
 144 'host toolchain') is used to build various tools that will run on the local
 145 system during the build process.
 146
 147 ### Step 4 summary - Build the payload
 148 To actually do anything useful with coreboot, you need to build a payload to
 149 include into the rom. The idea behind coreboot is that it does the minimum amount
 150 possible before passing control of the machine to a payload. There are various
 151 payloads such as grub or SeaBIOS that are typically used to boot the operating
 152 system. Instead, we used coreinfo, a small demonstration payload that allows the
 153 user to look at various things such as memory and the contents of the coreboot
 154 file system (CBFS) - the pieces that make up the coreboot rom.
 155
 156 ### Step 5 summary - Configure the build
 157 This step configures coreboot's build options using the menuconfig interface to
 158 Kconfig. Kconfig is the same configuration program used by the linux kernel. It
 159 allows you to enable, disable, and change various values to control the coreboot
 160 build process, including which mainboard(motherboard) to use, which toolchain to
 161 use, and how the runtime debug console should be presented and saved.
 162 Anytime you change mainboards in Kconfig, you should always run `make distclean`
 163 before running `make menuconfig`. Due to the way that Kconfig works, values will
 164 be kept from the previous mainboard if you skip the clean step. This leads to a
 165 hybrid configuration which may or may not work as expected.
 166
 167 ### Step 6 summary - Build coreboot
 168 You may notice that a number of other pieces are downloaded at the beginning of
 169 the build process. These are the git submodules used in various coreboot builds.
 170 By default, the _blobs_ submodule is not downloaded. This git submodule may be
 171 required for other builds for microcode or other binaries. To enable downloading
 172 this submodule, select the option "Allow use of binary-only repository" in the
 173 "General Setup" menu of Kconfig
 174 This attempts to build the coreboot rom. The rom file itself ends up in the
 175 build directory as 'coreboot.rom'. At the end of the build process, the build
 176 displayed the contents of the rom file.
 177
 178 ### Step 7 summary - Install QEMU
 179 QEMU is a processor emulator which we can use to show the coreboot boot
 180 process in a virtualised environment.
 181
 182 ### Step 8 summary - Run QEMU
 183 Here's the command line instruction broken down:
 184 * `qemu-system-x86_64`
 185 This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to
 186 ISA bridge.
 187 * `-bios build/coreboot.rom`
 188 Use the coreboot rom image that we just built. If this flag is left out, the
 189 standard SeaBIOS image that comes with QEMU is used.
 190 * `-serial stdio`
 191 Send the serial output to the console. This allows you to view the coreboot
 192 boot log.