Patrick Georgi has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 1:
(5 comments)
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md File Documentation/flashmap.md:
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md@3 PS1, Line 3: ## Flashmap
Add a high-level overview of the relationship between FMAP & CBFS. […]
I can provide a follow up to fill in the fmap/cbfs things and the what and how.
There is not really an "IFD integration", just in so far as that both structures can point out the same toplevel layout.
I'd also move stuff (this and other things) around to clean out the toplevel namespace (eg. cbfs, ifd, timestamps, untrusted input in SMM)
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md@6 PS1, Line 6: originally developed for Chromium OS fmap predates Chromium OS, but it came into coreboot for CrOS.
How about:
[FMAP](https://code.google.com/p/flashmap) is a binary format to describe partitions in a flash chip. It was added to coreboot to support the requirements of Chromium OS firmware but then was also used in other scenarios where precise placement of data in flash was necessary, or for data that is written to at runtime, as CBFS is considered too fragile for such situations.
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md@8 PS1, Line 8: s, for plural (outside the ``)
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md@34 PS1, Line 34: scanner, parser, semantic : analyzer, and I'd drop all those and just stick with the converter. Scanner, parser etc are part of it.
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md@54 PS1, Line 54: 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()`. I guess this should be replaced with something more practical: some actual example (a simplified chromeos.fmd, maybe), an explanation of what's going on in that example, and a plain reference to fmd_scanner.{l,y} (without fluff about "PL people") for those who want the formal description of the language.