osbwww/site/docs/maintain/porting.md

---

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 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.

If 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.

Cloning Osbmk

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 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 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:

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 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.

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 osboot 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 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.