diff options
| -rw-r--r-- | Documentation/Lesson1.md | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/Documentation/Lesson1.md b/Documentation/Lesson1.md new file mode 100644 index 0000000000..0a10ba3723 --- /dev/null +++ b/Documentation/Lesson1.md @@ -0,0 +1,168 @@ +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-5 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, gnat-5, zlib1g-dev` are needed to build the coreboot +toolchain. + +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. |