Documentation/tutorial/part1.md

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