1 Coreboot CBFS Specification
2 Jordan Crouse <jordan@cosmicpenguin.net>
6 This document describes the coreboot CBFS specification (from here referred
7 to as CBFS). CBFS is a scheme for managing independent chunks of data in
8 a system ROM. Though not a true filesystem, the style and concepts are
13 The CBFS architecture looks like the following:
15 /---------------\ <-- Start of ROM
19 | | Name | | |-- Component
39 | | Reset | | <- 0xFFFFFFF0
44 The CBFS architecture consists of a binary associated with a physical
45 ROM disk referred hereafter as the ROM. A number of independent of
46 components, each with a header prepended on to data are located within
47 the ROM. The components are nominally arranged sequentially, though they
48 are aligned along a pre-defined boundary.
50 The bootblock occupies the last 20k of the ROM. Within
51 the bootblock is a master header containing information about the ROM
52 including the size, alignment of the components, and the offset of the
53 start of the first CBFS component within the ROM.
57 The master header contains essential information about the ROM that is
58 used by both the CBFS implementation within coreboot at runtime as well
59 as host based utilities to create and manage the ROM. The master header
60 will be located somewhere within the bootblock (high end of the ROM). A
61 pointer to the location of the header will be located at offset
62 -4 from the end of the ROM. This translates to address 0xFFFFFFFC on a
63 normal x86 system. The pointer will be to physical memory somewhere
64 between - 0xFFFF0000 and 0xFFFFFFF0. This makes it easier for coreboot
65 to locate the header at run time. Build time utilities will
66 need to read the pointer and do the appropriate math to locate the header.
68 The following is the structure of the master header:
74 unsigned int bootblocksize;
80 The meaning of each member is as follows:
82 'magic' is a 32 bit number that identifies the ROM as a CBFS type. The magic
83 number is 0x4F524243, which is 'ORBC' in ASCII.
85 'version' is a 32 bit number that identifies the version of CBFS. The current
86 version is 0x31313131 ('1111' in ASCII) which is endian-independent.
88 'romsize' is the size of the ROM in bytes. Coreboot will subtract 'size' from
89 0xFFFFFFFF to locate the beginning of the ROM in memory.
91 'bootblocksize' is the boot block size in bytes. There is no limitation on
92 the boot block size as in v3.
94 'align' is the number of bytes that each component is aligned to within the
95 ROM. This is used to make sure that each component is aligned correctly with
96 regards to the erase block sizes on the ROM - allowing one to replace a
97 component at runtime without disturbing the others.
99 'offset' is the offset of the the first CBFS component (from the start of
100 the ROM). This is to allow for arbitrary space to be left at the beginning
101 of the ROM for things like embedded controller firmware.
103 'pad' rounds the header to 32 bits and reserves a little room for later use.
106 The bootblock is a mandatory component in the ROM. It is located in the
107 last bootblocksize bytes of ROM space, and contains, among other things,
108 the location of the master header and the entry point for the loader
109 firmware. The bootblock does not have a component header attached to it.
114 CBFS components are placed in the ROM starting at 'offset' specified in
115 the master header and ending at the bootblock. Thus the total size available
116 for components in the ROM is (ROM size - bootblocksize - 'offset'). Each CBFS
117 component is to be aligned according to the 'align' value in the header.
118 Thus, if a component of size 1052 is located at offset 0 with an 'align' value
119 of 1024, the next component will be located at offset 2048.
121 Each CBFS component will be indexed with a unique ASCII string name of
124 Each CBFS component starts with a header:
130 unsigned int checksum;
134 'magic' is a magic value used to identify the header. During runtime,
135 coreboot will scan the ROM looking for this value. The default magic is
136 the string 'LARCHIVE'.
138 'len' is the length of the data, not including the size of the header and
139 the size of the name.
141 'type' is a 32 bit number indicating the type of data that is attached.
142 The data type is used in a number of ways, as detailed in the section
145 'checksum' is a 32bit checksum of the entire component, including the
148 'offset' is the start of the component data, based off the start of the header.
149 The difference between the size of the header and offset is the size of the
152 Immediately following the header will be the name of the component, which will
153 null terminated and 16 byte aligned. The following picture shows the
154 structure of the header:
158 |--------| <- sizeof(struct cbfs_file)
160 |--------| <- 'offset'
163 \--------/ <- start + 'offset' + 'len'
165 == Searching Alogrithm ==
167 To locate a specific component in the ROM, one starts at the 'offset'
168 specified in the CBFS master header. For this example, the offset will
171 From that offset, the code should search for the magic string on the
172 component, jumping 'align' bytes each time. So, assuming that 'align' is
173 16, the code will search for the string 'LARCHIVE' at offset 0, 16, 32, etc.
174 If the offset ever exceeds the allowable range for CBFS components, then no
177 Upon recognizing a component, the software then has to search for the
178 specific name of the component. This is accomplished by comparing the
179 desired name with the string on the component located at
180 offset + sizeof(struct cbfs_file). If the string matches, then the component
181 has been located, otherwise the software should add 'offset' + 'len' to
182 the offset and resume the search for the magic value.
186 The 'type' member of struct cbfs_file is used to identify the content
187 of the component data, and is used by coreboot and other
188 run-time entities to make decisions about how to handle the data.
190 There are three component types that are essential to coreboot, and so
195 Stages are code loaded by coreboot during the boot process. They are
196 essential to a successful boot. Stages are comprised of a single blob
197 of binary data that is to be loaded into a particular location in memory
198 and executed. The uncompressed header contains information about how
199 large the data is, and where it should be placed, and what additional memory
202 Stages are assigned a component value of 0x10. When coreboot sees this
203 component type, it knows that it should pass the data to a sub-function
204 that will process the stage.
206 The following is the format of a stage component:
215 The header is defined as:
218 unsigned int compression;
219 unsigned long long entry;
220 unsigned long long load;
225 'compression' is an integer defining how the data is compressed. There
226 are three compression types defined by this version of the standard:
227 none (0x0), lzma (0x1), and nrv2b (0x02), though additional types may be
228 added assuming that coreboot understands how to handle the scheme.
230 'entry' is a 64 bit value indicating the location where the program
231 counter should jump following the loading of the stage. This should be
232 an absolute physical memory address.
234 'load' is a 64 bit value indicating where the subsequent data should be
235 loaded. This should be an absolute physical memory address.
237 'len' is the length of the compressed data in the component.
239 'memlen' is the amount of memory that will be used by the component when
242 The component data will start immediately following the header.
244 When coreboot loads a stage, it will first zero the memory from 'load' to
245 'memlen'. It will then decompress the component data according to the
246 specified scheme and place it in memory starting at 'load'. Following that,
247 it will jump execution to the address specified by 'entry'.
248 Some components are designed to execute directly from the ROM - coreboot
249 knows which components must do that and will act accordingly.
253 Payloads are loaded by coreboot following the boot process.
255 Stages are assigned a component value of 0x20. When coreboot sees this
256 component type, it knows that it should pass the data to a sub-function
257 that will process the payload. Furthermore, other run time
258 applications such as 'bayou' may easily index all available payloads
259 on the system by searching for the payload type.
262 The following is the format of a stage component:
274 The header is as follows:
276 struct cbfs_payload {
277 struct cbfs_payload_segment segments;
280 The header contains a number of segments corresponding to the segments
281 that need to be loaded for the payload.
283 The following is the structure of each segment header:
285 struct cbfs_payload_segment {
287 unsigned int compression;
289 unsigned long long load_addr;
291 unsigned int mem_len;
294 'type' is the type of segment, one of the following:
296 PAYLOAD_SEGMENT_CODE 0x45444F43 The segment contains executable code
297 PAYLOAD_SEGMENT_DATA 0x41544144 The segment contains data
298 PAYLOAD_SEGMENT_BSS 0x20535342 The memory speicfied by the segment
300 PAYLOAD_SEGMENT_PARAMS 0x41524150 The segment contains information for
302 PAYLOAD_SEGMENT_ENTRY 0x52544E45 The segment contains the entry point
305 'compression' is the compression scheme for the segment. Each segment can
306 be independently compressed. There are three compression types defined by
307 this version of the standard: none (0x0), lzma (0x1), and nrv2b (0x02),
308 though additional types may be added assuming that coreboot understands
309 how to handle the scheme.
311 'offset' is the address of the data within the component, starting from
312 the component header.
314 'load_addr' is a 64 bit value indicating where the segment should be placed
317 'len' is a 32 bit value indicating the size of the segment within the
320 'mem_len' is the size of the data when it is placed into memory.
322 The data will located immediately following the last segment.
326 The third specified component type will be Option ROMs. Option ROMS will
327 have component type '0x30'. They will have no additional header, the
328 uncompressed binary data will be located in the data portion of the
333 There is a 4th component type ,defined as NULL (0xFFFFFFFF). This is
334 the "don't care" component type. This can be used when the component
335 type is not necessary (such as when the name of the component is unique.
336 i.e. option_table). It is recommended that all components be assigned a
337 unique type, but NULL can be used when the type does not matter.