sravan/system76-coreboot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs/tutorial: Wrap the text in part?.md to 72 characters

Browse Source 
Signed-off-by: Martin Roth <gaumless@gmail.com>
Change-Id: I4f0a07b4ab729aafdb4a1149a7617cd34392cf12
Reviewed-on: https://review.coreboot.org/c/coreboot/+/64967
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
This commit is contained in:
Martin Roth
2022-06-04 19:52:42 -06:00
committed by Martin L Roth
parent 25aeaac85b
commit d2c3e26513
3 changed files with 348 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
Documentation/tutorial/part1.md
View File

@@ -2,11 +2,11 @@ Tutorial, part 1: Starting from scratch
===========================================
This tutorial will guide you through the process of setting up a working
coreboot toolchain. In same cases you will find specific instructions for Debian (apt-get),
Fedora (dnf) and Arch Linux (pacman) based package management systems. Use the
instructions according to your system.
coreboot toolchain. In same cases you will find specific instructions
for Debian (apt-get), Fedora (dnf) and Arch Linux (pacman) based package
management systems. Use the instructions according to your system.
** Note: Summaries of each of the steps are at the end of the document. **
**Note: Summaries of each of the steps are at the end of the document.**
Download, configure, and build coreboot
@@ -16,13 +16,15 @@ Download, configure, and build coreboot
### Step 1 - Install tools and libraries needed for coreboot
Debian based distros:
`sudo apt-get install -y bison build-essential curl flex git gnat libncurses5-dev m4 zlib1g-dev`
`sudo apt-get install -y bison build-essential curl flex git gnat`
`libncurses5-dev m4 zlib1g-dev`
Arch based distros:
`sudo pacman -S base-devel curl git gcc-ada ncurses zlib`
Redhat based distros:
`sudo dnf install git make gcc-gnat flex bison xz bzip2 gcc g++ ncurses-devel wget zlib-devel patch`
`sudo dnf install git make gcc-gnat flex bison xz bzip2 gcc g++`
`ncurses-devel wget zlib-devel patch`
### Step 2 - Download coreboot source tree
@@ -36,8 +38,8 @@ cd coreboot
### Step 3 - Build the coreboot toolchain
Please note that this can take a significant amount of time. Use `CPUS=` to
specify number of `make` jobs to run in parallel.
Please note that this can take a significant amount of time. Use `CPUS=`
to specify number of `make` jobs to run in parallel.
This will list toolchain options and supported architectures:
@@ -53,12 +55,12 @@ make crossgcc-aarch64 CPUS=$(nproc) # build Aarch64 toolchain
make crossgcc-riscv CPUS=$(nproc) # build RISC-V toolchain
```
Note that the i386 toolchain is currently used for all x86 platforms, including
x86_64.
Note that the i386 toolchain is currently used for all x86 platforms,
including x86_64.
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.
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
@@ -117,7 +119,8 @@ make savedefconfig
cat defconfig
```
There should only be two lines (or 3 if you're using the system toolchain):
There should only be two lines (or 3 if you're using the system
toolchain):
```Text
CONFIG_PAYLOAD_ELF=y
@@ -134,8 +137,8 @@ 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.
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
@@ -157,8 +160,8 @@ 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.
You should see the serial output of coreboot in the original console
window, and a new window will appear running the coreinfo payload.
Summary
@@ -168,10 +171,10 @@ Summary
### Step 1 summary - Install tools and libraries needed for coreboot
Depending on your distribution you have installed the minimum additional
software requirements to continue with downloading and building coreboot.
Not every distribution has the tools, that would be required,
installed by default. In the following we shortly introduce the purpose of the
installed packages:
software requirements to continue with downloading and building
coreboot. Not every distribution has the tools, that would be required,
installed by default. In the following we shortly introduce the purpose
of the installed packages:
* `build-essential` or `base-devel` are the basic tools for building software.
* `git` is needed to download coreboot from the coreboot git repository.
@@ -180,67 +183,72 @@ installed packages:
are needed to build the coreboot toolchain. `gcc` and `gnat` have to be
of the same version.
If you started with a different distribution or package management system you
might need to install other packages. Most likely they are named slightly
different. If that is the case for you, we'd like to encourage you to contribute
to the project and submit a pull request with an update for this documentation
for your system.
If you started with a different distribution or package management
system you might need to install other packages. Most likely they are
named slightly different. If that is the case for you, we'd like to
encourage you to contribute to the project and submit a pull request
with an update for this documentation for your system.
### 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.
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.
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 into 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 the coreboot
file system (CBFS) - the pieces that make up the coreboot rom.
To actually do anything useful with coreboot, you need to build a
payload to include into 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 the coreboot file
system (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.
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.
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
@@ -253,11 +261,11 @@ process in a virtualised environment.
Here's the command line instruction broken down:
* `qemu-system-x86_64`
This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to
ISA bridge.
This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3
PCI to ISA bridge.
* `-bios build/coreboot.rom`
Use the coreboot rom image that we just built. If this flag is left out, the
standard SeaBIOS image that comes with QEMU is used.
Use the coreboot rom image that we just built. If this flag is left out,
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
boot log.
Send the serial output to the console. This allows you to view the
coreboot boot log.