Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/33664 Change subject: Documentation: Update CBFS ...................................................................... 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 https://review.coreboot.org/c/coreboot/+/33664 To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: coreboot Gerrit-Branch: master Gerrit-Change-Id: I84d07ae1c5c1ded2b9ab5934e2babbbabb749440 Gerrit-Change-Number: 33664 Gerrit-PatchSet: 1 Gerrit-Owner: Patrick Rudolph <patrick.rudolph@9elements.com> Gerrit-MessageType: newchange