1Rebuilding coreboot image generation 2==================================== 3 4Current situation 5----------------- 6ChromeOS (CrOS) probably has the most complex image bundling process in the 7coreboot ecosystem. To make CrOS features more accessible to the wider 8coreboot community, we want to move these capabilities into upstream 9coreboot’s build system. 10 11Right now, the CrOS build system creates coreboot images, and various 12instances of the payload (with different configuration options), plus some 13more files (eg. EC firmware), then passes them to a CrOS-specific utility 14(`bundle_firmware.py`) to build the final image from that. 15 16`bundle_firmware` adds a flashmap (fmap) to the final image and creates 17additional CBFS filesystems in fmap regions. It then extracts some files from 18the original CBFS region (that was put in place carefully to later match to 19the default fmap region) and copies some of them into the others, as well as 20putting more data (eg. the bitmap data, keys) as raw data into other fmap 21regions. 22 23With the recent addition of more files to CBFS, both on the coreboot side 24(dsdt, FSP, and so on) and with ChromeOS specifics (eg. more files describing 25boot screens) we either need to expand the scope of bundle\_firmware or move 26the capability to build complex images to upstream coreboot’s build system. 27This document proposes to do the latter and outlines how this could be 28achieved. 29 30Problems with the current build system parts 31-------------------------------------------- 32One common sentiment is that it should be possible to reuse some of the 33existing mechanisms that are supposed to be supplanted by this. 34The main concern during this design that precluded their use was that none of 35them provides a comprehensive solution to building complex coreboot based 36images: 37* fmap.dts and fmd provide a flash layout, but no assignment of files of regions 38* cbfs-files-y ends up as an internal make variable using 39 `weird|formatting|to|deal|with|make’s|limitations` 40* make isn’t powerful enough to deal with ordering these entries in said 41 variable to guarantee success if there’s enough room for the files. While that 42 could be added, that becomes more make macro work indistinguishable from magic 43 that people fail to understand, break and with good reason complain about 44 to work around such issues, ChromeOS firmware uses a custom tool with even 45 more special cases to finally build the image it needs. If coreboot upstream 46 is to support vboot, it should also be powerful enough not to need magic tools 47 that only live within downstream projects. 48 49Requirements 50------------ 51A complete ChromeOS coreboot image consists of (depending on the device) 52* platform specific data in raw fmap regions (eg IFD, ME firmware), 53* the bootblock (coming from the bootblock), 54* three copies of coreboot, consisting of the stages (verstage, romstage, 55 ramstage) plus data, 56* depthcharge plus data (with each of the coreboot copies), 57* EC firmware files (with each of the coreboot copies), 58* signatures over several parts of the image and 59* some final checksumming over parts of the image to satisfy boot ROM 60 tests on ARM 61 62A complete upstream coreboot image (with fallback/normal switch configuration, 63using a yet to be implemented switching scheme based on fmaps) consists of 64* platform specific data in raw fmap regions (eg IFD, ME firmware), 65* two copies of coreboot, consisting of 66 * the bootblock and 67 * the stages (romstage, ramstage) plus data, 68* payload plus data (with each of the coreboot copies), 69 70Since a single platform is potentially built with different payload 71configurations (eg. modding a Chromebook to not use the verified ChromeOS 72boot scheme), some concerns need to be kept separate: 73* Platform requirements that have nothing to do with the payload or boot schemes 74 * IFD, ME, … need to copied to the right place 75 * boot ROM requirements such as checksums must be honored 76* Payload/boot scheme requirements 77 * Having one to three regions with certain files copied into them 78 79Proposal 80-------- 81The proposal is based on manifest files that describe certain aspects of the 82final image. 83The number of manifest files may change over time, but this seems to be a 84reasonable approach for now. As long as coreboot uses fmap and cbfs, there 85should be few need to change the language, since composition is done through 86files. 87 88The final image is generated by a utility that is handed a number of manifests 89and the size of the flash (derived from `CONFIG_ROM_SIZE`). These manifest files 90deal with different concerns, with the following an example that should match 91current use cases: 92 93Chipset manifest 94---------------- 95The chipset details if there are any non-coreboot regions, and assigns them 96names, locations, sizes and file contents and prepares a region for what is 97“platform visible” (eg. IFD’s BIOS region) that may be of flexible size 98(depending on the flash chip’s size). For the purpose of this document, that 99region is called “BIOS”. 100It can also specify if there’s a post processing requirement on the final 101image. 102 103coreboot manifest 104----------------- 105coreboot provides lists of the files it generates for each category it’s 106building (eg. bootblock, verstage, romstage, ramstage). They not only contain 107the stages themselves, but also additional files (eg. dsdt belongs to ramstage 108since that’s where it is used) 109 110Boot method manifest 111-------------------- 112The boot method manifest can subdivide the BIOS region, eg. using it directly 113(for coreboot’s “simple” bootblock), splitting it in two (for coreboot’s 114fallback/normal) or in many parts (for ChromeOS, which requires two CBFS 115regions, one for GBB, several for VPD, …). 116It also specifies which of the file lists specified earlier belong in which 117region (eg. with verstage verifying romstage, verstage needs to be only in 118ChromeOS’ RO region, while romstage belongs in RO and both RW regions). 119It can also specify a post processing step that is executed before the 120chipset’s. 121 122Payload and additional manifests 123-------------------------------- 124External components should also provide manifests to add files to categories. 125This way the payload and other components (eg. EC firmware) can be developed 126without needing to touch the central boot method manifest (that likely resides 127in the coreboot tree, given that coreboot needs to deal with choosing fmap 128regions already). 129 130coreboot build system 131--------------------- 132The coreboot build system will be split more distinctly in two phases: The 133first is about building the files (with results like romstage.elf), while the 134second phase covers the assembly of the final image. 135 136By having a global picture of the final image’s requirements, we can also 137avoid issues where files added earlier may prevent later additions that have 138stricter constraints - without resorting to hacks like 139https://chromium-review.googlesource.com/289491 that reorder the file addition 140manually. 141 142Example 143------- 144As an example, we’ll define an Intel-based board with a postprocessing tool 145(something that doesn’t exist, but isn’t hard to imagine): 146 147It specifies an IFD region, an ME, and the BIOS region. After the image is 148built, the entire image needs to be processed (although the tool likely works 149only on a small part of it) 150 151It’s built in a ChromeOS-like configuration (simplified at places to avoid 152distracting from the important parts), so it has three CBFS regions, and 153several data regions for its own purpose (similar to GBB, FWID, VPD, …). After 154the regions are filled, one data region must be post-processed to contain 155signatures to enable verifying other regions. 156 157``` 158Chipset manifest 159================ 160# A region called IFD, starting at 0, ending at 4K 161region IFD: 0 4K 162# Add the specified file “raw” into the region. 163# If the file is smaller than the region, put it at the bottom and fill up 164# with 0xff 165raw IFD: build/ifd.bin align=bottom empty=0xff 166# Call the postprocessor on the data that ends up in IFD (in this example it 167# might lock the IFD) 168postprocess IFD: util/ifdprocess -l 169 170# a region called ME, starting at 4K, ending at 2M 171region ME: 4K 2M 172raw ME: 3rdparty/blobs/soc/intel/xanadu/me.bin align=bottom empty=0x00 173 174# a region called BIOS, starting at 2M, filling up the free space 175# filling up fails (build error) if two regions are requested to fill up 176# against each other 177region BIOS: 2M * 178 179# This would define a region that covers the last 4K of flash. 180# The BIOS region specified above will end right before it instead of 181# expanding to end of flash 182# region AUX: -4K -0 183 184# specify the tool that post-processes the entire image. 185postprocess image: util/intelchksum/intelchksum.sh 186 187coreboot manifest 188================= 189# declare that build/verstage.elf belongs into the group ‘verstage’ 190# these groups are later referred to by the “cbfs” command. 191group verstage: build/verstage.elf stage xip name=fallback/verstage 192group romstage: build/romstage.elf stage xip name=fallback/romstage 193group ramstage: build/ramstage.elf stage name=fallback/ramstage 194compression=lzma 195group ramstage: build/dsdt.aml compression=lzma 196 197boot method manifest 198==================== 199# Define RO as region inside BIOS, covering the upper half of the image. 200# It’s a build error if the result crosses outside BIOS. 201# math expressions are wrapped with ( ), 202# and mentions of regions therein always refer to their size 203subregion BIOS RO: ( image / 2 ) -0 204 205# Define RW to cover the rest of BIOS. 206# The order of RW and RO doesn’t matter except to keep comments clearer. 207# Dynamic items like RW (“*”) will be sized to fill unused space after 208# everything else is placed. 209subregion BIOS RW: 0 * 210 211# It may be necessary to separate the RO/RW definition into another manifest 212# file 213# that defines the RO configuration of the flash 214 215# Some more subregions, with dynamically calculated sizes 216subregion RW RW_A: 0 ( RW / 2 ) 217subregion RW RW_B: * -0 218subregion RW_A FW_MAIN_A: RW_A * -0 219subregion RW_A VBLOCK_A: 0 64K 220# foo +bar specifies start + size, not (start, end) 221# also, start is given as “the end of VBLOCK_A” 222# (while using a region in the “end” field means “start of region”) 223subregion RW_A FWID_A: VBLOCK_A +64 224 225# To make the example not too verbose, RO only has the CBFS region 226subregion RO BOOTSTUB: 0 * 227 228# Postprocess the data that ends up in VBLOCK_A, 229# passing the listed regions as additional arguments. 230# Circular dependencies are build errors. 231postprocess VBLOCK_A(FW_MAIN_A): signtool 232 233# binding files to regions indirectly through groups 234cbfs BOOTSTUB: verstage, romstage, ramstage, payload 235cbfs FW_MAIN_A: romstage, ramstage, payload 236 237# defining defaults: unless overridden, in all regions that use CBFS (“*”), 238# we want all files to come with SHA256 hashes. 239# Wildcard defaults have lower priority than specific defaults. 240# Other conflicts lead to a build error. 241cbfsdefaults *: hash=sha3 242 243payload manifest 244================ 245group payload: payload.elf payload 246group payload: bootscreen.jpg name=splashscreen.jpg type=splashscreen 247 248EC firmware manifest 249==================== 250# overrides the cbfsdefault above 251group payload: ecrw.bin name=ecrw hash=sha256 252group payload: pdrw.bin name=pdrw hash=sha256 253``` 254 255manifest parsing 256---------------- 257The exact BNF is work in progress. 258 259Some parser rules are 260* one line per statement 261* '#' introduces a command until the end of line 262 263Some processing rules 264* When there’s a conflict (eg. two statements on what to do to a region, 265 overlap, anything that can’t be determined), that is a build error. 266* the order of statements doesn’t matter, enabling simple addition of more 267 manifests where the need arises. 268 269
