Documentation: Add lesson1 from the wiki
Convert the lesson1 document from the wiki to markdown, update it for Ubuntu 18.04, and extend it slightly with new information. Change-Id: Ieab60148f8bdd340e4c4c4c1dd7b6ed18fbd6ed7 Signed-off-by: Martin Roth <gaumless@gmail.com> Reviewed-on: https://review.coreboot.org/26387 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Tested-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com> Reviewed-by: Patrick Georgi <pgeorgi@google.com> Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
This commit is contained in:
parent
035ee6a668
commit
0b71cf164b
|
@ -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.
|
Loading…
Reference in New Issue