Difference between revisions of "Per region file arguments"

From flashrom
Jump to: navigation, search
(Alternative #2)
 
(29 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 explicit alternative ==
+
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>)...
 
     [-i <region>]... (-r|-w|-v [<region>:]<filename>)...
Line 27: 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
  
==== optional Rules: ====
+
==== 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 ==
 +
 
 +
{| 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.
  
* forbid combinations of '''-r/-w/-v <filename>''' without a '''<region>''' and with? less flexible but easier to use
+
[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.