Per region file arguments

From flashrom
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

This wiki is retired

Our website is https://www.flashrom.org, instructions on how to add or update documentation are here

All wiki content available in read-only mode at wiki.flashrom.org

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

Alternative #1

   [-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.

Alternative #2

Deprecate `-i`, embed region into -r/-w/-v

   -r|-w|-v [<region>:]<filename>
  • No optional or non-positional arguments
  • Must err out if -r/-w/-v are mixed.
  • Cannot manipulate regions and chip-sized files in a single operation.
  • Erasing specific regions will be unsupported since -E does not take arguments.

Alternative #3

-r/-w/-v set mode and have no arguments. Non-hyphenated command line arguments are treated as either <filename> or <region>:<filename>.

   -r|-w|-v region:region.bin file.bin
  • -r/-w/-v is set only once
  • Eliminates concerns about optional argument to -r/-w/-v and makes them consistent with -E.
  • Chip-sized file and <region>:<filename> arguments are passed consistently; no difference in treatment with regard to -r/-w/-v.
  • Need to ensure chip-sized file is used at most once
  • We can either deprecate `-i`, or treat it as a special case for operations on the whole chip (erase options or chip-sized file).

Use cases

Operation CrOS syntax Alternative #1 Alternative #2 Alternative #3
Read entire chip into file flashrom -p prog -r file.bin flashrom -p prog -r file.bin flashrom -p prog -r file.bin flashrom -p prog file.bin -r
Read region(s) into chip-sized file flashrom -p prog -l layout -i region -r file.bin flashrom -p prog -l layout -i region -r file.bin n/a flashrom -r -p prog -l layout -i region file.bin
Read region(s) into region-sized files flashrom -p prog -l layout -i region:region.bin -r flashrom -p prog -l layout -r region:region.bin flashrom -p prog -l layout -r region:region.bin flashrom -r -p prog -l layout region:region.bin
Read region(s) into region-sized files and into chip-sized file [1] flashrom -p prog -l layout -i region:region.bin -r file.bin flashrom -p prog -l layout -r region:region.bin -r file.bin flashrom -p prog -l layout -r region:region.bin -r file.bin flashrom -r -p prog -l layout region:region.bin file.bin
Write chip-sized file to chip flashrom -p prog -w file.bin flashrom -p prog -w file.bin flashrom -p prog -w file.bin flashrom -w -p prog file.bin
Write regions(s) from chip-sized file to chip flashrom -p prog -l layout -i region -w file.bin flashrom -p prog -l layout -i region -w file.bin n/a flashrom -w -p prog -l layout -i region file.bin
Write region(s) from region-sized files to chip flashrom -p prog -l layout -i region:region.bin -w flashrom -p prog -l layout -w region:region.bin flashrom -p prog -l layout -w region:region.bin flashrom -w -p prog -l layout region:region.bin
Write chip-sized file while applying region-specific patches [2] flashrom -p prog -l layout -i region:region.bin -w file.bin flashrom -p prog -l layout -w region:region.bin -w file.bin flashrom -p prog -l layout -w region:region.bin -w file.bin flashrom -w -p prog -l layout region:region.bin file.bin
Verify using a chip-sized file flashrom -p prog -v file.bin flashrom -p prog -v file.bin flashrom -p prog -v file.bin flashrom -v -p prog file.bin
Verify regions using a chip-sized file flashrom -p prog -l layout -i region -v file.bin flashrom -p prog -l layout -i region -v file.bin n/a flashrom -v -p prof -l layout -i region file.bin
Verify regions using region-sized files flashrom -p prog -l layout -i region:region.bin -v flashrom -p prog -l layout -v region:region.bin flashrom -p prog -l layout -v region:region.bin flashrom -v -p prog -l layout region:region.bin
Erase chip flashrom -p prog -E flashrom -p prog -E 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 (?) n/a flashrom -p prog -l layout -i region -E

[1] This is a niche case used in some ChromeOS scripts that might not be necessary anymore.

[2] This is an optimization for when certain data is generated during manufacturing of the system and needs to be flashed to specific regions, e.g. ChromeOS VPD; In other words, this "patches" the base firmware image supplied to `-w` with data that may be generated dynamically.