Column 5: Introducing CBFS. (2011-07-27)

As you may have seen when trying out Coreboot under QEMU, you might have noticed that the ROM image is not just a monolithic block, but that it contains named objects. Welcome to CBFS, the Coreboot File System. As far as Coreboot is concerned, this is a read-only file system. A special tool (cbfstool) can add extra components to a ROM image file. File deletion is not supported at all. In theory it is possible to write additional files to an actual flash chip, but this is not supported by the flash utility. Instead, the ROM image is composed (as a file on disk) by cbfstool and then the whole image is flashed into the actual flash chip.

Header format

The ROM contains a boot block with the low level startup code and this block starts with the CBFS header (which starts with the ASCII characters ORBC). This header contains the total size of the ROM (so the start address can be found). Further the alignment is specified, for instance that each header must start at an address that is aligned to a multiple of 16 bytes. Everything in the ROM outside the boot block is occupied by CBFS files.

Each CBFS file consists of a header, a file name (null-terminated ASCII string) and the file contents. The header starts with the ASCII string "LARCHIVE", which is easy to spot when viewing the ROM image with a hex/ASCII viewer. The next file follows the previous file immediately at the next aligned address. The file name can contain slashes (giving the illusion of subdirectories) but there is no directory structure. Documentation about the header format can be found in documentation/cbfs.txt in the Coreboot source tree. Because the file system structure is so simple, it is easy for the ROM code to scan for certain files. Even the boot block (which is written in assembly language) has to scan for the ROM stage (code in src/arch/x86/walkcbfs.S). Every other component uses the C code in src/lib/cbfs.c

File types

The ROM can contain the following types of files:

Coreboot can store two sets of stages (plus payload): the normal set and the fallback set. The romstage, coreboot_ram and payload files of the normal set are stored in the "subdirectory" named "normal", the files of the fallback set are stored in the "subdirectory" named "fallback". The startup code contains some logic to execute the "fallback" code instead of the "normal" code when the "normal" code has failed to start properly. This way experimental code can be tried out while we can still get back to the old code. This fallback mechanism is not fool-proof but it will help you out in most cases.


Many files in CBFS can be compressed with LZMA. This is a Lempel-Ziv type compressor (not unlike the one used in gzip), but it has two advantages over other compression methods:

Compression speed is not very high and the compression code takes considerably more space than the decompressor, but that is fine for this type of application.

The decompression code must be included in the ROM stage, so it can decompress the RAM stage and payload.