system76-coreboot/Documentation/lessons/lesson1.md

coreboot Lesson 1: Starting from scratch
========================================

From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for
a very basic build:

Download, configure, and build coreboot
---------------------------------------

### Step 1 - Install tools and libraries needed for coreboot
    $ sudo apt-get install -y bison build-essential curl flex git gnat libncurses5-dev m4 zlib1g-dev

### Step 2 - Download coreboot source tree
    $ git clone https://review.coreboot.org/coreboot
    $ cd coreboot

### Step 3 - Build the coreboot toolchain
Please note that this can take a significant amount of time

    $ make crossgcc-i386 CPUS=$(nproc)

Also note that you can possibly use your system toolchain, but the results are
not reproducible, and may have issues, so this is not recommended.  See step 5
to use your system toolchain.

### Step 4 - Build the payload - coreinfo
    $ make -C payloads/coreinfo olddefconfig
    $ make -C payloads/coreinfo

### Step 5 - Configure the build

##### Configure your mainboard
    $ make menuconfig
       select 'Mainboard' menu
       Beside 'Mainboard vendor' should be '(Emulation)'
       Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4'
       select < Exit >
These should be the default selections, so if anything else was set, run
`make distclean` to remove your old config file and start over.

##### Optionally use your system toolchain (Again, not recommended)
       select 'General Setup' menu
       select 'Allow building with any toolchain'
       select < Exit >

##### Select the payload
       select 'Payload' menu
       select 'Add a Payload'
       choose 'An Elf executable payload'
       select 'Payload path and filename'
       enter 'payloads/coreinfo/build/coreinfo.elf'
       select < Exit >
       select < Exit >
       select < Yes >

##### check your configuration (optional step):

    $ make savedefconfig
    $ cat defconfig

There should only be two lines (or 3 if you're using the system toolchain):

    CONFIG_PAYLOAD_ELF=y
    CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf"

### Step 6 - build coreboot
    $ make

At the end of the build, you should see:

    Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4)

This means your build was successful. The output from the build is in the build
directory. build/coreboot.rom is the full rom file.

Test the image using QEMU
-------------------------

### Step 7 - Install QEMU
    $ sudo apt-get install -y qemu

### Step 8 - Run QEMU
Start QEMU, and point it to the ROM you just built:

    $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio

You should see the serial output of coreboot in the original console window, and
a new window will appear running the coreinfo payload.

Summary
-------

### Step 1 summary - Install tools and libraries needed for coreboot
You installed the minimum additional requirements for ubuntu to download and
build coreboot. Ubuntu already has most of the other tools that would be
required installed by default.

* `build-essential` is the basic tools for doing builds.  It comes pre-installed
on some Ubuntu flavors, and not on others.
* `git` is needed to download coreboot from the coreboot git repository.
* `libncurses5-dev` is needed to build the menu for 'make menuconfig'
* `m4, bison, curl, flex, zlib1g-dev, gcc, gnat` and `g++` or `clang`
are needed to build the coreboot toolchain. `gcc` and `gnat` have to be
of the same version.

If you started with a different distribution, you might need to install many
other items which vary by distribution.

### Step 2 summary - Download coreboot source tree
This will download a 'read-only' copy of the coreboot tree. This just means
that if you made changes to the coreboot tree, you couldn't immediately
contribute them back to the community. To pull a copy of coreboot that would
allow you to contribute back, you would first need to sign up for an account on
gerrit.

### Step 3 summary - Build the coreboot toolchain.
This builds one of the coreboot cross-compiler toolchains for X86 platforms.
Because of the variability of compilers and the other required tools between
the various operating systems that coreboot can be built on, coreboot supplies
and uses its own cross-compiler toolchain to build the binaries that end up as
part of the coreboot ROM. The toolchain provided by the operating system (the
'host toolchain') is used to build various tools that will run on the local
system during the build process.

### Step 4 summary - Build the payload
To actually do anything useful with coreboot, you need to build a payload to
include in the rom. The idea behind coreboot is that it does the minimum amount
possible before passing control of the machine to a payload. There are various
payloads such as grub or SeaBIOS that are typically used to boot the operating
system. Instead, we used coreinfo, a small demonstration payload that allows the
user to look at various things such as memory and the contents of coreboot's
cbfs - the pieces that make up the coreboot rom.

### Step 5 summary - Configure the build
This step configures coreboot's build options using the menuconfig interface to
Kconfig. Kconfig is the same configuration program used by the linux kernel. It
allows you to enable, disable, and change various values to control the coreboot
build process, including which mainboard(motherboard) to use, which toolchain to
use, and how the runtime debug console should be presented and saved.
Anytime you change mainboards in Kconfig, you should always run `make distclean`
before running `make menuconfig`. Due to the way that Kconfig works, values will
be kept from the previous mainboard if you skip the clean step. This leads to a
hybrid configuration which may or may not work as expected.

### Step 6 summary - Build coreboot
You may notice that a number of other pieces are downloaded at the beginning of
the build process. These are the git submodules used in various coreboot builds.
By default, the _blobs_ submodule is not downloaded. This git submodule may be
required for other builds for microcode or other binaries. To enable downloading
this submodule, select the option "Allow use of binary-only repository" in the
"General Setup" menu of Kconfig
This attempts to build the coreboot rom. The rom file itself ends up in the
build directory as 'coreboot.rom'. At the end of the build process, the build
displayed the contents of the rom file.

### Step 7 summary - Install QEMU
QEMU is a processor emulator which we can use to show coreboot

### Step 8 summary - Run QEMU
Here's the command line broken down:
* `qemu-system-x86_64`
This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to
ISA bridge.
* `-bios build/coreboot.rom`
Use the bios rom image that we just built. If this is left off, the standard
SeaBIOS image that comes with QEMU is used.
* `-serial stdio`
Send the serial output to the console. This allows you to view the coreboot
debug output.