GNUBoot
/
coreboot-kgpe-d16
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs/tutorial: Update markdown for part1 

The tutorial documents were updated from the wiki very early in the
transition to markdown, and the style has changed over time.  This
updates the markdown style to match documents that are being created
now.

Signed-off-by: Martin Roth <gaumless@gmail.com>
Change-Id: I619c04f420042f530335482c30070436f9190865
Reviewed-on: https://review.coreboot.org/c/coreboot/+/64966
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Singer <felixsinger@posteo.net>
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
This commit is contained in:
Martin Roth 2022-06-04 19:11:07 -06:00 committed by Martin L Roth
parent dfdfab71eb
commit 25aeaac85b
1 changed files with 108 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
Documentation/tutorial/part1.md
View File

@ -6,31 +6,52 @@ coreboot toolchain. In same cases you will find specific instructions for Debian
Fedora (dnf) and Arch Linux (pacman) based package management systems. Use the Fedora (dnf) and Arch Linux (pacman) based package management systems. Use the
instructions according to your system. instructions according to your system.
** Note: Summaries of each of the steps are at the end of the document. **
Download, configure, and build coreboot Download, configure, and build coreboot
--------------------------------------- ---------------------------------------
### Step 1 - Install tools and libraries needed for 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
$ sudo pacman -S base-devel curl git gcc-ada ncurses zlib Debian based distros:
$ sudo dnf install git make gcc-gnat flex bison xz bzip2 gcc g++ ncurses-devel wget zlib-devel patch `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`
### Step 2 - Download coreboot source tree ### Step 2 - Download coreboot source tree
$ git clone https://review.coreboot.org/coreboot
$ cd coreboot ```Bash
git clone https://review.coreboot.org/coreboot
cd coreboot
```
### Step 3 - Build the coreboot toolchain ### Step 3 - Build the coreboot toolchain
Please note that this can take a significant amount of time. Use `CPUS=` to Please note that this can take a significant amount of time. Use `CPUS=` to
specify number of `make` jobs to run in parallel. specify number of `make` jobs to run in parallel.
This will list toolchain options and supported architectures: This will list toolchain options and supported architectures:
$ make help_toolchain ```Bash
make help_toolchain
```
Here are some examples: Here are some examples:
$ make crossgcc-i386 CPUS=$(nproc) # build i386 toolchain ```Bash
$ make crossgcc-aarch64 CPUS=$(nproc) # build Aarch64 toolchain make crossgcc-i386 CPUS=$(nproc) # build i386 toolchain
$ make crossgcc-riscv CPUS=$(nproc) # build RISC-V toolchain 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 Note that the i386 toolchain is currently used for all x86 platforms, including
x86_64. x86_64.
@ -39,76 +60,113 @@ 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 not reproducible, and may have issues, so this is not recommended. See step 5
to use your system toolchain. to use your system toolchain.
### Step 4 - Build the payload - coreinfo ### Step 4 - Build the payload - coreinfo
$ make -C payloads/coreinfo olddefconfig
$ make -C payloads/coreinfo ```Bash
make -C payloads/coreinfo olddefconfig
make -C payloads/coreinfo
```
### Step 5 - Configure the build ### Step 5 - Configure the build
##### Configure your mainboard ##### Configure your mainboard
$ make menuconfig
select 'Mainboard' menu ```Bash
Beside 'Mainboard vendor' should be '(Emulation)' make menuconfig
Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4' ```
select < Exit >
Do the next steps in the menu:
```Text
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 These should be the default selections, so if anything else was set, run
`make distclean` to remove your old config file and start over. `make distclean` to remove your old config file and start over.
##### Optionally use your system toolchain (Again, not recommended) ##### Optionally use your system toolchain (Again, not recommended)
select 'General Setup' menu
select 'Allow building with any toolchain' ```Text
select < Exit > select 'General Setup' menu
select 'Allow building with any toolchain'
select < Exit >
```
##### Select the payload ##### Select the payload
select 'Payload' menu
select 'Add a Payload' ```Text
choose 'An Elf executable payload' select 'Payload' menu
select 'Payload path and filename' select 'Add a Payload'
enter 'payloads/coreinfo/build/coreinfo.elf' choose 'An Elf executable payload'
select < Exit > select 'Payload path and filename'
select < Exit > enter 'payloads/coreinfo/build/coreinfo.elf'
select < Yes > select < Exit >
select < Exit >
select < Yes >
```
##### Check your configuration (optional step): ##### Check your configuration (optional step):
$ make savedefconfig ```Bash
$ cat defconfig 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):
CONFIG_PAYLOAD_ELF=y ```Text
CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf" CONFIG_PAYLOAD_ELF=y
CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf"
```
### Step 6 - build coreboot ### Step 6 - build coreboot
$ make
```Bash
make
```
At the end of the build, you should see: At the end of the build, you should see:
Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4) `Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4)``
This means your build was successful. The output from the build is in the build This means your build was successful. The output from the build is in the build
directory. build/coreboot.rom is the full rom file. directory. build/coreboot.rom is the full rom file.
Test the image using QEMU Test the image using QEMU
------------------------- -------------------------
### Step 7 - Install QEMU ### Step 7 - Install QEMU
$ sudo apt-get install -y qemu
$ sudo pacman -S qemu * Debian: `sudo apt-get install -y qemu`
$ sudo dnf install qemu * Arch: `sudo pacman -S qemu`
* Redhat: `sudo dnf install qemu`
### Step 8 - Run QEMU ### Step 8 - Run QEMU
Start QEMU, and point it to the ROM you just built: Start QEMU, and point it to the ROM you just built:
$ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio ```Bash
qemu-system-x86_64 -bios build/coreboot.rom -serial stdio
```
You should see the serial output of coreboot in the original console window, and You should see the serial output of coreboot in the original console window, and
a new window will appear running the coreinfo payload. a new window will appear running the coreinfo payload.
Summary Summary
------- -------
### Step 1 summary - Install tools and libraries needed for coreboot ### Step 1 summary - Install tools and libraries needed for coreboot
Depending on your distribution you have installed the minimum additional Depending on your distribution you have installed the minimum additional
software requirements to continue with downloading and building coreboot. software requirements to continue with downloading and building coreboot.
Not every distribution has the tools, that would be required, Not every distribution has the tools, that would be required,
@ -128,13 +186,16 @@ 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 to the project and submit a pull request with an update for this documentation
for your system. for your system.
### Step 2 summary - Download coreboot source tree ### Step 2 summary - Download coreboot source tree
This will download a 'read-only' copy of the coreboot tree. This just means 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 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 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 allow you to contribute back, you would first need to sign up for an account on
gerrit. gerrit.
### Step 3 summary - Build the coreboot toolchain. ### Step 3 summary - Build the coreboot toolchain.
This builds one of the coreboot cross-compiler toolchains for X86 platforms. This builds one of the coreboot cross-compiler toolchains for X86 platforms.
Because of the variability of compilers and the other required tools between Because of the variability of compilers and the other required tools between
@ -144,7 +205,9 @@ 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 'host toolchain') is used to build various tools that will run on the local
system during the build process. system during the build process.
### Step 4 summary - Build the payload ### Step 4 summary - Build the payload
To actually do anything useful with coreboot, you need to build a payload to 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 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 possible before passing control of the machine to a payload. There are various
@ -153,7 +216,9 @@ 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 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. file system (CBFS) - the pieces that make up the coreboot rom.
### Step 5 summary - Configure the build ### Step 5 summary - Configure the build
This step configures coreboot's build options using the menuconfig interface to 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 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 allows you to enable, disable, and change various values to control the coreboot
@ -164,7 +229,9 @@ 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 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. hybrid configuration which may or may not work as expected.
### Step 6 summary - Build coreboot ### Step 6 summary - Build coreboot
You may notice that a number of other pieces are downloaded at the beginning of 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. 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 By default, the _blobs_ submodule is not downloaded. This git submodule may be
@ -175,11 +242,15 @@ 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 build directory as 'coreboot.rom'. At the end of the build process, the build
displayed the contents of the rom file. displayed the contents of the rom file.
### Step 7 summary - Install QEMU ### Step 7 summary - Install QEMU
QEMU is a processor emulator which we can use to show the coreboot boot QEMU is a processor emulator which we can use to show the coreboot boot
process in a virtualised environment. process in a virtualised environment.
### Step 8 summary - Run QEMU ### Step 8 summary - Run QEMU
Here's the command line instruction broken down: Here's the command line instruction broken down:
* `qemu-system-x86_64` * `qemu-system-x86_64`
This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to