Documentation/getting_started/build_system.md

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