diff options
author | Sol Boucher <solb@chromium.org> | 2015-02-26 11:47:19 -0800 |
---|---|---|
committer | Patrick Georgi <pgeorgi@google.com> | 2015-05-08 19:55:42 +0200 |
commit | 69b88bf1276d2cb0309e2fc96df9d33a893138e3 (patch) | |
tree | 2dc297765cb1f858e5f2f6865481eeafdad8e897 /util/cbfstool/README.fmaptool | |
parent | 5f7e4f019e258a49fff78e90509d1fda280fc147 (diff) | |
download | coreboot-69b88bf1276d2cb0309e2fc96df9d33a893138e3.tar.gz coreboot-69b88bf1276d2cb0309e2fc96df9d33a893138e3.tar.bz2 coreboot-69b88bf1276d2cb0309e2fc96df9d33a893138e3.zip |
fmaptool: Introduce the fmd ("flashmap descriptor") language and compiler
This adds a compiler for a language whose textual representation of flashmap
regions will be used to describe the layout of flash chips that contain more
than just a single CBFS. Direct integration with cbfstool (via a new
command-line switch for the create action) is forthcoming but will be added
separately.
BUG=chromium:461875
TEST=Use Chromium OS's cros_bundle_firmware script on the fmap.dts file for
panther. Using the latter file as a reference, write a corresponding
fmap.fmd file and feed it through fmaptool. Run both binary output files
though the flashmap project's own flashmap_decode utility. Observe only
the expected differences.
BRANCH=None
Change-Id: I06b32d138dbef0a4e5ed43c81bd31c796fd5d669
Signed-off-by: Sol Boucher <solb@chromium.org>
Original-Commit-Id: 005ab67eb594e21489cf31036aedaea87e0c7142
Original-Change-Id: Ia08f28688efdbbfc70c255916b8eb7eb0eb07fb2
Original-Signed-off-by: Sol Boucher <solb@chromium.org>
Original-Reviewed-on: https://chromium-review.googlesource.com/255031
Original-Reviewed-by: Julius Werner <jwerner@chromium.org>
Original-Reviewed-by: Stefan Reinauer <reinauer@chromium.org>
Reviewed-on: http://review.coreboot.org/9942
Tested-by: build bot (Jenkins)
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Diffstat (limited to 'util/cbfstool/README.fmaptool')
-rw-r--r-- | util/cbfstool/README.fmaptool | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/util/cbfstool/README.fmaptool b/util/cbfstool/README.fmaptool new file mode 100644 index 000000000000..f806c43d78bc --- /dev/null +++ b/util/cbfstool/README.fmaptool @@ -0,0 +1,67 @@ +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>[@<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>[(CBFS)][@...] [...] [{...}] + }] + [<subsection name>[(CBFS)][@...] [...] [{...}]] + # 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. + - In particular, it is only legal to place a (CBFS) annotation on a leaf section; that is, choosing + to add child sections excludes the possibility of putting a CBFS in their parent. Such + annotations 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(). |