141 lines
5.8 KiB
Markdown
141 lines
5.8 KiB
Markdown
---
|
|
title: Porting Guide
|
|
...
|
|
|
|
This guide is intended for those with very little knowledge of firmware
|
|
in general and coreboot in particular.
|
|
Most boards in coreboot can be quite easily ported to libreboot.
|
|
You don't need any knowledge of a particular programming language or
|
|
technology in general to port a board.
|
|
If you want to make more major contributions to the build system,
|
|
please read the [main maintenance page.](/docs/maintain/index.html)
|
|
|
|
You will certainly need flashing equipment if you wish to follow this guide.
|
|
See the [flashing guide](/docs/install/spi.html) to find out what you'll need.
|
|
|
|
Coreboot is replacement firmware for the firmware chips on the printed
|
|
circuit board (PCB) of the machine in question.
|
|
Libreboot is a *distribution* of Coreboot.
|
|
You may be used to referring to your machine as *machine, device, laptop*
|
|
or it's name (ex: thinkpad t420).
|
|
Because we're targeting chips on the PCB, we refer to all of the above terms
|
|
synonymously as `board.`
|
|
The rest of this article will refer to the board you wish to port to
|
|
libreboot as `board.`
|
|
|
|
If `board` is not supported in coreboot then you need to start there first.
|
|
Libreboot developers will generally not port new boards to coreboot on request.
|
|
If you're not sure whether your board is in coreboot check the [coreboot table of hardware.](https://coreboot.org/status/board-status.html)
|
|
|
|
If you have determined that `board` is supported by coreboot, but is not
|
|
supported by libreboot, then follow the rest of this guide to try to port it yourself.
|
|
If you're still unable to port the board, or anything in this guide is
|
|
unclear, then contact libreboot developers.
|
|
The best way to get in touch is via [libreboot irc.](/contact.html#irc-chatroom)
|
|
|
|
Cloning lbmk
|
|
============
|
|
|
|
Before you try to get any work done, you'll need to clone the lbmk (libreboot make)
|
|
project.
|
|
To do so, you'll need to have git installed on your machine. You can then clone
|
|
the project.
|
|
|
|
git clone https://codeberg.org/libreboot/lbmk
|
|
|
|
If you want more information on building lbmk see [the build instructions.](/docs/build/index.html)
|
|
|
|
Coreboot Config
|
|
===============
|
|
|
|
Coreboot payloads (GRUB, Seabios, etc) are built separately.
|
|
You therefore only need to focus on the coreboot config(s) for `board.`
|
|
All of these configs are stored under resources/coreboot/`board`
|
|
|
|
The easiest way to start a new configuration for a given board is to copy an existing
|
|
configuration and make the necessary modifications.
|
|
For example, if one wanted to port the t420s, then the t420 config would be an excellent
|
|
starting point.
|
|
|
|
cp -r resources/coreboot/t420_12mb/ resources/coreboot/t420s_12mb
|
|
|
|
You can then easily modify the existing coreboot configs for you board via lbmk.
|
|
|
|
./modify coreboot configs t420s_12mb
|
|
|
|
This script will provide a curses interface through which you can easily modify the
|
|
necessary variables and settings.
|
|
The most important thing to change is `Mainboard.`
|
|
You must make sure that the mainboard definition in this config matches `board.`
|
|
For example, you would want to change lenovo/t420 to lenovo/t420s.
|
|
Selecting `exit` in the curses interface will prompt you to ask if you want to save your
|
|
changes, make sure to answer yes.
|
|
Note that you will generally have to go through this process twice, since there is
|
|
a corebootfb and txtmode config for each board (the script will handle this for you).
|
|
|
|
Now you can build and test the rom for `board.`
|
|
Once you have finished this, you can try flashing the resulting rom to your board as a test.
|
|
|
|
./build boot roms t420s_12mb
|
|
|
|
If you try to flash this rom and it fails, then there are two probable reasons:
|
|
|
|
1) CBFS size or ROM size is wrong
|
|
2) The blobs are incompatible
|
|
|
|
Solutions to these problems follow in the proceeding sections.
|
|
|
|
Wrong CBFS and or ROM size
|
|
==========================
|
|
|
|
Different boards have different flash chip setups.
|
|
Generally, you have one or two flash chips with a combined size of 4-16MB.
|
|
Thankfully, flashrom will let you know the size of the flash chip you're flashing.
|
|
For example: when flashing an X230, you'll see that one chip is 8192, and the other is 4096.
|
|
The total rom size should therefore be set as 12MB.
|
|
|
|
The CBFS size depends directly on the size of the flash chip selected.
|
|
Make sure that your CBFS size is not larger than the maximum for your board.
|
|
CBFS sizes are stated as hex values, here is a table showing the correct maximums
|
|
for various rom sizes.
|
|
|
|
| ROM Size | CBFS size |
|
|
|:--------:|:---------:|
|
|
| 8MB | 0x7E0000 |
|
|
| 12MB | 0xBE0000 |
|
|
| 16MB | 0xFE0000 |
|
|
|
|
Obtaining Blobs
|
|
===============
|
|
|
|
The easiest way to see if your coreboot config is valid is to extract the required
|
|
binary blobs from a backup of your vendor rom.
|
|
You'll need a unified rom for dual chip setups; see [the ivybridge haswell guide](/docs/install/ivy_has_common.html)
|
|
for instructions on creating a unified rom image.
|
|
|
|
Extracting the blobs from a vendor rom image is automated in lbmk.
|
|
Simply run `./blobutil extract [board] [/path/to/backup.bin]`
|
|
For example:
|
|
|
|
./blobutil extract t420s_12mb t420s_backup.bin
|
|
|
|
You can then modify your coreboot configs again and set the path for the
|
|
intel firmware descriptor, intel management engine, and gigabit ethernet firmware.
|
|
|
|
Getting Help
|
|
============
|
|
|
|
Once you have tried everything above, you might find that the board still doesn't
|
|
work.
|
|
If that is the case, then you should contact libreboot developers for more help.
|
|
You can ping `shmalebx9` and/or `leah` on irc or submit an issue on git.
|
|
In either case, make sure to include a detailed description of everything you
|
|
tried, and what exactly happened when you tried to flash the rom.
|
|
If your board is not supported in libreboot, then you can assume that our
|
|
developers don't have it.
|
|
You'll therefore be expected to test roms created by libreboot developers on
|
|
your own machine.
|
|
|
|
In the meantime, you can always externally flash a backup of your vendor rom
|
|
to keep your machine working while development progresses on your board.
|