Documentation/lib/flashmap.md

   1 # Flashmap and Flashmap Descriptor in coreboot
   2
   3 ## Flashmap
   4
   5 [Flashmap](https://code.google.com/p/flashmap) (FMAP) is a binary format to
   6 describe partitions in a flash chip. It was added to coreboot to support the
   7 requirements of ChromiumOS firmware but then was also used in other scenarios
   8 where precise placement of data in flash was necessary, or for data that is
   9 written to at runtime, as CBFS is considered too fragile for such situations.
  10 The Flashmap implementation inside coreboot is the de facto standard today.
  11
  12 Flashmap partitions the image into clearly delimited sections and some of those
  13 sections may be CBFSes that can hold arbitrary-length files (at least one, the
  14 default CBFS, called `COREBOOT`). General guidance is that everything with
  15 strict layout requirements (e.g. must be aligned to erase blocks or
  16 something else) should have its own Flashmap section, and everything else should
  17 normally go into CBFS.
  18
  19 The Flashmap itself starts with a header `struct fmap` and followed by a list of
  20 section descriptions in `struct fmap_area`. All fields in those structures are
  21 in little endian format.
  22
  23 ### Header
  24 The header `struct fmap` has following fields:
  25 * `signature`: 8 characters as `"__FMAP__"`.
  26 * `ver_major`: one byte for major version (currently only 1).
  27 * `ver_minor`: one byte for minor version (current value is 1).
  28 * `base`: 64 bit integer for the address of the firmware binary.
  29 * `size`: 32 bit integer for the size of firmware binary in bytes.
  30 * `name`: 32 characters for the name of the firmware binary.
  31 * `nareas`: 16 bit integer for the number of area definitions (i.e., how many
  32   sections are in this firmware image) following the header.
  33
  34 ### Area Definition
  35 The section is defined by `struct fmap_area` with following fields:
  36 * `offset`: 32 bit integer for where the area starts (relative to `base` in
  37   header).
  38 * `size`: 32 bit integer for the size of area in bytes.
  39 * `name`: 32 characters for a descriptive name of this area. Should be unique to
  40   all sections inside same Flashmap.
  41 * `flags`: 16 bit integer for attributes of this area (see below).
  42
  43 ### Area Flags
  44 Currently the defined values for `flags` in `struct fmap_area` are:
  45 * `FMAP_AREA_PRESERVE`: suggesting the section should be preserved when
  46   updating firmware, usually for product data like serial number, MAC address,
  47   or calibration and cache data.
  48 * `FMAP_AREA_STATIC`: Not really used today.
  49 * `FMAP_AREA_COMPRESSED`: Not really used today.
  50 * `FMAP_AREA_RO`: Not really used today.
  51
  52 ### FMAP section
  53 The whole Flashmap (`struct fmap` and list of `struct fmap_area`) should be
  54 stored in a standalone section named as `FMAP` (which should be also described
  55 by the Flashmap itself in `struct fmap_area`). There's no restriction for where
  56 it should be located (or how large), but usually we need to do a linear or
  57 binary search on whole firmware binary image to find Flashmap so a properly
  58 aligned address would be better.
  59
  60 ### COREBOOT section
  61 coreboot firmware images (`coreboot.rom`) should have at least one Flashmap
  62 section that is reserved for CBFS. Usually it is named as `COREBOOT`.
  63
  64 ## Flashmap Descriptor
  65
  66 Since coreboot is starting to use a "partition" of Flashmap to describe the
  67 flash chip layout (both at runtime and when flashing a new image onto a
  68 chip), the project needs a reasonably expressive plain text format for
  69 representing such sections in the source tree.
  70
  71 Flashmap Descriptor (FMD) is a [language and
  72 compiler](https://chromium-review.googlesource.com/#/c/255031) inside coreboot
  73 utility folder that can be used to generate final firmware images (i.e.
  74 `coreboot.rom`) formatted by Flashmap.
  75
  76 The FMD implementation is in coreboot `utils/cbfstool` folder. Here's an
  77 informal language description:
  78
  79 ```
  80 # <line comment>
  81 <image name>[@<memory-mapped address>] <image size> {
  82     <section name>[(flags)][@<offset from start of image>] [<section size>] [{
  83         <subsection name>[@<offset from start of parent section>] [<subsection size>] [{
  84             # Sections can be nested as deeply as desired
  85             <subsubsection name>[(flags)][@...] [...] [{...}]
  86         }]
  87         [<subsection name>[(flags)][@...] [...] [{...}]]
  88         # There can be many subsections at each level of nesting: they will be inserted
  89         # sequentially, and although gaps are allowed, any provided offsets are always
  90         # relative to the closest parent node's and must be strictly increasing with neither
  91         # overlapping nor degenerate-size sections.
  92     }]
  93 }
  94 ```
  95
  96 Note that the above example contains a few symbols that are actually meta
  97 syntax, and therefore have neither meaning nor place in a real file. The `<.*>`s
  98 indicate placeholders for parameters:
  99
 100 * The names are strings, which are provided as single-word (no white space)
 101   groups of syntactically unimportant symbols (i.e. every thing except `@`, `{`,
 102   and `}`): they are not surrounded by quotes or any other form of delimiter.
 103 * The other fields are non-negative integers, which may be given as decimal or
 104   hexadecimal; in either case, a `K`, `M`, or `G` may be appended (without
 105   intermediate white space) as a multiplier.
 106 * Comments consist of anything one manages to enter, provided it doesn't start a
 107   new line.
 108
 109 The `[.*]`s indicate that a portion of the file could be omitted altogether:
 110
 111 * Just because something is noted as optional doesn't mean it is in every case:
 112   the answer might actually depend on which other information is---or
 113   isn't---provided.
 114 * The "flag" specifies the attribute or type for given section. The most
 115   important supported flag is "CBFS", which indicates the section will contain
 116   a CBFS structure.
 117 * In particular, it is only legal to place a (CBFS) flag on a leaf section; that
 118   is, choosing to add child sections excludes the possibility of putting a CBFS
 119   in their parent. Such flags are only used to decide where CBFS empty file
 120   headers should be created, and do not result in the storage of any additional
 121   metadata in the resulting FMAP section.
 122
 123 Additionally, it's important to note these properties of the overall file and
 124 its values:
 125
 126 * Other than within would-be strings and numbers, white space is ignored. It
 127   goes without saying that such power comes with responsibility, which is why
 128   this sentence is here.
 129 * Although the `section name` must be globally unique, one of them may (but is
 130   not required to) match the image name.
 131 * It is a syntax error to supply a number (besides 0) that begins with the
 132   character `0`, as there is no intention of adding octals to the mix.
 133 * The image's memory address should be present on (and only on) layouts for
 134   memory-mapped chips.
 135 * Although it may be evident from above, all `section` offsets are relative only
 136   to the immediate parent. There is no way to include an absolute offset (i.e.
 137   from the beginning of flash), which means that it is "safe" to reorder the
 138   sections within a particular level of nesting, as long as the change doesn't
 139   cause their positions and sizes to necessitate overlap or zero sizes.
 140 * A `section` with omitted offset is assumed to start at as low a position as
 141   possible (with no consideration of alignment) and one with omitted size is
 142   assumed to fill the remaining space until the next sibling or before the end
 143   of its parent.
 144 * It's fine to omit any `section`'s offset, size, or both, provided its position
 145   and size are still unambiguous in the context of its *sibling* sections and
 146   its parent's *size*. In particular, knowledge of one .*section 's children or
 147   the `section`s' common parent's siblings will not be used for this purpose.
 148 * Although `section`s are not required to have children, the flash chip as a
 149   whole must have at least one.
 150 * Though the braces after `section`s may be omitted for those that have no
 151   children, if they are present, they must contain at least one child.
 152
 153 To see the formal description of the language, please refer to the Lex and Yacc
 154 files: `fmd_scanner.l` and `fmd_scanner.y`.