Difference between revisions of "Per region file arguments"

From flashrom
Jump to: navigation, search
(Handle top/bottom placement)
(Alternative #2)
 
(26 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 (''non-positional'').
+
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: ====
* if no '''<filename>''' is given, all '''-i''' arguments must specify a '''<file>'''
+
* 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 any '''-i region:<file>''' is given along with '''<filename>''', read all included regions into '''<filename>''' and all included regions with a '''<file>''' specified into the respective file
+
** 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 any '''-i region:<file>''' is given along with '''<filename>''', the data of '''-i region:<file>''' takes precedence
+
** If '''-i region:<file>''' is used, write content from '''<file>''' to '''region''' or verify content from '''<file>''' against '''region'''.
** regions with files given with '''-i region:<file>''' must not overlap
+
** 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 details: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes
+
More examples: https://www.chromium.org/chromium-os/packages/cros-flashrom#TOC-Partial-Reads-and-Writes
  
== More explicit alternative ==
+
== Alternative #1 ==
  
 
     [-i <region>]... (-r|-w|-v [<region>:]<filename>)...
 
     [-i <region>]... (-r|-w|-v [<region>:]<filename>)...
Line 53: Line 63:
 
is specified, in which case the uncovered part would be padded with the
 
is specified, in which case the uncovered part would be padded with the
 
flash chip's erased state (usually 0xff).
 
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>
 +
 +
* File argument is mandatory; 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 positional or optional argument to -r/-w/-v and makes them consistent with -E.
 +
* Files (chip-sized and region-sized) are handled in a consistent manner similar to standard Unix commands such as ls, rm, cat, etc.
 +
* 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 ==
 +
 +
{| class="wikitable"
 +
|-
 +
|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.

Latest revision as of 16:27, 11 May 2021

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>
  • File argument is mandatory; 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 positional or optional argument to -r/-w/-v and makes them consistent with -E.
  • Files (chip-sized and region-sized) are handled in a consistent manner similar to standard Unix commands such as ls, rm, cat, etc.
  • 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.