1# The coreboot build system 2(this document is still incomplete and will be filled in over time) 3 4## General operation 5The coreboot build system is based on GNU make but extends it significantly 6to the point of providing its own custom language. 7The overhead of learning this new syntax is (hopefully) offset by its lower 8complexity. 9 10The build system is defined in the toplevel `Makefile` and `toolchain.mk` 11and is supposed to be generic (and is in fact used with a number of other 12projects). Project specific configuration should reside in files called 13`Makefile.mk`. 14 15In general, the build system provides a number of "classes" that describe 16various parts of the build. These cover the various build targets in coreboot 17such as the stages, subdirectories with more source code, and the general 18addition of files. 19 20Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used 21by filling in a variable of that name followed by `-y` (eg. `romstage-y`, 22`subdirs-y`, `cbfs-files-y`). 23The `-y` suffix allows a simple interaction with our Kconfig build 24configuration system: Kconfig options are available as variables starting 25with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty. 26 27This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to 28`class` depending on the choice for `FOO`. 29 30## classes 31Classes can be defined as required. `subdirs` is handled internally since 32it's parsed per subdirectory to add further directories to the rule set. 33 34TODO: explain how to create new classes and how to evaluate them. 35 36### subdirs 37`subdirs` contains subdirectories (relative to the current directory) that 38should also be handled by the build system. The build system expects these 39directories to contain a file called `Makefile.mk`. 40 41Subdirectories are not read at the point where the `subdirs` statement 42resides but later, after the current directory is handled (and potentially 43others, too). 44 45### cbfs-files 46This class is used to add files to the final CBFS image. Since several more 47options need to be maintained than can comfortably fit in that single 48variable, additional variables are used. 49 50`cbfs-files-y` contains the file name used in the CBFS image (called `foo` 51here). Additional options are added in `foo-$(option)` variables. The 52supported options are: 53 54* `file`: The on-disk file to add as `foo` (required) 55* `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary` 56 (required) 57* `compression`: Can be `none` or `lzma` (default: none) 58* `position`: An absolute position constraint for the placement of the file 59 (default: none) 60* `align`: Minimum alignment for the file (default: none) 61* `options`: Additional cbfstool options (default: none) 62 63`position` and `align` are mutually exclusive. 64 65### Adding Makefile fragments 66 67You can use the `add_intermediate` helper to add new post-processing steps for 68the final `coreboot.rom` image. For example you can add new files to CBFS by 69adding something like this to `site-local/Makefile.mk` 70 71``` 72$(call add_intermediate, add_mrc_data) 73 $(CBFSTOOL) $< write -r RW_MRC_CACHE -f site-local/my-mrc-recording.bin 74``` 75 76Note that the second line must start with a tab, not spaces. 77 78```{eval-rst} 79See also :doc:`../tutorial/managing_local_additions`. 80``` 81 82#### FMAP region support 83With the addition of FMAP flash partitioning support to coreboot, there was a 84need to extend the specification of files to provide more precise control 85which regions should contain which files, and even change some flags based on 86the region. 87 88Since FMAP policies depend on features using FMAP, that's kept separate from 89the cbfs-files class. 90 91The `position` and `align` options for file `foo` can be overwritten for a 92region `REGION` using `foo-REGION-position` and `foo-REGION-align`. 93 94The regions that each file should end in can be defined by overriding a 95function called `regions-for-file` that's called as 96`$(call regions-for-file,$(filename))` and should return a comma-separated 97list of regions, such as `REGION1,REGION2,REGION3`. 98 99The default implementation just returns `COREBOOT` (the default region) for 100all files. 101 102vboot provides its own implementation of `regions-for-file` that can be used 103as reference in `src/vboot/Makefile.mk`. 104