blob: 831e882804e860efdd976f80a98368120c7fd4c5 [file] [log] [blame]
Stefan Reinauer013c7cf2009-04-08 07:47:01 +00001
2Received: from ([]
3 for; Fri, 19 Dec 2008 23:11:59 +0100
4From: Jordan Crouse <>
Stefan Reinauer14e22772010-04-27 06:56:47 +00007Greetings. I apologize for the incompleteness of what I am about to
8discuss. I was planning on working on it leisurely, but my employment
9circumstances changed and I've been trying to get it completed in a
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000010hurry before I had to leave it behind.
Stefan Reinauer14e22772010-04-27 06:56:47 +000012I've been thinking a lot about LAR lately, and ways to make it more
13extensible and robust. Marc and I have been trading ideas back and
14forth for a number of months, and over time a clear idea of what I
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000015wanted to do started to take shape.
Stefan Reinauer14e22772010-04-27 06:56:47 +000017My goal was to add small things to LAR while retaining the overall
18scheme. Over time, the scheme evolved slightly, but I think you'll find
19that it remains true to the original idea. Below is the beginnings of
20an architecture document - I did it in text form, but if met with
21aclaim, it should be wikified. This presents what I call CBFS - the
Martin Roth4b18a922017-06-03 20:16:01 -060022next generation LAR for next generation coreboot. Its easier to
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000023describe what it is by describing what changed:
Stefan Reinauer14e22772010-04-27 06:56:47 +000025A header has been added somewhere in the bootblock similar to Carl
26Daniel's scheme. In addition to the coreboot information, the header
27reports the size of the ROM, the alignment of the blocks, and the offset
28of the first component in the CBFS. The master header provides all
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000029the information LAR needs plus the magic number information flashrom needs.
Stefan Reinauer14e22772010-04-27 06:56:47 +000031Each "file" (or component, as I style them) now has a type associated
32with it. The type is used by coreboot to identify the type of file that
33it is loading, and it can also be used by payloads to group items in the
Peter Stuge450b23f2009-04-14 00:01:34 +000034CBFS by type (i.e - bayou can ask for all components that are payloads).
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000035
Stefan Reinauer14e22772010-04-27 06:56:47 +000036The header on each "file" (or component, as I like to style them) has
37been simplified - We now only store the length, the type, the checksum,
38and the offset to the data. The name scheme remains the same. The
Jonathan Neuschäfer8ee93ae262018-04-09 13:05:29 +020039additional information, which is component specific, has been moved to
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000040the component itself (see below).
Stefan Reinauer14e22772010-04-27 06:56:47 +000042The components are arranged in the ROM aligned along the specified
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000043alignment from the master header - this is to facilitate partial re-write.
45Other then that, the LAR ideas remain pretty much the same.
Stefan Reinauer14e22772010-04-27 06:56:47 +000047The plan for moving the metadata to the components is to allow many
48different kinds of components, not all of which are groked by coreboot.
49 However, there are three essential component types that are groked by
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000050coreboot, and they are defined:
Stefan Reinauer14e22772010-04-27 06:56:47 +000052stage - the stage is being parsed from the original ELF, and stored in
53the ROM as a single blob of binary data. The load address, start
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000054address, compression type and length are stored in the component sub-header.
Stefan Reinauer14e22772010-04-27 06:56:47 +000056payload - this is essentially SELF in different clothing - same idea as
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000057SELF, with the sub-header as above.
Stefan Reinauer14e22772010-04-27 06:56:47 +000059optionrom - This is in flux - right now, the optionrom is stored
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000060unadulterated and uncompressed, but that is likely to be changed.
Stefan Reinauer14e22772010-04-27 06:56:47 +000062Following this email are two replies containing the v3 code and a new
63ROM tool to implement this respectively. I told you that I was trying
64to get this out before I disappear, and I'm not kidding - the code is
65compile tested and not run-tested. I hope that somebody will embrace
66this code and take it the rest of the way, otherwise it will die a
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000067pretty short death.
Stefan Reinauer14e22772010-04-27 06:56:47 +000069I realize that this will start an awesome flamewar, and I'm looking
70forward to it. Thanks for listening to me over the years - and good
71luck with coreboot. When you all make a million dollars, send me a few
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000072bucks, will you?
Martin Roth4b18a922017-06-03 20:16:01 -060076coreboot CBFS Specification
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000077Jordan Crouse <>
79= Introduction =
Peter Stuge450b23f2009-04-14 00:01:34 +000081This document describes the coreboot CBFS specification (from here
82referred to as CBFS). CBFS is a scheme for managing independent chunks
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000083of data in a system ROM. Though not a true filesystem, the style and
84concepts are similar.
87= Architecture =
Peter Stuge450b23f2009-04-14 00:01:34 +000089The CBFS architecture looks like the following:
Stefan Reinauer013c7cf2009-04-08 07:47:01 +000090
91/---------------\ <-- Start of ROM
92| /-----------\ | --|
93| | Header | | |
94| |-----------| | |
95| | Name | | |-- Component
96| |-----------| | |
97| |Data | | |
98| |.. | | |
99| \-----------/ | --|
100| |
101| /-----------\ |
102| | Header | |
103| |-----------| |
104| | Name | |
105| |-----------| |
106| |Data | |
107| |.. | |
108| \-----------/ |
109| |
110| ... |
111| /-----------\ |
112| | | |
113| | Bootblock | |
114| | --------- | |
115| | Reset | | <- 0xFFFFFFF0
116| \-----------/ |
Peter Stuge450b23f2009-04-14 00:01:34 +0000120The CBFS architecture consists of a binary associated with a physical
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000121ROM disk referred hereafter as the ROM. A number of independent of
122components, each with a header prepended on to data are located within
123the ROM. The components are nominally arranged sequentially, though they
124are aligned along a pre-defined boundary.
126The bootblock occupies the last 20k of the ROM. Within
127the bootblock is a master header containing information about the ROM
128including the size, alignment of the components, and the offset of the
Peter Stuge450b23f2009-04-14 00:01:34 +0000129start of the first CBFS component within the ROM.
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000130
131= Master Header =
133The master header contains essential information about the ROM that is
Peter Stuge450b23f2009-04-14 00:01:34 +0000134used by both the CBFS implementation within coreboot at runtime as well
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000135as host based utilities to create and manage the ROM. The master header
136will be located somewhere within the bootblock (last 20k of the ROM). A
137pointer to the location of the header will be located at offset
Stefan Reinauer48ca7b22009-12-17 09:42:30 +0000138-4 from the end of the ROM. This translates to address 0xFFFFFFFC on a
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000139normal x86 system. The pointer will be to physical memory somewhere
140between - 0xFFFFB000 and 0xFFFFFFF0. This makes it easier for coreboot
141to locate the header at run time. Build time utilities will
142need to read the pointer and do the appropriate math to locate the header.
144The following is the structure of the master header:
Peter Stuge450b23f2009-04-14 00:01:34 +0000146struct cbfs_header {
David Hendricks90ca3b62012-11-16 14:48:22 -0800147 u32 magic;
148 u32 version;
149 u32 romsize;
150 u32 bootblocksize;
151 u32 align;
152 u32 offset;
153 u32 architecture;
154 u32 pad[1];
Stefan Reinauer6a001132017-07-13 02:20:27 +0200155} __packed;
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000156
157The meaning of each member is as follows:
Stefan Reinauer14e22772010-04-27 06:56:47 +0000159'magic' is a 32 bit number that identifies the ROM as a CBFS type. The
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000160magic
161number is 0x4F524243, which is 'ORBC' in ASCII.
David Hendricks90ca3b62012-11-16 14:48:22 -0800163'version' is a version number for CBFS header. cbfs_header structure may be
164different if version is not matched.
Martin Roth4b18a922017-06-03 20:16:01 -0600166'romsize' is the size of the ROM in bytes. coreboot will subtract 'size' from
Stefan Reinauer013c7cf2009-04-08 07:47:01 +00001670xFFFFFFFF to locate the beginning of the ROM in memory.
David Hendricks90ca3b62012-11-16 14:48:22 -0800169'bootblocksize' is the size of bootblock reserved in firmware image.
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000171'align' is the number of bytes that each component is aligned to within the
Stefan Reinauer14e22772010-04-27 06:56:47 +0000172ROM. This is used to make sure that each component is aligned correctly
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000173with
174regards to the erase block sizes on the ROM - allowing one to replace a
175component at runtime without disturbing the others.
Jonathan Neuschäfer45e6c822018-12-11 17:53:07 +0100177'offset' is the offset of the first CBFS component (from the start of
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000178the ROM). This is to allow for arbitrary space to be left at the beginning
179of the ROM for things like embedded controller firmware.
David Hendricks90ca3b62012-11-16 14:48:22 -0800181'architecture' describes which architecture (x86, arm, ...) this CBFS is created
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000184= Bootblock =
Stefan Reinauer14e22772010-04-27 06:56:47 +0000185The bootblock is a mandatory component in the ROM. It is located in the
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000186last
18720k of the ROM space, and contains, among other things, the location of the
188master header and the entry point for the loader firmware. The bootblock
189does not have a component header attached to it.
191= Components =
Peter Stuge450b23f2009-04-14 00:01:34 +0000193CBFS components are placed in the ROM starting at 'offset' specified in
Stefan Reinauer14e22772010-04-27 06:56:47 +0000194the master header and ending at the bootblock. Thus the total size
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000195available
Peter Stuge450b23f2009-04-14 00:01:34 +0000196for components in the ROM is (ROM size - 20k - 'offset'). Each CBFS
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000197component is to be aligned according to the 'align' value in the header.
Stefan Reinauer14e22772010-04-27 06:56:47 +0000198Thus, if a component of size 1052 is located at offset 0 with an 'align'
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000199value
200of 1024, the next component will be located at offset 2048.
Peter Stuge450b23f2009-04-14 00:01:34 +0000202Each CBFS component will be indexed with a unique ASCII string name of
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000203unlimited size.
Peter Stuge450b23f2009-04-14 00:01:34 +0000205Each CBFS component starts with a header:
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000206
Peter Stuge450b23f2009-04-14 00:01:34 +0000207struct cbfs_file {
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000208 char magic[8];
209 unsigned int len;
210 unsigned int type;
211 unsigned int checksum;
212 unsigned int offset;
215'magic' is a magic value used to identify the header. During runtime,
216coreboot will scan the ROM looking for this value. The default magic is
217the string 'LARCHIVE'.
219'len' is the length of the data, not including the size of the header and
220the size of the name.
222'type' is a 32 bit number indicating the type of data that is attached.
223The data type is used in a number of ways, as detailed in the section
226'checksum' is a 32bit checksum of the entire component, including the
227header and name.
Stefan Reinauer14e22772010-04-27 06:56:47 +0000229'offset' is the start of the component data, based off the start of the
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000230header.
231The difference between the size of the header and offset is the size of the
232component name.
Stefan Reinauer14e22772010-04-27 06:56:47 +0000234Immediately following the header will be the name of the component,
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000235which will
236null terminated and 16 byte aligned. The following picture shows the
237structure of the header:
239/--------\ <- start
240| Header |
Peter Stuge450b23f2009-04-14 00:01:34 +0000241|--------| <- sizeof(struct cbfs_file)
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000242| Name |
243|--------| <- 'offset'
244| Data |
245| ... |
246\--------/ <- start + 'offset' + 'len'
Jonathan Neuschäfer8ee93ae262018-04-09 13:05:29 +0200248== Searching Algorithm ==
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000249
250To locate a specific component in the ROM, one starts at the 'offset'
Peter Stuge450b23f2009-04-14 00:01:34 +0000251specified in the CBFS master header. For this example, the offset will
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000252be 0.
254 From that offset, the code should search for the magic string on the
255component, jumping 'align' bytes each time. So, assuming that 'align' is
25616, the code will search for the string 'LARCHIVE' at offset 0, 16, 32, etc.
Peter Stuge450b23f2009-04-14 00:01:34 +0000257If the offset ever exceeds the allowable range for CBFS components, then no
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000258component was found.
260Upon recognizing a component, the software then has to search for the
261specific name of the component. This is accomplished by comparing the
262desired name with the string on the component located at
Stefan Reinauer14e22772010-04-27 06:56:47 +0000263offset + sizeof(struct cbfs_file). If the string matches, then the
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000264component
265has been located, otherwise the software should add 'offset' + 'len' to
266the offset and resume the search for the magic value.
268== Data Types ==
Peter Stuge450b23f2009-04-14 00:01:34 +0000270The 'type' member of struct cbfs_file is used to identify the content
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000271of the component data, and is used by coreboot and other
272run-time entities to make decisions about how to handle the data.
274There are three component types that are essential to coreboot, and so
275are defined here.
277=== Stages ===
279Stages are code loaded by coreboot during the boot process. They are
280essential to a successful boot. Stages are comprised of a single blob
281of binary data that is to be loaded into a particular location in memory
282and executed. The uncompressed header contains information about how
283large the data is, and where it should be placed, and what additional memory
284needs to be cleared.
286Stages are assigned a component value of 0x10. When coreboot sees this
287component type, it knows that it should pass the data to a sub-function
288that will process the stage.
290The following is the format of a stage component:
293| Header |
295| Binary |
296| .. |
299The header is defined as:
Peter Stuge450b23f2009-04-14 00:01:34 +0000301struct cbfs_stage {
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000302 unsigned int compression;
303 unsigned long long entry;
304 unsigned long long load;
305 unsigned int len;
306 unsigned int memlen;
309'compression' is an integer defining how the data is compressed. There
310are three compression types defined by this version of the standard:
Patrick Georgi2f39eae2013-08-31 08:16:27 +0200311none (0x0), lzma (0x1), and nrv2b (0x02, deprecated), though additional
312types may be added assuming that coreboot understands how to handle the scheme.
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000313
314'entry' is a 64 bit value indicating the location where the program
315counter should jump following the loading of the stage. This should be
316an absolute physical memory address.
318'load' is a 64 bit value indicating where the subsequent data should be
319loaded. This should be an absolute physical memory address.
321'len' is the length of the compressed data in the component.
323'memlen' is the amount of memory that will be used by the component when
324it is loaded.
326The component data will start immediately following the header.
328When coreboot loads a stage, it will first zero the memory from 'load' to
329'memlen'. It will then decompress the component data according to the
330specified scheme and place it in memory starting at 'load'. Following that,
331it will jump execution to the address specified by 'entry'.
332Some components are designed to execute directly from the ROM - coreboot
333knows which components must do that and will act accordingly.
335=== Payloads ===
337Payloads are loaded by coreboot following the boot process.
339Stages are assigned a component value of 0x20. When coreboot sees this
340component type, it knows that it should pass the data to a sub-function
341that will process the payload. Furthermore, other run time
342applications such as 'bayou' may easily index all available payloads
343on the system by searching for the payload type.
346The following is the format of a stage component:
349| Header |
350| Segment 1 |
351| Segment 2 |
352| ... |
354| Binary |
355| .. |
358The header is as follows:
Peter Stuge450b23f2009-04-14 00:01:34 +0000360struct cbfs_payload {
361 struct cbfs_payload_segment segments;
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000362}
364The header contains a number of segments corresponding to the segments
365that need to be loaded for the payload.
367The following is the structure of each segment header:
Peter Stuge450b23f2009-04-14 00:01:34 +0000369struct cbfs_payload_segment {
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000370 unsigned int type;
371 unsigned int compression;
372 unsigned int offset;
373 unsigned long long load_addr;
374 unsigned int len;
375 unsigned int mem_len;
378'type' is the type of segment, one of the following:
380PAYLOAD_SEGMENT_CODE 0x45444F43 The segment contains executable code
381PAYLOAD_SEGMENT_DATA 0x41544144 The segment contains data
Jonathan Neuschäfer8ee93ae262018-04-09 13:05:29 +0200382PAYLOAD_SEGMENT_BSS 0x20535342 The memory specified by the segment
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000383 should be zeroed
384PAYLOAD_SEGMENT_PARAMS 0x41524150 The segment contains information for
385 the payload
386PAYLOAD_SEGMENT_ENTRY 0x52544E45 The segment contains the entry point
Elyes HAOUAS89011be2018-05-29 08:31:10 +0200387 for the payload
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000388
389'compression' is the compression scheme for the segment. Each segment can
390be independently compressed. There are three compression types defined by
Patrick Georgi2f39eae2013-08-31 08:16:27 +0200391this version of the standard: none (0x0), lzma (0x1), and nrv2b
392(0x02, deprecated), though additional types may be added assuming that
393coreboot understands how to handle the scheme.
Stefan Reinauer013c7cf2009-04-08 07:47:01 +0000394
395'offset' is the address of the data within the component, starting from
396the component header.
398'load_addr' is a 64 bit value indicating where the segment should be placed
399in memory.
401'len' is a 32 bit value indicating the size of the segment within the
404'mem_len' is the size of the data when it is placed into memory.
406The data will located immediately following the last segment.
408=== Option ROMS ===
410The third specified component type will be Option ROMs. Option ROMS will
411have component type '0x30'. They will have no additional header, the
412uncompressed binary data will be located in the data portion of the
415=== NULL ===
417There is a 4th component type ,defined as NULL (0xFFFFFFFF). This is
418the "don't care" component type. This can be used when the component
419type is not necessary (such as when the name of the component is unique.
420i.e. option_table). It is recommended that all components be assigned a
421unique type, but NULL can be used when the type does not matter.