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 osboot. 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.
You will certainly need flashing equipment if you wish to follow this guide. See the flashing guide 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. Osboot 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 osboot as
board is not supported in coreboot then you need to start there first. Osboot 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.
If you have determined that
board is supported by coreboot, but is not supported by osboot, 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 osboot developers. The best way to get in touch is via osboot irc.
Before you try to get any work done, you’ll need to clone the osbmk (osboot make) project. To do so, you’ll need to have git installed on your machine. You can then clone the project.
git clone https://notabug.org/osboot/osbmk
If you want more information on building osbmk see the build instructions.
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/
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 osbmk.
./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:
Solutions to these problems follow in the proceeding sections.
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|
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 for instructions on creating a unified rom image.
Extracting the blobs from a vendor rom image is automated in osbmk. 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.
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 osboot developers for more help. You can ping
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 osboot, then you can assume that osboot developers don’t have it. You’ll therefore be expected to test roms created by osboot 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.
Markdown file for this page: https://osboot.org/docs/maintain/porting.md
This HTML page was generated by the untitled static site generator.