<p>Martin Roth has uploaded this change for <strong>review</strong>.</p><p><a href="https://review.coreboot.org/26387">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Documentation: Add lesson1 from the wiki<br><br>Convert the lesson1 document from the wiki to markdown, update it<br>for Ubuntu 18.04, and extend it slightly with new information.<br><br>Change-Id: Ieab60148f8bdd340e4c4c4c1dd7b6ed18fbd6ed7<br>Signed-off-by: Martin Roth <gaumless@gmail.com><br>---<br>A Documentation/Lesson1.md<br>1 file changed, 168 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://review.coreboot.org:29418/coreboot refs/changes/87/26387/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Documentation/Lesson1.md b/Documentation/Lesson1.md</span><br><span>new file mode 100644</span><br><span>index 0000000..0a10ba3</span><br><span>--- /dev/null</span><br><span>+++ b/Documentation/Lesson1.md</span><br><span>@@ -0,0 +1,168 @@</span><br><span style="color: hsl(120, 100%, 40%);">+coreboot lesson 1 - Starting from scratch</span><br><span style="color: hsl(120, 100%, 40%);">+=========================================</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for</span><br><span style="color: hsl(120, 100%, 40%);">+a very basic build:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Download, configure, and build coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+---------------------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 1 - Install tools and libraries needed for coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+ $ sudo apt-get install -y bison build-essential curl flex git gnat-5 libncurses5-dev m4 zlib1g-dev</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 2 - Download coreboot source tree</span><br><span style="color: hsl(120, 100%, 40%);">+ $ git clone https://review.coreboot.org/coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+ $ cd coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 3 - Build the coreboot toolchain</span><br><span style="color: hsl(120, 100%, 40%);">+Please note that this can take a significant amount of time</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ $ make crossgcc-i386 CPUS=$(nproc)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Also note that you can possibly use your system toolchain, but the results are</span><br><span style="color: hsl(120, 100%, 40%);">+not reproducible, and may have issues, so this is not recommended. See step 5</span><br><span style="color: hsl(120, 100%, 40%);">+to use your system toolchain.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 4 - Build the payload - coreinfo</span><br><span style="color: hsl(120, 100%, 40%);">+ $ make -C payloads/coreinfo olddefconfig</span><br><span style="color: hsl(120, 100%, 40%);">+ $ make -C payloads/coreinfo</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 5 - Configure the build</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* ##### Configure your mainboard</span><br><span style="color: hsl(120, 100%, 40%);">+ $ make menuconfig</span><br><span style="color: hsl(120, 100%, 40%);">+ select 'Mainboard' menu</span><br><span style="color: hsl(120, 100%, 40%);">+ Beside 'Mainboard vendor' should be '(Emulation)'</span><br><span style="color: hsl(120, 100%, 40%);">+ Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4'</span><br><span style="color: hsl(120, 100%, 40%);">+ select < Exit ></span><br><span style="color: hsl(120, 100%, 40%);">+These should be the default selections, so if anything else was set, run</span><br><span style="color: hsl(120, 100%, 40%);">+`make distclean` to remove your old config file and start over.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* ##### Optionally use your system toolchain (Again, not recommended)</span><br><span style="color: hsl(120, 100%, 40%);">+ select 'General Setup' menu</span><br><span style="color: hsl(120, 100%, 40%);">+ select 'Allow building with any toolchain'</span><br><span style="color: hsl(120, 100%, 40%);">+ select < Exit ></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* ##### Select the payload</span><br><span style="color: hsl(120, 100%, 40%);">+ select 'Payload' menu</span><br><span style="color: hsl(120, 100%, 40%);">+ select 'Add a Payload'</span><br><span style="color: hsl(120, 100%, 40%);">+ choose 'An Elf executable payload'</span><br><span style="color: hsl(120, 100%, 40%);">+ select 'Payload path and filename'</span><br><span style="color: hsl(120, 100%, 40%);">+ enter 'payloads/coreinfo/build/coreinfo.elf'</span><br><span style="color: hsl(120, 100%, 40%);">+ select < Exit ></span><br><span style="color: hsl(120, 100%, 40%);">+ select < Exit ></span><br><span style="color: hsl(120, 100%, 40%);">+ select < Yes ></span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+##### check your configuration (optional step):</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ $ make savedefconfig</span><br><span style="color: hsl(120, 100%, 40%);">+ $ cat defconfig</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+There should only be two lines (or 3 if you're using the system toolchain):</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ CONFIG_PAYLOAD_ELF=y</span><br><span style="color: hsl(120, 100%, 40%);">+ CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 6 - build coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+ $ make</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+At the end of the build, you should see:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4)</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This means your build was successful. The output from the build is in the build</span><br><span style="color: hsl(120, 100%, 40%);">+directory. build/coreboot.rom is the full rom file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Test the image using QEMU</span><br><span style="color: hsl(120, 100%, 40%);">+-------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 7 - Install QEMU</span><br><span style="color: hsl(120, 100%, 40%);">+ $ sudo apt-get install -y qemu</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 8 - Run QEMU</span><br><span style="color: hsl(120, 100%, 40%);">+Start QEMU, and point it to the ROM you just built:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+You should see the serial output of coreboot in the original console window, and</span><br><span style="color: hsl(120, 100%, 40%);">+a new window will appear running the coreinfo payload.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Summary</span><br><span style="color: hsl(120, 100%, 40%);">+-------</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 1 summary - Install tools and libraries needed for coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+You installed the minimum additional requirements for ubuntu to download and</span><br><span style="color: hsl(120, 100%, 40%);">+build coreboot. Ubuntu already has most of the other tools that would be</span><br><span style="color: hsl(120, 100%, 40%);">+required installed by default.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* `build-essential` is the basic tools for doing builds. It comes pre-installed</span><br><span style="color: hsl(120, 100%, 40%);">+on some Ubuntu flavors, and not on others.</span><br><span style="color: hsl(120, 100%, 40%);">+* `git` is needed to download coreboot from the coreboot git repository.</span><br><span style="color: hsl(120, 100%, 40%);">+* `libncurses5-dev` is needed to build the menu for 'make menuconfig'</span><br><span style="color: hsl(120, 100%, 40%);">+* `m4, bison, curl, flex, gnat-5, zlib1g-dev` are needed to build the coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+toolchain.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+If you started with a different distribution, you might need to install many</span><br><span style="color: hsl(120, 100%, 40%);">+other items which vary by distribution.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 2 summary - Download coreboot source tree</span><br><span style="color: hsl(120, 100%, 40%);">+This will download a 'read-only' copy of the coreboot tree. This just means</span><br><span style="color: hsl(120, 100%, 40%);">+that if you made changes to the coreboot tree, you couldn't immediately</span><br><span style="color: hsl(120, 100%, 40%);">+contribute them back to the community. To pull a copy of coreboot that would</span><br><span style="color: hsl(120, 100%, 40%);">+allow you to contribute back, you would first need to sign up for an account on</span><br><span style="color: hsl(120, 100%, 40%);">+gerrit.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 3 summary - Build the coreboot toolchain.</span><br><span style="color: hsl(120, 100%, 40%);">+This builds one of the coreboot cross-compiler toolchains for X86 platforms.</span><br><span style="color: hsl(120, 100%, 40%);">+Because of the variability of compilers and the other required tools between</span><br><span style="color: hsl(120, 100%, 40%);">+the various operating systems that coreboot can be built on, coreboot supplies</span><br><span style="color: hsl(120, 100%, 40%);">+and uses its own cross-compiler toolchain to build the binaries that end up as</span><br><span style="color: hsl(120, 100%, 40%);">+part of the coreboot ROM. The toolchain provided by the operating system (the</span><br><span style="color: hsl(120, 100%, 40%);">+'host toolchain') is used to build various tools that will run on the local</span><br><span style="color: hsl(120, 100%, 40%);">+system during the build process.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 4 summary - Build the payload</span><br><span style="color: hsl(120, 100%, 40%);">+To actually do anything useful with coreboot, you need to build a payload to</span><br><span style="color: hsl(120, 100%, 40%);">+include in the rom. The idea behind coreboot is that it does the minimum amount</span><br><span style="color: hsl(120, 100%, 40%);">+possible before passing control of the machine to a payload. There are various</span><br><span style="color: hsl(120, 100%, 40%);">+payloads such as grub or SeaBIOS that are typically used to boot the operating</span><br><span style="color: hsl(120, 100%, 40%);">+system. Instead, we used coreinfo, a small demonstration payload that allows the</span><br><span style="color: hsl(120, 100%, 40%);">+user to look at various things such as memory and the contents of coreboot's</span><br><span style="color: hsl(120, 100%, 40%);">+cbfs - the pieces that make up the coreboot rom.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 5 summary - Configure the build</span><br><span style="color: hsl(120, 100%, 40%);">+This step configures coreboot's build options using the menuconfig interface to</span><br><span style="color: hsl(120, 100%, 40%);">+Kconfig. Kconfig is the same configuration program used by the linux kernel. It</span><br><span style="color: hsl(120, 100%, 40%);">+allows you to enable, disable, and change various values to control the coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+build process, including which mainboard(motherboard) to use, which toolchain to</span><br><span style="color: hsl(120, 100%, 40%);">+use, and how the runtime debug console should be presented and saved.</span><br><span style="color: hsl(120, 100%, 40%);">+Anytime you change mainboards in Kconfig, you should always run `make distclean`</span><br><span style="color: hsl(120, 100%, 40%);">+before running `make menuconfig`. Due to the way that Kconfig works, values will</span><br><span style="color: hsl(120, 100%, 40%);">+be kept from the previous mainboard if you skip the clean step. This leads to a</span><br><span style="color: hsl(120, 100%, 40%);">+hybrid configuration which may or may not work as expected.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 6 summary - Build coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+You may notice that a number of other pieces are downloaded at the beginning of</span><br><span style="color: hsl(120, 100%, 40%);">+the build process. These are the git submodules used in various coreboot builds.</span><br><span style="color: hsl(120, 100%, 40%);">+By default, the BLOBS submodule is not downloaded. This git submodule may be</span><br><span style="color: hsl(120, 100%, 40%);">+required for other builds for microcode or other binaries. To enable downloading</span><br><span style="color: hsl(120, 100%, 40%);">+this submodule, select the option "Allow use of binary-only repository" in the</span><br><span style="color: hsl(120, 100%, 40%);">+"General Setup" menu of Kconfig</span><br><span style="color: hsl(120, 100%, 40%);">+This attempts to build the coreboot rom. The rom file itself ends up in the</span><br><span style="color: hsl(120, 100%, 40%);">+build directory as 'coreboot.rom'. At the end of the build process, the build</span><br><span style="color: hsl(120, 100%, 40%);">+displayed the contents of the rom file.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 7 summary - Install QEMU</span><br><span style="color: hsl(120, 100%, 40%);">+QEMU is a processor emulator which we can use to show coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+### Step 8 summary - Run QEMU</span><br><span style="color: hsl(120, 100%, 40%);">+Here's the command line broken down:</span><br><span style="color: hsl(120, 100%, 40%);">+* `qemu-system-x86_64`</span><br><span style="color: hsl(120, 100%, 40%);">+This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to</span><br><span style="color: hsl(120, 100%, 40%);">+ISA bridge.</span><br><span style="color: hsl(120, 100%, 40%);">+* `-bios build/coreboot.rom`</span><br><span style="color: hsl(120, 100%, 40%);">+Use the bios rom image that we just built. If this is left off, the standard</span><br><span style="color: hsl(120, 100%, 40%);">+SeaBIOS image that comes with QEMU is used.</span><br><span style="color: hsl(120, 100%, 40%);">+* `-serial stdio`</span><br><span style="color: hsl(120, 100%, 40%);">+Send the serial output to the console. This allows you to view the coreboot</span><br><span style="color: hsl(120, 100%, 40%);">+debug output.</span><br><span></span><br></pre><p>To view, visit <a href="https://review.coreboot.org/26387">change 26387</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://review.coreboot.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://review.coreboot.org/26387"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: coreboot </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: Ieab60148f8bdd340e4c4c4c1dd7b6ed18fbd6ed7 </div>
<div style="display:none"> Gerrit-Change-Number: 26387 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Martin Roth <martinroth@google.com> </div>