CBFSTOOL(8)

🎀 CBFSTOOL — NAME

cbfstool — bestie, this is the management utility for CBFS formatted ROM images, straight outta the coreboot tools 👑

---

🌸 SYNOPSIS

cbfstool [-h]
cbfstool FILE COMMAND [-v] [PARAMETERS]...

---

✨ DESCRIPTION

Okay so real talk: this is the management utility for CBFS formatted ROM images. That's the whole vibe. It's giving "I poke at firmware and I'm good at it" 💅

---

💖 OPTIONS

Every single one, no skipping, periodt:

• -H header_offset — do NOT go looking for the header, just use this offset* 🎯
• -T — output a top-aligned memory address
• -u — accept short data; fill upward / from the bottom
• -d — accept short data; fill downward / from the top
• -F — force it. Do the thing. No cap.
• -g — generate position and alignment arguments
• -U — unprocessed; don't decompress or make ELF
• -v — give me verbose output (-v=INFO, -vv=DEBUG output) 🗣️
• -h — display this help message (the classic)
• --ext-win-base — base of extended decode window in host address space (x86 only)
• --ext-win-size — size of extended decode window in host address space (x86 only)

---

🔥 COMMANDS

➕ add

add [-r image,regions] -f FILE -n NAME -t TYPE [-A hash]
       [-c compression] [-b base-address | -a alignment] [-p padding
       size] [-y|--xip if TYPE is FSP] [-j topswap-size] (Intel CPUs
       only) [--ibb] [--ext-win-base win-base --ext-win-size win-size]

Add a component ✨

• -j valid size: 0x10000 0x20000 0x40000 0x80000 0x100000

🚀 add-payload

add-payload [-r image,regions] -f FILE -n NAME [-A hash]
       [-c compression] [-b base-address] (linux specific: [-C cmdline]
       [-I initrd])

Add a payload to the ROM. Linux girlies get the extra -C cmdline and -I initrd moment 🐧

🎭 add-stage

add-stage [-r image,regions] -f FILE -n NAME [-A hash]
       [-c compression] [-b base] [-S
       comma-separated-section(s)-to-ignore] [-a alignment]
       [-Q|--pow2page] [-y|--xip] [--ibb] [--ext-win-base win-base
       --ext-win-size win-size]

Add a stage to the ROM 🌟

🧱 add-flat-binary

add-flat-binary [-r image,regions] -f FILE -n NAME
       [-A hash] -l load-address -e entry-point [-c compression] [-b
       base]

Add a 32bit flat mode binary

🔢 add-int

add-int [-r image,regions] -i INTEGER -n NAME [-b base]

Add a raw 64-bit integer value. Just a number, living its truth 🫶

👑 add-master-header

add-master-header [-r image,regions] [-j topswap-size] (Intel CPUs only)

Add a legacy CBFS master header

❌ remove

remove [-r image,regions] -n NAME

Remove a component. Gone. Blocked. Unfollowed 💀

🧹 compact

compact -r image,regions

Defragment CBFS image. Self-care for your ROM 🧖

📋 copy

copy -r image,regions -R source-region

Create a copy (duplicate) cbfs instance in fmap

🏗️ create (legacy style)

create -m ARCH -s size [-b bootblock offset]
       [-o CBFS offset] [-H header offset] [-B bootblock]

Create a legacy ROM file with CBFS master header* ✨

🆕 create (new-style)

create -M flashmap [-r list,of,regions,containing,cbfses]

Create a new-style partitioned firmware image

🗺️ layout

layout [-w]

List mutable (or, with -w, readable) image regions

🖨️ print

print [-r image,regions] [-k]

Show the contents of the ROM. Show me what you got 👀

📤 extract

extract [-r image,regions] [-m ARCH] -n NAME -f FILE [-U]

Extracts a file from ROM

✍️ write

write [-F] -r image,regions -f file [-u | -d] [-i int]

Write file into same-size [or larger] raw region

📖 read

read [-r fmap-region] -f file

Extract raw region contents into binary file

✂️ truncate

truncate [-r fmap-region]

Truncate CBFS and print new size on stdout

🎈 expand

expand [-r fmap-region]

Expand CBFS to span entire region

---

🧮 OFFSETS

So the numbers that come along with the -b, -H, and -o switches* can show up in two possible formats, bestie:

• if their value is greater than 0x80000000, they get interpreted as a top-aligned x86 memory address
• otherwise, they're treated as an offset into flash

That's it, that's the rule 🌈

---

🏛️ ARCHITECTURES

arm64, arm, mips, ppc64, power8, riscv, x86, unknown

---

🗂️ TYPES

bootblock, cbfs header, legacy stage, stage, simple elf, fit_payload, optionrom, bootsplash, raw, vsa, mbi, microcode, intel_fit, fsp, mrc, cmos_default, cmos_layout, spd, mrc_cache, mma, efi, struct, deleted, null, amdfw

okay so listen, this part is important: these actions and switches are only valid when working with legacy images whose structure is described primarily by a CBFS master header.

New-style images, in contrast, exclusively make use of an FMAP to describe their layout. That FMAP must minimally contain an 'FMAP' section specifying the location of this FMAP itself, plus a 'COREBOOT' section describing the primary CBFS. 🫶

Also worth noting: when you're working with such images, the -F and -r switches default to 'COREBOOT' for convenience, and the -b switch becomes relative to the selected CBFS region's lowest address.

The one exception to this rule is the top-aligned address, which is always relative to the end of the entire image rather than relative to the local region. This is true for both input (sufficiently large) and output (-T) data. No cap, that's just how it is 💅

---

💜 AUTHORS

• coresystems GmbH.
• Man page written by Ahmad Khalifa.

---

and that's the whole page, bestie 🎀 it shipped as part of System Administration Utilities back in November 2024 — go forth and manage those ROM images, you absolute icon 👑✨🦋