Per region file arguments: Difference between revisions
(8 intermediate revisions by 2 users not shown) | |||
Line 5: | Line 5: | ||
[-i <region>[:<file>]]... -r|-w|-v [<filename>] | [-i <region>[:<file>]]... -r|-w|-v [<filename>] | ||
Where '''<filename>''' can be given anywhere on the command line ( | Where '''<filename>''' can be given anywhere on the command line (non-positional, matching legacy flashrom behavior) | ||
The syntax has been in use since 2011 to optimize flashrom for manufacturing and time-sensitive use cases (OS boot/resume/suspend paths). It is deployed on all ChromeOS devices and used during manufacturing of ChromeOS devices, so it has a long history of usage even though the syntax has not yet been adopted upstream. | |||
==== Rules: ==== | ==== Rules: ==== | ||
* | * Argument to -r/-w/-v is optional. | ||
** If used, it tells flashrom to operate on a ROM-sized file. | |||
** If not, flashrom will only operate on region-sized files specified in -i arguments. | |||
* If no argument to -r/-w/-v is specified, then files must be specified via -i arguments. | |||
* -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic. | |||
* For reading: | * For reading: | ||
** | ** If '''-i region:<file>''' is used, read content from '''region''' into '''<file>'''. | ||
** If any '''-i region:<file>''' is specified along with '''-r <filename>''', read all included regions into '''<filename>''' and all included regions with a '''<file>''' specified into the respective file | |||
* For writing and verifying: | * For writing and verifying: | ||
** | ** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''. | ||
** | ** If any '''-i region:<file>''' is specified along with '''-w <filename>''', the data of '''-i region:<file>''' will overwrite data in <filename>. This is useful for patching specific regions of a generic image, for example if you have a release image for a platform and wish to patch it with machine-specific data (such as MAC address) at manufacturing time. | ||
** Regions with files specified via '''-i region:<file>''' must not overlap | |||
More | More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes | ||
== More explicit alternative == | == More explicit alternative == | ||
Line 29: | Line 39: | ||
* if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either | * if no '''-r/-w/-v <filename>''' (i.e. without a '''<region>''') is specified, no '''-i''' arguments may be given either | ||
==== | ==== optionally, stricter ==== | ||
Never mix '''<region>:<file>''' with the old '''-i''' syntax in one invocation: | |||
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...) | |||
== Files not matching the region's size == | |||
Both syntaxes can be extended for files that are smaller than the region: | |||
<region>[<filename> | |||
would denote that the file's contents should be placed at the start/bottom | |||
of the region, | |||
<region>]<filename> | |||
that the file's contents should be placed at the end/top of the region. | |||
By default the uncovered part of the region should be kept as is, unless | |||
--pad | |||
is specified, in which case the uncovered part would be padded with the | |||
flash chip's erased state (usually 0xff). | |||
==== Additonal rules ==== | |||
* | * Beside `:`, `[` and `]` wouldn't be allowed in region names. |
Revision as of 16:41, 27 November 2018
Current chromium impl.
Current chromium flashrom implements the syntax like this:
[-i <region>[:<file>]]... -r|-w|-v [<filename>]
Where <filename> can be given anywhere on the command line (non-positional, matching legacy flashrom behavior)
The syntax has been in use since 2011 to optimize flashrom for manufacturing and time-sensitive use cases (OS boot/resume/suspend paths). It is deployed on all ChromeOS devices and used during manufacturing of ChromeOS devices, so it has a long history of usage even though the syntax has not yet been adopted upstream.
Rules:
- Argument to -r/-w/-v is optional.
- If used, it tells flashrom to operate on a ROM-sized file.
- If not, flashrom will only operate on region-sized files specified in -i arguments.
- If no argument to -r/-w/-v is specified, then files must be specified via -i arguments.
- -r/-w/-v and -i options are non-positional, allowing commands to be easily constructed dynamically by higher-level logic.
- For reading:
- If -i region:<file> is used, read content from region into <file>.
- If any -i region:<file> is specified along with -r <filename>, read all included regions into <filename> and all included regions with a <file> specified into the respective file
- For writing and verifying:
- If -i region:<file> is used, write content from <file> to region or verify content from <file> against region.
- If any -i region:<file> is specified along with -w <filename>, the data of -i region:<file> will overwrite data in <filename>. This is useful for patching specific regions of a generic image, for example if you have a release image for a platform and wish to patch it with machine-specific data (such as MAC address) at manufacturing time.
- Regions with files specified via -i region:<file> must not overlap
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes
More explicit alternative
[-i <region>]... (-r|-w|-v [<region>:]<filename>)...
Easier to implement, no optional arguments, no non-positional arguments.
Rules for sanity:
- combinations of -r/-w/-v are not allowed
- -r/-w/-v <filename> (i.e. without a <region>) may only be specified once
- if no -r/-w/-v <filename> (i.e. without a <region>) is specified, no -i arguments may be given either
optionally, stricter
Never mix <region>:<file> with the old -i syntax in one invocation:
([-i <region>]... (-r|-w|-v <filename>) | (-r|-w|-v <region>:<filename>)...)
Files not matching the region's size
Both syntaxes can be extended for files that are smaller than the region:
<region>[<filename>
would denote that the file's contents should be placed at the start/bottom of the region,
<region>]<filename>
that the file's contents should be placed at the end/top of the region. By default the uncovered part of the region should be kept as is, unless
--pad
is specified, in which case the uncovered part would be padded with the flash chip's erased state (usually 0xff).
Additonal rules
- Beside `:`, `[` and `]` wouldn't be allowed in region names.