summaryrefslogtreecommitdiff
path: root/util
diff options
context:
space:
mode:
authorHung-Te Lin <hungte@chromium.org>2019-03-06 00:06:13 +0800
committerPatrick Georgi <pgeorgi@google.com>2019-04-11 11:24:32 +0000
commit0043a3db20f0f38955845e2179b6c74b36ed23a7 (patch)
tree38c2e0d5c8669f4fb099a680eca1a56de7ab3ed4 /util
parenta751445de4df403182666e8bf1a81c1886f16c48 (diff)
downloadcoreboot-0043a3db20f0f38955845e2179b6c74b36ed23a7.tar.xz
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 (based on original README.fmaptool). BUG=None TEST=None (only documentation) Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin <hungte@chromium.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/31766 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Rudolph <siro@das-labor.org>
Diffstat (limited to 'util')
-rw-r--r--util/cbfstool/README.fmaptool69
1 files changed, 0 insertions, 69 deletions
diff --git a/util/cbfstool/README.fmaptool b/util/cbfstool/README.fmaptool
deleted file mode 100644
index 86fc3b2192..0000000000
--- 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().