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:

• Stages of Coreboot itself (romstage and coreboot_ram). Like the boot block, the ROM stage contains code that must be executed in-place, but the the ROM stage contains position independent code. The RAM stage will be copied to RAM before it is executed and it may even be compressed.
• Payloads. The payload can be compressed and it will be copied to RAM before it is executed. In fact it consists of several segments, each of which can be compressed individually and each of which can be copied to a different address. The program cbfstool parses an ELF file into its individual segments and stores them in the format required by Coreboot. There is one primary payload (e.g. fallback/payload), but some payloads (such as Bayou and SeaBIOS) support running additional payloads.
• ROM images (VGA ROM, other option ROMs). In the current version of Coreboot they are stored as-is. They contain no extra header and they are not compressed.
• Configuration files (boot order, CMOS layout).
• Boot splash images (supported by SeaBIOS).
• Diskette images (supported by SeaBIOS).

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.

Compression

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:

• The compression ratio is very good. This is in part due to the use of range coding, a type of arithmetic coding.
• The decompression code is very compact, just 5 kilobytes.

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