Documentation: add start of documentation of the build system
Change-Id: Ic4a4b4d71852bfe0b1fc52373e88d0a53b145844 Signed-off-by: Patrick Georgi <pgeorgi@chromium.org> Reviewed-on: https://review.coreboot.org/16150 Tested-by: build bot (Jenkins) Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
This commit is contained in:
parent
51fc93fb22
commit
1b52e2596e
|
@ -0,0 +1,86 @@
|
|||
# The coreboot build system
|
||||
(this document is still incomplete and will be filled in over time)
|
||||
|
||||
## General operation
|
||||
The coreboot build system is based on GNU make but extends it significantly
|
||||
to the point of providing its own custom language.
|
||||
The overhead of learning this new syntax is (hopefully) offset by its lower
|
||||
complexity.
|
||||
|
||||
The build system is defined in the toplevel `Makefile` and `toolchain.inc`
|
||||
and is supposed to be generic (and is in fact used with a number of other
|
||||
projects). Project specific configuration should reside in files called
|
||||
`Makefile.inc`.
|
||||
|
||||
In general, the build system provides a number of "classes" that describe
|
||||
various parts of the build. These cover the various build targets in coreboot
|
||||
such as the stages, subdirectories with more source code, and the general
|
||||
addition of files.
|
||||
|
||||
Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used
|
||||
by filling in a variable of that name followed by `-y` (eg. `romstage-y`,
|
||||
`subdirs-y`, `cbfs-files-y`).
|
||||
The `-y` suffix allows a simple interaction with our Kconfig build
|
||||
configuration system: Kconfig options are available as variables starting
|
||||
with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty.
|
||||
|
||||
This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to
|
||||
`class` depending on the choice for `FOO`.
|
||||
|
||||
## classes
|
||||
Classes can be defined as required. `subdirs` is handled internally since
|
||||
it's parsed per subdirectory to add further directories to the rule set.
|
||||
|
||||
TODO: explain how to create new classes and how to evaluate them.
|
||||
|
||||
### subdirs
|
||||
`subdirs` contains subdirectories (relative to the current directory) that
|
||||
should also be handled by the build system. The build system expects these
|
||||
directories to contain a file called `Makefile.inc`.
|
||||
|
||||
Subdirectories are not read at the point where the `subdirs` statement
|
||||
resides but later, after the current directory is handled (and potentially
|
||||
others, too).
|
||||
|
||||
### cbfs-files
|
||||
This class is used to add files to the final CBFS image. Since several more
|
||||
options need to be maintained than can comfortably fit in that single
|
||||
variable, additional variables are used.
|
||||
|
||||
`cbfs-files-y` contains the file name used in the CBFS image (called `foo`
|
||||
here). Additional options are added in `foo-$(option)` variables. The
|
||||
supported options are:
|
||||
|
||||
* `file`: The on-disk file to add as `foo` (required)
|
||||
* `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary`
|
||||
(required)
|
||||
* `compression`: Can be `none` or `lzma` (default: none)
|
||||
* `position`: An absolute position constraint for the placement of the file
|
||||
(default: none)
|
||||
* `align`: Minimum alignment for the file (default: none)
|
||||
* `options`: Additional cbfstool options (default: none)
|
||||
|
||||
`position` and `align` are mutually exclusive.
|
||||
|
||||
#### FMAP region support
|
||||
With the addition of FMAP flash partitioning support to coreboot, there was a
|
||||
need to extend the specification of files to provide more precise control
|
||||
which regions should contain which files, and even change some flags based on
|
||||
the region.
|
||||
|
||||
Since FMAP policies depend on features using FMAP, that's kept separate from
|
||||
the cbfs-files class.
|
||||
|
||||
The `position` and `align` options for file `foo` can be overwritten for a
|
||||
region `REGION` using `foo-REGION-position` and `foo-REGION-align`.
|
||||
|
||||
The regions that each file should end in can be defined by overriding a
|
||||
function called `regions-for-file` that's called as
|
||||
`$(call regions-for-file,$(filename))` and should return a comma-separated
|
||||
list of regions, such as `REGION1,REGION2,REGION3`.
|
||||
|
||||
The default implementation just returns `COREBOOT` (the default region) for
|
||||
all files.
|
||||
|
||||
vboot provides its own implementation of `regions-for-file` that can be used
|
||||
as reference in `src/vboot/Makefile.inc`.
|
Loading…
Reference in New Issue