diff options
Diffstat (limited to 'Documentation/lessons/lesson1.md')
| -rw-r--r-- | Documentation/lessons/lesson1.md | 169 |
1 files changed, 0 insertions, 169 deletions
diff --git a/Documentation/lessons/lesson1.md b/Documentation/lessons/lesson1.md deleted file mode 100644 index bbb3eb5582..0000000000 --- a/Documentation/lessons/lesson1.md +++ /dev/null @@ -1,169 +0,0 @@ -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. |