Patrick Rudolph has uploaded this change for review.
Documentation: Update CBFS
Update some parts to match current implementation.
Change-Id: I84d07ae1c5c1ded2b9ab5934e2babbbabb749440
---
M Documentation/lib/cbfs.md
M Documentation/lib/payloads/selfboot.md
2 files changed, 46 insertions(+), 34 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/64/33664/1
diff --git a/Documentation/lib/cbfs.md b/Documentation/lib/cbfs.md
index 83d8b44..ce87b78 100644
--- a/Documentation/lib/cbfs.md
+++ b/Documentation/lib/cbfs.md
@@ -7,7 +7,7 @@
## Introduction
-This document describes the coreboot CBFS specification (from here
+This document describes the coreboot filesystem specification (from here
referred to as CBFS). CBFS is a scheme for managing independent chunks
of data in a system ROM. Though not a true filesystem, the style and
concepts are similar.
@@ -15,7 +15,7 @@
## Architecture
-The CBFS architecture looks like the following:
+The CBFS on x86 architecture looks like the following:
```
/---------------\ <-- Start of ROM
@@ -49,11 +49,11 @@
The CBFS architecture consists of a binary associated with a physical
ROM disk referred hereafter as the ROM. A number of independent of
-components, each with a header prepended on to data are located within
-the ROM. The components are nominally arranged sequentially, though they
+components, each with a header prepended on to data are located within
+the ROM. The components are nominally arranged sequentially, though they
are aligned along a pre-defined boundary.
-The bootblock occupies the last 20k of the ROM. Within
+On x86 legacy the bootblock occupies the last 20k of the ROM. Within
the bootblock is a master header containing information about the ROM
including the size, alignment of the components, and the offset of the
start of the first CBFS component within the ROM.
@@ -62,14 +62,13 @@
The master header contains essential information about the ROM that is
used by both the CBFS implementation within coreboot at runtime as well
-as host based utilities to create and manage the ROM. The master header
-will be located somewhere within the bootblock (last 20k of the ROM). A
-pointer to the location of the header will be located at offset
--4 from the end of the ROM. This translates to address 0xFFFFFFFC on a
-normal x86 system. The pointer will be to physical memory somewhere
-between - 0xFFFFB000 and 0xFFFFFFF0. This makes it easier for coreboot
-to locate the header at run time. Build time utilities will
-need to read the pointer and do the appropriate math to locate the header.
+as host based utilities to create and manage the ROM. The master header
+will be located at the start of CBFS. A pointer to the location of the
+header will be located at offset -4 from the end of the ROM.
+This translates to address 0xFFFFFFFC on a normal x86 system.
+This makes it easier for coreboot to locate the header at run time.
+Build time utilities will need to read the pointer and do the appropriate
+math to locate the header.
The following is the structure of the master header:
@@ -114,16 +113,16 @@
for.
## Bootblock
-The bootblock is a mandatory component in the ROM. It is located in the
-last 20k of the ROM space, and contains, among other things, the location of the
-master header and the entry point for the loader firmware. The bootblock
-does not have a component header attached to it.
+The bootblock is a mandatory component in the ROM. On x86 legacy it is located
+at the end of the CBFS, and contains, among other things, the location of the
+master header and the entry point for the loader firmware. On other
+architectures the bootblock might not be part of the CBFS.
## Components
CBFS components are placed in the ROM starting at 'offset' specified in
-the master header and ending at the bootblock. Thus the total size
-available for components in the ROM is (ROM size - 20k - 'offset').
+the master header and ending at the end of the CBFS. Thus the total size
+available for components in the ROM is (ROM size - 'offset').
Each CBFS component is to be aligned according to the 'align' value in the
header.
Thus, if a component of size 1052 is located at offset 0 with an 'align'
@@ -208,10 +207,10 @@
#### Stages
-Stages are code loaded by coreboot during the boot process. They are
-essential to a successful boot. Stages are comprised of a single blob
+Stages are code loaded by coreboot during the boot process. They are
+essential to a successful boot. Stages are comprised of a single blob
of binary data that is to be loaded into a particular location in memory
-and executed. The uncompressed header contains information about how
+and executed. The uncompressed header contains information about how
large the data is, and where it should be placed, and what additional memory
needs to be cleared.
@@ -244,8 +243,8 @@
`compression` is an integer defining how the data is compressed. There
are three compression types defined by this version of the standard:
-none (0x0), lzma (0x1), and nrv2b (0x02, deprecated), though additional
-types may be added assuming that coreboot understands how to handle the scheme.
+none (0x0), lzma (0x1), and lz4 (0x02), though additional types may be
+added assuming that coreboot understands how to handle the scheme.
`entry` is a 64 bit value indicating the location where the program
counter should jump following the loading of the stage. This should be
@@ -271,13 +270,13 @@
#### Payloads
Payloads are loaded by coreboot following the boot process.
+The default payloads supported by coreboot are [SELF] payloads.
-Stages are assigned a component value of 0x20. When coreboot sees this
+[SELF] stages are assigned a component value of 0x20. When coreboot sees this
component type, it knows that it should pass the data to a sub-function
-that will process the payload. Furthermore, other run time applications such
-as 'bayou' may easily index all available payloads
-on the system by searching for the payload type.
-
+that will process the payload. Furthermore, other run time applications such
+as 'bayou' may easily index all available payloads on the system by searching
+for the payload type.
The following is the format of a stage component:
@@ -338,9 +337,9 @@
`compression` is the compression scheme for the segment. Each segment can
be independently compressed. There are three compression types defined by
-this version of the standard: none (0x0), lzma (0x1), and nrv2b
-(0x02, deprecated), though additional types may be added assuming that
-coreboot understands how to handle the scheme.
+this version of the standard: none (0x0), lzma (0x1), and lz4 (0x02), though
+additional types may be added assuming that coreboot understands how to handle
+the scheme.
`offset` is the address of the data within the component, starting from
the component header.
@@ -355,6 +354,13 @@
The data will located immediately following the last segment.
+#### FIT payload
+
+A payload of type [FIT] is supported on some architectures.
+
+[FIT] stages are assigned a component value of 0x21 and do not support
+compressions at all.
+
#### Option ROMS
The third specified component type will be Option ROMs. Option ROMS will
@@ -364,8 +370,11 @@
#### NULL
-There is a 4th component type ,defined as NULL (0xFFFFFFFF). This is
-the "don't care" component type. This can be used when the component
+There is a 4th component type, defined as NULL (0xFFFFFFFF, 0x00000000).
+This is the "don't care" component type. This can be used when the component
type is not necessary (such as when the name of the component is unique.
i.e. option_table). It is recommended that all components be assigned a
unique type, but NULL can be used when the type does not matter.
+
+[FIT]: payloads/fit.md
+[SELF]: payloads/selfboot.md
diff --git a/Documentation/lib/payloads/selfboot.md b/Documentation/lib/payloads/selfboot.md
index 62a4393..791d6c0 100644
--- a/Documentation/lib/payloads/selfboot.md
+++ b/Documentation/lib/payloads/selfboot.md
@@ -18,6 +18,8 @@
address they specify. If it's not possible to load the payload at the specified
address, the system won't boot.
+Implementations details can be found in the [CBFS] documentation.
+
### Calling conventions
The SELF payload is called with a pointer to the coreboot tables as first
argument.
@@ -26,3 +28,4 @@
and a pointer to the *FDT* as arguments.
[RISC-V]: ../../arch/riscv/index.md
+[CBFS]: ../cbfs.md
To view, visit change 33664. To unsubscribe, or for help writing mail filters, visit settings.