Hung-Te Lin has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/31766
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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.
BUG=None TEST=None (only documentation).
Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin hungte@chromium.org --- A Documentation/flashmap.md M Documentation/index.md D util/cbfstool/README.fmaptool 3 files changed, 116 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/1
diff --git a/Documentation/flashmap.md b/Documentation/flashmap.md new file mode 100644 index 0000000..c6780b6 --- /dev/null +++ b/Documentation/flashmap.md @@ -0,0 +1,115 @@ +# Flashmap and Flashmap Descriptor in coreboot + +## Flashmap + +[Flashmap](https://code.google.com/p/flashmap) (FMAP) is a binary format +originally developed for Chromium OS to manipulate firmware image and to +represent the layout of flash chips. With Flashmap, the firmware image is split +into multiple `fmap_area` (may also be referred as 'regions', or 'sections'). +Each area has a name, offset, size and 16 bits of flags. + +coreboot puts most data in the CBFS structure. But many systems, especially +Chromium OS, need some area to be created in different format and layout. For +example, Chromium OS has defined a key-value style "Vital Product Data" (VPD) +that cannot live inside CBFS. Intel firmware also usually need a place to put +the firmware for management engine. Some ARM SOCs also need to preserve +calibration data in the fixed location. This is very helpful to manipulate +non-coreboot data. + +As a result, Flashmap is now directly supported by coreboot, and is the +de facto standard FMAP implementation. + +## Flashmap Descriptor + +Since coreboot is starting to use a "partition" of Flashmap to describe the +flash chip layout (both at runtime and when flashing a new image onto a +chip), the project needs a reasonably expressive plain text format for +representing such sections in the source tree. + +Flashmap Descriptor (FMD) is a [language and +compiler](https://chromium-review.googlesource.com/#/c/255031) inside coreboot +utility folder that can be used to generate final firmware images (i.e. +`coreboot.rom`) formatted by Flashmap. + +The FMD in coreboot `utils` folder contains a scanner, parser, semantic +analyzer, 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 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()`. diff --git a/Documentation/index.md b/Documentation/index.md index dd8714c..9398458 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -186,3 +186,4 @@ * [Utilities](util.md) * [Release notes for past releases](releases/index.md) * [Flashing firmware tutorial](flash_tutorial/index.md) +* [Flashmap and Flashmap Descriptor](flashmap.md) diff --git a/util/cbfstool/README.fmaptool b/util/cbfstool/README.fmaptool deleted file mode 100644 index 86fc3b2..0000000 --- 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().
Philipp Deppenwiese has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 1: Code-Review-2
(2 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. What about IFD integration? Why, What and How to use it. Examples of writing fmd files and so on
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. Not root directory linking for coreboot internals
Philipp Deppenwiese has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 1: -Code-Review
Julius Werner has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 1:
(1 comment)
https://review.coreboot.org/#/c/31766/1/Documentation/flashmap.md File Documentation/flashmap.md:
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 probably use a rewrite (if you have the time). It would be better to have less focus on history and more on the current state: the FMAP partitions the image into clearly delimited sections and some of those sections may be CBFSes that can hold arbitrary-length files (at least one, the default CBFS, called COREBOOT). General guidance is to make everything that has strict layout requirements (e.g. must be aligned to erase blocks or something else) should be its own FMAP section, and everything else should normally go into CBFS.
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.
Hello Philipp Deppenwiese, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/31766
to look at the new patch set (#2).
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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.
BUG=None TEST=None (only documentation).
Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin hungte@chromium.org --- M Documentation/index.md A Documentation/lib/flashmap.md A Documentation/lib/index.md D util/cbfstool/README.fmaptool 4 files changed, 161 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/2
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
Julius Werner has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 3:
(3 comments)
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md File Documentation/lib/flashmap.md:
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md@14 PS3, Line 14: to make everything that : has strict layout requirements (e.g. must be aligned to erase blocks or : something else) should be Sorry, I think you copied the grammar mistakes out of my comment. ;)
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md@20 PS3, Line 20: strcut typo
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md@45 PS3, Line 45: programmed (or after some security policy is enabled). Can we clarify that these first three are deprecated and (should) currently not (be) used by anyone? I'm honestly not sure what they were originally used for, if anything, but they don't seem to make sense in modern coreboot context. "COMPRESSED" is a single flag that doesn't tell you anything about the compression algorithm, so even if we wanted direct FMAP compression it would seem pointless. "RO" is usually better handled with nested sections since I don't think(?) we have any write-protection mechanism that can cover more than one region. And I don't really understand what "STATIC" was supposed to be in the first place.
Hello Philipp Deppenwiese, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/31766
to look at the new patch set (#4).
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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.
BUG=None TEST=None (only documentation).
Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin hungte@chromium.org --- M Documentation/index.md A Documentation/lib/flashmap.md A Documentation/lib/index.md D util/cbfstool/README.fmaptool 4 files changed, 164 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/4
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 4:
(1 comment)
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md File Documentation/lib/flashmap.md:
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md@20 PS3, Line 20: strcut
typo
Done
Hello David Hendricks, Philipp Deppenwiese, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/31766
to look at the new patch set (#5).
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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.
BUG=None TEST=None (only documentation).
Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin hungte@chromium.org --- M Documentation/index.md A Documentation/lib/flashmap.md A Documentation/lib/index.md D util/cbfstool/README.fmaptool 4 files changed, 167 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/5
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 5:
(2 comments)
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md File Documentation/lib/flashmap.md:
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md@14 PS3, Line 14: to make everything that : has strict layout requirements (e.g. must be aligned to erase blocks or : something else) should be
Sorry, I think you copied the grammar mistakes out of my comment. […]
Done
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md@45 PS3, Line 45: programmed (or after some security policy is enabled).
Can we clarify that these first three are deprecated and (should) currently not (be) used by anyone? […]
I'm not sure if they are deprecated. For example, all the WP_RO sections in chromeos.fmd may include FMAP_AREA_RO (and yes it's nested). It's probably just because we didn't have good tools before.
COMPRESSED - it may be still helpful to help people realizing "hey, you should not try a raw dump or execution for this section".
+dhendrix to see how we should revise the descriptions above.
Julius Werner has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 5:
(1 comment)
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md File Documentation/lib/flashmap.md:
https://review.coreboot.org/#/c/31766/3/Documentation/lib/flashmap.md@45 PS3, Line 45: programmed (or after some security policy is enabled).
For example, all the WP_RO sections in chromeos.fmd may include FMAP_AREA_RO (and yes it's nested).
But what does that actually say that isn't already said by the WP_RO region? Having multiple redundant ways to describe the same thing is not good -- it just opens up the possibility for inconsistencies. As long as Chrome OS factory scripts (and whatever else wants to read WP information from the FMAP) only checks for WP_RO, adding a second mechanism is pointless and can only cause problems.
A similar thing goes for COMPRESSED... I don't see a scenario where this would really be helpful. There are no global similarities between FMAP sections anyway. The contents of every section are completely specific to the section name, i.e. you cannot assume that they all contain code or anything. If you want to inspect the contents of a section you have to first figure out what that specific section means anyway. A flag like this would only make sense if we had some global, section-independent FMAP compression scheme, and there are no plans to have that atm.
I think we should only have flags when someone has a concrete, real-world use case and there's actually code doing something with it somewhere (like PRESERVE). Otherwise the flag would be useless because nobody knows what exactly it's supposed to do and under what circumstances to set them, so you couldn't ever rely on it being set correctly.
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 5:
But what does that actually say that isn't already said by the WP_RO region?
WP_RO is simply a recommendation for Chrome OS firmware layout. - We had firmware before WP_RO was introduced. - What if someday we want multiple sections being write-protected? - Will it be more descriptive to set ME section (when ME locked) as RO? - For people that wants to use Coreboot but not ChromeOS, they can use whatever names they like, and enable AREA_RO in their process.
Somehow I feel we should remove the logic of hard-coded 'WP_RO' name in CrOS factory, and always looking at AREA_RO flag to decide which section to apply WP. Unfortunately there's too much legacy that we can't drop it.
I think we should only have flags when someone has a concrete
In latest version I've added a note these are not used by any coreboot users today and hope that's enough.
Julius Werner has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 5:
- What if someday we want multiple sections being write-protected?
The hardware write-protect mechanism doesn't support that anyway.
- For people that wants to use Coreboot but not ChromeOS, they can use whatever names they like, and enable AREA_RO in their process.
I think it would make sense for other coreboot users to follow the example we set in that case. Consistency is good.
Somehow I feel we should remove the logic of hard-coded 'WP_RO' name in CrOS factory, and always looking at AREA_RO flag to decide which section to apply WP. Unfortunately there's too much legacy that we can't drop it.
We could do that if you want to. I don't really think it would be any better than a well-known section name, but it wouldn't be worse. You'd have to change the factory code to follow that and to correctly detect and abort if more than one unoverlapping section is marked like that, though.
But if we're not doing that, I don't think we should advertise an "RO" flag anywhere either. People may think it works and has an effect when it actually doesn't. I'm not saying that we should never have a flag like that, but I don't think we should have it before we actually have code using it.
Hello David Hendricks, Philipp Deppenwiese, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/31766
to look at the new patch set (#6).
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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.
BUG=None TEST=None (only documentation).
Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin hungte@chromium.org --- M Documentation/index.md A Documentation/lib/flashmap.md A Documentation/lib/index.md D util/cbfstool/README.fmaptool 4 files changed, 162 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/6
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 5:
Patch Set 5:
- What if someday we want multiple sections being write-protected?
The hardware write-protect mechanism doesn't support that anyway.
The WP mechanism on SPI flash does not support that (today). For example, on x86 we can set multiple regions as read-only to AP in SI_DESC, just like ME.
Anyway, I've changed the description of all 3 fields to "Not really used today" (hesitate to call that "deprecated" because it's simply we (cros, or coreboot) don't use it. other flashmap users may find it useful). Hope that would work.
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 6:
(1 comment)
https://review.coreboot.org/#/c/31766/6/Documentation/lib/flashmap.md File Documentation/lib/flashmap.md:
https://review.coreboot.org/#/c/31766/6/Documentation/lib/flashmap.md@61 PS6, Line 61: section that is reserved for CBFS. Usually it is named as `COREBOOT`. why is there no Area Flag "CBFS" ?
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 6:
(1 comment)
https://review.coreboot.org/#/c/31766/6/Documentation/lib/flashmap.md File Documentation/lib/flashmap.md:
https://review.coreboot.org/#/c/31766/6/Documentation/lib/flashmap.md@61 PS6, Line 61: section that is reserved for CBFS. Usually it is named as `COREBOOT`.
why is there no Area Flag "CBFS" ?
FMAP does not know about CBFS. What we set in previous patches are "Flashmap Descriptor" flags (which was known as annotation) - see below.
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 6:
any further feedbacks or any blessing for +2?
Philipp Deppenwiese has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 6: Code-Review+2
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 6:
(1 comment)
https://review.coreboot.org/#/c/31766/6/Documentation/lib/index.md File Documentation/lib/index.md:
https://review.coreboot.org/#/c/31766/6/Documentation/lib/index.md@7 PS6, Line 7: t I'm getting the error "toctree contains reference to nonexisting document u'cbfs.txt'" Please remove it until it has been converted to markdown.
Hello David Hendricks, Philipp Deppenwiese, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/31766
to look at the new patch set (#7).
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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.
BUG=None TEST=None (only documentation).
Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin hungte@chromium.org --- M Documentation/index.md A Documentation/lib/flashmap.md A Documentation/lib/index.md D util/cbfstool/README.fmaptool 4 files changed, 161 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/7
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 7:
(1 comment)
https://review.coreboot.org/#/c/31766/6/Documentation/lib/index.md File Documentation/lib/index.md:
https://review.coreboot.org/#/c/31766/6/Documentation/lib/index.md@7 PS6, Line 7: t
I'm getting the error "toctree contains reference to nonexisting document u'cbfs.txt'" […]
Done
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 7:
(2 comments)
https://review.coreboot.org/#/c/31766/7//COMMIT_MSG Commit Message:
https://review.coreboot.org/#/c/31766/7//COMMIT_MSG@11 PS7, Line 11: in coreboot. Also explained what is FMD and how to use it. Is the existing documentation from cbfstool just copied over?
https://review.coreboot.org/#/c/31766/7//COMMIT_MSG@14 PS7, Line 14: TEST=None (only documentation). The dot/period at the end can be removed.
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
Patch Set 7: Code-Review+2
Hello Patrick Rudolph, David Hendricks, Philipp Deppenwiese, build bot (Jenkins),
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/31766
to look at the new patch set (#8).
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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 --- M Documentation/index.md A Documentation/lib/flashmap.md A Documentation/lib/index.md D util/cbfstool/README.fmaptool 4 files changed, 161 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/66/31766/8
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 8:
(2 comments)
https://review.coreboot.org/#/c/31766/7//COMMIT_MSG Commit Message:
https://review.coreboot.org/#/c/31766/7//COMMIT_MSG@11 PS7, Line 11: in coreboot. Also explained what is FMD and how to use it.
Is the existing documentation from cbfstool just copied over?
It's based on that, plus few information I've added.
https://review.coreboot.org/#/c/31766/7//COMMIT_MSG@14 PS7, Line 14: TEST=None (only documentation).
The dot/period at the end can be removed.
Done
Patrick Georgi has submitted this change and it was merged. ( https://review.coreboot.org/c/coreboot/+/31766 )
Change subject: Documentation: Explain FMAP and FMD ......................................................................
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 --- M Documentation/index.md A Documentation/lib/flashmap.md A Documentation/lib/index.md D util/cbfstool/README.fmaptool 4 files changed, 161 insertions(+), 69 deletions(-)
Approvals: build bot (Jenkins): Verified Patrick Rudolph: Looks good to me, approved
diff --git a/Documentation/index.md b/Documentation/index.md index dd8714c..6eb2e69 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -181,6 +181,7 @@ * [System on Chip-specific documentation](soc/index.md) * [Mainboard-specific documentation](mainboard/index.md) * [Payload-specific documentation](lib/payloads/index.md) +* [Library-specific documentation](lib/index.md) * [SuperIO-specific documentation](superio/index.md) * [Vendorcode-specific documentation](vendorcode/index.md) * [Utilities](util.md) diff --git a/Documentation/lib/flashmap.md b/Documentation/lib/flashmap.md new file mode 100644 index 0000000..5da0e99 --- /dev/null +++ b/Documentation/lib/flashmap.md @@ -0,0 +1,153 @@ +# Flashmap and Flashmap Descriptor in coreboot + +## Flashmap + +[Flashmap](https://code.google.com/p/flashmap) (FMAP) 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. +The Flashmap implementation inside coreboot is the de facto standard today. + +Flashmap partitions the image into clearly delimited sections and some of those +sections may be CBFSes that can hold arbitrary-length files (at least one, the +default CBFS, called `COREBOOT`). General guidance is that everything with +strict layout requirements (e.g. must be aligned to erase blocks or +something else) should have its own Flashmap section, and everything else should +normally go into CBFS. + +The Flashmap itself starts with a header `struct fmap` and followed by a list of +section descriptions in `strcut fmap_area`. + +### Header +The header `struct fmap` has following fields: +* `signature`: 8 characters as `"__FMAP__"`. +* `ver_major`: one byte for major version (currently only 1). +* `ver_minor`: one byte for minor version (current value is 1). +* `base`: 64 bit integer for the address of the firmware binary. +* `size`: 32 bit integer for the size of firmware binary in bytes. +* `name`: 32 characters for the name of the firmware binary. +* `nareas`: 16 bit integer for the number of area definitions (i.e., how many + sections are in this firmware image) following the header. + +### Area Definition +The section is defined by `struct fmap_area` with following fields: +* `offset`: 32 bit integer for where the area starts (relative to `base` in + header). +* `size`: 32 bit integer for the size of area in bytes. +* `name`: 32 characters for a descriptive name of this area. Should be unique to + all sections inside same Flashmap. +* `flags`: 16 bit integer for attributes of this area (see below). + +### Area Flags +Currently the defined values for `flags` in `struct fmap_area` are: +* `FMAP_AREA_PRESERVE`: suggesting the section should be preserved when + updating firmware, usually for product data like serial number, MAC address, + or calibration and cache data. +* `FMAP_AREA_STATIC`: Not really used today. +* `FMAP_AREA_COMPRESSED`: Not really used today. +* `FMAP_AREA_RO`: Not really used today. + +### FMAP section +The whole Flashmap (`struct fmap` and list of `struct fmap_area`) should be +stored in a standalone section named as `FMAP` (which should be also described +by the Flashmap itself in `struct fmap_area`). There's no restriction for where +it should be located (or how large), but usually we need to do a linear or +binary search on whole firmware binary image to find Flashmap so a properly +aligned address would be better. + +### COREBOOT section +coreboot firmware images (`coreboot.rom`) should have at least one Flashmap +section that is reserved for CBFS. Usually it is named as `COREBOOT`. + +## Flashmap Descriptor + +Since coreboot is starting to use a "partition" of Flashmap to describe the +flash chip layout (both at runtime and when flashing a new image onto a +chip), the project needs a reasonably expressive plain text format for +representing such sections in the source tree. + +Flashmap Descriptor (FMD) is a [language and +compiler](https://chromium-review.googlesource.com/#/c/255031) inside coreboot +utility folder that can be used to generate final firmware images (i.e. +`coreboot.rom`) formatted by Flashmap. + +The FMD implementation is in coreboot `utils/cbfstool` folder. 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 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. + +To see the formal description of the language, please refer to the Lex and Yacc +files: `fmd_scanner.l` and `fmd_scanner.y`. diff --git a/Documentation/lib/index.md b/Documentation/lib/index.md new file mode 100644 index 0000000..85e0460 --- /dev/null +++ b/Documentation/lib/index.md @@ -0,0 +1,7 @@ +# Library-specific documentation + +This section contains documentation about coreboot internal technical +information and libraries. + +# Structure and layout +- [Flashmap and Flashmap Descriptor](flashmap.md) diff --git a/util/cbfstool/README.fmaptool b/util/cbfstool/README.fmaptool deleted file mode 100644 index 86fc3b2..0000000 --- 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().
-
Hung-Te Lin (Code Review) -
Julius Werner (Code Review)
-
Patrick Georgi (Code Review)
-
Patrick Rudolph (Code Review)
-
Paul Menzel (Code Review)
-
Philipp Deppenwiese (Code Review)