Sol Boucher | 69b88bf | 2015-02-26 11:47:19 -0800 | [diff] [blame] | 1 | Flashmap descriptors in coreboot |
| 2 | ================================ |
| 3 | Flashmap (https://code.google.com/p/flashmap) is a binary format for representing the layout of |
| 4 | flash chips. Since coreboot is starting to use a "partition" of this format to describe the flash |
| 5 | chip layout---both at runtime and when flashing a new image onto a chip---, the project needed a |
| 6 | reasonably expressive plaintext format for representing such sections in the source tree. Our |
| 7 | solution is the fmd ("flashmap descriptor") language, and the files in this directory contain a |
| 8 | scanner, parser, semantic analyser, and flashmap converter. Here's an informal language description: |
| 9 | |
| 10 | # <line comment> |
| 11 | <image name>[@<memory-mapped address>] <image size> { |
| 12 | <section name>[@<offset from start of image>] [<section size>] [{ |
| 13 | <subsection name>[@<offset from start of parent section>] [<subsection size>] [{ |
| 14 | # Sections can be nested as deeply as desired |
| 15 | <subsubsection name>[(CBFS)][@...] [...] [{...}] |
| 16 | }] |
| 17 | [<subsection name>[(CBFS)][@...] [...] [{...}]] |
| 18 | # There can be many subsections at each level of nesting: they will be inserted |
| 19 | # sequentially, and although gaps are allowed, any provided offsets are always |
| 20 | # relative to the closest parent node's and must be strictly increasing with neither |
| 21 | # overlapping nor degenerate-size sections. |
| 22 | }] |
| 23 | } |
| 24 | |
| 25 | Note that the above example contains a few symbols that are actually metasyntax, and therefore have |
| 26 | neither meaning nor place in a real file. The <.*> s indicate placeholders for parameters: |
| 27 | - The names are strings, which are provided as single-word---no whitespace---groups of |
| 28 | syntactically unimportant symbols (i.e. everything except @, {, and }): they are not surrounded |
| 29 | by quotes or any other form of delimiter. |
| 30 | - The other fields are nonnegative integers, which may be given as decimal or hexadecimal; in |
| 31 | either case, a K, M, or G may be appended---without intermediate whitespace---as a multiplier. |
| 32 | - Comments consist of anything one manages to enter, provided it doesn't start a new line. |
| 33 | The [.*] s indicate that a portion of the file could be omitted altogether: |
| 34 | - Just because something is noted as optional doesn't mean it is in every case: the answer might |
| 35 | actually depend on which other information is---or isn't---provided. |
| 36 | - In particular, it is only legal to place a (CBFS) annotation on a leaf section; that is, choosing |
| 37 | to add child sections excludes the possibility of putting a CBFS in their parent. Such |
| 38 | annotations are only used to decide where CBFS empty file headers should be created, and do not |
| 39 | result in the storage of any additional metadata in the resulting FMAP section. |
| 40 | Additionally, it's important to note these properties of the overall file and its values: |
| 41 | - Other than within would-be strings and numbers, whitespace is ignored. It goes without saying |
| 42 | that such power comes with responsibility, which is why this sentence is here. |
| 43 | - Although the .*section names must be globally unique, one of them may---but is not required to--- |
| 44 | match the image name. |
| 45 | - It is a syntax error to supply a number---besides 0---that begins with the character 0, as there |
| 46 | is no intention of adding octals to the mix. |
| 47 | - The image's memory address should be present on---and only on---layouts for memory-mapped chips. |
| 48 | - Although it may be evident from above, all .*section offsets are relative only to the immediate |
| 49 | parent. There is no way to include an absolute offset (i.e. from the beginning of flash), which |
| 50 | means that it is "safe" to reorder the .*section s within a particular level of nesting, as long |
| 51 | as the change doesn't cause their positions and sizes to necessitate overlap or zero sizes. |
| 52 | - A .*section with omitted offset is assumed to start at as low a position as possible---with no |
| 53 | consideration of alignment---and one with omitted size is assumed to fill the remaining space |
| 54 | until the next sibling or before the end of its parent. |
| 55 | - It's fine to omit any .*section 's offset, size, or both, provided its position and size are |
| 56 | still unambiguous in the context of its *sibling* sections and its parent's *size*. In |
| 57 | particular, knowledge of one .*section 's children or the .*section s' common parent's siblings |
| 58 | will not be used for this purpose. |
| 59 | - Although .*section s are not required to have children, the flash chip as a whole must have at |
| 60 | least one. |
| 61 | - Though the braces after .*section s may be omitted for those that have no children, if they are |
| 62 | present, they must contain at least one child. |
| 63 | |
| 64 | PL people and sympathizers may wish to examine the formal abstract syntax and context-free grammar, |
| 65 | which are located in fmd_scanner.l and fmd_scanner.y, respectively. Those interested in the |
| 66 | algorithm used to infer omitted values will feel at home in fmd.c, particularly near the definition |
| 67 | of validate_and_complete_info(). |