Hung-Te Lin has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 3:
(6 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@6 PS1, Line 6: originally developed for Chromium OS
fmap predates Chromium OS, but it came into coreboot for CrOS. […]
Done
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md@8 PS1, Line 8:
s, for plural (outside the ``)
Done
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md@17 PS1, Line 17: non-coreboot data.
I think some of this may have been written before CBFS was fully integrated into FMAP and could prob […]
Done
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.
Done
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 chr […]
These were copied from README.fmaptool so I'd like to keep them as the first version of doc. Feel free to revise that in follow up changes.
https://review.coreboot.org/#/c/31766/1/Documentation/index.md File Documentation/index.md:
https://review.coreboot.org/#/c/31766/1/Documentation/index.md@189 PS1, Line 189: * [Flashmap and Flashmap Descriptor](flashmap.md)
Create a namespace called "Library-specific documentation" for it. […]
Done