Per region file arguments
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.
- 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
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:
would denote that the file's contents should be placed at the start/bottom of the region,
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
is specified, in which case the uncovered part would be padded with the flash chip's erased state (usually 0xff).
- Beside `:`, `[` and `]` wouldn't be allowed in region names.
|Operation||CrOS syntax||Proposed syntax|
|Read entire chip into file||flashrom -p prog -r file.bin||flashrom -p prog -r file.bin|
|Read region(s) into chip-sized file||flashrom -p prog -l layout -i region -r file.bin||?|
|Read region(s) into region-sized files||flashrom -p prog -l layout-i region:region.bin -r||?|
|Read region(s) into region-sized files and into chip-sized file*||flashrom -p prog -l layout-i region:region.bin -r file.bin||?|
|Write chip-sized file to chip||flashrom -p prog -w file.bin||flashrom -p prog -w file.bin|
|Write regions(s) from chip-sized file to chip||flashrom -p prog -l layout -i region -w file.bin||?|
|Write region(s) from region-sized files to chip||flashrom -p prog -l layout -i region:region.bin -w||?|
|Verify using a chip-sized file||flashrom -p prog -v file.bin||flashrom -p prog -v file.bin|
|Verify regions using a chip-sized file||flashrom -p prog -l layout -i region -v file.bin||?|
|Verify regions using region-sized files||flashrom -p prog -l layout -i region:region.bin -v||?|
|Erase chip||flashrom -p prog -E||flashrom -p prog -E|
|Erase regions(s)||flashrom -p prog -l layout -i region -E||flashrom -p prog -l layout -i region -E|
- This is a niche case used in some ChromeOS scripts that might not be necessary anymore.