Difference between revisions of "Per region file arguments"

From flashrom
Jump to: navigation, search
(Files not matching the region's size)
(Rules:)
Line 8: Line 8:
  
 
==== 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.
 +
* 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 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 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 given with '''-i region:<file>''' must not overlap
+
** 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 ==
 
== More explicit alternative ==

Revision as of 05:21, 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).

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