Hung-Te Lin has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/31766
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Documentation: Explain FMAP and FMD
The Flashmap (FMAP) was not clearly documented. The new flashmap.md explains where to find more details about that and how / why it was used in coreboot. Also explained what is FMD and how to use it.
BUG=None TEST=None (only documentation).
Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin hungte@chromium.org --- A Documentation/flashmap.md M Documentation/index.md D util/cbfstool/README.fmaptool 3 files changed, 116 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/1
diff --git a/Documentation/flashmap.md b/Documentation/flashmap.md new file mode 100644 index 0000000..c6780b6 --- /dev/null +++ b/Documentation/flashmap.md @@ -0,0 +1,115 @@ +# Flashmap and Flashmap Descriptor in coreboot + +## Flashmap + +[Flashmap](https://code.google.com/p/flashmap) (FMAP) is a binary format +originally developed for Chromium OS to manipulate firmware image and to +represent the layout of flash chips. With Flashmap, the firmware image is split +into multiple `fmap_area` (may also be referred as 'regions', or 'sections'). +Each area has a name, offset, size and 16 bits of flags. + +coreboot puts most data in the CBFS structure. But many systems, especially +Chromium OS, need some area to be created in different format and layout. For +example, Chromium OS has defined a key-value style "Vital Product Data" (VPD) +that cannot live inside CBFS. Intel firmware also usually need a place to put +the firmware for management engine. Some ARM SOCs also need to preserve +calibration data in the fixed location. This is very helpful to manipulate +non-coreboot data. + +As a result, Flashmap is now directly supported by coreboot, and is the +de facto standard FMAP implementation. + +## Flashmap Descriptor + +Since coreboot is starting to use a "partition" of Flashmap to describe the +flash chip layout (both at runtime and when flashing a new image onto a +chip), the project needs a reasonably expressive plain text format for +representing such sections in the source tree. + +Flashmap Descriptor (FMD) is a [language and +compiler](https://chromium-review.googlesource.com/#/c/255031) inside coreboot +utility folder that can be used to generate final firmware images (i.e. +`coreboot.rom`) formatted by Flashmap. + +The FMD in coreboot `utils` folder contains a scanner, parser, semantic +analyzer, and Flashmap converter. Here's an informal language description: + +``` +# <line comment> +<image name>[@<memory-mapped address>] <image size> { + <section name>[(flags)][@<offset from start of image>] [<section size>] [{ + <subsection name>[@<offset from start of parent section>] [<subsection size>] [{ + # Sections can be nested as deeply as desired + <subsubsection name>[(flags)][@...] [...] [{...}] + }] + [<subsection name>[(flags)][@...] [...] [{...}]] + # There can be many subsections at each level of nesting: they will be inserted + # sequentially, and although gaps are allowed, any provided offsets are always + # relative to the closest parent node's and must be strictly increasing with neither + # overlapping nor degenerate-size sections. + }] +} +``` + +Note that the above example contains a few symbols that are actually meta +syntax, and therefore have neither meaning nor place in a real file. The `<.*>`s +indicate placeholders for parameters: + +* The names are strings, which are provided as single-word (no white space) + groups of syntactically unimportant symbols (i.e. every thing except `@`, `{`, + and `}`): they are not surrounded by quotes or any other form of delimiter. +* The other fields are non-negative integers, which may be given as decimal or + hexadecimal; in either case, a `K`, `M`, or `G` may be appended (without + intermediate white space) as a multiplier. +* Comments consist of anything one manages to enter, provided it doesn't start a + new line. + +The `[.*]`s indicate that a portion of the file could be omitted altogether: + +* Just because something is noted as optional doesn't mean it is in every case: + the answer might actually depend on which other information is---or + isn't---provided. +* The "flag" specifies the attribute or type for given section. The most + important supported flag is "CBFS", which indicates the section will contain + a CBFS structure. +* In particular, it is only legal to place a (CBFS) flag on a leaf section; that + is, choosing to add child sections excludes the possibility of putting a CBFS + in their parent. Such flags are only used to decide where CBFS empty file + headers should be created, and do not result in the storage of any additional + metadata in the resulting FMAP section. + +Additionally, it's important to note these properties of the overall file and +its values: + +* Other than within would-be strings and numbers, white space is ignored. It + goes without saying that such power comes with responsibility, which is why + this sentence is here. +* Although the `section name` must be globally unique, one of them may (but is + not required to) match the image name. +* It is a syntax error to supply a number (besides 0) that begins with the + character `0`, as there is no intention of adding octals to the mix. +* The image's memory address should be present on (and only on) layouts for + memory-mapped chips. +* Although it may be evident from above, all `section` offsets are relative only + to the immediate parent. There is no way to include an absolute offset (i.e. + from the beginning of flash), which means that it is "safe" to reorder the + sections within a particular level of nesting, as long as the change doesn't + cause their positions and sizes to necessitate overlap or zero sizes. +* A `section` with omitted offset is assumed to start at as low a position as + possible (with no consideration of alignment) and one with omitted size is + assumed to fill the remaining space until the next sibling or before the end + of its parent. +* It's fine to omit any `section`'s offset, size, or both, provided its position + and size are still unambiguous in the context of its *sibling* sections and + its parent's *size*. In particular, knowledge of one .*section 's children or + the `section`s' common parent's siblings will not be used for this purpose. +* Although `section`s are not required to have children, the flash chip as a + whole must have at least one. +* Though the braces after `section`s may be omitted for those that have no + children, if they are present, they must contain at least one child. + +PL people and sympathizers may wish to examine the formal abstract syntax and +context-free grammar, which are located in `fmd_scanner.l` and `fmd_scanner.y`, +respectively. Those interested in the algorithm used to infer omitted values +will feel at home in `fmd.c`, particularly near the definition of +`validate_and_complete_info()`. diff --git a/Documentation/index.md b/Documentation/index.md index dd8714c..9398458 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -186,3 +186,4 @@ * [Utilities](util.md) * [Release notes for past releases](releases/index.md) * [Flashing firmware tutorial](flash_tutorial/index.md) +* [Flashmap and Flashmap Descriptor](flashmap.md) diff --git a/util/cbfstool/README.fmaptool b/util/cbfstool/README.fmaptool deleted file mode 100644 index 86fc3b2..0000000 --- a/util/cbfstool/README.fmaptool +++ /dev/null @@ -1,69 +0,0 @@ -Flashmap descriptors in coreboot -================================ -Flashmap (https://code.google.com/p/flashmap) is a binary format for representing the layout of -flash chips. Since coreboot is starting to use a "partition" of this format to describe the flash -chip layout---both at runtime and when flashing a new image onto a chip---, the project needed a -reasonably expressive plaintext format for representing such sections in the source tree. Our -solution is the fmd ("flashmap descriptor") language, and the files in this directory contain a -scanner, parser, semantic analyser, and flashmap converter. Here's an informal language description: - -# <line comment> -<image name>[@<memory-mapped address>] <image size> { - <section name>[(flags)][@<offset from start of image>] [<section size>] [{ - <subsection name>[@<offset from start of parent section>] [<subsection size>] [{ - # Sections can be nested as deeply as desired - <subsubsection name>[(flags)][@...] [...] [{...}] - }] - [<subsection name>[(flags)][@...] [...] [{...}]] - # There can be many subsections at each level of nesting: they will be inserted - # sequentially, and although gaps are allowed, any provided offsets are always - # relative to the closest parent node's and must be strictly increasing with neither - # overlapping nor degenerate-size sections. - }] -} - -Note that the above example contains a few symbols that are actually metasyntax, and therefore have -neither meaning nor place in a real file. The <.*> s indicate placeholders for parameters: - - The names are strings, which are provided as single-word---no whitespace---groups of - syntactically unimportant symbols (i.e. everything except @, {, and }): they are not surrounded - by quotes or any other form of delimiter. - - The other fields are nonnegative integers, which may be given as decimal or hexadecimal; in - either case, a K, M, or G may be appended---without intermediate whitespace---as a multiplier. - - Comments consist of anything one manages to enter, provided it doesn't start a new line. -The [.*] s indicate that a portion of the file could be omitted altogether: - - Just because something is noted as optional doesn't mean it is in every case: the answer might - actually depend on which other information is---or isn't---provided. - - The "flag" specifies the attribute or type for given section. The most - important supported flag is "CBFS", which indicates the section will contain a CBFS structure. - - In particular, it is only legal to place a (CBFS) flag on a leaf section; that is, choosing - to add child sections excludes the possibility of putting a CBFS in their parent. Such - flags are only used to decide where CBFS empty file headers should be created, and do not - result in the storage of any additional metadata in the resulting FMAP section. -Additionally, it's important to note these properties of the overall file and its values: - - Other than within would-be strings and numbers, whitespace is ignored. It goes without saying - that such power comes with responsibility, which is why this sentence is here. - - Although the .*section names must be globally unique, one of them may---but is not required to--- - match the image name. - - It is a syntax error to supply a number---besides 0---that begins with the character 0, as there - is no intention of adding octals to the mix. - - The image's memory address should be present on---and only on---layouts for memory-mapped chips. - - Although it may be evident from above, all .*section offsets are relative only to the immediate - parent. There is no way to include an absolute offset (i.e. from the beginning of flash), which - means that it is "safe" to reorder the .*section s within a particular level of nesting, as long - as the change doesn't cause their positions and sizes to necessitate overlap or zero sizes. - - A .*section with omitted offset is assumed to start at as low a position as possible---with no - consideration of alignment---and one with omitted size is assumed to fill the remaining space - until the next sibling or before the end of its parent. - - It's fine to omit any .*section 's offset, size, or both, provided its position and size are - still unambiguous in the context of its *sibling* sections and its parent's *size*. In - particular, knowledge of one .*section 's children or the .*section s' common parent's siblings - will not be used for this purpose. - - Although .*section s are not required to have children, the flash chip as a whole must have at - least one. - - Though the braces after .*section s may be omitted for those that have no children, if they are - present, they must contain at least one child. - -PL people and sympathizers may wish to examine the formal abstract syntax and context-free grammar, -which are located in fmd_scanner.l and fmd_scanner.y, respectively. Those interested in the -algorithm used to infer omitted values will feel at home in fmd.c, particularly near the definition -of validate_and_complete_info().